firkin-runtime

firkin-runtime is the production Apple/VZ composition crate.

It is allowed to know about:

• firkin-core VM and container mechanics.
• firkin-template checkout, setup, cache-warming, and freshness execution.
• firkin-substrate capacity, snapshot, warm-pool, benchmark, and hygiene policy.
• firkin-types shared value types.
• firkin-e2b Cube/E2B-compatible API contracts.

Lower-level crates must not depend back on this crate. VZ-backed template snapshot sinks, snapshot-restore session creation, live capacity admission, and CubeAPI runtime wiring belong here.

Runtime storage must not default to TMPDIR. FirkinStorageConfig is the library surface for storage roots: durable state defaults to ~/.firkin/state, rebuildable caches default to ~/.firkin/cache, and callers can pass explicit roots or use FIRKIN_STATE_DIR / FIRKIN_CACHE_DIR. Continuation snapshots, restore staging, single-node snapshots, and E2B local state derive from this layout unless a more specific artifact root is configured.

The first restore seam is RuntimeSnapshotRestore: it admits active capacity, calls a SnapshotSessionLauncher with the durable snapshot manifest, records a warm_snapshot_restore latency sample, and releases capacity if restore fails. RuntimeCubeSandboxCreate wraps that path for CubeAPI/E2B create: it restores the prepared template snapshot as the primary create path and returns the SDK-visible RuntimeSandbox shape while keeping the Firkin session and active capacity reservation in the runtime report. FirkinRuntimeAdapter implements firkin_e2b::RuntimeAdapter over that same path, so LocalRuntimeBackend can create Cube/E2B sandboxes by restoring prepared Firkin snapshot artifacts directly. It also hard-rejects direct template preparation and restrictive network policy until those production paths have real Firkin-owned enforcement. Port routing is session-owned: RuntimePortRouter lets the restored Firkin session open the live byte stream, and firkin-core containers implement it through VM vsock dialing. Readiness is session-owned as well: RuntimeReadinessProbe checks that the restored service surface is reachable before the adapter exposes the sandbox, records ready_probe latency, and tears the session down if readiness fails. Command execution is session-owned too: RuntimeCommandRunner lets the adapter serve the local envd process start contract from the restored session and retain command_start plus first_stdout_byte samples. The first non-interactive command after a prepared-template restore also records start.resume_to_first_stdout_ms, which composes restore start through the first stdout byte while preserving the lower-level restore and command spans. Session stop is session-owned too: RuntimeSessionStop lets the adapter stop the live runtime session before releasing active capacity, and firkin-core containers implement it by signaling the init process. The adapter retains lifecycle benchmark samples from create/follow-up restore readiness, command start, first output, and stop, giving the Cube-facing path a concrete source for measured warm_snapshot_restore, ready_probe, command_start, first_stdout_byte, and kill_delete evidence. RuntimeSessionTerminate asks a SessionTerminator to stop/delete an active session, releases active capacity only after termination succeeds, and records kill_delete latency. RuntimeDiskPressureGuard is the host free-space floor admission seam; callers provide a DiskPressureProbe for the operator-selected runtime root, and work is blocked before snapshot or VM pressure can drive the host below that floor. HostDiskPressureProbe is the default host implementation; it reads available space with df -Pk to preserve this crate's no-unsafe boundary. RestartReconciliation applies substrate restart decisions through a runtime executor adapter, giving the controller one ordered path for recover, cleanup, and quarantine work after restart. RuntimeStuckVmCleanup applies heartbeat-timeout cleanup decisions through a runtime cleaner adapter, keeping stuck-VM policy separate from live VZ termination mechanics.

With the snapshot feature enabled, CoreContainerSnapshotSink adapts a live firkin-core container into firkin-template's async TemplateSnapshotSink. RuntimeContinuationSnapshotCapture uses that same sink contract to save a stopped, idle, or exited session as a continuation snapshot and records snapshot_save latency for the capture path. RuntimeTemplateBuildSnapshot is the runtime-owned template build seam: a live adapter runs repo clone/setup/cache-warm commands inside the target runtime, a snapshot sink persists the prepared VM/container state, and the report records cold_template_build plus snapshot_save latency. CoreTemplateCommandRunner runs that command path in a live firkin-core container through exec calls, while CubeAPI create wiring remains a separate adapter. RuntimeCubeSandboxFollowup wraps continuation restore for follow-up prompts: it restores the continuation snapshot, preserves the stopped/idle/exited reason, and returns the SDK-visible RuntimeSandbox shape with the Firkin session reservation in the report. FirkinRuntimeAdapter::start_followup exposes that path to Cube-facing runtime wiring without pretending it is the same operation as E2B pause/resume.

RuntimeWarmPoolMaintain is the first warm-pool runtime seam: it asks a WarmPoolSessionLauncher to restore a snapshot for a repo/template/runtime key and records the resulting WarmPoolEntry in the substrate ledger. RuntimeWarmPoolCheckout promotes that warm entry to active use, returns an active reservation, and records warm_pool_checkout latency. RuntimeWarmPoolService owns the retained snapshot pool, replenishment supervisor, and snapshot launcher together so a runtime process has one testable object for refill ticks and warm checkouts. It can also spawn an owned refill task with a shutdown handle for process-level service wiring.