mikronova/draupnir

build-thing launch axis + the machine spine — design

Class: design · Home: draupnir, because draupnir is the hub the whole machine spine hangs from. The how-to is in build-thing-launch-guide.md. This doc is the map for the deep-wiring that connects a built artifact to a running, asserted machine, all Rust, no shell.

1. The thesis: two axes, not one list

A build-thing produces an artifact and then (optionally) launches it. Those are two different things, and conflating them is what made exe / container / kvm / iso read as one list when it is really a matrix:

kvm is not an artifact — it is a launch target. An artifact declares which targets it supports; the UI renders the launch control that fits. This is the whole correction: build-thing already has ArtifactKind ∈ {Exe,Lib,Wasm,Container,Vm,Service} (edda nornir-build-thing/src/variant.rs); what it lacks is a first-class launch axis beside the build one, and a kind-aware rendering of it.

2. The machine spine — who owns what

The launch axis only works because there is exactly one machine spine underneath, and every layer has a single job:

• tunnr — the muscle. Owns the QEMU/OVMF/KVM primitive (boot_test, src/boot_primitive.rs) and the OS-less appliance semantics (boot contract, markers, PID-1 payloads). It already boots both models: direct-kernel when a kernel is set, firmware/bootloader-in-disk when it is empty.
• draupnir — the thin seam. The boot/provisioning library: one BootSpec, ImageSource, Boot/Lifecycle, fleet fan-out, the seed builder, three backend adapters (kvm→tunnr, oci, redfish). It is the ruler from tunnr's thinnest appliance to the fattest full distro — the same axis as direct-kernel ↔ bootloader-in-disk.
• Skidbladnir — airgap-install application. Should delete its own qemu argv builder (unfold::kvm / full_argv / Command::new("qemu-system-x86_64")) and route through draupnir::kvm::KvmBoot. It already consumes draupnir::seed; the launcher is the last thing it twins.
• dwarves — the CI/CD forge. Pure orchestrator; it never instantiates a VM itself. It calls the ready-made tool (jera → draupnir → tunnr). Its run_vm today is a TODO stub — the wiring turns it into a real call.

No cycle: draupnir → tunnr-vm (feature backend-tunnr) is one-directional; the tunnr → draupnir edge lives only in leaf crates (tunnr-demo, payloads/*), never in tunnr-vm. Clean DAG, verified against the Cargo.tomls.

3. The keystone change — draupnir grows a fat-dist boot model

Today draupnir::ImageSource (src/lib.rs:124) can express direct-kernel (KernelRootfs) and kernel+disk (Disk) — but validate() requires a kernel on both (src/lib.rs:622-624), so it cannot express the kernel-less, bootloader-in-disk boot that a fat distro (and Skidbladnir's airgap install) needs. That single gap is why jera_vm_routable() is always false.

The five focused edits (all in draupnir; zero in tunnr — the engine already does it):

1. src/lib.rs:124 — add ImageSource::BootloaderDisk { disk: String } (self-booting disk, no -kernel).
2. src/lib.rs:154 — suits(): BootloaderDisk suits Backend::Kvm.
3. src/lib.rs:622 — validate(): require only the disk path, not a kernel.
4. src/lib.rs:~463 — a bootloader_disk constructor peer.
5. src/kvm.rs:74 — to_tunnr_spec: map BootloaderDisk to an empty-kernel tunnr_vm::BootSpec (tunnr firmware-boots the disk). And, while here, fix the seed drift (kvm.rs:104): use tunnr's native BootSpec::with_seed instead of hand-rolling the seed -drive into extra_qemu_args, so the seed argv is authored in one place.

This unlocks both downstream moves at once: the fat-dist launch, and Skidbladnir routing onto draupnir.

4. The launch axis — declared in the model, rendered elsewhere

The wiring adds an explicit launch action, distinct from build, to the build-thing data model (edda/crates/nornir-build-thing/src/surface.rs, state_json) — kind-aware:

• Container → DEPLOY (a future bollard podman run).
• Vm / iso → BOOT CONSOLE (a future tunnr_vm::boot_test, serial + contract markers).
• Exe → RUN (spawn + exit code).

This is a declaration of what launch a cell supports, carried in state_json for a consumer (dwarves, or a future UI) to render. Two deliberate scope lines:

• nornir is out of scope. nornir is huge and its viz (src/viz/build_tab.rs, test_boot.rs) is not touched by this wiring. The model declares the axis; where it renders is a separate decision.
• logs get their own framework. The surface exposes a typed seam (LaunchOutput { Logs, Serial }) as the hand-off point — it does not implement log/serial streaming. That is a separate framework, wired later.

No shell — when the executor is built, container work is the bollard Rust API and VM work is boot_test; neither lives in this model phase.

5. Caching & sealing

• holger is the artifact cache/store: built container/VM artifacts are content- addressed and stored via dwarves' existing HolgerArtifactStore seam, so a launch can pull a prior build instead of rebuilding.
• znippy can seal/package an artifact set, but is not required for the launch axis today — noted as optional, not wired in this pass.

6. The shell island — ported to Rust

tunnr's outer Buildroot orchestration was variants/buildroot/build.sh + board/tunnr/post-build.sh (shell). Both are now deleted and ported to pure Rust:

• tunnr-buildroot (tunnr-vm::buildroot) — the orchestrator: reuses build_rust_init for the inner PID-1, clones Buildroot via gix (behind the buildroot-fetch feature — no shelled git, law L9), and runs Buildroot make via a direct Command::new("make") (a sanctioned build-tool exec, not shell glue).
• tunnr-postbuild — the BR2_ROOTFS_POST_BUILD_SCRIPT hook as a compiled Rust binary. Because it is compiled it is executable by construction, so the post-build.sh mode-100644 / Error-126 bug is gone rather than patched.

BuildShVmBuilder calls the Rust path; the defconfigs point at the compiled hook. No shell remains in the Buildroot path — the last island is drained.

7. What the wiring touches (the deep pass)

Every row is compile-gated; nothing is reported wired that does not build.