GodspeedOS

Small enough to understand. Rigorous enough to trust.

GodspeedOS is a capability-based microkernel operating system written in Rust. Every privileged action requires an explicit, unforgeable capability. Services are isolated in their own address spaces. Failures are loud, never silent. Authority is never inherited or ambient - only granted.

The kernel is deliberately tiny: memory isolation, scheduling, IPC routing, capability enforcement, interrupt routing, and multi-core coordination. Nothing else. Everything above it - drivers, the filesystem, the shell - is a restartable userspace service. The only unkillable component is the kernel itself.

Where to start

This site is a rendered view of the project's own documents. Ninety-one of its ninety-six pages - including every one linked below - are a two-line stub that pulls the real file straight from the repository, so they cannot drift from the source (that is Commandment III applied to the docs themselves). The five exceptions are written for the site because they have no file to be a view of: this page, the Gallery, the Services tour, the Utilities index and Writing a program for GodspeedOS. Those five are checked against the repository on every build instead - that a utility has a row, that a service's peers match its contract - because prose someone wrote is prose that can go stale.

• The Ten Commandments - the human-readable distillation of the whole design. Ten laws that bound every decision. Start here.
• The Constitution - the full specification: the invariants, the capability model, IPC, the scheduler, the memory model, the unsafe policy, and the contribution rules. When the constitution and the code disagree, the constitution wins.
• The Glossary - the abbreviations (TLB, DMA, IOMMU, AHCI, BSP, IPI, and the rest).
• The Almanac - the project's logbook: the days something was learned, in the words of the person who learned it. The bugs, the wedges, and the lessons that became commandments.

How it works, in one breath

A capability is a token carrying a resource id, a rights set, and a generation number. Holding one is the necessary and sufficient authority for the actions it permits. Kill a service and its endpoint generation is bumped; every outstanding capability to it goes stale at once, and the next use returns EndpointDead. Clients look the service back up by name through the kernel's name directory, reacquire a fresh capability, and resume - possibly against a new instance on a different core, which is invisible to them. Identity is stable; location is not.

The Design Notes trace how that model plays out in real subsystems - the filesystem, the block driver, DMA confinement, naming, the scripting language, the network stack - and the Forward-Looking note sketches where it goes next: across a cluster.

Seeing it run

The Gallery shows GodspeedOS actually booting and running - captured from the real system, not mocked up.

CLAUDE.md

Capability-Based Microkernel OS

Status: v3.7 - SMP-Integrated Spec, Reviewed, with Forward-Looking Appendices Scope: v1 milestone (multi-core kernel, two services, cross-core IPC, supervisor restart with core reassignment) Audience: Contributors, reviewers, future maintainers

Table of Contents

1. Purpose of This Document
2. Project Identity
3. Constitution: Non-Negotiable Invariants
4. Architecture Overview
5. Repository Structure
6. Trusted Computing Base
7. Capability System
8. IPC
9. Scheduler and SMP
10. Memory Model
11. Bootstrap Sequence
12. Drivers and Interrupts
13. Service Contracts
14. Service Lifecycle
15. State and Persistence
16. Update Model
17. Developer Workflow
18. Unsafe Policy
19. Debugging Model
20. Performance Philosophy
21. Contribution Rules
22. Identity Test Suite
23. First Milestone
24. Glossary
25. Final Principles
26. Architectural Discipline

Appendices (forward-looking, mostly non-normative):

• Appendix A: Bootloader Choice (Limine)
• Appendix B: Userspace Posture
• Appendix C: Forward-Looking Vision (Non-Normative)
• Appendix D: Shell, Scripting, and Utility Ecosystem (Non-Normative, Far Future)

1. Purpose of This Document

This document is the constitution of the project. It defines the enforceable laws and concrete decisions of the OS.

It is not aspirational. It is a commitment to specific trade-offs.

It exists to:

• Ensure the system remains small, correct, and enforceable.
• Prevent contributors from introducing hidden complexity.
• Make every architectural decision traceable to a stated rationale.
• Resolve future arguments by appeal to written law rather than memory.

When this document and the code disagree, the document wins and the code is wrong. When this document and reality disagree, the document is amended and the change is recorded.

How to read this document. Each section's present-tense body is the current, canonical law - read it as settled fact. The inline Amendment YYYY-MM-DD blocks record how a rule reached its present form and why; they are ratified history, not open proposals or drafts. Where an amendment and the body it sits under read differently, the most recent amendment is the canonical state and the body is being brought up to match. You never need the git history to know the current law: it is the section body, as amended. Sections whose state changed the most over time (notably §6, the TCB) open with a short "current canonical state" box so the settled answer is available before the history that produced it.

The appendices at the end of this document collect forward-looking design notes. Appendix A documents a v1 commitment (the bootloader choice). Appendices B, C, and D are explicitly non-normative - they record design intent and discussion, not commitments. Their content does not amend the constitution.

This constitution has a human-readable distillation: COMMANDMENTS.md, the Ten Commandments of Godspeed. Each commandment is grounded in the invariants and sections it enforces here. Where a commandment and this document disagree, this document is the law and the commandment is amended to match (it is the distillation, not the source).

2. Project Identity

2.1 What This Project Is

A deliberately small, fully-understood capability microkernel, built to internalize the design discipline of capability-based systems by writing one.

2.2 What This Project Is Not

• A novel research system.
• A POSIX-compatible OS.
• A production-grade kernel.
• A general-purpose application platform.
• A competitor to seL4, Fuchsia, Hubris, Redox, or Genode.

2.3 Goals, Ranked

1. Clarity over novelty. Every part of the system should be explainable in a paragraph.
2. Correctness over cleverness. A boring, verifiable design beats a clever, fragile one.
3. Execution over theory. Shipping a working ping/pong beats refining a perfect spec.

2.4 v1 Architectural Principles

• Isolation over performance.
• Explicit transitions over implicit mutation.
• Identity over location.
• Simplicity over cleverness.
• Loud failures over silent fallbacks.

2.5 v1 Permanent Decisions

Amendment 2026-10-17 (live handover): a running service may be REPLACED without stopping, by a second program - code is still never changed inside a running one. The operator asked for Erlang's upgrade-in-place. What this row rejects stays rejected: no new code is ever loaded into a running address space, so W^X holds and the bytes that run are always the bytes the supervisor checked from the disk (14.1). What is now allowed is the observable half of Erlang's feature, made out of mechanisms the system already has: the new version is a separate, isolated program, started BESIDE the running one under the same name; the running one hands it its state over IPC and ends itself (gs::handover, docs/developer-services-design.md 14). What Erlang calls code change is the successor reading the old version's state - written by the package, explicitly.

What the kernel learns: one spawn flag, SPAWN_FLAG_HANDOVER. SpawnImage (which only the supervisor can call, 14.1) may start a task beside the ONE task already running under its name; the name directory re-points to the new endpoint, and the old task's death leaves the name alone (the endpoint-id guard that already handles a respawn racing a death). No new syscall, no shared memory, no capability passed between the two except the successor's endpoint, which the supervisor sends with the offer. A name never has more than two instances. Not a seventh responsibility: it is spawning (4.3), with one refusal relaxed for one caller.

What is opt-in, and what is not promised. A package declares handover = true; without it, an upgrade stops the old version and starts the new as before. Capabilities do not travel (the successor holds its own spawn request's), a request sent to the old version after it drained its queue is lost with it - its caller's gs::call reports OutcomeUnknown, exactly as for a death - and the state is one message. Services only; an app's handover (its screen moving with its state) is not built.

2.6 Reference Systems

3. Constitution: Non-Negotiable Invariants

These are the laws that bound every design choice. Any change that violates an invariant must first amend the invariant - and amendments require a written rationale.

1. No ambient authority. Every privileged action requires an explicit capability.

   Amendment 2026-06-12 (H1): DMA-capable devices were an unstated exception to this invariant - a driver could direct its controller's DMA engine at any physical address, kernel-equivalent reach the capability model never granted. H1 (IOMMU confinement) closes the gap: a confined device reaches only its granted arena. See §6.4.

2. No shared mutable memory by default. Services have isolated address spaces.
3. All authority is explicit. Capabilities, not identity.
4. Kernel remains tiny. Memory, scheduling, IPC, capabilities, interrupts, cross-core routing. Nothing else.
5. Unsafe is isolated and audited. Permitted only in arch/, memory/, capability/, smp/.
6. Services must be restartable (with stated TCB exceptions).
7. Contracts are enforced, not interpreted.
8. State must be explicit and owned. No anonymous singletons.
9. No unowned global mutable state. Immutable globals are fine.
10. System must remain understandable. 30-minute whiteboard rule.
11. Identity is stable; location is not. Services have stable names; their core assignment may change across restarts.
12. Failures are loud, never silent. No silent fallbacks at the kernel boundary.

4. Architecture Overview

4.1 Layered View

  ┌──────────────────────────────────────────────────┐
  │  Application Services  (replaceable)             │
  ├──────────────────────────────────────────────────┤
  │  System Services                                 │
  │  events  ·  block-driver  ·  fs                  │
  ├──────────────────────────────────────────────────┤
  │  Trusted Root  (trusted, restartable)            │
  │  supervisor   (init removed; registry retired)   │
  ├──────────────────────────────────────────────────┤
  │  Kernel  (mechanism, not policy)                 │
  │  memory · scheduler · ipc · capability           │
  │  syscall · interrupts · smp/routing              │
  ├──────────────────────────────────────────────────┤
  │  Architecture Layer  (unsafe boundary)           │
  │  arch/<isa>  - one directory per ISA, and the    │
  │  ONLY place that knows which machine this is     │
  ├──────────────────────────────────────────────────┤
  │  Hardware  (multi-core)                          │
  └──────────────────────────────────────────────────┘

Amendment 2026-09-12 (multi-architecture): this document described a single-ISA system, and had stopped being true some months ago. It named arch/x86_64 in the layered view above, in the repository map (§5) and in the TCB table (§6.1), and mentioned RISC-V nowhere at all. There are now four complete ports, all verified on real hardware - x86-64 (HP T630, Dell Wyse), ARMv7 (Raspberry Pi 2), AArch64 (Raspberry Pi 4) and RISC-V 64 (StarFive VisionFive 2 Lite) - plus three stubs that boot and print (riscv32, loongarch64, s390x). The gap predates the RISC-V work; the constitution was not amended for the ARM ports either.

What this amendment does NOT change is the point of it. No invariant moves, no kernel responsibility is added, and the TCB does not grow: arch/<isa> was always the unsafe boundary (invariant 5, §18.1), and only the directory built for the machine in front of you is compiled into it. What changed is that the noun is now plural.

The property that makes this affordable is worth stating as law, because it is what is actually being defended. A port is bounded to arch/<isa>/: you write that directory and nothing else in the kernel changes. Architecture-neutral code reaches hardware only through the arch::imp seam and must never name an ISA - enforced mechanically by scripts/arch_boundary_check.py (neutral layers reach hardware only through the seam) and scripts/arch_seam_check.py (every arch answers every member of it, discovered from usage rather than a hand-kept list). The RISC-V port was the first completed with no neutral kernel CODE naming the ISA - two comments in memory/allocator.rs and task/scheduler.rs cite it as explanation, which is the honest extent of the claim and the standard the others are being brought to. For comparison, neutral code still names arm in 8 places, aarch64 in 4 and x86_64 in 3.

The rule the operator set for that work, recorded here because it is the bar: an ISA port is not complete when it boots. It is complete when architecture-neutral code no longer knows that the ISA was added. Where neutral code still enumerates ISAs by name - the supervisor's #[cfg(any(...))] spawn arms, the SDK's hwclass list - that is acknowledged debt, not the model.

Amendment 2026-09-13 (portability-hardening): the debt named above is MEASURED now, not counted by hand, and both of its examples are out of date. The amendment above states the bar correctly and then points at two things as the standing debt. One is gone and the other was never an example of it:

• The supervisor's #[cfg(any(...))] spawn arms are gone. That file carried 49 arch-conditional sites when this branch began; it carries 4. (47 when the spawn-table work itself started - two had already gone in the commit that named the board facts. The 49 is the figure milestones/ uses, so this says the same thing they do.) The USB host table was FIVE tables, one per arch plus an empty catch-all, and is now one table whose rows are present exactly where their image is; the seven-times-repeated any(x86_64, aarch64, riscv64) was one question - is configuration space reachable - and is now one build.rs fact. Three service crates went the same way, and where the ISA still answers, it is asked ONCE per fact in a build script rather than at every site that needs it.
• The SDK's hwclass list is not an ISA enumeration and never was. It names DEVICE kinds - NIC, XHCI, EHCI, DWC2, FRAMEBUFFER - plus PCI class-code addressing. That is step D's answer to this problem, not an instance of it: a driver names a device class and the kernel resolves it, which is exactly what stops a new board needing a new name here.

And the count itself was the wrong instrument. "Neutral code still names arm in 8 places, aarch64 in 4 and x86_64 in 3" was true when written and had drifted to 6, 4 and 2 before anybody re-measured, because a hand count is right on the day it is taken and silently wrong afterwards. Worse, nothing was watching: arch_boundary_check.py forbids inline assembly and named arch modules outside arch/, and a #[cfg(target_arch = "arm")] in kernel/src/task/mod.rs is neither, so the debt this paragraph names could grow without failing anything. Userspace had a ratchet (shared_surface_check.py); the neutral kernel had none.

It does now - the same one, which is the honest shape since it is one property asked of two layers. The standing figure is 54 arch-conditional sites outside arch/: 2 in the neutral kernel, 52 above it (46 and 44 when this was written; the rise is board facts in services/supervisor/build.rs and services/wifi-driver/build.rs - the Pi 4's radio (+1), the audio drivers (+4) and, on 2026-10-04, the VisionFive's radio and nic-driver's radio bridge as its own fact (+4) - blessed together that day; and on 2026-10-05 one fewer, when the VisionFive gained the bridge too and the bridge fact became the radio fact by derivation rather than a second test of the instruction set (-1); docs/porting.md has the per-file tree). It may fall freely and may not rise without a recorded reason. What is left is listed rather than implied. The neutral kernel is down to 2, and both are target_pointer_width on one constant - a 32-bit address space genuinely cannot hold a 4 GiB virtual address, so the width IS the question rather than an ISA standing in for one. Above the kernel, nic-driver picks its MAC by ISA on three of four boards and needs a kernel query to stop (backlog/21), hw-enumerator packs a host-bridge config selector that belongs in arch/ (backlog/25), and the rest are the SDK's syscall seam, which §18.1 designates and which is the one place the ISA is genuinely the question.

4.2 SMP View (Per-Core)

  Kernel (shared, concurrent)
  ┌────────────────────────────────────────────────┐
  │  Routing Table: EndpointId → CoreId            │
  │  Capability Table                              │
  └─────────────┬──────────────┬───────────────┬───┘
            IPI │          IPI │           IPI │
  ┌─────────────▼──┐  ┌────────▼───┐  ┌────────▼───┐
  │    Core 0      │  │   Core 1   │  │   Core 2   │
  │   Run Queue    │  │  Run Queue │  │  Run Queue │
  │   Services     │  │  Services  │  │  Services  │
  └────────────────┘  └────────────┘  └────────────┘
    ▲ syscall             ▲ syscall       ▲ syscall

4.3 Kernel Scope (Strict) - MISCIS

The six, and the mnemonic for them - MISCIS, said like "misses": Memory isolation, IPC, Scheduling, Capabilities, Interrupts, SMP routing.

• Memory isolation (per-service address spaces, page tables)
• IPC (synchronous message passing, bounded queues, cross-core routing)
• Scheduling (per-core run queues, round-robin with timer preemption)
• Capability enforcement (validation on every privileged syscall, generation check)
• Interrupt routing (delivery to userspace driver services)
• SMP routing (EndpointId → CoreId map, IPI wakeup)

Leave these six bullets as plain text. scripts/commandments.py parses each line up to the ( as the responsibility's NAME, so bolding the mnemonic letters inside them - **M**emory isolation - turned every name into something it did not recognise and failed six modules at once. Caught in seconds by the gate that reads this list, which is the argument for deriving it from here rather than copying it into config.

"Do not expand MISCIS" is therefore the short form of §4.4: a seventh responsibility is a change to what this kernel IS, not a feature. scripts/commandments.py (I-responsibilities) derives the six from this very list and fails on a module that serves something outside it, so the acronym and the gate read the same source.

The list is ordered to spell the word. It previously ran memory / scheduling / IPC / ... which spells MSICIS, and the order carries no meaning - the checker builds a SET from these bullets and does not care. A mnemonic that does not match the list it names is a small trap, so the list moved rather than the mnemonic.

4.4 Kernel Anti-Scope

The kernel does not contain filesystem logic, network stack, drivers (beyond minimal arch boot), logging infrastructure, application logic, developer tooling, work-stealing scheduler, service migration, or load balancing.

Amendment 2026-06-18 (P2, file-as-capability): delegated resource capabilities do not add file logic to the kernel. The kernel gains the ability to mint, route, and revoke capabilities for resources whose meaning is defined by a service (§7.10). It still contains no filesystem logic: it tracks an opaque ResourceId and its owning endpoint and nothing more; the owning service (fs) alone maps ResourceId → file. "A file is a capability" thus becomes literally true while this anti-scope holds - the kernel never learns what a file is.

5. Repository Structure

os/
  CLAUDE.md
  README.md
  Cargo.toml

  kernel/
    src/
      main.rs
      arch/                # ONE DIRECTORY PER ISA; `arch::imp` aliases the one being built
        x86_64/            #   complete - boot.rs, interrupts.rs, context_switch.rs, page_tables.rs, ap_boot.rs
        arm/               #   complete - ARMv7-A, Raspberry Pi 2 (hardware-verified)
        aarch64/           #   complete - Raspberry Pi 4 (hardware-verified)
        riscv64/           #   complete - QEMU virt + StarFive VisionFive 2 Lite (hardware-verified)
        riscv32/  loongarch64/  s390x/    #   stubs: boot + UART only
      memory/              # frame.rs, page.rs, allocator.rs, bitmap.rs
      task/                # mod.rs, state.rs, scheduler.rs (per-core)
      ipc/                 # message.rs, endpoint.rs, queue.rs, routing.rs, names.rs
      capability/          # cap.rs, table.rs, rights.rs, generation.rs, delegated.rs
      smp/                 # core.rs, ipi.rs, percpu.rs, spinlock.rs, names.rs
      syscall/dispatch.rs
      interrupt/route.rs
      invariants/assertions.rs
      log.rs               # kernel ring buffer
      bootcon/             # boot + panic framebuffer blit (11.4) - NOT a terminal; see console/

  services/
    supervisor/            # restart authority + name authority (TCB); spawned directly by the kernel
                           #   (init removed, Phase 5; registry service retired, Phase 4 - Path C §3.7)
    events/
    console/               # the terminal: ANSI/CSI, grid, cursor, scroll (docs/console-service.md 9)
    block-driver/          # restartable (Phase D)
    fs/                    # restartable (Phase D); depends on block-driver

  sdk/rust/                # service_context.rs, capability.rs, ipc.rs

  osdev/
    src/main.rs
    src/validator.rs       # JSON Schema validation

  examples/
    ping/
    pong/

  contracts/
    schema/service.schema.json

  docs/                  # narrative design notes; `docs/CLAUDE.md` is the index
    observability.md     #   the events sink: logs, traces, metrics, persistence
    service-ownership.md #   who owns a service: images, authority, discovery
    naming-design.md     #   name resolution out of the kernel (Path C)
    persistence.md       #   block driver + filesystem, file-as-capability
    console-service.md   #   the terminal, and the kernel's boot/panic floor
    ...                  #   the index lists them all

  audits/                # append-only EVIDENCE, not documentation
    unsafe-audit.md      #   every unsafe block; CI checks it matches source
    kernel-audit.md  security-audit.md  userspace-audit.md  documentation-audit.md
    2026-07-15-full-trilogy-report.md  #   a dated run of all of them at once

  tests/
    qemu/
      identity/            # identity test suite (§22)
      harness/             # shared test infrastructure
      perf/                # performance benchmarks (§22 B1-B10) - 10/10 ✅

  scripts/               # THE ENFORCEMENT LAYER, and the non-x86 build paths
    commandments.py      #   the Ten Commandments, mechanised where they can be
    commandments_redteam.py #  probes that BREAK each check, so a dead check is caught
    contract_check.py    #   every contract matches its kernel service_config
    unsafe_check.py      #   the unsafe audit matches the source
    doc_refs.py          #   no doc points at a file that does not exist
    facts_check.py       #   a number a doc restates matches the code that owns it
    site_check.py        #   the 5 hand-written site pages still match the repository
    arch_boundary_check.py #  neutral layers reach hardware ONLY through the `arch::imp` seam
    arch_seam_check.py   #   ...and every arch ANSWERS every member of it (the other direction)
    scaffold_check.py    #   ...and the BOUNDED-PORT TEST: how far a fresh ISA gets with only
                         #   `arch/<isa>/` written. The two above prove no RULE is broken; this one
                         #   exercises the claim, because a count is a proxy and a build is not
    shared_surface_check.py #  ratchets arch-conditional code ABOVE the kernel (the other axis:
                         #   `target_arch` there is usually "which BOARD am I on")
    one_way_check.py     #   ONE way to write a service or a driver: `gs`. Ratchets, per crate, the raw
                         #   SDK calls the standard library already covers - may fall, may not rise, and
                         #   a NEW crate starts at zero. Counts only methods with a `gs` replacement, which
                         #   it names; a gap in `gs` is closed in `gs` (backlog/71, 2026-10-05)
    quit_wait_check.py   #   NO SILENT WAIT in the shell, which observes every command: each wait reads
                         #   the command's watch or says on the line above why it cannot trap anyone
                         #   (`// quit-ok:`), and those exceptions may fall, not rise (backlog/fixed/89)
    port_scope_check.py  #   ...and the one the other four cannot answer: did the port EDIT anything
                         #   outside `arch/<isa>/` and the twelve files `docs/porting.md` marks `+`.
                         #   They all ask whether a RULE was broken; an ordinary edit to a neutral
                         #   kernel file breaks none of them, so five ran green over exactly that
    dash_check.py        #   no em/en dashes anywhere (§21)
    foreign_word_check.py #  no DOC shows a POSIX/DOS word being used as a command. `ls`
                         #   became `dir` and the rename reached the shell, the specs and
                         #   the help text - and missed TEN worked examples. Derived from
                         #   the shell's own `FOREIGN_HINTS`, never a hand-kept list
    line_ref_check.py    #   a `path.rs:NNN` citation still points at what it claims. A line
                         #   number rots on the next edit above it, and fifteen checkers
                         #   looked at none: Audit 7 found 7 of 11 wrong, four documents
                         #   citing ONE dead line. `audits/` is exempt - dated evidence
    doc_command_check.py #   a documented INVOCATION must work. `doc_symbols_check` asks
                         #   whether a NAME resolves and `facts_check` whether a NUMBER
                         #   matches; nothing asked whether a documented prompt runs. `dir long /` does
                         #   not - `long` was removed, so the shell lists a directory NAMED
                         #   `long` and discards the path, which is a WRONG ANSWER rather
                         #   than an error. Reads `SUBCMD_FIRST` and osdev's own `match
                         #   suite`, so it cannot drift from either
    comment_symbol_check.py # ...and the same question asked of CODE COMMENTS, which are
                         #   27,126 lines across 238 files - twice the documentation, inside
                         #   the kernel, and read FIRST because they sit beside the code.
                         #   Resolution is STRICTER than for a doc: `doc_symbols_check`
                         #   accepts a name found anywhere in the source, comments included,
                         #   which here would be circular - the comment would satisfy
                         #   itself. A name cited by a comment must exist in CODE. Most of
                         #   its baseline is permanent and correct: registers, SBI calls and
                         #   Linux functions a driver cites on purpose (§26.14)

    # WHERE THESE RUN, which until 2026-09-26 was the hole under all the others. The eight
    # DOCUMENTATION checkers above (doc_refs, docs_index_check, facts_check,
    # foreign_word_check, line_ref_check, site_check, backlog_check, doc_command_check) were
    # on NO developer build path: they ran only in `build.yml`, which is
    # `workflow_dispatch`-only and paused, and in `release.yml`, which fires on a `v*` tag.
    # Documentation was therefore checked AT RELEASE - too late by construction, and v0.20.0
    # is the worked example (its tag run failed late and the release shipped with no
    # artefacts). They are in `osdev`'s `EXTRA_CHECKS` now, so a build runs them. ~11.5 s for
    # all eight, measured. The rule this list already states about `line_ending_check.py`
    # applies to itself: a checker on one build path is a checker on none.
    service_embed_check.py #  every managed service is really embedded in the image
    embed_order_check.py #   the supervisor is newer than the services it embeds
    stack_fit_check.py   #   a service's frames fit the stack it is given (§26.6.1)
    test_report.py       #   collate a suite run into a report
    board.py             #   ONE way to build a bootable image for any port:
                         #   `py scripts/board.py pi2|pi4|visionfive|x86 [--crash-window]`.
                         #   Owns the POLICY the four ports used to state differently - a
                         #   board image is ALWAYS release, every port takes the same flags,
                         #   every build ends by naming the artifact and what to copy where
                         #   (including the per-port RENAMES). The per-port scripts below do
                         #   the work and stay callable
    arm_build.py  pi4_build.py  riscv_build.py  arm_run.py  pi4_run.py  riscv_run.py

  utilities/             # the SPEC for every shell utility, one file each, plus 0_conventions
    0_conventions.md     #   the 14 rules every utility obeys
  website/               # the published book (mdBook); pages `{{#include}}` the
                         #   sources above, so a doc and its page cannot drift
  backlog/               # open items - recorded rather than closed (§26.7)
  boot/                  # per-board boot config (pi2/, pi4/)
  contracts/schema/      # the JSON Schema a service contract is validated against
  examples/              # 15 worked services
  milestones/            # what was achieved and when; ALMANAC.md is the chronicle
  bugs/                  # long-form investigations of four specific hardware bugs
  editors/               # syntax files for the gsh shell language

6. Trusted Computing Base

Current canonical state (as amended below). The non-restartable set is {kernel} alone - the kernel is the only component that cannot be restarted; everything else recovers from death rather than forcing a reboot. Present-tense status of every former TCB member:

• supervisor - trusted but restartable: the kernel respawns it on death (unconditionally, forever) and it reconciles with the still-running services (§6.2).
• init - removed entirely; the kernel spawns the supervisor directly (Path C / Phase 5).
• registry - left the TCB, then the service was retired; naming is now a minimal kernel directory (naming Phase 4 / Path C).
• block-driver, fs - restartable storage services, made safe by fs's crash-consistent recovery (Phase D); their death is a supervisor restart, not a reboot.
• DMA drivers (xhci/ehci on x86, dwc2 on ARM) - all userspace services; in the TCB only on a machine with no IOMMU, where unconfined DMA is kernel-equivalent reach. Where an IOMMU confines them they are least-privilege and drop out (§6.4).

The dated amendments in §6.1-§6.3 record how this floor was reached and why. They are ratified history, not proposals; this box is the settled result they add up to.

6.1 TCB Members

Amendment 2026-06-12 (H1): DMA-capable drivers are no longer an unconditional TCB member. Before H1 they were an implicit, unstated member: with no IOMMU a driver directs its controller's DMA engine at any physical address - kernel-equivalent power the capability model never granted (see the invariant 1 amendment). H1 makes their trust machine-dependent: confined by an IOMMU, a compromise is bounded to the granted arena, so the driver is genuinely least-privilege and restartable and leaves the TCB; on a machine with no IOMMU it stays trust-critical by necessity. The same binary, different posture, with the difference printed at boot. §6.4 is the full treatment; §22 Test 12 pins the confined case.

Amendment 2026-06-17 (Phase D / FS robustness): block-driver and fs are no longer TCB members. They were a v1 simplification (§6.3): fs owned persistent state it could not recover after a crash, so its death - and that of the block-driver it depends on - was a panic+reboot. The filesystem robustness program closes that gap: fs now commits every metadata mutation through a crash-consistent redo-journal and recovers to a consistent state on mount (Phase C; docs/persistence.md §6.8). With recovery in hand, both services are restartable like any other: the kernel notifies the supervisor of their death, which respawns them; fs re-mounts (recovering via the journal) and re-registers, block-driver re-initialises the controller, and clients reacquire via the registry and retry (§14.3, §6.2). block-driver holds no persistent state and was already operationally restartable. Their boot-time spawn must still succeed to bootstrap persistence (§11.3); only their runtime death is now recovered, not fatal. Worked example of invariant 11 and the §6.3 goal reached. §22 Test 13 pins it (fs survives its own restart). The remaining non-restartable set is now just init + supervisor + kernel.

Amendment 2026-07-25 (ARM/USB): the Phase D recovery guarantee is BACKEND-CONDITIONAL, and the backend reports which case it is in. Phase D (above) dropped block-driver and fs from the TCB on the strength of crash-consistent recovery. Bringing up USB mass storage on the ARM32 port showed that guarantee is not a property of fs alone: a redo journal is pure ordering - staged blocks durable before the commit record that authorises replaying them, that record durable before any home block moves - and ordering can only be enforced by a device that attests durability. Two cases, and the difference is a printed fact rather than a hidden assumption (exactly the §6.4 posture):

• A backend that attests durability keeps the guarantee intact. ahci issues FLUSH CACHE EXT when fs asks for it, at the journal barriers (amended 2026-08-22: it used to flush after every 512-byte sector, which cost a transaction a stack of full device flushes and made a single file write take tens of seconds on a SATA SSD; the barriers fs already declares - staged blocks before the commit record, commit record before any home block - are what the guarantee rests on, and a per-sector flush added nothing to them). The consequence is stated plainly: unflushed FILE DATA can be lost on a power cut, while METADATA stays crash-consistent, which is exactly what this section claims and no more. after every write; SD/EMMC completes a write only after the card releases its busy line. Ordering holds, fs recovers to a consistent state on mount, and the Phase D TCB claim stands unchanged.
• A backend that cannot does not. The Pi 2's USB stick refuses SYNCHRONIZE CACHE outright, and FUA - which the drive does honour - costs more time per write than the driver's command budget can give it (USE_FUA, then in the in-kernel arch/arm/dwc2.rs; that file was DELETED by the 2026-08-17 amendment below and the driver is services/dwc2 now - the DEVICE's refusal is what this paragraph turns on, and it is unchanged by where the driver lives). With no barrier available, a power cut can lose the tail of a write sequence, and fs says so once per mount rather than implying a guarantee it cannot deliver. Metadata is still CRC-verified, so the failure is DETECTED loudly on read; what is lost is automatic recovery, not the ability to notice.

So the honest form of the Phase D claim is: fs is restartable everywhere; it is crash-recoverable on a backend that can be ordered. Where it cannot be, fs remains restartable (its death is still a supervisor restart, never a reboot - §6.2 is untouched) and a power loss may require a reformat. Recorded rather than closed, per §26.7: the fix is a block path that can wait out a busy device without holding the core, which is real work and not a constant.

Amendment 2026-09-23 (hardware): the amendment above is RIGHT about the rule and WRONG about its only example. The Pi 2 is not a backend that cannot be ordered - it was never tested, and when it finally was, it recovered. The 2026-07-25 amendment names the Raspberry Pi 2's USB stick as the worked case of a device that "refuses SYNCHRONIZE CACHE outright", and concludes that on that board a power loss may require a reformat. Both halves are contradicted by the machine.

The refusal. Seven sessions across three USB stacks - dwc2 on the Pi 2, xhci on the Pi 4, xhci on the VisionFive 2, one physical stick - and fs has printed no durability warning on any of them. That warning fires at both journal barriers whenever the flush comes back false, so on every run where writes committed it ran and stayed silent: the device answered SYNCHRONIZE CACHE(10) and accepted it. The only local evidence for the refusal was an instrument that could not tell a refusing device from a dead driver - it fired twice in build/pi2a.log immediately after block-driver died, restarting, blaming the stick for a flush nobody was there to answer. That is fixed (Durable / Refused / NoAnswer), and three of the seven sessions ran with the corrected instrument.

The consequence. On 2026-09-23 a power cut 17 s into churn 30, on a PLAIN image with no crash-window, at a moment nobody chose, landed inside the commit-to-checkpoint window:

fs: journal recovered 4 block(s) from an interrupted write
churn verify: 7 file(s) checked, 0 empty, NONE torn
check: 13 files, 2 dirs, 0 bad; the free count already agreed with the tree - nothing was repaired

A replay of 4 blocks means the commit record was durable BEFORE any home block moved. That ordering is the whole of the guarantee, and this device enforced it. It took three attempts, which is ordinary variance.

Corrected the same day, in this amendment rather than around it: the paragraph above first read "at the ~2% per-cut odds the window's sub-millisecond life implies". That figure was wrong. It took fs's own "normally lasts under a millisecond" comment - written about the Dell Wyse, an AHCI SSD - and applied it to a USB stick. The window IS the checkpoint, the interval between the commit record becoming durable and the last home block landing, and those writes are slow on a stick, so there it is a large fraction of each transaction rather than a sliver of it. Measured across every unassisted cut: six hits in twelve (T630 two of two, Pi 2 third of three, Pi 4 first, VisionFive first, Wyse one of five). At 2% that outcome is about 1 in 10^8, so the estimate is refuted rather than imprecise. All five boards have been cut on the same current build. Nothing else in this amendment depends on it - the evidence for the Pi 2 is the replay itself, not how many tries it took - but the number was acted on, so it is corrected where it was stated rather than left for a reader to trip over.

What does NOT change, and is the reason this is an amendment rather than a retraction. The guarantee stays backend-conditional. That reasoning is sound and untouched: a redo journal is pure ordering, ordering can only be enforced by a device that attests durability, and a device that refuses or LIES about a flush cannot carry the guarantee. fs-lyingflush models exactly that case in QEMU and it stays. The honest form of the Phase D claim - fs is restartable everywhere, and crash-recoverable on a backend that can be ordered - is correct as written.

What changes is that the claim is about a CLASS of device, not about this board. The Pi 2 was the one named instance and it does not belong in it; the sentence naming it stands above as ratified history, and this amendment is the canonical state (§1). No board in this project is currently known to refuse the barrier. If one is found, it belongs here with the evidence that put it here - which is the standard the Pi 2 was held to only after the fact, and the point of recording this at all.

The FUA half is untouched and still true: the stick does honour FUA, and FUA costs more per write than the driver's command budget can give it. That was never the load-bearing claim - the flush is - but it is not contradicted by anything here.

Five boards, four ISAs, three storage backends, power cut 5 of 5 recovered in the strong form, and ALL FIVE cut UNASSISTED - Wyse, T630, Pi 2, Pi 4 and VisionFive 2, each landing in the commit window with no held-open pause helping the device. The Pi 4 and VisionFive also had crash-window cuts a day earlier; those are superseded, so no result this amendment rests on depends on a window held open for the device's convenience. docs/gsfs-carnage.md §4 carries the matrix; backlog/fixed/42 carries the investigation, including the two earlier Pi 2 cuts that missed the window and what they did and did not measure.

Amendment 2026-06-09 (H11): registry is no longer a TCB member. It became a real userspace name service (register/lookup over IPC, holding only delegated caps and deriving copies). It owns no kernel-critical state, so its runtime death degrades name resolution temporarily rather than corrupting the system, and it is now restartable (see §6.2, §6.3). Its boot-time spawn must still succeed (the name service must come up to bootstrap), which remains fatal (§11.3). Worked example of invariant 11 - identity (the name) is stable; the registry instance/location is not.

Amendment 2026-06-21 (naming Phase 4 / Path C): the registry SERVICE is RETIRED. Moving name→endpoint resolution to the supervisor (Phases 0a-3c, docs/naming-design.md) left the registry's only remaining job - handing a client a cap to a service by name - to a minimal name → endpoint recovery directory inside the kernel (ipc::names + the gated AcquireSendCap). The supervisor wires every service from a name → cap map at boot and on restart; clients reacquire names through the directory. So the registry service is deleted outright (crate, config, spawn, §22 Test 11/1B moved off it). This is the bounded "one exception" of Path C (§3.7): a thin naming directory stays in the kernel - justified by §6.3 (the recovery anchor must be unkillable) - even though name policy lives in the supervisor. the registry's own design note was DELETED with the service (9a880b12, pre-public cleanup), so this amendment and docs/naming-design.md are the whole record. This line used to point at the file itself, which sent a reader after a document that no longer exists.

6.2 Failure Semantics

The only unkillable component is the kernel itself. Every userspace service - including the supervisor - is restartable; its death is recovered, never a reboot.

Amendment 2026-06-21 (Path C / Phase 6): the supervisor is restartable; its death is no longer a kernel panic. When the supervisor dies (a fault, or a deliberate kill - chaos kill-storm supervisor, the operator control channel), the kernel respawns it - the kernel is the last-resort recovery anchor, the one thing that cannot die (§3.7). The respawned supervisor re-registers its death-notification endpoint in the kernel directory (so notifications re-point to it) and reconciles: it adopts the still-running services (reacquiring each by name) rather than duplicating them, and respawns any that died. The non-restartable set is now {kernel} alone - §6.3's goal reached at its floor. (init removed, Phase 5; registry retired, Phase 4; block-driver + fs restartable, Phase D.) Pinned by §22 Test 15.

The respawn is unbounded - deliberately. The kernel respawns the supervisor unconditionally, forever; there is no cap-then-panic. A bound would re-introduce the very reboot this eliminates (deferred from 1 death to N) and hand an attacker a trivial denial-of-service (kill the supervisor N times to force a reboot). This is not unbounded-resource behaviour (§26.6): each respawn first reclaims the dead instance's frames/kstack/caps, then allocates fresh, so the footprint is constant and reclaimed every time - only a count grows, and a count is not a resource. Each respawn is loud (logged with a running count, §26.4/§26.7), so a sustained loop is visible and an operator can intervene, but the system stays alive rather than rebooting. "Assume the worst" → always recover.

block-driver, fs, and shell are restartable. Their runtime death is recovered by the supervisor's death-notification restart loop (the kernel notifies the supervisor, which respawns them); clients see a temporary EndpointDead / lookup miss, reacquire by name via the kernel directory, and retry (§14.3). fs re-mounts to a consistent state via its crash-consistency journal (Phase C; docs/persistence.md §6.8). The shell is the user's interface - a crash or a deliberate kill shell respawns a fresh prompt (the in-flight command is lost - a re-init, not a resume, §14.2/§25 - but the session recovers) instead of leaving a dead session; closing the one service that used to stay dead-forever if killed ("nothing escapes"; invariant 6). registry left the TCB via H11 (then the service was retired, Phase 4); block-driver + fs via the Phase D amendment (§6.1). Only their boot-time spawn failure is fatal (§11.3).

Amendment 2026-10-11 (ask): the death notice says HOW the task ended, because the kernel already decides it and was throwing it away. A task ends in exactly two ways: the kill syscall, or a CPU fault in user mode (a service that panics ends as the second - its panic handler reads address 0). The kernel takes that path every time, and then told the supervisor only the name, so "why did fs restart?" could be answered nowhere in the system: a deliberate kill and a crash looked the same.

The notice now carries it: the name, a NUL, then K and the name of the task that called kill, or F, a fault kind (memory, instruction fetch, illegal instruction, protection, alignment, or one the port does not classify) and the address the port has for it (task::death, the SDK's death). Each port's user-fault path names the kind; x86's shared exception stub does not know its vector and says so rather than guessing. The supervisor keeps the newest per name and answers supcmd::DEATH; its "died, restarting" line now ends - killed by shell or - memory fault at 0x0.

What this does NOT add, which is why it is an amendment and not a seventh responsibility. No syscall, no capability, no new authority and no record held by the kernel: the cause rides the notice the kernel already sends, to the one task that already receives it, for exactly the tasks it already reports. The kernel learns nothing about any service; it reports a fact about its own kill path. The record - bounded, newest per name, volatile across a supervisor restart - is the supervisor's, which already recorded THAT the service died. Mechanism, not policy (26.10): whether a kill was justified is the killer's to say, and nothing here tries to.

Verified in QEMU on all four ports (a kill named on each; a fault on AArch64 through net-stack's el0-fault-test); osdev test identity 24/0 and adv 15/0. docs/ask-design.md 6 recorded this as the missing contract.

Failure on any core that corrupts shared kernel state (capability table, routing table) results in kernel panic on all cores.

Silent recovery of TCB state risks undefined system state. Loud failure plus clean restart is the only safe v1 option.

6.3 Reducing TCB Over Time - goal reached, at the floor

The v2 goal was: only init, supervisor, and the kernel remain non-restartable. That goal is now met and exceeded - the non-restartable set is {kernel} alone. registry was dropped early via H11 (a restartable userspace name service, then retired entirely in naming Phase 4 / Path C); block-driver and fs were dropped via the Phase D amendment (§6.1, 2026-06-17) once the filesystem gained crash-consistent recovery (the redo-journal, docs/persistence.md §6.8) - so an fs restart re-mounts to a consistent state rather than corrupting it. init was removed outright (Path C / Phase 5): the kernel spawns the supervisor directly. And finally the supervisor itself was made restartable (Path C / Phase 6, §6.2): the kernel respawns it on death - unconditionally, forever - and it recovers from the kernel's name directory (adopting the live services). So the kernel is the only unkillable thing (docs/naming-design.md §3.7) - DMA drivers aside, and only on a machine without an IOMMU (§6.4). The floor is reached; there is nothing left to shrink.

6.4 DMA-Capable Drivers and the IOMMU (H1)

Amendment 2026-06-12 (H1). Adopts IOMMU DMA-confinement as the mechanism that brings DMA-capable userspace drivers into the least-privilege model (invariant 1).

DMA-capable userspace drivers (xhci, ehci) are not trusted root. Their trust status is machine-dependent, and which case holds is reported loudly at boot (invariant 12):

• Without an IOMMU, a DMA-capable driver holds implicit kernel-equivalent power: it programs its controller's DMA engine with physical addresses and can therefore read or write anywhere in RAM, regardless of the capabilities it holds. Its compromise is unbounded, so it is trust-critical by necessity. (Boot reports iommu: no IVRS table ... drivers stay in TCB.)
• With an IOMMU confining it (H1), the device can reach only the driver's granted DMA arena; a DMA outside it faults rather than corrupting memory. A compromise is then bounded to the arena the capability model already granted, so the driver is genuinely least-privilege and restartable - exactly as ordinary services are. (Boot reports iommu: ... confined BDF ...; out-of-arena DMA is pinned by §22 Test 12.)

This machine-dependent posture is deliberate: the same driver binary is least-privilege on a machine whose IOMMU confines it and trust-critical on one without, and the difference is a printed boot fact rather than a hidden assumption. Confinement is applied per driver and only where it fits the driver's DMA shape - xhci is confined to its arena; ehci (which legitimately reaches firmware/hub regions and a low-speed device only through a hub's transaction translator) runs in transparent IOMMU passthrough. See docs/iommu.md.

Operationally these drivers were already restartable (their death reclaims their IOMMU resources and the supervisor respawns them); this amendment makes the trust claim official, not the runtime behaviour.

Amendment 2026-09-12 (multi-architecture / DMA census): this section names its members as a LIST, and the list was short. The rule is restated by PROPERTY. §6.1's table and this section's opening sentence enumerate xhci, ehci and dwc2 as the DMA-capable drivers whose trust is machine-dependent. That enumeration is not the rule - the rule is the argument two paragraphs above, which turns only on a device being able to DMA: any service granted a DMA arena is trust-critical on a machine that cannot confine it. Two services meet that test and were never listed: block-driver (the AHCI command list / FIS / PRDT / data buffers) and nic-driver (the TX/RX descriptor rings and packet buffers on e1000, RTL8168, GENET and dwmac alike). Their absence understated the TCB rather than changing it - both were always in it by this section's own reasoning.

What confinement actually covers today, stated as fact rather than intent:

• xhci is the only confined driver in the system. ehci and block-driver keep a stale firmware DMA pointer that confinement would fault, so both run in deliberate passthrough (kernel/src/task/mod.rs, the confine flag on HwClass::Pci - this cited a DeviceSpec type that has never existed, and it was introduced to replace a rotting line number on the grounds that a field name cannot drift); nic-driver is spawned confine=false.
• AMD-Vi is x86-only. Every iommu:: entry point on arm, aarch64 and riscv64 is a stub and confine_device returns false. Three of the four shipping ports are therefore entirely in the "without an IOMMU" case, with no confined driver at all.

So the honest reading of this section is: the machine-dependent posture is real and the mechanism works, but it currently bounds exactly one device on one architecture. Everything else that can DMA is trust-critical. This is recorded rather than closed (§26.7) because the remaining cases are blocked on hardware (no SMMU is wired up on any non-x86 board) and on a firmware quirk (the stale pointer), not on effort. docs/networking.md and docs/ahci.md each carried the opposite claim for their own driver and are corrected in the same change.

Amendment 2026-10-03 (audio): there are TWO confined drivers now, and the kernel releases a confinement by the device, not by name. The amendment above says xhci is the only confined driver in the system. audio-driver (Intel High Definition Audio, docs/audio.md) is spawned confined as well: every DMA its controller makes - the command rings, the buffer descriptor list, the ring of sound - is inside its arena, so confinement refuses nothing it does legitimately. Verified in QEMU on q35 with amd-iommu: the confinement selftest passes, the tone plays through the confined domain, and a kill and restart releases and re-confines the device (build/audio_iommu_qemu.log). Its controller uses plain MSI, so the interrupt message is in configuration space, out of the driver's reach.

The kernel change it needed adds no responsibility. On a driver's death the kernel reverted the device's confinement only for xhci and ehci, named; a third confined driver would have leaked its I/O page table on every restart. It now releases for ANY task that holds a device, which is exact because the release does nothing for a device that was never confined. The bus-master clear beside it moved from a list of four names to the same per-task device record in the same change. Both are memory isolation the kernel already enforced (§4.3), now keyed on what a task holds.

What does not change: AMD-Vi is still x86-only, ehci, block-driver and nic-driver are still in passthrough, and on the T630 the audio driver does not yet use DMA at all (docs/audio.md, A6), so on real hardware xhci is still the one confined device. The mechanism now bounds two devices, on one architecture, one of them in QEMU only.

(Note 2026-10-08: the T630 confines the audio controller too - its log shows xhci and 00:01.1 each confined with an arena - so on real hardware there were two confined devices, and they shared one IOMMU domain ID. AMD-Vi caches translations by domain ID, so that sharing was a defect; each confined device now has its own (kernel/src/arch/x86_64/iommu.rs, domain_of). Found under an xhci that stopped completing commands in a chaos run, docs/wifi-usb.md 51.)

Amendment 2026-07-16 (SEC-2): a confined USB driver's least-privilege claim is bounded by the console it drives. A USB keyboard driver is, by function, the machine's input path: it delivers keystrokes to the shell via CONSOLE_PUSH, and keystrokes are commands. The kernel cannot distinguish a faithfully-decoded key-press from a synthesized one, so no code check can let a real keyboard type a privileged command while stopping a compromised driver from injecting the same bytes (both reach the shell through the same input ring). CONSOLE_PUSH holders are therefore inside the shell's trust perimeter - IOMMU confinement bounds the driver's DMA, not its console-injection authority. What the code can do is deny the driver any authority it does not need for that role: SEC-2 removed REBOOT from the USB drivers, so a compromised driver can no longer hard-reset the machine directly from any context - reboot lives only with the shell (its reboot command). The residual (a keyboard can type) is inherent to being a keyboard, and is recorded here rather than papered over. audits/security-audit.md SEC-2.

Amendment 2026-07-19 (SEC-2 follow-up): Ctrl+Alt+Del is restored, routed through the shell. The chord initially became ordinary keystrokes, which removed a familiar affordance. It now works again without giving the driver back anything: the USB driver only signals the chord on the console stream (hid::CTRL_ALT_DEL_SIGNAL, a byte outside ASCII that no typed key produces) and the shell - the principal that legitimately holds REBOOT - makes the decision. What SEC-2 actually won is intact: a driver still cannot issue the reboot syscall, in any context, even when no shell is listening. And it grants the driver no new authority, because a CONSOLE_PUSH holder could already type reboot - the residual named just above. Scope: the chord is handled at the shell prompt; while a full-screen app owns the console the shell is not reading, so quit it first.

Amendment 2026-08-09 (Pi 4 / AArch64): the USB stack is OUT of the kernel, and the in-kernel driver is DELETED. The amendment below records that on ARM the USB drivers are in-kernel TCB members "by construction", and calls the userspace split "future work awaiting device-IRQ-to-userspace routing". On AArch64 (Raspberry Pi 4) that work is done: kernel/src/arch/aarch64/xhci.rs (2742 lines of ring-0 code parsing descriptors supplied by whatever was plugged in) no longer exists. The xhci SERVICE drives the controller through an MMIO capability and a DMA arena granted at spawn, reaches the console through CONSOLE_PUSH, and serves storage over the block IPC protocol that block-driver already spoke. The kernel's entire remaining involvement with USB is to establish that the controller is present and reachable and to say so.

This was a feature flag first (xhci-userspace / usb-via-xhci) so both drivers could exist while the service was proven on hardware. The flags are now deleted too: a flag that selects between a compliant and a non-compliant kernel leaves the violation one build away, and it was a genuine footgun (it had to reach three crates; setting some of them gave two drivers on one controller, or none, with every half booting fine alone). There is no build of AArch64 GodspeedOS in which the kernel drives USB. Commandment I is closed on this port, not merely satisfiable.

What this does NOT buy: the driver is still a TCB member on this board (SEC-33). The Pi 4 has no IOMMU/SMMU wired up - every iommu:: entry point on aarch64 is a stub and confine_device returns false - and the service is granted its controller's BAR plus a DMA arena including its physical base. So it can point the controller's DMA at any address, which is kernel-equivalent reach by §6.4's own rule, exactly as an unconfined x86 driver would be. The honest statement is therefore: a buggy USB driver on the Pi 4 is now bounded; a compromised one is still kernel-equivalent.

That distinction is worth being precise about, because the milestone is real but narrower than "Commandment I closed" sounds. What the move genuinely bought is (a) the ACCIDENT surface - ring-0 descriptor parsing became a restartable service, which is the whole content of SEC-29, now closed on aarch64 - and (b) ambient authority: SEC-2's no-REBOOT win travels here (unlike arm32, where an in-kernel driver implicitly holds every kernel authority), and the service holds only CONSOLE_PUSH, its log, its endpoint, its BAR and its arena. The kernel-scope violation is closed; the TRUST posture is unchanged until an SMMU confines the device. Also unmet on this port: §6.4 requires the confinement case to be "reported loudly at boot", and nothing is printed either way (SEC-34).

ARM32 (Pi 2) has since followed - see the 2026-08-17 amendment below. When this was written its DWC2 stack was still in the kernel and still a TCB member; that is no longer true, and the sentence that said the two ports "differ in exactly this" is superseded. Verified: chaos max-carnage 100 rounds, selfcheck 349, hot-plug of keyboard and mass storage in both directions, all on the userspace driver.

Amendment 2026-08-17 (ARM32 / Pi 2): the DWC2 stack is OUT of the kernel too, and arch/arm/dwc2.rs is DELETED. The amendment below (SEC-29/SEC-30) records the in-kernel ARM USB stack as a machine-dependent posture that could not be fixed on this hardware, because ARM did not route device IRQs to userspace. It does now: services/dwc2 registers for USB_VECTOR (arch/arm/irq.rs) and is driven by the interrupt rather than the core-0 timer tick. So the two consequences that amendment draws no longer hold as stated: the memory-safety of arch/arm/dwc2.rs is not TCB-critical because that file does not exist, and SEC-2's win DOES now travel to ARM - the ARM USB driver is a service holding only the capabilities its contract grants, so it cannot call hardware_reset and does not sit inside the kernel trust perimeter.

What does NOT change, and is the same caveat the Pi 4 carries: the Pi 2 has no IOMMU/SMMU, so the driver's DMA is unconfined and a COMPROMISED driver is still kernel-equivalent by §6.4's own rule. A buggy one is now bounded and restartable; a malicious one is not. The ACCIDENT surface is what closed here, exactly as on aarch64. The residual that is inherent everywhere also stands: a keyboard's keystrokes are commands (SEC-2).

The same is now true of the DISPLAY on this port: kernel/src/fbcon (1,172 lines of terminal emulation) left the kernel for services/console, leaving only the §11.4 boot/panic blit (docs/console-service.md §9). Verified on hardware: chaos 50 rounds, 0 kernel panics, 0 liveness wedges, selfcheck 350/0.

[SUPERSEDED IN PART by the 2026-08-17 amendment above - read that first.] The in-kernel ARM USB stack this describes NO LONGER EXISTS: arch/arm/dwc2.rs is deleted and services/dwc2 drives the controller from userspace on USB_VECTOR. Kept because §1 makes an amendment ratified history - this records why ARM USB was ever a TCB member, which is what the later amendment is a reply to. What still holds is the DMA half: the Pi 2 has no IOMMU/SMMU (iommu::confine_device returns false on this arch), so a COMPROMISED driver remains kernel-equivalent by §6.4's rule. A buggy one is now bounded and restartable. This block is placed out of date order, after the amendment that supersedes it, so it is marked rather than left to be read as current.]

Amendment 2026-07-23 (SEC-29/SEC-30): on the ARM32 (Raspberry Pi 2) port the USB drivers are in-kernel TCB members - a machine/arch-dependent posture, the ARM analog of the no-IOMMU case above, and larger. The amendments above concern userspace USB drivers (xhci/ehci) confined - or not - by an IOMMU. The ARM port has no such split yet: the DWC2 USB host driver (keyboard, CDC-ECM/smsc95xx networking, mass-storage) runs in the kernel (arch/arm/dwc2.rs, driven from boot + the core-0 timer tick), because ARM does not yet route device IRQs to userspace (arch/arm/CLAUDE.md, "Drivers on ARM"). So on ARM the USB stack is ring-0 code that parses untrusted device-supplied descriptors and frames, and it is a TCB member by construction. This is strictly more than the no-IOMMU x86 case: there the driver is untrusted-but-userspace with only its DMA unconfined; here the driver is the kernel. It is not fixable on this hardware - the Pi 2 has no IOMMU/SMMU to confine USB DMA regardless, and the userspace-driver split awaits device-IRQ-to-userspace routing - so, per §26.7, it is recorded rather than closed. Two consequences follow: (a) the memory-safety of arch/arm/dwc2.rs is TCB-critical (audited: audits/unsafe-audit.md, audits/security-audit.md Audit 2, no UB/OOB/race); (b) SEC-2's win does not travel to ARM - "REBOOT lives only with the shell, not the USB driver" is an x86 property; an in-kernel ARM driver implicitly holds all kernel authority (it could call hardware_reset directly), so the ARM keyboard driver sits inside the kernel trust perimeter, not merely the shell's. The residual that IS shared with x86 is inherent: a keyboard's keystrokes are commands (SEC-2). audits/security-audit.md Audit 2 (SEC-29/30) is the full treatment.

7. Capability System

7.1 Concept

A capability is an unforgeable token granting specific rights to a specific resource at a specific generation. Holding a cap is necessary and sufficient authority for the actions it permits - provided its generation still matches the kernel's record.

7.2 Capability Structure

Capability = ResourceId + Rights + Generation

• ResourceId - identifies the target resource (endpoint, memory region, MMIO range).
• Rights - bitfield of permitted actions (READ, WRITE, SEND, RECV, GRANT, REVOKE).
• Generation - monotonic counter assigned by the kernel when the resource is created or replaced.

7.3 Properties

• Unforgeable. Only the kernel constructs valid capabilities.
• Explicit. Authority comes from holding a cap, not from identity.
• Non-escalating. Rights cannot be widened.
• Scoped. Targets a specific resource, not a class.
• Revocable. Kernel can invalidate at any time.
• Transferable (with GRANT right).
• Generationed. Stale caps fail their generation check on use.

7.4 Rights Model

7.5 Generations

Every capability carries a generation number. Every resource in the kernel tracks its current generation.

Bumping rules:

• Restartable / destroyable resources bump their generation when they are destroyed or replaced. This invalidates all outstanding caps targeting them.
• Stable resources (kernel-owned, never reclaimed) keep generation 0 forever.

Validation on use:

syscall(cap, action, args):
    if cap.resource_id not in kernel_table:
        return CapNotHeld
    if cap.generation != kernel_table[cap.resource_id].generation:
        return CapRevoked or EndpointDead   # depending on cause
    if action not in cap.rights:
        return CapInsufficientRights
    perform action

  syscall(cap, action, args)
    │
    ├─ cap.resource_id in kernel table?
    │       No  ──▶  CapNotHeld
    │       Yes ↓
    ├─ cap.generation == table generation?
    │       No (destroyed)  ──▶  EndpointDead
    │       No (revoked)    ──▶  CapRevoked
    │       Yes ↓
    └─ action in cap.rights?
            No  ──▶  CapInsufficientRights
            Yes ──▶  perform action  ──▶  Ok

The generation check is one atomic comparison. It is the v1 mechanism for cross-core revocation: bumping the generation on one core makes every cap on every other core stale, with no synchronous notification required.

7.6 Lifecycle

  [kernel mints cap with current generation]
           │
        Created
           │  inserted into cap table
         Held ◀────── action complete ──────┐
           │  syscall + rights + gen check   │
          Used ────────────────────────────▶─┘
           │
           ├── send with GRANT ──▶  Transferred ──▶  Held (receiver's table)
           │
           └── kernel bumps resource gen ──▶  Stale
                                                 │
                                    next use: CapRevoked / EndpointDead

7.7 Error Codes

Both error codes are kept; they share a mechanism but communicate different intent:

Same generation-mismatch mechanism underlies CapRevoked and EndpointDead; the kernel returns the more specific code based on whether the resource was destroyed (endpoint dead) or had its cap explicitly revoked. ReplyDead shares that mechanism on the reply side: a caller blocked in a synchronous Call (§8.2) wakes with ReplyDead the instant its replier's endpoint dies (§8.6).

7.8 Capability Table Concurrency

Multiple cores may execute syscalls touching the same capability table simultaneously. v1 uses a locking discipline that guarantees:

• Reads (cap lookup, generation check) and writes take the SAME exclusive lock; nothing here is wait-free or reader-parallel.
• Writes (cap insertion on spawn, removal on death) are serialized.
• A revocation in flight on one core is visible to a syscall in flight on another core within bounded time (next memory barrier).

The exact primitive is an implementation choice, not a spec choice.

v1 implementation note: A single global lock is acceptable for the v1 milestone. Syscall-path serialization is a known performance cost; sharded or RCU-based designs are explicit v2 work and require benchmarks before adoption.

Amendment 2026-09-12: it is a SpinLock, not an RwLock, and this section claimed a property the code never had. GLOBAL_RESOURCES is a SpinLock<GlobalResourceTable> (kernel/src/capability/table.rs); there is no RwLock type anywhere in the kernel. So "reads are wait-free under common cases" was never true: a cap lookup takes the same exclusive lock a spawn does and can spin behind it. The bullet above is corrected. This does not weaken any guarantee - §7.8's actual requirements (reads correct, writes serialized, revocation visible within bounded time) all hold under plain mutual exclusion, and it is strictly more conservative than the RwLock this described. What changes is the performance claim, which B7 measures.

7.9 Example

fn main(ctx: ServiceContext) -> Result<()> {
    let log       = ctx.capability("log_write")?;
    let pong_send = ctx.capability("ipc_send.pong")?;

    log.info("ping starting")?;
    pong_send.send(Message::text("hello"))?;
    Ok(())
}

7.10 Delegated Resource Capabilities (P2 - file-as-capability)

Amendment 2026-06-18 (P2). Extends the capability model so a resource's meaning can be owned by a service while the kernel still mints, validates, routes, and revokes its caps. This is the mechanism that makes "a file is a capability" literally true (docs/persistence.md §7.2).

The kernel mints unforgeable caps (§7.3) but has no concept of a file (§4.4). Delegated resource capabilities bridge the two: a service owns a band of ResourceIds whose meaning only it knows, and the kernel treats each as an opaque resource - identical machinery to an endpoint cap.

• Mint. A service asks the kernel (resource_mint) to allocate a fresh ResourceId in its band, register it (generation 0, Alive), record the service's endpoint as its owner, and mint a cap with chosen Rights (READ/WRITE/GRANT). The service hands a (narrowed) copy to a client by the existing embedded-cap transfer (§8.5). fs does this on Open, recording ResourceId → file.
• Use = send. A holder uses the cap by sending on it. The kernel validates it (generation + required right) and routes the message to the owning service's endpoint, badged with the ResourceId - so the owner knows which resource without the kernel knowing what it means. A read/write to a file is then a first-class capability operation: validated, denied, or revoked by the same code path as any cap.
• Revoke = generation bump (§7.5). The owner revokes a resource it owns (resource_revoke); every outstanding cap to it goes stale and the next use returns CapRevoked. fs revokes on delete/close.
• Minting is gated (§3.1). resource_mint requires a RESOURCE_MINT capability, granted only to services that legitimately issue resources (e.g. fs). Delegated minting is explicit authority, never ambient.

Every §7.3 property holds for a delegated resource cap exactly as for an endpoint cap: unforgeable, non-escalating (rights narrow on transfer), scoped (to one ResourceId), revocable, generationed. The kernel learns nothing about files; it routes opaque resources. Pinned by §22 Test 14.

8. IPC

8.1 Model

Synchronous message passing with bounded per-endpoint queues. Endpoints are owned by services; services are pinned to cores; sending across cores goes through the kernel routing table.

8.2 Syscalls

#![allow(unused)]
fn main() {
send(endpoint_cap, message)     -> Result<(), IpcError>   // blocks if full
recv(endpoint_cap)              -> Result<Message, IpcError>  // blocks until msg
try_send(endpoint_cap, message) -> Result<(), IpcError>   // non-blocking
call(target_cap, reply_cap, recv_cap, message)
                                -> Result<Message, IpcError>  // send request + block for reply
call_deadline(target_cap, reply_cap, recv_cap, message, secs)
                                -> Result<Option<Message>, IpcError>  // `call`, bounded
}

call is the synchronous request/reply primitive (syscall 41). It sends the request to target carrying a one-shot reply cap (the caller's own endpoint), then blocks awaiting the reply. It wakes with the reply, or - if the replier dies before replying - with ReplyDead (§8.6), so it never hangs. This is mechanism, not policy (§26.10): the kernel learns only about a reply cap and its death semantics, never "request/reply" or "RPC". It is the primitive behind the SDK's request_with_reply; the reply-side twin of the blocked-sender EndpointDead wake.

Amendment 2026-08-21 (CallDeadline, syscall 50): call gains a BOUND, because the unbounded one was being worked around in a way that lost messages. call is the only primitive that dequeues the REPLY specifically (matched to the reply cap), leaving every other message queued - but it blocks forever, so the SDK hand-rolled a bounded variant out of send + a plain endpoint recv. A plain recv takes whatever is next, and a service that SERVES clients on the endpoint it awaits replies on would therefore consume an unrelated client request, fail to match it, and drop it: the request lost outright, and the real reply arriving later as an orphan that desynced every following exchange. Observed on both the Pi 2 and the Pi 4 as fs clients hanging and the block protocol "losing step".

The fix is not a workaround at the caller. It is the correct primitive made usable: same reply-cap semantics, same call_dequeue, plus the deadline machinery RecvTimeout already uses. This is mechanism, not policy (§26.10) - the kernel learns a deadline, not what the caller is waiting for

• and it is what §26.6 asks of every wait in the first place. Ok(None) means the deadline passed; the reply cap is the caller's to reclaim, exactly as on any other failure (§8.5).

A new syscall is a new kernel responsibility and the surface is pinned (Commandment I), so this is recorded here rather than merely added: it is call with a bound, not a new capability, and the enforcement layer refused the change until this amendment existed.

8.3 Routing

The kernel maintains a routing table:

EndpointId → (CoreId, Generation, Liveness)

On every send, the kernel:

1. Validates the cap (rights + generation).
2. Looks up the target endpoint in the routing table.
3. Enqueues into the target endpoint's queue (which lives on the target's core).
4. If the receiver is blocked on recv, sends an IPI to its core to wake it.

8.4 Send Flow

  Service A (Core 0)           Kernel                  Service B (Core 1)
       │                          │                            │
       │── send(endpoint_cap, ───▶│                            │
       │        message)          │ validate cap               │
       │                          │ (rights + generation)      │
       │◀── CapNotHeld ───────────│  cap not in table          │
       │◀── CapRevoked ───────────│  gen mismatch (revoked)    │
       │◀── EndpointDead ─────────│  gen mismatch (dead)       │
       │                          │                            │
       │   [queue full]           │                            │
       │   A blocked ─────────────│────────────────────────────│
       │   in routing table       │  (waiting for queue space) │
       │                          │                            │
       │   [queue has space]      │                            │
       │                          │── copy msg into B's queue ─│
       │◀── Ok ───────────────────│                            │
       │                          │── IPI Core 1 ─────────────▶│
       │                          │   wake B if blocked        │

8.5 Message and Queue Format

• Maximum message size: 4 KiB (one page).
• Queue depth: 16 messages per endpoint, fixed in v1. Worst-case 64 KiB per endpoint queue.
• Copy semantics: kernel copies sender → receiver. Zero-copy is permanently rejected (§2.5).
• Embedded capabilities: caps inside a message are transferred (with GRANT) and removed from sender's table.

Queue depth is not configurable per endpoint in v1. Per-endpoint depth is a v2 concern.

Transferring a capability - the three checks. Embedding a cap in a message moves authority. The kernel enforces the rules below but cannot warn you at compile time, so an author (and a reviewer) must verify all three every time a cap is sent:

1. Grantable? The cap being sent must hold the GRANT right, or the transfer is rejected with CapNotGrantable (§7.7). A copy made by derive_cap carries only the rights of its source, so a send-only cap yields a send-only copy that cannot be transferred. Do not assume a transfer succeeded; a send that embeds an un-grantable cap fails, and the receiver gets nothing (§7.4, §7.6).
2. Moved, not kept. A successful transfer removes the cap from the sender's table (§7.6): authority moves, it does not duplicate. Reusing that handle afterward is a use of a cap you no longer hold. And if the transfer failed, the cap stayed - reclaim it (so a table slot does not leak, §26.6). Either way, the outcome of the send decides what you may do next: never ignore it.
3. Narrowed to need. Grant the least rights the receiver needs (§7.3). In particular, do not pass GRANT onward unless the receiver is meant to re-delegate - a cap handed out with GRANT lets its holder transfer it again. Rights only narrow on transfer; widening is impossible, so the floor you set is the floor forever.

8.6 Failure Semantics

Amendment 2026-06-30 (reply-side death-wake): a caller blocked awaiting a reply wakes with ReplyDead, completing the sender side of this table. The rows above already wake a blocked sender when its target endpoint closes (EndpointDead); the reply side was the missing twin. A synchronous request/reply caller (the SDK request_with_reply, on which fs's block_rpc rides) sends a request carrying a one-shot reply cap and then blocks awaiting the reply on its own endpoint. If the replier died after receiving the request but before replying, that blocked recv hung forever - a reply that will never come. The kernel now tracks, for a caller blocked in a synchronous CALL, the endpoint it awaits; the endpoint-death path finds any such caller (its outstanding reply cap's holder has died) and wakes it with the new ReplyDead code, mirroring the blocked-sender wake exactly (same generation/liveness mechanism, same cross-core IPI). This is mechanism, not policy (§26.10): the kernel learns only about a reply cap and its death semantics - never "request/reply" or "RPC". It is bounded (a blocked task has at most one in-flight call, so one tracking slot per task). It is the executable form of Commandment VIII for interdependent services: a dependent waits on its dependency's reply (truth), and a dependency that dies wakes it loudly rather than hanging it. Pinned by osdev test reply-dead (the reply-side twin of §22 Test 4).

No delivery guarantee. A successful send means the message was queued, not processed. Protocols requiring acknowledgment must build it explicitly.

8.7 Send-During-Restart Race

Without explicit handling, this race is real:

• Core 0: A reads cap to B (generation 4, alive).
• Core 1: B is killed, generation bumped to 5.
• Core 0: A's send syscall executes.

Resolution: the kernel checks A's cap generation against the routing table's current generation atomically inside the send syscall. The generation has been bumped to 5; A's cap is generation 4; send returns EndpointDead. The race is invisible to the developer.

8.8 Cross-Core IPC Cost

Cross-core sends pay one IPI to wake a blocked receiver, one memory barrier on enqueue, and cache-line bouncing on the queue's head/tail indices. These are real costs but they are bounded and predictable. v1 does not optimize cross-core IPC beyond getting it correct.

8.9 Deadlock and Mutual-Blocking Avoidance

The kernel does not detect or break deadlocks.

Design rule: In any protocol where A and B both send to each other, at least one direction MUST use try_send. Mutual blocking sends are an anti-pattern the kernel will not detect and will not recover from. The supervisor's quantum-starvation watchdog is a last resort, not a primary mitigation.

The classic deadlock - A and B both call send to a full queue - is the developer's responsibility to prevent at the protocol level. Use try_send, structure as request/response, or apply explicit timeouts.

9. Scheduler and SMP

9.1 Model

• Multi-core in v1. Number of cores discovered at boot.
• Per-core run queues. Each core runs round-robin over its own queue.
• Static placement. Services are pinned at spawn; they never migrate.
• 10 ms preemption quantum, per core, enforced by each core's local timer.

  spawn ──▶  Ready
               │  scheduler selects
               ▼
            Running ◀──────────────────────────────────────────┐
               │                                                │
               ├── timer preemption (10 ms) / yield() ─────────┘
               │
               ├── recv() on empty queue ──▶  BlockedOnRecv
               │                                   │
               │                   message arrives │
               │                   (IPI wake) ─────┘
               │
               ├── send() on full queue ──▶  BlockedOnSend
               │                                   │
               │               queue drains (IPI) ─┤
               │               or EndpointDead ─────┘
               │
               └── page fault / supervisor kill ──▶  Dead
                                                        │
                                            frames reclaimed, generation bumped

9.2 Placement (Strict)

When the supervisor spawns a service:

1. If the contract specifies [placement] core = N:
   - If core N exists and is ready, spawn on N.
   - Otherwise, spawn rejected with PlacementInvalid.
     The supervisor logs the rejection and skips the service.
     The system continues with the services that did start.
2. If no placement specified:
   - Round-robin across ready cores.
3. Once placed, the service stays on that core for its lifetime.

Rationale (strict): Contracts are enforced, not interpreted (§3.7). A contract that names a core means the developer expressed deployment intent. Silently rerouting to a different core would be exactly the kind of reinterpretation a capability-based system is designed to forbid. Contracted placement is deployment-coupled by design.

On restart: the placement decision is re-evaluated from scratch using the rules above. The supervisor does not remember the previous core.

• If the contract specified a core, that core is required again. If it is unavailable, the restart fails with PlacementInvalid - the same strict rule as initial spawn.
• If the contract did not specify a core, round-robin selects a fresh core, which may differ from the previous one.

This is consistent with invariant 11 (identity is stable; location is not). Sticky placement would make location stable across restart, contradicting the principle. Mid-execution migration remains forbidden.

9.3 Yield

#![allow(unused)]
fn main() {
yield() -> ()
}

Yield is advisory. Preemption remains enforced regardless. The scheduler does not rely on cooperative behavior for correctness or fairness.

9.4 Cross-Core Wakeups

When a syscall on core 0 needs to wake a task on core 1 (e.g., send woke a blocked recv), the kernel sends an IPI to core 1. The receiving core's IPI handler re-enters the scheduler.

9.5 What v1 Does Not Have

• Work stealing
• Load balancing
• Priority scheduling
• Service migration
• Core hotplug (cores discovered at boot are fixed for system lifetime)

10. Memory Model

10.1 Isolation

Each service has a separate virtual address space established at spawn time via per-task page tables.

10.2 Limits

[resources.memory]
request = "32MiB"   # minimum needed to start
limit   = "64MiB"   # maximum permitted

10.3 Enforcement

  Service memory action
    │
    ├── alloc within limit ─────────────▶  Memory returned  ──▶  Continue
    │
    ├── alloc beyond limit ─────────────▶  AllocDenied  ──▶  Service continues (may degrade)
    │
    └── access outside mapped region ──▶  Page fault  ──▶  Service killed
                                                                  │
                                                    Supervisor decides restart

10.4 Two Failure Modes

AllocDenied is recoverable. The service knows it asked for too much and can degrade.

A protection violation is unrecoverable. The service is in undefined state and the only safe response is termination.

10.5 TLB Coherence

When a page is unmapped (service killed, memory reclaimed), the kernel issues a TLB shootdown via IPI to every core. Operations resume only after acknowledgment from all cores. v1 minimizes unmap frequency by reclaiming memory only at service death.

Amendment 2026-10-10 (backlog/fixed/80 K20): this section names the guarantee, not a mechanism, and the mechanism it named had not run for some time. The paragraph above says the kernel "issues a TLB shootdown via IPI to every core" and waits for acknowledgments. It does not. The broadcast that did that had no caller, and has been deleted. What the kernel guarantees, and has guaranteed all along, is this:

No core can use a translation into a frame after that frame has been freed.

• Reclamation waits for quiescence. A dead task's stack and page tables are not freed until no core is running it or still leaving it (core_still_using, CORE_LEAVING in task/scheduler.rs). Nothing is freed while a task can still execute.
• Every switch invalidates on the core that switches. x86 writes CR3 (no PCID), ARMv7 issues TLBIALL when TTBR0 changes, RISC-V issues sfence.vma after writing satp, and AArch64 flushes on every switch. A core that ran the dead task has dropped its entries before it stops counting as "leaving" it.
• Where an idle core keeps a dead root installed, the free invalidates everywhere. On AArch64 an idle core keeps the last task's root in TTBR0, and the CPU may walk it speculatively, so free_page_table_root issues an inner-shareable invalidate (tlbi vmalle1is) before the root goes back to the allocator. The other ports switch an idle core to the kernel's own root.
• Nothing changes a mapping under a running task. User mappings are only added while a task lives; the kernel-stack guard pages are unmapped on the boot core before any other core starts; the Pi 4 framebuffer remap is boot-only and invalidates inner-shareable anyway.
• No address-space identifier is in use on any port (no PCID, ASID 0 throughout). A port that adopts one must not reuse it before the invalidation that makes the reuse safe.

What this does NOT change. Translation coherence is still a kernel responsibility, under memory isolation and SMP routing (4.3); no responsibility is added or removed, and no guarantee is weakened. Removing the broadcast removed no local invalidation. If a future feature changes a live mapping - a remap, a permission downgrade, an unmap a running task can observe - it brings the cross-core invalidation it needs with it, and is recorded here; until then that machinery would be speculative code (26.2).

Two residuals, recorded rather than closed (26.7). Both concern speculation only; the kernel makes no access through either window. (a) On every port a task that kills ITSELF still has its root installed while its lower tables are freed (the root itself is deferred, CORE_PENDING_PML4). (b) An AArch64 idle core walks a root whose lower tables have been freed, until free_page_table_root's invalidate. Whether wrong-path speculation through a recycled table frame can have a visible effect - setting an accessed bit, or a speculative read of a device register through a garbage descriptor - is not checked. The smallest hardening for both, should it ever be needed, is to switch the core to the kernel root before reclaim.

Pinned by P7, which no longer stands in for this property with a generation count. A task stamps a pattern into fresh pages and is killed - from another core on even cycles, by its own fault on odd ones - and a checker given the same addresses, on the same core and on another, must read only the zeroes the kernel hands out (no_stale_translation_after_death, 32 cycles). Shown to fail when the checker is broken and when the kill path skips both its wait and its wake. Its limit, recorded: a kill path that skips ONLY the wait still passes, because the wake stops the victim before its frames are reused. The per-port proof is recorded in backlog/fixed/80 K20.

11. Bootstrap Sequence

11.1 Sequence

  Limine (Bootloader)
    ── loads kernel image, hands off to BSP
    ── supplies: physical memory map, framebuffer, SMP topology, HHDM

  Kernel BSP
    ── paging, IDT, GDT
    ── frame allocator, capability subsystem
    ── start APs (real-mode trampoline → long mode)
         APs: enter idle scheduler loop
    ── mark all available cores ready
    ── spawn supervisor on Core 0   (the kernel's ONE direct spawn - no init)

  supervisor (Core 0)
    ── spawn events on Core 0
    ── read boot manifest
    ── spawn services per placement policy (§9.2),
       wiring each from its name→cap map (no kernel name resolution)

  ── System reaches multi-core steady state ──

Amendment 2026-06-21 (naming Phases 3b-5): the kernel spawns the supervisor directly; init is removed; the registry service is retired. Moving name→endpoint resolution out of the kernel (docs/naming-design.md, Path C §3.7) makes the supervisor the name authority. Phase 3b moved the name service under the supervisor; Phase 4 then retired the registry service entirely (the kernel's minimal name → endpoint recovery directory - ipc::names + the gated AcquireSendCap - is the namer now; the supervisor wires every service from its name → cap map and clients reacquire by name through the directory). Phase 5 removes init: the kernel's one direct spawn is the supervisor (task::spawn_supervisor, using the gated SUPERVISOR_ELF), and the supervisor - not init - spawns the logger. The supervisor's boot-time spawn failure is still fatal (the kernel panics, "supervisor spawn failed", §11.3, §6.2) - now from the kernel's direct spawn rather than an init abort. The non-restartable set is now just supervisor + kernel.

Amendment 2026-09-12 (multi-architecture): the sequence above is the x86-64 one, and THERE IS MORE THAN ONE ENTRY PATH. kernel_main is called only by x86-64's _start. The ARM, AArch64 and RISC-V ports bring the machine up themselves (arm_boot_main, aarch64_boot_main, and the RISC-V S-mode entry) and then join the same neutral kernel. The consequence is a real trap rather than a pedantic one: anything added to the neutral boot path runs on x86 alone, silently, and a port that never reaches it shows no error at all. Limine, the HHDM and APIC-supplied SMP topology are x86-64 facts; the others discover memory and harts from a device tree and start secondary cores through their own mechanism (PSCI on ARM, SBI HSM on RISC-V). Everything §11 says about WHAT must be true at the end of boot holds on every port; only the route differs.

The bootloader is Limine, accessed via the Limine Boot Protocol. Limine is responsible for loading the kernel image, supplying the physical memory map, the framebuffer descriptor, kernel relocation info, and the SMP topology (APIC IDs of all available cores). See Appendix A for the bootloader rationale and installation story.

11.2 BSP and APs

• BSP (Bootstrap Processor) - the first core to execute kernel code. Responsible for kernel init and bringing APs online.
• APs (Application Processors) - secondary cores. Brought up via real-mode trampoline (arch/x86_64/ap_boot.rs), then jump to long-mode kernel code, then enter idle.

Because Limine supplies APIC IDs directly, the kernel does not need to probe ACPI/MADT for SMP topology. This removes a non-trivial subsystem from arch/x86_64/ap_boot.rs.

11.3 Failure During Bootstrap

11.4 Logging Before Any Service Exists

The kernel maintains a 16 KiB ring buffer (a single shared sink). Anything logged writes to the ring buffer and the serial console - always, not only before a service is up. Nothing drains it, deliberately: drain_to_events has zero callers and kernel/src/log.rs says so in its first line. (This body previously said "per-core view" - there is one static RING - and that events "drains the accumulated buffer once, at its own startup". It never has; backlog/fixed/06 is open, and the 2026-09-04 amendment below establishes non-drainage as the design.)

Amendment 2026-09-04 (logger -> events): the service is renamed, and this section's title was wrong in a second way that matters more than the name. The title read "Logging Before Logger Exists", which implies logging is something the logger service does once it is up, and that the kernel ring is a stand-in until then. It is not, and never was. ctx.log() is syscall 5, gated by the log_write capability, writing the kernel ring and serial DIRECTLY - always, for every service, for the life of the machine. No log line has ever been sent to that service; its contract declares only ipc_receive, and its endpoint is drained with unrecognised messages dropped.

The consequence is a property worth naming, because it is easy to destroy by tidying: logging does not depend on the service being up. A chaos storm that kills it loses no log output, and ctx.log() never blocks on it and never returns EndpointDead from it. So logs must NOT be re-pointed at events as it grows - that would make observing a failure depend on a service that can fail, which is the same argument §15 makes about storage, one layer up. Traces and metrics ride IPC to the service; logs stay on the floor.

The rename itself is the name catching up with the job. The service has held the 192-event IPC trace ring since trace shipped, and has never held a log. events rather than observability: observe already exists as the live view, house style is one short word, and a service named after a property of a system becomes the dumping ground §4.4 and §26.2 exist to prevent. It is cheap because the capability model works - ctx.log() resolves through log_write_slot and the trace path through a single SINK_NAME constant, so no service names its own sink.

What is NOT renamed, deliberately: log_write, log_write_slot, ctx.log(), syscall 5 and kernel/src/log.rs. Those are this section's floor, which is a separate path the service was never on. §22 Test 2's assertions are renamed log_received / log_did_not_receive for the same reason - they check that a log reached the floor, which is what they always checked.

No kernel responsibility is added or removed. The kernel was edited (hard-coded service-name lists in task/scheduler.rs and build.rs), which is re-verification rather than growth. Design note and evidence: docs/observability.md §1 and §9.

Where the machine's only output device is a display, the floor also includes a minimal framebuffer blit (kernel/src/bootcon): plain ASCII, escape sequences discarded, no character grid, no cursor, no scrollback. It is not a terminal - the terminal is the console service (docs/console-service.md §9).

Amendment 2026-08-17 (console service): the log floor covers a minimal framebuffer blit, because §11.4 was x86-shaped. This section said "serial console" because on a PC serial is always there. On a Raspberry Pi wired to a TV it may not be, and a kernel that can only speak to a serial port it does not have is mute - a boot that fails before any service exists, or a panic, produces a frozen screen and no reason on it, which is exactly the silent failure invariant 12 forbids.

The blit earns ring-0 residency by impossibility, which is the only thing that does (the bar the control channel failed to clear and the supervisor spawn clears): a panic halts every core, including the console service, so it cannot ask a service to report it. Boot output has the same shape - it precedes every service, including the one that would render it. Both are this section's existing ring-buffer argument applied to a machine with no serial port, which is why the answer is the same one: a bounded floor the kernel owns.

The amendment is deliberately narrow, and the narrowness is the point. What left the kernel in the same change was 1,172 lines of terminal emulation - the ANSI/CSI state machine, the UTF-8 decoder, the shadow grid, the cursor, scrolling, reverse video - because rendering a shell prompt is policy (§26.10) and a display driver is §4.4 anti-scope by name. What the floor keeps cannot format, cannot position, and cannot scroll: reaching the bottom of the screen clears it and starts again at the top, since serial holds the full history either way. Ownership of the framebuffer transfers to the service when the kernel GRANTS it, at spawn - not when the service first renders - and returns to the kernel if that service dies, or on a panic.

§22 has no new test: the property this pins is a negative one on a machine we cannot fail on demand in QEMU. It is pinned instead by scripts/commandments.py, which counts the kernel's modules against §4.3 and for which fbcon was the last standing violation.

Amendment 2026-10-08 (events log boot): the floor keeps a fixed copy of the BOOT, and it is readable. The ring above wraps, and nothing reads it - so on a busy machine the boot was gone from the kernel within seconds, and the only record of what a machine found as it came up was a serial cable that is often not attached. The kernel already held every one of those bytes and had no way to give them back.

Beside the ring, log.rs now keeps the first 32 KiB ever logged, which fills once and then never changes. InspectKernel query 27 copies a range of it out, INTROSPECT-gated, because the boot log names every service and device on the machine; the shell shows it as events log boot. A full record says so, and that later lines are on serial.

What this does NOT change is the point of the amendment above. The record is read by COPY, never drained, so no log line depends on a reader being up, and ctx.log() is exactly what it was. It is the floor this section already defines, made readable - not a log service in the kernel. The kernel does not parse a line, keep a line count, or know which lines matter: it keeps bytes in order and stops when the array is full. No responsibility is added (it is 4.3's memory and the existing 11.4 ring); the new query is pinned in COMMANDMENTS.baseline.toml because a query is surface. The cost is 32 KiB of kernel memory on every port.

12. Drivers and Interrupts

12.1 Model

Kernel routes interrupts. Drivers are user-space services. block-driver is restartable like any other service (§6.1, Phase D amendment 2026-06-17) - it was "trusted in v1" until fs gained crash-consistent recovery.

12.2 Routing

  Hardware IRQ N (arrives on some core)
    │
    ▼
  Kernel IDT handles interrupt
    │
    ▼
  Interrupt Router dispatches by IRQ number
    │
    ▼  IPC message to driver's interrupt endpoint
  Driver Service
    ── recv() returns interrupt event
    ── handles device via MMIO capability

If the driver runs on a different core than the one receiving the IRQ, routing crosses cores via the same IPC mechanism as any other cross-core send.

12.3 Driver Capabilities

[capabilities]
hw_interrupt = [12]                       # IRQ line
hw_mmio      = ["0xfee00000+0x1000"]      # MMIO region

The kernel validates these at spawn time and grants caps only for the specified resources.

Amendment 2026-10-01 (DevicePower, syscall 54): the device grant is RENEWABLE - a service granted a device's window may ask the kernel to cut and restore that device's power. This is not a seventh responsibility. The grant above already includes power: on the Pi 4 the kernel powers the SD domain through the firmware mailbox at boot BEFORE it can hand wifi-driver the radio's window, because a window to an unpowered device is not a grant. What the kernel could not do was renew it, and the CYW43455 made that matter: six host-side resets - I/O reset, core halt, 802.11 reset, chipcommon and PMU watchdogs, a RAM clear - each left a chip whose ROM will not boot a new firmware (docs/wifi.md 45). Only cutting its power is a power-on, and every reference driver's recovery path cuts power.

What the kernel learns, and what it does not. It mints DEVICE_POWER at spawn to the one service it hands a fixed peripheral window to, where the arch layer can power the device behind it (arch::imp::device_power_control) - derived from the grant, not from a privilege bit the spawner passes, and never to anyone else, because a window has exactly one holder. DevicePower(on) checks that holding and drives the pin the arch layer names for the CALLER'S device (device_power): on the Pi 4, WL_ON on the firmware's GPIO expander, through the mailbox SET_GPIO_STATE tag - the pin Linux's mmc-pwrseq-simple toggles for the same chip. The kernel does not know what the device is, what firmware it runs, whether it is alive, or when its power should be cut: those are the driver's (§26.10), and the hold-off and settle times are the device's and live in the driver with it. Every other port answers the seam with false, and the syscall reports that honestly rather than pretending. (Note 2026-10-08: the VisionFive 2 Lite answers it too - its AIC8800's power pin, by device kind WIFI_SDIO, result by read-back, arch/riscv64. Every port but those two answers false.)

Why it is recorded. A new syscall and a new resource widen the surface Commandment I pins, and the gate refused this change until this paragraph existed - which is the gate working. The service that uses it does so as its LAST resort, after adopting the firmware it finds running (docs/wifi.md 46); the power cycle is for a firmware that has stopped, and it is what turns "reboot the machine" into "the driver recovers in a few seconds" (docs/wifi.md 47). It is also the first brick of a shutdown: the grants run in reverse, with power the last thing taken.

Amendment 2026-10-01 (later still): the paragraph two above overstates what was shown. It says six host-side resets "each left a chip whose ROM will not boot a new firmware" and that "only cutting its power is a power-on". Every one of those resets, and every warm power-up after them, ran with the Arm cores at their minimum clock - the Pi firmware drops them a minute after boot when no cpufreq sets one - and with the cores held at turbo (force_turbo=1, docs/wifi.md 55) every power cycle comes up cold. So the power cut is shown to WORK, not shown to be the only thing that would; whether the resets alone recover a fast host's chip is open (docs/wifi.md 56). The grant itself stands on its own: cutting a device's power is still the one recovery that cannot depend on the device's cooperation.

Amendment 2026-10-01 (CpuClock, syscall 55): the kernel sets the Arm clock to one of the firmware's two ends, and a SERVICE decides which. The Pi firmware owns the Arm clock and, with no OS asking it for a rate, drops the cores to their minimum a minute after boot and leaves them there. The CYW43455's firmware traps when it is uploaded that slowly (docs/wifi.md 55), so something has to be able to ask for speed. The only way to ask is the firmware mailbox, which the kernel already owns - the SD power, the GPIO expander and the radio's power cut all go through it - and a channel with one owner cannot be handed to a service as well.

What the kernel learns, and what it does not. CpuClock(max) sets the clock to the firmware's own GET_MIN_CLOCK_RATE or GET_MAX_CLOCK_RATE and returns what it reads back. The caller cannot name a rate. It is gated by CPU_CLOCK (resource 18), a privilege bit the supervisor may delegate and grants to ONE service, power, because the clock is one machine-wide setting and a second holder would silently overwrite the first. Who may be fast, for how long, and when to go back are power's: a LEASE of at most 30 s, the clock at its maximum while any is open and its minimum otherwise, and a lease nobody releases expiring on its own, so a holder that dies cannot pin the machine fast (docs/power.md 15, 26.10). Every port but the Pi 4 answers the seam with None and the syscall says so.

Why it is recorded. A new syscall, a new resource and a new privilege bit widen the surface Commandment I pins. This is mechanism on a channel the kernel already owns, not a seventh responsibility

• the same argument as DevicePower above - and the power service is where the policy, and any future power policy, lives.

Amendment 2026-10-01 (later): the result follows the pin's READ-BACK. DevicePower used to report success whenever the firmware accepted the SET_GPIO_STATE request, which it does whether or not the pin moved - and in QEMU, where the expander is not emulated, a cut that never happened was reported as done. It now returns success only when WL_ON reads back at the level asked for. The spawn also logs BT_ON, the same chip's Bluetooth enable: it reads 0 on this board, so WL_ON really is the whole of the radio's power and nothing else needs cutting (docs/wifi.md 53). No syscall, resource or authority changes.

Amendment 2026-10-03 (audio on the Pis): a grant may include routing the device's pins and starting its clock, and the Pis' DMA page is granted whole. The Pis' 3.5 mm jack is two PWM channels fed by the SoC's DMA engine (docs/audio.md, "The Pis"). Two of the steps that make it usable live in SHARED blocks: every pin's function in the GPIO page, every clock in the clock manager's. So the kernel does them as part of the grant, at spawn, exactly as it powers the SD domain before granting the radio's window - routes the jack's two pins to the PWM and starts the PWM clock at a fixed rate - and the driver (pwm-audio) is granted the PWM page and the DMA engine's page, mapped side by side, and a DMA arena. The device is a new kind (HwClass::AudioPwm), present where the arch says so (fixed_device_present, renamed from audio_pwm_present by the amendment below).

What this is not. No syscall, no privilege bit, no runtime role: the kernel acts once at spawn and holds no policy - the sample rate (the PWM's range), the volume and when to play are the driver's (26.10). Not a seventh responsibility: it is the grant made usable, the reasoning of the DevicePower amendment above.

What it costs, recorded rather than hidden (26.7). The DMA engine's page holds all fifteen channels and their shared status, so the driver is granted more than the one channel it uses. It is no more REACH than it already has - on these boards no IOMMU confines any DMA-capable driver (6.4), so a driver that can point one channel anywhere can already reach all of memory - but it is more than the grant names. The alternative, a kernel-mediated "start this channel" syscall, would grow the kernel to narrow a grant that confers nothing new, and was declined for that reason. The kernel also learns one more service name (pwm-audio, in the Pis' fixed-window table and the two restart lists), the existing name-keyed practice that step D's classes are replacing. [Superseded the same day by the amendment below: the kernel learns no service name for audio, or for any other driver.]

Amendment 2026-10-03 (later): the kernel knows ONE service by name, the supervisor, and nothing it grants or reports is keyed on a name any more. The amendment above recorded the kernel learning pwm-audio as "the existing practice". The operator asked whether that was normal, and it was not: it was debt, and docs/service-ownership.md had already said why it cannot be enforced - once the supervisor supplies the images, any image started under a matching name inherits whatever a name-keyed table grants that name. Six decisions moved off the name:

• Fixed device windows (the Pis' SoC blocks) are granted by the device KIND the spawn request names (arch::imp::map_fixed_device(pt, kind), fixed_device_present(kind)), the same trust as a PCI class code. The Pi 4 radio gained the kind it lacked, WIFI_SDIO.
• DevicePower reaches the pin of the kind the caller was GRANTED, not of the name it has.
• Death notification and the restart count follow SPAWN_FLAG_WATCHED, set by the supervisor from its MANAGED roster. The kernel's two lists of nineteen names are gone, and with them the drift that once left time and control uncounted; V-managed-watched checks the chain that replaced them.
• The display is reclaimed from, and console output delivered to, the task granted the FRAMEBUFFER kind, not whatever is called console.
• Two grants were removed because nothing used them: the Pi 2 block-driver's EMMC window (its disk is USB; the EMMC is the boot card) and a name-matched console_push mint that matched nothing.

No responsibility moves and no authority widens: every change narrows who a grant reaches, from "anything with this name" to "the request that names this device". One spawn flag is added to a request the kernel already validates. The name the kernel still knows is supervisor, because the kernel spawns and respawns it (6.2). docs/audio.md, "No service names in the kernel".

Amendment 2026-10-14 (PowerOff, syscall 56): the kernel turns the machine off, now or at the ONE deadline it holds, and the OPERATOR decides when. reboot resets the machine through a channel the kernel owns on every port; turning it off uses the same channels - the Pis' power-management watchdog with the boot partition set to 63 (halt) instead of cleared, the RISC-V firmware's SRST call with the shutdown type instead of a reboot, and on x86 ACPI soft-off (S5), read from the FADT and the DSDT's \_S5 package in the tables the kernel already walks for the IOMMU. Each port answers one new seam member, power_off, which returns only when the hardware did not turn off, with the reason; then every core halts through halt_all_cores and the last line says it is safe to switch off. A halt asked for is not a crash and is not printed as one.

The deadline, and why the kernel holds it. PowerOff turns the machine off now, or sets the machine's one pending power-off up to 24 h ahead, or cancels it. The kernel holds that deadline on the scheduler's existing tick and fires it whether or not any service is alive, because a shutdown must not be lost with the services that asked for it or count it down (the operator ruled a lost shutdown unacceptable, docs/shutdown.md 4.4). It is the kernel's own scheduled action, not service state (15): no service's data is kept, nothing is keyed by name, and a reboot clears it. Earliest wins - a holder may bring a shutdown forward, never push one back - any holder may cancel, every change is logged with the caller, and the time is monotonic, never the wall clock.

Who holds it. POWER_OFF (resource 19) is a privilege bit the supervisor may delegate, granted to the SHELL alone, beside REBOOT: ending the session is the operator's, and no service has a reason to end it - a failing service is restarted, never the machine. power holds no shutdown authority; it reads the deadline, warns and does a bounded tidy-up three seconds before it. The Commandments baseline lists the shell as the one holder, so a second (a power button) is a recorded decision. A holder acts only on its own inputs and never offers shutdown-on-request to other services, which would reopen an anonymous path one level up; the keyboard residual of SEC-2 (6.4) applies, since anything that can type can type shutdown.

Visible, deliberately. InspectKernel query 28 (the seconds left, or -1) is UNGATED, deliberately, because a deadline that outlives every service must be seen by everything that might report it, and a shutdown planted by a compromised holder must never be hidden. It discloses no task's state and confers no authority.

What it does not do, recorded rather than hidden (26.7). ACPI asks the OS to run the firmware's \_PTS method before S5, which is bytecode this kernel does not interpret; a machine that gates S5 on it - the HP T630 - halts instead of powering off, and says so. The Pi 2 cannot cut its own 5 V and halts; the Pi 4's firmware cuts its rails only where its EEPROM sets POWER_OFF_ON_HALT=1; the VisionFive's firmware cannot reach its power chip and stops inside the call, so the kernel says what to do before making it. Hardware-verified on all five boards, 2026-10-14: the Wyse powers off and the rest halt, each saying which (docs/shutdown.md 5).

Why it is recorded. A new syscall with three operations, a query, a resource and a seam member widen the surface Commandment I pins. It is mechanism on channels the kernel already owns - reboot's sibling, and one more timed action - not a seventh responsibility, the argument the DevicePower and CpuClock amendments above make. MISCIS is unchanged.

Amendment 2026-10-15 (reboot on the deadline, S6): the one deadline also holds a REBOOT. The operator asked that reboot take shutdown's forms - reboot counting down from 3, reboot now, reboot 10m. A delayed reboot has exactly the problem a delayed shutdown had: held in a service, it dies with the service. So it rides the same deadline. PowerOff gains two ops, 3 (reboot in secs) and 4 (cancel it), gated by REBOOT rather than POWER_OFF - the right that already resets the machine, held by the shell alone (SEC-2) - and the deadline is one word holding the tick and which of the two falls due, so a set, a cancel and the tick each see both together. A reboot that falls due resets through hardware_reset, the path Reboot (18) already takes.

There is still ONE deadline, and it holds one action. While a shutdown is pending a reboot is refused, and the other way round, so neither can quietly replace the other and a shutdown can never be lost to a reboot that happened to be asked for sooner. Earliest wins within a kind, as before. Query 28 now answers secs * 2 + kind (1 for a reboot), still ungated, so what is pending and when are one answer that cannot disagree with itself.

What it does not add. No syscall, no resource, no privilege bit, no seam member: two ops on a syscall this section already records, gated by a right the shell already holds, firing a reset the kernel already performs on its existing tick. Not a seventh responsibility, for the reason the amendment above gives; MISCIS is unchanged. What grows is surface - two ops and a query's encoding - recorded here because Commandment I pins surface and the gate counts syscalls and queries, not ops, so it would not have refused this. reboot now and Ctrl+Alt+Del stay the immediate Reboot (18). QEMU-verified 2026-10-15 (osdev test shutdown, a reboot falling due and the machine back at a prompt); hardware-verified on all five boards the same day. The Pi 4's first card cut its last line on reset; the UART wait that fixed it is in arch/, and the Pi 2 and the Pi 4's re-card show the lines whole.

13. Service Contracts

13.1 Format

name    = "ping"
version = "0.1.0"

[resources.memory]
request = "32MiB"
limit   = "64MiB"

[capabilities]
ipc_send    = ["pong"]
ipc_receive = ["ping"]
log_write   = true

[placement]
core = 0    # optional; if omitted, supervisor uses round-robin

13.2 Placement Field (Strict)

• Omitted → supervisor places via round-robin across available cores.
• Specified → supervisor requires that exact core. If unavailable, spawn is rejected with PlacementInvalid.

Strict semantics: A contract that names a core is a deployment-intent statement. The supervisor will not silently reroute to a different core. If placement.core = 2 and core 2 didn't come up, the service does not start; the supervisor logs the rejection and continues. Contract authors should specify placement only when they have a real reason.

13.3 Request, Not Permission

The developer declares what the service needs. The OS decides whether to grant it.

13.4 Build-Time Validation

osdev validates contracts using JSON Schema applied to the TOML structure.

Guarantees: correct structure, valid capability names, valid resource declarations, valid core IDs (range check only), required fields present.

Non-guarantees: behavioral correctness, that the binary uses only declared caps, that limits are reasonable, that the requested core will be available at spawn time.

Build-time validation is structural, not behavioral. Behavioral enforcement is runtime-only in v1.

13.5 Schema

contracts/schema/service.schema.json. Versioned. Breaking changes require a major version bump and a documented migration.

13.6 Runtime Enforcement

Every syscall checks the calling task's capability table, populated at spawn time from the spawn request. The kernel does not consult the contract at runtime, and never has.

Amendment 2026-09-14: the capability table is populated from the SPAWN REQUEST, not from the contract, and this section said otherwise for long enough that it led a contributor into a change that compiles, validates, passes every checker, and does nothing.

What actually grants authority. The supervisor holds each service's image and sends the kernel a spawn request carrying its privilege word, send peers, memory limit, core and device class; the kernel mints exactly that, after refusing any privilege the supervisor does not itself hold (SUPERVISOR_DELEGATABLE, privileges_caller_lacks) - which is what keeps delegation from being ambient authority (§3.1). The kernel's own service_config table covers its ONE direct spawn, the supervisor (§11.1). Those two are the whole of it.

The kernel cannot read a contract. It is no_std and cannot parse TOML at spawn. That is not a new fact and not an implementation shortcut - scripts/contract_check.py has opened with it since it was written, and that script exists PRECISELY because the .toml is a second, human-facing declaration that can drift from the first.

So what is a contract? A build-time declaration: schema-validated by osdev validate (§13.4), and reconciled against what is really granted by contract_check.py (memory limit, placement, send peers) and by IV-contract-authority in scripts/commandments.py (the authority capabilities). It is the reviewable statement of what a service may do (§26.9). It is not the mechanism.

Why this was worth amending rather than leaving as a near-enough shorthand. A weak model was given "let recorder restart a service it sees stop responding", with no mention of any checker. It added service_control = true to recorder's contract and reported that the kernel would grant it at spawn - which is what this section and §14.1 both told it. The change compiled, osdev validate passed it, and all twelve checkers stayed silent. It does not work: recorder's privilege word is 0, every call is denied, and the denial is discarded twice (the SDK's restart swallows its own kill error and the caller wrote let _ = ...) while the log line printed BEFORE the call asserts a restart that never happened. A service that looks authorised on paper, cannot act, and says it did.

And it had been caught before. audits/userspace-audit.md flagged exactly this in 2026-07-12 - quoting this section's own words back at it, that "the contract stops being the authority's source of truth" - and marked it RESOLVED. The resolution changed the CODE and left the constitution saying the wrong thing, which is how a corrected defect goes on causing the error it was corrected for. Four other documents repeated the claim and are fixed in the same change.

That is this document leading someone into a silent failure, which is invariant 12 broken at the documentation layer rather than the kernel one. The gate that now catches it is IV-contract-authority; this amendment removes the reason it would be needed a second time.

14. Service Lifecycle

14.1 Spawn

1. Supervisor takes the service's image and its row in the spawn table (the contract was validated at BUILD time, §13.4 - nothing parses TOML here).
2. Determines core placement (round-robin or contract override per §9.2; rejected if contracted core unavailable).
3. Asks the kernel to create a new task on that core, in a spawn request carrying the privilege word, send peers, memory limit and device class.
4. Kernel refuses any privilege the supervisor does not itself hold (SUPERVISOR_DELEGATABLE), so a spawner passes on what it has and never mints.
5. Kernel mints capabilities per the spawn request (each tagged with current resource generation).
6. Kernel maps service binary into new address space.
7. Service registers any owned endpoints in the kernel name directory (ipc::names).
8. Service enters main loop on its assigned core.

  Supervisor ─── spawn(name, request) ───▶  Kernel
                                               │
                              resolve placement (§9.2):
                              contract core or round-robin
                                               │
                        Err(PlacementInvalid) ◀─┤  (core unavailable: stop here)
                                               │
                              allocate Task + CapTable from the request
                              map binary into new address space
                              enqueue task on target core run queue
                                               │
  Supervisor ◀── Ok(task_id) ────────────────┘
                                               │
  New Service:                      enters execution
    ── registers endpoint in the kernel name directory
    ── service_main() ── enters work loop

Amendment 2026-09-26 (step C): step 1 above is only true because the kernel now accepts an IMAGE from userspace, and that widening was never recorded here. When the supervisor took ownership of every service image (docs/service-ownership.md, step C), the kernel stopped holding the bytes it spawns. Its catalogue is supervisor alone. So a spawner can no longer ask for "the image you already have" - it must SUPPLY one, and SpawnImage (syscall 52) is the syscall that accepts it.

Starting arbitrary bytes is a different authority from starting a known service, and it is now a different capability. SPAWN and image-spawn were the same right until step C, which meant every SPAWN holder - the shell, chaos, control, every probe - could introduce NEW CODE under a real service's name in the window while that service was dead, and a client reacquiring that name (§14.3) would wire itself to it. SpawnImage therefore requires IMAGE_SPAWN on top of SPAWN, and the kernel refuses the call when a caller holds only the latter.

IMAGE_SPAWN is deliberately NOT delegatable. It is absent from SUPERVISOR_DELEGATABLE, so the supervisor cannot pass it on even to a service it trusts - a delegatable version would re-open the hole one grant later. The only two callers in the tree are the supervisor's own spawn_by_image and spawn_probe_row; everything else asks the supervisor over IPC. It stops the authority leaking to the dozen services that merely wanted to start something.

What the supervisor GAINED, said plainly, because this is a real widening and not a re-labelling. Before step C the kernel held every image, so a runtime-compromised supervisor could start only code the kernel already carried - it could start the wrong service, or the right one too often, but it could not introduce code that was not in the image. After step C it can. A compromised supervisor supplies the bytes, so it can run anything under any name, and nothing before step 2 prevents that - step 2 (a signature over each image, docs/service-ownership.md) exists precisely to close it. This does not move the TCB: the supervisor is the trusted root (§6.1) and its compromise was always systemic. It does mean the CONSEQUENCE of that compromise is strictly larger than it was, and per §26.7 a limitation that cannot be closed today is recorded rather than left for a reader to discover. The IRQ-routing half of the same concern IS closed: the kernel refuses raw vectors and raw MMIO outright, as the paragraph below describes.

What the kernel refuses, so that "supplies an image" is not "supplies a machine". The request is a fixed, versioned struct, and the kernel rejects a wrong version, a wrong size, an unreadable buffer, a name outside 1..=64 bytes, a dma_pages over its cap, an unknown device class, a BDF on a non-PCI class, any privilege the caller does not hold itself (privileges_caller_lacks), and - the two that matter most - raw MMIO addresses and raw interrupt vectors. A driver names a device CLASS and the kernel resolves the window, the arena, the BDF and the vector against its own bus scan (§12.3). A caller cannot hand the kernel an address and be given it.

Why this is recorded rather than merely implemented. It is a new kernel authority and a widened syscall surface, which Commandment I pins and §26.9 requires be traceable to the capability that granted it. The code says all of this at kernel/src/capability/mod.rs; the constitution said none of it, and docs/service-ownership.md has carried "the CLAUDE.md amendment for step C must state the widening" as an open item since. No invariant moves: authority is still explicit (§3.3) and the kernel still holds no policy - it validates a request and mints exactly what the request asks for and the spawner may give (§13.6, §26.10). The net effect on authority points BOTH ways and it is worth being exact about which: narrower for the dozen SPAWN holders, who lost the ability to introduce code at all, and wider for the supervisor alone, as the paragraph above records.

Amendment 2026-10-17 (install): the supervisor starts an image READ FROM THE DISK, for an installed package, and only after checking its signature. Step 1 above holds for every built-in service; an installed package (godspeed install, utilities/61_godspeed.md 4b) is the one exception, and it is the step-2 shape the amendment above names. The supervisor reads a fetched package from /system/packages/, checks it with the code godspeed verify runs - the publisher's signature over its manifest, the signing key's standing in this machine's trust record, the contract and this machine's binary against the manifest's digests - and hands the kernel the very bytes it hashed, through SpawnImage as for any other image (services/supervisor/src/installed.rs). It does so at install, at every boot and at every restart, with nothing cached between.

What an installed package is given, and why it is safe to give: no privilege at all - none is asked for and none can be granted - and send peers only where its signed contract requests them AND the operator approved them, never supervisor. It runs under its package name, publisher/name, which no built-in service can hold, so it can never stand in for one when a client reacquires a name (14.3). Restarts are bounded: five a boot, then it is left down, loudly.

What is NOT closed, recorded rather than hidden (26.7). The signature is checked against the trust record and the grant read from the package's folder, and both are on /system, which every fs holder can write: something that can write there can replace the trust record or widen a grant, up to what the signed contract requests. The narrowing to the contract is what keeps a forged grant from reaching further. IMAGE_SPAWN stays the supervisor's alone and undelegated; godspeed-pm asks over IPC (supcmd::INSTALL). No kernel change, no new syscall, and no responsibility added: the supervisor already starts images and already decides with what.

Amendment 2026-10-17, later (apps): one thing beyond peers, the console, for an app and only with the operator's answer. An installed package of kind app is a utility that owns the screen and the keyboard while it runs (gs::app, docs/developer-services-design.md 13.2, approved by the operator the same day). The supervisor starts it with SPAWN_FLAG_REQ_CONSOLE - the console read capability chaos and the shell already hold - when its grant names console, which godspeed install asks about by name, and refuses to start an app whose grant does not. Still no privilege bit: the console is a spawn flag, and a service or a utility is never given it. The residual is SEC-2's (6.4): a holder of the keyboard can read what is typed while it runs, which is exactly what the operator was asked to approve. The kernel gives the console back when the app dies, so a crash cannot keep it.

Amendment 2026-10-23 (drivers): an installed driver is given ONE DEVICE, by what the bus says it is, and the authority that device carries - which on a machine with no IOMMU puts it inside the TCB (6.4). Not recorded when the first part shipped: v0.29.0 gave a driver package its device's register window and nothing else, v0.30.0 the same, and this section said nothing of it. What a driver package is given now (docs/developer-services-design.md 13.1, services/supervisor/src/installed.rs), each named in its signed contract and approved by the operator:

• A PCI device, by class (hw_pci_class): the kernel resolves which device from its own bus scan, exactly as for an in-tree driver named by class (12.3), and grants its register window - plus its interrupt when the contract asks (hw_pci_irq; the kernel allocates the vector, the caller names none) and a DMA arena of the size it asks (hw_dma, at most 2 MiB, never an address). Confinement is requested; whether it happens is the kernel's, per device (6.4).
• A device an in-tree driver drives is TAKEN OVER, not shared: the supervisor stops that driver and keeps it stopped while the package is installed, and starts it again when the package is uninstalled, ends, or is left down. One holder per device, which the kernel does not enforce for a PCI device and the supervisor does.
• A USB device, by vendor and product (hw_usb): no hardware authority of its own at all. Its host (xhci, dwc2, and ehci since the same day) binds it and serves its transfers to the one driver given that host as a send peer (gs::driver::bus), so the package is the host's client, as wifi-usb always was.

The TCB consequence, stated as 6.4 requires. A driver package granted a DMA arena on a machine whose IOMMU does not confine its device - every Pi, the VisionFive, and any x86 device the kernel leaves in passthrough - can point the device at any address: kernel-equivalent reach, so it is trust-critical by necessity, exactly as an unconfined in-tree driver is. That is why the arena is approved by a SECOND question at install, and why the question is asked on every machine: nothing a service can ask says whether the kernel will confine this device, so the warning is given rather than guessed (a confined machine asks needlessly; recorded, 26.7). A driver package with registers only, or a USB driver, carries no such reach.

What does not change: no privilege bit (the device is a hardware class in the spawn request, and the supervisor already spawns by class), no kernel change and no new syscall, and IMAGE_SPAWN stays the supervisor's alone. MISCIS is unchanged.

14.2 Restart and Cap Rebinding (Possibly Cross-Core)

  Steady state: Service A (Core 0) holds cap to Service B gen=4 (Core 1)

  Step 1 - Supervisor kills B:
    Kernel closes B's endpoints, drains queues
    Kernel bumps B's generation: 4 → 5
    Kernel reclaims B's memory (TLB shootdown on all cores)

  Step 2 - A tries to send via stale cap:
    A ── send(gen=4 cap) ──▶ Kernel ── EndpointDead ──▶ A
                              (gen mismatch: held=4, current=5)

  Step 3 - Supervisor spawns B on Core 2:
    Kernel starts B with fresh cap table (gen=5)
    B re-registers its endpoint in the kernel name directory

  Step 4 - A reacquires:
    A ── AcquireSendCap("B") ──▶ fresh cap (gen=5, Core 2)   [kernel name directory]
    A ── send(gen=5 cap) ──▶ Ok  (routes to Core 2)

Key principle: the new instance may run on a different core than the old one. Clients never know - they see only EndpointDead, reacquire by name through the kernel directory, and resume.

14.3 Cascading Failure

Cascading failure is the client's responsibility. There is no implicit recovery. If A depends on B and B restarts, A's next syscall returns CapRevoked or EndpointDead, and A must retry, degrade, or fail.

Reacquiring the endpoint is necessary but not sufficient. A fresh cap to B's new instance does not refresh anything A obtained from B's previous incarnation. Every secondary thing A still holds that was derived from the dead instance - a socket or connection id, a resource or open-file cap, a generation number, or a cached copy of B's state - is stale: the new B never issued it and does not know it. A must discard or re-establish each of these against the new instance. In particular, A must not keep serving a cached view of B's state as authoritative once B has restarted: that view is a derived copy of B's truth (§26.4, Commandment III), and that truth was just replaced. Reacquire the endpoint, and re-derive everything that hung off the old one.

14.4 Supervisor API

#![allow(unused)]
fn main() {
supervisor.kill(service_name) -> Result<()>
supervisor.restart(service_name, placement_override?: CoreId) -> Result<()>
}

Required capability: service_control (held only by supervisor).

• kill - immediate. The killed service does not get a chance to clean up. Clean shutdown is a separate codepath.
• restart - kill followed by spawn. Placement is determined as follows:
  • If placement_override is provided, the supervisor requires that core (subject to the strict rules of §9.2; rejected if the core is unavailable).
  • If placement_override is omitted, the placement decision is re-evaluated from scratch per §9.2 - contract-specified placement re-applies (and may fail with PlacementInvalid if unavailable); unspecified placement gets a fresh round-robin choice.
  • The previous core is not remembered. A service that ran on core 1 before the restart has no implicit affinity for core 1 after.

14.5 Kill Semantics

Kill is for misbehaving services and for restart. It is not a graceful shutdown mechanism.

Amendment 2026-10-17 (Exit, syscall 57): a program may END ITSELF, with a status, and the death notice says so. Until now nothing ended a task but the kill syscall or a fault, so every program was a service that never returns, and a program that does one job - a utility - could not exist outside the shell (docs/stdlib-design.md 1, option B, chosen by the operator). Exit(status) ends the caller by the path a task that kills itself already takes (handle_kill's tail), with a third cause: the notice carries E and the status, beside K (killed by) and F (a fault) (6.2 amendment 2026-10-11).

It takes no capability, and that is deliberate, not an oversight against 21. The rule there - a syscall that does not validate a capability is rejected - exists so that no syscall reaches authority without one. Exit reaches nothing: the one task it can end is the caller, as Yield and Park act on the caller and take none. A program could already end itself by faulting; this makes the same end deliberate and says how.

What the kernel learns, and what it does not. A number, said in the notice. What an exit MEANS is the supervisor's (26.10): an installed package that ends itself is not restarted, because it finished; a service in MANAGED that exits is restarted as any death is, because it is meant to run. The kernel keeps no record. No responsibility is added: ending a task is the scheduler's already (4.3). Pinned in COMMANDMENTS.baseline.toml; one more SDK call site (18.5, exit).

15. State and Persistence

State belongs to services, not the kernel. Services that need to survive restart must persist externally and reconstruct on startup.

The filesystem service is the externalization mechanism for everyone else and cannot persist to itself. Resolution: the block driver holds a direct hardware capability and stores fs metadata. fs gives itself transactional metadata recovery - every mutation commits through a crash-consistent redo-journal and fs recovers to a consistent state on mount (docs/persistence.md §6.8). With that, block-driver and fs are restartable and no longer in the TCB (§6.1 Phase D amendment, 2026-06-17); their death is a supervisor restart, not a reboot. The recovery guarantee is backend-conditional - see the 2026-07-25 amendment in §6.1.

Stateless services (events in v1) restart trivially. Example application services (ping, pong) are also stateless and restart trivially - but they are demonstration services in examples/, not permanent architectural components.

16. Update Model

  Update package
    │
    ├── Signature valid?   No  ──▶  Reject
    │       Yes ↓
    ├── Contract valid?    No  ──▶  Reject
    │       Yes ↓
    └── Policy allows?     No  ──▶  Reject
            Yes ↓
    Supervisor restarts service with new binary

Push vs pull is irrelevant - verification is the security property. Live code update is permanently rejected (§2.5); the only update mechanism is restart-with-new-binary.

17. Developer Workflow

osdev build                         # build kernel + services
osdev run --smp <N>                 # boot in QEMU with N cores
osdev image                         # build bare-metal image → build/os-usb.img (UEFI GPT)
osdev restart <service> [--core N]  # restart in running OS; --core is dev-mode only
osdev logs <service>                # tail logs
osdev test identity                 # run §22 test suite
osdev validate                      # validate every service contract
osdev mkfs / script-disk            # build a filesystem image / a script disk

# NOT IMPLEMENTED - these are `todo!()` stubs that panic if invoked:
#   osdev new <service-name>        # scaffold        (copy examples/00-hello instead)
#   osdev publish                   # package + serve
#   osdev status <service>          # state + core     (use the shell's `status`)
#   osdev caps <service>            # held caps        (use the shell's `caps`)

osdev restart --core N is the CLI surface for the supervisor's placement_override (§14.4). It is rejected outside dev mode and subject to the same strict placement rules as a contract-specified core.

Iteration loop: edit → build → restart → logs. Only the changed service restarts. (publish is in the not-implemented list above, so the loop does not pass through it; §26.2's "not implemented; will be implemented when a test requires it" is the honest state of all four.)

18. Unsafe Policy

18.1 Permitted

kernel/src/arch/, kernel/src/memory/, kernel/src/capability/, kernel/src/smp/.

Plus the SDK's audited hardware/ABI layer: the syscall ABI (raw_syscall, inline asm!) and the MMIO/DMA accessor modules (sdk/rust/src/mmio.rs and sdk/rust/src/dma.rs). Userspace drivers (§12) cannot touch device registers or DMA memory without unsafe; isolating it to these designated SDK modules - each block carrying a // SAFETY: comment - keeps the driver services themselves unsafe-free behind safe wrappers (Mmio::read32, Dma::write32, etc.), exactly as the kernel isolates its unsafe to the four layers above. This is a recognition of what the syscall ABI already required, extended to the hardware access §12 needs.

Amendment 2026-10-17 (install): the SDK's memory.rs is a fourth permitted module, for a task's OWN memory. AllocMem (syscall 6) returns an address, and an address becomes something a service can read and write only through unsafe. Until now nothing outside the tests needed that - every working set fit a stack (26.6.1) - and the one case that did, P7's stamped pages, lives in adversarial.rs. The install loader is the first production case: the supervisor reads a package's image from fs, checks its digest and signature, and hands the kernel those same bytes, and an image is larger than any stack. Region is two blocks (bytes, bytes_mut) over exactly the pages a successful AllocMem mapped, and the supervisor stays unsafe-free behind it, as a driver does behind Mmio.

What it is not: an allocator. There is no free - the kernel reclaims a task's memory at its death (10.5) - so a region is asked for once, its size is the bound, and it is reused. No syscall and no kernel change; the rule that new unsafe lives in a permitted layer (18.5) is met by naming this one.

Plus the SDK's audited adversarial test module (sdk/rust/src/adversarial.rs). The §22 red-team / fuzz / chaos suite must reach the raw ABI with fuzzed syscall numbers and arguments, and must execute deliberate ring-3 faults (a null read, a non-canonical read, a divide-by-zero) to prove the kernel kills the faulting task rather than wedging the machine (invariant 12; A14 / A15 / C2) - things no safe wrapper can otherwise express. Isolating that unsafe to this one designated, SAFETY-commented module (fuzz_syscall, fault_null_read, fault_noncanonical_read, fault_divide_by_zero) keeps the test services themselves (probe) unsafe-free, exactly as the hardware/ABI layer keeps the driver services unsafe-free. This is a recognition of what adversarial testing already required: probe used to hold this unsafe directly - an untracked §18.2 violation the userspace audit (M8) closed. The module is test-only; no production service calls it (a fault primitive just kills the caller, which the kernel handles). scripts/unsafe_check.py now scans services/ and fails on any service unsafe, mechanically enforcing the isolation.

18.2 Forbidden

All userspace services, osdev/, and all of sdk/ except the audited hardware/ABI layer named in §18.1 - and all kernel code outside the four permitted layers. A driver service that writes unsafe directly (rather than going through the SDK's safe Mmio/Dma wrappers) is rejected.

Amendment 2026-09-13: this is enforced by the COMPILER now, not only by a grep. Every crate under services/, examples/ and osdev/ carries #![deny(unsafe_code)], so rustc refuses the crate rather than a script noticing afterwards. That closes what a text scan cannot see - unsafe produced by a macro expansion, or spelled across lines - and it fails at the author's keyboard instead of at the next CI run.

deny rather than forbid, for exactly one reason, stated so nobody "tightens" it and breaks the build: a #[no_mangle] declaration is itself covered by the unsafe_code lint (an exported symbol can collide, which is a soundness hole), and every service needs #[no_mangle] service_main because build.rs links with --entry=service_main. forbid cannot be relaxed even for that. So the crates carry deny plus ONE #[allow(unsafe_code)] on the entry symbol, and scripts/unsafe_check.py asserts both halves: that the attribute is present, and that the only #[allow] sits on #[no_mangle]. An #[allow] anywhere else fails the check - the exception cannot become a door.

No policy changes here. §18.2 already forbade this; what changed is who enforces it.

18.3 Documentation

Every unsafe block carries a SAFETY comment:

#![allow(unused)]
fn main() {
// SAFETY: <argument for why this is sound>
unsafe { ... }
}

A PR with an unsafe block lacking a SAFETY comment is rejected without review.

18.4 Audit Trail

audits/unsafe-audit.md lists every unsafe block. CI checks the file matches source.

18.5 Grandfathered Floors

unsafe outside the four permitted layers (§18.1) is tolerated only as grandfathered lines in task/, syscall/, interrupt/, loader.rs and main.rs, and in the two SDK files named below, frozen at the counts in audits/unsafe-audit.md. Those counts may decrease freely but may increase only by an amendment recorded here and in the audit, with a written safety + necessity rationale.

Amendment 2026-09-12: the SDK's service_context.rs (82) and ipc.rs (8) are recorded as grandfathered floors, and this list gains loader.rs and main.rs, which it had always omitted. Neither is new unsafe - both are the state of the tree being written down for the first time. scripts/unsafe_check.py scanned only kernel/src/ and services/, so the SDK's ~125 unsafe lines were audited by nothing at all while §18.4 claimed CI checks the audit against source (backlog/fixed/18). The scan now covers sdk/, which is what makes these floors enforceable rather than merely stated.

They are one design consequence, not 90 violations. 86 of the 90 are unsafe { raw_syscall(..) } call sites: raw_syscall is an unsafe fn because it issues the trap instruction, so every caller opens a block - and these two files ARE the wrapper layer §18.1 describes, the one that exists so that driver and application services need no unsafe of their own. That worked: services/ is at ZERO, mechanically enforced. The isolation stopped one layer short of itself.

The fix that would actually close this is a SAFE raw_syscall wrapper - the kernel validates every user pointer, so passing integers to a validating callee is sound - which collapses ~86 of them and leaves the SDK at roughly the 35 lines §18.1 sanctions. That is an SDK redesign on every service's call path, so per §26.7 it is recorded here as the known route rather than half-done. Until then the floors may only fall.

New unsafe that a feature or hardening needs must first try to live in a permitted layer (arch/, memory/, capability/, smp/) rather than grow a grandfathered file. A precondition that is merely boot-ordering (violating it wedges boot - a liveness bug, not UB) does not justify an unsafe fn; make it a safe fn with a documented contract, like memory::init / smp::init. Worked example: the H4 kstack-guard / W^X hardening (2026-06-08) was structured so its page-table unsafe lives in arch/ and the boot call sites are safe fns - main.rs and task/mod.rs stayed at their floors with no amendment needed. Four amendments to the grandfathered floors stand; the service_context.rs floor fell to 83 after the first two (2026-10-04, a dead call site removed) and the boot record took it back to 84; it fell to 80 on 2026-10-10, when the four spawn-by-name syscalls (7, 19, 38, 39) were retired with their SDK wrappers (backlog/fixed/80 K14), and to 77 on 2026-10-11, when the three uncalled NET_DEVICE wrappers went (backlog/21); it rose to 79 on 2026-10-14 and to 80 on 2026-10-17 by the amendments below. A fall needs no amendment, so this line only keeps the figure current (audits/unsafe-audit.md):

Amendment 2026-10-17 (Exit): sdk/rust/src/service_context.rs 79 -> 80. One call site, exit: one unsafe { raw_syscall(57, ..) } behind the safe ServiceContext::exit and gs::program::exit, for the 14.5 amendment of the same date. Necessity: a program cannot reach a syscall any other way. Safety: one integer and no pointer, and the syscall does not return.

Amendment 2026-10-14 (PowerOff): sdk/rust/src/service_context.rs 77 -> 79. Two call sites behind the §12.3 amendment of the same date: power_off_call, one unsafe { raw_syscall(56, ..) } behind the three safe wrappers power_off, power_off_in and power_off_cancel; and power_off_pending, one unsafe { raw_syscall(13, 28, ..) }. The same single design consequence as the CpuClock amendment below. Necessity: a service cannot reach a syscall any other way. Safety: integers only, and the kernel checks the capability before acting; query 28 takes no pointer.

Amendment 2026-10-08 (the boot record): sdk/rust/src/service_context.rs 83 -> 84. One more unsafe { raw_syscall(13, 27, ..) } call site, boot_record_query, behind the safe boot_record_size and boot_record_read of the 11.4 amendment of the same date - one block for both, the same single design consequence as the two below. Necessity: a service cannot reach a syscall any other way. Safety: the read's buffer is typed at the kernel's chunk size, and the kernel validates the range before writing into it.

Amendment 2026-10-01 (CpuClock): sdk/rust/src/service_context.rs 83 -> 84. One more unsafe { raw_syscall(55, ..) } call site, the wrapper cpu_clock behind the §12.3 amendment of the same date - the same single design consequence as the DevicePower amendment below. Necessity: a service cannot reach a syscall any other way. Safety: one integer to a kernel that checks the capability before asking the firmware anything.

Amendment 2026-10-01 (DevicePower): sdk/rust/src/service_context.rs 82 -> 83. One more unsafe { raw_syscall(54, ..) } call site, the wrapper device_power behind the §12.3 amendment of the same date. It is the same single design consequence the 2026-09-12 amendment describes - the SDK IS the wrapper layer, so a new syscall is one more block here and zero in any service - and the safe raw_syscall that would collapse all of them remains the recorded route. Necessity: a service cannot reach a syscall any other way. Safety: the kernel validates the capability before touching any pin, and the call passes two integers.

19. Debugging Model

Bugs are classified as one of: kernel, arch, memory, ipc, capability, smp, service, cli.

Bug reports include: logs (kernel ring buffer + service), contract(s), QEMU repro steps including -smp N value, expected behavior, actual behavior, suspected classification.

Kernel panics print the reason (KERNEL PANIC: {info}) to the serial console and the kernel log ring buffer. Panics on any core halt the system: the panic path broadcasts an NMI so every core halts, not only the panicking one (§6.2). A reserved-page mechanism to persist the panic reason across reboot was once described here but was never implemented (and init, which would have re-read it, is removed - Phase 5); the panic reason lives on the serial console only.

20. Performance Philosophy

Ranked: correctness, observability, performance.

The IPC fast path is the exception. In a microkernel, every meaningful operation crosses an IPC boundary. v1 IPC uses simple predictable structures: one memcpy, constant-time cap + generation check, one IPI on cross-core wake.

No vibes-based optimization. Perf claims require benchmarks in tests/qemu/perf/.

21. Contribution Rules

A PR is rejected without further review if it:

• Introduces global mutable state outside a single owning service.
• Introduces ambient authority.
• Bypasses the capability system or generation check.
• Adds service migration or work stealing.
• Adds zero-copy IPC.
• Adds live code update.
• Introduces silent fallbacks at the kernel boundary.
• Breaks restartability of a non-TCB service.
• Adds unsafe code without a SAFETY comment, or outside permitted layers.
• Adds a syscall that does not validate a capability.
• Changes the IPC fast path without a benchmark.
• Edits CLAUDE.md without a rationale in the commit message.
• Introduces an em-dash (U+2014) or en-dash (U+2013) anywhere - in prose, code, comments, string literals, commit messages, or docs. Only the plain ASCII hyphen (-) is permitted as a dash; box-drawing characters are fine. This is a house writing convention, enforced repo-wide for consistency.
• Weakens a gate rather than the rule it enforces. Deleting a checker or removing one from EXTRA_CHECKS, widening a path exemption, adding a baseline entry instead of fixing what it found, using a conform-ok marker to go quiet rather than to record an exception, or making a diagnostic vaguer (22.7). The enforcement layer is open to contribution like everything else and a rule may be repealed - by amending this document with a written rationale, so that the law and the gate change together. What is rejected is the version where the law still says one thing and the gate has stopped noticing. CONTRIBUTING.md carries the long form.

Reviewers ask: does this respect the constitution, leave the kernel small, present a convincing unsafe argument, include a test, make the system more or less understandable?

A grounded catalog of these violations - each paired with the correct pattern and the section it breaks - is docs/anti-patterns.md, the field guide to constitutional violations. Scan the categories your change touches before opening a PR.

22. Identity Test Suite

22.1 Purpose

The identity tests are the minimum set of tests that, if any one fails, the system is no longer the system this document describes.

They are the executable form of the constitution. If you change the spec in a way that invalidates one of these tests, you have changed system identity. That requires a CLAUDE.md amendment.

22.2 Categorization

The test suite is layered. Each layer answers a different question about kernel correctness. A pass on one layer is necessary but not sufficient. Battle-hardening requires passing all layers.

  ┌─────────────────────────────────────────────────────────────────────┐
  │  Foundation - must pass before anything else                        │
  │  Identity (§22) - Tests 1-15 ✅ - Constitutional invariants        │
  └──────────────────────┬──────────────────────────────────────────────┘
          ┌──────────────┴─────────────────┐
          ▼                                ▼
  ┌───────────────────┐          ┌───────────────────┐
  │  Property         │          │  Fuzz             │
  │  Universal invs.  │          │  Crash resistance │
  │  under random     │          │  on adversarial   │
  │  inputs           │          │  inputs           │
  └───────┬───────────┘          └──────────┬────────┘
          ▼                                 ▼
  ┌───────────────────┐          ┌───────────────────┐
  │  Stress           │          │  Adversarial      │
  │  No drift, leak,  │          │  Cap isolation    │
  │  or corruption    │          │  under attack     │
  └───────┬───────────┘          └──────────┬────────┘
          └─────────────┬────────────────────┘
                ┌───────┴────────┐
                ▼                ▼
      ┌──────────────────┐  ┌──────────────────┐
      │  Performance     │  │  Chaos           │
      │  Latency /       │  │  Graceful        │
      │  throughput      │  │  degradation     │
      │  baselines       │  │  under failures  │
      └──────────────────┘  └──────────────────┘

Tests live under tests/qemu/, organized by category:

tests/qemu/
  identity/      # §22.5-§22.6 (complete)
  property/      # see Property Tests below
  fuzz/          # see Fuzz Tests below
  stress/        # see Stress Tests below
  perf/          # see Performance Benchmarks below
  adversarial/   # see Adversarial / Red-Team Tests below
  chaos/         # see Chaos Tests below
  harness/       # shared infrastructure

The base harness (§22.3) boots the OS with a configurable -smp N value; multi-core tests assert on N ≥ 2. The battle-hardening categories extend it with longer timeouts (stress, perf), metric collection (perf), and fault injection (chaos).

The bar across every category is the same as identity: no FAIL, no BLOCKED with a vague reason. A failure means a real bug - fix it, add a regression test to the appropriate suite, then move on.

Identity (§22) - Complete

All passing (Tests 1-15; harness reports 24 cases incl. A/B + IR + Test 11 + Test 15). No regressions allowed. Any failure here is a constitutional violation that requires either a kernel fix or a CLAUDE.md amendment. Test 11 (added by H11) is now name-resolves-after-restart-via-the-kernel-directory - the registry service was retired in naming Phase 4 / Path C (docs/naming-design.md §3.7), so Test 11 pins the directory's restart property instead of a registry service. Test 1B now corrupts the supervisor (the registry it used to corrupt is gone). Test 15 (Path C / Phase 6) pins that the supervisor itself survives its own restart - the kernel respawns it, so the unkillable set is {kernel} alone.

Property Tests

Property tests assert universal claims over randomized inputs. Identity tests prove the system can satisfy each invariant; property tests prove it always does. Each test runs thousands of iterations with QuickCheck-style generators.

Bar: any property failure is a logic bug. Kernel must be fixed before any other work proceeds.

Fuzz Tests

Fuzz tests find the inputs that crash the kernel that no one would write by hand. The bar is binary and absolute: the kernel must never panic on user-controllable input.

Any panic discovered by F1-F8 is a kernel bug. The fix is mandatory and includes a regression test added to the relevant identity or property suite.

Stress Tests

Stress tests find the bugs that only appear under sustained load. Identity tests prove correctness for individual operations; stress tests prove the system does not drift, leak, or corrupt over hours of operation.

Bar: at the end of each test, the kernel has not panicked, memory accounting is consistent, all services are in a defined state, and no resource is leaked.

Performance Benchmarks

Performance benchmarks lock in numbers so regressions are detected commit-to-commit. Absolute values matter less than the deltas.

Results are committed to tests/qemu/perf/baseline.json. Comparison is MANUAL. collect_perf_baseline only WRITES the baseline; the regression_threshold_pct: 10 it emits is an inert field nothing reads, and no workflow runs the perf suite at all (every test workflow is workflow_dispatch-only; the release workflow builds images, it does not benchmark). This said "CI compares each run against baseline and flags regressions >= 10%", which described a gate that has never existed. The §7.8 single global lock will surface most visibly in B7 - record the number now so the v2 sharded/RCU migration has a target.

Adversarial / Red-Team Tests

Adversarial tests verify capability isolation holds under direct attack. The system claims a capability model with no ambient authority; these tests run services that try to break that claim.

Bar: every attack returns a defined error. Any attack that succeeds is a security hole; any attack that panics the kernel is a kernel bug. Both are mandatory fixes.

Chaos Tests

Chaos tests verify graceful degradation when something the kernel depends on fails partially. Total failures (kernel panic, TCB death) are covered by §6.2 and Test 1B. Chaos tests cover the between cases.

Bar: the system either continues correctly with degraded capacity, or panics loudly with a defined reason. Silent corruption is never acceptable. Per invariant 12 (§3): failures are loud, never silent.

22.3 Test Harness

  osdev test identity
    │
    ├── build: identity-only supervisor + kernel
    ├── create disk image, install bootloader
    │
    └── for each test:
           │
           ├── boot QEMU (-smp N; + -enable-kvm when /dev/kvm available)
           ├── test service runs scenario
           ├── harness reads serial console line by line
           │
           ├── expected output matched?  ──▶  PASS
           ├── fail_on string seen?      ──▶  FAIL
           ├── timeout fires?            ──▶  FAIL
           │
           └── 500 ms isolation pause (OS reclaims QEMU pages)

Where these tests actually live (spec -> implementation). The pseudocode in this section pins each test; the executable form lives in osdev/, not as .rs files under tests/qemu/. The identity cases (Tests 1-11 and 15, each A/B, plus the interrupt-routing IR1A/IR1B) are data-driven TestSpec entries in osdev/src/validator.rs, run together by osdev test identity - 24 cases. Tests 12, 13, and 14 are heavier bare-metal scenarios with their own subcommands - osdev test iommu (Test 12), osdev test fs-restart (Test 13), osdev test file-cap (Test 14) - in osdev/src/main.rs and osdev/src/shell_test.rs. The per-directory guide tests/qemu/identity/CLAUDE.md maps every spec Test to its entry, and the other categories (Property, Fuzz, Stress, Perf, Adversarial, Chaos, and their brutal variants) are TestSpec tables in the same validator.rs.

22.4 Sequencing Note

"Tests before code" is aspirational. You cannot run any test until the kernel boots and IPC works. Honest sequence: write test specs (this section); build minimum kernel + harness; see tests fail for the right reasons; implement until they pass.

A test failing for the wrong reason (compile error, harness bug, missing cap not declared in test contract) is a failure of the test, not the kernel.

22.5 Conventions

• Each test has a positive case (the system permits what it should) and a negative case (the system refuses what it shouldn't).
• Pseudocode is illustrative, not literal Rust.
• Each test names the spec section it pins.
• Multi-core tests run with -smp 4 minimum unless otherwise stated.

Test 1: Bootstrap to Steady State

Pins: §11 (Bootstrap), §6 (TCB).

1.A - Positive: Healthy Multi-Core Boot

test bootstrap_steady_state_positive:
    # Phase 5: no init - the kernel spawns the supervisor directly; the supervisor spawns events.
    image = build_kernel(boot_manifest=[supervisor, events])
    qemu  = boot(image, smp=4)

    assert serial_contains("supervisor: ready", within=5s)
    assert serial_contains("events: ready",     within=5s)
    assert serial_contains("smp: 4 cores ready", within=5s)
    assert kernel_did_not_panic()

1.B - Negative: TCB Failure Panics

test bootstrap_tcb_failure_panics:
    # Path C / Phase 5: init is removed, so the KERNEL spawns the supervisor directly. A corrupt
    # supervisor ELF fails that spawn → the kernel panics (no init abort, so no "reason:" prefix).
    image = build_kernel(boot_manifest=[corrupt_binary("supervisor"), events])
    qemu = boot(image, smp=4)

    assert serial_contains("KERNEL PANIC", within=5s)
    assert serial_contains("supervisor spawn failed")
    assert qemu_state == "halted"
    assert no_app_services_started()

Test 2: Capability Enforcement

Pins: §3.1 (no ambient authority), §7 (use validation).

2.A - Positive

test cap_enforcement_positive:
    s = spawn_test_service(contract="[capabilities] log_write = true")
    assert s.invoke(Log("hello")) == Ok
    assert log_received("hello")

2.B - Negative

test cap_enforcement_negative:
    s = spawn_test_service(contract="[capabilities] # no log_write")
    assert s.invoke(Log("hello")) == Err(CapNotHeld)
    assert log_did_not_receive("hello")
    assert s.is_alive()

Test 3: IPC Send / Receive (Same Core)

Pins: §8 (IPC), §7.4 (SEND right).

3.A - Positive

test ipc_send_recv_positive:
    a = spawn(contract="ipc_send=['b'], placement.core=0")
    b = spawn(contract="ipc_receive=['b'], placement.core=0")

    a.send(target="b", payload="ping")
    msg = b.recv()
    assert msg.payload == "ping"

3.B - Negative

test ipc_send_without_send_right:
    cap_no_send = mint_endpoint_cap(target=b, rights=[])
    a.install_cap("b_endpoint", cap_no_send)
    assert a.try_send(target="b", payload="ping") == Err(CapInsufficientRights)
    assert b.queue_depth() == 0

Test 4: Endpoint Death Semantics

Pins: §8.6 (failure semantics), §14.2 (restart drops endpoints), §8.5 (queue depth = 16).

4.A - Positive: Send-After-Death Returns EndpointDead

test endpoint_death_send_returns_dead:
    b = spawn_simple_recv_service()
    a = spawn_with_cap_to(b.endpoint)

    supervisor.kill(b)
    wait_for_revocation()

    assert a.try_send(b.endpoint, "after death") == Err(EndpointDead)

4.B - Negative: Blocked Sender Wakes With EndpointDead

The queue depth is 16 (§8.5), so this test fills it deterministically.

test blocked_sender_wakes_on_endpoint_death:
    b = spawn(non_consuming_receiver)            # never calls recv
    a = spawn_with_cap_to(b.endpoint)

    for i in 0..16:
        a.send("fill", index=i)                  # fills the 16-deep queue

    handle = a.send_async("blocked")             # 17th: must block
    assert handle.is_pending()

    supervisor.kill(b)
    wait_for_revocation()

    assert handle.poll(timeout=1s) == Err(EndpointDead)
    assert a.is_alive()

Test 5: Capability Transfer Requires GRANT

Pins: §7.6 (transfer rule), §7.4 (GRANT right).

5.A - Positive

test grant_positive:
    cap = mint_cap(target=resource_X, rights=[READ, GRANT])
    sender.install_cap("X", cap)

    msg = Message::with_cap(cap)
    assert sender.send(receiver.endpoint, msg) == Ok

    received = receiver.recv()
    assert received.embedded_cap.use(READ) == Ok
    assert sender.has_cap("X") == false

5.B - Negative

test grant_negative:
    cap = mint_cap(target=resource_X, rights=[READ])     # no GRANT
    sender.install_cap("X", cap)

    msg = Message::with_cap(cap)
    assert sender.send(receiver.endpoint, msg) == Err(CapNotGrantable)
    assert sender.has_cap("X") == true
    assert receiver.queue_depth() == 0

Test 6: Supervisor Restart and Cap Rebinding

Pins: §14.2 (restart flow), §14.3 (cascading failure).

6.A - Positive

test supervisor_restart_positive:
    pong         = spawn("pong")
    original_pid = pong.pid

    supervisor.restart("pong")
    wait_for_serial("pong: ready", within=5s)

    assert pong.pid != original_pid
    assert kernel_did_not_panic()
    assert all_other_services_alive()

6.B - Negative

test stale_cap_revoked_after_restart:
    ping = spawn("ping")
    pong = spawn("pong")

    supervisor.restart("pong")
    wait_for_serial("pong: ready")

    assert ping.send_via_stale_cap("hello") in [Err(CapRevoked), Err(EndpointDead)]

    fresh = ping.reacquire_by_name("pong")
    assert ping.send_via(fresh, "hello") == Ok

Test 7: Memory Limit Enforcement

Pins: §10.3 (enforcement), §10.4 (two failure modes).

7.A - Positive

test memory_alloc_within_limit:
    s = spawn(contract="memory.limit = 64MiB")
    assert s.alloc(32 * MiB) == Ok
    assert s.alloc(20 * MiB) == Ok
    assert s.is_alive()

7.B - Negative (Two Modes)

test memory_alloc_beyond_limit_recoverable:
    s = spawn(contract="memory.limit = 64MiB")
    s.alloc(60 * MiB)
    assert s.alloc(20 * MiB) == Err(AllocDenied)
    assert s.is_alive()
    assert s.alloc(2 * MiB) == Ok

test memory_protection_violation_kills_service:
    s = spawn(contract="memory.limit = 64MiB")
    s.alloc(32 * MiB)
    s.write_to_unmapped_address(0xdead_0000)
    wait_for_kill(within=1s)
    assert s.is_dead()
    assert kernel_did_not_panic()

Test 8: Preemption of Non-Yielding Service

Pins: §3.6 (no service can monopolize), §9.1 (10 ms quantum), §9.3 (yield is advisory).

8.A - Positive

test yield_advisory_works:
    yielder = spawn_yielding_service(core=0)
    other   = spawn_logging_service(core=0)

    run_for(1s)
    assert other.log_count    >= 90
    assert yielder.tick_count >= 50

8.B - Negative

test non_yielding_service_is_preempted:
    hog   = spawn_tight_loop_service(core=0)
    other = spawn_logging_service(core=0)

    run_for(1s)
    assert other.log_count >= 1     # minimum bar
    assert other.log_count >= 40    # near fair share
    assert hog.is_alive()
    assert kernel_did_not_panic()

Test 9: Cross-Core IPC

Pins: §8.3 (routing), §8.4 (send flow), §9 (per-core scheduler).

9.A - Positive

test cross_core_ipc_positive:
    a = spawn(contract="ipc_send=['b'], placement.core=0")
    b = spawn(contract="ipc_receive=['b'], placement.core=1")

    assert a.assigned_core == 0
    assert b.assigned_core == 1

    a.send(target="b", payload="hello from core 0")
    msg = b.recv()
    assert msg.payload == "hello from core 0"

9.B - Negative

test cross_core_no_authority_leak:
    a = spawn(contract="placement.core=0")          # no caps to b
    b = spawn(contract="ipc_receive=['b'], placement.core=1")

    fake_cap = a.try_construct_cap(target=b.endpoint, rights=[SEND])
    assert fake_cap == Err(CapForgeryAttempted)
    assert b.queue_depth() == 0

Test 10: Restart With Core Reassignment

Pins: §9.2 (placement, strict), §14.2 (restart can change core), §14.4 (placement override), §11 (identity stable; location not).

10.A - Positive

test restart_changes_core_transparently:
    pong = spawn(contract="placement.core=1")
    assert pong.assigned_core == 1
    pong_gen_old = pong.generation

    supervisor.restart("pong", placement_override=2)
    wait_for_serial("pong: ready on core 2", within=5s)

    assert pong.assigned_core == 2
    assert pong.generation     > pong_gen_old

10.B - Negative

test client_reacquires_after_core_change:
    ping = spawn(contract="placement.core=0")
    pong = spawn(contract="placement.core=1")

    supervisor.restart("pong", placement_override=2)
    wait_for_serial("pong: ready on core 2")

    assert ping.send_via_stale_cap("hello") == Err(EndpointDead)

    fresh = ping.reacquire_by_name("pong")
    assert fresh.target_core == 2
    assert ping.send_via(fresh, "hello") == Ok
    assert pong.received("hello")

Test 11: Name Resolves After Restart, via the Kernel Directory (Path C / Phase 4)

Pins: §6.1/§6.2 (a restartable service's death is a supervisor restart, not a panic), §14 (supervisor restart authority), §3.11 (identity over location), §4.4/§26.10 (naming = the kernel's minimal recovery directory, not a service).

Amendment 2026-06-21 (naming Phase 4): the registry service is retired (docs/naming-design.md §3.7, "Path C"). Name→endpoint resolution is a minimal directory inside the kernel (ipc::names

• the gated AcquireSendCap); the supervisor wires services from a name → cap map and clients reacquire names via the directory. There is no registry service to kill. This test was "registry survives its own restart" (H11); it now pins the directory's restart property - a restartable service killed and respawned must re-establish without a kernel panic, and its name must resolve to the new instance (the directory re-records it on respawn). block-driver is the disk-free restartable target (it idles with no disk in the identity build).

test name_resolves_after_restart_via_directory:
    wait_for_serial("supervisor: ready")
    control.kill("block-driver")                   # a restartable service (Phase D)

    assert serial_contains("supervisor: block-driver died, restarting")
    assert serial_contains("supervisor: block-driver restarted")
    assert serial_contains("name-map + block-driver")  # re-recorded → directory resolves the new instance
    assert kernel_did_not_panic()
    # Clients reacquire "block-driver" by name via the kernel directory (§14.3) - pinned end-to-end
    # for fs←block-driver and shell←fs by the files-test double-storm regression.

Test 12: Confined Driver Cannot DMA Outside Its Arena (H1)

Pins: §3.1 / invariant 1 (no ambient authority - the DMA gap), §6.4 (DMA-capable drivers are least-privilege when IOMMU-confined), §12 (drivers).

The point of H1: a confined DMA-capable driver's device can reach only its granted arena. A DMA outside it must be blocked at the IOMMU (a logged IO_PAGE_FAULT on real hardware), never silently read/write other memory. This is the executable form of the §6.4 trust claim - without it, "confined" is a word, not a guarantee.

Runs only where an IOMMU is present (osdev test iommu launches QEMU with -device amd-iommu); on a machine with no IVRS the driver is trusted (§6.4) and the test is not applicable.

Verification is structural, not a live fault, and the reason is a QEMU limitation. QEMU's emulated amd-iommu installs the device tables and page tables but does not enforce translation faults on unmapped I/O addresses - a device DMA to an unmapped page is silently allowed through. So a live IO_PAGE_FAULT cannot be observed under QEMU. The harness therefore asserts the property QEMU can be made to prove: the kernel's confinement selftest - a CPU-side walk of the device's I/O page table - confirms the arena translates identity and the page one past it is unmapped (so a DMA there has no translation and would fault on conforming silicon). That selftest is exactly the structure an IO_PAGE_FAULT is raised from; pinning it pins the guarantee. (The live fault itself is hardware-verified on the T630 and reproducible anywhere via the iommu-fault-test build feature, which confines the driver to an empty domain so its normal init DMA lands out-of-arena.)

test confined_driver_dma_faults:           # osdev test iommu
    boot(smp=2, iommu=on)                                     # q35 + amd-iommu + qemu-xhci + usb-kbd
    assert serial_contains("iommu: ... confined BDF")         # driver is confined to its arena

    # The kernel's confinement selftest walks the device's I/O page table: the arena
    # maps identity, and the page one past arena_end has NO mapping - the structural
    # form of "out-of-arena DMA would fault" (QEMU can't raise the fault itself).
    assert serial_contains("iommu: selftest PASS")
    assert serial_contains("(outside) unmapped")

    assert serial_contains("keyboard found")                  # driver still operates THROUGH the domain
    assert kernel_did_not_panic()                             # confinement is not fatal to a well-behaved driver

# Live-fault form (hardware / `--features iommu-fault-test`, not QEMU's lenient model):
#   confine the driver to an EMPTY domain → its first init DMA is out-of-arena →
#   IOMMU raises IO_PAGE_FAULT, kernel logs it, memory outside the arena is unchanged.

Test 13: Filesystem Survives Its Own Restart (Phase D)

Pins: §6.1/§6.2 (fs + block-driver are restartable, not trusted root), §6.3 (TCB-shrink goal reached), §15 (transactional recovery), §14 (supervisor restart authority), §3.11.

fs and block-driver are restartable userspace services (Phase D amendment 2026-06-17), made safe by fs's crash-consistent recovery (Phase C). Killing fs must NOT panic the kernel; the supervisor must observe its death and respawn it; fs must re-mount to a consistent state (persisted data intact) and re-register; and a client must reacquire it by name and keep working.

test fs_survives_own_restart:                     # osdev test fs-restart
    boot(bare-metal + AHCI disk; shell on COM1, control on COM2)
    shell("drives flash data" → y)                # format
    shell("write /t.txt survives-restart")
    assert shell("read /t.txt") contains "survives-restart"

    control.kill("fs")                            # was a panic+reboot pre-Phase-D

    assert serial_contains("supervisor: fs died, restarting")
    assert serial_contains("supervisor: fs restarted")
    assert serial_contains("fs: serving file API")   # re-mounted + re-registered

    # The shell reacquires a fresh fs cap by name via the kernel directory (§14.3); the file persisted.
    assert shell("read /t.txt") contains "survives-restart"
    assert kernel_did_not_panic()

Test 14: File Is a Capability (P2)

Pins: §7.3 (cap properties), §7.10 (delegated resource capabilities), §3.1 (no ambient authority), §3.3 (authority by capability, not identity).

The P2 amendment (2026-06-18) makes a file a real, kernel-minted capability via delegated resource caps. This test pins that the file cap is a genuine capability - not a service-level token - by exercising the three properties that distinguish one: unforgeable, revocable, non-escalating.

test file_is_a_capability:
    # fs hands out a real cap on open (delegated resource cap, §7.10)
    rw = fs.open("/doc.txt", rights=[READ, WRITE])     # returns a file capability
    assert rw.write("hello") == Ok
    assert rw.read()         == "hello"

    # Unforgeable (§7.3): a fabricated handle is not a cap
    assert use_random_handle_as_file_cap() in [Err(CapNotHeld), Err(CapInvalid)]

    # Non-escalating (§7.3): a READ-only file cap cannot write
    ro = fs.open("/doc.txt", rights=[READ])
    assert ro.read()          == "hello"
    assert ro.write("nope")   == Err(CapInsufficientRights)

    # Revocable (§7.5/§7.10): deleting the file revokes every cap to it
    fs.delete("/doc.txt")                               # fs revokes the resource (gen bump)
    assert rw.read()  == Err(CapRevoked)
    assert ro.read()  == Err(CapRevoked)
    assert kernel_did_not_panic()

Implemented (2026-06-18) as osdev test file-cap (9/9 ✅). The shell fcap <file> command opens a file as a real kernel capability and exercises every property above end-to-end: read/write through the cap; non-escalation at both layers (the kernel rejects a READ-only cap's WRITE invocation with CapInsufficientRights, and fs refuses a write op carried under a read-validated badge - op ≤ right); a fabricated handle is rejected (unforgeable); and the cap is CapRevoked after close/delete (revocable). The badge that carries the validated (resource_id, right) to fs is an unforgeable kernel-set Message field (LastRecvBadge syscall) - a client cannot fake a file-cap invocation over its ordinary fs send cap.

Test 15: Supervisor Survives Its Own Restart (Path C / Phase 6)

Pins: §6.2 (the supervisor is restartable - its death is a kernel respawn, not a reboot), §6.3 (TCB-shrink reached its floor: unkillable = {kernel}), §3.7/§4.4 (the kernel is the recovery anchor), §14 (restart authority), §3.11 (identity over location).

Amendment 2026-06-21 (Path C / Phase 6): the supervisor is restartable. Killing it (a fault, or a deliberate chaos kill-storm supervisor / the operator control channel) must not panic the kernel. The kernel respawns it - unconditionally, forever (no bound: a bound would re-introduce the reboot and be a DoS, §6.2) - and the respawned supervisor reconciles: it adopts the still-running services (reacquiring each by name from the kernel directory) instead of duplicating them. The running services (pong/ping cross-core IPC, the shell) keep going throughout - the shell survives killing its own spawner. This is the executable proof that the unkillable set is {kernel} alone.

test supervisor_survives_own_restart:           # osdev test identity (also: chaos kill-storm supervisor)
    wait_for_serial("supervisor: ready")
    control.kill("supervisor")                    # was a kernel panic pre-Phase-6 (it was trusted root)

    assert serial_contains("kernel: supervisor died - respawning")   # the kernel is the recovery anchor
    assert serial_contains("supervisor: adopted running block-driver") # reconciled, not duplicated
    assert kernel_did_not_panic()
    # The shell-test storms it 4× (chaos kill-storm supervisor 4 → recovered 4/4, kernel alive, no
    # bound) and the prompt still answers afterward - the system stayed up across every respawn.

22.6 Test Coverage Matrix

If any cell becomes obsolete, the corresponding spec section is being changed and the change requires a CLAUDE.md amendment.

22.7 The Stranger Test - is the PUBLIC interface doing the teaching?

Every test above this line asks whether the kernel is correct. This one asks whether the system can be USED, and it is the only test here whose subject is the developer rather than the machine.

The bar: give the least capable model available a fresh context, the PUBLIC developer documentation only, and one ordinary application requirement. No architectural coaching. If it produces a correct Godspeed program under those conditions, the public interface is doing a substantial amount of the teaching. If it can only succeed after someone explains MISCIS, the interface is not finished, whatever the kernel does.

Why the weakest model rather than the best. A sophisticated model can infer the architecture from the source and would pass by being clever, which measures the model. A weak one cannot, so what it produces measures the DOCUMENTATION AND THE API. The point is not to find out whether Godspeed can be understood; it is to find out whether it has to be understood before it can be used.

Let the repository teach, and do not grade on a curve. The temptation is to explain the rules and then be pleased when they are followed. The rules are already mechanised, so the test is whether the gates catch a stranger's mistakes and whether the resulting error says enough to recover from: #![deny(unsafe_code)] refuses unsafe at the compiler, arch_boundary_check refuses an ISA-conditional workaround, commandments.py refuses ambient authority and an unrecoverable peer, and Error::retry_is_safe answers the one question a stranger is most likely to get wrong. A gate that fires with an unhelpful message is a finding, not a pass.

It is the inversion of the grokability probe in audits/documentation-audit.md, which asks whether a weak model can REGENERATE a document. That one tests whether Godspeed can be understood; this one tests whether it can be used without being understood. Both use the same instrument and neither substitutes for the other.

This is not an identity test and does not pretend to be. It has no pass/fail assertion, cannot be run in CI, and failing it does not mean the system stopped being the system §22.1 describes. It means v1's stated intent - "Godspeed is simple to program for because its own architecture has a small, coherent and honest developer interface" - is not yet met. It is recorded here rather than in docs/ alone because that intent is a commitment, and a commitment nobody measures is a preference.

The correct path must be easier than cheating. That is the whole design rule this test exists to check, and the honest form of the success condition: a stranger should fall into the supported model because it is the path of least resistance, not because they were told to.

docs/stranger-test.md has the protocol, what to measure, and the difficulty ladder.

23. First Milestone ✅ Complete

23.1 Goal

Boot the OS multi-core.
Start two services (ping on core 0, pong on core 1).
Send a message between them via cross-core IPC.
Kill pong.
The supervisor restarts it (possibly on a different core).
The system continues running.

23.2 Acceptance Criteria ✅

1. osdev run --smp 4 boots the OS with 4 cores; supervisor, events, ping, and pong reach steady state. ✅ (As recorded in 2026-05 this read "init, supervisor, registry, logger"; init was removed in Phase 5, the registry service retired in Phase 4, and logger renamed events in 2026-09.)
2. ping placed on core 0; pong placed on core 1. ✅
3. osdev logs ping shows ping sending a message every second. ✅
4. osdev logs pong shows pong receiving each message (cross-core IPC). ✅
5. osdev restart pong --core 2 kills pong on core 1 and respawns it on core 2. ✅
6. ping observes EndpointDead and reacquires by name; the new cap routes to core 2. ✅
7. After reacquisition, ping and pong continue communicating across the new core boundary. ✅
8. The kernel does not panic on any core. ✅
9. All identity tests in §22 pass. ✅ (ten at the time; fifteen tests / 24 cases today.)

23.3 Bare-Metal Achievement ✅

GodspeedOS has booted on real x86_64 hardware (4-core CPU, 4 GB RAM) via UEFI USB boot (2026-05-21).

• osdev image produces a UEFI GPT disk image at build/os-usb.img. (This said build/os.img, which is the QEMU/BIOS image - osdev/src/disk_image.rs notes the two are named apart on purpose, and §17 has it right.)
• Image written to USB with Cygwin dd; boots via BOOTX64.EFI (Limine 12.x).
• All 4 cores come up; cross-core IPC (ping core 0 → pong core 1) runs continuously on hardware.
• Null modem serial (115200 8N1, PuTTY) confirms boot output; log appended to build/putty_serial_output.log.
• bare-metal supervisor feature excludes harness-driven probe services that require QEMU's control port.

Persistence + file-as-capability hardware-proven on the HP T630 (2026-06-18). Booted the bare-metal os.img on the T630 (AMD GX-420GI, real AHCI SSD) and ran the shell selfcheck suite: ran 163, failed 0. That run includes the full persistence stack (GSFS0008 format, journal, fsck/drives check, read-only drives scrub) and the file-as-capability self-check (fcap, §22 Test 14): a file opened as a real kernel capability, read/written through the cap, non-escalation enforced at both the kernel and fs layers, a forged handle rejected, and the cap revoked on close and on rename - all green on real hardware, no panic. The §7 "north star" (a file is a capability, true not approximate) is hardware- validated, not just QEMU. Serial in build/putty_serial_output.log.

Hardware performance data (perf-brutal-only build, ~3 GHz CPU, 2026-05-21):

HP T630 (AMD GX-420GI, Jaguar/Puma+, ~2 GHz) - per-probe isolated measurements (one benchmark alone: no ping/pong, no competing probes; 2026-05-31, build ed8a151). µs/ms at ~2 GHz:

All cycle counts. † = perf-brutal in-suite p50 (already low-variance); the rest are single-probe isolation builds (osdev image --mode iso-bp{3,5,7,9,10}; bp5 covers BP5+BP6). The two columns are not a clean head-to-head: J5005 was perf-brutal (contended), the T630 column is isolated (uncontended), so they compare fairly only where both were clean - BP1/BP4/BP8 at ~1.9-2.5×, genuine Jaguar-vs-Goldmont IPC. Where the T630 number is lower (BP3) the J5005 figure was itself contention-inflated. BP5/BP6 (spawn/restart) are memory-bandwidth-bound - the low-power thin client lags most there. The full investigation behind BP2 (the COM2 timer-ISR wedge, fixed a306fd3) is in bugs/1_FINDINGS_AP_TO_BSP_IPI.md.

23.4 Out of Scope for v1

Filesystem persistence beyond the trusted block driver, network stack, work-stealing scheduler, service migration, zero-copy IPC, live code updates, restartable block driver / fs, update model in production mode, core hotplug, per-endpoint queue depth in contract.

24. Glossary

• AP - Application Processor. Any core other than the BSP.
• BSP - Bootstrap Processor. The first core to execute kernel code.
• Call - The synchronous request/reply IPC syscall (§8.2, syscall 41): send a request carrying a one-shot reply cap, then block awaiting the reply; wakes with the reply or with ReplyDead if the replier dies first, so it never hangs. Mechanism, not policy - the kernel learns a reply cap, not "RPC". The primitive behind the SDK request_with_reply.
• Capability - Unforgeable token: ResourceId + Rights + Generation.
• Delegated resource capability - A capability for a resource whose meaning is defined by a service (e.g. a file owned by fs), not the kernel. The owning service mints and revokes it (resource_mint/resource_revoke, gated by a RESOURCE_MINT cap); the kernel validates and routes it as for any cap, badging a send with the opaque ResourceId so the owner knows which resource. The mechanism behind file-as-capability (§7.10, P2).
• Endpoint - IPC destination owned by a service. Bounded queue, depth 16 in v1.
• Generation - Monotonic counter on resources; mismatch on cap use indicates the resource was destroyed or replaced.
• Grant - The right to transfer a capability via IPC.
• Identity test - A test that pins a constitutional decision (§22).
• IPI - Inter-Processor Interrupt. Mechanism for a core to wake another core.
• Limine - The bootloader used in v1. See Appendix A.
• Placement - Strict assignment of a service to a specific core at spawn time. Re-evaluated from scratch on every spawn, including post-restart spawns; the previous core is not remembered.
• PlacementInvalid - Error returned when a contracted core is unavailable; spawn rejected, supervisor logs and skips.
• Quantum - The 10 ms time slice after which the per-core scheduler preempts.
• Reply cap - A one-shot capability to the caller's own endpoint, sent inside a Call request so the replier can reply to it. The kernel tracks, per blocked caller, the target endpoint it awaits; if that endpoint dies, the caller is woken with ReplyDead. The reply-side twin of the blocked-sender record (§8.2, §8.6).
• ReplyDead - Error returned when the replier's endpoint dies while the caller is blocked in a Call awaiting its reply (value -12; §7.7, §8.6). The reply-side twin of EndpointDead, on the same generation/liveness mechanism.
• Routing table - Kernel structure mapping EndpointId → (CoreId, Generation, Liveness).
• TCB - Trusted Computing Base. Kernel + arch + smp + supervisor. (Not init - it was removed in Path C / Phase 5; the kernel spawns the supervisor directly. And the supervisor is trusted but RESTARTABLE, Phase 6, so the only unkillable component is the kernel.) registry left the TCB via H11 (and the registry service was then retired entirely - naming Phase 4 / Path C, docs/naming-design.md §3.7); block-driver + fs left via the Phase D amendment (§6.1, once fs gained crash-consistent recovery). DMA drivers (xhci/ehci, and ARM's dwc2) are in the TCB only on a machine without an IOMMU to confine them (§6.4); all three are userspace services now.
• Trusted root - supervisor (sole; init was removed in Path C / Phase 5 - the kernel spawns the supervisor directly). It is trusted but restartable (Path C / Phase 6, §6.2): the kernel respawns it on death - unconditionally, forever - so its failure is recovered, not a reboot. The only unkillable component is the kernel itself. (block-driver + fs are restartable storage services.)
• Name directory - the kernel's minimal name → EndpointId map (ipc::names) + a gated "mint a SEND cap by name" (AcquireSendCap). The bounded recovery anchor that replaced the registry service (naming Phase 4 / Path C, §3.7): the supervisor wires services from a name → cap map and clients reacquire names through the directory. (The retired registry service's design note was deleted with the service; docs/naming-design.md §3.7 is the record.)
• Service - Userspace component with a contract, capability table, and isolated address space.
• Contract - a service's contracts/<name>.toml (e.g. examples/ping/contracts/ping.toml) declaring resource, capability, and placement requirements.
• Supervisor - User-space service holding restart authority over other services.
• osdev - Host-side CLI for building, publishing, and controlling the OS in QEMU.

25. Final Principles

Undefined behavior in spec becomes bugs in system.

If it violates the model, it does not belong.

If an identity test fails, the system is no longer this system.

Identity is stable. Location is not. Movement is invisible. Death is visible.

Failures are loud, never silent.

A failing Godspeed that preserves its invariants is preferable to a working Godspeed that violates them.

The last one ranks the others. Every principle above can be traded against a deadline, a benchmark or a stubborn bug, and this says which way that trade goes: a system that fails while keeping its model intact is still this system, and can be fixed. A system that works by breaking its model is a different system that happens to run today, and what it has really lost is the reason to trust any of the rest of this document.

This is not a preference for failure. It is a statement about what a fix is: making the system work WITHIN the model, and never widening the model to admit what is easier. Where the two genuinely cannot be reconciled, the honest move is to record the gap loudly and leave it open (§26.7) rather than close it with a violation.

Appendix A: Bootloader Choice (Limine)

Status: v1 commitment. This appendix documents and justifies a concrete decision; it is part of the v1 spec, not aspirational.

A.1 Decision

The v1 bootloader is Limine, accessed by the kernel via the Limine Boot Protocol.

A.2 What Limine Provides to the Kernel

At handoff, Limine supplies the kernel with:

• Physical memory map - usable, reserved, ACPI, framebuffer regions all classified.
• Framebuffer descriptor - base address, dimensions, pixel format. Avoids ever needing VGA text mode.
• Kernel relocation info - physical and virtual base addresses of where the kernel was loaded.
• SMP topology - APIC IDs of all available processors, used by kernel/smp and arch/x86_64/ap_boot.rs. This removes the need to probe ACPI/MADT in v1.
• Higher-half direct map - physical memory pre-mapped at a known high-half virtual address, available immediately.
• Boot-time module list - ability to load additional binaries (e.g., the initial service manifest) alongside the kernel.

A.3 Why Limine for v1

A.4 Installation Story

GodspeedOS ships with Limine. Users do not install or pre-install Limine separately.

UEFI systems:

• The OS image places BOOTX64.EFI (the Limine UEFI loader) at /EFI/BOOT/BOOTX64.EFI on the EFI System Partition.
• The kernel binary is placed where limine.conf references it.
• Firmware → BOOTX64.EFI → Limine → kernel.

BIOS systems:

• The installer runs limine bios-install to write Limine's stage-1 to the MBR (or VBR).
• Stages 2 and 3 of Limine live on disk alongside the kernel; loaded by the stage-1.
• Firmware → MBR → Limine → kernel.

In both cases the Limine binaries are part of the OS image. The end user installs the OS; Limine arrives with it.

A.5 Dual-Boot Support

Out of scope for v1. If pursued later, Limine supports chainloading other bootloaders, which is the cleanest path. v1 assumes a dedicated machine or VM.

A.6 Alternatives Considered

A.7 Implementation Notes

• The integration code lives in kernel/src/arch/x86_64/boot.rs.
• The Limine protocol version used is pinned in the workspace Cargo.toml. Protocol version bumps are PR-reviewed.
• The boot handoff (Limine to kernel main) is §11 itself. A separate docs/bootstrap.md was listed here and in §5 but was never written; §11 is the walkthrough, and pointing at it is both truthful and shorter than writing a second file to repeat it.

Appendix B: Userspace Posture

Status: Non-normative. Records the v1 stance on userspace languages and the design intent for early services. Does not amend the constitution.

B.1 Primary Language: Rust

All v1 userspace services are written in Rust against sdk/rust/.

Reasons:

• The kernel is Rust; sharing a toolchain dramatically simplifies the build and CI pipeline.
• Capability handles in sdk/rust/capability.rs are typed Rust structures. C or other-language equivalents would need parallel SDKs.
• Contract validation in osdev is Rust; reusing the same JSON Schema crate end-to-end avoids drift.
• Borrow-check discipline meshes naturally with the no-shared-mutable-state invariant.

B.2 Other Languages

The syscall ABI follows System V AMD64. Any language that can produce a freestanding ELF binary and call via that ABI can run as a service.

Plausible second-fits:

• C - would need a sdk/c/ of thin syscall wrappers. Capability handles become opaque integers; the type-safety of the Rust SDK is lost.
• Zig - bare-metal-capable, no runtime, comparable ergonomics to C with better safety. A sdk/zig/ is a future possibility.

Out of scope:

• Languages with substantial runtimes (Go, Python, JavaScript, Java) - would require porting their runtime as a GodspeedOS service. Each is a multi-month project on its own.

B.3 Shell ≠ Unix Shell

The traditional Unix shell relies on fork, exec, file-descriptor inheritance, ambient stdin/stdout/stderr, environment-variable inheritance, and anonymous pipe sharing. None of those primitives exist in GodspeedOS.

A "shell" in this system is a capability-broker service. It:

• Holds a capability to a console service (keyboard input + display output).
• Holds the authority to ask the supervisor to spawn other services (via a cap to invoke supervisor.spawn).
• Reads commands and constructs spawn requests, including the explicit caps each child should receive.

This means there is no stdin, only an IPC endpoint to a console service. There is no fork, only an authenticated request to the supervisor. There is no inherited environment, only the caps the parent explicitly granted.

Note (2026-08-17): a console service now exists, and it owns OUTPUT only. This appendix anticipated one service holding "keyboard input + display output"; what was built holds the display - the terminal model, the grid, the cursor and the rendering (docs/console-service.md §9). Keyboard INPUT is still brokered by the shell through the kernel's single-reader console ring, for the reason recorded in docs/console-service.md §5a: there is one input ring and one reader slot, so a service that owned the keyboard would block in ConsoleRead and could not also field take/release messages. The split is deliberate, not partial. This appendix stays non-normative; it is the intent, and the difference is recorded here rather than left to read as a description of what shipped.

The full mechanics of how Unix-style scripting maps onto this model - pipes as capability-mediated endpoints, redirection as cap minting, etc. - are explored in Appendix D.

B.4 Open Question for Later

When real userspace work begins, the first user-facing design decision is how Unix-flavored the interface should feel - Genode-style superficial familiarity (the Unix word works, even though it is a capability-bearing service) versus a fully fresh vocabulary. Either is defensible. Picking deliberately matters because retrofitting later is painful.

Answered 2026-09-23, and by a third option neither of those two is. The vocabulary is fresh - dir, read, delete, copy, match, count - and the shell keeps a table of the Unix and DOS words (FOREIGN_HINTS) purely so that typing the reflex tells you the Godspeed word. It is a HINT and never an alias: ls does not run, it answers try \dir``. So familiarity is spent on DISCOVERY rather than on compatibility, and nobody ends up writing scripts against a second set of names that has to be supported forever.

Recorded here because this appendix is where the question was posed, and an open question that has been answered is worse than one that never was - the next reader takes it as still open. The mechanism is in services/shell; scripts/foreign_word_check.py reads that same table to make sure no document in this repository shows one of those words being used as a command, which is how the ls -> dir rename was found to have missed ten worked examples.

Note 2026-10-13: two Unix words are commands, cd and pwd, and each has a reason. cd was kept from the start because it is universal (utilities/17_cd.md). pwd joined it with the filesystem layout (docs/filesystem-layout.md 6): the prompt is a plain gsh> , so something has to say where you are, and pwd is cd's other half - anyone who knows one knows the other. It left FOREIGN_HINTS, where its hint had been cd ., which asked a reader to know a Unix convention (.) without naming anything. The rule above is unchanged: every other foreign word is still a hint and never an alias, and a new exception needs a reason of its own written beside it, as this one is.

Note 2026-10-14: and a third, shutdown, with its reason. It is the word Linux, Windows and macOS share, and it names the ACT - ending the session - rather than promising a mechanism: on the T630, the Pis and the VisionFive the machine halts without losing power, so poweroff would claim what does not happen (docs/shutdown.md). It left FOREIGN_HINTS, where its hint had been reboot - wrong advice, since reboot turns nothing off - and halt and poweroff stay hints that answer shutdown.

Appendix C: Forward-Looking Vision (Non-Normative)

Status: Non-normative. Records design intent for post-v1 directions. Items may be deferred indefinitely, redesigned, or rejected when their time comes. This appendix does not amend the constitution.

C.1 observe - Native Top/Htop Equivalent

Tentative timeline: v2 candidate.

A native introspection tool, distinct from any third-party utility, that surfaces what the system is doing.

The architecture makes this easier than the equivalent on Unix. Per-service state is already structured: caps held, assigned core, memory request/limit, current allocation, IPC queue depths, generation, liveness. The supervisor already knows about every service. The kernel already tracks per-task state.

observe would be a service holding capabilities to query the supervisor and a kernel-provided introspection endpoint, formatting the result for display. There is no need to parse a /proc-style text interface - the data is already structured.

C.2 Native Metrics Emission

Tentative timeline: v2 / v3 candidate.

The system should emit metrics by default, without requiring third-party agents.

Architectural intent: the kernel emits structured events (IPC volume, cap denials, scheduler statistics, restart events) on a known endpoint. This is a publication, not a feature baked into kernel logic - the kernel does not know what format consumers want. A separate metrics service holds the consuming capability and exports in whatever format is appropriate (Prometheus exposition, OpenTelemetry, statsd, custom).

Constraint: this must not pollute kernel scope. The kernel publishes; the metrics service interprets.

Note (2026-08-31): the "known endpoint" above is the part to re-examine; the constraint under it is exactly right. This appendix predates the trace utility, which shipped with ZERO kernel growth - the ring lives in the logger service and the instrumentation in the SDK. The reasoning that kept it out of ring 0 applies here: a kernel event queue needs a bound, a bound needs a drop policy, and deciding what to discard is a judgement (§26.10). A kernel-held endpoint to a RESTARTABLE consumer is worse still - stale, with nobody above it to recover it (§14.3).

(Update 2026-09-04: that service is now called events - see the §11.4 amendment. The note is left as written, including the old name, because it is dated; only this line is added, so a reader is not sent looking for a service that no longer answers to it.)

Kernel STATE is already published by pull (InspectKernel, 25 queries, and TaskStat, gated by INTROSPECT). Kernel EVENTS can ride the §11.4 shape: a bounded ring the kernel writes and a service DRAINS - no endpoint, no consumer identity, no policy in the kernel. docs/observability.md has the full argument and the three-part test any new mechanism must pass first. Non-normative, as is this appendix.

C.3 Cluster Mode (Single-System-Image)

Tentative timeline: multi-year research direction. Not a milestone commitment for any specific version.

The ambition: multiple GodspeedOS instances, possibly identified by a shared token, joining together to act as a single system. Conceptually similar to what k8s does for containers, but at the OS layer: services on any node, IPC across nodes, single namespace.

Why this is unusually feasible architecturally:

• Invariant 11 ("identity is stable; location is not") is the design primitive distributed systems are built on. The routing table generalizes cleanly: EndpointId → CoreId becomes EndpointId → (NodeId, CoreId). SMP already separated identity from execution location; cluster mode extends "location" from a core to a (node, core) pair without changing the philosophy.
• The generation-number mechanism for cross-core revocation extends to cross-node revocation.
• The absence of POSIX, fork, shared memory, and ambient authority means none of the impossible-to-distribute primitives are baked in. Linux clustering attempts (OpenSSI, MOSIX) all foundered on mmap, signals, and inherited file descriptors.

Why it is still a multi-year project, not a v2 weekend:

• Synchronous IPC does not survive network latency. Either remote IPC must be a different primitive (loses transparency), or "blocking send" must mean something different cross-node (semantic fork in the API).
• Cluster membership, leader election, and consensus are real distributed-systems problems (Raft / Paxos territory).
• Cryptographic capability transfer over a network - caps must remain unforgeable when crossing the wire.
• Cross-node TCB definition: does the supervisor on node A have authority over services on node B? If yes, a compromised supervisor compromises the cluster. If no, what coordinates restarts?
• Failure semantics expand: not just node crashes, but network partitions, split-brain, and partial failures.

Reference points:

• Plan 9 from Bell Labs achieved network-transparent files and processes 30+ years ago.
• Barrelfish (Microsoft Research) explored "the OS as a distributed system" via the multikernel model.
• MOSIX, OpenSSI, LOCUS - Linux/Unix attempts at SSI; useful for understanding what didn't work and why.

The architectural primitives in this constitution are unusually well-suited for revisiting these ideas. Whether and when to attempt it is open.

C.4 Cluster Routing: Architecture and API

Full design notes, failure semantics, flow control, ordering, registry scope, transport options, and TCB authority model live in docs/cluster-design.md. This section records the headline conclusions.

The routing table generalizes from EndpointId → CoreId to EndpointId → (NodeId, CoreId). The invariant "identity is stable; location is not" already encodes this - cluster mode extends the definition of location without changing the philosophy. The generation mechanism handles cross-node service mobility identically to how it handles cross-core restarts today.

The remote IPC API uses a distinct call surface (send_remote with explicit timeout) rather than transparent routing. The existing constitution invariants settle this: a successful local send guarantees queue delivery on this machine; a successful remote send guarantees handoff to a transport. These are different contracts with different durability and failure obligations, and pretending otherwise is the architectural mistake transparent-clustering systems have historically made. The network boundary is visible at three layers: contract (ipc_send_remote), type system (RemoteSendCap vs LocalSendCap), and call site. Applications that never declare ipc_send_remote are entirely unaffected by cluster membership.

Three questions must be resolved before cluster mode can ship: the transport protocol (which shapes failure semantics and ordering guarantees), the registry consistency model (distributed name resolution is the largest single piece of work, comparable in scope to most of v1), and cross-node TCB authority (whether a supervisor on node A governs services on node B - the central security question for clustering).

Appendix D: Shell, Scripting, and Utility Ecosystem (Non-Normative, Far Future)

Status: Non-normative, far-future. Records the design intent for what shell scripting could look like on GodspeedOS, and what porting Unix-style utilities would actually require. This appendix does not amend the constitution.

D.1 Why This Is Possible

The capability constraints in the constitution do not forbid shell scripting. They reshape what scripting is under the hood.

The fundamental abstraction of a shell script is "compose a sequence of commands and feed data between them." Nothing in the constitution forbids that. What changes is how composition happens.

D.2 Walking Through Bash Primitives

D.3 The Pipe Pattern

The interesting case is the pipe, because Unix pipes rely on fork and inherited file descriptors - neither of which exists.

In GodspeedOS, cmd1 | cmd2 becomes:

1. Shell creates a fresh IPC endpoint.
2. Shell grants cmd1 a SEND cap to that endpoint, via its spawn contract.
3. Shell grants cmd2 a RECV cap to the same endpoint, via its spawn contract.
4. cmd1's "stdout" is "send to the cap I was granted."
5. cmd2's "stdin" is "recv from the cap I was granted."

Pipes still exist. They are capability-mediated rather than fd-mediated.

The user-facing syntax can look exactly familiar:

ls /data | grep .txt > files.list

The shell does more capability brokerage than bash; the user sees the same thing.

D.4 The Security Upside

Capability-mediated scripting is meaningfully safer than POSIX shell by construction.

rm -rf / cannot exist on GodspeedOS unless the user (via the shell) explicitly grants the rm service a WRITE cap to /. The shell becomes the deliberate place where authority is decided. It can refuse dangerous compositions, ask for confirmation, or apply policy.

There is no equivalent of "ambient authority leaked through fork-exec and now the wrong process deleted everything."

D.5 Language Design - Open Question

The script language syntax does not fall out of the architecture. Three plausible directions:

Likely lean: modern-shell-inspired. POSIX-shell quirks exist for historical reasons that don't apply here.

D.6 What "Porting" GNU Utilities Would Actually Mean

A common assumption is that supporting Unix-style utilities means "port GNU coreutils." This is misleading.

It is not a port. It is a rewrite. GNU coreutils is hundreds of thousands of lines of POSIX-specific C. You cannot recompile it against a new libc and expect it to work, because the underlying primitives don't exist:

• No fork / exec.
• No errno.
• No POSIX signals (no SIGPIPE, SIGINT, SIGTERM handlers).
• No inherited file descriptors.
• No environment-variable inheritance.
• No process groups, sessions, or terminal control as POSIX defines them.

Each utility has to be rewritten in Rust (or whatever) against the GodspeedOS SDK. Contract per utility. Capabilities for everything it touches. IPC for what it produces and consumes.

The rewrite is genuinely simpler per-utility, however, because the OS handles the plumbing that POSIX utilities have to handle themselves:

A cat-equivalent in GodspeedOS is on the order of 30 lines of Rust. GNU cat is hundreds of lines, mostly handling POSIX corner cases that GodspeedOS doesn't have.

D.7 Realistic Expectations

The GNU community is heavily invested in POSIX. Existing GNU code is unlikely to be ported by its existing maintainers; the architectural mismatch is too large.

A more realistic scenario is a fresh community building a coreutils-equivalent for GodspeedOS from scratch in Rust, motivated by the architecture rather than by carrying forward existing code. The friendliness this appendix describes is friendliness to the rewrite, not friendliness to existing C source.

Bash compatibility is explicitly not on offer. A shell language that resembles bash superficially but is its own thing underneath is fine; pretending bash scripts will run unmodified would be a lie that bites users later.

D.8 Why This Belongs in Far-Future Scope

None of this is v1, v2, or v3 work. It is what becomes possible once:

• The kernel and TCB are stable.
• A real userspace exists (events, fs, network).
• A supervisor API for service-initiated spawn (with cap delegation) exists - currently supervisor.spawn is supervisor-internal.
• The userspace community has formed enough to have opinions on what shell language to design.

This appendix exists so that, when that time comes, the design intent is on record and the architectural reasoning is preserved.

26. Architectural Discipline

The architecture survives only if the discipline survives.

The greatest long-term risk to this system is not memory corruption, race conditions, or hardware failure.

The greatest risk is gradual architectural erosion:

• hidden complexity;
• convenience abstractions;
• implicit behavior;
• speculative extensibility;
• silent fallback paths;
• and features that weaken the model in exchange for short-term ergonomics.

This section exists to preserve the architectural mindset that produced the system.

26.1 The Model Is The Product

GodspeedOS is not merely a collection of kernel features.

The value of the system is the coherence of the model:

• explicit authority;
• bounded behavior;
• visible failure;
• typed capabilities;
• restartability;
• and identity separated from execution location.

A feature that weakens the model weakens the system, even if the feature appears useful.

The architecture itself is the product.

26.2 Features Must Be Pulled Into Existence

Features are added because:

• a constitutional invariant requires them;
• an identity test requires them;
• a real operational problem requires them;
• or a demonstrated implementation limitation requires them.

Features are not added because:

• they may be useful later;
• other systems have them;
• they feel incomplete without them;
• or they might support hypothetical future flexibility.

Speculative abstraction is architectural debt.

The preferred state of an unneeded feature is:

not implemented; will be implemented when a test requires it

Deferral is a design decision, not a weakness.

26.3 Identity Tests Define System Identity

Identity tests are not implementation tests.

They are executable constitutional invariants.

A passing identity test means:

• the implementation still matches the model;
• the guarantees in this document still hold;
• the architectural invariants still compose correctly;
• and the system is still the system this document describes.

A failing identity test is evidence of architectural drift.

If an identity test fails:

• either the implementation is wrong;
• or the constitution has changed.

There is no third category.

26.4 No Silent Complexity

Complexity must remain visible.

Reject:

• hidden retries;
• invisible caching layers;
• implicit authority escalation;
• silent transport substitution;
• transparent distributed semantics;
• automatic fallback behavior;
• convenience APIs that weaken guarantees;
• or abstractions that obscure ownership or failure.

The system should always make it possible to answer:

• where authority came from;
• where state lives;
• who owns the state;
• what failed;
• what guarantees exist;
• what the timeout boundary is;
• and what recovery obligations now exist.

If those questions become difficult to answer, the abstraction is too opaque.

Visible caching is not silent complexity. The rejection above is of invisible caches: ones that can drift and lie with no way to tell. A derived view (a cache, index, or precomputed count) is legitimate when it reduces to a single irreducible source, is reconciled when it drifts (a repair path rebuilds it from that source), and is subordinate (the source wins; the view is never authoritative). The free bitmap and free count of fs are exactly such views of the file tree: stored, but not a second truth. The line this section draws is between a visible, reconcilable derived view (allowed) and a hidden, unreconcilable one (rejected). This is Commandment III (COMMANDMENTS.md); see also §3.8 and §3.9 / Invariant 9.

26.5 Explicitness Over Magic

The system intentionally prefers explicit operations over implicit convenience.

Examples:

• explicit capability passing instead of ambient authority;
• explicit restart instead of live mutation;
• explicit remote IPC instead of transparent clustering;
• explicit reacquisition instead of silent rebinding;
• explicit queue limits instead of elastic growth;
• explicit contracts instead of inferred permissions.

This is not accidental minimalism.

It is how the system preserves mechanical honesty.

26.6 Bounded Behavior Over Optimistic Behavior

Every subsystem should have:

• bounded memory usage;
• bounded queue growth;
• bounded retry behavior;
• bounded authority;
• bounded execution scope;
• and bounded failure semantics.

Unbounded behavior eventually becomes undefined behavior under load.

If a subsystem cannot explain:

• its limits;
• saturation behavior;
• failure mode;
• and recovery strategy;

then the subsystem is incomplete.

26.6.1 Bounded memory means stack and arenas, not heap (settled direction)

The default mechanism for bounded memory is no heap. State lives in fixed stack arrays, in bounded reusable arenas (a fixed region + a bump pointer, reset between operations), or in immutable rodata - never behind a general allocator. The heap reflex is resisted by default.

This is not asceticism; it is how the bound stays visible. A fixed footprint can be read off the source - the maximum a subsystem can use is right there. There is no allocator in the trusted base to fragment, to fail in the middle of an operation, or to turn memory use into a runtime mystery. And overflow fails the GodspeedOS way: loud, into a guard page, killing one service - never a silent slide into thrashing. A heap erases each of those properties, which is why it is the exception (declared, scoped) and not the default.

When a working set feels too big for the stack, the move is not to reach for a heap - it is to change the representation so the working set is small:

• stream in fixed chunks instead of buffering the whole thing (the edit piece table holds one window of an arbitrarily large file, never the file; read/write/copy stream in IO_CHUNK pieces);
• refer to data by (offset, len) spans instead of copying it (piece spans; interned string ids in the records Table);
• give a subsystem its own named, bounded arena instead of a shared allocator (the records arena), reset between uses;
• iterate with an explicit bounded stack instead of call-stack recursion (tree's walk).

format_args! is already bounded - it does not allocate. The no-heap rule forbids a growable buffer, not lazy formatting. Building output with format_args! - and logging it with the SDK's log_fmt, which renders through a fixed 256-byte stack buffer - IS the bounded discipline, not a violation of it. Do not hand-roll digit-by-digit number formatting to "avoid the heap" that format_args! never touches; reach for log_fmt (or write! into a fixed-size array) instead. Over- applying this section - refusing the sanctioned bounded tool and reinventing it - is itself the mistake.

A hard ceiling reached loudly is therefore a feature, not a missing heap: it says "rethink the working set." (The selfcheck | write stack overflow was exactly this lesson - the fix was to forbid the unbounded nesting, not to add a heap.)

This is simplicity as much as fault tolerance (§2.3). The bounded representation is usually also the clearer one, because the constraint forces you to name the working set instead of hand-waving it onto a heap. Per §26.13 the bar is simple-and-bounded, not clever-and-cramped: a stack-only design that is harder to read than a heap one is a regression, not a win. The goal is the right data shape - a piece table, a ring buffer, an arena - over which boring code is small by construction.

26.7 Loud Failure Over Hidden Recovery

The system must prefer visible failure over ambiguous state.

A loud crash is preferable to silent corruption.

A rejected operation is preferable to undefined semantics.

A restart is preferable to hidden mutation.

A visible timeout is preferable to indefinite waiting.

A reported failed recovery is preferable to a hidden one.

The developer must never be forced to guess whether:

• an operation succeeded;
• a message was delivered;
• authority still exists;
• or the system silently degraded behavior.

The kernel boundary must remain semantically honest.

A recovery that itself fails is still a failure. Retrying, reacquiring, or falling back is the right response to a failure - but when the recovery step also fails, that outcome must remain as visible as the original failure. Proceeding as though a failed recovery had succeeded - discarding its result and continuing - converts a loud failure into a silent one and hides exactly the state an operator needs to see. Every failure path, including a retry that ultimately fails, is reported, never swallowed. This holds in any language: an ignored error return is the same silent fallback as a suppressed exception.

A limitation that cannot be closed is RECORDED, never papered over. The rule above governs what the system does at runtime; this governs what the project says about itself, and it is the same refusal to hide. Some gaps cannot be closed today - the hardware has no such unit, the fix is real work and not a constant, the honest guarantee is narrower than the one already claimed. The temptation is to leave the broader claim standing because it is nearly true. Write the gap down instead: state plainly what does NOT hold, where, and why, at the place a reader would otherwise rely on the claim.

A recorded limitation is a thing the next person can fix and can plan around. An unrecorded one is discovered by whoever trusts the document, usually at the worst moment, and it costs them the right to trust the rest of it. This is why a narrowed guarantee is amended into the text rather than quietly left; §6.1's backend-conditional crash-recovery claim and its ARM DMA posture are both here for exactly this reason.

26.8 Identity Over Location

Services are identities, not placements.

Core assignment is an execution detail.

Node assignment is an execution detail.

The location of execution may change across restart boundaries without changing system identity.

The architecture must continue to separate:

• who a service is;
• from where a service currently executes.

Location is mutable. Identity is stable.

26.9 Authority Must Remain Visible

Authority should always be inspectable and traceable.

A reviewer should be able to determine:

• what a service can do;
• where the authority came from;
• which capability granted it;
• and whether the authority can be revoked.

No subsystem may gain authority through:

• process ancestry;
• ambient inheritance;
• hidden globals;
• implicit trust;
• or side effects.

Authority is granted deliberately or not at all.

26.10 The Kernel Is Mechanism, Not Policy

The kernel exists to enforce invariants, not interpret intent.

The kernel provides:

• isolation;
• scheduling;
• capability enforcement;
• IPC routing;
• memory protection;
• interrupt routing;
• and bounded primitives.

The kernel does not:

• guess developer intent;
• silently reinterpret contracts;
• optimize correctness away;
• or make policy decisions on behalf of services.

Policy belongs in services.

Mechanism belongs in the kernel.

26.11 Understandability Is A Hard Requirement

The system must remain understandable by a single engineer.

The "30-minute whiteboard rule" is mandatory:

• a contributor should be able to explain the architecture,
• the capability flow,
• the restart model,
• the IPC semantics,
• and the failure model

on a whiteboard in roughly 30 minutes.

If understanding requires:

• tribal knowledge;
• hidden runtime behavior;
• undocumented interactions;
• or layered abstractions across dozens of components;

then the system has exceeded its acceptable complexity budget.

26.12 Correctness Before Performance

Performance matters.

Correctness matters more.

Predictability matters more than peak throughput.

The system intentionally accepts:

• extra copies;
• extra validation;
• explicit synchronization;
• and visible restart boundaries

when they preserve architectural clarity and bounded correctness.

Optimization is permitted only when:

• invariants remain visible;
• failure semantics remain unchanged;
• observability is preserved;
• and the resulting system is no harder to reason about.

26.13 Discipline Over Cleverness

Clever code is not an achievement if it weakens the model.

The preferred implementation is:

• boring;
• explicit;
• inspectable;
• testable;
• restartable;
• and mechanically honest.

The system should resist:

• abstraction for its own sake;
• framework-style indirection;
• meta-programming layers;
• hidden runtime behavior;
• and architecture driven by novelty.

A smaller coherent system is preferred over a larger impressive one.

26.14 Borrow The Mechanism, Never The Model

Reference implementations are how this project learns hardware. Linux, BSD and u-boot are read as executable datasheets: which register the silicon needs written, in what order, with what value, and what the device does when you get it wrong. That reading is encouraged and has repeatedly been the difference between a working driver and a week of guessing.

What is borrowed is the SILICON'S requirement. What is not borrowed is the other system's model.

Those two are easy to confuse, because they arrive in the same file. A register write sequence is a fact about the hardware and belongs here unchanged. An ambient global, an unbounded buffer, a heap allocation on a hot path, a driver living in the kernel because that is where the reference put it - those are that system's answers to that system's constraints, and they are not facts about anything. Importing them because "Linux does it" is how a model rots while every individual change looks justified.

The test is one question: is this a property of the device, or a property of their design? Ordering, timing, magic values, error semantics, what a bit means - the device. Where the state lives, who owns it, how it is allocated, what happens when it fails - ours to decide, under the constitution.

Divergence from a reference is therefore normal and does not need apologising for; it needs recording. When this system deliberately does something differently, say so at the point of difference and say why, so the next reader knows it was a decision and not an oversight. Silent divergence is how a port acquires bugs nobody can explain; unexplained convergence is how it acquires violations nobody noticed.

26.15 Preserve The Invariants

Every contributor is responsible for preserving:

• identity over location;
• explicit authority;
• bounded behavior;
• typed capabilities;
• failure visibility;
• restartability;
• and no silent fallback.

If a proposal weakens those principles, the burden of proof is on the proposal.

The default answer to architectural uncertainty is:

• simplify;
• reduce scope;
• make the behavior explicit;
• and preserve the invariants.

26.16 Final Reminder

The system is allowed to evolve.

The model is not allowed to rot.

Every feature, abstraction, optimization, and subsystem must justify its existence against the constitution.

If the implementation becomes easier to extend but harder to reason about, the system has regressed.

Correctness is not enough.

The architecture must remain coherent.

The Ten Commandments of Godspeed

These Commandments define the architectural boundaries of Godspeed. They are not coding guidelines or stylistic preferences. They exist to preserve a system that remains simple, recoverable, and understandable as it grows.

They are the human-readable distillation of the constitution in CLAUDE.md - each is grounded in the invariants and sections it enforces. Where a Commandment and the code disagree, the code is wrong (CLAUDE.md §1). Where a Commandment and the constitution disagree, the constitution is the law and this document is amended to match.

For a catalog of concrete violations of these Commandments - each paired with the correct pattern and grounded in the section it breaks - see docs/anti-patterns.md, the field guide to constitutional violations.

Respect Godspeed

I. Thou shalt not expand the responsibilities of the kernel. It is complete. Use a service.

The kernel's responsibilities are complete: memory isolation, scheduling, IPC, capability enforcement, interrupt routing, and cross-core routing - and nothing else. New hardware support, new CPU architectures, and bug fixes are welcome. New responsibilities are not.

Before proposing a kernel change, ask: "Why isn't this a service?" If the answer is "because it is more convenient," it belongs outside the kernel.

Why the kernel stays tiny - and why that boundary is a reward, not a restriction.

The kernel is audited regularly and exhaustively against these Commandments (the living record is audits/kernel-audit.md).

The cost of that audit does not grow linearly with the kernel - it grows with the interactions between its responsibilities. A real audit never examines each responsibility in isolation; it cross-checks every responsibility against every other, looking for shared state, lock ordering, fault propagation, hidden assumptions, and the cracks between subsystems where the most dangerous bugs emerge.

Every new responsibility therefore creates more than additional code. It creates additional interactions that must be understood, verified, and trusted. In practice, N responsibilities produce roughly N² relationships to reason about.

A tiny kernel can be audited end-to-end. Its guiding promise - that nothing above it may panic or wedge it - can be continuously verified rather than merely hoped for. Add one more responsibility, and the increase in trust required is far greater than the increase in code.

A bounded kernel is therefore not a limitation imposed on the architecture. It is the property that makes the architecture continuously auditable, and therefore trustworthy. Every responsibility refused permanently reduces future audit effort, shrinks the privileged attack and failure surface, and keeps the kernel's guarantees affordable to verify.

Refuse responsibility, and be rewarded.

Grounded in: §4.3-§4.4 (kernel scope and anti-scope), §26.10 (the kernel is mechanism, not policy), §26.11 (understandability is a hard requirement - the 30-minute whiteboard rule), §22 (the identity/audit suites that keep the guarantee executable), Invariant 4 (the kernel remains tiny).

II. Thou shalt love Chaos and trust in it. Thy service shall pass through Maximum Carnage.

Passing unit tests does not prove correctness. Every service shall eventually face failure, memory pressure, restart storms, spawn storms, queue floods, and whatever new forms Chaos invents.

If Chaos finds a bug, the bug already existed. Treat Chaos as your teacher, not your enemy.

Grounded in: §22 (the identity, stress, adversarial, and chaos suites - and chaos max-carnage), §2.3 (execution over theory), §26.7 (loud failure over hidden recovery).

III. Thou shalt not duplicate truth. Store irreducible facts. Derive the rest.

There must be exactly one irreducible source of truth - the minimal state from which everything else can be reconstructed, and which cannot itself be reduced to anything smaller. Everything else is a derived view of it.

This is not a ban on caches, indexes, or precomputed counts. A derived view may be stored, and may even drift, provided it is reconstructible from the source, reconciled when it drifts (a repair path rebuilds it from the source), and subordinate - on any disagreement the source wins; the view is never authoritative. A filesystem's free bitmap is a stored index of its file tree (fsck rebuilds it from the tree); the free count is a stored index of the bitmap. Neither is a second truth - both reduce to the tree.

What is forbidden is a second irreducible truth: two stored facts that can diverge with no way to decide which is right, or trusting a derived view as if it were the source. The test is not "is it stored?" nor "can it drift?" - it is "does it reduce to one source, and does that source win?"

Grounded in: §3.8 (state explicit and owned), §3.9 / Invariant 9 (no unowned global mutable state), §26.4 (caching must be visible and reconcilable, never hidden).

IV. Thou shalt honor service contracts.

Services communicate through explicit contracts. Do not bypass a contract. Do not invent hidden communication paths. If a service cannot express its needs through its declared contract, redesign the contract - not the architecture.

Grounded in: §13 (service contracts), §3.7 / Invariant 7 (contracts are enforced, not interpreted), §13.6 (runtime enforcement from the SPAWN REQUEST at spawn; the contract is the build-time declaration reconciled against it, never the runtime source - amended 2026-09-14).

V. Thou shalt not assume thy service is special. Only the kernel is special.

Every service must be prepared to fail. Every service must be prepared to restart. No service is exempt. If the Supervisor itself must survive its own death - and it must, for the kernel respawns it

• so must yours.

The only unkillable component is the kernel. Everything above it is identity, not location, and identity survives restart.

Being unexceptional cuts both ways. Just as no service is too important to restart, none is too important to admit when it could not recover. When a service tries to recover from a failure - a retry, a reacquire, a fallback - and that recovery itself fails, the failure is still a failure: surface it. A recovery whose own failure is discarded becomes a silent success, and the service then proceeds on a state it never actually reached - the very hidden failure this system forbids. Recover if you can; when you cannot, say so plainly.

Grounded in: §6.2-§6.3 (the supervisor is restartable; the unkillable set is {kernel} alone), Invariant 6 (services must be restartable), Invariant 11 (identity is stable; location is not), §26.7 (loud failure over hidden recovery), Invariant 12 (failures are loud, never silent).

Corrupt Not Godspeed

VI. Thou shalt not introduce shared mutable state.

Services communicate through IPC. Shared mutable state creates invisible coupling, destroys isolation, complicates recovery, and makes failure unpredictable. If multiple services require the same information, expose it through a service - not through shared memory.

Grounded in: Invariant 2 (no shared mutable memory by default), Invariant 9 (no unowned global mutable state), §2.5 (zero-copy IPC is permanently rejected for this reason).

VII. Thou shalt not introduce ambient authority.

Authority must always be explicit. A service may perform only the actions its capabilities grant. Hidden privilege eventually becomes both a security vulnerability and an architectural dependency.

There is no authority by identity, ancestry, or inheritance - only by capability.

Grounded in: Invariant 1 (no ambient authority), Invariant 3 (all authority is explicit), §7 (the capability system), §26.9 (authority must remain visible).

VIII. Thou shalt not rely upon timing for correctness. Wait for truth, not time. But ensure the truth includes failure.

Time does not prove correctness. Sleeping longer does not make a race disappear. Correctness must come from observable truth:

• acknowledgements
• state transitions
• contracts
• events
• capabilities (and their generations)

Time may conserve CPU. It must never determine correctness.

And the truth must include failure. Waiting on the truth of success alone - the reply, the acknowledgement - is only half the discipline. If the thing you wait for dies or never comes, that truth never arrives and a pure success-wait hangs forever: a wait that cannot observe failure has quietly become an infinite wait on time. So failure is a first-class truth - a peer's death, a dead endpoint, a broken contract, a revoked capability - and you must wake on it exactly as you would on success. A caller blocked awaiting a reply must wake the instant its replier dies (ReplyDead), never hang. Only a truth that includes failure makes "wait on truth" complete.

Grounded in: §8.6 (acknowledgement is explicit - a successful send means queued, not processed; and failure is explicit - a caller blocked awaiting a reply wakes with ReplyDead when its replier dies), §7.5 (the generation check, not a delay, settles a restart race), §9.3 (yield is advisory), §22.4 (a test waits for observable output, never a fixed sleep).

IX. Thou shalt always plan for recovery, for thy service shall fail.

Failure is not exceptional. It is expected. Every service should recover cleanly without assuming a perfect world. A client whose dependency restarts must reacquire and retry, not crash.

And reacquiring is not just the endpoint. Anything the dependency's previous incarnation handed you - a connection or socket id, a handle, a cached value, a generation - is stale once it restarts, and must be re-established with the new instance or discarded. A fresh connection does not refresh what the dead one gave you; a cached view of a restarted peer's state is no longer the truth.

If recovery cannot be tested, it does not exist.

Grounded in: §14 (service lifecycle, restart, and cap rebinding), §14.3 (cascading failure is the client's responsibility), §6.2 (death is recovered, not a reboot), §22 (recovery is pinned by the chaos and identity suites).

X. Thou shalt place complexity where it belongs.

Complexity is sometimes necessary. Hidden complexity never is. Do not move complexity into the kernel because it is convenient. Do not push complexity onto users because it is easier. Place it in the layer that naturally owns it.

Good architecture is not the absence of complexity. It is complexity in the correct place.

Grounded in: §26.10 (the kernel is mechanism, not policy), §26.11 (the 30-minute whiteboard rule), §26.13 (discipline over cleverness), §26.4 (no silent complexity).

Final Admonition

These Commandments are not independent. Violate one and you eventually violate all.

Architectural corruption rarely begins with catastrophe. It begins with a single compromise:

"Just this once."

Over time, that compromise spreads in subtle and unpredictable ways until the architecture itself becomes difficult to reason about.

These Commandments were not written for style, tradition, or amusement. They were written in response to real bugs, real wedges, real failures, and real lessons learned while building Godspeed.

Treat them very seriously.

And when a compromise offers itself because the system does not yet work, know which way the trade goes:

A failing Godspeed that preserves its invariants is preferable to a working Godspeed that violates them.

This is not a love of failure. It is what a fix IS. A system that fails with its model intact is still Godspeed, and can be repaired. A system that works by breaking its model is another system wearing the name, and it has spent the only thing that made the rest of this document worth obeying.

So make it work WITHIN the model. Never widen the model to admit what is easier. And where the two truly cannot be reconciled, say so plainly and leave the gap open, for a recorded failure can be fixed by whoever comes next, and a quiet violation cannot even be found.

Grounded in: CLAUDE.md §25 (the principle that ranks the others) and §26.7 (a failure is reported, never swallowed - so a limitation that cannot be closed today is RECORDED, not papered over).

Of Borrowed Wisdom

Thou shalt read the works of others, for they have met this silicon before thee. Linux, BSD and u-boot are read here as executable datasheets, and that reading has many times been the difference between a working driver and a week of guessing.

But take from them the requirement of the DEVICE, and never the shape of THEIR HOUSE.

Both arrive in the same file, and only one of them is a fact:

• Take the order of writes, the timing, the magic values, the error semantics, the meaning of a bit. These are properties of the hardware and are true wherever they are read.
• Leave the ambient global, the unbounded buffer, the allocation on the hot path, the driver that lives in the kernel because that is where they put it. These are their answers to their constraints, and they are facts about nothing.

When in doubt, ask one question:

Is this a property of the device, or a property of their design?

To copy their design because they are respected is how a model rots while every single change looks justified. Where thou dost diverge from them, do not apologise - RECORD it, at the point of difference, with the reason. Silent divergence breeds bugs no one can explain; unexplained convergence breeds violations no one noticed.

Grounded in: CLAUDE.md §26.14. See also §26.6.1 - when their answer is a heap and thine cannot be, change the representation rather than the rule.

Tried by Fire

A contribution is not considered proven until it has passed through the fire.

The fire of Godspeed consists of seven complementary trials:

1. Identity - Does it remain itself?
2. Property - Does it preserve its invariants?
3. Fuzz - Does unexpected input reveal hidden assumptions?
4. Stress - Does pressure change correctness?
5. Performance - Does it remain efficient under sustained load?
6. Adversarial - Can deliberate attack break its guarantees?
7. Chaos - Can it recover when the unexpected becomes reality?

Each trial has increasingly brutal variants. Passing one trial does not excuse failing another.

Grounded in: §22 - these seven are the categories of the test suite: the Identity tests and the six battle-hardening layers, each with a harsher "brutal" variant. A green check from one trial is necessary; it is never sufficient. This is Commandment II made into a gauntlet.

Blessings

Godspeed on thy journey.

• May thy architecture remain uncorrupted.
• May thy contracts remain true.
• May thy services endure failure.
• May truth be uncovered through fire.

Bankole Ogundero.

GLOSSARY.md

Abbreviations and Acronyms of GodspeedOS

This file expands the abbreviations and acronyms that appear across the GodspeedOS codebase, specification, and docs, with a one-line meaning grounded in how the project actually uses each one.

It is deliberately scoped to abbreviations and short forms. For architectural terms (capability, endpoint, generation, placement, routing table, supervisor, name directory, delegated resource capability, TCB, and so on) the authority is the Glossary in CLAUDE.md section 24 - read that for the prose definitions of the model itself. Where this file and CLAUDE.md disagree, CLAUDE.md wins.

Only abbreviations the repository genuinely uses are listed. Each was verified by grep before inclusion.

The table below is also read by a program: ask "what is MISCIS?" answers from it, read when ask is built (services/ask/build.rs), so a row's shape - three cells, the abbreviation first - is load-bearing, and a definition has one copy, this one.

Alphabetical list

Naming schemes

A few families of identifiers are easier to understand as a scheme than as a list. Rather than enumerate every one, here is what each prefix means.

Amendment and program IDs (in CLAUDE.md)

- H-prefix (H1, H4, H11, ...) - numbered hardening / security amendments to the constitution. Each closes a specific gap with a written rationale. H1 = IOMMU DMA-confinement (closes the DMA hole in invariant 1); H4 = kstack-guard / W^X hardening; H11 = making registry a restartable userspace service (it left the TCB). - P-prefix (P2) - a feature/persistence amendment. P2 = file-as-capability (delegated resource capabilities, section 7.10). (Note: P1-P10 separately label the property tests - see below; context disambiguates.) - "Path C" - the chosen end-state of the naming-out-of-kernel redesign (docs/naming-design.md section 3.7): name policy lives in the supervisor while the kernel keeps only a minimal gated recovery directory. - Phases (Phase 4, Phase 5, Phase 6, Phase D, ...) - the ordered implementation steps within an amendment program. For example, in Path C: Phase 4 retires the registry service, Phase 5 removes init, Phase 6 makes the supervisor restartable; the "Phase D" amendment dropped block-driver and fs from the TCB once fs gained crash-consistent recovery.

Test-suite IDs (CLAUDE.md section 22, tests/qemu/)

The identity suite numbers its constitutional tests (Test 1 ... Test 15). The battle-hardening categories use a letter prefix plus a number:

- (Identity) - Tests 1-15, the executable constitution; a failure is a constitutional violation. - P - Property tests (P1-P10): universal invariants under randomized inputs. - F - Fuzz tests (F1-F8): the kernel must never panic on user-controllable input. - S - Stress tests (S1-S10): no drift, leak, or corruption under sustained load. - B - Performance Benchmarks (B1-B10): latency/throughput numbers tracked against a baseline. - BP - the Brutal Perf variant of the benchmarks (BP1-BP10): the same metrics run in a contended "perf-brutal" build, the form quoted in the hardware results table. - A - Adversarial / red-team tests (A1-A10): capability isolation under direct attack. - C - Chaos tests (C1-C7): graceful degradation under partial failures. - "brutal" - in general, the harsher contended variant of a suite (e.g. perf-brutal).

The name directory

Not an abbreviation but worth stating once: the name directory is the kernel's minimal name -> EndpointId map (ipc::names) plus a gated "mint a SEND cap by name" call (AcquireSendCap). It is the bounded recovery anchor that replaced the retired registry service (Path C / Phase 4): the supervisor wires services from a name -> cap map, and clients reacquire a service by name through this directory after a restart.

Amendment shorthand

CLAUDE.md and the docs refer to past amendments by short codes. This decodes the common ones; each is defined in full at its cited section.

Hardware and Systems Abbreviations

The short forms that appear throughout the kernel, the drivers, and the design docs. Each is listed because the repository genuinely uses it (verified by grep), and defined by how GodspeedOS uses it - not by its most general industry meaning. Architectural terms remain the province of CLAUDE.md section 24; these are the abbreviations you meet while reading the code.

CPU, interrupts, and time

- ARM - Advanced RISC Machines: the instruction set family GodspeedOS runs on besides x86_64. Two ports exist and they are genuinely different machines, not one with a flag: arm32 (ARMv7-A, Raspberry Pi 2, four Cortex-A7 cores) and AArch64 (ARMv8-A, Raspberry Pi 4). Each brings its own boot path, its own USB host controller, and its own timer. - APIC - Advanced Programmable Interrupt Controller. The interrupt hardware the kernel drives for timers and inter-core signalling. - LAPIC - the local APIC, one per core. Owns that core's timer and receives its interrupts. - IOAPIC - the I/O APIC: routes device interrupt lines (legacy INTx) to a core's vector. - LVT - Local Vector Table. The LAPIC registers that say which vector a local source (e.g. the timer) raises, and whether it is masked. - ISR - Interrupt Service Routine: the handler that runs when a vector fires. - IRQ - Interrupt ReQuest: a device's interrupt line or its assigned vector. - IPI - Inter-Processor Interrupt: one core interrupting another (used for wakeups and TLB shootdown). See also CLAUDE.md section 24. - NMI - Non-Maskable Interrupt: reaches a core even with interrupts disabled, which is why the panic path uses it to halt every core (SEC-18). - MSI / MSI-X - Message Signalled Interrupts: a device raises an interrupt by writing a message rather than asserting a pin, so it can be targeted at a chosen core. - TSC - Time Stamp Counter: the CPU's cycle counter. TSC-Deadline is a one-shot timer mode armed by writing a deadline; the kernel re-arms it every tick. - PIT - Programmable Interval Timer (i8254). Legacy but portable, so it is the ground truth the kernel calibrates the TSC and the LAPIC timer against. - ARAT - Always Running APIC Timer: a CPU flag meaning the LAPIC timer keeps ticking through deep C-states. Without it, halting an idle core can drop its wakeup. - C-state - a CPU idle power state. Deeper states save more power but can power-gate the APIC. - RTC / CMOS - the battery-backed real-time clock; the wall-clock source (date, uptime, and any pacing that must not trust the TSC). - SMP - Symmetric MultiProcessing: multiple cores running the same kernel.

Memory and addressing

- MMIO - Memory-Mapped I/O: device registers accessed as memory rather than I/O ports. - DMA - Direct Memory Access: a device reading or writing RAM itself. Unconfined DMA is kernel-equivalent power, which is why section 6.4 treats it so carefully. - IOMMU - I/O Memory Management Unit: translates and confines device DMA, so a driver's device reaches only its granted arena (H1). - TLB - Translation Lookaside Buffer: the CPU's cache of page-table translations; a stale entry must be shot down across cores. - CR3 - the x86 register holding the current address space's page-table root. - PML4 - the top-level x86-64 page table. - HHDM - Higher-Half Direct Map: all physical memory mapped at a known high virtual base, so the kernel can reach any frame without a temporary mapping.

Buses, devices, and storage

- PCI - the device bus the kernel enumerates. BDF = Bus/Device/Function, a device's address on it. - AHCI - the SATA controller interface the block driver drives. SATA is the disk interface itself. - USB - Universal Serial Bus. xHCI is the USB 3 host controller, EHCI the USB 2 one. - HID - Human Interface Device: the USB class for keyboards and mice. - qTD / QH - EHCI queue Transfer Descriptor and Queue Head: the DMA structures describing a USB transfer and the endpoint queue it belongs to. - NIC - Network Interface Controller. - UART - the serial port hardware behind the console (COM1) and the test control channel (COM2).

Boot, formats, and files

- UEFI / BIOS - the two firmware styles a machine may boot with. ESP = EFI System Partition, the FAT32 partition holding the bootloader. - GPT / MBR - GUID Partition Table and Master Boot Record: the two partition-table formats. - ELF - Executable and Linkable Format: the binary format of the kernel and every service. - GSFS - the GodspeedOS filesystem (GSFS0008). - CRC - Cyclic Redundancy Check: the checksum guarding superblocks, directories, and data blocks.

Networking

- TCP / UDP - the transport protocols. ICMP carries ping. ARP resolves an IP to a MAC. DHCP leases an address; DNS resolves names.

Tooling

- QEMU - the emulator used for development. TCG is its software (no-virtualisation) engine; KVM is hardware-accelerated virtualisation. - SDK - sdk/rust, the crate every service links against. - POSIX - the Unix interface standard GodspeedOS deliberately does not implement (section 2.2, Appendix B.3).

Buses and devices

- PCIe - PCI Express. Electrically different, same configuration model, so the same class-code lookup finds a device on either. The Pi 4 reaches its USB controller this way. - BDF - Bus/Device/Function: the three numbers that name one device on a PCI bus, packed here as (bus << 8) | (dev << 3) | func. It is an identifier, not an address - the kernel reads that device's own registers to learn what it is worth. - BAR - Base Address Register. Where a device's registers live in memory. Which BAR holds them is a property of the device, not its class: an xHCI uses BAR0, an AHCI controller uses BAR5. - SMMU - the ARM name for an IOMMU. Neither Raspberry Pi wires one up, which is recorded rather than glossed over. - INTx - the legacy PCI interrupt pin. Routed through the IOAPIC and, on this hardware, deliverable only to the boot processor - which is why the EHCI driver is pinned to core 0. - SoC - System on Chip. A controller soldered into the processor package rather than sitting on a bus, so no scan can find it: the Pi 4's ethernet is one, and is asked about separately.

Storage

- SATA - the drive attachment the T630 and Wyse boot from. - SSD - solid-state drive. - LBA - Logical Block Address: which 512-byte sector, counted from zero. The unit of the block protocol between fs and block-driver. - PIO - Programmed I/O: moving data through CPU register reads and writes instead of DMA. Slower, and needs no DMA authority at all. - MSC - USB Mass Storage Class: how a USB stick presents itself, driven over BOT. - BOT - Bulk-Only Transport: the command wrapper (CBW), data, status (CSW) sequence that carries SCSI commands over USB bulk endpoints. - SCSI - the command set inside those wrappers (READ(10), WRITE(10), INQUIRY).

USB

- xHCI - the USB 3 host controller interface. Class code 0x0C0330 everywhere, forever, which is what lets a driver name its device without the kernel being taught what one is. - EHCI - the USB 2 host controller interface (0x0C0320). Present on the T630, absent on the Wyse - both cases are exercised. - DWC2 - the DesignWare USB 2 controller in the Raspberry Pi 2. One controller carrying the keyboard, the disk and the network at once. - TRB - Transfer Request Block: one 16-byte entry on an xHCI ring - a command, a data stage, or a completion event. A completion event carries the address of the TRB it completes, which is what lets a reply be matched to the request that asked for it rather than merely to the same slot. - PHY - the physical-layer chip that actually drives the wire, addressed through MDIO. - MDIO - the two-wire management bus used to read and write PHY registers.

Serial, display, and boot

- PL011 - the ARM UART on both Raspberry Pis. On the Pi 4 the firmware routes it to Bluetooth unless dtoverlay=disable-bt says otherwise, which is why that line is in the boot config. - FIFO - the small hardware queue in front of a device, 16 bytes deep on the PL011. Writing past a full one drops bytes, so every write polls first. - ANSI / CSI - the escape sequences a terminal interprets for colour and cursor movement. Handled by the console service; the kernel's boot floor discards them deliberately. - ESP - EFI System Partition: the FAT partition UEFI firmware loads a bootloader from. - BSP / AP - Bootstrap Processor and Application Processor: the core that starts first, and every other core it then brings up. - EL0 / EL1 - AArch64 exception levels: user code and kernel code respectively.

Networking

- MAC - the six-byte hardware address of a network interface. - IP - Internet Protocol: the addressing net-stack routes on, alongside the TCP and UDP transports it speaks. - ARP - Address Resolution Protocol: finds the MAC address for an IP address. - ICMP - the protocol ping uses. - DHCP - how the machine is given an address when it comes up. - DNS - name resolution. - SNTP - the time protocol the clock is set from on a machine with no RTC. - RX / TX - receive and transmit, the two directions of a network ring.

The system

- IPC - Inter-Process Communication: the message passing that every operation in this system crosses. Synchronous, copied by the kernel, bounded queues, and always under a capability. - TCB - Trusted Computing Base: the parts whose compromise compromises everything. Here it is the kernel alone, plus DMA-capable drivers on a machine with no IOMMU. - ABI - the calling convention a service and the kernel agree on at the syscall boundary. - API - the operations one component offers another. - CPU / RAM - processor and memory.

The Almanac of GodspeedOS - A History of Understanding

What this is. Not a changelog. Git already records what changed and when; this records why the thinking changed. Every entry below pins a date to a realization - a thing the project came to understand that it had not understood the day before - and then names the principle, commandment, or design decision that the realization produced. It is the intellectual history of the system, told backward from the rules to the days that earned them.

It is a record, rarely touched - a reflective document to look back on, not a living one. For the law, read CLAUDE.md; for its distillation, read COMMANDMENTS.md. This file is the answer to the question a contributor eventually asks at a whiteboard: "Why is it written that way?" The dates are real, anchored to commits and to the dated amendments in the constitution. The reasons are the part worth keeping.

Contents

• 2026-05-08 - The day the screen first said the machine was alive
• 2026-05-09 - The day the nouns became verbs
• 2026-05-10 - The day two services talked across a boundary
• 2026-05-12 - The day a service died and came back
• 2026-05-21 - The day the model met a real machine
• ~2026-05-30 - The day the thin client taught me about real concurrency
• 2026-06-09 - The day a trusted service stopped being trusted (H11)
• 2026-06-12 - The day I found kernel-equivalent power hiding in a driver (H1)
• 2026-06-17 - The day a crash stopped meaning a reboot (Phase D)
• 2026-06-18 - The day a file became a real capability (P2)
• 2026-06-20 to 2026-06-21 - The day I deleted the registry and learned what is truly irreducible
• 2026-06-21 - The day nothing was allowed to be unkillable but the kernel
• 2026-06-21 - The day Maximum Carnage was born
• 2026-06-22 to 2026-06-28 - The days Carnage found the wedges no one would write by hand
• 2026-06-25 - The day I wrote the constitution down as ten lines
• 2026-06-29 - The day the examples had to teach the truth
• 2026-06-30 to 2026-07-01 - The day "wait on truth" turned out to be half a truth
• 2026-07-03 - The day the shell became a language, and a 10 MB script was a non-event
• 2026-07-04 - The day the system survived a million acts of violence
• 2026-07-04 - The day gsh was finished, and never once reached for a heap
• 2026-07-04 - The day a private discipline became a public one
• 2026-07-04 - The day it shipped, and called itself 0.1
• 2026-07-07 to 2026-07-08 - The day the wire became location
• 2026-07-09 - The day half a truth came back for the mount loop
• 2026-07-09 - The day recovery became a fixed point
• 2026-07-10 - The day the kernel met a second architecture, and fit the machine it found
• 2026-07-11 to 2026-07-13 - The days the whole system stood for audit
• 2026-07-14 - The day the boundary became something a machine enforced
• 2026-07-14 - The day one kernel booted three instruction sets in QEMU virt
• 2026-07-25 - The day the second architecture stopped being a demonstration
• 2026-07-27 - The day a stick swap ended the hunt, and the recovery earned its keep
• 2026-07-31 - The day I learned what my instruments could not see
• 2026-08-09 to 2026-08-12 - The day the kernel gave up the USB stack, and then gave up the choice
• 2026-08-17 to 2026-08-29 - The day the terminal left the kernel, and I learned what earns ring 0
• 2026-09-03 to 2026-09-04 - The day the kernel stopped interpreting the bus
• 2026-09-05 to 2026-09-06 - The day five bugs stood in a line, each hiding the one behind it
• 2026-09-06 - The day the second core stopped being an answer
• 2026-09-12 to 2026-09-13 - The day "it boots" stopped being the standard
• 2026-09-13 to 2026-09-14 - The day the enforcement layer was pointed at itself
• 2026-09-26 to 2026-09-27 - The day a rule nobody could read stopped counting as enforced
• 2026-09-27 to 2026-09-28 - The day the radio scanned the room
• 2026-09-29 to 2026-09-30 - The day the radio joined, and the cable learned to step aside
• 2026-09-30 to 2026-10-02 - The day the warm chip turned out to be a slow host
• 2026-10-15 to 2026-10-19 - The day the machine learned to trust what it fetched
• The Days I Was Wrong
  • ~2026-06-21 - The day the constitution rejected its author
  • ~2026-06-27 - The day I reached for a heap
  • 2026-06-28 - The day my own test lied to me
  • 2026-07-25 - The day I tuned against a number the disk was writing
  • 2026-09-06 - The day I read a zero that had never been measured
• The Named Bugs - the teachers

2026-05-08 - The day the screen first said the machine was alive

The repository opened, and by the end of the day the kernel booted to a steady state under QEMU - Limine handoff, serial, GDT, IDT - after two x86 correctness bugs were found and fixed in the same sitting.

What I came to understand: a boot is not a feature you add; it is a fact you either observe on the wire or you do not have. The very first thing built was not the kernel - it was the ability to see the kernel: serial output before anything else.

What it produced: the instinct that became failures are loud, never silent (Invariant 12) and Commandment VIII's deeper sibling - wait for truth, not time. From day one, progress was something the serial console showed, never something assumed.

2026-05-09 - The day the nouns became verbs

In a single push the kernel gained a frame allocator and page tables, a preemptive scheduler, capability enforcement with generation checks, and synchronous IPC.

What I came to understand: the constitution's vocabulary - capability, generation, endpoint, quantum - was not description; each word had to be a mechanism or it was a lie. A "capability" that is not checked on every syscall is just a number.

What it produced: the discipline behind Commandment VII (no ambient authority) and the §7 capability model - authority is the cap you hold and the generation it carries, validated every single time, never inferred from who you are.

2026-05-10 - The day two services talked across a boundary

Cross-core IPC came up after a stack overflow and a silent-exception halt were chased down, and the first user-space service ran in ring 3: an ELF loaded, spawned, and logging through a syscall.

What I came to understand: the moment code crossed the kernel boundary, the kernel's job stopped being "do the work" and became "route, isolate, and enforce." A service is not a privileged part of the kernel that happens to live elsewhere; it is an untrusted identity the kernel mediates.

What it produced: Commandment I (the kernel is complete; use a service) and §26.10 (the kernel is mechanism, not policy). The line drawn that day - work lives in services, the kernel only mediates - never moved.

2026-05-12 - The day a service died and came back

The v1 milestone met its bar: ping on core 0, pong on core 1, a message across the boundary, pong killed, the supervisor restarting it, the system continuing.

What I came to understand: the headline was never "two services talk." It was "one can die and the other does not care, because it talks to a name, not a place." A client that saw EndpointDead, looked the name up again, and resumed had just demonstrated the whole philosophy in miniature.

What it produced: Invariant 11 (identity is stable; location is not) made concrete, and the seed of Commandment IX - recovery is the client's job, and a restart is normal, not exceptional.

2026-05-21 - The day the model met a real machine

GodspeedOS booted on real x86_64 hardware via UEFI USB (CLAUDE.md §23.3). The bring-up machine was a Dell Wyse 5070 thin client - the Intel J5005 (Goldmont+) of the first performance tables. Four cores up, cross-core ping/pong running on metal.

What I came to understand: QEMU is a model of a machine, and a model is a place where bugs hide politely. Real silicon does not round off the corners. A thing is not "done" because it is green in emulation.

What it produced: the standard that would later harden into Commandment II - chaos and correctness are judged on hardware - and the habit of treating a clean QEMU run as a hypothesis, not a verdict.

~2026-05-30 - The day the thin client taught me about real concurrency

On the Wyse, bare-metal boot froze shortly after the supervisor came up, and a cross-core reply-to-the-BSP path stalled hard under load. The diagnosis (bugs/1_FINDINGS_AP_TO_BSP_IPI.md, 2026-05-30): core 0 wedged with interrupts disabled, so a sender blocked on recv on the BSP was never woken. Development moved to the HP T630 (AMD GX-420GI, Jaguar/Puma+, 4 cores), the permanent SMP test machine thereafter.

What I came to understand: concurrency bugs are not abstract; they are specific to the silicon that exposes them. The J5005's stall was not a flaky machine - it was the machine telling the truth about an IF=0 wedge that QEMU and a friendlier CPU had both forgiven.

What it produced: the conviction behind Commandment VIII (rely on observable truth, not timing) and a permanent test rig on hardware that does not forgive. Cross-core correctness is only honest on a machine willing to deadlock you.

2026-06-09 - The day a trusted service stopped being trusted (H11)

registry became a real user-space name service holding only delegated caps, so its death degraded name resolution temporarily instead of corrupting the system - and it left the Trusted Computing Base (CLAUDE.md §6.1, Amendment 2026-06-09).

What I came to understand: "trusted" had been doing two jobs at once - "holds authority" and "cannot be allowed to die." Those are different claims, and conflating them is how a TCB quietly grows.

What it produced: the first real motion of the TCB-shrink program, and the early form of Commandment V - no service is special. A name service that resolves a stable name is itself just an identity, replaceable like any other.

2026-06-12 - The day I found kernel-equivalent power hiding in a driver (H1)

IOMMU DMA-confinement landed (CLAUDE.md §6.4, Amendment 2026-06-12). A DMA-capable driver, confined, reaches only its granted arena; the trust posture - confined or trust-critical - is now printed at boot.

What I came to understand: the very first invariant, no ambient authority, had an unstated exception I had never written down. A driver could aim its controller's DMA engine at any physical address - reach the capability model never granted, granted instead by physics. The model said "no ambient authority" while a USB driver quietly held the most ambient authority in the machine.

What it produced: the amendment that closed the gap in Invariant 1, and Commandment VII made literal at the hardware edge - authority must be visible, so the posture is a boot fact, not a hidden assumption. A silent exception to an invariant is worse than no invariant, because it lies.

2026-06-17 - The day a crash stopped meaning a reboot (Phase D)

With a crash-consistent redo-journal and recovery-on-mount, fs and block-driver became restartable and left the TCB (CLAUDE.md §6.1, Amendment 2026-06-17).

What I came to understand: the only reason the filesystem had been unkillable was that it could not recover - and "cannot recover" is a property you can engineer away, not a law of nature. Once recovery existed, the special status evaporated.

What it produced: Commandment IX made concrete (plan for recovery, and a service that can recover need not be trusted) and another rung down the TCB ladder toward {kernel}.

2026-06-18 - The day a file became a real capability (P2)

Delegated resource capabilities arrived (CLAUDE.md §7.10, Amendment 2026-06-18): fs mints a genuine, kernel-validated, revocable cap on open. The same day, the full persistence stack and the file-as-capability self-check ran green on the HP T630 against a real SSD - a file opened as a cap, read and written through it, non-escalation enforced, a forged handle rejected, the cap revoked on close.

What I came to understand: the meaning of a file belongs to a service, never to the kernel. The kernel does not need to know what a file is to mint, route, and revoke its capability - it only needs to carry an opaque resource id and let fs supply the meaning. "A file is like a capability" was a compromise; "a file is a capability" was achievable, and the difference was the whole point.

What it produced: the §7 north star - a file is a capability, literally, not by analogy - and a reinforcement of Commandment X (complexity in the layer that owns it): file semantics live in fs, capability mechanism lives in the kernel, and neither reaches into the other.

2026-06-20 to 2026-06-21 - The day I deleted the registry and learned what is truly irreducible

Over a phased migration, name-to-endpoint resolution moved out of the kernel and the registry service was retired outright (CLAUDE.md §6.1, Amendment 2026-06-21, "Path C"). A minimal name -> endpoint directory inside the kernel became the namer; the supervisor wires services from a name -> cap map; clients reacquire by name.

What I came to understand: an entire service had existed to store a mapping that turned out to be almost entirely derivable - the supervisor already knew the caps, the kernel needed only a tiny recovery anchor. Deleting it revealed how little state is genuinely irreducible, and how much "truth" is really a derived view dressed up as a source.

What it produced: this is the day behind Commandment III - do not duplicate truth; store the irreducible fact, derive the rest. When someone asks why III is written the way it is, the honest answer is: because deleting the registry showed that only a tiny amount of state was ever truly irreducible, and everything else should be reconstructed, not stored twice.

2026-06-21 - The day nothing was allowed to be unkillable but the kernel

Two long-standing exceptions fell at once. The shell was made restartable - kill shell respawns a fresh prompt instead of leaving a dead session. And in the Path C finale, the supervisor itself became restartable: the kernel respawns it on death, unconditionally and forever, and the respawned supervisor reconciles by adopting the still-running services. The non-restartable set reached its floor: {kernel} alone.

What I came to understand: every "this one cannot die" was a comfort, not a requirement. If the supervisor - the holder of restart authority - can itself be respawned by the kernel, then no service has any standing to claim exemption. "Trusted" finally, fully stopped meaning "unkillable."

What it produced: Commandment V in its strongest form - no service is special; only the kernel is special - grounded in Invariant 6 (services must be restartable) and §6.2-6.3 (the unkillable set is {kernel}). Identity survives restart; only the kernel is location.

2026-06-21 - The day Maximum Carnage was born

chaos max-carnage arrived - a storm that kills a random live service every round and asserts the kernel survives. It grew into a per-round sweep over every live service, mixing kills, queue floods, memory pressure, and spawn storms.

What I came to understand: passing tests proves a system handles the failures you imagined. It says nothing about the ones you did not. The only way to trust a system is to spend real effort trying to destroy it and watch it refuse.

What it produced: Commandment II - love Chaos and trust in it; thy service shall pass through Maximum Carnage - and the standard that a green unit suite is necessary but never sufficient. Chaos is the teacher; if it finds a bug, the bug already existed.

2026-06-22 to 2026-06-28 - The days Carnage found the wedges no one would write by hand

The storm did exactly what it was built to do. A 71K-round SMP deadlock from concurrent TLB shootdowns (fixed 2026-06-24 with per-core shootdown). A supervisor-respawn wedge where respawn ran inside an IF=0 timer ISR and could not acknowledge shootdown IPIs (fixed 2026-06-23 by moving respawn to an interrupt-enabled point). And at high round counts on the T630, a page-table reclaim page fault where a driver kill followed a corrupt PTE into an out-of-RAM frame - which led to the root-cause fix: quiesce DMA on driver kill (2026-06-28).

What I came to understand: these were not new bugs Carnage created - they were old bugs Carnage revealed, latent since the day the code was written, waiting for the one interleaving that QEMU and light load never produced. A system you have not tried to break is a system whose real failure modes you have simply never met.

What it produced: the conviction under Commandment II made unarguable, and the practice of long soaks on real hardware as the acceptance bar - the verdict tightened every time a soak exposed a wedge, because a test that passes a known-broken target is a weak test, not a clean one.

2026-06-25 - The day I wrote the constitution down as ten lines

COMMANDMENTS.md was authored - the Ten Commandments of Godspeed, each grounded in the invariants it enforces.

What I came to understand: the greatest long-term threat to the system was never a race or a fault - it was erosion. Hidden complexity, a convenience here, a silent fallback there, each reasonable on its own, would rot the model one "just this once" at a time. And a 2,700-line constitution is hard to defend a pull request against in the moment; ten memorable lines are not.

What it produced: the realization that the architecture, not the code, is the product (§26.1) - which is why a constitution exists at all, and why it has a human-readable distillation. The Commandments were written in response to real bugs, real wedges, and real lessons; they are the compressed memory of everything above.

2026-06-29 - The day the examples had to teach the truth

The example library was rebuilt as a Commandment-grounded reference for contributors, modelling the real patterns - placement defaults, explicit capability passing - rather than carrying stale registry references from a retired design.

What I came to understand: demonstration code that no one runs drifts into a lie, and a lie in the examples teaches the wrong model to exactly the people most willing to learn it. Examples are documentation that executes; if they are not tested, they are not true.

What it produced: the examples folded under Commandment IX's rule - if it cannot be tested, it does not exist - applied to teaching material, and a reaffirmation that the model is only as honest as the smallest program that claims to follow it.

2026-07-03 - The day the shell became a language, and a 10 MB script was a non-event

gsh grew from a flat command-runner into a real programming language - variables, arithmetic, conditionals, switch, loops, functions with bounded recursion, libraries (import), defer, typed-pipe aggregators, $( ) capture, and console input with a secret-taint guard rail - built the way everything here is built: fixed stacks, bounded arenas, streaming, no heap, loud on every ceiling. Then a 10 MB script was run, and nothing happened. That is the whole point.

What I came to understand: the ~7 KiB cap on a run-from-file script had felt like a limitation to apologize for. The 10 MB test inverted it. A heap-backed loader meeting a 10 MB file has a bad day - it allocates, it fragments, maybe it runs out of memory mid-parse. The streaming minifier meets the same file, reads about 7 KiB of it, prints one loud line - a huge script is a program - and carries on. The bound is not the wall the language hits; it is the thing that lets the language meet a pathological input and shrug. "Handled gracefully" and "bounded" turned out to be the same sentence.

The design of the language taught that lesson twice more, in miniature, by refusing to let me claim more than the system could honestly deliver. A secret from input secret is a guard rail against the accidental echo, not a vault - because once you may write it to a file, you can always read it back, so airtight secrecy is impossible by construction, and pretending otherwise would have been a lie the console told the user. And a function is not a pipe source - a boundary I found only by writing a real program (the selfcheck tour) that tripped over it, fn greet quietly shadowing the greet service.

What it produced: the proof that §26.6.1 is not a kernel rule - it is the rule. The same "change the representation, do not reach for a heap" that governs the piece table and the record arena governs a whole userspace language, and it holds from a 7 KiB script to a 10 MB one with no special case. A bounded system does not fear scale; it renders scale boring. (§26.6.1; Commandment III and the loud-failure discipline.)

2026-07-04 - The day a private discipline became a public one

The licenses were chosen - GPL-2.0-only for the OS, Apache-2.0 for the SDK - the tree swept for secrets and stray dashes, and on 2026-07-04 it went public: github.com/godspeedhq/godspeed-os. (The org is godspeedhq because plain godspeed was already taken - by a personal account that hosts, of all things, Android kernel repos; the project is godspeed-os, leaving room for a godspeed-lang beside it when the language comes.) 939 commits of private practice, opened in one setting change.

What I came to understand: every lesson above was learned in private, where the only person the discipline had to convince was me. Public means the constitution now has to hold against contributors who did not live through the wedges - which is precisely what the Commandments were written for.

What it produced: the moment the invariants stopped being a personal practice and became a public contract - held by the same identity tests, the same chaos bar, and the same ten commandments that earned them. The work of keeping the architecture uncorrupted does not end here; it opens. This was the almanac's one entry dated forward on purpose - the anticipated day, kept blank until the launch could make it real. It is real now.

2026-06-30 to 2026-07-01 - The day "wait on truth" turned out to be half a truth

A million-round chaos max-carnage soak finished with the system alive but the filesystem gone - ls said "no filesystem," drives read raw, and a cold reboot brought it all back. No data was lost; the disk was intact the whole time. So the bug was not corruption. It was a recovery that never happened.

The cause was a single wall-clock timer. fs waited eight seconds for block-driver to report a readable disk, then gave up. Under a soak that had wedged the AHCI controller, eight seconds was never going to be enough - the controller needed a hard reset, not more waiting - so fs latched "no filesystem" and sat there. The timer felt like the safe, obvious way to wait for a dependency. It was the trap. Commandment VIII, exactly: wait on truth, not time.

What I came to understand, and it had a turn in it. Removing the timer and waiting on block-driver's actual reply fixed the soak - but following that discipline rigorously exposed something deeper. The request/reply primitive itself could hang: a blocking wait on a reply hangs forever if the reply never comes, and it never comes if the peer dies mid-request. "Wait on truth" had quietly become "wait forever" for the one truth it could not see: the peer's death. The easy version of a principle ("do not use timers") and the complete version of it are not the same thing.

So the fix was not only in fs; it was in what "truth" means. We taught the kernel that a peer's death is a truth too - a synchronous Call whose caller wakes with ReplyDead the instant its replier dies, the reply-side twin of the sender-side wake §8.6 already had. seL4's Call/Reply, borrowed for exactly this. And the principled part, which was the owner's call: putting it in the kernel grows its code but not its responsibility - IPC death-semantics were always the kernel's job (Commandment I is about scope, not line count). Mechanism, not policy: the kernel learned about a reply cap, never about "RPC."

And then the fix had a hidden failure of its own. The kernel change passed every green test - identity, fs-restart, a new ReplyDead pin - and still drained the whole system to zero on the first hardware soak: recovery of the dead supervisor hung on a single trigger, the timer ISR, which the storm starves, and the new code's latency was just enough to lose a race main had narrowly won. The lesson turned on itself. A fix I believed was complete was again only half-satisfied, and the half missing was the failure case - caught by exactly the fire this whole entry is about. The repair drove recovery from the storm's own hot path, the yield, making it un-starvable - stronger than it had ever been.

What it produced. Commandment VIII, deepened: wait for truth, not time - but ensure the truth includes failure. A wait that cannot observe failure has quietly become an infinite wait on time. A standard for every contributor (CONTRIBUTING.md): interdependent services wait on each other's truth, the reply or the loud fact of death, never on a clock. And the lesson I keep relearning, now with teeth: a principle you believe you have satisfied is usually only half-satisfied, and the half you are missing is what happens when things fail.

2026-07-04 - The day the system survived a million acts of violence

chaos max-carnage all-services 1000000 ran to completion, and the system works as expected.

A million rounds. Each round is not a gentle probe - it kills every restartable service, floods every endpoint it can reach, storms memory and the spawner, and rotates a kill through whatever is left. This is the same soak that, in the entry just above, drained the system to "no filesystem" on its first hardware run and taught the hardest version of Commandment VIII. This time it finished. Nothing had to be rebooted. The prompt still answered.

A million is not a number you reach by luck. Fault tolerance that is 99.99% correct dies long before round ten thousand: leak one frame per kill, fail to reclaim one capability, leave one lock wedged, and the footprint grows without bound until something falls over. To reach 1,000,000 every recovery path has to be not merely correct but conserving - each respawn reclaims the dead instance's frames, kstack, and caps before it allocates fresh, so the footprint is flat and only a count grows (§6.2). The kernel respawns the supervisor unconditionally, forever; the supervisor reconciles - adopts the survivors, respawns the dead; clients see EndpointDead, reacquire by name, and retry. unkillable = {kernel}, and the kernel held a million times over.

This is the entry above, vindicated. The wait-on-truth fix, the un-starvable respawn driven from the yield path, the ReplyDead reply-side twin - each was built to survive exactly this fire, and now the fire has burned a million times and the house still stands. Fault tolerance stopped being a claim in a constitution and became a measured fact. The model was right; the proof is a number with six zeroes.

The receipt. When the storm was called off, observe now on the T630 put the whole truth on one screen:

--------------------------- system state (8 live) ---------------------------
UPTIME: 3d 03:07:34     CPU: C0 99% C1 99% C2 0% C3 0% (49%)     RAM: 5 MiB used / 7 GiB total (0%)
TASK  NAME          CORE  STATE      RESTARTS   QUEUE   UPTIME
 3    supervisor    C0    BlockRecv    142829    0/16      9h
 4    block-driver  C1    BlockRecv    142826    0/16      9h
 5    fs            C1    BlockRecv    997721    0/16      9h
 6    shell         C0    Running      997721    0/16      9h
 7    logger        C0    BlockRecv    143706    0/16      9h
 8    xhci          C1    Running      143704    0/16      9h
 9    ehci          C1    Ready        143706    0/16      9h
drives:  0  data  GSFS  122104 MiB (122074 MiB free)

RESTARTS is what observe calls deaths recovered, not clean re-runs - the soak's odometer. fs and shell had each come back from death 997,721 times; supervisor, block-driver, logger, and the two USB drivers each sat near 142,000-143,000 - together roughly 2.7 million individual service deaths, every one recovered, not one escalated. And the number that settles it is two lines up: <a class="gs-abbr" href="glossary.html#gl-cpu"><abbr title="RAM - processor and memory.">RAM</abbr></a>: 5 MiB used. Flat. After 2.7 million deaths and resurrections and three days of uptime, memory had not grown by a single page - one leaked frame per death would have bled ~11 GiB; the machine used 5 MiB of its 7 GiB, and the 122 GiB SSD sat untouched at 122074 MiB free. That is what "conserving, not merely correct" (§6.2) looks like the moment you finally read the meter.

2026-07-04 - The day gsh was finished, and never once reached for a heap

gsh started as a batch runner: run_lines split a file on ; and \n and handed each line to execute. It is now a language. Variables and arithmetic, if / switch, for / loop with break / continue, functions with parameters and bounded recursion, libraries via import, defer, record aggregators, typed pipes - and, last, the output-capture cluster: for line in (producer) to walk a stream, if myfn to branch on a function's result, and $(fn) to capture a function's output into a value. That last one closed the set. gsh is complete.

And it never once reached for a heap. Every part of it lives on the stack or in a fixed, named arena: the ~5 KiB variable table, the ~7 KiB script buffer, the 512 B capture buffer, the 16-frame block stack. Not one general allocator in the whole interpreter. When a working set felt too big for the stack, the answer was never "add a heap" - it was "change the representation": stream a file in fixed chunks, refer to data by (offset, len) spans, give a subsystem its own bounded arena, iterate with an explicit stack instead of native recursion (§26.6.1). The constraint did not cramp the design; it improved it. Every limit in gsh is a number you can read off the source.

The proof is a 10 MB script. A shell that malloc'd its way through source would choke on it or take the machine down with it. gsh reads ~7 KiB, truncates the rest loudly, runs the tour it can hold - functions, captures, error paths and all - and leaves the prompt answering. Overflow is not a crash here; it is a feature. Every bound fails the same honest way: a value too big for the 512 B capture, a script too big for the 7 KiB buffer, a statement too long to hold across a read - each is a loud, specific refusal, never a silent truncation and never a corrupted result. The system tells you the truth about its limits.

The last feature nearly went the other way, and the honesty of the ask is the whole point. Capturing a function's output looked like it wanted a big buffer, and the question came out loud: "is this a cool place to use a heap - throw the function on a heap, get the result, throw the heap away?" That is the reflex, caught in mid-air - because "scratch space, filled, then discarded" is not a heap, it is a bounded stack buffer, which is exactly what we used (512 bytes - it lives in the executor's own frame, so it must stay small enough to coexist with everything else on a 256 KiB stack; a captured value is a name, a number, a short line). The heap is a shape of thought, and the shape can almost always be had without the allocator. gsh is that argument, made in code, half a kilobyte at a time.

2026-07-04 - The day it shipped, and called itself 0.1

Hours after the repository went public, GodspeedOS cut its first release: v0.1.0 - a tagged, checksummed, bootable UEFI image on the releases page. The old v1.0 tag - the marker left when the first cross-core ping/pong survived a restart - was deleted to make room for it. A system that had called itself "v1" for two months shipped its first release numbered 0.1.0.

What I came to understand: a version number is not a trophy for a milestone reached; it is a claim about maturity, and the honest claim was 0.x. "v1" was the name of a goal met - two services, cross-core IPC, restart. But the software underneath is still moving fast - a whole language landed the same week - and SemVer 0.x means precisely that: anything may still change. Numbering it 1.0.0 would have promised a stability the system does not yet owe anyone. The crates already knew; they had said 0.1.0 all along. The release only spoke the truth the code was already telling.

What it produced: the system's own honesty discipline, turned on its own version string - say what is true, even when a larger number would flatter. The milestone was v1; the software is 0.1; both are true, and the release states the one that matters to a person about to boot it. (A smaller truth rode along: the 64 MiB image is 99.4% empty space, so it ships compressed to under half a megabyte - honest about its size, too.)

2026-07-07 to 2026-07-08 - The day the wire became location

The networking stack, already carrying a real DHCP lease and a ping on the T630's Realtek NIC, was taught to survive the two things a real network interface actually does: the cable moves, and the services die. A running ping now rides an unplug and a replug - it reports the link down, and when the cable returns and the lease re-acquires, it simply resumes, q-abortable the whole time. net-stack configures itself the moment the driver sees carrier; net renew repairs a bad lease inside the running service, no restart; and chaos max-carnage nic-driver,net-stack storms both networking services together, round after uncapped round, while the link keeps coming back.

What I came to understand: the cable is location, and the socket is identity - the same separation SMP drew between a service and its core, now drawn at the edge of the physical world. A link that goes down is not an error to fail on; it is a location changing, exactly what Invariant 11 was written to make survivable. The stack does not own the cable's state any more than a service owns its core; it observes carrier as a fact and reconverges when the fact changes. Plugging in a cable is not a command to handle - it is a truth to notice.

What it produced: Invariant 11 (identity is stable; location is not) reaching all the way to the RJ45 - and the networking half of the restartability story the storage stack had been telling. A socket cap outlives the cable, the lease, the driver, and the stack; every one of those is location, and the system reconverges to the identity from any of them moving. "Not even a blip" is what identity-over-location feels like when you finally pull the plug and watch it come back.

2026-07-09 - The day half a truth came back for the mount loop

A rapid second kill all-services on the T630 - the whole restartable set killed twice within seconds

• wedged the storage stack for good. Not a crash: a permanent thrash. fs had read a garbage disk capacity from a stale reply, derived a backup-superblock LBA far past the end of the disk, and asked for it; the AHCI controller stuck its command-issue bit without ever setting BSY, so the port recovery that watched only BSY never fired; and the mount loop retried the impossible read forever. The keyboard looked dead because the whole machine was buried under an infinite storage retry.

What I came to understand: this was the same lesson as the million-round soak that deepened Commandment VIII (the 2026-06-30 entry above) - and that is exactly the point. That day I taught fs and the kernel that a peer's death is a truth a wait must be able to see. But "wait on truth, and the truth must include failure" is not a fix you apply once and retire; it is a lens you re-apply at every wait you write. The mount loop was a new wait, written to spin until success, and it had quietly inherited the original sin: it could observe success forever and failure never. A persistently unreadable disk was a truth it had no way to conclude. The principle had not failed; I had simply found one more place I had not yet held it to.

What it produced: the three fixes that finish Commandment VIII in the storage stack - a port COMRESET that escalates on a stuck command-issue bit and not only on BSY (so the controller self-heals the wedge instead of retrying into it); a capacity reply fs accepts only in its exact, bounded shape (so a stale reply is never misread as a truth); and a mount loop with a failure-truth exit - bounded real attempts, after which fs comes up degraded and loud, "storage unavailable, data intact," rather than spinning on a disk that will never answer. And the input path learned the same shape from the other side: the console now drains the UART on read, not only on the timer tick, so a keystroke - a truth you can observe directly - is never held hostage to a proxy the storm can starve. One lesson, three surfaces, re-applied where I had not yet applied it.

2026-07-09 - The day recovery became a fixed point

The same double-kill storm exposed a second, quieter fault. When the supervisor came back and adopted the still-running services, a death notice could still arrive for a service it had already recovered - a duplicate, or one in flight when the respawn completed. Reacting to that notice the obvious way spawned a second instance of a service that was already alive, and the churn fed the very storm it was trying to survive.

What I came to understand: recovery cannot be a reflex fired per event; it has to be convergence to a target set. The supervisor's job is not "handle each death" but "make the world match the manifest" - every notice reconciles the live tasks against the set that should be running and acts only on the difference. A service already present is a no-op it logs as already recovered; a service genuinely absent is respawned, exactly once. Framed that way, the supervisor becomes a fixed point: from any perturbation - one kill, a storm, its own death mid-storm - it settles to "every service alive, one instance each," and a redundant notice is absorbed, never amplified. It is Invariant 11 seen from the restarter's side: the supervisor restores an identity set, indifferent to how many messages announce the same gap, exactly as a client is indifferent to which core the name now lives on.

What it produced: the supervisor's death handling made idempotent - the recovery-side complement to identity-over-location, and the property that lets chaos max-carnage kill everything, twice, in a tight loop without the recovery path becoming its own denial-of-service. A system that reconverges is one you can hit as hard as you like: it does not matter in what order, or how many times, the bad news arrives.

2026-07-10 - The day the kernel met a second architecture, and fit the machine it found

Two things landed the same day. The kernel stopped guessing how big the machine is: the MAX_CORES ceiling was deleted, and every per-core structure became a boot arena sized to the core count Limine actually reports, while the frame bitmap became sized from the RAM that is actually present - no cap, no waste (this branch, through cfb0a88). And then the hardened image booted on a second CPU architecture: a Dell Wyse 5070, Intel Goldmont+, came up first try - SMP, the AHCI flash, the Realtek NIC pulling a real DHCP lease and answering a ping, the shell - all of it, on silicon from a different vendor than the AMD GX-420GI (the HP T630) that every wedge in this almanac had been caught on.

There was a wound in that. The very first bare-metal boot, back on 2026-05-21, had been on a Goldmont+ part too, and within the week it stalled hard under load (The Sleeper on Core Zero, the first IF=0 bug) and sent development to the AMD T630 for good - the workhorse on which the shootdown deadlock, the respawn wedge, the DMA-after-death, and the million-round soak were all found and fixed. Two months and a hardened kernel later, Goldmont+ got its second chance and took it cleanly, first boot. Even the one thing known to be AMD-specific - TSC calibration, broken on the GX-420GI because it exposes no CPUID frequency leaf - simply worked on the Intel part, because the fallback calibrates against the PIT: a machine-specific truth read at boot, never hardcoded.

What I came to understand: portability is not a feature you write; it is the absence of assumptions you should never have made. Nothing in the boot path had to be told about the Wyse. The kernel counts its cores from Limine, sizes its bitmap from the memory map, and calibrates its clock against whatever timer answers - so a machine it has never seen configures the machine, not a constant in the source. A kernel that fits the machine it finds has nothing left to port. And the two CPUs it has truly lived on - AMD first, as the workhorse; Intel Goldmont+ second, as the proof - are now one image, unchanged between them.

What it produced: the dynamic-topology work (no MAX_CORES, RAM-sized bitmap) as the executable form of "identity over location" pushed all the way down to the hardware census - the machine's size is location, discovered, never identity, assumed. The only ceiling left is the xAPIC's 8-bit LAPIC id, and even that is now loud rather than silent: past 255 cores the kernel says so and names x2APIC as the next step, instead of quietly wrapping. Two CPUs, two vendors, one image, booting to the same steady state.

2026-07-11 to 2026-07-13 - The days the whole system stood for audit

For the first time the system was read the way a constitution asks to be read - not "does it work?" but "does it still obey?" A kernel audit (2026-07-11, audits/kernel-audit.md), run as a parallel sweep of independent readers over every subsystem, checked the code against the Ten Commandments and the invariants and surfaced three real things: two paths where a non-page-fault CPU exception - a stray #GP, a div0 in a service - halted the whole machine instead of killing just the offending ring-3 task (a single bad instruction in userspace could wedge the kernel), and one where a transient allocation failure on the supervisor-respawn path could panic! into a reboot, defeating the very Phase-6 recovery it lived inside. Then a userspace audit (2026-07-12 to 2026-07-13, audits/userspace-audit.md), the first of its kind, graded every service - the coupled pairs first, block-driver/fs and nic-driver/net-stack, then the rest - against the same law: 0 high, 8 medium, 8 low, each finding logged with a fix or a recorded deferral.

What I came to understand: the audit is affordable because the kernel is small. The 30-minute whiteboard rule (§26.11) and Commandment I (the kernel is complete; keep it small) had always been framed as correctness and understandability properties - but they were quietly an audit budget all along. A 2,700-line constitution enforced against a kernel one engineer can hold in their head can be walked end to end in an afternoon; the same audit against a monolith is a standing team that never finishes. Tininess is not only what makes the kernel correct or secure - it is what makes the recurring act of checking correctness and security cheap enough to actually do, release after release. The kernel stayed small so that auditing it could stay routine.

What it produced: audits/kernel-audit.md and audits/userspace-audit.md as living artifacts - a standing, repeatable practice rather than a one-time pass - and the recognition that the north star of an audit is that nothing above the kernel may panic or wedge it: a service's worst instruction should cost that service its life and no more. The findings became the next increment of work; the discipline became a habit. A model you can re-verify in an afternoon is a model that stays honest between the days someone thinks to check.

2026-07-14 - The day the boundary became something a machine enforced

Straight off the audit, the arch boundary stopped being a habit and became a law. The survey came first - because you cannot seal what you have not measured: 126 places where a neutral file reached for the x86 layer by name, 23 lines of inline assembly living outside arch/, and - the number that mattered - zero of either in the capability table or IPC. Then the sealing: one seam, crate::arch::imp, that names "the implementation for whatever architecture this is"; all 126 references routed through it; every inline-asm operation (read the page-table base, invalidate a TLB entry, mask interrupts, send an IPI) moved out of the neutral layers and behind an arch::imp primitive, so that not one arch-neutral file holds a single instruction of assembly. And last, the part that makes it stick: arch_boundary_check.py, a CI guard that fails the build if any file outside arch/ so much as writes asm! or names a specific architecture.

What I came to understand: a boundary that lives only in a contributor's head, or even in a well-written doc, will rot - because nothing stops the next well-meaning change from crossing it. The whole difference between a convention and a law is whether a machine refuses to let you break it. The seam made the boundary nameable (arch::imp, one place); the guard made it unbreakable (CI, every push). This is §26 - the architecture survives only if the discipline survives - turned from an aspiration into a mechanism. And the survey taught its own lesson: the belief "the boundary is clean" was worth nothing until it was a number, and the number that carried the whole bet was the zero in capability/ and ipc/.

What it produced: the arch::imp seam and the arch-boundary guard - the fourth of the kernel's mechanical disciplines (alongside the unsafe audit, the contract reconcile, and the dash convention). A boundary you can no longer cross by accident, only by deleting the guard on purpose. It set the stage for the only test that could prove the boundary was real.

2026-07-14 - The day one kernel booted three instruction sets in QEMU virt

With the boundary sealed and enforced, it was put to the one test that cannot be argued with. The arch-neutral kernel - the capability table, IPC, scheduler, syscall dispatch, memory, task, loader, every service's logic - was compiled and booted on three genuinely different instruction sets, writing only arch/<isa>/. x86-64 ran the full OS, all the way to the gsh> shell. AArch64 booted under QEMU's virt virtual machine (qemu-system-aarch64 -M virt) and put a line on the PL011 UART. RISC-V booted under the same virt machine (qemu-system-riscv64 -M virt), handed off by OpenSBI into S-mode, and put a line on the 16550. Not one arch-neutral file changed between them. Three QEMU-virt consoles, one codebase.

What I came to understand: a boundary is a claim until a second implementation drops in behind it without touching what it bounds - and it becomes a law on the third. The demarcation was never something to prove on a whiteboard; it was something to observe on a wire, exactly like the boot on day one. And the tell was in how the three went. AArch64 took real debugging: the CPU traps FP/SIMD at EL1 by default and Rust emits NEON for a byte-copy, so the first port faulted before its first Rust statement (found by reading the exception ESR off qemu -d int), and the stack pointer had to be forced 16-aligned. That was me learning the architecture's personality. RISC-V went first try, no debugging - riscv64imac is soft-float, so there was nothing to trap, and by the third ISA the playbook was solid enough that the neutral kernel simply came along for the ride. That asymmetry is what "bounded" feels like: the second implementation teaches you the arch's quirks, the third is a formality. The deepest thing is that this day and the audit days were the same act seen from two sides - the audit proved the inside was honest (nothing above the kernel could wedge it), and the port proved the edge was real (nothing inside had smuggled the machine into the model). A boundary is only as trustworthy as the code it bounds is clean; the code was clean because it had already been walked end to end. The small kernel that was cheap to audit was, for the same reason, cheap to carry to a new machine.

What it produced: docs/multi-arch.md, and the founding thesis closed into a demonstrated fact. The boundary is now held not by intention but by four CI guards and three live QEMU-virt consoles: to add a fourth ISA you implement arch/<new>/ to the imp surface, add one #[cfg(target_arch)] arm, and the compiler plus CI prove that no neutral file had to move. A capability microkernel kept small enough to fully audit has an arch boundary clean enough that a new architecture is a bounded drop-in - claim to proof, in the span of a day that only looked sudden because a hundred careful days came before it.

2026-07-25 - The day the second architecture stopped being a demonstration

On a Raspberry Pi 2, on real silicon, the shell printed run: ran 349, failed 0.

The arm32 port had booted before. It had reached userspace, driven a keyboard through a hub, mounted a disk, spoken DHCP over USB ethernet. What was different on this day is that the whole self-check ran and every case passed: the language tour, the pipes, the records, the filesystem, and - the one that mattered most - fcap, the file-as-capability proof (§22 Test 14). A file opened as a real kernel capability, written and read through the cap, non-escalation enforced at both the kernel and the fs layer, a forged handle rejected, the cap revoked on close and on rename. The §7 north star, true on a second architecture and not by assertion.

Four bugs stood in the way, and the striking thing is that not one of them was visible under emulation:

1. A single DWC2 channel shared by the keyboard poll and storage, where a keyboard split abandoned mid-flight corrupted the next block transfer.
2. resource_invoke packing its right field at bit 32 of a syscall argument, where arm32's register is 32 bits wide, so the right arrived as zero.
3. The Bulk-Only Transport reset recovery missing its first step - the Mass Storage Reset that resynchronises the device's state machine, without which clear-halt unsticks the pipes and leaves the device still waiting for a transfer we had abandoned.
4. A failed recovery that reported nothing, because its result was discarded with let _ =.

What I came to understand: these were not logic bugs, they were bugs about the machine being real. An emulator gives you a device that is patient, coherent, infinitely fast, and stateless between commands. Every one of the four was the consequence of a device that is none of those - a channel that is genuinely contended, a register that is genuinely 32 bits, a controller that genuinely holds state you must resynchronise, and a recovery that can genuinely fail. QEMU had said yes to all four for months. It was not lying; it was answering a different question.

And the third and fourth are the same bug wearing different clothes. The reset step was missing, and the code that would have told me it was missing threw its answer away. §26.7 already said a failed recovery must stay visible. What I had not appreciated is why that matters so much: a silent failed recovery does not merely hide a defect, it misdirects the investigation. Because the verdict was discarded, the log could not distinguish a device that was confused from a device that was gone - so I concluded the hardware had failed, and asked the operator to go test their USB stick. They pushed back: the stick was fine. They were right. The defect was mine, and the reason I could not see it was a return value nobody read. An error you discard does not just cost you the error. It costs you the next several hours, spent looking at the wrong component.

What it produced: bot_recover now performs the full spec sequence and returns its verdict, and says out loud when it could not recover - which turns "storage is broken" into the answerable question "is this device confused, or gone?". The rule earned a sharper form: an unread error return is not a missing log line, it is a wrong suspect.

2026-07-27 - The day a stick swap ended the hunt, and the recovery earned its keep

The self-check printed run: ran 349, failed 0. Then it printed it again, and again - eight times in a row, on a Raspberry Pi 2, on real silicon. Consistent zero: the bar that had sat just out of reach for a week of hardware round-trips.

What reached it was not a line of code. It was pulling out the USB stick and pushing in a different one.

For days the storage had failed the same way: under sustained I/O - a drives check reading the whole tree - the stick would stop answering, roughly once per run, and cost the handful of tests in flight at that instant. Every layer above it was made to survive that: a stuck-endpoint reset, an escalation to port-reset and re-enumeration, a filesystem that re-mounts on an I/O error, a journal that replays an interrupted write. And along the way real defects fell out that had nothing to do with any stick - a synchronous Call that took the wrong message off its own queue because it matched replies by arrival order instead of by sender (latent on x86 too); a format that condemned its own successful writes by reading them back through a device that served stale data; the FIFOs sized for a keyboard while a 512-byte bulk packet needed the whole of one. Each was found, each was fixed, and still a revival cost a run.

The operator proposed the one experiment I had been talking around: change the stick. Eight clean runs later, the answer was unambiguous. The old stick's own controller had been failing under load - not leaving the bus, just wedging its own firmware while staying plugged in. A dodgy part.

What I came to understand: faults stack, and fixing a real one does not exonerate the layer beneath it. The 2026-07-25 entry above is the same investigation, two days earlier, and its conclusion was true - the silent clear-halt was a genuine defect, and "the stick is fine" was the right correction at the time, because the software bug was masking everything under it. But "the software bug was real" and "the stick was fine" are not the same statement, and I had quietly treated them as one. Peel a real fault and you do not reach innocence; you reach the next fault. Only a controlled experiment - one variable changed, everything else held - can isolate the last one, and no amount of reading an ambiguous log substitutes for it.

And the elaborate recovery was not wasted on a problem that turned out to be hardware - it was the whole point. The proof is in the same log: the old, failing stick dropped off twice and still produced two 349, failed 0 runs, because the recovery caught it and carried on. Resilience surviving a genuinely failing device, gracefully, is exactly what resilience is for. The reply-correlation fix and the others would have been worth making on any stick; the recovery earned its keep on the bad one.

What it produced: the discipline of the one-variable swap before the multi-day rewrite - because the next thing I had been about to build was a full interrupt-driven restructure of the USB stack, days of work, to fix what a $3 part swap settled in an afternoon. That the restructure is still worth doing (for reasons that were never this bug) is a separate decision, now made in the clear rather than under the pressure of a failure I had misattributed.

2026-08-09 to 2026-08-12 - The day the kernel gave up the USB stack, and then gave up the choice

kernel/src/arch/aarch64/xhci.rs was 2,742 lines of ring-0 code parsing descriptors supplied by whatever someone had plugged in. It worked. It had driven a keyboard and a disk on a Raspberry Pi 4 for weeks. On this day it was deleted, and the xhci SERVICE drove the controller instead - through an MMIO capability and a DMA arena granted at spawn, reaching the console through CONSOLE_PUSH, serving storage over the block protocol block-driver already spoke. The kernel's entire remaining involvement with USB became establishing that the controller is present and saying so.

The move was done behind a feature flag first, so both drivers could exist while the service was proven on hardware. Then the flag was deleted too, and that second deletion is the part worth remembering.

What I came to understand: a flag that selects between a compliant kernel and a non-compliant one does not resolve the violation, it stores it. As long as usb-via-xhci existed, there was a build of GodspeedOS in which the kernel drove USB - one flag away, and Commandment I was satisfiable rather than satisfied. It was also a genuine footgun: the flag had to reach three crates, and setting some of them gave two drivers on one controller, or none, with every half booting fine alone.

And I had to be precise about what the move actually bought, because the milestone is real but narrower than "Commandment I closed" sounds. The Pi 4 has no SMMU wired up: confine_device returns false, and the service is granted its controller's BAR plus a DMA arena including its physical base. So it can still point the controller's DMA anywhere, which is kernel-equivalent reach by the same rule that governs an unconfined x86 driver. The honest statement is: a buggy USB driver on the Pi 4 is now bounded; a compromised one is still kernel-equivalent. What closed was the accident surface - ring-0 descriptor parsing became a restartable service - and the ambient authority, since the service holds only what its contract grants. The trust posture is unchanged until an SMMU confines the device, and saying otherwise would have been the nicer sentence and the wrong one.

2026-08-17 to 2026-08-29 - The day the terminal left the kernel, and I learned what earns ring 0

Two more evictions, on the port with the least room for them. arch/arm/dwc2.rs - the whole ARM32 USB stack, keyboard and networking and mass storage - became services/dwc2, driven by a real device interrupt rather than the core-0 timer tick. And kernel/src/fbcon, 1,172 lines of terminal emulation, became services/console: the ANSI/CSI state machine, the UTF-8 decoder, the shadow grid, the cursor, scrolling, reverse video, all of it out.

What stayed behind cannot format, cannot position, and cannot scroll. Reaching the bottom of the screen clears it and starts again at the top.

What I came to understand: the test for ring-0 residency is not "is this important" or "is this hard to do elsewhere". It is impossibility. A panic halts every core, including the console service, so a panic cannot ask a service to report it - the kernel must be able to say the machine died using only itself. Boot output has the same shape: it precedes every service, including the one that would render it. That argument justifies exactly a bounded blit and not one line more. Rendering a shell prompt is policy; a display driver is anti-scope by name. The operator control channel had asked for ring-0 residency earlier and failed this same bar, which is how I knew the bar was real and not built to fit what I already wanted to keep.

The evictions also made honest a claim that had been quietly arch-specific. The logging floor said the kernel writes to "the serial console", which is always true on a PC and false on a Pi wired to a TV. A kernel that can only speak to a port it does not have is mute, and a boot failure on that machine was a frozen screen with no reason on it.

2026-09-03 to 2026-09-04 - The day the kernel stopped interpreting the bus

The kernel held a table of what every device class was: which BAR, which IRQ, which BDF, per class, sixteen of them. A driver was spawned because the kernel knew what an xHCI was. By the end of D3 the supervisor owned the images and a driver named a device class code, which the kernel resolved from a table it holds no opinion about. service_config rows went 222 to 2. Embedded images went 30 to 1. Per-class device statics went 16 to 0.

Four bugs surfaced during it, each found by an instrument built for a different one: an fs reply desync, a block-driver "no disk" latch, an xHCI port-status misattribution, and an arm32 serial splice that was corrupting the very evidence being used to chase the other three.

What I came to understand: "the kernel is mechanism, not policy" is easy to agree with and hard to notice breaking. Not one of those sixteen statics arrived as a policy decision. Each arrived as one more small fact the kernel happened to know, and the aggregate was a kernel with opinions about PCI. The question that catches this is not "is this policy?" - nobody ever answers yes - but "does the kernel have to interpret anything here, or can it be handed the answer?"

2026-09-05 to 2026-09-06 - The day five bugs stood in a line, each hiding the one behind it

logger became events, which was the name catching up with the job: it had held the IPC trace ring since tracing shipped and had never held a log line in its life. Then it grew metrics and a log window, and recorder grew beside it to put a capture on disk. Ordinary feature work.

Then the hardware disagreed, five times, and every disagreement presented identically: a row that simply was not there.

1. The sink was reacquired on send failure - and the sample that triggered the reacquire was dropped.
2. A missed resolve latched forever, because u32::MAX was read as "this service holds no sink cap", a permanent fact, when it is also what a service sees if the sink happens to be mid-restart at its first emission.
3. The kernel dropped the peer DECLARATION when a declared peer was down at spawn. Not the capability - the declaration. AcquireSendCap authorises a reacquire only for a declared name, so a service spawned during the 47 milliseconds its peer was restarting could never reach that peer again, for the life of the instance. It cost fs its disk and produced 113 failures in one run, with storage reported unavailable while block-driver sat idle beside it having received exactly one message.
4. A capless publisher never asked for a capability, because the reacquire that would have fixed it sat behind a send failure - and a send that never happens never fails.
5. Liveness waited out its 64-message interval after a restart, so a quiet service read as dead.

What I came to understand: the third is a violation of the restart contract, in the kernel, and it had been there the whole time. The constitution promises a client can reacquire a restarted peer; a scheduling accident of 47 milliseconds silently revoked that promise for the life of a service. It was findable only because an error message, added mid-investigation for an unrelated reason, distinguished "refused" from "the name does not resolve" - two words apart, and the whole diagnosis hung on them.

The shape they share is the lesson, and it generalises well past observability: a recovery path that only runs on failure cannot recover a component that never gets far enough to fail. Four of the five were a version of that. If a thing recovers only when it errors, ask what happens to the one that never starts.

2026-09-06 - The day the second core stopped being an answer

Several times, a scheduling or liveness problem had been answered by moving a service to a different core. That is not a fix; it is a workaround that depends on a second core existing to absorb the fault. So the absorber was taken away: one core, on a Raspberry Pi 4 that has four.

It survived. Three clean self-checks, a hundred rounds of Maximum Carnage, 611 kills, 500 endpoint floods, zero panics, zero liveness wedges. The cost was 1.6x slower for 4x fewer cores, which is what a synchronous-IPC microkernel should cost when most services are blocked on recv most of the time. Predictable degradation, no correctness cliff.

The experiment found something on its first boot, before any of that. The compiler said it without being asked:

warning: struct `PlacementInvalid` is never constructed

The placement rule promises that a contracted core which is unavailable rejects the spawn, with the rationale spelled out: silently rerouting would be exactly the kind of reinterpretation a capability system is designed to forbid. It had never been enforced. xhci declares core 2 and started on core 0 without a word, on every machine, for the entire life of the project.

What I came to understand: every conclusion ever drawn from "it works on core N" rested on a fact the kernel never checked. Those placement lines have been decorative. That is worse than a missing feature - it is a silent fallback at the kernel boundary, which the contribution rules list as an automatic rejection - and what makes it instructive rather than merely wrong is that the type existed. PlacementInvalid was defined, resolve() named it in its signature, and nothing ever constructed one. The shape of enforcement was in place without the enforcement, which is the most convincing way for a guarantee to be absent.

The Days I Was Wrong

2026-09-06 - The day I read a zero that had never been measured

Chasing why a service had stopped publishing metrics, I added an instrument: a one-shot line that would say so if the sink had been resolved late. The hardware run came back and the line was not there. I reported that as evidence - "resolved LATE: 0, so the latch was never the cause" - and moved the investigation somewhere else on the strength of it.

The instrument had no call site. The edit that added it had two halves; the first landed in trace.rs, the second hit an assertion error and never wrote, and I re-ran only the other half. The helper compiled, was public, and was called by nothing. The zero was not a measurement of a healthy system. It was not a measurement at all.

What I came to understand: a missing instrument reads exactly like a healthy one. Both produce silence, and silence is what I was treating as information. Every other kind of broken tool announces itself - a test that cannot compile, a check that errors - but an instrument that was never wired in returns the same thing a passing system does, and it returns it confidently.

The habit that comes out of it is small and mechanical: after adding a report, verify the CALL SITE exists, not that the helper compiles. grep -c for the caller, in the same breath as writing it. I already knew to distrust a number I had not earned; what I had not internalised is that an absence is a number too, and it needs earning in the same way.

There is an uncomfortable second half. It cost a hardware round-trip, which is the user's time and not mine, and I had reported the conclusion with more confidence than the evidence carried. The correction was mine to make and I made it in the next message - but the run was already spent.

2026-07-27 - The day I almost rewrote the world to fix a dodgy part

The drop-off left a fingerprint, and I read it wrong. At every capture the port register said the same thing: HPRT bit 0 set, device connected, port enabled. I took that as proof the fault was mine - the device is right there, so my polled, interrupts-masked transfer path must be wedging the channel. I built the case, and I proposed the fix that followed from it: convert the whole USB stack to interrupt-driven, the way Linux does. A week of work, and I was ready to start.

The signal was ambiguous and I did not hold it as ambiguous. "Present but not answering" is equally the signature of a stick whose own controller has wedged - it stays electrically connected while its firmware stops responding. The port register cannot tell those two apart; it reports the wire, not the silicon at the far end of it. I resolved the ambiguity in the direction I already believed, which is the whole mechanism of being confidently wrong.

The operator resolved it the honest way, by changing one variable. Eight clean runs on a new stick.

What I came to understand: an instrument that cannot distinguish two hypotheses must not be read as favouring either, however much one of them fits the story I am telling. And when a cheap experiment can separate them - swap the part, change the one variable - it is worth more than another round of inference, and far more than committing days of work to the reading I preferred. I nearly rebuilt the entire transfer path to fix a fault that lived in a flash chip.

What it produced: reach for the one-variable swap before the multi-day rewrite; treat an ambiguous instrument as ambiguous; and notice when a proposed fix is large in proportion to how certain I actually am of the cause. The interrupt-driven rewrite may still happen - but as an improvement chosen freely, not as a cure for a disease I had misdiagnosed.

The entries above are mostly victories - the days understanding clicked into place. But the days worth keeping most are the ones where the architecture had to beat the author. A constitution that only ever agreed with my instinct would be a mirror, not a law. These are the days it told me no, and was right to. They are the proof that the rules bind the founder first.

~2026-06-21 - The day the constitution rejected its author

While hardening Maximum Carnage, I noticed an apparent contradiction: Chaos exempted itself while running. Earlier, the shell had been exempt from Chaos so that I would always have a way back into the system, and that exemption had later proved to be hiding bugs. My first instinct was simple: if no service is special, then perhaps Chaos itself belonged in the kernel, so it could destroy every service, including itself.

What I came to understand: the apparent contradiction came from confusing operation with verification. Chaos is fundamental to verifying the system, but it is not fundamental to operating it. A test harness cannot terminate itself while coordinating the test, any more than a scheduler can deschedule itself out of existence. Chaos remaining alive during a run is not privilege; it is the logical consequence of the role it performs. The kernel already provides the escape path through the serial console, so Chaos needs no special authority beyond the capabilities it already holds.

Moving Chaos into the kernel would have violated Commandment I: the kernel's responsibility is to operate the system; Chaos exists to challenge it.

What it produced: perhaps the strongest proof yet that the Commandments are not written only for contributors - they constrained the project's own author. The idea was rejected, Chaos remained a userspace service (§4.4, §26.10), and the constitution proved that it governs principles, not people.

~2026-06-27 - The day I reached for a heap

A working set felt too big for the stack - an editor meant to open files of any size - and the reflex was instant: add an allocator.

What I came to understand: "too big for the stack" is almost never a reason to add a heap. It is a reason to change the representation until the working set is small - a piece table, a streaming window, spans instead of copies. A heap would have hidden the bound; the constraint forced me to find the right data shape instead, and the right shape was simpler than the allocator would have been.

What it produced: §26.6.1 (bounded memory means stack and arenas, not heap) and the habit of reading a hard ceiling reached loudly as a feature - a prompt to rethink the working set - not as a missing allocator.

2026-06-28 - The day my own test lied to me

A chaos flood-storm passed, and I believed it. Then I looked closer: it had been counting a full queue as "drained," so it had been passing a target that was actually broken. I had overstated a fix on the strength of a test that could not fail.

What I came to understand: a test that passes a known-broken target is not a clean test, it is a weak one - and a green check from a weak test is worse than no test, because it sells false confidence. Fix the verdict before you trust the result.

What it produced: the verification was rebuilt to demand that a re-sent message actually land, which immediately exposed three real clogs the old test had been hiding. Trust a system only as far as you trust the test that watched it.

2026-07-25 - The day I tuned against a number the disk was writing

Hunting the arm32 storage failures, I steered by the self-check's failure count: 83, then 7, then 61, then 7 again. I moved a constant, read the count, and drew a conclusion each time. One of those conclusions condemned a change that had in fact worked.

The count was partly measuring the disk. A corrupt root directory block fails nearly every file test no matter what the build does, and that block persisted across reboots. So a run could report 61 failures while the subsystem I had just changed had never been healthier - 4 USB-layer errors, down from 27. I read the catastrophe and reverted the fix that caused it.

What I came to understand: before trusting a metric, ask what else can move it. A number that sums several independent causes cannot attribute any of them. The honest instrument had been sitting in the same log the whole time - the USB-layer error count, which nothing on disk can influence, and which told a clean monotone story from the first run to the last: 235, then 27, then 5. I had two instruments and spent several hardware round-trips reading the noisy one, because it was the one the test suite printed at the end in bold.

What it produced: the discipline of judging a subsystem by a metric only that subsystem can move, and of treating persistent state as a variable in every experiment that touches it. Also the habit of saying so plainly when a previous conclusion was drawn from a contaminated number, rather than quietly letting the corrected result stand as though the reasoning had been sound.

2026-07-31 - The day I learned what my instruments could not see

The Pi 2 learned to notice what you unplug - keyboard, storage, an unknown dongle, the ethernet cable - and the fix that mattered was not more polling but asking the hub's change-latch what had happened instead of inferring it from what the port looked like now. A level tells you the present; a latch tells you the event. Everything else that week followed from instruments, and from their blind spots.

Four times the evidence was in hand and read wrong. A 30-second freeze, blamed on storage through five commits, was the chaos harness pacing itself with a fixed yield count - and a yield costs a full quantum when nothing else is runnable, which is exactly the state chaos creates. The tell had been in the first log: a ceiling at exactly 30.0 s, never exceeded, is a count, not a stall. A guard that had logged 141 silent "phantom frame" refusals looked like a guard working; it was a guard reporting that the kill path was freeing a driver's MMIO as RAM. A stale comment describing finished work as pending, and a note calling a three-week-old fix a todo, each bought a confident wrong answer. And 57 green tests said nothing about the case I had changed, because every one of them was cross-core and the broken path was same-core.

What I came to understand: every instrument has a shape, and a failure outside that shape is invisible to it - so a green result means "nothing in what this could see", never "nothing". Ask what an instrument is structurally incapable of noticing before trusting it, and treat a silent guard, an exact repeated number, and a note that says "todo" as claims to verify rather than facts. The corollary is kinder than it sounds: the BSP had been able to halt onto a dead timer for the life of the port, and only became visible when a change stopped userspace spinning long enough for the core to idle. The bug was never created. Something merely stopped hiding it.

2026-09-07 - The day the emulator's luck ran out

GodspeedOS booted on a fourth architecture. Starting kernel ... and then our own banner, out of a 16550 on a StarFive JH7110, from a kernel U-Boot loaded off an SD card. What made the day worth writing down is not that it worked. It is that everything which went wrong first was something QEMU was structurally incapable of telling me, and that three of them were the same mistake.

The kernel would not load at all: Bad Linux RISCV Image magic! after U-Boot had read all 4279 bytes perfectly. booti requires a 64-byte header that Linux defines and a flat binary must carry. QEMU had never asked for it, because -kernel is handed an ELF and takes the entry point from the ELF header, while booti is handed a raw image and has nowhere else to look. The difference was in the BOOT PROTOCOL, not the silicon, so no amount of emulator testing could have surfaced it. And when I wrote the header, the jump at its front had to be wrapped in .option norvc: with compressed instructions on, j assembles to two bytes, every field behind it shifts, and the magic lands somewhere U-Boot does not read.

Before that, the board disagreed with the emulator about nearly everything the port had assumed. RAM at 0x4000_0000 rather than 0x8000_0000, so the kernel was linked to an address the loader would never jump to. A 4 MHz timer where QEMU runs 10. OpenSBI v1.2 against QEMU's v1.8. And the boot hart is hart 1, because hart 0 is the JH7110's monitor core. Only the UART agreed, at 0x1000_0000, which was luck rather than design and the single reason the banner printed unchanged.

That week I had already spent a day on an x86 bug of exactly this shape. Core 0's local APIC id was published only inside AP startup, so a single-core boot never published it and every interrupt was addressed to APIC id 0. It was invisible to the whole suite because QEMU's boot processor really IS id 0: the wrong value was accidentally right on the only machine CI runs. Now the same trap was waiting one architecture over, in "hart 0 is the boot hart" - natural, universally true in the emulator, and false on the first real board I tried.

I also spent hours solving the wrong problem. The card could not be mounted on Windows, so I fought diskpart, Set-Partition and wsl --mount in turn, and every one refused. The user asked why we were making it hard, and whether wiping the card would do. It would, and the reason was in the board's own boot log all along: Trying to boot from SPI. The bootloader lives in the board's flash, not on the card, so the card only ever needed to carry a kernel, and a single partition Windows would happily letter was enough. I had been reading that log for other facts for two days.

What I came to understand: an emulator does not merely omit hardware, it supplies DEFAULTS, and a default that happens to match your assumption hides the assumption instead of testing it. Zero is the dangerous one, because zero is what an untested field already contains: APIC id 0, hart 0, an entry point read from a header that a real loader will not read. So the question to ask of a green emulator run is not "did it pass" but "which of my assumptions did this environment happen to satisfy", and the answer is worth writing down before the hardware arrives rather than after it disagrees. The corollary is why the first hardware boot should be the smallest thing that can possibly fail: five assumptions died in one afternoon, and each one announced itself by name only because there was nothing else in the kernel for them to hide behind.

2026-09-08 - The day a borrowed mechanism brought someone else's memory map

GodspeedOS became a system on RISC-V today rather than a kernel that boots: four harts, ten services, a shell that answers, a fault that kills a task instead of the machine, and its own chaos suite run to completion on real silicon - 53 kills across ten rounds, the supervisor itself killed three times and respawned by the kernel, which then adopted the services still running rather than duplicating them.

None of that is the thing worth writing down. This is: four separate bugs today were the same fact about this machine, and I reached for x86's shape first every time.

On x86 the kernel lives higher-half. Userspace is low, the kernel is high, and nothing in the code says so - it is a property of the LAYOUT, invisible at every call site that depends on it. On RISC-V this kernel is identity-mapped from zero and a service links at 0x400000, so the two share an address range. Every place x86 had quietly been using "which half" as the boundary, I inherited a check that compiled, ran, and answered wrongly:

• The syscall-pointer check rejects a kernel address on x86 because of where the kernel is. Here it answers true for the kernel's own code - correctly, since a task may legitimately map its own page at that virtual address.
• Building a task's address space by copying top-level entries works on x86 because the halves cannot collide. Here it replaced the supervisor's own text with a kernel mapping, and the first thing the first service ever did was fault on an address that WAS mapped, by an entry it never asked for.
• Reclaiming a dead task by walking "the low half" is the same assumption a third time. Here it would hand the kernel's UART mapping back to the frame allocator.

In all three the answer is the same and it is not an index: the U bit. One fact about the port, three places it decides everything, and it took three separate failures to see it was one fact. Section 26.14 already says to borrow the silicon's requirement and never the other system's model. What I had not understood is that a memory map is part of that model even when no line of code mentions it. Portable code can carry an unportable assumption in complete silence, because the assumption lives in the addresses rather than in the instructions.

And the fourth was yesterday's lesson wearing a different hat. A hart asked which core it was; the lookup requires the core to be marked ready, a hart cannot be ready before it knows its core, and the function falls through to 0. So all four harts reported themselves core 0, four of them wrote on one core's scheduler state, and the first service died of a capability error that had nothing to do with capabilities. Zero again: not absent, not an error - a plausible answer, from a function with no way to say "I do not know".

A quieter version of the same thing cost several hundred restarts. reclaim_user_frames was a stub returning 0, and the kill path PRINTS what it returns. freed 0 frames reads as this task had nothing; it meant nothing was reclaimed. A service faulting in a restart loop leaked its whole address space every cycle, and the machine died of an allocation failure a long way from the cause.

What I came to understand: a stub that returns a NUMBER is not neutral, and neither is a lookup that falls through to one. Absence has to be expressible - None, an error, a refusal - or every caller downstream treats a placeholder as data and the failure surfaces somewhere it cannot be traced back from. And when porting, the code that compiles unchanged is exactly the code to distrust: it brought its author's address space with it, and that is the part no compiler checks.

2026-09-12 to 2026-09-13 - The day "it boots" stopped being the standard

Five machines ran GodspeedOS in one day - Raspberry Pi 2, Raspberry Pi 4, StarFive VisionFive 2 Lite, HP T630, Dell Wyse 5070 - across three instruction sets, each surviving a hundred rounds of chaos and three self-check runs with zero failures. Four of them reported the same number: ran 461, failed 0. That coincidence is the whole point of the entry, and it is not a coincidence.

The realization: a portability claim measured in ports is measured in the wrong unit. The project had four working ports and said so proudly. What it could not say was what the FIFTH would cost. "It boots on four architectures" is a statement about the past; the rule the operator set is a statement about the future - an ISA port is not complete when it boots, it is complete when architecture-neutral code no longer knows that the ISA was added. Nothing measured that. So the branch stopped counting ports and started counting the thing a new port actually pays: every place outside arch/<isa>/ that still knows which machine it was built for.

The two that stayed are the honest part: both are target_pointer_width on one constant, where a 32-bit address space genuinely cannot hold a 4 GiB virtual address. The width IS the question. They are counted, not exempted, so a reader can see them and see why.

What made the reduction possible was noticing that the question was usually wrong, not the answer. Above the kernel, target_arch almost never means "which instruction set" - it means "which BOARD am I on", and those come apart. nic-driver picks its MAC by ISA, so a different NIC on a board of the same ISA drives the wrong silicon. The supervisor asked "am I ARM?" when it meant "does my disk hang off a USB host?". Five per-arch tables in one file existed because nobody had named the fact they all encoded. Once the fact was named once - in a build.rs table, or a seam member every arch answers - the arms collapsed. Five USB_IMAGES tables became one. Seven copies of "is configuration space reachable" became one has_hw_enumerator.

And three times, improving the code would have let us step off the ruler. The shared-surface check matched only the literal target_arch = "...", so moving a question into a build script, or onto target_pointer_width where it belonged, would have read as the site disappearing. Each time, the ruler was widened BEFORE the change landed. The third time it immediately found eight sites in services/supervisor/build.rs that had never been counted at all, and a whole layer - the neutral kernel - that had no ratchet while userspace had had one for a week.

A measurement that gets better when you improve the code is not measuring the code.

The lesson that cost the most had nothing to do with architecture. The VisionFive would not boot. Its extlinux.conf was CRLF, because .gitattributes said *.conf text and "text" on a Windows checkout means CRLF - so U-Boot read the trailing carriage return as part of every FILENAME and could open nothing the config named. The menu rendered perfectly the whole time, because a stray CR in a display string only returns the cursor.

In the failing log, a Debian file fails to load immediately after ours. I read that as an independent control - even an untouched stock file fails, so it is not us - and built two rounds of hardware theory on it: a dying card, a marginal supply, buy another card. Two reflashes later a stock card booted Debian at 22 MiB/s and disproved all of it. The second failure was never independent: with a CRLF config every label's filename carries the CR, Debian's included. Both were failing for one reason, and the second one was mine.

Two entries failing does not make the second one a control. A control has to run FIRST, or in a session of its own.

The card's own README already carried the general form of that warning, from the PREVIOUS VisionFive incident: a measurement that contradicts something the project says out loud is the moment to stop and reconcile, not to write the measurement down and move on. The project said out loud that this board boots GodspeedOS. I reasoned around it instead of reading the record.

So the branch ends with a document rather than a number. docs/porting.md says what you write (one directory and five wiring lines), what you will unavoidably touch anyway - all 46, by kind, with what each would take to close - which of the five checkers tells you where you are, and the rule: if you find yourself editing anything else, stop and ask why. Both of its headline figures are owned by facts_check.py, so they cannot rot the way the hand count in §4.1 already had, from 8/4/3 to 6/4/2, with nothing watching.

What is still NOT proven is written in it too, because the alternative is a document that flatters itself: the bounded-port test measures M1 only. It proves a fresh ISA COMPILES. Whether one boots, reaches steady state, or spawns a supervisor is listed and not asserted. And no new ISA was added on this branch - the surface was shrunk, not tested in the direction that matters. The experiment that would settle it is named: take loongarch64, already at M1, and drive it to M4, counting every file outside arch/loongarch64/ that has to change. That number is the answer, and nothing else is.

2026-09-13 to 2026-09-14 - The day the enforcement layer was pointed at itself

The previous entry ends with five machines and ran 461, failed 0. This one starts the morning after, with a question that had no instrument behind it: the project had ten commandments and five of them mechanised, and everyone assumed the other five were the unmechanisable ones.

They were not. They were the ones nobody had tried.

The realization: you do not find an absent gate by reading the rules. You find it by making the shortcut tempting and watching where a contributor goes. The method was to hand a deliberately weak model a task whose correct answer is harder than its shortcut, with no mention of any checker, and then read the diff. Four tasks, four different commandments, and every one of them found something that twelve green checkers had been walking past.

That last row is the honest frame for the rest. Not one byte of any of the four shipping kernels changed in two days. Everything here is the layer that decides whether the next change is allowed.

What each gate found the first time it was run

Not one of them found nothing, which is itself the finding - these were not hypothetical rules.

• A rule written down beside an enforced rule, enforced by nothing. kernel/src/arch/CLAUDE.md names "two rules the boundary is built on", and arch_boundary_check.py sat next to it enforcing only the first. Eight neutral-kernel sites were violating the second, and they surfaced only when a 32-bit port hit them as compile errors - which is the worst way to find a rule you already wrote down, because the porter must first work out that the fault is yours.
• Authority pinned by NAME, not by CONTENT. I-service-table pinned which services the kernel knows; nothing pinned what those services are given. Adding an IRQ line, flipping has_console_read, or adding a privilege bit changed no name, no cfg, no unsafe, and no syscall. The enforcement layer had said so about itself for months, in a field nobody read: "that is Commandment VII, and it is not built yet."
• A contract that claims authority nothing grants. The weak model added service_control = true to a service's .toml, wrote the restart logic, and reported success. It compiled, osdev validate passed it, and all twelve checkers stayed silent - correctly, because nothing that grants authority had been touched. The service would have had every call denied, the denial discarded twice, and a log line printed before the call asserting a restart that never happened.
• Five services holding a send cap they cannot refresh. Every peer here is restartable and chaos kills them all, so a stale cap is a wasting asset. The failure is silent by construction: trace emission is try_send with the result deliberately dropped, so a dead peer looks exactly like a live one.
• Seven user-facing verbs with no specification, in a folder whose own conventions document declares itself canonical for every utility. One of them is selfcheck - the most-used verb in the project, the one every hardware run in this repository reports through.

The one that was our fault, not the model's

The contract finding was the sharpest, because the model was following the constitution. CLAUDE.md said, in two places, that the kernel mints capabilities from the contract at spawn. It does not, and never has: the kernel is no_std and cannot parse TOML, and authority arrives in the supervisor's spawn request. contract_check.py exists because the .toml is a second declaration that drifts.

And it had been caught before. An audit flagged it on 2026-07-12, quoting the section's own words back at it, and marked it RESOLVED. The resolution changed the code and left the document. Two months later a contributor read the document and did exactly what it said.

A fix that closes a defect and leaves the text that caused it has not finished. That is the rule this day earned, and it is why §13.6 and §14.1 now carry a dated amendment instead of a shorthand that was nearly true.

The dominant failure mode of an enforcement layer

Three times in two days, an instrument reported a clean pass while reading nothing:

• a regex alternative written as \bcfg! inside a non-raw Python string, where \b is the BACKSPACE character. That branch matched nothing; every cfg! site counted zero. print() of the pattern looked correct, because a backspace is invisible. Only repr() showed it;
• a site scan that counted #[cfg] attributes and silently ignored cfg!() expressions, reporting 22 where the answer was 28;
• a peer parser that matched a literal &[..] and therefore read no peers at all for the two services whose row passes a named constant - so the authority gate shipped two days earlier had been passing over grants it could not see.

None of these fails loudly. A checker that has stopped matching is indistinguishable from a codebase that has stopped violating, and the second reading is the flattering one. The only defence that worked was making the instrument assert itself against a known-matching input at load time, and refusing to run when it cannot. shared_surface_check.py now does exactly that, with the incident in the comment.

A count you did not watch change is not a measurement. The corollary the project already knew for hardware counters turns out to apply to its own checkers, and more sharply, because a checker is believed by definition.

What was deliberately NOT built

Three designs were measured and thrown away rather than shipped: matching duplicate constants by VALUE gave 3,381 candidates, restricting to values the arch seam names gave 715, and both were essentially coincidence. Matching by NAME within one crate gave 31, every one readable. A baseline of several hundred entries is not a gate, it is a graveyard.

And Commandment X was not closed by inventing a tenth check. Its kernel half was already enforced four times over under Commandment I; its user half genuinely had nothing, and now has one narrow check that reconciles the vocabulary against its documentation. What remains - place complexity in the layer that naturally owns it - is a judgement no pattern reads, and it is written down in docs/x-residue.md rather than implied to be covered. The number reached 10 of 10 because a real gap closed. A number optimised instead of a property secured is the failure §26.3 exists to prevent, and the residue document is how that stays true.

The Named Bugs - the teachers

Some bugs are worth naming, because a name turns a failure into shorthand. Years from now someone will say "do not repeat the Registry Illusion," and everyone in the room will know exactly what that means. These are not listed because they were bugs. They are here because they were teachers.

• The Truncated Right (2026-07-25) - resource_invoke packed its right field at bit 32 of a syscall argument. On 32-bit ARM that register is 32 bits wide, so the field arrived as zero: the kernel validated a right of nothing, fs received a badge of nothing, and a READ-only file capability invoked declaring WRITE walked straight past the check meant to stop it. Taught: authority can be lost to arithmetic. A capability check cannot fail safely if the right never arrives to be checked - and a value assembled by shifting hides its width from the reader, which is why the 32-bit ABI rule exists and why this still slipped past it.
• The Silent Clear-Halt (2026-07-25) - the USB reset recovery discarded the result of its control transfers with let _ =, so a recovery that achieved nothing looked exactly like one that worked. One failed command then wedged storage forever with no explanation. Taught: a discarded error does not merely hide a failure, it points the investigation at the wrong component - here, at the operator's hardware, which was innocent. (§26.7, the sharpest lesson it has taught.)
• The Registry Illusion (2026-06-21) - an entire service existed to store a name-to-cap mapping that turned out to be almost entirely derivable: the supervisor already held the caps, the kernel needed only a tiny recovery anchor. Taught: most of what looks like irreducible truth is a derived view dressed up as a source. (Commandment III.)
• The Sleeper on Core Zero (~2026-05-30) - on the Dell Wyse, a service blocked on recv on the bootstrap core was never woken: core 0 sat with interrupts disabled, and the cross-core wake IPI had nowhere to land. Taught: a cross-core wake is only as good as the target core's willingness to be interrupted. The first appearance of the IF=0 family.
• The IF=0 Respawn Wedge (2026-06-23) - the kernel respawned the supervisor from inside an interrupts-disabled timer ISR, so it could not acknowledge the TLB-shootdown IPIs it depended on, and the whole machine froze. Taught: a recovery path that runs where it cannot be interrupted cannot recover; privileged work belongs where interrupts are enabled.
• The Global TLB ACK Wedge (2026-06-24) - at 71,000 carnage rounds, two cores each waited on the other to acknowledge a global TLB shootdown, and both stopped. Taught: a global barrier under true concurrency is a deadlock waiting for the one interleaving that triggers it; make it per-core.
• The DMA After Death (2026-06-28) - a driver was killed and its memory reclaimed, but its device's DMA engine kept writing into the freed-and-reused frame, and eventually scribbled over a kernel page table. Taught: a device's DMA outlives the driver that aimed it; quiesce the hardware before reclaiming its memory, and reserve the arena so a stray write can never reach a page table.
• The Mortal Shell (2026-06-21) - the shell, the user's own interface, was the last thing that stayed dead if you killed it. Taught: nothing escapes restartability, not even the face of the system. (Invariant 6; identity over location applies to the shell too.)
• The Test That Lied (2026-06-28) - a flood-storm counted a full queue as "drained" and passed a target that was broken. Taught: a green check from a test that cannot fail is false confidence; fix the verdict first. (The bug behind "the day my own test lied to me," above.)
• The Four-Thousand-Year Uptime (2026-06-28) - uptime briefly reported ~4,987 days because the clock was derived from a momentarily-glitched source. Taught: a derived view is only as honest as its source; deglitch at the source, never paper over the symptom.
• The Mount That Only Knew Success (2026-07-09) - a rapid double kill-storm fed fs a garbage disk capacity; it chased a backup superblock past the end of the disk, the AHCI port stuck its command-issue bit without ever setting BSY so recovery never fired, and the mount loop retried the impossible read forever. Taught: a wait that can observe only success is an infinite wait on failure - the same Commandment VIII lesson, re-learned at a new loop. Hold the principle at every wait, not once. (The 2026-06-30 teaching, come back for the mount loop.)
• The Realtek Head Desync (2026-07-12) - on the Wyse's RTL8168, transmit was driven through a multi-slot C+ descriptor ring, but the controller's TPPoll advanced its own head independently of the ring index the driver tracked; the two drifted, OWN bits stranded, and TX wedged with a telltale desc=0xb000004a isr=0x0091. The fix was to stop pretending the ring was deeper than the driver could keep coherent: a single transmit descriptor, always end-of-ring, poked once per frame. Taught: match the driver's ring discipline to what the controller's poll actually advances - a phantom ring you cannot keep in sync is worse than one honest slot. (This bug is invisible in QEMU, which emulates an e1000, not a Realtek - it existed only on hardware and was only ever found there.)

Add to this list as the project earns new names. A bug that taught something deserves to be remembered by name.

Compiled once, looking back - a record of what was understood, and the rules that understanding produced.

Godspeed.

2026-09-26 to 2026-09-27 - The day a rule nobody could read stopped counting as enforced

The previous entry ends at 10 of 10 commandments mechanised. This one starts with what that number hides: a rule is not enforced when a machine can check it. It is enforced when a contributor can understand why it said no. Eighteen checkers ran on every build, and there was no way to ASK them anything. You learned the rules by failing a build, which is precisely what 22.7 says the repository must not require of a stranger - and 22.7 had said so, in writing, for months, with nothing holding it:

"A gate that fires with an unhelpful message is a finding, not a pass."

That is a claim about rendered TEXT. Nothing in the project had ever read the text.

The realization: the enforcement layer had been built as a wall and needed to be a door. Not a second gate - the same gates, askable, with one verdict, naming which of the Ten a violation breaks and what to do about it. osdev conform, rendering like rustc: a stable code, the commandment, = why before = help, both escape routes stated including the legitimate one, and a count of how many checks RAN - because a run that silently skipped twelve and printed a clean verdict is the failure the whole thing exists to prevent.

The line that turned out to be the design

Two kinds of finding, and conflating them would have produced a tool nobody could trust:

• Decidable - one right answer, no reader needed. An em-dash must be a hyphen.
• Judgement - the fix is not determined by the violation. A comment naming a dead symbol might want correcting, or might be correctly RECORDING a removal and want baselining, and half of what the comment sweep of the day before had found was the second kind.

So conform fixes the first, reports the second, and always says which it did. A clean run prints fixed 3, 0 need a decision, never a bare ok: "I changed your files and said nothing" is what makes people distrust a formatter. And the rule that fell out - conform may only fix what a gate would fail you for, and it takes the scope FROM that gate - is why it imports dash_check and reads the checker list out of osdev/src/main.rs rather than restating either. Nothing restated cannot drift.

The instrument agreed with me, again

Twelve defects were found in this work and every one by running the thing rather than reading it. The one worth keeping is the golden-file harness, --bless, which writes the observed diagnostic into each test case so nobody hand-copies twenty-four of them. On its first real use it produced a green suite of eighteen containing five tests that proved nothing: two plants aimed at examples/ when the checkers scan services/, one writing back bytes identical to what was already there, one citing a line in a sentence with no word to anchor on, and one appending a duplicate TOML table.

It recorded "no finding" as the truth, five times, and reported 18 of 18.

A golden file defends a judgement; it cannot make one. That sentence was in the docstring before it cost anything, which is the only reason anybody looked - and it is the same shape as every instrument in this project that has ever lied: the counter declared inside its loop, the flush verdict that could not tell a refusing device from an absent one, the health line reading disk yes while 400 of 412 probes failed. An instrument that agrees with you is the one to distrust.

The same day, a checker written that morning exempted itself from the problem it describes: its docstring cited XHCI_FOUND and CNTP_TVAL as examples of dead names, its own corpus included its own prose, and so every name it mentioned resolved BY being mentioned. Fourteen names passed, including the two dead statics that had motivated writing it at all.

And the last one arrived after the merge, which is the one worth remembering longest. The fixture that plants a CRLF boot config planted its carriage returns by INHERITING them from its own file - and .gitattributes gives a Windows checkout CRLF and everyone else LF. So it fired here and would have found nothing in CI, where --bless would have written "no finding" down as the truth for the third time. A fixture that inherits bytes from the checkout measures the checkout. Both numbers were green on the machine that produced them, and neither could have revealed it; what revealed it was deleting the files and checking them out again. The bytes a plant needs are declared now, and the fixtures are pinned to LF, and the proof is that forcing all 24 to CRLF leaves exactly one failure - the gate correctly reporting 24 files full of carriage returns.

What a catalogue is for

The answer to "have I seen every message?" was no - fifteen of twenty-seven codes, and two of the Ten, which is the primary vocabulary. So the messages are written down: tests/conformance/GALLERY.md, one entry per rule, generated by planting a real violation from the same corpus the selftest verifies. One corpus, two views, and the coverage list COMPUTED - so an absence nobody explained is reported as a defect rather than mistaken for coverage.

Two honest results came out of insisting on that. GS0008 can never fire: Commandment VIII has no mechanical check at all, and a code advertised in --list that nothing can produce reads as coverage, so it says so. And Commandment III's check has a narrow real blind spot - it matches a plain integer literal, so an expression-valued constant duplicated across two files is invisible to it. Both were found by trying to write a test for something and failing.

What did not change

Not one byte of any shipping binary. Eighteen checkers before, eighteen after; the same rules, the same verdicts. What changed is that a contributor can now ask, and be answered in words that name the law and the fix - and that the answer itself is held to a standard, because it is written down where a diff can see it.

2026-09-27 to 2026-09-28 - The day the radio scanned the room

The Pi 4's onboard WiFi - a Broadcom CYW43455 behind the Arasan SDIO block at fe300000 - went from a device nobody had proven was a radio to one that listed the ten networks in the room, with names, signal strength and channel, in two days and about twenty-five boots. docs/wifi.md sections 13 through 35 are the record; this is what the record is about.

A radio is a second computer

The chip has an ARM Cortex-R4 with 800 KiB of memory and no firmware of its own. Until the host writes 609 KB into that memory and releases the processor, there is no 802.11 anywhere inside it - nothing to ask, nothing to enumerate. Every other device this project has driven is fixed-function silicon that works from reset. This one boots from us. That single fact shaped the whole effort: phase 2 was a bootloader for someone else's CPU, and its bugs were bootloader bugs - the core held in reset when it should have been clocked and halted, the reset vector left unwritten, a token at the top of memory that the firmware overwrites to say it is alive.

The failures that read as facts

The chip refused a scan with BCME_NOTUP through four boots of bring-up commands that were all accepted. The cause was regulatory data: a blob called CLM, which says which channels may be used at what power, and which was vendored in this repository the whole time with a comment explaining exactly how it is delivered and why it was not yet. A radio with no channel rules will not transmit or scan, and from outside that is indistinguishable from an interface that is down. The firmware was telling the truth; it was being asked the wrong question.

Before that, the first control reply came back as sixteen bytes containing fragments of the driver's own request - cur_ where a command number belonged, dd from cur_ether**add**r in the request-id field, and -24. The driver had told the firmware its header began 16 bytes after where it actually was, so the firmware parsed the iovar name as a header and complained about the length. The correct line from the reference was quoted in the driver's own documentation, three paragraphs above the code that contradicted it. A correct citation next to wrong code reads as verification, and cost three boots.

Read the whole function

Ten of the twenty-five boots were spent on bugs that were mine rather than the protocol's, and they share a cause. Asking a reference for "the line that sets X" returns a true line that hides its neighbours: a flag that is a parameter, a value assembled from a constants list, a sequence returned in the order it was found rather than the order it runs. Every time a complete function was read in execution order - the CR4 halt, the bring-up sequence, the blob download - the answer was in it and correct first time. The rule already existed in arch/CLAUDE.md from an earlier bug in the same effort; this was the cost of knowing it and not applying it.

Boot the other operating system

The single most useful line of the two days was in a Raspberry Pi OS boot log, and it was not about WiFi: mmc-bcm2835 fe300000.mmcnr. Linux does not drive this controller with generic SDHCI at all; the Pi Foundation has its own driver for the block, with a settling delay after every register write, a data timeout, and a PIO loop that moves a whole block between checks. Every host-side comparison until that boot had been against the wrong driver. It was the operator's idea, and it replaced a day of inference with a morning of transcription.

Wait on the truth

The scan worked one boot before anyone could see it. Twelve result events and a completion marker arrived, every one decoded, and the network list never printed - because the collection loop bounded itself by a count of polls named as milliseconds, and each empty poll was a bus transaction plus a sleep. Four thousand "milliseconds" was two minutes; the capture ended first. The firmware had said complete at the two-second mark. The loop ends on that word now, and the count is a bound underneath it with an honest name. It is the project's oldest lesson - a count is not a duration - and the eighth Commandment as a fix rather than a rule.

What was borrowed and what was not

The silicon's requirements came from Linux, OpenBSD and the Pi Foundation's driver, quoted at every point of use: register sequences, header layouts, byte orders, the four-byte integer an integer command carries. What did not come along is how those systems organise a scan - dynamic result lists, callbacks into a wireless subsystem, work queues. The results live in a fixed array of thirty-two on the stack that counts what it could not keep; the driver reads frames in its own loop; the state belongs to the call that made it. Ten glommed frames were dropped on the floor because the reference drops them too and its scans work.

What is not done, said plainly

The driver scans at boot as its own self-test. The shell cannot ask it to yet, so wifi at the prompt still answers unavailable; that path, the numbered picker the operator designed, wifi join <ssid>, and secure-versus-open from the beacon's information elements are the next work. Association, the credential path and data frames are phases 4 and 5. The network identifiers from the successful scan are in the operator's capture and not in this repository, because the neighbours did not agree to appear in it.

Later the same night - it became a command

wifi list at the prompt: the shell asks the driver over IPC, the radio sweeps, eleven records print in the order the specification set, and a second run scans again on the same session. Neither contract changed - the shell already reaches drivers by name, and the driver already replies through the cap it is handed. It cost one boot, to the oldest bug in the notes: a peer spawned after you has to be reacquired by name before the first request has anywhere to go. Phase 3's deliverable - wifi list lists the SSIDs in the room - is met as written. Security stays unknown until the beacon's information elements are read, and quitting does not yet stop the radio's sweep; both are recorded in the driver rather than pretended.

2026-09-29 to 2026-09-30 - The day the radio joined, and the cable learned to step aside

The scan had shown the room. Joining a network in it was supposed to be the firmware's job - phase 4's row in the plan says "firmware-offloaded" - and the firmware said no, three ways: the switch that hands it the WPA2 handshake does not exist on this build. So the host runs the handshake, as OpenBSD's does, and the driver grew the cryptography a station needs and nothing more: SHA-1, HMAC, PBKDF2, the 802.11 PRF, AES-128 with a computed S-box, the RFC 3394 unwrap, every one checked against a published vector at boot. Then the four messages, each quoted from net80211 at the line where it is answered.

Two bytes, twice

The first run of the handshake verified message 3 - which settles that the passphrase, the key derivation and the signature path were all right, since the access point's MIC is computed with a key derived from the same passphrase - and was refused at the key install. The key structure had been sized by adding up its fields: 162. sizeof is 164, because C pads a 4-aligned struct's tail, and the firmware checks sizeof. The operator had rechecked the passphrase several times; the log says it was never in question. The next morning the signal reading fell to the same lesson: ten bytes of fields, twelve of sizeof, refused for a day as BADARG. A hand count of a C struct cannot see the padding. Read sizeof off a compiler.

A key is kept only once it has joined

The driver kept the derived key the moment the passphrase arrived, so a join that failed left behind a key nothing had proved, and the next wifi join used it without asking. The operator had to forget between every attempt. Now a typed passphrase becomes a key in a working buffer, enters the table after JOINED and not before, and is zeroed either way. Store on success, never on receipt.

The cable always wins

With the join working the operator pulled the ethernet cable and expected ping to follow the radio. It did not, because nothing above the join existed - and when asked which link should carry the frames when both are there, the answer was five words: "cable always wins. unplug the cable, switch to wifi automatically." So the radio became the fifth backend of nic-driver, the link front end, over the same three frame ops the Pi 2's USB adapter answers, and the cable decides: while the PHY reports a link the frames go over it, when it does not they go to the radio if it is joined, and back when it returns. net-stack needed one rule the design had not foreseen - a link whose address changes is a different link, and a cable never did that - and re-configures when the address under it moves.

The first boot proved it and then went deaf

Cable out, the stack configured itself over the radio on the first try: discover, offer, acknowledge, ARP, an echo to the gateway, all through the air. Then every exchange with the radio began timing out at exactly its bound, and observe showed the shape: nic-driver blocked with sixteen stale requests behind it, the radio idle with an empty queue. The radio was answering nothing because it had nothing to answer on: the driver had never released a reply cap, a task holds sixty-four, and from the fiftieth request on the kernel could install no more. Three lines. The wifi commands alone had never reached sixty-four in a boot; the stack's polling reached it in seconds. The same shape exposed two more things, both recorded: a one-second bound on the radio lets a caller's inbox fill behind the call, so it is a hundred milliseconds now; and the kernel, handed a message for a blocked receiver whose queue is full, drops it and says it was delivered - a silent fallback in the IPC path, held for the next kernel change (and fixed that afternoon: it returns QueueFull now, backlog/fixed/65).

Works beautifully

The second boot: ping over the radio, 36 of 38 with the two lost being the switch itself, then none; cable in, a new lease, ping over the cable; out again, over the radio with no new join; twice round. The radio answers in under a millisecond. The operator's words were "Works beautifully (ethernet cable plugged and unplugged)", and the sentence after the join, which had four quote marks in it, was rewritten to have none. Later that day the driver learned to answer the access point's periodic group-key rekey, which would otherwise have taken the link down on the router's timer; it cannot be provoked and has not yet been seen. The network's name and the access point's addresses are in the operator's captures and not in this repository.

2026-09-30 to 2026-10-02 - The day the warm chip turned out to be a slow host

The radio joined, and then the operator ran chaos with it carrying the link: 826 rounds, the kernel never panicked, nothing wedged, and the radio was dead from the first round. Every one of 397 respawns of wifi-driver found a chip that would not take a new firmware. Three days later the same test ran 100 rounds and 50 rounds with the radio up at the end of both, and a power cycle came up cold every time. Most of what lay between was learning which of the things the logs said were true. docs/wifi.md 45 to 58 is the record, kept with its wrong turns in it.

Adopt, do not restart

The first fix was to stop doing the thing that broke. A kill of the SERVICE does nothing to the CHIP: the firmware the dead instance loaded is still running, still associated. The respawn was resetting the chip and loading a new firmware over a live one, which is the case the chip's ROM will not boot. So a respawn now looks first, with two register reads, and a firmware found running is ADOPTED - its keys are read back and the link is back in about seven seconds. The best recovery is often to notice there is nothing to recover.

Power, granted twice

For a firmware that has truly stopped, every reference driver cuts the chip's power, and on the Pi 4 the pin that does it lives behind the firmware mailbox the kernel owns. The kernel was already powering the SD domain at boot, because a window onto an unpowered device is not a grant. What it could not do was grant it again. So DevicePower is the device grant made renewable: given only to the service holding that device's window, and it reports what the pin READS BACK, not that the request was accepted. In QEMU, where the pin is not emulated, the first version reported a cut that never happened.

The chip was never warm

Six host-side resets, a RAM clear, and the "warm chip" theory with every one of them: whatever survived a reset, it made the next firmware trap at pc 0x25. The number that ended it was a stopwatch, not a register. A cold upload took 3.26 s and every upload after a cut took 7.19 s, five times out of five, on the same bus. The reason was in the firmware's own documentation: initial_turbo holds the Arm cores fast for the first minute after boot, "or until cpufreq sets a frequency" - and nothing in GodspeedOS had ever set one. So a minute in, the cores dropped to their minimum and stayed there. Every load inside that minute came up cold; every load after it was slow, and trapped. force_turbo=1 proved it on the card: five power cycles, every one cold. Six resets had been tested against a host running at a fraction of its speed, and the chip was blamed for it.

Why a slow upload makes the firmware trap is still not known, and is written down as not known.

Mechanism here, policy there

force_turbo holds the cores fast forever to make a three-second load work. The operator asked whether the kernel had to own the clock at all, and whether a fast clock could be left stuck on if the service asking for it died. Both questions shaped the answer. The kernel learned one thing, CpuClock: set the clock to the firmware's own minimum or maximum, and read back what it is. It cannot name a rate and never decides when. A new service, power, owns that: it hands out LEASES of up to 30 seconds, holds the clock at its maximum while any is open and at its minimum when none is, and a lease nobody returns expires on its own. The driver takes one for each load. On the card: 600 MHz between loads, 1500 MHz during them, five loads, every one cold. A grant that can outlive its holder needs a deadline, and the deadline belongs with the policy, not the mechanism.

The clock left the network stack

net-stack used to fetch the time itself, inside its serve loop, so a ping could queue behind a time server. Now net-stack knows nothing about clocks. It offers one general operation, "send this datagram and answer me when the reply comes", and serves everyone else while it waits. time builds its own query with a random nonce and checks it comes back. Testing that in the emulator found two bugs that the real board could never show. The emulated Pi 4 has no random-number block, so the first time service that asked for a nonce took the KERNEL down from an unprivileged call; the kernel now probes the block at boot like any other device. And a deliberately unanswerable time server showed net-stack's "no reply" arriving eight seconds late, because its deadlines were checked only when some unrelated message woke it. On real hardware the server always answers, and neither would ever have been seen.

An answer is not a reply to the question you just asked

The kernel's Call takes the oldest reply FROM the peer, not the reply to the request just sent. So an answer the shell had stopped waiting for was read as the next command's: a stale OK made powercycle kill the driver mid-cycle and leave the chip unpowered, and late radio downs were counted as chips that "came up warm" in 150 ms. The first fix drained the queue; the second COUNTED what the driver still owed and skipped that many. QEMU then showed why the count could never be right: it was counted by watching the reply mailbox, every peer's replies land there, and nothing on a message says who sent it. A stray two-byte answer from another service cancelled an owed radio answer, and the next wifi status printed the previous one's. Now every request carries a tag the driver hands back, and every wait takes only the reply with its own tag. A fact carried in the reply beats a count kept beside it.

The same hunt found the SDK destroying other services' capabilities. After a request is sent, the kernel moves the reply capability to the peer and empties the sender's slot, and the next capability the sender receives lands in that slot. On a timeout the SDK "reclaimed" the slot by number, and so deleted whatever had arrived in it - another client's way to be answered. It was on every service's request path, on every port. The boot that morning logged reply cap is dead twice; the boot after the fix, through a 50-round chaos run, logged it none. A slot number is not a name for what is in it.

Chaos, again

chaos max-carnage, 100 rounds and 701 kills with the radio carrying the link, every service restarted between 45 and 56 times, and at the end the radio rejoined, time set the clock from the network, and 19 pings out of 19 came back. Fifty more rounds two boots later, with the same ending. The chip is a second computer that chaos cannot touch; the driver is Godspeed's, and it recovers the way everything else does.

And it pipes

The specification had said wifi list | count worked; the shell refused it, because wifi had never been added to its list of things that can start a pipe. Now the reports pipe and the actions refuse with a sentence - join asks for a passphrase, and in a pipe its prompt would vanish. Then wifi list became RECORDS in a pipe, so wifi list | sort reverse dbm puts the strongest network first. That needed a number the record model did not have: signal is measured in dBm, always below zero, and every number in a table had been unsigned. Writing the magnitude would be a different fact, and text sorts -9 after -80. So the record model gained a signed number, pulled into existence by the one column that needed it.

2026-10-15 to 2026-10-19 - The day the machine learned to trust what it fetched

Until this week a Godspeed machine ran exactly the software it was built with. Five days later it could reach the internet over TLS, fetch a package someone else had published, and prove who signed it and that no byte had changed. It could then start it, upgrade it while it ran, and put the old version back if the new one would not start, on all five boards. It took three repositories, not one: the OS; godspeed-cli on the developer's workstation; and godspeed-registry, a Cloudflare Worker over R2. Released as v0.29.0, "Signed, Sealed, Delivered".

No library fit, so the protocol was written and the arithmetic was not

The registry had to be reached over HTTPS; software fetched over a channel anyone can alter is software anyone can replace. No TLS library fit this tree as it stood. The one that keeps to the no-heap rule is Apache-2.0 only, which GPL-2.0-only cannot include, and the rest need a heap or are C. So sdk/tls is a TLS 1.3 client written from RFC 8446: the key schedule, the record layer, the handshake, and the verifier that says why a chain was refused. The parts that are easy to get subtly wrong were taken, on purpose, from libraries built for them: RustCrypto's hashes and AES-GCM, dalek's X25519, p256 and p384, and rustls-webpki for the chain. It is section 26.14 drawn at a new line: borrow what is a fact about mathematics; write what is a decision about this system.

It is deliberately narrow: a client, TLS 1.3, one cipher suite, one key exchange, ECDSA certificates, and every buffer the caller's. RFC 8448 prints a whole handshake byte for byte, and the tests reproduce every value in it. The narrowness was paid for once, honestly: a server with only an RSA certificate cannot be checked, and godspeed says so in a sentence rather than as alert 40.

One contract, checked in three places

The CLI that publishes, the Worker that accepts, and the machine that installs each verify a package with the same crate, godspeed-package. The Worker checks a manifest when it is reserved, each file as it is uploaded, and all of them again at finalisation; the machine then checks it once more, from scratch. The trust chain is the same everywhere:

• a root pinned at first contact;
• a timestamp and a snapshot that make a stale registry look stale;
• namespaces that say which keys may publish under which name;
• a manifest signed by one of those keys.

The Worker signs only the two documents that must change without a person: the snapshot after each publish, and the timestamp every six hours. Which keys may sign for whom is signed offline, and the Worker cannot change it. A compromised server can stop answering, but it cannot lie about who published what.

Fetched is not installed, and the supervisor believes nothing it checked yesterday

A fetch keeps a package and grants it nothing. An install is the supervisor reading the package back from the disk, checking the signature, the key's standing, the contract and the binary against the manifest, and handing the kernel the very bytes it hashed. It does that at install, at every boot and at every restart, with nothing cached between. A check whose result is remembered is a check of the past.

An installed package gets no privilege. It gets the peers its signed contract asks for, and only the ones the operator approved. It runs under a publisher/name no built-in service can hold, so it can never answer for one when a client reacquires a name.

Kinds are decided by who governs the life

Four kinds of program arrived: service, utility, app and driver. The question that settled them was not how long each runs. It was who decides when it ends:

• the system restarts a service;
• a utility ends itself with a status;
• an app lasts as long as the operator keeps it open;
• a driver lives with its device.

A word processor is an app even if it runs all day.

The utility needed the kernel to learn one thing, Exit, and it takes no capability. The rule that every syscall checks a capability exists so that nothing reaches authority without one, and the only task Exit can end is the caller. A rule is read by what it protects.

Erlang's upgrade, without changing running code

The operator asked for Erlang's upgrade in place. What the constitution had rejected, new code loaded into a running program, stays rejected. What was built is the half of Erlang anyone can observe: the new version starts beside the old one under the same name, the old one hands its state over in one message and ends, and the name moves. The bytes that run are still the bytes the supervisor checked.

The offer carries a key from the hardware random source, and a board without one does no handover at all rather than one keyed by the clock. A version that cannot take over is stopped and started instead: its checks run before the stop, and a failed start puts the old one back.

The download was paced by a clock, and the bugs were habits

A 10 MB file came in at 113 KiB/s in QEMU, and the number that explained it was 100. net-stack looked at the wire once per 100 ms tick, so a download moved one window per tick however fast the link was. Four changes took it to 872 KiB/s, and the T630's cable to 629 KiB/s:

• burst polling;
• a 256 KiB window;
• out-of-order data kept in the ring;
• delayed ACKs.

Then the boards found what QEMU could not:

• The RTL8168 driver emptied its receive ring before every frame it sent. It had done so since July, to recover a ring that filled while nobody read it, and that was harmless while each request had one reply. With a sender running ahead, every ACK threw a ring of data away. The e1000 driver had dropped the same habit long before, and QEMU emulates only the e1000. The fix kept the recovery, but moved it to where the chip reports the stall.
• With the reset gone, the Wyse took exactly 24 frames and fell silent without saying it had stopped. That is one ring, the same "one ring's worth" the T630 showed in July, hidden ever since by the reset. A receiver that gives nothing for a second is now restarted whether it says so or not. Every restart is logged with the bits the chip set, so the next board says which case it is in.
• The Pi 4's radio lost a large window's bursts. It hands them over as superframes bigger than its driver's buffer, and it lost them until the radio died. A connection over a radio keeps the small window until the driver can take them.
• "Connections stay open after a program ends" turned out not to be the program. The client had closed; the server simply had not sent its FIN, and fin-wait-2 waited for it with no limit, with only two slots in the table. An orphan is now let go after two seconds, as Linux does.

None of these could be seen in the emulator, and each was found by a card read line by line.

What is not done, said plainly

Downloads are not yet at the speed of the link (backlog/93):

• the RTL8168's ring still overflows;
• the Pi 4's radio still runs on the small window;
• the VisionFive's radio sends slowly;
• every connect waits on an ARP it does not need.

And on the last day the operator asked whether this was v1. The answer was not yet, and measured:

• drivers still reach past the standard library;
• the public surface has no gate that fails on a change;
• no compatibility policy is written;
• the surface changed that very day.

v1 is a promise to contributors, and a promise that is not gated is a preference (backlog/71).

Writing a program for GodspeedOS

This is the page for someone who wants to use GodspeedOS rather than understand it. You should not need MISCIS, the capability table, or the IPC wire format to read a file.

The API reference

The standard library API reference - godspeed, imported as gs. Every module carries its own documentation, including what each call blocks on, what authority it needs, and which failures are safe to retry.

The SDK API reference - godspeed_sdk, the layer underneath: the syscalls themselves, and the audited unsafe (CLAUDE.md 18.1). You should not need it. Services and drivers alike are written on gs, drivers through gs::driver (below), and scripts/one_way_check.py holds every program in this repository to zero raw SDK calls that gs covers. A driver package from outside this repository may call it too, but outside the compatibility promise: the SDK can change between releases where gs does not (docs/driver-library.md).

Four kinds of program

The developer CLI makes each with one command, godspeed new <kind> <name>, written on gs from its first line, with a contract and a README that says how to build and run it:

A fifth, library, is reusable code for the others and runs nowhere on its own. godspeed package turns a project into a signed package and godspeed install puts it on a machine; osdev test kinds installs one of each of the four, made from the templates untouched, and sees each do its job.

Start here

A whole program - every line of it, because the parts around your code are not guessable:

#![allow(unused)]
#![no_std]                  // no operating system underneath this one
#![no_main]                 // the entry point is `service_main`, not `main`
#![deny(unsafe_code)]       // required of every program; see the note below

fn main() {
use godspeed::{self as gs, Error, ServiceContext};

// `#[no_mangle]` is itself covered by the `unsafe_code` lint (an exported symbol can collide), and
// the entry symbol must be exported because the linker looks for `service_main` by name. So this
// ONE `#[allow]` is expected on this ONE item. Anywhere else it is rejected.
#[allow(unsafe_code)]
#[no_mangle]
pub extern "C" fn service_main(ctx: ServiceContext) -> ! {
    let mut fs = gs::fs::Fs::new(&ctx);

    // There is no `read_to_string`. GodspeedOS has no heap (CLAUDE.md 26.6.1), so the CALLER owns
    // the buffer and the bound is visible in the source.
    let mut buf = [0u8; 4096];
    match fs.read_into("/data/message.txt", &mut buf) {
        Ok(n) => gs::io::println(&ctx, core::str::from_utf8(&buf[..n]).unwrap_or("<not utf-8>")),
        Err(e) => gs::io::report(&ctx, "read", e),
    }

    // A program does not return. This one is a SERVICE, which waits to be stopped once its work is
    // done; a utility ends instead, with `gs::program::exit` or `Output::finish` (CLAUDE.md 14.5).
    loop { gs::task::yield_now(&ctx); }
}
}

And a contract, or it reaches nothing

Authority is granted, never assumed. A program granted no fs peer gets Error::Unreachable from its first call - not a crash, and not a silent nothing. Put this beside your Cargo.toml, in contracts/<name>.toml:

name    = "hello"
version = "0.1.0"

[resources.memory]
request = "8MiB"
limit   = "16MiB"

[capabilities]
ipc_send     = ["fs"]     # talk to the filesystem; the spawn row must grant it too (below)
ipc_receive  = ["hello"]  # your own endpoint, named after you
log_write    = true       # the log (`ctx.log`) AND the screen (`io::println`, `io::report`)

Printing is log_write. Everything in gs::io, io::report included, makes the kernel's ConsoleWrite call, and LOG_WRITE is the capability the kernel checks before it. Every task holds it, so output appears regardless; declaring it is the contract saying truthfully what the program does, and scripts/contract_check.py requires it of every program that prints.

Never ask for console_push to print. It is the authority to push bytes into the keyboard ring, which the shell reads as typed commands (SEC-2). A keyboard driver needs it; your program does not, and the same checker refuses a console_push declaration that nothing in the code uses.

This page said the opposite until 2026-10-09 - that printing needs console_push and that a program without it is silent. That was a conclusion drawn from documentation and never run; the kernel's code and the project's own test log both refute it (docs/stranger-test.md, "Run 4 was wrong about the screen").

Ask for what you use and nothing more: the contract is the reviewable statement of what your program may do (CLAUDE.md 26.9).

The contract declares; it does not grant. The kernel cannot read TOML. What a running program actually holds comes from the SPAWN REQUEST the supervisor sends, built from the program's row in the supervisor's spawn table (IMAGES in services/supervisor/src/main.rs) - for this program, ("stdlib-hello", .., &["fs"], ..). A peer in the contract with no matching row is a program that looks authorised on paper and is not (CLAUDE.md 13.6). For services, scripts/contract_check.py reconciles the two.

examples/stdlib-hello is the complete, buildable version of this, a step further: it writes a file larger than one IPC message and reads it back, and osdev test examples checks every byte.

The one thing to get right

Every call returns Result<_, gs::Error>, and the error that matters most is the one describing an operation whose outcome nobody knows:

#![allow(unused)]
fn main() {
match fs.write("/data/log.txt", b"hello") {
    Ok(()) => {}
    Err(e) if e.retry_is_safe() => { /* nothing happened: try again */ }
    Err(e) => { /* it MAY have happened: do NOT blindly retry */ }
}
}

Error::OutcomeUnknown means the request left and no answer came back before the deadline. Error::PeerDied means the request arrived and the service died before answering. Either way the write may have committed. Retrying it is not a retry, it is a second write, and for anything that is not idempotent that is a different bug from the one you were recovering from.

retry_is_safe() returns false for both, so that nobody has to derive the rule themselves. This is the failure the Stranger Test watches hardest, because it is invisible in a passing build.

If your program SERVES other tasks

Most programs do not, and can skip this. A service does: it answers requests on its own endpoint, and that is the same endpoint replies from fs and net-stack arrive on. So there is a question with a wrong answer that looks like the right one - what happens to a client request that lands while you are waiting for a reply?

The library's answer is that it does not touch it. A call waits on the reply capability it sent, so the kernel hands back that reply and leaves everything else queued for your own loop. You do not have to drain anything, and nothing you did not ask for is consumed.

#![allow(unused)]
fn main() {
// A service loop. `fs.read_into` may block for seconds; a client that speaks during it is still
// waiting on your endpoint afterwards, not lost.
loop {
    let _req = gs::ipc::recv(&ctx);
    let client = gs::ipc::take_sent_cap(&ctx);   // the reply capability the client sent with it
    let mut buf = [0u8; gs::ipc::MAX_BYTES];
    let n = fs.read_into("/data/answer.txt", &mut buf).unwrap_or(0);
    if let Some(c) = client {
        // Answers without blocking, AND gives the one-shot capability's slot back. A plain send
        // would keep it, and leak one slot per request until the table is full.
        let _ = gs::ipc::reply(&ctx, c, &gs::ipc::Message::from_bytes(&buf[..n]));
    }
}
}

Two exceptions, both of which say so where you reach for them:

• A capability you hold - an open file (gs::file::File), a socket or a connection (gs::net) - is invoked rather than sent by name, and the kernel routes its reply the same way. Anything else that arrives during one of those is held for you: drain take_held() in a loop after each operation and feed what comes back into your own loop. They are real client requests, and only you can answer them.
• A handle built with Fs::with_notice polls for an operator pressing q, which means it takes whatever arrives. That is right for a shell, which serves nobody, and wrong for a service.

If your program drives a DEVICE

A driver holds authority nothing else does - a register window, perhaps a DMA arena and an interrupt - and gs::driver is how it uses each. It holds device-NEUTRAL mechanisms only: what a register means stays in your driver, and there is no gs::driver::usb or ::wifi, ever.

#![allow(unused)]
fn main() {
let Some(regs) = gs::driver::registers(&ctx) else {
    ctx.log("mydev: no device was granted - nothing to drive");
    gs::ipc::park(&ctx)
};
regs.write32(CMD, START);
if gs::driver::wait::until(&ctx, gs::driver::wait::Budget::ms(10), || regs.read32(STATUS) & BUSY == 0).is_err() {
    ctx.log("mydev: the device did not finish within 10 ms");   // the CALLER says which wait
}
}

A driver installed as a package is given what its contract names and the operator approves: its register window, its interrupt, and a DMA arena (asked about by a question of its own, because where no IOMMU confines the device a driver with an arena can reach all of memory) - or, for a USB device, its host through bus. A device a GodspeedOS driver drives is taken over while the package is installed. All but the registers arrived after v0.30.0 (docs/developer-services-design.md 13.1). The drivers in this repository use all of the above. docs/driver-library.md is the design and the record of each module's arrival.

gs::program::mode is the mode a program was started in, for one that does more than one thing.

What the library will not do

• Allocate on your behalf. No heap, by design. You pass the buffer.
• Hide a failure. There is no silent retry and no fallback path. If something did not happen, the call says so, and if it might have happened, it says that instead.
• Grant authority. A handle is not a permission. gs::fs::Fs::new carries nothing of its own: every call rides the capability your contract was already granted, and a service that never asked for the filesystem gets Error::Unreachable from the first call. The library makes granted authority convenient to use; it never makes ungranted authority available.

The design report

How the library was designed, and what building it changed - including the mistakes found by migrating real services onto it, the friction reported rather than worked around, and what is deliberately not built yet.

The brief it was built from - the original requirement, annotated with what was met and what was not.

A native standard library for GodspeedOS - Phase 1 design report

Status: Phase 1 report, REVIEWED AND APPROVED 2026-09-23. The first slice is implemented on feat/stdlib - stdlib/rust with error, call, fs, io; examples/stdlib-hello; services/recorder migrated. Option A was taken (services only, no kernel change); the terminating task of §1 was left open and unimplemented, which is the point of recording it here. (2026-10-25: since closed by option B - Exit, syscall 57, added 2026-10-17 (CLAUDE.md 14.5) - and a program that ends itself is written on gs::program.)

What follows is the report as written before any code, kept as it was argued. §7 onwards records what building it changed, section by dated section; §25 (2026-10-09) is the latest, every service moved onto gs.

1. The headline: there is nothing for a standard library to be a library FOR, yet

The brief asks for this to become possible:

use godspeed::fs;

fn main() -> Result<(), godspeed::Error> {
    let contents = fs::read_to_string("/data/hello.txt")?;
    println!("{contents}");
    Ok(())
}

Three things in those six lines do not exist in GodspeedOS, and only one of them is a library problem.

fn main() does not exist. Every runnable thing in this repository is a SERVICE, and its entry point is:

#![allow(unused)]
fn main() {
#[no_mangle]
pub extern "C" fn service_main(ctx: ServiceContext) -> !
}

All 14 examples return !. They cannot return. There is no exit syscall: of the 52 syscalls in kernel/src/syscall/dispatch.rs the only one that ends a task is Kill (8), which kills a task by name and is gated behind service_control - a capability held by the supervisor, and one no application should hold, since holding it means being able to kill anything.

There are no applications. utilities/ holds 56 utility specifications. Not one of them is a program. read, dir, copy, seal, churn and the rest are FUNCTIONS INSIDE services/shell/src/main.rs - cmd_read, cmd_dir, cmd_copy - in a single crate of roughly 17,000 lines. The shell is not a program launcher; it is the program, and the utilities are its subroutines.

So "a programmer writes a small Godspeed utility" currently means "a programmer adds a function to the shell". A standard library cannot change that on its own, and a standard library that pretends otherwise would be the first thing in the repository to lie about the architecture.

This is the STOP condition the brief names, and it is being reported rather than worked around:

If an apparently convenient standard-library API requires a new kernel responsibility, STOP. Document the missing mechanism and explain why it appears necessary before making any kernel change.

What is actually missing

A terminating task: something that is spawned, runs, produces a result, and ends, releasing its resources and reporting an outcome to whoever started it.

Is that a new MISCIS responsibility? Careful reading says no, and that is the important part:

• The kernel already reclaims a task's frames, kstack and capability table when it dies, and already bumps its generation and wakes blocked peers (§14.2). Voluntary exit needs none of that built.
• The kernel already notifies the supervisor of a death, and the supervisor already decides what to do about it. Today the answer is always "respawn".
• What is missing is a task's ability to say "I am finished, and here is my status" rather than dying by fault or by someone else's Kill.

That is arguably not a seventh responsibility but a completion of the first six: it is the Scheduling and Capability machinery that already exists, reached through one more syscall, with the policy (what a finished task's status means, whether it is restarted) staying in the supervisor where §26.10 puts it.

But it is still a kernel change, so it is not mine to make. Three options, and a recommendation:

Recommendation: A now, B as a separate reviewed change, never C. C reintroduces the security objection that killed backlog/fixed/41: a deputy holding service_control on behalf of arbitrary programs. A is honest and immediately useful. B is the real answer and deserves its own discussion rather than arriving as a side effect of a convenience library.

2. What the repository already has

Inspected: sdk/rust/ (6,944 lines across 12 modules), all 20 services, all 14 examples, the 52 syscalls, and the fs/block wire protocols.

3. The repeated plumbing, measured

3.1 The filesystem wire protocol is hand-copied between crates

FS_OK is declared independently in four crates: fs, shell, copier, recorder. OP_STAT_FILE = 12 in two. The shell re-declares 21 of the filesystem's 27 opcodes.

Reading a file means knowing the byte layout. From cmd_read in the shell, abbreviated:

#![allow(unused)]
fn main() {
let stat = fs_request_q(ctx, OP_STAT_FILE, path, &[]);      // three outcome arms
let sp = stat.payload_bytes();
let exists = sp.first() == Some(&FS_OK) && sp.len() >= 11 && sp[1] == 1;
let is_dir = exists && sp[10] == 1;
let size = u64::from_le_bytes([sp[2], sp[3], sp[4], sp[5], sp[6], sp[7], sp[8], sp[9]]);
// then loop read_at in IO_CHUNK pieces, handling errors at each step
}

Roughly thirty lines, and every one of them is an opportunity to index the wrong byte. This branch already shipped a bug of exactly that shape: a guessed opcode (FS_OP_WRITE_FILE = 1, actually 10) made churn write nothing for twelve seconds and report success.

This is the clearest candidate in the repository. The wire format is a fact the filesystem owns; every other crate is currently re-deriving it from a comment.

3.2 The honest failure model exists, and the ergonomic path throws it away

DeadlineOutcome already distinguishes the states the brief asks about:

#![allow(unused)]
fn main() {
pub enum DeadlineOutcome { Reply(Message), SendFailed, QueueFull, Timeout }
}

That is the right model and the brief's instruction not to invent a parallel one is correct. SendFailed means the request never left, so retrying is safe. Timeout means it may have committed, so retrying is how one copy becomes two. The distinction is load-bearing.

The problem is that it is one of eight variants and three enums (ReqOutcome, DeadlineOutcome, DeadlineOutcomeInto), and the shortest-named ones return Option<Message>, which collapses SendFailed and Timeout into a single None. services/copier says so at the call site:

"Retry only on Err (the send failed), NEVER on Ok(None) (the deadline passed)... a slow fs is alive, and re-sending a write to it is how one copy becomes two. request_with_reply_deadline cannot express the difference."

Five services reached for request_with_reply_call_err to get the distinction back: block-driver, control, copier, nic-driver, recorder.

So the stdlib's job here is not to design a failure model. It is to make the honest one the DEFAULT and the SHORTEST path, and to stop offering the lossy one for new code.

3.3 Every client re-implements reacquire-and-retry

§14.3 puts the obligation on the client: a cap to a restarted service is stale forever. Every service that talks to fs therefore carries its own "send, and if the send failed reacquire by name and try once more" loop. It is about fifteen lines, it is subtle (the retry must NOT cover the timeout case), and it is written out separately in each crate.

4. Proposed minimum surface

Every module below answers the brief's seven-question architectural test. Nothing is proposed because it would round out a list.

Explicitly NOT proposed yet, because the brief says to leave out what is unclear:

• net - the brief asks for a network-oriented migration, and I would want to inspect net-stack's socket surface properly before claiming a shape. Deferred to a follow-up, not dismissed.
• task, time, cap - no demonstrated repeated plumbing found. time is one syscall, cap is already ServiceContext, and task needs the §1 answer first.

The API shape Godspeed actually wants

fs::read_to_string returning a String cannot exist: there is no heap (§26.6.1), deliberately. Distorting Godspeed to resemble Rust std here is exactly what the brief forbids. The honest shape is the one the repository already uses everywhere:

#![allow(unused)]
fn main() {
// The caller owns the buffer. Bounded by construction, no allocator, no hidden growth.
let mut buf = [0u8; 4096];
let n = gs::fs::read_into("/data/hello.txt", &mut buf)?;
gs::io::println(str::from_utf8(&buf[..n])?);
}

That is six lines against thirty, removes every raw byte index, and does not pretend the machine has a heap.

5. Risks

1. The stdlib must not become a second SDK. ServiceContext is 4,059 lines and already the single door. If gs:: wraps all of it, there are two doors and Commandment IV's "what can this service reach" question gets two answers. Proposal: the stdlib wraps the WIRE PROTOCOLS and the REQUEST PATTERN, and re-exports ServiceContext untouched for everything else.

2. Authority must stay visible. gs::fs::read_into needs the caller's existing fs send capability. It must take the ServiceContext (or a handle derived from it) as an argument rather than reaching for a global, or the "no ambient authority" invariant becomes a comment. This is the single most important line in the whole design.

3. Portability. Nothing proposed needs #[cfg(target_arch)]. The wire protocols are little-endian by contract and already proven to cross architectures (cross_isa.py 12/0, one volume carried x86-64 to riscv64 and back). The stdlib must not become the 45th arch-conditional site.

4. Where does it live? sdk/rust is the services' SDK. A separate stdlib/rust crate that depends on it keeps the layering honest and lets the SDK stay the low-level ABI. This needs a decision and is not mine to take alone.

6. What I recommend, and what I need from review

Recommended first slice, assuming Option A (services only, no kernel change):

1. gs::fs over the wire protocol, with the byte layout owned once.
2. gs::call - one honest request primitive returning the existing DeadlineOutcome shape, with reacquire-and-retry built in and correct (retry on SendFailed, never on Timeout).
3. gs::io - a thin, documented console surface.
4. Migrate services/recorder (filesystem) and one console path, and report what still needs raw plumbing.

Three questions for you:

1. Option A, B, or C for §1? This decides whether the deliverable is "a standard library for services" or "the application model plus a standard library". I recommend A now and B as its own reviewed change.
2. Crate boundary: new stdlib/rust depending on sdk/rust, or a gs module inside the SDK?
3. Is net in the first slice? The brief asks for a network migration; I would rather inspect net-stack first and propose it separately than guess at a socket API now.

Nothing will be implemented until these are answered.

7. What building it changed

The design above is kept as argued. This records where reality differed.

The migration drove the API, which is what it was for. services/recorder needed three operations the proposed surface did not have - create_sized (allocate an extent), write_at (positional write) and rename. The tempting shortcut was a raw_op(opcode, ..) escape hatch, which would have leaked the opcodes straight back out and defeated the module's whole purpose. They were added as typed operations instead.

Measured result on recorder: 680 lines to 627, and raw fs/IPC plumbing from 22 sites to 2. The two that remain are a protocol tag constant of its own and a comment. Its filesystem call helper went from 55 lines to 15 - but the line count is the least of it: it used to return bool, so a write that hit the deadline (and may therefore have landed) was indistinguishable from one that never left. Eleven lines of comment explained that difference and the signature discarded it. It returns Result now.

A Commandment check broke, and it was right to. Moving reacquisition into gs::call made it invisible to IX-peer-reacquire, which looks for a reacquisition API in the SERVICE's own source. It reported recorder as having no recovery path.

That is the real architectural friction in this work, and it generalises: a standard library that absorbs a Commandment-enforced behaviour makes that behaviour unverifiable where the checker looks for it. Baselining an exemption would have been the wrong answer - a weakened check is worse than no check. The fix has two halves:

1. reacquire_api now credits gs::call, so a service routing through it gets the path it has.
2. IX-stdlib-delegates is a new check asserting that stdlib/rust/src/call.rs really does reacquire, and does it on SendFailed rather than on a deadline. Without it, half 1 is a hole: a service would pass IX for calling a library that had quietly stopped doing the work, and the property would decay from "this service can recover" into "this service calls something that used to".

Commandments went 20 checks to 21, red-team probes 73 to 75, both new probes firing.

Host tests cover the error model only, and deliberately. godspeed_sdk provides the panic_handler and so does std, so any dependent crate's host test build hits duplicate lang item. The split follows the pattern kernel/src/clock.rs documents: the pure logic - which is most of the semantics worth testing - has no SDK import and is unit-tested on the host; anything that talks to a service is for the target, where it can meet a filesystem that can really be restarted. A mock would only prove this library agrees with a mock.

Still open, unchanged: the terminating task (§1), net (needs net-stack inspected properly), and target-side suites for fs/call against a real service restart.

8. net: inspected, and the answer is NOT YET

§4 deferred net rather than guessing at a socket API. Inspected properly now, and the deferral holds - but the inspection found something better than a socket module.

Why not now

Two clients is not repeated application plumbing, it is two call sites, and one of them sends a single byte. Against that, the protocol moved 34 times in three releases. The brief is explicit on both counts: "Every abstraction must correspond to a demonstrated application need", and "be conservative about declaring APIs stable... small enough that we understand the semantics of what we commit to."

Wrapping it now would freeze a shape that is still moving, for one and a half consumers.

What the inspection found instead

A socket is a delegated resource capability, the same §7.10 mechanism as file-as-capability - resource_mint to issue, resource_invoke to use, last_recv_badge to authenticate, with a rights check on every operation (LOP_ACCEPT and LOP_CLOSE both demand RIGHT_WRITE, because both change what the machine does on the wire).

That mechanism has two independent issuers already - fs for files and net-stack for sockets - plus the shell as a consumer of both, and two worked examples. So the abstraction with demonstrated need is not net. It is:

gs::cap - hold, invoke and narrow a delegated resource capability, without hand-rolling the badge and rights dance.

That is the honest next slice by the brief's own test: it removes plumbing that is genuinely repeated across two unrelated services, it wraps one named Godspeed mechanism rather than a protocol still in flux, and it cannot widen authority because rights only ever narrow on transfer (§7.3).

It is NOT being built now either, for the same reason net is not: the shell is the only real consumer today, and a second would settle the shape. Recorded, not started.

What would change the answer for net

A second substantive client. If time ever needs more than one byte, or an application wants a socket, the repeated plumbing appears and gs::net earns its place - most likely on top of gs::cap rather than beside it.

9. net built, and the dogfood earned its keep

Built at the operator's direction, overruling §8's "not yet". The surface is status, resolve, ping, arp, tcp and renew, plus a pure addr::Ipv4.

Two deliberate boundaries, stated in the module rather than left to be discovered: UDP sockets and TCP listeners are NOT included, because those are delegated resource capabilities and need machinery shared with file capabilities - half-building that twice is how it goes wrong. And ping returns Ok(false) for silence rather than an error, because a diagnostic tool that conflates "no answer" with "the request failed" lies about which half is broken.

The bug the migration found, which is the point of migrating

The first draft sent [opcode, ..]. The real framing is [tag, patience_secs, opcode, ..]:

#![allow(unused)]
fn main() {
// services/net-stack
None => match (pl_raw.first(), pl_raw.len()) {
    (Some(t), n) if n >= 2 => (&pl_raw[2..], Reply { tag: Some(*t) }),
    _                      => (pl_raw,      Reply { tag: None }),
}
}

Any request of two bytes or more has its first two bytes eaten. So status() - one byte, below the strip threshold - worked by accident, while resolve("example.com") had its opcode taken as a tag and dispatched on 'x'. Every call but one was wrong, and all of them compiled.

It was found by reading services/shell's own client while looking for something to migrate, which is exactly what the brief predicts: "the migration is part of the test." Nothing short of a target run would otherwise have caught it, because the failure mode is a machine quietly talking to the wrong thing.

The module header had already warned that net-stack's protocol moved 34 times in three releases and that the cost of being wrong here is not a compile error. That warning turned out to be about the draft immediately below it.

What is still owed

• The network migration itself. gs::net is written and correct against the protocol, but no utility has been moved onto it yet: the shell's net client lives behind ShellCtx, whose ServiceContext is private, so the migration needs a small accessor rather than a rewrite. That is the next commit, not a design problem.
• Target-side tests, for the same reason as §7: the interesting failures are a service that restarts and a deadline that passes, and neither is reachable on the host.

10. The network dogfood: cmd_tcp, and the result that went the wrong way

The migration §9 said was next is done. The shell's tcp command no longer knows the wire format.

ServiceContext was not private after all. §9 recorded that this needed "a small accessor rather than a rewrite". Wrong: ShellCtx has a Deref impl, so &*ctx yields &ServiceContext and the migration needed no shell change at all beyond the call site. Recorded because the previous entry sent the next reader after work that did not exist.

The line count went UP, and that is the honest result. recorder shrank 680 lines to 627. This did the opposite:

So the plumbing did disappear - all ten sites of it - and the function still grew seven code lines. The growth is entirely in the outcome arms: ReqOutcome has three variants and Error has thirteen, so what was three arms is now four plus a catch-all. That is not overhead, it is the honest cost of a richer failure model: the old code could not distinguish "connected to nothing" from "net-stack refused" because the SDK had no way to say it. A library that makes the error model finer will make some call sites longer, and reporting only the case that shrank would be choosing the flattering instrument.

Error::Cancelled exists because of this migration, and it caught me making the exact mistake the library exists to prevent. The shell is explicit that the user's own q is not a fault. My first cut of request_within_notice folded ReqOutcome::Aborted into OutcomeUnknown - collapsing "you pressed a key" into "we do not know what happened to your request", which would have taught the operator that a deliberate keypress produces an error line. That is the same lossy merge §7 records the SDK making with DeadlineOutcome, committed by the library built to stop it, one branch later. It survived a compile and every gate; what caught it was reading the three arms it had to preserve.

Net::with_notice exists for the same reason. ns_request always passed an on_linger callback printing [q] quit, so a migration that ignored it would have silently deleted an affordance. The callback takes nothing and returns nothing - it means only "you have been waiting a while" - so the console stays entirely on the shell's side and the library learns nothing about terminals.

The wire format was wrong in the first draft, and only the dogfood found it. gs::net sent [opcode, ..]. net-stack strips TWO bytes from any request of two bytes or more and echoes the tag at reply byte 0, so a request must be [tag, patience, opcode, ..]. Everything except status() dispatched on garbage - and status() worked by accident, because a one-byte request falls below the strip threshold and reaches a default arm that answers status anyway. A single passing call concealed a module-wide framing error. Fixed at the header, with the echoed tag now checked on return (a mismatched tag is Error::Malformed, never read as this call's answer).

No net-stack change was needed, or made. git diff main...HEAD -- services/net-stack/ is empty. The format was always net-stack's; the library was taught to speak it. So this migration owes no hardware re-test of the protocol - what it owes is the same target-side testing §7 and §9 already record.

Still owed, unchanged: target-side tests against a service that really restarts, and gs::cap.

11. Four file operations, and three things the shell knew that the library did not

gs::fs gains list_dir, create_dir_all, move_to and delete_all - the ordinary file operations that had callers hand-rolling them. Two corrections to what section 9 claimed about the ceiling, made while reading the service rather than its comments:

• OP_CAPACITY and OP_FLUSH are not file operations. They are block-driver opcodes that fs uses as a CLIENT. Counting them as candidates for gs::fs was reading a constant list without reading what serves it.
• send_res! already sends a REASON. On FS_ERR the service appends its own words - "name already exists", "cannot move root", "source not found" - and from_fs_status mapped the status byte and dropped the sentence. A loud failure was being made quieter in transit (26.7). Fs::reason keeps it in a bounded buffer the handle owns, documented as diagnostic-only: branch on the Error, print the reason.

The shell's hand-rolled version was better than mine, twice

services/shell has nine OP_LIST_DIR call sites behind one DirCursor. I wrote list_dir first and read DirCursor after, which is the wrong order, and it had two properties I had missed:

1. A page cap. My loop followed next for as long as the service said more - an unbounded execution scope (26.6) resting entirely on the service behaving. DIR_PAGE_MAX is now the same 512 the shell uses.
2. A cut flag. Hitting that cap must not look like finishing. The shell's own comment is the rule: "a partial answer that reads as a complete one is the thing this whole mechanism exists to remove". My Result<usize, Error> had nowhere to put it - an error would have been a lie, since the entries WERE delivered, and a bare count would have been exactly the silent truncation the pagination handling existed to prevent. Hence Listing { visited, complete }: the count cannot be read without the field that says whether it is the whole directory.

This is the dogfood working in the opposite direction from the usual story. The library did not teach the caller; the caller taught the library. Worth recording plainly, because a design report that only lists what the new code improved is not an honest instrument.

A hazard that had to be fixed before any migration was safe

gs::fs minted tags from a 0xC0..0xFF band; the shell mints from the whole 1..=255 range. Two independent counters on one channel, with overlapping ranges. A tag check only REJECTS a mismatch, so a collision does not fail loudly - it lets a stale reply be ACCEPTED as the current request's answer, which is precisely the "run it twice and the protocol loses step" desync tagging was added to remove. Rare, silent, and therefore worse than common and loud.

So migrating one shell site while the others still called next_fs_tag would have introduced a rare wrong answer. The band bought nothing (a tag need only differ from the request before it on the SAME channel, and net is a different channel), so it is gone: Fs advances exactly as the shell does, and Fs::from_tag / Fs::tag let a caller lend its counter and take it back. One counter per channel.

Architectural friction, reported rather than worked around

list_dir's closure borrows the handle mutably, so you cannot make another fs call while listing. That makes the API right for the simple case the Stranger Test asks about ("list a directory") and wrong for an interleaved one.

cmd_churn_verify - the power-cut verifier - is the interleaved case: it lists /churn (/system/scratch/churn since 2026-10-13) and reads each file as it goes. Migrating it would have forced a two-pass collect into a roughly 16 KB stack buffer the original never needed, on a shell stack already known to be tight. That is a memory discipline regression caused by the shape of my API, so it was not migrated, and the reason is recorded here instead of being engineered around. The page-at-a-time alternative that would fix it is what DirCursor already is; whether the library should offer that second shape is an open question and not a thing to add speculatively (26.2).

What was migrated, and what it proves

cmd_dir - a pure listing, decoding exactly the five fields DirEntry carries. It also needed Fs::with_notice, an inconsistency I had introduced rather than found: cmd_tcp got Net::with_notice so a lingering request keeps offering [q] quit, and every shell filesystem call uses fs_request_q, so migrating any of them without the equivalent would have silently deleted that affordance (utilities/0_conventions.md rule 9).

What deliberately stayed in the shell: a name is rendered SAFE there, because that is a property of writing to a terminal, not of reading a directory. A name holding ESC [ 2J clears the screen when listed, scrolling away the listing meant to reveal it (found by osdev test fs-fuzz). DirEntry::name is raw bytes precisely so this layer can decide - a library that pre-sanitised would have made the hostile name unprintable AND unreachable, so delete could not remove it either.

Verified in QEMU, osdev test files, 245 passed 0 failed, including the three cases that pin exactly what this change risked:

many: dir lists all 45 entries across pages
many: dir does not report a truncated listing
many: dir shows both the first and the last entry

A gate that was covering nothing

scripts/doc_symbols_check.py never scanned stdlib/rust/src. Every backticked symbol in docs/stdlib-design.md was being checked against a source set that EXCLUDED the crate the document is about, so the gate's silence read as a pass while it verified nothing. Found because a correct reference (request_within_notice) failed. Fixed; the scan now covers the crate, and one stale baseline entry could be dropped as a result.

Still owed, unchanged: target-side tests against a service that really restarts, and gs::cap. Newly recorded: backlog/fixed/45, the published book has no standard-library section, which blocks the Stranger Test from an honest first run.

12. gs::cap is NOT built, and the reason is a gap in the kernel surface

Section 10 named gs::cap - delegated resource capabilities, the mechanism behind "a file is a capability" (7.10) - as the best next candidate. Reading the path before writing it turned up a blocker, so it is recorded rather than built. backlog/46 is the full entry.

resource_invoke (syscall 31) is a SEND. It embeds a reply cap and returns on delivery; the caller then waits with a plain recv. That is exactly the shape CLAUDE.md 8.2's CallDeadline amendment condemns:

a service that SERVES clients on the endpoint it awaits replies on would therefore consume an unrelated client request, fail to match it, and drop it

That amendment fixed the NAMED-PEER path - request_with_reply_call matches the reply by its sender

• and left the RESOURCE path on the primitive it had just condemned. There is no CallDeadline form of resource_invoke.

The one existing caller is exempt by accident, not by design. services/shell opens every file-cap invocation with while ctx.try_recv().is_some() {}, draining whatever is queued. That is safe only because the shell serves nobody on that endpoint. In a service that does, the same line discards live client requests - so the shell working is not evidence the pattern is sound.

A library cannot do either thing. It cannot drain, because it does not know whether its caller serves clients; and without draining it inherits a wait that can eat a message. gs::cap is meant for ordinary services - a facility only usable by a task with no clients is not the public interface 22.7 measures - so it is not started.

A correction to what this section first said. It concluded "a new syscall is a new kernel responsibility, so this is the operator's gate". That reasoning is wrong, and the operator corrected it: syscall count is not responsibility count. A primitive completing the semantics of a responsibility the kernel already owns is not kernel growth. The question is not "does this add a syscall" but "does an existing MISCIS mechanism have an incomplete semantic".

Applying that test properly changes the finding, and makes it larger rather than smaller.

The hole is generic, and it predates this library. Three services mint delegated resource caps - fs (files), net-stack (TCP connection and listener caps) and shell - and 7.10 is written in terms of an opaque ResourceId whose meaning only the owner knows. examples/resource-server and examples/holder are a worked pair naming no filesystem at all, and holder waits like this:

#![allow(unused)]
fn main() {
Ok(())  => Ok(ctx.recv()),   // routed: block for the owner's reply on our endpoint
}

An unbounded recv. If the owner dies after receiving the invocation and before replying, holder hangs forever - Commandment VIII broken in the example that teaches the mechanism, and 8.6 has a row promising exactly that caller is woken on the Call path.

So there are two holes, not one: no reply correlation (hole 1, above) and no ReplyDead reaching resource invocation (hole 2), because a SEND never tells the kernel a reply is awaited.

Answering the MISCIS test - if gs::cap never existed, would the hole exist? Yes, and it already does, in a published example and on the shell's socket path. gs::cap did not create this; it was the first caller that could not look away from it, because a library cannot assume its caller serves nobody.

No kernel change is being proposed or made. That a standard-library feature exposed this creates no urgency to change the kernel, and a mechanism must justify itself independently of the feature that revealed it. backlog/46 records the question, the first-principles answers, the genericity test, and what a future investigation should settle - including the entirely acceptable outcome that resource_invoke is intentionally narrow, in which case its contract gets written down and examples/holder gets fixed or explained.

gs::cap stays unbuilt. Nothing is lost: file-as-capability works today for the caller it has.

The useful thing here is not a feature. No code shipped from this section. What it produced is a hidden assumption made visible - that resource invocation is safe only from a task whose endpoint is otherwise idle, a contract nothing states and one published example does not honour.

13. The governing constraint: the library CONSUMES capability, it never CREATES it

Stated by the operator, and it is the rule the rest of this report should have been written against from the start:

The stdlib's job is to make existing Godspeed functionality pleasant and safe to consume. It isn't supposed to create functionality that the OS doesn't already possess.

So if implementing a stdlib API apparently requires stdlib API -> new syscall -> kernel modification, that is a reason to stop and question the stdlib/SDK composition, not an invitation to modify the kernel.

What this does to the gs::cap conclusion

Section 12 and the backlog/46 triage answered "is the mechanism incomplete, and how expensive is the remedy" - and concluded rung D with a remedy cheaper than first thought. That framing was subtly wrong, because it is not the library's question. Under this constraint the answer is shorter and firmer:

gs::cap correctly does not exist, because the OS does not currently possess safe general resource invocation. A standard library cannot offer a guarantee the system underneath it does not make. The work ended the moment the gap was identified; filling it would have been the library manufacturing a capability rather than re-serving one.

The triage in backlog/46 keeps its value - it rules out B and C with evidence, so a future branch does not repeat the search - but it is a note for whoever picks the mechanism up, not a plan for this branch. feat/stdlib touches neither kernel/ nor sdk/: both diffs against main are empty, and that is now stated at the top of the backlog entry so the analysis cannot be misread as a proposal.

The constraint is STRUCTURAL now, not a promise

The property that enforces this is #![deny(unsafe_code)] on the crate. Without unsafe the library cannot issue a syscall, so it is confined to the SDK's safe surface and can only ever re-serve what already exists. A stdlib able to reach the raw ABI could quietly grow a capability the system does not have.

The attribute was present from the first commit. Nothing was checking it, and the check that should have was broken in two independent ways, both found by adding the root and then deliberately deleting the attribute to watch the gate fire:

1. unsafe_check.py's DENY_ROOTS was ("services", "examples", "osdev") - the stdlib was not scanned at all. The same gap class as doc_symbols_check.py not scanning stdlib/rust/src, found the same day. A new top-level crate is invisible to every gate whose roots are a hand-kept list, and being invisible reads exactly like passing.
2. The presence test was satisfiable by a COMMENT. It asked DENY_ATTR not in text against the raw file, and stdlib/rust/src/lib.rs explains the attribute in its module documentation five lines above declaring it. Deleting the real attribute left the gate green. The #[allow] scan in the same function already strips // before matching, for exactly this reason - the lesson had been learned for one half of the function and not the other.

Both fixed, and the guard now fires on a deleted attribute. Worth stating plainly: for the whole of this branch, the one property making "the library cannot manufacture capability" structural rather than aspirational was resting on nobody deleting a line by accident.

14. gs::cap is built, and the answer was rung B all along

Section 12 said this module would not be built because the OS did not possess safe general resource invocation. That was right about the OS and wrong about why, and the error was mine: I had recorded, in backlog/46,

A service-layer tag cannot fix this. Echoing a caller-supplied tag would let the caller RECOGNISE a wrong message, but recv has already CONSUMED it and there is no requeue. Selective dequeue is inherently kernel-side.

The first sentence is true and the conclusion does not follow. A caller does not have to requeue a message it should not have taken. It can HOLD it and hand it back. Correlation is what makes holding possible, and correlation is a protocol property, not a kernel one. So this was rung B - existing userspace machinery, composed wrongly - and it needed no kernel change. kernel/ and sdk/ are still untouched on this branch.

What was actually missing

services/fs speaks two protocols. The NAMED one (OP_WRITE_FILE and friends) carries a tag at byte 0 of the request and echoes it at byte 0 of the reply. The FILE-CAP one (FOP_READ/WRITE/STAT/ CLOSE) carried none. Same service, same file, opposite answers to the same question.

That asymmetry was the whole blocker. With nothing to match on, a holder must either block on a bare recv and read whatever arrives as its reply, or drain its queue and destroy anything else in it. The shell drains, which is safe only because the shell serves nobody.

The fix is one tag, restoring the convention the sibling protocol always had:

request   [tag, FOP_*, ..]      (was [FOP_*, ..])
reply     [tag, FS_*,  ..]      (was [FS_*,  ..])

The edit is deliberately tiny: p is shadowed past the tag so every offset below is unchanged, and the send closure prepends so every reply site is unchanged. One extra 3562-byte reply buffer in serve_filecap, against a 256 KiB frame limit.

What the library does with it

File::invoke sends tagged and waits. A message that is not the reply is held in a bounded array and handed back via File::take_held, never dropped. If there is no room left to hold, the operation stops rather than dropping: what was taken is handed back, what was not taken is still in the kernel queue, and the caller gets OutcomeUnknown because that is the truth.

HELD_MAX is 2. A held message is a full 4 KiB Message, so the bound is small and readable from the source (26.6.1) rather than generous and invisible.

The obligation is stated rather than hidden: a task that serves clients must drain take_held after each operation. Ignoring those messages loses them just as surely as draining would have - the difference is that here you are told.

One design decision worth naming

File borrows &mut Fs. The two speak to one service over one endpoint, so they must share ONE tag counter; two counters can mint the same tag for two exchanges in flight, and the result is not a loud rejection but a stale reply silently accepted as the current answer. The borrow makes that structural - the borrow checker will not let the bug be spelled. The cost is one open file per handle, and Fs::from_tag/Fs::tag are the escape for anyone who needs two.

The dogfood earned its keep again

fcap - the osdev test file-cap self-check that pins 22 Test 14 - gained a section repeating the core property through gs::cap. It failed on the first run:

fcap: FAIL gs::cap round trip - the service sent a reply this library could not parse

invoke VERIFIES the tag and returns the message whole; it does not strip it, because stripping means rebuilding a 4 KiB Message per read. My own doc comment claimed otherwise - "the tag is already checked and stripped" - and read_at and size believed the comment rather than the code, reading the status byte as the first byte of the length. A comment that lies is worse than no comment, and this one lied to its own author within the hour.

Fixed, and the two library checks are now NAMED assertions rather than folded into the aggregate, because gs::cap is the one caller that must work from a task which also serves clients.

Verified

• osdev test file-cap: 15 passed, 0 failed (was 13 - the two new assertions).
• osdev test files: 245 passed, 0 failed. An earlier run reported one failure, tab abs-path timeout, on a code path this change does not touch; it passed on re-run and is recorded here as the host-load flake it was rather than quietly re-run until green.
• osdev test fs-restart: 11 passed, 0 failed.
• 13 of 13 gates green; cargo test -p godspeed 7/7.

What is still open

backlog/46 stays open, narrowed. The fs file-capability path is correlated now, but the same gap remains wherever else a delegated resource cap is invoked:

• net-stack's socket and listener caps carry no tag, so sock still relies on draining.
• examples/holder still does a bare ctx.recv() and hangs forever if its owner dies - hole 2, the missing ReplyDead, which a tag does NOT fix. That one is genuinely about the mechanism, not the protocol, and is left recorded rather than papered over. (Since corrected: its wait after a resource_invoke is bounded by recv_abortable_deadline, so a dead owner costs a deadline, not a hang. It still hand-rolls the invoke rather than using gs::resource::invoke, which is pub(crate) - §24 and §25.)

15. The target-side tests, and the error the restart found

Section 7 recorded target-side tests as owed, and section 9 repeated it. They exist now, and the first one turned up a defect that no amount of reading would have.

gs::fs across a real restart was already covered - by a vacuous assertion

osdev test files kills fs twice (chaos kill-storm fs 2) and then runs dir /. Since cmd_dir walks gs::fs::list_dir, that has been exercising the library against a genuinely dead-and-respawned service all along. The assertion, though, was:

#![allow(unused)]
fn main() {
check!(!r.contains("storage unavailable"), "shell reacquires fs after its own restart")
}

That passes on silence. A hang, a dropped reply, an empty listing, a command that quietly gave up

• all of them contain no error string. It is the same vacuous shape that let "390 writes" satisfy a guard looking for "0 writes" earlier in this branch. It now requires a real listing (the trailing count) and the absence of both error lines, which makes it an assertion rather than a hope.

gs::cap across a real restart: fcap gsreuse

A new command holds a gs::cap::File (now gs::file::File) across a real fs kill and reads through it afterwards. Pinned by four named assertions in osdev test fs-reuse, which went from 8 cases to 12.

Scope, stated rather than quietly narrowed. fcap reuse additionally deletes the original and writes a same-length replacement into the freed blocks, proving the stale cap cannot read the REPLACEMENT. This test does not, and the reason is the library's own design: File borrows &mut Fs, so while the capability is held the handle cannot write the replacement - and dropping the File to free the handle CLOSES the capability, which is the thing under test. The borrow is deliberate (it makes a second tag counter unspellable), so the constraint is real. What is pinned here is the half that is the library's to get right: a stale capability yields a NAMED error rather than a hang, a silent success, or a wrong answer. The block-reuse case stays pinned by fcap reuse against the same kernel and the same fs.

Two things the test found that review did not

1. service_answered() can never be true for a stale capability. My first probe waited for fs to come back by invoking the held capability and watching for service_answered(). It never fires: the kernel rejects a stale cap on the generation check BEFORE routing, so the owning service is never reached and never answers. The error model was right and the instrument was wrong. The probe moved to inspect_endpoint_generation, a kernel query needing no fs request and therefore no tag - which matters because the handle is borrowed for the whole scope.

2. The library named the wrong cause. The refusal printed:

fcap gsreuse: the stale cap was refused - the service could not be reached (nothing happened)

fs was up and serving. What happened is that the capability was REVOKED when its issuer died (7.5). "Could not be reached" names a different fault and sends an operator to check a service that is running perfectly - precisely the complaint this branch wrote into cmd_tcp two sections ago.

The information was there and I was discarding it. resource_invoke returns IpcError::CapError(CapError), and CapError separates CapRevoked and EndpointDead from CapInsufficientRights. My invoke collapsed all of them by GUESSING from the rights mask instead of reading the error. It now reads it, and Error::Revoked exists:

the capability was revoked - re-open it (nothing happened)

retry_is_safe is FALSE for it, for the less obvious of the two reasons. Retrying cannot double-apply anything - the kernel refused before routing - so it is harmless. It also cannot ever succeed, and a caller looping on that predicate would spin forever. The question the predicate answers is "should I retry", and the honest answer is no: re-open. The host test says so in those words, because the next person to add a variant will face the same choice.

Verified

• osdev test fs-reuse: 12 passed, 0 failed (was 8).
• osdev test file-cap: 15 passed, 0 failed.
• osdev test files: 245 passed, 0 failed.
• 13 of 13 gates green; cargo test -p godspeed 7/7.

Still owed, and now the only owed item from section 7: nothing. The remaining open work is backlog/46's hole 2 and the net-stack socket caps, neither of which is a library gap.

16. The socket capabilities, and a comment that had the problem backwards

backlog/46's hole 1 is now closed for every delegated-resource issuer in the system. net-stack's socket, listener and connection capabilities carry a correlation tag, as fs's file capabilities already do.