diff --git a/changelog.md b/changelog.md index e12b98b..67440c1 100644 --- a/changelog.md +++ b/changelog.md @@ -15,6 +15,16 @@ sustained stretch without a correction. ## Unreleased +### 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 +its explicit `is_downloads: false` field. Unmeasured rename and occupied-slot +swap behavior are deliberately not exposed. + ### The screen shortens one control's words, and not because of the words A Mono Synth's oscillator tab draws `SIN` where the catalog says `Sine`. Whether diff --git a/docs/api.md b/docs/api.md index 70487fa..50508cd 100644 --- a/docs/api.md +++ b/docs/api.md @@ -77,7 +77,7 @@ already read and need no connection; calling them as methods raises | **Device list** | `pin_model()`, `unpin_model()`, `pinned_models()`, `master_volume()` | | **Neural Captures** | `captures()` and `list_irs()` to browse the library, `set_capture(cell, entry)` to place one. Creating a capture is the unit's own wizard; disconnect first, since a connected client suppresses it | | **Discovery** | `list_folders()`: every folder the unit knows, including the factory Captures Library and plugin artist presets; `recents()`, `favorites()`, `add_favorite()`, `remove_favorite()` | -| **Manage presets** | `save_current_preset(setlist, slot, name)`, `delete_preset(setlist, name)`, `move_preset(setlist, name, to_slot)` | +| **Manage presets** | `save_current_preset(setlist, slot, name)`, `delete_preset(setlist, preset)`, `move_preset(setlist, preset, to_slot)`; `preset` may be the exact name or a `ProductData` returned by `list_presets()` | | **Local backups** | `create_local_backup()` returns the unit's validated portable backup document; serialize it to JSON wherever you keep backups | **Rows and columns are zero-based, and the unit displays rows 1 to 4.** `row=0` diff --git a/docs/manual-coverage.md b/docs/manual-coverage.md index b5a62f5..b97c2f6 100644 --- a/docs/manual-coverage.md +++ b/docs/manual-coverage.md @@ -105,8 +105,8 @@ settled is in [capture.md](capture.md). | Preset descriptive tags | n/a | not preserved by any save path, including the unit's own Save As, so they are build-chain metadata no library can write. The instrument category is separate and fully mapped (`Instrument`: Guitar 1, Bass 2, Synth 3, Vocal 4, Other 5) | | Preset description, author, cloud id | no | ignored by a `Grid` update. The unit stamps `author_name` from the signed-in cloud account on every save | | Preset volume and pan | n/a | ignored by every route tried, and the unit has no control for them; they read 1.0 and 0.5 on every preset | -| Delete a preset | yes | `delete_preset()`, eventually consistent. `delete_setlist()` removes a whole setlist | -| Move a preset | yes | `move_preset()`, same-setlist only observed | +| Delete a preset | yes | `delete_preset()`, eventually consistent. Pass a listing's `ProductData` to preserve the device-provided key, or the exact display name for the measured 4.0.1 path shape. `delete_setlist()` removes a whole setlist | +| Move a preset | yes | `move_preset()`, same-setlist only observed; accepts the same device-provided `ProductData` or exact-name forms as delete | | Factory and My Presets setlists | yes | `Setlist.FACTORY`, `Setlist.USER` | | User folders / additional setlists | yes | `create_setlist()` makes them and `list_folders()` finds them; `list_presets()` accepts any key. MIDI CC#32's "User folders" 2 to 12 are created, not built in | | Create a folder, nested navigation | yes | `create_setlist(name)`. Setlists are siblings under `/media/p4/Presets`, not children of My Presets | diff --git a/docs/protocol.md b/docs/protocol.md index af20cdd..970fe05 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -2103,8 +2103,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"}}}` | read-back | asynchronous: a listing within about 2 s is stale, about 5 s is reliable | -| `move_preset` | `File{MOVE, folder{files{key}}, to_folder{files{index}}}` | read-back | source by file path, destination by index; asynchronous like delete | +| `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 | | `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 8ced99f..7e8601f 100644 --- a/pyquadcortex/protocol/client.py +++ b/pyquadcortex/protocol/client.py @@ -4187,37 +4187,60 @@ def save_current_preset( return e.name return None - def delete_preset(self, setlist_path: str, name: str): - """Delete the preset named ``name`` from the setlist at ``setlist_path``. - - 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. + def _stored_preset_key(self, setlist_path: str, preset) -> str: + """Resolve a display name or validate a listed ProductData key.""" + if not isinstance(preset, pa.ProductData): + # Backward-compatible and deliberately listing-free: hardware + # teardown depends on a best-effort delete even when listing reads + # are silent. On measured 4.0.1 listings this reconstructed path is + # byte-for-byte the same value as the device-supplied key. + return f"{setlist_path.rstrip('/')}/{preset}.pb" + if not (field_present(preset, "key") and preset.key): + raise ControlNotDrivable( + "stored preset product key", + "the supplied ProductData carries no key, so the device did " + "not provide an address", + "pass a populated ProductData from list_presets(), or pass " + "the exact display name to use the measured 4.0.1 path shape", + ) + prefix = setlist_path.rstrip("/") + "/" + if not preset.key.startswith(prefix): + raise ValueError( + f"preset key {preset.key!r} does not belong to " + f"setlist {setlist_path!r}") + return preset.key + + def delete_preset(self, setlist_path: str, preset): + """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. """ msg = pa.FileMessage(action=pa.MessageAction.DELETE, type=0) msg.folder.key = setlist_path msg.folder.is_factory = False - msg.folder.files.add().key = f"{setlist_path}/{name}.pb" + msg.folder.files.add().key = self._stored_preset_key( + setlist_path, preset) return self._file_operation(msg) - def move_preset(self, setlist_path: str, name: str, to_position): - """Move the preset named ``name`` to slot ``to_position`` (same setlist). + def move_preset(self, setlist_path: str, preset, 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"``). - - Confirmed by capture: dragging "Darkglass AO900 - 2_1" onto slot 28D sent ``File{action: MOVE, type: 0, folder{key: - , files{key: "/.pb"}}, - to_folder{key: , files{index: 219}}}`` - source by FILE - PATH, destination by LINEAR slot index. + 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. """ msg = pa.FileMessage(action=pa.MessageAction.MOVE, type=0) msg.folder.key = setlist_path msg.folder.is_factory = False - msg.folder.files.add().key = f"{setlist_path}/{name}.pb" + msg.folder.is_downloads = False + msg.folder.files.add().key = self._stored_preset_key( + setlist_path, preset) msg.to_folder.key = setlist_path msg.to_folder.files.add().index = _as_position(to_position) return self._file_operation(msg) diff --git a/tests/test_client.py b/tests/test_client.py index a4cae35..e07a7a5 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -586,37 +586,105 @@ def test_save_current_preset_sends_file_create_by_reference(): ) -def test_delete_preset_sends_file_delete_by_path(): - # CONFIRMED wire shape (Windows capture 2): delete addresses the preset by - # its device file path "/.pb", not by slot index. - qc = client.QuadCortex(FakeTransport()) - qc.delete_preset("/media/p4/Presets/My Presets", "Test save to user sl") +def _preset_listing(setlist, *entries): + listing = pa.FileMessage() + listing.folder.key = setlist + for values in entries: + entry = listing.folder.files.add() + for field, value in values.items(): + setattr(entry, field, value) + return listing + + +def test_delete_preset_uses_the_authoritative_catalog_key(): + setlist = "/media/p4/Presets/My Presets" + listing = _preset_listing(setlist, { + "index": 220, + "name": "Test save to user sl", + "key": f"{setlist}/opaque-device-key-220", + }) + fake = FakeTransport() + qc = client.QuadCortex(fake) + qc.delete_preset(setlist, listing.folder.files[0]) sent = qc._t.sent[-1] assert isinstance(sent, pa.FileMessage) assert sent.action == pa.MessageAction.DELETE assert sent.type == 0 assert sent.folder.key == "/media/p4/Presets/My Presets" assert sent.folder.is_factory is False - assert ( - sent.folder.files[0].key - == "/media/p4/Presets/My Presets/Test save to user sl.pb" - ) + assert sent.folder.files[0].key == f"{setlist}/opaque-device-key-220" + assert not sent.folder.files[0].HasField("name") + assert not sent.folder.files[0].HasField("index") + assert not sent.HasField("to_folder") -def test_move_preset_sends_file_move(): - # CONFIRMED wire shape (Windows capture 2): source by file path, - # destination by linear slot index in to_folder. +def test_delete_preset_by_name_stays_listing_free_for_hardware_cleanup(): + setlist = "/media/p4/Presets/My Presets" qc = client.QuadCortex(FakeTransport()) - qc.move_preset("/media/p4/Presets/My Presets", "Darkglass AO900 2_1", 219) + qc.delete_preset(setlist, "Test save to user sl") + assert qc._t.sent[-1].folder.files[0].key == \ + f"{setlist}/Test save to user sl.pb" + + +def test_a_product_key_must_belong_to_the_named_setlist(): + qc = client.QuadCortex(FakeTransport()) + wrong = pa.ProductData( + key="/media/p4/Presets/Factory Presets/Cali Basswalk.pb") + with pytest.raises(ValueError, match="does not belong"): + qc.delete_preset("/media/p4/Presets/My Presets", wrong) + assert qc._t.sent == [] + + +def test_a_product_without_a_key_refuses_with_auditable_evidence(): + qc = client.QuadCortex(FakeTransport()) + with pytest.raises(ControlNotDrivable) as caught: + qc.delete_preset("/media/p4/Presets/My Presets", + pa.ProductData(name="Unnamed")) + assert caught.value.control == "stored preset product key" + assert "no key" in caught.value.evidence + assert "list_presets" in caught.value.workaround + + +def test_move_preset_uses_an_authoritative_key_and_the_captured_flag(): + setlist = "/media/p4/Presets/My Presets" + listing = _preset_listing( + setlist, + {"index": 218, "name": "Darkglass AO900 2_1", + "key": f"{setlist}/opaque-source"}, + {"index": 219, "name": "Unsaved"}, + ) + fake = FakeTransport() + qc = client.QuadCortex(fake) + qc.move_preset(setlist, listing.folder.files[0], 219) sent = qc._t.sent[-1] assert isinstance(sent, pa.FileMessage) assert sent.action == pa.MessageAction.MOVE - assert ( - sent.folder.files[0].key - == "/media/p4/Presets/My Presets/Darkglass AO900 2_1.pb" - ) + assert sent.folder.is_downloads is False + assert sent.folder.files[0].key == f"{setlist}/opaque-source" assert sent.to_folder.key == "/media/p4/Presets/My Presets" assert sent.to_folder.files[0].index == 219 + assert not sent.to_folder.HasField("is_factory") + + +def test_move_preset_matches_the_captured_cortex_builder_bytes(): + setlist = "/media/p4/Presets/My Presets" + product_key = f"{setlist}/Numb.pb" + listing = _preset_listing( + setlist, + {"index": 55, "name": "Numb", "key": product_key}, + {"index": 54, "name": "Unsaved"}, + ) + fake = FakeTransport() + qc = client.QuadCortex(fake) + qc.move_preset(setlist, listing.folder.files[0], 54) + assert fake.sent[-1].SerializeToString() == bytes.fromhex( + "08 04 18 00 22 4a 0a 1c 2f 6d 65 64 69 61 2f 70 34 2f 50 72 65 73 " + "65 74 73 2f 4d 79 20 50 72 65 73 65 74 73 20 00 28 00 3a 26 0a 24 " + "2f 6d 65 64 69 61 2f 70 34 2f 50 72 65 73 65 74 73 2f 4d 79 20 50 " + "72 65 73 65 74 73 2f 4e 75 6d 62 2e 70 62 2a 22 0a 1c 2f 6d 65 64 " + "69 61 2f 70 34 2f 50 72 65 73 65 74 73 2f 4d 79 20 50 72 65 73 65 " + "74 73 3a 02 10 36" + ) # -- session hello ------------------------------------------------------------- @@ -744,6 +812,12 @@ def test_find_preset_looks_a_preset_up_by_name(): def test_save_and_move_accept_slot_names(): fake = FakeTransport() + fake.broadcast = _preset_listing( + str(Setlist.USER), + {"index": 1, "name": "Some Preset", + "key": f"{Setlist.USER}/opaque-source"}, + {"index": 219, "name": "Unsaved"}, + ) qc = client.QuadCortex(fake) qc.save_current_preset(Setlist.USER, "30A", "Some Preset") @@ -973,9 +1047,17 @@ 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. - qc = client.QuadCortex(TimingOutTransport()) - assert qc.delete_preset(Setlist.USER, "Some Preset") is None - assert qc.move_preset(Setlist.USER, "Some Preset", "28D") is None + transport = TimingOutTransport() + transport.broadcast = _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 assert qc.save_current_preset(Setlist.USER, "30A", "Some Preset") == "Some Preset"