Skip to content

Commit the CorOS 4.0.1 ModelRepo payload, so regeneration needs no unit - #80

Merged
jonathanstokes merged 14 commits into
mainfrom
catalog/model-repo-payload-4-0-1
Sep 23, 2026
Merged

jonathanstokes merged 14 commits into
mainfrom
catalog/model-repo-payload-4-0-1

Conversation

@jonathanstokes

@jonathanstokes jonathanstokes commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Commits the CorOS 4.0.1 ModelRepo payload as
tests/fixtures/catalog/model_repo_coros_4_0_1.bin, with a provenance record
beside it and a test that holds it to the snapshot it generates. ADR-0022
records the decision, and docs/architecture.md gains the offline command
beneath its profile recipe.

The three generators in scripts/ already accept --payload. Until now the only
payload lived on the maintainer's disk, so regenerating the 4.0.1 snapshot needed
that one unit, which is the single input a contributor cannot borrow. #45 is
stalled on exactly that: its clone-resolution change makes options.py stale,
and its author runs CorOS 4.1.0, where generating into the 4.0.1 snapshot would
mislabel firmware data.

With this committed, regenerating is offline and repeatable:

python scripts/generate_options.py --snapshot coros_4_0_1 \
    --payload tests/fixtures/catalog/model_repo_coros_4_0_1.bin

What holds it

tests/test_catalog_payload.py regenerates every snapshot listed in its
PAYLOADS table from that snapshot's own payload and compares byte for byte. A
saved input nothing reads rots quietly: without this, the offline suite would
pass identically on a truncated payload, on another unit's, or on noise.

This is not the hardware check and does not replace it.
tests/hardware/test_generated_constants.py asks whether the snapshot matches
the unit, which only a unit can answer. This asks whether it matches its own
recorded input, which is what makes regeneration reproducible off the unit.

Provenance

Read on 2026-09-22: zenos_git_hash 4.0.1, app_fw_version d14e, device_type
QC, confirmed from the unit's own Version reply rather than assumed. 46,695
bytes.

The payload states nothing about its own origin. Its XML root carries no
attributes and its tar member no metadata, so that claim would otherwise rest on
my word alone. model_repo_coros_4_0_1.provenance.json records the firmware
fields of the Version reply, and a test holds every payload to having one. The
serial number, MAC address and custom name are deliberately left out: they
identify an owner's unit and say nothing about the firmware.

Two facts worth committing alongside it

The payload is a firmware fact, not a fact about this unit. It describes
every model the firmware knows, including plugin content no licence has been
bought for. 90 models carry a sku and a plugin_id, always together and never
one alone; this unit owns none of them and its catalog lists the Gojira, Cory
Wong, Nolly and Plini families in full. So a generated snapshot does not vary
with what a unit owns. The inference runs one way only, and ADR-0022 says so.

Payload bytes are not stable; parsed catalogs are. Each read rotates a
per-model blob token. There are 351 of these, 13 of them empty, which is why
docs/domain-model.md counts 338 models carrying one. Anything comparing
catalogs compares parsed output, never a payload hash.

Testing

  • python -m pytest: 2974 passed, 7 skipped
  • python -m mypy: clean across 46 source files. Note that mypy is configured
    files = ["pyquadcortex"], so it does not read the new test module; this is
    the same 46 files as on main.
  • git diff --check: clean

Hardware

The owner has waived the hardware run for this pull request. The reasoning,
recorded so the waiver is auditable rather than assumed:

The suite exists to catch two things: library code that misbehaves against the
unit, and records claiming something about the unit that is no longer true. This
pull request adds no library code. It does touch three files under
tests/hardware/, but only their docstrings, which this branch made false by
committing the catalog they said was unavailable; no assertion, fixture or
outcome moves. The one hardware test covering this ground,
tests/hardware/test_generated_constants.py::test_the_committed_snapshot_matches_this_unit,
regenerates from the live unit and compares with the committed snapshot. This
branch changes neither the snapshot nor the generators, so that test's outcome
cannot move.

Triage

/triage-pr ran twelve times across this branch's heads, from dc42eb1 to
98de622, the last three returning approve with no merge blockers. The
per-pass detail is in the commit messages, which name what each pass found and
what changed; this is what it amounts to.

