From 3713a32e89fd921980d76f687a65c275f30a58e7 Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Tue, 22 Sep 2026 11:29:27 -0500 Subject: [PATCH 1/2] Four things #60 left behind, three of them already reviewed #60 merged with five non-blocking review comments unaddressed. Four were defects on main rather than preferences, and the author will not return to them now the pull request is closed. - Both docstrings had replaced their dated capture records with prose. Review thread 3992216374 asked for the 4.0.1 captured shape to stay; it did not. Restored, with the session and frame numbers measured on 2026-09-21. - docs/protocol.md section 10.2 printed the MOVE shape without is_downloads while the coverage table two thousand lines later said the flag is present. One document, two shapes. Section 10.2 now carries it, plus the measured asymmetry: present and false on MOVE, absent from the DELETE in the same session. - delete_preset and move_preset took an unannotated preset. The package ships py.typed, so dropping `name: str` silently removed a guard from every downstream caller: delete_preset(Setlist.USER, 42) type-checked and sent a delete for a preset named "42". Both declare `str | ProductData` again, verified by running mypy over a caller that passes an int. - test_move_preset_matches_the_captured_cortex_builder_bytes claimed a provenance its bytes do not have; they are what the lines above them build. Renamed to what it pins, with the capture it was measured against named. Also restores the by-name form in the silent-transport test. That form is the only one the repository calls (tests/hardware/conftest.py teardown) and a silent device is the case it exists for, so covering only the ProductData form left the hole open. This one was review comment five and is beyond the four agreed; drop it if you would rather it went separately. Evidence for the wire claims is the three recorded CorOS 4.0.1 sessions: one MOVE at session 02 frame 25825, one DELETE at session 02 frame 19033, and 784 of 784 occupied preset-setlist entries keyed /.pb. --- changelog.md | 8 ++++++++ docs/protocol.md | 8 +++++++- pyquadcortex/protocol/client.py | 34 ++++++++++++++++++++++++--------- tests/test_client.py | 25 +++++++++++++++--------- 4 files changed, 56 insertions(+), 19 deletions(-) diff --git a/changelog.md b/changelog.md index 67440c1b..d2fc7925 100644 --- a/changelog.md +++ b/changelog.md @@ -15,6 +15,14 @@ sustained stretch without a correction. ## Unreleased +### `delete_preset()` and `move_preset()` say which types they take + +Both declare `str | ProductData` again. The previous entry left the parameter +unannotated, so a downstream caller passing a number type-checked and then sent +a delete for a preset named after it. The captured `DELETE` and `MOVE` shapes +are back in the docstrings with their dates, and `protocol.md` section 10.2 +prints `is_downloads` on `MOVE`, matching the coverage table. + ### Preserve device-provided preset keys without adding a listing dependency `delete_preset()` and `move_preset()` now also accept the `ProductData` returned diff --git a/docs/protocol.md b/docs/protocol.md index 970fe05d..0f978dd9 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -1363,13 +1363,19 @@ File{action: DELETE, type: 0, ``` File{action: MOVE, type: 0, - folder{key: , files{key: "/.pb"}}, + folder{key: , is_factory: false, is_downloads: false, + files{key: "/.pb"}}, to_folder{key: , files{index: 219}}} ``` Source by file path, destination by linear index. Only same-setlist moves have been observed. `delete_from_library` exists in the schema and was never sent. +`is_downloads` is present and false on `MOVE` and absent from the `DELETE` in +the same session. Measured 2026-09-21 in the three recorded CorOS 4.0.1 +sessions, which hold one `MOVE` (session 02, frame 25825) and one `DELETE` +(session 02, frame 19033). + ### 10.3 Setlists **Creating a setlist** is captured from the unit's own "New Setlist" and diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 7e8601fb..21ed487e 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -4187,7 +4187,8 @@ def save_current_preset( return e.name return None - def _stored_preset_key(self, setlist_path: str, preset) -> str: + def _stored_preset_key(self, setlist_path: str, + preset: str | pa.ProductData) -> str: """Resolve a display name or validate a listed ProductData key.""" if not isinstance(preset, pa.ProductData): # Backward-compatible and deliberately listing-free: hardware @@ -4210,14 +4211,21 @@ def _stored_preset_key(self, setlist_path: str, preset) -> str: f"setlist {setlist_path!r}") return preset.key - def delete_preset(self, setlist_path: str, preset): + def delete_preset(self, setlist_path: str, preset: str | pa.ProductData): """Delete a stored preset from ``setlist_path``. ``preset`` is either its exact display name or the ``ProductData`` - returned by :meth:`list_presets`. On three CorOS 4.0.1 captures every - occupied entry's key was exactly ``/.pb``; passing a - listing entry avoids reconstructing it, while the name form remains a - listing-free compatibility path for best-effort cleanup. + returned by :meth:`list_presets`. Passing a listing entry sends the + device's own key. The name form stays listing-free, for cleanup that + cannot wait for a listing read. + + Confirmed by capture: deleting "Test save to user sl" from slot 28E + sent ``File{action: DELETE, type: 0, folder{key: , + is_factory: false, files{key: "/.pb"}}}`` - the + preset is addressed by its device FILE PATH (name-based, ``.pb`` + extension), NOT by slot index. Measured 2026-09-21: every occupied + preset-setlist entry in the three recorded CorOS 4.0.1 sessions + carried that same key shape. """ msg = pa.FileMessage(action=pa.MessageAction.DELETE, type=0) msg.folder.key = setlist_path @@ -4226,14 +4234,22 @@ def delete_preset(self, setlist_path: str, preset): setlist_path, preset) return self._file_operation(msg) - def move_preset(self, setlist_path: str, preset, to_position): + def move_preset(self, setlist_path: str, preset: str | pa.ProductData, + to_position): """Move a stored preset into ``to_position`` in the same setlist. ``to_position`` is either the linear slot index or the slot name shown on the unit (``"28D"``). ``preset`` may be its exact display name or the ``ProductData`` returned by :meth:`list_presets`; the latter supplies - the device's own key. Cortex Control 4.0.1 was captured adding - ``is_downloads: false`` to this MOVE shape. + the device's own key. + + Confirmed by capture: dragging "Darkglass AO900 2_1" onto slot 28D + sent ``File{action: MOVE, type: 0, folder{key: , + is_factory: false, is_downloads: false, files{key: "/.pb"}}, to_folder{key: , files{index: + 219}}}`` - source by FILE PATH, destination by LINEAR slot index. + ``is_downloads`` is present and false here and absent from the DELETE + in the same session. Measured 2026-09-21. """ msg = pa.FileMessage(action=pa.MessageAction.MOVE, type=0) msg.folder.key = setlist_path diff --git a/tests/test_client.py b/tests/test_client.py index e07a7a5d..3ac42661 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -666,7 +666,12 @@ def test_move_preset_uses_an_authoritative_key_and_the_captured_flag(): assert not sent.to_folder.HasField("is_factory") -def test_move_preset_matches_the_captured_cortex_builder_bytes(): +def test_move_preset_serializes_the_captured_field_order_and_flags(): + # Pins field numbering, field ORDER and the explicit false flags against the + # shape measured in windows-session-02 frame 25825 (CorOS 4.0.1). The key + # below is this test's own string, not a device-supplied one, so this says + # nothing about which key the caller should send - see the tests above for + # that. It does catch is_downloads or is_factory going away. setlist = "/media/p4/Presets/My Presets" product_key = f"{setlist}/Numb.pb" listing = _preset_listing( @@ -1047,17 +1052,19 @@ def test_file_operations_do_not_raise_when_the_device_stays_silent(): # File ops are asynchronous and every host write is STALLed, so a missing reply # says nothing about success. Raising made callers wrap each one in # try/except and verify by re-reading anyway. - transport = TimingOutTransport() - transport.broadcast = _preset_listing( + # Both forms of ``preset``. The by-name form is the one hardware teardown + # uses (tests/hardware/conftest.py), and a silent device is exactly the case + # it has to survive, so testing only the ProductData form leaves that hole. + source = _preset_listing( str(Setlist.USER), {"index": 1, "name": "Some Preset", "key": f"{Setlist.USER}/opaque-source"}, - {"index": 219, "name": "Unsaved"}, - ) - qc = client.QuadCortex(transport) - source = transport.broadcast.folder.files[0] - assert qc.delete_preset(Setlist.USER, source) is None - assert qc.move_preset(Setlist.USER, source, "28D") is None + ).folder.files[0] + for preset in ("Some Preset", source): + qc = client.QuadCortex(TimingOutTransport()) + assert qc.delete_preset(Setlist.USER, preset) is None + assert qc.move_preset(Setlist.USER, preset, "28D") is None + qc = client.QuadCortex(TimingOutTransport()) assert qc.save_current_preset(Setlist.USER, "30A", "Some Preset") == "Some Preset" From c86a3761f00f8d6bd88983c923f3b5c2f73fc2ac Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Tue, 22 Sep 2026 11:39:21 -0500 Subject: [PATCH 2/2] Triage: an unevidenced flag, an overstated count, two changelog entries Four findings from /triage-pr on 3713a32, three of them repo-rule breaches. The blocker was mine: the restored MOVE record gained is_factory: false alongside is_downloads, and the evidence sentence named only is_downloads. In this repository an unevidenced wire assertion is a defect whether or not it is true. Decoding session 02 frame 25825 and frame 19033 settles it - is_factory is explicitly present and false on BOTH captured messages, and to_folder carries neither flag. The claim was right and its evidence was not, so the record now states both flags in a table and says what to_folder omits. The delete_preset coverage row said "three Cortex Control 4.0.1 captures". The three sessions hold one DELETE. The three-session evidence is about listing keys, not about DELETE messages, and the Verified-by column is where evidence strength is declared. Split into "one captured DELETE + three-session key evidence". The move_preset row gained is_factory for the same reason the block did. Both docstrings gave a date and no count, so a reader could not tell the MOVE shape rests on a single frame. Each now names its capture. The changelog carried two Unreleased entries for the same change, the second narrating what the first got wrong. Both are unreleased, so both are editable, and writing.md says a correction replaces the wrong sentence rather than sitting beside it. Folded into one entry, which also drops a docs/protocol.md mention: that file is not in the wheel, and the changelog is for someone who installs the package. Findings on the loop variable shadowing a module import, to_position staying unannotated, SetlistPosition.is_downloads 800 lines away, and the two-clause evidence tag are dismissed. --- changelog.md | 15 ++++----------- docs/protocol.md | 18 ++++++++++++------ pyquadcortex/protocol/client.py | 14 +++++++++----- 3 files changed, 25 insertions(+), 22 deletions(-) diff --git a/changelog.md b/changelog.md index d2fc7925..779df922 100644 --- a/changelog.md +++ b/changelog.md @@ -15,21 +15,14 @@ sustained stretch without a correction. ## Unreleased -### `delete_preset()` and `move_preset()` say which types they take - -Both declare `str | ProductData` again. The previous entry left the parameter -unannotated, so a downstream caller passing a number type-checked and then sent -a delete for a preset named after it. The captured `DELETE` and `MOVE` shapes -are back in the docstrings with their dates, and `protocol.md` section 10.2 -prints `is_downloads` on `MOVE`, matching the coverage table. - ### Preserve device-provided preset keys without adding a listing dependency `delete_preset()` and `move_preset()` now also accept the `ProductData` returned by `list_presets()`, validate that its key belongs to the requested setlist, and -send that key unchanged. The exact-name form remains listing-free and preserves -the measured CorOS 4.0.1 `/.pb` wire shape, including hardware -cleanup when listing reads are silent. The captured move shape now also carries +send that key unchanged. Both take `str | ProductData`, so a caller that passes +anything else is a type error. The exact-name form remains listing-free and +preserves the measured CorOS 4.0.1 `/.pb` wire shape, including +hardware cleanup when listing reads are silent. The captured move shape carries its explicit `is_downloads: false` field. Unmeasured rename and occupied-slot swap behavior are deliberately not exposed. diff --git a/docs/protocol.md b/docs/protocol.md index 0f978dd9..133c034d 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -1371,10 +1371,16 @@ File{action: MOVE, type: 0, Source by file path, destination by linear index. Only same-setlist moves have been observed. `delete_from_library` exists in the schema and was never sent. -`is_downloads` is present and false on `MOVE` and absent from the `DELETE` in -the same session. Measured 2026-09-21 in the three recorded CorOS 4.0.1 -sessions, which hold one `MOVE` (session 02, frame 25825) and one `DELETE` -(session 02, frame 19033). +Both explicit false flags are measured. The three recorded CorOS 4.0.1 +sessions hold one `MOVE` (session 02, frame 25825) and one `DELETE` (session +02, frame 19033); this is what each carries, decoded 2026-09-21. + +| field | `DELETE` | `MOVE` | +|---|---|---| +| `folder.is_factory` | present, false | present, false | +| `folder.is_downloads` | absent | present, false | +| `to_folder.is_factory` | n/a | absent | +| `to_folder.is_downloads` | n/a | absent | ### 10.3 Setlists @@ -2109,8 +2115,8 @@ wire, with no independent read-back. | `set_scene_label` / `set_scene_color` | `SceneLabel` / `SceneColor{UPDATE, index, label/color}` | read-back | colour is ARGB uint32; exact round-trip | | `copy_scene` | `SceneCopy{UPDATE, from_index, to_index, is_swap}` | read-back + on-unit | `from_index` and `is_swap` confirmed; label and colour travel with the state | | `save_current_preset` | `File{CREATE, folder{key, files{index, name, instrument}}}` | read-back | snapshots the grid; `preset_payload` is ignored | -| `delete_preset` | `File{DELETE, folder{files{key: "/.pb"}}}` | three Cortex Control 4.0.1 captures + read-back | Every occupied entry in those captures exposed that exact key. The API also accepts the listing's `ProductData`, validates that its device-provided key belongs to the named setlist, and sends the key unchanged. Works, but asynchronously: a listing within about 2 s is stale, about 5 s is reliable | -| `move_preset` | `File{MOVE, folder{is_downloads: false, files{key}}, to_folder{files{index}}}` | Cortex Control 4.0.1 capture + read-back | Source by file path, destination by index; asynchronous like delete. The explicit false flag is present on the captured wire shape. The API accepts either the exact name or a listing `ProductData` and never waits for a listing before sending | +| `delete_preset` | `File{DELETE, folder{files{key: "/.pb"}}}` | one captured `DELETE` + three-session key evidence + read-back | Every occupied entry in those captures exposed that exact key. The API also accepts the listing's `ProductData`, validates that its device-provided key belongs to the named setlist, and sends the key unchanged. Works, but asynchronously: a listing within about 2 s is stale, about 5 s is reliable | +| `move_preset` | `File{MOVE, folder{is_factory: false, is_downloads: false, files{key}}, to_folder{files{index}}}` | one captured `MOVE` + read-back | Source by file path, destination by index; asynchronous like delete. The explicit false flag is present on the captured wire shape. The API accepts either the exact name or a listing `ProductData` and never waits for a listing before sending | | `set_param_scene_mode` | `Grid{UPDATE, ..., params{index, scene_mode}}` (flag alone) | read-back | a value in the same message voids it | | `set_chain_output` | `Grid{UPDATE, preset{chains{row, out_portid}}}` | read-back | required for a new chain: the unit never assigns an output on its own | | `set_param(Mixer(row), ...)` | `Grid{UPDATE, preset{chains{row, mixer{params{index, param_values}}}}}` | read-back | supports per-scene; how factory presets build scenes | diff --git a/pyquadcortex/protocol/client.py b/pyquadcortex/protocol/client.py index 21ed487e..70a9b1b8 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -4223,9 +4223,11 @@ def delete_preset(self, setlist_path: str, preset: str | pa.ProductData): sent ``File{action: DELETE, type: 0, folder{key: , is_factory: false, files{key: "/.pb"}}}`` - the preset is addressed by its device FILE PATH (name-based, ``.pb`` - extension), NOT by slot index. Measured 2026-09-21: every occupied - preset-setlist entry in the three recorded CorOS 4.0.1 sessions - carried that same key shape. + extension), NOT by slot index. ``folder.is_factory`` is present and + false; ``folder.is_downloads`` is absent. One captured ``DELETE``, + session 02 frame 19033, decoded 2026-09-21. Separately, every occupied + preset-setlist entry in all three recorded sessions carried that same + key shape. """ msg = pa.FileMessage(action=pa.MessageAction.DELETE, type=0) msg.folder.key = setlist_path @@ -4248,8 +4250,10 @@ def move_preset(self, setlist_path: str, preset: str | pa.ProductData, is_factory: false, is_downloads: false, files{key: "/.pb"}}, to_folder{key: , files{index: 219}}}`` - source by FILE PATH, destination by LINEAR slot index. - ``is_downloads`` is present and false here and absent from the DELETE - in the same session. Measured 2026-09-21. + Both ``folder`` flags are present and false; ``to_folder`` carries + neither. ``is_downloads`` is absent from the DELETE in the same + session. One captured ``MOVE``, session 02 frame 25825, decoded + 2026-09-21. """ msg = pa.FileMessage(action=pa.MessageAction.MOVE, type=0) msg.folder.key = setlist_path