Installable System Backlog

Detailed decomposition of Installable System: an installed, persistent capOS that boots from disk and keeps mutable system configuration across reboots, composed with the immutable boot manifest.

docs/tasks/README.md links here. Installable System became the selected milestone after the Device Driver Foundation closeout and is now closed for the bounded local/QEMU installable-system contract. The behavior track below landed through item 8, and item 9 reconciled the proposal/body wording to the landed install, provision, update, and rollback contracts. This milestone does not pull public L4 ingress, AWS/Azure live support, direct-remapping production hardware, userspace smoltcp/L4 readiness, secure boot/signing, or production release authority into selected scope.

Landed Foundations (What This Builds On)

These contracts exist today and the track decomposes against them, not against the proposal’s projected shapes. Present tense is landed behavior.

Divergences From The Proposal (Structural Reconcile Closed)

The proposal was written before the storage prerequisites landed and projects shapes that differ from the landed contracts. The initial reconcile task recorded the landed storage contracts and placement decisions before the behavior track ran; the behavior track then landed through item 8 below. The structural docs reconcile task updated the proposal’s structure and body wording to the landed install, provision, update, and rollback contracts without broadening selected scope.

• On-disk layout. The proposal projected three partitions (boot / system / data) on the installed disk. The base make image raw boot image still produces a single hybrid BIOS+UEFI image with one GPT ESP, and the co-located CAPOSST1 Store + CAPOSWF1 writable filesystem remains available as a separate data-region image for the focused storage and early data-region smokes. The landed installable-system disk path no longer stops there: task 5 (installable-bootable-disk-system-data-regions) folds that co-located data-region image into the bootable disk as GPT partition 2 at the fixed data-region LBA, so make run-installable-disk boots from one disk carrying both the ESP and the persistent data region. Tasks 2-4 describe the separate auto-mounted data-disk model they originally built on; item 5 is the landed integrated single-disk packaging.
• Persistent naming. The proposal stores the overlay “under a well-known system Namespace root (system/config/<generation>)”. The landed Namespace is RAM-only and does not survive reboot. Persistent naming and the active/known-good pointers are therefore grounded in the landed writable filesystem (CAPOSWF1 paths and small marker files) plus the content-addressed persistent Store (CAPOSST1) for immutable generation objects. No new persistent-Namespace kernel cap is assumed.
• Generations and epochs. No landed Store, Namespace, or SystemManifest schema carries a system-generation/epoch field today (other caps such as AccountRecord and the DDF revocation generations do, but not the installable-system path). The monotonic epoch + content hash the proposal relies on for stale-write rejection and rollback are carried inside the overlay’s own capnp object and the writable-filesystem marker files, not by extending Store or Namespace.
• Composition machinery. Landed in track item 3 (2026-05-26): the SystemConfigOverlay capnp object plus SystemManifest.extensionPoints, and init’s read/decode/validate/compose with base-pins-win / overlay-adds-within- declared-extension-points / no-new-authority precedence and fail-closed base-floor fallback (make run-installable-overlay). Generation/rollback selection of which overlay is active landed in task 4, and the install/provision/update/rollback flows landed in tasks 6-8.

Ordered Track

Each item names its acceptance and the landed APIs it builds on. Dispatchable records live under docs/tasks/ with the same ids.

1. installable-system-proposal-reconcile (docs). Done 2026-05-26. Reconciled installable-system-proposal.md to the landed contracts above: single hybrid ESP boot image (no three projected partitions), persistent config region grounded in the writable filesystem + content-addressed persistent Store, RAM-only Namespace (naming/pointers are writable-filesystem files), and no system-generation field on the Store/Namespace/SystemManifest path. Recorded the data/system region placement decision. The structural proposal/body wording update is closed by item 9. Builds on: all five storage/boot prerequisites.

