From 0ef28b3d7882912e97e795792b2e52e906620be5 Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Wed, 9 Sep 2026 14:10:23 -0500 Subject: [PATCH] docs: the File READ enumerates and does not gate pushes 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. --- changelog.md | 7 +++++ docs/capture.md | 35 +++++++++++++++++++--- docs/protocol.md | 51 +++++++++++++++++++++++++++++++-- pyquadcortex/protocol/client.py | 13 ++++++--- 4 files changed, 96 insertions(+), 10 deletions(-) diff --git a/changelog.md b/changelog.md index 9bf157c..159fea6 100644 --- a/changelog.md +++ b/changelog.md @@ -26,6 +26,13 @@ Both connect layers accept `initial_file_listing=False`, omitting only the handshake's eager `File` READ. The default remains eager, and listing operations still fetch explicitly when called on a profile that verifies them. +Deferring costs the enumeration and nothing else a save announces. Measured +2026-09-09 on CorOS 4.0.1: a preset saved on the unit is announced identically +whether or not the `File` READ was sent, so a listener does not go deaf by +setting this. A delete, a rename and an IR import were not measured. That also +corrects a general statement in [docs/protocol.md](docs/protocol.md) section +4.2, which had every READ in the connect burst acting as a subscription. + ### Where a knob's numbers start comes from the device now, not a table The Quad Cortex has knobs whose bottom position shows a word - usually `OFF` - diff --git a/docs/capture.md b/docs/capture.md index 803078c..4f0362f 100644 --- a/docs/capture.md +++ b/docs/capture.md @@ -41,7 +41,7 @@ from pyquadcortex.protocol.proto import ProductionAutomation_pb2 as pa # m.HasField("metronome_status") and not m.params # # Note this is a NOISE list, not an allow-list, and pair it with a heartbeat - -# see "Three ways your instrument lies about silence" below. +# see "Four ways your instrument lies about silence" below. NOISE = {"GlobalTempoMessage", "IOMeterMessage", "GridModelMeterMessage", "KeepAliveMessage", "ModuleStatsMessage"} @@ -65,11 +65,11 @@ with lock: print(f"{name}: {body[:400]}") ``` -## Three ways your instrument lies about silence +## Four ways your instrument lies about silence -Every one of these produced a confident wrong conclusion in this project, and all three +Every one of these produced a confident wrong conclusion in this project, and all four look identical from the outside: **the device appears not to answer.** The device was -behaving correctly all three times. +behaving correctly all four times. A useful heuristic came out of it. A *flaky* negative is usually the device - reads here are lazy and the first request after connecting is often dropped. A *perfectly consistent* @@ -143,6 +143,33 @@ documentation, along with a method that quietly returned the wrong list. Correla `request_id`, which the device does echo, and when a match predicate times out, log what DID arrive before concluding nothing did. +**4. A listener you never actually registered records nothing, and nothing looks +exactly like silence.** The listener above is attached after `connect()` returns, which is +fine for an action you perform yourself but too late for the connect handshake's own burst +- by then it is seconds from starting. Catching the burst means subscribing through +`protocol.connect(before_handshake=...)`, and that hook is called WITH the started +transport and expects you to register on it: + +```python +protocol.connect(before_handshake=tap) # WRONG +protocol.connect(before_handshake=lambda t: t.add_listener(tap)) # right +``` + +The wrong form raises nothing. `tap` is called exactly once, with the `Transport` object +as its "message", and never again. Measured 2026-09-09: one recorded message in 35 +seconds, on a link that was healthy and had just delivered a 399-message folder +enumeration to nobody. + +The heartbeat from lie 2 does not necessarily save you here. If it counts what the +recorder holds, that one spurious entry can satisfy its liveness test, and it will print +ALIVE over an empty recording - which is what happened. Count something you know the +device sends unprompted, such as the tempo stream, rather than the total. + +What does catch it is a POSITIVE CONTROL: an arm of the experiment where you already know +what the device should say. Run that arm FIRST. A silent instrument then shows up in the +arm that was supposed to be noisy, before you have spent the session believing a negative. +`tests/hardware/conftest.py` has the correct registration if you want a worked example. + ## Diff the whole state, do not hunt for a field The listener above answers "what does the device SAY when I do this?". When the answer is diff --git a/docs/protocol.md b/docs/protocol.md index 0439063..b376c76 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -519,8 +519,55 @@ appears to want the whole set before it considers the client fully connected. The optional initial `File` READ makes this a 22-type burst by default or 21 when deferred. A contributed CorOS 4.1.0 check on 2026-09-08 connected with the 21-type form and later enumerated all 586 folders explicitly under -`Support.EXPERIMENTAL`. Whether omitting `File` also opts out of later file -change broadcasts remains unmeasured. +`Support.EXPERIMENTAL`. + +**`File` is the one type measured to behave differently: it enumerates, and it +does not gate pushes.** This corrects the rule at the top of this section, which +was recorded as covering every type in the burst. Measured 2026-09-09 on CorOS +4.0.1 / `d14e`: a client that never sends the `File` READ is still told when a +preset is saved on the unit. The other 21 types were NOT tested one at a time - +the rule above 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. On CorOS 4.1.0 the question remains unmeasured. + +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, followed about ten seconds +later by a scene change. 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. Each run kept recording +for about three minutes after the save, with a heartbeat every 15 seconds, and +the `File` count was stable from the save to the end. + +The save's own cascade is identical in both runs and in the same order: `File`, +`UndoRedo`, then `RecallPreset`, `Scene`, `RecentsFavorites`, `SetlistPosition` +and the `Grid` pushes, all inside about a second. So omitting the READ costs the +399-message enumeration and costs nothing else a SAVE announces. A delete, a +rename and an IR import were not measured. + +What carries this is the right-hand column, not the left. The left only shows the +flag took effect, which `tests/test_client.py` already proves offline. 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` in the burst is that the same +recorder, in the same run, caught that `1`, so it was demonstrably not deaf. One +trial per arm. + +The first attempt produced a convincing false negative: the recorder was never +registered at all, and logged one message in 35 seconds on a healthy link. The +trap and how to avoid it are lie 4 in [capture.md](capture.md#four-ways-your-instrument-lies-about-silence), +which is where it belongs - it is a fact about the instrument, not about the +device. What belongs here is why this measurement survived it. The eager arm is +a positive control, it ran first, and it failed loudly. + +The default run also reproduces two records elsewhere in this file: 399 folders +in the enumeration, and three inbound `Version` messages per connect. The +deferred run enumerates nothing, by construction. `QuadCortex._hello()`, which `pyquadcortex.protocol.connect()` runs for you, does the same thing with one deliberate difference: it does **not** issue a host diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 92c5850..ff56f59 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -570,10 +570,15 @@ def _hello(self, timeout: float = 5.0, settle: float = 2.0, valid CC version). 3. ``Connection{connected: true}``. 4. A READ for each state type in ``_SUBSCRIBE_TYPES`` - this is the - subscription that makes the device start pushing that state. The - ``File`` READ is optional because it immediately enumerates the - entire folder tree. Whether it also subscribes later file changes - has not been measured. + subscription that makes the device start pushing that state, with + one measured exception. The ``File`` READ only ENUMERATES: it + immediately dumps the whole folder tree, and omitting it does not + stop the push a save announces. Measured 2026-09-09 on CorOS 4.0.1 + / ``d14e``: an on-unit Save As announced ``File`` identically with + the READ sent and with it omitted (``docs/protocol.md`` section + 4.2, which also says what was NOT measured). So + ``initial_file_listing=False`` costs the enumeration and nothing + else a save announces. Returns the echoed ResetCommsBuffers reply. After this, ``read_preset`` and the device's live-sync pushes work.