# Microsandbox Compatibility Map

This document maps Microsandbox's non-public compatibility boundaries. It exists to help contributors and agents surface backward-compatibility risks early; it does not require every previous behavior to be preserved automatically.

When a proposed change crosses one of these boundaries, identify the risk before implementation. Do not silently add a shim, migration, fallback, or legacy implementation. Explain the compatibility directions involved, the failure mode, and the available choices, then follow the change-safety rules in `AGENTS.md`.

Public SDK, CLI, and HTTP API compatibility is intentionally outside this map. The focus here is the protocols, transports, durable formats, runtime ABIs, and lifecycle contracts that make existing Microsandbox installations and sandboxes continue to work.

## Compatibility Directions

Review every direction that applies to the change:

```text
new host ---------> old running sandbox / old agentd
new release ------> old MSB_HOME / database / runtime state
new reader -------> old disk / snapshot / archive / cache / metadata
old release ------> state written by the new release
exported artifact -> another release / platform / architecture
new component ----> independently running old component during upgrade
```

A clean, early refusal may be compatible when continued operation would be unsafe. Silent reinterpretation, partial mutation before refusal, stranded durable state, and corruption are not acceptable fallback behavior.

## System Boundaries

```text
CLI / SDK
   |
   | launch JSON + inherited descriptors or Windows config file
   v
host runtime <---------- JSON-lines control socket / named pipe
   |
   | local agent socket / named pipe
   | fixed frame header + CBOR
   v
relay <---- ring buffers ----> libkrun virtio console "agent"
                                  |
                                  v
                              guest agentd
                                  |
                   +--------------+---------------+
                   |              |               |
                bootstrap      filesystem      heartbeat

MSB_HOME
   +-- SQLite database and migration history
   +-- sandbox disks and volume data
   +-- snapshots and portable archives
   +-- OCI/materialization cache
   +-- filesystem metadata xattrs, ADS, and sidecars
   +-- sockets, locks, logs, journals, and shared memory
```

## 1. Host-to-Guest Agent Protocol

The agent protocol is the most explicit cross-version boundary. Its versioning policy is defined in [`crates/protocol/VERSIONING.md`](crates/protocol/VERSIONING.md).

The immutable outer frame is:

```text
[length: u32 big-endian][id: u32 big-endian][flags: u8][CBOR envelope]

CBOR envelope = { v: generation, t: wire message name, p: encoded payload }
```

Compatibility-sensitive elements include the header size, byte order, maximum frame size, ID routing, flag bits, CBOR envelope keys, message wire names, message introduction generations, payload field names and meanings, and terminal/session/shutdown semantics. The relay routes on IDs and flags without decoding CBOR, so changing the header cannot be hidden behind payload negotiation.

Evolution rules:

- Keep the outer frame shape stable.
- Add message types; never remove, rename, or redefine shipped wire types.
- Assign every new message type an introduction generation and bump the protocol generation.
- Make new payload fields optional or defaultable.
- Do not change a shipped field's meaning or type in place; use a version-specific type and converter for a genuine format break.
- Negotiate the lower peer generation and capability-gate every newer operation before sending it.
- Keep an old codec until the supported compatibility horizon deliberately moves; the current host still understands the pre-0.5 codec and handshake.
- Make any new flag bit safe for an old relay to ignore, or use a capability-gated message instead.

Sources and checks:

- [`crates/protocol/lib/message.rs`](crates/protocol/lib/message.rs) defines the generation, frame constants, flags, wire names, and message introduction map.
- [`crates/protocol/lib/codec.rs`](crates/protocol/lib/codec.rs) defines current framing and validation.
- [`packages/agent-client/rust/lib/client.rs`](packages/agent-client/rust/lib/client.rs) performs codec detection, version negotiation, and host-side send gating.
- [`crates/runtime/lib/runner/relay.rs`](crates/runtime/lib/runner/relay.rs) depends on ID ranges and flag semantics without decoding message bodies.
- [`crates/protocol/tests/schema_snapshot.rs`](crates/protocol/tests/schema_snapshot.rs) freezes the versioned surface and checks append-only message evolution.
- [`scripts/smoke/cli/pre05-running-sandbox-compat.sh`](scripts/smoke/cli/pre05-running-sandbox-compat.sh) exercises a current host against a real pre-0.5 running sandbox.

Required review should include golden encoded payload bytes when serialization changes. Schema snapshots protect the protocol inventory, but they do not freeze every payload's encoded representation.

Generation-11 resource observations add two gated messages without modifying prior payloads or framing. The client refuses the new read unless both the host relay and guest advertise support before transport admission; see the dual capability gate below. New agents return explicit per-resource unavailability on older kernels. Readiness sampling uses fixed sysfs paths with bounded inventory/record reads and does not touch the liveness pulse or idle-activity counters. Query identity and validated fields are only inputs to runtime operation fencing, which must still be implemented before reporting resize completion.

### Execution output backpressure

Execution limits are fixed at sandbox creation and advertised in `Ready.exec_limits`: 128 executions, 1 MiB stdin allowance, 4 MiB combined stdout/stderr allowance, and 16 KiB stdin and output chunks. These allowances total at most 640 MiB across admitted executions before transport, allocator, and kernel-pipe overhead; they are not preallocated. Earlier guests advertise 64 KiB stdin and 1 MiB output limits, which newer clients continue to honor. The values are built-in defaults, not user configuration; clients obey the advertised values, so the defaults can change between releases without a lockstep upgrade. The SDK has no stdin staging queue. Generation-10 cumulative `.stdin.ack` and `.output.ack` messages replenish consumed allowance. Released older SDKs retain legacy behavior outside the buffering guarantee; new SDKs fall back to historical buffering when Ready lacks limits. Existing sandboxes remain compatible without a restart, but only a new guest boot with the updated runtime selects the larger defaults. Intermediate unreleased generation-10 builds are not compatibility targets. No new snapshot-manifest extension is required. Disk-only restores use the current built-in defaults, while memory restores preserve the guest limits from captured Ready; restoring a memory snapshot that captured limits requires the launch capability `exec_limits`. Disk and catalog formats are unchanged. Older relay and cross-version launch coverage must be validated separately from same-version tests.

### PTY leader completion

PTY completion follows the tracked process's exit rather than waiting for every descendant to close its inherited slave descriptor (issue #2089). The agent observes exit concurrently with output, wakes the reader through a private close-on-exec pipe, and delivers queued output before the existing `ExecExited` event. Final draining retains output-window acknowledgements and has no elapsed-time cutoff. Its 1 MiB post-exit byte bound exceeds Linux's standard PTY flip-buffer budget (640 KiB) plus the N_TTY queue (4 KiB), preventing an ongoing descendant writer from delaying completion indefinitely; this is not a total command-output limit. Revisit that bound if the bundled kernel changes PTY buffering. The agent adds no descendant kill signal; terminal hangup and explicit process-group signal semantics remain in effect. Pipe-mode execution is unchanged.

No wire fields, protocol versions, SDK signatures, or persisted layouts change. Older SDKs can observe the corrected completion through the existing event; newer SDKs still encounter the bug when the running guest uses an unpatched agent. Deploying the corrected guest agent requires a new guest boot; replacing the SDK alone or restoring a memory snapshot containing the old agent does not apply the fix. Validation includes the released 0.7.15 SDK/runtime with the patched agent and the revamp SDK with that runtime, plus legacy and flow-controlled agent tests. `scripts/smoke/managed-job-pty-exit.mjs` verifies normal exit, explicit kill, repeatable waits, exact final output, and descendant survival in a disposable local home.

## 2. Bootstrap, Init, and Guest Runtime Contract

The first current-protocol host frame is `core.bootstrap` with message ID zero and no flags. The guest then reports resolved init state, the relay installs identity mappings, the host acknowledges init, and only then may the guest become ready.

```text
host                     guest agentd
 |---- core.bootstrap ------>|
 |<--- core.init.resolved ---|
 |---- core.init.ack -------->|
 |<--- core.ready -----------|
```

Compatibility-sensitive elements include bootstrap field defaults and tagged variants, first-message ordering, root/mount/network/security encoding, bind identity exchange, hostname and environment behavior, handoff state, and legacy boot-environment spellings.

Stable guest/VMM identifiers and paths include:

- Virtio-console port name `agent`.
- Runtime virtiofs tag `msb_runtime`.
- Guest runtime mount point `/.msb` and its script, TLS, and heartbeat paths.
- Root block device `/dev/vda`.
- Additional disk lookup through `/dev/disk/by-id/virtio-<id>` with the existing sysfs fallback.
- Special host and guest shutdown delays used for normal termination and handoff.

Sources: [`crates/protocol/lib/bootstrap.rs`](crates/protocol/lib/bootstrap.rs), [`crates/protocol/lib/lib.rs`](crates/protocol/lib/lib.rs), [`crates/agentd/lib/agent.rs`](crates/agentd/lib/agent.rs), [`crates/agentd/lib/init.rs`](crates/agentd/lib/init.rs), and [`crates/runtime/lib/runner/vm.rs`](crates/runtime/lib/runner/vm.rs).

Guest init selection is an optional `init_observation` field on the existing Ready payload. It distinguishes agentd retaining PID 1 from the exact guest path selected and preflighted for handoff; it does not assert that a foreign init completed exec or finished booting. It contains no arguments or environment. Older agents and relays leave this evidence unknown, and the unchanged Ready reader ignores the new field. No message kind, protocol generation, launch contract or required response field changes. The runtime preserves the observation in its existing nested Ready checkpoint resource and after restore. Absent observations retain the original Ready encoding; existing artifact readers can still decode that nested document. This transport evidence does not itself implement saved-config init projection or portable activation; original SDK `auto` intent is retained separately below. Existing handoff freezer refusals and graceful shutdown semantics are unchanged.

Init selection now also has a separate host-private `last-active/init.json` record, bound to the catalog/sandbox/run/runtime-boot identity and activation generation. The strict `state.json` and terminal receipt formats remain unchanged, so older runtimes can continue opening the catalog and journal while ignoring this file. New activation records init before confirming the main journal; failure follows the approved uncertain-start termination path. A pending journal, later unsupported runtime, changed owner or missing evidence cannot certify an old selection. Live configuration generations retain the immutable boot choice. The unreleased private capture receipt adds an optional init observation under its existing digest; older receipts decode as unknown, and released SDKs do not request this private receipt contract. Stopped capture independently selects terminal provenance and revalidates the init evidence across the disk cut. Raw configuration and init arguments/environment are not rewritten or exported by this change; portable init projection and activation still require implementation.

Force-stop now invokes the existing dead-process reconciliation while holding transition ownership, before clearing active configuration. This preserves a terminal receipt and terminates the latest run record after SIGKILL bypasses the runtime exit observer. The existing lifecycle lock, process identity and legacy endpoint checks still govern reconciliation. Missing or failed evidence remains unknown, and receipt failure does not prevent existing kill cleanup. No new catalog fields, signals or runtime requests are introduced.

The local SDK configuration now records optional `init_provenance` separately from `init.cmd`: fresh resolution records builtin, explicit path or original auto selection, and image-entrypoint resolution retains auto intent while storing the concrete launch path. The hint contains no arguments or environment. Explicit builder init setters and sparse init overrides replace inherited intent even when the executable is unchanged. Persistence drops a hint if a direct config edit changes its associated init. Deserializing/restarting older configuration does not manufacture a missing hint; a fresh builder resolution describes the newly selected configuration. Capture validates the hint against the recorded raw init field, independently of guest selection, and rejects contradictions without logging values.

This optional local field changes no catalog schema, launch argument, guest protocol or cloud request. Released readers ignore the extra field and may discard it when writing; supported runtime capability selection still gates private retention. Missing evidence remains unknown. Portable init projection and activation remain required within PR3; this local provenance record is not an archive format or an activation switch.


The local SDK's optional host-private `command_provenance` records the runtime CMD and the reusable CMD that preceded a detached invocation. It does not change the effective command, restart behavior, launch/guest protocol, or cloud request. Older configurations without this evidence, and records whose command was changed by an older writer, remain unknown during reconstruction; an explicit new CMD or complete creation spec establishes a new declaration. The reconstruction guard is not serialized. Capture checks the hint against the independently retained raw source, and error/Debug output does not expose argv. This is private source evidence only: it does not emit portable configuration or replay ancestor invocations. Portable inclusion still requires the agreed exclusion, binding and security controls.

## 3. Local Agent IPC and Relay Routing

Unix clients and runtimes recognize canonical hashed socket paths, legacy flat hashed paths, and an older deep sandbox path. Windows uses named pipes derived from the legacy hash. The runtime publishes compatibility symlinks where safe and must not overwrite a live endpoint.

Compatibility-sensitive elements include the hash input and truncation, directory and socket names, Unix path-length fallback, Windows pipe names, compatibility symlinks, stale-endpoint cleanup ordering, lifecycle-lock paths, and lock ownership. Relay compatibility also depends on client ID-range allocation, maximum clients, terminal routing, disconnect cleanup, and shutdown flags.

Sources: [`crates/runtime/lib/client/ipc.rs`](crates/runtime/lib/client/ipc.rs), [`crates/runtime/lib/runner/relay.rs`](crates/runtime/lib/runner/relay.rs), and [`sdk/rust/lib/runtime/spawn.rs`](sdk/rust/lib/runtime/spawn.rs).

Path changes require an old-path probe or alias for the supported horizon. Never change a path hash or delete a socket until liveness and ownership have been resolved through the existing lock and endpoint checks.

Unix endpoint liveness probes connect directly to each existing canonical and historical pathname rather than queueing a redundant filesystem metadata lookup first. This prevents unrelated blocking-pool saturation from exhausting the shared 50 ms probe budget for absent endpoints. Live or busy listeners remain protected, timeout remains conservative, and uncertain connection errors still propagate before cleanup. NUL-containing paths remain invalid filesystem names and are not reinterpreted as Linux abstract sockets. Path identities, lifecycle ownership, cleanup ordering, wire data and old-runtime listener support are unchanged. Permission diagnostics now identify the connect operation even when directory traversal caused the denial.

## 4. Live-Control Protocol

The host runtime exposes a separate Unix socket or Windows named pipe for live modifications. Each connection exchanges one JSON request line and one JSON response line. Operations currently cover capability discovery, CPU and memory state or targets, and secret updates.

Compatibility-sensitive elements include newline framing, the tagged `op` names, response variants, resource field meanings, capability discovery, and the distinction between an absent endpoint, an unsupported operation, and a failed operation. Older runtimes predate capability discovery, and callers intentionally use operation-specific fallback behavior.

Sources: [`crates/runtime/lib/runner/control.rs`](crates/runtime/lib/runner/control.rs) and [`sdk/rust/lib/sandbox/modify.rs`](sdk/rust/lib/sandbox/modify.rs).

Windows control clients retry missing-pipe (`ERROR_FILE_NOT_FOUND`) and busy-pipe errors before sending a request, within one total one-second connection budget. Restore's remaining startup deadline can cancel that wait sooner. Other errors still fail immediately; established requests are never replayed. This tolerates asynchronous listener creation and gaps between pipe instances without changing protocol bytes, endpoint identities, or old-runtime capability semantics. A genuinely absent endpoint may now take up to one second to report unavailable instead of failing immediately.

Add operations and optional fields rather than redefining existing ones. Capability-gate behavior whose absence cannot be interpreted safely by older clients.

The SDK's immediate CPU and memory resize results now report the existing `accepted` state after a successful target acknowledgement. A setter's quantities cannot establish fresh completion for that operation: plugged memory can remain offline, and memory above a shrink target means shrink may still be pending. Existing requested, actual and enforced fields, successful mutation behavior, wire requests and persistence remain unchanged. This deliberately changes the previous premature `applied` or `converging` classification; callers must not treat `plan.applied` as guest completion. No new observation request is sent to an older runtime, and no mutation is replayed. The capability-gated generation-two host `control.resize` operation now assigns a runtime incarnation, opaque operation ID and independent CPU/memory generation after target acceptance. Legacy setters also advance that resource generation, so an older client can supersede a new client's pending wait without ambiguity. The runtime retains at most 256 records in memory, preserving each resource's latest record; restart or missing history never becomes completion. CPU confirmation requires the guest online prefix and host enforcement to match. Memory confirmation joins byte-exact host device identity/target/plugging with query-bound guest onlining evidence; MemTotal and plugged capacity alone are insufficient. Unsupported relay, guest or kernel observation never means success. Rust `apply_with_resize_tracking` selects support before dispatch and retains the legacy path on older runtimes, without mutation replay. Exact waits re-read returned IDs, including supplied applied records; CLI `modify --wait` uses its own apply identities. Timeout or cancellation ends only waiting. Structured outcome/error parity in all bindings and background confirmation for telemetry remain unfinished.

A stricter live memory target uses an optional pressure sample on the existing generation-11 resource query. The guest reads MemTotal and MemAvailable together. The runtime returns `memory_pressure` before changing the device target, resize history, or retained configuration when the minimum required reduction exceeds available bytes. This also applies to older SDKs talking to the capable runtime and guest. Growth, repeated targets and older components keep their prior behavior. An unavailable measurement leaves the previous admission policy in effect. Concurrent guest allocations can still exhaust memory after admission.

Live disk-only snapshots use the distinct `disk_checkpoint_create` operation and capability. An absent capability is false: callers refuse before capture rather than silently capturing RAM or copying a writable disk. The runtime serializes the disk rollover with other control mutations and preserves a user's pause. This does not change the agent protocol or snapshot format; the result uses the existing file-state layer descriptor. Stopped disk capture retains its lifecycle lock and existing behavior.

Resident pause/resume sends one authoritative mutation rather than first observing pause state and querying capabilities. The runtime checks support before mutation, including idempotent requests, and the client requires the expected state in the response; unknown operations and incomplete replies fail. Ordinary get/list pause projection remains unchanged. Guest freezing retains one `cgroup.events` descriptor and waits for notifications with a fixed deadline; each poll timeout is capped at 1 ms so rate-limited kernel notifications cannot delay the next authoritative state check. Clock correction still precedes workload thaw, and no control or agent wire format changes.

The subsequent unreleased generation-9 transport repair routes internal freeze/thaw directly from the coordinator to the existing relay through a bounded in-process queue. Ordinary control/bulk input is gated at complete frames; admitted input remains guest-owned until consumed, while unadmitted input stays source-owned and ordered. The guest keeps stdin/TCP delivery nonblocking with respect to its control loop and preserves accepted input through restore. Private replies and cumulative credit updates never become SDK responses. The immutable frame header, released generation-8 schema, and public sockets are unchanged. Full capture requires an acknowledged bidirectional frame boundary; failure or timeout does not authorize a partial capture.

## 5. Launcher-to-Runtime Process Protocol

In v0.7.0, the private launcher is `msb machine`; `msb sandbox` is the public command group and `sbx` is its alias. The current CLI also recognizes previous internal `msb sandbox` launches. The SDK selects the tested v0.6.x launch contract for previous executables and encodes the corresponding arguments and JSON. Public top-level verbs such as `msb run` remain supported.

