Platform and limits

Supported platforms

Everything that opens a project's Store must share one Linux kernel, and the Store must sit on alocal ext4, xfs or btrfs filesystem. SQLite's locks, and LayerFS's own coordination between writers, only work within one kernel, so LayerFS checks this when it opens the Store and refuses anything else asUnsupported, before any write. There is no fallback route.

npm --prefix sdk/js run build:native   # on the Linux host that loads it

Store formats change between versions, and an older Store is refused rather than migrated: start a fresh project with the new version.

Durability

The Store runs one profile, Disposable: SQLite in WAL mode with synchronous=OFF. LayerFS never waits for the disk to confirm a write, which keeps every Commit short.

Durability is not claimed. A crash of LayerFS itself loses nothing it reported as committed, but an operating-system crash or power loss can lose recent history or damage the Store. A durable profile exists in the code but is turned off for now. Keep anything you can't afford to lose somewhere else as well, for example by pushing Git from inside a Workspace.

Concurrency model

One project, one Store file, one writer at a time, with short holds. Agents' tool calls are separated by model thinking time, so two Commits at the same instant are rare; LayerFS keeps them correct rather than racing them. The Store diagram shows the shape.

• Reads never wait. They read a committed snapshot beside the writer.
• Writes take turns. Heavy work (building and encoding the new tree) runs side by side; only the short step that checks the head, merges and publishes is one at a time. A write waits its turn instead of failing.
• Same Branch, many writers. Each write merges with the head it meets: different paths both land, the same path is refused with Conflict. See Merge and conflicts.
• Create Sandboxes one at a time. Creates take a lock per project; one that meets another is refused Busy before doing anything. After that, Sandboxes work independently.
• Keep each agent sequential. Give every agent its own Sandbox and let it run its calls one after another. One process can make up to six calls to one Sandbox at once.
• Nothing is retried. Every call is attempted once and answers its exact outcome. On Unknown or Failed, look before you act again.

Limits

No file, Workspace or Commit has a size cap of its own; disk space and the filesystem are the limits. These are the edges of single calls:

What isn't saved

History is the filesystem: the files, folders, links and modes in a tree. It is not a snapshot of a running machine.

• Processes, memory and sockets. A dev server or a database running in a Sandbox isn't in any Commit. Forking a Branch gives you its files, not its processes.
• Command output. sandbox.exec returns stdout and stderr to you; they aren't stored. Save what matters to a file in the Workspace, or in your own logs.
• Uncommitted Workspace changes. Nothing is saved until sandbox.commit. Unmounting with discard, or losing the container, drops them.
• Files outside the Workspace. /tmp and read-only volumes mounted into a Sandbox are not part of the tree.
• Runs without changes. A step that changes nothing makes no Commit, and a message on sandbox.exec creates no history.
• Copy times. fs.cp gives copies new timestamps; fs.mv keeps them.
• Daemon logs. sandbox.close deletes the container and its logs; save them first if you trace.

A command's exit doesn't prove everything it started has finished. A Commit saves the Workspace as it stands at that moment, including what background processes have written so far.