One durable filesystem truth. Many isolated workspaces.
LayerStack orders immutable B, L, and S layers in a newest-first manifest. Each session leases that chain, projects it through OverlayFS with a private upperdir, and changes durable truth only through conflict-aware atomic publication.
The stack is durable. The execution view is leased. Mutation is private. Publication is atomic.
Persistent core
manifest.json
Visible order
manifest-owned
Retention
lease-pinned
A workspace is a temporary projection. Publication returns it to the stack.
Storage and the namespace process substrate are independent roots. They meet in a leased overlay view; private mutations become durable only when capture and publication close the loop.
LayerStack store
The manifest defines the visible filesystem. Immutable layers carry base bytes, published changes, and compacted history; leases decide what may be reclaimed.
Overlay workspace view
Pinned lowerdirs and a fresh upperdir become one workspace inside the holder's mount namespace.
Execute and edit
Commands and live file operations read the union while every write, copy-up, and deletion stays in the session upperdir.
Capture, resolve, and prepend one L* layer
Publication closes the loop by prepending the resolved changeset to the LayerStack manifest.
Squash is a maintenance side loop. It compacts eligible L/S runs and remounts safe live sessions without changing visible bytes; it is not the end of every request.
- Durable
- One newest-first manifest orders immutable B, L, and S layers.
- Stable
- A lease pins the exact lower-layer chain used by a live session.
- Private
- Commands and file operations mutate only the session upperdir.
- Atomic
- A resolved changeset becomes one new L layer, or publication rejects it.
Start with the architectural question you need answered.
The chapters follow the same loop, but each one owns a specific boundary instead of presenting the system as disposable stages.
- 01
What is durable?
LayerStack store & copy-on-write
Newest-first manifests, immutable B/L/S layers, leases, conflicts, and blame.
Open chapter - 02
What does a session see?
Overlay workspace projection
Pinned lower layers and private writable state become one workspace tree.
Open chapter - 03
Where does code run?
Namespace execution & isolation
Persistent holders, one-shot runners, isolation layers, and teardown.
Open chapter - 04
How do private changes become durable?
Capture, resolve & publish
Session gates, capture, per-path conflict resolution, and atomic publication.
Open chapter - 05
How does the chain stay bounded?
Squash & live remount
Squash, verified remounting, crash survival, and conservative cleanup.
Open chapter