Skip to content

Add profile-owned CorOS 4.1 catalog and observations - #44

Draft
tony-xmelon wants to merge 27 commits into
stokes-audio:mainfrom
tony-xmelon:codex/coros-4-1-catalog-and-observations
Draft

tony-xmelon wants to merge 27 commits into
stokes-audio:mainfrom
tony-xmelon:codex/coros-4-1-catalog-and-observations

Conversation

@tony-xmelon

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

Copy link
Copy Markdown
Contributor

Summary

This is the CorOS 4.1-specific half of the split requested in #42.

  • add generated 4.1.0 model/parameter/option snapshots while keeping public unversioned imports on 4.0.1
  • bind QuadCortex41 to the profile-owned snapshots and record its measured operations
  • pin complete qualified model IDs, option member values, and parameter indexes for both snapshots
  • keep the 4.0.1 generated output byte-compatible while deriving catalog counts from live data
  • preserve both firmware records in documentation

Live evidence

A read-only CorOS 4.1.0 run on 2026-09-11 regenerated the option snapshot directly from the attached unit: 148 enums, 322 boolean parameters, 13 dynamic parameters. A separate timed connect trace recorded:

  • identity UPDATE at +0.8476 s
  • device Version READ at +0.8484 s
  • compatibility UPDATE at +0.8982 s

The USB session was closed after both measurements.

Validation

Current head: 76110fdcc2d7e4764203a4510d5a19f8d8e35ba2

  • model/options/params/docs/coverage scope: 730 passed, 1 skipped
  • python -m mypy pyquadcortex: clean (50 source files)
  • git diff --check: clean

