Skip to content

feat: the device profile seam - connect resolves a profile, and a profile refuses what it has not verified (ADR-0020) - #52

Merged
jonathanstokes merged 33 commits into
mainfrom
feat/profile-seam
Sep 7, 2026
Merged

jonathanstokes merged 33 commits into
mainfrom
feat/profile-seam

Conversation

@jonathanstokes

@jonathanstokes jonathanstokes commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

ADR-0020 (merged in #51) decided that a connection resolves a device profile before the handshake and that nothing else branches on firmware or model. This PR builds that seam. The client class IS the profile: QuadCortex stays the CorOS 4.0.1 base and behaves exactly as before; QuadCortex41 is a stub that connects and verifies nothing yet; QuadCortexMini is a stub that is recognised and refused, with its docstring as the outline for whoever finishes it. connect() waits, inside the same patience window as the handshake, for a Version reply carrying device_type and zenos_git_hash, resolves the pair in a registry, and refuses the unknown with UnsupportedDevice. An operation a profile has not verified refuses under the default Support.VERIFIED and runs with one warning under Support.EXPERIMENTAL. Generated constants live in pyquadcortex/protocol/catalogs/coros_4_0_1/; the old import paths are shims and still mean 4.0.1. The hardware suite marks the operations each test verifies, takes --profile to measure a unit the registry would refuse, and prints, per profile, which operations passed. Design: docs/superpowers/specs/2026-09-03-device-profile-seam-design.md; plan: docs/superpowers/plans/2026-09-03-device-profile-seam.md.

Changes

  • protocol/support.py: the vocabulary (Support, Evidence, EVERYTHING, Hardware, NoSnapshot, unverified_text, measured_firmware). Imports nothing from the package.
  • protocol/client.py: QuadCortex declares DEVICE_TYPE, MEASURED_ON, EVIDENCE, HARDWARE, VERIFIED, models/params/options, ALWAYS; operations(); __init_subclass__ requires a direct subclass, validates overrides against VERIFIED, guards unverified inherited operations, registers last; support and unverified_operations; set_block refuses a model id the unit's own catalog lacks.
  • protocol/profiles.py: QuadCortex41, QuadCortexMini, UnsupportedDevice, registry(), stubs(), resolve() with a version-aware "nearest" hint that names --profile.
  • protocol/session.py and device/device.py: connect(..., profile=None, support=Support.VERIFIED); the identity read for resolution and the handshake share one handshake_patience deadline.
  • protocol/catalogs/coros_4_0_1/: the three generated modules, moved byte-for-byte; shims at the old paths; check_artifacts.py proves the package ships.
  • scripts/generate_*.py and scripts/_snapshots.py: --snapshot NAME (required, validated; --out is gone); one shared helper writes the snapshot package and rewrites its __init__ from what exists; the params.py docstring example is rendered from the catalog.
  • tests/hardware/: session connects Support.EXPERIMENTAL; --profile CLASSNAME; profile and scratch_preset fixtures; @pytest.mark.verifies(...) on every test; --verifies NAME (validated); a four-line per-profile report; tests/test_hardware_markers.py holds UNMARKED_OPERATIONS, one reason per operation no test verifies.
  • Docs: STEERING §5/§6/§7, CLAUDE.md, protocol.md header and §4.4, architecture.md ("Adding a device profile"), contributing.md, changelog (BREAKING: generator flags), api.md.

Test plan

  • Offline suite: 2694 passed, 3 skipped. mypy clean over 46 files. git diff --check clean.
  • Every plan task reviewed by a fresh reviewer against the spec; a whole-branch review and one fix wave; then the repo's triage pass (four reviewers) and two fix batches, the second re-triaged. Everything found was fixed except the items below.
  • The hardware suite has NOT been run on this branch. Nothing here needed the unit. First thing after merge, on the 4.0.1 unit: pytest tests/hardware --hardware. The report's last line, "VERIFIED and claimed by a test, not passed", must be empty. What only that run can check: connect() now sends a Version READ before ResetCommsBuffers on every connection (the same read qcctl version has always made, but new in the connect path); set_block reads qc.catalog before every placement (a ~47 KB fetch on a cold connection, cached afterwards); scratch_preset has never run against a unit; the Support.EXPERIMENTAL session connect and the profile-aware test_generated_constants comparison are unexercised.

Deferred, with reasons

  • Exception type for the set_block catalog miss. It raises ControlNotDrivable with the lookup as its evidence; the measured UNPLACEABLE_MODELS case beside it raises a plain ValueError. A reviewer called that an inversion. Kept as is so the model layer catches one refusal type; maintainer's call.
  • set_block's refusal does not yet name the profile whose snapshot has the id (spec §5 "if any"): every other profile binds NoSnapshot, so there is nothing to name until a second snapshot exists (PR Add profile-owned CorOS 4.1 catalog and observations #44).
  • qcctl has no --profile / --support flags; only Python callers can drive an unmeasured unit. Follow-up.
  • HARDWARE and stubs() are declared and read only by tests; the docstrings now say who the first reader will be.
  • A VERIFIED entry naming no operation is silently ignored (no profile has a non-trivial set yet); VERIFIED: Any could be frozenset[str] | _Everything.
  • set_param_option still checks the 4.0.1 options module, not self.options (needs a NoSnapshot-aware fix).
  • hasattr / getattr(..., default) on a NoSnapshot are silent by Python's rules; no call site does this.
  • forget_probes in the tests filters throwaway subclasses by the literal name "Probe"; _guarded's warn-once set is not thread-safe (worst case a duplicate log line); config._profile could be a StashKey; marked_operations() sees decorator markers only.

… has not verified

mypy did not need the `# type: ignore[attr-defined]` the plan anticipated for
`guard._unverified = True`; omitted as an unused-ignore. Used `ControlNotDrivable`
directly in the guard (already imported by name in client.py) rather than
`errors.ControlNotDrivable`, since `errors` itself is not imported as a module here.
…s plain functions only

__init_subclass__ took every guard's implementation from QuadCortex, so a
class two levels down was guarded against the BASE - silently discarding the
measured override its parent profile made. ADR-0020 is one class per measured
unit, so that case is now refused with a TypeError before anything else runs,
and the guard site says why the base is the right source given the rule.

operations()'s predicate failed open. A staticmethod object is callable, so a
future public static helper would have been guarded and handed self as its
first argument; a property would have been replaced by a plain function and
never refused. The predicate now counts plain functions only, and a new test
holds that every public property is an ALWAYS entry with its reason.

unverified_text reads cls.__name__ plainly; the test's stand-in is a real
class rather than an object carrying __name__ as an attribute.
…are run from

CATALOGS was a relative path, so a run from anywhere but the repo root built a
fresh pyquadcortex/protocol/catalogs tree beside the working directory and
reported success, leaving the real snapshot untouched. contributing.md and
architecture.md both give the command with no working directory, so that was
the ordinary case, not the exotic one.

All three generators now anchor on the script's own location. The output-path
test redirects CATALOGS instead of the working directory, and a second test
holds the anchor itself.
…nnot leak on a failed recall, and excuses cannot rot

--verifies NAME made the end-of-run report lie. The markers were recorded for
every COLLECTED test and the deselection happened afterwards, so `claimed`
named operations the run never touched - and each one that a profile VERIFIES
was printed as a regression. The recording is now a function, _claims, which
narrows first and records what survives; tests/test_hardware_report.py drives
the hook with a config double and holds both.

scratch_preset opened its try: after the name check and the recall, so either
failing left the copy in the owner's User setlist under the fixed name - the
leak _release_scratch exists to prevent, and the one that makes the next run's
delete-by-name ambiguous. The try: now opens the moment the copy exists.

UNMARKED_OPERATIONS could name an operation that no longer exists; a renamed
one left its excuse behind and nothing said so.
… set_block evidence

Spec section 2 promised the generated header would record the zenos_git_hash of
the unit the payload came from. It does not, and should not: the snapshot name
carries the CorOS version by construction, a --payload run has no hash to
record, and embedding one would break the byte comparison with the committed
file. The clause is dropped rather than built.

set_block's catalog refusal says which kind of evidence it rests on - the
catalog's contract, since the catalog is read from the unit - because no unit
has been asked to place a model it does not have.

tests/test_session.py's mid-file import moves to the header; tests/test_profiles.py
imports FakeTransport the way pytest already has the module, rather than
importing the 4,400-line file a second time under another name.
The suite is the instrument that measures a profile, and it could not be run
against the unit that needs measuring: it connected with no profile= and
refused before a test could look. --profile CLASSNAME resolves a name over
QuadCortex and everything registered under it, and an unknown name stops the
run naming the real ones.

The 4.1 docstring also cites its evidence: PR #42's description, 2026-09-03,
2742 passed / 8 skipped on CorOS 4.1.0 / d14e, by tony-xmelon - a
contributor's report the maintainer has not reproduced.
version() accepts a reply carrying only the serial or only the firmware, which
is right for a caller and right for the per-field cache rule - the unit answers
a Version READ twice. Resolution needs device_type AND zenos_git_hash, so
reading identity through that looser predicate refused a unit this library has
a profile for, whenever the first answer was partial.

The identity read now waits on the strict predicate inside the same
handshake_patience budget, and the exhaustion message says which question went
unanswered. The profile= device-type check compares unconditionally, since the
field is now guaranteed.
… firmware

The check reads qc.catalog, so the first set_block of a connection pays a
~47 KB fetch even with verify=False, and a fetch that does not answer raises
the transport's TimeoutError rather than refusing the placement. Both are now
in the docstring.

The firmware in that refusal came from a private join, which rendered
"(CorOS )" for a profile with an empty MEASURED_ON. support.measured_firmware
renders it once, for the refusal and for unverified_text.
… is checked

save_current_preset writes and then waits for the unit to confirm, so a confirm
that timed out raised with the copy already in the owner's User setlist - the
one line the try was opened after. The try now opens before the save, and
_release_scratch lists the setlist before deleting, so a save that never wrote
is not reported as a restore that could not finish.

--verifies now refuses a name that is not an operation, and one no collected
test names. Either deselected every test, and pytest reports that as a green
run of nothing.

The list_presets excuse says what is true: the fixture reads it, and no test
uses the fixture yet.
…orts

The three generators each carried their own copy of the snapshot-package
helper, and all three created the __init__ once, naming models, options and
params whether or not they existed - so a snapshot generated one module at a
time, or an interrupted run, left a package that raised ImportError the moment
anything touched it. scripts/_snapshots.py holds the one copy: it refuses a
--snapshot that is not a package name, and rewrites the __init__ from what is
on disk. With all three modules there the file it writes is the committed
coros_4_0_1/__init__.py byte for byte.

The module docstrings also give commands that work: --snapshot is required, and
the output is a snapshot package rather than the old flat module.
…who reads it

max() over MEASURED_ON compared strings, so 4.9.0 read as newer than 4.10.0 and
the hint offered the older profile to measure an unknown unit as. It now splits
on "." and compares the numeric parts as numbers.

_describe's evidence table falls back to the enum's own name rather than
raising KeyError on a level nobody has added a phrase for yet.

HARDWARE is declared ahead of its first reader, so it says so: the intended
consumer is the model layer's footswitch and expression translation, which
still hard-codes eight letters and reads this once a profile with a different
count is measured on a unit.

Tests cover both halves of resolve()'s presence check, and that the
experimental warning is once per connection rather than once per process.
It was written before the seam existed and still said the work was next, in the
future tense, on the same page as the entry describing the seam that landed.
…call site

The helper took the profile class, which mypy cannot match against a protocol
carrying __name__ - a class object has one and an instance does not - so
set_block's call was the only place with a real class rather than an Any, and
it was the place that failed. Taking MEASURED_ON itself removes the question.
…ops the run at collection

delete_preset tolerates an absent name (it goes through _file_operation,
which swallows TimeoutError and returns None), so the listing guard in
_release_scratch only made a flaky list_presets skip a delete that would
have worked - leaving the fixed-name scratch copy on the owner's unit.
Drop the guard and call delete_preset unconditionally.

--profile is now checked in pytest_collection_modifyitems too, beside the
--verifies checks, so a typo'd class name is one UsageError before any
test runs rather than one per test in the _connection fixture. The
--verifies refusal for "no collected test names it" now also mentions a
narrowed path as a cause. CLAUDE.md's hardware-suite convention line is
updated to match docs/STEERING.md.
…n keys never cross types

Both hints in resolve() told a caller to connect(profile=X,
support=Support.EXPERIMENTAL) and then run `pytest tests/hardware
--hardware`, which cannot work since that command connects with no
profile unless told. Reworded to `pytest tests/hardware --hardware
--profile <ClassName>`, keeping a short clause for the Python caller.

_version_key left a non-numeric segment as a str, so comparing a plain
release against a pre-release ("4.1.0" vs "4.1.0-rc1") raised TypeError
inside the refusal path. Each segment is now tagged (1, int) or (0, str)
so ints and strings never compare directly and a numeric release still
sorts above its own pre-release.
…ust the maintainer's

The generator hard-coded "read from the maintainer's unit" in every
snapshot's docstring, which stops being true the moment a second profile
(a 4.1.0 unit, a Mini) is measured on someone else's hardware. Neutral
wording names ADR-0020 instead. The committed coros_4_0_1/__init__.py is
regenerated by hand to match byte for byte.
@jonathanstokes
jonathanstokes merged commit 98c1f99 into main Sep 7, 2026
5 checks passed
@jonathanstokes
jonathanstokes deleted the feat/profile-seam branch September 7, 2026 05:10
tony-xmelon pushed a commit to tony-xmelon/pyquadcortex that referenced this pull request Sep 8, 2026
…ty, as measured

The first hardware run after PR stokes-audio#52 merged failed two tests on facts the
seam changed. connect() now reads Version before the handshake, so a
listener registered through before_handshake sees three inbound Version
messages: the full reply to that read (+0.71 s), the unit's own
Version{READ} 1 ms behind it, and the announce answer carrying
cortex_control_version_valid (+0.73 s). The state layer is listening by
then, so the identity entry holds device_serial_number and app_fw_version
ahead of the burst; the reply also carries unkept fields, so the entry
stays marked and the first read still asks the unit once.

Measured 2026-09-06 on Quad Cortex, CorOS 4.0.1 / d14e, with a listener
on every inbound Version through connect and a 12 s burst. Both tests and
docs/protocol.md section 4 now state it; the 2026-08-27 measurement of one
Version stands for _hello() alone.
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