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.

Keyboard shortcuts