Add the vmFacts runtime export plan #31

Merged

vnprc merged 3 commits from agent/vmfacts-runtime-contract into master

2026-08-01 02:53:20 +01:00

allod-agent commented

2026-07-31 12:23:23 +01:00

Member

Adds the dev plan for the remaining half of the microvm arc's contract 1: exporting the inventory runtime fact through archetypes.vmFacts.<name>.runtime. Inventory's half already landed; this is the third source of truth that contract makes agree.

It is planned as its own slice, ahead of the rest of milestone 4, because contract 18 makes both allod/nexus key-rotation tools dispatch on this exact attribute — allod/nexus#21 and allod/nexus#22 cannot start until it exists.

Implementation is tracked by allod/archetypes#27 and is one additive field in nix/vm-facts.nix plus check coverage in flake.nix.

Risk

Plan document only; no runtime behavior. The change it plans is scored R2 Medium: vmFacts is a public flake output read host-side by allod/nexus, so adding a field is a public interface change with cross-repo ordering, held below R3 by being additive-only with every consumer across seven repos enumerated and verified inert.

Validation

Reviewed by an independent agent that verified empirical claims against the tree rather than reading the prose. It returned no blockers and four majors, all folded:

The proposed negative proof for the coherence check was not workable as written — the stdenv's set -eu would have made the deliberately-failing invocation abort the builder, and the natural fix (|| true) would have made the proof vacuous. The plan now specifies return 1 over exit, an if-guarded negative call, a grep pinning the failure to the diff rather than to any failure, and a sabotage value inside the valid enum so nothing else can satisfy it.
An in-check enum assertion would have been unfalsifiable by construction, since inventory's checkedMachines trip-wire already guarantees it. The plan now declines to add it and says why, keeping contract 1's enum command as a manual acceptance test.
One sabotage step was not executable as stated: deleting the presence guard raises a missing-attribute EvalError, which tryEval does not catch, so the check aborts opaquely instead of naming the fixture. The plan now predicts that actual outcome and records that the guard's job is to name the error, not to create it.
The claim that a deploy flake calling lib.mkVmFacts with its own data would inherit inventory's enum was false, and the reviewer demonstrated the bypass. The plan now records it as an accepted, inert gap with the mitigation named: contract 18's consumers must fail closed on an unrecognized runtime.

Six minors and four nits — wrong line numbers, an incomplete consumer enumeration missing allod/deploy, and an over-claimed test rationale — were also folded. The reviewer independently reproduced all four libvirt drvPath hashes in the acceptance table and re-derived the consumer-compatibility conclusion without finding a counterexample.

Refs allod/strategy#20

Adds the dev plan for the remaining half of the microvm arc's **contract 1**: exporting the inventory `runtime` fact through `archetypes.vmFacts.<name>.runtime`. Inventory's half already landed; this is the third source of truth that contract makes agree. It is planned as its own slice, ahead of the rest of milestone 4, because **contract 18** makes both allod/nexus key-rotation tools dispatch on this exact attribute — allod/nexus#21 and allod/nexus#22 cannot start until it exists. Implementation is tracked by allod/archetypes#27 and is one additive field in `nix/vm-facts.nix` plus check coverage in `flake.nix`. ## Risk Plan document only; no runtime behavior. The change it plans is scored **R2 Medium**: `vmFacts` is a public flake output read host-side by `allod/nexus`, so adding a field is a public interface change with cross-repo ordering, held below R3 by being additive-only with every consumer across seven repos enumerated and verified inert. ## Validation Reviewed by an independent agent that verified empirical claims against the tree rather than reading the prose. It returned no blockers and four majors, all folded: - The proposed negative proof for the coherence check was not workable as written — the stdenv's `set -eu` would have made the deliberately-failing invocation abort the builder, and the natural fix (`|| true`) would have made the proof vacuous. The plan now specifies `return 1` over `exit`, an `if`-guarded negative call, a `grep` pinning the failure to the diff rather than to any failure, and a sabotage value inside the valid enum so nothing else can satisfy it. - An in-check enum assertion would have been unfalsifiable by construction, since inventory's `checkedMachines` trip-wire already guarantees it. The plan now declines to add it and says why, keeping contract 1's enum command as a manual acceptance test. - One sabotage step was not executable as stated: deleting the presence guard raises a missing-attribute `EvalError`, which `tryEval` does not catch, so the check aborts opaquely instead of naming the fixture. The plan now predicts that actual outcome and records that the guard's job is to name the error, not to create it. - The claim that a deploy flake calling `lib.mkVmFacts` with its own data would inherit inventory's enum was false, and the reviewer demonstrated the bypass. The plan now records it as an accepted, inert gap with the mitigation named: contract 18's consumers must fail closed on an unrecognized runtime. Six minors and four nits — wrong line numbers, an incomplete consumer enumeration missing `allod/deploy`, and an over-claimed test rationale — were also folded. The reviewer independently reproduced all four libvirt drvPath hashes in the acceptance table and re-derived the consumer-compatibility conclusion without finding a counterexample. Refs allod/strategy#20

allod-agent added 1 commit

2026-07-31 12:23:23 +01:00