Skip to content

Preserve authoritative preset keys without listing first - #60

Merged
jonathanstokes merged 5 commits into
stokes-audio:mainfrom
tony-xmelon:codex/preset-file-mutations
Sep 22, 2026
Merged

jonathanstokes merged 5 commits into
stokes-audio:mainfrom
tony-xmelon:codex/preset-file-mutations

Conversation

@tony-xmelon

@tony-xmelon tony-xmelon commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • accept a ProductData from list_presets() for delete and move, validate that its key belongs to the requested setlist, and send the device-provided key unchanged
  • preserve the listing-free exact-name path and measured CorOS 4.0.1 <setlist>/<name>.pb shape
  • include the explicit captured is_downloads: false MOVE field
  • remove the unmeasured rename and occupied-target SWAP behavior from this PR

Evidence

All occupied entries in three recorded Cortex Control 4.0.1 sessions used exactly <setlist>/<display name>.pb. Supplying ProductData avoids 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: 85774ac21a629899bbffba71128196c62086a2f6

  • focused mutation tests: 8 passed
  • docs/coverage/hardware-marker tests: 243 passed, 1 skipped
  • python -m mypy pyquadcortex: clean (46 source files)
  • git diff --check: clean

A broad test_client.py run passes all unaffected cases but this machine resolves an unrelated installed tests package 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 --check clean.

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: 85774ac21a629899bbffba71128196c62086a2f6

Focused 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.

@tony-xmelon
tony-xmelon force-pushed the codex/preset-file-mutations branch from 4be6d53 to 2fdb2c4 Compare September 11, 2026 10:21
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

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 jonathanstokes left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_presets documents as two reads in five seeing nothing within eight seconds. It now raises TimeoutError, the delete never goes out, and the scratch copy stays on my unit under the fixed name. The next run then stops at _scratch_slot and 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.

Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread tests/test_client.py Resolved
Comment thread tests/test_client.py Resolved
Comment thread tests/test_client.py Resolved
Comment thread tests/test_hardware_markers.py Resolved
@tony-xmelon tony-xmelon changed the title Use authoritative keys for preset file mutations Preserve authoritative preset keys without listing first Sep 11, 2026
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

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.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Synchronized with upstream main at 640a8e9 (merged maintainer PRs #63–#65). Current head is 26af4c2; post-merge validation is recorded in the PR body.

…utations

# Conflicts:
#	changelog.md
#	docs/api.md
#	docs/manual-coverage.md
#	docs/protocol.md

@jonathanstokes jonathanstokes left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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: false on MOVE. Exactly one MOVE and one DELETE exist across all three sessions, both in windows-session-02. The MOVE (frame 25825, t=149.8s) carries is_downloads explicitly 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:

  1. 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.
  2. test_move_preset_matches_the_captured_cortex_builder_bytes still claims a provenance the bytes do not have. I decoded them; they are what the code above them builds.
  3. The silent-transport regression test no longer covers the by-name form, which is the only form the repo calls.
  4. preset is unannotated on two public methods. This is the one I would most like changed - the package ships py.typed, so a downstream delete_preset(Setlist.USER, 42) used to be a mypy error and now is not.
  5. docs/protocol.md section 10.2 still prints the MOVE shape without is_downloads while 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.

Comment on lines +4216 to +4220
``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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
``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.

Comment on lines +4233 to +4236
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
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):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
def move_preset(self, setlist_path: str, preset, to_position):
def move_preset(self, setlist_path: str, preset: str | pa.ProductData,
to_position):

Comment thread tests/test_client.py
assert not sent.to_folder.HasField("is_factory")


def test_move_preset_matches_the_captured_cortex_builder_bytes():

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Comment thread tests/test_client.py
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/protocol.md
| `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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

@jonathanstokes
jonathanstokes marked this pull request as ready for review September 22, 2026 01:35
@jonathanstokes
jonathanstokes merged commit 6ca36a4 into stokes-audio:main Sep 22, 2026
5 checks passed
@tony-xmelon
tony-xmelon deleted the codex/preset-file-mutations branch September 22, 2026 09:11
@jonathanstokes

Copy link
Copy Markdown
Contributor

Hardware run on the merged commit

Recording this after the fact, because the approving review above carried a run on 85774ac2 and that is not the commit that landed.

What happened in between: updating this branch to main moved the head to 053da6c, so the recorded run was no longer on the final commit. The re-run on 053da6c died 17 tests in when the USB link dropped (DeviceLostError: the USB device is gone (IOHIDDeviceSetReport failed: (0xE0005000))) and needed a power cycle - an environment fault, not anything in this PR, and void as evidence either way. This PR was then merged without a completed run on its head.

Here is that run, on the merge commit 6ca36a4 itself:

============== operations on QuadCortex (CorOS 4.0.1, MAINTAINER) ==============
tests: 117 passed, 0 failed, 0 errored, 3 skipped; operations measured: 17 of 17 claimed
passed:                                 ['active_scene', 'clear_expression', 'create_local_backup', 'read_current_preset', 'set_bypass', 'set_chain_input', 'set_expression', 'set_global_eq', 'set_hold_timing', 'set_input_port', 'set_param', 'set_scene_color', 'set_scene_label', 'set_tempo_mode', 'switch_scene', 'tempo_mode', 'update_settings'] (17)
failed or skipped:                      [] (0)
passed, not VERIFIED:                   [] (0)   <- candidates to add
VERIFIED and claimed by a test, failed: [] (0)   <- regressions by name
117 passed, 3 skipped in 267.46s (0:04:27)

Clean: 17 of 17 claimed operations measured, no regressions. This is also the cleanest of the three runs - the single fixture error in the 85774ac2 run was #76's hand-back defect, and #76 came in with the main merge, so read_current_preset and set_param measure again here.

One thing this run does not cover, same as the first: neither delete_preset nor move_preset is exercised by the hardware suite beyond scratch_preset's by-name teardown. Both sit in UNMARKED_OPERATIONS for reasons that still hold. So the is_downloads field still rests on the capture (windows-session-02, frame 25825) rather than on a run, which is what the capture is for.

The five non-blocking comments on this PR are unaddressed and are now on main. Follow-up coming for four of them.

jonathanstokes added a commit that referenced this pull request Sep 22, 2026
jonathanstokes added a commit to tony-xmelon/pyquadcortex that referenced this pull request Sep 22, 2026
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants