0.2.x architecture roadmap
Planned specificationFrom workspace runtime to Ephemeral Sandbox Fabric.
A checkpoint-native platform for isolated multiagent development, parallel RL rollouts, and MCTS search—sharing one durable LayerStack state plane across OCI/Linux and WASI execution.
0 B clean fork
no lower payload clone before the session writes
O(F) first write
a lower-only F-byte file may be copied up in full
Lhot + Hcold
the conditional settled payload target after squash and GC
Target architecture
One state graph, many isolated executions.
Workload controllers share the same orchestration and state primitives. Only bounded, selected nodes become live sandboxes; the remaining graph stays durable and disk-backed.
Workload controllers
Multiagent development
Tasks · reviews · merges
RL coordinator
Policies · seeds · trajectories
MCTS controller
Select · expand · backpropagate
Sandbox orchestration plane
SandboxGroup
Immutable checkpoint graph
Search state
Visits · rewards · frontier
Scheduler
Leases · quotas · locality
Evaluator
Tests · reward · acceptance
LayerStack durable state plane
Logical manifests
Runtime-neutral workspace identity
CAS
Content · metadata · logical state
Transactions
OCC · leases · recovery · GC
Artifacts
Logs · patches · trajectories
Bounded execution fabric
OCI/Linux executor
Native immutable lower + private OverlayFS upper
WASI executor
Capability-scoped LayerStack filesystem
Sealed checkpoint result
Evaluate → accept, merge, backpropagate, or prune
Physical storage lifecycle
Share clean roots; charge the bytes that isolated sessions really own.
LayerStack avoids cloning the merged workspace when a session starts. That does not make every edited session free: OverlayFS copy-up can place a complete resulting file in the private upperdir. CDC optimizes retained immutable history after publication; it does not turn the active upperdir into a byte-patch store.
total(t) = Lhot(t) + Hcold(t) + ΣUactive(t) + Pstaging(t) + M(t)Count native hot roots, unique cold history, every live private upper, publication staging, and all metadata/recovery state. CAS bytes alone are never total LayerStack storage.
- 01+ O(1) metadata
Clean fork
The child leases the same immutable lower root and starts with an empty private upperdir.
- 02upper may add ≈ F
First edit to lower-only file F
OverlayFS may copy up the complete file before applying a tiny logical write. The upper entry is a resulting file, not a byte delta.
- 03one upper file
Ten edits in one session
Repeated writes reuse that session’s copied-up inode; they do not create ten private historical versions before publication.
- 04ΣUactive; worst case ≈ N·F
N modified sessions
Isolation requires separate writable uppers. Clean sessions remain cheap, but independently modified copies are real physical payload.
Publication controls the peak; squash controls retained history.
- Publish
- A stream-build can temporarily add another staged payload. An eligible, journaled same-filesystem carrier transfer can seal a quiesced upperdir without a second payload copy; merge and compatibility fallbacks still build a new carrier.
- Squash + CDC
- Content identities reuse unchanged regions across revisions only after superseded native carriers can be retired. Old leased roots remain readable and continue to pin their required bytes.
- Settled target
- Near one current logical copy is conditional: one hot current native view, no modified live upper, no old lease requiring another native carrier, and settled GC. It is not a fork-time or publication-peak guarantee.
- Execution
- exec_command, file I/O, PTY, and stdin stay on the native OverlayFS path. No CAS reconstruction is added to command execution.
Migration plan
Four dependency-ordered milestones.
Each milestone has a narrow objective and a falsifiable exit gate. A later phase must not compensate for a failed storage, isolation, or recovery invariant.
Phase 01
Universal LayerStack
- Objective
- Turn LayerStack into the portable source of workspace truth without moving CAS reconstruction onto command execution.
- Delivery scope
- Runtime-neutral logical tree manifests and content identities.
- Native materialization for ordinary OCI/Linux file and PTY execution.
- Strict separation between portable identity and worker-local extent locations.
Exit gate
The same immutable root opens through OCI and WASI workspace views with verified logical equivalence; OCI commands perform no per-read CAS reconstruction.
Unlocks
- Portable checkpoints
- Backend independence
Phase 02
SandboxGraph Runtime
- Objective
- Promote immutable checkpoint nodes—not running sessions—to the durable branching abstraction.
- Delivery scope
- Durable SandboxGroup, SandboxNode, and ExecutionAttempt records.
- Root-addressed activate, checkpoint, merge, promote, prune, and retry.
- Private writable deltas with OCC, leases, crash recovery, and bounded GC.
Exit gate
Sibling writes remain isolated, a hot local fork duplicates zero lower-directory payload bytes, and stale promotion cannot overwrite newer work.
Unlocks
- Multiagent branches
- Review and merge
Phase 03
Rollout Fabric
- Objective
- Schedule a large durable search graph onto a small, bounded pool of live isolated sandboxes.
- Delivery scope
- Lease-based placement with concurrency, resource, and locality limits.
- Versioned evaluators, policies, seeds, trajectories, and acceptance records.
- MCTS statistics outside immutable checkpoints and idempotent rollout retries.
Exit gate
Retries cannot double-apply reward or backpropagation, inactive nodes stay disk-backed, and frontier leases remain valid through recovery and GC.
Unlocks
- Parallel RL rollout
- MCTS expansion
Phase 04
Ephemeral Sandbox Fabric
- Objective
- Unify heterogeneous executors and locality-aware workers behind the same checkpoint and evaluation contract.
- Delivery scope
- OCI/Linux and WASI workspace adapters over the shared state plane.
- Capability-aware worker registration and cache-local placement.
- Pinned environment semantics, provenance, observability, and result sealing.
Exit gate
A Sandbox Group schedules reproducibly onto every supported backend without target-image utilities, writable-state sharing, or backend-specific checkpoint truth.
Unlocks
- Heterogeneous workers
- Cluster-scale placement
Product requirements
The contracts 0.2.x must preserve.
Required outcomes
- Every selectable node is an immutable root plus durable logical state and provenance.
- Every active attempt owns a private writable delta, namespace, lease, and resource budget.
- Logical fork cost is O(1) with respect to workspace size; hot forks add zero lowerdir payload bytes.
- Only explicit OCC merge or promotion may advance a canonical project root.
- Memory and live sandbox count remain bounded independently of graph size and history depth.
- Checkpoint publication, retries, evaluation, backpropagation, and GC recover idempotently.
Excluded from the required path
- No CRIU or instruction-exact live-process rollback in the portable core.
- No FUSE, custom kernel, loop device, XFS reflink, or target-image helper in the required path.
- No writable upperdir shared between parent, child, or sibling attempts.
- No one-container-or-VM-per-durable-node residency model.
- No search statistics embedded in immutable filesystem manifests.
- No silent promotion of speculative or stale results.
Workload model
One substrate, three orchestration patterns.
| Dimension | Multiagent development | RL coordinator | MCTS controller |
|---|---|---|---|
| Graph shape | Branching DAG with merge nodes | Wide fan-out from a pinned root | Selection and expansion tree |
| Durable output | Code checkpoint, tests, review evidence | Trajectory, reward, terminal state | Child checkpoint and evaluation |
| Integration rule | Merge compatible writes through OCC | Learner consumes versioned trajectories | Backpropagate once per accepted rollout |
| Retention policy | Keep active branches and published history | Keep trajectories; prune most workspaces | Lease frontier; prune rejected subtrees |