CLAUDE.md: ToyOS's trust model, the signed image's privileges and the order a fact is taken from its sources; Thunderbolt and USB4 is a track

[Japabu]

Root CLAUDE.md gains three rules the owner approved on 2026-10-13, and the tracker gains one track he asked for. No production code, source, test or manifest changes.

The owner's decision

1. Trust model (Architecture → Capabilities). ToyOS trusts only what it cannot avoid trusting: the CPU and chipset vendor with its signed microcode, the platform firmware (UEFI, AML, SMM), which already holds the whole machine, and the signed image with its pinned toolchain and crates. Isolation covers everything else: programs, users and sessions, the network, file contents, and external or hot-plug devices, whose DMA stays behind the IOMMU. Inside the trusted base a check is a bug fence. It is kept where it is cheap and catches our own mistakes, such as a write landing in RAM, the IOMMU, the interrupt controllers or another driver's device. It never withholds a feature for want of a vendor document.
2. Privilege (Capabilities, beside the trust model). A privilege beyond a normal device claim (a reset line, DMA without an IOMMU, a firmware register window) is granted only by name, in the signed image's system.toml, to a program that image ships. A package installed later never gets one, whoever signed it.
3. Source order (Principles → Zero legacy). A fact is taken from these sources, in order of preference: the vendor's document; then the vendor's own code under any licence, including code its engineers wrote for another OS; then anyone else's code; and last a measurement on our machines, which also checks every fact above it that a bench can reach. Code is read only clean-room. Where a fact came from is kept in the reader's evidence and never in the tree.
4. Thunderbolt and USB4 (new track issues/toyos-supports-thunderbolt-and-usb4.md). The owner wants ToyOS to support them, including PCIe tunnelled through them. Nothing is designed yet. Until a design is ruled, the 2026-10-04 "Refuse external, record reflash" ruling holds. The exit is a metal row on a bench machine that has such a port.

How it was written

• The Zero legacy sentence was rewritten instead of extended. The source order comes first. Then "Code is read only clean-room", which replaces "read another implementation's source, whatever its licence, only clean-room": the order already says that vendor code under any licence is a source. The owner's provenance clause was merged into the existing "keeping the provenance in its own evidence", which now reads "keeping where each came from in its own evidence and never in the tree".
• The trust sentences come right before the isolation sentence, so "Isolation is for everything else … and is non-negotiable" takes over the old bold lead-in. The bold now marks only The filesystem is inside it, and the "Not yet true of files" caveat stays next to it.
• Net growth of root CLAUDE.md is these sentences only. No other line changed. No issue was edited, and the only new one is the track above.

