Skip to content

docs: name both new IRR-CA anchors in the SoundDispatchOutcome docstring - #1269

Merged
jleinenbach merged 1 commit into
1.7from
docs/ap7-sound-outcome-anchor-refs
Sep 4, 2026
Merged

docs: name both new IRR-CA anchors in the SoundDispatchOutcome docstring#1269
jleinenbach merged 1 commit into
1.7from
docs/ap7-sound-outcome-anchor-refs

Conversation

@jleinenbach

Copy link
Copy Markdown
Owner

What

Adds one paragraph to the class docstring of SoundDispatchOutcome in
const.py, pointing at the two anchors this type is the carrier of:

  • IRR-CA-SOUND-FAILURE-CLASS for the per-member "may a caller arm a push
    cooldown" table;
  • IRR-CA-STOP-BREAKS-SELF-INFLICTED-COOLDOWN for the stop-path qualifier.

Documentation only. No behaviour change, no signature change, no test change.

Why

SoundDispatchOutcome exists because a bool cannot carry the state space, and
the rule that only TRANSPORT_FAILED may arm a push cooldown is the whole
point of the type. That rule and both of its anchors lived in
docs/PLAY_SOUND_ARCHITECTURE.md and in comments in coordinator/locate.py
and api.py, but not in the docstring a caller actually reads when they hover
the type. This repository already treats that shape as a defect class: see
tests/test_stop_sound_correlation.py::test_api_docstrings_declare_no_ring_confirmation,
which pins the same discipline for api.py ("a boundary that lives only in a
design document gets re-discovered as a bug").

This is the last open item of the DoD of AP-7 in the plan
PLAN_GFMY_SOUND_FAILURE_CLASSIFICATION. AP-1 to AP-7 shipped with #1262; only
this docstring reference was missed.

Measured

  • Anchor gate (every IRR-CA- anchor cited under custom_components/ resolves
    in the architecture document): no MISSING line, before and after.
  • git diff --name-only origin/1.7custom_components/googlefindmy/const.py
    only, 11 added lines, nothing removed. README.md and strings.json
    untouched, as the DoD requires.
  • ruff check and ruff format --check: clean.
  • pytest tests/test_stop_sound_correlation.py tests/test_sound_dispatch_contract.py tests/test_coordinator_sound_uuid.py tests/test_coordinator_locate_basics.py
    → 123 passed.

Review note

The first draft of this paragraph was wrong in a way worth recording: it tied
"a play cannot silence the stop its cancel key exists for" to
_note_stop_transport_problem_without_extending(). That function does
something else. The break-through happens at the readiness gate
(coordinator/locate.py, the used_own_fresh_key and time.monotonic() < self._push_cooldown_until branch); the function only keeps a running window
from being restarted by a stop that already broke through, which is the
separate "it cannot feed itself" property. The paragraph now states both, in
the order the code has them, and no longer claims the window was necessarily
armed by the very play that stored the key -- the code says that is the common
case, not a proven one.

The type carries the classification that IRR-CA-SOUND-FAILURE-CLASS
defines and that IRR-CA-STOP-BREAKS-SELF-INFLICTED-COOLDOWN qualifies on
the stop path, but its own docstring named neither. A reader of const.py
found the rule stated, and its two anchors, only in
docs/PLAY_SOUND_ARCHITECTURE.md and in comments elsewhere, which is the
shape that gets a boundary re-discovered as a bug.

The added paragraph states what each anchor is good for rather than
merely naming it:

- the per-member "may a caller arm a push cooldown" table, so a reader
  looking for the cooldown verdict of one member knows where it lives;
- the stop-path qualifier in the two parts the code keeps apart: the
  readiness gate lets a correlated stop through a running window, and a
  stop that then fails on the transport is reported through
  _note_stop_transport_problem_without_extending(), which puts a window
  that was already running back instead of restarting it.

Documentation only, no behaviour change. Every anchor cited under
custom_components/ still resolves in docs/PLAY_SOUND_ARCHITECTURE.md
(anchor grep: no MISSING line). README.md and strings.json are
untouched.

Closes the last open DoD item of AP-7 in
PLAN_GFMY_SOUND_FAILURE_CLASSIFICATION; AP-1 to AP-7 shipped with #1262.
@jleinenbach

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: f3b70f88cc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@jleinenbach
jleinenbach marked this pull request as ready for review September 4, 2026 11:50
@codecov

codecov Bot commented Sep 4, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@jleinenbach
jleinenbach merged commit e9fa306 into 1.7 Sep 4, 2026
24 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant