Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion 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`. 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.
- 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. The connect burst is waited for as a GROUP: `HandshakeBurst.BURST_TAIL` names the four messages that close it, and the fixture registers the model cache before the recorder so that "the recorder has all four" means the cache has applied them. Never wait on one message of that group - `RecallPreset` is its FIRST member and the other three trail it by 3.6-6.0 ms against a 100 ms poll, which cost two hardware tests a few runs in a hundred. A new `StateEntry` comes through `BURST_TAIL`, `OUTSIDE_THE_BURST` or `NOT_WARMED_BY_THE_BURST` in `tests/test_handshake_burst_recorder.py`, with its reason, and there is no fourth way. 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 Down
23 changes: 23 additions & 0 deletions docs/STEERING.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,29 @@ Single-device, single-connection USB HID at interactive rates (129-byte reports)

## Change Log

### 2026-09-14 - The connect burst is waited for as a group, not a head message

**What changed:** the hardware suite's burst recorder waits for every message in
`HandshakeBurst.BURST_TAIL` - `RecallPreset`, `SetlistPosition`, `PresetDirty`,
`Scene` - rather than for `RecallPreset` alone. The connection fixture registers
the model cache BEFORE the recorder, so "the recorder has all four" implies "the
cache has applied all four" rather than merely nearly. `unfinished()` names what
never arrived, and prints once in the run's own report as well as in the three
tests that guard on it. A new cache entry now has to come through `BURST_TAIL`,
`OUTSIDE_THE_BURST` or `NOT_WARMED_BY_THE_BURST` in
`tests/test_handshake_burst_recorder.py`, each with its reason - the same shape
as `UNMARKED_OPERATIONS` and `BOUNDARY_MODULES`.

**Why:** `RecallPreset` is the FIRST of those four on the wire and the other three
follow within 3.6 to 6.0 ms, against a 100 ms poll. Two hardware tests failed
together on 2026-09-11 and passed on a re-run of the same commit; simulating the
poll's phase puts it at a few runs in a hundred. A gate that fails intermittently for reasons unrelated to
the change teaches people to re-run until green, which is how a real regression
gets waved through.

**Scope of impact:**
- **Updated:** tests/hardware/conftest.py, tests/hardware/test_model_state.py, tests/hardware/test_preset_surface.py, tests/hardware/test_broadcast_listener.py, tests/hardware/readme.md, tests/test_handshake_burst_recorder.py, docs/protocol.md "Connect burst, measured", CLAUDE.md, STEERING.md section 10
- **Not updated (intentionally):** ADR.md - the stop condition is a bug fix in the suite, not an architectural choice; nothing under `pyquadcortex/` - the library never had this bug; `BURST_TAIL` stays off the profile class (ADR-0020) until a second profile has measured its own burst, and the timeout names the message it never saw, which is the evidence that would move it
### 2026-09-12 - The Off-detent table is deleted; the floor is derived (ADR-0015)

**What changed:** `units.FLOOR_WIRE` is gone. `Parameter.floor` is derived from
Expand Down
25 changes: 25 additions & 0 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -2095,6 +2095,31 @@ the order `RecallPreset`, `SetlistPosition`, `PresetDirty`, `Scene` - and with n
pushes, because nothing changed. The seed `RecallPreset` sets `action`, `preset` and
`reason`.

Re-measured 2026-09-14 on 4.0.1 / d14e over three consecutive connections, timestamped from
before the handshake by a `connect(before_handshake=...)` listener, so these are seconds
after connect on the same clock as the 4.9 s / 5.1 s figures above. The four landed at
11.21 s, 11.08 s and 11.07 s, spread over 6.0 ms, 3.6 ms and 5.8 ms, in that same order
every time. The arrival time varies session to session - 9 s to 11.2 s observed - so it is
the ORDER and the SPREAD that are stable enough to build on, not the moment.

**`RecallPreset` is the FIRST of the four, not the last.** That matters to anything
treating it as the signal that the burst is over: the other three are still a few
milliseconds out. The hardware suite's burst recorder did exactly that, and it polls at
100 ms, so its stop landed at a uniformly random point in the 100 ms after `RecallPreset`
and falls inside the group a few times in a hundred. `Scene` is lost most often, because it
arrives last - and losing `Scene` alone is already enough to fail a test.

Two kinds of evidence, and they are worth keeping apart. **Observed:** it failed a real run
on 2026-09-11 and passed on a re-run of the same commit. **Simulated:** driving the real
recorder with the four messages at their measured spacing and the poll's phase drawn
uniformly from its 100 ms interval - which is what a connection does to it - loses one or
more of the three over 300 runs, and 0 of 300 after the change. Two independent runs of
that simulation put the rate between 6% and 10% per message, differing by how the 3.6-6.0 ms
spacing is modelled, so the order of magnitude is the finding and the digits are not. The
recorder now waits for all four (`BURST_TAIL` in `tests/hardware/conftest.py`), and
`tests/test_handshake_burst_recorder.py` holds the mechanism offline with a gap staged wide
enough that it needs no simulation. Wait for the group, not for its head.

**`read_preset()` RECALLS the slot it reads** - that was already documented - and the
recall **resets the active scene to the preset's default, discards unsaved edits, and
interrupts the audio**.
Expand Down
Loading
Loading