Two findings changed the branch materially. The first pass found nothing held
the fixture: the offline suite would have passed identically on a truncated
payload, on another unit's, or on noise, so tests/test_catalog_payload.py was
written. The eighth found that test's own docstring calling it redundant, when it
is the only guard for the case where a model the snapshot generates no constants
for joins the catalog - measured, one extra model carrying a sku and a
plugin_id whose only parameter is a float leaves all three generated files byte
for byte identical, and only the model count moves. That is ADR-0022's first open
question, so the assertion is its guard.

One changed the record. The fifth pass found ADR-0022 silently contradicting
ADR-0015, whose last consequence cites the size of this exact file as the reason
not to commit it. That is settled explicitly now rather than left standing.

The rest, and the great majority, were my own claims that the artifact
contradicted
- a fix announced and not performed, a comment describing
behaviour the code did not have, a figure nobody could reproduce. Three of them
were produced by the commit fixing the previous one. The ninth pass drew the
structural conclusion: ADR-0022 now records one byte count a test pins, the
payload's 46,695, plus the 556,732-byte ModelRepo.xml quoted from ADR-0015's
own reasoning and derivable from the same committed file. Every other figure is
gone, because a number no test holds goes stale in silence, and this record
proved that about itself twice.

The tenth and eleventh passes found a class none of the others had looked for:
text elsewhere in the repository that this branch invalidates at a distance. Five
files gave the catalog's absence as their reason for existing - a hardware test
justifying itself with "the whole ModelRepo.xml is not committed",
scripts/extract_scale_fixture.py restating ADR-0015's republication argument in
full, and three more hardware docstrings drawing the same analogy. None was in
the diff when it was found; all five are now, corrected rather than left
standing. The twelfth pass swept the repository by concept rather than by
reading order and found nothing further.

No pass found a defect in the code, the payload or the generated output. Every
number in ADR-0022 has been independently re-measured against the payload and
against main on the twelfth pass, along with every figure elsewhere in the
repository the payload can now answer - 539 stepNames, the hidden counts,
the display_pos populations, the 40 scales.json rows. The payload
contradicts none of them.

Findings not acted on

  • pyquadcortex/protocol/catalogs/coros_4_0_1/__init__.py still says a
    snapshot is "generated by the scripts in scripts/ from a connected unit",

    which is now one of two routes. It is a generated file, so correcting it means
    editing scripts/_snapshots.py, regenerating, and moving the pin in
    tests/test_generators.py - a real change to the generator for a mild
    staleness, better made deliberately than as the last item of a review round.
  • tests/test_catalog.py's "ships no vendor data" is true as scoped to the
    tests it describes, but reads wider now that extract_scale_fixture.py no
    longer cites it as a repository-wide promise. Rewriting it is a question about
    that test's own claim, not about this branch.

Earlier

  • "Purchasable, not purchased" rests on one unit, which owns no plugin
    content, so the inference holds one way only. Recorded as an open consequence
    in ADR-0022 rather than resolved; settling it needs a payload from a unit that
    owns some, and none has been read.
  • docs/domain-model.md is not edited to reconcile its 338 against the
    payload's 351. That file is out of scope for this branch; the 13 empty
    attributes explaining the gap are recorded in ADR-0022 instead.

Note for review

ADR-0022 is a decision record written on the owner's behalf. The decision is his;
the framing and the four rejected options are mine, and are worth reading as
argument rather than as settled record.

🤖 Generated with Claude Code

The three generators in `scripts/` accept `--payload`, and until now the only
payload was on the maintainer's disk. Regenerating the 4.0.1 snapshot therefore
needed the baseline unit, which is the one thing a contributor cannot borrow.
#45 stalled on exactly that: its parser change makes `options.py` stale and its
author runs CorOS 4.1.0, where generating into the 4.0.1 snapshot would mislabel
firmware data.

Read from the baseline unit on 2026-09-22: `zenos_git_hash` 4.0.1,
`app_fw_version` d14e, `device_type` QC.

The payload is a firmware fact, not a fact about this unit. It describes every
model the firmware knows, including plugin content the unit holds no licence
for: `is_factory` is false for anything carrying a `sku` or a `plugin_id`, which
marks a model purchasable rather than purchased. This unit has no plugin
purchases and its catalog still lists the Gojira, Cory Wong, Nolly and Plini
families. Neural Capture slots are user content and carry no option lists, so
they cannot move a generated count either.