Complete previous invocations use the separate boot-only decoder; `msb machine` retains strict execution-intent validation. Runtime selection keeps the unified setup API and its installed-binary precedence. Launch selection uses our embedded-version reader and cached previous contracts, without additional capability/help probes.

TCP limits retain the serialized `max_connections` key despite the canonical SDK field becoming `max_tcp_connections`. Optional UDP limits use `max_udp_connections`. Previous launches retain their TCP defaults/clamps and fixed 256-session UDP budget; explicit UDP limits require the current launch contract and are rejected before launching an older runtime. This prevents either direction of SDK/runtime version skew from silently broadening previous limits or ignoring an explicit new limit.

Published-port accept-queue depth uses the optional `tcp_accept_queue_size` key, omitted when unset so a launch that does not ask for it is byte-identical for every runtime. Omission now means a 1,024-deep queue on each published TCP listener, where earlier runtimes inherited mio's 128; the host kernel clamps both to `somaxconn`. Previous SDKs launching the current runtime get the deeper queue too. That is deliberate and not pinned at the boundary: queue depth is not a resource or policy limit, and the shallow queue was the defect. An explicit value requires a runtime that advertises `tcp_accept_queue_size` through `__launch-protocol`; the SDK probes only when the key is set and returns an upgrade-required error otherwise, because v0.7.x `machine` runtimes decode network JSON leniently and would drop the key. v0.6.x launch contracts reject it before launch and never receive the key. Managed cloud rejects it before HTTP, as the cloud create contract carries no published ports.

The optional `max_inbound_tcp_connections` launch key limits active published-port connections; zero means unlimited. Omission uses runtime defaults: unlimited in 0.7.9+, 256 in older versions, including when launched by an older SDK. Only explicit overrides trigger the `__launch-protocol` capability check; unsupported runtimes return an upgrade-required error. v0.6.x launch contracts and managed cloud reject overrides before launch or HTTP, respectively.

HTTP CONNECT outbound proxies accept optional Basic authentication through an optional `credentials` member on the `protocol: "http_connect"` proxy, alongside the optional SOCKS5 credentials that already use the same shape and host-side resolution. The durable configuration holds only the username and a host-side password source; the launcher resolves the password and passes it through the existing launch transport, so nothing durable stores plaintext. An authenticated proxy requires a runtime that advertises `http_connect_proxy_auth` through `__launch-protocol`. The SDK probes only when credentials are present, so an unauthenticated proxy keeps its existing `http_connect_proxy` requirement, and an older runtime returns an upgrade-required error before launch.

That probe covers SDK launches only. v0.7.x `machine` runtimes and v0.7.x SDKs decode the proxy object leniently, so a saved configuration reopened by an older release drops `credentials` and would connect without authentication; a read-modify-write through an older SDK can then persist the stripped representation. No representability check in `crates/db/lib/compat/` covers this field today, and the downgrade preflight matches v0.6.x and v0.7.0-v0.7.6 rather than v0.7.7. Adding `credentials` to an existing variant also breaks Rust consumers that construct `OutboundProxy::HttpConnect` literally or match its fields exactly, and `OutboundProxyBuildError` is not `#[non_exhaustive]`.

Starting a sandbox crosses a private process boundary. On Unix, launch JSON is passed through inherited descriptor 96, the parent watchdog uses descriptor 97, startup JSON uses descriptor 98, and the lifecycle lock uses descriptor 99. Windows uses a short-lived launch-config file and platform-specific startup plumbing. Detach acknowledgement bytes and graceful-shutdown signals are also part of this contract.

Compatibility-sensitive elements include descriptor numbers, ownership and close-on-exec behavior, launch JSON field names and defaults, startup response shape, watchdog EOF meaning, signal meaning, detach acknowledgement, secret transport, and parent/child cleanup ordering.

Windows runtimes before v0.6.16 do not hold the current lifecycle lock. For SDK-launched processes, the SDK atomically records the exact Windows process creation token, PID, sandbox/run IDs, and ownership mode in `<sandbox>/runtime/sdk-process.json` after guest readiness. Old runtimes and SDKs ignore this file; SQLite schemas and configuration payloads are unchanged. Legacy graceful stop verifies the named-pipe server against a retained process handle and waits for that same process object to exit. A terminal database row or an unused lifecycle lock alone cannot complete stop. The same record protects recovery and restart from recycled PIDs. Missing ownership evidence for a live legacy process produces an error instead of false success; a malformed record is not silently ignored. These checks never grant permission to force-kill a runtime.

