docs: name both new IRR-CA anchors in the SoundDispatchOutcome docstring - #1269
Merged
Conversation
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.
Owner
Author
|
@codex review |
|
Codex Review: Didn't find any major issues. Another round soon, please! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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
marked this pull request as ready for review
September 4, 2026 11:50
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds one paragraph to the class docstring of
SoundDispatchOutcomeinconst.py, pointing at the two anchors this type is the carrier of:IRR-CA-SOUND-FAILURE-CLASSfor the per-member "may a caller arm a pushcooldown" table;
IRR-CA-STOP-BREAKS-SELF-INFLICTED-COOLDOWNfor the stop-path qualifier.Documentation only. No behaviour change, no signature change, no test change.
Why
SoundDispatchOutcomeexists because a bool cannot carry the state space, andthe rule that only
TRANSPORT_FAILEDmay arm a push cooldown is the wholepoint of the type. That rule and both of its anchors lived in
docs/PLAY_SOUND_ARCHITECTURE.mdand in comments incoordinator/locate.pyand
api.py, but not in the docstring a caller actually reads when they hoverthe 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 adesign 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; onlythis docstring reference was missed.
Measured
IRR-CA-anchor cited undercustom_components/resolvesin the architecture document): no
MISSINGline, before and after.git diff --name-only origin/1.7→custom_components/googlefindmy/const.pyonly, 11 added lines, nothing removed.
README.mdandstrings.jsonuntouched, as the DoD requires.
ruff checkandruff 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 doessomething else. The break-through happens at the readiness gate
(
coordinator/locate.py, theused_own_fresh_key and time.monotonic() < self._push_cooldown_untilbranch); the function only keeps a running windowfrom 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.