Each read rotates a per-model `blob` token, so payloads never match byte for
byte. With the 351 `blob` attributes blanked, the catalog read on 2026-07-26 is
identical to this one. Compare parsed catalogs, never payload hashes.

`docs/capture.md` gains the section that says all of this and gives the command.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
jonathanstokes and others added 3 commits September 22, 2026 14:14
Findings from /triage-pr on this branch. The blocking three:

STEERING section 2 said the catalog dump lives in the lab repository, which this
branch makes false. Corrected in place rather than added to.

The `is_factory` sentence read as a biconditional. 119 models are non-factory
and only 90 carry a `sku` and a `plugin_id`; the other 29 are internal helpers
and hidden entries. `sku` and `plugin_id` also always occur together, 90 of 90,
so "a sku or a plugin_id" implied a split the payload never shows. The claim now
lives in ADR-0022, stated one way round and with the numbers.

The decision had no record and nothing protected the file. ADR-0022 holds it
with the four rejected options; `CLAUDE.md` gains a bullet beside the one for
the generated bindings.

The rest of the triage that earned a change:

Nothing held the fixture. It was the only file under `tests/` no test touched,
so the suite would have passed identically on a truncated or wrong-firmware
payload. `tests/test_catalog_payload.py` regenerates every snapshot from its own
payload and compares byte for byte, plus a shape tripwire. This is the check the
offline suite was missing, and it is not the hardware check: that one asks
whether the snapshot matches the unit, this one whether it matches its recorded
input.

The section was in the wrong document. `docs/capture.md` is how to observe what
the unit sends, and `architecture.md` step 1 already owned the regeneration
recipe while still saying "against the new unit". The note went there instead,
and capture.md is untouched.

Dropped rather than kept: the 351 `blob` count, which conflicts on its face with
`domain-model.md`'s 338 because 13 are empty strings; and the 2026-07-26
comparison, which no reader of this repository can repeat. Both survive in
ADR-0022 as consequences, where their limits are stated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Git already detects them, so this changes no behaviour today. It is stated
because the file exists to serve contributors on Windows, and this repository
added its .gitattributes rule after CRLF fixture failures in #42 and #45.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…tatements

The first triage's document move was written up as done and was not done. The
revert used `git checkout -- docs/capture.md`, which restores the file to its
COMMITTED state - and the section was already committed one commit earlier. So
the file never changed, the payload story was told in three places at once, and
the commit message and pull request description both claimed otherwise. The
section is deleted here, and the deletion is asserted rather than assumed.

ADR-0022 claimed the payload reproduces the package `__init__.py` byte for byte.
It does not reproduce it at all: `_snapshots.py` builds that file from the
directory listing, and `tests/test_generators.py` already pins it. Claim
narrowed to the three files the payload actually generates.

The 351 `blob` attributes were dropped from every document while the pull
request description said they survived in ADR-0022. They now do, with the 13
empty strings that reconcile them against `domain-model.md`'s 338.

ADR-0022's decision sentence said the test covers every snapshot; its
consequences said an unlisted profile is not covered. The decision now says what
the test does, which is to cover what `PAYLOADS` lists.

Also from the second pass:

The payload states nothing about its own origin - no root attributes, no tar
metadata - so "this is the 4.0.1 catalog" rested on the committer's word.
`model_repo_coros_4_0_1.provenance.json` records the firmware fields of the
`Version` reply, and a test holds every payload to having one. The serial
number, MAC address and custom name are deliberately left out: they identify an
owner's unit and say nothing about the firmware.

The shape tripwire's docstring claimed it catches a truncated or wrong-firmware
payload. It catches neither - truncation raises while the fixture parses, and
another unit's reply already fails the byte-for-byte comparison. What it gives
is a legible failure, and it now says so. Its numbers move into the `PAYLOADS`
row so a second payload cannot be added and silently go unchecked.

`_generator` was a second copy of `test_generators._load` that registered
nothing, so each of three parametrized runs re-executed a generator and pushed
`scripts/` onto `sys.path` again. It reuses the existing loader.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jonathanstokes jonathanstokes mentioned this pull request Sep 22, 2026
5 tasks done
jonathanstokes and others added 10 commits September 22, 2026 15:57
…numbers

