Skip to content

Harden live preset reads without swallowing concurrent recalls - #62

Draft
tony-xmelon wants to merge 10 commits into
stokes-audio:mainfrom
tony-xmelon:codex/recall-read-resilience
Draft

tony-xmelon wants to merge 10 commits into
stokes-audio:mainfrom
tony-xmelon:codex/recall-read-resilience

Conversation

@tony-xmelon

@tony-xmelon tony-xmelon commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • retry a live-preset read once within one caller-supplied total timeout budget
  • log each timeout and retain the final TimeoutError cause
  • discount concurrent arrivals only when every observed arrival exactly restates the keyed answer fields
  • preserve needs_read when a genuinely different recall arrives during the read
  • keep Cortex Control compatibility Version responses out of identity state
  • document FieldPlan.accepts as the cache admission boundary

Validation

Current head: 2291e310d1df306f28f990307ac4caa2fccd3be6

  • focused new resilience cases: 12 passed
  • includes attempts=1, exactly one send, old request-id rejection, retained cause, exact duplicate, and different-recall cases
  • python -m mypy pyquadcortex: clean (46 source files)
  • git diff --check: clean

A broader local invocation encounters only this machine's unrelated installed tests package shadowing repository helpers. The previous exact full offline baseline for this branch family was 2,699 passed / 3 skipped plus three known Windows fixture assertions.

Hardware evidence

Combined with #44, this runtime passed the CorOS 4.1 physical suite at 95 passed, 4 fixture-dependent skips, 0 failed, with all 16 claimed operations green. The equality-based correction is stricter than that measured predecessor: an exact duplicate no longer dirties the cache, while a different concurrent recall cannot be swallowed.

This PR remains draft pending maintainer review and #44 ordering.

Upstream sync — 2026-09-12

