Repository navigation
feat: the device profile seam - connect resolves a profile, and a profile refuses what it has not verified (ADR-0020) - #52
Merged
Conversation
…e old paths are shims
… 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.
…w the next profiles arrive
…refuses the unknown
…nce test asserts the announce
…ple from the catalog
… them per profile
…m, and the scratch fixture cannot leak
…ontributing, changelog, api
…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.
This was referenced Sep 7, 2026
Merged
2 tasks done
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
QuadCortexstays the CorOS 4.0.1 base and behaves exactly as before;QuadCortex41is a stub that connects and verifies nothing yet;QuadCortexMiniis 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 aVersionreply carryingdevice_typeandzenos_git_hash, resolves the pair in a registry, and refuses the unknown withUnsupportedDevice. An operation a profile has not verified refuses under the defaultSupport.VERIFIEDand runs with one warning underSupport.EXPERIMENTAL. Generated constants live inpyquadcortex/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--profileto 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:QuadCortexdeclaresDEVICE_TYPE,MEASURED_ON,EVIDENCE,HARDWARE,VERIFIED,models/params/options,ALWAYS;operations();__init_subclass__requires a direct subclass, validates overrides againstVERIFIED, guards unverified inherited operations, registers last;supportandunverified_operations;set_blockrefuses 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.pyanddevice/device.py:connect(..., profile=None, support=Support.VERIFIED); the identity read for resolution and the handshake share onehandshake_patiencedeadline.protocol/catalogs/coros_4_0_1/: the three generated modules, moved byte-for-byte; shims at the old paths;check_artifacts.pyproves the package ships.scripts/generate_*.pyandscripts/_snapshots.py:--snapshot NAME(required, validated;--outis gone); one shared helper writes the snapshot package and rewrites its__init__from what exists; theparams.pydocstring example is rendered from the catalog.tests/hardware/: session connectsSupport.EXPERIMENTAL;--profile CLASSNAME;profileandscratch_presetfixtures;@pytest.mark.verifies(...)on every test;--verifies NAME(validated); a four-line per-profile report;tests/test_hardware_markers.pyholdsUNMARKED_OPERATIONS, one reason per operation no test verifies.Test plan
git diff --checkclean.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 aVersionREAD beforeResetCommsBufferson every connection (the same readqcctl versionhas always made, but new in the connect path);set_blockreadsqc.catalogbefore every placement (a ~47 KB fetch on a cold connection, cached afterwards);scratch_presethas never run against a unit; theSupport.EXPERIMENTALsession connect and the profile-awaretest_generated_constantscomparison are unexercised.Deferred, with reasons
set_blockcatalog miss. It raisesControlNotDrivablewith the lookup as its evidence; the measuredUNPLACEABLE_MODELScase beside it raises a plainValueError. 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 bindsNoSnapshot, so there is nothing to name until a second snapshot exists (PR Add profile-owned CorOS 4.1 catalog and observations #44).qcctlhas no--profile/--supportflags; only Python callers can drive an unmeasured unit. Follow-up.HARDWAREandstubs()are declared and read only by tests; the docstrings now say who the first reader will be.VERIFIEDentry naming no operation is silently ignored (no profile has a non-trivial set yet);VERIFIED: Anycould befrozenset[str] | _Everything.set_param_optionstill checks the 4.0.1optionsmodule, notself.options(needs aNoSnapshot-aware fix).hasattr/getattr(..., default)on aNoSnapshotare silent by Python's rules; no call site does this.forget_probesin 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._profilecould be aStashKey;marked_operations()sees decorator markers only.