capOS Documentation

capOS is a research operating system where every kernel service and every cross-process service is a typed Cap’n Proto capability invoked through a shared-memory ring. There is no ambient authority, no global path namespace, and the only remaining syscalls are cap_enter and exit. The current implementation boots on x86_64 QEMU, loads a Cap’n Proto boot manifest, starts manifest-declared services, and exercises ring-native IPC, capability transfer, and init-driven spawning through QEMU smoke binaries.

Use this book as the current system manual. It separates implemented behavior from proposals, research notes, and operational planning files. What capOS Is has the short version of what makes the design unusual.

Start Here

• What capOS Is describes the implemented system model and the main authority boundaries.
• Current Status lists what works today, what is partial, and what remains future work.
• Build, Boot, and Test gives the commands used to build the ISO, boot QEMU, and run host-side validation.
• Repository Map maps the main subsystems to source files.

Deeper References

• Capability Model explains the capability-table and invocation model.
• Authority Accounting records the current transfer/accounting design.
• DMA Isolation, Trusted Build Inputs, and Panic Surface Inventory cover security and verification inventories.
• Research Index links prior-art notes used to shape the design.
• mdBook Documentation Site Proposal defines the documentation structure and status vocabulary.

Operational planning still lives outside the book in ROADMAP.md, WORKPLAN.md, and REVIEW_FINDINGS.md. Treat those as live planning and review records, not stable architecture pages.

What capOS Is

A research kernel that boots on x86_64 QEMU. The rest of this page is about why it looks the way it does — the specific design bets behind the code — not a feature inventory. For the feature-by-feature matrix, see Current Status.

Status: Partially implemented.

What Makes capOS Different

capOS is a research vehicle for a few specific design bets. Each is unusual on its own; the combination is the point.

• Everything is a typed capability. System resources are accessed through Cap’n Proto interfaces defined in schema/capos.capnp. There is no ambient authority — no global path namespace, no open-by-name, no implicit inherit. A process can only invoke objects present in its local capability table.
• The interface IS the permission. Instead of a parallel READ/WRITE/EXEC rights bitmask (Zircon, seL4), attenuation is a narrower capability: a wrapper CapObject exposing fewer methods, or an Endpoint client facet that cannot RECV/RETURN. The kernel just dispatches; policy lives in interfaces. See Capability Model.
• io_uring-style shared-memory ring for every call. Every process owns a submission/completion queue page. Userspace writes SQEs with a normal memory store; the kernel processes them through cap_enter. New operations are SQE opcodes (CALL, RECV, RETURN, RELEASE, NOP), not new syscalls. The remaining syscall surface is cap_enter and exit.
• Release is transport, not an application method. Dropping the last owned handle in capos-rt submits a CAP_OP_RELEASE SQE; the kernel removes the slot. No close() method on every interface, no mutable table self-reference during dispatch.
• Capability transfer is first-class. Copy and move descriptors ride sideband on CALL/RETURN SQEs. Move reserves the sender slot until the receiver accepts and preflight checks pass, then commits or rolls back atomically — no lost, duplicated, or half-inserted authority.
• Cap’n Proto wire format end-to-end. The same encoding describes the boot manifest, runtime method calls, and future persistence/remote transparency. The CQE log is itself a serialized capnp message stream, which opens the door to record/replay, audit, and migration as OS primitives rather than external tooling.
• Host-testable pure logic. Cap-table, frame-bitmap, ELF parser, frame ledger, lazy buffers, and the ring model all live in capos-lib / capos-config and run under cargo test-lib, Miri, Loom, Kani, and proptest without any kernel scaffolding. Kernel glue stays thin.
• Schema-first boot. system.cue is compiled to a Cap’n Proto SystemManifest embedded as the single Limine boot module. The manifest carries binaries, capability grants, exports, badges, and restart metadata as typed structured data — not shell scripts or baked environment variables.

Execution Model

Each process owns an address space, a local capability table, a mapped capability-ring page, and a read-only CapSet page that enumerates its bootstrap handles. The kernel enters Ring 3 with iretq and returns through cap_enter or the timer. Ordinary capability calls progress only via cap_enter; timer-side polling handles non-CALL ring work and call targets that are explicitly safe for interrupt dispatch. Details in Process Model, Capability Ring, and Scheduling.

Boot Flow

The kernel receives exactly one Limine module — a Cap’n Proto SystemManifest compiled from system.cue — validates it, loads the referenced ELFs, builds per-service capability tables and CapSet pages, and starts the scheduler. The default boot still wires the service graph in the kernel; the selected milestone is to move generic manifest execution into init through ProcessSpawner. Full walkthrough in Boot Flow and Manifest and Service Startup.

Authority Boundaries

Authority is carried by cap-table hold edges with generation-tagged CapIds. Ring 0 ↔ Ring 3, capability table ↔ kernel object, endpoint IPC, copy/move transfer, manifest/boot-package, and process spawn are the boundaries reviewers care about; each one fails closed at hostile input. See Trust Boundaries for the boundary table and Authority Accounting for the transfer and quota invariants.

What capOS Is Not

A POSIX clone, a microkernel-shaped Linux replacement, or a production OS. It is a place to try the above choices and see which ones survive contact with real workloads. See Build, Boot, and Test to run it.

Current Status

This page describes current repository behavior, not the full long-term design. For operational priority and open review items, read WORKPLAN.md and REVIEW_FINDINGS.md.

Implemented

Boot and Kernel Baseline

• Limine boots the x86_64 kernel in QEMU.
• The kernel initializes serial output, GDT, IDT, PIC, PIT, syscall MSRs, memory management, page tables, heap allocation, and the global capability registry.
• The kernel creates its own page tables with per-section permissions and keeps the higher-half direct map for physical memory access.
• SMEP/SMAP are enabled when the QEMU CPU advertises support.

Code: kernel/src/main.rs, kernel/src/arch/x86_64/, kernel/src/mem/.

Validation: cargo build --features qemu, make run.

Process and Userspace Runtime

• Processes have isolated address spaces, per-process kernel stacks, CapSet bootstrap pages, capability rings, and local capability tables.
• ELF loading supports static no_std userspace binaries and TLS setup.
• capos-rt owns the userspace entry path, allocator initialization, ring-client access, typed clients, result-cap parsing, and owned-handle release.

Code: kernel/src/spawn.rs, kernel/src/process.rs, capos-rt/src/, init/src/main.rs, demos/.

Validation: make capos-rt-check, make run, make run-spawn.

Capability Ring and IPC

• The shared ring ABI supports CALL, RECV, RETURN, RELEASE, and NOP transport operations.
• cap_enter processes submissions and can block until completions arrive or a timeout expires.
• Endpoints route ring-native IPC between processes.
• Direct IPC handoff lets a blocked receiver run before unrelated round-robin work after a matching CALL arrives.
• Transport errors and application exceptions are surfaced through CQEs and typed runtime client errors.

Code: capos-config/src/ring.rs, kernel/src/cap/ring.rs, kernel/src/cap/endpoint.rs, capos-rt/src/ring.rs, capos-rt/src/client.rs.

Validation: cargo test-ring-loom, make run.

Capabilities

Implemented kernel capabilities include:

• Console for serial output.
• FrameAllocator for physical frame grants.
• Endpoint for IPC rendezvous.
• VirtualMemory for anonymous user page map, unmap, and protect operations.
• ProcessSpawner and ProcessHandle for init-driven child process creation and wait semantics.

Code: kernel/src/cap/console.rs, kernel/src/cap/frame_alloc.rs, kernel/src/cap/endpoint.rs, kernel/src/cap/virtual_memory.rs, kernel/src/cap/process_spawner.rs.

Validation: make run, make run-spawn, cargo test-lib.

Capability Transfer and Release

• IPC CALL and RETURN support sideband transfer descriptors.
• Copy and move transfer are implemented.
• Move transfer reserves the sender slot until destination insertion and commit.
• Transfer result caps carry interface ids to userspace.
• CAP_OP_RELEASE removes local capability-table slots and is integrated with runtime owned-handle drop.

Code: kernel/src/cap/transfer.rs, kernel/src/cap/ring.rs, capos-lib/src/cap_table.rs, capos-rt/src/ring.rs.

Validation: cargo test-lib, make run.

Manifest Tooling and Smokes

• tools/mkmanifest turns system.cue into a Cap’n Proto boot manifest.
• The build uses repo-pinned Cap’n Proto and CUE tool paths through the Makefile; direct mkmanifest invocation also rejects missing, unpinned, or version-mismatched CUE compilers.
• Default QEMU smoke services cover CapSet bootstrap, Console paths, ring corruption handling, reserved opcodes, NOP, ring fairness, TLS, VirtualMemory, FrameAllocator cleanup, Endpoint cleanup, and cross-process IPC.
• system-spawn.cue drives the ProcessSpawner smoke where init spawns endpoint, IPC, VirtualMemory, and FrameAllocator cleanup children and checks hostile spawn inputs.

Code: tools/mkmanifest/, system.cue, system-spawn.cue, demos/.

Validation: cargo test-mkmanifest, make generated-code-check, make run, make run-spawn.

Partially Implemented

Init-Owned Service Startup

init can use ProcessSpawner in the spawn smoke, but default make run still uses the kernel boot path to create all manifest services. The selected milestone is to make default boot use init to validate and execute the service graph.

Current blockers are tracked in WORKPLAN.md and REVIEW_FINDINGS.md. Manifest schema-version guardrails, BootPackage authority exposure to init, init-side manifest graph validation, ProcessSpawner badge attenuation, direct manifest-tool CUE pin enforcement, generic manifest spawning, and child-local FrameAllocator/VirtualMemory grants are in place for the spawn-manifest path. Remaining milestone work is legacy kernel service-graph retirement for the default boot path.

Hardware and Networking

The QEMU virtio-net path has legacy PCI config-space enumeration and a make run-net boot target. A virtio-net driver, smoltcp integration, ICMP, and TCP smoke are not implemented.

Code: kernel/src/pci.rs, kernel/src/arch/x86_64/pci_config.rs, tools/qemu-net-harness.sh.

Validation: make run-net, make qemu-net-harness for the existing PCI smoke path.

Security and Verification Track

The repo has Miri, proptest, fuzz, Loom, Kani, generated-code, dependency policy, trusted-build-input, panic-surface, and DMA-isolation work. Coverage is not complete for every trust boundary.

References: Trusted Build Inputs, Panic Surface Inventory, DMA Isolation, and Security and Verification Proposal.

Future Work

Future architecture includes generic manifest execution in init, service restart policy, capability-scoped system monitoring, notification objects, promise pipelining, epoch revocation, shared-buffer capabilities, scheduling-context donation, session quotas, SMP, storage and naming, userspace networking, cloud boot support, user identity, policy enforcement, boot-to-shell authentication, text shell launch, and broader language/runtime support.

Design references:

• Service Architecture
• Storage and Naming
• Networking
• SMP
• Userspace Binaries
• Shell
• Boot to Shell
• System Monitoring
• User Identity and Policy

Build, Boot, and Test

The commands below are the current local workflow for the x86_64 QEMU target. The root Cargo configuration defaults to x86_64-unknown-none, so host tests must use the repo aliases instead of bare cargo test.

Prerequisites

Expected host tools:

• Rust nightly from rust-toolchain.toml
• make
• qemu-system-x86_64
• xorriso
• curl, sha256sum, and standard build tools for pinned tool downloads
• Go, used by the Makefile to install the pinned CUE compiler when needed
• Optional policy and proof tools for extended checks: cargo-deny, cargo-audit, cargo-fuzz, cargo-miri, and cargo-kani

The Makefile pins and verifies:

• Limine at the commit recorded in Makefile
• Cap’n Proto compiler version 1.2.0
• CUE version 0.16.0

Pinned tools are installed under the clone-shared .capos-tools directory next to the git common directory.

Build the ISO

make

This builds:

• the kernel with the default bare-metal target;
• init as a standalone release userspace binary;
• release-built demo service binaries under demos/;
• the capos-rt-smoke binary;
• manifest.bin from system.cue;
• capos.iso with Limine boot files.

Relevant files: Makefile, limine.conf, system.cue, tools/mkmanifest/.

Boot QEMU

make run

This builds the ISO with the qemu feature, boots QEMU with serial on stdio, and uses the isa-debug-exit device so a clean kernel halt exits QEMU with the expected status.

The default smoke path should print kernel startup diagnostics, manifest service creation, demo output, and final halt. Current default smokes include CapSet bootstrap, capos-rt-smoke, Console paths, ring corruption recovery, reserved opcode handling, NOP, ring fairness, TLS, VirtualMemory, FrameAllocator cleanup, Endpoint cleanup, and cross-process IPC.

Spawn Smoke

make run-spawn

This boots with system-spawn.cue. Only init is boot-launched by the manifest; init uses ProcessSpawner to launch endpoint, IPC, VirtualMemory, and FrameAllocator cleanup demo children, wait for ProcessHandles, and exercise hostile spawn inputs.

This is the current validation path for init-driven process creation. It is not yet the default manifest executor.

Networking and Measurement Targets

make run-net
make qemu-net-harness
make run-measure

• make run-net attaches a QEMU virtio-net PCI device and exercises current PCI enumeration diagnostics.
• make qemu-net-harness runs the scripted net smoke path.
• make run-measure enables the separate measure feature for benchmark-only counters and cycle measurements. Do not treat it as the normal dispatch build.

Formatting and Generated Code

make fmt
make fmt-check
make generated-code-check

• make fmt formats the kernel workspace plus standalone init, demos, and capos-rt crates.
• make fmt-check verifies formatting without modifying files.
• make generated-code-check verifies checked-in Cap’n Proto generated code against the repo-pinned compiler path.

Host Tests

cargo test-config
cargo test-ring-loom
cargo test-lib
cargo test-mkmanifest
make capos-rt-check

• cargo test-config runs shared config, manifest, ring, and CapSet tests on the host target.
• cargo test-ring-loom runs the bounded Loom model for SQ/CQ protocol invariants.
• cargo test-lib runs host tests for pure shared logic such as ELF parsing, capability tables, frame allocation, and related property tests.
• cargo test-mkmanifest runs host tests for manifest generation.
• make capos-rt-check builds the standalone runtime smoke binary with the userspace relocation flags used by the boot image.

Extended Verification

make dependency-policy-check
make fuzz-build
make fuzz-smoke
make kani-lib
cargo miri-lib

These require optional tools. Use them when changing dependency policy, manifest parsing, ELF parsing, capability-table/frame logic, or proof-covered shared code. See the Security and Verification Proposal for the rationale behind the extended verification tiers.

Validation Rule

For behavior changes, a clean build is not enough. The relevant QEMU process must exercise the behavior and print observable output that proves the path works. make run is the default end-to-end gate; make run-spawn, make run-net, or make run-measure are additional gates for their specific features.

Repository Map

This map names the main source locations for the current system. It is not an ownership file; use it to find the code behind architecture and validation claims.

Root Files

• README.md gives the compact project overview.
• ROADMAP.md records long-range stages and broad feature direction.
• WORKPLAN.md records the current selected milestone and implementation ordering.
• REVIEW_FINDINGS.md records open review findings and verification history.
• REVIEW.md defines review expectations.
• Makefile builds pinned tools, userspace binaries, manifests, ISO images, QEMU targets, formatting checks, generated-code checks, and policy checks.
• rust-toolchain.toml pins the Rust toolchain.
• .cargo/config.toml sets the default bare-metal target and useful cargo aliases.

Schema and Shared ABIs

• schema/capos.capnp defines capability interfaces, manifest structures, exceptions, ProcessSpawner, ProcessHandle, and transfer-related schema.
• capos-config/src/manifest.rs defines the host and no_std manifest model.
• capos-config/src/ring.rs defines CapRingHeader, SQE/CQE structures, opcodes, flags, and transport error constants shared by kernel and userspace.
• capos-config/src/capset.rs defines the read-only bootstrap CapSet ABI.
• capos-config/src/cue.rs supports evaluated CUE-style manifest data.
• capos-config/tests/ring_loom.rs models bounded ring protocol behavior with Loom.

Validation: cargo test-config, cargo test-ring-loom, make generated-code-check.

Shared Pure Logic

• capos-lib/src/elf.rs parses ELF64 images for kernel loading and host tests.
• capos-lib/src/cap_table.rs implements CapId, capability-table storage, stale-generation checks, grant preparation, transfer transaction helpers, commit, and rollback.
• capos-lib/src/frame_bitmap.rs implements the host-testable physical frame bitmap core.
• capos-lib/src/frame_ledger.rs tracks outstanding FrameAllocator grants.
• capos-lib/src/lazy_buffer.rs provides bounded lazy buffers used by ring scratch paths.

Validation: cargo test-lib, cargo miri-lib, make kani-lib, fuzz targets under fuzz/fuzz_targets/.

Kernel

• kernel/src/main.rs is the boot entry point, hardware setup sequence, manifest parsing path, and boot-launched service creation path.
• kernel/src/spawn.rs loads user ELF images, creates process state, maps bootstrap pages, and enqueues spawned processes.
• kernel/src/process.rs defines Process, process states, kernel stacks, and initial userspace CPU context.
• kernel/src/sched.rs implements the single-CPU scheduler, timer-driven preemption, blocking cap_enter, direct IPC handoff, and deferred cancellation wakeups.
• kernel/src/serial.rs implements COM1 output and kernel print macros.
• kernel/src/pci.rs implements the current QEMU virtio-net PCI enumeration smoke path.

Validation: cargo build --features qemu, make run, make run-spawn, make run-net.

Kernel Architecture

• kernel/src/arch/x86_64/gdt.rs sets up kernel/user segments and TSS state.
• kernel/src/arch/x86_64/idt.rs handles exceptions and timer interrupts.
• kernel/src/arch/x86_64/syscall.rs implements syscall MSR setup and entry.
• kernel/src/arch/x86_64/context.rs defines timer context-switch state.
• kernel/src/arch/x86_64/pic.rs and pit.rs configure legacy interrupt hardware.
• kernel/src/arch/x86_64/smap.rs enables SMEP/SMAP and brackets user memory access.
• kernel/src/arch/x86_64/tls.rs handles FS-base/TLS support.
• kernel/src/arch/x86_64/pci_config.rs provides legacy PCI config I/O.

Kernel Memory

• kernel/src/mem/frame.rs wraps the shared frame bitmap with Limine memory map initialization and global kernel access.
• kernel/src/mem/paging.rs manages page tables, address spaces, permissions, user mappings, W^X enforcement, and address-space teardown.
• kernel/src/mem/heap.rs initializes the kernel heap.
• kernel/src/mem/validate.rs validates user buffers before kernel access.

Related docs: DMA Isolation, Trusted Build Inputs.

Kernel Capabilities

• kernel/src/cap/mod.rs initializes kernel capabilities and resolves manifest service capability tables.
• kernel/src/cap/table.rs re-exports shared capability-table logic and owns the kernel-global table.
• kernel/src/cap/ring.rs validates and dispatches ring SQEs.
• kernel/src/cap/transfer.rs validates transfer descriptors and prepares transfer transactions.
• kernel/src/cap/endpoint.rs implements Endpoint CALL, RECV, RETURN, queued state, cleanup, and cancellation behavior.
• kernel/src/cap/console.rs implements serial Console.
• kernel/src/cap/frame_alloc.rs implements FrameAllocator.
• kernel/src/cap/virtual_memory.rs implements per-process anonymous memory operations.
• kernel/src/cap/process_spawner.rs implements ProcessSpawner and ProcessHandle.
• kernel/src/cap/null.rs implements the measurement-only NullCap.

Related docs: Capability Model, Authority Accounting.

Userspace

• init/ is the standalone init process. In the spawn smoke, it uses ProcessSpawner, grants initial child capabilities, waits on ProcessHandles, and checks hostile spawn inputs.
• capos-rt/src/entry.rs owns the runtime entry path and bootstrap validation.
• capos-rt/src/alloc.rs initializes the userspace heap.
• capos-rt/src/syscall.rs provides raw syscall wrappers.
• capos-rt/src/capset.rs provides typed CapSet lookup helpers.
• capos-rt/src/ring.rs implements the safe single-owner ring client, out-of-order completion handling, transfer descriptor packing, and result-cap parsing.
• capos-rt/src/client.rs implements typed clients for Console, ProcessSpawner, and ProcessHandle.
• capos-rt/src/bin/smoke.rs is the runtime smoke binary packaged by the default manifest.

Validation: make capos-rt-check, make run, make run-spawn.

Demo Services

demos/ is a nested userspace smoke-test workspace. Each demo is a release-built service binary packaged into the boot manifest:

• capset-bootstrap
• console-paths
• ring-corruption
• ring-reserved-opcodes
• ring-nop
• ring-fairness
• unprivileged-stranger
• tls-smoke
• virtual-memory
• frame-allocator-cleanup
• endpoint-roundtrip
• ipc-server
• ipc-client

Shared demo support lives in demos/capos-demo-support/src/lib.rs.

Validation: make run, make run-spawn.

Manifest and Tooling

• system.cue is the default manifest source.
• system-spawn.cue is the ProcessSpawner smoke manifest source.
• tools/mkmanifest/ evaluates manifest input, embeds binaries, validates manifest shape, and writes Cap’n Proto bytes.
• tools/check-generated-capnp.sh verifies checked-in generated schema output.
• tools/qemu-net-harness.sh runs the current QEMU net harness.
• fuzz/ contains fuzz targets for manifest Cap’n Proto decoding, mkmanifest JSON conversion/validation, and ELF parsing.

Validation: cargo test-mkmanifest, make generated-code-check, make fuzz-build, make fuzz-smoke.

Documentation