Rules these contradict: search of .claude/agents/*.md and every subdirectory CLAUDE.md

No prompt or subdirectory CLAUDE.md refuses a feature for want of a vendor map or forbids reading vendor code. I changed nothing outside root CLAUDE.md. Every rule that touches the new ones is listed below, with why it does not leave the tree saying two things:

• implementer.md Measure, build, test, and reviewer.md Fit: "never takes its authority from another implementation's source" and "a citation of another implementation's source as authority" (a BLOCKER). These are consistent with the source order. A fact read from code enters only through a clean-room specification, and the tree cites no implementation.
• The same two passages, "where the vendor's documentation … back it, it follows and cites them", and root CLAUDE.md's "a fixed delay only where a hardware document mandates it …, cited at the site". The new "never in the tree" is attached to the clean-room reader's evidence, so it covers facts read from code. Citing a vendor document at the site still stands. See Unsure.
• implementer.md and reviewer.md Tests: "a test's oracle for what hardware does is the vendor's document, or ToyOS's own read checked against it". The source order says where a design takes a fact. This rule says what a test may assert against. Code read clean-room is never an oracle, and the order's last tier, our own measurement, is the oracle's second clause. Not two things.
• reviewer.md Tests: "its copy of a fact a primary source states is never an oracle". This agrees with the order, which puts the primary source first.
• implementer.md A fork: "a ToyOS arm stands on the platform's own specification, never on another platform's arm copied as its authority". Copying an arm as authority is not a clean-room reading, so the two are consistent.
• Root CLAUDE.md Fail fast, trust nothing: "no defensive code". A bug fence fails loudly on our own mistake and hides no failure, so it is not defensive code.
• kernel/CLAUDE.md: "A device a process drives reaches only the memory its grants map". This holds for every device today. The privilege rule says who may ever be granted DMA without an IOMMU, not that such a grant exists. If one is built, this caveat has to name it. See Unsure.
• build/CLAUDE.md: "images/system.toml defines which programs to build and what the supervisor starts at boot". This is consistent with granting a privilege by name in the signed image's system.toml.

Gates

No production code changed, so the checks root CLAUDE.md asks of a production change (negative control, independent oracle) do not apply. The one gate that reads these files is build/sourcegate.rs's no_tracked_file_identifies_a_machine_or_its_network, which scans every tracked file. It runs inside the host suite.

• cargo run -- --ci host > host.log 2>&1; echo EXIT=$? at aad72fa5d85063e6e799a66c6ebf1bde5e39778f: EXIT=0. The log, with the home path masked, is https://github.com/ToyOSOrg/evidence/blob/c059d771bfed39ca31716e99c9276d771cc43dbb/host-ci-aad72fa5d.log, and sourcegate::tests::no_tracked_file_identifies_a_machine_or_its_network ... ok is at line 449.
• No guest test or metal row reads these files, so none was run.

Unsure

• "Where a fact came from is recorded in the reader's provenance, never in the tree": I read "the reader" as the clean-room reader. A broader reading would also take the vendor-document citations out of the tree, which implementer.md, reviewer.md and root CLAUDE.md's fixed-delay rule all require. That would make the tree say two things. If the owner meant the broader reading, those three rules have to change with it.
• The kernel/CLAUDE.md grant caveat stays true only as long as no privileged program is granted DMA without an IOMMU.

🤖 Generated with Claude Code

https://claude.ai/code/session_015xhaydXCVRNscoccHYFUWy

[Japabu]

Orchestrator on the open reading. The narrow reading is right.

• A vendor's document is still cited at the site, as the existing rules require.
• What stays out of the tree is a code source: another implementation, whoever wrote it, read clean-room. Its provenance lives in the reader's evidence alone.

Make the sentence say that, so a reader cannot take the broad reading. The kernel/CLAUDE.md DMA rule stays as it is. The work that first grants DMA without an IOMMU updates it.

[Japabu]

Review of #907 at aad72fa5d (round 1)

Net lines: git diff --shortstat origin/main...aad72fa5d gives 2 files changed, 27 insertions(+), 2 deletions(-). Production 0, tests 0; root CLAUDE.md +2/−2 (two lines rewritten), new issue +25. Evidence: cargo run -- --ci host at aad72fa5d gives EXIT=0, and the log (evidence pr-907, c059d771b) ends with Host: 76 step(s), all green. Its FAILED lines are the loom and proclife controls the CI judges by their verdict. No guest test or metal row reads these files. The branch merges cleanly onto the current origin/main (a3c471b11).

BLOCKER

• CLAUDE.md:22 — The branch still owes the orchestrator's ruling (CLAUDE.md: ToyOS's trust model, the signed image's privileges and the order a fact is taken from its sources; Thunderbolt and USB4 is a track #907 (comment)). The sentence must say that what stays out of the tree is a code source, meaning another implementation whoever wrote it, and that a vendor's document is still cited at the site. The text at this head does not say either. The new subject "Code is read only clean-room" also leaves the tree saying two things. It drops the old "another implementation's source", which was the scope implementer.md:90-91 relies on: "Upstream's source in a fork is the code being changed, not another implementation". As written, the root rule now covers a fork's upstream source, ToyOS's own code, and the dependency source that implementer.md:100-101 and reviewer.md:173 require agents to search. The fix is one sentence that names another implementation's code, whoever wrote it, as what is read only clean-room, with the provenance of each fact taken from it kept in the reader's evidence and never in the tree, while a vendor's document stays cited at the site.
• .claude/agents/implementer.md:26-27 against CLAUDE.md:22 — The tree now says two things. Root says "A fact is taken … then from the vendor's own code …, then from anyone else's code". implementer.md says "A design, a value or a test's oracle never takes its authority from another implementation's source". A value whose only basis is vendor code read clean-room takes its authority from that code, so an implementer who follows the prompt refuses what the owner's order now allows. The body's "Rules these contradict" claims the two agree, but that holds only for reviewer.md:58, which says "a citation of another implementation's source as authority". implementer.md is not scoped to a citation. It needs the same scope as reviewer.md:58: never cites another implementation's source as its authority. An agent edits a role prompt only when briefed to, so the orchestrator briefs this edit into this pull request.

NOTE

• issues/toyos-supports-thunderbolt-and-usb4.md:21-25 — When this exit is met, a function below an external port is claimed by a userland driver. That turns red the row that issues/the-iommu-refuses-nothing-yet.md's exit asks for: "a userland claim of a function below an external port … is refused by name". The exit should say that the owner's ruling on the design retires that refusal and its row. Otherwise two open tracks have exits that cannot both stay green.
• issues/toyos-supports-thunderbolt-and-usb4.md:15-17 — The Constraint paragraph restates root CLAUDE.md Capabilities, and its "from the moment it appears" goes beyond the owner's "whose DMA stays behind the IOMMU". issues/README.md lets a track carry only a constraint a reader would otherwise pay to re-derive. The paragraph should be cut to its pointer, or say only what the owner gave.
• CLAUDE.md:25 — The heading "Fail fast, trust nothing" now stands three paragraphs above "ToyOS trusts only what it cannot avoid trusting". The owner approved neither a change to that heading nor keeping it beside the new model. The orchestrator should put this to him rather than leave the root saying "nothing" and "only what it cannot avoid". (Prose.)
• PR body — "The owner's decision" item 3 quotes the provenance clause as "kept in the reader's evidence and never in the tree", but Unsure quotes it as "recorded in the reader's provenance, never in the tree". Only one of these is his wording. (Prose; the orchestrator corrects it.)

SEND BACK