Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
f49c35b
docs: design spec for the ADR-0020 device profile seam
jonathanstokes Sep 5, 2026
6e7d07e
docs: spec self-review - one-way imports, generated example, --verifi…
jonathanstokes Sep 5, 2026
b381fbb
docs: implementation plan for the device profile seam
jonathanstokes Sep 5, 2026
04b17a3
feat: the vocabulary a device profile is described in (ADR-0020)
jonathanstokes Sep 6, 2026
3720e9e
feat: generated constants live in a per-firmware snapshot package; th…
jonathanstokes Sep 6, 2026
779da56
feat: QuadCortex is the 4.0.1 profile, and a subclass refuses what it…
jonathanstokes Sep 6, 2026
094c570
fix: a subclass the guard rejects is never registered as a profile
jonathanstokes Sep 6, 2026
d2489cd
feat: the profile registry, resolve(), and the two stubs that show ho…
jonathanstokes Sep 6, 2026
59dc98e
feat: connect() resolves the device profile before the handshake and …
jonathanstokes Sep 6, 2026
216eee8
fix: the identity read shares the handshake's patience, and the annou…
jonathanstokes Sep 6, 2026
1130350
feat: set_block refuses a model id the unit's own catalog does not list
jonathanstokes Sep 6, 2026
4e6a2fb
feat: generators write a named snapshot and render the docstring exam…
jonathanstokes Sep 6, 2026
efec412
fix: the params docstring example is the lowest-id cab across every C…
jonathanstokes Sep 6, 2026
835604c
test: the hardware suite names the operations it verifies and reports…
jonathanstokes Sep 6, 2026
f663c38
fix: the hardware report counts teardown, claims only what tests clai…
jonathanstokes Sep 6, 2026
5da6bee
docs: the profile seam in STEERING, CLAUDE, protocol, architecture, c…
jonathanstokes Sep 6, 2026
9a489ab
docs: QuadCortex lives in client.py, and the seam entry carries the d…
jonathanstokes Sep 6, 2026
2eb162d
fix: a profile subclasses QuadCortex directly, and operations() count…
jonathanstokes Sep 6, 2026
9f00086
fix: generators write into the repo's catalogs package wherever they …
jonathanstokes Sep 6, 2026
86cdb8a
fix: the hardware report claims only what ran, the scratch fixture ca…
jonathanstokes Sep 6, 2026
31ed288
docs: the snapshot header carries the name only; tidy imports and the…
jonathanstokes Sep 6, 2026
b8492ba
feat: --profile points the hardware suite at a unit the registry refuses
jonathanstokes Sep 6, 2026
d57bb9d
fix: connect waits for a Version it can resolve a profile from
jonathanstokes Sep 6, 2026
4957b6a
docs: set_block says the catalog check fetches, and a stub renders no…
jonathanstokes Sep 6, 2026
bf823f0
fix: the scratch fixture cannot leak on a failed save, and --verifies…
jonathanstokes Sep 6, 2026
de7fef1
fix: --snapshot is validated, and a half-generated snapshot still imp…
jonathanstokes Sep 6, 2026
e2718a9
fix: the nearest profile is the newest by version, and HARDWARE says …
jonathanstokes Sep 6, 2026
10b865f
docs: the profile entry in the changelog describes what shipped
jonathanstokes Sep 6, 2026
20bdb1e
fix: measured_firmware takes the versions, so mypy sees the one real …
jonathanstokes Sep 6, 2026
8844e97
docs: STEERING names the shared snapshot helper and the suite's --pro…
jonathanstokes Sep 6, 2026
aca47f3
fix: the scratch teardown deletes unconditionally, a bad --profile st…
jonathanstokes Sep 6, 2026
aa7eba2
fix: resolve()'s hints name a command that actually works, and versio…
jonathanstokes Sep 6, 2026
7be6861
docs: a generated snapshot's __init__ names any connected unit, not j…
jonathanstokes Sep 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Read `docs/STEERING.md` before non-trivial work (new operations, transport or fr

## Conventions

- Dev setup: `uv venv && uv pip install -e ".[dev]"` (or plain venv + pip, see contributing.md). Run tests with `.venv/bin/python -m pytest`. The suite passes offline - no hardware, no `hid` import, no `DYLD_LIBRARY_PATH`. The hardware suite's `--hardware` gate is two hooks in `tests/hardware/conftest.py` and stays two: pytest skips `pytest_ignore_collect` for a path named on the command line, so `pytest_collection_modifyitems` refuses that one loudly. Never fold them into one; `tests/test_hardware_gate.py` proves both. A module in `tests/hardware/` also needs a basename no module under `tests/` owns - pytest maps `tests/hardware/test_scales.py` and `tests/test_scales.py` to one module name and refuses the second, which is why two files there end `_on_unit`. Rename; do not reach for `__init__.py` or `consider_namespace_packages`, because three offline modules do `from waiting import ...` and that works only while pytest puts `tests/` on `sys.path`.
- Dev setup: `uv venv && uv pip install -e ".[dev]"` (or plain venv + pip, see contributing.md). Run tests with `.venv/bin/python -m pytest`. The suite passes offline - no hardware, no `hid` import, no `DYLD_LIBRARY_PATH`. The hardware suite's `--hardware` gate is two hooks in `tests/hardware/conftest.py` and stays two: pytest skips `pytest_ignore_collect` for a path named on the command line, so `pytest_collection_modifyitems` refuses that one loudly. Never fold them into one; `tests/test_hardware_gate.py` proves both. A module in `tests/hardware/` also needs a basename no module under `tests/` owns - pytest maps `tests/hardware/test_scales.py` and `tests/test_scales.py` to one module name and refuses the second, which is why two files there end `_on_unit`. Rename; do not reach for `__init__.py` or `consider_namespace_packages`, because three offline modules do `from waiting import ...` and that works only while pytest puts `tests/` on `sys.path`. A hardware test names what it verifies AND actually asserts on with `@pytest.mark.verifies(*operations)`, checked against `QuadCortex.operations()` at collection; `--verifies NAME` narrows a run to the tests naming it, and refuses a name that is not an operation or that no collected test names. `--profile CLASSNAME` (with `--hardware`) connects as that profile class instead of the one the unit resolves to, which is how a unit the registry would refuse - an unmeasured firmware, or a Mini - gets measured by the suite that measures it. `scratch_preset` is the fixture for getting a disposable copy of the loaded preset to edit. An operation no hardware test names has to appear in `tests/test_hardware_markers.py`'s `UNMARKED_OPERATIONS`, with the reason - that dict is the list a new operation must come through if no hardware test names it.
- Two namespaces, one package (ADR-0006): `pyquadcortex` is the model of the unit, `pyquadcortex.protocol` is the message-level API. The model's code lives in `pyquadcortex/device/` - not `model/`, because in this codebase the identifier `model` means an amp or pedal block (`protocol/models.py`, `catalog.Model`, `ModelCatalog`, `set_block(model=...)`). The model imports the protocol layer; nothing under `pyquadcortex/protocol/` may import from `pyquadcortex/device/`.
- Every conversion between a screen value and a wire value lives in the `pyquadcortex/device/translate/` PACKAGE and nowhere else in the package outside `pyquadcortex/protocol/` - the whole package, not just `device/`, because a rule scoped to a directory is satisfied by moving the code one directory up. It covers rows 1-4, slots 1-8, scene and footswitch letters, preset addresses and display units. Outside the boundary that means no `+1`/`-1` on a coordinate AND none of the other spellings of the same conversion (`ord`/`chr`, a letter table in any container, `divmod` on a position, a one-based `enumerate`, `ROWS.index(...)`), and no module reaching past the boundary for a protocol-layer name that carries a coordinate or a raw scale - the converters and also the readers that hand back wire indexes, such as `protocol.stomp_assignments`. `tests/test_translation.py` reads the source and proves both, and pins where each check stops seeing rather than implying it sees everything. The boundary is a package, so its exemption covers a DIRECTORY: `BOUNDARY_MODULES` in that file names the modules inside it, and adding `translate/anything.py` has to come through that list with a reason - otherwise the arithmetic scan skips the new file for the same reason it skips the real converters. The same file now carries a second list, `PROTOCOL_NON_CONVERSIONS`, for protocol-layer names the boundary uses that are NOT conversions (`field_present`, the port enums). It exists because the boundary reads whole presets now, so "everything it reaches for is a conversion" stopped being true; a name has to be on one list or the other, and which one is a judgement a reviewer makes from the reason written beside it. A model API takes `FootswitchLetter`, never a bare footswitch integer, because a footswitch index and a block's column are different numbers that usually agree. A new conversion goes in that module with its own test, however small it is, and its protocol-layer name joins that file's allowlist in the same commit.
- The model represents what the unit shows, in the unit's own words, and never guesses. A control we understand but cannot yet drive is modelled and REFUSES the operation (ADR-0007); a control we do not understand is omitted, with the reason recorded in `docs/domain-model.md`'s appendix. Nothing ships with a "this might be stale or wrong" caveat. A refusal is `protocol.ControlNotDrivable(control, evidence, workaround)` - never a bare `ValueError` and never a message-only raise. All three fields are required, and `evidence` records what was actually tried, because a refusal nobody can audit is the guess the rule exists to prevent. Before writing one, ADR-0010 applies: the differential capture comes first, and "the unit broadcasts nothing" is not on its own a finding about the wire. Do not derive a refusal from a RULE about parameter types either - the first instance had three plausible rules tried against hardware and all three were false, so `LANE_OUTPUT_UNASSIGNABLE` is a measured list with the disproofs written beside it.
Expand All @@ -25,7 +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; the rule is decided, the seam is not built yet): `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`: a contributor reports d14e on 4.1.0 as well as 4.0.1 (PR #44). 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.
- 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`: a contributor reports d14e on 4.1.0 as well as 4.0.1 (PR #44). `protocol.models`/`params`/`options` are shims over the QC 4.0.1 snapshot in `protocol/catalogs/coros_4_0_1/`; a connection's own snapshot is `qc.models`. 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. A subclass of `QuadCortex` lists what it has verified in `VERIFIED`; everything else it inherits is guarded and refuses under `Support.VERIFIED`. Never put a version check in a method body - override on the profile class, and list the override in `VERIFIED`.
- 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.
Expand Down
31 changes: 26 additions & 5 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,36 @@ correction.

## Unreleased

### BREAKING: the generators take `--snapshot`, and constants moved

`scripts/generate_models.py`, `generate_params.py` and `generate_options.py`
require `--snapshot coros_x_y_z` and write `pyquadcortex/protocol/catalogs/<snapshot>/`;
`--out` is gone. The generated modules moved there; `pyquadcortex.protocol.models`,
`params` and `options` still import and still mean CorOS 4.0.1, as shims.

### The connection knows which unit it is talking to (ADR-0020)

`connect()` reads the unit's `Version` first and picks the profile class for
`(device_type, zenos_git_hash)`: `QuadCortex` for a Quad Cortex on 4.0.1,
`QuadCortex41` for 4.1.0, and `UnsupportedDevice` for anything else, before
the handshake. `connect(profile=...)` names a class deliberately for a unit
nobody has measured. `connect(support=Support.EXPERIMENTAL)` runs operations
a profile has not verified, with one warning each; the default
`Support.VERIFIED` refuses them. `qc.models`, `qc.params`, `qc.options` are the
connection's own constants; `qc.unverified_operations` says what its profile
has not verified. `set_block` refuses a model id the unit's catalog lacks.
The Quad Cortex Mini is recognised and refused with instructions.

### 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`.
model lives on the profile, connect resolves it before the handshake, and an
unknown profile refuses to connect rather than borrowing the nearest one. This
entry records the rules; the entry above is the seam that implements them. No
module tests a version string on its own, and `protocol.models`, `params` and
`options` still mean the Quad Cortex 4.0.1 snapshot, as shims over it. See
`docs/ADR.md`.

### `version()` no longer answers with the unit's own question

Expand Down
25 changes: 25 additions & 0 deletions contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,31 @@ When you confirm behavior on hardware, say so in the pull request: which operati
which CorOS version, and how you verified it (a read-back, or watching the unit).
That evidence is what keeps [docs/protocol.md](docs/protocol.md) trustworthy.

## Adding a device profile

A new CorOS release, or a new model, is a new `QuadCortex` subclass (ADR-0020),
not a change to the existing baseline. On the unit it covers:

1. **Generate the snapshot.** `scripts/generate_models.py --snapshot coros_x_y_z`
and the params and options generators; bind the three modules on the new class.
2. **Run the suite.** `pytest tests/hardware --hardware --profile QuadCortexMini`
against the unit, naming your new class. `--profile` connects as that class
instead of the one the unit's identity resolves to, which is what lets the
suite run at all on a unit the registry would refuse; the suite always
connects `Support.EXPERIMENTAL`, so nothing refuses before it is measured.
3. **Fill `VERIFIED`.** The report at the end of the run names which operations
passed; put those names in the class's `VERIFIED` set.
4. **Record differences beside the 4.0.1 record.** Anything that behaved
differently goes in [docs/protocol.md](docs/protocol.md), dated and named
next to the existing entry, never in its place, and overridden on the new
class.

Profiles are named by CorOS version, never by `app_fw` - a contributor reports
firmware `d14e` on both CorOS 4.0.1 and 4.1.0 (PR #44), so the app firmware
string distinguishes nothing. `MEASURED_ON` lists the exact `zenos_git_hash`
strings a suite run has covered; a patch release is added to it after a suite
run confirms it, not assumed to behave like the version already there.

## Style

Match the style of the surrounding code. Keep changes focused - unrelated cleanups are
Expand Down
Loading
Loading