Released Windows v0.6.10–v0.6.13 use libkrun v0.1.31, whose console can deliver bootstrap data before guest userspace opens its port. The libkrun fix is [`933467c`](https://github.com/superradcompany/libkrun/commit/933467c0320f72b69b40fd169a1f59f887f797f4), shipped in v0.1.32 and consumed by microsandbox v0.6.14. Native qualification reproduced the v0.6.10 startup failure with both the current SDK and its matching released SDK. An SDK launch adapter does not repair this defect inside the released executable; qualifying those exact binaries remains blocked.

User-supplied OCI writable uppers (`RootfsSource::Oci` with `RootDisk::DiskImage`) participate in exclusive disk-attachment admission, including duplicate checks against additional mounts. They use the existing canonical-path resolution, platform lock and runtime handoff; OCI base layers are not locked by this rule. This rejects simultaneous attachments that previously went unchecked, without changing disk bytes or launch protocols. An older launcher that omitted the lock remains undetectable through this mechanism. Windows retains the existing canonical-path sidecar identity, which does not unify distinct hard links to the same file.

On Linux, stop and kill also pin the departing runtime with a process pidfd, validating its inherited lifecycle descriptor before following it. This waits for the whole thread group rather than treating a zombie leader or lifecycle-lock release as completed disk teardown, and does not wait on a later sandbox's attachment to the same external disk. It does not reap the SDK's child or change descriptor handoff. This path requires `pidfd_open` (Linux 5.3 or later) and permission to inspect the runtime's `/proc` descriptors; unsupported or denied probes return an error rather than silently claiming completion. Already-exited or stale PIDs without the matching inherited lifecycle descriptor retain the existing lifecycle/resource reconciliation path.

Linux SDK child collection uses pidfd notifications and `try_wait()`, with polling when pidfds are unavailable. Detached resources are observed while retained and after release; unfinished collection transfers to one process-wide reaper thread when the Tokio runtime shuts down. Collection never terminates a detached VM and preserves the owned child's exit status for later waits. These SDK-internal changes do not alter launch descriptors, watchdog acknowledgements, runtime/agent protocols, storage, or older-runtime compatibility. A live but undriven current-thread runtime can delay its async observers until driven or shut down.

On macOS, stop and kill observe the departing process through a `kqueue` exit registration, checking its process birth identity and existing lifecycle descriptor. Exit notification follows file-table teardown, unlike lifecycle-lock release alone. If registration races an already-exiting process, birth-identified `kern.proc.pid` observation waits for zombie/disappearance rather than treating a failed process lookup as completed cleanup. Observation does not reap the child, unlock its disks, or wait for a subsequent disk owner. Inspection failures remain errors. This changes host-side completion timing only; launch descriptors, lock paths, agent messages, and persisted state are unchanged in both SDK/runtime directions. It cannot release lock copies retained by an older SDK process.

Sources: [`crates/runtime/lib/client/launch.rs`](crates/runtime/lib/client/launch.rs), [`crates/runtime/lib/runner/vm.rs`](crates/runtime/lib/runner/vm.rs), [`sdk/rust/lib/runtime/spawn.rs`](sdk/rust/lib/runtime/spawn.rs), and [`crates/cli/lib/machine_cmd.rs`](crates/cli/lib/machine_cmd.rs).

Windows disk attachment retains the existing exclusive sidecar filenames and sharing mode. The launcher duplicates non-inheritable sidecar handles into the exact spawned process and sends their values through a bounded startup-only stdin message, required by the hidden `msb machine --disk-locks-stdin` flag. The runtime adopts them before opening guest disks; successful handoff closes the launcher's copies without an unlocked interval. The SDK sends this flag only to modern runtimes; previous runtimes retain launcher-owned locks and never receive the unsupported flag. Failed or cancelled handoffs terminate the child before storage cleanup; confirmed exit also clears any remaining parent copies. Stop/start observes owned-disk sidecar release, independently of retained SDK objects. This changes the Windows private launch contract, not SDK APIs, agent framing, snapshot formats, or disk bytes.

Unix disk-lock descriptors stay close-on-exec in the SDK parent and become inheritable only in the intended child's pre-exec callback. Successful spawn closes the parent's copies without explicitly unlocking the child's shared open-file descriptions. The runtime receives the same locked descriptors; this Unix handoff preserves fixed launch descriptors, JSON and paths. Stop and terminal restart additionally observe this sandbox's owned-disk marker locks under transition/lifecycle ownership, since a zombie leader and free lifecycle lock do not prove deferred file teardown finished. Named/external disks retain ordinary conflict admission. An already-running older development SDK can still retain its own parent lock copy; the new observer waits or times out rather than forcibly unlocking that genuine holder. Drop that old handle or restart that SDK process before retesting with the corrected handoff.

Launch JSON requires an explicit `execution` intent (`boot` or `restore`) and rejects unknown fields. Restores also pass the internal `msb machine --restore` argument: a runtime predating this contract rejects the unknown argument rather than ignoring a JSON restore source and cold-booting. The argument, intent, and complete strictly validated `checkpoint_restore` source must agree before VM construction. Unsupported restore behavior is an error, never a fresh-boot fallback. These #8 development contracts replace superseded unreleased forms without shims; they do not change portable snapshot bytes.

The launcher owns the child before awaiting its initial PID reply and while awaiting agent readiness. Cancellation at either wait immediately requests termination of that exact child; while the owning Tokio runtime remains available, a reaper retains the process handle and disk locks until exit. Explicit startup failure uses bounded termination/reaping and reports pending cleanup if exit cannot be confirmed. This is rollback of an unfinished launch, not a timeout or force-stop policy for an established sandbox. A creation guard now retains transition ownership through provisional-row insertion and final catalog publication, queues reconciliation behind cancelled writes on the single database writer, and only rolls back data after acquiring runtime lifecycle ownership. If bounded cleanup cannot prove exit, durable restore intent and storage remain; this does not promise indefinite in-memory retention or complete cancellation safety before named-volume provisioning finishes.

Startup progress extends the existing private startup channel; it does not introduce another socket. Preparation EOF is ordered after structured boot-error publication, while a flushed Activating frame permits normal channel closure. Asynchronous readiness/restore-activation failures also publish their actual cause before triggering exit. Optional preparation progress is coalesced and is not part of the guest agent protocol. Full restores announce Activating only after RAM, CPU, and devices reach the construction pause, including eager loading inside `Vm::enter`. Preparation has no fixed deadline; the creator retains cancellation, process ownership, and error handling. The existing bounded identity/clock acknowledgement, thaw, and public readiness waits begin afterward. Cold-boot deadlines are unchanged. Completed RAM byte progress alone is not the activation boundary.

The child database config retains `checkpoint_restore` while construction is incomplete. Only successful restore activation and creation finalization remove it. A failed or interrupted attempt retains its child-owned staging and rejects start, auto-start through exec, modification, compaction, and snapshot creation; remove and recreate it from the intact input snapshot. This replaces the earlier unreleased #8 behavior that discarded restore intent before success. Do not reopen these development rows with older #8 binaries that skip that field. Successful restores retain the ordinary later stop/start lifecycle; no portable snapshot format or schema version changes.

## 6. Database, Configuration, and Migration History

Rust patch names now match their targets: the shared `SandboxSpecPatch` replaces the old shared `SandboxConfigPatch` name, while the SDK derives `SandboxConfigPatch` from `SandboxConfig`. Rust callers must update imports and access shared settings through `.spec` on the SDK patch. The builder accepts the full SDK patch. These source API changes do not change configuration-file, persisted sandbox, or host/guest wire formats; runtime metadata remains internal and create-time credentials remain excluded from serialization.

The `ConfigPatch` derive always names patches `TypePatch` and generates `into_config()`, requiring the target type to implement `Default`. The `name`, `skip_into_config`, and `skip_accessors` options are removed. Custom derive users must update renamed patch references and implement `Default` or write their patch manually.

Generated per-field methods now inherit the source field's visibility, including setters, clears, replacements, and collection accessors. Callers that used public methods for private or restricted fields must move that access into the permitted scope or expose the source field. Fluent and `_mut` forms remain available. These are Rust source API changes; patch serialization and merge behavior are unchanged.

User and managed config readers default an omitted version to 1 and reject invalid or unsupported versions. User config writers emit `version: 1` and reject unsupported versions before saving. Managed files use generated patches over the existing value types. The documented v0.6.16 fixture is exercised in `sdk/rust/lib/config/persistence.rs`; this is not an older-binary execution test. Older binaries ignore the user version field and do not implement managed configuration. No sandbox records, database schemas, or host/guest formats change.

On Unix, managed configuration now rejects a file or immediate parent directory that is not root-owned or is group- or world-writable. Permission-inspection errors also reject loading. This replaces warning-only behavior in the unreleased managed-config branch: affected CLI/SDK backend construction fails until an administrator corrects deployment permissions. A missing managed file remains optional. ACLs, other ancestor directories, and Windows permissions remain outside these checks; file formats and existing backend instances are unchanged.

User-file I/O belongs to `GlobalConfigPatch`; `GlobalConfig` holds resolved values. Patch saves replace the saved settings without adding defaults, preserve explicit clears, and retain the existing field shapes and custom serializers. Unknown user fields are ignored when loading and discarded when saving, matching the previous behavior. Registry edits therefore leave unrelated omitted settings absent. Runtime diagnosis uses the same resolved user, environment/SDK, and managed settings as local backend construction. Configuration errors are reported instead of showing fallback runtime paths. Downgrade maintenance continues to resolve saved user settings independently of managed policy.

`sandbox_defaults.outbound_proxy` adds an optional default using the existing `OutboundProxy` wire type. Missing fields preserve existing behavior; older readers ignore the new global setting and cannot enforce it. Resolved sandbox and launch configurations use the existing proxy fields. In Rust, exhaustive `SandboxDefaults` literals need the new field (or `..Default::default()`), and `NetworkSpecPatch.outbound_proxy` is now `Option<Option<OutboundProxy>>` to distinguish omission from explicit clearing; generated proxy setters retain their signatures.

Rust local-backend construction now reports errors in config files and global constraints immediately: `LocalBackend::lazy()` and `LocalBackendBuilder::build_lazy()` return `Result`. Callers add `?` or handle the error; `try_build_lazy()` and `LocalBackend`'s `Default` implementation are removed. Language bindings propagate construction failures through their existing error types. Database setup remains lazy. Proxy defaults are validated after sandbox layering, before network use.

Direct builder creation now retains patches through image resolution and materializes once in the backend. `build()` and the concrete create APIs keep their signatures. For local creation, a concrete `workdir: None` now becomes an omitted patch field: it honors global workdir (including an explicit clear), and inherits image workdir only when global workdir is also omitted. Previously, concrete `None` skipped global workdir and inherited directly from the image. Rust callers using `Sandbox::create(config)` or `SandboxBuilder::from(config)` should supply a concrete workdir to fix its value, or use an explicit sparse patch clear when clearing is intended. Sparse user-file and builder `workdir: null` explicitly clears image defaults; omit the field to inherit them. Older binaries may fill an explicitly cleared workdir from image metadata. Configuration, sandbox-record, and host/guest wire shapes are unchanged. User and managed config structures ignore unknown fields; managed-file loading warns with their key paths without logging values. Existing value-type validation still applies. Final validation precedes replacement and sandbox-state writes; an OCI pull may precede final validation. Non-replacement OCI creation checks name availability before pulling, then rechecks under transition ownership before writing state; concurrent conflicts can still be detected after the pull.

The public `SdkConfig` type and `load_sdk_config()` exports are removed. Rust callers reading saved `active_profile` and `profiles` use `GlobalConfigPatch::load()`; callers needing effective local settings use `LocalBackend::config()`. This is a Rust source change, not a persisted-file change. Explicit `MSB_BACKEND=local` also reports malformed user configuration instead of silently discarding it.

Concrete `SandboxConfig` values with `placement_profile: None` or `outbound_proxy: None` now inherit global defaults on local creation, as workdir does. A sparse `Some(None)` explicitly clears them, and managed values still take precedence. The global proxy default is new; placement-profile inheritance changes behavior for existing Rust callers with configured defaults.

Registry host patches now merge individual fields. A managed TLS-only entry preserves user auth and ambient or per-call credentials; explicit `auth: null` suppresses them. Auth objects remain atomic replacements. Generated registry map setters now accept `RegistryEntryPatch` values; the public `RegistryEntry` value type and `LocalBackendBuilder::registry_hosts()` signature remain available. Serializing a complete `RegistryEntry` now writes `insecure: false` explicitly so converting that value to a sparse patch does not lose the setting. Saved sparse patches still omit unspecified fields. Older binaries understand the same fields but do not enforce managed policy.

Managed `deployment_profile: null` removes host enforcement. Managed `active_profile: null` (or an empty name) clears profile selection without clearing `MSB_BACKEND`; selecting a named local profile enforces local execution. These replace the pre-release branch's earlier clearing behavior. No released managed-policy format is being migrated.

Cloud backends now capture user settings and managed overrides during construction. Cloud sandbox creation and host-side SSH use those retained sources, with managed overrides applied last. Explicit cloud credentials no longer bypass an invalid user config file. Requests use the existing cloud wire fields; unsupported sandbox options fail before HTTP dispatch. Concrete cloud requests whose maximum CPU or memory equals the requested size keep those maxima tied to the final managed size, since cloud creation does not support a separate hotplug aperture. Existing cloud sandboxes and hosted SSH gateways are unchanged. The synchronous backend construction and resolution signatures remain unchanged.

Runtime SDK and environment path inputs are captured when a local backend is constructed. Changes take effect on a new backend; path accessors use its resolved settings and filesystem fallbacks without rereading managed policy. Callers constructing a bare `GlobalConfig` for path accessors or `setup::resolve_runtime()` must provide runtime path values themselves or obtain the resolved config from a backend. Language SDK setup helpers and the Cargo-installed wrapper resolve these layers before selecting a complete runtime pair. Snapshot restore rejects managed settings that conflict with captured root-disk layout or full-checkpoint CPU and memory geometry; it does not rewrite captured state.

`allowed_backends` is an optional global setting, also accepted in managed overrides. Missing or effective null allows both kinds; a supplied list replaces the lower list, and an empty list is invalid. Prohibited backend construction fails before database initialization or HTTP dispatch, including direct SDK construction. Selection precedence is unchanged, and restrictions do not reroute selection. Existing backend instances retain captured policy. Older CLI/SDK versions ignore this field and can remove it when saving user configuration; fleet enforcement requires supporting clients. Rust exhaustive `GlobalConfig` literals need the new field or `..Default::default()`. No runtime launch, catalog, host/guest, or cloud request format changes.

`Backend::info()` and `default_backend_info()` now return `MicrosandboxResult<BackendInfo>`. Rust callers add `?` or handle errors; custom trait implementations update their return type. A failed default-backend resolution reports its original configuration error instead of misleading cloud/programmatic metadata. Python, Node, Go, and Ruby diagnostics propagate errors through their existing language error mechanisms; successful shapes are unchanged. The standalone CLI can now select and dispatch to cloud; previous standalone builds rejected cloud selection. New `context list`, `use`, and `reset` subcommands inspect profiles or save a sparse preference without resolving credentials; plain `context` still resolves a backend. Preference writes retain the existing unknown-field-discard behavior.

The unreleased SDK context revamp replaces the public backend/handle surfaces described in the historical notes above. LocalContext construction captures configuration synchronously and opens the catalog lazily. Resource identities, runtime launch and agent/control wire formats, catalog schemas, snapshot artifact formats and serialized sandbox configuration remain unchanged by that revamp. Unqualified SDK calls use the same configured destination as the CLI and default to local. Explicit resource selectors override that destination. Builders and resources retain the context they captured. See [SDK migration](docs/migrations/sdk-contexts.mdx) for application-source changes.

Profile serialization is the accepted exception: new writers emit `kind: "local"` or `kind: "remote"`; readers accept legacy `backend` and `cloud` aliases. An older SDK/CLI reading a profile rewritten by the new writer may reject it. This does not authorize rewriting resource records or relaxing runtime compatibility. Keep a copy of the old profile configuration before sharing it with older clients, and use separate configuration files when both reader generations must continue operating. Reader/writer alias fixtures and profile preference persistence tests cover the new format; they do not establish compatibility of older readers with rewritten profiles.

Selected native providers validate binding ABI 1, exact SDK version and supported local/remote capability before use. Their allocation, result-release and cancellation operations stay with the library that created the object. This wrapper/native version requirement is independent of SDK-to-runtime compatibility: choosing a selected provider does not waive the supported historical runtime boundaries. Local qualification uses released v0.7.15 runtime fixtures and does not claim a complete v0.6.x runtime matrix.

The SQLite database under `MSB_HOME` is a durable protocol between releases. Host and runtime processes must also agree on WAL, busy timeout, foreign-key, synchronous, and writer settings.

On Unix, catalog identity checks read filesystem metadata without opening an extra descriptor. Control and metrics lookups share one database identity per backend. On macOS, that identity retains a dedicated read-only SQLite connection, including after ordinary pool connections expire. SQLite owns that connection's close so verification and identity teardown preserve other connections' POSIX locks. Linux retains its `O_PATH` handles and Windows retains its file handles. Database replacement detection, schemas, journal modes, and SDK/runtime protocols are unchanged.

Source-bound snapshot groups additionally use a persisted catalog UUID and the sandbox's autoincrement row ID. Their optional `group-source.json` sidecar leaves the strict legacy `group.json`, immutable descriptors and archives unchanged. The source name is display information; deleting and recreating that name cannot redirect capture into the original history. Imported and historical groups without the sidecar remain unbound. The new capture API refuses to append to those groups and requires a new group; this is an intentional 0.8 capture-workflow change, not an artifact conversion or a restriction on reading, exporting or restoring them.

The UUID is initialized lazily in the separately versioned `microsandbox_catalog_identity` table, within one SQLite writer transaction. It adds no migration-ledger entry and changes no existing table or runtime SQL. Missing, malformed or unsupported rows in an existing identity table are refused rather than silently regenerated. Database reopen and `VACUUM` preserve identity; a separately initialized database gets a new identity. A database backup retains the backed-up identity. Qualification with the pre-change local CLI verifies catalog reopen and group list/inspect/export; it does not establish every historical binary's compatibility. Older storage writers do not enforce source binding and must not be used to append a different sandbox to a bound group's history.

Compatibility-sensitive elements include migration IDs and order, migration semantics, schema columns and constraints, persisted enum/tag spellings, JSON configuration shapes, desired versus active configuration, install and maintenance leases, allocation state, recovery journals, and the downgrade floor.

Evolution rules:

- Never reorder, rename, or reuse a shipped migration ID.
- Do not edit an applied migration to produce different previous results; add a new migration.
- Require applied migrations to form the canonical prefix and refuse a schema ahead of the current binary.
- Transform every persisted representation of changed state, including desired and active configurations.
- Journal multi-artifact operations durably and refuse startup or downgrade while an incomplete operation remains.
- Make downgrade either reconstruct the older representation exactly or refuse before mutating state.
- Preserve already-running runtimes' SQL and active-file contracts during upgrades. Exclusive installation and downgrade operations retain their own admission checks.

Sources: [`crates/db/lib/pool.rs`](crates/db/lib/pool.rs), [`crates/migration/lib/lib.rs`](crates/migration/lib/lib.rs), [`crates/migration/lib/schema_metadata.rs`](crates/migration/lib/schema_metadata.rs), and [`sdk/rust/lib/backend/local/mod.rs`](sdk/rust/lib/backend/local/mod.rs).

Local startup serializes database opening, migration, and snapshot reconciliation using the existing `msb.db.migration.lock` file and shared process-lock helper (`flock` on Unix, `LockFileEx` on Windows). This replaces the former Windows no-op without changing database schemas, lease semantics, or the lock path. Genuine exclusive install/downgrade operations still refuse normal startup. Older Windows binaries that bypass this lock do not participate in the serialization; do not initialize the same home concurrently with them. The shared helper creates owner-only lock files on Unix and refuses symlink lock paths.

Tests should open copies of real older databases, migrate them, exercise the affected behavior, and test every supported reverse migration or refusal path.

SDK and user-facing CLI catalog opens apply pending recognized migrations under the migration lock and install lease, including while older runtime processes remain active. Pending SQL migrations commit together. Fresh homes use the current SDK/CLI schema independently of the selected VM executable. Private `msb machine` launches still open runtime pools without performing migrations. Already-running VMs must retain working lifecycle writes, exit recording and resource cleanup; upgrade does not restart them or reinterpret their live configuration.

The upgrade transaction reserves SQLite's writer before migration reads, so concurrent lifecycle writes cannot interleave with partial schema changes. Older runtime writes may briefly wait for commit; migration duration and shutdown races need live qualification against their busy timeouts. After an upgrader exits, the next catalog opener can reclaim its dead-owner lease under the migration lock; live owners and incomplete downgrade journals still block admission. A downgrade rejected before artifact mutation retires its journal into a hidden `.cancelled-<operation-id>` directory, preserving diagnostic files without blocking ordinary commands. Once artifact mutation may have started, explicit downgrade recovery remains required.

Older SDKs/CLIs may refuse to reopen the upgraded catalog because its migration history is newer; preserving their catalog access is not the same guarantee as keeping their already-running VMs alive. Catalog migrations normalize previous configuration JSON before current readers deserialize it, including the saved active configuration of already-running VMs. Unknown migration identities still fail even when their count matches a known schema. These catalog rules do not replace launcher, agent, or snapshot-format capability checks.

SDK/CLI processes from v0.6.4 through v0.6.18 that opened the catalog before an upgrade rewrite `config` from a stale read on any modify with planned changes; from v0.6.9 they also rewrite the `sandbox_labels` projection. Only a modify that also makes a live CPU, memory, or secret change rewrites `active_config`. A concurrent live label change can be lost from the copies such a modify rewrites; recovery requires setting the affected label again. Of the three label copies, only `active_config` is compare-guarded, and only on a live label change; `config` and the projection remain last-writer-wins for every modify, as before.

The guest-clock migration adds only a compatibility marker, so older SDKs/CLIs refuse the catalog before dropping `runtime.guest_clock`. It does not change tables, saved settings, or running VM behavior. Rolling back the marker checks raw JSON in both `config` and `active_config`; only absent, null, or explicit `sync` policies are representable by older readers. A non-default or unrecognized policy, or invalid JSON, refuses rollback without rewriting settings or removing the marker. The existing downgrade preflight runs this check before live state is changed.

Windows abandoned-lease recovery checks whether the process has exited, not merely whether its PID can be opened: another process may retain a handle to the terminated owner. Unix retains its conservative PID-existence check during resource teardown. Both paths preserve live owners, match the observed lease before clearing it, and refuse admission while an incomplete downgrade journal exists.

Downgrade operation ownership uses the existing `db/self-downgrade/msb.db.migration.lock` path and OS lock protocol, but competing commands fail immediately instead of waiting through another command's download or confirmation prompt. Ownership lasts through staging, execution and journal retirement, separately from the catalog migration lock. Exiting releases ownership without deleting the lock file or bypassing an incomplete recovery journal; an older command's lock still excludes a newer contender.

Caller overrides are saved in the optional `sandbox.caller_config_overrides` column. A digest ties them to the resolved config; changes from older writers invalidate them. Older rows have no saved overrides. Rollback drops only this column, preserving resolved and active configs. Restore resources and registry credentials are excluded; snapshot and runtime formats are unchanged. Inline secret values are saved in both the resolved config and caller overrides; source-backed secrets retain their references.

Rebuilds now preserve explicit settings and clears. Use builder setters, `overlay()`, or modification APIs: saved overrides can overwrite direct edits to a resolved `SandboxConfig`.

Incomplete local creates use the additive `m20261024_000001_sandbox_creation` migration. The nullable `sandbox.creation_state` records `preparing` or `prepared`; NULL means creation is complete. The nullable `volume.pending_creation_sandbox_id` references the sandbox whose unfinished creation owns that new volume, with `ON DELETE RESTRICT`. Preexisting volumes are not marked. If interruption or cleanup failure leaves marked volumes, remove or replace their owning sandbox rather than removing those volumes individually. Cleanup removes files before clearing the markers and deleting the owned volume and sandbox rows in one transaction. Triggers prevent restarting incomplete sandboxes or prematurely deleting marked resources. Downgrade refuses while either marker remains; explicitly remove or replace incomplete sandboxes first. Existing lifecycle status values are unchanged, and old runtime SQL leaves the added columns untouched. Archive extraction reserves an ordinary incomplete sandbox row before writing staging files, so interruption leaves a visible `archive-stage-*` owner that can be explicitly removed. The destination is not replaced until archive admission succeeds; after transfer, the destination row owns the files before the staging row is retired. This uses the same migration and does not add a table or alter the archive format. Preparation uses a separate `.creation.lock` beside the existing transition lock. Filesystem workers retain that lock after task cancellation, and recovery tests lock ownership rather than PID liveness. Successful creation publishes `Running`, restores the requested ephemeral flag, and clears both markers in one transaction after validation.

Standalone volumes additionally use `m20261029_000001_volume_creation`: nullable `volume.creation_state` is `creating` until formatting succeeds and NULL afterwards. The row and marker commit together before files are written. A filesystem worker retains the existing volume-name lock after caller cancellation; removal waits for that worker, deletes files first, then clears the marker and deletes the row in one transaction. Pending volumes remain listed for recovery, but lookup, filesystem access, and sandbox adoption reject them. Explicit volume removal recovers them even after a process crash. Downgrade refuses until incomplete standalone volumes are removed. Existing completed rows and old runtime writes keep their previous meanings; no launch or guest protocol changes are introduced.

The existing unknown-migration admission rule still applies: older SDKs and CLIs refuse to reopen this upgraded home. Use a supporting SDK and CLI, a supported downgrade, or a separate `MSB_HOME`. Already-running older VMs retain their existing sandbox/run tables and SQL; their continued operation must be validated separately from catalog reopening. No stop-all-sandboxes upgrade gate is added. The recovery ordering covers launcher/process interruption; it does not strengthen the catalog's existing host-power-loss durability settings.

### Protected sandbox state

The protected-layout security exception requires a patched SDK/CLI and a runtime advertising `protected_guest_state` for every new VM launch, including restart and restore. Missing capability or a failed probe produces an upgrade-required error before layout migration. The existing catalog admission rule excludes old SDKs/CLIs from an upgraded home; old tools remain usable in eligible unupgraded homes. Stop old SDK/CLI applications sharing a home during its upgrade. Already-running VMs retain their existing database contract and gain the new boundary only after restart. New SDKs refuse live storage capture and maintenance until that restart; exec and stop remain available.

Only `sbx/guest-state/` is exported as `/.msb`; authoritative root/owned-disk journals, checkpoints, object stores, and growth/compaction staging live in the host-managed sandbox namespace. Legacy parsing proposes disk views within independently established host-configured roles; it never authorizes a new path. Migration pins regular no-follow sources, accounts for aliases and excludes related writers, then captures independent clone/sparse copies. Explicit external disks retain their write-through binding. Ambiguous complete views require explicit identity-bound selection; missing dependencies and unauthorized sources remain rejected.

Capture holds per-file read leases on Linux and deny-write/delete handles on Windows, rejecting existing writable handles or mappings. A broken lease invalidates the capture epoch. macOS requires explicit maintenance recovery with an operator confirmation that legacy VMs across all homes are stopped and old-tool launches or writes to the selected storage are prevented until completion. Same-home transition/lifecycle checks remain defense in depth; one catalog cannot prove global writer quiescence. New creation and ready-layout operations bypass these migration-only gates. A durable group certificate follows capture of every selected disk and a final source-identity/lease audit in one protected epoch; full metadata validation still precedes Ready publication. Uncertified partial captures are discarded and recaptured together on resume; certified internal captures no longer depend on retained originals, while external write-through disks still require their original identity and writer protection.

The existing explicit storage-preview API captures complete alternatives into private staging before admitting the sandbox. It shares copies of common layers and materializes each requested view separately. A dedicated runtime capability and guest reader are required for filesystem inspection. The reader receives detached, read-only disks. For a managed OCI root it combines the captured upper with the image's matching lower. Confirming a choice revalidates the disk group and binds the selected layers to their reviewed contents through transaction recovery. Cancellation before admission discards the session without changing the sandbox's protection or active disks. Normal interactive repair imports the validated existing selection without invoking this preview API or asking the user to choose a disk version. Unresolved layouts are reported for maintainer investigation. The CLI accepts `--sandbox` for diagnosis and repair while retaining positional targets. CLI safety confirmations are interactive; noninteractive repair returns a blocker when consent or investigation is required. JSON output and explicit SDK recovery APIs remain available. Its multi-sandbox interface runs each repair through the same lifecycle and writer checks, records partial actions, and never uploads diagnostic reports.

Legacy admission also validates destination namespace authority without repairing permissions. Execution retains Windows no-delete handles on stable publication parents through completion; Unix traversal exemptions require a verified private ancestor. A shared 256 MiB budget bounds estimated eager parser metadata across the selected root and owned-disk group before full parsing. This is not an RSS or total VM memory bound. Recheck the accounting when changing the pinned parser dependency. These checks do not inventory new or already-ready storage.

Read-only inspection precedes backend initialization and permits only SQLite's ordinary WAL/SHM read-lock coordination. Windows legacy import also checks catalog permissions without repairing them before deriving disk authority. Fresh initialization requires the live creation call's reservation identity and saved configuration, not a catalog flag alone. Admission validates before registering protection. The private `.storage-migration/operation.json` freezes the operation, configuration identity, original journals and selected objects. Its distinct in-progress schema is also published at `state-layout.json`, where schema-1 readers reject it. Durable catalog protection and both legacy-path guards precede capture; every required disk journal is published before the schema-1 ready marker. Interrupted admission resumes forward, never by removing guards or rediscovering a different head. Already-ready sandboxes skip migration inventory, capture and admission writes. Legacy journal and heartbeat guards reject old runtime startup; they do not isolate an already-exploited process running as the same host user.

## 7. Home and Runtime Path Layout

Directory names under `MSB_HOME` and the runtime directory are durable locators used by binaries from different releases. This includes the database, cache, sandboxes, volumes, snapshots, logs, secrets, TLS material, SSH state, sockets, locks, journals, and configuration files.

Sources: [`crates/utils/lib/lib.rs`](crates/utils/lib/lib.rs) and [`crates/runtime/lib/client/ipc.rs`](crates/runtime/lib/client/ipc.rs).

Renaming a directory or file requires migration or old-location probing. Preserve atomic publication and cleanup ordering, and never infer that an unrecognized old path is safe to delete.

Unix FUSE initialization preserves the runtime process umask. Guest creation modes still use the guest request and mask; new host-managed files and directories request `0600` and `0700` and clear inherited ACLs. Explicit repair of stopped, protected sandboxes tightens recognized host state and clears its ACLs, including intentional sharing on that state; guest-state and directory-volume contents, external mounts, shared caches, and unknown paths remain excluded. Repair leaves already-private snapshot hardlinks unchanged and refuses non-private links outside the recognized set or objects replaced since inspection. No catalog, journal, launch, or guest-protocol format changes; Windows ready-storage repair remains a no-op.

## 8. Disk and Filesystem Image Formats

Disk-image bytes outlive the binary that produced them. ext4 compatibility includes superblock feature flags, group descriptors, checksums, inode size and reserved inodes, 64-bit layouts, JBD2 journal state, resize-inode behavior, clean/dirty state, and replay requirements. EROFS and VMDK constants, descriptors, block sizes, extents, device tables, adapters, and alignment rules are likewise durable formats.

Sources: [`crates/image/lib/ext4`](crates/image/lib/ext4), [`crates/image/lib/erofs/format.rs`](crates/image/lib/erofs/format.rs), and [`crates/image/lib/stitch/vmdk.rs`](crates/image/lib/stitch/vmdk.rs).

Parsers and mutators must validate the complete supported feature set before their first write. Unsupported state must fail cleanly without partially updating metadata. Tests for mutators must use multiple previous layouts, dirty and journaled images, boundary sizes, failure injection, filesystem checkers, and post-operation mount/read/write verification where the platform permits.

## 9. Snapshots, Manifests, and Portable Archives

Dedicated full restore now requires captured external filesystem and additional-disk bindings by default. `--allow-missing-resources` and the equivalent SDK restore option explicitly retain unavailable devices; neither resource inheritance nor relaxed captured-object validation waives the completeness check. This is an intentional behavior change for new restore callers, not a snapshot or database migration. Direct branching retains its existing resource-selection semantics. Disk-only restores now require mappings for recorded external binds unless missing resources are explicitly allowed. The check runs in the SDK before VM launch, including when using an older runtime. Only relaxed object validation combined with required backing sends the optional `require_backing` field inside the strictly decoded external-mount launch binding. That combination probes `required_restore_backing` through the existing `__launch-protocol` command and returns an upgrade-required error when unsupported. Ordinary strict restores omit the field and need no extra probe; older SDK requests retain their existing wire interpretation. Missing root/owned payloads, malformed snapshots, and incompatible mount flags are never waived. Custom-vsock route completeness is not enforced by this storage admission check; previous captures do not contain a portable route inventory.

Disk snapshots may carry the advisory `microsandbox.external-mounts` descriptor extension, which lists guest paths only (never host paths) of mounts whose backing is not captured. It is never in `requires`, so older readers ignore it and restore as before; snapshots without it are unchanged.

Disk-generation manifests now carry an exact `file_size` and an optional `integrity_root`. Root disks and copied external/named disks in new full checkpoints and local branches default to structural validation without content hashing; explicit integrity capture records roots, and recorded roots are verified on portable admission. RAM object IDs and verification remain unchanged. This replaces the unreleased disk-generation contract without a format-version bump: earlier development checkpoints missing file sizes and older readers requiring disk roots are rejected. Released disk-only descriptors are unchanged. Control capability `optional_disk_integrity` gates full/branch capture on matching running runtimes; neither SDK launch nor root-disk journal initialization implicitly computes missing disk hashes. The Go FFI retains its existing branch calling convention and adds an optional, capability-checked integrity entry point. Sandbox-owned disks retain their existing journal integrity policy and record hashes during capture. Their portable descriptors also carry exact file sizes; readers check recorded hashes and always check lengths. Hashless owned layers remain included in archives rather than becoming hash-based borrowed dependencies.

Unreleased full checkpoints require an explicit `geometry` record in `checkpoint.json`: original CPU count/capacity and initial RAM/capacity. Live resize targets cannot substitute for the original guest-physical layout. Capture writes the public requirements summary from this runtime-owned record; restore rejects disagreement before RAM preparation. CPU and virtio-mem state retain the actual/requested counts and plugged-block bitmap separately, including unfinished resize operations. Earlier development full checkpoints missing these records are rejected, not guessed or migrated. This is an approved replacement of unreleased full state; released disk-only descriptors and archives are unchanged.

The global setting `snapshots.max_filesystem_state_mib` (default 4, valid 1 through 4095) sets the virtio-fs backend state budget per device. The admitted size of a virtio-fs (type 26) device-state object derives from that budget through the libkrun device state codec, and other device types admit 1 MiB. Encodings are unchanged. At the default, every checkpoint written by a released version stays admitted; a budget below the default can refuse checkpoints that default hosts accept. Readers from v0.7.0 through v0.7.6 refuse virtio-fs state objects over 1 MiB during verification, export, import, and restore. A reader with a smaller budget refuses a larger state before changing anything. Older releases ignore the `snapshots` key and keep their 4 MiB budget, so they fail closed on larger states. The launch field `fs_state_limit_bytes` is omitted at the default; a non-default value needs the runtime `fs_state_limit` capability, so older runtimes are refused before launch, and the previous launch contract refuses it.

Archive build scans descriptors and checkpoint metadata without extracting payloads or retaining temporary storage. Captured settings continue through the existing sparse configuration layers. Creation extracts into private staging, verifies the admitted descriptor identity, and validates the resulting resources before replacing a destination. The original archive must remain available through creation; changing its admitted descriptor is rejected. Compressed inputs may still be streamed during metadata inspection. Payload integrity errors can surface during creation rather than build. Archive formats, extensions, database state, and SDK/runtime protocols are unchanged.

Snapshot descriptors carry a stable random `snap_...` ID; their canonical bytes determine the descriptor digest, not that ID. Compatibility-sensitive elements include field order, required `null` values, map ordering, duplicate-key handling, tag spellings, schema and integrity identifiers, payload names, parent identities, state/scope/format variants, extension requirements, and translation-graph behavior.

Archive compatibility includes compression detection, `archive.json`, canonical inventory order, transport digests, accepted path grammar, legacy paths, cache-closure entries, and rejection of duplicate, missing, or escaping paths.

Installed snapshots now live under `snapshots/<group>/<snapshot_id>/`. `group.json` selects a head; `group-member.json` stores a local friendly name without changing descriptor identity. Bare selectors mean a group head, and `group:member` selects an exact member. Existing flat artifacts remain readable by explicit path; this change does not silently move their directories. The index keys local artifact paths rather than globally unique portable IDs/digests, so importing the same snapshot into two groups preserves both copies. Downgrade refuses grouped state before rewriting artifacts or rolling back the index.

Capture records the actual source snapshot lineage in the existing descriptor `parent` field. Per-sandbox cursor publication serializes captures without holding a VM pause; group head publication is locked separately. Automatic head advancement requires known ancestry, not capture timestamps, export dependency bases, or import order. An explicit head selection may rewind or choose a sibling. Missing ancestry may prevent advancement but is not a missing payload dependency. Archives optionally carry friendly names in `msb-snapshot-member-names`; their snapshot IDs, payload paths and descriptor schema are unchanged.

Capture publication and source removal/replacement share a stable lock in `run_dir/locks/<lifecycle-hash>.snapshot-lineage.lock`, outside the removable sandbox directory. A caller needing multiple ownership guards acquires transition, then lineage, then runtime lifecycle ownership. The cursor remains in the sandbox directory; its schema and portable snapshot identities are unchanged. This replaces the unreleased directory-local lock, not a shipped artifact format.

Snapshot cleanup coordination is host-only: descriptor, archive, catalog, and SDK/runtime wire formats are unchanged. Unix readers retain descriptor locks. Windows readers normally use the existing per-entry `.msb-leases` namespace outside the removable snapshot directory, falling back to a descriptor lock when an external parent denies sidecar creation. Deletion checks descriptor-only readers before closing its own descriptor handle for the Windows rename; a later descriptor reader makes that rename fail. Older SDKs and CLIs do not participate in this lease protocol, so concurrent cleanup with them still requires coordinated maintenance.

Cleanup recovery retains the existing descriptor, group, journal, and catalog formats. Republishing an installed snapshot preserves its availability when publication fails; absent artifacts still reserve `publishing` before installing files. Removing a stale grouped index entry is allowed only after the whole group directory disappears, with the existing digest and child checks. Malformed deletion records with quarantined payloads retain those payloads and identify the journal in the error. These changes do not alter SDK/runtime protocols or require a catalog migration.

The unreleased group-writer coordination uses a separate per-group admission key in the store root's `.msb-leases` directory, outside the replaceable group. Updated capture publication, import, head mutation, removal, and deletion recovery enter before creating member leases or mutating group paths; detached workers retain admission through their work. Capture staging is a hidden sibling of the group. Existing descriptor and namespace reader pins remain independent, and no descriptor, archive, catalog migration, or runtime message changes are required for this coordination. Unmodified writers do not honor the new gate, so it cannot enforce a mixed-version maintenance window by itself.

Windows atomic imports use the explicitly approved Transactional NTFS (TxF) dependency. The importer resolves the optional APIs dynamically, checks the destination filesystem and its transaction capability, and qualifies an actual disposable rename/rollback before staging archives or reserving a group/catalog entry. Unsupported or disabled TxF fails with an actionable error; it never falls back to partial publication. This restricts the import destination to supported NTFS volumes, without changing snapshot descriptors or SDK/runtime protocols. Group directories and coordination files retain their identity; new members, reused aliases, head and the recovery commit marker change in the same filesystem transaction. Catalog completion is journaled separately and remains recoverable after process death. This does not authorize concurrent uncoordinated older storage writers or claim power-loss qualification.

Archive imports resolve the existing destination group before reserving member paths, so publication retains one canonical catalog address on Windows and through symlinked ancestors. Publication recovery atomically replaces the supplied alias row together with its canonical row; it does not merge distinct artifact paths by portable identity. Existing pending rows remain recoverable without a schema, descriptor, archive, or SDK/runtime protocol change.

`snapshot load` accepts multiple archive paths; the former positional destination is now `--dest DIR`. Single-archive SDK methods and their return types remain; batch methods return one handle per input archive head in input order. The batch resolves exact disk-layer and RAM-object dependencies from supplied archives, the explicitly selected destination group, and an optional external base. No archive encoding changes or global snapshot search are involved. Borrowed payloads belong to destination staging and use the existing integrity codecs before publication. A compatible source may contain more layers than the omitted prefix; dependency identities still must match. Direct archive restore retains its explicit-base contract.

Batch head selection is independent of input order: one proven lineage tip uses existing fast-forward rules; ambiguous tips preserve an existing head or leave a new group headless. `--set-head` refuses an ambiguous batch. IDs, aliases, duplicate labels, and payloads are checked before member publication. Atomic batch publication exposes either the previous membership/head or the complete resulting group. On macOS and Linux, capability checks require hard links, atomic directory exchange and directory durability; unsupported destinations refuse before publication without a non-atomic or payload-copy fallback. Immutable payloads and existing reader-lock files retain their inode identity, while mutable metadata is prepared separately. A failure after exchange but before the parent-directory durability flush reports an unknown outcome and retains the previous generation; recover through the same group before retrying. A committed filesystem journal makes SQLite completion recoverable. On Windows, the approved capability-gated TxF publisher provides atomic publication. Older readers remain supported, but operators must suspend and drain conflicting older capture/import/removal/head-edit/reindex/prune writers during import and recovery; unrelated running VMs need not stop. These changes do not rewrite archive or immutable descriptor formats.

Complete-directory publication writes a `.group-preparations` record into the current group before linking any payload into a private generation. It pins the staged sibling name and directory identity so a new writer or catalog recovery can reclaim abandoned preparation under stable writer admission. The record is not copied into the new view: after exchange, the old view and its preparation records are reclaimed together. Recovery refuses substituted directories and symlinks and never scans unrelated private directories for deletion. An interruption before this record is durable can leave an empty temporary directory, but no staged payload links. Existing unjournaled development leftovers are not inferred to be safe to delete. Complete-directory publication also writes a separate `.group-retirements` record into the new view before exchange. It records only the retired sibling name and its filesystem identity; recovery validates both, flushes the live view, removes the retired payload links, and durably retires the record afterward. Interrupted cleanup remains retryable even if an older reader already consumed the original-format catalog-deletion receipt. Private generations are excluded from recovery discovery: they are reclaimed through their live group under its stable writer admission, never treated as independent groups. Existing snapshot descriptors, archive formats and deletion-receipt schemas are unchanged.

Unreleased #8 incremental exports use `completeness: "dependent"` and the must-understand `msb-snapshot-dependencies-v1` extension. `--since` records omitted physical disk-prefix layers and reusable RAM-object identities; `--last-layers` only omits disk layers. The complete target memory manifest and CPU/device state remain included. Loading and direct archive restore resolve the explicitly supplied base into owned staging before opening the complete target. This replaces the unreleased disk-only dependency encoding without a compatibility shim or snapshot descriptor change. Readers that do not understand this requirement refuse it; ordinary standalone archives are unchanged.

Full checkpoints and local branches now retain `transport_host_input`, `transport_input_credit`, and `transport_guest_bulk_bytes` in the existing `guest:agentd` resource binding. These are complete-frame cumulative positions and absolute grants, including credit still owned by pending captured input. Restore validates and seeds them before guest activation; resetting them would incorrectly grant capacity twice. Older unreleased development full snapshots missing this state are refused, and new full captures require their matching host/guest implementation. This is an approved replacement of unreleased state, not a snapshot schema bump or migration; released disk-only snapshots are unaffected.

The finalized private transport-credit contract charges stdin, inline filesystem/TCP payloads, and ordered EOF to the existing logical data (`bulk_*`) counters on either physical port. Command/control counters remain available when captured input is still awaiting consumption. Ready advertises barrier contract `2`; the superseded development contract `1` is not translated or restored. The outer frame, generation-8 data format, snapshot descriptor schema, and public SDK requests are unchanged. The ordinary writer retains bounded admission permits until physical delivery, permits unrelated metadata to pass credit-blocked payloads, and preserves per-correlation and client-disconnect ordering. Guest input processing also yields to the runtime after bounded actual reads, including partial records; this does not shrink wire records or change snapshot boundaries.

Routine host clock maintenance is independent of unrelated correlation input, but stays ordered with other clocks and true global lifecycle fences. Its timestamp is sampled at console admission, not when queued; disconnect cleanup signals fence their own session only. Maintenance remains subject to the pause gate. This bounds host-queue timestamp age, not subsequent aging of already-admitted bytes during arbitrary host suspension or the kernel-only pause fallback when the workload freezer is unavailable.

Local execution signals can use the optional host-only `exec_control` Ready extension and generation-two `control.exec.signal` operation on the existing host-control endpoint. This capability requires acknowledged guest range leases and bounded, nonblocking input contract `2`. Its random connection token is ephemeral, never captured or persisted, and is revoked with the owning agent connection; queued requests also retain a revocable execution lease. Immediate signals wait for `ExecStarted`. Signals and disconnect cleanup may pass unadmitted stdin/EOF, while accepted stdin and EOF retain their byte order. Process creation, client-range transitions, and pause/capture gates remain authoritative. Graceful shutdown can interrupt queued exec input but retains ordering with other effects, including filesystem writes; a stop timeout never authorizes force termination. The control dispatcher has two bounded lanes, with FIFO retained within each connection, so a pending paused signal cannot prevent Resume. Native local SDK connections use the advertised route; arbitrary streams and peers without the capability keep their existing transport. New managed jobs refuse unsupported guests before launch. Delivery acknowledgement confirms the complete console write, not guest signal handling or process exit; failures are explicit, admitted timeouts may still deliver, and callers must observe the terminal result rather than replaying a signal automatically. Existing public Ready struct literals, SDK method signatures, guest message types, frame layout, and snapshot descriptors are unchanged.

On Windows, console readers await in-process wake notifications instead of scheduling a blocking wait every 100 ms. The native manual-reset event remains available to synchronous consumers; cancellation drops the async wait without leaving a blocked worker. This changes no launch, console framing, agent capability, or SDK/runtime wire contract in either direction.

Managed-job terminal attachment retains bounded local input and drains bytes preceding Ctrl-] to runtime admission before releasing its lease. A two-second drain limit returns the local `input_not_flushed` error on incomplete or ambiguous delivery; it does not send EOF, terminate the job, or replay unconfirmed bytes. Windows managed-job console delivery uses an opt-in bounded, cancellable queue, while existing sandbox attach and SSH retain their current event delivery. Python preserves explicit null stdin separately from omission, so detached null input closes and omitted input retains its pipe. These corrections change no public signatures, host/guest operation, capability gate, launch JSON, persisted job record, or catalog schema.

