Skip to content

docs: the File READ enumerates and does not gate pushes - #70

Merged
jonathanstokes merged 2 commits into
mainfrom
docs/file-read-not-a-subscription-gate-v2
Sep 15, 2026
Merged

jonathanstokes merged 2 commits into
mainfrom
docs/file-read-not-a-subscription-gate-v2

Conversation

@jonathanstokes

@jonathanstokes jonathanstokes commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

docs/protocol.md section 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 for File, and this writes down the measurement that shows it.

A client that never sends the File READ is still told when a preset is saved on the unit. So initial_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_handshake and no type filter on either run.

connect File in the burst File after the on-unit save
default 399 1
initial_file_listing=False 0 1

The 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 File would 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's 0 is that the same recorder, in the same run, caught that 1, so it was demonstrably not deaf.

What this does NOT claim

Most of it, and the record says so:

  • The other 21 types in the burst were never tested one at a time. The original rule came from section 4.1's all-or-nothing observation, not from omitting individual READs, so this says nothing about whether they gate their own pushes.
  • Only a Save As was measured. A delete, a rename and an IR import were not.
  • CorOS 4.1.0 is untouched. The contributor's caveat is narrowed to that profile rather than deleted.
  • One trial per arm.

The instrument error, and where it lives

The first attempt produced a convincing false negative: the recorder was passed AS before_handshake rather 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.md as 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:

  • That document's listener example attaches after connect() returns, so it had no worked example of catching the connect burst at all - which is the case the trap lives in.
  • Its own heartbeat advice (lie 2) does not catch this one. The heartbeat counted what the recorder held, so a single spurious entry satisfied its liveness test and it printed ALIVE over an empty recording. It now says to count something the device sends unprompted instead.

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.md section 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 _hello docstring 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/ADR update is owed: their "subscription" references are all Transport.add_listener and ADR-0009, a different sense.

Review

/triage-pr Phase 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 as d14e alone 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. The capture.md split above also came out of that review.

Hardware

Run on the final commit aac4e09, Quad Cortex, CorOS 4.0.1, firmware d14e:

============== operations on QuadCortex (CorOS 4.0.1, MAINTAINER) ==============
tests: 115 passed, 0 failed, 0 errored, 3 skipped; operations measured: 17 of 17 claimed
failed or skipped:                      [] (0)
passed, not VERIFIED:                   [] (0)   <- candidates to add
VERIFIED and claimed by a test, failed: [] (0)   <- regressions by name

================== 115 passed, 3 skipped in 181.73s (0:03:01) ==================

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.

@jonathanstokes
jonathanstokes force-pushed the docs/file-read-not-a-subscription-gate-v2 branch from 843ced1 to 0095802 Compare September 14, 2026 23:44
@jonathanstokes
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
jonathanstokes force-pushed the docs/file-read-not-a-subscription-gate-v2 branch from 0095802 to 0ef28b3 Compare September 15, 2026 17:21
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