LayerStack COW Architecture — Ephemeral Sandbox

Section 01 · LayerStack copy-on-write

Share history. Isolate mutation. Reconcile at publication.

The name describes the structure: a stack of immutable layers. Copy-on-write describes the execution rule: agents read through the shared stack, but write only into their own temporary layer.

Layer + Stack

An ordered immutable history

A manifest points to the visible layers in newest-first order. Reads use the first visible version of each path; squash can compact old runs without changing that logical view.

Copy + on write

A private mutation surface

Every session mounts the same read-only lower history beneath a fresh upperdir. The kernel copies up a lower file only when that session first mutates it.

LayerStack: The store and ordered manifest of immutable filesystem layers. The manifest is newest-first, so the first layer containing a path wins.
Base · B*: The content-addressed starting workspace. Every branch can reference the same physical payload instead of cloning it.
Published layer · L*: An immutable delta created from a resolved publish. A successful commit prepends it to the manifest.
Upperdir: One session’s private writable overlay directory. New files, copy-ups, and deletion markers live here until capture.
Lease: A pinned manifest snapshot that keeps a session’s lower layers alive and makes its execution view stable.
Whiteout: Overlay metadata that means “this lower path is deleted.” It lets a delta remove a file without mutating older layers.

System breakdown

A write travels forward; a publish loops back into history.

Published stack

L000042

newest published delta

S000041

compacted history

B000001-base

one shared base payload

Session overlay

upperdir/ws-17rw

private writes + whiteouts

union view

lowerdir+ro

lease · newest-first · pinned

Publication gate

1capture upperdir changes
2compare path fingerprints
3merge or reject conflicts
4fsync, rename, prepend manifest

result → next L*

Lease

Pin the current manifest and its ordered lower paths.

Mount

Attach a fresh upperdir and workdir above that frozen view.

Execute

Read the union; direct every mutation into the private upperdir.

Capture

Scan the upperdir into writes, symlinks, deletes, and opaque dirs.

Resolve

Compare path fingerprints with head and merge eligible text.

Commit

Prepend one immutable layer—or reject the entire changeset.

Space + time complexity

Constant base payload, proportional private state.

LayerStack removes the expensive N × B clone. It does not make total storage or every operation constant-time. The honest model separates shared history from per-session state.

Storage model

Mode A S(N) = B + P + ΣΔᵢ + N·M_sandbox

Mode B S(N) = B + P + one sandbox + ΣΔᵢ + N·M_session

B: one physical base payload
P: retained shared published history
Δᵢ: rollout i private COW bytes
M: topology-specific metadata

As N grows

Physical base payloadΘ(1)

Private metadataΘ(N)

Private COW bytesΣΔᵢ

A tiny logical edit can still copy up a whole file, so Δᵢ may be larger than the user-visible diff.

Operational time model

B = base bytes · L = visible layers · P = path components · R = returned bytes · F = copied-up file · W = write · C = captured paths · H = hashed/merged bytes · K = compacted bytes

Operation	Time	Why
Build or populate the base	`Θ(B) once`	Read and materialize the B-byte workspace before it can be shared.
Create one workspace session	`Θ(L)`	Build the lease and ordered lowerdir list; no Θ(B) workspace copy.
Read R bytes from a path	`O(L·P + R) worst case`	Lookup may cross L layers and P path components, then returns the file bytes.
First write to a lower-only file	`O(F + W)`	Overlay copy-up may copy the full F-byte file before applying a W-byte write.
Later writes in the same session	`O(W)`	The file already lives in the private upperdir.
Capture and publish	`≈ O(C log C + C·L·P + H)`	Sort C captured paths, resolve them through the stack, and hash or merge H affected bytes.
Squash a selected layer run	`O(K)`	Materialize K compacted bytes to shorten future lowerdir chains.

Runtime isolation + conflict detection

Let agents run wide. Coordinate at the narrow gate.