Prior combined hardware evidence with #62: 95 passed, 4 fixture-dependent skips, 0 failed, all 16 claimed operations green. This PR remains draft until its #62 dependency and maintainer review are settled.

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: 730 passed, 1 skipped; mypy clean (50 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: 76110fdcc2d7e4764203a4510d5a19f8d8e35ba2

Focused validation: 580 generator, profile, and session tests passed; writing-policy checks passed (18 passed, 1 skipped).

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.

Maintainer follow-up — 2026-09-27

Head: 9b3a96bc9124d216fd4e26bfceb00cf25473b524.

Addressed the latest review: read_current_preset is no longer in QuadCortex41.VERIFIED pending PR #62; the operation coverage table records the 4.1 evidence; all six stable-ID model renames are documented; the Version handshake timing is in docs/protocol.md; the handshake assertion no longer allows a profile-specific answer; and the generated member fixtures now have a regeneration script. The stale changelog count and chronology comments are also corrected.

Validation on this branch: full offline suite 2,998 passed, 7 skipped; focused profiles/models/params/options/writing suite 580 passed, 3 skipped; mypy clean (50 files); diff check clean. The hardware handshake test collects (8 tests) but was not run. QC Remote currently reports the unit disconnected, so no exact-head hardware result is claimed. CI for this head is queued.

Keeping this PR draft until the full CorOS 4.1 hardware suite runs on this exact head. Upstream-main sync remains deferred to the final pre-merge step, as requested in review.

Maintainer follow-up — 2026-09-27

Current head: 9f33e908bd3850a837f4702cdccec899dcf4aac5.

Clarified the operation-count history in changelog.md: the 2026-09-11 hardware run measured 16 inherited operations; read_current_preset was later removed from this profile's VERIFIED set pending #62, leaving 15 inherited operations plus the local-backup and device-name methods (17 currently verified). The docs/STEERING.md 2026-09-19 entry is already above the 2026-09-17 entry on this head, so no reorder was needed.

Validation: tests/test_writing.py — 77 passed, 3 skipped; git diff --check clean. The existing full-suite, typing, and exact-head CI evidence is unchanged; no hardware run is claimed on this docs-only update.

Final upstream sync and exact-head validation — 2026-09-27

Merged current upstream main at d8d40f3 into this branch. The pushed merge commit is 546b4449c81c3f4b16e237f3e98f2abd4ca63b92.

Validation on that exact commit:

  • Full offline suite: 3004 passed, 7 skipped.
  • Full hardware gate on CorOS 4.1.0 with --profile QuadCortex41: 118 passed, 0 failed, 0 errored, 5 skipped in 254.33s.
  • The hardware operation report records 21/21 claimed operations; 19 passed, while read_current_preset and set_param skipped on their test preconditions. No VERIFIED operation regressed. inhibited_modules, redo, and undo passed as unverified candidates.
  • mypy: clean across 50 source files.
  • Wheel and sdist built; twine check passed for both; git diff --check clean.
  • All 47 inline review conversations are resolved.

The direct-HID run used the compatible hidapi 0.15.0 Windows extension in the isolated test environment because the separately declared pure-Python hid wrapper could not locate hidapi.dll on this host. No project dependency or source file was changed for that environment workaround.

The device was restored and reconnected afterward: clean Fender Deluxe 37 at 1A, master volume 97. GitHub CI on exact head 546b444 passed: build/twine, mypy, and Python 3.11, 3.12, and 3.13. This section supersedes earlier validation notes. The PR remains draft until #62 completes the maintainer-requested final 4.0.1 hardware rerun and merge sequence; #44 is not being merged ahead of #62.

Exact-head hardware rerun — 2026-09-28

Reran the full hardware gate on unchanged head 546b4449c81c3f4b16e237f3e98f2abd4ca63b92 against CorOS 4.1.0 / QuadCortex41: 118 passed, 0 failed, 0 errored, 5 skipped in 257.73s; 21/21 claimed operations were measured and there were no failed verified operations. The original active preset was restored cleanly; the shared broker is ready/synchronized and master volume remained unchanged at 100.

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

Thank you for keeping this as a draft while we settle the two-version design. I read it fully anyway, so you have the notes now and can work on them at your own pace. This is a comment, not a verdict.

One limit on my side: my unit runs CorOS 4.0.1 and will stay there for a while, so I cannot verify the 4.1 catalog on hardware. Everything below is from reading the code and the docs, and from comparing the old and new generated files programmatically.

Three things I could not attach to a line, because the files are not in this diff:

  • Critical: pyquadcortex/protocol/params.py line 23 (the module docstring) still shows models.CabsimBassM.N212_DARKGLASS_NEO_M, which this PR removes. Copying the example raises AttributeError. The text comes from scripts/generate_params.py line 187, so the fix is in the generator, then regenerate. tests/test_docs.py does not resolve model names in snippets, which is why CI stays green.
  • Nit: docs/protocol.md lines 250-254 (already on main) say the 2026-09-03 session was "same firmware, not a newer CorOS". This PR says that unit was on 4.1.0. Both are true only in the sense that the app firmware is d14e on both. I will settle that wording in the baseline ADR, but I wanted you to know the two texts disagree.
  • This branch does not have the UTF-8 write fix from #42, so regenerating on a Windows machine would write a file Python cannot import. Once #42 merges, a rebase on top of it takes care of that.

Items marked Critical: are the ones I think must change before this can leave draft. Items marked Nit: are optional. Please tell me if anything is unclear; I am happy to explain more.

Stokes

Comment thread pyquadcortex/protocol/options.py Resolved
Comment thread pyquadcortex/protocol/models.py Resolved
Comment thread docs/api.md Resolved
Comment thread docs/protocol.md Resolved
Comment thread changelog.md Resolved
Comment thread changelog.md Resolved
Comment thread tests/test_models.py Resolved
Comment thread pyquadcortex/protocol/params.py Resolved
Comment thread pyquadcortex/protocol/options.py Resolved
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Thank you for the careful and very swift review, Stokes. I have pushed 9f4910f and kept the PR in draft. It addresses the critical items and the related nits: the stale cab example is fixed at the generator source; generated modules now call themselves firmware-specific snapshots; 4.1-only model IDs and parameter indexes are refused when absent from the connected catalog; the 4.0.1 hardware constants test skips with an explicit explanation; the controlled 4.0.1 PresetDirty finding is restored and the single 4.1 event is recorded only as uncontrolled/ambiguous; the speculative retry and loosened hardware-test logic are removed; the changelog follows the BREAKING heading convention and includes MinivoicerMode; and generated model names, parameter-class names, and option members/values are now pinned. I also recorded the Overlord widget change and the unexplained ¤ separator.\n\nThe focused offline suite is green (1,160 passed, 1 skipped), mypy is clean, and git diff --check is clean. The full Windows run reached 2,678 passed / 3 skipped, with three unrelated checkout-platform failures in existing path-separator and byte-for-byte LF fixture tests. I will leave the branch in draft pending your two-version ADR/design, as requested. Any further feedback or pointers are very welcome.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

I have also merged current upstream main into this draft, preserving the newly merged expression-assignment work alongside the catalog changes and resolving the changelog conflict. The PR is mergeable again; the post-merge applicable suite is green (2,692 passed, 3 skipped, with the same 3 Windows baseline assertions deselected), and mypy remains clean.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Hardware follow-up after addressing the review:

  • 23/23 review conversations now have point-specific responses.
  • Full offline suite: 2,692 passed, 3 skipped, with only the same three unchanged Windows path/CRLF assertions deselected.
  • Static typing: clean across 39 source files; all three downstream typing tests pass.
  • Changed hardware modules on CorOS 4.1.0: 10 passed, 2 skipped because the loaded preset had no suitable writable block.
  • The hardware run exposed a reproducible 4.1 handshake difference (zero connect-burst Version acknowledgements across four fresh connections). Commit 737c95e records it and keeps the assertion strict per firmware rather than accepting either count.

The PR remains a draft for the versioned-client design discussion.

jonathanstokes added a commit that referenced this pull request Sep 4, 2026
…ies on

Pre-PR self-review findings, addressed:

- The test held the firmware half of the identity predicate and not the
  serial half; a predicate on app_fw_version alone passed it. Both halves
  are now asserted.
- Listener-before-wake ordering was pinned for request() only. A sibling
  test in test_transport.py holds it for await_broadcast, which version()
  now uses and the identity entry's arrival count relies on.
- LoopbackTransport's replies fallback is scoped to the reads that really
  answer with a same-type message (SAME_TYPE_READS), so any other type
  filed in the wrong dict still hits the loud error.
- ReplyingTransport asserts the trigger sent exactly one message before
  keying the canned reply off it.
- The CLI's _open_unconnected docstring no longer gives a stale reason.
- version()'s docstring and the coverage row record the post-fix hardware
  run: five back-to-back calls through the new path all returned the full
  reply.
- ADR-0020: status line matches the file's convention; the version()
  consequence no longer says the fix "lands first" or demands the full
  reply; ATMA = Mini is labelled as inferred from the schema; the catalog
  PR is named as #42, split into #44; the footswitch sentence reads as
  intended and names its source.
- STEERING, CLAUDE.md and architecture.md say the seam is not built yet
  rather than describing it in the present tense, and attribute the
  "d14e on 4.1.0" claim to the contributor.
- protocol.md's new Version section is 4.4, after 4.3, instead of an
  unnumbered heading that swallowed the rest of section 4; the host undo
  measurement behind the domain-model correction has a coverage row.
tony-xmelon pushed a commit to tony-xmelon/pyquadcortex that referenced this pull request Sep 5, 2026
Two contributions arrived from units the maintainer does not have - a Mini
opened over USB (stokes-audio#31) and a CorOS 4.1.0 catalog (stokes-audio#42, then stokes-audio#44) - and
neither could be verified on the unit that defines the baseline. ADR-0020
decides the shape before the seam is built: a connection resolves a device
profile from device_type and zenos_git_hash in the unit's own Version
reply, an unknown pair refuses to connect, profile= is the deliberate way
to measure an unmeasured unit, and everything that differs by firmware or
model lives on the profile. Profiles are named by CorOS version, never by
app_fw, because d14e is reported on both 4.0.1 and 4.1.0.

STEERING sections 2 and 6, the decision table and change log, the
protocol.md header, the architecture checklist, README, contributing.md
and CLAUDE.md now describe profiles with evidence levels instead of one
baseline. protocol.md gains the record behind the version() fix, "A
Version READ is answered twice". domain-model.md corrects the claim that
no host can trigger undo (UndoRedo{UPDATE, undo: true} does, measured on
4.0.1 and reported on 4.1.0) and records the U+00A4 separator seen in 27
labels of the 4.1.0 catalog and none of 4.0.1.

No code branches on a version string yet. protocol.models, params and
options still mean the Quad Cortex 4.0.1 snapshot, and CC_VERSION still
announces 4.0.1.
…alog-and-observations

# Conflicts:
#	changelog.md
#	docs/protocol.md
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Updated the draft onto #52 in 5ddd1fb and reshaped it around ADR-0020 instead of preserving the obsolete global-catalog layout. The CorOS 4.1.0 models/options/params now live in catalogs/coros_4_1_0 and QuadCortex41 binds that snapshot; the unversioned compatibility imports remain the 4.0.1 baseline. Focused validation: 1,264 passed, 1 skipped; hardware suite collection 99/99; mypy clean; rebuilt wheel/sdist artifact check clean. I have kept this draft because QuadCortex41.VERIFIED should be populated only from a fresh profile-aware hardware run.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Synced with upstream �2331cc at head 6885db0 and resolved the overlap with #53 by preserving both the pre-handshake Version READ behavior and the measured firmware-specific announce counts (4.0.1: one; 4.1.0: zero). It remains draft pending the required full hardware suite on this exact commit. Focused validation: 1300 passed, 1 skipped; 99 hardware tests collected; mypy and git diff --check clean.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

@jonathanstokes, the profile half is now complete at final head 6b4b9b. The full hardware suite passed on CorOS 4.1.0 (94 passed, 5 skipped), the 15 measured operations are recorded in QuadCortex41.VERIFIED, and the exact report is in the description. The PR is marked ready; GitHub does not permit this contributor account to invoke the re-request-review API, so please treat this as the review request when convenient.

@tony-xmelon
tony-xmelon marked this pull request as draft September 11, 2026 12:55
@tony-xmelon tony-xmelon changed the title Add the CorOS 4.1 catalog and firmware observations Add profile-owned CorOS 4.1 catalog and observations Sep 11, 2026
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Thank you for the detailed review. Addressed in 9b77102: restored byte-compatible 4.0.1 generation, made counts data-derived, restored public 4.0.1 tests, added full member/value/index fixtures for both snapshots, corrected docs/profile wording, appended STEERING, and recorded fresh 4.1 catalog plus exact Version timings. Focused result: 730 passed, 1 skipped; mypy/diff clean.

…alog-and-observations

# Conflicts:
#	changelog.md
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

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

…alog-and-observations

# Conflicts:
#	changelog.md
#	docs/STEERING.md
#	docs/api.md
#	docs/protocol.md
#	pyquadcortex/protocol/profiles.py
#	scripts/generate_options.py
#	tests/test_models.py
#	tests/test_profiles.py
#	tests/test_session.py

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

Reviewed at 76110fdc. The profile shape is right, the parametrised snapshot
tests are a real improvement on the old pinned name list, and the Twelve
special case in generate_options.py shows the 4.0.1 byte-compatibility was
taken seriously. Three things block it, and the first needs your 4.1 unit
rather than a patch.

1. The three 4.1 files were never regenerated, and the branch moved under them

The snapshot was read on 2026-09-11. Between then and this head the branch
merged eight days of generator and parser work, and the committed 4.1 files
predate all of it. Two consequences I can demonstrate:

The catalog parser fix never reached models.py. catalog.py now keeps a
model carrying hidden="false", which restored two amps to 4.0.1 on
2026-09-15. The 4.1 snapshot still drops them:

>>> from pyquadcortex.protocol.catalogs.coros_4_0_1 import models as m40
>>> from pyquadcortex.protocol.catalogs.coros_4_1_0 import models as m41
>>> m40.GuitarAmplifier.BOGNA_UBER_CLEAN
1130
>>> m41.GuitarAmplifier.BOGNA_UBER_CLEAN
AttributeError: BOGNA_UBER_CLEAN

Both units have those amps. A 4.1 user cannot name two amps a 4.0.1 user can.
A regeneration restores both, so the count is 422, not 420 - which means
model_members_coros_4_1_0.txt, the changelog and docs/api.md are all pinned
to the wrong number.

The option-audit work never reached options.py. The file's own header says
it was generated by scripts/generate_options.py --snapshot coros_4_1_0, but
it is missing three of the four dicts that generator writes unconditionally,
and every per-enum audit stamp:

Published name coros_4_0_1 coros_4_1_0
OPTION_LABELS yes yes
OPTION_CONTESTED yes no
OPTION_AUDIT yes no
OPTION_USAGE yes no
enums carrying an audit status 110 of 110 0 of 148
>>> from pyquadcortex.protocol.catalogs.coros_4_1_0 import options
>>> options.OPTION_AUDIT
AttributeError: module '...coros_4_1_0.options' has no attribute 'OPTION_AUDIT'

ADR-0020 makes qc.options the connected profile's snapshot, so three of that
module's four published names are gone on a 4.1 connection.

That render() emits all three for every snapshot, and that audit_status()
returns None for a list nobody read - which renders as "NOT audited against
the screen. These names are the catalog's stepNames, which is not known to be
the wording the unit draws" - is pinned by
tests/test_generators.py::test_a_list_nobody_read_says_so_in_its_own_docstring.
So a real regeneration stamps all 148 lists. The committed file stamps none.

Why that stamp matters here specifically: MinivoicerMode is MAJOR/MINOR/ CHROM on 4.0.1 and MAJOR/HARMONIC_MINOR/NATURAL_MINOR/MELODIC_MINOR/ CHROMATIC on 4.1. The 4.0.1 class says in plain words that nobody has held
those spellings against the screen. The 4.1 class says nothing, so its five
names read as if somebody had. docs/STEERING.md has the rule the stamp exists
for: an unchecked list must not look checked.

Nothing offline can see this. No generator run happens in CI, and no
ModelRepo payload is committed, so "the committed file is what the generator
produces" is unverifiable offline for either snapshot. The new
test_the_published_members_and_values_have_not_changed compares enum members
and len(OPTION_LABELS) only; the test that did assert the module's published
surface was renamed to test_the_public_module_covers_the_4_0_1_lists_the_ generator_found and now applies to the 4.0.1 shim alone. So the new fixtures
pin the stale output as correct, and the next regeneration will read as a
regression rather than a fix.

Please re-run all three generators against your 4.1 unit at this head and
commit what they write, then re-pin the three coros_4_1_0 fixtures.
tests/hardware/test_generated_constants.py diffs all three byte for byte
against the live unit and prints the first differing line; one run of it on
this head settles whether anything else drifted too.

2. Option enum names are not stable across snapshots, and the changelog tells callers to depend on them

The changelog says "Callers should use qc.models, qc.params, and
qc.options from the connected profile". Written exactly that way, this breaks:

>>> qc.options.OnOff.RELEASE     # 4.0.1: fine
>>> qc.options.OnOff.RELEASE     # 4.1:   AttributeError: module has no attribute 'OnOff'

Same two-position list, ('RELEASE', 'FREEZE'), published as OnOff on 4.0.1
and Freeze on 4.1. Ten lists are renamed this way with identical labels -
CoryWongDelayYYMode to Mode2, MonoSynthRoot to Root,
Legendary87MRatio to Ratio5, and seven more. Eleven public names disappear
between the snapshots and forty-nine appear.

These are generator naming choices, not device renames. Either the generator
should keep a name stable when the labels are unchanged, or the docs should say
plainly that enum names are per-snapshot and portable code must address lists
another way. I do not think a contributor should pick between those, so it is
flagged rather than suggested - but it should be settled here, because the five
open PRs on this profile inherit whichever way it goes.

3. The changelog names one of three silent value remaps

The entry names MinivoicerMode value 2. Three lists remap, and stored
integers change meaning with no error on either side:

list value 4.0.1 4.1.0
MinivoicerMode 1 MINOR HARMONIC_MINOR
MinivoicerMode 2 CHROM NATURAL_MINOR
synth SCALE (Scale -> OverlordSynthScale) 1 MINOR HARMONIC_MINOR
synth SCALE (Scale -> MultivoicerScale) 1 MINOR MAJOR

The MultivoicerScale row is the sharp one: 0 was MAJOR and is now
CHROMATIC. The entry's line about the Overlord scale "no longer being a
boolean-shaped control" describes the widget, not the stored value. Since the
snapshot is being regenerated anyway, worth rebuilding this table from the
regenerated files rather than from these.

Smaller things

Each of these is a one-click suggestion on the line it belongs to; none of them
blocks.

  • profiles.py:23 says "16 measured operations" where VERIFIED has 17. The
    body and the changelog both explain the 16 + create_local_backup, so it is
    only the summary line.

  • profiles.py:25 cites hardware run 99a5cd5; that is not an object in this
    repository, so the evidence anchor cannot be followed.

  • tests/test_client.py:16 imports params and never uses it.

  • tests/test_client.py:1717 passes a bare 6031 against an empty catalog in a
    test named for a CorOS 4.1 model constant; the test just below it was changed
    the other way, to models_4_1.Delay.ARPEGGIO_DELAY.

  • client.py:1175 deletes one blank line, unrelated to this PR and a needless
    conflict surface for the five open PRs on this profile.

  • scripts/check_artifacts.py lists all four coros_4_0_1 files and not the
    new package. Its own comment says a dropped snapshot fails on first attribute
    access; now profiles.py imports the 4.1 modules at module scope, so it would
    be an ImportError on import pyquadcortex.protocol.profiles. The file is
    not in this diff so I cannot suggest it inline; the four lines are:

        "pyquadcortex/protocol/catalogs/coros_4_1_0/__init__.py",
        "pyquadcortex/protocol/catalogs/coros_4_1_0/models.py",
        "pyquadcortex/protocol/catalogs/coros_4_1_0/params.py",
        "pyquadcortex/protocol/catalogs/coros_4_1_0/options.py",
  • tests/hardware/test_model_state.py:305 keys on profile.__name__ == "QuadCortex41". A subclass of QuadCortex41 would take the 4.0.1 branch and
    fail on inherited behaviour; issubclass says what is meant.

  • generate_options.py:666 special-cases 12 to keep the 4.0.1 output
    byte-identical. That is a good reason and worth a comment saying so, since the
    4.1 file now reads "13 parameters" where its sibling reads "Twelve".

  • tests/test_models.py dropped the comment explaining 414 (and why it was 412
    until the hidden fix). That paragraph is the single piece of prose most
    likely to have caught the missing amps above; worth carrying into the
    parametrised test.

Two asks from the 2026-09-11 review that are still open

  • docs/protocol.md records the three 4.1 shapes but not the timing. The
    numbers are in the PR description (+0.8476 s, +0.8484 s, +0.8982 s) and
    not in the repository.
  • The "this corrects an earlier observation" framing came out of the changelog
    and protocol.md, and survives in tests/hardware/test_model_state.py:
    "that exact trace corrects four earlier connection windows that missed the
    last shape."

The entries.py pointer is right, and its section number resolves - the 4.1
note does land inside ### 4.2 The sequence.

Comment thread pyquadcortex/protocol/profiles.py Resolved
Comment thread pyquadcortex/protocol/profiles.py Resolved
Comment thread tests/test_client.py Resolved
Comment thread tests/test_client.py Resolved
Comment thread pyquadcortex/protocol/client.py Resolved
Comment thread scripts/generate_options.py Resolved
Comment thread tests/hardware/test_model_state.py Resolved
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Thank you for the precise review. All seven points are addressed at 6e98555, with individual replies on each conversation:

  • corrected the profile summary to 17 operations and identified 99a5cd5 as a contributor-fork commit;
  • removed the unused import and the redundant 4.1 model-refusal test;
  • restored the unrelated client whitespace;
  • documented why the generator spells out twelve only for the 4.0.1 byte-for-byte snapshot; and
  • made the hardware branch profile-inheritance-safe with issubclass(..., QuadCortex41).

Validation on the exact head: focused affected surface 910 passed; full Windows suite 2991 passed, 6 skipped plus only the five known upstream Windows path/newline baseline failures; mypy, build, twine, and git diff --check all pass. GitHub CI is green on Python 3.11, 3.12, 3.13, mypy, and build/twine. All seven review conversations are resolved.

@jonathanstokes

Copy link
Copy Markdown
Contributor

#42 has merged, and it brought pyquadcortex/protocol/profiles.py into main in a new shape. This branch no longer merges cleanly. The conflicts are in:

  • changelog.md
  • pyquadcortex/protocol/profiles.py
  • tests/test_profiles.py
  • tests/test_session.py

Could you merge current main in? A review before that reads code that cannot land.

Separately, the first blocker from the 2026-09-21 review still looks open to me. The three files under pyquadcortex/protocol/catalogs/coros_4_1_0/ were last changed on 2026-09-11, and neither 9bf85a3 nor 6e98555 touched them. Can you confirm whether you have re-run the three generators against your 4.1 unit at this head and committed what they wrote?

…alog-and-observations

# Conflicts:
#	changelog.md
#	pyquadcortex/protocol/profiles.py
#	tests/test_profiles.py
#	tests/test_session.py
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Merged current upstream main and pushed 283f00c.

I also reran generation against the connected CorOS 4.1.0 unit at this head. That exposed a real stale snapshot delta: models.py and params.py were regenerated and now include Bogna Uber Clean/Lead, taking the factory-model count from 420 to 422; their golden fixtures and documentation moved with them.

The third generator was invoked against the same live catalog but deliberately refused to write options.py: this branch has no CorOS 4.1-specific DRIVEN reading for the catalog's Pink/White noise disagreement, and the generator's evidence guard will not borrow the 4.0.1 reading across firmware. I have not bypassed that guard or claimed a complete three-generator run. That evidence row is the one remaining #44 blocker.

Exact-head offline validation: 2998 passed, 7 skipped; mypy clean across 50 source files; build and twine check passed; diff check clean.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Thank you — the remaining hardware blocker is now resolved at df15e9b.

I used the connected CorOS 4.1.0 unit to drive all seven Overlord Synth OSC1 WAVE positions individually and captured the physical 800×480 framebuffer for each. The screen sequence was SIN, TRI, SAW, SQR, PUL, WHT, PNK. In particular, catalog position 5 (Pink NS) rendered WHT, while position 6 (White NS) rendered PNK; a paired capture also showed OSC1 WHT and OSC2 PNK together. The temporary block was removed and the saved preset reloaded afterward, with the original identity, grid, and clean state verified.

I then fetched the live 59,224-byte ModelRepo payload and reran generate_options.py --snapshot coros_4_1_0 against it. The committed 4.1 options.py is the resulting output, including OPTION_AUDIT, OPTION_USAGE, OPTION_CONTESTED, and the guarded corrected enum values. Repeating generation against the same payload produced the identical SHA-256 (278811e0b2e1db92b448bd1ed7c01dff222f67ab500a016142d07bf9da43d0bf). Together with the preceding live regeneration of models.py and params.py, all three 4.1 generators have now been run against the unit at this head.

Exact validation: 2998 passed, 7 skipped; mypy clean across 50 source files; wheel and sdist built successfully and both passed twine check; git diff --check clean. Further feedback and pointers are very welcome.

@tony-xmelon
tony-xmelon marked this pull request as ready for review September 22, 2026 22:50

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

Checked on df15e9b2, with a trial merge onto current main.

What I verified offline

  • The 4.0.1 byte-compatibility claim holds exactly. This branch's generators, run against the committed payload tests/fixtures/catalog/model_repo_coros_4_0_1.bin (46,695 bytes), reproduce all three catalogs/coros_4_0_1/ modules with a zero-byte diff. On the trial merge, main's own tests/test_catalog_payload.py passes.
  • load_readings filters by snapshot, so the seven new 4.1 readings leave the 4.0.1 options.py untouched. That is part of the same proof.
  • Trial merge onto current main is clean, no conflicts. Full offline suite: 3004 passed, 7 skipped. mypy clean, 50 source files.
  • profiles.py follows the recipe main's own docstring gives, and it is byte-identical between this branch's merge base and current main, so there is no drift to reconcile.
  • The seven replies reading System.Collections.Hashtable.body are a posting-tool failure, not answers. I checked all eight affected threads against this head: every one is genuinely fixed in the code. The replies are unreadable, the work landed.

What I cannot verify

The 4.1 snapshot has no committed payload, so nothing offline can check those 8,720 lines against the firmware that produced them, or regenerate them. I can confirm only that they carry the current generator's output shape. Please read the 4.1 half of this review as unchecked by me.

Blocking

1. read_current_preset is verified on evidence from code that is not in this branch.

It sits in QuadCortex41.VERIFIED, which turns the guard off. The docstring says the proving run combined this profile with #62's live-preset fix, and #62 is still an open draft. #62 exists because CorOS 4.1.0 emits an unkeyed duplicate before the keyed reply, and it changes read_current_preset to two bounded attempts.

Merge this alone and a 4.1 caller gets the single-attempt implementation with no refusal and no warning, on the strength of a run against code that is not here. The description says this itself: "This PR remains draft until its #62 dependency and maintainer review are settled." It is no longer a draft.

Either drop read_current_preset from VERIFIED until #62 lands, or land #62 first.

2. No hardware run is recorded on the final commit.

The description's validation names 76110fd. Two substantive commits landed after it: 283f00c changed the shipped constants (420 to 422), and df15e9b added seven dated hardware readings. Per contributing.md a pull request is marked ready only once the hardware suite has run on its final commit and the run is in the description, or the owner waives it. I cannot waive it, and I have not run one.

Worth fixing, not blocking

3. Sixteen new hardware verifications, no coverage table rows. The root CLAUDE.md asks that a hardware verification be recorded in the docstring and in docs/protocol.md's coverage table in the same change. The protocol.md diff here is prose only. Nothing was added for set_param, set_bypass, switch_scene, set_expression, set_global_eq, update_settings or the other ten.

4. Six renamed model constants are undocumented. The changelog covers MONO_SYNTH to OVERLORD_SYNTH and the Minivoicer value change well. It does not mention that six more constants changed name at identical wire ids:

id 4.0.1 4.1.0
3000 MICROTUBES_B3K DOUGLAS_MT_3K
3006 MICROTUBES_VMT DOUGLAS_VINTAGE_MT
21001 N210C_DARKGLASS_M N210_DOUGLAS_CERAMIC_M
21005 N212_DARKGLASS_NEO_M N212_DOUGLAS_NEODYMIUM_M
33001 N210C_DARKGLASS_ST N210_DOUGLAS_CERAMIC_ST
33005 N212_DARKGLASS_NEO_ST N212_DOUGLAS_NEODYMIUM_ST

The ids match, so no write goes anywhere wrong. But qc.models.MICROTUBES_B3K raises AttributeError on a 4.1 connection, which is the same upgrade surprise the Minivoicer note exists to prevent.

5. A hardware test encodes a profile difference the docs say is not one. tests/hardware/test_model_state.py:306 allows len(announce_answers) <= 1 on QuadCortex41 and asserts not announce_answers everywhere else, while docs/protocol.md says 4.1.0 produced the same three shapes and closes "the missing answer is recorded here without treating it as a profile difference." As written, a leaked announce answer fails on 4.0.1 and passes on 4.1. The profile that measured the behaviour is the one that loses the assertion.

6. tests/fixtures/generated/*.txt has no generator. Nothing in scripts/ writes these six files, and test_the_published_model_names_and_ids_have_not_changed compares against them directly. After any legitimate catalog change the only recourse is hand-editing a generated file, which this repo forbids everywhere else. For 4.0.1 they are also redundant with test_catalog_payload.py, which pins the module against its payload and is strictly stronger.

See the two inline notes for the changelog count and the STEERING ordering.

Dismissed

  • The set-to-length change in tests/test_profiles.py is not a regression. __init_subclass__ derives the guard from VERIFIED, so the old set equality was near-tautological, and the length form additionally catches a VERIFIED name that is not an operation. I checked both against a typo'd name.
  • tests/test_client.py:4805 importing the 4.1 snapshot into a 4.0.1 client test is what the earlier review asked for, so it stays.
  • The two added comment lines in pyquadcortex/device/entries.py change no behaviour. They are a pointer into docs/protocol.md sitting in the model layer, and #62 also touches that file, so dropping them would remove a needless conflict surface. Not worth another round on its own.

One more thing, for the maintainer rather than this branch: ADR-0022 left open "whether a second profile should be required to commit its payload rather than merely invited to", because no second profile had landed. This is that profile. It is worth noting that 283f00c added BOGNA_UBER_CLEAN and BOGNA_UBER_LEAD, the same two constants maintainer commit 9e53582 unlocked by fixing the hidden read in catalog.py. That was a parser change, reproducible offline from a payload. Without one, the 4.1 snapshot sat stale for a week and a second trip to the hardware is what found it.

This branch is 25 commits behind main and the ruleset uses strict status checks, so it will need a sync. That is the last step before merge, not now.

Comment thread changelog.md Resolved
Comment thread docs/STEERING.md Resolved
@tony-xmelon
tony-xmelon marked this pull request as draft September 26, 2026 23:52
@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Clarified the count in 9f33e90: the 2026-09-11 report measured 16 inherited operations, while current QuadCortex41.VERIFIED has 17 methods after read_current_preset was removed pending #62 (15 inherited + local backup + device name). This keeps the changelog aligned with the code and the dependency order. I also rechecked the chronology thread: docs/STEERING.md already places 2026-09-19 above 2026-09-17 on this head, so no content change was necessary. Writing-policy tests pass (77 passed, 3 skipped); no hardware claim is added.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Rechecked both remaining inline conversations against head 9f33e90. The operation history now distinguishes the 16 inherited operations from the current 17 verified methods (including local backup and set-device-name), and the 2026-09-19 steering entry is already in reverse-chronological order above 2026-09-17. Exact-head CI run 36282540097 is green on build/twine, mypy, and Python 3.11/3.12/3.13. I’m resolving those two now-outdated threads; the outstanding exact-head 4.1 hardware run and final main sync remain as stated in the PR description.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

I revalidated the current exact head 546b444 after the main sync: full offline suite 3,004 passed, 7 skipped (using the repository tests package explicitly; the machine's unrelated user-site ests package shadows it under a plain invocation). CI remains green 5/5. The remaining exact-head CorOS 4.1 hardware rerun is still outstanding; QC Remote currently reports the device disconnected or owned by another application, so I did not start a conflicting run.

@tony-xmelon

Copy link
Copy Markdown
Contributor Author

Exact-head CorOS 4.1.0 hardware validation is now complete on 546b4449c81c3f4b16e237f3e98f2abd4ca63b92 (direct HID; shared broker was disconnected for the run and reconnected afterward):

============ operations on QuadCortex41 (CorOS 4.1.0, CONTRIBUTED) ============
tests: 118 passed, 0 failed, 0 errored, 5 skipped; operations measured: 21 of 21 claimed
118 passed, 5 skipped in 257.73s (0:04:17)

The suite reported zero failed verified operations. After reconnecting the shared broker, the original loaded preset was restored at its original address with dirty: false; master volume was unchanged. The exact-head full suite is now recorded here for the requested 4.1.0 evidence.

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