2. installable-data-region-boot-mount (behavior). Done 2026-05-26 02:02 UTC. Wires the persistent data region (the co-located CAPOSST1 Store + CAPOSWF1 writable filesystem) into the boot path: under the installable_data_region kernel feature, run_init best-effort calls cap::grant_data_region, which mounts the auto-attached data disk, scopes a writable Directory to the system/config subtree (writable_fs::mount_config_root), and grants init that Directory (data-config) plus the persistent Store (data-store) under well-known CapSet names – granted together or not at all. It fails closed wholesale to the base manifest (caps unchanged, “no data region; base floor” diagnostic) when the disk is absent, has a malformed superblock, or is missing the system/config root; the disk caps stay out of the manifest so the fail-closed boots do not abort on a mandatory cap. No new kernel cap type or schema change. Proof: make run-installable-data-region boots the same ISO three times – seeded disk (init prints the resolved system/config contents), no disk (base floor), and zeroed-superblock disk (base floor). Builds on: writable_fs.rs, persistent_store.rs, the co-located image tool (--seed-config), and run_init.

3. installable-config-overlay-schema-and-merge (behavior, schema). Done 2026-05-26 02:55 UTC. Added the persistent SystemConfigOverlay capnp object (overlay version, monotonic epoch, SHA-256 content hash, additional services, network/runtime settings, account-store location) and the SystemManifest.extensionPoints declared extension points (ManifestExtensionPoints: additional-services allowance/count, allowed service caps, minOverlayEpoch, settings allowances – closed by default). Init now reads system/config/overlay.bin from the granted config region, decodes it (SystemConfigOverlay::from_capnp_bytes re-validates the overlay version and content hash), and composes it over the base plan (compose_onto): base pins win (no base-service-name or init collision), overlay services name only base-shipped binaries and request only allowedServiceCaps (no new authority classes), epoch >= minOverlayEpoch, count <= maxAdditionalServices, and carried settings require their allowance. Any schema-invalid, version-mismatched, content-hash-mismatched, stale-epoch, extension-point-violating, or missing overlay is rejected whole; init boots the base floor and surfaces [init] overlay rejected: <reason>. Host encoder tools/mkmanifest mkoverlay bin emits the overlay bytes (filling the canonical hash); tools/mkstore-image --writable --seed-overlay seeds system/config/overlay.bin. Proof: make run-installable-overlay boots the same featured ISO three times – valid overlay (the overlay-extra service runs), base-pin collision (rejected, base floor preserved), corrupt overlay (rejected, base floor). Did NOT add generations/rollback (task 4). Builds on: task 2, capos-config manifest validation, schema/capos.capnp SystemManifest.

4. installable-system-generation-rollback (behavior). Done 2026-05-26 03:41 UTC. Userspace-only over the already-granted persistent Store + writable system/config Directory; no schema or kernel change. Represents system-config generations as content-addressed Store objects keyed by SHA-256 (immutable, deduped), tracks the known-good active pointer and a staged/attempting candidate pointer as monotonic-pointer-epoch marker files (gen-active/gen-candidate) in the writable config region, records a boot attempt durably before applying a candidate, and auto-falls-back to the known-good generation when a candidate is left unconfirmed (a boot that does not reach the health checkpoint) – the brick-proofing guarantee. Also promotes a confirmed candidate, rolls config back to a retained prior generation (monotonic pointer advance pointing at older content), and rejects a stale/replayed (lower-or-equal-epoch) pointer. init/src/main.rs run_generation_rollback_checks, gated by a base service named generation-proof, exercises all of this end-to-end against the real durable primitives with observable [gen] ... assertions. Did NOT add the installer (task 6) or update flow (task 8). Proof: make run-installable-generation boots a --seed-config disk twice – boot 1 exercises the full mechanism in one boot and durably leaves an unconfirmed attempting candidate; boot 2 re-reads the committed markers from a fresh mount and proves across-reboot auto-fallback to the known-good generation. Builds on: task 3 and the persistent Store/writable filesystem durability.

5. installable-bootable-disk-system-data-regions (behavior). Done 2026-05-26 04:31 UTC. One integrated bootable disk now carries the boot ESP (GPT partition 1) and the co-located CAPOSST1 Store + CAPOSWF1 writable data region (GPT partition 2), and boots through the landed task 2-4 path reading the data region from the same disk it booted from – not a separate smoke-only drive. tools/mkdiskimage.sh gained --data-image / --data-offset-bytes (it folds the tools/mkstore-image --writable image into a second GPT partition) and derives the ESP size from --esp-sectors (the integrated disk uses the same 128 MiB ESP as the raw disk-image targets so a debug kernel fits). The kernel installable_disk feature (implies installable_data_region) adds a fixed data-region base LBA (cap::data_region_base_lba = 264192) applied at the single persistent_store/writable_fs read_range/write_range choke points; the kernel trusts that fixed tool/kernel layout contract rather than parsing the GPT, exactly as the superblock LBAs already are. Proof: make run-installable-disk builds one disk (boot ESP + seeded data region carrying a valid config overlay) and boots it as a single virtio-blk device; the gate is data region: mounted from the boot disk plus [overlay-extra] started via overlay – a service only the data region supplies – not a clean boot alone. Did NOT add the installer (task 6). Builds on: mkdiskimage.sh, tools/mkstore-image --writable, task 4.

