From cabf3994b0dcf00206637768ef0985e520694b51 Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Fri, 4 Sep 2026 11:37:00 -0500 Subject: [PATCH 1/3] fix: version() no longer answers with the unit's own question The unit answers a Version READ twice: the full UPDATE, and 1 ms later its own Version{READ} carrying action alone - the question it asks Cortex Control. Neither carries a request_id, so Transport.request correlated by type and handed the second one to whichever waiter was next. Five back-to-back version() calls on the maintainer's unit returned full, empty, full, empty, full, and a caller reading custom_name or the serial got "" every second time with no error. version() now waits by type and predicate and accepts only a Version that carries an identity field, device_serial_number or app_fw_version. The unit's question carries neither, nor does the handshake's cortex_control_version_valid answer. A PARTIAL reply carrying one of the two is still returned: four state tests prove the per-field cache rule with exactly that shape, and refusing it would turn the rule into a timeout. The two offline fakes that drive the real client through a Version read learned the broadcast path, delivering the reply and the unit's trailing question to listeners as the wire does. Measured on Quad Cortex, CorOS 4.0.1 / d14e, 2026-09-03; after the fix five back-to-back calls all returned the full reply. --- pyquadcortex/protocol/client.py | 22 +++++++++++++++-- tests/test_client.py | 42 +++++++++++++++++++++++++++++++++ tests/test_device.py | 18 ++++++++++++++ tests/test_state.py | 15 ++++++++---- 4 files changed, 91 insertions(+), 6 deletions(-) diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 876114c..86ed0ea 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -459,9 +459,27 @@ def version(self, timeout: float = 10.0): Works without the connect handshake, so it is a good first call to confirm the device is talking. + + Confirmed on hardware 2026-09-03 (Quad Cortex, CorOS 4.0.1 / d14e): the + unit answers a ``Version{READ}`` TWICE - the full UPDATE, and 1 ms later + its own ``Version{READ}`` carrying ``action`` alone, the question it asks + Cortex Control. Neither carries a ``request_id``, so a type-correlated + ``request()`` returned the empty one on every second call: five calls in + a row went full, empty, full, empty, full. The wait therefore accepts + only a ``Version`` that carries IDENTITY - ``device_serial_number`` or + ``app_fw_version`` - which the unit's question does not, and neither + does the handshake's ``cortex_control_version_valid`` answer. A partial + reply carrying one of the two is still returned, because the cache keeps + what the unit sent and re-reads for the rest (CLAUDE.md, "never cache an + incomplete reply as if it were complete"). See ``protocol.md``, "A + ``Version`` READ is answered twice". """ - return self._t.request( - pa.VersionMessage(action=pa.MessageAction.READ), timeout=timeout + return self._t.await_broadcast( + pa.VersionMessage, + lambda: self._t.send(pa.VersionMessage(action=pa.MessageAction.READ)), + timeout=timeout, + match=lambda m: (m.HasField("device_serial_number") + or m.HasField("app_fw_version")), ) def find_preset(self, name: str, setlist: str = Setlist.USER, diff --git a/tests/test_client.py b/tests/test_client.py index e5deaed..f54960b 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -4321,3 +4321,45 @@ def test_the_bypass_switch_delay_takes_milliseconds(): qc = client.QuadCortex(FakeTransport()) with pytest.raises(TypeError, match="no 0..1 device scale"): qc.set_expression_bypass(Block(0, 2), delay_ms=Encoded(0.5)) + + +# -- version() and the unit's own Version READ ---------------------------------- + + +def test_version_insists_on_the_full_reply_and_ignores_the_units_own_read(): + """Measured 2026-09-03 on CorOS 4.0.1 / d14e: a host ``Version{READ}`` is + answered by the full UPDATE and, 1 ms later, by the device's OWN + ``Version{READ}`` carrying ``action`` alone. Neither has a request_id, so a + type-correlated wait hands the second one to whichever waiter is next in + line - five back-to-back ``version()`` calls returned full, empty, full, + empty, full. The read therefore accepts only a ``Version`` carrying an + identity field, serial or firmware. A PARTIAL reply with one of them is + still accepted: the cache keeps what the unit sent and re-reads the rest, + and refusing it here would turn that rule into a timeout. See protocol.md, + "A ``Version`` READ is answered twice".""" + full = pa.VersionMessage(action=pa.MessageAction.UPDATE, + app_fw_version="d14e", + device_serial_number="QA00EE910", + custom_name="Neural DSP Quad Cortex") + fake = FakeTransport() + fake.broadcast = full + qc = client.QuadCortex(fake) + + got = qc.version() + + assert got is full + sent = fake.sent[-1] + assert isinstance(sent, pa.VersionMessage) + assert sent.action == pa.MessageAction.READ + assert not sent.HasField("request_id"), "a READ reply carries no id to echo" + match = fake.last_match + assert match is not None, "version() waited by type alone" + assert match(full) is True + # The device's own question to the host, which arrives right behind the answer. + assert match(pa.VersionMessage(action=pa.MessageAction.READ)) is False + # The connect burst's answer to our announce: an UPDATE, but not the identity. + assert match(pa.VersionMessage(action=pa.MessageAction.UPDATE, + cortex_control_version_valid=True)) is False + # A partial identity is still an answer; the cache's per-field rule owns it. + assert match(pa.VersionMessage(action=pa.MessageAction.UPDATE, + app_fw_version="d14e")) is True diff --git a/tests/test_device.py b/tests/test_device.py index 60cefc5..2f9a5f0 100644 --- a/tests/test_device.py +++ b/tests/test_device.py @@ -90,6 +90,24 @@ def request(self, msg, timeout=5.0): listener(message) # listeners see a reply first (ADR-0009) return reply + def await_broadcast(self, expected_class, trigger, timeout=5.0, match=None): + """The same delivery as :meth:`request`, for a read that waits by type + and predicate rather than by request id - which ``version()`` does, + because the unit's own ``Version{READ}`` arrives right behind the + answer and a type-correlated wait cannot tell them apart. The reply and + the trailing messages all reach the listeners, as on the wire; the + caller gets the first one the predicate accepts.""" + trigger() + reply = self.canned[type(self.sent[-1]).__name__] + arrived = [reply] + self.trailing + for message in arrived: + for listener in list(self.listeners): + listener(message) + for message in arrived: + if isinstance(message, expected_class) and (match is None or match(message)): + return message + raise TimeoutError(f"no {expected_class.__name__} the predicate accepted") + def add_listener(self, listener): self.listeners.append(listener) return lambda: self.listeners.remove(listener) diff --git a/tests/test_state.py b/tests/test_state.py index 7a4a0cf..698ed77 100644 --- a/tests/test_state.py +++ b/tests/test_state.py @@ -81,14 +81,21 @@ def await_broadcast(self, message_class, trigger, timeout=5.0, match=None): name = message_class.__name__ self.reads[name] += 1 trigger() - try: + if name in self.broadcasts: reply = self.broadcasts[name] - except KeyError: # pragma: no cover - a test bug + if callable(reply): + reply = reply(self.sent[-1] if self.sent else None) + elif name in self.replies: + # A READ whose answer is a same-type message with no id to echo - + # `version()` since 2026-09-03 - waits by type and predicate, but + # the unit's answer is the same canned reply either way. + reply = self.replies[name] + if callable(reply): + reply = reply() + else: # pragma: no cover - a test bug raise AssertionError( f"the test asked the unit for a {name} broadcast and set no " f"reply for it") - if callable(reply): - reply = reply(self.sent[-1] if self.sent else None) if match is not None and not match(reply): raise AssertionError( f"the canned {name} does not satisfy the match the real read " From 26ab9c11d220b047245520818853997841c127c8 Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Fri, 4 Sep 2026 11:37:00 -0500 Subject: [PATCH 2/3] docs: one baseline becomes a registry of device profiles (ADR-0020) Two contributions arrived from units the maintainer does not have - a Mini opened over USB (#31) and a CorOS 4.1.0 catalog (#42, then #44) - and neither could be verified on the unit that defines the baseline. ADR-0020 decides the shape before the seam is built: a connection resolves a device profile from device_type and zenos_git_hash in the unit's own Version reply, an unknown pair refuses to connect, profile= is the deliberate way to measure an unmeasured unit, and everything that differs by firmware or model lives on the profile. Profiles are named by CorOS version, never by app_fw, because d14e is reported on both 4.0.1 and 4.1.0. STEERING sections 2 and 6, the decision table and change log, the protocol.md header, the architecture checklist, README, contributing.md and CLAUDE.md now describe profiles with evidence levels instead of one baseline. protocol.md gains the record behind the version() fix, "A Version READ is answered twice". domain-model.md corrects the claim that no host can trigger undo (UndoRedo{UPDATE, undo: true} does, measured on 4.0.1 and reported on 4.1.0) and records the U+00A4 separator seen in 27 labels of the 4.1.0 catalog and none of 4.0.1. No code branches on a version string yet. protocol.models, params and options still mean the Quad Cortex 4.0.1 snapshot, and CC_VERSION still announces 4.0.1. --- CLAUDE.md | 1 + README.md | 3 ++- changelog.md | 22 ++++++++++++++++++++++ contributing.md | 7 +++++-- docs/ADR.md | 29 +++++++++++++++++++++++++++++ docs/STEERING.md | 31 +++++++++++++++++++++++++++++-- docs/architecture.md | 9 ++++++++- docs/domain-model.md | 21 ++++++++++++++++----- docs/protocol.md | 39 +++++++++++++++++++++++++++++++++------ 9 files changed, 145 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f50ca72..e53970c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,6 +25,7 @@ Read `docs/STEERING.md` before non-trivial work (new operations, transport or fr - A parameter value SAYS WHICH SCALE IT IS ON (ADR-0016). Every knob has two number lines: the screen's, which differs per knob, and the device's, which is 0..1 for all 3,809 of them. `set_param` takes one value and it must be typed - `Real` for the screen's line, `Db`/`Hertz`/`Percent`/`Milliseconds`/`Seconds`/`Semitones`/`Cents`/`Bpm` to name the unit and have it checked against the catalog, `Encoded` for the device's line, and a bare string for a string parameter. A bare number is REFUSED, because on a lane VOLUME `Real(0.0)` is unity and `Encoded(0.0)` is silence and nothing in a plain `0.0` says which was meant. `Encoded` stays accepted everywhere and is NEVER advertised where a unit type would serve. Two source-reading tests hold that, and between them they say exactly how far it reaches: `tests/test_examples.py` covers `examples/`, and `tests/test_docs.py` covers the code blocks inside docstrings. Each use must carry a written reason nearby. NOT covered, deliberately: prose in `docs/`, which needs judgement rather than a regex, and the error messages that OFFER `Encoded` to a caller who has just been refused - that is the message's job. `values.py` is exempt because it is where the two scales are defined against each other. Only `Encoded` works with no device attached, since the other two need the catalog. This is protocol-layer work on purpose - the translation boundary governs coordinates this library CHOOSES (rows 1-4, scene letters), not units the device PUBLISHES. - EVERY method that writes a value takes a typed one, not just `set_param` (ADR-0017). The settings are not catalog models, so the scale comes from somewhere else - and there are three cases, which must not be blurred. A wire 0..1 with a KNOWN scale (an input port's GAIN, -12..+60 dB; a Global EQ band's GAIN, -12..+12 dB - and those are NOT known equally well, see below) takes the unit type and converts, through a real `catalog.Parameter` so it gets the one law rather than a private copy. A wire 0..1 with NO known scale (output level, USB level, master volume, Global EQ frequency/Q/OUT level, a Global EQ index) takes `Encoded` only, and a `Real` raises `ControlNotDrivable` naming what would settle it - never an invented span. A setting with no 0..1 line at all (the HOLD threshold in ms, the tuner offset in Hz) refuses `Encoded`, because the wire carries the real number. `units.SETTING_SPANS` holds the two known spans WITH how well each is known, and they differ: four measured points against the manual plus two. SELECTORS are not values and stay plain - impedance, input type, ground lift, hp_select, dry_wet, filter type, mute and bypass take an enum or a bool. - A generated parameter constant CARRIES ITS UNIT in its type (ADR-0018), so a type checker rejects `set_param(LaneOutputParam.VOLUME, Hertz(217))` before it runs. mypy is a BLOCKING CI job over the whole package, with ONE suppression in the whole config (`ignore_missing_imports` for `hid`, which ships no stubs) - the ~195 phantom errors from the generated bindings are fixed by committing `*_pb2.pyi` stubs emitted in the same protoc run. `scripts/compile_protos.sh` refuses to write bindings without them AND rewrites their cross-references package-relative: protoc emits `import Preset_pb2` flat, the bindings survive that through the sys.path shim in `proto/__init__.py`, and a type checker cannot - so every field carrying a `Preset` type would read as `Any` while mypy reported success. `tests/test_packaging.py` holds both halves. The runtime check is unchanged and still covers every other caller. What is easy to break: `set_param`'s three overloads. A `Param` IS an `int`, so an int overload that accepts real values swallows every wrong-unit call - overload resolution takes the first MATCH and a failing first overload falls through. The int overload therefore takes only `Encoded`, a string or a switch, which makes `set_param(target, 21, Real(3))` a static error although it runs; address by index and say `Encoded`, or name the parameter. `tests/test_typing.py` holds both directions and is mutation-tested, because a checker that stops catching things stays green and one that cries wolf gets turned off. +- A connection resolves a DEVICE PROFILE before the handshake (ADR-0020): `device_type` plus `zenos_git_hash` from the unit's own `Version` reply, looked up in a registry of measured profiles. An unknown pair REFUSES to connect; there is no fallback to the nearest profile, and `profile=` is the deliberate way to measure an unmeasured unit. Everything that differs by firmware or model lives on the profile - the generated constants snapshot, the announce string, the hardware facts, the operations measured to differ - and no other module tests a version string. A profile that has not measured an operation refuses it with `ControlNotDrivable` whose evidence says so. Name a profile by CorOS version, never by `app_fw`: d14e is reported on both 4.0.1 and 4.1.0. Until the seam is built, `protocol.models`/`params`/`options` mean the QC 4.0.1 snapshot, and an observation from another profile goes BESIDE the 4.0.1 record in `docs/protocol.md`, dated and named, never in its place. `version()` accepts only a `Version` carrying an identity field (serial or firmware) because the unit answers a `Version` READ twice and `request()` cannot tell the full reply from the device's own READ; a PARTIAL reply is still accepted, because the per-field cache rule owns incomplete answers. - Docstrings state their evidence: confirmed on hardware vs inferred from the schema. When you verify something on hardware, record it (docstring + coverage table) in the same change. - The frame trailer's two flag bytes are REPORTED, and never decide what happens to a payload (ADR-0019). `framing.decode_reports` returns a `Frame` naming all of it: type, `encrypted` (`n+4`), `compressed` (`n+5`), `device_bytes` (`n+6`, still meaningless). Compression is detected by the gzip magic bytes and NOT by the flag - CortexUSB reads the flag and needed a skip-list for types 32 and 33 to make it work, which is the argument. The RX path does compare the two and logs a line when they disagree, because the 15675/15675 agreement was measured on CorOS 4.0.1 only and a firmware that broke it must not do so quietly. And nothing here decrypts: an encrypted payload gets labelled and dropped, because the messages behind that flag are `License` and `CloudLogin` and the key derivation would be reimplemented from someone else's MIT source. Both flags describe the FRAME, not the type - a `License` READ is unflagged and its reply is encrypted - so never key either one off a message type. Wanting the decryption means reopening ADR-0019, not adding coverage. - Code in the RX path preserves "the RX thread never dies": wrap every decode, skip unknown types at debug level, reset the reassembly buffer on anything malformed. diff --git a/README.md b/README.md index 33c36cd..8fb4066 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,8 @@ with it. ## Status **Working, and verified on real hardware** on macOS (Apple Silicon) and Windows, -against **CorOS / Cortex Control 4.0.1** (device firmware `d14e`). Every +against **Quad Cortex, CorOS / Cortex Control 4.0.1** (device firmware `d14e`), +the one device profile measured so far (ADR-0020 in `docs/ADR.md`). Every operation listed below has been exercised on a physical unit. The test suite runs fully offline, with no device attached. diff --git a/changelog.md b/changelog.md index a00d9ba..f8a4139 100644 --- a/changelog.md +++ b/changelog.md @@ -20,6 +20,28 @@ correction. ## Unreleased +### The repo describes device profiles, not one baseline (ADR-0020) + +A profile is what the unit reports in its `Version` reply: `device_type` and +`zenos_git_hash`, the CorOS version. Everything that differs by firmware or +model will live on the profile, connect will resolve it before the handshake, +and an unknown profile will refuse to connect rather than borrow the nearest +one. This entry records the rules; the seam is the next piece of work. No code +branches on a version string yet, and `protocol.models`, `params` and `options` +still mean the Quad Cortex 4.0.1 snapshot. See `docs/ADR.md`. + +### `version()` no longer answers with the unit's own question + +The unit answers a `Version` READ twice: the full reply, and 1 ms later its own +`Version{READ}` carrying `action` alone. `version()` waited by message type, so +two calls close together alternated between them - full, empty, full, empty - +and a caller reading `custom_name` or the serial got `""` every second time +with no error. It now accepts only a `Version` carrying an identity field, the +serial or the firmware, so the unit's question is never returned as the answer. +A partial reply carrying one of the two is still returned; the state cache +keeps what the unit sent and re-reads for the rest. Measured on Quad Cortex, +CorOS 4.0.1 / d14e. + ### You can read back which expression pedals are assigned `set_expression` could always write an assignment. Nothing could read one back: diff --git a/contributing.md b/contributing.md index 87ad287..0113850 100644 --- a/contributing.md +++ b/contributing.md @@ -101,8 +101,11 @@ If your change touches the live device path and you want to verify it on a real - **Quit Cortex Control first.** It holds the USB interface exclusively, so nothing else can talk to the device while it is running. - The device protocol is **unversioned** and can change across CorOS / Cortex Control - updates. This library is verified against **4.0.1** (firmware `d14e`); if you are on - a newer version, re-verify the framing and schema before assuming a bug. + updates. This library is verified against **Quad Cortex, CorOS 4.0.1** (firmware + `d14e`); if you are on a newer version, re-verify the framing and schema before + assuming a bug. A different firmware or a Mini is a different DEVICE PROFILE + (ADR-0020): record what you measure beside the 4.0.1 record in `docs/protocol.md`, + dated and named by CorOS version, rather than in its place. When you confirm behavior on hardware, say so in the pull request: which operation, which CorOS version, and how you verified it (a read-back, or watching the unit). diff --git a/docs/ADR.md b/docs/ADR.md index 9c66c93..05e2b31 100644 --- a/docs/ADR.md +++ b/docs/ADR.md @@ -339,3 +339,32 @@ Records are append-only once `Decided` and built upon: a shipped decision is nev - The trailer offsets live in named constants (`TRAILER_TYPE`, `TRAILER_ENCRYPTED`, `TRAILER_COMPRESSED`, `TRAILER_DEVICE`) so a test can pin them separately from the code that reads them. - `encode_message` writes the same bytes it always did. The host sets neither flag and fills neither device byte. - Anyone who later wants (b) has to reopen this record rather than add it as coverage. + +## ADR-0020: Connect resolves a device profile, and nothing else branches on firmware or model + +- **Status:** Decided (2026-09-03, owner) +- **Decision:** A connection resolves a **device profile** before the handshake, from two fields of the unit's own `Version` reply: `device_type` (QC, or ATMA, which is the Quad Cortex Mini) and `zenos_git_hash` (the CorOS version string). The pair is looked up in a registry of profiles this library has measured. A known pair builds the client and the model for that profile and then runs the handshake with that profile's announce string. An unknown pair **refuses to connect** with an error naming what the unit said. There is no fallback to "the nearest profile". A caller who wants to measure an unmeasured unit passes `profile=` explicitly, and that fails if the unit is not that profile. Everything that differs by firmware or model lives on the profile: the generated constants snapshot, the announce string, the hardware facts, and the operations measured to behave differently. No other module tests a version string. +- **Context:** The library was built against one unit: Quad Cortex, CorOS 4.0.1, app firmware d14e. `docs/protocol.md`, `docs/STEERING.md` and `QuadCortex.CC_VERSION` all name that one baseline, and the protocol carries no version number, so nothing on the wire says when a statement stops being true. Two contributions in September 2026 pushed on that. PR #31 opened the Mini over USB with the same client, although the Mini has four footswitches where the client assumes eight and has controls (`set_stomp_momentary`) it does not have. PR #42 regenerated the model catalog from a CorOS 4.1.0 unit, which renamed seven public constants, removed eleven option enums, changed the members of a kept one, and added eight model ids that a 4.0.1 unit does not have. The maintainer's unit stays on 4.0.1 until the Domain Model work is done, so neither contribution could be verified on the unit that defines the baseline, and merging either would have failed the hardware suite on that unit. The plan the maintainer wants is support for several units at once: Quad Cortex 4.0.1, Quad Cortex 4.1, and the Mini, each measured on its own hardware. + Verified while writing this record: `VersionMessage.DeviceType` has exactly two values, `QC = 0` and `ATMA = 1` (`protocol/proto/ProductionAutomation.proto:116-119`); `zenos_git_hash` reads `"4.0.1"` on the maintainer's unit; a `Version` READ is answered before the handshake (`qcctl version` uses that path and ran today); the recovered schema already carries Mini-only fields (`Mode.atma_page`, `AtmaPowerOnMode`, `atma_looper_lock_mode`), because Cortex Control serves both units from one schema. +- **Options:** + - **(a) One profile per measured unit, resolved at connect, refusing the unknown - chosen.** Cost: a registry, a seam in `connect()`, and one class per profile. Benefit: every statement about the wire has a named owner, and a unit nobody measured cannot be driven by accident. + - **(b) Track the newest firmware and let older units fall behind.** Simplest. Rejected: the maintainer cannot measure the newest firmware, so "tracking" would mean committing constants and behaviours nobody with a unit can check. It also breaks the hardware suite on the only unit that runs it. + - **(c) One client with version checks scattered where behaviour differs.** Familiar shape, cheap to start. Rejected: a table of `if version == ...` is the "rule about parameter types" this repo already learned from (`LANE_OUTPUT_UNASSIGNABLE` had three plausible rules and all were false). Differences must be measured per profile, and a scattered check invites a guess. + - **(d) Read everything from the live catalog and ship no generated constants.** The device does publish its own catalog at connect. Rejected as the whole answer: the constants are what make an index-addressed write free of a catalog fetch and what let a type checker reject a wrong unit (ADR-0018). The live catalog is kept as the check, not the source of the constants. + - **(e) Fall back to the closest known profile when the pair is unknown.** Rejected by the owner, as on PR #31: a client that connects to something it was not designed for and then fails silently is worse than one that refuses. Refuse, and let `profile=` be the deliberate way in. +- **Open Questions:** + - Whether `app_fw_version` is `d14e` on CorOS 4.1.0 as well. The contributor reports so. If true, the app firmware string cannot distinguish the two and profiles must key on `zenos_git_hash`, which this record already does. Unverified by the maintainer. + - The Mini's USB product id and CorOS numbering. PR #31 reports a different product id; no Mini has been measured. `open_device()` still opens product `0x880A` only, so a Mini does not even enumerate today. The Mini profile exists in the registry as "unmeasured, refused" until an owner measures one. + - Whether a future Mini firmware needs its own schema bindings. The recovered schema covers both units today. A profile can carry its own bindings module if a measurement ever demands it; nothing is built for that until then. + - What "measured" means for a profile the maintainer cannot verify. Proposed: the registry records an evidence level per profile, the way `units.SETTING_SPANS` records how well each span is known, so "contributed, not verified by the maintainer" is a stated fact rather than an omission. +- **Rationale:** The unit says what it is before the handshake, so the library can know before it acts. That is the whole argument for resolving at connect. Putting every difference on the profile, rather than where the difference is felt, keeps the rule from `CLAUDE.md` intact: a control we understand but cannot drive refuses, and a control we do not understand is omitted. A profile that has not measured an operation refuses it with `ControlNotDrivable` whose evidence says "not measured on this profile". That is the existing refusal applied to a new axis, not a new mechanism. + Model and firmware are two axes, and they do not need the same treatment. The model decides hardware facts and schema: footswitch count, controls that exist, a different USB product. The firmware decides the catalog snapshot, the announce string and the wire behaviours that were measured to differ. But both resolve through one seam, so there is one place to look. Profiles are concrete, one per unit somebody has measured, not a matrix of flags. A shared base holds every wire shape the schema makes identical; a profile overrides where it was measured to differ. + Namespacing the generated constants under the profile dissolves the rename problem that PR #42 surfaced. A 4.1 snapshot can ship with 4.1 names without changing what a 4.0.1 user imports, and the unversioned names keep meaning the maintainer's baseline until a later record moves them. +- **Consequences:** + - `protocol.connect()` and `pyquadcortex.connect()` gain a profile step: open, read `Version`, resolve, build, handshake. `version()` must return the full reply for this to be safe; today it can return the unit's bare echo of the READ instead (recorded in `protocol.md`, "A `Version` READ is answered twice"). That fix lands first. + - The generated snapshots move under a per-profile namespace. `protocol.models`, `protocol.params` and `protocol.options` keep pointing at the QC 4.0.1 snapshot until a record says otherwise. A connected client exposes its own profile's snapshot, so code written against the connection cannot pick up the wrong one. + - `set_block` checks the model id against the live catalog before sending. Today it sends any id and a refusal from the unit is reported as a DSP or port problem. That check is correct on its own and lands independently of the profile work. + - The hardware suite exposes the connected profile as a fixture. `tests/hardware/test_generated_constants.py` compares against that profile's snapshot, not "the" snapshot. A test with no measurement for the connected profile skips with a reason that names the profile. + - `docs/STEERING.md` and the `docs/protocol.md` header stop naming one baseline and name profiles with evidence levels. Every observation in `protocol.md` says which profile it was measured on. A 4.1 observation is written beside the 4.0.1 record, dated, never in place of it. + - Contributed profiles are welcome, and they arrive as one registry entry, one snapshot, and observations tagged with their profile. The seam, the refusal rule and the evidence levels are the maintainer's to write, because they encode what "supported" means here. + - Reversal is cheap until the second profile ships and expensive after: once code depends on `qc.models` meaning "my profile's snapshot", collapsing back to one namespace breaks every such caller. That is the one-way door this record closes. diff --git a/docs/STEERING.md b/docs/STEERING.md index 474fd3a..74add53 100644 --- a/docs/STEERING.md +++ b/docs/STEERING.md @@ -22,7 +22,7 @@ The whole repository: the `pyquadcortex/` package (including the committed gener ### Integration points -- **The device itself:** wire behavior is verified against CorOS / Cortex Control 4.0.1, device firmware d14e. The protocol carries no version number, so nothing is negotiated at runtime. +- **The device itself:** wire behavior is verified per DEVICE PROFILE (ADR-0020), a profile being `device_type` plus `zenos_git_hash` (the CorOS version) as the unit reports them in its `Version` reply. One profile is measured by the maintainer: Quad Cortex, CorOS 4.0.1, firmware d14e. Quad Cortex 4.1.0 has contributed evidence the maintainer cannot verify; the Quad Cortex Mini (`device_type` ATMA) has none. The protocol carries no version number, so the profile read at connect is the only version information there is. - **hidapi:** the `hid` pip package is a ctypes binding to the OS-level hidapi C library, which users install themselves (see README). - **PyPI:** published as `pyquadcortex` with the `qcctl` console script; release process in [`releasing.md`](releasing.md). - **Planning notes:** the maintainer's planning material for future work (including the domain model) lives in a separate private repo; this repo carries only the library and its engineering docs. @@ -68,7 +68,7 @@ The model layer holds the state (design in [`domain-model.md`](domain-model.md) - **The protobuf runtime pin is coupled to the committed gencode, and so is the generator floor.** The runtime validates `runtime >= gencode` at import time; a mismatch is a hard `ImportError` for every user. Currently gencode 7.35.1, pinned `>=7.35.1,<8` (see ADR-0001). The generator is `grpcio-tools`, which carries its own protoc and so decides the gencode by which version is installed, hence the `grpcio-tools>=1.83.0` floor in the dev extra. Older gencode still imports, so both guards are explicit: `scripts/compile_protos.sh` refuses to write a downgrade, and `tests/test_packaging.py` proves the committed gencode and the pin floor are the same number (see ADR-0008). - **Python >= 3.11.** - **The default test suite runs fully offline.** No test imports `hid`, touches hardware, or needs `DYLD_LIBRARY_PATH`; CI runs the real suite on plain runners for every PR (see ADR-0002). A separate hardware-in-the-loop suite - state-neutral on success, best-effort restore on failure, never run in CI - lives in `tests/hardware/` and runs only under `pytest --hardware` (see ADR-0005). That gate is TWO hooks in `tests/hardware/conftest.py`, not one: pytest offers `pytest_ignore_collect` only the paths it reaches by walking a directory, so a path named on the command line is caught instead by `pytest_collection_modifyitems`, which stops the run with an error naming the flag. `tests/test_hardware_gate.py` holds both halves up through a subprocess. Its modules must stay import-safe offline, and two offline tests hold that: `tests/test_hardware_gate.py` collects the whole tree under `--hardware` with `hid` poisoned, which imports every module in the directory, and `tests/test_scene_echo_predicates.py` imports `tests/hardware/test_write_echo.py` to exercise its predicates with no unit attached - the only way a predicate that can never match gets caught cheaply. -- **Wire baseline: CorOS / Cortex Control 4.0.1, firmware d14e.** The protocol is unversioned, so no behavior is guaranteed across firmware updates; [`architecture.md`](architecture.md) has the re-verification checklist. +- **Wire behaviour is stated per device profile, and a profile is named by CorOS version, never by `app_fw`** (ADR-0020). The measured baseline is Quad Cortex, CorOS 4.0.1, firmware d14e; d14e is also reported on 4.1.0, so it distinguishes nothing. An unknown profile refuses to connect rather than borrowing the nearest one. An observation from another profile is recorded beside the 4.0.1 record in `protocol.md`, dated and named. The protocol is unversioned, so no behavior is guaranteed across firmware updates; [`architecture.md`](architecture.md) has the re-verification checklist. - **Exclusive device access.** Cortex Control holds the HID interface exclusively, so the library and Cortex Control cannot be connected at the same time. ## 7. Decision Records @@ -96,6 +96,7 @@ Decisions for this area are recorded in [`ADR.md`](ADR.md): | ADR-0017 | Every setting takes a typed value, and says so when it has no scale to convert against | | ADR-0018 | A parameter constant carries its unit, and CI runs a type checker | | ADR-0019 | The frame trailer's flags are read and reported; an encrypted payload is labelled, not decrypted | +| ADR-0020 | Connect resolves a device profile, and nothing else branches on firmware or model | ## 8. Open Questions @@ -135,6 +136,32 @@ Single-device, single-connection USB HID at interactive rates (129-byte reports) ## Change Log +### 2026-09-03 - One baseline becomes a registry of device profiles (ADR-0020) + +**What changed:** the repo stops describing one firmware as "the" baseline and +describes device profiles instead. A profile is `device_type` plus +`zenos_git_hash` from the unit's own `Version` reply, and it owns everything +that differs by firmware or model: the generated constants snapshot, the announce +string, the hardware facts, and the operations measured to differ. Connect will +resolve the profile before the handshake and refuse an unknown one. The +`protocol.md` header, section 2 and section 6 here, and `CLAUDE.md` now say so. +`version()` accepts only a `Version` carrying an identity field, because the unit +answers a `Version` READ with the full reply AND its own `Version{READ}` 1 ms +later, and a type-correlated wait returned the empty one every second call. + +**Why:** two contributions arrived from units the maintainer does not have - a +Mini opened over USB (#31) and a CorOS 4.1.0 catalog (#42, then #44) - and +neither could be verified on the unit that defines the baseline. Merging either +would have failed the hardware suite on that unit and moved the baseline without +a decision. The maintainer wants Quad Cortex 4.0.1, Quad Cortex 4.1 and the Mini +supported at once, each measured on its own hardware, so the shape had to be +decided before the seam is built. + +**What did NOT change, on purpose:** no code branches on a version string yet. +`protocol.models`, `params` and `options` still mean the QC 4.0.1 snapshot, and +`CC_VERSION` still announces 4.0.1. The seam, the registry and the per-profile +namespaces are the next piece of work; this entry records the rules they follow. + ### 2026-09-03 - The trailer's two unread bytes are named (ADR-0019) **What changed:** `framing.decode_reports` returns a frozen `Frame` instead of a diff --git a/docs/architecture.md b/docs/architecture.md index 2561615..1d0597f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -691,7 +691,14 @@ and no schema version on the wire, so nothing tells you at runtime that a firmware update changed a message. Assume nothing survives a major update until you re-check it. -When moving to a new CorOS / Cortex Control release: +A new CorOS release is a new DEVICE PROFILE, not a replacement of the baseline +(ADR-0020). Its constants, announce string and measured behaviours arrive as a +registry entry beside the existing ones, and its observations are recorded in +`protocol.md` beside the 4.0.1 record, dated and named. Name it by +`zenos_git_hash`, the CorOS version, never by `app_fw`: d14e is reported on +both 4.0.1 and 4.1.0. + +When measuring a new CorOS / Cortex Control release: 1. **Re-recover and re-diff the schema.** The `.proto` files in `protocol/proto/` were recovered from the Cortex Control application for diff --git a/docs/domain-model.md b/docs/domain-model.md index 12486a9..1655684 100644 --- a/docs/domain-model.md +++ b/docs/domain-model.md @@ -1143,11 +1143,13 @@ tried rather than just what is unknown. ### Genuinely open - **`RecallPreset.reason` UNDO.** The value exists in the schema and has never been - observed. It may be unreachable on this firmware: there is **no grid-level undo on the - unit** - the only UNDO is Looper X's, which is a Looper action and not a preset recall - - so nothing found so far can cause a recall whose reason is UNDO. `UndoRedo` messages do - arrive after accepted edits and carry a per-slot frame count, so the undo machinery is - real; what is missing is any way for a human or a host to trigger it. + observed. The unit's undo IS reachable from a host: a sparse `UndoRedo{UPDATE, undo: + true}` (`08 01 28 01`) reverses the last grid edit and `redo: true` (`08 01 30 01`) + reapplies it - measured 2026-09-03 on Quad Cortex, CorOS 4.0.1 / d14e, and by a + contributor on 4.1.0 (PR #42, where the client methods land). The touchscreen still has + no undo of its own beyond Looper X's. Whether the recall that follows a host undo + carries `reason: UNDO` was not captured in either session - both read the preset back + instead of watching the push - so this stays open, one listener away from an answer. - **Bypass persistence over MIDI.** The unit's own SCENE BYPASS BEHAVIOR wording groups **MIDI with footswitches**, not with the touchscreen - a distinction the manual's summary omits. A USB HID write was measured and behaves like the touchscreen, but the MIDI half @@ -1417,6 +1419,15 @@ On ``, `blob` is also unexplained: a same-length string of letters that **changes between fetches**. Two dumps of one unit taken minutes apart differed on 338 models and on nothing else. A per-fetch token of some kind, not content. +On `