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.

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 the manifest, validates the kernel-owned boot boundary, loads only initConfig.init.binary into a fresh AddressSpace, builds init’s bootstrap capability table and read-only CapSet page from initConfig.init.caps, enqueues init, and starts the scheduler.

Default boot uses the standalone init ELF as that init process. It receives the bootstrap authority needed to read BootPackage, validate the service graph, spawn child services, and supervise them. The foreground capos-shell is now an init-started service with the terminal, credential, session, audit, and broker capabilities needed for the local shell flow; it does not receive BootPackage or broad ProcessSpawner authority. Focused shell-family manifests such as system-smoke.cue and system-shell.cue also boot standalone init, which launches capos-shell as a single supervised service with the proof-specific cap bundle.

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[validate kernel manifest boundary]
    Manifest --> InitImage[parse and map init ELF]
    Manifest --> InitCaps[build init CapTable and CapSet page]
    InitImage --> InitProcess[create init Process and ring]
    InitCaps --> InitProcess
    InitProcess --> Scheduler[start round-robin scheduler]
    Scheduler --> Init[enter init]
    Init --> DefaultPath[default init-owned service graph]
    DefaultPath --> Shell[spawn capos-shell service]
    DefaultPath --> Gateway[spawn remote-session gateway and resident services]
    Init --> SpawnPath[focused system-spawn executor path]
    SpawnPath --> BootPackage[read BootPackage manifest]
    SpawnPath --> Spawner[spawn child services]
    Spawner --> Children[focused demo processes]

The invariant is that the kernel starts only initConfig.init after validating the kernel-owned manifest boundary, and no child service starts until mkmanifest/init validation has accepted service binary references, authority graph structure, and bootstrap capability source/interface checks.

Design

The boot path is deliberately single-shot. The kernel receives a single packed manifest and validates only the kernel-owned boot contract before creating init. Init then performs the userspace execution step: it reads manifest chunks from BootPackage, validates a metadata-only ManifestBootstrapPlan, resolves kernel and service cap sources, and asks ProcessSpawner to load each child ELF into its own address space with its own user stack, TLS mapping if present, ring page, and CapSet mapping.

The default manifest (system.cue) now boots an init-owned local path: the kernel launches the standalone init binary described by initConfig.init, and init spawns the shell, remote-session CapSet gateway, and resident services from initConfig.services. The shell mints an anonymous UserSession on startup through SessionManager.anonymous(), receives an empty-allowlist anonymous launcher from the broker, and waits at its own interactive prompt. The user types login (or setup on a fresh image) to upgrade in place. The smoke and shell manifests use focused init-owned single-shell graphs, while system-spawn.cue remains the broader focused init-owned graph retained for ProcessSpawner validation.

Invariants

• Limine must provide exactly one boot module, and that module is the manifest.
• Kernel manifest validation must complete before init is enqueued, and init BootPackage validation must complete before any child service is spawned.
• 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 follows the process entry contract documented in Userspace Runtime.
• 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, boot-only-init 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, and read-only typed launch-parameter mapping.
• kernel/src/cap/mod.rs - bootstrap capability resolution and CapSet entry construction for init.
• capos-config/src/manifest.rs - manifest decode and schema-version storage.
• capos-config/src/validation.rs - graph/source/binary validation policy.
• tools/mkmanifest/src/lib.rs - host-side manifest validation and binary embedding.
• system.cue and manifests/system-spawn.cue - default and spawn-focused boot graphs.
• limine.conf and Makefile - bootloader config, ISO construction, QEMU targets.

Validation

• make run-smoke validates the scripted focused init-owned login path: standalone-init boot from system-smoke.cue, init-spawned capos-shell, password prompt, failed-auth redaction, successful shell launch, narrow shell bundle, and clean QEMU halt.
• make run is the operator-facing interactive boot path with the terminal UART on stdio and console/debug output logged separately.
• make run-spawn validates that the kernel boot-launches only the standalone init with Console, BootPackage, and ProcessSpawner, and that init validates BootPackage metadata before running the focused ProcessSpawner, Timer, IPC, and memory smokes.
• 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

• The shell-family focused manifests are init-owned. The init-mandate scope task must define whether remaining self-contained direct-boot proofs are an explicit class or migrate behind init.
• A future manifest-loader or mkmanifest gate should reject boot graphs outside that policy once the direct-proof scope is settled.