Add public dev plan for microvm.nix framework adoption #21

Merged

vnprc merged 1 commit from agent/microvm-secret-injection-plan into master

2026-07-28 21:25:32 +01:00

allod-agent commented

2026-07-28 20:27:08 +01:00

Member

Adds the public half of a cross-boundary dev plan for adopting microvm.nix as a VM runtime in the framework.

dev-plans.md requires a cross-boundary plan to split, with the public plan a self-contained leaf executable by a public-only agent and the private plan owning integration and full-build validation. This is the public leaf: it names no machine, path, or key, and every acceptance test in it runs inside a dev VM.

The plan follows a hands-on spike rather than a design sketch. Its interface contracts were each observed in real nested microVM boots on the pinned nixpkgs and microvm.nix revisions, and the failure modes that would otherwise be silent are contract items with mutation fixtures rather than prose warnings: a credentialFiles value copied into the world-readable store as a Nix path literal, a blacklisted qemu_fw_cfg yielding no credentials while the guest boots successfully, and an empty persistent path set producing a guest that discards an agent's work at restart.

The Acceptance Tests section leans on nested boots because this stack has already paid once for a happy-path build passing while first boot stranded a machine. The mutation fixtures must be shown to fail on sabotaged input, following the pattern the archetypes mutated-registry and vmFacts negative checks already establish.

Scope deliberately excludes ephemeral per-boot host keys and the credential-brokering work in allod/strategy#13. Both are separable, and folding either in would couple a testable framework change to a question that is cheaper to answer afterwards.

Revised after review: the plan was originally titled and scoped as "secret injection", which named the arc after its riskiest unknown rather than its deliverable — credential delivery is what makes the adoption possible, not what the adoption is. Renamed to framework adoption, and two gaps that belonged to neither half are now assigned. Persistent guest state is in scope, because a read-only store image means anything not on a declared writable volume is lost at restart, and a guest that receives its credentials and then loses an agent's work has adopted nothing. The guest's network interface declaration is in scope while addressing and host TAP setup are the deployment's, so neither half assumes the other covered it. The Rollback section now states that a persistent volume is the one thing a revert does not reconstruct.

Risk

R0 for this PR — a document under dev-plans/, no code and no generated behavior. The arc it describes is scored R3 inside the plan, with the reasoning for why it is not R4 stated explicitly.

Validation

Conforms to the eight required sections in dev-plans.md. Risk is calibrated against that file's authority-of-state, blast-radius, recoverability, and validation-limits questions. Contains no private reference, satisfying the self-contained-leaf requirement.

Refs allod/strategy#20

Adds the public half of a cross-boundary dev plan for adopting microvm.nix as a VM runtime in the framework. `dev-plans.md` requires a cross-boundary plan to split, with the public plan a self-contained leaf executable by a public-only agent and the private plan owning integration and full-build validation. This is the public leaf: it names no machine, path, or key, and every acceptance test in it runs inside a dev VM. The plan follows a hands-on spike rather than a design sketch. Its interface contracts were each observed in real nested microVM boots on the pinned nixpkgs and microvm.nix revisions, and the failure modes that would otherwise be silent are contract items with mutation fixtures rather than prose warnings: a `credentialFiles` value copied into the world-readable store as a Nix path literal, a blacklisted `qemu_fw_cfg` yielding no credentials while the guest boots successfully, and an empty persistent path set producing a guest that discards an agent's work at restart. The Acceptance Tests section leans on nested boots because this stack has already paid once for a happy-path build passing while first boot stranded a machine. The mutation fixtures must be shown to fail on sabotaged input, following the pattern the `archetypes` mutated-registry and `vmFacts` negative checks already establish. Scope deliberately excludes ephemeral per-boot host keys and the credential-brokering work in allod/strategy#13. Both are separable, and folding either in would couple a testable framework change to a question that is cheaper to answer afterwards. Revised after review: the plan was originally titled and scoped as "secret injection", which named the arc after its riskiest unknown rather than its deliverable — credential delivery is what makes the adoption possible, not what the adoption is. Renamed to framework adoption, and two gaps that belonged to neither half are now assigned. Persistent guest state is in scope, because a read-only store image means anything not on a declared writable volume is lost at restart, and a guest that receives its credentials and then loses an agent's work has adopted nothing. The guest's network interface declaration is in scope while addressing and host TAP setup are the deployment's, so neither half assumes the other covered it. The Rollback section now states that a persistent volume is the one thing a revert does not reconstruct. ## Risk R0 for this PR — a document under `dev-plans/`, no code and no generated behavior. The arc it describes is scored R3 inside the plan, with the reasoning for why it is not R4 stated explicitly. ## Validation Conforms to the eight required sections in `dev-plans.md`. Risk is calibrated against that file's authority-of-state, blast-radius, recoverability, and validation-limits questions. Contains no private reference, satisfying the self-contained-leaf requirement. Refs allod/strategy#20

allod-agent added 1 commit

2026-07-28 20:27:08 +01:00