03 · Product specification

The behavioral contract for Ephemeral Sandbox Fabric.

This specification defines the public model, operations, invariants, acceptance criteria, and capability boundaries for 0.2.x. It is intentionally backend-neutral where semantics must survive OCI/Linux and WASI.

Document: PRD + technical spec
Status: Proposed
Version: 0.2.x target
Compatibility: Additive migration

Problem statement

Sessions are useful execution handles, but poor durable branch identities.

Multiagent coding, RL, and MCTS all create more logical branches than can remain live. If durable state is coupled to containers, mounts, or mutable sessions, cost grows with history and recovery becomes backend-specific. The product needs a durable graph abstraction that can be activated on demand.

Primary jobs to be done

Multiagent developer

Fork isolated work from a stable checkpoint, review evidence, and merge compatible results without accidental cross-writes.

RL coordinator

Fan out reproducible trajectories from a pinned policy/root pair while bounding live compute and retaining versioned outputs.

MCTS controller

Select, expand, evaluate, and prune a durable search tree without assigning one resident sandbox to every node.

Platform operator

Recover leases, transactions, and garbage collection after crashes while preserving selectable checkpoints.

Public object model

Stable product identities are separate from runtime attempts.

The graph model exposes durable intent. ExecutionAttempt records bind that intent to a specific backend, environment, resource budget, and lease for only as long as execution is needed.

SandboxGroup

Owns one immutable checkpoint graph and its canonical generation.

group_id
canonical_node_id
generation
policy

owns

SandboxNode

A selectable, immutable checkpoint with parentage and logical state.

node_id
parents[]
root_id
logical_state
status

activates

ExecutionAttempt

A disposable activation of one node on one backend.

attempt_id
node_id
executor
lease_id
private_delta

produces

Evaluation

Versioned evidence and decision for one sealed result.

evaluation_id
attempt_id
evaluator_version
reward
verdict

Operation contract

Small primitives compose development, rollout, and search.

Every mutating operation accepts an idempotency key. Operations that advance shared state also accept an expected generation or root, making stale decisions visible instead of silently overwriting newer work.

Graph

create_group: Create a graph from an existing immutable root.
fork: Create O(1) child nodes referencing a sealed parent.
inspect: Read node, ancestry, provenance, leases, and evaluation state.
prune: Mark an unleased subtree unreachable and eligible for bounded GC.

Execution

activate: Lease a node and create a backend-specific execution attempt.
exec: Run command/PTY work inside the attempt isolation boundary.
suspend: Quiesce and seal a new immutable child checkpoint.
retry: Create a new attempt without mutating the failed attempt record.

Integration

evaluate: Attach versioned tests, reward, acceptance, and evidence.
merge: Resolve compatible changes from multiple roots using OCC.
promote: CAS the canonical node from an expected generation.
export: Materialize a root, patch, or artifact with provenance.

State machines

Node and attempt states make partial failure explicit.

SandboxNode

draft
sealed
terminal
pruned

ExecutionAttempt

queued
active
quiescing
sealed
failed
released

Normative requirements

Falsifiable requirements with acceptance evidence.

ID	Requirement	Acceptance evidence
FR-01	Forking a sealed node creates children without copying the parent workspace payload.	Allocated payload bytes for N hot local forks remain zero for shared lower data.
FR-02	Sibling attempts must not observe each other’s unsealed writes.	Concurrent write/read isolation test across at least two siblings.
FR-03	Sealing publishes filesystem root, logical state, provenance, and result atomically.	Crash injection at every journal boundary yields either no node or one complete node.
FR-04	Promotion and merge reject stale expected generations.	Race test proves at most one competing canonical advance succeeds.
FR-05	Retries must not double-apply reward, evaluation, or MCTS backpropagation.	Repeated delivery of the same idempotency key leaves counters unchanged.
FR-06	Selectable nodes and their ancestor closure remain pinned through GC.	Concurrent prune/GC/activate test never loses a leased root.
FR-07	The same logical root must open with equivalent content through supported OCI/Linux and WASI adapters.	Cross-backend manifest walk produces equal paths, types, bytes, modes, and link targets.
FR-08	Live sandbox count must remain bounded independently of durable graph size.	A large inactive graph never exceeds configured attempt and memory quotas.
FR-09	Target images must not require LayerStack helpers or repository utilities.	Execution succeeds in a minimal compatible image using worker-provided projection only.
FR-10	Every result must retain root, environment, policy/evaluator, attempt, and parent provenance.	Exported evidence passes referential-integrity validation.

Quality attributes

Performance is measured without weakening correctness.

Fork complexity

Benchmark

O(1) metadata in workspace size; zero lower payload duplication for a hot local root.

Command I/O

Profile

OCI/Linux uses native filesystem access on the execution hot path.

Recovery

Fault injection

Every journaled mutation is replayable or abortable without an ambiguous node.

Scalability

Load test

Durable graph size is decoupled from live process, mount, and memory residency.

Portability

Schema audit

Durable state contains no worker-local mount paths, inode identity, or backend-only truth.

Observability

Trace audit

Every transition emits correlated group, node, attempt, root, lease, and trace identifiers.

Capability and trust model

Portable state does not imply identical executor privilege.

Coordinator

May create graph intent and request work; cannot forge sealed roots or evaluations.

State plane

Trusted for object integrity, OCC, leases, journal recovery, and provenance.

Worker

Trusted to enforce the selected backend boundary and attest the produced result.

Sandbox code

Untrusted; receives only scoped workspace, process, network, and resource capabilities.

OCI/Linux mount privilege is confined to the worker/executor boundary and is never delegated to sandbox commands.
WASI receives capability-scoped preopens backed by the same logical root contract.
No writable delta is shared between attempts, including parent/child and sibling relationships.
Environment, base image/module, network policy, secrets policy, and evaluator version are pinned in provenance.
CAS objects are verified before use; logical manifests never trust worker-local paths as identity.

Non-goals for 0.2.x

Explicitly outside the portable core.

Live process time travel

CRIU and instruction-exact rollback may be adapters later; filesystem/logical checkpoints define the core.

Unprivileged Linux OverlayFS

The design scopes mount capability; it does not remove the kernel’s privilege requirements.

One runtime for every backend

OCI/Linux and WASI share state semantics, not identical syscall or process semantics.

Automatic semantic merge

The core provides OCC and evidence; domain-specific agents or tools choose conflict resolution.

Infinite retention

Leases and reachability protect useful history; bounded GC reclaims unselected branches.

One attempt per node

Retries are first-class records and never rewrite prior evidence.