Repository navigation
Description
Status
Owner-approved architecture direction on 2026-11-13 (decision record), not an implemented guarantee or authorization to publish. Governing program: #5415. Existing accepted ADR-001, ADR-037 and ADR-055 remain authoritative; the composable-pack format/policy/clock still need reviewed durable changes; landed ADR-059 is a preview design and grants no warm authority.
Goal and approaches
One authored workload should produce a portable, immutable and independently verified production artifact without giving its author, a local host signer, a cache, or a development run production authority. Three shapes were considered:
| Shape | Advantage | Why not the first production path |
|---|---|---|
| Compose at boot | Potentially shared runtime disks | Requires a new boot ABI and mutable external dependencies at launch. |
| Compose at install from external layers | Smaller application download | Breaks the self-contained offline-verifiable artifact boundary. |
| Compose at package build (recommended) | One sealed, signed boot closure and existing admission contract | Repeats runtime bytes across application bundles; cache verified inputs during build instead. |
Recommended contract
- Authoring and format: In
mvm, lower the existing narrowmvm.pack-spec/v2TOML/SDK front end into a frozen, versioned lock over one application, ordered exact-version/manifest-digest-pinned runtime inputs, and a selected signed base and guest runtime. Make a new schema-9 self-contained.mvmpkgwith an explicit production composition member distinct from the existing schema-8 host-local Dev member; retain published v1, schema-2 descriptor and complete-bundle meanings. Do not silently fall back to Nix, a different base, an old schema or an unverified tool graph. Broader multi-application/tool graphs require a later reviewed version. - Producer and trust: The builder materializes candidate ext4/verity but has no release key. A separate protected verifier checks frozen source, signed descriptor and policy bytes, immutable selected base/runtime, archive/member hashes, actual selected entrypoint and health-boot subject before authorized signing.
mvm-packspublishes only after its compatible producer andmvmconsumer both refuse incomplete evidence, independent publisher/bundle trust, stale or rolled-back revocations and mismatched output. Every release needs exact source, signer, descriptor, distribution-rights authorization and readback. Local or PR-only signatures never enroll an official publisher. - One authority path: An authenticated
mvmdrequest is the only production launch origin (ADR-037). A local CLI or SDK may build, inspect and test a production-shaped archive but executes only in development posture. The existing signed-plan, policy, host-grant and backend admission owner checks the selected closure on every run, including cache hits; no component can grant itself egress, secrets or writable host paths. A Dev-onlyrun --composeproof remains one-use, invocation-private and ineligible for install, export, production or later warm claim. - Warm custody: Extend the existing
TrustedSnapshotServiceand backend contract with an owned generation-bound read lease over the exact authenticated boot closure. Budget sealed Linux memfds and parent/FD residency; use inode-pinned fs-verity for large inputs only after independent provider evidence. Hold descriptors through the actual VMM's last child. No pathname, reflink, permission bit or cache hit substitutes for immutable custody; missing support, stale handles, owner loss or exhaustion refuses warm before execution. APFS and other unwitnessed providers stay unsupported. - First target: Production claim and speed gate start on x86_64 Linux/KVM/Firecracker. arm64 Linux and macOS/HVF retain development evidence but must refuse unsupported production/warm guarantees until their own signed-output, custody, admission and latency witnesses exist. No guest NIC or SSH is introduced.
- Clock and release gate: Report acquisition, first-use publication/build, signed-bundle verification, prepared cold, warm claim and replacement separately. Fresh verification and admission must not move outside the required invocation-to-readiness witness. The accepted cold <300 ms and warm <50 ms requirements remain in force; reconcile the prepared-artifact lane's separate verification clock with ADR-001 before accepting a production latency report. Run adversarial and backend witnesses on the exact candidate bytes before publication.
Decisions required before implementation
- Review the schema-9 composition/provenance floor with the
mvmandmvm-packsformat owners; proposed application/runtime components remain unpublishable until both sides and protected signing are ready. - Resolve the currently conflicting egress policy-merge descriptions into one tested deny/ceiling rule and confirm the production clock with the security and performance owners. Do not ship an alternative merge rule in a composer.
- Review the typed owner/descriptor lease API in landed ADR-059 before wiring warm claims; merged fix(runtime): guard trusted snapshot publication lifecycle #5407 covers reservation/generation guards, not VMM-lifetime custody. No direct-VMM probe or mock is a live backend witness.
- Approve any narrowing of draft PR feat(pack): stage portable composition from current main #5326 to a Dev-only preview separately. Its existing warm/speed acceptance items are not silently completed or deleted.
Existing authority
mvmADR-001, ADR-037, ADR-055, composable-pack build contract, performance reference.mvm-packsproposed ADR 004, ADR 005, ADR 006; no new component publication follows from these proposals.- ADR-059 now records the accepted preview direction; merged #5407 guards snapshot publication lifecycle but enables no VMM read lease or warm claim. Draft #5326 remains candidate evidence, not shipped authority.
Data and lifecycle shape
PackSpecV2 (authored intent) → frozen exact input lock → protected complete bundle + registry descriptor (two independent signatures/trust roots) → installed digest pin → fresh signed plan + authenticated mvmd origin → admitted backend start. The optional warm branch reserves and seals that same authenticated boot closure, issues a generation-bound owner handle, yields an owned VMM read lease and admits each child afresh; removing/quarantined states cannot become claimable. Audit and receipts distinguish verified build, admitted start, guest-ready child and terminal outcome.
Spikes and decision rules
- Descriptor custody (timebox: one focused Linux spike): hand a bounded sealed kernel/rootfs/runtime closure through the scoped Firecracker launcher, then inspect the objects the VMM actually holds; test mutation, renamed path, budget exhaustion and owner restart. Proceed to warm wiring only if the owner keeps a generation-bound descriptor lease until the last child and every failed transition remains unclaimable. Otherwise keep warm unsupported and revise the provider plan; a direct-VMM probe alone fails this rule.
- Latency decomposition (timebox: one named-host measurement run): on a provisioned x86_64 KVM host, time acquisition, first-use publication, verified input reuse, fresh admission, backend start and readiness separately on the exact candidate. Proceed with the <300 ms/<50 ms architecture only if the measured critical path has a plausible bounded route without skipping authorization; otherwise identify the dominant phase and revisit design before optimizing or publishing a speed claim.
- Offline closure (timebox: one verifier fixture): reconstruct the exact complete bundle and signed input proofs from a clean cache with a still-valid revocation feed. Proceed with the schema-9 floor only if an offline verifier can refuse one changed input, missing signed policy or rolled-back feed without consulting a developer's local signer or source tree. Otherwise return to format-owner review; do not sign an official descriptor.
Activity
auser commentedon Nov 13, 2026
Wave 0 review agenda
The program is planned, not approved for implementation or release. These four independent decision packets are ready for the appropriate owners:
No box in epic #5415 should close from these proposals alone. After owner/format review, record the accepted durable contract or ADR changes, then plan dependent implementation tickets against those exact accepted revisions. No existing PR branch was changed by this planning work.
auser commentedon Nov 13, 2026
Owner decision — 2026-11-13
The owner approved the recommended planning and contract directions in the Wave 0 review agenda:
Scope of this approval: architecture direction and permission to plan its smaller tickets. It does not approve a specific wire encoding, implementation, branch merge, official signer, package publication, or production release. #5413 and epic #5415 remain open; each acceptance checkbox closes only after its own reviewed code, exact-head validation and required live evidence.