Skip to content

Four things #60 left behind - #77

Merged
jonathanstokes merged 2 commits into
mainfrom
fix/four-follow-ups-from-60
Sep 22, 2026
Merged

jonathanstokes merged 2 commits into
mainfrom
fix/four-follow-ups-from-60

Conversation

@jonathanstokes

@jonathanstokes jonathanstokes commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

What this is

#60 merged with five non-blocking review comments unaddressed. Four of them were defects on main rather than preferences, and the author will not be coming back to them now the pull request is closed. This fixes those four.

The four

# defect fix
1 Both docstrings replaced their dated capture records with prose. Review thread 3992216374 asked for the 4.0.1 captured shape to stay; it did not. Restored, each naming the capture it rests on.
2 docs/protocol.md section 10.2 printed the MOVE shape without is_downloads, while the coverage row said the flag is present. One document, two shapes. Section 10.2 carries both explicit false flags, with a table of what each captured message holds.
3 delete_preset and move_preset took an unannotated preset. Both declare str | ProductData again.
4 test_move_preset_matches_the_captured_cortex_builder_bytes claimed a provenance its bytes do not have. Renamed to what it pins, with the capture named.

On 3, the guard it removed. The package ships py.typed, so dropping name: str silently cost every downstream caller a check. delete_preset(Setlist.USER, 42) type-checked and sent a delete for a preset named 42, which _file_operation then swallowed. Verified by running mypy over a caller that passes an int: two arg-type errors before #60, none after it, two again now.

One thing beyond the agreed four

The silent-transport test (test_file_operations_do_not_raise_when_the_device_stays_silent) had been narrowed to the ProductData form. The by-name form is the only one this repository calls - tests/hardware/conftest.py teardown - and a silent device is exactly the case that test exists for, so the hole was on the path that matters. Same file, same theme, so it is here. Say the word and I will split it out.

Evidence

The three recorded CorOS 4.0.1 sessions hold one MOVE (session 02, frame 25825) and one DELETE (session 02, frame 19033). 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

Separately, 784 of 784 device-reported occupied preset-setlist entries across all three sessions are keyed <setlist>/<name>.pb, zero mismatches.

That key-shape rule holds for preset setlists only. In the same captures, Neural Capture folders report 8248 named entries keyed by bare 64-hex hash. That scope limit is not documented anywhere and is not addressed here - it is a separate question about whether delete_preset should accept a capture-folder key at all.

Triage round

/triage-pr on 3713a32 found one blocker and three repo-rule breaches, all fixed in c86a376:

  • Blocker. The restored MOVE record gained is_factory: false while the evidence sentence named only is_downloads - an unevidenced wire assertion, which is a defect here whether or not it is true. Decoding both frames settled 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 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. Split into "one captured DELETE + three-session key evidence".
  • Both docstrings gave a date and no count, so the single-frame basis of the MOVE shape was invisible. Each now names its capture.
  • Two ## Unreleased changelog entries described the same change, the second narrating what the first got wrong. Both unreleased, so both editable, and writing.md says a correction replaces the wrong sentence. Folded into one.

Four findings dismissed: a loop variable shadowing an unused import, to_position staying unannotated (consistent with save_current_preset), SetlistPosition.is_downloads 800 lines away, and a two-clause evidence tag.

Validation

  • Offline suite: 2965 passed, 7 skipped.
  • mypy pyquadcortex: clean, 46 source files.
  • Hardware suite on this head (c86a376), CorOS 4.0.1, maintainer unit:
============== operations on QuadCortex (CorOS 4.0.1, MAINTAINER) ==============
tests: 117 passed, 0 failed, 0 errored, 3 skipped; operations measured: 17 of 17 claimed
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 266.97s (0:04:26)

Nothing here changes what goes on the wire, and the byte-for-byte MOVE serialization test pins that.

Not changed

docs/STEERING.md, CLAUDE.md and docs/ADR.md are untouched. Nothing here changes a decision, an owned path or an architectural rule - it restores records and an annotation that a merged pull request removed. STEERING section 5 already carries "Evidence in docstrings" as a named pattern with client.py as its example; this restores that pattern rather than changing it.

🤖 Generated with Claude Code

#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.
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.
@jonathanstokes
jonathanstokes marked this pull request as ready for review September 22, 2026 16:45
@jonathanstokes
jonathanstokes merged commit 00941f3 into main Sep 22, 2026
5 checks passed
@jonathanstokes
jonathanstokes deleted the fix/four-follow-ups-from-60 branch September 22, 2026 16:47
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.

1 participant