The comment explaining why this file borrows `test_generators._load` said the
shared loader caches. It does not: it assigns `sys.modules[name]` and then
execs unconditionally, so three parametrized cases built three modules and left
six `sys.path` entries behind for every later test module. Measured, not
assumed. The borrowing is now wrapped in `functools.cache`, so the comment
describes what happens and the entries stop accumulating.

The provenance record stated the payload's size and digest and nothing checked
either. Re-reading the catalog from the same unit gives a payload that parses
identically, so every generator comparison would still pass while both numbers
went stale in silence - the failure this file's own docstring warns about. Both
are now asserted against the file beside them. This is not comparing two
payloads by hash, which ADR-0022 forbids; it is checking that a record
describes its neighbour.

The privacy guard read only `version_reply`'s keys, so a serial moved to the
top level or pasted into a comment would have passed. It scans the document.

Also from the third pass:

The note in `architecture.md` sat inside the list headed "On the unit it
covers" while describing how to rebuild with no unit attached. It now stands
after the list, and carries the command the pull request claimed it had.

The fixture returns its row's path, so the failure message prints the payload
that actually failed rather than a name built from the snapshot, and the
provenance test stops re-looking-up what the fixture already knew.

`comms_version` was excluded from the record for the stated reason that it
identifies a unit. It does not; it is a protocol version, and a `bytes` field
with no faithful JSON spelling. Both reasons are now given correctly.

ADR-0022 gains the `Open Questions` section the format requires, holding the
one-unit inference and the question of whether a second profile must commit its
payload. The STEERING entry names `.gitattributes` and says `domain-model.md`
was left alone on purpose.

Dropped: the unused `importlib.util` import.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… nothing

Two claims in committed text that the branch contradicts.

The `comms_version` correction was made and then destroyed. After mutating the
provenance record to prove an assertion bites, the restore was
`git checkout -- <file>`, which took the file back to its COMMITTED state and
carried the correction away with the mutation. The commit message and the pull
request description had already announced it. This is the second time a
`git checkout --` restore has silently reverted real work on this branch; the
first was `docs/capture.md`. Restores here now come from a copy taken before
the mutation, and the correction is asserted on disk rather than assumed from
an exit code.

`functools.cache` on the borrowed loader was justified by a claim that does not
hold. The three parametrized cases ask for three DIFFERENT generators, so every
call is a miss and the wrapper changes nothing today: measured, a run of this
file adds the same entries with and without it. It begins to matter only when
`PAYLOADS` gains a second row. The comment now says that, instead of claiming
the accumulation stops. Two smaller corrections in the same comment: all three
generators insert two path entries, not `generate_models.py` alone, and this
module was itself inserting `scripts/` while complaining about the practice.
`_snapshots` now loads through the same loader, so that insert is gone.

Also from the fourth pass:

`options.py` has a second input. `generate_options` reads
`option_readings.json` besides the payload, so a reading row moves the
generated file with no payload and no generator change. The test docstring
named two causes of failure and ADR-0022 named none; both now say so.

ADR-0022 put `Open Questions` after `Rationale`; the format declares it between
`Options` and `Rationale`, where all twenty other records that carry it put it.
Its open question pointed at a `docs/protocol.md` row for the count of 90,
which that row does not carry. Sentence dropped.

`architecture.md` said only step 1 needs the unit. Step 2 runs the hardware
suite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…adicted

ADR-0015's last consequence says `scales.json` distils its parameters out of a
real catalog "because committing `ModelRepo.xml` would republish 556 KB of the
vendor's product catalog". That file is this one: gunzip the payload and its
single tar member is `ModelRepo.xml`, 556,732 bytes, the same number to the
byte. Two records were left that a reader could not both act on, and this
branch had spent four passes removing exactly that.

ADR-0022 now names the bullet and says why the concern no longer decides. What
is committed is the 46,695-byte reply as the unit sent it, compressed in git
and never expanded on disk. The repository already publishes this catalog's
content in derived form - the committed snapshot is 290 KB of model, parameter
and option names generated from this exact file - so the names were already
here and the payload adds the structure around them. And it is a functional
input held by a test rather than a browsable catalog. What grew is the sdist,
by 47 KB.

