feat(runtime): persist engine lifecycle and state mutation contract

[ericksoa]

Summary

Adds a dormant, provider-neutral persisted engine lifecycle and exact-runtime state-mutation contract on top of the managed bootstrap transaction in #8052. The batch binds snapshot, clone, rebuild, backup, restore, and recovery to durable engine authority, then defines a mandatory supported-or-unsupported stateMutation facet that future Docker, Podman, and MXC-style providers can implement without central runtime switches.

This does not activate Podman or change default onboarding. New managed-image onboarding remains reachable only through the hidden, undocumented --temp-managed-runtime experiment gate inherited from #8261. Podman remains absent from the production provider registry, and its state-mutation facet remains explicitly unsupported until the recovery qualification slice.

Related Issue

Part of #7744.

Changes

• Define versioned lifecycle actions and resource roles for snapshot creation, snapshot clone, rebuild, backup, restore, and recovery.
• Bind each transaction to the exact provider, engine authority, endpoint authority, source and target runtime IDs, runtime-state digest, and acceleration-state digest.
• Record restart-safe transaction phases, one exclusive process-owned mutation lease, target-position-bound commands, completion receipts, and an exact retirement tombstone.
• Revalidate persisted authority, injected engine, runtime handles, state digest, and execution lease before and after mutation and during recovery.
• Define a versioned declarative state-mutation plan derived from an agent projection, with bounded selectors and stable plan/projection SHA-256 bindings.
• Reject executable commands, callbacks, unknown fields, traversal, system roots, control characters, duplicate or oversized selectors, noncanonical digests, accessors, sparse arrays, inherited serialization hooks, and non-scalar Unicode.
• Require provider-owned acquire, fence assertion, activation, and recovery operations before state mutation can be enabled.
• Keep Docker, Kubernetes, Podman, and the MXC-style test provider explicitly unsupported for state mutation in this dormant contract slice.
• Preserve real Docker managed-bootstrap support from feat(runtime): add dormant Podman managed bootstrap transaction #8052 while keeping Podman bootstrap/state mutation out of production selection.
• Add focused lifecycle, contract, Podman-dormancy, adversarial validation, MXC-style pluggability, and source-shape coverage.
• Document the internal lifecycle ownership and deferred GPU/provider activation boundary in src/lib/onboard/managed-bootstrap/README.md.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: The batch is internal and dormant. Its ownership and activation boundary are recorded only in the internal managed-bootstrap README; no public support surface changes.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: The persisted authority tests cover restart, drift, filesystem, command-scope, lease, and tombstone boundaries. The imported provider-neutral contract is the reviewed and hardened logical change from feat(runtime): define provider state-mutation contract #8186 at d167fb83c, including fixes for inherited serialization hooks and non-scalar Unicode aliases.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the lifecycle documentation source before batching
• Result: docs-updated
• Evidence: The internal README accurately documents the provider-neutral ledger, restart lease, exact runtime-target authority, retirement tombstone, and dormant activation boundary. The state-mutation contract adds no public CLI, configuration, default, workflow, or supported behavior.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable for this dormant contract batch.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Podman GPU and host-local inference qualification remain mandatory later slices in [Epic] Support native Podman with buildless managed onboarding #7744.

Verification

• PR description includes a Signed-off-by: line and every new commit is signed with DCO
• Normal pre-commit and pre-push hooks passed
• Targeted behavior tests pass — 147/147 focused provider, Podman, persisted lifecycle, state-mutation, and source-boundary tests passed on exact head 224748828a33
• Applicable broad local gates passed — CLI build, CLI typecheck, repository checks, source-shape budget, test-size budget, test-conditional scan with zero added test if statements, Biome hooks, git diff --check, and exact-delta secret scanning passed
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new doc pages only)

---

Signed-off-by: Aaron Erickson aerickson@nvidia.com

[apurvvkumaria]

Comment — reviewed exact head baa495a. Persisted engine lifecycle recovery is safe to merge and I found no blocking defect. Non-blocking fast follow: add a recovery contract for the case where an external mutation succeeds but the callback or receipt publication fails. The mutation-authorized retry can otherwise repeat the operation unless each provider reconciles or resumes idempotently; a narrow follow-up test would make that requirement explicit.

[apurvvkumaria]

Comment — reviewed exact head 9209d31 against its stacked base. The provider-neutral lifecycle and new host-local inference authority remain dormant; receipts use closed schemas and digest-pinned images, engine authority is operation-scoped, and requested NVIDIA devices must match the qualified CDI inventory. Focused validation passes 53 of 53 tests. No blocking correctness, security, compatibility, or regression defect found. Non-blocking fast follow: before activating this boundary, normalize host device paths before applying the raw /dev/nvidia rejection, or allowlist the exact non-CDI device forms emitted by supported launchers, so dot-segment aliases cannot bypass the intended CDI-only rule. A narrow follow-up PR covering that translator edge is sufficient; it is not reachable from the current trusted launcher subset and does not need to delay this PR. The branch currently conflicts with its stacked base, so any conflict-resolution revision needs re-review.

[cv]

Reviewed commit 9209d3180a in bottom-up stack order. This PR depends on #8056, which is not approval-ready. This lifecycle layer conflicts with its current base and has failing image, audit, CI, and E2E evidence. Review remains blocked until the parent is reconstructed or repaired, this branch is restacked on the accepted parent commit, and current CI, security, and documentation evidence passes for the resulting commit. No approval is granted for the current branch.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.