Repository navigation
docs: one baseline becomes a registry of device profiles (ADR-0020); fix version() - #51
Merged
Merged
Conversation
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.
This was referenced Sep 5, 2026
2 of 3 tasks
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
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_typeandzenos_git_hashin the unit's ownVersionreply, 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 byapp_fw. No code branches on a version string yet; this is the rule the seam will follow.It also fixes
version(). The unit answers aVersionREAD twice: the full reply, and 1 ms later its ownVersion{READ}carrying onlyaction.version()waited by type, so back-to-back calls alternated between them and read an emptycustom_nameor 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.mdsections 2 and 6, decision table and change log;CLAUDE.mdbullet;docs/architecture.mdchecklist preamble;README.md;contributing.md: profiles with evidence levels instead of one baseline.docs/protocol.md: header rewritten per profile; new section 4.4 "AVersionREAD is answered twice"; coverage rows for theversion()change and the host undo measurement.docs/domain-model.md: the claim that no host can trigger undo is corrected with the measuredUndoRedowrites; 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_numberorapp_fw_version).await_broadcast; two test doubles learned the broadcast path and deliver the unit's trailing question to listeners as the wire does.Test plan
git diff --checkclean.version()calls before the fix returned full, empty, full, empty, full; after the fix all five returned the full reply.Deferred findings (from pre-PR self-review)
docs/protocol.mdsays "measured ond14e" 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.ReplyingTransportintests/test_device.pyrepeats a four-line deliver-to-listeners loop in two methods. Left as is: a test double reads better flat than through a helper.