From 8a045f185d49c59e32e3bd5932dcb3ed13c26500 Mon Sep 17 00:00:00 2001 From: japabu Date: Tue, 13 Oct 2026 09:31:35 +0200 Subject: [PATCH 1/4] CLAUDE.md: ToyOS's trust model, and the order a fact is taken from its sources The owner's ruling. Capabilities now names the trusted base (the CPU and chipset vendor with its signed microcode, the platform firmware, the signed image with its pinned toolchain and crates), makes a check inside it a bug fence that never withholds a feature for want of a vendor document, and puts everything else behind isolation, external and hot-plug DMA behind the IOMMU. Zero legacy now ranks a fact's sources: the vendor's document, the vendor's own code under any licence, anyone else's code, and a measurement on our machines that also checks every fact above it a bench can reach. Code of any kind is read clean-room, and where a fact came from stays in the reader's evidence, never in the tree. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015xhaydXCVRNscoccHYFUWy --- CLAUDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index db33debd76..9bd0268e2f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,7 +19,7 @@ There are no spec documents. A rule a reader can check lives in an agent's promp ## Principles -- **Zero legacy.** No backwards compatibility, no fallbacks, no workarounds, no BIOS, no 32-bit. Research state-of-the-art OS design instead of replicating older OSes, and read another implementation's source, whatever its licence, only clean-room: one agent writes from it a specification of facts citing no implementation, keeping the provenance in its own evidence, and another builds from that specification alone, handed to it in its brief and never committed. +- **Zero legacy.** No backwards compatibility, no fallbacks, no workarounds, no BIOS, no 32-bit. Research state-of-the-art OS design instead of replicating older OSes. A fact is taken first from the vendor's document, then from the vendor's own code under any licence, its engineers' code for another OS included, then from anyone else's code, and last from a measurement on our machines, which also checks every fact above it that a bench can reach. Code is read only clean-room: one agent writes from it a specification of facts citing no implementation, keeping where each came from in its own evidence and never in the tree, and another builds from that specification alone, handed to it in its brief and never committed. - **Zero silent debt.** Dead code is deleted; every abstraction earns its place. A discovered compromise has exactly two legal outcomes: remove it, or record it with ownership, evidence and an exit condition — and it stays a present-state weakness until removed. - **Code is liability.** If code can be deleted, it is; code that does not earn its keep is deleted or simplified, and not knowing whether it is needed is no reason to keep it. Tooling is code too: a gate, lock, check or test is added only for what reading cannot see. - **Fail fast, trust nothing.** Panics over silent degradation; exhaustive matches; the unimplemented dies loudly; no defensive code. Input that crossed a trust boundary is never trusted and never panics the kernel — it is refused. Never a flat wait, in code or in a test: wait on the event, bounded by a timeout that fails loudly; a fixed delay only where a hardware document mandates it and offers no notification, cited at the site. @@ -43,7 +43,7 @@ There are no spec documents. A rule a reader can check lives in an agent's promp **Syscall ABI** — `sdk/abi/`: struct layouts, syscall numbers, typed wrappers; completely unstable. The cleanest, most sustainable ABI beats convenience; a removed number is free. `sdk/toyos/` builds on it with typed handles, IPC framing, ports, namespaces and `surface` — userland uses `toyos`, the kernel uses `toyos-abi` only. -**Capabilities** — a process holds exactly what its parent moved into it, and among kernel objects there is nothing it can name to get more. No registry, no connect-by-name, no pid-as-authority: `/system/bin/supervisor` builds every program's namespace and device claims from `system.toml` before spawning it, and a handle a process does not hold is a bug in that process — the kernel ends it rather than answering a word it can ignore. **Isolation is non-negotiable, and the filesystem is inside it**: a process names only the paths in the view its parent built for it, the unit of isolation is the program, and a user is the part of the tree a session was handed. Not yet true of files: the kernel still resolves every path against one machine-wide tree until the storage track's per-program views land. +**Capabilities** — a process holds exactly what its parent moved into it, and among kernel objects there is nothing it can name to get more. No registry, no connect-by-name, no pid-as-authority: `/system/bin/supervisor` builds every program's namespace and device claims from `system.toml` before spawning it, and a handle a process does not hold is a bug in that process — the kernel ends it rather than answering a word it can ignore. 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. Inside that base a check is a bug fence, 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. Isolation is for everything else — programs, users and sessions, the network, file contents, and external or hot-plug devices, whose DMA stays behind the IOMMU — and is non-negotiable. **The filesystem is inside it**: a process names only the paths in the view its parent built for it, the unit of isolation is the program, and a user is the part of the tree a session was handed. Not yet true of files: the kernel still resolves every path against one machine-wide tree until the storage track's per-program views land. **CPU state** — a CPU's control registers come from one declaration, applied by the BSP and by every AP and asserted on each; no read-modify-write decides what either holds. From aad72fa5d85063e6e799a66c6ebf1bde5e39778f Mon Sep 17 00:00:00 2001 From: japabu Date: Tue, 13 Oct 2026 09:42:54 +0200 Subject: [PATCH 2/4] CLAUDE.md: a privilege beyond a device claim is the signed image's alone; issues: Thunderbolt and USB4 is a track The owner's ruling, beside the trust model in Capabilities: a reset line, DMA without an IOMMU or a firmware register window is granted only by name in the signed image's system.toml to a program that image ships, and never to a package installed later, whoever signed it. The owner wants Thunderbolt and USB4, PCIe tunnelled through them included; it is filed as an open track with no design, and the external-port refusal holds until one is ruled. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015xhaydXCVRNscoccHYFUWy --- CLAUDE.md | 2 +- issues/toyos-supports-thunderbolt-and-usb4.md | 25 +++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 issues/toyos-supports-thunderbolt-and-usb4.md diff --git a/CLAUDE.md b/CLAUDE.md index 9bd0268e2f..3dec042a24 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,7 +43,7 @@ There are no spec documents. A rule a reader can check lives in an agent's promp **Syscall ABI** — `sdk/abi/`: struct layouts, syscall numbers, typed wrappers; completely unstable. The cleanest, most sustainable ABI beats convenience; a removed number is free. `sdk/toyos/` builds on it with typed handles, IPC framing, ports, namespaces and `surface` — userland uses `toyos`, the kernel uses `toyos-abi` only. -**Capabilities** — a process holds exactly what its parent moved into it, and among kernel objects there is nothing it can name to get more. No registry, no connect-by-name, no pid-as-authority: `/system/bin/supervisor` builds every program's namespace and device claims from `system.toml` before spawning it, and a handle a process does not hold is a bug in that process — the kernel ends it rather than answering a word it can ignore. 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. Inside that base a check is a bug fence, 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. Isolation is for everything else — programs, users and sessions, the network, file contents, and external or hot-plug devices, whose DMA stays behind the IOMMU — and is non-negotiable. **The filesystem is inside it**: a process names only the paths in the view its parent built for it, the unit of isolation is the program, and a user is the part of the tree a session was handed. Not yet true of files: the kernel still resolves every path against one machine-wide tree until the storage track's per-program views land. +**Capabilities** — a process holds exactly what its parent moved into it, and among kernel objects there is nothing it can name to get more. No registry, no connect-by-name, no pid-as-authority: `/system/bin/supervisor` builds every program's namespace and device claims from `system.toml` before spawning it, and a handle a process does not hold is a bug in that process — the kernel ends it rather than answering a word it can ignore. 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. 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. Inside the trusted base a check is a bug fence, 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. Isolation is for everything else — programs, users and sessions, the network, file contents, and external or hot-plug devices, whose DMA stays behind the IOMMU — and is non-negotiable. **The filesystem is inside it**: a process names only the paths in the view its parent built for it, the unit of isolation is the program, and a user is the part of the tree a session was handed. Not yet true of files: the kernel still resolves every path against one machine-wide tree until the storage track's per-program views land. **CPU state** — a CPU's control registers come from one declaration, applied by the BSP and by every AP and asserted on each; no read-modify-write decides what either holds. diff --git a/issues/toyos-supports-thunderbolt-and-usb4.md b/issues/toyos-supports-thunderbolt-and-usb4.md new file mode 100644 index 0000000000..397b48f152 --- /dev/null +++ b/issues/toyos-supports-thunderbolt-and-usb4.md @@ -0,0 +1,25 @@ +--- +status: open +kind: track +opened: 2026-10-13 +--- + +# ToyOS supports Thunderbolt and USB4, PCIe tunnelled through them included + +The owner wants it (2026-10-13), and nothing of it is designed yet. Until a +design is put to him and ruled, "Refuse external, record reflash" (owner, +2026-10-04) holds: a userland driver's claim of a function below an external +port is refused by name (`issues/the-iommu-refuses-nothing-yet.md`, +`issues/a-driver-that-reflashes-its-device-escapes-its-isolation.md`). + +**Constraint.** An external or hot-plug device is outside the trusted base +(root `CLAUDE.md`, Capabilities): a function tunnelled through the port has +its DMA behind the IOMMU from the moment it appears. + +Owner: the orchestrator. + +**Exit**: a metal row on a bench machine with a Thunderbolt or USB4 port reads, +with a device plugged into that port: the device is enumerated and driven; a +PCIe function tunnelled through it is claimed by a userland driver and its DMA +into its grants completes; and that function aimed at memory no grant maps is a +`DMA FAULT` record, the machine still running, as the row's negative control. From f7e61728d41eb730c2167f52cc2ea1c19b262cf1 Mon Sep 17 00:00:00 2001 From: japabu Date: Tue, 13 Oct 2026 09:56:47 +0200 Subject: [PATCH 3/4] CLAUDE.md: another implementation's code is read only clean-room, a vendor's document is cited at the site; implementer.md: never cites another implementation as authority Review round 1 of #907. The clean-room sentence names another implementation's code, whoever wrote it, so a fork's upstream, a dependency and ToyOS's own code stay out of it, keeps the provenance of each fact in the reader's evidence, and says a vendor's document is still cited at the site (orchestrator's ruling). implementer.md takes reviewer.md's scope: a design, value or oracle never cites another implementation's source as its authority, so a fact read clean-room from vendor code is no longer refused by one prompt and allowed by the root. The heading "Fail fast, trust nothing" becomes "trust no input", which is what its body already says. The Thunderbolt/USB4 track's constraint is a pointer, and its exit retires the external-port refusal's row. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015xhaydXCVRNscoccHYFUWy --- .claude/agents/implementer.md | 2 +- CLAUDE.md | 4 ++-- issues/toyos-supports-thunderbolt-and-usb4.md | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.claude/agents/implementer.md b/.claude/agents/implementer.md index 333aaf584d..9b1d18d9b4 100644 --- a/.claude/agents/implementer.md +++ b/.claude/agents/implementer.md @@ -24,7 +24,7 @@ A design is chosen on its merits for the modern hardware ToyOS targets, never be development environment (QEMU, CI, the dev host) or a particular test machine lacks or has a feature, and never because another OS does it that way; when an environment cannot run the right design, the environment changes or the gap is filed. A design, a value or a test's oracle never -takes its authority from another implementation's source; where the vendor's documentation, the +cites another implementation's source as its authority; where the vendor's documentation, the published specifications or the published state of the art back it, it follows and cites them, and leaves them only when they leave it. Bench numbers on a design they back are reported and never block it, but a metal timing past twice its machine's record reds every design: that ceiling is a diff --git a/CLAUDE.md b/CLAUDE.md index 3dec042a24..567b1fac40 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,10 +19,10 @@ There are no spec documents. A rule a reader can check lives in an agent's promp ## Principles -- **Zero legacy.** No backwards compatibility, no fallbacks, no workarounds, no BIOS, no 32-bit. Research state-of-the-art OS design instead of replicating older OSes. A fact is taken first from the vendor's document, then from the vendor's own code under any licence, its engineers' code for another OS included, then from anyone else's code, and last from a measurement on our machines, which also checks every fact above it that a bench can reach. Code is read only clean-room: one agent writes from it a specification of facts citing no implementation, keeping where each came from in its own evidence and never in the tree, and another builds from that specification alone, handed to it in its brief and never committed. +- **Zero legacy.** No backwards compatibility, no fallbacks, no workarounds, no BIOS, no 32-bit. Research state-of-the-art OS design instead of replicating older OSes. A fact is taken first from the vendor's document, then from the vendor's own code under any licence, its engineers' code for another OS included, then from anyone else's code, and last from a measurement on our machines, which also checks every fact above it that a bench can reach. Another implementation's code, whoever wrote it, is read only clean-room: one agent writes from it a specification of facts citing no implementation, keeping the provenance of each fact in its own evidence and never in the tree, and another builds from that specification alone, handed to it in its brief and never committed; a vendor's document is still cited at the site. - **Zero silent debt.** Dead code is deleted; every abstraction earns its place. A discovered compromise has exactly two legal outcomes: remove it, or record it with ownership, evidence and an exit condition — and it stays a present-state weakness until removed. - **Code is liability.** If code can be deleted, it is; code that does not earn its keep is deleted or simplified, and not knowing whether it is needed is no reason to keep it. Tooling is code too: a gate, lock, check or test is added only for what reading cannot see. -- **Fail fast, trust nothing.** Panics over silent degradation; exhaustive matches; the unimplemented dies loudly; no defensive code. Input that crossed a trust boundary is never trusted and never panics the kernel — it is refused. Never a flat wait, in code or in a test: wait on the event, bounded by a timeout that fails loudly; a fixed delay only where a hardware document mandates it and offers no notification, cited at the site. +- **Fail fast, trust no input.** Panics over silent degradation; exhaustive matches; the unimplemented dies loudly; no defensive code. Input that crossed a trust boundary is never trusted and never panics the kernel — it is refused. Never a flat wait, in code or in a test: wait on the event, bounded by a timeout that fails loudly; a fixed delay only where a hardware document mandates it and offers no notification, cited at the site. - **The kernel never crashes from userland.** A kernel bug crashes loudly; a userland bug never reaches it. - **Userland first.** The kernel takes on only what userland cannot. - **No kernel threads.** The kernel creates no thread but the per-CPU idle loop: kernel work runs, bounded, on the thread or interrupt that caused it and is charged to it; long-running work with no owner is a userland server's. diff --git a/issues/toyos-supports-thunderbolt-and-usb4.md b/issues/toyos-supports-thunderbolt-and-usb4.md index 397b48f152..782ad58157 100644 --- a/issues/toyos-supports-thunderbolt-and-usb4.md +++ b/issues/toyos-supports-thunderbolt-and-usb4.md @@ -12,9 +12,7 @@ design is put to him and ruled, "Refuse external, record reflash" (owner, port is refused by name (`issues/the-iommu-refuses-nothing-yet.md`, `issues/a-driver-that-reflashes-its-device-escapes-its-isolation.md`). -**Constraint.** An external or hot-plug device is outside the trusted base -(root `CLAUDE.md`, Capabilities): a function tunnelled through the port has -its DMA behind the IOMMU from the moment it appears. +**Constraint**: root `CLAUDE.md`, Capabilities. Owner: the orchestrator. @@ -23,3 +21,5 @@ with a device plugged into that port: the device is enumerated and driven; a PCIe function tunnelled through it is claimed by a userland driver and its DMA into its grants completes; and that function aimed at memory no grant maps is a `DMA FAULT` record, the machine still running, as the row's negative control. +The owner's ruling on the design retires the external-port refusal and its row +in `issues/the-iommu-refuses-nothing-yet.md`'s exit. From e5a61550504c9745c9dc9ee438cb3670ebd0db79 Mon Sep 17 00:00:00 2001 From: japabu Date: Tue, 13 Oct 2026 20:30:04 +0200 Subject: [PATCH 4/4] CLAUDE.md: the privilege rule is isolation's single exception; a published specification ranks with the vendor's document Review round 2 of #907. "Isolated without exception" contradicted the privilege sentence two clauses later, so the privilege rule now follows the isolation sentence as its single exception. "Granted only by name" collided with "names and process IDs do not grant authority" and is now "granted only in the signed image's system.toml". For USB4, PCIe or ACPI the governing document is a standards body's, so the first rank is the vendor's document or the governing published specification. The clean-room sentence says "code" at both ends. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015xhaydXCVRNscoccHYFUWy --- CLAUDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 351eac3bfc..2c30978647 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,7 +26,7 @@ Read the code for current behavior. `Cargo.toml` accounts for packages; `images/ The supervisor constructs process namespaces and endowments. The kernel enforces object authority; each userland protocol validates its own inputs and grants. The target is per-program filesystem views; inspect the storage track and code for the remaining shared kernel paths. -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 controls the whole machine, and the signed image with its pinned toolchain and crates. Everything else is isolated without exception: 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, 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. A privilege beyond a normal device claim, such as a reset line, DMA without an IOMMU or 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. +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 controls the whole machine, and the signed image with its pinned toolchain and crates. Everything else is isolated: programs, users and sessions, the network, file contents, and external or hot-plug devices, whose DMA stays behind the IOMMU. The single exception is a privilege beyond a normal device claim, such as a reset line, DMA without an IOMMU or a firmware register window: it is granted only in the signed image's `system.toml`, to a program that image ships, and a package installed later never gets one, whoever signed it. Inside the trusted base a check is a bug fence, 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. The loader owns every UEFI call, before ExitBootServices. CPU control registers come from one declaration, applied and asserted on every CPU. Input translation belongs in userland, per surface. The kernel's logging responsibility is its record ring and console; logkeeper owns the log file. POSIX compatibility belongs in `sdk/libc`, never in the kernel's native interface. @@ -34,9 +34,9 @@ Read the relevant subtree's `CLAUDE.md`: `kernel/`, `system/`, `tests/`, `build/ ## Research and dependencies -Choose designs on their merits for modern hardware. Use vendor documentation, published specifications and research. Take a fact first from the vendor's document, then from the vendor's own code under any licence, including its engineers' code for another OS, then from anyone else's code, and last from a measurement on our machines, which also checks every fact above it that a bench can reach. Measurements test assumptions and expose regressions; a missing gain on one bench does not alone reject a sound general design. Label proposals and inferences honestly. Creative architectural exploration may precede measurement; uncertain implementation assumptions must be investigated before relying on them. +Choose designs on their merits for modern hardware. Use vendor documentation, published specifications and research. Take a fact first from the vendor's document or the governing published specification, then from the vendor's own code under any licence, including its engineers' code for another OS, then from anyone else's code, and last from a measurement on our machines, which also checks every fact above it that a bench can reach. Measurements test assumptions and expose regressions; a missing gain on one bench does not alone reject a sound general design. Label proposals and inferences honestly. Creative architectural exploration may precede measurement; uncertain implementation assumptions must be investigated before relying on them. -Read another implementation's code, whoever wrote it, only clean-room: one agent derives facts and keeps the provenance of each in its evidence, never in the repository; another implements from those facts without seeing the source. The derived specification goes in the implementation brief, not the repository. A vendor's document is still cited at the site. Editing an upstream fork is governed by the implementer's fork rules. No upstream pull request is sent for now. +Read another implementation's code, whoever wrote it, only clean-room: one agent derives facts and keeps the provenance of each in its evidence, never in the repository; another implements from those facts without seeing the code. The derived specification goes in the implementation brief, not the repository. A vendor's document is still cited at the site. Editing an upstream fork is governed by the implementer's fork rules. No upstream pull request is sent for now. Use general, widely used crates as published when they are the cleanest solution. Write ToyOS-specific functionality ourselves, including drivers; minimize kernel dependencies and keep libc out of the kernel. A security boundary may justify our own well-tested crate. A fork carries upstream-quality source changes and goes when upstream supplies them; packaging alone uses unmodified source pinned by hash.