Merged upstream main at 640a8e9 (maintainer PRs #63–#65: measured pan spans and Global EQ scale/offset corrections). Post-merge validation: 5 focused read tests plus 405 state/profile/docs tests passed, 1 skipped; mypy clean (46 files); git diff --check clean.

Upstream sync - 2026-09-19

Merged upstream main at cfe39cc6592148d4196fa3028c2776f6618c41b6 (including maintainer PRs #70-#75) and resolved overlaps in favor of the current upstream API and evidence model.

Current head: 2291e310d1df306f28f990307ac4caa2fccd3be6

Focused validation: 8 focused authoritative-read tests passed.

GitHub CI on this exact head is green: build + twine check, mypy, and tests on Python 3.11, 3.12, and 3.13 all pass.

No new maintainer comments were posted during this sync. This PR remains draft under its stated hardware/evidence policy; the displayed CHANGES_REQUESTED decision is the earlier review and has not yet been refreshed.

Maintainer follow-up — 2026-09-27

Current head: 133335cd8413f335906f45b83e6e77178f6b56c4.

Addressed the three prose requests at this head: ADR-0011's Decision text is append-only and retains its amended-date pointer; the StateEntry / ENTRIES one-answer contract and issue #25 pointer are present; and _version_describes_device precedes the _VERSION_FOR_IDENTITY evidence block.

The maintainer's two successful CorOS 4.0.1 runs were on predecessor de1123b7, before the current-main sync. Exact reported result:

============== operations on QuadCortex (CorOS 4.0.1, MAINTAINER) ==============
tests: 120 passed, 0 failed, 0 errored, 3 skipped; operations measured: 21 of 21 claimed
passed:                                 ['active_scene', 'clear_expression', 'create_local_backup', 'inhibited_modules', 'read_current_preset', 'redo', 'set_bypass', 'set_chain_input', 'set_device_name', 'set_expression', 'set_global_eq', 'set_hold_timing', 'set_input_port', 'set_param', 'set_scene_color', 'set_scene_label', 'set_tempo_mode', 'switch_scene', 'tempo_mode', 'undo', 'update_settings'] (21)
failed or skipped:                      [] (0)
passed, not VERIFIED:                   [] (0)
VERIFIED and claimed by a test, failed: [] (0)
120 passed, 3 skipped in 285.93s (0:04:45)

That is strong evidence for de1123b, but not the final synced head. As requested, this PR remains draft pending the maintainer's offered rerun on 133335c. Offline validation on the final head is 2,980 passed, 7 skipped, mypy clean (46 files), and CI green on Python 3.11–3.13 plus build/twine.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Review correction pushed in 66752e5 before exact-head hardware testing: the two-message RecallPreset read is measured only on CorOS 4.1.0, so its expected arrival count now lives on QuadCortex41. The 4.0.1 base continues to expect one reply and retains its conservative concurrent-push behavior. Updated offline scope: 455 passed, 1 skipped; diff check and compileall clean. Exact-head hardware run is queued after PR #44's run.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Final follow-up head is b73d38c. The CorOS 4.1 two-arrival fact is profile-scoped, protocol-shaped client doubles retain the one-arrival default, and the full offline run is 2,699 passed / 3 skipped with only the three documented Windows baseline assertions; mypy is clean across 46 files. Exact combined #44 + #62 hardware validation at 99a5cd5 passed 95 / skipped 4 / failed 0, with no operation regression. This remains draft only on the #44 snapshot/Version dependency.

@jonathanstokes jonathanstokes left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes. Two things block, and one of them is a policy item rather than a bug.

The hardware run this PR needs has not happened on this head. The run quoted in the description is on 99a5cd5, which is this PR combined with #44, not on b73d38c. This change edits the shared base class that a 4.0.1 unit uses: the live-preset read method, the identity entry, and the cache read path in device/state.py. So the run that proves 4.0.1 still behaves exactly as measured on 2026-09-07 has to be on this head, on a 4.0.1 unit, and that run is mine to make. When you update the description, please paste the operations on ... block and pytest's own last line rather than summarising them. Keeping this a draft until then is the right call, and I appreciate you saying plainly which commit the numbers came from.

The other blocker is inline, on pyquadcortex/device/state.py line 451.

What I checked. I built your head in a scratch worktree. The offline suite gives 2,702 passed and 3 skipped, mypy is clean across 46 files, and the branch still applies to current main. I also ran two small probes of the cache behaviour; the results are in the inline comment on state.py.

Two things that are right, and worth saying. The two-arrival fact really does live on the profile class rather than in a method body, which is what ADR-0020 asks for, and tests/test_profiles.py pins it. And the 4.0.1 base does keep its stricter single-arrival behaviour: I fed the 4.1-shaped double reply to the plain QuadCortex class and it correctly refused to trust the cache.

Merge order: this one before #44. #44 is behind main, has changes requested, overlaps seven files with this PR, and its own description says its hardware gate depends on this one. This PR on its own can be tested on my 4.0.1 unit today. It cannot be tested on a 4.1 unit until #44 lands, because QuadCortex41 has no catalog snapshot before then. So the order is: fix these, I run it on 4.0.1, merge, then #44 rebases and re-runs on 4.1.

One thing you do not need to worry about: the section 7.2 correction here does not collide with a separate unpushed 4.0.1 correction about File reads in section 4.2. Different section, no conflict.

Comment thread pyquadcortex/device/state.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread docs/protocol.md Resolved
Comment thread pyquadcortex/device/entries.py Resolved
Comment thread pyquadcortex/device/entries.py Resolved
Comment thread tests/test_client.py Resolved
Comment thread tests/test_state.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
@tony-xmelon tony-xmelon changed the title Harden live preset reads Harden live preset reads without swallowing concurrent recalls Sep 11, 2026
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Thank you — addressed in 9585bee. Fixed arrival counts are gone: only exact field-equal restatements are discounted, while a different concurrent recall preserves needs_read. Retry shares one total budget, warns on each timeout, retains the cause, and now has attempts=1/old-ID/send-count coverage. ADR/docs wording and the 4.0.1 measurement were restored.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Synchronized with upstream main at 640a8e9 (merged maintainer PRs #63–#65). Current head is ffcfcb9; post-merge validation is recorded in the PR body.

…esilience

# Conflicts:
#	CLAUDE.md
#	changelog.md
#	docs/ADR.md
#	docs/protocol.md
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Merged current upstream main at de1123b. The recall-read resilience behavior required no conflict-specific change.

Exact-head validation: 2974 passed, 7 skipped; mypy clean; build and twine check passed; diff check clean.

@jonathanstokes

Copy link
Copy Markdown
Contributor

I ran the 4.0.1 hardware suite on this head, de1123b7. Everything I still want changed is prose, so there was no reason to make you wait for it.

Two runs, same numbers both times, on Quad Cortex QA00EE910, CorOS 4.0.1, firmware d14e.

============== operations on QuadCortex (CorOS 4.0.1, MAINTAINER) ==============
tests: 120 passed, 0 failed, 0 errored, 3 skipped; operations measured: 21 of 21 claimed
passed:                                 ['active_scene', 'clear_expression', 'create_local_backup', 'inhibited_modules', 'read_current_preset', 'redo', 'set_bypass', 'set_chain_input', 'set_device_name', 'set_expression', 'set_global_eq', 'set_hold_timing', 'set_input_port', 'set_param', 'set_scene_color', 'set_scene_label', 'set_tempo_mode', 'switch_scene', 'tempo_mode', 'undo', 'update_settings'] (21)
failed or skipped:                      [] (0)
passed, not VERIFIED:                   [] (0)   <- candidates to add
VERIFIED and claimed by a test, failed: [] (0)   <- regressions by name
120 passed, 3 skipped in 285.93s (0:04:45)

All three skips are about my setup rather than your change: the loaded preset has no branch, and the two tempo-mode ones want a snapshot label and a captures directory that a fresh worktree does not have.

So 4.0.1 still behaves the way it was measured on 2026-09-07. The cache read path and the identity entry are both fine, and the equality check does what you said it does.

Three things left, all in the text.

1. ADR-0011's Decision bullet is rewritten in place. docs/ADR.md's Lifecycle section says a shipped decision is never rewritten, only built on, and the rewrite also drops the (amended 2026-08-27, see the consequences) pointer. Put the Decision bullet back the way it reads on main, pointer included, and let your two new Consequences bullets carry the new rule. They are correct and they are the right place for it.

2. The StateEntry and ENTRIES prose is still deleted. I raised this last time and it is the one review item still open. Issue #25's first acceptance criterion is that the cache's one-answer rule is written down where the next person meets it, and it says the state layer says so in as many words. That is the paragraph this removes, so please restore it. The story that owns the flood design is #25, split out of #12 for exactly that reason, so the pointer should name #25 rather than #12.

3. _version_describes_device now sits inside the #: comment block that documents _VERSION_FOR_IDENTITY, which cuts the block off from the thing it describes. Move the function above the block.

On whether the run carries forward: if those three prose fixes are the only thing that lands, it stands and I will mark this ready. The branch is behind main by two merges and the ruleset will want that fixed before merge, so if you sync main as well, I will run it again on the final head.

One more thing worth saying. This does not depend on #44. It is green on current main on its own, and the two do not conflict in entries.py either. Whichever lands first, the other only has to fix changelog.md.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

@jonathanstokes Thanks for the precise follow-up. I restored ADR-0011's append-only Decision wording (including its amended-date pointer), restored the StateEntry one-answer contract and changed the stream-design pointer to issue #25, and moved _version_describes_device above the identity evidence comment so that comment documents _VERSION_FOR_IDENTITY. I merged current main at d8d40f3; final head is 133335c. Validation on this head: 2,980 passed, 7 skipped; mypy clean across 46 source files; git diff --check clean. The two 4.0.1 hardware runs you reported on de1123b were before the main sync, so please rerun the hardware suite on this final head as you offered. The PR remains draft until that final hardware result is recorded.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

@jonathanstokes I verified the three prose changes at final synced head 133335c; the local tree is clean and the exact-head CI run is green. I have updated the description with your precise two-run 4.0.1 report on predecessor de1123b and clearly marked it as not the final synced head. Since I merged current main after your offer, please rerun the hardware suite on 133335c when convenient; I will keep the PR draft until that result is recorded. I am not merging #44 ahead of this, per your stated order.

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.

2 participants