Skip to content

Own immutable warm publications through typed read leases #5419

Open

Description

@auser

Scope

Review and implement the typed owner/descriptor publication and claim API that landed preview ADR-059 requires before any warm backend is enabled. Governing program #5415 and architecture #5413. The ADR direction is not yet a shipped warm guarantee.

Acceptance

  • Obtain owner API and lifecycle review: exact authenticated boot closure, reserved RAM/FD/parent budget, sealed publication, generation-bound nonserializable handle, owned read lease, active VMM/child references, removal and quarantined failure state. Claims accept no arbitrary source path.
  • Extend the existing TrustedSnapshotService and TrustedSnapshotBackend contracts instead of adding a parallel warm gate. Stage/validate/publish/claim/remove and cancellation must not turn a failed or stale publication into a claimable one; owner restart loses ephemeral handles and re-authenticates inputs.
  • Positive and negative hermetic tests: concurrent publication/claim/remove, stale generation, changed closure, exhausted reservations, seal failure, cleanup failure and owner crash/restart. Keep all real backends unsupported until each adapter and VMM-lifetime witness exists.

Context and validation

Start with crates/mvm-runtime/src/trusted_snapshot_service.rs, crates/mvm-fs/src/trusted_snapshot.rs, crates/mvm-runtime/src/warm_service.rs, ADR-001 and landed preview ADR-059. Merged #5407 adds ID reservation, generation and cleanup guards; current materialize(handle, destination) still does not issue an owned VMM-lifetime immutable read lease. Run focused runtime/filesystem tests, cargo clippy --workspace -- -D warnings, cargo check --workspace, cargo run -p xtask -- check-all, and gated Linux compilation when shared types change. Mock tests are not a live backend witness.

Depends on: owner/descriptor API review. Independent of: Dev preview and first schema review. Linux provider and warm-claim wiring depend on this contract.

Activity

  1. auser commented on Nov 13, 2026

    @auser
    CollaboratorAuthor

    Owner/descriptor API review packet — no warm claim enabled

    The current TrustedSnapshotService publishes an ID and later materialize(handle, destination) returns a clone strategy; the TrustedSnapshotBackend contract requires an immutable source view but gives the caller a writable destination. Neither return value owns the VMM's actual boot descriptors through its last child. Draft ADR-059 approves the direction, but it is not a shipped claim.

    Alternatives and recommendation

    1. Extend the existing service/contract with a typed owned read lease (recommended): one owner reserves a bounded exact boot closure, publishes sealed bytes, returns a generation-bound nonserializable handle, and claims an RAII lease holding the selected kernel/rootfs/runtime descriptors through VMM and child lifetime. Keep legacy cold materialization separate; it cannot be relabelled as warm.
    2. Add a parallel warm-lease manager alongside TrustedSnapshotService: superficially smaller diff, but two lifecycle owners can disagree about handle freshness, budget, removal and crash state. Do not choose this without an explicit ownership redesign.
    3. Reuse materialize(destination) as the warm witness: rejected. A writable destination, pathname or reflink is not the immutable object the VMM opened.

    Contract to approve

    • Identity binds selected signed base, kernel/initramfs, full guest runtime, component/descriptor pins, filesystem output, device shape, backend and publisher/revocation evidence. A handle contains an owner generation, not signed-plan authority. Every child gets new current revocation/policy/host-grant checks and a one-use admitted plan.
    • States are reserved → sealed → leased → removing, with failed staging/cleanup quarantined. Reserve RAM/FD/parent capacity before publication. A stale or wrong-generation handle, lost owner, changed closure, missing kernel-backed immutable provider or exhausted budget is a typed refusal, not silent cold substitution when warm was required.
    • The lease owns opened objects until the actual VMM's last child releases them. Cancellation and crash reclaim capacity without making a stale generation claimable. An owner restart loses memfds and reconstructs only after fresh authenticated input checks; a path name cannot recover authority.
    • Linux sealed memfds may back explicitly budgeted small inputs; a large-rootfs fs-verity provider needs independent inode-pinned digest evidence before selection. APFS/HVF and arm64 warm claims remain refused until independently implemented and witnessed. A trusted host is assumed; this is not protection against an active malicious host.

    Review gate

    Approve the owner/descriptor API and transition/refusal types before #5422 or #5427 changes shared runtime shapes. Tests must include concurrent publish/claim/remove, tampering, stale epoch/generation, owner crash, RAM/FD exhaustion, failed cleanup and actual scoped Firecracker descriptor identity. Mock and direct-VMM probes alone cannot claim this contract works live.

  2. auser commented on Nov 13, 2026

    @auser
    CollaboratorAuthor

    Owner approved the recommended typed owner/read-lease direction in #5413. Draft ADR-059, the owner/descriptor API, budget/crash/refusal states and actual VMM lifetime still need reviewed durable implementation and live witnesses. No warm claim is enabled or accepted by this decision alone.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions