From 4e847be67d105c8d31da564d756c1816060a3252 Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Wed, 23 Sep 2026 13:32:16 -0500 Subject: [PATCH] ADR-0023: a profile matches its own firmware's client ADR-0020 reads two ways. Its Decision names "the operations measured to behave differently"; its Rationale names "the wire behaviours that were measured to differ" and "a profile overrides where it was measured to differ". Outcome or wire, and nothing had parted them until #59. On CorOS 4.1.0 a contributor drove four setlist operations against disposable folders: the 4.0.1 create and delete shapes, and the shapes Cortex Control 4.1 sends. All four worked, each confirmed by a listing. So the shapes differ on the wire and not in outcome. This record reads all three clauses as the wire. ADR-0020's decision stands and its status is unchanged. An override's record now carries two measurements, the client's shape and what the inherited shape did on that firmware, rather than one. architecture.md's new-profile recipe and the QuadCortex41 docstring gave the outcome reading and are corrected here, since they are what a contributor finishing a profile actually reads. --- CLAUDE.md | 4 ++++ docs/ADR.md | 38 ++++++++++++++++++++++++++++++- docs/STEERING.md | 11 +++++++++ docs/architecture.md | 8 ++++--- pyquadcortex/protocol/profiles.py | 7 ++++-- 5 files changed, 62 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2c5be73..656c6cf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -160,6 +160,10 @@ small documentation fixes. `qc.models`. (ADR-0020) - An observation from another profile goes beside the 4.0.1 record in `docs/protocol.md`, dated and named. +- A profile overrides an operation when that firmware's own client sends a + different shape, even where the inherited shape still works. The override + records both: the client's shape, and what the inherited shape did on that + firmware. (ADR-0023) - A docstring states its evidence: confirmed on hardware, or inferred from the schema. Record a hardware verification in the docstring and in `docs/protocol.md`'s coverage table in the same change. diff --git a/docs/ADR.md b/docs/ADR.md index e6b05a8..265dff6 100644 --- a/docs/ADR.md +++ b/docs/ADR.md @@ -6,7 +6,7 @@ Architectural decisions for this repository are captured in this file, appended ## Format -Each ADR has: ID, Title, Status, Decision, Context, Options, Open Questions, Rationale, Consequences. A `Supersedes: ADR-NNNN` line appears only when the record replaces a prior decision. A `Settles with: ADR-NNNN` line appears when a record leaves an earlier decision standing but overturns the reasoning of one of its consequences, which `Supersedes` would overstate. +Each ADR has: ID, Title, Status, Decision, Context, Options, Open Questions, Rationale, Consequences. A `Supersedes: ADR-NNNN` line appears only when the record replaces a prior decision. A `Settles with: ADR-NNNN` line appears when a record leaves an earlier decision standing but overturns the reasoning of one of its consequences, which `Supersedes` would overstate. A `Narrows: ADR-NNNN` line appears when a record leaves an earlier decision standing and fixes the reading of wording that turned out to carry two meanings. **Status** is one of `Proposed`, `Under Discussion`, `Decided`, `Superseded`, `Rejected`, optionally annotated: e.g. `Decided (confirmed 2026-08-03)` or `Superseded by ADR-NNNN (2026-08-03)`. @@ -429,3 +429,39 @@ Records are append-only once `Decided` and built upon: a shipped decision is nev - A payload carries no statement of its own provenance: the XML root has no attributes and the tar member has no metadata. `model_repo_.provenance.json` records the identifying fields of the `Version` reply beside it, minus the serial number, MAC address and custom name, which are the owner's and not the firmware's. - Payload bytes are not reproducible between reads and must never be compared by hash; compare parsed catalogs. The one recorded comparison is the maintainer's, across reads on 2026-07-26 and 2026-09-22, identical once the `blob` attributes are blanked. The earlier payload is not committed, so that comparison cannot be repeated from this repository. - The claim that a snapshot does not vary with what a unit owns rests on one unit, which owns no plugin content. A payload from a unit that does own some would settle it; none has been read. + +## ADR-0023: A profile sends what its own firmware's client sends, even where the inherited shape still works + +- **Status:** Decided (2026-09-23) +- **Decision:** A device profile overrides an operation when that firmware's own client is measured to send a different shape. It overrides whether or not the inherited shape also works there. The override's docstring and its row in [`protocol.md`](protocol.md) carry both measurements: what the firmware's client sends, and what the inherited shape did on the same firmware. Where the inherited shape was measured to work too, the record says so in the same place. A profile with no reading of its firmware's client does not override on suspicion. +- **Context:** ADR-0020's rationale says a profile "overrides where it was measured to differ". Two readings of "differ" fit the words: differ on the wire, or differ in outcome. Nothing had parted them until #59. On CorOS 4.1.0, 2026-09-11, a contributor drove four setlist operations against disposable folders, each confirmed by a listing, both folders absent afterwards: + + | shape sent | result on CorOS 4.1.0 | + |---|---| + | the 4.0.1 `create_setlist` shape | folder created | + | the 4.0.1 `delete_setlist` shape | folder removed | + | Cortex Control 4.1's create shape | folder created | + | Cortex Control 4.1's delete shape | folder removed | + + So the shapes differ on the wire and not in outcome. That is a contributor's report on their own unit; the maintainer's runs CorOS 4.0.1 and stays there until the domain model is done, so it cannot be reproduced here. + The three CorOS 4.0.1 USB captures cannot narrow it. Across 15,675 logical messages they hold six host-to-device `File` messages: three `READ`, one preset save, one preset delete, one preset move. There is no folder create or delete in them, and neither `parent_key` under the presets root nor `delete_from_library` appears in either direction. +- **Options:** + - **(a) Override where the firmware's own client differs on the wire - chosen.** The library then sends what that firmware's maintained client sends. A firmware that tightens what it accepts does not first appear here as a write that lands nowhere. Cost: two wire shapes for one operation, carried on evidence the maintainer cannot reproduce, including on delete, which has no undo. + - **(b) Override only where the inherited shape was measured to fail.** The cheaper rule, and the one ADR-0020's words invite: one shape until something breaks. Rejected for what it costs to satisfy. A shape the firmware stops accepting is a write the unit ignores, so the evidence this rule waits for is a delete that does nothing, found by a caller who believes the setlist is gone. That is bad enough on create, where a caller believes a setlist exists that does not. On delete it is worse: `delete_from_library` has no known meaning, and the inherited shape leaves it unset, which hands the choice to the firmware. While that is unknown, the shape that states its intent is the one to send. + - **(c) Always send the oldest shape any measured firmware accepts.** One shape for every profile, and the least code. Rejected: it drifts further from every unit's own client with each release, and the drift is invisible, because the unit does not reject a write it ignores. + - **(d) Send both shapes and compare.** Not available. A file operation returns no error, `_file_operation` treats silence as normal, and a delete cannot be tried a second time. +- **Open Questions:** + - Whether a 4.1 unit ever rejects the 4.0.1 shapes. Unmeasured, and the reason this record exists instead of a measurement. + - What `delete_from_library` means when set true. Only false has been sent. The name suggests a second deletion somewhere, which is why nothing sends true. + - Whether a firmware's client can be read without a unit on that firmware. Cortex Control 4.1's shapes were read from the application, and confirming one still took a unit. +- **Narrows: ADR-0020.** Its override trigger reads as outcome rather than wire in three places. The Decision names "the operations measured to behave differently". The Rationale names "the wire behaviours that were measured to differ" and "a profile overrides where it was measured to differ". All three are read here as differing on the wire. ADR-0020's decision stands and its status is unchanged: this record fixes the reading rather than replacing the record. +- **Rationale:** The unit accepts and ignores a write it does not understand, and a file operation returns no error. So "the inherited shape still works" is one firmware, measured once, on one unit. True, and narrow. A firmware's own client is the other evidence, maintained by the people who change the firmware. Tracking it means a change in what a firmware expects arrives as a shape somebody can read. + Each override is a second code path on evidence the maintainer cannot check, and the first two are setlist create and delete. That cost is paid against option (b)'s: under (b) a shape goes wrong quietly, and the person who finds out believed a delete had happened. + Nothing else loosens. An override still needs a measurement, and still names its firmware, its date and whose unit it ran on. What changed is which measurement licenses it. +- **Consequences:** + - #59 may override `create_setlist` and `delete_setlist` on `QuadCortex41` under this rule, if both records state that the 4.0.1 shapes also worked on CorOS 4.1.0. + - An override's evidence is two measurements, not one: the client's shape, and the inherited shape's outcome on that firmware. A record carrying only the first is incomplete. + - A profile may override an operation the inherited shape drives correctly. The reason goes in the docstring, so nobody reads the override as a fix for a failure that never happened. + - Nothing licenses an override from the schema alone, or from a client shape with no unit to confirm it. The rule in `CLAUDE.md` holds: the model never guesses. + - This rule covers a profile's operations, which is what `QuadCortex.operations()` lists. The keepalive is not one of them: it lives in the transport, and [`protocol.md`](protocol.md) 4.3 carries its own reasoning for holding the measured 4.0.1 shape. + - Reversal stays cheap while the overrides are few. Each one is a method, a test and a row. diff --git a/docs/STEERING.md b/docs/STEERING.md index ec34ba4..409683b 100644 --- a/docs/STEERING.md +++ b/docs/STEERING.md @@ -170,6 +170,7 @@ Decisions are recorded in [`ADR.md`](ADR.md): | ADR-0020 | Connect resolves a device profile, and nothing else branches on firmware or model | | ADR-0021 | An approval stops counting once the pull request's code changes | | ADR-0022 | The payload a catalog snapshot is generated from is committed beside it | +| ADR-0023 | A profile sends what its own firmware's client sends, even where the inherited shape still works | ## 8. Open Questions @@ -233,6 +234,16 @@ Entries are short by design ([`writing.md`](writing.md)). The full narrative behind each one is in the lab repository, `doc/pyquadcortex/history/steering-change-log.md`, and in the pull requests. +### 2026-09-23 - A profile matches its firmware's own client (ADR-0023) + +- **What changed:** a profile overrides an operation when that firmware's own + client sends a different shape, whether or not the inherited shape also works + there. The override records both measurements. +- **Why:** ADR-0020's "measured to differ" read two ways, and #59 parted them. +- **Scope:** `ADR.md`, `CLAUDE.md`, `architecture.md`, section 7 here, and + the `QuadCortex41` docstring that gave the old reading. Left alone: + `protocol.md`, which #59 changes. + ### 2026-09-22 - A snapshot's input is committed beside it (ADR-0022) - **What changed:** the `ModelRepo` payload the 4.0.1 snapshot is generated from diff --git a/docs/architecture.md b/docs/architecture.md index 7fd10c9..7a736ec 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -516,9 +516,11 @@ On the unit it covers: that passed. Put them in the class's `VERIFIED` set. `MEASURED_ON` lists the exact `zenos_git_hash` strings a suite run has covered; a patch release is added after a run confirms it. -4. **Record differences beside the 4.0.1 record.** Anything that behaved - differently is written into `protocol.md` next to the existing entry, dated and - named, and overridden on the new class. +4. **Record differences beside the 4.0.1 record.** Any operation whose shape + differs on the wire is written into `protocol.md` next to the existing entry, + dated and named, and overridden on the new class, even where the inherited + shape still works. The entry records both measurements: what the client + sends, and what the inherited shape did on that firmware (ADR-0023). Step 1 is the one you repeat. A generator change means regenerating, and without a saved reply that means borrowing the unit again. Each generator also takes diff --git a/pyquadcortex/protocol/profiles.py b/pyquadcortex/protocol/profiles.py index 0a3dd76..27ffaf5 100644 --- a/pyquadcortex/protocol/profiles.py +++ b/pyquadcortex/protocol/profiles.py @@ -37,8 +37,11 @@ class QuadCortex41(QuadCortex): 2. ``pytest tests/hardware --hardware --profile QuadCortex41``; the report at the end lists the operations whose tests passed. Put those names in ``VERIFIED``. - 3. Record any operation that behaved differently in ``docs/protocol.md`` - beside the 4.0.1 record, dated and named, and override it here. + 3. Record any operation whose shape differs on the wire in + ``docs/protocol.md`` beside the 4.0.1 record, dated and named, and + override it here, even where the inherited shape still works. Record + both measurements: what the client sends, and what the inherited shape + did on that firmware (ADR-0023). """ MEASURED_ON = ("4.1.0",)