• docs/capability-model.md is the current capability architecture reference.
• docs/*-design.md files record targeted implemented or accepted designs.
• docs/proposals/ contains accepted, future, exploratory, and rejected designs.
• docs/research.md and docs/research/ summarize prior art.
• docs/proposals/mdbook-docs-site-proposal.md defines the documentation site structure and status vocabulary used by these Start Here pages.

Boot Flow

Boot flow defines the trusted path from firmware-owned machine state to the first user processes. It establishes memory management, interrupt/syscall entry, capability tables, process rings, and the boot manifest authority graph.

Status: Partially implemented. Limine boot, kernel initialization, manifest parsing, ELF loading, process creation, and QEMU halt-on-success are implemented. The current default boot still lets the kernel interpret the whole service graph. The selected milestone in WORKPLAN.md is to move manifest graph execution into init.

Current Behavior

Firmware loads Limine, Limine loads the kernel and exactly one module, and the kernel treats that module as a Cap’n Proto SystemManifest. The kernel rejects boots with any module count other than one.

kmain initializes serial output, x86_64 descriptor tables, memory, paging, SMEP/SMAP, the kernel capability table, the idle process, PIC, and PIT. It then parses and validates the manifest, loads each service ELF into a fresh AddressSpace, builds per-service capability tables and read-only CapSet pages, enqueues the processes, and starts the scheduler.

flowchart TD
    Firmware[UEFI or QEMU firmware] --> Limine[Limine bootloader]
    Limine --> Kernel[kmain]
    Limine --> Module[manifest.bin boot module]
    Kernel --> Arch[serial, GDT, IDT, syscall MSRs]
    Kernel --> Memory[frame allocator, heap, paging, SMEP/SMAP]
    Kernel --> Manifest[parse and validate SystemManifest]
    Manifest --> Images[parse and map service ELFs]
    Manifest --> Caps[build CapTables and CapSet pages]
    Images --> Processes[create Process structs and rings]
    Caps --> Processes
    Processes --> Scheduler[start round-robin scheduler]
    Scheduler --> User[enter first user process]

The invariant is that no user service starts until manifest binary references, authority graph structure, and bootstrap capability source/interface checks have passed.

Design

The boot path is deliberately single-shot. The kernel receives a single packed manifest and validates the graph before creating any process. ELF parsing is cached per binary name, but each service gets its own address space, user stack, TLS mapping if present, ring page, and CapSet mapping.

The default manifest (system.cue) packages init, capos-rt-smoke, and the demo services directly. The spawn manifest (system-spawn.cue) packages only init as an initial service and grants it ProcessSpawner plus endpoint caps; init then spawns selected child services.

Future behavior is narrower: the kernel should start only init with fixed bootstrap authority and a manifest or boot-package capability. init should validate and execute the service graph through ProcessSpawner.

Invariants

• Limine must provide exactly one boot module, and that module is the manifest.
• Manifest validation must complete before any declared service is enqueued.
• Service ELF load failures roll back frame allocations before boot continues or fails.
• Kernel page tables are active and HHDM user access is stripped before SMEP/SMAP are enabled.
• The kernel passes _start(ring_addr, pid, capset_addr) in RDI, RSI, and RDX.
• CapSet metadata is read-only user memory; the ring page is writable user memory.
• QEMU-feature boots halt through isa-debug-exit when no runnable processes remain.

Code Map

• kernel/src/main.rs - kmain, manifest module handling, validation, service image loading, process enqueue, halt path.
• kernel/src/spawn.rs - ELF-to-address-space loading, fixed user stack, TLS mapping, Process construction helpers.
• kernel/src/process.rs - process bootstrap context, ring page mapping, CapSet page mapping.
• kernel/src/cap/mod.rs - manifest capability resolution and CapSet entry construction.
• capos-config/src/manifest.rs - manifest decode, schema-version guardrails, and graph/source/binary validation.
• tools/mkmanifest/src/lib.rs - host-side manifest validation and binary embedding.
• system.cue and system-spawn.cue - default and spawn-focused boot graphs.
• limine.conf and Makefile - bootloader config, ISO construction, QEMU targets.

Validation

• make run validates the default manifest, kernel-side service startup, process creation, scheduler entry, and clean QEMU halt.
• make run-spawn validates init-owned spawning through ProcessSpawner for the current transition path.
• cargo test-config covers manifest decode, roundtrip, and validation logic.
• cargo test-mkmanifest covers host-side manifest conversion and embedding checks.
• make generated-code-check verifies checked-in Cap’n Proto generated output.

Open Work

• Move default service graph interpretation from the kernel into init.
• Retire kernel-side service graph wiring after default make run proves the init-owned path.

Process Model

The process model defines how capOS represents isolated user programs, how they receive authority, how they enter and leave the scheduler, and how a parent can observe a child.

Status: Partially implemented. Processes, isolated address spaces, ELF loading, fixed bootstrap ABI, exit cleanup, process handles, and init-driven child spawning are implemented. Restart policy, kill, generic post-spawn grants, and init-side manifest graph execution remain open.

Current Behavior

A Process owns a user address space, a per-process capability table, a ring scratch area, a kernel stack, a saved CPU context, a mapped capability ring, and an optional read-only CapSet page. Process IDs are assigned by an atomic counter.

ELF images are loaded into fresh user address spaces. PT_LOAD segments are mapped with page permissions derived from ELF flags, the user stack is fixed at 0x40_0000, and PT_TLS data is mapped into a per-process TLS area below the ring page. The process starts from a synthetic CpuContext that returns to Ring 3 with iretq.

ProcessSpawner lets a holder spawn packaged boot binaries, grant selected caps to the child, and receive a non-transferable ProcessHandle result cap. ProcessHandle.wait either completes immediately for an already-exited child or registers one waiter.

Design

Process construction separates image loading from capability-table assembly. The kernel first maps all boot-launched service images, then builds capability tables for all services so service-sourced caps can resolve against declared exports. Spawned children use the same image loading and Process creation helpers, but their grants are supplied by the calling process through ProcessSpawner.

Each process starts with three machine arguments:

• RDI - fixed ring virtual address (RING_VADDR).
• RSI - process ID.
• RDX - fixed CapSet virtual address, or zero if no CapSet is mapped.

Exit releases authority before the Process storage is dropped. The scheduler switches to the kernel page table before address-space teardown, cancels endpoint state for the exiting pid, completes any pending process waiter, and defers the final process drop until execution is on another kernel stack.

Future process lifecycle work should keep authority transfer explicit: parents should not gain ambient access to child internals, and child grants should come from named caps plus interface checks.

Invariants

• A process cannot access a resource unless its local CapTable holds a cap.
• Bootstrap CapSet metadata is immutable from userspace.
• A stale CapId generation must not name a reused cap-table slot.
• ProcessSpawner raw grants require a copy-transferable cap or an endpoint owner cap; client-endpoint grants attenuate endpoint authority.
• ProcessSpawner kernel-source grants are limited to fresh child-local address-space-bound caps; they cannot be badged or exported from init.
• ProcessHandle caps are non-transferable.
• At most one waiter may be registered on a ProcessHandle.
• Process exit releases cap-table authority before the kernel stack frame is freed.

Code Map

• kernel/src/process.rs - Process, bootstrap CPU context, ring/CapSet mapping, exit capability cleanup.
• kernel/src/spawn.rs - ELF mapping, stack mapping, TLS mapping, process construction helpers.
• kernel/src/sched.rs - process table, process handles, wait completion, exit path.
• kernel/src/cap/process_spawner.rs - ProcessSpawnerCap, ProcessHandleCap, spawn grant validation, child-local kernel grants, child CapSet construction.
• capos-lib/src/cap_table.rs - CapId generation and cap-table operations.
• capos-config/src/capset.rs - fixed CapSet page ABI.
• schema/capos.capnp - ProcessSpawner, ProcessHandle, and CapGrant.
• init/src/main.rs - current init-side spawn smoke and hostile spawn checks.

Validation

• make run validates kernel-launched service processes, CapSet bootstrap, exit cleanup, and clean halt.
• make run-spawn validates ProcessSpawner, ProcessHandle.wait, child grants, init-spawned IPC demos, and hostile spawn failures.
• cargo test-lib covers CapTable generation, stale-slot, and transfer primitives.
• cargo test-config covers CapSet and manifest metadata used to build process grants.
• cargo build --features qemu verifies the kernel and QEMU-only paths compile.

Open Work

• Make default boot launch only init and execute the validated service graph through init.
• Add lifecycle operations such as kill and post-spawn grants only after their authority semantics are explicit.
• Implement restart policy outside the kernel-side static boot graph.

Capability Model

How capabilities work in capOS.

Status: Partially implemented. Generation-tagged cap tables, typed schema interface IDs, manifest/CapSet grants, badges, transport-level release, and Endpoint copy/move transfer are implemented. Revocation propagation, persistence, and bulk-data capabilities remain future work.

What is a Capability

A capability in capOS is a reference to a kernel object that carries:

• An interface (what methods can be called), defined by a Cap’n Proto schema
• A permission (the object it references, enforced by the kernel)
• A wire format (Cap’n Proto serialized messages for all invocations)

A process can only access a resource if it holds a capability to it. There is no ambient authority – no global namespace, no “open by path” syscall, no implicit resource access.

Schema as Contract

Capability interfaces are defined in .capnp schema files under schema/. The schema is the canonical interface definition. Currently defined:

interface Console {
    write @0 (data :Data) -> ();
    writeLine @1 (text :Text) -> ();
}

interface FrameAllocator {
    allocFrame @0 () -> (physAddr :UInt64);
    freeFrame @1 (physAddr :UInt64) -> ();
    allocContiguous @2 (count :UInt32) -> (physAddr :UInt64);
}

interface VirtualMemory {
    map @0 (hint :UInt64, size :UInt64, prot :UInt32) -> (addr :UInt64);
    unmap @1 (addr :UInt64, size :UInt64) -> ();
    protect @2 (addr :UInt64, size :UInt64, prot :UInt32) -> ();
}

interface Endpoint {}

interface ProcessSpawner {
    spawn @0 (name :Text, binaryName :Text, grants :List(CapGrant)) -> (handleIndex :UInt16);
}

interface ProcessHandle {
    wait @0 () -> (exitCode :Int64);
}

interface BootPackage {
    manifestSize @0 () -> (size :UInt64);
    readManifest @1 (offset :UInt64, maxBytes :UInt32) -> (data :Data);
}

# Management-only introspection. Ordinary handle release uses the system
# transport opcode CAP_OP_RELEASE, not a method here.
interface CapabilityManager {
    list @0 () -> (capabilities :List(CapabilityInfo));
    # grant is planned for Stage 6 (IPC and Capability Transfer)
}

Each interface has a unique 64-bit TYPE_ID generated by the Cap’n Proto compiler. TYPE_ID is the schema constant. interface_id is the runtime metadata used by CapSet/bootstrap descriptions and endpoint delivery headers. Method dispatch uses the interface assigned to the capability entry plus method_id; method_id selects a method inside that schema.

This is not capability identity. A CapId is the authority-bearing handle in a process table, analogous to an fd. Multiple capabilities can expose the same interface:

• cap_id=3 -> serial-backed Console
• cap_id=4 -> log-buffer-backed Console
• cap_id=5 -> Console proxy served by another process

All three use the same Console TYPE_ID, but they are different objects with different authority. The manifest/CapSet should record the expected schema TYPE_ID as interface metadata for typed handle construction. Normal CALL SQEs do not need to repeat it because the kernel or serving transport can derive it from the target capability entry. CapSqe keeps reserved tail padding for ABI stability.

The kernel exposes the initial CapSet to each process as a read-only 4 KiB page mapped at capos_config::capset::CAPSET_VADDR and passes its address in RDX to _start. The page starts with a CapSetHeader { magic, version, count } and is followed by CapSetEntry { cap_id, name_len, interface_id, name: [u8; 32] } records in manifest declaration order. Userspace looks up caps by the manifest name rather than by numeric index (capos_config::capset::find), so grants can be reordered in system.cue without breaking clients. The mapping is installed without WRITABLE so userspace cannot mutate its own bootstrap authority map.

Security invariant: a CapTable entry exposes one public interface. If the same backing state must be available through multiple interfaces, mint multiple capability entries, each wrapping the same state with a narrower interface. Do not grant one handle that accepts unrelated interface_id values; that makes hidden authority easy to miss during review.

Invocation Path

Capabilities are invoked via a shared-memory capability ring (io_uring- inspired). Each process has a submission queue (SQ) and completion queue (CQ) mapped into its address space. Two invocation paths exist:

Caller builds capnp params message
    → serialize to bytes (write_message_to_words)
    → write CALL SQE to SQ ring (pure userspace memory write)
    → advance SQ tail
    → caller invokes cap_enter for ordinary capability methods
      (timer polling only runs explicitly interrupt-safe CALL targets)
    → kernel reads SQE, validates user buffers
    → CapTable.call(cap_id, method_id, bytes)
    → kernel writes CQE to CQ ring
    ... caller reads CQE after cap_enter, or spin-polls only for
        interrupt-safe/non-CALL ring work ...
    → caller reads CQE result

CapObject::call does not receive a caller-supplied interface ID. The cap table derives the invoked interface from the target entry before invoking the object. The SQE carries only the capability handle and method ID because each capability entry owns one public interface:

#![allow(unused)]
fn main() {
pub trait CapObject: Send + Sync {
    fn interface_id(&self) -> u64;
    fn label(&self) -> &str;
    fn call(
        &self,
        method_id: u16,
        params: &[u8],
        result: &mut [u8],
        reply_scratch: &mut dyn ReplyScratch,
    ) -> capnp::Result<CapInvokeResult>;
}
}

All communication goes through serialized capnp messages, even when caller and callee are in the same address space. This ensures the wire format is always exercised and makes the transition to cross-address-space IPC seamless.

The result buffer is supplied by the caller (the user-validated SQE result region). Implementations serialize directly into it and return the number of bytes written, so the kernel’s dispatch path does not allocate an intermediate Vec<u8> per invocation.

Capability Table

Each process has its own capability table (CapTable), created at process startup. The kernel also maintains a global table (KERNEL_CAPS) for kernel-internal use. Each table maps a CapId (u32) to a boxed CapObject.

CapId encoding: [generation:8 | index:24]. The generation counter increments when a slot is freed, so stale CapIds (from a previous occupant of the slot) are rejected with CapError::StaleGeneration rather than accidentally referring to a different capability.

Operations:

• insert(obj) – register a new capability, returns its CapId
• get(id) – look up a capability by ID (validates generation)
• remove(id) – revoke a capability, bumps slot generation
• call(id, method_id, params) – dispatch a method call against the interface assigned to the capability entry

Each service receives capabilities from cap::create_all_service_caps(), which runs a two-pass resolution over the whole manifest: pass 1 materializes each service’s kernel-sourced caps as Arc<dyn CapObject> and records its declared exports; pass 2 assembles each service’s CapTable in declaration order, cloning the exported Arc when another service’s CapRef resolves via CapSource::Service. Declaration order is preserved because numeric CapIds are assigned by insertion order and smoke tests depend on specific indices. CapRef.source is a structured capnp union, not an authority string:

struct CapRef {
    name @0 :Text;
    expectedInterfaceId @1 :UInt64;
    union {
        unset @2 :Void; # invalid; keeps omitted sources fail-closed
        kernel @3 :KernelCapSource;
        service @4 :ServiceCapSource;
    }
}

enum KernelCapSource {
    console @0;
    endpoint @1;
    frameAllocator @2;
    virtualMemory @3;
}

struct ServiceCapSource {
    service @0 :Text;
    export @1 :Text;
}

The source selector chooses the object or authority to grant. The expectedInterfaceId value is a schema compatibility check against the constructed object, not the authority selector itself. This distinction matters because different objects can implement the same interface.

Transport-Level Capability Lifetime

Cap’n Proto applications do not usually model capability lifetime as an application method on every interface. The RPC transport owns capability reference bookkeeping.

The standard Cap’n Proto RPC protocol is stateful per connection. Each side keeps four tables: questions, answers, imports, and exports. Import/export IDs are connection-local, not global object names. When an exported capability is sent over the connection, the export reference count is incremented. When the importing side drops its last local reference, the transport sends Release to decrement the remote export count. Implementations may batch these releases. If the connection is lost, in-flight questions fail, imports become broken, and exports/answers are implicitly released. Persistent capabilities, when implemented, are a separate SturdyRef mechanism and should not be treated as owned pointers.

References:

• Cap’n Proto RPC Protocol: Handling disconnects
• Cap’n Proto rpc.capnp: four tables and Release

This distinction matters for capOS:

• close() is application protocol. A File.close() method can flush dirty state, commit metadata, or tell a server that a session should end.
• Release / cap drop is transport protocol. It removes one reference from the caller’s local capability namespace and eventually lets the serving side reclaim the object if no references remain.
• Process exit is bulk transport cleanup. Dropping the process must release all caps in its table, cancel pending calls, and wake peers waiting on those calls.

capOS therefore needs a system transport layer in the userspace runtime (capos-rt / later language runtimes), not just raw SQE helpers. That transport should own typed client handles, local reference counts, promise-pipelined answers, and broken-cap state. When the last local handle is dropped, it should submit a transport-level release operation to the kernel ring.

Ordinary handle release is a transport concern, not an application method. The target design: the generated client drops the last local handle (RAII / GC / finalizer), the runtime transport submits the CAP_OP_RELEASE ring opcode, and the kernel removes the caller’s CapTable slot with mutable access to that table. Encoding release as a regular method call on CapabilityManager was rejected because it would mutate the same table used to dispatch the call; CapabilityManager is therefore management-only (list(), later grant()), not the default release path. CAP_OP_FINISH remains reserved in the same transport opcode namespace for application-level “end of work” signals that the transport must deliver reliably, so the kernel can tell them apart from a truly malformed opcode.

Current status: the kernel dispatches CAP_OP_RELEASE as a local cap-table slot removal and fails closed for stale or non-owned cap IDs. capos-rt bootstrap handles remain explicitly non-owning, while adopted owned handles queue CAP_OP_RELEASE on final drop. Result-cap adoption validates the kernel-supplied interface ID before producing an owned typed handle. CAP_OP_FINISH remains reserved and returns CAP_ERR_UNSUPPORTED_OPCODE. Process exit remains the fallback cleanup path for unreleased local slots.

Access Control: Interfaces, Not Rights Bitmasks

capOS deliberately does not use a rights bitmask (READ/WRITE/EXECUTE) on capability entries, despite this being standard in Zircon and seL4. The reason is that Cap’n Proto typed interfaces already serve as the access control mechanism, and a parallel rights system creates an impedance mismatch.

Why rights bitmasks exist in other systems: Zircon and seL4 use rights because their syscall interfaces are untyped – a handle is an opaque reference to a kernel object, and the kernel needs something to decide which fixed syscalls are allowed. capOS has typed interfaces where the .capnp schema defines exactly what methods exist.

capOS’s approach: the interface IS the permission. To restrict what a caller can do, grant a narrower capability:

• Fetch (full HTTP) → HttpEndpoint (scoped to one origin)
• Store (read-write) → Store wrapper that rejects write methods
• Namespace (full) → Namespace scoped to a prefix

The “restricted” capability is a different CapObject implementation that wraps the original. The kernel doesn’t know or care – it dispatches to whatever CapObject is in the slot. Attenuation is userspace/schema logic, not a kernel mechanism.

When transfer control is needed (Stage 6): meta-rights for the capability itself (can it be transferred? duplicated?) may be added as a small bitmask. These are about the reference, not the referenced object, and don’t overlap with interface-level method access control.

See research.md for the cross-system analysis that led to this decision (§1 Capability Table Design).

Planned Enhancements (from research)

Tracked in ROADMAP.md Stages 5-6:

• Badge (from seL4) – u64 value per capability entry, delivered to the server on invocation. Implemented for manifest cap refs, IPC transfer, and ProcessSpawner endpoint-client minting so servers can distinguish callers without separate capability objects per client.
• Epoch (from EROS) – per-object revocation epoch. Incrementing the epoch invalidates all outstanding references. O(1) revoke, O(1) check.

Current Limitations

• Blocking wait exists, but waits are still process-level. cap_enter(min_complete, timeout_ns) processes pending SQEs and can block the current process until enough CQEs exist or a finite timeout expires. It is not yet a general futex/thread wait primitive; in-process threading and futex-shaped measurements are tracked separately.
• No persistence. Capabilities exist only at runtime.
• Capability transfer is implemented for Endpoint CALL/RECV/RETURN. Transfer descriptors on the capability ring let callers and receivers copy or move transferable local caps through IPC messages. See storage-and-naming-proposal.md “IPC and Capability Transfer” for the full design.
• Transfer ABI (3.6.0 draft). Sideband transfer descriptors are defined in capos-config/src/ring.rs as CapTransferDescriptor:
  • cap_id is the sender-side local capability-table handle.
  • transfer_mode is either CAP_TRANSFER_MODE_COPY or CAP_TRANSFER_MODE_MOVE.
  • xfer_cap_count in CapSqe is the descriptor count.
  • For CALL/RETURN, descriptors are packed at addr + len after the payload bytes and must be aligned to CAP_TRANSFER_DESCRIPTOR_ALIGNMENT.
  • Result-cap insertion semantics are defined by CapCqe: result reports normal payload bytes, while cap_count reports how many CapTransferResult { cap_id, interface_id } records were appended immediately after those payload bytes in result_addr when CAP_CQE_TRANSFER_RESULT_CAPS is set. User space must bound-check result + cap_count * CAP_TRANSFER_RESULT_SIZE against its requested result_len.
  • Transfer-bearing SQEs are fail-closed:
    • unsupported-by-kernel-transfer path: CAP_ERR_TRANSFER_NOT_SUPPORTED (until sideband transfer is enabled),
    • malformed descriptor metadata (invalid mode, reserved bits, non-zero _reserved0, misalignment, overflow): CAP_ERR_INVALID_TRANSFER_DESCRIPTOR,
    • all other reserved-field misuse remains CAP_ERR_INVALID_REQUEST.
• No revocation propagation. Removing a table entry doesn’t invalidate copies or derived capabilities. Epoch-based revocation is planned.
• No bulk data path. All data goes through capnp message copy. SharedBuffer / MemoryObject capability needed for file I/O, networking, GPU data plane. See storage-and-naming-proposal.md “Shared Memory for Bulk Data” for the interface design.

Future Directions

• Capability transfer. Cross-process capability calls already go through the kernel via Endpoint objects with RECV/RETURN SQE opcodes on the existing per-process capability ring (no new syscalls). The remaining transfer work will carry capability references with sideband descriptors and install result caps in the receiver’s local table. See storage-and-naming-proposal.md for how this enables Directory.open() returning File caps, Namespace.sub() returning scoped Namespace caps, etc.
• Persistence. Serialize capability state to storage using capnp format. Restore capabilities across reboots.
• Network transparency. Forward capability calls to remote machines using the same capnp wire format. A remote Console capability looks identical to a local one.

Capability Ring

The capability ring is the userspace-to-kernel transport for capability invocation. It avoids one syscall per operation while preserving a typed Cap’n Proto method boundary and explicit completion reporting.

Status: Implemented. The shared-memory ring, cap_enter, CALL/RECV/RETURN/RELEASE/NOP dispatch, structured transport errors, bounded scratch buffers, and Loom ring model are implemented. FINISH, promise pipelining, multishot, link, drain, and SQPOLL remain future work.

Current Behavior

Each non-idle process gets one 4 KiB ring page mapped at RING_VADDR. The page contains a volatile header, a 16-entry submission queue, and a 32-entry completion queue. Userspace writes CapSqe records, advances sq_tail, and uses cap_enter(min_complete, timeout_ns) to make ordinary calls progress.

sequenceDiagram
    participant U as Userspace runtime
    participant R as Ring page
    participant K as Kernel ring dispatcher
    participant C as Capability object
    U->>R: write CapSqe and advance sq_tail
    U->>K: cap_enter(min_complete, timeout_ns)
    K->>R: read sq_head..sq_tail
    K->>K: validate SQE fields and user buffers
    K->>C: call method or endpoint operation
    C-->>K: completion, pending, or error
    K->>R: write CapCqe and advance cq_tail
    K-->>U: return available CQE count
    U->>R: read matching CapCqe

Timer polling also processes each current process’s ring before preemption, but only non-CALL operations and CALL targets that explicitly allow interrupt dispatch may run there. Ordinary CALLs wait for cap_enter.

Why ordinary CALL waits for cap_enter: Submitting a CALL SQE is only a shared-memory write. The kernel still needs a safe execution point to drain the ring and run capability code. Timer polling runs in interrupt context, so it must not execute arbitrary capability methods that may allocate, block on locks, mutate page tables, spawn processes, parse Cap’n Proto messages, or perform IPC side effects. cap_enter is the normal process-context drain point: it processes pending SQEs, posts CQEs, and then either returns the available completion count or blocks until enough completions arrive. The design keeps SQE publication syscall-free and batchable, keeps the syscall ABI limited to exit and cap_enter, and avoids turning the timer interrupt into a general capability executor. A future SQPOLL-style path can remove the explicit syscall from the hot path only by running dispatch in a worker context, not from arbitrary timer interrupt execution.

Design

CapSqe is a fixed 64-byte ABI record. CAP_OP_CALL names a local cap-table slot and method ID plus parameter/result buffers. CAP_OP_RECV and CAP_OP_RETURN implement endpoint IPC. CAP_OP_RELEASE removes a local cap-table slot through the transport. CAP_OP_NOP measures the fixed ring path. CAP_OP_FINISH is ABI-reserved and currently returns CAP_ERR_UNSUPPORTED_OPCODE.

The kernel copies user params into preallocated per-process scratch, dispatches capability methods, serializes results directly into caller-provided result buffers, and posts CapCqe. A successful method returns non-negative bytes written. Transport failures are negative CAP_ERR_* codes. Application exceptions are serialized CapException payloads with CAP_ERR_APPLICATION_EXCEPTION.

Transfer-bearing CALL and RETURN SQEs pack CapTransferDescriptor records after the params/result payload. Successful result-cap transfers append CapTransferResult records after normal result bytes.

Future behavior should use the reserved SQE fields for system transport features, not ad hoc per-interface extensions.

Invariants

• SQ and CQ sizes are powers of two and fixed by the ABI.
• Unknown opcodes fail closed; FINISH is reserved, not silently accepted.
• Reserved fields must be zero for currently implemented opcodes.
• cap_enter rejects min_complete > CQ_ENTRIES.
• User buffers must be in user address space with page permissions matching read/write intent before copy.
• Timer dispatch must not run capabilities that allocate, block on locks, or mutate page tables unless the cap explicitly opts in.
• Per-dispatch SQE processing is bounded by SQ_ENTRIES.
• Transfer descriptors must be aligned, valid, and bounded by MAX_TRANSFER_DESCRIPTORS.

Code Map

• capos-config/src/ring.rs - shared ring ABI, opcodes, errors, SQE/CQE structs, endpoint message headers, transfer records.
• kernel/src/cap/ring.rs - kernel dispatcher, SQE validation, CQE posting, cap calls, endpoint CALL/RECV/RETURN, release, transfer framing.
• kernel/src/arch/x86_64/syscall.rs - cap_enter syscall.
• kernel/src/sched.rs - timer polling, cap-enter blocking, direct IPC wake.
• kernel/src/process.rs - ring page allocation and mapping.
• capos-rt/src/ring.rs - runtime ring client, pending calls, transfer packing, result-cap parsing.
• capos-rt/src/entry.rs - single-owner runtime ring client token and release queue flushing.
• capos-config/tests/ring_loom.rs - bounded producer/consumer model.

Validation

• cargo test-ring-loom validates SQ/CQ producer-consumer behavior, capacity, FIFO, CQ overflow/drop behavior, and corrupted SQ recovery.
• make run exercises Console CALLs, reserved opcode rejection, ring corruption recovery, NOP, fairness, transfers, and endpoint IPC.
• make run-measure exercises measurement-only NOP and NullCap baselines.
• cargo test-config covers shared ring layout and helper invariants.
• make capos-rt-check checks userspace runtime ring code under the bare-metal target.

Open Work

• Implement CAP_OP_FINISH as part of the system Cap’n Proto transport.
• Add promise pipelining using pipeline_dep and pipeline_field.
• Define LINK, DRAIN, and MULTISHOT semantics before accepting those flags.
• Add SQPOLL after SMP gives the kernel a spare execution context.

IPC and Endpoints

Endpoints let one process serve capability calls to another process without adding a separate IPC syscall surface. The same ring transport carries ordinary kernel capability calls and cross-process endpoint calls.

Status: Partially implemented. Ring-native endpoint CALL/RECV/RETURN, client endpoint attenuation, badges, copy and move capability transfer, direct IPC handoff, and cleanup for many exit paths are implemented. Notification objects, promise pipelining, shared buffers, revocation, and transfer-path cleanup refactoring remain open.

Current Behavior

An Endpoint is a kernel capability object with queues for pending client calls, pending server receives, and in-flight calls awaiting RETURN. A service that owns the raw endpoint can receive and return. Importers receive a ClientEndpoint facet that can CALL but cannot RECV or RETURN.

sequenceDiagram
    participant Client
    participant ClientRing as Client ring
    participant Endpoint
    participant ServerRing as Server ring
    participant Server
    Server->>ServerRing: submit RECV on raw endpoint
    Client->>ClientRing: submit CALL on client facet
    ClientRing->>Endpoint: deliver params and caller result target
    Endpoint->>ServerRing: complete RECV with EndpointMessageHeader and params
    ServerRing-->>Server: cap_enter returns completion
    Server->>ServerRing: submit RETURN with call_id and result
    ServerRing->>Endpoint: take in-flight target
    Endpoint->>ClientRing: post caller CQE with result and badge
    ClientRing-->>Client: wait returns matching completion

If a CALL arrives before a RECV, the endpoint queues bounded params. If a RECV arrives before a CALL, the endpoint queues the receive request. Delivered calls move into the in-flight queue until the server returns or cleanup cancels them.

Design

Endpoint IPC is capability-oriented. The manifest can export a raw endpoint from one service; importers get a narrowed client facet. This keeps server-only authority out of clients without introducing rights bitmasks.

CALL and RETURN may carry sideband transfer descriptors. Copy transfers insert a new cap into the receiver while preserving the sender. Move transfers reserve the sender slot, insert the destination, then remove the source on commit. RETURN-side transfers append result-cap records after the normal result payload.

Badges are stored on cap-table hold edges and delivered to servers with endpoint invocation metadata, so one endpoint can distinguish callers without one object per caller.

Future IPC should add notification objects for lightweight signaling and promise pipelining for Cap’n Proto-style dependent calls.

Invariants

• Only raw endpoint holders may RECV or RETURN.
• Imported endpoint caps are ClientEndpoint facets and must reject RECV and RETURN from userspace.
• Endpoint queues are bounded by call count, receive count, in-flight count, per-call params, and total queued params.
• Each in-flight call has a kernel-assigned non-zero call_id.
• CALL delivery copies params into kernel-owned queued storage before the caller can resume.
• Move transfer commit must not leave both source and destination live.
• Transfer rollback must preserve source authority if destination insertion or result delivery fails.
• Process exit must cancel queued state involving that pid and wake affected peers when possible.

Code Map

• kernel/src/cap/endpoint.rs - endpoint queues, client facet, call IDs, cancellation by pid.
• kernel/src/cap/ring.rs - endpoint CALL/RECV/RETURN dispatch, result copying, deferred cancellation CQEs.
• kernel/src/cap/transfer.rs - transfer descriptor loading and transaction preparation.
• capos-lib/src/cap_table.rs - cap-table transfer primitives and rollback.
• kernel/src/cap/mod.rs - manifest export resolution and client-facet construction.
• capos-config/src/ring.rs - EndpointMessageHeader, transfer descriptors, transfer result records, endpoint opcodes.
• demos/capos-demo-support/src/lib.rs - endpoint, IPC, transfer, and hostile IPC smoke routines.
• demos/endpoint-roundtrip, demos/ipc-server, demos/ipc-client - QEMU smoke binaries.

Validation

• make run validates same-process endpoint RECV/RETURN, cross-process IPC, endpoint exit cleanup, badged calls, transfer success/failure paths, and clean halt.
• make run-spawn validates init-spawned endpoint-roundtrip, server, and client processes.
• cargo test-lib covers cap-table transfer preflight, provisional insertion, commit, rollback, stale generation, and slot exhaustion cases.
• cargo test-ring-loom covers ring queue behavior that endpoint IPC depends on for completion delivery.

Open Work

• Add notification objects for signal-style events.
• Add Cap’n Proto promise pipelining after endpoint routing can resolve dependent answers.
• Add shared-buffer or memory-object capabilities for bulk data transfer.
• Add epoch-based revocation if broad authority invalidation becomes necessary.

Userspace Runtime

The userspace runtime owns the repeated mechanics that every service needs: bootstrap validation, heap initialization, typed capability lookup, ring submission, completion matching, application exception decoding, and handle lifetime.

Status: Partially implemented. capos-rt provides a no_std entry ABI, fixed heap, typed CapSet lookup, a single-owner ring client, typed Console and ProcessSpawner clients, result-cap adoption, and release-on-drop for owned handles. Full generated bindings, promise pipelining, language runtimes, and broad transport semantics remain future work.

Current Behavior

Runtime-owned _start receives (ring_addr, pid, capset_addr), initializes a fixed heap, validates the ring address, reads the read-only CapSet page, installs an emergency Console panic path when available, calls capos_rt_main(runtime), and exits with the returned code.

The Runtime lends out at most one RuntimeRingClient at a time. The client wraps the raw ring page, keeps request buffers alive until completions are matched, handles out-of-order completions, packs copy-transfer descriptors, and parses result-cap records. Owned runtime handles queue CAP_OP_RELEASE when the last local reference is dropped; the release queue flushes when a ring client is borrowed or dropped.

Design

The runtime separates non-owning bootstrap references from owned local handles. CapSet entries produce typed Capability<T> values only when the interface ID matches the requested type. Result-cap adoption performs the same interface check before producing OwnedCapability<T>.

Typed clients are thin wrappers over the ring client. They encode Cap’n Proto params, submit CALL SQEs, wait for a matching CQE, decode transport errors, and decode kernel-produced CapException payloads into client errors.

Future generated clients should preserve this split: transport lifetime and completion matching belong in the runtime, while interface-specific encoding belongs in generated or handwritten client wrappers.

Invariants

• ring_addr must equal RING_VADDR; runtime bootstrap rejects any other address.
• The CapSet header magic/version must validate before lookup.
• CapSet handles are non-owning unless explicitly adopted.
• Only one runtime ring client may be live at a time for a process.
• Request params and result buffers must outlive their matching CQE.
• A result cap can be consumed only once and only with the expected interface ID.
• Dropping the final owned handle queues exactly one local CAP_OP_RELEASE.
• Release flushing treats stale or already-removed caps as non-fatal cleanup.

Code Map

• capos-rt/src/entry.rs - _start, Runtime, bootstrap validation, single-owner ring token, release queue flushing.
• capos-rt/src/alloc.rs - fixed userspace heap initialization.
• capos-rt/src/capset.rs - typed CapSet lookup wrappers.
• capos-rt/src/ring.rs - ring client, pending calls, completion matching, copy-transfer packing, result-cap parsing.
• capos-rt/src/client.rs - Console, ProcessSpawner, ProcessHandle clients and exception decoding.
• capos-rt/src/lib.rs - typed capability marker types and owned handle reference counting.
• capos-rt/src/panic.rs - emergency Console output path.
• init/src/main.rs and capos-rt/src/bin/smoke.rs - current runtime users.

Validation

• make capos-rt-check builds the runtime smoke binary with userspace relocation constraints.
• make run validates runtime entry, typed Console calls, exception decoding, owned handle release, result-cap parsing through IPC, and clean process exit.
• make run-spawn validates ProcessSpawnerClient, ProcessHandleClient, result-cap adoption, and release behavior under init spawning.
• cd capos-rt && cargo test --lib --target x86_64-unknown-linux-gnu covers host-testable runtime invariants when run explicitly.

Open Work

• Replace duplicated demo support ring helpers with capos-rt where practical.
• Add generated client bindings after the schema surface stabilizes.
• Implement promise/answer transport semantics beyond current placeholders.
• Define release behavior for queued handles when a process exits before the release queue flushes.

Manifest and Service Startup

The manifest is the boot-time authority graph. It names binaries, services, initial capabilities, exported service caps, restart policy metadata, badges, and system config.

Status: Partially implemented. Manifest parsing, Cap’n Proto encoding, CUE conversion, binary embedding, kernel-side service startup, service exports, endpoint client facets, badges, BootPackage manifest exposure to init, init-side graph validation, and generic init-side spawning through ProcessSpawner are implemented for system-spawn.cue. Retiring the default kernel-side service graph is the remaining selected milestone work.

Current Behavior

tools/mkmanifest requires the repo-pinned CUE compiler, evaluates system.cue, embeds declared binaries, validates binary references and authority graph structure, serializes SystemManifest, and places manifest.bin into the ISO. The kernel receives that file as the single Limine module.

flowchart TD
    Cue[system.cue or system-spawn.cue] --> Mkmanifest[tools/mkmanifest]
    Binaries[release userspace binaries] --> Mkmanifest
    Mkmanifest --> Manifest[manifest.bin SystemManifest]
    Manifest --> Limine[Limine boot module]
    Limine --> Kernel[kernel parse and validate]
    Kernel --> Tables[CapTables and CapSet pages]
    Tables --> BootServices[default: kernel-enqueued services]
    Tables --> Init[spawn manifest: init gets ProcessSpawner and BootPackage]
    Init --> BootPackage[BootPackage.readManifest chunks]
    BootPackage --> Plan[capos-config ManifestBootstrapPlan validation]
    Init --> Spawner[ProcessSpawner.spawn]
    Spawner --> Children[init-spawned child processes]

The default manifest currently starts all services from the kernel. The spawn manifest starts only init, grants it ProcessSpawner plus a read-only BootPackage cap, and lets init read bounded manifest chunks into a metadata-only capos-config::ManifestBootstrapPlan. Init validates binary references, authority graph structure, exports, cap sources, and interface IDs before spawning the endpoint, IPC, VirtualMemory, and FrameAllocator cleanup demos. Spawn grants carry explicit requested badges: raw parent-capability grants must preserve the source hold badge, endpoint-client grants may mint the requested badge only from an endpoint-owner source, and kernel-source FrameAllocator/VirtualMemory grants mint fresh child-local caps without badges.

Design

Manifest validation has three layers:

• Binary references: binary names are unique, service binary references resolve, and referenced binary payloads are non-empty.
• Authority graph: service names, cap names, export names, and service-sourced references are unique and resolvable; re-exporting service-sourced caps is rejected.
• Bootstrap cap sources: expected interface IDs match kernel sources or declared service exports.

Kernel startup resolves caps in two passes. Pass 1 creates kernel-sourced caps and records declared exports. Pass 2 resolves service-sourced imports against the export registry, attenuating endpoint exports to client-only facets for importers. Declaration order is preserved because CapIds are assigned by insertion order and CapSet entries mirror that order.

Future behavior should make the kernel parse only enough boot information to launch init with manifest/boot-package authority. init should use BootPackage.readManifest to validate the service graph, call ProcessSpawner, grant caps, and wait for services where policy requires it.

Invariants

• The manifest is schema data, not shell script or ambient namespace.
• Omitted cap sources fail closed.
• Cap names within one service are unique and are the names userspace sees in CapSet.
• Service exports must name caps declared by the same service.
• Service-sourced imports must reference a declared service export.
• Endpoint exports to importers must be attenuated to client-only facets.
• expectedInterfaceId checks compatibility; it is not the authority selector.
• Badges travel with cap-table hold edges and endpoint invocation metadata. Spawn-time client endpoint minting carries the requested child badge instead of copying the parent’s owner-hold badge.

Code Map

• schema/capos.capnp - SystemManifest, ServiceEntry, CapRef, KernelCapSource, ServiceCapSource, RestartPolicy.
• capos-config/src/manifest.rs - manifest structs, CUE conversion, capnp encode/decode, metadata-only ManifestBootstrapPlan, schema-version guardrails, validation.
• tools/mkmanifest/src/lib.rs and tools/mkmanifest/src/main.rs - host-side manifest build pipeline and binary embedding.
• kernel/src/main.rs - kernel manifest module parse and validation.
• kernel/src/cap/mod.rs - service cap creation, exports, endpoint attenuation, CapSet entry construction.
• kernel/src/cap/boot_package.rs - read-only manifest-size and chunked manifest-read capability.
• kernel/src/cap/process_spawner.rs - init-callable spawn path for packaged boot binaries.
• capos-rt/src/client.rs - typed BootPackage and ProcessSpawner clients.
• init/src/main.rs - current spawn manifest executor smoke.
• system.cue and system-spawn.cue - current manifests.

Validation

• cargo test-config validates manifest decode, CUE conversion, graph checks, source checks, and binary reference checks.
• cargo test-mkmanifest validates host-side manifest conversion, embedded binary handling, and pinned CUE path/version checks.
• make run validates default kernel-side manifest execution.
• make run-spawn validates system-spawn.cue, init-side BootPackage manifest reads, init-side manifest graph validation, init-side spawning, hostile spawn failures, child grants, process waits, and cap-table exhaustion checks.
• make generated-code-check validates schema-generated Rust stays in sync.

Open Work

• Retire the default kernel-side service graph and make the normal boot path launch only init before service startup.

Memory Management

Memory management gives the kernel controlled ownership of physical frames, separates user processes, enforces page permissions, and exposes memory authority only through explicit capabilities.

Status: Partially implemented. Physical frame allocation, heap initialization, kernel page-table remapping, per-process address spaces, ELF/user stack/TLS mappings, user-buffer validation, FrameAllocator, and VirtualMemory caps are implemented. Broader quota unification, SMP-safe validation, shared buffers, huge pages, and hardware I/O memory isolation remain open.

Current Behavior

The frame allocator builds a bitmap from the Limine memory map, marks all non-usable frames as used, reserves frame zero, and reserves its own bitmap frames. The heap is initialized separately for kernel allocation.

Paging initialization builds a new kernel PML4, remaps kernel sections with section-specific permissions, copies upper-half mappings with NX applied and user access stripped, switches CR3, then enables page-global support. SMEP/SMAP are enabled after those mappings are active.

Each user AddressSpace owns its lower-half page tables and clones the kernel’s upper-half mappings. Dropping an address space walks the user half and frees mapped frames and page-table frames. VirtualMemory lets a process map, unmap, and protect anonymous user pages, with a 256-page per-address-space tracking limit.

Design

The kernel keeps physical allocation host-testable by placing bitmap logic in capos-lib and wrapping it with kernel HHDM access in kernel/src/mem/frame.rs. Page-table manipulation stays in the kernel because it is architecture-specific.

ELF loading and VirtualMemory both use page-table flags to preserve W^X: non-executable data gets NX, writable mappings are explicit, and userspace pages must be USER_ACCESSIBLE. The CapSet and ring bootstrap pages occupy reserved virtual pages; VirtualMemory rejects ranges that overlap either one.

User-buffer validation checks that user pointers stay below the user address limit and that page-table permissions match the requested access. SMAP UserAccessGuard brackets kernel copy operations into or out of user pages.

Future memory work should unify quotas across frame grants, VM mappings, shared buffers, and DMA resources rather than adding one-off counters per cap.

Invariants

• Frame addresses are 4 KiB aligned.
• The frame bitmap’s own frames are never returned as free frames.
• Upper-half kernel mappings are not user-accessible.
• Kernel text is RX, rodata is read-only NX, and data/bss are RW NX.
• User address spaces own only lower-half page-table frames.
• CapSet is read-only/no-execute; ring is writable/no-execute.
• VirtualMemory cannot map, unmap, or protect the ring or CapSet pages.
• VirtualMemory protect/unmap only succeeds for pages tracked as owned by the cap’s address space.

Code Map

• capos-lib/src/frame_bitmap.rs - host-testable physical frame bitmap core.
• capos-lib/src/frame_ledger.rs - outstanding grant ledger for FrameAllocator cleanup.
• kernel/src/mem/frame.rs - Limine memory-map integration and global frame allocator wrapper.
• kernel/src/mem/heap.rs - kernel heap setup.
• kernel/src/mem/paging.rs - kernel remap, AddressSpace, page mapping, VM-cap page tracking, user copy helpers.
• kernel/src/mem/validate.rs - user-buffer validation.
• kernel/src/cap/frame_alloc.rs - FrameAllocator capability and cleanup.
• kernel/src/cap/virtual_memory.rs - VirtualMemory capability.
• kernel/src/spawn.rs - ELF, stack, and TLS user mappings.
• kernel/src/arch/x86_64/smap.rs - SMEP/SMAP setup and user access guard.

Validation

• cargo test-lib covers frame bitmap, frame ledger, ELF parser, and cap-table pure logic.
• cargo miri-lib runs host-testable capos-lib tests under Miri when installed.
• make kani-lib proves bounded frame bitmap, cap ID, and ELF parser invariants when Kani is installed.
• make run validates ELF mapping, process teardown, FrameAllocator cleanup, TLS, VirtualMemory map/protect/unmap/quota/release smoke, and clean halt.
• make run-spawn validates ELF load failure rollback and frame exhaustion handling through ProcessSpawner.

Open Work

• Resolve quota fragmentation across FrameAllocator, VirtualMemory, and future shared memory.
• Harden user-buffer validation for SMP-era page-table races.
• Add shared-buffer or memory-object capabilities for zero-copy data paths.
• Add DMA isolation and device memory capability boundaries before userspace drivers.
• Add huge-page handling only with explicit ownership and teardown rules.

Scheduling

Scheduling decides which process runs, preserves CPU state across preemption and blocking, and integrates capability-ring progress with process execution.

Status: Partially implemented. Single-CPU preemptive round-robin scheduling, PIT timer interrupts, full context switches, cap_enter blocking waits, user-mode idle, process exit, and direct IPC handoff are implemented. SMP, per-CPU data, kernel-mode idle, priority, and restart policy are future work.

Current Behavior

The scheduler stores processes in a BTreeMap<Pid, Process> and ready pids in a VecDeque. PIT fires at roughly 100 Hz through IRQ0. On each timer tick, the kernel wakes timed-out or satisfied cap_enter waiters, processes the current process’s ring in timer mode, saves the current context, rotates ready processes, switches CR3, updates TSS.RSP0 and the syscall kernel stack, restores FS base, and returns to the next user context.

cap_enter(min_complete, timeout_ns) processes pending SQEs immediately. If the requested completion count is not available and the timeout permits blocking, the current process enters Blocked(CapEnter { ... }) and the syscall entry path switches to another process.

When endpoint delivery satisfies a blocked server RECV, the scheduler can set a direct IPC target. The next scheduling decision runs that server before ordinary round-robin work when it is ready.

Design

The implementation keeps ring dispatch outside the global scheduler lock. Timer dispatch extracts ring/cap/scratch handles, releases the scheduler lock, processes bounded SQEs, then reacquires the scheduler lock to choose the next process. This prevents Cap’n Proto decode, serial output, and capability method bodies from running under the global scheduler lock.

The idle task is currently a user-mode process with one code page and one stack page. It exists because the timer return path assumes interrupts entered from CPL3. A future kernel-mode idle loop requires distinct IRQ entry/restore handling for CPL0 and CPL3 frames.

Exit switches to the kernel PML4 before tearing down the exiting address space, releases capability authority, completes process waiters, and defers final drop until the scheduler is running on another kernel stack.

Invariants

• The idle process must never block in cap_enter or exit.
• Ring dispatch must not hold the scheduler lock.
• Timer dispatch runs with the current process CR3, so user buffers are accessible only for that process.
• Blocked cap_enter waiters wake when enough CQEs are available or their finite timeout expires.
• Direct IPC handoff is a scheduling preference, not a bypass of process state checks.
• The scheduler must update TSS.RSP0 and syscall kernel RSP on each switch.
• FS base is saved and restored across context switches for TLS.
• The final drop of an exiting process must not occur on its own kernel stack.

Code Map

• kernel/src/sched.rs - process table, run queue, blocking, wakeups, timer scheduling, exit, direct IPC target.
• kernel/src/arch/x86_64/context.rs - CPU context layout, timer entry/restore, tick counter.
• kernel/src/arch/x86_64/idt.rs - timer interrupt handler wiring.
• kernel/src/arch/x86_64/pic.rs and kernel/src/arch/x86_64/pit.rs - PIC remap and PIT setup.
• kernel/src/arch/x86_64/gdt.rs - TSS and kernel stack updates.
• kernel/src/arch/x86_64/syscall.rs - blocking syscall transition for cap_enter.
• kernel/src/arch/x86_64/tls.rs - FS base save/restore.
• kernel/src/process.rs - process state, kernel stacks, idle process.

Validation

• make run validates timer preemption, ring fairness, direct IPC handoff, blocked cap_enter wakeups, process exit, and clean halt.
• make run-spawn validates process wait blocking and child exit completion through ProcessHandle.wait.
• cargo build --features qemu verifies QEMU-only scheduler and halt paths.
• QEMU smoke output for IPC includes direct handoff diagnostics when the server is woken from a blocked RECV.

Open Work

• Replace the user-mode idle process with a kernel/per-CPU idle context after interrupt restore paths support CPL0 timer entries.
• Implement SMP with per-CPU scheduler state, per-CPU syscall stacks, and TLB shootdown.
• Add priority or policy scheduling only after the current authority and IPC semantics remain stable.
• Add service restart policy outside the static boot graph.

Trust Boundaries

This page gives reviewers one place to find the hostile-input boundaries, trusted inputs, and current isolation assumptions that matter for capOS security review.

Current Boundaries

Security Invariants

• All authority is represented by capability-table hold edges; no syscall or host tool path should bypass the capability graph.
• The interface is the permission: method authority is expressed by the typed Cap’n Proto interface or by a narrower wrapper capability, not by ambient process identity.
• Kernel operations at hostile boundaries validate structure, bounds, ownership, generation, interface ID, and resource availability before mutating privileged state.
• Failed transfer, spawn, manifest, and DMA setup paths must leave ledgers, cap tables, frame ownership, and in-flight call state unchanged or explicitly rolled back.
• Trusted build inputs must be pinned or drift-review-visible before their output becomes part of the boot image or generated source baseline.

Open Work

• Unify fragmented resource ledgers into the authority-accounting model so reviewers can audit quotas without following parallel counters.
• Harden open panic-surface entries that become more exposed as spawn, lifecycle, SMP, or userspace drivers expand hostile input reachability.
• Keep DMA in kernel-owned bounce-buffer mode until the DMAPool, DeviceMmio, and Interrupt transition gates have code and QEMU proof.

Verification Workflow

This page maps capOS claims to the commands, QEMU smokes, fuzz targets, proof tools, and review documents that currently support them.

Local Command Set

Use the repo aliases and Makefile targets instead of bare host commands. The workspace default Cargo target is x86_64-unknown-none, so host tests rely on aliases that set the host target explicitly.

Do not claim full verification unless the relevant command actually ran in the current change. For doc-only changes, use an appropriately narrower check such as mdbook build.

Review Workflow

1. Identify the changed trust boundary or state that the change is docs-only.
2. Read REVIEW.md for the applicable security, unsafe, memory, performance, capability, and emergency-path checklist.
3. Read REVIEW_FINDINGS.md before judging correctness so known open findings are not treated as solved behavior.
4. For system-design work, list the concrete design and research files read; reviewers should reject vague grounding such as “docs” or “research”.
5. Run the smallest command set that exercises the changed behavior, then add QEMU proof for user-visible kernel or runtime behavior.
6. Record unresolved non-critical findings in REVIEW_FINDINGS.md with concrete remediation context before treating the task as reviewed.

Evidence by Claim

Fuzzing and Proof Tracks

The current fuzz corpus lives under fuzz/ and covers manifest Cap’n Proto input, exported JSON conversion for mkmanifest, and arbitrary ELF parser input. Run fuzzers when a change alters those parsers, schema shape, or validation rules.

Kani coverage is intentionally narrow and lives in capos-lib, where pure logic can be bounded without hardware state. Add or refresh Kani harnesses for ledger, cap-table, bitmap, and parser invariants when those invariants become part of a security claim.

Loom coverage belongs in shared ring logic. Extend cargo test-ring-loom when SQ/CQ ownership, ordering, corruption recovery, or wake semantics change.

Documentation Sources

• REVIEW.md: rules for security, unsafe code, capability invariants, resource accounting, and emergency paths.
• REVIEW_FINDINGS.md: open remediation backlog and latest verification records.
• ../trusted-build-inputs.md: trusted compiler, generated-code, dependency, bootloader, manifest, and host-tool inputs.
• ../panic-surface-inventory.md: classified panic-like surfaces and commands used to generate the inventory.
• ../authority-accounting-transfer-design.md: authority graph, quota, transfer, rollback, and ProcessSpawner accounting invariants.

Panic-Surface Inventory

Scope: panic!, assert!, debug_assert!, .unwrap(), .expect(), todo!, and unreachable! surfaces relevant to boot manifest loading, ELF loading, SQE handling, params/result buffers, IPC, and future spawn inputs.

Classification terms:

• trusted-internal: depends on kernel/shared-code invariants, static ABI layout, or host build/test code; not directly controlled by a service.
• boot-fatal: reached during boot/package setup before mutually untrusted services run. Bad platform/package state can halt the system.
• untrusted-input reachable: reachable from userspace-controlled SQEs, Cap’n Proto params/result buffers, IPC state, manifest/package data, or future spawn-controlled service/binary data.

Summary

No current panic!/assert!/unwrap()/expect() site found in the kernel ring dispatch path directly consumes raw SQE fields or user params/result-buffer pointers. Those paths mostly return CQE errors through kernel/src/cap/ring.rs.

The remaining relevant surfaces are boot-fatal setup assumptions, scheduler internal invariants that would become more exposed once untrusted spawn/lifecycle inputs can create or destroy processes dynamically, one IPC queue invariant, and a manifest validation .expect() guarded by a prior graph-validation call.

Manifest And Future Spawn Inputs

ELF Inputs

SQE And Params/Result Buffers

IPC

Scheduler And Process Lifecycle

Boot Platform And Memory Setup

Verification Notes

Inventory commands run:

rg -n "\b(panic!|assert!|assert_eq!|assert_ne!|debug_assert!|debug_assert_eq!|debug_assert_ne!|unwrap\(|expect\(|todo!|unreachable!)" kernel capos-lib capos-config init demos tools schema system.cue Makefile docs -g '*.rs' -g '*.cue' -g '*.md' -g 'Makefile'
rg -n "\b(panic!|assert!|assert_eq!|assert_ne!|debug_assert!|debug_assert_eq!|debug_assert_ne!|unwrap\(|expect\(|todo!|unreachable!)" kernel/src capos-lib/src capos-config/src init/src demos/capos-demo-support/src demos/*/src tools/mkmanifest/src -g '*.rs'