Agents do not contend on one writable checkout. Each executes in a holder-owned mount namespace with a private upperdir; isolated networking can add a separate network boundary. Concurrency control moves to a short publication transaction.

agent-a

Δ src/auth.ts

disjoint path

agent-b

Δ README.md · hunk 1

mergeable text

agent-c

Δ README.md · hunk 1

overlapping edit

OCC publication gate

Recheck each source path against current head. Attempt a three-way merge for eligible text. Commit every resolved path atomically, or commit none.

base · head · command

disjoint → clean

mergeable → merged

overlap → rejected

Paths ignored by policy are deliberately outside this per-path validation pass.

LayerStack enables a higher practical cap; it does not set one. By removing full workspace copies and shared-write races, it makes wider concurrency safer and cheaper. Command execution still has a configured limit—currently 256 by default—plus OS and resource ceilings.

Concurrent execution lanes

Subject to CPU, memory, namespace, and mount capacity.

Shared writable worktrees

Unpublished writes stay in their originating session.

Atomic publication boundary

Coordination is deferred until an agent has a result.

File-operation blame

Publication records line ownership.

This is not Git blame. During conflict resolution, LayerStack records whether each final line came from the command or the active file. After commit, the file domain maps that structure to an opaque runtime owner.

Attribution pipeline

1
Resolve
Origin::Command or Origin::Active(i)
2
Map
mint workspace_session:<id> or operation:<id>
3
Append
write one audit event after the layer commits
4
Query
tile and coalesce owner ranges for file_blame

file_blame

$ file_blame src/auth.ts

1–8original

9workspace_session:ws-17

10–12original

13–14operation:req-91

Published only

Live upperdir edits stay invisible until commit.

Squash-safe

Auditability is stored outside the compacted LayerStack.

Best-effort

A dropped post-commit audit append resolves uncovered lines to unknown.

Two fanout modes

Choose the isolation boundary, keep the sharing invariant.

Fanout can happen outside the runtime with N sandboxes, or inside one runtime with N workspace sessions. Both avoid N full copies of the base; their failure boundaries and private overhead are different.

Here, parallel describes the resulting execution lanes. Current sandbox batch creation and workspace-session setup serialize their setup calls before those environments run concurrently.

Shared-base provisioning · payload written once per digest

01
Hash input
Derive the content-addressed workspace identity.
02
Build privately
Populate a nonce cache entry without exposing partial state.
03
Promote or reuse
Atomically install the digest, or reuse the winner of a race.
04
Lease read-only
Every sandbox points at the same immutable base payload.

O(1) base payload means storage is shared by digest, not that all setup work is constant-time. N sandboxes still need N private runtime records, writable trees, and namespace lifecycles.

Mode A · isolation first

N concurrently runnable sandboxes

sandbox 1

sandbox 2

sandbox N

Docker image layers and the content-addressed workspace base are shared. Container writable state, scratch, LayerStack metadata, and COW deltas remain private.

Best fit: untrusted, heterogeneous, or failure-sensitive rollouts.

Mode B · density first

N sessions in one sandbox

one sandbox · one LayerStack

session 1

session 2

session N

Sessions share the same lower paths and daemon, while each owns an upperdir, workdir, holder, lease, and COW delta.

Best fit: dense, homogeneous rollout batches.

B000001-base

same content digest · one physical payload

Θ(1) in rollout count N

Why this maps naturally to RL rollouts

Cheap forks, isolated trajectories, attributable artifacts.

01
checkpoint + task
02
fork environment
03
observe · act · use tools
04
verify + reward
05
collect trajectory
06
update policy

Fast reset semantics

Drop private state and point the next rollout at the same base digest.

Leakage becomes testable

A marker written by one rollout must never appear in another view.

Results remain explainable

Base digest, private bytes, tool traces, and published owners travel with the trajectory.

Scope the claim carefully: LayerStack makes the immutable base payload Θ(1) in N. Private deltas, control metadata, trajectories, model weights, and compute still scale with the rollout batch.