ADR-0015's decision is untouched and stays `Decided`; only that bullet's
reasoning is overturned, so this is a named settlement rather than a supersede.
It does leave `scales.json`'s reason for existing weaker, which is now an open
question on ADR-0022 rather than a silence.

Also from the fifth pass:

`GENERATORS` was a hand-kept list beside `_snapshots.MODULES`, which is the one
list of what a snapshot package holds. It is derived from it, so a fourth
generator joins this check by existing.

The cache comment enumerated three call sites and there are four; `_snapshots`
loads through the same helper. Renamed `_generator` to `_script`, since it
stopped being only generators when that call was added.

`CLAUDE.md` protected `model_repo_*.bin` while `.gitattributes` marked `*.bin`.
One glob now, so a second payload cannot land on one side only.

The `architecture.md` sentence is rewritten rather than patched a third time.
It said step 1 needs the unit "twice", which was never explained and is not
true of step 2, which runs the hardware suite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The settlement written last pass said the repository already publishes this
catalog's content, "so the names were already here and what the payload adds is
the structure around them". That is the half of the argument doing the
persuading, and it is wrong.

`models.py` and `params.py` emit factory content only, and say so. Measured
against main: 77 of the 119 non-factory model names appear nowhere else in the
repository - Gojira, Cory Wong, Nolly, Plini, SLO-100, Fortin, Parallax - and
161 parameter names exist only on non-factory models. Those are exactly the
licence-gated families ADR-0015 was weighing. Worse, the record's own Context
bullet says the payload carries plugin content no licence has been bought for,
twelve lines above. It contradicted itself and the false half was the
persuasive one.

Even for factory content the claim overreached: the snapshot spells a model as
the constant `N810_AMPED_VT_ALN_70S_M` where the payload carries
`810 Amped VT Aln 70s (M)` verbatim, so 137 factory names are absent from main
as written too.

The argument is deleted rather than reworded. The settlement now states the
cost: this does republish content the repository did not carry, and the
decision accepts it. What changed the weight of ADR-0015's concern is size and
purpose - 46,695 bytes that stay compressed against the 556 KB of XML it was
weighing, a functional input held by a test - set against a snapshot nobody but
the maintainer can regenerate. It is a trade, and the bullet now says so
instead of dissolving it.

`Settles with: ADR-NNNN` was a field the Format section did not define. It is
defined, beside `Supersedes:`, for the case where a record leaves a decision
standing and overturns one consequence's reasoning.

Also from the sixth pass:

The cache comment was rewritten false by the commit that rewrote it. Deriving
`GENERATORS` from `_snapshots` added a fifth call over four names, so the
wrapper now saves exactly one exec rather than none. Measured, then written.

`CLAUDE.md` protects `tests/fixtures/catalog/*.bin` and claims this file holds
each one, while only `PAYLOADS` rows were held. A payload committed without a
row was protected by the rule and checked by nothing.
`test_every_committed_payload_has_a_row` closes that.

The sdist consequence counted the payload and not the provenance record beside
it. The measured increase is 48,757 bytes.

Corrected: "a fourth generator joins by existing" - it joins by being added to
`_snapshots.MODULES`, which is still a list someone keeps, just the only one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two of these were introduced by the sixth pass's own fix, which is the point.

The sdist figure of 48,757 bytes reproduces nothing. Built with the project's
own backend: main is 771,392 bytes and this branch is 824,266, so the pull
request adds 52,874. The Settles-with bullet claimed the distributed sdist grew
by 48,757 "including the provenance record", and it does not. Both places now
carry measured numbers, and the two files' own sizes are given as sizes rather
than as a delta they are not.

The one factory example was the single factory name main already carries
verbatim. `810 Amped VT Aln 70s (M)` is the worked example in
`generate_models._constant_name`'s docstring, so the sentence it was supporting
had a counterexample for its evidence. The example is now
`110 US PRN Brown FatJ 10s (M)`, which is genuinely absent, and the 137 of 397
the commit message had and the record dropped is back in the record.

"161 parameter names" sat under "Measured against main" and was not measured
against main: 64 of the 161 appear there verbatim, so the number supporting
that sentence is 97. The 161 is a payload-internal fact and has been removed
rather than relabelled.

