Repository navigation
Preserve authoritative preset keys without listing first - #60
Conversation
4be6d53 to
2fdb2c4
Compare
|
Same-commit hardware preflight passed builder review and acquired a responsive Quad Cortex, but correctly aborted before any mutation because the loaded preset has unsaved changes. Zero CREATE/UPDATE/DELETE/MOVE/SWAP/COPY frames were transmitted. Keeping this draft until the owner saves or reloads the preset and the disposable mutation run can complete. |
jonathanstokes
left a comment
There was a problem hiding this comment.
Requesting changes. I checked the claims against the three recorded CorOS 4.0.1 USB sessions in the lab repo, so most of what follows is measured rather than guessed.
The premise, measured
I decoded all three captures. On CorOS 4.0.1 every occupied preset in a folder listing does carry a key, and in all thirteen entries across the three sessions that key is exactly the folder path, plus the display name, plus .pb. Empty slots carry only an index and a read-only flag, no key at all.
So on my unit the authoritative key and the old reconstructed path are the same string, character for character. Delete and the move branch send identical bytes before and after this change. That belongs in the description, because it changes what the eventual hardware run has to prove: the entire behaviour difference on 4.0.1 is the new listing round trip, the new exceptions it can raise, and two new actions that no 4.0.1 capture has ever shown.
I like the direction. Asking the device for its own identifier instead of rebuilding one is the right instinct, and the is_downloads flag you added to the move is a real gap closed. I checked that one: Cortex Control 4.0.1 did send it and our old code did not.
Four things block merge. Three have lines and are inline. This one has no line to attach it to.
Blocker: the hardware fixture teardown now throws where it used to do nothing
tests/hardware/conftest.py:515 calls delete_preset by name in teardown, unconditionally. The docstring right above it, at lines 491 to 501, says that is safe precisely because the delete tolerates a silent device and returns None. It then explains at length why we deliberately do not consult a listing first: a flaky listing could skip a delete that would have worked, leaving the scratch copy on the unit. This change moves the listing read inside delete_preset, where the fixture cannot opt out of it.
I reproduced both directions against a fake transport:
- The scratch save failed and nothing was stored, so teardown deletes a name that is not there. It now raises
ValueError: preset 'pyquadcortex scratch' is not in ..., and every test using the fixture reports my unit as unrestored for a preset that never existed. - The listing does not arrive, which
list_presetsdocuments as two reads in five seeing nothing within eight seconds. It now raisesTimeoutError, the delete never goes out, and the scratch copy stays on my unit under the fixed name. The next run then stops at_scratch_slotand asks me to delete it by hand.
That second one is exactly the leak the conftest comment says it rejected a listing guard to prevent. It needs fixing here, either by keeping a tolerant path for the delete-by-name case or by changing the fixture in the same commit.
Docs the change contradicts, none of them touched
The coverage table at docs/protocol.md:2805-2806 still names the file path shape and still says source by file path. rename_preset has no row at all, though our rule is that a new operation updates that table in the same change. The prose in section 7.7 still describes the old path, docs/api.md:78 lists the two old signatures, and the two conftest docstrings above are now false.
There is also the evidence rule. A 4.1 observation goes beside the 4.0.1 record, dated and named by CorOS version, never in its place. Several docstrings here do the replacing version instead, which is the specific thing that rule exists to stop.
Nothing pins the shape you are now depending on
Every new test hand-builds a listing with a key set, but no test at the producing end, and no recorded capture fixture, pins that the device actually supplies that shape. list_presets's own docstring still lists index, name and instrument, and never mentions key. A firmware that reshaped or dropped the key would make every mutation raise on real hardware while this entire suite stays green.
Description
No Hardware section yet. The template wants the commit hash, the CorOS version, the operations on ... block and pytest's last line, or a stated no-unit or a maintainer waiver. Your comment says the preflight correctly aborted on a dirty preset, so this is rightly still a draft. When you do get the run, it should specifically cover a scratch preset teardown, a move onto an occupied slot, and a rename read-back, because those are the three places this review says we are flying blind.
One smaller thing: the description says the offline run needed a temporary uncommitted marker file, so the green result reported is not the run CI performs.
Minor, with no line worth attaching it to
Two methods now accept a listing entry in a parameter still called name, while rename_preset uses name for the new name. That is three meanings for one parameter name across three adjacent methods.
The rest is inline. Two of those, the swap branch and the rename, are the same shape as #47: the firmware that measured the behaviour refuses it, and the firmware that never measured it runs it unguarded. Worth checking on every new operation.
|
Thank you for catching the unsafe expansion. Addressed in 4311f6a by narrowing the PR: no listing is required, ProductData keys are validated under the named setlist, the exact-name 4.0.1 path remains, and unmeasured rename/SWAP behavior was removed. The body and docs now state the measured sources and boundaries. |
…utations # Conflicts: # changelog.md
…utations # Conflicts: # changelog.md # docs/api.md # docs/manual-coverage.md # docs/protocol.md
jonathanstokes
left a comment
There was a problem hiding this comment.
Approving. The design is materially narrower than the version I blocked, and the two things I objected to are gone by removal rather than by argument. Nothing here blocks merge.
I checked your evidence against the captures
Both claims in the PR description hold. I decoded the three recorded 4.0.1 sessions rather than taking them on trust:
<setlist>/<display name>.pb. 784 of 784 device-reported occupied entries under preset setlists (My Presets,Factory Library) carry exactly that key. Zero mismatches. The one named entry without a key turned out to be a host-sent CREATE, not a device listing.is_downloads: falseon MOVE. Exactly one MOVE and one DELETE exist across all three sessions, both in windows-session-02. The MOVE (frame 25825, t=149.8s) carriesis_downloadsexplicitly present with value false. The DELETE (frame 19033, t=54.6s) does not carry it at all. Your change adds it to MOVE only, which matches.
One scope caveat worth writing down somewhere: the key-shape rule is a fact about preset setlists, not about folders generally. In the same captures, Neural Capture folders (local_nc_root, 106_f, and friends) report 8248 named entries whose key is a bare 64-hex hash with no path and no .pb, and /opt/neuraldsp/impulse_responses reports 1764 entries with no key field at all. Since list_presets() documents that it accepts those folder keys, delete_preset("106_f", <an entry from that listing>) raises ValueError: ... does not belong to setlist '106_f' on a ProductData the device itself supplied. Deleting a capture was never an advertised use of a preset method and the name form was already silently wrong there, so this is not a regression - but the refusal blames the wrong thing.
Hardware run
Run once on 85774ac2, CorOS 4.0.1, maintainer unit:
============== operations on QuadCortex (CorOS 4.0.1, MAINTAINER) ==============
tests: 115 passed, 0 failed, 1 errored, 4 skipped; operations measured: 17 of 17 claimed
passed: ['active_scene', 'clear_expression', 'create_local_backup', 'set_bypass', 'set_chain_input', 'set_expression', 'set_global_eq', 'set_hold_timing', 'set_input_port', 'set_scene_color', 'set_scene_label', 'set_tempo_mode', 'switch_scene', 'tempo_mode', 'update_settings'] (15)
failed or skipped: ['read_current_preset', 'set_param'] (2)
passed, not VERIFIED: [] (0) <- candidates to add
VERIFIED and claimed by a test, failed: ['read_current_preset', 'set_param'] (2) <- regressions by name
115 passed, 4 skipped, 1 error in 182.51s (0:03:02)
The error is not yours. test_option_structure_on_unit.py errored at fixture setup with "the loaded preset already has unsaved edits" - the separately-tracked defect where the suite hands the unit back with the edited-preset flag set, fixed in #76, which landed in main after this branch's base. The two operations listed as "regressions by name" are the ones that errored test claims; they never ran. Neither is touched by this PR.
What the run did and did not verify about this change. It verified that nothing here breaks the suite, and that the by-name delete still works: scratch_preset's teardown calls delete_preset(setlist, name) and I confirmed afterwards that no scratch preset was left in the User setlist. It did not exercise the ProductData path or the new is_downloads field at all - move_preset is never called by the hardware suite, and both operations sit in UNMARKED_OPERATIONS for reasons I wrote. So is_downloads goes out to the unit for the first time on the strength of the capture above, not of a run. I am content with that, given the capture is unambiguous, but it should be recorded rather than implied.
Routing to docs/manual-coverage.md instead of adding a hardware test is the correct call under this repo's rules, and I am not asking for one.
Comments
None of these block. Seven inline, and the first four are the ones where a thread was marked resolved and the code says otherwise:
- Both docstrings lost their dated capture records. Thread 3992216374 asked for the 4.0.1 shape to stay; it did not come back. Suggestions inline, and I have added the frame numbers I measured.
test_move_preset_matches_the_captured_cortex_builder_bytesstill claims a provenance the bytes do not have. I decoded them; they are what the code above them builds.- The silent-transport regression test no longer covers the by-name form, which is the only form the repo calls.
presetis unannotated on two public methods. This is the one I would most like changed - the package shipspy.typed, so a downstreamdelete_preset(Setlist.USER, 42)used to be a mypy error and now is not.docs/protocol.mdsection 10.2 still prints the MOVE shape withoutis_downloadswhile the new coverage row says the flag is present.
Fix what you agree with. I am happy to merge with any subset of these outstanding.
| ``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 ``<setlist>/<name>.pb``; passing a | ||
| listing entry avoids reconstructing it, while the name form remains a | ||
| listing-free compatibility path for best-effort cleanup. |
There was a problem hiding this comment.
The captured record that was here is gone rather than kept. Thread 3992216374 asked for the 4.0.1 captured shape to stay, with any 4.1.0 reading recorded beside it and labelled as read from the binary; the thread is resolved but the shape is not back. CLAUDE.md's rule is that a docstring states its evidence, and "on three CorOS 4.0.1 captures" names a firmware but no capture and no date.
I re-decoded the three sessions to check your claim, and it holds: one DELETE exists across all three (windows-session-02, frame 19033, t=54.6s) and it sent exactly this shape. So the old record and your new sentence are both true and can sit together.
| ``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 ``<setlist>/<name>.pb``; passing a | |
| listing entry avoids reconstructing it, while the name form remains a | |
| listing-free compatibility path for best-effort cleanup. | |
| ``preset`` is either its exact display name or the ``ProductData`` | |
| returned by :meth:`list_presets`. Passing a listing entry sends the | |
| device's own key; the name form stays listing-free for best-effort | |
| cleanup. | |
| Confirmed by capture: deleting "Test save to user sl" from slot 28E | |
| sent ``File{action: DELETE, type: 0, folder{key: <setlist path>, | |
| is_factory: false, files{key: "<setlist path>/<name>.pb"}}}`` - the | |
| preset is addressed by its device FILE PATH (name-based, ``.pb`` | |
| extension), NOT by slot index. In all three recorded 4.0.1 sessions | |
| every occupied preset-setlist entry carried that same key. |
| 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. |
There was a problem hiding this comment.
Same as on delete_preset: the dated capture record came out and prose went in.
Your is_downloads claim checks out, and it is worth stating more precisely than "was captured adding". I decoded the sessions: exactly one MOVE exists (windows-session-02, frame 25825, t=149.8s), its folder.is_downloads is explicitly present with value false, and the one DELETE in the same session does not carry the field at all. That asymmetry is the interesting fact and nothing in the tree records it.
| 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. | |
| ``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. | |
| Confirmed by capture: dragging "Darkglass AO900 2_1" onto slot 28D | |
| sent ``File{action: MOVE, type: 0, folder{key: <setlist path>, | |
| is_downloads: false, files{key: "<setlist path>/<name>.pb"}}, | |
| to_folder{key: <setlist path>, files{index: 219}}}`` - source by FILE | |
| PATH, destination by LINEAR slot index. The explicit ``is_downloads: | |
| false`` is present on MOVE and absent from the DELETE in the same | |
| session. |
| f"setlist {setlist_path!r}") | ||
| return preset.key | ||
|
|
||
| def delete_preset(self, setlist_path: str, preset): |
There was a problem hiding this comment.
This is the one I would most like changed. Dropping name: str for an unannotated preset removes a guard the package ships to its users: pyquadcortex carries py.typed, so before this change qc.delete_preset(Setlist.USER, 42) was a mypy error for every downstream caller. Now it type-checks, sends key="/media/p4/Presets/My Presets/42.pb", and _file_operation returns None exactly as a success does.
Repo mypy is deliberately not strict, so CI stays green either way - this is about what downstream gets. The union is one line:
| def delete_preset(self, setlist_path: str, preset): | |
| def delete_preset(self, setlist_path: str, preset: str | pa.ProductData): |
_stored_preset_key on line 4190 and move_preset on 4229 want the same annotation.
|
|
||
| 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): |
There was a problem hiding this comment.
| def move_preset(self, setlist_path: str, preset, to_position): | |
| def move_preset(self, setlist_path: str, preset: str | pa.ProductData, | |
| to_position): |
| assert not sent.to_folder.HasField("is_factory") | ||
|
|
||
|
|
||
| def test_move_preset_matches_the_captured_cortex_builder_bytes(): |
There was a problem hiding this comment.
Threads 3992216440 and 3992216451 both land here and neither is closed. I decoded the hex independently: it is byte-for-byte what the four lines above it build, and the key it pins is f"{setlist}/Numb.pb", invented on line 671 - the reconstructed display-name path, which is the thing this PR argues we should stop rebuilding. No capture in the repo mentions "Numb" or index 54; the one recorded MOVE is "Darkglass AO900 2_1" at index 219.
The test is still worth keeping - it would catch is_downloads going away, and that is a real regression guard. The problem is only that its name claims a provenance the bytes do not have.
| def test_move_preset_matches_the_captured_cortex_builder_bytes(): | |
| def test_move_preset_serializes_the_captured_field_order_and_flags(): |
If you want it to pin the device rather than the field order, build it from the recorded MOVE: "Darkglass AO900 2_1" onto index 219, which is windows-session-02 frame 25825.
| 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 |
There was a problem hiding this comment.
This test exists for the case where the device never answers, and it no longer covers the form that case actually arises in. tests/hardware/conftest.py:682 calls delete_preset(setlist, name) by name during teardown, and that is now the only caller in the repo; after this change the silent-transport assertion runs on the ProductData form instead.
The new test_delete_preset_by_name_stays_listing_free_for_hardware_cleanup does not fill the gap, because it uses a plain FakeTransport, which answers.
Keeping both forms under TimingOutTransport is enough. The transport.broadcast seeding is also dead at this head - _stored_preset_key never reads a listing - so it can go, here and in test_save_and_move_accept_slot_names.
| | `delete_preset` | `File{DELETE, folder{files{key: "<setlist>/<name>.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: "<setlist>/<name>.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 | |
There was a problem hiding this comment.
This row says the explicit false flag is present on the captured MOVE shape, and section 10.2 above still prints that shape without it:
File{action: MOVE, type: 0,
folder{key: <setlist path>, files{key: "<setlist path>/<name>.pb"}},
to_folder{key: <setlist path>, files{index: 219}}}
One document, two shapes. A correction replaces the wrong sentence rather than sitting beside it, so section 10.2's block wants is_downloads: false added to folder (it is outside this diff, so I cannot suggest it inline).
Also, the "Verified by" column has a controlled vocabulary defined in the paragraph above the table - read-back, on-unit, captured only - and these two rows introduce "three Cortex Control 4.0.1 captures + read-back" and "Cortex Control 4.0.1 capture + read-back".
Hardware run on the merged commitRecording this after the fact, because the approving review above carried a run on What happened in between: updating this branch to main moved the head to Here is that run, on the merge commit Clean: 17 of 17 claimed operations measured, no regressions. This is also the cleanest of the three runs - the single fixture error in the One thing this run does not cover, same as the first: neither The five non-blocking comments on this PR are unaddressed and are now on |
Four things #60 left behind
stokes-audio#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 <setlist>/<name>.pb.
Summary
ProductDatafromlist_presets()for delete and move, validate that its key belongs to the requested setlist, and send the device-provided key unchanged<setlist>/<name>.pbshapeis_downloads: falseMOVE fieldEvidence
All occupied entries in three recorded Cortex Control 4.0.1 sessions used exactly
<setlist>/<display name>.pb. SupplyingProductDataavoids reconstructing that value when a listing is already available, without introducing a mandatory listing read. The byte-exact MOVE fixture pins the captured explicit false field.Validation
Current head:
85774ac21a629899bbffba71128196c62086a2f6python -m mypy pyquadcortex: clean (46 source files)git diff --check: cleanA broad
test_client.pyrun passes all unaffected cases but this machine resolves an unrelated installedtestspackage for helper imports; those environment-only import failures are unchanged and outside this diff.Upstream sync — 2026-09-12
Merged upstream main at
640a8e9(maintainer PRs #63–#65: measured pan spans and Global EQ scale/offset corrections). Post-merge validation: 5 focused mutation tests plus 243 docs/coverage tests passed, 1 skipped; mypy clean (46 files);git diff --checkclean.Upstream sync - 2026-09-19
Merged upstream main at
cfe39cc6592148d4196fa3028c2776f6618c41b6(including maintainer PRs #70-#75) and resolved overlaps in favor of the current upstream API and evidence model.Current head:
85774ac21a629899bbffba71128196c62086a2f6Focused validation: 6 focused preset-mutation tests passed.
GitHub CI on this exact head is green: build + twine check, mypy, and tests on Python 3.11, 3.12, and 3.13 all pass.
No new maintainer comments were posted during this sync. This PR remains draft under its stated hardware/evidence policy; the displayed CHANGES_REQUESTED decision is the earlier review and has not yet been refreshed.