Code tests were not run for this doc-only inventory because the write scope is limited to docs/panic-surface-inventory.md and no Rust code, schema, manifest, or build configuration changed.

Trusted Build Inputs

This inventory covers the build inputs currently trusted by the capOS boot image, generated bindings, host tooling, and verification paths. It started as the S.10.0 inventory and now records the S.10.2 generated-code drift check. It now also records the S.10.3 dependency policy.

Summary

S.10.3 Dependency Policy

Dependency changes are accepted only if they satisfy this policy and are recorded in the owning task checklist.

Dependency classes

Use these classes when reviewing a dependency change:

• Kernel-critical no_std: crates used directly by kernel, capos-lib, and capos-config.
• Userspace-runtime no_std: crates used by init, demos, and capos-rt.
• Host/build: crates used by tools/*, build.rs helpers, and generated output pipelines.
• Test/fuzz/dev: crates gated by dev-dependencies or target-specific for fuzz/proptests/smoke support.

Required pre-merge criteria

For any added dependency (or bump in any class):

1. Manifest and features are explicit. Dependency entries must include explicit feature choices; avoid default-features = true unless justified.
2. No_std compatibility is proven for no_std classes. Kernel-critical and userspace-runtime dependencies must compile in a #![no_std] mode with alloc where expected. cargo build -p <crate> --target x86_64-unknown-none must succeed for every kernel/no_std crate affected.
3. Security policy checks run and pass. CI-equivalent checks for the touched workspace are required through make dependency-policy-check, which runs cargo deny check on every Cargo manifest and cargo audit on every lockfile.
4. Dependency class change is justified in review. PR text must include target class, ownership rationale, transitive graph impact, and why the crate is not a transitive replacement for an already-allowed dependency.
5. Lockfile behavior is explicit. Update only intended lockfiles and record intentional cross-workspace drift in this document if workspace purpose differs.

No_std add/edit checklist

• Reject crates that require std, OS I/O, or unsupported platform APIs in the dependency path intended for kernel classes.
• Reject dependencies that re-export broad platform facades or large unsafe surface unless there is a replacement with smaller scope and better audit visibility.
• Record a license and supply-chain review result (via policy checks) before merge.
• Confirm no unsafe contract escapes are added without a review surface note in the relevant module.

Standing requirements

• Add S.10.3 checks to the target branch plan item for any kernel/no_std crate dependency change and document the exact pass command set.
• Keep lockfile deltas review-visible in normal PR flow; lockfile pinning is the minimum bar, not the gate.
• Keep transitive drift in sync with the trust class: class-wide divergence across lockfiles requires explicit justification.

Remaining gaps after S.10.3 policy

• Continue Rust toolchain pinning work (date/hash pin, reproducible host compiler inputs) as a separate build-reproducibility task.
• Decide whether final ISO/payload hashes become policy-grade inputs in production-hardening stages.

Bootloader and ISO Inputs

The Makefile now pins Limine at commit aad3edd370955449717a334f0289dee10e2c5f01 and verifies these copied artifacts:

make limine-ensure clones https://github.com/limine-bootloader/limine.git only when limine/.git is absent, fetches the pinned commit if needed, checks it out detached, and runs make inside the Limine tree (Makefile:34-40). make limine-verify then checks the repository HEAD and artifact checksums (Makefile:42-49). The ISO copies the kernel, generated manifest.bin, Limine config, and verified Limine artifacts into iso_root/, runs xorriso, then runs limine bios-install (Makefile:51-65).

Remaining reproducibility gap: Limine source is pinned, but the Limine build host compiler and environment are not pinned or recorded.

Rust Toolchain

rust-toolchain.toml specifies:

• channel = "nightly"
• targets = ["x86_64-unknown-none", "aarch64-unknown-none"]

This is a floating channel pin, not a reproducible toolchain pin. A future rustup resolution can move the compiler even when the repository is unchanged. The current local host resolved to:

• rustc 1.96.0-nightly (2972b5e59 2026-04-03)
• cargo 1.96.0-nightly (888f67534 2026-03-30)
• host target x86_64-unknown-linux-gnu

The Makefile derives HOST_TARGET from rustc -vV (Makefile:12) and uses that for tools/mkmanifest (Makefile:28-29). Cargo aliases in .cargo/config.toml:4-22 hard-code x86_64-unknown-linux-gnu for host tests.

Remaining reproducibility gap: pin the nightly by date or exact toolchain hash, and record required components. Until then, compiler drift can change codegen, linking, lints, and generated bindings without a repository diff.

Cargo Dependencies

The root workspace members are capos-config, capos-lib, and kernel (Cargo.toml:1-4). init/, demos/, tools/mkmanifest/, and fuzz/ are standalone workspaces with their own lockfiles.

Important direct dependencies and current root-lock resolutions:

Standalone lockfile drift observed during this inventory:

Cargo lockfiles pin exact crate versions and crates.io checksums, so ordinary crate upgrades are review-visible through lockfile diffs. They do not, by themselves, define whether a dependency is acceptable for kernel/no_std use, whether multiple lockfiles must converge, or whether advisories/licenses block the build.

S.10.3 policy gate:

• deny.toml defines the shared license, advisory, ban, and source baseline.
• make dependency-policy-check runs cargo deny check on the root workspace, init, demos, tools/mkmanifest, capos-rt, and fuzz.
• The same target runs cargo audit --deny warnings on every checked-in lockfile.
• Local packages are marked publish = false so cargo-deny treats them as private, and local path dependencies include version = "0.1.0" so registry wildcard requirements can remain denied.
• CI installs pinned cargo-deny 0.19.4 and cargo-audit 0.22.1 and runs the target.

Remaining dependency-policy gap: decide whether standalone lockfiles may intentionally drift from the root lockfile, especially for capnp and allocator crates used by userspace.

Cap’n Proto Compiler, Runtime, and Generated Bindings

The trusted Cap’n Proto inputs are:

• schema/capos.capnp, the source schema.
• Repo-local pinned capnp, invoked through the capnpc Rust build dependency via CAPOS_CAPNP.
• capnp runtime crate with default-features = false and alloc.
• capnpc codegen crate.
• Generated capos_capnp.rs written to Cargo OUT_DIR.
• Local no_std patching applied after generation.

kernel/build.rs and capos-config/build.rs both run capnpc::CompilerCommand over ../schema/capos.capnp, then read the generated capos_capnp.rs, assert that the expected #![allow(unused_variables)] anchor is present, and inject:

#![allow(unused)]
#![allow(unused_imports)]
fn main() {
use ::alloc::boxed::Box;
use ::alloc::string::ToString;
}

The generated code used by builds is included from OUT_DIR in capos-config/src/lib.rs:10-12 and kernel/src/main.rs:15-18. The expected patched output is checked in as tools/generated/capos_capnp.rs, so schema, compiler, capnpc crate, and patch-output changes must update that baseline and become review-visible as a source diff.

S.10.2 generated-code drift check:

• make generated-code-check runs tools/check-generated-capnp.sh.
• The script invokes the actual Cargo build-script path for capos-config and capos-kernel in an isolated target directory, so it checks the generated artifacts that those crates would include from OUT_DIR.
• The script verifies that each patched file still contains the capnpc anchor plus the local no_std patch imports, compares the two crate outputs byte-for-byte, and then compares both outputs against tools/generated/capos_capnp.rs.
• Any intentional schema/codegen/patch change must update the checked-in baseline in the same review, making generated output drift review-visible.
• make check runs fmt-check plus generated-code-check for a single local or CI entry point.
• Current pinned compiler source is capnproto-c++-1.2.0.tar.gz from https://capnproto.org/ with SHA-256 ed00e44ecbbda5186bc78a41ba64a8dc4a861b5f8d4e822959b0144ae6fd42ef. The checked-in tools/generated/capos_capnp.rs baseline must be regenerated with that compiler when schema or codegen behavior intentionally changes. The current pinned baseline SHA-256 is 224b4ec2296f800bd577b75cfbd679ebb78e7aa2f813ad9893061f4867c9dd3d.

Remaining gaps for S.10.3:

• The no_std patching logic still lives in both build scripts. The baseline and pairwise output comparison catch divergent results, but a future cleanup could move the patch helper into shared source to reduce duplication.

Cargo Build Scripts

Build scripts currently do these trusted operations:

The linker build scripts derive CARGO_MANIFEST_DIR from Cargo and only emit link arguments plus rerun directives. The capnp build scripts read and rewrite generated code under OUT_DIR. None of these scripts fetch network resources.

S.10.2 coverage: make generated-code-check exercises both capnp build scripts through Cargo, validates the patched generated files, and fails if the two crate outputs drift apart or no longer match the checked-in generated baseline.

Manifest, Embedded Binaries, and Downloaded Artifacts

system.cue declares named binaries and services. Makefile:54-55 builds manifest.bin by running tools/mkmanifest on the host. mkmanifest runs:

1. Resolve the clone-shared pinned CUE compiler from git state, reject missing or mismatched CAPOS_CUE, check cue version v0.16.0, then run cue export system.cue --out json (tools/mkmanifest/src/main.rs:65-128).
2. JSON-to-CueValue conversion and manifest validation (tools/mkmanifest/src/main.rs:13-23).
3. Binary embedding from relative paths (tools/mkmanifest/src/lib.rs:135-180).
4. Binary-reference validation and Cap’n Proto serialization (tools/mkmanifest/src/main.rs:37-49).

Path handling rejects absolute paths, parent traversal, non-normal components, and canonicalized paths that escape the manifest directory (tools/mkmanifest/src/lib.rs:182-217). The generated manifest.bin is copied into the ISO as /boot/manifest.bin (Makefile:117) and loaded by Limine via limine.conf:5.

Downloaded or generated artifacts in the current build:

Remaining gaps for S.10.2/S.10.3:

• Decide whether CI should record or compare hashes for manifest.bin, embedded ELF payloads, or the final ISO for reproducible-build tracking.
• Pin or record xorriso, qemu-system-x86_64, OVMF firmware, and other host tools used by build and boot verification with the same strictness as capnp and cue.
• Decide whether CI should record the pinned cue export JSON or final manifest.bin bytes if manifest reproducibility becomes release-critical.

Host Tools

Current local host versions observed during this inventory:

These are environment observations, not repository pins. make run-uefi also trusts /usr/share/edk2/x64/OVMF.4m.fd (Makefile:82-83) without a checksum.

Remaining gap for S.10.3: decide the minimum supported host tool versions and whether they are enforced by CI, a container/devshell, or explicit preflight checks.

Verification Used for This Inventory

This was a documentation-only inventory. Code tests and QEMU boot were not run because no source, build, runtime, or generated-code behavior was changed.

Scoped read-only verification commands used:

• git status --short --branch
• rg -n "S\\.10|trusted|supply|Limine|limine|capnp|capnpc|QEMU|qemu|download|curl|git clone|wget|build\\.rs|rust-toolchain|Cargo\\.lock" ...
• rg --files
• cargo metadata --locked --format-version 1 --no-deps
• rg -n '^name = |^version = |^checksum = ' Cargo.lock init/Cargo.lock demos/Cargo.lock tools/mkmanifest/Cargo.lock fuzz/Cargo.lock
• command -v rustc cargo capnp cue qemu-system-x86_64 xorriso sha256sum git make
• rustc -Vv, cargo -V, capnp --version, cue version, qemu-system-x86_64 --version, xorriso -version, make --version, git --version

DMA Isolation Design

S.11 gates PCI, virtio, and later userspace device-driver work on an explicit DMA authority model. The immediate goal is narrow: let the kernel bring up a QEMU virtio-net smoke without creating a user-visible raw physical-memory escape hatch.

Short-Term Decision

Use kernel-owned bounce buffers for the first in-kernel QEMU virtio-net smoke.

The kernel allocates DMA-capable pages from its own frame allocator, owns the virtqueue descriptor tables and packet buffers, programs the device with the corresponding physical addresses, and copies packet payloads between those buffers and the networking stack. No userspace process receives a DMA buffer capability, a physical address, a virtqueue pointer, or a BAR mapping for this smoke.

This is deliberately conservative:

• It works before ACPI/DMAR or AMD-Vi parsing, IOMMU page-table management, MSI/MSI-X routing, and userspace driver lifecycle supervision exist.
• It keeps all physical-address programming inside the kernel, where the same code that allocates the frames also bounds the descriptors that reference them.
• It does not make the current FrameAllocator capability part of the DMA path. FrameAllocator can expose raw frames today and is already tracked in REVIEW_FINDINGS.md; DMA must not build new untrusted-driver semantics on that interface.
• It gives the smoke a disposable implementation path. When NIC or block drivers move to userspace, bounce-buffer authority becomes a typed DMAPool object instead of an ad hoc physical-address grant.

An IOMMU-backed DMA-domain model remains the target for direct device access from mutually untrusted userspace drivers, but it is not a prerequisite for the first QEMU smoke. Without an IOMMU, a malicious bus-mastering device can still DMA to arbitrary RAM at the hardware level; the short-term smoke assumes QEMU-provided virtio hardware and protects against confused or untrusted userspace, not hostile hardware.

Authority Model

Device authority is split into three independent capabilities:

• DMAPool: authority to allocate, expose, and revoke device-visible memory within a kernel-owned physical range or IOMMU domain.
• DeviceMmio: authority to map and access one device’s register windows.
• Interrupt: authority to wait for and acknowledge one interrupt source.

Holding one of these capabilities never implies the others. A driver needs all three for a normal device, but the kernel and init can grant, revoke, and audit them separately.

DMAPool Invariants

DMAPool is the only future userspace-facing authority that may cause a device-visible DMA address to exist.

• Authority: A holder may allocate buffers only from the pool object it was granted. It may not request arbitrary physical frames, import caller virtual memory by address, or derive another pool.
• Physical range: Every exported device address must resolve to pages owned by the pool. The kernel records the allowed host-physical page set and validates every descriptor mapping against that set before a device can use it. If an IOMMU domain backs the pool, the exported address is an IOVA, not raw host physical memory.
• Ownership: Each DMA buffer has one pool owner, one device-domain owner, and explicit CPU mappings. Sharing a buffer with another process requires a later typed memory-object transfer; copying packet data is the default until that object exists.
• No raw grants: Userspace never receives an unrestricted host-physical address. A driver may receive an opaque DMA handle or an IOVA meaningful only to its DMAPool/device domain. It cannot turn that value into access to unrelated RAM.
• Bounds: Buffer length, alignment, segment count, and queue depth are bounded by the pool. Descriptor chains that point outside an allocated buffer, wrap arithmetic, exceed device limits, or reference freed buffers fail closed before doorbell writes.
• Revocation: Revoking the pool first quiesces the device path using it, prevents new descriptors, waits for or cancels in-flight descriptors, then removes IOMMU mappings or invalidates bounce-buffer handles before freeing pages.
• Reset: If in-flight DMA cannot be proven stopped, revocation escalates to device reset through the owning device object before pages are reused.
• Residual state: Pages returned from a pool are zeroed or otherwise scrubbed before reuse by a different owner. Receive buffers are treated as device-written untrusted input until validated by the driver or stack.

For the in-kernel QEMU smoke, the kernel is the only DMAPool holder. The same invariants apply internally even though no userspace capability object is exposed yet.

DeviceMmio Invariants

DeviceMmio is register authority, not memory authority.

• Authority: A holder may map only BARs or subranges recorded in the claimed device object. It may not map PCI config space globally, another function’s BAR, RAM, ROM, or synthetic kernel pages.
• Physical range: Each mapping is bounded to the BAR’s decoded physical range, page-rounded by the kernel, and tagged as device memory with cache attributes appropriate for MMIO. Partial BAR grants must preserve page-level isolation; otherwise the grant must cover the whole page-aligned register window and be treated as that much authority.
• Ownership: At most one mutable driver owner controls a device function’s MMIO at a time. Management capabilities may inspect topology, but register writes require the claimed DeviceMmio object.
• No DMA implication: Mapping registers does not grant any DMA buffer, frame allocation, interrupt, or config-space authority. Doorbell writes are accepted only as effects of register access; descriptor validity is enforced by DMAPool before queues are made visible to the device.
• Revocation: Revocation unmaps the driver’s register pages, marks the device object unavailable for new calls, and invalidates outstanding MMIO handles. Stale mappings or calls fail closed.
• Reset: Revoking the final mutable DeviceMmio owner resets or disables the device unless a higher-level device manager explicitly transfers ownership without exposing it to an untrusted holder.

Interrupt Invariants

Interrupt is event authority for one routed source.

• Authority: A holder may wait for, mask/unmask where supported, and acknowledge only its assigned vector, line, or MSI/MSI-X table entry. It may not reprogram arbitrary interrupt controllers or claim another source.
• Ownership: Each interrupt source has one delivery owner at a time. Shared legacy lines must be represented as a kernel-demultiplexed object with explicit device membership, not as ambient access to the whole line.
• Range: The capability records the hardware source, vector, trigger mode, polarity, and target CPU/routing state. User-visible operations are checked against that record.
• Revocation: Revocation masks or detaches the source, drains pending notifications for the old holder, invalidates waiters, and prevents stale acknowledgements from affecting a new owner.
• Reset: If the source cannot be detached cleanly, the owning device is reset or disabled before the interrupt is reassigned.
• No MMIO or DMA implication: Interrupt delivery does not grant register access, DMA buffers, or packet memory.

Revocation Ordering

Device revocation must follow a fixed order:

1. Stop new submissions by invalidating the driver’s user-visible handles.
2. Revoke MMIO write authority by write-blocking or unmapping BAR pages, or by disabling the device before any DMA teardown starts.
3. Mask or detach interrupts.
4. Quiesce virtqueues or device command queues.
5. Reset or disable the device if in-flight DMA cannot be accounted for.
6. Remove IOMMU mappings or invalidate bounce-buffer handles.
7. Scrub and free DMA pages.

This order prevents a stale driver from racing revocation with doorbell writes, interrupt acknowledgement, or descriptor reuse. Logical handle invalidation is not sufficient while a BAR remains mapped; register-write authority must be removed or the device must be disabled before descriptor or DMA-buffer ownership is reclaimed.

Future Userspace-Driver Transition Criteria

Moving NIC or block drivers out of the kernel is gated by S.11.2. The gate is only open when all rows below are implemented and demonstrated.

For each row, the transition requires an owner, implementation notes, and a CI-backed verification path. Until all rows pass, Phase 4.2 NIC/block drivers remain in-kernel for functionality, and only kernel-mapped bounce-buffer mode is allowed for prototype DMA.

S.11.2 Decision Record

S.11.2 is not complete until the kernel has a dedicated device manager object model that can produce, transfer, and revoke DMAPool, DeviceMmio, and Interrupt in a single ownership transaction for a driver process.

Current status: transition remains blocked pending implementation of the conditions above.

S.9 Design: Authority Graph and Resource Accounting for Transfer

This document defines the concrete S.9 design gate for:

• WORKPLAN 3.6 capability transfer (xfer_cap_count, copy/move, rollback)
• WORKPLAN 5.2 ProcessSpawner prerequisites (spawn quotas and result-cap insertion)

S.9 is complete when this design contract is concrete enough to guide implementation. The invariants and acceptance criteria below are implementation gates for later work in 3.6/5.2/S.8/S.12, not requirements for declaring the S.9 design artifact complete.

1. Authority Graph Model

Authority is modeled as a directed multigraph:

• Nodes:
  • Process(Pid)
  • Object(ObjectId) (kernel object identity, independent of per-process CapId)
• Edges:
  • Hold(Pid -> ObjectId) with metadata:
    • cap_id (table-local handle)
    • interface_id
    • badge
    • transfer_mode (copy, move, non_transferable)
    • origin (kernel, spawn_grant, ipc_transfer, result_cap)

Security invariant A1: all authority is represented by Hold edges; no operation can create object authority outside this graph.

Security invariant A2: each process mutates only its own CapTable edges except through explicit transfer/spawn transactions validated by the kernel.

Security invariant A3: for every live Hold edge there is exactly one cap_id slot in one process table referencing the object generation.

2. Per-Process Resource Ledger and Quotas

Each process owns a kernel-maintained ResourceLedger with hard limits. Enforcement is fail-closed at reservation time (before side effects).

ResourceLedger {
  cap_slots_used / cap_slots_max
  endpoint_queue_used / endpoint_queue_max
  outstanding_calls_used / outstanding_calls_max
  scratch_bytes_used / scratch_bytes_max
  frame_grant_pages_used / frame_grant_pages_max
  log_bytes_window_used / log_bytes_per_window (token bucket)
  cpu_time_us_window_used / cpu_budget_us_per_window (token bucket)
}

Initial quota profile for Stage 6/5.2 bring-up (tunable by kernel config):

• cap_slots_max: 256
• endpoint_queue_max: 128 messages
• outstanding_calls_max: 64
• scratch_bytes_max: 256 KiB
• frame_grant_pages_max: 4096 pages (16 MiB at 4 KiB pages)
• log_bytes_per_window: 64 KiB/sec with 256 KiB burst
• cpu_budget_us_per_window: 10,000 us per 100,000 us window

Security invariant Q1: no counter may exceed its max.

Security invariant Q2: every resource reservation has a matched release on all success, error, timeout, process-exit, and rollback paths.

Security invariant Q3: quota checks for transfer/spawn happen before mutating sender or receiver capability state.

3. Diagnostic Rate Limiting and Aggregation

Repeated invalid ring/cap submissions are aggregated per process and error key.

• Key: (pid, error_code, opcode, cap_id_bucket)
• Buckets:
  • cap_id_bucket = exact cap id for stale/invalid cap failures
  • cap_id_bucket = 0 for structural ring errors
• Per-key token bucket: allow first N=4 emissions/sec, then suppress.
• Suppressed counts are flushed once per second as one summary line:
  • pid=X invalid submissions suppressed=Y last_err=...

Security invariant D1: invalid submission floods cannot consume unbounded serial bandwidth or scheduler time in log formatting.

Security invariant D2: suppression never hides first-observation diagnostics for a new (pid,error,opcode,cap bucket) key.

4. Transfer and Rollback Semantics

Transfers (xfer_cap_count > 0) use a kernel transfer transaction (TransferTxn) scoped to a single SQE dispatch. The current ring ABI does not provide kernel-owned SQE sequence numbers or a durable transaction table, so userspace replay of a copy-transfer SQE is repeatable: each replay is treated as a new copy grant. Move-transfer replay fails closed after the source slot is removed or reserved by the first successful dispatch.

Future exactly-once replay suppression requires transaction identity scoped to (sender_pid, call_id, sqe_seq) and a monotonic transfer epoch. Until that exists, exactly-once claims apply only within one dispatch attempt, not across malicious rewrites of shared SQ ring indexes.

Phases:

1. Prepare:
   • validate SQE transport fields and xfer_cap_count
   • validate sender ownership/generation/transferability for each exported cap
   • reserve receiver quota (cap_slots, outstanding_calls, scratch if needed)
   • pin sender entries in txn state (no sender table mutation yet)
2. Commit:
   • insert destination edges exactly once
   • for copy: increment object refcount/export ref
   • for move: remove sender slot only after destination insertion succeeds
   • publish completion/result
3. Finalize:
   • release transient reservations
   • mark txn terminal (committed or aborted)

On any error before Commit, rollback is full:

• receiver inserts are not visible
• sender slots/refcounts unchanged
• reservations released
• CQE returns transfer failure (CAP_ERR_TRANSFER_ABORTED / subtype)

On error during Commit, kernel executes compensating rollback to preserve exactly-once visibility: either all inserts are visible with matching sender state transition, or none are visible.

Security invariant T1: each transfer descriptor is applied at most once within a single SQE dispatch attempt.

Security invariant T2: move transfer is atomic from observer perspective; no state exists where both sender and receiver lose authority due to partial apply.

Security invariant T3: copy-transfer SQE replay is explicitly repeatable until kernel-owned transaction identity exists. Move-transfer replay fails closed after source removal or source reservation.

Security invariant T4: CAP_OP_RELEASE removes one local hold edge only from the caller table and decrements remote export refs exactly once.

5. Integration with 3.6 Capability Transfer

3.6 implementation must consume this design directly:

• CALL and RETURN validate all currently-reserved transfer fields fail-closed when unsupported.
• xfer_cap_count path is wired through TransferTxn (no ad hoc direct inserts).
• Badge propagation is explicit in transfer descriptors and copied into destination edge metadata.
• CAP_OP_RELEASE uses the same authority ledger and refcount bookkeeping.

3.6 acceptance criteria:

1. Copy transfer produces one new receiver edge and retains sender edge.
2. Move transfer produces one new receiver edge and deletes sender edge atomically.
3. Any transfer failure leaves sender and receiver CapTables unchanged.
4. Copy replay is an explicit repeatable-grant policy until a kernel-owned transaction identity is added; move replay fails closed after source removal or reservation.
5. CAP_OP_RELEASE on stale/non-owned cap fails closed without mutating other process tables.

6. Integration with 5.2 ProcessSpawner Prerequisites

5.2 must use the same accounting and transfer machinery:

• spawn() preflights child quotas (cap_slots, outstanding_calls, scratch, frame_grant_pages, endpoint queue baseline) before mapping child memory or scheduling.
• Parent-provided CapGrant entries are inserted via the same transfer transaction semantics (copy for initial grants in 5.2.2).
• Returned ProcessHandle is inserted through the standard result-cap insertion path and accounted as a normal cap slot.
• Child setup rollback must unwind:
  • address space mappings
  • ring page
  • CapSet page
  • kernel stack
  • allocated frames
  • provisional capability edges/reservations

5.2 acceptance criteria:

1. Spawn failure at any step leaves no child-visible process and no leaked ledger usage.
2. Successful spawn accounts all child bootstrap resources within quotas.
3. Parent and child cap-table accounting remains balanced under repeated spawn/exit cycles.
4. ProcessHandle.wait and exit cleanup release outstanding-call/scratch/frame usage deterministically.

7. Implementation Notes for Verification Tracks

This design unblocks:

• S.8 hostile-input tests for quota and invalid-transfer failures.
• S.12 Kani bounds refresh for ledger and transfer invariants.
• Target 12 in docs/proposals/security-and-verification-proposal.md with explicit allocator hooks and fail-closed exhaustion behavior.

Proposal Index

This page classifies proposal documents by current role so readers do not confuse implemented behavior, active design direction, future architecture, and rejected alternatives.

Active or Near-Term

Future Architecture

Rejected or Superseded

Maintenance

When a proposal becomes implemented, rejected, or stale, update this index in the same change that changes the proposal or corresponding implementation. Long proposal files may describe target behavior; this index is the first status checkpoint before a reader opens those documents.

Proposal: Capability-Based Service Architecture

How capOS processes receive authority, compose into services, and expose layered capabilities — without a service manager daemon.

Problem

Traditional OSes grant processes ambient authority (file system, network, IPC namespaces) and then restrict it via sandboxing (seccomp, namespaces, AppArmor). Service managers like systemd handle dependencies, lifecycle, and resource limits through a central daemon with a massive configuration surface.

capOS inverts this: processes start with zero authority and receive only the capabilities they need. The capability graph implicitly encodes service dependencies, resource limits, and access control. No central daemon required.

Process Startup Model

A process receives its entire authority as a set of named capabilities at spawn time. There is no ambient authority to fall back on — if a capability wasn’t granted, the operation is impossible.

The child process sees its granted capabilities by name. It cannot discover or request capabilities it wasn’t given.

Capability Layering

Each process consumes lower-level capabilities and exports higher-level ones. Authority narrows at every layer:

Kernel
  │
  ├─ Nic cap (raw frame send/receive for one device)
  ├─ Timer cap (monotonic clock)
  ├─ DeviceMmio cap (one device's BAR regions)
  └─ Interrupt cap (one IRQ line)
       │
       v
NIC Driver Process
  │
  └─ Nic cap ──> Network Stack Process
                   │
                   ├─ TcpSocket cap (one connection)
                   ├─ UdpSocket cap (one socket)
                   └─ NetworkManager cap (create sockets)
                        │
                        v
                   HTTP Service Process
                     │
                     ├─ Fetch cap (any URL)
                     │    │
                     │    v
                     │  Trusted Process (holds Fetch, mints scoped caps)
                     │
                     └─ HttpEndpoint cap (one origin)
                          │
                          v
                     Application Process

The application at the bottom holds an HttpEndpoint cap scoped to a single origin. It cannot make raw TCP connections, send arbitrary packets, or touch any device. The capability is the security policy.

HTTP Capabilities

Two levels of HTTP capability: Fetch (general) and HttpEndpoint (scoped). HttpEndpoint is implemented by a process that holds a Fetch cap and restricts it.

Fetch

Unrestricted HTTP access — equivalent to the browser Fetch API. The holder can make requests to any URL. This is the base capability that HTTP service processes use internally.

interface Fetch {
    # General-purpose HTTP request to any URL.
    request @0 (url :Text, method :Text, headers :List(Header), body :Data)
        -> (status :UInt16, headers :List(Header), body :Data);
}

struct Header {
    name @0 :Text;
    value @1 :Text;
}

Fetch is powerful — granting it is roughly equivalent to granting arbitrary outbound network access. It should only be held by service processes that need to make requests on behalf of others, not by application code directly.

HttpEndpoint

A restricted view of Fetch, scoped to a single origin. The holder can only make requests within the bounds encoded in the capability.

interface HttpEndpoint {
    # Request scoped to this endpoint's origin.
    # Path is relative (e.g., "/v1/users").
    request @0 (method :Text, path :Text, headers :List(Header), body :Data)
        -> (status :UInt16, headers :List(Header), body :Data);
}

Note: same request() signature as Fetch, but path instead of url. The origin is implicit — bound into the capability at mint time.

Attenuation

A process holding Fetch mints HttpEndpoint caps by narrowing authority. The core restriction is always origin — Fetch can reach any URL, HttpEndpoint is locked to one host. Additional constraints (path prefixes, method restrictions, rate limits) are possible but are userspace policy details, not OS-level concerns.

This is the standard object-capability attenuation pattern: same interface, less authority. The application code is identical whether it holds a broad or narrow HttpEndpoint.

Boot and Initialization Sequence

The kernel doesn’t know about services. It boots, creates a handful of kernel-provided caps, and spawns exactly one process: init. Everything else is init’s responsibility.

Current State vs Target State

The implementation is in transition. The default system.cue path still lets the kernel spawn every service listed in the manifest and wire cross-service caps through kernel/src/cap/mod.rs::create_all_service_caps. The system-spawn.cue path now sets config.initExecutesManifest; in that mode the kernel validates the full manifest, boots only the first init service, grants init BootPackage and ProcessSpawner, and lets init resolve the remaining ServiceEntry graph through ProcessSpawner.

The target model removes the kernel-side service graph entirely. The manifest stops being a kernel authority graph and becomes a boot package delivered to init:

• List of embedded binaries (init needs them before any storage service exists; they can’t be fetched from a filesystem that hasn’t started).
• Init’s config blob (CUE-encoded tree; what to spawn, with what attenuations, with what restart policy).
• Kernel boot parameters (memory limits, feature flags) consumed by the kernel itself, not forwarded to init.

The kernel spawns exactly one userspace process (init) with a fixed cap bundle:

• Console — kernel serial wrapper (may be replaced later by a userspace log service, with init retaining a direct console cap for emergency use).
• ProcessSpawner — only init and its delegated supervisors hold this.
• FrameAllocator — physical frame authority for init’s own allocations.
• VirtualMemory — per-process address-space authority for init.
• DeviceManager — enumerate/claim devices; init delegates device-specific slices to drivers.
• Timer — monotonic clock.
• BootPackage — read-only cap exposing the embedded binaries and the config blob.

Everything else — drivers, net-stack, filesystems, supervisors, apps — init spawns at runtime via ProcessSpawner with appropriate attenuation. No manifest ServiceEntry, no cross-service CapRef, no manifest exports.

Pre-Init Boundary After Stage 6

Rule of thumb: no userspace service runs before init. The kernel’s job is primitive cap synthesis and a single-process handoff; init’s job is the whole service graph. Concretely, after Stage 6:

• Stays in kernel pre-init: memory map ingest, frame allocator, heap, paging, GDT/IDT/TSS, serial for kernel diagnostics, scheduler, ring dispatch, kernel-cap CapObject impls, ELF loading for init, boot package measurement (if attested boot is added).
• Stays in manifest: binaries list + init config blob + kernel boot params. Schema-wise, ServiceEntry and CapSource::Service disappear; SystemManifest shrinks to binaries + initConfig + kernelParams.
• Moves to init: service topology, cross-service cap wiring, attenuation, restart policies, dynamic spawn, cap export/import, supervision trees. Anything a service manager would do.
• Moves to init or later services: logging policy, config store, secrets, filesystem mounts, network configuration, device binding.

Edge cases that might look like they want a pre-init service but don’t:

• Early crash / panic handling. Kernel-side panic handler, no service needed.
• Recovery shell. Kernel fallback: if init fails to reach a healthy state within a timeout (e.g. exits immediately, or never issues a liveness SQE), kernel optionally spawns a “recovery” binary from the boot package with the same cap bundle. Still just one userspace process at a time pre-supervisor-loop.
• Attested/measured boot. Kernel hashes binaries in the boot package before handing BootPackage to init. The measurement agent, if any, runs as a normal service spawned by init with a cap to the sealed measurements.
• Early-boot console. Kernel owns serial and exposes Console to init. A userspace log service can layer on top later; it is not pre-init.

Legacy Manifest Fields After Stage 6

ServiceEntry.caps, CapSource::Service, and ServiceEntry.exports are transitional. ProcessSpawner and the generic init-side spawn loop are now in place for system-spawn.cue; the remaining cleanup is to remove these fields from the kernel bootstrap contract:

1. Delete ServiceEntry and CapSource::Service from schema/capos.capnp.
2. Collapse SystemManifest.services into initConfig: CueValue.
3. Remove create_all_service_caps, the two-pass resolver, and the manifest authority-graph validator (validate_manifest_graph).
4. Kernel spawns one process from initConfig.initBinary with the fixed cap bundle described above plus BootPackage.

The re-export restriction added in capos-config::validate_manifest_graph (service A exports cap sourced from B.ep) becomes moot at that point because there are no manifest exports at all. It stays as defensive validation while the transitional schema exists.

Init Binary Embedding

Init is part of the kernel’s bootstrap contract, not a configuration choice: the cap bundle handed to init is a kernel ABI, the _start(ring, pid, …) entry shape is a kernel ABI, and a version-mismatched init is a footgun with no payoff in a single-init research OS. So the init ELF ships inside the kernel binary via include_bytes!, not as a separate manifest entry or Limine module.

Shape:

• init/ stays a standalone crate with its own linker script and code model (user-space base 0x200000, static relocation model, 4 KiB alignment). Not a workspace member; different build flags than the kernel.
• kernel/build.rs drives init/’s build (or depends on the prebuilt artifact at a known path) and emits an include_bytes!("…") into a kernel::boot::INIT_ELF: &[u8] static.
• Kernel bootstrap parses INIT_ELF through the same capos_lib::elf path used for service binaries, creates the init address space via AddressSpace::new_user(), loads segments, populates the cap bundle (including BootPackage), and jumps. No Limine module lookup for init.
• SystemManifest.binaries stops containing an “init” entry. Its binaries list is services-only. BootPackage exposes only what init hands out to children.
• Measured-boot attestation (if added) covers the kernel ELF, which transitively covers init’s bytes. Service binaries are hashed separately by the kernel before handing BootPackage to init.

What this does not change:

• Init still runs in Ring 3 with its own page tables; embedding is byte packaging, not privilege merging.
• Init is still ELF-parsed at boot — the same loader and W^X enforcement apply. The only thing different is where the bytes came from.
• Service binaries (everything spawned after init) stay in the boot package as distinct blobs, exposed to init via BootPackage. They are not linked into the kernel; their lifecycle is independent of the kernel’s.

What option was rejected: fully linking init into the kernel crate (shared compilation unit, shared text). That collapses the kernel/user build boundary, couples linker scripts and code models, and puts init’s panics/UB inside the kernel’s compilation context. The process-isolation boundary survives that arrangement — but the build-time separation that makes the boundary trustworthy does not. include_bytes! preserves the separation; static linking destroys it.

Kernel boot
  │
  ├─ Create kernel caps: Console, Timer, DeviceManager, ProcessSpawner
  │
  └─ Spawn init with all kernel caps
       │
       init process (PID 1)
         │
         ├─ Phase 1: Core services (sequential — each depends on previous)
         │    ├─ DeviceManager.enumerate() → list of devices
         │    ├─ Spawn NIC driver with device-specific caps
         │    ├─ Wait for NIC driver to export Nic cap
         │    ├─ Spawn net-stack with Nic + Timer caps
         │    └─ Wait for net-stack to export NetworkManager cap
         │
         ├─ Phase 2: Higher-level services (can be parallel)
         │    ├─ Spawn http-service with TcpSocket cap from net-stack
         │    ├─ Spawn dns-resolver with UdpSocket cap
         │    └─ ...
         │
         └─ Phase 3: Applications
              ├─ Spawn app-a with HttpEndpoint("api.example.com")
              ├─ Spawn app-b with Fetch cap (trusted)
              └─ ...

The Init Process in Detail

Init is a regular userspace process with privileged caps. It is the only process that holds ProcessSpawner (the right to create new processes) and DeviceManager (the right to enumerate and claim devices). It can delegate subsets of these to child supervisors.

// init/src/main.rs — this IS the system configuration

fn main(caps: CapSet) {
    let spawner = caps.get::<ProcessSpawner>("spawner");
    let devices = caps.get::<DeviceManager>("devices");
    let timer = caps.get::<Timer>("timer");
    let console = caps.get::<Console>("console");

    // === Phase 1: Hardware drivers ===

    // Find the NIC
    let nic_device = devices.find("virtio-net")
        .expect("no network device found");

    // Spawn NIC driver — gets ONLY its device's MMIO + IRQ
    let nic_driver = spawner.spawn(SpawnRequest {
        binary: "/sbin/virtio-net",
        caps: caps![
            "device_mmio" => nic_device.mmio(),
            "interrupt"   => nic_device.interrupt(),
            "log"         => console.clone(),
        ],
        restart: RestartPolicy::Always,
    });

    // The driver exports a Nic cap once initialized
    let nic: Cap<Nic> = nic_driver.exported("nic").wait();

    // === Phase 2: Network stack ===

    let net_stack = spawner.spawn(SpawnRequest {
        binary: "/sbin/net-stack",
        caps: caps![
            "nic"   => nic,
            "timer" => timer.clone(),
            "log"   => console.clone(),
        ],
        restart: RestartPolicy::Always,
    });

    let net_mgr: Cap<NetworkManager> = net_stack.exported("net").wait();

    // === Phase 3: HTTP service ===

    let tcp = net_mgr.create_tcp_pool();

    let http_service = spawner.spawn(SpawnRequest {
        binary: "/sbin/http-service",
        caps: caps![
            "tcp" => tcp,
            "log" => console.clone(),
        ],
        restart: RestartPolicy::Always,
    });

    let fetch: Cap<Fetch> = http_service.exported("fetch").wait();

    // === Phase 4: Applications ===

    // Trusted telemetry agent — gets full Fetch
    spawner.spawn(SpawnRequest {
        binary: "/sbin/telemetry",
        caps: caps![
            "fetch" => fetch.clone(),
            "log"   => console.clone(),
        ],
        restart: RestartPolicy::OnFailure,
    });

    // Sandboxed app — gets scoped HttpEndpoint
    let api_cap = fetch.attenuate(EndpointPolicy {
        origin: "https://api.example.com",
        paths: Some("/v1/users/*"),
        methods: Some(&["GET", "POST"]),
    });

    spawner.spawn(SpawnRequest {
        binary: "/app/my-service",
        caps: caps![
            "api" => api_cap,
            "log" => console.clone(),
        ],
        restart: RestartPolicy::OnFailure,
    });

    // Init stays alive as the root supervisor
    supervisor_loop(&spawner);
}

Key Mechanisms

Cap export. A spawned process can export capabilities back to its parent via the ProcessHandle (see Spawn Mechanism section). This is how the NIC driver makes its Nic cap available to the network stack — init spawns the driver, waits for it to export "nic", then passes that cap to the next process.

Restart policy. Encoded in SpawnRequest, enforced by the supervisor loop in the spawning process. When a child exits unexpectedly:

1. Old caps held by the child are automatically revoked (kernel invalidates the process’s cap table on exit)
2. Supervisor re-spawns with the same SpawnRequest
3. New instance gets fresh caps — same authority, new identity

Dependency ordering. Sequential in code: wait() on exported caps blocks until the dependency is ready. No declarative dependency graph needed — Rust’s control flow is the dependency graph.

Service Taxonomy

Concrete categories of userspace services capOS expects to run. All spawned by init (or a supervisor init delegates to) after Stage 6. None are pre-init.

Hardware Drivers

One process per managed device. Each holds exactly the caps for its own hardware: an DeviceMmio slice, the corresponding Interrupt cap, and optionally a DmaRegion cap carved out of the frame allocator. Exports a typed device cap (Nic, BlockDevice, Framebuffer, Gpu, …). Examples: virtio-net, virtio-blk, NVMe, AHCI, framebuffer/GPU.

Platform Services

• Logger / journal — accepts Log cap writes, forwards to console and/or durable storage. Init and kernel bootstrap use a direct Console cap until the logger is up; afterwards new services get Log caps only.
• Filesystem — one per mounted volume. Consumes a BlockDevice cap, exports Directory / File caps. FAT, ext4, overlay, tmpfs.
• Store — capability-native content-addressed storage backing persistent capability state (storage-and-naming-proposal.md).
• Network stack — userspace TCP/IP (networking-proposal.md). Consumes Nic + Timer, exports NetworkManager, TcpSocket, UdpSocket, TcpListener.
• DNS resolver — consumes a UdpSocket, exports Resolver.
• Config / secrets store — reads the initial config from BootPackage, exposes runtime Config and Secret caps with per-key attenuation.
• Cloud metadata agent — detects IMDS / ConfigDrive / SMBIOS on cloud boot and delivers a ManifestDelta (cloud-metadata-proposal.md).
• Upgrade manager — orchestrates CapRetarget for live service replacement (live-upgrade-proposal.md).
• Capability proxy — makes local caps reachable over the network with capnp-rpc transport (Plan 9’s exportfs equivalent).
• Measurement / attestation agent — consumes sealed kernel hashes from BootPackage, exposes Quote caps for remote attestation.

Supervisors

Per-subsystem restart managers that hold a narrowed ProcessSpawner plus the caps of the subtree they own. If any child crashes, the supervisor tears down and re-spawns the set. Example: net-supervisor owns NIC driver + net-stack + DHCP client.

Application Services

User-facing or user-spawned processes: HTTP servers, API gateways, worker pools, shells, interactive tools. Hold only the narrow caps the supervisor grants (HttpEndpoint for one origin, Directory for one mount, etc.). Human users, service accounts, guests, and anonymous callers are represented by session/profile services that grant scoped cap bundles; they are not kernel subjects or ambient process credentials. See user-identity-and-policy-proposal.md.

What Does Not Become a Service

• Console / serial — stays in the kernel as a CapObject wrapper. Small enough, needed for kernel diagnostics, no benefit from userspace isolation. A userspace log service can layer on top.
• Frame allocator, virtual memory, scheduler, ring dispatch — kernel primitives, exposed as caps but not as services.
• Interrupt delivery, DMA mapping — kernel mechanisms, exposed to drivers as caps.
• Boot measurement — if added, happens in the kernel before BootPackage exists; the measurement agent (userspace) only reports them.

Supervision

Supervision Tree

Init doesn’t have to supervise everything directly. It can delegate:

init (root supervisor)
  ├─ net-supervisor (holds: spawner subset, device caps)
  │    ├─ virtio-net driver
  │    ├─ net-stack
  │    └─ http-service
  └─ app-supervisor (holds: spawner subset, service caps)
       ├─ my-service
       └─ another-app

Each supervisor is a process that holds a ProcessSpawner cap (possibly restricted to specific binaries) and the caps it needs to grant to children. If net-supervisor crashes, init restarts it, and it re-spawns the entire networking subtree.

Supervisor Loop

#![allow(unused)]
fn main() {
fn supervisor_loop(children: &[SpawnRequest], spawner: &ProcessSpawner) {
    let mut handles: Vec<ProcessHandle> = children.iter()
        .map(|req| spawner.spawn(req.clone()))
        .collect();

    loop {
        // Wait for any child to exit
        let (index, exit_code) = wait_any(&handles);
        let req = &children[index];

        match req.restart {
            RestartPolicy::Always => {
                handles[index] = spawner.spawn(req.clone());
            }
            RestartPolicy::OnFailure if exit_code != 0 => {
                handles[index] = spawner.spawn(req.clone());
            }
            _ => {
                // Process exited normally, don't restart
            }
        }
    }
}
}

Socket Activation

systemd pre-creates a socket and passes the fd to the service on first connection. In capOS, the supervisor does the same with caps:

Eager (default): supervisor spawns the child immediately with a TcpListener cap. Child calls accept() and blocks.

Lazy: supervisor holds the TcpListener cap itself. On first incoming connection (or on first accept() from a proxy cap), it spawns the child and transfers the cap. The child code is identical in both cases.

#![allow(unused)]
fn main() {
// Lazy activation — supervisor holds the listener until needed
let listener = net_mgr.create_tcp_listener();
listener.bind([0,0,0,0], 8080);

// This blocks until a connection arrives
let _conn = listener.accept();

// Now spawn the actual service, giving it the listener
spawner.spawn(SpawnRequest {
    binary: "/app/web-server",
    caps: caps!["listener" => listener, "log" => console.clone()],
    restart: RestartPolicy::Always,
});
}

Configuration

See docs/proposals/storage-and-naming-proposal.md for the full storage, naming, and configuration model.

Summary: the system topology is currently defined in a capnp-encoded system manifest baked into the boot image. tools/mkmanifest compiles the human-authored system.cue or system-spawn.cue source into the binary manifest. The transition path already lets init validate and execute that manifest through ProcessSpawner; the default boot path still needs to retire the legacy kernel-side service graph. Runtime configuration lives in a capability-based store service once that service exists.

Comparison with Traditional Approaches

Spawn Mechanism

Spawning is a capability-gated operation. The kernel provides a ProcessSpawner capability — only the holder can create new processes.

Implemented Kernel Slice

The kernel now provides:

1. ProcessSpawner capability — a CapObject impl in kernel/src/cap/process_spawner.rs. Methods:

   • spawn(name, binaryName, grants) -> handleIndex — resolve a boot-package binary, load ELF, create address space (builds on existing elf.rs loader and AddressSpace::new_user() in mem/paging.rs), populate the initial cap table, schedule the process, and return the ProcessHandle through the ring result-cap list
   • the returned ProcessHandle cap lets the parent wait for child exit in the first slice; exported caps and kill semantics are later lifecycle work

2. Initial cap passing — at spawn time, the kernel copies permitted parent cap references into the child’s cap table or mints authorized child-local kernel caps. Raw grants preserve the source badge, endpoint-client grants can mint a requested badge from an owner endpoint, and child-local FrameAllocator/VirtualMemory grants are created for the child’s address space. The parent’s references are unaffected.

3. Cap export — future lifecycle work will let a child register a cap by name in its ProcessHandle, making it available to the parent (or anyone holding the handle). This is the mechanism behind nic_driver.exported("nic").wait() once exported-cap lookup is added.

Schema

interface ProcessSpawner {
    spawn @0 (name :Text, binaryName :Text, grants :List(CapGrant)) -> (handleIndex :UInt16);
}

struct CapGrant {
    name @0 :Text;
    capId @1 :UInt32;
    interfaceId @2 :UInt64;
    mode @3 :CapGrantMode;
    badge @4 :UInt64;
    source @5 :CapGrantSource;
}

struct CapGrantSource {
    union {
        capability @0 :Void;
        kernel @1 :KernelCapSource;
    }
}

enum CapGrantMode {
    raw @0;
    clientEndpoint @1;
}

interface ProcessHandle {
    wait @0 () -> (exitCode :Int64);
}

Note on capability passing: Capabilities are referenced by cap table slot IDs (UInt32), not by Cap’n Proto’s native capability table mechanism. spawn() returns the ProcessHandle through the ring result-cap list; handleIndex identifies that transferred cap in the completion. The first slice passes a boot-package binaryName instead of raw ELF bytes so the request stays within the bounded ring parameter buffer. kill, post-spawn grants, and exported-cap lookup remain future lifecycle work until their teardown and authority semantics are implemented. capOS uses manual capnp dispatch (CapObject trait with raw message bytes, not capnp-rpc), so cap references are plain integers and typed result caps use the ring transfer-result metadata. See userspace-binaries-proposal.md Part 7 for the surrounding userspace bootstrap schema context.

Relationship to Existing Code

The current kernel has these pieces in place:

• ELF loading (kernel/src/elf.rs) — parses PT_LOAD segments, validates alignment, and feeds the reusable spawn primitive behind ProcessSpawner.
• Address space creation (kernel/src/mem/paging.rs) — AddressSpace::new_user() creates isolated page tables with the kernel mapped in the upper half.
• Cap table (kernel/src/cap/table.rs) — CapTable with insert(), get(), remove(), transfer preflight, provisional insert, commit, and rollback helpers. Each Process owns one local table.
• Process struct and scheduler (kernel/src/process.rs, kernel/src/sched.rs) — a process table plus round-robin run queue are in place for both legacy manifest-spawned services and init-spawned children.

Generic capability transfer/release and the reusable ProcessSpawner lifecycle path are complete enough for init-owned service startup. Remaining lifecycle gaps are kill, post-spawn grants, runtime exported-cap lookup, restart supervision, and retiring the default kernel-side service graph.

Prerequisites

This proposal describes the target architecture. Individual pieces (like Fetch/HttpEndpoint) are additive — they’re userspace processes that compose existing caps into higher-level ones. No kernel changes needed beyond Stages 4-6.

First Step After Transfer and ProcessSpawner — done 2026-04-22

The minimal demonstration of this architecture landed together with capability transfer and ProcessSpawner:

1. ProcessSpawner cap in kernel/src/cap/process_spawner.rs wraps ELF loading and address-space creation behind a typed capability.
2. Init spawns children — make run-spawn boots a manifest with config.initExecutesManifest set; the kernel boots only init, then init spawns endpoint-roundtrip, ipc-server, and ipc-client from manifest entries through ProcessSpawner, grants endpoint owner/client facets, and waits on each ProcessHandle.
3. Cross-process cap invocation — spawned client invokes the server’s Endpoint cap, server replies, both print to console.

This exercises: spawn cap, initial cap passing, manifest-declared export recording, cross-process cap invocation, hostile-input rejection, and per-process resource exhaustion paths. Generic manifest execution exists for the system-spawn.cue transition path. Making it the default make run path and deleting the legacy kernel resolver is the selected follow-on milestone in WORKPLAN.md.

Open Questions

1. Cap revocation. If a service is restarted, its old caps should be invalidated. Planned approach (from research): epoch-based revocation (EROS-inspired, O(1) invalidate) plus generation counters on CapId (Zircon-inspired, stale reference detection). See ROADMAP.md Stages 5-6.

2. Cap discovery. How does a process learn what caps it was given? Resolved: name→(cap_id, interface_id) mapping passed at spawn via a well-known page (CapSet). See userspace-binaries-proposal.md Part 2. cap_id is the authority-bearing table handle. interface_id is the transported capnp TYPE_ID used by typed clients to check that the handle speaks the expected interface.

3. Lazy spawning. Should the init process start everything eagerly, or should caps be backed by lazy proxies that spawn the backing service on first invocation?

4. Cap persistence. If the system reboots, should the cap graph be reconstructable from saved state? Or is it always rebuilt from init code?

5. Delegation depth. Can an application further delegate its HttpEndpoint cap to a subprocess? If so, the HTTP gateway needs to support fan-out. If not, how is this restriction enforced?

Proposal: Storage, Naming, and Persistence

What replaces the filesystem in a capability OS where Cap’n Proto is the universal wire format.

The Problem with Filesystems

In Unix, the filesystem is the universal namespace. Everything is a path: /dev/sda, /etc/config, /proc/self/fd/3, /run/dbus/system_bus_socket. Paths are ambient authority — any process can open /etc/passwd if the permission bits allow. The filesystem conflates naming, access control, persistence, and device abstraction into one mechanism.

capOS has capabilities instead of paths. Access control is structural (you can only use what you were granted), not advisory (permission bits checked at open time). This means:

• No global namespace needed — each process sees only its granted caps
• No path-based access control — the cap IS the access
• No distinction between “file”, “device”, “socket” — everything is a typed capability interface

A traditional VFS would reintroduce ambient authority through the back door. Instead, capOS needs a storage and naming model native to capabilities and Cap’n Proto.

Core Insight: Cap’n Proto Everywhere

Cap’n Proto is already used in capOS for:

• Interface definitions — .capnp schemas define capability contracts
• IPC messages — capability invocations are capnp messages
• Serialization — capnp wire format crosses process boundaries

If we extend this to storage, then:

• Stored objects are capnp messages
• Configuration is capnp structs
• Binary images are capnp-wrapped blobs
• The boot manifest is a capnp message describing the initial capability graph

No format conversion anywhere. The same tools (schema compiler, serializer, validator) work for IPC, storage, config, and network transfer.

Architecture

Three Layers

Target architecture after the manifest executor and process-spawner work:

Boot Image (read-only, baked into ISO)
  │
  │  capnp-encoded manifest + binaries
  │
  v
Kernel (creates initial caps from manifest)
  │
  │  grants caps to init
  │
  v
Init (builds live capability graph)
  │
  ├──> Filesystem services (FAT, ext4 — wrap BlockDevice as Directory/File)
  │
  ├──> Store service (capability-native content-addressed storage)
  │      backed by: virtio-blk, RAM, or network
  │
  └──> All other services (receive Directory, Store, or Namespace caps)

Layer 1: Boot Image

The boot image (ISO/disk) contains a capnp-encoded system manifest loaded as a Limine module alongside the kernel. The manifest describes:

struct SystemManifest {
    # Binaries available at boot, keyed by name
    binaries @0 :List(NamedBlob);
    # Initial service graph — what to spawn and with what caps
    services @1 :List(ServiceEntry);
    # Static configuration values as an evaluated CUE-style tree
    config @2 :CueValue;
}

struct NamedBlob {
    name @0 :Text;
    data @1 :Data;
}

struct ServiceEntry {
    name @0 :Text;
    binary @1 :Text;          # references a NamedBlob by name
    caps @2 :List(CapRef);    # what caps this service receives
    restart @3 :RestartPolicy;
    exports @4 :List(Text);   # cap names this service is expected to export
}

struct CapRef {
    name @0 :Text;                 # local name in the child's cap table
    expectedInterfaceId @1 :UInt64; # generated .capnp TYPE_ID for validation
    union {
        unset @2 :Void;             # invalid; keeps omitted sources fail-closed
        kernel @3 :KernelCapSource;
        service @4 :ServiceCapSource;
    }
}

enum KernelCapSource {
    console @0;
    endpoint @1;
    frameAllocator @2;
    virtualMemory @3;
}

struct ServiceCapSource {
    service @0 :Text;
    export @1 :Text;
}

enum RestartPolicy {
    never @0;
    onFailure @1;
    always @2;
}

struct CueValue {
    union {
        null @0 :Void;
        boolean @1 :Bool;
        intValue @2 :Int64;
        uintValue @3 :UInt64;
        text @4 :Text;
        bytes @5 :Data;
        list @6 :List(CueValue);
        fields @7 :List(CueField);
    }
}

struct CueField {
    name @0 :Text;
    value @1 :CueValue;
}

Capability source identity is already structured in the bootstrap manifest, so source selection does not depend on parsing authority strings:

struct CapRef {
    name @0 :Text;                 # local name in the child's CapSet
    expectedInterfaceId @1 :UInt64; # generated .capnp TYPE_ID for validation
    union {
        unset @2 :Void;             # invalid; keeps omitted sources fail-closed
        kernel @3 :KernelCapSource;
        service @4 :ServiceCapSource;
    }
}

enum KernelCapSource {
    console @0;
    endpoint @1;
    frameAllocator @2;
    virtualMemory @3;
}

struct ServiceCapSource {
    service @0 :Text;
    export @1 :Text;
}

KernelCapSource / ServiceCapSource select the authority to grant. The expectedInterfaceId field carries the generated Cap’n Proto interface TYPE_ID and only checks that the granted object speaks the expected schema. It cannot replace source identity: many different objects may expose the same interface while representing different authority.

The build system (Makefile) generates this manifest from a human-authored description and packs it into the ISO as manifest.bin. Current code embeds every SystemManifest.binaries entry into that manifest as NamedBlob data, including the release-built init and smoke-demo ELFs. Exposing the manifest to init as a read-only BootPackage capability (rather than letting the kernel parse and act on the service graph) is the selected follow-on milestone.

Using a CueValue tree instead of AnyPointer keeps the manifest directly decodable in no_std userspace without depending on Cap’n Proto reflection.

Transitional Schema Note

ServiceEntry, CapSource::Service, and ServiceEntry.exports are transitional. ProcessSpawner and copy/move cap transfer are implemented (2026-04-22), but the default make run boot path still has the kernel spawn every declared service and wire cross-service caps. Once init owns generic manifest execution, the manifest loses the service graph entirely:

struct SystemManifest {
    # Binaries available at boot, keyed by name
    binaries @0 :List(NamedBlob);
    # Init's config blob (replaces the service graph)
    initConfig @1 :CueValue;
    # Kernel boot parameters (memory limits, feature flags)
    kernelParams @2 :CueValue;
}

ServiceEntry / CapRef disappear from the schema and become plain CUE fields inside initConfig. Init reads them at runtime and calls ProcessSpawner directly. validate_manifest_graph, validate_bootstrap_cap_sources, and create_all_service_caps all retire once that happens. See docs/proposals/service-architecture-proposal.md — “Legacy Manifest Fields After Stage 6” for the deprecation plan.

Layer 2: Kernel Bootstrap

Target design for the kernel’s boot role:

1. Parse the system manifest (read-only capnp message from Limine module).
2. Hash the embedded binaries for optional measured-boot attestation.
3. Create kernel-provided capabilities: Console, Timer, DeviceManager, ProcessSpawner, FrameAllocator, VirtualMemory (per-process), and a read-only BootPackage cap exposing SystemManifest.binaries and initConfig.
4. Spawn init — exactly one userspace process — with that cap bundle.

Current code has not reached this split for the default boot: the kernel still parses the manifest and creates one process per ServiceEntry. The transition path exists in system-spawn.cue: it sets config.initExecutesManifest, the kernel validates the full manifest but boots only init, and init spawns endpoint, IPC, VirtualMemory, and FrameAllocator cleanup demo children through ProcessSpawner. Retiring the legacy kernel resolver for default make run is the selected follow-on milestone tracked in WORKPLAN.md.

Layer 3: Init and the Live Capability Graph

Target init reads initConfig from the BootPackage cap and executes it:

fn main(caps: CapSet) {
    let spawner = caps.get::<ProcessSpawner>("spawner");
    let boot = caps.get::<BootPackage>("boot");
    let config = boot.init_config()?;  // CueValue

    // Walk service entries from the config and spawn in dependency order
    for entry in config.field("services")?.iter()? {
        let binary = boot.binary(entry.field("binary")?.as_str()?)?;
        let granted = resolve_caps(entry.field("caps")?, &running_services, &caps);
        let handle = spawner.spawn(binary, granted, entry.field("restart")?.into())?;
        running_services.insert(entry.field("name")?.as_str()?.into(), handle);
    }

    supervisor_loop(&running_services);
}

In this target model, init is a generic manifest executor rather than a hardcoded service graph. The system topology is defined in the boot package’s initConfig, not in init’s source code. Changing what services run means rebuilding the boot image with a different config blob, not recompiling init. Manifest graph resolution stops being a kernel concern.

The current transition still uses SystemManifest.services as the service graph instead of initConfig; init reads the BootPackage manifest, validates a metadata-only ManifestBootstrapPlan, resolves kernel and service cap sources, records exported caps, spawns children in manifest order, and waits for their ProcessHandles.

Two Storage Models

capOS supports two complementary storage models, both exposed as typed capabilities:

Filesystem Capabilities (Directory, File)

For accessing traditional block-based filesystems (FAT, ext4, ISO9660) and for POSIX compatibility. A filesystem service wraps a BlockDevice and exports Directory/File capabilities.

BlockDevice (raw sectors)
    │
    └──> Filesystem service (FAT, ext4, ...)
              │
              ├──> Directory caps (namespace over files)
              └──> File caps (read/write byte streams)

This model maps naturally to USB flash drives, NVMe partitions, and network-mounted filesystems. The open() and sub() operations return new capabilities via IPC cap transfer (see “IPC and Capability Transfer” below).

Capability-Native Store (Store, Namespace)

For capOS-native data: configuration, service state, content-addressed object storage. A store service wraps a BlockDevice and exports Store/Namespace capabilities.

BlockDevice (raw sectors)
    │
    └──> Store service
              │
              ├──> Store cap (content-addressed put/get)
              └──> Namespace caps (mutable name→hash mappings)

Content-addressing provides automatic deduplication, verifiable integrity, and immutable references. Namespaces add mutable bindings on top.

Bridging the Two Models

The models are composable. An adapter service can bridge between them:

• FsStore adapter: exposes a Directory tree as a content-addressed Store (hash each file’s contents, directory listings become capnp-encoded objects)
• StoreFS adapter: exposes Store/Namespace as a Directory tree (each name maps to a File whose contents are the stored object)
• Import/export: a utility service reads files from a Directory and stores them in a Store, or materializes Store objects as files in a Directory

In both cases the adapter is a userspace service holding caps to both subsystems. No kernel mechanism needed — just capability composition.

File I/O Interfaces

Directory, File, Store, and Namespace caps may be scoped to a user session, guest profile, anonymous request, or service identity, but the cap remains the authority. POSIX ownership metadata is compatibility data inside these services, not a system-wide authorization channel. See user-identity-and-policy-proposal.md.

BlockDevice

Raw sector access, served by device drivers (virtio-blk, NVMe, USB mass storage). The driver receives hardware capabilities (MMIO, IRQ, FrameAllocator for DMA) and exports a BlockDevice cap.

interface BlockDevice {
    readBlocks  @0 (startLba :UInt64, count :UInt32) -> (data :Data);
    writeBlocks @1 (startLba :UInt64, count :UInt32, data :Data) -> ();
    info        @2 () -> (blockSize :UInt32, blockCount :UInt64, readOnly :Bool);
    flush       @3 () -> ();
}

For bulk transfers, readBlocks/writeBlocks accept a SharedBuffer capability instead of inline Data (see “Shared Memory for Bulk Data” below). The inline-Data variants work for metadata reads and small operations; the SharedBuffer variants avoid copies for large I/O.

File

Byte-stream access to a single file. Served by filesystem services. Created dynamically when a client calls Directory.open() — the filesystem service creates a File CapObject for the opened file and transfers it to the caller via IPC cap transfer.

interface File {
    read     @0 (offset :UInt64, length :UInt32) -> (data :Data);
    write    @1 (offset :UInt64, data :Data) -> (written :UInt32);
    stat     @2 () -> (size :UInt64, created :UInt64, modified :UInt64);
    truncate @3 (length :UInt64) -> ();
    sync     @4 () -> ();
    close    @5 () -> ();
}

close releases the server-side state for this file (open cluster chain cache, dirty buffers). The kernel-side CapTable entry is removed by the system transport via CAP_OP_RELEASE when the local holder releases it; generated capos-rt handle drop still needs RAII integration before ordinary userspace handles submit that opcode automatically. CapabilityManager is management-only (list(), later grant()); it does not expose a drop() method because ordinary handle lifetime belongs to the transport, not to an application call on the same table that dispatches it.

Attenuation: a read-only File wraps the original and rejects write, truncate, sync calls. An append-only File rejects write at offsets other than the current size.

Directory

Namespace over files on a filesystem. Served by filesystem services. open() and sub() return new capabilities via IPC cap transfer.

interface Directory {
    open    @0 (name :Text, flags :UInt32) -> (file :File);
    list    @1 () -> (entries :List(DirEntry));
    mkdir   @2 (name :Text) -> (dir :Directory);
    remove  @3 (name :Text) -> ();
    sub     @4 (name :Text) -> (dir :Directory);
}

struct DirEntry {
    name  @0 :Text;
    size  @1 :UInt64;
    isDir @2 :Bool;
}

sub() returns a Directory scoped to a subdirectory — the analog of chroot. The caller cannot traverse upward or see the parent directory. open() with create flags creates a new file if it doesn’t exist.

The flags field in open() is a bitmask: CREATE = 1, TRUNCATE = 2, APPEND = 4. No READ/WRITE flags — those are determined by the Directory cap’s attenuation (a read-only Directory returns read-only Files).

Syscall Trace: Reading a File from a FAT USB Drive

Four userspace processes: App, FAT service, USB mass storage, xHCI driver.

With promise pipelining (one submission):

Cap’n Proto promise pipelining lets the App chain dependent calls without waiting for intermediate results. The App submits a single pipelined request: “open this file, then read from the result”:

# Single pipelined submission (SQEs with PIPELINE flag):
#   call 0: dir.open("report.pdf")         → promise P0
#   call 1: P0.file.read(offset=0, len=4096)  → depends on P0

cap_submit([
    {cap=2, method=OPEN, params={"report.pdf", flags=0}},
    {cap=PIPELINE(0, field=file), method=READ, params={offset:0, length:4096}},
])
  → kernel routes call 0 to FAT service via Endpoint
  → FAT service reads directory entry from BlockDevice
  → FAT service creates FileCapObject, replies with File cap
  → kernel sees pipelined call 1 targeting the File cap from call 0
  → kernel dispatches call 1 to the same FAT service (or direct-invokes
    the new File CapObject if it's a local endpoint)
  → FAT service maps offset → cluster chain → LBA
  → FAT service submits CALL SQE: {cap=blk_cap, method=READ_BLOCKS, params={lba, count}}
      → USB mass storage → xHCI → hardware → back up
  ← completion: {data: [4096 bytes]}, File cap installed as cap_id=5

One app-to-kernel transition. The kernel resolves the pipeline dependency internally — the App never sees the intermediate File cap until the whole chain completes (though the cap is installed and usable afterward).

This is a core Cap’n Proto feature: by expressing “call method on the not-yet-resolved result of another call,” the client avoids a round-trip for each link in the chain. For deeper chains (e.g., dir.sub("a").sub("b") .open("file").read(0, 4096)), the savings compound — one submission instead of four sequential syscalls.

Without pipelining (two sequential ring submissions):

Without promise pipelining, the App submits two separate CALL SQEs via the ring, blocking on each completion before submitting the next:

# 1. Open file (App holds Directory cap, cap_id=2)
# App writes CALL SQE: {cap=2, method=OPEN, params={"report.pdf", flags=0}}
cap_enter(min_complete=1, timeout=MAX)
  → kernel routes CALL to FAT service via Endpoint
  → FAT service reads directory entry from BlockDevice
  → FAT service creates FileCapObject for this file
  → FAT service posts RETURN SQE with [FileCapObject] in xfer_caps
  → kernel installs File cap in App's table → cap_id=5
  ← App reads CQE: result={file: cap_index=0}, new_caps=[5]

# 2. Read 4096 bytes from offset 0
# App writes CALL SQE: {cap=5, method=READ, params={offset:0, length:4096}}
cap_enter(min_complete=1, timeout=MAX)
  → kernel routes CALL to FAT service
  → FAT service maps offset → cluster chain → LBA
  → FAT service submits CALL SQE: {cap=blk_cap, method=READ_BLOCKS, params={lba, count}}
      → kernel routes to USB mass storage
      → mass storage submits CALL SQE: {cap=usb_cap, method=BULK_TRANSFER, params={scsi_cmd}}
          → kernel routes to xHCI driver
          → xHCI programs TRBs, waits for interrupt
          ← returns raw sector data
      ← returns sector data
  ← FAT service extracts file bytes, posts RETURN SQE with {data: [4096 bytes]}

This works but costs two round-trips where pipelining needs one. The synchronous path is useful for simple cases and bootstrapping; pipelining is the intended steady-state model.

In both cases, the intermediate IPC hops (FAT → USB mass storage → xHCI) are invisible to the App.

Capability-Native Store

The Store Capability

Once the system is running, persistent storage is provided by a userspace service — the store. It’s backed by a block device (virtio-blk), and exposes a content-addressed object store where objects are capnp messages.

interface Store {
    # Store a capnp message, returns its content hash
    put @0 (data :Data) -> (hash :Data);
    # Retrieve by hash
    get @1 (hash :Data) -> (data :Data);
    # Check existence
    has @2 (hash :Data) -> (exists :Bool);
    # Delete (if caller has authority — see note below)
    delete @3 (hash :Data) -> ();
}

Note on delete: In a content-addressed store, deleting a hash can break references from other namespaces pointing to the same object. delete on the base Store interface is dangerously broad — a StoreAdmin interface (separate from Store) may be more appropriate, with delete restricted to a GC service that can verify no live references exist. Open Question #3 (GC) should be resolved before implementing delete. The attenuation table below lists Store (full) as “Read, write, delete any object” — in practice, most callers should receive a Store attenuated to put/get/has only.

Content-addressed means:

• Deduplication is automatic (same content = same hash)
• Integrity is verifiable (hash the data, compare)
• References between objects are just hashes embedded in capnp messages
• No mutable paths — “updating a file” means storing a new version and updating the reference

Mutable References: Namespaces

A Namespace capability provides mutable name-to-hash mappings on top of the immutable store:

interface Namespace {
    # Resolve a name to a store hash
    resolve @0 (name :Text) -> (hash :Data);
    # Bind a name to a hash (if caller has write authority)
    bind @1 (name :Text, hash :Data) -> ();
    # List names (if caller has list authority)
    list @2 () -> (names :List(Text));
    # Get a sub-namespace (attenuated — restricted to a prefix)
    sub @3 (prefix :Text) -> (ns :Namespace);
}

A Namespace cap scoped to "config/" can only see and modify names under that prefix. This is the analog of a chroot — but structural, not a kernel hack. The sub() method returns a new Namespace cap via IPC cap transfer.

Future: union composition. The research survey recommends extending Namespace with Plan 9-inspired union semantics — a union(other, mode) method that merges two namespaces with before/after/replace ordering. This adds composability without a global mount table. See research.md §6.

IPC and Capability Transfer

Several storage operations return new capabilities: Directory.open() returns a File, Directory.sub() returns a Directory, Namespace.sub() returns a Namespace. This requires dynamic capability management — the kernel must install new capabilities in a process’s CapTable at runtime as part of IPC.

The Capability Ring

All kernel-userspace interaction goes through a shared-memory ring pair (submission queue + completion queue), inspired by io_uring. SQE opcodes map to capnp-rpc Level 1 message types. The ring is allocated per-process at spawn time and mapped into the process’s address space.

Syscall surface: 2 syscalls. New capabilities, operations, and transfer mechanisms are expressed as new SQE opcodes instead of expanding the syscall ABI.

Writing SQEs is syscall-free, but ordinary capability CALLs make progress through cap_enter. Timer polling handles non-CALL ring work and only CALL targets that explicitly opt into interrupt-context dispatch. cap_enter flushes pending SQEs and can block the process until min_complete completions are available or a finite timeout expires. An indefinite wait uses timeout_ns = u64::MAX; timeout_ns = 0 keeps the call non-blocking. A future SQPOLL-style worker can reintroduce a zero-syscall CALL-completion hot path without running arbitrary capability methods from timer interrupt context.

The ring structs and synchronous CALL dispatch are implemented and working. See capos-config/src/ring.rs for the shared ring structs and kernel/src/cap/ring.rs for kernel-side processing.

Ring Layout

One 4 KiB page per process, mapped into both kernel (HHDM) and user space:

┌─────────────────────────┐  offset 0
│ Ring Header              │  SQ/CQ head, tail, mask, flags
├─────────────────────────┤  offset 128
│ SQE Array (16 × 64B)    │  submission queue entries
├─────────────────────────┤  offset 1152
│ CQE Array (32 × 32B)    │  completion queue entries
└─────────────────────────┘

SQ: userspace owns tail (producer), kernel owns head (consumer)
CQ: kernel owns tail (producer), userspace owns head (consumer)

SQE Opcodes

Five opcodes handle everything — client calls, server dispatch, capability transfer, pipelining, and lifecycle:

TIMEOUT is an alternative to the timeout_ns argument on cap_enter: it works with zero-syscall polling (kernel fires the CQE on a timer tick) and composes with LINK/DRAIN for deadline-based chains.

SQE flags: PIPELINE (cap_id is a promise reference), LINK (chain to next SQE), MULTISHOT (keep generating CQEs), DRAIN (barrier).

Promise Pipelining

A CALL SQE can target either a concrete CapId or a PromisedAnswer reference (via the PIPELINE flag + pipeline_dep/pipeline_field fields). The kernel resolves the dependency chain internally:

SQE[0]: CALL dir.open("report.pdf")        → user_data=100
SQE[1]: CALL [PIPELINE: dep=100, field=0].read(0, 4096)  → user_data=101

One cap_enter call. The kernel dispatches SQE[0], extracts the File cap from the result, and dispatches SQE[1] against it — all without returning to userspace between steps.

The Endpoint Kernel Object

For cross-process IPC, an Endpoint connects client-side proxy caps to a server’s receive loop:

Client's CapTable                                   Server's CapTable
┌─────────────────┐                                 ┌──────────────────┐
│ cap 2: Proxy     │                                 │ cap 0: Endpoint   │
│   → endpoint ────────── Endpoint ◄──── RECV SQE ──│                  │
│   badge: 42      │     (kernel obj)                │                  │
└─────────────────┘                                 └──────────────────┘

The server posts a RECV SQE (with MULTISHOT flag). Incoming calls appear as CQEs with badge, interface_id, method_id, and a kernel-assigned call_id. The server responds by posting a RETURN SQE referencing the call_id.

interface_id is the transported schema ID for the interface being invoked. It should equal the generated TYPE_ID for that capnp interface. cap_id is the authority-bearing table handle; interface_id is only the protocol tag. The target capability entry owns one public interface; method_id selects a method inside that interface, while cap_id identifies the object being invoked. If the same backing state needs another interface, the transport should mint a separate capability entry for that interface rather than letting one handle accept multiple unrelated interface_id values.

Direct-Switch IPC

When a client’s CALL targets a cap served by a blocked server (waiting on RECV), the kernel marks that server as the direct IPC handoff target so the next context-switch path runs the callee before unrelated round-robin work. The current implementation still uses the ordinary saved-context restore path; small-message register transfer remains a future fastpath after measurement. See research.md §2.

Capability Transfer via Ring

Capabilities travel as sideband arrays (CapTransferDescriptor) alongside capnp message bytes:

• CALL params: params buffer contains the capnp message bytes followed by xfer_cap_count transfer descriptors packed at addr + len, which must be aligned to CAP_TRANSFER_DESCRIPTOR_ALIGNMENT.
• RETURN results: server result buffers carry the capnp reply bytes and may carry return transfer descriptors on addr + len; the kernel inserts destination capability records in the caller’s result buffer after the normal result bytes. Count is reported in CQE cap_count and those records are written as CapTransferResult { cap_id, interface_id } values at result_addr + result. The requested result buffer (result_len) must be large enough for both normal reply bytes and all appended cap_count records.

xfer_cap_count > 0 with malformed descriptor metadata (bad mode bits, reserved bits, _reserved0, or misalignment) fails closed as CAP_ERR_INVALID_TRANSFER_DESCRIPTOR. Kernels that have not yet enabled transfer handling should return CAP_ERR_TRANSFER_NOT_SUPPORTED for transfer-bearing SQEs.

The capnp wire format’s WirePointerKind::Other encodes capability indices in messages. The sideband arrays map these indices to actual CapIds. The kernel does not parse capnp messages — it transfers a list of caps alongside the opaque message bytes.

Dynamic Capability Management

Every open(), sub(), or resolve() creates and transfers a new capability at runtime. The kernel’s CapTable insert() and remove() are the primitives. Capabilities flow through RETURN SQE sideband arrays (and through the manifest at boot). No separate cap_grant mechanism needed — authority flow follows the ring’s IPC graph.

The CapTable generation counter handles stale references: when a File cap is closed (slot freed, generation bumps), any cached CapId returns StaleGeneration instead of accidentally hitting a new occupant.

Shared Memory for Bulk Data

Copying file data through capnp Data fields works for metadata and small reads, but is impractical for anything above a few KB. A 1 MB read through a capability CALL copies data four times: device → driver heap → capnp message → kernel buffer → client buffer.

SharedBuffer Capability

A SharedBuffer (also called MemoryObject, listed in ROADMAP.md Stage 6) is a kernel object backed by physical pages that can be mapped into multiple address spaces simultaneously. Zero copies between processes.

interface SharedBuffer {
    # Map into caller's address space (returns virtual address and size)
    map   @0 () -> (addr :UInt64, size :UInt64);
    # Unmap from caller's address space
    unmap @1 () -> ();
    # Size of the buffer
    size  @2 () -> (bytes :UInt64);
}

The kernel creates SharedBuffer objects on request (via a kernel-provided BufferAllocator capability). The pages are reference-counted — the buffer persists as long as any process holds a cap to it.

File I/O with SharedBuffer

File and BlockDevice interfaces support both inline-Data and SharedBuffer modes:

# Small read (< ~4 KB): inline in capnp message
file.read(offset=0, length=256) → {data: [256 bytes]}

# Large read: caller provides SharedBuffer, server fills it
let buf = buf_alloc.create(1048576);   # 1 MB SharedBuffer
file.readBuf(offset=0, buf, length=1048576) → {bytesRead: 1048576}
# Data is now in buf's mapped pages — no copy through kernel

Extended File interface with SharedBuffer support:

interface File {
    read      @0 (offset :UInt64, length :UInt32) -> (data :Data);
    write     @1 (offset :UInt64, data :Data) -> (written :UInt32);
    readBuf   @2 (offset :UInt64, buffer :SharedBuffer, length :UInt32) -> (bytesRead :UInt32);
    writeBuf  @3 (offset :UInt64, buffer :SharedBuffer, length :UInt32) -> (written :UInt32);
    stat      @4 () -> (size :UInt64, created :UInt64, modified :UInt64);
    truncate  @5 (length :UInt64) -> ();
    sync      @6 () -> ();
    close     @7 () -> ();
}

The readBuf/writeBuf methods accept a SharedBuffer cap (transferred via IPC). The server maps the buffer, performs DMA or memory copies into it, then returns. The caller reads directly from the mapped pages.

For BlockDevice, the same pattern applies — the driver maps the SharedBuffer, programs DMA descriptors pointing to its physical pages, and the device writes directly into the shared memory.

When to Use Each Mode

Attenuation

Storage services mint restricted capabilities using wrapper CapObjects:

An application that only needs to read its config gets a read-only Directory scoped to its config path. It can’t write, can’t see other apps’ directories, can’t access the raw BlockDevice.

Naming Without Paths

Traditional OS: process opens /var/lib/myapp/data.db — a global path.

capOS: process receives a Directory or Namespace cap at spawn time, opens "data.db" within it. The process has no idea where on disk this lives. It can’t traverse upward. There is no global root.

# Traditional: global path namespace
/
├── etc/
│   └── myapp/
│       └── config.toml
├── var/
│   └── lib/
│       └── myapp/
│           └── data.db
└── sbin/
    └── myapp

# capOS: per-process capability set (no global namespace)
Process "myapp" sees:
  "config" → Directory(read-only, scoped to myapp's config files)
  "data"   → Directory(read-write, scoped to myapp's data files)
  "state"  → Namespace(read-write, scoped to myapp's store objects)
  "log"    → Console cap
  "api"    → HttpEndpoint cap

The process doesn’t know or care about the backing storage layout. It just uses the capabilities it was granted.

Configuration

Build-Time Config (Boot Manifest)

The system manifest is authored at build time. The human-writable source could be any format — TOML, CUE, or even a Makefile target that generates the capnp binary. What matters is that it compiles to a SystemManifest capnp message baked into the ISO.

Example source (TOML, compiled to capnp by a build tool):

[services.virtio-net]
binary = "virtio-net"
restart = "always"
caps = [
    { name = "device_mmio", source = { kernel = "device_mmio" } },
    { name = "interrupt", source = { kernel = "interrupt" } },
    { name = "log", source = { kernel = "console" } },
]
exports = ["nic"]

[services.net-stack]
binary = "net-stack"
restart = "always"
caps = [
    { name = "nic", source = { service = { service = "virtio-net", export = "nic" } } },
    { name = "timer", source = { kernel = "timer" } },
    { name = "log", source = { kernel = "console" } },
]
exports = ["net"]

[services.fat-fs]
binary = "fat-fs"
restart = "always"
caps = [
    { name = "blk", source = { service = { service = "usb-storage", export = "block-device" } } },
    { name = "log", source = { kernel = "console" } },
]
exports = ["root-dir"]

[services.my-app]
binary = "my-app"
restart = "on-failure"
caps = [
    { name = "api", source = { service = { service = "http-service", export = "api" } } },
    { name = "docs", source = { service = { service = "fat-fs", export = "root-dir" } } },
    { name = "data", source = { service = { service = "store", export = "namespace" } } },
    { name = "log", source = { kernel = "console" } },
]

A build tool validates this against the capnp schemas (does virtio-net actually export "nic"? does http-service support endpoint() minting?) and produces the binary manifest.

Runtime Config (via Store)

Once the store service is running, configuration can be stored there and updated without rebuilding the ISO. The store is just another capability — a config-management service could watch for changes and signal services to reload.

Connection to Network Transparency

If capabilities are the only abstraction, and capnp is the only wire format, then the transport is irrelevant:

• Local IPC: capnp message copied between address spaces by kernel
• Local store: capnp message written to block device
• Remote IPC: capnp message sent over TCP to another machine
• Remote store: capnp message fetched from a remote store service

A capability reference doesn’t encode where the backing service lives. The kernel (or a proxy) handles routing. This means:

• A Directory cap could be backed by local FAT or a remote 9P server
• A Namespace cap could be backed by local storage or a remote store
• A Fetch cap could route through a local HTTP service or a remote proxy
• A ProcessSpawner cap could spawn locally or on a remote machine

The system manifest could describe services that run on different machines, and the capability graph spans the network. This is the “network transparency” item in the roadmap — it falls out naturally from the model.

Persistence of the Capability Graph

The live capability graph (which process holds which caps) is ephemeral — it exists in kernel memory and is lost on reboot. The system manifest describes the intended graph, and init rebuilds it on each boot.

For true persistence (resume after reboot without re-initializing):

1. Each service serializes its state to the store before shutdown
2. On next boot, the manifest includes “restore from store hash X” hints
3. Services read their saved state from the store and resume

This is application-level persistence, not kernel-level. The kernel doesn’t snapshot the capability graph — services are responsible for their own state. This avoids the complexity of EROS-style transparent persistence while still allowing stateful services.

Phases

Phase 1: Boot Manifest (parallel with Stage 4)

• Define SystemManifest schema in schema/
• Build tool (tools/mkmanifest) that compiles system.cue into a capnp-encoded manifest and packs it into the ISO as a Limine module
• Kernel parses the manifest and currently creates one process per ServiceEntry
• Kernel passes the manifest to init as bytes or a Manifest capability without interpreting the child service graph in the system-spawn.cue transition path
• Init becomes a generic manifest executor instead of a demo parser for the system-spawn.cue transition path
• No persistent storage yet — boot image is the only data source

Phase 2: File I/O Interfaces in Schema (parallel with Stage 6)

Depends on: IPC (Stage 6) for cross-process cap transfer.

• Add BlockDevice, File, Directory, DirEntry, SharedBuffer to schema/capos.capnp
• Implement kernel Endpoint and RECV/RETURN SQE opcodes
• Capability transfer in IPC replies (RETURN SQE xfer_caps installs caps in caller’s table)
• Demo: two-process file server (in-memory File/Directory service + client)

Phase 3: RAM-backed Store (after Phase 2)

Depends on: IPC (Stage 6) for cross-process store access.

• Implement Store and Namespace as a userspace service
• Backed by RAM (no disk driver yet, data lost on reboot)
• Services can store and retrieve capnp objects at runtime
• Demonstrates the naming model without requiring a block device driver
• Namespace.sub() returns new caps via IPC cap transfer

Phase 4: BlockDevice Drivers and Filesystem (after virtio infrastructure)

• virtio-blk driver (userspace, reuses virtqueue infrastructure from networking smoke test)
• BlockDevice trait implementation
• FAT filesystem service: wraps BlockDevice, exports Directory/File caps
• SharedBuffer integration for bulk reads (depends on Stage 6 MemoryObject)
• Store service uses BlockDevice for persistence
• System state survives reboot via store + manifest restore hints

Phase 5: Network Store (after networking)

• Store service can replicate to or fetch from a remote store
• Capability references transparently span machines
• Directory cap backed by a remote filesystem (9P-style)

Relationship to Other Proposals

• Networking proposal — the NIC driver and net stack are services described in the manifest, not hardcoded. The store could be backed by network storage once networking works. A remote Directory cap (9P over capnp) reuses the same File/Directory interfaces.
• Service architecture proposal — the manifest replaces code-as-config for init. ProcessSpawner, supervision, and cap export work as described there, but driven by manifest data instead of compiled Rust code. IPC Endpoints are the mechanism for service export.
• Capability model — IPC cap transfer (Endpoint + RETURN SQE) is the mechanism that makes open() and resolve() work. SharedBuffer is the bulk data path that makes file I/O practical. Both are tracked in ROADMAP.md Stage 6.

Open Questions

1. Manifest validation. How much can the build tool verify statically? Cap export names depend on runtime behavior of services. Should services declare their exports in their own metadata (like a package manifest)?

2. Schema evolution. When a service’s capnp interface changes, stored objects referencing the old schema need migration. Cap’n Proto has backwards-compatible schema evolution, but breaking changes need a story.

3. Garbage collection. Content-addressed store accumulates unreferenced objects. Who GCs? A separate service with Store read + delete authority? Reference counting in the namespace layer?

4. Large objects. Storing multi-megabyte binaries as single capnp Data fields is wasteful (capnp allocates contiguously). SharedBuffer partially addresses this for I/O, but the Store’s put/get interface still takes Data. Options: chunked storage (Merkle tree of hashes), a streaming Blob interface, or SharedBuffer-aware Store methods.

5. Trust model for the manifest. The boot manifest has full authority to define the system. Who signs it? How do you prevent a tampered ISO from granting excessive caps? Secure boot integration?

6. File locking and concurrent access. Multiple processes opening the same file through the same filesystem service need coordination. Options: mandatory locking in the filesystem service (rejects conflicting opens), advisory locking via a separate Lock capability, or single-writer enforcement at the Directory level (open with exclusive flag).

7. RETURN+RECV atomicity. When a server posts a RETURN SQE followed by a RECV SQE, there must be no window where a client call can arrive but the server isn’t listening. SQE LINK chaining (RETURN → RECV) should provide this atomicity — the kernel processes both SQEs as a unit.

Proposal: Userspace TCP/IP Networking

How capOS gets from “kernel boots” to “userspace process opens a TCP connection.”

This document has two parts: a kernel-internal smoke test (actionable now) and a userspace networking architecture (blocked on Stages 4-6).

Part 1: Kernel-Internal Networking (Phase A)

Prove that capOS can send and receive TCP/IP traffic. Everything runs in-kernel — no IPC, no capability syscalls, no multiple processes needed.

What’s Needed

1. PCI enumeration — scan config space, find virtio-net device. Uses the standalone PCI/PCIe subsystem described in cloud-deployment-proposal.md Phase 4 (~200 lines of glue code on top of the shared PCI infrastructure)
2. virtio-net driver — init virtqueues, send/receive raw Ethernet frames. Use virtio-drivers crate or implement manually (~600-800 lines)
3. Timer — PIT or LAPIC timer for smoltcp’s poll loop (retransmit timeouts, Instant::now() support). Not a full scheduler — just a monotonic clock (~50-100 lines)
4. smoltcp integration — implement phy::Device trait over the in-kernel driver, create an Interface with static IP, ICMP ping, then TCP
5. QEMU flags — add -netdev user,id=n0 -device virtio-net-pci,netdev=n0 to the Makefile

Milestones

• Ping: ICMP echo to QEMU gateway (10.0.2.2 with default user-mode net)
• HTTP: TCP connection to a host-side server, send GET, receive response

Estimated Scope

~1000-1500 lines of new kernel code. ~200 more for TCP on top of ping.

Crate Dependencies

Timer Source Decision

Resolved: PIT is already configured at 100 Hz from Stage 5. A monotonic TICK_COUNT (AtomicU64 in kernel/src/arch/x86_64/context.rs) increments on each timer interrupt, providing ~10ms resolution — sufficient for TCP timeouts. Switch to LAPIC timer when SMP lands (see smp-proposal.md Phase A).

QEMU Network Config

Part 2: Userspace Networking Architecture (Phases B+C)

Blocked on: Stage 4 (Capability Syscalls), Stage 5 (Scheduling), Stage 6 (IPC + Capability Transfer).

Architecture

+--------------------------------------------------+
|  Application Process                             |
|    holds: TcpSocket cap, UdpSocket cap, ...      |
|    calls: connect(), send(), recv() via capnp    |
+---------------------------+----------------------+
                            | IPC (capnp messages)
+---------------------------v----------------------+
|  Network Stack Process (userspace)               |
|    smoltcp TCP/IP stack                          |
|    holds: NIC cap (from driver), Timer cap       |
|    implements: TcpSocket, UdpSocket, Dns caps    |
+---------------------------+----------------------+
                            | IPC (capnp messages)
+---------------------------v----------------------+
|  NIC Driver Process (userspace)                  |
|    virtio-net driver                             |
|    holds: DeviceMmio cap, Interrupt cap          |
|    implements: Nic cap                           |
+---------------------------+----------------------+
                            | capability syscalls
+---------------------------v----------------------+
|  Kernel                                          |
|    DeviceMmio cap: maps BAR into driver process  |
|    Interrupt cap: routes virtio IRQ to driver     |
|    Timer cap: provides monotonic clock            |
+--------------------------------------------------+

Three separate processes, each with minimal authority:

1. NIC driver – only has access to the specific virtio-net device registers and its interrupt line. Implements the Nic interface.
2. Network stack – holds the Nic capability from the driver. Runs smoltcp. Implements higher-level socket interfaces.
3. Application – holds socket capabilities from the network stack. Cannot touch the NIC or raw packets directly.

Prerequisites

Phase B: Capability Interfaces

• Define networking schema (Nic, TcpSocket, etc.) in schema/net.capnp
• Implement Nic and NetworkManager as kernel-internal CapObjects wrapping the Phase A code
• Verify capability-based invocation works end-to-end in kernel

Phase C: Userspace Decomposition

• Move NIC driver into a userspace process
• Move network stack into a separate userspace process
• Application process uses socket capabilities via IPC
• Full capability isolation achieved

Cap’n Proto Schema (draft — will evolve with IPC implementation)

interface Nic {
    transmit @0 (frame :Data) -> ();
    receive @1 () -> (frame :Data);
    macAddress @2 () -> (addr :Data);
    linkStatus @3 () -> (up :Bool);
}

interface DeviceMmio {
    map @0 (bar :UInt8) -> (virtualAddr :UInt64, size :UInt64);
    unmap @1 (virtualAddr :UInt64) -> ();
}

interface Interrupt {
    wait @0 () -> ();
    ack @1 () -> ();
}

interface Timer {
    now @0 () -> (ns :UInt64);
    sleep @1 (ns :UInt64) -> ();
}

interface TcpSocket {
    connect @0 (addr :Data, port :UInt16) -> ();
    send @1 (data :Data) -> (bytesSent :UInt32);
    recv @2 (maxLen :UInt32) -> (data :Data);
    close @3 () -> ();
}

interface NetworkManager {
    createTcpListener @0 () -> (listener :TcpListener);
    createUdpSocket @1 () -> (socket :UdpSocket);
    getConfig @2 () -> (addr :Data, netmask :Data, gateway :Data);
}

Open Questions

1. DMA memory management. Dedicated DmaAllocator capability vs extending FrameAllocator with allocDma?
2. Blocking model. Kernel blocks caller on IPC channel vs return “would block” vs both?
3. Buffer ownership. Copy into IPC message vs shared memory vs capability lending?

References

Crates

• smoltcp — no_std TCP/IP stack
• virtio-drivers — no_std virtio drivers (rCore project)

Specs

• virtio 1.2 spec — Section 5.1 covers network device
• OSDev Wiki: PCI, Virtio

Prior Art

• rCore — virtio-drivers + smoltcp
• Redox smolnetd — microkernel userspace net stack
• Fuchsia Netstack3 — capability-oriented, userspace, Rust
• Hermit — unikernel with smoltcp + virtio-net

QEMU

• QEMU Networking
• QEMU virtio-net

Proposal: Error Handling for Capability Invocations

How capOS communicates errors from capability calls back to userspace processes.

This proposal defines a two-level error model: transport errors (the invocation mechanism itself failed) and application errors (the capability processed the request and returned a structured error). The design aligns with Cap’n Proto’s own exception model and the patterns used by seL4, Zircon, and other capability systems.

Note (2025-06): This proposal was written when cap_call was the synchronous invocation syscall. Since then, cap_call has been replaced by the shared-memory capability ring + cap_enter syscall. The two-level error model and CapException schema remain valid, but the delivery mechanism changes: transport errors and application errors are communicated through CQE result fields (status code + result buffer), not syscall return values. The “Syscall Return Convention” section below describes the original cap_call convention; a future revision should map these error codes to CQE status fields instead.

Current CQE Error Namespace

The capability ring uses signed 32-bit CapCqe.result values. Non-negative values are opcode-specific success results; negative values are kernel transport errors defined in capos-config/src/ring.rs:

This is deliberately a small transport namespace. Interface-specific failures should be encoded in the result payload once the target capability successfully handles the request.

Transfer-related transport mapping (3.6.0 ABI slice)

• CAP_ERR_TRANSFER_NOT_SUPPORTED is used for transfer-bearing SQEs that the kernel currently dispatches but does not yet process (xfer_cap_count != 0 on kernels where sideband transfer is off).
• CAP_ERR_INVALID_TRANSFER_DESCRIPTOR is used for structurally validly dispatched transfer SQEs where transfer metadata is malformed:
  • descriptor transfer_mode is not exactly CAP_TRANSFER_MODE_COPY or CAP_TRANSFER_MODE_MOVE;
  • any descriptor reserved bits are set;
  • any descriptor _reserved0 field is non-zero;
  • descriptor region placement (addr + len) is misaligned;
  • descriptor range overflows or cannot be safely bounded.
• CAP_ERR_TRANSFER_ABORTED is reserved for transaction failure after partial transfer side effects are prepared and must not be observed (all-or-nothing rollback boundary).
• CAP_ERR_INVALID_REQUEST remains for non-transfer transport malformation (unsupported opcodes for today, unsupported SQE fields not part of the transfer path, and malformed result/payload buffer pairs).

Problem Statement

Currently, cap_call returns u64::MAX on any error and prints the details to the kernel serial console. The userspace process receives no information about what went wrong – it cannot distinguish “invalid capability ID” from “method not implemented” from “out of memory inside the service.”

Every other capability system separates transport-level errors (bad handle, message validation failure) from application-level errors (the service processed the request and returned a meaningful error). capOS needs both.

Background: How Other Systems Do This

Cap’n Proto RPC Protocol

The Cap’n Proto RPC specification defines an Exception type in rpc.capnp:

struct Exception {
  reason @0 :Text;
  type @3 :Type;
  enum Type {
    failed @0;        # deterministic failure, retrying won't help
    overloaded @1;    # temporary resource exhaustion, retry with backoff
    disconnected @2;  # connection to a required capability was lost
    unimplemented @3; # method not supported by this server
  }
  trace @4 :Text;
}

These four types describe client response strategy, not error semantics. The capnp Rust crate maps them to capnp::ErrorKind::{Failed, Overloaded, Disconnected, Unimplemented}.

Cap’n Proto’s official philosophy (from KJ library and Kenton Varda’s writings): exceptions are for infrastructure failures, not application semantics. Application-level errors should be modeled as unions in method return types.

Capability OS Error Models

Common pattern: a small kernel error code set for transport failures, combined with service-specific typed errors for application failures.

POSIX errno: Why Not

POSIX errno is a global flat namespace of ~100 integers that conflates transport errors (EBADF) with application errors (ENOENT). In a capability system:

• EACCES/EPERM don’t apply – if you have the capability, you have permission; if you don’t, you can’t even name the resource.
• A global error namespace conflicts with typed interfaces where errors should be scoped to the interface.
• No room for structured information (which argument was invalid, how much memory was needed).
• Not composable across trust boundaries – a callee’s errno has no meaning in the caller’s address space without explicit serialization.

Design

Principle: Two Levels, One Wire Format

Level 1 – Transport errors are returned in the syscall return value. These indicate that the capability invocation mechanism itself failed before the target CapObject was reached. No result buffer is written.

Level 2 – Application errors are returned as capnp-serialized messages in the result buffer. The capability was found and dispatched; the implementation returned a structured error. The syscall return value distinguishes this from a successful result.

Both levels use Cap’n Proto serialization for the error payload (level 2 always, level 1 when there’s a result buffer available). This keeps one parsing path in userspace.

Syscall Return Convention

The cap_call syscall (number=2) currently returns:

• 0..N – success, N bytes written to result buffer
• u64::MAX – error (undifferentiated)

New convention:

The transport error codes are a small closed set (like seL4’s 11 values). New transport errors can be added, but the set should remain small and stable.

CapException Schema

Add to schema/capos.capnp:

enum ExceptionType {
    failed @0;
    overloaded @1;
    disconnected @2;
    unimplemented @3;
}

struct CapException {
    type @0 :ExceptionType;
    message @1 :Text;
}

This mirrors Cap’n Proto RPC’s Exception struct. The four types match capnp::ErrorKind and describe client response strategy:

• failed – deterministic failure, retrying won’t help. Covers invalid arguments, invariant violations, deserialization errors, and any capnp::ErrorKind variant not in the other three categories.
• overloaded – temporary resource exhaustion (out of frames, table full). Client may retry with backoff.
• disconnected – the capability’s backing resource is gone (device removed, process exited). Client should re-acquire the capability.
• unimplemented – unknown method ID for this interface. Client should not retry.

The message field is a human-readable string for diagnostics/logging. It must not contain security-sensitive information (internal pointers, kernel addresses) since it crosses the kernel-user boundary.

Application-Level Errors in Interface Schemas

Following Cap’n Proto’s philosophy, expected error conditions that a caller should handle programmatically belong in the method return type, not in the exception mechanism.

Example – FrameAllocator can legitimately run out of memory:

struct AllocResult {
    union {
        ok @0 :UInt64;       # physical address
        outOfMemory @1 :Void;
    }
}

interface FrameAllocator {
    allocFrame @0 () -> (result :AllocResult);
    freeFrame @1 (physAddr :UInt64) -> ();
    allocContiguous @2 (count :UInt32) -> (result :AllocResult);
}

The caller can pattern-match on the result union without parsing an exception. This is the Zircon/FIDL model: transport errors at the syscall layer, application errors as typed return values.

When to use each:

Kernel Implementation

CapObject trait change

The ring SQE does not carry a caller-supplied interface ID. The trait shape below keeps interface selection out of capability implementations because each capability entry owns one public interface:

#![allow(unused)]
fn main() {
pub trait CapObject: Send + Sync {
    fn interface_id(&self) -> u64;
    fn label(&self) -> &str;
    fn call(
        &self,
        method_id: u16,
        params: &[u8],
        result: &mut [u8],
        reply_scratch: &mut dyn ReplyScratch,
    ) -> capnp::Result<CapInvokeResult>;
}
}

Implementations serialize directly into the caller’s result buffer and return a completion containing the number of bytes written, or Pending for async endpoint calls. Dispatch uses the interface assigned to the target capability entry; normal CALL SQEs do not need to repeat that interface ID. capnp::Error carries ErrorKind with the four RPC exception types. The kernel’s dispatch handler converts Err(capnp::Error) into a serialized CapException message and writes it to the result buffer.

Syscall handler changes

In cap_call(), the error path changes from:

#![allow(unused)]
fn main() {
Err(e) => {
    kprintln!("cap_call: ... error: {}", e);
    u64::MAX
}
}

to:

#![allow(unused)]
fn main() {
Err(CapError::NotFound) => ECAP_NOT_FOUND,
Err(CapError::StaleGeneration) => ECAP_NOT_FOUND,
Err(CapError::InvokeError(e)) => {
    // Serialize CapException to result buffer
    let exception_bytes = serialize_cap_exception(&e);
    if result_ptr != 0 && result_capacity >= exception_bytes.len() {
        copy_to_user(result_ptr, &exception_bytes);
        ECAP_APPLICATION_ERROR
    } else {
        ECAP_APPLICATION_ERROR_NO_BUFFER
    }
}
}

The serialize_cap_exception function maps capnp::ErrorKind to ExceptionType:

This matches how capnp-rpc maps exceptions to the wire format.

Userspace API

The init crate (and future userspace libraries) wraps cap_call in a helper that interprets the return value:

#![allow(unused)]
fn main() {
pub enum CapCallResult {
    Ok(Vec<u8>),
    Exception(ExceptionType, String),
    TransportError(TransportError),
}

pub enum TransportError {
    InvalidCapability,
    InvalidBuffer,
    ParamsTooLarge,
}

pub fn cap_call(
    cap_id: u32,
    method_id: u16,
    params: &[u8],
    result_buf: &mut [u8],
) -> CapCallResult {
    let ret = sys_cap_call(cap_id, method_id, params, result_buf);
    match ret {
        ECAP_NOT_FOUND => CapCallResult::TransportError(TransportError::InvalidCapability),
        ECAP_BAD_BUFFER => CapCallResult::TransportError(TransportError::InvalidBuffer),
        ECAP_PARAMS_TOO_LARGE => CapCallResult::TransportError(TransportError::ParamsTooLarge),
        ECAP_APPLICATION_ERROR => {
            let (typ, msg) = deserialize_cap_exception(result_buf);
            CapCallResult::Exception(typ, msg)
        }
        ECAP_APPLICATION_ERROR_NO_BUFFER => {
            CapCallResult::Exception(ExceptionType::Failed, String::new())
        }
        n => CapCallResult::Ok(result_buf[..n as usize].to_vec()),
    }
}
}

Future: Batched Calls

When capOS adds batched capability invocations (async rings, pipelining), each request in the batch gets its own result status. The same two-level model applies per-request:

• Transport error for the batch envelope (invalid ring descriptor, bad capability table) fails the whole batch.
• Per-request transport errors (individual bad cap_id) fail that request.
• Application errors are per-request, written to each request’s result slot.

This matches how NFS compound operations and JSON-RPC batch requests work: a transport error on the batch vs per-operation results.

What This Does NOT Cover

• Error logging/tracing infrastructure. How errors get collected, aggregated, or displayed is a separate concern. The kernel currently prints to serial; a future ErrorLog capability could capture structured error streams.
• Retry policy. The ExceptionType hints at retry strategy (overloaded -> retry, failed -> don’t), but the retry logic itself belongs in userspace libraries, not the kernel.
• Error propagation across capability chains. When capability A calls capability B which calls capability C, and C fails – how does the error propagate back through A? This is a concern for the IPC and capability transfer stages (Stage 6+). The current proposal handles the single-hop case.
• Transactional semantics. Whether a failed operation has side effects (partial writes, allocated-but-not-returned frames) is per-capability semantics, not a kernel-level concern.

Migration Path

Phase 1: Transport error codes (minimal, no schema changes)

Change cap_call to return distinct error codes instead of u64::MAX for all failures. Update the init crate to interpret them. No new schema types needed – application errors still use u64::MAX - 3 but without a structured payload (treated as opaque failure).

This is backward-compatible: existing userspace code that checks == u64::MAX sees different values for different errors, but any >= u64::MAX - 255 check catches all errors.

Phase 2: CapException serialization

Add ExceptionType and CapException to the schema. Implement serialize_cap_exception in the kernel. Update init to deserialize and display errors. Now userspace gets the exception type and message string.

Phase 3: Per-interface application errors

As interfaces mature, add typed error unions to method return types for expected error conditions. FrameAllocator::allocFrame returns AllocResult instead of bare UInt64. The exception mechanism remains for unexpected failures.

Design Rationale

Why mirror capnp RPC’s Exception type instead of inventing our own? Cap’n Proto already defines a well-thought-out exception taxonomy. The four types (failed, overloaded, disconnected, unimplemented) map directly to capnp::ErrorKind in Rust. Using the same vocabulary means capOS capabilities can eventually participate in capnp RPC networks without translation. It also means the Rust compiler enforces exhaustive matching on ErrorKind variants that matter.

Why not put error codes in the syscall return value only (like seL4)? seL4’s 11 error codes work because seL4 kernel objects are simple and fixed-function. capOS capabilities are arbitrary typed interfaces – a file system, a network stack, a GPU driver. The error vocabulary is open-ended. Encoding all possible errors as syscall return values would either require an ever-growing enum (fragile) or lose information (back to errno’s problems). The capnp-serialized CapException in the result buffer gives unbounded expressiveness without changing the syscall ABI.

Why not use capnp exceptions for everything (skip the transport error codes)? Because transport errors happen before the capability is reached. There’s no CapObject to serialize an exception. The kernel would have to synthesize a capnp message on behalf of a non-existent capability, which is wasteful and semantically wrong. A small integer return code is cheaper and more honest about what happened.

Why not define a generic Result(Ok) wrapper in the schema? Cap’n Proto generics only bind to pointer types (Text, Data, structs, lists, interfaces), not to primitives (UInt32, Bool). A Result(UInt64) for allocFrame wouldn’t work. Per-method result structs with unions are more flexible and don’t hit this limitation. The cost is a bit more schema boilerplate, which is acceptable given that capOS has a small number of interfaces.

Why string-based messages (like Plan 9) instead of structured error fields? String messages are adequate for diagnostics and logging. Structured error data belongs in the typed return unions (Phase 3), where the schema enforces what fields exist. Putting structured data in CapException would duplicate the schema’s job and encourage using exceptions for flow control, which Cap’n Proto explicitly warns against.

Security Review and Formal Verification Proposal

How to reason about the correctness and security of the capOS kernel and its trust boundaries in a way that fits a research OS – pragmatic tooling now, targeted verification where it pays off, no aspirational seL4-style full- kernel proofs. The docs/research/sel4.md survey already concluded that Isabelle/HOL-over-C verification does not transfer to Rust and that the design constraints matter more than the proof artefact. This proposal codifies that conclusion into a concrete tooling and process plan.

This proposal uses CWE for concrete vulnerability classes, CAPEC for attacker patterns, Rust language rules / unsafe-code guidance for low-level coding rules, Common Criteria protection-profile concepts for OS security functions, and capability-kernel practice (seL4/EROS-style invariants) for authority, IPC, object lifetime, and scheduler properties. Web-application checklists are not the baseline for OS design review.

Grounding sources:

• MITRE CWE for root-cause weakness labels: CWE-20 explicitly covers raw data, metadata, sizes, indexes, offsets, syntax, type, consistency, and domain rules; CWE also marks broad classes such as CWE-20 and CWE-400 as discouraged for final vulnerability mapping when a more precise child fits.
• MITRE CAPEC for attacker behavior, especially input manipulation (CAPEC-153), command injection (CAPEC-248), race exploitation (CAPEC-26 / CAPEC-29), and flooding/resource pressure (CAPEC-125).
• Rust Reference and Rust 2024 Edition Guide for unsafe-block and unsafe_op_in_unsafe_fn obligations.
• seL4 MCS and the existing capOS research notes for capability-authorized access to kernel objects and CPU time.
• Common Criteria General Purpose Operating System Protection Profile for OS access-control, security-function, trusted-channel/path, and user-data protection concepts. capOS is not trying to certify against it; the PP is a vocabulary check for what an OS security review should not omit.

1. Philosophy and Scope

capOS is explicitly a research OS whose design principle is “schema-first typed capabilities, minimal kernel, reuse the Rust ecosystem.” Three consequences shape this proposal:

1. The schema is part of the TCB. A bug in the .capnp schema, or in the way generated code is patched for no_std, is exactly as dangerous as a bug in the kernel. The schema, the capnpc build pipeline, and the generated code all need review attention – not only hand-written kernel code.
2. The kernel should stay small. “Everything else is a capability” means the TCB is naturally bounded. Verification effort scales with TCB size, so resisting kernel bloat is itself a security property.
3. The interface is the permission. Access control lives in capnp method definitions and in userspace cap wrappers (a narrow cap is a different CapObject), not in kernel rights bitmasks. Review must confirm that the kernel never short-circuits this: no ambient authority, no method that bypasses CapObject::call, no syscall that exposes an object without a capability handle.

Non-goals:

• Full functional-correctness proof of the kernel à la seL4. Infeasible in Rust today, and the payoff is low for a research system whose surface area is still changing.
• Proving information-flow / confidentiality properties end-to-end.
• Certifying a specific configuration for external deployment.

2. Trust Boundaries and Threat Model

Enumerating the boundaries forces every future review to ask “which boundary does this change touch?” and picks out the code paths that matter.

Current boundaries

Attacker model

• Untrusted service binaries. Today’s services are checked into the repo, but the manifest pipeline is meant to load arbitrary binaries eventually. Assume every byte of a service’s SQEs, params buffers, result buffer pointers, and return addresses is attacker-controlled.
• Untrusted manifest. Once manifests are produced outside the repo (e.g. generated from CUE fragments, passed in as a Limine module), the manifest parser must reject every malformed input without panicking.
• Resource exhaustion. Once multiple mutually-untrusting services run, a service can attack by filling rings, endpoint queues, capability tables, frame pools, scratch arenas, logs, or CPU time. Boundedness and accounting are security properties, not performance polish.
• Build input drift. The schema/codegen path is already part of the TCB. External build inputs such as the bootloader checkout, Rust dependencies, capnp code generation, and generated-code patching must be reproducible enough that review can tell what changed.
• Host tooling input. Build tools and generators run with developer/CI filesystem access. Treat manifest/config-derived paths and command arguments as untrusted until bounded to the intended directory and execution context.
• Residual state and disclosure. Kernel logs, returned buffers, recycled frames, endpoint scratch space, and generated artifacts must not expose kernel pointers, stale bytes from another process, secrets, or build-system paths that increase attacker leverage.
• Hostile interrupts / preemption. The scheduler preempts at arbitrary points. Any kernel invariant that is only transiently true must be held under the right lock or with interrupts disabled.
• Out of scope (for now): physical attacks, speculative-execution side channels, malicious hardware, IOMMU bypass from DMA devices. These become in-scope once the driver stack lands; revisit the threat model then.

3. Tiered Approach

Four tiers, cheapest first. Each tier is independently useful, and later tiers assume earlier ones are in place.

Tier 1 – Hygiene and CI (cheap, high value)

These are the controls that make every other tier work. The initial GitHub Actions baseline exists in .github/workflows/ci.yml; it runs formatting, host tests, cargo build --features qemu, make capos-rt-check, and make generated-code-check. The QEMU smoke job installs its own boot tools and runs make plus make run, but remains non-blocking, so it is not yet a required boot assertion.

• Continuous integration via GitHub Actions (or equivalent). Current baseline: make fmt-check, cargo test-config, cargo test-ring-loom, cargo test-lib, cargo test-mkmanifest, cargo build --features qemu, make capos-rt-check, and make generated-code-check. Remaining CI work: treat QEMU boot as a required CI gate once runtime flakiness is acceptable, then add the security policy jobs below.
• cargo clippy --all-targets -- -D warnings across workspace members, with a curated set of clippy::pedantic / clippy::nursery lints that pay off for kernel code (clippy::undocumented_unsafe_blocks, clippy::missing_safety_doc, clippy::cast_possible_truncation, etc.). Do NOT enable all of pedantic blindly – review each lint and either enable it or add a rationale comment.
• cargo-deny for license and advisory gating; cargo-audit for the RustSec advisory DB against Cargo.lock. Dependencies include capnp, spin, x86_64, limine, linked_list_allocator – all externally maintained.
• cargo-geiger report of unsafe surface area per crate, checked in as a snapshot and diffed in CI so growth is visible in PRs.
• Deny unsafe_op_in_unsafe_fn (already required by edition 2024; make sure it stays on) and missing_docs on public kernel items where it is not already the case.
• Dependency review discipline: every new dep needs a one-line rationale in the commit message and a check that it is no_std-capable, maintained, and does not pull in a surprise async runtime or heavy transitive graph.
• No-std dependency rubric: kernel/no_std additions require an explicit compatibility check that core/alloc paths do not regress to std through default feature drift, and class ownership is recorded against docs/trusted-build-inputs.md.
• Boot/build input pinning: pin external bootloader/tool downloads to an auditable revision or checksum. Branch names are not enough for TCB inputs. CI should fail when generated capnp bindings or no-std patching change outside an intentional schema/codegen update.
• Untrusted-path panic audit: panic!, assert!, .unwrap(), and .expect() are acceptable during bring-up, but every path reachable from manifest bytes, ELF bytes, SQEs, params buffers, result buffers, and future IPC messages needs either a fail-closed error or a documented halt policy.
• Hardware protection smoke tests: boot under QEMU with SMEP/SMAP-capable CPU flags and assert CR4.SMEP/CR4.SMAP once paging is initialized. Every explicit user-memory dereference must be wrapped in a short STAC/CLAC window once SMAP is enabled.

Tier 2 – Targeted dynamic analysis

Aimed at the host-testable pure-logic crates (capos-lib, capos-config) where the Rust toolchain just works. No kernel changes required.

• Miri on the cargo test-lib and cargo test-config suites. Catches UB in pure-logic code: invalid pointer arithmetic, uninitialized reads, bad provenance, unsound unsafe. The FrameBitmap and CapTable tests in particular push against slot indexing, generation counters, and raw &mut [u8] handling – exactly what miri is good at.
• proptest (or quickcheck) on:
  • capos-lib::elf::parse – random bytes / random perturbations of a valid header must never panic and must refuse anything that isn’t a correctly formed user-half ELF64.
  • capos-lib::frame_bitmap – interleaved sequences of alloc, alloc_contiguous, free, mark_used preserve the invariant free_count == popcount(bitmap == 0) and never double-free.
  • capos-lib::cap_table – insert/remove/lookup sequences preserve “every returned id resolves to its insertion-time object, and stale ids are rejected.”
  • capos-config::manifest encode/decode round trip on arbitrary manifests.
• cargo fuzz harnesses (libFuzzer) on the same three parsers: elf::parse, manifest::decode, and the ring SQE decoder that will land as part of IPC. These run outside CI (they never terminate) but should have a seed corpus checked into fuzz/corpus/ and be run for a fixed budget nightly or on-demand.
• Sanitizers on host tests: RUSTFLAGS=-Zsanitizer=address (and thread) on cargo test-lib under nightly. Requires nothing more than a CI job; cheap to add.

Tier 3 – Concurrency model checking

The capability ring is a lock-free single-producer / single-consumer protocol using volatile reads, release/acquire fences, and a shared head/ tail pair. It is the most likely source of subtle memory-ordering bugs and is also the most isolated – a perfect fit for model checking.

• Loom on a host-buildable wrapper of the ring protocol. Extract the producer/consumer state machine from capos-config::ring into a form where atomics can be swapped for loom::sync::atomic, and write Loom tests that enumerate all interleavings of producer/consumer for small ring sizes (2–4 slots). Properties to check:
  • No CQE is lost.
  • No CQE is double-delivered.
  • The sq_head/sq_tail and cq_head/cq_tail pointers never observe a state that implies tail - head > SQ_ENTRIES.
  • The “corrupted producer state” fail-closed policy (REVIEW_FINDINGS.md “Userspace Ring Client”) holds under adversarial interleavings.
• Shuttle as a lighter alternative for regression-style tests once the specific bugs are known; cheaper per run, randomised rather than exhaustive. Good for long-running overnight jobs.

Loom coverage here is disproportionately valuable: it substitutes for the SMP-hardness work the project has explicitly deferred, and it exercises exactly the ordering that TOCTOU-style bugs hide in.

Tier 4 – Bounded verification of specific invariants

Not a full-kernel proof. Targeted, property-specific, one-module-at-a-time.

• Kani (bounded model checking for Rust, via CBMC). Good fit for small, heap-free, arithmetic-heavy functions. Candidate modules:
  • capos-lib::cap_table – prove that for all insert; remove; insert' sequences under a u8 generation counter, a stale CapId never resolves. Bound: table size ≤ 4, generation window ≤ 256.
  • capos-lib::frame_bitmap – prove that for all bitmap sizes up to N bytes, alloc_frame followed by free_frame of the same frame restores the original bitmap and free_count.
  • capos-lib::elf::parse bounds checks: prove that every index into the program header table is < len, given the validated phentsize and phnum.
• Verus (SMT-based Rust verifier, active development at MSR) for invariants that Kani can’t handle ergonomically, particularly those involving loops and ghost state. Worth tracking but don’t commit to it yet – the proof-engineering cost is real, and the tool is still young. Revisit once IPC lands and the kernel has stable public APIs.
• Creusot / Prusti are alternatives in the same space. Do not invest in more than one SMT-based verifier; pick whichever has the best story for no_std + alloc code when Tier 4 starts.

Deliberately out of scope: Isabelle/HOL, Coq proofs, Frama-C. They would require re-encoding Rust in a foreign semantic framework with no established Rust front-end mature enough for kernel code.

4. Security Review Process

REVIEW.md is the rules document and REVIEW_FINDINGS.md is the open-issue log. REVIEW.md contains the common security checklist that applies across kernel, userspace, host tooling, generators, and CI. The per-boundary prompts below are an expansion of that common checklist for OS-specific code paths.

CWE/CAPEC tagging policy

Security findings should carry CWE metadata when the mapping is specific enough to help a reviewer or future audit. Do not force a CWE into every title.

• Prefer Base/Variant CWE IDs when the root cause is known: CWE-770 for unbounded allocation, CWE-88 for argument injection, CWE-367 for a concrete validation-to-use race, CWE-416 for a real use-after-free.
• Use Class IDs as temporary or umbrella labels: CWE-20 for “input was not validated enough” before the missing property is known; CWE-400 for general resource exhaustion only when the enabling mistake is not more precise.
• Use capability-kernel invariants instead of weak CWE mappings for design properties such as “no ambient authority”, “cap transfer happens exactly once”, “revocation cannot leave stale authority”, and “scheduling context donation cannot fabricate CPU authority”. Cite CWE-862/CWE-863 only when the issue is actually a missing or incorrect authorization check.
• Use CAPEC for the attacker pattern when useful: input manipulation, command injection, race exploitation, flooding, or path/file manipulation. CAPEC is not a substitute for the CWE root-cause tag.

Current checklist coverage:

Per-boundary review checklist

• Syscall surface change (arch/x86_64/syscall.rs):
  • Every register-passed argument is treated as attacker-controlled.
  • No user pointer is dereferenced without validate_user_buffer.
  • Numeric conversions, copy lengths, and pointer arithmetic are checked before constructing slices or entering a UserAccessGuard scope.
  • Kernel stack pointer and TSS.RSP0 invariants are preserved.
  • The syscall count stays bounded; a new syscall has an SQE-opcode alternative considered and explicitly rejected with rationale.
• Ring dispatch change (kernel/src/cap/ring.rs):
  • SQ bounds check and per-dispatch SQE limit still enforced.
  • Corrupted SQ state fails closed (never re-processes the same bad state on the next tick).
  • No allocation in the interrupt-driven path beyond what is already documented in REVIEW_FINDINGS.md.
  • Result buffers and endpoint scratch buffers cannot leak stale bytes beyond the returned completion length.
• User buffer validation change (kernel/src/mem/validate.rs):
  • Address range check precedes PTE walk.
  • PTE flags checked: present, user, and write (if the buffer is written).
  • Single-CPU assumption explicit; TOCTOU note retained until SMP lands.
• ELF loader change (capos-lib::elf):
  • Every field bounded before use (phentsize, phnum, p_offset, p_filesz, p_memsz, p_vaddr).
  • Segments confined to the user half.
  • Overlap check preserved.
  • Integer arithmetic uses checked add/subtract before deriving mapped addresses, file slices, or zero-fill ranges.
• Manifest change (capos-config::manifest):
  • Every optional field is either present or the service is rejected.
  • Name / binary / cap source strings are length-bounded.
  • Unknown / unsupported numbers in CUE input fail-closed with a path- specific error.
  • Capability grants are checked as an authority graph before any rejected graph can start a service.
• Schema change (schema/capos.capnp):
  • Backward-compatible with existing wire format, or migration documented.
  • Every new method has an explicit capability-granting story (who mints the cap that lets this method be called?).
  • Generated code no_std patching still applies.
• Host tool or generator change (tools/*, build.rs, CI scripts):
  • Manifest/config-derived paths cannot escape intended directories through absolute paths, traversal, symlinks, or file-type confusion.
  • External command execution uses explicit binaries and argument APIs, not shell interpolation of untrusted strings.
  • Generated outputs are review-visible and fail closed on malformed inputs.
  • Generated files and diagnostics do not disclose secrets, absolute paths, or stale build outputs beyond what the developer intentionally requested.
• Unsafe block added or expanded: Tier 1 clippy lints plus REVIEW.md §“Unsafe Usage” checklist already cover this; the review should cite the specific invariant being maintained in the commit message.

Threat-model refresh

On every stage completion (Stage 6 IPC, Stage 7 SMP, first driver landing, first time a manifest comes from outside the repo), re-run §2 of this document and update it. The list of trust boundaries grows over time; the proposal decays if it doesn’t grow with the code.

Periodic full audit

Once per stage, schedule a focused audit pass:

1. Re-verify every boundary’s code is still enforced at its documented entry point (no new bypass path).
2. Re-run all Tier 2/3 jobs with the latest toolchain (catches tool-upgrade regressions).
3. Walk through open items in REVIEW_FINDINGS.md and confirm each is still correctly classified (still open, fixed, or explicitly accepted).
4. Record the audit date + outcome at the top of REVIEW_FINDINGS.md, matching the existing “Last verification” convention.

5. Concrete Verification Targets

Ordered by value and feasibility. Each one is a specific, bounded piece of work a contributor can pick up without needing to redesign the kernel.

Targets 1–4 are feasible today and should be the first batch of work. Target 10 is the security gate before treating Stage 6 services as untrusted. Targets 11–12 should be designed before capability transfer lands, otherwise the first IPC implementation will bake in ambient resource authority. Target 14 gates user-mode or semi-trusted drivers.

Current status as of 2026-04-21:

• Targets 1–2 have initial Kani coverage in capos-lib.
• Target 3 has arbitrary-input proptest coverage and a cargo-fuzz target for ELF bytes. The current Kani harness still only proves the short-input early-reject path because fully symbolic ELF parsing reaches allocator and sort internals before there is a sharper proof obligation.
• Target 4 has cargo-fuzz coverage for manifest decoding/roundtrip and mkmanifest exported-JSON conversion.
• Target 5 has a feature-gated Loom model for the shared ring protocol.
• Target 13 has an initial CI baseline plus generated-code drift checking, dependency audit/deny gates, and required QEMU boot still open.

6. Phased Plan

This slots into WORKPLAN.md as a cross-cutting track rather than a phase – items are independent of Stage 6 IPC and can proceed in parallel.

• Track S.1 – CI bootstrap – landed 2026-04-21
  • .github/workflows/ci.yml: fmt-check, test-config, test-ring-loom, test-lib, test-mkmanifest, cargo build --features qemu, make capos-rt-check, generated-code drift checking, and dependency policy checking.
  • QEMU smoke installs build-essential, capnproto, qemu-system-x86, xorriso, and cue v0.16.0 before running make and make run; it remains optional/non-blocking until boot runtime is stable enough to make it a required gate.
  • Clippy-with-deny and cargo-geiger remain future hardening jobs.
• Track S.2 – Miri + proptest on capos-lib – landed 2026-04-21
  • Add proptest dev-dependency to capos-lib.
  • Host properties for capos-lib::cap_table and capos-lib::frame_bitmap; ELF arbitrary-input coverage remains open under S.13.
  • cargo test-lib runs the native host suite; cargo miri-lib runs the same crate under Miri.
• Track S.3 – Manifest + mkmanifest fuzzing – landed 2026-04-21
  • fuzz/ crate with harnesses for manifest::decode and tools/mkmanifest CUE → capnp pipeline. Seed corpus checked in.
• Track S.4 – Ring Loom harness – landed 2026-04-21
  • Extract the SPSC protocol from capos-config::ring into a test-only wrapper where atomics are swappable.
  • Loom tests covering corruption, overflow, and ordering.
  • Doubles as regression coverage for Phase 1.5 in WORKPLAN.md.
• Track S.5 – Kani on capos-lib – initial harnesses landed 2026-04-21
  • CapTable generation/index/stale-reference invariants.
  • FrameBitmap alloc/free symmetry over a small symbolic bitmap model plus a concrete bounded contiguous-allocation proof.
  • ELF parser short-input early-reject panic-freedom.
  • The current bounds are intentionally conservative so make kani-lib remains a practical gate; broader symbolic ELF and contiguous-allocation proofs should wait for more specific invariants.
• Track S.6 – Security review docs stay aligned
  • Keep REVIEW.md’s common security checklist aligned with §4’s boundary prompts as new boundaries land.
  • Add a “threat model refresh” step to the stage-completion workflow in CLAUDE.md.
• Track S.7 – Stage-6-aware refresh
  • Re-run §2 trust-boundary inventory after capability transfer/release semantics land.
  • Plan Loom coverage for cross-process routing and direct-switch IPC.
• Track S.8 – Untrusted-service hardening gate
  • Wire SMEP/SMAP enablement into x86_64 init after paging is live.
  • Replace raw user-slice construction in syscall/ring paths with checked copy/access helpers that bracket the actual access with STAC/CLAC.
  • Add QEMU hostile-userspace tests for bad pointers, kernel-half pointers, invalid caps, corrupted rings, and services without Console authority.
  • Audit untrusted-input paths for panics before Stage 6 endpoints run mutually-untrusting processes.
• Track S.9 – Authority graph and resource accounting – landed 2026-04-21
  • Concrete design is captured in docs/authority-accounting-transfer-design.md.
  • Defines authority graph invariants, per-process quota ledger (cap slots, endpoint queue, outstanding calls, scratch, frame grants, log volume, CPU budget), diagnostic aggregation, and exactly-once transfer/rollback semantics.
  • Establishes acceptance criteria that gate WORKPLAN 3.6 capability transfer and 5.2 ProcessSpawner implementation.
• Track S.10 – Supply-chain and generated-code TCB
  • Pin Limine and other external build inputs by revision/checksum rather than branch name.
  • Make capnp generated-code changes review-visible in CI, including the no-std patching step.
  • Consider cargo-vet only after cargo-deny/cargo-audit are in place; vetting too early is process theater.
  • S.10.3 adds a concrete dependency policy: no_std additions are accepted only with class attribution, cargo deny + cargo audit, and explicit lockfile intent.
  • S.10.3 enforcement is make dependency-policy-check, backed by deny.toml and pinned CI installs of cargo-deny 0.19.4 and cargo-audit 0.22.1.
• Track S.11 – Device/DMA isolation gate
  • Before PCI/virtio/NVMe/user drivers land, choose the DMA isolation story: IOMMU-backed DMA domains or kernel-owned bounce buffers.
  • Define DMAPool, DeviceMmio, and Interrupt capability invariants: bounded physical ranges, explicit interrupt ownership, device reset on revoke, and no raw physical-address grants to untrusted drivers.
  • S.11.2 requires a concrete ownership-transition gate before userspace NIC/ block drivers are allowed.
• Track S.12 – Kani harness bounds refresh
  • Revisit Kani bounds and harness shape once capability transfer, resource-accounting, or validate_user_buffer exposes concrete proof obligations.
  • Prefer actionably narrow properties over arbitrary symbolic parser exploration that spends verifier time in allocator or sort internals.
• Track S.13 – ELF parser arbitrary-input coverage
  • Add proptest coverage for capos-lib::elf::parse on arbitrary bytes and valid-header perturbations.
  • Add a cargo fuzz target for ELF bytes once the corpus and runtime budget are defined.

Tracks S.1 through S.5 have initial coverage. S.6 is ongoing doc hygiene and should move with review-process changes. S.8 must land before Stage 6 runs mutually-untrusting services. S.9 design is complete and now gates concrete implementation work in 3.6/5.2. S.11 gates device-driver work. S.12 should not expand bounds for their own sake; it is a refresh point when new kernel invariants make better proof targets available. S.13 closes the remaining target-3 gap from the table above.

7. What This Proposal Does Not Promise

• No claim that capOS will be “secure” at the end. It will be harder to write a silently wrong change to the code paths the tooling covers, and it will be easier to find the ones that are still wrong.
• No proof obligation on every PR. Kani and Loom are expensive to run on every push; CI runs them on a reduced schedule (e.g. nightly, or on PRs that touch the covered crates).
• Userspace and host-tool bugs are in scope, but their impact is classified by boundary. A userspace bug should not compromise kernel isolation; a host-tool bug can still compromise the build TCB or developer/CI filesystem.
• No claim that confidentiality is handled beyond architectural isolation. Timing channels, cache side channels, device side channels, and covert channels through shared services remain explicit research topics, not current implementation goals.

8. Relation to Other Docs

• docs/research/sel4.md §1 and §6.1 already make the case that full verification is not the right goal. This proposal is the operational answer.
• REVIEW.md is the reviewer’s rulebook. This proposal explains the security and verification rationale behind its common checklist and per-boundary prompts.
• REVIEW_FINDINGS.md is the open-issue log. This proposal feeds it – every bug found by Tier 2/3/4 tooling lands there unless fixed in the same change.
• ROADMAP.md owns the stages; this proposal does not add stages, only a cross-cutting track that runs alongside them.
• WORKPLAN.md owns concrete ordering; Track S.1–S.11 above is the actionable slice mirrored there.

Proposal: Capability-Based Binaries, Language Support, and POSIX Compatibility

How userspace binaries receive, use, and compose capabilities — from the native Rust runtime through POSIX compatibility to running unmodified software.

Current State

The init binary (init/src/main.rs) is no_std Rust with a static heap allocator and still reaches the raw bootstrap syscalls through shared demo support. It validates its CapSet, invokes the Console capability over the capability ring, and exits. The former ring and IPC smokes now live as separate release-built binaries in the nested demos/ workspace. The kernel creates multiple processes from the boot manifest and schedules them with round-robin preemption. Init is not yet based on a reusable runtime crate — demos/capos-demo-support is only a test-support shim, not capos-rt.

The kernel-side roadmap (Stages 4-6) provides the capability ring (SQ/CQ shared memory + cap_enter syscall, implemented), scheduling, and IPC. This proposal covers the userspace half: what binaries look like, how they’re built, and how existing software runs on a system with no ambient authority.

Part 1: Native Userspace Runtime (capos-rt)

The Problem

Every userspace binary currently needs to:

• Define _start and a panic handler
• Set up an allocator
• Construct raw syscall wrappers
• Manually serialize/deserialize capnp messages
• Know the syscall ABI (register layout, method IDs)

This is fine for one proof-of-concept binary. It won’t scale to dozens of services.

Solution: A Userspace Runtime Crate

capos-rt is a no_std + alloc Rust crate that every native capOS binary depends on. It provides:

1. Entry point and allocator setup.

// capos-rt provides the real _start that:
// - initializes the heap allocator (bump allocator over a fixed region,
//   or grows via FrameAllocator cap if granted)
// - parses the initial capability set from a kernel-provided page
// - calls the user's main(CapSet)
// - calls sys_exit with the return value

#[capos_rt::main]
fn main(caps: CapSet) -> Result<(), Error> {
    let console = caps.get::<Console>("console")?;
    console.write_line("Hello from capOS")?;
    Ok(())
}

2. Syscall layer. Raw syscall asm wrapped in safe Rust functions. The entire syscall surface is 2 calls – new operations are SQE opcodes, not new syscalls:

• sys_exit(code) – terminate process (syscall 1)
• sys_cap_enter(min_complete, timeout_ns) – flush pending SQEs, then wait until N completions are available or the timeout expires (syscall 2)

Capability invocations go through the per-process SQ/CQ ring. capos-rt provides helpers for writing SQEs and reading CQEs:

#![allow(unused)]
fn main() {
/// Submit a CALL SQE to the capability ring and wait for the CQE.
pub fn cap_call(
    ring: &mut CapRing,
    cap_id: u32,
    method_id: u16,
    params: &[u8],
    result_buf: &mut [u8],
) -> Result<usize, CapError> {
    ring.push_call_sqe(cap_id, method_id, params);
    sys_cap_enter(1, u64::MAX);
    ring.pop_cqe(result_buf)
}
}

3. Cap’n Proto integration. Re-exports generated types from schema/capos.capnp and provides typed wrappers:

#![allow(unused)]
fn main() {
// Generated from schema + thin wrapper in capos-rt
impl Console {
    pub fn write(&self, data: &[u8]) -> Result<(), CapError> {
        let mut msg = capnp::message::Builder::new_default();
        let mut req = msg.init_root::<console::write_params::Builder>();
        req.set_data(data);
        self.invoke(0, &msg)  // method @0
    }

    pub fn write_line(&self, text: &str) -> Result<(), CapError> {
        let mut msg = capnp::message::Builder::new_default();
        let mut req = msg.init_root::<console::write_line_params::Builder>();
        req.set_text(text);
        self.invoke(1, &msg)  // method @1
    }
}
}

4. CapSet – the initial capability environment.

At spawn time, the kernel writes the process’s initial capabilities into a well-known page (or passes them via registers/stack – ABI TBD). capos-rt parses this into a CapSet: a name-to-CapId map.

#![allow(unused)]
fn main() {
pub struct CapSet {
    caps: BTreeMap<String, CapEntry>,
}

struct CapEntry {
    id: u32,            // authority-bearing slot in the process CapTable
    interface_id: u64,  // generated capnp TYPE_ID, carried for type checking
}

impl CapSet {
    /// Get a typed capability by name. Fails if not present or wrong type.
    pub fn get<T: Capability>(&self, name: &str) -> Result<T, CapError> { ... }

    /// List available capability names (for debugging/discovery).
    pub fn list(&self) -> impl Iterator<Item = (&str, u64)> { ... }
}
}

interface_id is not a handle. It is metadata carrying the generated Cap’n Proto TYPE_ID for the interface expected by the typed client. The handle is id (CapId). A typed client constructor must check that entry.interface_id == T::TYPE_ID, then store the CapId. Normal CALL SQEs do not need to repeat the interface ID because each capability table entry exposes one public interface. The ring SQE keeps fixed-size reserved padding for ABI stability, not a required interface field for the system transport.

This matters for the system transport because several capabilities can expose the same interface while representing different authority: a serial console, a log-buffer console, and a console proxy all have the Console TYPE_ID, but different CapId values.

Crate Structure

capos-rt/
  Cargo.toml          # no_std + alloc, depends on capnp
  build.rs            # capnpc codegen from schema/capos.capnp
  src/
    lib.rs            # re-exports, #[capos_rt::main] macro
    syscall.rs        # raw asm syscall wrappers
    caps.rs           # CapSet, CapEntry, Capability trait
    alloc.rs          # userspace heap allocator setup
    generated.rs      # include!(capnp generated code)

capos-rt is NOT a workspace member (same as init/ – needs different code model and linker script). It’s a path dependency for userspace crates.

Init After capos-rt

// init/src/main.rs -- after capos-rt exists
use capos_rt::prelude::*;

#[capos_rt::main]
fn main(caps: CapSet) -> Result<(), Error> {
    let console = caps.get::<Console>("console")?;
    let spawner = caps.get::<ProcessSpawner>("spawner")?;
    let manifest = caps.get::<Manifest>("manifest")?;

    console.write_line("capOS init starting")?;

    for entry in manifest.services()? {
        let binary_name = entry.binary();
        let granted = resolve_caps(&entry, &running_services, &caps)?;
        let handle = spawner.spawn(entry.name(), binary_name, &granted)?;
        running_services.insert(entry.name(), handle);
    }

    supervisor_loop(&running_services, &spawner)
}

Part 2: Capability-Based Binary Model

Binary Format

ELF64, same as now. The kernel’s ELF loader (kernel/src/elf.rs) already handles PT_LOAD segments. No changes to the binary format itself.

What changes is the ABI contract between kernel and binary:

Initial Capability Passing

The kernel needs to communicate the initial cap set to the new process. Options:

Option A: Well-known page. Kernel maps a read-only page at a fixed virtual address (e.g., 0x1000) containing a capnp-serialized InitialCaps message:

struct InitialCaps {
    entries @0 :List(InitialCapEntry);
}

struct InitialCapEntry {
    name @0 :Text;
    id @1 :UInt32;
    interfaceId @2 :UInt64;
}

Option B: Register convention. Pass pointer and length in rdi/rsi at entry. Simpler, but the data still needs to live somewhere in user memory.

Option C: Stack. Push the cap descriptor onto the user stack before iretq. Similar to how Linux passes auxv to _start.

Option A is cleanest – the page is always there, no calling-convention dependency, and it naturally extends to passing additional boot info later.

Service Binary Lifecycle

1. Kernel loads ELF, creates address space, populates cap table
2. Kernel maps InitialCaps page at well-known address
3. Kernel enters userspace at _start

4. capos-rt _start:
   a. Initialize heap allocator
   b. Parse InitialCaps page into CapSet
   c. Call user's main(CapSet)

5. User main:
   a. Extract needed caps from CapSet
   b. Do work (invoke caps, serve requests)
   c. Optionally export caps to parent once ProcessHandle export lookup exists

6. On return from main (or sys_exit):
   a. Kernel destroys process
   b. All caps in process's cap table are dropped
   c. Parent's ProcessHandle receives exit notification

Part 3: Language Support Roadmap

Tier 1: Rust (native, now)

Rust is the only language that matters until the runtime is stable. Reasons:

• no_std + alloc works today with the existing kernel
• capnp crate (v0.25) has no_std support with codegen
• Zero runtime overhead – no GC, no dynamic linker, no libc
• Same language as the kernel, shared understanding of the memory model
• Ownership model maps naturally to capability lifecycle

All system services (drivers, network stack, store) will be Rust.

Tier 2: C (via libcapos.h, after Stage 6)

C is the second target because most existing driver code and system software is C, and the FFI boundary with Rust is trivial.

libcapos is a static library providing:

#include <capos.h>

// Ring-based capability invocation (synchronous wrapper around SQ/CQ ring)
int cap_call(cap_ring_t *ring, uint32_t cap_id, uint16_t method_id,
             const void *params, size_t params_len,
             void *result, size_t result_len);

// Typed wrappers (generated from .capnp schema)
int console_write(cap_t console, const void *data, size_t len);
int console_write_line(cap_t console, const char *text);

// CapSet access
cap_t capset_get(const char *name);
uint64_t capset_interface_id(const char *name);

// Syscalls (the entire syscall surface -- 2 calls total)
_Noreturn void sys_exit(int code);                   // terminate
uint32_t sys_cap_enter(uint32_t min_complete,        // flush SQEs + wait
                       uint64_t timeout_ns);

Implementation: libcapos is Rust compiled to a static .a with a C ABI (#[no_mangle] extern "C"). The capnp message construction happens in Rust behind the C API. This avoids requiring a C capnp implementation.

C binaries link against libcapos.a and use the same linker script as Rust userspace binaries. The entry point and allocator setup are in libcapos.

Tier 3: Regular Rust Runtime Support

After the native capos-rt service model is stable, the next language priority is making capOS build and run ordinary Rust programs as far as the capability model permits. The target is not an ambient POSIX clone; it is a Rust runtime path where common crates can use allocation, time, threading where available, and capability-backed I/O through capOS-native shims.

This has higher priority than C++ and should be evaluated before broad POSIX compatibility work, because Rust is already the system language and can reuse the existing capos-rt ownership and ring abstractions directly.

Tier 4: Go (GOOS=capos)

Go is the next high-priority runtime after regular Rust. It needs in-process threading, futex-like wait/wake, TLS/runtime metadata support, GC integration, and a network poller mapped to capOS capabilities. See docs/proposals/go-runtime-proposal.md for the dedicated plan.

Go has higher priority than C++ because it unlocks CUE and a large practical tooling/runtime ecosystem; C++ support should not displace the Go runtime track.

Tier 5: Any Language Targeting WASI (longer term)

See Part 5 below. Languages that compile to WASI (Rust, C, Go, etc.) can run on capOS through a WASI-to-capability translation layer.

Important distinction: WASI works differently for compiled vs. interpreted languages:

• Compiled languages (Rust, C) compile directly to .wasm — no interpreter in the loop. WASI is a clean, efficient execution path.
• Interpreted languages (Python, JS, Lua) still need their interpreter (CPython, QuickJS, etc.) — it’s just compiled to .wasm instead of native code. The stack becomes: script → interpreter.wasm → WASI runtime → kernel. You pay for a wasm sandbox layer on top of the interpreter you’d need anyway.

For interpreted languages, WASI sandboxing is valuable when running untrusted code (plugins, user-submitted scripts) where you don’t trust the interpreter itself. For trusted system scripts, native CPython/QuickJS via the POSIX layer (Part 4) is simpler and faster — the capability model already constrains what the process can do.

Tier 6: Managed Runtimes (much later)

Languages with their own runtimes (Java, .NET) would need their runtime ported to capOS. This is large effort and low priority. WASI is the pragmatic answer for these languages.

Go is a special case — see docs/proposals/go-runtime-proposal.md for the custom GOOS=capos path (motivated by CUE support). Go via WASI (GOOS=wasip1) is an alternative for CPU-bound use cases but lacks goroutine parallelism and networking.

C++ Note: pg83/std

pg83/std (https://github.com/pg83/std) was reviewed as a possible easier path to C++ on capOS. It is MIT licensed and centered on ObjPool, an arena-owned object graph model with small containers and lightweight public interfaces.

The useful subset for capOS is the low-level core: std/mem, std/lib, std/str, std/map, std/alg, std/typ, and std/sys/atomic. The main shim boundary is std/sys/crt.cpp, which currently provides allocation, memory/string intrinsics, and monotonic time through hosted libc calls.

The full library is not a shortcut to C++ support. It assumes hosted/POSIX facilities in large areas: malloc/free, clock_gettime, pthreads, poll, epoll/kqueue, sockets, fd I/O, DNS, and optional TLS libraries. Its build also expects a C++26-capable compiler. On the current development host, g++ 13.3.0 rejected -std=c++26 and clang++ was unavailable.

Treat it as a later C++ experiment after libcapos and C/C++ startup exist: port only the freestanding arena/container subset first, with exceptions and RTTI disabled unless a concrete C++ ABI decision enables them. Regular Rust and Go remain higher-priority runtime tracks.

Language-Specific Notes

Python

CPython is a C program. It can reach capOS via two paths:

1. WASI: CPython compiled to python.wasm, runs inside Wasmtime/WAMR on capOS. Note: this is still CPython — WASI doesn’t eliminate the interpreter, it just compiles it to wasm. The stack is: script.py → python.wasm → WASI runtime (native) → kernel.
2. POSIX layer: CPython compiled to native ELF via musl + libcapos-posix. Direct: script.py → cpython (native) → kernel.

WASI path — upstream status (as of March 2026):

• CPython on WASI is Tier 2 since Python 3.13 (PEP 816)
• Works for compute-only workloads (no I/O beyond stdout)
• No sockets/networking — blocked on WASI 0.3 (no release date)
• No threading — WASI SDK 26/27 have bugs, skipped by CPython
• WASI 0.2 skipped entirely — going straight to 0.3
• Python 3.14 targets WASI 0.1, SDK 24

POSIX path:

• Full CPython built against musl + libcapos-posix
• Networking works immediately (via TcpSocket/UdpSocket caps behind the POSIX socket shim), no dependency on WASI 0.3
• More integration work than WASI, but unblocked

MicroPython: Small C program (~100K source) designed for embedded use. Builds against musl + libcapos-posix with minimal effort. No threading, no mmap, minimal syscall surface. Good for early scripting needs before full CPython is ported.

When to use which:

Recommendation: Use POSIX path (native CPython) as the primary Python target once the POSIX layer exists. WASI path for sandboxed/untrusted execution. MicroPython for early experimentation. No custom Python runtime port needed — both paths reuse upstream CPython.

JavaScript / TypeScript

Same situation as Python — JS engines (V8, SpiderMonkey, QuickJS) are C/C++ programs that can be compiled to native via POSIX layer or to wasm via WASI. In both cases, the engine interprets JS; WASI just sandboxes the engine itself.

QuickJS is the MicroPython equivalent — tiny (~50K lines C), embeddable, trivially builds against libcapos. Good candidate for embedded scripting in capOS services without pulling in a full V8.

Lua

Tiny C implementation (~30K lines). Trivially builds against libcapos. Good candidate for an embedded scripting language in capOS services. Alternatively, runs via WASI with near-zero overhead.

Part 4: POSIX Compatibility Layer

Why POSIX at All?

capOS is not POSIX and doesn’t want to be. But:

1. Existing software. Most useful software assumes POSIX. A DNS resolver, an HTTP server, a database – all speak open()/read()/write()/socket(). Without some compatibility layer, every piece of software must be rewritten.

2. Developer familiarity. Programmers know POSIX. A compatibility layer lowers the barrier to writing capOS software, even if native caps are better.

3. Gradual migration. Port software first with POSIX compat, then incrementally convert to native capabilities for tighter sandboxing.

The goal is NOT full POSIX compliance. It’s a pragmatic translation layer that maps POSIX concepts to capabilities, enabling existing software to run with minimal modification while preserving capability-based security.

Architecture: libcapos-posix

Application (C/Rust, uses POSIX APIs)
  │
  │  open(), read(), write(), socket(), ...
  │
  v
libcapos-posix (POSIX-to-capability translation)
  │
  │  Maps fds to caps, paths to namespace lookups
  │
  v
libcapos (native capability invocation)
  │
  │  SQ/CQ ring + cap_enter syscall
  │
  v
Kernel (capability dispatch)

libcapos-posix is a static library that provides POSIX-like function signatures. It is NOT libc – it doesn’t provide malloc (that’s the allocator in capos-rt/libcapos), locale support, or the thousand other things in glibc. It’s the ~50 syscall wrappers that matter for I/O.

File Descriptor Table

POSIX programs think in file descriptors. capOS has capabilities. The translation is a per-process fd-to-cap mapping table inside libcapos-posix:

#![allow(unused)]
fn main() {
struct FdTable {
    entries: BTreeMap<i32, FdEntry>,
    next_fd: i32,
}

enum FdEntry {
    /// Backed by a Console cap (stdout/stderr)
    Console { cap_id: u32 },
    /// Backed by a Namespace + hash (opened "file")
    StoreObject { namespace_cap: u32, hash: Vec<u8>, cursor: usize },
    /// Backed by a TcpSocket cap
    TcpSocket { cap_id: u32 },
    /// Backed by a UdpSocket cap
    UdpSocket { cap_id: u32 },
    /// Backed by a TcpListener cap
    Listener { cap_id: u32 },
    /// Pipe (IPC channel between two caps)
    Pipe { read_cap: u32, write_cap: u32 },
}
}

On process startup, libcapos-posix pre-populates:

• fd 0 (stdin): if a Console or StdinReader cap is in the CapSet
• fd 1 (stdout): mapped to Console cap
• fd 2 (stderr): mapped to Console cap (or a separate Log cap)

Path Resolution

POSIX open("/etc/config.toml", O_RDONLY) becomes:

1. libcapos-posix looks up the process’s Namespace cap (from CapSet, name "fs" or "root")
2. Strips leading / (there is no global root – the namespace IS the root)
3. Calls namespace.resolve("etc/config.toml") to get a store hash
4. Calls store.get(hash) to retrieve the object data
5. Creates an FdEntry::StoreObject with cursor at 0
6. Returns the fd number

Relative paths work the same way – there’s no cwd concept by default, but libcapos-posix can maintain a synthetic cwd string and prepend it.

Path scoping is automatic. If the process was granted a Namespace scoped to "myapp/", then open("/data.db") resolves to "myapp/data.db" in the store. The process can’t escape its namespace – there’s no .. traversal because namespaces are flat prefix scopes, not hierarchical directories.

Supported POSIX Functions

Grouped by what capability backs them:

Console cap -> stdio:

Namespace + Store caps -> file I/O:

TcpSocket/UdpSocket caps -> networking:

Not supported (returns ENOSYS or EACCES):

Process Creation Compatibility

capOS process creation is spawn-style, not fork/exec-style. A new process is a fresh ELF instance selected by ProcessSpawner, with an explicit initial CapSet assembled from granted capabilities. The parent address space is not cloned, and an existing process image is not replaced in place.

posix_spawn() is the compatibility primitive for subprocess creation. A libcapos-posix implementation maps it to ProcessSpawner.spawn(), translates file actions into fd-table setup and capability grants, and passes argv and environment data through the process bootstrap channel once that ABI exists. Programs that use the common fork() followed immediately by exec() pattern should be patched to call posix_spawn() directly.

Full fork() is intentionally not a native kernel primitive. Supporting it would require copy-on-write address-space cloning, parent/child register return semantics, fd-table duplication, a per-capability inheritance policy, safe handling for outstanding SQEs/CQEs, and defined behavior for endpoint calls, timers, waits, and process handles that are in flight at the fork point. Threaded POSIX processes add another constraint: only the calling thread is cloned, while locks and async-signal-safe state must remain coherent in the child.

If a concrete port needs more than posix_spawn(), the next step should be a narrow compatibility shim with vfork()/fork-for-exec semantics backed by ProcessSpawner, not a general kernel clone operation. That shim would suspend the parent, restrict child actions to exec-or-exit, and avoid pretending that arbitrary address-space cloning exists.

Security Model

The POSIX layer does NOT weaken capability security. Every POSIX call translates to a capability invocation on caps the process was actually granted:

• open("/etc/passwd") fails if the process’s namespace doesn’t contain "etc/passwd" – not because of permission bits, but because the name doesn’t resolve
• socket(AF_INET, SOCK_STREAM, 0) fails if the process wasn’t granted a NetworkManager cap
• fork() fails unconditionally – there’s no way to synthesize it from caps

A POSIX binary on capOS is more constrained than on Linux, not less. The compatibility layer provides familiar function signatures, not familiar authority.

Building POSIX-Compatible Binaries

my-app/
  Cargo.toml        # depends on capos-posix (which depends on capos-rt)
  src/main.rs       # uses libc-style APIs

Or for C:

#include <capos/posix.h>   // open, read, write, close, socket, ...
#include <capos/capos.h>   // cap_call, capset_get, ...

int main() {
    // Works -- stdout is mapped to Console cap
    write(1, "hello\n", 6);

    // Works -- if "data" namespace cap was granted
    int fd = open("/config.toml", O_RDONLY);
    char buf[4096];
    ssize_t n = read(fd, buf, sizeof(buf));
    close(fd);

    // Works -- if NetworkManager cap was granted
    int sock = socket(AF_INET, SOCK_STREAM, 0);
    // ...
}

The linker pulls in libcapos-posix.a -> libcapos.a -> startup code. Same ELF output, same kernel loader.

musl as a Base (Optional, Later)

For broader C compatibility (printf, string functions, math), libcapos-posix can be layered under musl libc. musl has a clean syscall interface – all system calls go through a single __syscall() function. Replacing that function with capability-based dispatch gives you full libc on top of capOS capabilities:

// musl's syscall entry point -- we replace this
long __syscall(long n, ...) {
    switch (n) {
        case SYS_write: return capos_write(fd, buf, len);
        case SYS_open:  return capos_open(path, flags, mode);
        case SYS_socket: return capos_socket(domain, type, protocol);
        // ...
        default: return -ENOSYS;
    }
}

This is the same approach Fuchsia uses with fdio + musl, and Redox OS uses with relibc. It works and it gives you printf, fopen, getaddrinfo, and most of the C standard library.

Priority: after native capos-rt and libcapos are stable. musl integration is a significant engineering effort and should only be done when there’s actual software to port.

Part 5: WASI as an Alternative to POSIX

Why WASI Fits capOS Better Than POSIX

WASI (WebAssembly System Interface) was designed from the start as a capability-based system interface. Its concepts map almost directly to capOS:

WASI programs already assume they get no ambient authority. A WASI binary compiled for capOS would need essentially zero translation for the security model – just a thin ABI adapter.

Architecture: Wasm Runtime as a capOS Service

WASI binary (.wasm)
  │
  │  WASI syscalls (fd_read, fd_write, path_open, ...)
  │
  v
wasm-runtime process (Wasmtime/wasm-micro-runtime, native capOS binary)
  │
  │  Translates WASI calls to capability invocations
  │  Each wasm instance gets its own CapSet
  │
  v
libcapos (native capability invocation)
  │
  v
Kernel

The wasm runtime is itself a native capOS process. It receives caps from its parent and partitions them among the wasm modules it hosts. This gives you:

• Language independence. Any language that compiles to WASI (Rust, C, C++, Go, Python, JS, …) runs on capOS
• Sandboxing for free. Wasm’s memory isolation + capOS capability scoping
• No porting effort for software that already targets WASI
• Density. Multiple wasm modules in one process, each with different caps

WASI vs Native Performance

Wasm adds overhead: bounds-checked memory, indirect calls, no SIMD (WASI preview 2 adds some). For system services (drivers, network stack), native Rust is the right choice. For application-level code (business logic, CLI tools, web services), wasm overhead is acceptable and the portability is worth it.

WASI Implementation Phases

Phase 1: wasm-micro-runtime as a capOS service. WAMR is a lightweight C wasm runtime designed for embedded/OS use. Build it as a native capOS C binary (via libcapos). Support fd_write (Console), proc_exit, and args_get – enough to run “hello world” wasm modules.

Phase 2: WASI filesystem via Namespace. Map WASI path_open/fd_read/ fd_write to Namespace + Store caps. Pre-opened directories become Namespace caps.

Phase 3: WASI sockets. Map WASI socket APIs to TcpSocket/UdpSocket caps.

Phase 4: WASI component model. WASI preview 2 components can expose and consume typed interfaces. These map naturally to capOS capability interfaces – a wasm component that exports an HTTP handler becomes a capability that other processes can invoke.

Part 6: Putting It All Together – Porting Strategy

Spectrum of Integration

Most native                                              Most compatible
     |                                                          |
     v                                                          v
Native Rust    C with libcapos    C with POSIX layer    WASI binary
(capos-rt)     (typed caps)       (libcapos-posix)      (wasm runtime)

- Best perf     - Good perf        - Familiar API        - Any language
- Full cap      - Full cap         - Auto sandboxing     - Auto sandboxing
  control         control            via cap scoping       via wasm + caps
- Most work     - Moderate work    - Least rewrite       - Zero rewrite
  to write        to write           for existing C        for WASI targets

Example: Porting a DNS Resolver

Native Rust: Rewrite using capos-rt. Receives UdpSocket cap, serves DNS lookups as a DnsResolver capability. Other processes get a DnsResolver cap instead of calling getaddrinfo(). Clean, typed, minimal authority.

C with POSIX layer: Take an existing DNS resolver (e.g., musl’s getaddrinfo implementation or a standalone resolver). Compile against libcapos-posix. Give it a UdpSocket cap and a Namespace cap for /etc/resolv.conf. It calls socket(), sendto(), recvfrom() – all translated to cap invocations. Works with minimal changes, but can’t export a typed DnsResolver cap (it speaks POSIX, not caps).

WASI: Compile a Rust DNS resolver to WASI. Run it in the wasm runtime. Same capability scoping, but through the wasm sandbox.

Recommended Approach for capOS

1. System services: native Rust only. Drivers, network stack, store, init – these are the foundation and must use capabilities natively. No POSIX layer here.

2. First applications: native Rust. While the ecosystem is young, applications should use capos-rt directly. This validates the cap model.

3. C compatibility: when porting specific software. Don’t build the POSIX layer speculatively. Build it when there’s a specific C program to port (e.g., a DNS resolver, an HTTP server, a database). Let real porting needs drive which POSIX functions to implement.

4. WASI: as the general-purpose application runtime. Once the native runtime is stable, the wasm runtime becomes the “run anything” answer. Lower priority than native Rust, but higher priority than full POSIX/musl compat, because WASI’s capability model is a natural fit.

Part 7: Schema Extensions

New schema types needed for the userspace runtime:

# Extend schema/capos.capnp

struct InitialCaps {
    entries @0 :List(InitialCapEntry);
}

struct InitialCapEntry {
    name @0 :Text;
    id @1 :UInt32;
    interfaceId @2 :UInt64;
}

interface ProcessSpawner {
    spawn @0 (name :Text, binaryName :Text, grants :List(CapGrant)) -> (handleIndex :UInt16);
}

struct CapGrant {
    name @0 :Text;
    capId @1 :UInt32;
    interfaceId @2 :UInt64;
}

interface ProcessHandle {
    wait @0 () -> (exitCode :Int64);
}

These definitions now live in schema/capos.capnp as the single source of truth. spawn() returns the ProcessHandle through the ring result-cap list; handleIndex identifies that transferred cap in the completion. The first slice passes a boot-package binaryName instead of raw ELF bytes so spawn requests stay inside the bounded ring parameter buffer; manifest-byte exposure and bulk-buffer spawning remain later work. kill, post-spawn grants, and exported-cap lookup are deferred until their lifecycle semantics are implemented.

Implementation Phases

Phase 1: capos-rt (parallel with Stage 4)

• Create capos-rt/ crate (no_std + alloc, path dependency)
• Implement syscall wrappers (sys_exit, sys_cap_enter) and ring helpers
• Implement CapSet parsing from well-known page
• Implement typed Console wrapper (first cap used from userspace)
• Rewrite init/ to use capos-rt
• Entry point macro, panic handler, allocator setup

Deliverable: init prints “Hello” via Console cap invocation through capos-rt, not raw asm.

Phase 2: Service binaries (after Stage 6)

• Add capnp codegen to capos-rt build.rs (shared with kernel)
• Implement typed wrappers for all schema-defined caps
• Build the first multi-process demo: init spawns server + client, client invokes server cap
• Establish the pattern for service binaries (Cargo.toml template, linker script, build integration)

Deliverable: two userspace processes communicate via typed capabilities.

Phase 3: libcapos for C (after Phase 2)

• Expose capos-rt functionality via extern "C" API
• Write capos.h header
• Build system support for C userspace binaries (linker script, startup)
• Port one small C program as validation

Deliverable: a C “hello world” using console_write_line().

Phase 4: POSIX compatibility (driven by need)

• Implement FdTable and path resolution
• Start with file I/O (open/read/write/close over Namespace + Store)
• Add socket wrappers when networking is userspace
• Optionally integrate musl for full libc

Deliverable: an existing C program (e.g., a simple HTTP server) runs on capOS with minimal source changes.

Phase 5: WASI runtime (after Phase 3)

• Build wasm-micro-runtime as a native capOS C binary
• Map WASI fd_write/proc_exit to caps
• Extend to filesystem and socket WASI APIs
• Run a “hello world” wasm module

Deliverable: hello.wasm runs on capOS.

Open Questions

1. Allocator strategy. Should the userspace heap be a fixed-size region (simple, but limits memory), or should it grow by invoking a FrameAllocator cap (flexible, but every allocation might syscall)? Likely answer: fixed initial region + grow-on-demand via cap.

2. Async I/O. The SQ/CQ ring is inherently asynchronous (submit SQEs, poll CQEs), but the initial capos-rt wrappers provide blocking convenience (submit one CALL SQE + cap_enter(1, MAX)). Real services need batched async patterns. Options:

   • Submit multiple SQEs, poll CQEs in an event loop (io_uring style)
   • Green threads in capos-rt, each blocking on its own cap_enter
   • Userspace executor (like tokio) driving the ring

3. Cap passing in POSIX layer. POSIX has SCM_RIGHTS for passing fds over Unix sockets. Should the POSIX layer support something similar for passing caps? Or is this native-only?

4. Dynamic linking. Currently all binaries are statically linked. Should capOS support shared libraries? Probably not initially – static linking is simpler and the binaries are small. Revisit if binary size becomes a concern.

5. WASI component model integration. WASI preview 2 components have typed imports/exports that could map to capnp interfaces. Should the wasm runtime auto-generate capnp-to-WIT adapters from schemas? This would let wasm components participate natively in the capability graph.

6. Build system. How are userspace binaries packed into the boot image? Currently the Makefile builds init/ separately. With multiple service binaries, need a more scalable approach (build manifest that lists all binaries, Makefile target that builds and packs them all).

Relationship to Other Proposals

• Service architecture proposal – defines what services exist and how they compose. This proposal defines how those service binaries are built, what runtime they use, and how non-Rust software fits in.
• Storage and naming proposal – the POSIX open()/read()/write() translation targets the Store and Namespace caps defined there.
• Networking proposal – the POSIX socket translation targets the TcpSocket/UdpSocket caps from the network stack.

Proposal: Native Shell, Agent Shell, and POSIX Shell

How interactive operation should work on capOS without reintroducing ambient authority through a Unix-like command line.

Problem

capOS deliberately avoids global paths, inherited file descriptors, ambient network access, and process-wide privilege bits. A conventional shell assumes all of those. If capOS copied a Unix shell model directly, the shell would either be mostly useless or become an ambiently privileged escape hatch around the capability model.

The system needs three related, but distinct, shell layers:

• Native shell: schema-aware capability REPL and scripting language.
• Agent shell: natural-language planning layer over the native shell.
• POSIX shell: compatibility personality for existing programs and scripts.

All three must be ordinary userspace processes. None of them should receive special kernel privilege. The kernel and trusted capability-serving processes remain the enforcement boundary.

The first boot-to-shell milestone is text-only: local console login/setup and, later in the same family, a browser-hosted terminal gateway. Graphical shells, desktop UI, compositors, and GUI app launchers are a later tier. See boot-to-shell-proposal.md.

Design Principles

• A shell starts with only the capabilities it was granted.
• Natural language is not authority.
• A shell command compiles to typed capability calls, not stringly syscalls.
• Child processes receive explicit grants. There is no implicit inheritance of the shell’s full authority.
• Elevation is a capability request mediated by a trusted broker, not a flag inside the shell.
• Shell startup is a workload launch from a UserSession, service principal, or recovery profile. Session metadata informs policy and audit; it is not authority.
• Default interactive cap sets are broker-issued session bundles, not hard-coded shell privileges.
• POSIX behavior is an adapter over scoped Directory, File, socket factory, and process capabilities. It is not the native authority model.

User identity and policy sit above this shell model. A shell session may be associated with a human, service, guest, anonymous, or pseudonymous principal, but the session’s capabilities remain the authority. RBAC, ABAC, and mandatory policy decide which scoped caps a broker may grant; they do not create a kernel-side uid, role bit, or label check on ordinary capability calls. See user-identity-and-policy-proposal.md.

Layering

flowchart TD
    Input[Login, guest, anonymous, or service request] --> SessionMgr[SessionManager]
    SessionMgr --> Session[UserSession metadata cap]
    Session --> Broker[AuthorityBroker / PolicyEngine]
    Broker --> Bundle[Scoped session cap bundle]

    Bundle --> Agent[Agent shell]
    Bundle --> Native[Native shell]
    Bundle --> Posix[POSIX shell]

    Agent --> Plan[Typed action plan]
    Plan --> Native
    Posix --> Compat[POSIX compatibility runtime]

    Native --> Ring[capos-rt capability transport]
    Compat --> Ring
    Ring --> Kernel[Kernel cap ring]
    Ring --> Services[Userspace services]

    Agent --> Approval[Approval client cap]
    Approval --> Broker
    Broker --> Services
    Broker --> Audit[AuditLog]

The native shell is the primitive interactive surface. The agent shell emits native-shell plans after inspecting available schemas, current caps, and the session-bound policy context exposed to it. The POSIX shell is a compatibility consumer of capOS capabilities, not the model other shells are built on.

A shell may display a principal name, profile, role set, label, or POSIX UID, but those values are descriptive unless a trusted broker uses them to return a specific capability. Losing a home, logs, launcher, or approval cap cannot be repaired by presenting the same session ID back to the kernel.

Native Shell

The native shell is a typed capability graph operator. Its job is to inspect, invoke, pass, attenuate, release, and trace capabilities.

Example init or development session with explicit spawn authority:

capos:init> caps
log        Console
spawn      ProcessSpawner
boot       BootPackage
vm         VirtualMemory

capos:init> call @log.writeLine({ text: "hello" })
ok

capos:init> spawn "tls-smoke" with {
  log: @log
} -> $child
started pid 12

capos:init> wait $child
exit 0

Values

Native shell values should include:

• @name: a named capability in the current shell context.
• $name: a local value, result, promise, or process handle.
• structured values: text, bytes, integers, booleans, lists, and structs.
• result-cap values returned through the capOS transfer-result path.
• trace values representing CQE and call-history slices.

The shell should preserve interface metadata with every capability value. A method call is valid only if the target cap exposes the method’s schema.

Commands

Initial commands should be small and explicit:

caps
inspect @log
methods @spawn
call @log.writeLine({ text: "boot complete" })
spawn "ipc-server" with { log: @log, ep: @serverEp } -> $server
wait $server
release @temporary
trace $server
bind scratch = @store.sub("scratch")
derive readonly = @home.sub("config").readOnly()

inspect should show the interface ID, label, transferability, revocation state when available, and callable methods. It should not imply that two caps with the same interface ID are the same authority.

Syntax

The syntax should be structured rather than shell-token based. A CUE-like or Cap’n-Proto-literal-like shape fits capOS better than POSIX word splitting:

spawn "net-stack" with {
  log: @log
  nic: @virtioNic
  timer: @timer
}

The shell can still provide abbreviations, but the executable representation should be an ActionPlan object with typed fields.

Composition

Native composition should pass typed caps or structured values, not inherited byte streams by default:

pipe @camera.frames()
  |> spawn "resize" with { input: $, width: 640, height: 480 }
  |> spawn "jpeg-encode" with { input: $, quality: 85 }
  |> call @photos.write({ name: "frame.jpg", data: $ })

If a byte stream is desired, it should be explicit through a ByteStream, File, or POSIX adapter capability. This keeps the “pipe” operator from silently turning every interface into untyped bytes.

Namespaces

There is no global root. A native shell may have a current Directory or Namespace capability, but that is just a default argument:

capos:user> ls @config
services
network

capos:user> cd @config.sub("services")
capos:@config/services> ls
logger
net-stack

The shell cannot traverse above a scoped directory or namespace unless it holds another capability that names that authority.

Session Context

A session-aware shell may hold a self or session cap for UserSession.info() and audit context. That cap is metadata. It can identify the principal, auth strength, expiry, quota profile, and audit identity, but it cannot widen the shell’s CapSet or authorize kernel operations by itself.

The launcher or supervisor starts the shell with a CapSet returned by AuthorityBroker(session, profile). For interactive work, that bundle should usually include scoped terminal, home, logs, launcher, status, and approval caps. For service accounts, guest sessions, anonymous workloads, and recovery mode, the broker returns different bundles under explicit policy profiles.

Shell-launched children inherit only the caps named in the spawn plan. A child may receive a UserSession or session badge for audit, per-client quotas, or service-side selection, but object access still comes from the scoped object caps passed to that child.

Agent Shell

The agent shell is a natural-language planner that emits typed native-shell plans. It should not directly own broad administrative authority.

Example:

capos:init> start the IPC demo, give the client only the server endpoint and console, then wait for both

The agent produces a plan:

Plan:
1. Spawn "ipc-server" with:
   - log: Console
   - ep: Endpoint(owner)

2. Spawn "ipc-client" with:
   - log: Console
   - server: Endpoint(client facet from server)

3. Wait for both ProcessHandle caps.

Required authority:
- ProcessSpawner
- Console
- Endpoint owner cap
- BootPackage binary access

Only after validation does the plan execute. Validation checks the current cap set, schema method IDs, transferability, grant names, quota limits, and policy.

What the Agent Adds

The useful AI-specific behavior is not raw command execution. It is:

• intent decomposition into spawn, grant, wait, trace, and release steps.
• schema-aware parameter construction.
• least-authority grant selection.
• explanation of missing capabilities.
• diagnosis from structured errors, CQEs, logs, and process handles.
• conversion of vague requests into an explicit plan that can be audited.
• retry after typed failures without bypassing policy.

The agent should reason over capOS objects and schemas, not over an unbounded shell prompt.

Minimal Daily Cap Set

The daily-use agent shell should start with the user-identity proposal’s session bundle, minted by AuthorityBroker for one UserSession and profile:

terminal        TerminalSession or Console
self            self/session introspection
status          read-only SystemStatus
logs            read-only LogReader scoped to this user/session
home            Directory or Namespace scoped to user data
launcher        restricted launcher for approved user applications
approval        ApprovalClient

It should not receive these by default:

ProcessSpawner(all)
BootPackage(all)
DeviceManager
StoreAdmin
FrameAllocator
VirtualMemory for other processes
raw networking caps
global service supervisor caps

The shell can ask for more authority, but it cannot mint that authority for itself.

Guest and anonymous profiles should receive narrower variants. A guest shell may get terminal, tmp, and a restricted launcher, while an anonymous workload normally receives short-lived purpose caps, strict quotas, and no durable home namespace. An approval path exists only when the profile policy explicitly grants one.

Approval and Authentication

Elevation belongs in a trusted broker service that is outside the model-controlled agent process.

Conceptual interfaces:

interface ApprovalClient {
  request @0 (
    reason :Text,
    plan :ActionPlan,
    requestedCaps :List(CapRequest),
    durationMs :UInt64
  ) -> (grant :ApprovalGrant);
}

enum ApprovalState {
  pending @0;
  approved @1;
  denied @2;
  expired @3;
}

interface ApprovalGrant {
  state @0 () -> (state :ApprovalState, reason :Text);
  claim @1 () -> (caps :List(GrantedCap));
  cancel @2 () -> ();
}

interface AuthorityBroker {
  request @0 (
    session :UserSession,
    plan :ActionPlan,
    requestedCaps :List(CapRequest),
    durationMs :UInt64
  ) -> (grant :ApprovalGrant);
}

The agent shell holds only a session-bound ApprovalClient. It does not submit arbitrary PrincipalInfo, role, UID, label values, or authentication proofs as authority. The ApprovalClient forwards the bound UserSession and typed request to AuthorityBroker. The broker or a consent service wrapping it holds powerful caps, drives any trusted consent or step-up authentication path, and mints attenuated temporary caps after policy and authentication checks.

The conceptual API intentionally has no authProof argument on the agent-visible path. If a proof is needed, it is collected by SessionManager, the broker, or a trusted approval UI and reflected back to the agent only as pending, approved, denied, or expired.

Elevation Flow

User request:

restart the network stack

Agent plan:

Requested action:
- stop service "net-stack"
- spawn "net-stack"
- grant: nic, timer, log
- wait for health check

Missing authority:
- ServiceSupervisor(net-stack)

Requested duration:
- 60 seconds

Broker decision:

• Which UserSession and profile is this request bound to?
• Is that principal/profile allowed to restart net-stack?
• Is the requested binary allowed?
• Are the requested grants narrower than policy permits?
• Do mandatory confidentiality and integrity constraints allow the grant?
• Is there fresh user presence?
• Does this require step-up authentication?

If approved, the broker returns a narrow leased capability:

supervisor: ServiceSupervisor(service="net-stack", expires=60s)

It should not return broad ProcessSpawner, BootPackage, or DeviceManager authority when a scoped supervisor cap can do the job.

Authentication

Authentication proof should be consumed by the SessionManager or broker boundary, not exposed as a secret to the agent. Suitable mechanisms include:

• password or PIN for medium-risk local actions.
• hardware key or WebAuthn-style challenge for administrative actions.
• TPM-backed local presence for device or boot-policy operations.
• multi-party approval for destructive policy, storage, or recovery actions.

The model should never receive raw tokens, private keys, recovery codes, or full environment dumps.

Agent Hardening

The agent shell must treat files, logs, web pages, service output, and CQE payloads as untrusted data. They are not instructions.

Required behavior:

• show an executable typed plan before authority-changing actions.
• keep elevated caps leased, narrow, and short-lived.
• release temporary caps after the plan finishes or fails.
• audit every approval request, grant, cap transfer, and release.
• require exact targets for destructive actions.
• refuse broad phrases such as “give it everything” unless a trusted policy explicitly allows a named emergency mode.
• keep model memory separate from secrets and authentication proofs.

The enforcement rule is simple: the model may plan, explain, and request. Capabilities decide what can happen.

POSIX Shell

The POSIX shell is a compatibility layer for existing software and scripts. It should be useful, but it should not define native capOS administration.

Mapping

POSIX concepts map onto granted capabilities:

If a POSIX process has no network cap, connect() fails. If it has no directory mounted at /etc, opening /etc/resolv.conf fails. If it has no device cap, /dev is empty or synthetic.

A POSIX shell is launched with both a CapSet and compatibility profile metadata. The profile controls what legacy APIs report. The CapSet controls what the process can actually do.

Compatibility Limits

Exact Unix semantics should not be promised early.

• Prefer posix_spawn over full fork for the first implementation.
• fork with arbitrary shared process state can be emulated later if needed.
• setuid cannot grant caps. At most it asks a compatibility broker to replace the POSIX profile or launch a new process with a different broker-issued cap bundle.
• Mode bits and ownership metadata do not create authority.
• chmod can modify filesystem metadata exposed by a filesystem service, but it cannot grant caps outside that service’s policy.
• /proc is a debugging service view, not kernel ambient introspection.
• Device files exist only when a capability-backed adapter deliberately exposes them.

This is enough for many build tools and CLI programs without making POSIX the security model.

POSIX Session Caps

A normal POSIX shell session might receive:

terminal      TerminalSession
session       UserSession metadata
profile       POSIX profile view
root          Directory or FileServer synthetic root
launcher      restricted ProcessSpawner/command launcher
pipeFactory   ByteStream factory
clock         Timer

Optional caps:

tcp           scoped socket provider
home          writable user Directory
tmp           temporary Directory
proc          read-only process inspection tree

Administrative caps still require broker-mediated approval.

Recovery Shell

A recovery shell is a separate policy profile, not the normal agent shell with hidden extra privileges. It may receive a larger cap set, but only after strong local authentication and with full audit logging. Guest and anonymous profiles must not fall into recovery authority by omission.

Possible recovery bundle:

console
boot package read
system status read
service supervisor for critical services
read-only storage inspection
scoped repair caps
approval client

Destructive recovery operations should still go through exact-target approval. The recovery shell should be local-only unless a separate remote recovery policy explicitly grants network access.

Required Interfaces

This proposal implies several service interfaces beyond the current smoke-test surface:

• UserSession / SessionManager: principal/session metadata, audit context, and guest or anonymous profile creation (user identity proposal).
• TerminalSession: structured terminal I/O, window size, paste boundaries.
• SchemaRegistry: maps interface IDs to method names and parameter schemas.
• CommandRegistry: optional registry of native command capabilities.
• SystemStatus: read-only process and service status.
• LogReader: scoped log access.
• ServiceSupervisor: restart/status authority for one service or subtree.
• AuthorityBroker / ApprovalClient: session-bound base bundles, plan-specific leased grants, and policy/authentication mediation.
• CredentialStore, ConsoleLogin, and WebShellGateway: boot-to-shell authentication services for password-verifier setup, passkey registration, and text terminal launch (boot-to-shell proposal).
• AuditLog: append-only record of plans, approvals, grants, and releases.
• POSIXProfile / compatibility broker: synthetic UID/GID, names, $HOME, cwd, and profile replacement without treating POSIX metadata as authority.
• ByteStream / pipe factory: explicit byte-stream composition for POSIX and selected native pipelines.

These should be ordinary capabilities. A shell only sees the subset it has been granted.

Implementation Plan

1. Native serial shell

   • Built on capos-rt.
   • Lists initial CapSet entries.
   • Invokes typed Console methods.
   • Spawns and waits on boot-package binaries through ProcessSpawner.
   • Provides caps, inspect, call, spawn, wait, release, and trace.

2. Session-aware shell profile

   • Use the SessionManager -> UserSession metadata and AuthorityBroker(session, profile) -> cap bundle split.
   • Add self/session introspection without making identity metadata authoritative.
   • Start with guest, local-presence, and service-account profiles before durable account storage exists.

3. Structured native scripting

   • Add typed variables, result-cap binding, and plan serialization.
   • Add schema registry support for method names and argument validation.
   • Add explicit byte-stream adapters for commands that need text streams.

4. Approval broker

   • Define ActionPlan, CapRequest, ApprovalClient, and leased grant records.
   • Add local authentication and audit logging.
   • Make administrative native-shell operations request scoped caps through the broker instead of running from a permanently privileged shell.

5. Boot-to-shell integration

   • Add local console login/setup in front of the native shell.
   • Require a configured password verifier when one exists.
   • Enter setup mode when no console password verifier exists.
   • Treat guest as an explicit local profile and anonymous as a separate remote/programmatic profile, not as missing-password fallbacks.
   • Support passkey-only web terminal setup through local/bootstrap authority, not unauthenticated remote first use.

6. Agent shell

   • Natural-language frontend that emits native ActionPlan objects.
   • Starts with the broker-issued minimal daily session bundle.
   • Uses the approval broker for elevation.
   • Treats all external content as untrusted data.

7. POSIX shell

   • Implement after Directory/File, ByteStream, and restricted process launch exist.
   • Start with posix_spawn, fd table emulation, cwd, scoped root, pipes, and terminal I/O, plus synthetic POSIX profile metadata.
   • Add broader compatibility only as real workloads demand it.

Non-Goals

• No global root namespace.
• No shell-owned root/admin bit.
• No model-visible secrets.
• No default inheritance of all shell caps into children.
• No authorization from PrincipalInfo, UID/GID, role, or label values alone.
• No promise that POSIX scripts observe exact Unix behavior without a compatibility profile that grants the needed caps.

Open Questions

• Should the native shell syntax be CUE-derived, Cap’n-Proto-literal-derived, or a smaller custom grammar?
• How should schema reflection be packaged before a full runtime SchemaRegistry exists?
• What is the first minimal TerminalSession interface beyond Console?
• Should approval be synchronous only, or can long-running agent plans request staged approvals?
• How should audit logs be stored before persistent storage exists?

Proposal: Boot to Shell

How capOS should move from “boot runs smokes and halts” to an authenticated, text-only interactive shell without weakening the capability model.

Problem

The current boot path is still a systems bring-up path. It starts fixed services, proves kernel and userspace invariants, and exits cleanly. That is useful for validation, but it is not an operating environment.

The first interactive milestone should be deliberately modest:

• Boot QEMU or a local machine to a text console login/setup prompt.
• Start a native capability shell after local authentication or first-boot setup.
• Offer a browser-hosted text terminal later in the same milestone family, with WebAuthn/passkey authentication.
• Keep graphical shells, desktop UI, window systems, and app launchers as a later tier.

The risk is that “make it interactive” tends to smuggle ambient authority back into the system. A login prompt must not become a kernel uid, a web terminal must not become an unaudited remote root shell, and first-boot setup must not be a first-remote-client-wins race.

Scope

In scope:

• Serial/local text console login and first-boot credential setup.
• Native text shell as the post-login workload.
• Minimal SessionManager, CredentialStore, AuthorityBroker, and AuditLog pieces needed to launch that shell with an explicit CapSet.
• Password verifier records stored with a memory-hard password hash.
• Passkey registration and authentication for a web text shell.
• A passkey-only account path that does not require creating a password first.
• Local recovery/setup policy for machines with no credential records.

Out of scope:

• Graphical shell, desktop session, compositor, GUI app launcher, clipboard, or remote desktop.
• POSIX /bin/login, PAM, sudo, su, or Unix uid/gid semantics.
• Password reset by policy fiat. Recovery is a separate authenticated setup or operator action.
• Making authentication proofs visible to the shell, agent, logs, or ordinary application processes.

Design Principles

• Authentication creates a UserSession; capabilities remain the authority.
• The shell is an ordinary process launched with a broker-issued CapSet.
• Console authentication and web authentication feed the same session model.
• Passwords are verified against versioned password-verifier records; raw passwords are never stored, logged, or passed to the shell.
• Passkeys store public credential material only; private keys stay in the authenticator.
• First-boot setup requires local setup authority or an explicitly configured bootstrap credential. Remote first-come setup is not acceptable.
• A missing credential store does not imply an unlocked system.
• Guest and anonymous sessions are explicit policy profiles, not fallbacks for missing credentials.
• Development images may have an explicit insecure profile, but that must be visible in the manifest and serial output.

Architecture

The boot-to-shell path is a userspace service graph started by init after the manifest executor milestone is complete:

flowchart TD
    Kernel[kernel starts init only]
    Init[init manifest executor]
    Boot[BootPackage]
    Cred[CredentialStore]
    Session[SessionManager]
    Broker[AuthorityBroker]
    Audit[AuditLog]
    Console[ConsoleLogin]
    Web[WebShellGateway]
    Launcher[RestrictedShellLauncher]
    Shell[Native text shell]

    Kernel --> Init
    Init --> Boot
    Init --> Cred
    Init --> Session
    Init --> Broker
    Init --> Audit
    Init --> Console
    Init --> Web
    Console --> Session
    Web --> Session
    Session --> Broker
    Broker --> Launcher
    Launcher --> Shell
    Cred --> Session
    Audit --> Session
    Audit --> Broker

init owns broad boot authority long enough to start the authentication and session services. It should not spawn the interactive shell directly with broad boot caps. The broker returns a narrow shell bundle such as:

terminal        TerminalSession or Console
self            UserSession metadata
status          read-only SystemStatus
logs            scoped LogReader
home            scoped Namespace or temporary Namespace
launcher        RestrictedLauncher
approval        ApprovalClient

Early builds can omit storage-backed home and use a temporary namespace. They still should not hand the shell broad BootPackage, ProcessSpawner, FrameAllocator, raw device, or global service-supervisor authority by default.

Console Login

The local console path has three states.

Password Configured

If CredentialStore has an enabled console password verifier for the selected principal or profile, ConsoleLogin prompts for the password before launching the shell.

The verifier record should be versioned:

PasswordVerifier {
  algorithm: "argon2id"
  params: { memoryKiB, iterations, parallelism, outputLen }
  salt: random bytes
  hash: verifier bytes
  createdAtMs
  credentialId
  principalId
}

Argon2id is the default target because it is memory-hard and widely reviewed. The record must include parameters so stronger settings can be introduced without invalidating older records. A deployment may add a TPM- or secret-store-backed pepper later, but the design must not depend on a pepper being present.

On failed attempts, ConsoleLogin records an audit event and applies bounded backoff. The backoff state is not a security boundary by itself, because local attackers may reboot; the password hash strength still matters.

No Console Password

If no console password verifier exists, the console does not launch an ordinary shell. It enters setup mode.

Setup mode can:

• create the first console password verifier,
• enroll a first passkey for the web text shell,
• create both credentials,
• choose an explicit local guest or development profile if the manifest permits it.

For normal images, the setup flow must create at least one usable credential or leave the machine without an ordinary interactive shell. This matches the operator expectation: no configured password means “setup required”, not “open console”.

Passkey-Only Deployment

Passkey-only should be possible without creating a password. It still needs a bootstrap authority path.

Acceptable first-passkey bootstrap paths:

• local console setup enrolls the first passkey and then never creates a password verifier,
• the manifest or cloud metadata includes a predeclared passkey public credential for an operator principal,
• the console prints a short-lived setup challenge that a web enrollment flow must redeem before registering the first passkey.

Unacceptable path:

• the first remote browser to reach the web endpoint becomes administrator because no password exists.

If a machine is passkey-only, the local console can still expose setup, recovery, guest, or diagnostic profiles according to policy. It should not silently become an unauthenticated administrator shell.

Guest and Anonymous Profiles

The user-identity proposal distinguishes authenticated, guest, anonymous, and pseudonymous sessions. Boot-to-shell should consume that model directly.

Authenticated password login creates a human or operator UserSession with auth strength password. Authenticated passkey login normally creates a human, operator, or pseudonymous UserSession with auth strength hardwareKey. Neither proof is authority by itself; both feed the broker.

Guest is the only unauthenticated profile that belongs on the local interactive console by default. It is a deliberate SessionManager.guest() path with a local interactive affordance, weak or no authentication, short expiry, tight quotas, no durable home unless policy grants one, and a bundle such as:

terminal        TerminalSession
self            guest UserSession metadata
tmp             temporary Namespace
launcher        RestrictedLauncher(allowed = ["help", "settings"])
logs            scoped LogReader for this guest session

Guest should not receive ApprovalClient for administrative actions unless a named policy grants it. If no console password exists, setup may offer a guest session only when the manifest explicitly enables a guest profile. Otherwise the operator must create a credential or leave the ordinary shell unavailable.

Anonymous is different. It is usually remote or programmatic, has a random ephemeral principal ID, receives a smaller cap bundle than guest, and has no elevation path except “authenticate” or “create account”. It is not the console fallback for missing credentials, and it should not be counted as “booted to shell” unless the product goal is an explicitly anonymous demo.

If the web gateway later supports anonymous access, it should be a purpose-scoped workload or very restricted text terminal with no durable home, strict quotas, short expiry, and audit keyed by network context plus ephemeral session ID. It must not share the passkey setup path, because passkey-only bootstrap is a credential-enrollment flow, not anonymous access.

An empty CapSet remains the “Unprivileged Stranger” case. It is useful for attack-surface demonstration, but it is not a session profile and not a shell login mode.

Web Text Shell and Passkeys

The web shell in this milestone is a browser-hosted terminal transport, not a graphical shell. It should display the same native text shell protocol through a terminal UI and should launch the same kind of session bundle as the local console path.

Required pieces:

• network stack and HTTP/WebSocket or equivalent streaming transport,
• TLS or a deployment mode acceptable to browsers for WebAuthn,
• stable relying-party ID and origin policy,
• random challenge generation,
• passkey credential storage,
• user-verification policy,
• audit and rate limiting.

Passkey credential records should store public material:

PasskeyCredential {
  credentialId
  principalId
  publicKey
  relyingPartyId
  userHandle
  signCount
  transports
  userVerificationRequired
  createdAtMs
}

The authentication flow is:

1. Browser requests a login challenge.
2. WebShellGateway asks SessionManager or CredentialStore for a bounded, random challenge tied to the relying-party ID and intended principal.
3. Browser calls the platform authenticator.
4. Gateway verifies the WebAuthn assertion, origin, challenge, credential ID, public-key signature, user-presence/user-verification flags, and sign-count behavior.
5. SessionManager mints a UserSession with auth strength hardwareKey.
6. AuthorityBroker returns the shell bundle for that session/profile.
7. RestrictedShellLauncher starts the native text shell connected to the web terminal stream.

Registration requires an existing authenticated session, local setup authority, or an explicit bootstrap path. Passwordless registration is allowed; unauthenticated remote registration is not.

Required Interfaces

These are ordinary capabilities, not kernel modes.

CredentialStore

Owns credential verifier records and challenge state.

Responsibilities:

• list whether setup is required without exposing hashes,
• create password verifier records from setup authority,
• verify password attempts without returning the password or verifier bytes,
• register passkey public credentials,
• issue and consume bounded WebAuthn challenges,
• rotate or disable credentials through an authenticated admin path.

SessionManager

Creates UserSession metadata after successful authentication, explicit local guest policy, purpose-scoped anonymous policy, or setup policy. It should record auth method, auth strength, freshness, expiry, profile, and audit context. It should not hand out broad system caps directly. Boot-to-shell uses authenticated sessions and optional local guest sessions for ordinary interactive shells; anonymous sessions are narrower remote/programmatic contexts unless a manifest explicitly defines an anonymous demo terminal.

AuthorityBroker

Maps a session/profile to a narrow CapSet. Early policy can be static and manifest-backed. The important constraint is that the broker returns capabilities, not roles or strings that downstream services treat as authority.

ConsoleLogin

Consumes TerminalSession, CredentialStore, SessionManager, broker access, and a restricted shell launcher. It never receives broad boot-package or device authority unless a recovery profile explicitly grants it.

WebShellGateway

Terminates the browser terminal session, handles passkey challenge/response, and connects the authenticated session to the shell process. It should not own general administrative caps. It should ask the broker for the same narrow shell bundle as any other session.

AuditLog

Records setup entry, credential creation, failed attempts, successful session creation, broker decisions, shell launch, credential disablement, and logout. Audit entries must not include passwords, password hashes, passkey private material, bearer tokens, or complete environment dumps.

Prerequisites

Boot-to-shell should not be selected before these pieces are credible:

• Default boot uses init-owned manifest execution; the kernel starts only init with fixed bootstrap authority.
• init can start long-lived services and not just short smoke binaries.
• ProcessSpawner can launch the shell and login services with exact grants.
• A terminal input path exists. Current Console is output-oriented; login needs line input, paste boundaries later, and cancellation behavior.
• The native text shell exists as a capos-rt binary with caps, inspect, call, spawn, wait, release, and basic error display.
• Secure randomness exists for salts, session IDs, WebAuthn challenges, and setup tokens.
• There is at least boot-config-backed credential storage. Durable credential storage can come later, but the first implementation must be honest about whether credentials survive reboot.
• Minimal SessionManager, AuthorityBroker, and AuditLog services exist.
• A restricted launcher or broker wrapper prevents the shell from receiving broad init authority.
• Web text shell requires networking, HTTP/WebSocket or equivalent, TLS/origin handling, and WebAuthn verification. It can lag local console boot-to-shell.

Milestone Definition

The “Boot to Shell” milestone is complete when:

• make run-shell or the default boot path reaches a text login/setup prompt.
• With a configured password verifier, the console refuses the shell on a bad password and launches it on the correct password.
• With no console password verifier, the console enters setup mode and requires creating a credential or selecting an explicitly configured local guest or development policy before launching a normal shell.
• Guest console sessions, when enabled, are created through SessionManager.guest() and receive only terminal/tmp/restricted-launcher style caps with no administrative approval path by default.
• Anonymous sessions are not used as the missing-password console fallback and are not accepted as proof that the ordinary boot-to-shell milestone works.
• The shell starts with a broker-issued CapSet and can prove at least one typed capability call plus one exact-grant child spawn.
• Audit output records setup/auth/session/broker/shell-launch events without leaking secrets.
• The web text shell can authenticate with a registered passkey and launch the same native text shell profile.
• A passkey-only account can be enrolled through local setup authority or an explicit bootstrap credential, with no password verifier present.
• Graphical shell work is not part of the acceptance criteria.

Implementation Plan

1. Text console substrate. Add TerminalSession or extend the console service enough for authenticated line input, echo control, paste/framing markers later, and cancellation.

2. Native shell binary. Land the shell proposal’s minimal REPL over capos-rt: list CapSet entries, inspect metadata, call Console, spawn a boot-package binary, wait, release, and print typed errors.

3. Credential store prototype. Add boot-config-backed credential records and Argon2id verification. If Argon2id is too heavy for the first kernel/userspace environment, use a host-generated verifier in the manifest only as a temporary gate and keep the milestone open until in-system verification is real.

4. Console setup/login. Implement the configured-password path and no-password setup path. The setup code should create credential records through CredentialStore, not write ad hoc config in the shell process.

5. Minimal session and broker. Create UserSession metadata and a static policy broker that returns a narrow shell bundle. Add a manifest-gated local guest bundle and keep anonymous bundles separate from ordinary shell login. Prove the shell cannot obtain broad boot authority by default.

6. Audit and failure policy. Add audit records and bounded attempt backoff. Verify logs do not contain raw passwords, verifier bytes, passkey private data, or challenge secrets.

7. Web text shell gateway. After networking and a terminal transport exist, add WebAuthn registration and authentication for the browser-hosted terminal. Support passkey-only enrollment through local setup or explicit bootstrap authority.

8. Durability and recovery. Move credential records from boot config or RAM into a storage-backed service once storage exists. Define recovery as a credential-admin operation, not an implicit bypass.

Security Notes

• Password hashing belongs in userspace auth services, not the kernel fast path.
• WebAuthn challenge state must be single-use and bounded by expiry.
• The web gateway must validate origin and relying-party ID; otherwise passkey authentication is meaningless.
• Setup tokens are credentials. They must be short-lived, single-use, audited, and hidden from ordinary process output.
• Credential records are sensitive even though they are not raw secrets; avoid printing them in debug logs.
• The shell and any agent running inside it must treat logs, terminal input, files, web pages, and service output as untrusted data.

Non-Goals

• No graphical shell in this milestone.
• No passwordless remote first-use takeover.
• No kernel uid, gid, root, or login mode.
• No default shell access to broad BootPackage, raw ProcessSpawner, DeviceManager, raw storage, or global supervisor caps.
• No authentication proof passed through command-line arguments, environment variables, shell variables, audit records, or agent prompts.

Open Questions

• Which Argon2id parameters fit the early userspace memory budget while still resisting offline guessing?
• Should the first credential store be manifest-backed, RAM-backed, or wait for the first storage service?
• How should local console setup prove physical presence on cloud VMs where serial console access may itself be remote?
• What is the first acceptable TLS/origin story for QEMU and local development WebAuthn testing?
• Should passkey-only machines keep a disabled console password slot for later recovery, or should recovery be entirely credential-admin/passkey based?

Proposal: Symmetric Multi-Processing (SMP)

How capOS goes from single-CPU execution to utilizing all available processors.

This document has three phases: a per-CPU foundation (prerequisite plumbing), AP startup (bringing secondary CPUs online), and SMP correctness (making shared state safe under concurrency).

Depends on: Stage 5 (Scheduling) – needs a working timer, context switch, and run queue on the BSP before adding more CPUs.

Can proceed in parallel with: Stage 6 (IPC and Capability Transfer).

Current State

Everything is single-CPU. Specific assumptions that SMP breaks:

The comment in syscall.rs:12 already anticipates the fix: “Will be replaced by per-CPU data (swapgs) for SMP.”

Phase A: Per-CPU Foundation

Establish per-CPU data structures on the BSP. No APs are started yet – this phase makes the BSP’s own code SMP-ready so Phase B is a clean addition.

Per-CPU Data Region

Each CPU needs a private data area accessible via the GS segment base. On x86_64, swapgs switches between user-mode GS (usually zero) and kernel-mode GS (pointing to per-CPU data). The kernel sets KernelGSBase MSR on each CPU during init.

#![allow(unused)]
fn main() {
/// Per-CPU data, one instance per processor.
/// Accessed via GS-relative addressing after swapgs.
#[repr(C)]
struct PerCpu {
    /// Self-pointer for accessing the struct from GS:0.
    self_ptr: *const PerCpu,
    /// Kernel stack pointer for syscall entry (replaces SYSCALL_KERNEL_RSP).
    kernel_rsp: u64,
    /// Saved user RSP during syscall (replaces SYSCALL_USER_RSP).
    user_rsp: u64,
    /// CPU index (0 = BSP).
    cpu_id: u32,
    /// LAPIC ID (from Limine SMP info or CPUID).
    lapic_id: u32,
    /// Pointer to the currently running process on this CPU.
    current_process: *mut Process,
}
}

The syscall entry stub changes from:

movq %rsp, SYSCALL_USER_RSP(%rip)
movq SYSCALL_KERNEL_RSP(%rip), %rsp

to:

swapgs
movq %rsp, %gs:16          ; PerCpu.user_rsp
movq %gs:8, %rsp           ; PerCpu.kernel_rsp

And symmetrically on return:

movq %gs:16, %rsp          ; restore user RSP
swapgs
sysretq

Per-CPU GDT, TSS, and Stacks

Each CPU needs its own:

• GDT – the TSS descriptor encodes a physical pointer to the CPU’s TSS, so each CPU needs a GDT with its own TSS entry. The segment layout (kernel CS/DS, user CS/DS) is identical across CPUs.
• TSS – privilege_stack_table[0] (kernel stack for interrupts from Ring 3) and IST entries (double-fault stack) must be per-CPU.
• Kernel stack – each CPU needs its own stack for syscall/interrupt handling. Current size: 16 KB (4 pages). Same size per CPU.
• Double-fault stack – each CPU needs its own IST stack. Current size: 20 KB (5 pages).

#![allow(unused)]
fn main() {
/// Allocate and initialize per-CPU structures for one CPU.
fn init_per_cpu(cpu_id: u32, lapic_id: u32) -> &'static PerCpu {
    // Allocate kernel stack (4 pages) and double-fault stack (5 pages)
    let kernel_stack = alloc_stack(4);
    let df_stack = alloc_stack(5);

    // Create TSS with per-CPU stacks
    let mut tss = TaskStateSegment::new();
    tss.privilege_stack_table[0] = kernel_stack.top();
    tss.interrupt_stack_table[DOUBLE_FAULT_IST_INDEX] = df_stack.top();

    // Create GDT with this CPU's TSS
    let (gdt, selectors) = create_gdt(&tss);

    // Allocate and populate PerCpu struct
    let per_cpu = Box::leak(Box::new(PerCpu {
        self_ptr: core::ptr::null(),  // filled below
        kernel_rsp: kernel_stack.top().as_u64(),
        user_rsp: 0,
        cpu_id,
        lapic_id,
        current_process: core::ptr::null_mut(),
    }));
    per_cpu.self_ptr = per_cpu as *const PerCpu;
    per_cpu
}
}

LAPIC Initialization

Stage 5 uses the 8254 PIT (100 Hz) and 8259A PIC (IRQ0 → vector 32) for preemption on the BSP. Phase A must migrate from PIT to LAPIC timer before bringing APs online, since the PIT is a single shared device that cannot provide per-CPU timer interrupts. Phase A sets up the full LAPIC, which is needed for:

• Per-CPU timer – replace PIT with LAPIC timer (required for SMP)
• IPI – inter-processor interrupts for TLB shootdown and AP startup
• Spurious interrupt vector – must be configured per-CPU

Crate Dependencies