5a. ddf-multi-virtio-blk-device-support (behavior, DDF milestone). Lift the single-virtio-blk limit (per-device driver instance, DMA pool key, interrupt route, PCI claim) and add a target-disk BlockDevice/Store grant source scoping a cap to a specific device. Owned by the Device Driver Foundation milestone (docs/backlog/hardware-boot-storage.md “Reusable Block-Device Path”); the install flow depends_on it. Builds on: the landed device-agnostic transport seam and per-queue-keyed DMA ledger.

5b. installable-userspace-image-source (behavior, DONE 2026-05-26 08:15 UTC). Expose a userspace-readable read-only packaged-image source so a userspace installer can read the packaged boot/system bytes. Chosen shape: a QEMU-gated read-only Directory/File cap over the existing boot_iso ISO 9660 reader (kernel/src/iso/), not the boot-package payload alternative and not a general post-bootstrap filesystem service. The installable_image_source grant source (KernelCapSource @45) mounts the booted CD-ROM ISO 9660 /boot/bins/ tree and serves Directory.list/open

• File.read/stat; every mutating method fails closed. It is physically scoped to the ATAPI CD-ROM medium and cannot reach or mutate the writable virtio-blk target disk (blockDeviceTarget/writableFsRoot) – that write authority belongs to the install flow (task 6). Offsets/lengths are validated against the file extent before any device access, reusing the driver’s in-bounds checks; a past-EOF read clamps to empty and an absent name is rejected. Broader package browsing remains userspace-service work rather than an expansion of this fixture. Proof: make run-installable-image-source (kernel cap module kernel/src/cap/installable_image.rs; consumer demo demos/installable-image-source/; manifest system-installable-image-source.cue; harness tools/qemu-installable-image-source-smoke.sh). Builds on: task 5, the boot_iso ISO 9660 reader.

6. installable-system-install-flow (behavior). Done 2026-05-26 10:12 UTC. The capos-system-install userspace service (demos/installable-system-install/) installs a bootable capOS onto a blank target disk using only two granted caps: the read-only installable_image_source Directory over the booted CD-ROM /boot/bins/ and the target-scoped block_device_target BlockDevice selected by manifest PCI identity, never the boot disk. It copies the packaged bootable boot-region head (BOOTHEAD.BIN: protective MBR + primary GPT + the FAT ESP with Limine + release kernel + base manifest) to LBA 0, writes the backup GPT (BOOTGPT.BIN) at the LBA read from the primary GPT header (Limine validates it), and initializes an empty data region (DATAIMG.BIN: empty CAPOSST1 Store + CAPOSWF1 filesystem with just the system/config directory) at the fixed cap::data_region_base_lba. It validates every sector range before writing and verifies the read-back. The empty data region is the install floor; the operator’s first non-empty config generation is provisioning (task 7), not install. Proof: make run-installable-install – pass 1 installs into the manifest-selected virtio-blk target disk; pass 2 boots that disk standalone (no CD-ROM) and reaches the base service with its data region mounted (data region: mounted + [init] data-region mounted: system/config entries=0 + [console-paths] Console paths ok.), not a clean boot alone. The build packages the boot region split into head + backup GPT (tools/split-boot-region.py) so the installer reads only the populated ~15 MiB over the slow ATAPI PIO path rather than the whole FAT32 ESP. Did NOT add provisioning (task 7) or update/rollback (task 8). Builds on: task 5, the BlockDevice sector path, content-addressed Store, and the precursors 5a ddf-multi-virtio-blk-device-support and 5b installable-userspace-image-source.