Evolution rules:

- Do not make semantically harmless serialization changes to identity-bearing bytes without treating them as an identity format change.
- Keep legacy descriptor translation explicit; do not rely on a permissive generic reader when exact reconstruction matters.
- Use additive extensions with sorted must-understand requirements, or introduce a new schema plus forward and reverse translation.
- Publish payloads first and the verified descriptor last through temporary files, fsync, and atomic rename.
- Keep downgrade refusal until durable reverse artifact migration is complete.

Sources: [`crates/image/lib/snapshot/manifest.rs`](crates/image/lib/snapshot/manifest.rs), [`crates/image/lib/snapshot/migration.rs`](crates/image/lib/snapshot/migration.rs), and [`sdk/rust/lib/snapshot/archive.rs`](sdk/rust/lib/snapshot/archive.rs).

Runtime restore checks disk structure and exact file lengths before activation, and verifies content roots when recorded. Root-disk journal creation may reuse a recorded root only for the same unchanged immutable file; it never hashes an unrecorded layer implicitly. Its in-process cache retains at most 32 file handles, preferring larger physical files. Rewritten layers with recorded integrity receive a new root; unhashed layers remain unhashed. Detected mutation of a retained admitted file fails. Candidates are opened once per lookup, with comparisons bounded by the cache size. This reuse is not a persistent "verified" flag or a path-only cache, and the cache bound does not reduce supported chain depth.

Direct local branching prepares an immutable RAM baseline before freezing the workload; the paused capture still chooses the authoritative dirty generation and discards prepared baseline bytes when a complete capture is required. Linux local copies may use kernel-assisted extent transfers, while the explicit durable sparse-copy contract remains unchanged. Preparation time and allocated baseline bytes are recorded separately from guest dirty-page capture. This changes pause duration, not the captured epoch or durable snapshot format.

Linux ephemeral branching uses the capability-gated `branch_create_memfd` operation. The launcher creates an empty sealable memfd and transfers it with the first JSON byte over the existing control socket using SCM_RIGHTS. The source validates it before capture, fills it only when exact geometry and RAM admission allow, then applies write/grow/shrink/seal seals. The launcher already owns the object before source mutation; a read-only handle is inherited by the child at descriptor 95. The strict restore envelope's `memory_descriptor` field and local handoff's `memfd_lease` field require explicit descriptor-aware readers. Missing descriptors, mismatched geometry, and unsealed backing fail rather than becoming a pathname restore or cold boot. Descriptor requests are one-shot, not replayable control envelopes. No guest protocol or portable snapshot format changes.

The first capture still uses disk backing because configured guest MiB excludes some architecture-specific mappings. A reflink-capable backend or insufficient host/cgroup headroom also retains disk backing. Allocation failure before freeze releases partial RAM before one disk attempt. Changed topology discards the bounded reservation and uses a full disk capture. Ordinary non-Linux branch requests retain their existing named backing. A new Linux SDK refuses an old source without the descriptor capability before capture; an older runtime rejects the strict new restore fields. Existing disk handoffs remain readable. This replaces the unreleased named `/dev/shm` fast path without making previous RAM files eligible for automatic removal.

Only small, owner-only accounting records and stable handoff locks live under `/tmp/microsandbox-memory-<uid>/`; guest RAM does not. Pending captures reserve full capacity, completed generations account allocated backing bytes, and concurrent captures leave headroom for private writes. Source, launcher, and child pins protect accounting across handoff and source deletion. The kernel releases memfd bytes after all descriptor/mapping references disappear; later allocations reclaim unused lease records. This is potentially swappable local backing, not durable storage, a full-host admission guarantee, or zero-copy sharing between distinct generations.

Local disk handoffs retain child-owned immutable hardlinks and confined backing-name aliases. The child adopts these files and adds its own writable head instead of relocating the chain again. Older or imported non-basename references still use per-layer relocation. Optional host-owned admission receipts reuse integrity only for the same unchanged file identity, length and modification time; missing receipts use ordinary validation. Source journal durability is unchanged, and consumed handoff cleanup retains the child's disk layers for later cold restart. Mount-warning diagnostics are atomically replaced before readiness without a durability flush; they remain outside the guest-writable runtime share.

Incremental capture retains immutable object receipts only within the owning runtime's store lifetime. Reopened stores and unadmitted objects still verify bytes. Receipts retain no file descriptors; active operations open, check and temporarily pin the exact file. Capture uses two writers and three recycled 32 MiB packs, then synchronizes new directory entries before the existing root-last publication. Eager restore and cold memory-cache construction use at most four reusable 32 MiB read/hash buffers. Errors join workers before cleanup. These changes preserve the snapshot format and restored bytes, dirty-baseline rollover, pause/publication ordering and durability barriers; summed worker timings must not be interpreted as additive wall time.

Customer checkpoint fixes retain original construction geometry separately from actual/requested hotplug state. The virtio-mem device-local payload is schema 2: unplug acknowledgement now guarantees zero-on-reuse, and capture may represent actual unplugged blocks as zero without reading the reservation. Older development schema-1 device payloads cannot prove that promise and are rejected. Shrink and replug remain dirty transitions, so a delta replaces inherited nonzero bytes rather than leaving them implicit. This does not change the outer snapshot descriptor schema or released disk-only formats.

External filesystem capture uses defaultable freeze tags and an `external_mounts_synced` acknowledgement; absence is not proof of writeback. A full checkpoint with external mounts fails closed without that proof. Restored exports retain exact transport/node/handle identities; strict is default, and relaxed mode uses explicit EIO/ESTALE backends without recreating host data. Source-local authorization and restore warning records are host-only files in the sandbox directory, not the guest-writable runtime share. Cross-host archive paths grant no host authority. Managed additional disk volumes carry standalone immutable generations and become child-private disks; incremental root-prefix selectors never omit them accidentally.