The family list read as exhaustive and covers 65 of the 77. The other 12 are
internal and diagnostic - `ZenLink*`, `2-Track Looper`, the PCOM defaults,
Nameless - not licence-gated content, so the split is stated.

Also from the seventh pass:

ADR-0015 says `scales.json` distils "the parameters under test" out of a real
catalog. The paraphrase dropped those words, which are the ones explaining why
that file is small. Quoted now.

The coverage test compared basenames, so a row pointing outside the protected
directory could satisfy it while the file inside went unchecked. It compares
repo-relative paths.

STEERING said this repository carries the payload "each" snapshot is generated
from. One snapshot exists and nothing forces a second to commit one, so the
sentence would have gone stale on the next profile.

`_snapshots.MODULES` is half of what the package `__init__` is built from;
`EXPORTS` is the other half.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The docstring said it "catches nothing the byte-for-byte test misses". It
catches the one thing that test cannot see, and telling a future reader
otherwise invites its deletion.

The snapshot holds factory content only, by design. So a model this repository
generates no constants for can join the catalog without moving a generated
byte. Measured: one extra model carrying a `sku` and a `plugin_id`, whose only
parameter is a float and which therefore joins no option list, leaves
`models.py`, `params.py` and `options.py` byte for byte identical. The model
count is the only thing that moves. That case is ADR-0022's own first open
question - whether a unit that has bought an Archetype publishes anything the
maintainer's does not - so this assertion is its guard.

The settlement bullet put five licence-gated models in the harmless pile. Of
the 77 absent non-factory names, 70 carry a `sku` and a `plugin_id` and 7 do
not; the text said 65 from seven families and "the other 12 internal or
diagnostic". The three `Nameless` models are drawn Archetype content from an
eighth family the list omitted, and two hidden PCOM cab defaults are licensed
too. This is the bullet whose job is to state the republication cost rather
than deny it, so understating it by five is the specific failure it exists to
avoid. The split is now 70 and 7, both named.

The sdist byte count is removed rather than re-measured. It was stale again:
the previous commit added 37 bytes to the test module after the figure was
taken, so 824,266 described the commit before it. Only `/tests` is in the
sdist's `include`, so the number moves whenever a test changes and never when
this record does - a committed figure goes stale within a commit or two by
construction, which it did twice. The file sizes are stable facts and stay;
the growth is given as roughly 52 KB.

Also: the provenance record explains `comms_version`'s omission and not
`cortex_control_version`'s. Both are covered now, for their different reasons.
The `test_generators` import no longer needs its `noqa`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The provenance record's size was given as 1,552 bytes. The commit that wrote
that sentence is the commit that made it 1,718, by adding three lines to the
record and then rewriting the same bullet without re-reading the file. That is
the ninth instance of one failure, and the third produced by the commit fixing
the previous instance, so the fix this time is structural rather than
arithmetic: the bullet now records one size, the payload's 46,695 bytes, which
`tests/test_catalog_payload.py` pins against the file. Every other figure is
gone. A number no test holds is a number that goes stale silently, and this
record has now proved that twice about the sdist and once about itself.

"Only `/tests` is in the sdist's `include`" is false. There are eight entries:
the package, the tests, the scripts, the examples, the proto schema, the README,
the changelog and the licence. The conclusion drawn from it survives and is
stronger than was claimed - the figure moves on almost any change to the
repository - and `docs/` is not in the sdist at all, so a change to this record
never moves it.

The provenance record explained the absence of `cortex_control_version` and
`cortex_control_version_valid` as a choice about what belongs in the file. It
was not a choice. The unit's reply does not carry either: the first is what the
host announces TO the unit, and the second comes back in a later message of its
own, at +0.73 s, both recorded in `docs/protocol.md`. Stating a judgement where
the fact is "the wire does not carry it" is the distinction `docs/writing.md`
draws, and the `comms_version` clause beside it, which is a real exclusion, is
now marked as one.

The `PAYLOADS` comment still introduced the shape row as diagnostics, written
before the eighth pass established it as the guard for ADR-0022's first open
question. It points at the test that explains it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`tests/hardware/test_option_structure_on_unit.py` justifies itself with
"Nothing offline can do it: the whole `ModelRepo.xml` is not committed". After
this branch it is committed, inside the payload, and every attribute that test
reads comes out of `parse_model_repo`. The file is not in the diff, so this is
text the change invalidates at a distance - the same failure class as the nine
passes before it, in the one place none of them had looked.