7. installable-system-provision-flow (behavior). Done 2026-05-26 11:09 UTC. The capos-system-provision userspace service (demos/installable-system-provision/) runs as PID 1 over an installed system’s persistent data region and performs the proposal’s “Provision” flow, holding only three caps: a Console, the writable filesystem root (writable_fs_root, navigated to system/config), and the content-addressed persistent Store (persistent_store). On a disk whose system/config carries no active generation yet (the empty install floor task 6 leaves), it writes the operator’s first non-empty SystemConfigOverlay generation (epoch 1: an operator AccountRecord stored as a content-addressed Store record named from the overlay’s accountStoreLocation, a hostname, a log level, and one additional service), commits the generation object to the Store, writes system/config/overlay.bin (the shape init’s apply_config_overlay consumes, proven by task 3), and advances the gen-active pointer. It dispatches on durable state: a second boot of the same disk re-reads the gen-active pointer, resolves the generation object and operator account from the Store, and verifies the provisioned account/settings are the active durable config that survived the reboot. Did NOT add the update/rollback flow (task 8); reuses the overlay object and the existing AccountRecord schema with no schema change. Proof: make run-installable-provision boots the same --empty-config disk twice – pass 1 provisions and commits, pass 2 verifies the active generation + operator account + settings survived; a clean boot alone is not the gate. Builds on: task 6 (the empty install floor), task 3 (the overlay object and merge), task 4 (the generation/gen-active representation), and the writable-filesystem + persistent-Store durability.

8. installable-system-update-rollback-flow (behavior). Done 2026-05-26 11:35 UTC. The capos-system-update userspace service (demos/installable-system-update/) performs the proposal’s “Update” flow on top of the landed generation/rollback mechanism (task 4), userspace-only over the same three caps provision holds (Console, writable_fs_root navigated to system/config, persistent Store); no schema or kernel change. It writes a new SystemConfigOverlay generation into the content-addressed Store as a new root hash (old generation objects remain; the shared operator AccountRecord dedups), stages it as an attempting gen-candidate pointer without advancing the known-good gen-active pointer, and on the next boot commits by advancing active only when the candidate reaches its health checkpoint – otherwise the boot-attempt-vs-confirmed auto-fallback keeps the prior known-good. The overlay re-validation against the new base reuses the production SystemConfigOverlay::compose_onto against a base plan whose extension points revoked the overlay’s authority, so an update whose new base no longer admits the overlay falls back to the base floor with a surfaced error rather than applying. The data region (operator account + active config) is carried across every transition. It dispatches on durable state (update-phase marker) so commit-on-success and auto-fallback are both proven across a REAL reboot, not one process. Proof: make run-installable-update boots the same --empty-config disk THREE times – boot 1 provisions known-good gen1, rejects an overlay against a revoked-cap new base (kept base floor), and stages a healthy candidate gen2; boot 2 commits gen2 across the reboot and stages a failing candidate gen3; boot 3 auto-falls-back from gen3 across the reboot to known-good gen2 – distinct per-generation content hashes and a stable account hash on every line, the staged/commit/fallback/ marker-survival/data-region-carried assertions, not a clean boot alone. Builds on: task 6 (the install floor), task 7 (the provision/overlay shape), task 4 (the generation/gen-active/gen-candidate representation), and task 3 (overlay compose/validation).

9. installable-system-structural-doc-reconcile (docs-status). Done 2026-06-07 18:20 UTC through commit 12b8334a (committed 2026-06-07 18:19 UTC). Reconciled Installable System structural and body wording to the landed local/QEMU data-region, overlay, generation, install, provision, and update/rollback contracts. Preserved the RAM-only Namespace caveat and kept secure boot/signing, production release authority, public ingress, AWS/Azure live support, direct-remapping production hardware, userspace smoltcp/L4 readiness, and full durable account policy out of the closed Installable System scope.

Design Grounding

• Installable System – the design being decomposed.
• Hardware, Boot, and Storage – the Local Disk Storage, Writable Local Storage, and Bootable Disk Image milestones the landed prerequisites came from.
• Local Users, Storage, and Policy – the account store, a consumer of the persistent-config region.
• Run Targets, Init Mandate, and Default-Run Integration – the init mandate and boot-manifest policy any installed-system boot path must respect.
• Storage and Naming – the Store/Namespace/Directory/File model, content-addressing, and attenuation the persistence layer reuses.
• Manifest and Service Startup – the immutable base manifest the persistent overlay composes with.