Skip to content

docs: one baseline becomes a registry of device profiles (ADR-0020); fix version() - #51

Merged
jonathanstokes merged 3 commits into
mainfrom
feat/device-profiles
Sep 4, 2026
Merged

jonathanstokes merged 3 commits into
mainfrom
feat/device-profiles

Conversation

@jonathanstokes

Copy link
Copy Markdown
Contributor

Summary

Two contributions arrived from units I do not have: a Mini opened over USB (#31) and a CorOS 4.1.0 catalog (#42, split into #44). Neither could be verified on the unit that defines the baseline, and merging either would have failed the hardware suite on it and moved the baseline without a decision. This PR records the decision first. ADR-0020: 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. No code branches on a version string yet; this is the rule the seam will follow.

It also fixes version(). The unit answers a Version READ twice: the full reply, and 1 ms later its own Version{READ} carrying only action. version() waited by type, so back-to-back calls alternated between them and read an empty custom_name or serial every second time. It now accepts only a reply carrying an identity field. A partial reply carrying one is still returned, because the per-field cache rule owns incomplete answers.

Changes

  • docs/ADR.md: ADR-0020, five options, open questions for the two claims I could not verify (d14e on 4.1.0; the Mini's product id).
  • docs/STEERING.md sections 2 and 6, decision table and change log; CLAUDE.md bullet; docs/architecture.md checklist preamble; README.md; contributing.md: profiles with evidence levels instead of one baseline.
  • docs/protocol.md: header rewritten per profile; new section 4.4 "A Version READ is answered twice"; coverage rows for the version() change and the host undo measurement.
  • docs/domain-model.md: the claim that no host can trigger undo is corrected with the measured UndoRedo writes; appendix entry for the ¤ separator in 27 labels of the 4.1.0 catalog.
  • pyquadcortex/protocol/client.py: version() waits by type and predicate (device_serial_number or app_fw_version).
  • Tests: the predicate pinned in both directions and against both observed non-answers; listener-before-wake ordering pinned for await_broadcast; two test doubles learned the broadcast path and deliver the unit's trailing question to listeners as the wire does.

Test plan

  • Offline suite: 2540 passed, 3 skipped. mypy clean. git diff --check clean.
  • Hardware, Quad Cortex CorOS 4.0.1 / d14e, 2026-09-03: five back-to-back version() calls before the fix returned full, empty, full, empty, full; after the fix all five returned the full reply.
  • Pre-PR self-review by three reviewers (code, docs, tests); every finding addressed or listed below.
  • Reviewer: read ADR-0020 and say whether the refusal rule and the evidence levels match what "supported" should mean here.

Deferred findings (from pre-PR self-review)

  • docs/protocol.md says "measured on d14e" in about eight pre-existing places. Under the new header that string identifies nothing on its own; those read correctly as 4.0.1 by the header's default, so they are left for a follow-up sweep rather than widened into this PR.
  • ReplyingTransport in tests/test_device.py repeats a four-line deliver-to-listeners loop in two methods. Left as is: a test double reads better flat than through a helper.

The unit answers a Version READ twice: the full UPDATE, and 1 ms later its
own Version{READ} carrying action alone - the question it asks Cortex
Control. Neither carries a request_id, so Transport.request correlated by
type and handed the second one to whichever waiter was next. Five
back-to-back version() calls on the maintainer's unit returned full, empty,
full, empty, full, and a caller reading custom_name or the serial got ""
every second time with no error.

version() now waits by type and predicate and accepts only a Version that
carries an identity field, device_serial_number or app_fw_version. The
unit's question carries neither, nor does the handshake's
cortex_control_version_valid answer. A PARTIAL reply carrying one of the two
is still returned: four state tests prove the per-field cache rule with
exactly that shape, and refusing it would turn the rule into a timeout.

The two offline fakes that drive the real client through a Version read
learned the broadcast path, delivering the reply and the unit's trailing
question to listeners as the wire does. Measured on Quad Cortex, CorOS
4.0.1 / d14e, 2026-09-03; after the fix five back-to-back calls all
returned the full reply.
Two contributions arrived from units the maintainer does not have - a Mini
opened over USB (#31) and a CorOS 4.1.0 catalog (#42, then #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.
…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.
@jonathanstokes
jonathanstokes merged commit 7cd7efc into main Sep 4, 2026
5 checks passed
@jonathanstokes
jonathanstokes deleted the feat/device-profiles branch September 4, 2026 19:32
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