The test still earns its place, for a different reason: an offline count is a
count against the committed capture, and what these numbers need checking
against is the catalog the connected unit is running. That is what the
docstring now says.

Its three neighbours were checked and are still true. They justify themselves
by drift against the unit rather than by the catalog being unavailable, so the
payload does not touch them.

Also from the tenth pass:

ADR-0022 said it records "the one size a test holds and no others". It also
records 556,732 bytes for `ModelRepo.xml`, quoted from ADR-0015's reasoning and
derivable from the committed payload. The claim is scoped to the bullet it is
true of, and the second number is named.

The byte-for-byte failure message printed nothing useful when the only
difference was past `splitlines()` - both sides report end of file. Unreachable
today, since all three generators end with a newline, and now guarded.

`docs/protocol.md` describes this payload and could not point at an example.
It can.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… a reason

The tenth pass found one file outside the diff whose reasoning this branch
invalidates. Looking properly, there are four.

`scripts/extract_scale_fixture.py` carries ADR-0015's argument in full: the
obvious way to get real numbers, "committing `ModelRepo.xml`", "would republish
556 KB of the vendor's product catalog". That is the bullet ADR-0022's
`Settles with` section exists to retire, restated in `scripts/`, and
`tests/test_scales.py` sends readers to it for the reason. The docstring now
says the payload is committed and that what remains is the narrower point: the
fixture is the data under test. Whether it should be derived from the payload
instead is already ADR-0022's third open question.

`tests/hardware/test_generated_constants.py` said "nothing offline can notice -
the generated file is its own yardstick". It has a yardstick now, and this is
the test ADR-0022 names when arguing the two checks are complementary. The
clause is true for the reason that matters and false as written: the offline
check holds the snapshot against a capture, so the two agree while the unit
moves on. That is what it says.

`tests/hardware/test_scales_on_unit.py` drew the same analogy and inherits the
same correction.

Also:

ADR-0022 said the payload "is 46,695 bytes, which `tests/test_catalog_payload.py`
pins against the file". The test pins the provenance record against the file,
not this record's copy of the number, which was a third unpinned copy of exactly
the kind the same bullet argues against. It gives the size as about 46 KB and
points at the record.

The STEERING scope line named eight of the ten changed paths.

The trailing-newline guard called character counts bytes, and two generated
files are not ASCII.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…type

`tests/hardware/test_option_audit_on_unit.py` gave the catalog's absence as its
reason in two places, the same as the four already corrected. Its first is a
direct analogy to `test_generated_constants.py`, whose docstring this branch
changed to say the opposite. Its second says nothing offline can see the
`hidden` counts go stale; both can now be counted from the committed payload -
they are `true` 649 and `atma` 1 - and nothing does. Both sentences were
literally true and neither was the reason that holds, which is that a count
against a capture cannot see this unit's catalog move.

The four usage headers that show `--payload` named a file that does not exist,
`model_repo_payload.bin`. They name the committed one. `docs/architecture.md`
already did; these are where someone actually types the command.

Checked after the edit: all three generators still reproduce the committed
snapshot byte for byte from the committed payload.

Two findings from this pass are not acted on, and why:

`pyquadcortex/protocol/catalogs/coros_4_0_1/__init__.py` says a snapshot is
"generated by the scripts in `scripts/` from a connected unit", which is now
one of two routes. It is a generated file, so correcting it means editing
`scripts/_snapshots.py`, regenerating, and moving the pin in
`tests/test_generators.py`. That is a real change to the generator for a mild
staleness, and it is better made deliberately than as the twelfth item of a
review round.

`tests/test_catalog.py`'s "ships no vendor data" is true as scoped to the tests
it describes. It reads wider than it is now that `extract_scale_fixture.py` no
longer cites it as a repository-wide promise, but rewriting it is a question
about that test's own claim rather than about this branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jonathanstokes
jonathanstokes marked this pull request as ready for review September 22, 2026 23:07
@jonathanstokes
jonathanstokes merged commit be25b3e into main Sep 23, 2026
5 checks passed
@jonathanstokes
jonathanstokes deleted the catalog/model-repo-payload-4-0-1 branch September 23, 2026 14:38
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