For flat roots, `--with-image` archives may contain image configuration without layered EROFS/VMDK artifacts: the snapshot already supplies the whole root disk. Managed/tmpfs image dependencies still require the complete layered cache. An included layered cache must be complete even for a flat target; malformed partial bundles are not accepted. Older development readers that require layered artifacts refuse metadata-only bundles rather than silently cold-booting or substituting an image.

## 10. OCI Cache and Materializer ABI

The cache is rebuildable, but cache entries and closures can cross releases through `MSB_HOME` and snapshot archives. OCI semantics are externally defined: compressed descriptor digests, uncompressed diff IDs, ordered layers, whiteouts, opaque directories, hardlinks, extended attributes, non-UTF-8 paths, special files, and permissions must retain their meaning.

Flat filesystem cache identity includes a materializer ABI. Bump that ABI whenever emitted filesystem bytes or interpretation can change so incompatible entries miss instead of being reused. Preserve content-addressed verification and never retain bytes under a mismatched digest or size.

Sources: [`crates/image/MATERIALIZATION.md`](crates/image/MATERIALIZATION.md), [`crates/image/lib/cache/store.rs`](crates/image/lib/cache/store.rs), and [`crates/image/lib/flat.rs`](crates/image/lib/flat.rs).

## 11. Host Filesystem Metadata

Bind mounts and volumes persist virtual Linux stat information outside the guest. Linux uses the `user.msb.override_stat` xattr with a fixed packed versioned payload. Windows uses an alternate data stream or `.msb_override_stat` sidecar. The hidden synthetic `init.krun` entry is also a reserved filesystem contract used to inject agentd.

Compatibility-sensitive elements include xattr, ADS, and sidecar names; payload version, width, and byte order; uid, gid, mode, and rdev interpretation; symlink representation; path encoding; hidden-metadata filtering; reserved inode/handle values; and whiteout immunity.

Guest xattr access on Unix passthrough host mounts is limited to user.* attributes outside Microsandbox's reserved user.msb and OverlayFS's user.overlay namespaces. New runtimes hide other host xattr namespaces and reject guest reads, writes, and removals; older runtimes retain their previous behavior. Existing host xattrs are not rewritten or removed.

Sources: [`crates/filesystem/lib/backends/shared/stat_override.rs`](crates/filesystem/lib/backends/shared/stat_override.rs), [`crates/filesystem/lib/backends/passthroughfs/windows`](crates/filesystem/lib/backends/passthroughfs/windows), and [`crates/filesystem/lib/backends/shared/init_binary.rs`](crates/filesystem/lib/backends/shared/init_binary.rs).

New metadata layouts require a new decoder version and, when old writers must consume the state, a migration or clean refusal before mutation.

## 12. Runtime, Agentd, Libkrun, Firmware, and Kernel Bundle

The runtime, embedded agentd, exact `msb_krun` version, libkrun ABI, firmware, and patched kernel form one release unit. Their interfaces include virtio feature bits, device config layouts, console behavior, metrics and CPU-capacity devices, vsock behavior, TSI behavior, firmware filenames, and platform-specific VMM backends.

Sources: [`Cargo.toml`](Cargo.toml), [`crates/filesystem/build.rs`](crates/filesystem/build.rs), [`crates/filesystem/lib/agentd.rs`](crates/filesystem/lib/agentd.rs), [`crates/utils/lib/lib.rs`](crates/utils/lib/lib.rs), and [`vendor/libkrunfw/patches`](vendor/libkrunfw/patches).

Do not independently substitute or upgrade one component because its upstream ABI appears compatible. Verify the release bundle as a unit on every supported OS and architecture, including the embedded matching agentd, firmware/kernel, library soname, device behavior, and package-version checks.

The bundled Linux 6.12.118 kernel requires the virtio-fs completion-length fix in `msb_krun` 0.1.46. Ship the runtime and firmware together: older hosts report zero used-ring lengths and fail the kernel's response validation before guest initialization. The updated host also supports the previous 6.12.117 kernel. Full memory snapshots retain their captured kernel; installing new firmware does not add multigrain timestamps to those snapshots or already-running guests. A fresh guest boot uses the updated kernel. The backport improves observed nanosecond mtime/ctime updates on guest tmpfs, ext4, XFS and Btrfs without changing the timer frequency; it does not guarantee unique millisecond-rounded timestamps or change host-shared virtio-fs timestamp behavior.

Normal x86 boot now declares `krun.poweroff=i8042` in libkrun's default kernel command line. Matching libkrunfw registers a low-priority final poweroff handler that sends the existing i8042 exit byte after orderly Linux shutdown. Generic KVM identity is not enough to enable it. Without both the host declaration and the new kernel, Linux may halt without releasing VMM ownership; StopWithTimeout reports expiry without killing. Existing running guests and full snapshots retain their captured kernel and require a fresh boot/recapture to acquire the handler. ARM platform poweroff, explicit custom command-line replacement and SEV/TDX built-in overrides are unchanged; they are not implicitly qualified by the normal Linux x86 test.

## 13. Networking, DNS, Published Ports, and Secret Substitution

Gateway DNS rebinding protection also gates local-network discovery. `.local` requires broad native `Private` access; reverse zones containing restricted addresses require authorization of the whole zone, including ordered denies and the platform floor. A single allowed private subnet no longer enables all `.local` discovery. Response owners, embedded names and addresses are checked before caching, including configured NAT64 translations. Restricted ancillary RRsets may be removed from independently complete successful answers; incomplete replies are refused. Removing restricted records clears AD and whole-message signatures and removes signatures covering discarded RRsets. Clients depending on that metadata may fail validation. Explicit guest-selected resolvers retain their answer-address filtering and routing contract, and rebind-off remains an opt-out. No launch, agent, SDK, or persisted schema changes are introduced; older running runtimes retain their previous DNS behavior until restarted with the patched runtime.

Strict hostname policy is enabled by default. The v0.6.0–v0.6.17 launch gate rejects strict policies containing outbound hostname allow rules, including domain suffixes and rules applying in both directions. Policies without those rules retain their existing behavior on older runtimes because strict enforcement is unused. Explicit `strict: false` remains supported.

Observable network behavior is an effective compatibility contract. It includes default MTU, sandbox-slot address derivation, IPv4 subnet sizing, guest and gateway offsets, IPv6 prefixes, deterministic MAC addresses, interface name `eth0`, `host.microsandbox.internal`, DNS UDP and TCP behavior, DNS-over-TLS, TLS interception and trust paths, published-port binding, TCP half-close, UDP peer lifetime, destination policy, and host-side secret placeholder substitution.

TLS reconnects may use SNI to revalidate an expired DNS binding. A fresh policy-filtered answer must contain the chosen IP before connection policy is rechecked; no prior guest lookup is required. Deferring SYN admission never dials upstream. Non-SNI connections, UDP, ICMP, and ingress still require live bindings. No launch fields, persisted formats, protocols, SDK contracts, or agent/kernel requirements change. Older runtimes retain their previous TTL-expiry behavior.

