[zibi-pplx]

Summary

Move existing Firecracker callers onto the runtime-neutral contracts introduced by #961. Catalog definitions, node resolution and template build inputs use the generic environment shape while retaining their original canonical identity, stored JSON and environment references. The decoder rejects conversions that would discard or change requirements.

Resolution negotiates representation: new nodes return generic definitions to new clients and the equivalent legacy representation to old clients; new clients normalize responses from old nodes. Supervisor launch, VM-state probes, and scheduled, manual and base snapshot capture/restore use the generic RPCs. Sandbox reconciliation consumes the shared VM-state type. Snapshot capture derives the fallback runtime from recorded execution metadata, and restore uses the acknowledged consumer runtime. Historical unbound snapshots retain Firecracker fallback. VM-state probes remain Firecracker-only during this bridge; fallback is removed before other runtime adapters are enabled. Hoist the suspend capture request so its binding and storage fields remain reviewable.

The Firecracker-only rolling-upgrade bridge falls back only when a method is missing. Runtime refusals, cancellation and ambiguous transport failures do not replay through the old route. Fallback conversion failures retain the admission-refusal marker, giving old and new supervisors the same error classification without sending a legacy launch. Legacy launch inputs are converted fallibly before transport: combining a verified identity with any top-level legacy sandbox ID is refused locally, even when the IDs match. Existing timeouts, execution fences, source authentication and ownership rules remain. No SQL, executable, selection-policy or newly enabled runtime changes.

Validation

• Rebased on main at 718105d. The integrated Linux arm64 all-target checks passed; mixed-version capture and fallback regressions passed before the rebase.

• The metadata-derived capture path passed the mixed-version refusal test and client fallback matrix. Linux arm64 all-target sandbox-manager Clippy and Rust formatting passed.

• The old/new-supervisor launch matrix failed before the fallback marker fix (Internal instead of FailedPrecondition) and passed afterward, covering valid launches, mismatched identities and absent/empty containment executables. Invalid requests invoke no launch handler.

• The launch integration matrix passed: dual legacy identities cause zero launch or stop RPCs, valid acknowledgement succeeds, and missing or wrong acknowledgements stop the execution.

• The client fallback matrix passed for missing methods, success, cancellation, deadlines, transport failures and precondition refusals across Firecracker and other runtime requests.

• Linux arm64 all-target Clippy for node-manager and supervisor passed with warnings denied. Earlier bridge validation covered stable canonical identities, historical metadata, both environment representations and builder bindings; inherited execution: introduce runtime-neutral environment and control contracts #961 validation includes 109 runtime-core tests and Go binding checks.

• No live mixed-version or KVM deployment performed.

Severity and risk

Architectural migration. The primary risks are identity drift and mixed-version failures. Representation negotiation cannot select a different environment, and both RPC generations remain available during rollout.

Rollout

Land #961 then #920 and deploy them together to every participating service, CLI and rollback image. Verify Firecracker template builds, create, command, stop/start, pause/resume and suspend/restore through the new routes, including mixed-version fallback. During the canary, measure end-to-end VM-state probe latency and timeout rate on not-yet-upgraded nodes before considering a bounded capability cache. The runbook documents the cleanup-phase lifecycle metric-label transition while preserving the LOAD_SNAPSHOT configuration key.

After deployment is complete and old calls are drained, #921 removes the obsolete gRPC representation and routes. It retains compatibility with persisted environment identities. Keep the original public sandbox health field and enum names in this bridge; #921 changes them to runtime-neutral names at the JSON/string and generated-client migration boundary, with no permanent aliases.

AI assistance: Codex drafted the code, tests, documentation and description.

---

Stack created with Sapling. Best reviewed with ReviewStack.

• -> execution: route Firecracker through generic environment and control RPCs #920
• execution: introduce runtime-neutral environment and control contracts #961

[the-gigi-pplx]

Review — 5 findings

All Low. Reviewed on top of PR #961, as stacked.

Low

1. crates/libs/sbx/mgr/server/src/runtime_via_nodemgr.rs:31 — Every RuntimeControl call site passes a literal RuntimeKind::Firecracker, so the runtime-gated fallback guard never sees another value.
   The same literal appears in snapshot_scheduler.rs:977, create.rs:1162, grpc_state_snapshot.rs:1879 and grpc_lifecycle/suspend_snapshot.rs:688. It's correct today, because no other runtime launches. But the "other runtimes must not use the Firecracker fallback" property in runtime_control.rs is only as good as the next author remembering to change six literals. At least the snapshot sites already hand execution_metadata to snapshot_capture::bind, so they could derive the kind from it.

2. crates/libs/node/mgr/server/src/service/launch_prepare.rs:28 — Node-manager builds a LaunchFirecrackerRequest only to convert it to LaunchRuntimeRequest, then converts it back on fallback (runtime_supervisor_client.rs:336).
   The local try_into can't fail: the construction site at lines 581–590 already blanks sandbox_id when verified_runtime is set. Its InvalidArgument branch is dead, and it's the one launch-conversion error that isn't classified like the others. Building the generic request directly removes one conversion and that branch.

3. crates/libs/build/mgr/src/execution_binding.rs:258 — "boot" and "vmlinux" are spelled as literals here and twice in environment/transport.rs (into_runtime_neutral, from_representation).
   BootProfile::LINUX_DIRECT_ROLE / LINUX_DIRECT_FORMAT already exist in execution-spec/src/environment.rs:141. The builder check also tests ArtifactComponentKind::Kernel, which the decoder leaves to the legacy validator, so the two "is this the exact Firecracker profile" checks have already drifted slightly. One helper on EnvironmentDefinition that both call would keep them in step.

4. crates/libs/execution/common/src/environment/transport.rs:48 — canonical_identity() is a new pub method whose only callers are tests (transport/tests.rs, catalog/environment/tests.rs). pub(crate), #[cfg(test)], or comparing reference() would avoid widening the API for a test hook.

5. crates/libs/sbx/mgr/server/src/service/grpc_lifecycle/suspend_snapshot.rs:688 — The new capture_runtime_state call is one 163-character line, and line 692 is 181 characters.
   rustfmt --edition 2024 --check passes on the file, because rustfmt gives up on expressions it can't fit and leaves them alone. Hoisting the request into a let lets it format the block like the other migrated call sites.

Verified against 0bf44479e35347cb76366d73e00d20308c04637f. CI is green, including all four Kind/Firecracker smoke shards. Reproduced locally: the rustfmt --check result in (5). The rest was traced by reading the code at this head.

Ruled out while tracing:

• Snapshot artifact paths losing their leading slash is safe, because the jail-artifact validator strips it.
• Restore still takes the LoadSnapshot limiter key.
• New handlers rewrite Unimplemented, so a runtime refusal can't trigger the legacy replay.
• After an answered Unimplemented, the fallback's fresh supervisor retry budget only covers untransmitted failures.

The extra round trip for VM-state probes against old nodes is already on the canary plan in the description. I didn't run a mixed-version deployment.

[the-gigi-pplx]

Approved. 5 non-blocking findings in the review comment above.