feat(snapshot): add managed clone provider transaction

[ericksoa]

Summary

Adds the provider-owned transaction surface that will eventually prepare, accept, commit, and roll back a managed snapshot clone handoff. The dependency surface is available to later integration, but this slice remains dormant: the production snapshot action does not call it.

The transaction uses opaque provider receipts and exact immutable authority, with no Docker/Podman/MXC switch in central orchestration.

Related Issue

Part of #7744

Changes

• Add provider-neutral prepare, accept, commit, rollback, and incomplete-create cleanup for managed clone handoff.
• Bind every phase to exact provider identity, transaction identity, source runtime snapshot, destination sandbox, and immutable clone plan.
• Freeze and revalidate provider receipts across callbacks and reject phase, provider, transaction, destination, or authority drift.
• Expose the provider transaction through the snapshot dependency surface for later wiring.
• Keep the dependency unused by the production snapshot action and prove that dormancy explicitly.
• Preserve compatible snapshot test mocks while adding the dependency seam.
• Document provider ownership and deferred production integration.

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:
• 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: Exact-head review covers opaque provider authority, immutable receipts, exact transaction phases, rollback/cleanup ownership, and the dormant production boundary.
• 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 completed changes
• Result: docs-updated
• Evidence: Reviewed src/lib/onboard/lifecycle-contracts.md and the exact provider/dependency boundary at head/base 61c0137b569a942bc0f25111571bf9ddeabe38dc / e2467ea4d54ae6e792c29a94371d1d41926a9bb4. The contract remains provider-owned, MXC-neutral, dormant, and byte-identical at stable patch ID d15ce3bf05ecc904b18e3a04d3dddfd204f318b1; no buildless or Podman support is activated or advertised.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• Exact locally validated head/base: 61c0137b569a942bc0f25111571bf9ddeabe38dc / e2467ea4d54ae6e792c29a94371d1d41926a9bb4.
• Review budget: 5 files, +1,343/-2.
• Stable patch ID: d15ce3bf05ecc904b18e3a04d3dddfd204f318b1.
• The canonical channel-state fixture passed 4/4 and pre-push CLI typecheck passed on the exact head.
• Every branch commit is SSH-signed, contains a DCO trailer, and is GitHub Verified.
• 23 focused provider-transaction and dormancy tests passed on the byte-identical refreshed slice.
• Biome, Markdown lint, and git diff --check passed on the exact head.
• The preserved eager dependency seam is included here with compatible test mocks.
• Source-boundary coverage proves the production snapshot action does not call the transaction.
• No runtime-specific central switch, production clone activation, or public support claim exists.
• Applicable broad gate passed — exact-head required CI, both advisors, CodeRabbit, and protected E2E are the broad remote gates.

Risk Plan

• Primary risk: committing or rolling back a transaction using a receipt from another provider, destination, phase, or clone plan.
• Containment: normalized immutable receipts are revalidated at every phase and cleanup remains provider-owned.
• Regression risk: exporting a dependency can break existing snapshot mocks or accidentally activate a caller. Focused tests cover compatible mocks and an explicit no-call boundary.
• Rollback: the five-file slice is dormant and independently revertible.

Stack

• Base: merged PR3.9A feat(snapshot): prepare immutable managed clone handoff #8032, exact squash commit e2467ea4d54ae6e792c29a94371d1d41926a9bb4 on main.
• This slice: PR3.9B, branch feat/managed-clone-provider-transaction, exact head 61c0137b569a942bc0f25111571bf9ddeabe38dc.
• Next: PR3.9C adds the Hermes broker boundary on this exact parent.
• Buildless and Podman support remain disabled until the complete all-agent, multiarch, GPU/local-inference, recovery, installer, and protected-E2E gates in [Epic] Support native Podman with buildless managed onboarding #7744 pass.

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

Summary by CodeRabbit

• New Features

  • Added secure managed snapshot cloning with provider validation, credential checks, and destination ownership controls.
  • Added creation tracking, rollback support, and safe repeatable cleanup.
  • Expanded snapshot clone status and outcome reporting.

• Bug Fixes

  • Prevented uncertain or ambiguous provider operations from claiming ownership.
  • Kept standard production restores isolated from managed clone provider operations.

• Tests

  • Added comprehensive coverage for provider creation, reuse, cleanup, rollback, failures, and stale state handling.

• Documentation

  • Updated lifecycle documentation to describe managed cloning and cleanup behavior.

[ericksoa]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.