feat(runtime): persist container engine authority

[ericksoa]

Summary

Add a dormant, provider-neutral persistence contract for future snapshot, rebuild, restore, and recovery paths. These paths must compare a freshly provider-qualified container engine with its exact authority record before mutation. This slice adds the identity record and matcher only; no production lifecycle calls it, and it does not select, reconstruct, or activate Podman or any other runtime.

Related Issue

Related to #7744.

Changes

• Add a canonical versioned authority record binding one provider, operation scope, engine identity, endpoint-authority identity, and non-secret runtime binding digest.
• Add a private atomic store with write-once/idempotent semantics, stable metadata checks, bounded canonical parsing, and fail-closed symlink, ownership, permission, and conflict handling.
• Verify stored-file mode and canonical bytes through one O_NOFOLLOW descriptor in tests, avoiding a path-based check/use race.
• Add an exact matcher for a freshly provider-qualified injected engine; no production lifecycle calls the matcher in this slice.
• Exercise the contract with an MXC-style engine and keep production provider selection unchanged; source-shape coverage prevents the persistence boundary from importing managed-bootstrap implementations.
• Document the dormant ownership and deferred activation boundary in the internal managed-bootstrap map.

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: This slice is internal and dormant; its ownership and activation boundary is recorded in the internal managed-bootstrap README.
• 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: Maintainer-directed inert slice in [Epic] Support native Podman with buildless managed onboarding #7744; exact identity, filesystem, canonicalization, retry, and drift boundaries have focused adversarial tests.
• 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/managed-bootstrap/README.md, changed source comments, test titles, source-shape wording, and the PR description at exact head 269de66e5; all prior wording findings are resolved, and git diff --check passed. The append-only parent refresh to ae30b0694 preserves the exact reviewed slice diff and changes no reviewed documentation.
• Agent: Codex Desktop
• Qualification carry-forward: Exact head a2ae17e on base 03f5a3d preserves the byte-identical previously reviewed slice diff (stable patch ID 1eecb90d9b155b37b64b93c8d9c31feeb6b611d2; binary diff SHA-256 1c1968117fe5fae4894da9d74030aa39d6a6be8e8ae525c2ff2e7c594404efb6), and its source and documentation tree is unchanged from reviewed head 0fde3f9.

DGX Station Hardware Evidence

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

Verification

• Qualification-only exact head/base: a2ae17e / 03f5a3d; signed-DCO append-only cascade, stable-patch proof, byte-identical slice diff, final-tree equality, and normal pre-push hooks passed.
• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run --project cli src/lib/onboard/runtime-provider/persisted-engine-authority.test.ts (10 passed); npx vitest run --project integration test/runtime-provider-source-shape.test.ts (2 passed); CLI build and typecheck passed at exact implementation head b403f7a68; the exact head 269de66e5 reran the authority suite after the same-descriptor CodeQL repair; source-shape, Biome, diff-check, and normal push hooks pass.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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 pages only)

---

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 503de108-821b-42d7-81e3-002590693c17

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit a2ae17e in the feat/persisted-engin... branch remains at 96%, unchanged from commit d47ffe5 in the feat/podman-image-bo... branch.

TypeScript / code-coverage/cli

The overall coverage in commit a2ae17e in the feat/persisted-engin... branch remains at 81%, unchanged from commit d47ffe5 in the feat/podman-image-bo... branch.

Show a code coverage summary of the most impacted files.

File	feat/podman-image-bo... d47ffe5	feat/persisted-engin... a2ae17e	+/-
src/lib/onboard...trap/adapter.ts	0%	63%	+63%
src/lib/onboard...strap/docker.ts	0%	64%	+64%
src/lib/onboard...cker-journal.ts	0%	83%	+83%
src/lib/onboard...der/snapshot.ts	0%	83%	+83%
src/lib/onboard...one-rebinder.ts	0%	83%	+83%
src/lib/onboard...trap-journal.ts	0%	86%	+86%
src/lib/actions...ne-providers.ts	0%	86%	+86%
src/lib/onboard...-replacement.ts	0%	87%	+87%
src/lib/onboard...-transaction.ts	0%	88%	+88%
src/lib/onboard...test-fixture.ts	0%	96%	+96%

---

_{Updated August 01, 2026 13:59 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Partial review preserved 1 canonical finding(s) before the advisor stopped.

Model lanes

• GPT-5.6 Terra (primary): Failed after a partial review · low confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed

Second-opinion E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: onboard-repair, onboard-resume, cloud-onboard

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover the raced authority-record publication branch

• Location: src/lib/onboard/runtime-provider/persisted-engine-authority.ts:325
• Category: tests
• Problem: The store handles an EEXIST result from exclusive publication by loading the winner and accepting it only when it is byte-identical, but the new tests do not exercise that branch.
• Impact: A change to the raced-record handling can cause identical retries to fail or a conflicting winner to be accepted without a regression test detecting it.
• Recommendation: Add a unit test that creates a record after the initial load and before publication, then verifies that an identical raced record succeeds and a conflicting raced record throws.
• Verification: Inspect coverage of the false return from writeExclusiveRecord at lines 325-327, or run the persisted-engine-authority unit test after adding the controlled EEXIST interleaving.
• Test coverage: Mock or otherwise control publication so writeExclusiveRecord observes EEXIST after the first load; assert record returns the identical winner and rejects a different winner for the same operation.
• Evidence: src/lib/onboard/runtime-provider/persisted-engine-authority.ts:325-327 loads `raced` only after exclusive publication reports an existing target. src/lib/onboard/runtime-provider/persisted-engine-authority.test.ts covers sequential exact retries and conflicts, but no test drives the post-publication EEXIST branch.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[apurvvkumaria]

Comment — reviewed exact head a2ae17e. Container-engine authority publication is fail-safe and safe to merge; I found no blocking defect. Non-blocking fast follow: add an EEXIST publication-race test around the linkSync branch so concurrent first publication is permanently covered and the existing fail-closed behavior cannot regress. Core CI is green; advisor failures do not identify a product blocker.