RFC 0007: Snapshot and Recovery

Status: accepted for the preview in-memory contract; durable SQLite recovery remains a Phase 7 stress proof. A snapshot contains validated provider-neutral run state and the last event sequence; it excludes clients, secrets, functions, processes, and mutable registries. Import validates schema, identity, monotonic sequence, and terminal state. Uncertain mutating operations are recorded explicitly and never replayed automatically.

The v1alpha2 snapshot is deterministic, immutable, and bounded. It contains only run ID, definition identity/model/turn limit, completed turn count, provider-neutral message history, one combined plan identity, sorted previously used interaction IDs, last committed sequence, and a safe lifecycle status. The plan identity contains sorted compiled bean identities, the exact tool-plan ID, an explicit generated snapshot-compatibility identity, and a canonical fingerprint over all of them plus the leased tool definitions. It never serializes providers, tools, brokers, contexts, functions, credentials, process handles, clients, logs, or mutable registries. Conversation content is application data and persistence extensions must protect it accordingly.

Export succeeds only while suspended at a fully completed turn boundary or after a run terminal. Duplicate message/call IDs, unmatched tool calls/results, unknown fields, unsupported versions, active state, pending interactions, unresolved tool mutations, invalid roles, and oversized content fail closed.

Every process-boundary envelope is signed by a trusted snapshot authority. Its public claim contains an exact 32-byte scope ID, a positive key generation, and an exact 32-byte HMAC-SHA256. The canonical MAC input is a sequence of unsigned 64-bit big-endian length-prefixed components: domain spice.agent.run-authority/v1, scope ID, generation encoded as eight-byte big-endian, format, run ID, last sequence encoded as eight-byte big-endian, lifecycle encoded as four-byte big-endian, and the already-validated payload SHA-256. The authority HMAC and unknown Protobuf fields are not self-signed. Construction cannot produce an unsigned envelope. Import requires a keyed verifier; structure and the unkeyed payload digest never establish authority.

Only a suspended snapshot may resume. Compiled plan identities supplied by generated applications include the bean’s module, version, and source identity. The leased definition fingerprints cover the exact tool contracts. Before event log creation or engine mutation, the importer leases the recorded ToolPlanID and recomputes the combined PlanIdentity; missing, substituted, or changed plans fail closed and release the candidate lease. Resume additionally requires exclusive ownership. In the same daemon, a known active, suspended, terminal, or tombstoned run ID conflicts deterministically; import never replaces that authority. Across processes, import is permitted only after the caller establishes that the original run authority is dead, and the destination engine must not have seen the embedded run ID. The destination additionally resolves the scope and generation to a server-owned key and verifies the HMAC before any lease, tombstone, event-log, or engine mutation. Unknown scopes, unavailable generations, and incorrect HMACs share one secret-safe failure. Resume does not emit a second RunStarted; it continues at last_sequence+1, starts the next turn, and derives run-scoped model/message identities so a fresh process cannot reuse earlier lifecycle IDs. Terminal snapshots are inspectable but never resumable. Automatic replay of uncertain mutating work is deliberately excluded. An imported event tail has no copy of pre-snapshot events, so subscriptions with older cursors fail explicitly with the snapshot sequence as the recovery cursor. The plan ID records immutable host identity; successful resume requires a real live lease and never treats serialized identity as a process handle.

Convenience engine constructors intentionally leave snapshot compatibility empty. Their runs support local suspend/resume and deterministic export for inspection, but another engine refuses import. Generated applications must set one semantic compatibility identity and compiled identities for every executable provider, stage, observer, broker, static tool, and decorator bean. Static compatibility mismatches are rejected before LeaseGeneration can launch or revive dynamic resources.

HMAC authority is integrity and provenance, not encryption. The OS-backed authority stores a random scope ID and a distinct random key separately from local IPC tokens. Its authority-key generation is the generation signed on the wire; an independent per-run transition generation prevents replay without pretending the key rotated. A domain-separated per-run HMAC subkey binds the scope, run ID, and local transition generation, so even otherwise identical snapshots from different suspend generations have different claims. Stable per-run lock files are never unlinked. The authority binds and retains the validated authority-directory identity: Unix operations are descriptor-relative and Windows operations are handle-relative, so renaming or substituting a path cannot redirect authority state. Every open also validates the complete ancestry against OS ownership and delete/ACL-mutation rights and proves the walked final object is the retained object, preventing rollback by a different unprivileged principal after close/reopen. Windows trusts the volume namespace, current user, SYSTEM, Administrators, and TrustedInstaller; Unix trusts root and the current user, with sticky-directory semantics handled explicitly. Same-user and elevated compromise are outside the per-user authority boundary. Authority creation sets a newly created Unix leaf to 0700; opening an existing leaf is validation-only and requires it already be exactly 0700. Authority shutdown rejects new work and drains outstanding run/import leases before releasing that identity, then clears the canonical in-memory HMAC key. Proven cancellation at the final pre-write context check remains retryable; a failure after filesystem-writer invocation is uncertain even when the caller observes cancellation, because persistence or its final durability barrier may already have completed. ACTIVE cannot be imported, SUSPENDED records bind the exact digest and authority HMAC, IMPORTING is a durable consume point, and terminal records are non-resumable tombstones. Snapshot export remains logically read-only to kernel state but is authority-gated: signing SUSPENDED retains exclusive ownership, identical repeat export is idempotent, and a differing claim is rejected. Local resume durably writes ACTIVE at the next generation and invalidates the old claim while the kernel is still suspended; only then may the host resume the kernel. Import prepares and verifies while holding the lock, then the host consumes, commits its prepared kernel run, and activates. Failure before consume is abortable; failure after consume is explicitly uncertain and must not be retried automatically. In particular, an uncertain Activate after kernel commit retains the import transaction lock: the host must stop and join the committed kernel run before Abort/Close releases that lock, and execution must never continue without a returned active authority lease. Same-scope recovery is supported; copying a snapshot to another user scope fails closed.