Repository navigation
docs: the File READ enumerates and does not gate pushes - #70
Merged
Merged
Conversation
jonathanstokes
force-pushed
the
docs/file-read-not-a-subscription-gate-v2
branch
from
September 14, 2026 23:44
843ced1 to
0095802
Compare
jonathanstokes
marked this pull request as ready for review
September 14, 2026 23:48
Section 4.2 stated as a general rule that every READ in the connect burst acts as a subscription, so the device pushes that type only to clients that asked. Measured 2026-09-09 on CorOS 4.0.1 / d14e: that is false for File. A client that never sends the File READ is still told when a preset is saved on the unit. Two connections, the same on-unit action each time (one Save As into an empty user slot, then a scene change as a fencing marker), recorder attached through before_handshake with no type filter: default 399 File in the burst, 1 after the save initial_file_listing=False 0 File in the burst, 1 after the save The save's cascade is identical in both runs and in the same order, so omitting the READ costs the enumeration and nothing else a save announces. Says what was NOT measured, which is most of it: the other 21 types were never tested one at a time, a delete or rename or IR import was not measured, and 4.1.0 is untouched. Names the profile as CorOS 4.0.1 / d14e rather than d14e alone, since ADR-0020 has the app firmware string distinguishing nothing. The instrument error behind the first attempt lands in capture.md as a fourth way an instrument lies about silence, not here: a recorder passed AS before_handshake rather than registered on the transport that hook hands you subscribes to nothing and raises nothing. That section is where somebody wiring a recorder will look, and it had no worked example of catching the connect burst at all. It also now says why the heartbeat in lie 2 did not catch this one. The protocol record keeps only the part that is about this measurement - the eager arm is a positive control, it ran first, and it failed loudly - and links to the rest.
jonathanstokes
force-pushed
the
docs/file-read-not-a-subscription-gate-v2
branch
from
September 15, 2026 17:21
0095802 to
0ef28b3
Compare
…subscription-gate-v2
jonathanstokes
deleted the
docs/file-read-not-a-subscription-gate-v2
branch
September 15, 2026 17:37
This was referenced Sep 19, 2026
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.
docs/protocol.mdsection 4.2 said, as a general rule, that every READ in the connect burst acts as a subscription, so the device pushes that state type only to clients that asked for it. That is not true forFile, and this writes down the measurement that shows it.A client that never sends the
FileREAD is still told when a preset is saved on the unit. Soinitial_file_listing=False, which #48 added, costs the 399-message enumeration and costs nothing else a save announces. A listener does not go deaf by setting it.How it was measured
Two connections, the same action on the unit each time, with a recorder attached through
before_handshakeand no type filter on either run.Filein the burstFileafter the on-unit saveinitial_file_listing=FalseThe action was one Save As into an empty user slot, then a scene change about ten seconds later. The scene change is a fencing marker rather than part of the measurement: it proves the recorder was still live and that the operator acted, so an absent
Filewould have meant something.What carries the finding is the right-hand column, not the left. The left only shows the flag took effect, which the offline suite already proves. The finding is the deferred arm's
1- a push that arrived on a connection which never subscribed. What licenses trusting that arm's0is that the same recorder, in the same run, caught that1, so it was demonstrably not deaf.What this does NOT claim
Most of it, and the record says so:
The instrument error, and where it lives
The first attempt produced a convincing false negative: the recorder was passed AS
before_handshakerather than registered on the transport that hook hands you, so it subscribed to nothing, raised nothing, and logged one message in 35 seconds.That lesson lands in
docs/capture.mdas a fourth way an instrument lies about silence, NOT in the protocol record, because it is a fact about the instrument rather than about the device. Two things made it worth adding there rather than duplicating:connect()returns, so it had no worked example of catching the connect burst at all - which is the case the trap lives in.The protocol record keeps only the part that is about this measurement - the eager arm is a positive control, it ran first, and it failed loudly - and links to the rest.
What changed
docs/protocol.mdsection 4.2: the correction, in the file's usual correction style, beside the contributed 4.1.0 observation rather than replacing it.docs/capture.md: the trap as lie 4, section renamed "Four ways your instrument lies about silence".pyquadcortex/protocol/client.py: the_hellodocstring becomes definite instead of calling the question unmeasured.changelog.md: a paragraph on Allow deferring the initial file listing #48's entry, since it changes whether a reader should set that flag.No behaviour change. No
STEERING/CLAUDE/ADRupdate is owed: their "subscription" references are allTransport.add_listenerand ADR-0009, a different sense.Review
/triage-prPhase 1 was run on this branch by an independent reviewer, since I wrote it. Nine findings, none blocking, all fixed. The substantive ones were an unmeasured claim of uniqueness ("the exception"), the firmware named asd14ealone against ADR-0020, an evidence paragraph that cited a silence as proof the result was not a silence, one save generalized to "a file change", and a contributor's caveat deleted rather than narrowed. Thecapture.mdsplit above also came out of that review.Hardware
Run on the final commit
aac4e09, Quad Cortex, CorOS 4.0.1, firmware d14e:Offline suite
2847 passed, 4 skipped; mypy clean. The branch also carries a catch-up merge with main (#71), which is why the counts moved.Worth saying plainly: the suite passing is not what backs this change, because the suite has no test for the push gate. The evidence is the two-arm probe above, written into the record so the next person can see what was measured rather than take it on trust.