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, service exports, endpoint client facets, badges, BootPackage manifest exposure to init, init-side graph validation, and generic init-side spawning through ProcessSpawner are implemented. Default make run now uses the init-owned manifest executor; remaining work is post-milestone cleanup of the generic kernel service-cap resolver and long-term manifest shape.

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 --> InitCaps[init CapTable and CapSet page]
    InitCaps --> Init[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 starts only init from the kernel. It grants init ProcessSpawner, a read-only BootPackage cap, Console, and the endpoint owner caps needed to reconstruct the default demo graph. Init reads bounded manifest chunks into a metadata-only capos-config::ManifestBootstrapPlan, validates binary references, authority graph structure, exports, cap sources, and interface IDs, then spawns the default smoke services. 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. system-spawn.cue remains as a narrower init-owned graph for focused ProcessSpawner validation.

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 now resolves only init’s bootstrap caps. Init performs service execution in two userspace passes. The preflight pass walks services in manifest order, resolves kernel and service-sourced caps against init grants and prior exports, and rejects an unstartable graph before spawning children. The spawn pass grants caps in declaration order, records declared exports, and attenuates endpoint exports to client-only facets for importers.

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, and schema-version storage.
capos-config/src/validation.rs - manifest graph, binary-reference, and bootstrap capability-source validation policy.
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 - bootstrap cap creation and CapSet entry construction for init.
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 - BootPackage manifest reader, graph preflight, generic spawn loop, hostile spawn checks, and child waits.
system.cue and system-spawn.cue - default and focused init-owned 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 init-owned manifest execution, init-side BootPackage manifest reads, graph validation, spawning, hostile spawn failures, child grants, process waits, and cap-table exhaustion checks.
make run-spawn validates the narrower system-spawn.cue ProcessSpawner graph.
make generated-code-check validates schema-generated Rust stays in sync.

Open Work

Retire the remaining generic kernel service-cap resolver and move the long-term manifest shape toward a boot package plus init configuration.

Keyboard shortcuts