diff --git a/changelog.md b/changelog.md index 67440c1b..779df922 100644 --- a/changelog.md +++ b/changelog.md @@ -19,9 +19,10 @@ sustained stretch without a correction. `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 970fe05d..133c034d 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -1363,13 +1363,25 @@ 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. +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 **Creating a setlist** is captured from the unit's own "New Setlist" and @@ -2103,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 7e8601fb..70a9b1b8 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,23 @@ 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. ``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 @@ -4226,14 +4236,24 @@ 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. + 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 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"