Omitted HTTP denial settings now default to enabled + JSON, including in older payloads and saved configs. Denied requests may return `403` instead of a connection error; callers must check status. Set `deny_response: false` for silent closure or `deny_response_format: text` for legacy bodies and `{host}` substitution. JSON requires the `http_deny_json` runtime capability. Cloud behavior is unchanged. See [denial responses](docs/networking/overview.mdx#what-a-denied-http-request-sees) for message settings and protocol limits.

Network idle sleep is bounded by the existing one-second cleanup deadline and any earlier stack or deferred-close deadline, with packet and proxy events still waking it immediately.

Sources: [`crates/network/lib/lib.rs`](crates/network/lib/lib.rs), [`crates/network/lib/engine/network.rs`](crates/network/lib/engine/network.rs), and the remaining modules under [`crates/network/lib`](crates/network/lib).

Address or MAC changes can create collisions or silently alter policy identity. Protocol changes should be tested with real TCP, UDP, DNS, TLS, HTTP CONNECT, published-port, and secret-substitution clients, including fragmentation, half-close, cancellation, and denied-destination cases.

A secret's `substitution.header_fields` allowlist is launch-contract gated: a secret with a non-empty allowlist is refused when the selected runtime predates it, because a runtime that drops the field would substitute the placeholder in every header. Other runtime versions outside the tested range (anything but the v0.6.x contracts or the exact current build) are already rejected during launch-contract resolution, before encoding. `msb self downgrade` to v0.6.x or v0.7.0-v0.7.6 likewise refuses a saved `config`/`active_config` whose secret policy enables header substitution with a non-empty header allowlist, because those runtimes deserialize secret substitution leniently and would drop the allowlist; the persisted-config check lives with the database downgrade conversions under [`crates/db/lib/compat/`](crates/db/lib/compat/). See [`sdk/rust/lib/runtime/launch_input.rs`](sdk/rust/lib/runtime/launch_input.rs) and [`launch_contract.rs`](sdk/rust/lib/runtime/launch_contract.rs).

## 14. Vsock and SSH Protocol Adapters

Vsock stream and datagram routes have different message-boundary and shutdown semantics, with platform-specific Unix socket and Windows named-pipe backends. SSH maps exec channels to agent exec, SFTP to agent filesystem messages, and direct TCP forwarding to agent TCP messages. These mappings inherit agent protocol generation requirements.

Compatibility-sensitive elements include vsock port and route configuration, stream half-close, datagram boundaries, backend availability, SSH host-key and known-host persistence, authentication behavior, exit status and signal mapping, SFTP file semantics, and direct-tcpip capability gating.

Sources: [`crates/vsock/lib/stream.rs`](crates/vsock/lib/stream.rs), [`crates/vsock/lib/dgram.rs`](crates/vsock/lib/dgram.rs), [`crates/runtime/lib/runner/vm.rs`](crates/runtime/lib/runner/vm.rs), and [`sdk/rust/lib/sandbox/ssh.rs`](sdk/rust/lib/sandbox/ssh.rs).

Use standards-compliant clients in tests and exercise connections against older running agentd versions when changing the adapter-to-agent mapping.

The SDK-hosted SSH adapter maps negative agent exec codes, including `-1` for signal termination or a lost exit notification, to SSH exit status `1`. Nonnegative codes are preserved. SDK SSH clients map standard exit signals to `128 +` the Linux signal number and reject exec channels closed without a termination outcome. These corrections require no agent payload, version, or runtime capability change and apply to existing running guests. They do not identify an unknown signal or prove OOM, and the separately deployed cloud SSH gateway requires its own fix.

## 15. Metrics Shared-Memory ABI

Metrics use a binary shared-memory structure across independently executing processes. The header and slots have fixed sizes, magic, registry version, ABI, atomics, seqlock ordering, generation counters, lifecycle states, and reserved bytes.

Receipt-aged guest memory observations use 32 bytes of the v3 slot’s reserved tail. Guest usable total is at `0x148`, host monotonic receipt time at `0x150`, guest reporting interval at `0x158`, and the lifecycle stamp at `0x160`. Capability, validity and lifecycle use flag bits 11, 12 and 13. Released network counters retain offsets `0x130`–`0x140` and flag bits 8–10. Header and slot sizes, existing field offsets and meanings, object names, and ABI version remain unchanged. Separate capability and validity flags distinguish an unavailable observation from an older writer that never supplied one. New reservations clear these fields; readers ignore dirty tail bytes from older writers without the flags. v2 readers continue through the existing adapter and do not supply a guest total.

Only users of the unmerged PR5 preview need a fresh metrics registry. Stop its writers and readers before retiring the preview registry and restarting with the updated runtime. Released registries need no migration.

The additive `write_sample_with_guest_memory` entry point accepts a complete, same-report total/available pair; `None` invalidates it. A supporting writer must not reuse a captured report after pause, restore, or runtime replacement. Readers omit guest total, available, and usage when the slot is stale or the receipt expires at `max(3 seconds, 3 × guest reporting interval)`. Usage retains configured-limit-minus-available accounting. The original `write_sample` entry point retains legacy behavior; runtime producers must explicitly adopt the new path. These transport primitives do not by themselves establish guest resize completion or change the limit-update policy. The internal metrics crate's Rust `LiveMetric` and `SandboxMetrics` structs gain `memory_total_bytes` and original `guest_memory_observation` metadata, requiring direct struct literals to initialize them; the public language SDK metrics signatures are not changed by this transport step.

`MetricsSlotWriter::invalidate_guest_memory` clears guest-dependent validity and values synchronously under the existing seqlock, with the slot generation checked both before and inside the write. It preserves the sample timestamp, limit, host residency and other counters. Producers must serialize this operation with publication at their observation source; the seqlock alone cannot reject a report captured before a lifecycle transition. This API does not enable the runtime producer by itself. Buffered/exported snapshots additionally retain a live mapping token (allocation generation plus lifecycle epoch). The additive lifecycle flag gives meaning to an eight-byte epoch at reserved offset `0x160`; the header, slot size, existing offsets and ABI version stay unchanged. Invalidation advances the epoch even when a later report repeats identical values and receipt time. Before export, `guest_memory_is_fresh_at` checks that the allocation remains active, its writer is alive, and the epoch still matches; busy or changed slots omit guest-dependent values. An ordinary newer report in the same lifecycle does not invalidate an unexpired buffered report. Old writers without the lifecycle flag keep receipt-only or legacy behavior, and dirty reserved bytes are ignored. Updated writers retain the lifecycle stamp when switching to the legacy sampling API, but readers attach a validity token only to observation-aware samples; legacy usage and available-memory behavior is preserved. The token is host-local and is not serialized. The internal Rust snapshot structs also gain `guest_memory_validity`; direct struct literals must initialize it.

The collector preserves original receipt metadata through buffering and retry, rechecks expiry before dispatch, and retains the metadata when expired values are omitted. Built-in exporters also check each collection at observation time, including direct exporter calls. OTLP adds `microsandbox.memory.total` and `microsandbox.memory.available`; total is absent for older writers, while older available-memory observations keep their existing receipt-free behavior. Supporting writers lose usage/total/available together when expired; independent CPU, storage, host-resident and limit values remain. Custom exporters that retain batches after dispatch must recheck `guest_memory_is_fresh_at` before producing current observations. No exporter timestamp renews a guest report.

Sources: [`crates/metrics/lib/layout.rs`](crates/metrics/lib/layout.rs), [`crates/metrics/lib/registry.rs`](crates/metrics/lib/registry.rs), and [`crates/utils/lib/lib.rs`](crates/utils/lib/lib.rs).

Do not reorder fields, change widths or alignment, weaken atomic ordering, or redefine slot states under the same ABI. Incompatible changes must bump the registry version or ABI so old and new processes do not map the same object. Prefer checked-in offset and binary-layout fixtures in addition to total-size assertions.

The runtime sampler refreshes `memory_limit_bytes` in place inside the seqlock window so the slot follows live memory resizes, and sets the additive `SAMPLE_FLAG_MEMORY_LIMIT_LIVE` bit on those samples. Layout, offsets, existing flag bits, slot states, and `REGISTRY_VERSION` are unchanged. Existing readers test individual flag bits and ignore bits they do not know. Readers see live values from current runtimes with memory hotplug and the boot allocation when live sizing is unavailable; the Rust SDK prefers the slot value only when the flag is set and otherwise falls back to the catalog config. The OTLP `microsandbox.memory.host_resident` gauge is additive.

Paused runtimes omit the host-residency scan and clear the existing `SAMPLE_FLAG_MEMORY_HOST_RESIDENT` validity bit. The field retains its meaning as a current observation; no cached value is presented as current. Slot layout, registry ABI, timestamps, and other counter sampling remain unchanged. Historical v0.6 readers already interpret this cleared bit as unavailable, and newer readers continue to accept residency values from older runtimes that still scan while paused. This runtime change requires the additive libkrun selective-snapshot API; it does not change SDK launch or control protocols.

## 16. Heartbeats, Boot Errors, Logs, and Runtime Diagnostics

Operational artifacts are consumed across process boundaries and can influence lifecycle decisions. These include `/.msb/heartbeat.json`, `boot-error.json`, `exec.log`, runtime and kernel logs, temporary filenames, JSON field names, sequence numbers, timestamps, source labels, rotation suffixes, and atomic rename behavior.

Heartbeat semantics are compatibility-sensitive: missing or stale data alone is not proof that a sandbox has died, while active sessions affect idle shutdown. Boot errors must remain available before agent readiness. Log schemas and rotation ordering must remain readable by current SDK consumers.

Sources: [`crates/protocol/lib/heartbeat.rs`](crates/protocol/lib/heartbeat.rs), [`crates/runtime/lib/runner/heartbeat.rs`](crates/runtime/lib/runner/heartbeat.rs), [`crates/runtime/lib/client/boot_error.rs`](crates/runtime/lib/client/boot_error.rs), and [`crates/runtime/lib/runner/exec_log.rs`](crates/runtime/lib/runner/exec_log.rs).

Add optional fields where readers are tolerant. Rename files or fields only with dual-read or migration behavior for the supported horizon.

## 17. Lifecycle, Locks, Leases, and Ordering

Compatibility can depend on operation order even when no serialized shape changes. Lifecycle locks, database run rows, PID ownership, endpoints, metrics slots, CPU and writeback allocations, heartbeat state, maintenance leases, signals, shutdown delays, and cleanup together determine whether a sandbox is live and who may mutate it.

Compatibility-sensitive ordering includes:

- Resolving lock and process ownership before replacing or deleting endpoints.
- Preventing database and artifact migration while incompatible runtimes remain active.
- Reserving, activating, marking stale, and freeing shared resources in the established order.
- Allowing agentd and the guest filesystem to drain before forced VMM termination.
- Writing and verifying payloads before atomically publishing their identity-bearing descriptor.
- Persisting a recovery journal before the first mutation and clearing it only after durable completion.

Sources: [`crates/runtime/lib/client/ipc.rs`](crates/runtime/lib/client/ipc.rs), [`sdk/rust/lib/backend/local/mod.rs`](sdk/rust/lib/backend/local/mod.rs), [`sdk/rust/lib/runtime/handle.rs`](sdk/rust/lib/runtime/handle.rs), and artifact-specific migration and publication modules.

TCP completion follows both ordered half-closes; the first EOF alone keeps the opposite direction usable. In combined-port mode, validated guest-to-host TCP credit may pass queued host-to-guest raw data and its finish marker: it services the opposite direction without reordering input data or EOF. Opening, cancellation, ownership, and global lifecycle fences still constrain it. Raw TCP output may still be draining on the dedicated lane after its producer finishes. Decoded credit updates for a finished producer or absent TCP session are therefore no-ops, not cancellation: they cannot enable further output, and must not discard the queued tail or create a second terminal response. Active producers retain credit validation; data and finish messages retain their existing validation.

Review concurrency and crash points explicitly. A same-version happy-path test does not establish cross-version or crash compatibility.

Graceful Stop now waits for terminal state plus released lifecycle ownership of the selected local run. Its bounded variant spends one total budget, including lock acquisition and dispatch; zero expires before dispatch, and expiry/cancelling the wait never selects Kill. Normal host and guest shutdown handlers no longer install fallback kill timers. RequestStop remains dispatch-only. These guarantees require the updated runtime/agent bundle; already-running older runtimes and full snapshots retaining older agent code retain their older shutdown implementation. Independent attached-handle, parent-death, idle, maximum-duration and startup-command lifetime policies are unchanged.

## Review Triggers in Diffs

When inspecting a proposed change, treat these patterns as compatibility tripwires:

- `serde` rename, tag, default, flatten, deny-unknown-fields, enum, or numeric-type changes.
- Modified magic values, protocol versions, feature flags, message names, operation names, IDs, reserved bits, or frame limits.
- Changed path constants, filenames, extensions, hashes, truncation lengths, mount tags, interface names, device names, xattr keys, ADS names, or environment variables.
- Changed canonical serialization, field order, sorting, hashing domains, digest algorithms, UUID derivation, parent identity, or archive inventory.
- Edits to an existing migration instead of a newly appended migration.
- Changed ext4, EROFS, VMDK, OCI, journal, inode, block, descriptor, or checksum logic.
- Changed `repr(C)` structs, shared-memory fields, atomic orderings, slot states, virtio feature bits, or device config layouts.
- Changed startup, readiness, shutdown, timeout, signal, lock, lease, rename, fsync, or cleanup order.
- Changed exact internal dependency pins, embedded-agent selection, firmware versions, sonames, bundle URLs, or platform artifact names.
- Removal of a legacy parser, codec, path probe, translation, fallback, migration, or compatibility test.

## Expected Evidence Before Declaring Compatibility Safe

Choose evidence proportional to the boundary and failure risk:

1. Unit tests for parsing, validation, capability gates, and clean refusal before mutation.
2. Golden bytes or checked-in fixtures for wire, canonical, binary-layout, and identity-bearing formats.
3. Copies of artifacts produced by supported older releases: databases, ext4 images, manifests, archives, cache entries, and metadata trees.
4. Real older binaries for live host-to-agent, local IPC, launcher/runtime, and bundle interoperability.
5. Forward migration plus supported reverse migration or downgrade-refusal tests.
6. Crash and failure injection around journals, metadata writes, fsync, rename, publication, and cleanup.
7. External validators such as filesystem checkers and standards-compliant SSH, SFTP, DNS, TLS, TCP, UDP, OCI, and archive readers.
8. Platform and architecture coverage for Linux/KVM, macOS/HVF, Windows/WHP, Unix sockets, named pipes, firmware, and packaged runtime artifacts.

If an applicable direction cannot be tested locally, state exactly what remains unverified and which CI, platform, previous binary, or fixture is required.

## Guest filesystem flush policy

Capture requests carry an optional `guest_flush` field gated by `guest_flush_policy` capability. Missing fields retain the previous crash-consistent policy for old clients; explicit `auto` requires writeback for live disk-only capture. New full-capture clients may omit Auto for an older runtime because its capture contract is unchanged, but cannot downgrade Required or Skip silently. Explicit-policy pause has a separate operation so an old runtime cannot acknowledge it as ordinary pause. Legacy `Pause` and resume wire forms remain unchanged.

The existing guest freeze protocol carries `path:/` and captured storage selectors and acknowledges successful synchronization. The host retains the exact requested set only after that acknowledgement; a successful empty-set request never proves a root flush. Coverage is tied to the resident pause generation and is not serialized as a new portable snapshot format. Required writeback on a stopped guest or an unflushed paused guest fails before disk rollover; the runtime never resumes a paused guest implicitly.

The owned-block flush correction makes root and owned block writeback follow the selected policy rather than the mere presence of an owned mount. Explicit Skip disk snapshots now promise only crash-consistent block data. Auto full capture, branch, and plain pause no longer flush those block filesystems implicitly. Host-backed directory barriers and host disk drain/seal/durability remain unchanged. Older callers omitting capture policy also lose incidental owned-block writeback, retaining only their crash-consistent disk-capture contract; use a policy-aware caller with Auto or Required when guest writeback is needed. No request field, capability, guest protocol, or persisted format changes. Existing running runtimes retain their previous selection until restarted.

The Go native ABI adds an optional explicit-policy pause symbol, also used to detect support for policy fields on existing JSON capture/batch entry points. New Go clients refuse unavailable semantics rather than let an older library ignore those fields. Existing exported signatures remain unchanged. The Rust public capture configuration gains `guest_flush` with a serde default; Rust struct-literal callers must include the field. No agent protocol, archive schema, or database migration changes.

The approved Go exception covers all disk-capture entry points, including the handle convenience method and stopped sources: they require a policy-aware native library. Full Auto capture and unrelated operations remain compatible with older native libraries. This is separate from the running VM's capability gate; updating only the Go package cannot teach an old native library to enforce Auto's live-disk guarantee.

## Capture-once branch batches

`branch --names` and SDK batch methods reuse the existing local branch capture/restore envelope. The batch retains a process-local RAM pin and temporary owner-only links to immutable CPU/device/disk state; each child acquires its own links, RAM handle, writable disks, and VM generation identity. Nothing new is serialized into launch JSON, the database, or portable snapshots. Single-name branching still captures the current source state on each call. Batch names and known conflicts are checked before capture; per-child reservations remain authoritative against races. Validation/capture failures fail the call, while later startup failures return named outcomes without recapture or rollback of successful children. The Go FFI adds an optional batch symbol and refuses older native libraries without it rather than looping over single captures. Temporary batch staging is released on normal completion or cooperative cancellation; process-kill crash recovery is not a durable snapshot guarantee.

Batch startup is bounded and concurrent after the designated producer publishes its capture, including the producer child's own remaining startup. Results remain in input order, but runtime visibility, resource contention and readiness order are not ordered. Cancellation can therefore leave a different subset of already-successful detached children; unfinished children retain ordinary creation rollback ownership. No failed child retries capture. Unix disk-lock descriptors stay close-on-exec in the launcher and only the intended child inherits them; the runtime's existing lock lifetime and launch envelope are unchanged. Contended named-volume waits yield instead of blocking the startup executor, without changing their exclusion scope or persisted formats.

Named-volume provisioning now enforces that same name exclusion on Windows through the existing process-held file-lock primitive. Previously that platform's name lock was a no-op; concurrent batch children must wait for the first provisioner rather than race to create a volume or its catalog row. Unix locking and measured Linux startup behavior are unchanged.

### v0.6 secret policy translation

The catalog migration, previous launch codecs, and downgrade conversion share JSON field remapping, validated against the current types, in `microsandbox_types::compat::v0_5_0::local::secrets`. Unknown saved fields remain visible to preservation checks; the codec does not silently discard them. They translate `query_params` to `query` and merge previous `headers` and `basic_auth` into `headers` using logical OR. This approved mapping broadens substitution when the old switches differed. Explicit global passthrough defaults remain in `SecretsConfig.passthrough_hosts`; explicit per-secret passthrough remains in `SecretEntry.passthrough_hosts`. A per-secret blocking action overrides the global passthrough default. Changing the default violation action preserves passthrough settings.

The selected runtime's enforcement applies. The current runtime permits unchanged placeholders on credential-allowed hosts once the secret's host and TLS identity checks pass, while earlier v0.7 runtimes block disabled-location placeholders without explicit passthrough. This intentional policy change also applies to decoded v0.6 configurations; it does not change persisted or wire formats. All-disabled substitution remains invalid. No legacy-injection marker or generated allowed-host passthrough is retained. Modern launches materialize only explicit global defaults into per-entry destinations; persisted defaults remain available for future additions. Previous writers emit both header switches from the combined setting and reject unrepresentable policies. Catalog upgrade migrates secret policies in both `config` and `active_config` to the current format. It also normalizes older image, mount, CPU and pull-policy spellings required by current readers, retaining other supplied fields. Application readers deserialize the migrated format directly; previous records written afterward by old SDK processes are not supported. As with earlier config migrations, an already-open older SDK process is not protected from the new stored format: stop old SDK processes before sharing the upgraded catalog. This is separate from preserving already-running sandbox VMs.

`msb self downgrade` projects secret policies in both `config` and `active_config` before schema rollback. Preflight runs the same conversion on a database copy before artifact changes. Conversion and schema rollback commit together, including targets requiring no schema steps. Secret configs already in the previous format are left byte-for-byte unchanged. Failure identifies the sandbox and column without exposing secret values. The released-SDK integration test creates with the selected previous SDK, modifies/saves through the candidate SDK, invokes the CLI preflight and rollback functions, then restarts and checks data and HTTP substitution with that previous SDK. `MSB_TEST_OLD_VERSION` selects the target, defaulting to v0.6.18. It does not run the installer or change public command links.

A malformed saved row aborts the entire upgrade before any converted row is written. The error identifies the sandbox name, ID, and configuration column without including secret values. Stop SDK processes sharing that home, back up the home, and use the previous SDK/CLI to repair the named sandbox or remove it if its data is no longer needed; then retry the upgrade. Do not edit the migration history or skip the row. Valid previous policies with every substitution location disabled can migrate, but launching them under v0.7 requires enabling a substitution location or removing that secret policy.

Downgrade to v0.6.5 also restores that release's CPU and mount spellings. Its accepted image aliases are retained so older schema rollback steps can still recognize them. Migration history comparison accepts the shipped v0.6.16 ordering of the same complete migration set; missing, duplicate, or unknown migrations still refuse rollback. Isolated file mounts are supported when targeting v0.6.16–v0.6.18 and refused before creation for earlier runtimes. Linux installers accept the firmware basenames shipped by supported v0.6 releases and retain aliases for older SDK discovery; duplicate firmware entries are rejected before publication.

Downgrade to released v0.7.0–v0.7.2 also preflights both configuration columns, even without schema steps. Those targets cannot preserve a global secret passthrough default, so its presence (including an empty list or previous spelling) refuses the downgrade before changing artifacts or the live catalog. When no schema rollback is needed, this check reads the live catalog without requiring stopped sandboxes, a backup, or a preflight database copy. Schema rollbacks and v0.6 config rewrites retain their existing safeguards. Released v0.7.3–v0.7.6 support global passthrough defaults but still cannot enforce header allowlists, so their adapter applies only the header restriction check. Empty header allowlists mean all headers and do not block downgrades; the v0.6 adapter normalizes an explicit empty list before checking for lost fields. Supported v0.7 configurations remain byte-for-byte unchanged; flattening the default into existing entries would lose inheritance for future secrets.

Adding `passthrough_hosts` to the public Rust `SecretsConfig` and `CloudSecretsConfig` structs is an accepted Rust source-compatibility break. Direct struct literals must initialize the field or include `..Default::default()`; exhaustive destructuring must include the field or `..`. Existing builders and literals already using defaults need no changes. The domain field remains hidden from generated TypeScript/OpenAPI because it carries previous local defaults; the cloud contract exposes its own field. This does not introduce a Python or TypeScript call-signature change.

The populated global-passthrough fixture is hand-extended from captured v0.6.18 configurations, with inherited, blocking-override, and per-entry passthrough policies. It exercises persistence and cloud round trips, runtime projection, and downgrade without claiming another released-runtime capture.

The shared cloud decoder accepts both previous and current secret field names. Cloud must adopt the updated types/runtime to support both deployed contracts; changing the SDK alone is insufficient. The cloud contract retains optional global `passthrough_hosts` through serialization and domain conversion, so later secret additions inherit the default. Per-secret blocking overrides still take precedence.

## Compatibility code organization

Apply these guidelines when implementing an approved compatibility change:

- Group previous contracts under the owning crate's `compat/v<major>_<minor>_<patch>/`, named for the release that introduced the format. Reuse that module until the format changes; do not create a directory for every supported release. These directories describe contracts, not sequential migration steps. Split `local/` and `cloud/` only where their contracts differ.
- Keep saved-config conversion in the DB crate, runtime launch readers with the runtime, SDK runtime selection with the SDK, and shared wire types in the types crate. Keep current domain types outside versioned compatibility modules.
- Keep dispatch at the boundary and version-specific conversion inside its version module. Prefer explicit format versions or capabilities; isolate field-based detection needed for existing unversioned payloads. Never retry malformed current input as an older format.
- Prefer concrete Rust types for wire formats. Use `to_current` and `to_previous_version` for conversions, `encode` and `decode` at serialization boundaries, and `deserialize_*` for serde callbacks. Reuse types where contracts match; avoid duplicate representations, marker fields, and wrappers without a concrete behavioral need.
- Rewrite saved formats through DB migrations, then use ordinary current-type deserialization for normal reads and writes. JSON remapping is appropriate for migrations that must preserve unknown fields. Assess shared `MSB_HOME` SDK processes separately from running VM processes; follow the [database migration rules](#6-database-configuration-and-migration-history).
- Preserve defaults, field presence, and global versus per-entry overrides, including defaults for entries added later. Report behavior that cannot be represented before choosing a fallback. Downgrade preflight must catch incompatible state before mutation; migration failures must remain atomic and give actionable, secret-safe recovery context.
- Follow the [validation requirements](#expected-evidence-before-declaring-compatibility-safe) using released SDKs/runtimes and version-labeled fixtures. Include upgrade → edit/save → downgrade → restart, failed-migration rollback, and older readers of newly written artifacts where supported. Check cloud deployment order separately; local compatibility does not establish cloud compatibility.

### Current module layout

| Responsibility | Location |
| --- | --- |
| Shared contracts | `packages/microsandbox-types/rust/lib/compat`: `v0_5_0/local/secrets`, `v0_6_5/cloud/create`, `v0_6_7/cloud/secrets`, and `v0_7_0/local/secrets`. |
| Saved-config migration and downgrade conversion | `crates/db/lib/compat`: dispatch and record preparation in `config.rs`; adapters in `v0_5_0/secrets`, `v0_6_5/config`, `v0_7_0/secrets`, and `v0_7_3/secrets`. The CLI owns preflight and rollback transactions. |
| Cloud dispatch | The types crate's `compat/cloud.rs`. |
| SDK executable discovery, contract selection, preflight, and outgoing encoding | `sdk/rust/lib/runtime/launch_contract.rs`; `launch_input.rs` holds previous environment-encoding helpers. |
| Runtime incoming launch readers | `crates/runtime/lib/client/compat/launch.rs` selects readers and shares previous launch fields and conversion; `network.rs` shares network compatibility decoding. |
| Legacy storage formats | `crates/runtime/lib/checkpoint/compat/v0_7_0` decodes historical root and owned journals; `checkpoint/migration` owns shared validation, capture and forward recovery. The SDK owns catalog admission and related-writer exclusion. Parsing never bypasses these checks. |

Known destination releases use `semver::Version` across CLI downgrade and SDK launch selection; each compatibility layer owns its own release boundaries. Each versioned `to_previous_version` adapter prepares that contract or rejects settings it cannot preserve; the DB's v0.7.0 adapter returns no rewrite for supported records.

Incoming unversioned launch/cloud requests retain detection of previous formats. Cloud requests continue using the existing `/v1` API without a separate body version. Readers accept previous and current request formats; additional cloud contract versioning is deferred until a concrete incompatible change requires it. Explicit launch-message versioning remains separate follow-up work.

The runtime dispatcher selects the current reader when `execution` is present, `v0_6_10/launch.rs` when `bootstrap` is present, and `v0_5_9/launch.rs` otherwise. `client/launch.rs` contains both `LaunchConfig` and the `LaunchCapabilities` probe response. The launch type remains in the runtime crate to avoid a dependency cycle. SDK tests exercise its encoder against the runtime decoder; runtime tests also consume independently captured release payloads.

Launch and cloud requests reject duplicate recognized fields and conflicting previous/current spellings. Previous saved-format decoding and the duplicate-key JSON fixture reader in the SDK are test-only.

### Explicit snapshot verification coverage

Explicit checkpoint verification retains the existing `upper` and checkpoint-root projections and corruption-as-error behavior, and adds whole-artifact payload `coverage`. Missing ancestor/root/owned-disk checksums are incomplete rather than authenticated content. Unknown required descriptor extensions refuse verification because the reader cannot establish their coverage. CLI `snap verify` and `snap inspect --verify` exit unsuccessfully for incomplete coverage; this is an intentional CLI behavior change in the group/checkpoint API migration. Rust report struct literals must include the added coverage field. Node and Go wrappers receiving reports from an older native library expose `unknown` coverage instead of inferring completeness from the head checksum. Existing native JSON fields, runtime/agent protocols, persisted descriptors and archive formats are unchanged by this reporting change.

### Whole-group verification lifetime protection

Whole-group verification retains writer admission and one shared group lifetime lease outside the replaceable directory through selection and hashing. It closes each temporary descriptor pin after loading that member's metadata, bounding open descriptors independently of history length. Imports, captures and head changes on the same group wait until hashing finishes. This approved concurrency change prevents hard-link publication from changing payload ctime during strict mutation checks. Reads, sandbox execution and operations on other groups can continue. Updated member removal and rollback take the exclusive side of the group lifetime lease; they retain existing nonblocking busy/retry behavior. Cancellation of the async caller does not release either lease while its blocking hash worker still runs. Older writers do not honor writer admission; concurrent older mutations may still cause verification to report changed evidence.

Concurrent older removers must be stopped or upgraded for the duration of whole-group verification because they do not honor the group lifetime lease. This is the explicitly approved extension of the older-writer exclusion used for atomic import. Older readers remain supported, and exact-checkpoint operations retain their existing descriptor leases. Lock files remain outside replaceable group directories and are never removed as payload cleanup; rollback shares one exclusive lease across its members to avoid self-conflict. This does not change snapshot descriptors, archive formats or runtime protocols.

### Fresh snapshot archive targets

Fresh exports default to canonical `microsandbox.member-names` and `microsandbox.dependencies` keys. Their required-extension bindings make older readers refuse capabilities they do not understand instead of silently dropping checkpoint names or dependencies. `ArchiveCompatibility::V0_7_8` (CLI `--compatibility 0.7.8`) writes historical archive keys and checks packaged descriptors against the released reader’s capability set before opening output. Unsupported required behavior is refused, never stripped. This target is an archive metadata contract, not a VM execution-state converter or cross-architecture resume guarantee.

Readers continue to accept both archive dialects without normalizing input metadata. Fresh re-export uses the selected target regardless of input spelling; descriptors retain their identity. Node and Go explicitly probe native support before sending a requested target because older native decoders can ignore unknown option fields. Omitting the new option keeps existing calls usable with older native libraries. Python and Ruby reject unknown keywords in older bindings.

### Published capture recovery outcomes

`PublishedSnapshotArtifact.head_update` retains the head decision made by the installed capture when publication succeeds but source recovery fails. Archive-only captures omit it; older producers without this optional field remain readable, and bindings must not infer an outcome from a later mutable head read. Existing artifact identity, digest, recovery locators, error classification and nonzero failure behavior are unchanged. Rust callers constructing `PublishedSnapshotArtifact` literals must add `head_update: None` (or the recorded outcome) as part of the approved 0.8 SDK source migration. Snapshot descriptors and runtime protocols are unchanged.

## Snapshot spawn guest-clock parity

Python `guest_clock`, TypeScript `guestClock`, and Go `WithRestoreGuestClock` now project the existing restore clock policy through both group and checkpoint spawn, including progress variants. Omission remains distinct from explicit `sync`: it retains a recorded `off` policy, whereas explicit `sync` overrides it. The existing descriptor extension and runtime capability contract are unchanged. Go probes native support only for explicit selection; TypeScript reports unsupported when an older addon lacks the setter. Existing calls that omit the option retain their prior native path. The runtime must advertise support before an off policy can launch; no unsupported policy is silently dropped.

## Canonical group import options

Rust `Snapshot::load_with` and Go `Snapshot.Load` use `SnapshotImportOptions`, containing destination-store, external-base and head-selection controls. The group is supplied only by the positional argument. Legacy Rust `LoadOpts` and Go `SnapshotLoadOptions` retain their group field and existing artifact-loading behavior. This finalizes the unreleased group API within the 0.8 source migration; callers explicitly naming the draft canonical options type must use `SnapshotImportOptions`. Native transports still reject a conflicting legacy group field instead of silently ignoring it. Snapshot storage, archive bytes and runtime protocols are unchanged.

## Go snapshot response ownership

The optional `msb_snapshot_object_owned` native entry point returns an allocated JSON response, released with the existing `msb_agent_free_bytes` function. Current Go snapshot-object calls use it when present, preserving successful mutation results larger than the former 1 MiB caller buffer without replaying the operation. The original `msb_snapshot_object` ABI remains unchanged for older callers and native bundles. Older bundles without group receivers continue to return unsupported before dispatch; earlier bundles that have only the buffered group entry point retain that existing size limitation. This adds no runtime protocol, catalog or archive format requirement. Cancellation joins the native call before releasing inputs, and a completed successful response retains ownership even when context cancellation races it.

## Go snapshot producer capabilities

The optional `msb_supports_snapshot_artifact_receivers` symbol advertises `create_artifact` and `list_dir` operations that return retained checkpoint receivers. General snapshot-object dispatch predates those operations and is not sufficient evidence of support. New Go clients select the retained producer only when the marker and receiver entry points exist; older libraries continue through the existing capture/list ABI. This routing is selected before dispatch and never retries capture after a native error or uncertain outcome. Results from legacy producers retain their existing operations; new exact-receiver spawn/removal methods report unsupported when no receiver was returned. Existing symbols, older Go callers, snapshot bytes and runtime protocols remain unchanged.

## CLI configuration proxy input

The additive `network.proxy` file field (or unwrapped `proxy` in `--net-conf`) accepts the existing CLI proxy URL protocols and optional protocol-specific authentication. Endpoint and authentication replace as one value across file layers; explicit proxy flags replace that complete value too. SOCKS5 passwords remain destination environment references and use the existing resolver. Parsing files does not read them, and literal password fields are rejected.

Files omitting this field keep their existing behavior. Older CLI parsers reject files containing the new field; their error may identify the enclosing network configuration rather than naming the field. Callers using those binaries must keep using their existing supported proxy flags. This adds no runtime/agent protocol, SDK native symbol, persisted sandbox field, catalog migration or snapshot extension. It uses the existing `NetworkSpec.outbound_proxy` contract and backend support checks. It does not enable portable saved-config capture or restore.

## Failed-creation cleanup diagnostics

Post-readiness SDK failures still attempt the existing immediate termination of the creator-owned process and wait up to the existing five-second deadline. A confirmed exit preserves the original error and its classification. A signal, observation or wait failure that leaves termination unconfirmed now returns the existing runtime-error envelope with both the original failure and an explicit warning that the runtime may remain running. No mutation is replayed, and existing lifecycle ownership checks still prevent storage rollback while an owner remains. This adds no required response fields, runtime capabilities, shared catalog records or archive metadata; older bindings can decode the existing error kind. The new diagnostic does not claim rollback or successful termination merely because a kill request was accepted.

## Private checkpoint configuration receipts

Full and disk checkpoint control requests may opt into `retain_configuration`; the runtime advertises this through `configuration_capture`. Omission preserves existing capture behavior and adds no receipt field to its result. Checked Rust and TypeScript clients select support before mutation: framed requests probe the actual connected peer, and JSON requests require independent runtime-identity verification plus fresh capability discovery. Unsupported or timed-out discovery reports that the capture was not sent. No mutation is retried through another transport after dispatch. The probe and mutation share one request deadline.

The runtime selects confirmed local configuration after VM pause while retaining executor mutation authority, revalidates it before publication, and writes a private receipt bound to the checkpoint ID and full checkpoint root or disk-generation fingerprint. Missing or contradictory provenance records unknown evidence; it never substitutes next-start configuration. The response contains only a receipt digest. The local file is stored under the source sandbox's `last-active/captures`, outside portable payload closures, with owner-only permissions. Readers verify its size, identity and digest before returning private source values. This does not make the raw local configuration safe to export: the approved portable exclusions and destination-binding projection remain mandatory.

Receipts cannot overwrite earlier evidence. An ordinary prepublication error removes its prepared receipt; a process crash can leave a private orphan until source storage is removed. Published full-capture results retain their receipt reference when source recovery fails. This does not add a disk-capture recovery-result contract or enable the portable saved-config writer. The SDK requests receipts from capable peers, selects catalog/run identity before dispatch, and consumes receipts only after validating the returned capture. Confirmed values now supply the existing live snapshot user, full-state clock and mount projections; raw configuration is never copied wholesale into descriptors. A malformed, missing requested, or mismatched receipt refuses publication with redacted diagnostics. A later live change does not invalidate an already bound immutable receipt. Unsupported runtimes receive the original request with no retention lookup; unavailable evidence retains the existing legacy metadata behavior for now. The complete portable unknown/active/pending projection remains unfinished, so this is not a complete saved-config guarantee. The catalog schema, archive extensions, package versions and existing runtime operations remain unchanged. Rust callers constructing the affected public request/result structs must include the new optional fields as part of the planned 0.8 SDK source migration.

## Stopped checkpoint configuration selection

Stopped disk capture selects retained configuration for the latest terminated run while holding lifecycle ownership through the disk cut. It independently checks catalog, sandbox and run provenance, then rechecks the exact owner, generation and source after copying disk state. An observed change refuses publication. Desired next-start edits do not invalidate confirmed last-active evidence, and cancellation cannot release lifecycle ownership while the blocking cut remains active. Existing source image/root checks still apply.

Confirmed values supply the existing user and mount projections for installed and archive-only captures. Missing historical evidence remains unknown and retains existing legacy metadata behavior; no retention records are created for older runtimes. Malformed evidence refuses capture with redacted diagnostics. This does not export raw local configuration, change archive schemas, enable portable saved-config activation, or detect a direct catalog edit that was subsequently undone. The complete portable active/pending/unknown projection and destination enforcement remain required.

## Private captured script evidence

The unreleased configuration-capture receipt may include actual registered script bytes and guest uid/gid/mode separately from declared source text. Unix runtimes pin the exact mounted runtime backend at construction, observe only registered files while paused, and revalidate them before receipt publication. Unsafe, missing, changed or unsupported observations remain explicitly unknown; they do not add a refusal to existing snapshot operations. Legacy peers that do not request configuration receipts retain their existing protocol. Older receipts without script evidence remain readable as unavailable evidence. No archive member, released control envelope, catalog schema or shared-memory layout changes here. These host-private bytes must pass capture exclusions before any future portable emission, and observed script files alone do not establish full-state handle/resource compatibility. Portable saved-config writing and activation remain disabled until those consumers are complete.

The SDK now retains validated observed script backing alongside confirmed configuration through snapshot publication. Stopped captures select the last-active registration inventory under their existing lifecycle guard, pin sandbox/runtime directories without following substituted symlinks, and revalidate file contents and guest metadata after the disk cut. Pending next-start script registrations are not evidence of the stopped run. Changed, missing or unsupported backing remains unknown without changing legacy capture success; peers without retention continue their existing path. This introduces no portable field or activation behavior.

Checkpoint publication transfers ownership of its private configuration receipt as soon as the final directory rename succeeds. A later parent-directory sync failure reports uncertain durability and retains the visible checkpoint and its receipt; failures before rename still clean up unpublished receipts. This changes neither the receipt schema nor successful capture responses. Full-state capture exclusions protect matching active fields; a script recorded only as pending next-start intent may be omitted without weakening protection for active or unknown script backing.

Local SDK capture retains the original confirmed configuration fields, owner and generation alongside the decoded SDK view. Deserialization defaults are not promoted into recorded historical evidence. This is host-private, in-memory retention only: no new receipt fields, portable metadata, catalog records or legacy-runtime requests are introduced. Script inventory validation uses the recorded registrations; absent older inventories still accept an empty observation, while nonempty invented inventories fail. Portable projection must still apply exclusions and must not serialize this raw source wholesale.

## Snapshot spawn resource ceilings

The SDK destination builders expose the existing CPU and memory ceiling controls. Disk boot can select positive ceilings at least as large as the requested capacity; full-memory resume requires each explicitly supplied ceiling to equal captured geometry. Omission keeps the existing inheritance/default path. Zero remains explicit and invalid. Go requires native acknowledgement of each new option before dispatch; Node refuses setters absent from an older addon. Python and Ruby older native bindings reject unknown keywords. Existing runtime launch fields, snapshot geometry, catalog state and deprecated CLI restore grammar are unchanged.

## Snapshot destination command defaults (unreleased lifecycle work)

The snapshot destination builders expose working directory, shell, entrypoint, CMD and environment defaults for future commands. They do not request startup execution or modify captured processes during full resume. Explicit empty argv arrays remain different from omission. These setters reuse existing sandbox configuration and exec fields; no runtime wire or persisted format changes. Go checks each requested option against the native capability list before dispatch, and Node rejects absent native setters. Older Python/Ruby bindings keep their existing unknown-keyword refusal. No potentially applied operation is retried through a legacy entry point. Canonical CLI run ownership and the frozen deprecated restore grammar are unchanged by these SDK additions.

## Snapshot destination proxy (unreleased lifecycle work)

Snapshot spawning accepts the existing outbound proxy configuration and destination secret-source references. It reuses the ordinary creation launch contract and runtime capability admission; it does not add a guest protocol, save resolved passwords, or change captured guest interfaces. Go requires native acknowledgement of the proxy option before dispatch, Node rejects an absent setter, and older Python/Ruby bindings reject the new keyword. Missing destination passwords fail before runtime launch; ordinary failed-start cleanup may retain a stopped sandbox record. Python's shared parser accepts nested dictionaries produced by the typed public proxy object's serializer while continuing to reject raw dictionaries as public proxy inputs. No publication or package-version change is required.

## Snapshot spawn pull policy

Snapshot destination builders expose the existing image pull policy without changing the pinned manifest or source selection. The existing local creation path continues to validate the digest and resolve required image content before replacing a destination. The default `if-missing` and explicit `never` retain cache-only resolution when all required content exists. Explicit `always` now revalidates the recorded digest instead of accepting an unconditional cache hit; callers requesting it need a usable registry even with cached content. The original mutable tag is never followed. Go requires native acknowledgement of explicit pull policy before dispatch; Node rejects a missing setter in older addons; older Python/Ruby bindings reject the unknown keyword. No runtime protocol, snapshot descriptor or catalog field is added.

### Private environment origin evidence

New local creation records optional `environment_provenance` beside the existing private configuration. It identifies declared literals, host-forwarded values and unknown origins separately for workload and init environments, binding entries to their value digest without duplicating credential text. The actual environment and launch/restart behavior are unchanged. CLI `--env KEY` and `--init-env KEY` retain their origin after the existing host lookup; `KEY=value` remains an explicit literal declaration. Reconstructed older records do not acquire missing origin evidence. Explicit new declarations can replace a prior origin, while retained patches preserve their recorded origins. A mismatched value retains an explicit unknown origin across repeated layering, serialization and init inheritance; removing the stale hint must not allow a later pass to classify the value as a new literal.

Older readers may discard this optional hint. A newer reader then treats missing evidence as unknown instead of exporting it as a literal. This introduces no catalog migration, shared launch schema, control protocol or required response field. The hint and its digests are private and must not be emitted into portable metadata. Portable projection still needs to exclude or bind host-derived/secret values and apply capture controls; portable saved-config emission remains disabled until the complete capture/restore contract is implemented.

### Runtime capture projection (unreleased lifecycle work)

The internal runtime projector now applies explicit capture exclusions before constructing portable literals or hashing script bodies. Host-derived, secret-typed and unclassified environment values require a logical destination binding or a permitted omission. Positional arguments cannot be omitted, and full-state active script backing, init, hostname and clock cannot be discarded. Active and pending sections are sanitized independently; pending intent never supplies missing active values.

The retained-source adapter preserves raw field absence rather than exporting deserialization defaults. Reusable CMD requires private command-origin evidence; detached invocation arguments are not reused. Init requires guest observation, and handoff additionally requires the original auto/path intent. Script content and mode come from guarded observations rather than stale registration text. Missing older evidence stays unknown. The caller still owns catalog/run/generation validation, disk-cut coherence, full-state script ownership and handle fidelity, and complete cross-family document validation.

These helpers add no receipt fields, catalog migration, runtime request, protocol generation or archive extension. Portable saved-config emission and activation remain disabled until complete capture and destination enforcement are connected. Tests using receipts produced with an older guest establish unknown-init handling. Separate live builtin, explicit-path and auto-init runs with rebuilt current agents verify positive observation across modify/restart and stopped capture; the projector consumes those real stopped-source records. These checks do not activate portable saved-config emission.

### Resource and execution capture projection (unreleased)

Internal source projection now preserves resource observation reasons and reusable execution policy. Effective CPU/memory input must be observed or explicitly unknown; configured targets/defaults are rejected as observation evidence. Missing historical ceilings, THP, security, process limits or lifetime distinctions remain unknown. Label exclusions run before portable label construction, and system identity labels, host placement/profile names and ephemeral ownership are excluded. This adds no persisted field, catalog migration, SDK/runtime request or archive behavior. Portable emission and activation remain disabled while the complete source/destination pipeline is unfinished.


## Guarded network capture projection

The internal saved-config source adapter projects only portable network policy and logical destination requirements. It does not write metadata, change catalog or launch contracts, dispatch network operations or enable saved-config activation. Missing historical fields, including nested fields otherwise supplied by serde defaults, remain unknown; an explicitly recorded null remains distinct. Existing persisted TCP-count and TLS aliases are preserved. Source interface allocations, host endpoints/listeners, secret values/source references and CA paths/keys do not enter the projection. Binding inventory and full-resume backing remain caller obligations under the capture guard. No release, version bump or new private presence protocol is introduced.


## Guarded storage capture projection

The internal saved-config source adapter now projects recorded guest mount and socket-route requirements without source host paths, source volume-name lookup, file access or socket connections. Owned references must match the captured descriptor inventory. External backing kind and named-volume capacity come from caller-supplied observations under the source guard, never creation intent. Missing nested historical evidence keeps the whole relevant inventory unknown rather than selecting current defaults or silently dropping resources. Existing legacy mount decoding remains unchanged; legacy shapes lacking complete evidence are not reinterpreted as complete portable configuration. No metadata writer, catalog schema, launch protocol or public activation path is changed.


## Saved capture document assembly

The internal capture assembler now combines sanitized active sections and separately classified pending intent, derives a cross-family binding inventory and validates aggregate/legacy/owned-backing consistency. The retained capture object supplies its original raw source, observations and confirmed generation without rereading current mutable state. The method remains gated out of production publication; no artifact extension, catalog field, launch envelope or capability advertisement changes. Pending values cannot become active defaults or add activation demand. Optional source-name provenance remains separate from captured guest hostname identity. Resource/backing acquisition and full destination enforcement remain required before activation. The later private-capture section describes pending-source selection.

## Pending runtime declarations

The unshipped saved-config schema now distinguishes next-start `requested_handoff` init and script `declaration` values from observed init executables and materialized script backing. These variants require configured origin and are allowed only in pending metadata; active document admission, capture projection, restore selection and input preparation reject them before overrides or fresh mode can conceal them. Pending text uses the same exclusion and binding rules, and declaration bytes count toward the aggregate script limit. The raw-source adapter preserves missing fields as unknown, keeps detached invocation out of reusable CMD and records desired capacities as configured targets separately from active observations.

This refines an unreleased internal schema. It adds no emitted archive extension, capability advertisement, catalog field, runtime request or legacy-reader requirement. Portable capture/activation remains disabled. Production capture and deferred destination enforcement remain required; pending-source selection is described below. This pending-declaration schema does not itself establish presence; omitted historical settings without the separate matching private evidence remain unknown.

## Private default-presence evidence

The optional local `field_presence` hint distinguishes known serializer-omitted defaults from unavailable historical evidence. THP and absent network sections are value-bound. Mount ownership entries contain only kind and canonical guest path and certify that both UID/GID overrides are absent; they do not certify host backing or guest-effective ownership. Decode drops missing-parent, changed-value and malformed/future evidence before typed defaults can revive it during persistence. Explicit mount additions establish only the supplied declarations.

Older runtimes and SDKs continue using the existing configuration and catalog schema and may ignore or discard the hint. New restart/reconstruction never invents missing evidence. Active capture still requires exact retained-source/catalog equality and run/generation ownership, including after older writers modify the catalog. This is private evidence, not a new archive extension or capability claim, and portable saved-config emission/activation remains disabled pending completion of the destination consumers.

Decoded retained configuration also keeps missing environment origins unknown through sparse builder overlays. A missing evidence map cannot certify workload or init environment values as literals, even if the destination previously declared the same values. Matching recorded origins remain usable, and a later explicit declaration can establish new literal evidence. Repeated persistence preserves that distinction. Guest environment values, existing launch/modify operations, catalog schemas and released protocols are unchanged; the gated capture projector requires bindings or exclusion for unknown origins.

The same reconstruction rule applies to reusable CMD and original init selection. A historical invocation without command evidence cannot become a reusable default, and a resolved init path cannot establish whether its source selected `auto` or an explicit path. Matching recorded intent survives sparse overlays; explicit init/CMD setters and fresh spec declarations still establish new intent. The init uncertainty guard is builder-only and never serialized. The existing command, init arguments/environment, image-resolution behavior and launch protocol remain unchanged; missing intent stays unknown at the portable capture boundary.

## Recorded pending capture source

The unshipped capture-assembly API replaces `PendingCaptureSections` with `PendingCaptureSource::from_recorded`: callers supply the selected raw next-start record and its logical network/storage bindings, and the assembler projects every pending section. Experimental callers of the prior draft helper must update that construction; released SDK signatures, catalog fields, runtime requests and artifact formats are unchanged. No raw configuration is serialized into a snapshot.

Runtime, label and HTTP exclusions apply across active and pending sources before portable values are validated. A label selector may match either recorded source, but must match at least one and cannot address reserved labels. Desired resources, init/scripts and requested owned storage remain pending declarations; they never provide active observations or activation demand. Source selection and resource/backing coherence still belong to the capture guard, and production publication/activation remains disabled until those integrations and consumers are complete.

## Pending intent at the private capture boundary

The unreleased private configuration receipt now has an optional `pending` document covered by its existing digest and size bound. Live capture selects desired configuration in the same SQLite statement that validates active configuration and run identity, under the runtime's mutation authority. Stopped capture selects desired configuration while holding lifecycle ownership and revalidates its last-active provenance across the disk cut. Later desired-only edits do not replace the selected value; they do not invalidate active evidence. Direct catalog edits that change active provenance are still detected when observable, with the existing limitation that an edit subsequently undone cannot be detected.

The SDK retains the original pending document and only projects pending input matching that evidence. Missing pending evidence stays unknown; it is never filled from the current catalog or promoted into active settings. Invalid selected JSON fails with redacted diagnostics. Older receipts omit the field, released SDKs do not consume this private receipt contract, and unsupported runtimes keep the original capture routing. No catalog migration, public capability, archive extension, package version or launch protocol changes. This completes selection for captures with confirmed active evidence; legacy captures with unavailable active evidence remain unknown. Resource/backing observations, full-state closure, portable publication and destination enforcement remain unfinished.

## Registered-script guest metadata and offline staging

The unreleased saved-config document adds optional `active.script_backing` with observed guest UID/GID and ordinary mode for the runtime directory, scripts directory and exact registered-file inventory. Known metadata must agree with observed sanitized scripts; configured/default metadata, mismatched inventories/modes, privileged bits and pending backing evidence refuse. Missing older draft evidence remains unknown. Body binding removes source body/hash as before; metadata never supplies a hidden digest. This changes an internal draft schema and Rust struct literals, not an emitted archive, released runtime protocol, catalog or package version.

Full capture projection retains this metadata, while disk capture does not turn it into new-boot ownership policy. The new Unix staging function accepts source-independent bytes and guest metadata, keeps host permissions private, pins created file inodes through verification and rolls back the entire temporary directory on detected changes or errors. Existing boot staging retains its root-owned behavior. SDK full staging requires original inline digests, matching selected bytes/modes and observed metadata; bound or unknown identity refuses rather than manufacturing proof. The result is temporary backing only. Full filesystem/device-state admission, unregistered resources, complete runtime-share closure and destination policy remain required before activation. Existing launch/restore paths do not call these helpers, and portable emission/activation remains disabled.

## Capture projection preserves unknown backing and init intent

The unshipped projector rejects a full-state script-key omission when the active inventory is unknown/default, even when the selector matches pending intent. A known absent active key can still be omitted from pending content; disk capture retains its existing omission behavior. Pending init projection uses validated private provenance to distinguish original `auto` intent from the image-resolved executable path. A non-null init without provenance remains unknown; an explicitly recorded null still means no handoff. These repairs affect gated preparation only, without changing existing launch/restore routing, released protocols, catalogs or emitted artifacts.

## Registered script link relationships

The optional private script observer now reports unavailable evidence for registered files with multiple hard links. Captured names, bytes and permissions alone cannot reproduce shared inode identity, so new saved-config preparation must not certify such backing. Existing disk/full capture operations retain their success/error contract and use the existing unknown-evidence representation; no protocol, receipt, catalog or archive fields change. This is a conservative evidence check, not a complete runtime-share closure validator or an enablement of portable capture/activation.


### Nested network defaults in private presence evidence

The same optional private hint now records a fixed whitelist of serializer-omitted network defaults: absent HTTP denial messages, no-authentication SOCKS fields, default secret-policy fields, and unlimited rate-limit directions/buckets. Entries certify only absence or an empty value and are checked against the current typed configuration and recorded parent sections before use. Guest secret-placeholder names identify policy entries; credentials, host secret references, endpoints, paths and hashes of private values are not included. Required fields and token-bucket burst values still require explicit recorded evidence. Secret-entry omission hints also require the enclosing secret policy’s violation action to be recorded. If it is absent, those hints are retired before typed decoding; an explicit empty passthrough-host list and repeated save/reload cycles cannot promote a synthesized default into known policy. Ordinary secret-policy decoding and launch behavior remain unchanged. Fully explicit entries and empty secret lists need no omission hints, so reconstruction also retains an optional negative `secret_policy_unrecorded` marker in the private presence evidence. Malformed or future evidence cannot erase an indicated negative marker. This marker contains no values or identities and only prevents capture from treating a synthesized enclosing violation action as recorded intent. Sparse entry edits and repeated save/reload retain it; an explicit violation-action selection through a patch or either fluent builder clears it. Historical overlays replace the source’s uncertainty rather than borrowing the destination’s state. Released readers ignore the private evidence, and older writers can discard it; existing exact journal/catalog/run checks still reject stale active evidence after untracked writes. This adds no required launch/control field or catalog migration and does not enable portable publication.

Missing, changed, malformed or future evidence stays unknown. Reconstructing historical configuration cannot borrow nested evidence from a destination configuration, and explicit proxy replacement establishes only the supplied proxy declaration. Older writers may discard the optional hint without changing ordinary start/modify/restart behavior. Existing run/generation/catalog validation remains required; the hint alone cannot certify active configuration. No catalog schema, runtime protocol, required response, archive extension or portable capture/activation path changes.

### Missing TLS and DNS policy fields

The optional private field-presence hint also retains a fixed whitelist of missing TLS/DNS field names before typed decoding fills defaults. It contains no setting values, endpoints, host paths, certificates, credentials or hashes. Unrelated labels, save/reload cycles and fluent network edits preserve this negative evidence. Sparse replacements establish only the fields explicitly supplied, even when their values equal existing defaults; appending to an inherited list cannot establish its unknown prefix. Complete policy replacements can establish a new declaration. Historical aliases remain accepted, and malformed or future negative markers remain conservative rather than turning synthesized values into recorded intent.

Ordinary decoding, effective launch settings and existing start/modify/restart operations are unchanged. Older readers ignore the optional hint and older writers may discard it. The hint does not independently establish active configuration: the existing exact catalog, journal, run and generation checks must reject untracked active writes. This adds no catalog migration, required launch/control field, guest protocol or portable archive extension, and does not enable portable saved-config publication or activation.

## Negotiated mounted-storage observations

Private capture receipts have a separately negotiated `configuration_storage` capability. A client sends `retain_configuration_storage` only after support is selected; checked JSON and framed transports verify support again on the selected runtime before dispatch. Without this request, new runtimes omit the receipt member, preserving the previous strict receipt decoder. New clients accept older receipts as unknown storage evidence. No dispatched capture is retried through a legacy path.

Execution-limit evidence uses its own `configuration_exec_limits` capability and `retain_configuration_exec_limits` request field. A new client selects support before capture and the checked transport revalidates the selected peer before dispatch; unsupported peers keep their existing capture behavior with the field omitted. New runtimes emit `exec_limits` only when explicitly requested, preserving strict older receipt decoders. Values come from this runtime's guest Ready policy, never the current SDK's defaults. Missing guest evidence remains unknown. Receipt decoding requires all five fields and validates their ranges; the existing digest binds the complete record. Optional evidence may be omitted to preserve the receipt size bound, and complete unknown-configuration fallback clears it too. No mutation is replayed after an error. These host-private observations do not change catalog schemas, guest messages or launch arguments, and are not exported into archives. Portable saved-config projection and destination enforcement remain separately required before activation.

The optional receipt member records only guest-path mappings to filesystem kind and effective backend quota, sampled from successfully constructed backends owned by the capturing runtime. It contains no host source path, named-volume identity, credentials or backing contents. Zero quota and explicitly unlimited quota remain distinct; missing, ambiguous, unsupported or exhausted observations remain unknown. Block devices are not certified as filesystem backends. If optional storage evidence would exceed the existing private receipt size limit, the runtime omits it and the client treats storage as unknown; if the remaining configuration evidence also exceeds the limit, ordinary capture emits a bounded receipt with all source, pending, script, init and storage evidence unavailable. This uses the existing unknown-source representation and preserves the capture identity and digest. Consumers must not substitute desired configuration or defaults for that absence; workflows requiring saved configuration refuse unavailable evidence. Even the unknown receipt must fit the unchanged limit. The existing private receipt digest and source-run checks bind this evidence to the capture; portable archive writing remains separately disabled until destination enforcement and complete capture resource validation are implemented.

## Runtime-owned live labels

The optional `config_delta` discovery capability selects a compact desired-configuration update before dispatch. Unchanged large scripts stay in the catalog instead of consuming the control frame. The runtime checks the selected desired-document digest before starting its durable transition and compares the exact desired and active documents again in the catalog transaction, preserving concurrent writers' changes. Mixed modification plans retain their existing desired-state semantics. Older extension implementations without this capability receive the original full update; runtimes without the label extension retain the existing catalog path. Errors after dispatch never cause a legacy retry. Delta contents and both document digests remain host-private and redacted from diagnostics.

New SDKs select the host-only `control.labels` extension with a read-only `hello` before dispatching any live modification. The extension uses the existing generation-two framed control session and existing `control.error` responses; it does not add a guest message or change released control enums, launch arguments, catalog schemas, or language SDK signatures. Older JSON runtimes are selected out locally, and older framed runtimes can return `unsupported_operation` to discovery while remaining usable. Those peers keep the existing catalog label-update path. No failure after dispatching a label mutation permits fallback or replay.

Supported runtimes serialize label updates with their existing mutation authority. Each update is fenced by the selected runtime boot identity, latest running catalog owner, and SHA-256 of the exact active configuration selected by the SDK. A durable transition precedes the catalog transaction. That transaction preserves the existing atomic update of active labels, the SDK's validated desired configuration and the label index under the active-config compare-and-set. Confirmation preserves trusted source configuration only when its prior journal and catalog provenance agree. A failed pre-effect transition refuses the update; a failure after a possible effect reports `configuration_outcome_unknown` with the existing unknown-effect error classification and leaves the runtime running. The SDK does not repeat catalog persistence after a successful runtime response. Transaction failures roll back all three catalog representations; a possible commit followed by confirmation failure leaves the durable transition pending. The planned desired JSON travels only over the private host-control connection and is redacted from diagnostics.

Older SDKs can continue their existing catalog updates against new runtimes. Such untracked writes invalidate retained source evidence rather than being certified by a subsequent label change. Missing evidence stays unknown. The digest, journal and retained raw source are host-private and are not exported as snapshot metadata. Production portable capture/activation remains separately gated by the complete saved-config workflow.


## Snapshot spawn resource ceilings

The SDK destination builders expose the existing CPU and memory ceiling controls. Disk boot can select positive ceilings at least as large as the requested capacity; full-memory resume requires each explicitly supplied ceiling to equal captured geometry. Omission keeps the existing inheritance/default path. Zero remains explicit and invalid. Go requires native acknowledgement of each new option before dispatch; Node refuses setters absent from an older addon. Python and Ruby older native bindings reject unknown keywords. Existing runtime launch fields, snapshot geometry, catalog state and deprecated CLI restore grammar are unchanged.

## Snapshot destination command defaults (unreleased lifecycle work)

The snapshot destination builders expose working directory, shell, entrypoint, CMD and environment defaults for future commands. They do not request startup execution or modify captured processes during full resume. Explicit empty argv arrays remain different from omission. These setters reuse existing sandbox configuration and exec fields; no runtime wire or persisted format changes. Go checks each requested option against the native capability list before dispatch, and Node rejects absent native setters. Older Python/Ruby bindings keep their existing unknown-keyword refusal. No potentially applied operation is retried through a legacy entry point. Canonical CLI run ownership and the frozen deprecated restore grammar are unchanged by these SDK additions.

## Snapshot destination proxy (unreleased lifecycle work)

Snapshot spawning accepts the existing outbound proxy configuration and destination secret-source references. It reuses the ordinary creation launch contract and runtime capability admission; it does not add a guest protocol, save resolved passwords, or change captured guest interfaces. Go requires native acknowledgement of the proxy option before dispatch, Node rejects an absent setter, and older Python/Ruby bindings reject the new keyword. Missing destination passwords fail before runtime launch; ordinary failed-start cleanup may retain a stopped sandbox record. Python's shared parser accepts nested dictionaries produced by the typed public proxy object's serializer while continuing to reject raw dictionaries as public proxy inputs. No publication or package-version change is required.

## Snapshot spawn pull policy

Snapshot destination builders expose the existing image pull policy without changing the pinned manifest or source selection. The existing local creation path continues to validate the digest and resolve required image content before replacing a destination. The default `if-missing` and explicit `never` retain cache-only resolution when all required content exists. Explicit `always` now revalidates the recorded digest instead of accepting an unconditional cache hit; callers requesting it need a usable registry even with cached content. The original mutable tag is never followed. Go requires native acknowledgement of explicit pull policy before dispatch; Node rejects a missing setter in older addons; older Python/Ruby bindings reject the unknown keyword. No runtime protocol, snapshot descriptor or catalog field is added.


## Explicit snapshot group directories

`Snapshot.open(path)` and explicit CLI group paths reopen existing histories through the current group reader and locks. They introduce no catalog, artifact, or runtime protocol changes. Named lookup remains separate and never falls back from a missing path. Node and Go detect native support for the new operation before dispatch and report unsupported with older bindings; existing name-based operations retain their routing. Go uses the optional `msb_supports_snapshot_group_paths` symbol. Local paths are anchored before deferred work without collapsing Unix symlink/parent traversal. Cloud group names are unchanged.
Resource observation admission requires both guest generation 11 and the host-owned `relay_resource_observation: 1` Ready extension. Discovery only reads the original connection handshake; it sends no capability probe. Missing, malformed or unsupported relay metadata refuses the observation with `UnsupportedOperation` and `Delivery::NotSent`, including through the ordinary typed request API. Existing start, exec and resize routing is unchanged. The relay adds this extension after decoding guest Ready into its known shape, so the guest cannot supply it through an unknown field. Released Ready readers ignore the additive field. New relays route well-formed unknown reply names without typed-enum decoding, preserving bulk ordering and transport validation; malformed transport remains an error.

## Retained resize reads and control scheduling

Resize `Read` and `Current` return the latest retained operation evidence and coalesce a wake for the runtime observer. They do not query the guest synchronously on the shared ordinary-control queue. Completion still requires the existing generation-fenced host/guest observation; an accepted target, a status read or a wake cannot establish completion. Pending records report paused while execution is unavailable, while completed records retain their historical outcome. Old mutation requests, wire fields, history identities, observation capability checks and catalog formats are unchanged.


## Remote context compute selection

The SDK exposes `ComputeType`; `CloudComputeType` remains a deprecated SDK
re-export for existing callers. The shared HTTP contract type and its serialized
values are unchanged.

Remote contexts optionally capture `ComputeType` for new sandbox creates
and snapshot restores. The HTTP create body sends `compute: {"type": "standard"}`
or `compute: {"type": "shared"}` beside the nested `spec`. Unset contexts omit
`compute`, preserving the server default. Derivation retains the captured choice
unless explicitly overridden. Existing sandboxes, local launch contracts, saved
sandbox configuration, catalogs, and snapshot formats are unchanged.

This uses #2058's nested create contract, already supported by the Cloud request
reader alongside previous flat requests. Servers that only accept flat requests
cannot accept this candidate's nested create body; deploy the matching server
first. There is no retry with a flat request or silently omitted compute choice.
Binding JSON accepts only `standard` and `shared` and rejects compute options on
local contexts. Older native bindings reject the new `computeType` option as an
unknown field rather than dropping it. Local SDK/runtime compatibility is
unaffected by this option; historical runtime validation is separate from the
HTTP request tests.

## Remote destination naming

By explicit user direction, `remote` is the canonical `MSB_BACKEND` value,
serialized `ContextKind`, CLI diagnostic kind, and `allowed_backends` value.
Readers continue accepting `cloud` as an alias. Profile writers already use
`kind: "remote"`; their existing `backend`/`cloud` reader aliases remain.
Older SDKs and CLIs may reject newly written `remote` policy values or the new
CLI spelling. Upgrade those consumers before sharing rewritten settings.
This approved configuration/API naming change does not alter sandbox launch,
agent protocols, catalogs, snapshots, or the HTTP API's `Cloud*` type names.

## Managed Cloud root sources and mount owners

The SDK now forwards bind-directory and disk-image root sources already handled
by the Cloud API resolver and worker. Paths belong to the organization's host
volume and are never resolved against the SDK client's filesystem. A bind root
request to follow symlinks still refuses, because the Cloud source contract does
not represent it and the worker deliberately disables it.

By explicit user direction, remote mount owner IDs are enabled against current
Managed Cloud support. The resolver and worker preserve `MountOptions` owner
IDs and force strict stat virtualization for directory mounts. IDs change the
guest metadata fallback, not host ownership or tenant path authority. The SDK
still validates paired IDs and rejects owners on non-directory mounts. Earlier
server deployments might ignore these optional fields; there are no self-hosted
deployments in the user's supported fleet and this is an approved server-support
requirement. Local runtime capability checks are unchanged.

Local snapshot launch checks the architecture recorded in a memory checkpoint or identified by the pinned OCI image for a disk restore. A confirmed mismatch fails before a replacement stops its destination. Import, inspection and verification accept foreign artifacts. Historical disks without recognizable architecture metadata retain the existing launch behavior.

Disk snapshots captured with confirmed last-active guest-clock policy now use the existing clock descriptor extension. A recorded `off` survives group and archive restores unless the destination explicitly overrides it. Sync, historical descriptors and captures without clock evidence retain the existing fallback. Earlier readers without the required clock extension refuse a newly recorded off policy.

## Local kill and drain process identity

On Linux and macOS, kill and drain require evidence that the recorded PID belongs to the selected sandbox runtime. Linux sends signals through a captured pidfd. macOS verifies lifecycle ownership and process birth identity before signaling; Darwin’s PID-based syscall still leaves a narrow check-to-signal race.

Denied process inspection does not establish that a run is stale. Reconciliation requires a free lifecycle guard, no possibly live runtime socket, and free owned-disk guards; ambiguous ownership returns an error and preserves the active run. No public API, runtime protocol, or persisted-format change is required. Replacement and fresh-start recovery are separate from this change.

## Concurrent catalog sidecar teardown

Catalog hardening retries up to 16 complete inspections when SQLite sidecar teardown exposes an unlinked inode or the path changes during inspection. Every attempt repeats the ownership, link and permission checks; symlinks, hardlinks and untrusted access remain rejected. Continued churn returns an error. No SQLite schema, migration guard, lock protocol or runtime format changes.

### Restarting a snapshot with execution limits

A snapshot destination with a retained nondefault execution policy needs a runtime advertising `restored_exec_limits`. Initial creation checks this before replacing an existing sandbox. A later start on an older runtime fails with `saved execution limits require a runtime that can enforce them`. Use a capable runtime to restart it, including with an older SDK. The catalog remains readable and other sandboxes can start. Removing the destination removes its execution policy.

### Checkpoint CPU and memory observations

New clients and runtimes negotiate `configuration_freeze_resources` before requesting private capacity evidence. The host sends the original freeze payload to a guest without the observation capability. An older client receives its original receipt shape. Missing observations allow the checkpoint to succeed and leave the corresponding resource unknown. The observation is private to capture and does not change the public Ready type, guest protocol generation, snapshot format or metrics layout.
