From e333299d90a1a24bdcf65b2890c3c024b0393b25 Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Tue, 22 Sep 2026 12:45:30 -0500 Subject: [PATCH 1/2] Six follow-ups from #42, four of them a statement the code contradicts #42 was approved and its hardware suite passed on the 4.0.1 unit. These are the non-blocking findings from that review, applied rather than left to the author. None of them changes what the library does. Two of the six refreshed reasons in UNMARKED_OPERATIONS were not true. The wait_for_listing entry said "scratch_preset teardown uses it to confirm deletion"; wait_for_listing appears nowhere under tests/hardware/, and _release_scratch calls delete_preset and nothing else. The reason it replaced was correct, so it is back. The delete_preset entry claimed the teardown "confirms absence"; the fixture's own comment explains that a listing guard was tried there and removed on purpose, because list_presets is unreliable on a single READ, and delete_preset returns None rather than raising when the unit does not answer. Nothing catches either one: the marker test checks only that a reason is longer than 20 characters. docs/protocol.md carried two undo/redo rows in one table. The maintainer's row was already there and said the operations "land in PR #42"; #42 added a second row beside it instead of correcting it. After the merge a reader gets two answers, and one of them says the work has not landed. writing.md asks a correction to replace the wrong sentence rather than sit next to it, so the two rows are folded into the original's position. Every fact from both survives: the 2026-09-03 4.0.1 measurement, the contributor's 4.1.0 run, the bypass edit reversed and reapplied on disposable preset copies, and empty-history behaviour being unknown. The verification column takes the stronger of the two, "read-back + on-unit". The same stale forward reference in the prose at section 11 now names undo() and redo() as the drivers instead of promising them. Three test doubles kept a request(match=) argument that the real transport no longer has, and two of them implemented its semantics fully. A double wider than the thing it stands for is a trap: a later request(msg, match=...) in client.py would pass the whole offline suite and raise TypeError against a unit. In test_client.py the same edit also set self.last_match on every request() call, which would overwrite the predicate await_broadcast stores there and turn the assertions that read it into a TypeError on None. The read-twice comment in the inhibited_modules hardware test said the second read covers a dropped first READ. It does not: _read_state goes to await_broadcast, which raises TimeoutError with no retry. Reading twice is still worth doing, so the loop stays and the comment now says what it is for. profiles.py starts a sentence lowercase, from the semicolon #42 split. Not fixed here: undo, redo and inhibited_modules are absent from QuadCortex41.VERIFIED while their docstrings claim 4.1.0 confirmation, which is the defect #42 fixed for set_device_name alone. Promoting them needs 4.1 hardware evidence this repository does not have, and that evidence is the contributor's. It is raised on #42 for him to settle. No changelog entry: nothing here is visible to someone who installs the package. --- docs/protocol.md | 7 +++---- pyquadcortex/protocol/profiles.py | 2 +- tests/hardware/test_settings_values.py | 4 ++-- tests/test_client.py | 3 +-- tests/test_device.py | 4 +--- tests/test_hardware_markers.py | 4 ++-- tests/test_state.py | 4 +--- 7 files changed, 11 insertions(+), 17 deletions(-) diff --git a/docs/protocol.md b/docs/protocol.md index c3bd071b..fc2c9641 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -1795,8 +1795,8 @@ every entry for that id. **Undo and redo** are drivable: 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 CorOS 4.0.1 by preset read-back, and by a -contributor on 4.1.0 (PR #42, where `undo()` and `redo()` land). `UndoRedo` also -arrives after every accepted grid edit, which makes it an acceptance signal. +contributor on 4.1.0. `undo()` and `redo()` drive it. `UndoRedo` also arrives +after every accepted grid edit, which makes it an acceptance signal. ## 12. What the unit announces, and when @@ -2104,7 +2104,6 @@ wire, with no independent read-back. | connect handshake | `ResetCommsBuffers` + `Version` UPDATE + `ModelRepo` READ + `Connection` + subscribe READs | read-back | the connect gate; state pushes flow only after it | | version read | `Version{action: READ}` | read-back | two messages come back; `version()` accepts only one carrying `device_serial_number` or `app_fw_version` (section 4.4) | | `set_device_name` | `Version{UPDATE, custom_name}` | read-back + on-unit | sparse echo, read-back, and restoration confirmed on CorOS 4.0.1 and 4.1.0 | -| `undo` / `redo` | `UndoRedo{UPDATE, undo}` / `{UPDATE, redo}` | read-back + on-unit | a bypass edit was reversed and reapplied on disposable preset copies; empty-history behaviour is unknown | | `inhibited_modules` | `CompilerInhibitedModules{READ}` | read-back | explicit false/false reply on CorOS 4.0.1 and 4.1.0; true semantics are schema-derived, not yet observed | | `create_local_backup` | `LocalBackup{CREATE}` then `LocalBackup{UPDATE, backup_json}` pushes, the last with `is_last_chunk` | captured only | section 10.5. `can_apply_backup` never appeared, so the refusal path is unverified | | `recall_preset` / `read_preset` | `SetlistPosition{UPDATE, folder_key, position, is_factory, request_id}` then a `RecallPreset` push | read-back | the push echoes the recall's `request_id` | @@ -2168,7 +2167,7 @@ wire, with no independent read-back. | `io_settings` / `set_input_level` / `set_output_level` | `IOSettings{READ}` / `{UPDATE, settings{in_port` or `out_port{port_id, level}}}` | read-back | also reports impedance, type, ground lift and `plugged` | | `global_eq` / `set_global_eq_bypassed` | `GlobalEQ{READ}` / `{UPDATE, bypassed}` | read-back | five bands reported as 28 parameters | | `mode` / `set_mode` | `Mode{READ}` / `{UPDATE, mode}` | read-back | a slot index; `available_modes` lists the configured slots | -| host undo / redo (`undo()` / `redo()` land in PR #42) | `UndoRedo{UPDATE, undo: true}` / `{redo: true}` | preset read-back | measured 2026-09-03 on CorOS 4.0.1 and by a contributor on 4.1.0 | +| `undo` / `redo` | `UndoRedo{UPDATE, undo: true}` / `{redo: true}` | read-back + on-unit | measured 2026-09-03 on CorOS 4.0.1 and by a contributor on 4.1.0; a bypass edit was reversed and reapplied on disposable preset copies; empty-history behaviour is unknown | | `preset_dirty` | `PresetDirty{READ}` | request_id echo | answers as `UPDATE` in 2 to 11 ms; `is_dirty` has no presence; pushed unsolicited only when the flag changes | | `set_gig_view` | `ShowGigView{UPDATE, show}` | read-back + on-unit | `show` has no presence | | `set_param(LaneInput(row), ...)` | `Grid{UPDATE, preset{chains{row, input_control{hash: 28000, params{index, param_values}}}}}` | read-back | `NOISE REDUCTION`, `BYPASS` and `INPUT GAIN`, per-scene included | diff --git a/pyquadcortex/protocol/profiles.py b/pyquadcortex/protocol/profiles.py index ea700aa0..0a3dd768 100644 --- a/pyquadcortex/protocol/profiles.py +++ b/pyquadcortex/protocol/profiles.py @@ -25,7 +25,7 @@ class QuadCortex41(QuadCortex): not reproduced it, which is what ``Evidence.CONTRIBUTED`` says here. ``create_local_backup`` has its own dated 4.1.0 capture. The contributed device-name round trip also verified ``set_device_name``; both are VERIFIED. - other inherited operations refuse under ``Support.VERIFIED`` and run with + Other inherited operations refuse under ``Support.VERIFIED`` and run with a warning under ``Support.EXPERIMENTAL``. The snapshot is deliberately absent: binding the 4.0.1 constants would hand a 4.1 user names their unit does not use. diff --git a/tests/hardware/test_settings_values.py b/tests/hardware/test_settings_values.py index ea6c381b..0c282c16 100644 --- a/tests/hardware/test_settings_values.py +++ b/tests/hardware/test_settings_values.py @@ -46,8 +46,8 @@ def test_inhibited_modules_is_a_complete_read_only_snapshot(qc): Presence matters here: protobuf also returns false when an optional field was never sent, and reporting that default as device state would be a guess. """ - # Read twice because a first state READ can be dropped; both successful - # replies must carry explicit fields rather than protobuf defaults. + # Read twice so a second reply must also carry explicit fields rather than + # protobuf defaults. A dropped first READ raises; there is no retry here. for _ in range(2): state = qc.inhibited_modules() assert state.action == pa.MessageAction.UPDATE diff --git a/tests/test_client.py b/tests/test_client.py index 7beb8337..5b35edaa 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -38,9 +38,8 @@ def __init__(self, canned=None): def send(self, msg): self.sent.append(msg) - def request(self, msg, timeout=5.0, match=None): + def request(self, msg, timeout=5.0): self.sent.append(msg) - self.last_match = match return self.canned.get(type(msg).__name__) def next_request_id(self): diff --git a/tests/test_device.py b/tests/test_device.py index acae557d..922453a6 100644 --- a/tests/test_device.py +++ b/tests/test_device.py @@ -82,14 +82,12 @@ def __init__(self, canned, trailing=()): def send(self, msg): self.sent.append(msg) - def request(self, msg, timeout=5.0, match=None): + def request(self, msg, timeout=5.0): self.sent.append(msg) reply = self.canned[type(msg).__name__] for message in [reply] + self.trailing: for listener in list(self.listeners): listener(message) # listeners see a reply first (ADR-0009) - if match is not None and not match(reply): - raise TimeoutError(f"canned {type(reply).__name__} did not match") return reply def await_broadcast(self, expected_class, trigger, timeout=5.0, match=None): diff --git a/tests/test_hardware_markers.py b/tests/test_hardware_markers.py index 2792fbbd..4d2db48a 100644 --- a/tests/test_hardware_markers.py +++ b/tests/test_hardware_markers.py @@ -29,12 +29,12 @@ # copy into a free User slot and deletes it again - but no test uses it yet. "save_current_preset": "the undo/redo test's scratch_preset fixture confirms a save into a free User slot, but the test verifies undo/redo rather than the save wire shape", "recall_preset": "no hardware test yet; a recall discards the loaded preset's unsaved edits, so it needs scratch_preset around it", - "delete_preset": "the undo/redo test's scratch_preset teardown deletes its copy and confirms absence; no test isolates the delete wire shape itself", + "delete_preset": "the undo/redo test's scratch_preset teardown deletes its copy, but that delete is deliberately unconfirmed and a teardown asserts nothing", "copy_preset": "no hardware test yet; it writes into a second setlist, so a failed run leaves a stray preset in the owner's Directory", "move_preset": "no hardware test yet; it rearranges the slots a player has laid out for a gig, which a restore cannot make invisible mid-run", "read_preset": "the undo/redo test reads its scratch copy to choose an edit, but verifies the history result rather than the read operation itself", "find_preset": "no hardware test yet; it needs a name that exists on the unit, which the loaded preset supplies - just not written", - "wait_for_listing": "scratch_preset teardown uses it to confirm deletion; no test independently verifies its polling and stability contract", + "wait_for_listing": "no hardware test yet; it is the polling wrapper round list_presets and says nothing until a write changes a listing", "create_setlist": "no hardware test yet; it adds a folder to the owner's Directory that a failed run would leave behind", "delete_setlist": "no hardware test yet; it deletes a folder and everything in it, which is the one preset-library mistake nothing can undo", "duplicate_setlist": "no hardware test yet; it copies a whole setlist preset by preset, so a failed run leaves a partial folder behind", diff --git a/tests/test_state.py b/tests/test_state.py index 12e3526c..c08c17b4 100644 --- a/tests/test_state.py +++ b/tests/test_state.py @@ -114,7 +114,7 @@ def await_broadcast(self, message_class, trigger, timeout=5.0, match=None): self.push(reply) return reply - def request(self, message, timeout=5.0, match=None): + def request(self, message, timeout=5.0): name = type(message).__name__ self.sent.append(message) self.reads[name] += 1 @@ -126,8 +126,6 @@ def request(self, message, timeout=5.0, match=None): if callable(reply): reply = reply() self.push(reply) # every listener sees it first... - if match is not None and not match(reply): - raise TimeoutError(f"the canned {name} did not satisfy the waiter") return reply # ...and only then does the caller wake # -- the unit's side ------------------------------------------------------ From 349c194562f0ea9264b0731457849815e819c65c Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Tue, 22 Sep 2026 12:55:46 -0500 Subject: [PATCH 2/2] Triage: an unevidenced flag and a comment #42 made stale Two findings from /triage-pr on the first commit, both the same defect this pull request exists to remove: a sentence the code contradicts. The merged undo/redo coverage row claimed "read-back + on-unit". The table's own legend defines on-unit as confirmed on the unit's own screen, and no record in this repository says anyone watched the screen. Section 11 says "Measured 2026-09-03 on CorOS 4.0.1 by preset read-back". The undo and redo docstrings say a bypass edit was reversed and reapplied, with no screen reading. test_identity_and_history.py asserts only through read_current_preset(). The fold took the stronger of the two columns as though strength were the question; it is not, the measurement is, and the row it replaced already had it right. Back to "preset read-back", which is the maintainer's own wording. Nothing catches this: no test parses the Verified-by column. The section comment above the preset-library entries still said the scratch_preset fixture exists "but no test uses it yet". #42 landed the test that uses it, and the two entries immediately below the comment both describe that test. Four consecutive lines gave two answers to the same question. Also corrected: "drive it" in section 11 pointed at the 4.1.0 measurement rather than at the messages, because that measurement is the nearest antecedent. Dismissed: the merged row spelling the redo half `{redo: true}` rather than `{UPDATE, redo}` - the action is carried by the first half and this is the pre-existing row's shorthand. Raised for later, not here: nothing pins the test doubles' request() signature against protocol.transport.Transport.request, which is why #42 could widen three doubles and stay green. That wants a source-reading test of its own. --- docs/protocol.md | 7 ++++--- tests/test_hardware_markers.py | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/protocol.md b/docs/protocol.md index fc2c9641..1b92e1f5 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -1795,8 +1795,9 @@ every entry for that id. **Undo and redo** are drivable: 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 CorOS 4.0.1 by preset read-back, and by a -contributor on 4.1.0. `undo()` and `redo()` drive it. `UndoRedo` also arrives -after every accepted grid edit, which makes it an acceptance signal. +contributor on 4.1.0. `undo()` and `redo()` send these messages. `UndoRedo` +also arrives after every accepted grid edit, which makes it an acceptance +signal. ## 12. What the unit announces, and when @@ -2167,7 +2168,7 @@ wire, with no independent read-back. | `io_settings` / `set_input_level` / `set_output_level` | `IOSettings{READ}` / `{UPDATE, settings{in_port` or `out_port{port_id, level}}}` | read-back | also reports impedance, type, ground lift and `plugged` | | `global_eq` / `set_global_eq_bypassed` | `GlobalEQ{READ}` / `{UPDATE, bypassed}` | read-back | five bands reported as 28 parameters | | `mode` / `set_mode` | `Mode{READ}` / `{UPDATE, mode}` | read-back | a slot index; `available_modes` lists the configured slots | -| `undo` / `redo` | `UndoRedo{UPDATE, undo: true}` / `{redo: true}` | read-back + on-unit | measured 2026-09-03 on CorOS 4.0.1 and by a contributor on 4.1.0; a bypass edit was reversed and reapplied on disposable preset copies; empty-history behaviour is unknown | +| `undo` / `redo` | `UndoRedo{UPDATE, undo: true}` / `{redo: true}` | preset read-back | measured 2026-09-03 on CorOS 4.0.1 and by a contributor on 4.1.0; a bypass edit was reversed and reapplied on disposable preset copies; empty-history behaviour is unknown | | `preset_dirty` | `PresetDirty{READ}` | request_id echo | answers as `UPDATE` in 2 to 11 ms; `is_dirty` has no presence; pushed unsolicited only when the flag changes | | `set_gig_view` | `ShowGigView{UPDATE, show}` | read-back + on-unit | `show` has no presence | | `set_param(LaneInput(row), ...)` | `Grid{UPDATE, preset{chains{row, input_control{hash: 28000, params{index, param_values}}}}}` | read-back | `NOISE REDUCTION`, `BYPASS` and `INPUT GAIN`, per-scene included | diff --git a/tests/test_hardware_markers.py b/tests/test_hardware_markers.py index 4d2db48a..c8b4db51 100644 --- a/tests/test_hardware_markers.py +++ b/tests/test_hardware_markers.py @@ -26,7 +26,7 @@ # -- the preset library: writes that would touch the owner's own presets --- # The scratch_preset fixture is what these would be built on - it saves a - # copy into a free User slot and deletes it again - but no test uses it yet. + # copy into a free User slot and deletes it again. The undo/redo test uses it. "save_current_preset": "the undo/redo test's scratch_preset fixture confirms a save into a free User slot, but the test verifies undo/redo rather than the save wire shape", "recall_preset": "no hardware test yet; a recall discards the loaded preset's unsaved edits, so it needs scratch_preset around it", "delete_preset": "the undo/redo test's scratch_preset teardown deletes its copy, but that delete is deliberately unconfirmed and a teardown asserts nothing",