[Mkhoa161]

What this adds

A mount can cap the bytes its storage holds: capacity: 100MB in a mount block, Mount(vfs, capacity=...) / new Mount(vfs, { capacity }) in code, add_mount(..., capacity=) / addMount, a server clone or load override, or a dsh mount block. RAM only for now; any other backend refuses a cap (mount '/s3/': capacity needs a backend mirage can count; s3 does not).

• The refusal. A write that would grow the storage past its smallest cap fails with EDQUOT, "Disk quota exceeded": a new FsCondition, raised in Python as QuotaExceededError (an OSError, built as efbig builds FileTooLargeError) and in TypeScript as an FsError with code EDQUOT. The command reports it with its write-error status (1 for most, 2 for tar, 4 for sed, as GNU's), and the line goes on. Output written at once (printf, echo) is all or nothing: a refused > creates no file and leaves an existing one as it was, where GNU truncates at open. A streaming command (seq) keeps the bytes that landed before the refused chunk. Reaching the cap exactly passes.
• Every boundary names it through the table it already has: POSIX for FUSE, NFS and SFTP (Linux 122), WASI preview1 (19), CPython's errno for Monty, Emscripten's key for Pyodide (EIO when a build lacks it), HTTP 507 Insufficient Storage, and the errno body of RPC and MCP. sed -i reports a refused edit as couldn't edit and exits 4, as GNU sed's failed write does.
• Nothing is refused at creation. A mount over its cap keeps its data; reads, removals and shrinking writes pass, and only growth is refused. Counting is lazy: a storage is counted at its first counted write or df.
• One ledger per workspace, keyed by storage (vfs_storage_location, moved from workspace/mount/storage into the registry, its caller). Mounts of one store share one count and the smallest cap applies under every prefix, an uncapped alias included. A nested child mount's cap governs under it; an uncapped child is never counted against its parent. A store counted by one workspace cannot be capped by a second; the second's uncapped mounts account against the first's count. Unmounting a mount releases its own cap at once; the last cap's release detaches the usage, so the store pays nothing again. Close, a failed construction and a failed load release every cap.
• Uncapped stores take no lock and no count: each mutation pays only the store_change frame, which reads the usage before and after the change (about half a microsecond in Python).
• df and stat -f report a capped storage as QUOTA: total = the cap, used = counted bytes, available = cap − used, never below 0, each 1K figure rounded up as GNU rounds. A kernel statfs keeps its fixed answer.
• Snapshots save each mount's own cap and restore it unless the load's override names its own; an override on a backend that takes no cap (a disk folder handed back for a saved RAM mount) loads uncapped, while a RAM override keeps the saved cap. Copy and clone rebuild it.
• Sizes. parse_limit is now strict and identical on both hosts: a non-bool integer from 0 to 2^53 − 1 (a whole-number float is its integer, since JavaScript cannot tell 100.0 from 100), or ASCII digits, optionally followed by K, M or G and then an optional B, any case, inside outer ASCII whitespace. Anything else is refused with one message, must be a size like 100MB, got <value> (JSON as JavaScript prints it; Infinity and NaN by name). The cache limit (checked at load on both hosts, as capacity is) and a runtime's max_memory read sizes through it, so spellings both hosts used to read differently ("1_000", "1.5MB", "-5", "5T", an Arabic-Indic digit) are now refused on both.
• dsh refuses a mount-block key it does not take (vfs, mode, config, capacity), so a misspelt cap is an error rather than silently dropped.

Why a per-store lock instead of one loop per workspace

Python FUSE and NFS serve their callbacks on loop threads of their own (fuse/fs.py:83-84, workspace/nfs.py:89-93), so a counted RAM store can be changed from two threads at once. This change keeps that, and makes each capacity check and the table change it guards atomic with one threading.Lock per counted store. Callers take a public lock on the state object, as _Floor does (utils/ids.py:155-162, :194). The lock is held only inside plain synchronous helpers, never across an await, and a store nobody caps has no lock to take. The alternative is to serve FUSE and NFS on the workspace's own loop, so that no lock is needed. Traced from the code, that deadlocks on the caller's loop in two places. A synchronous file call on the mountpoint from async code (a notebook cell, a FastAPI handler) would block the loop that MirageFS._call hands each kernel request to (fuse/fs.py:105-108, which waits at bridge/sync.py:72-77). A local runtime started with its working directory on the mount would block in Popen's exec handshake on that loop while the child's chdir waits on FUSE (runtime/sandbox/program.py:237-250). Avoiding both needs a dedicated loop thread per workspace, with every async API hopping onto it: a change of its own. Table operations outside the capacity path (listings, reads, attribute changes) are not taken under the lock and behave as on main.

	Before this PR (main)	One loop per workspace (not chosen)	After this PR
Where FUSE and NFS serve	private loop threads	the workspace's loop	private loop threads, unchanged
What makes a capacity check atomic	— (no capacity)	one thread touches the ledger	one threading.Lock per counted store
Cost	—	about 1,400–2,000 lines for the caller's-loop form, estimated from its file list; the dedicated-loop-thread form that avoids the deadlocks is larger	about 40 lines in Python (store_change is 28 of them); none in TypeScript. At run time, a capped pwrite or publish copies the file's bytes while it holds the lock, as it copied them before this change
Risk	—	the two deadlocks above, traced from the code, if served on the caller's loop	a writer on another thread waits while the lock is held, longest during a store's first count or an admitted large allocation; stores nobody caps take no lock

How the lock is held: store_change (core/ram/usage.py) takes the counted store's StorageUsage.lock, re-checks under it that the store still holds that usage (a cap released or replaced while it waited is retried against the current usage, or the uncapped path), counts the table if it is uncounted, and yields; the block admits and charges before it changes the table. A block that raises past its charge marks the usage uncounted. After the block, a usage that appeared or changed while it ran is marked uncounted under its own lock, never while holding another, so the next counted operation recounts. TypeScript runs every callback on one thread, so its storeChange has no lock and no re-read.

Bounded landings

Counted but not admitted, each bounded, with later growth refused once it lands: a stream's pad back up to its position after another op shortens its file mid-stream (at most the stream's own earlier output); chunks a stream buffered before its store gained a usage (at most one publish window); and operations in flight when a store's usage appears, goes or is replaced, which land under the usage they started with and leave the current one to be recounted.

The other way round, one refusal is stricter than the bytes need: a replacing stream reserves each chunk's full length, because the file can change before the chunk lands. If another writer refills that file after the stream emptied it, a chunk that would only overwrite those bytes counts as growth, and at the exact cap it is refused. It takes two writers on one file at once; across 23,503 recorded agent shell lines, the only such shape is a background job relaunched onto the same log file (14 lines).

Decisions

• /dev is refused a capacity by class: DevVFS inherits the name ram, so a name check alone would let it through. It follows read_policy's isinstance(vfs, DevVFS); the message still names dev.
• Python's construction releases every cap it bound on any failure from placing the mounts on, its own /usr/bin and history mounts included.
• A length change that is not a whole, non-negative number of bytes is EINVAL before anything is charged, as ftruncate(2) answers.
• RAMAccessor keeps only the owner that counts its store; nothing reads the owners of uncapped mounts.
• An uncapped mount does not bind a usage: for RAM it shares the capped mount's accessor, so a bind changes nothing. Disk, where two accessors can reach one folder, will bind it.
• A publish lands the bytes it held in a finally, so a publish that fails cannot leave them in pending.
• TypeScript binds its constructor's mounts once the workspace is built, so a construction that fails earlier (a bad CLI, a bad secrets block) binds nothing. Python binds as it places each mount and releases on every failure path.
• A placement refused after its bind, by the bind itself (mount '/x/': this RAM store is counted by another workspace; ..., a CapacityError) or by a later step such as a walk_limit conflict, releases the cap it bound.
• vfs_storage_location lives in the registry, which keys the ledger by it; workspace/mount/storage imports the registry, so it takes the function from there.
• A cross-workspace refusal and a bad size name the mount by its normalized prefix (mount '/x/': ...), as the write-policy refusals do.

Tests

Unit tests on both hosts for every error table, the size grammar, StorageUsage, the ledger and capability, every RAM mutator (charge, refusal leaving the table unchanged, shrinking over the cap, sparse pwrite/truncate refused before the bytes are built, streams), every door, alias and nested topologies, release on unmount/close/failed construction/failed load, snapshots (an uncapped alias still counts against the cap after copy() and a load) and df/stat -f. Python adds lock tests on real threads: a second writer waits for the first one's locked block, a timer publish takes the lock, an inline publish runs outside it, usage bound or replaced mid-write is recounted, a writer waiting on a released usage takes the uncapped path, a failure past the charge leaves the usage uncounted, and load_state swaps and marks in one section.

Integration: 13 shell cases in integ/unix/capacity/, each on a workspace opened for that case alone (mount_capacity, capacity_door: open|load), on both runners; integ/runtime/write/capacity.json for a Monty guest; four FUSE probe keys (a kernel write refused with EDQUOT, the file left empty, and a shell write counting the kernel's bytes on the same store).

GNU

Pinned in debian:stable-slim (GNU coreutils 9.7): echo hi > /dev/full; echo $?; echo next prints bash: line 1: echo: write error: No space left on device, then 1 and next. Mirage keeps its redirect voice (/data2/b: Disk quota exceeded); the exit status and the line going on match. GNU cp reports a failed write as error writing; mirage's cp says cannot create regular file for any write failure, which predates this change.

Not in this PR

Disk capacity (a follow-up: per-file windows across loops, a folder walk to count, recounts after native writes). Memory and workspace-wide quotas.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[High impact] The changes since the last review appear safe to merge.

Summary

Adds byte caps to RAM, disk, Redis, and OPFS stores. Writes past the cap return EDQUOT, and snapshots keep each store’s cap.

• Capped stores stop growing when a write would pass their byte limit.
• Quota refusals reach shell commands, guest runtimes, and HTTP callers.
• Capacity settings follow mounts through workspace setup, aliases, and snapshots.
• Size settings now use the same strict byte format in Python and TypeScript.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Write to a store] --> B{Store capped?}
  B -->|No| E[Write bytes]
  B -->|Yes| C[Check and reserve growth]
  C --> D{Fits the cap?}
  D -->|No| F[Return EDQUOT]
  D -->|Yes| E
  E --> G[Update the stored-byte count]
  G --> H[Release reserved bytes]

Loading

_{Reviews (10) · Last reviewed commit: "fix(capacity): a replacement loses its c..." · Reviewed by Greptile}

[zechengz]

I pushed a follow-up commit, 32a83e7, that reworks how capacity is set. In short, capacity is now a setting on the store, like tmpfs size=, instead of a setting on the mount.

User interface

Where you set it

	Before (this PR)	Now
YAML	capacity: 100MB on the mount block	capacity: 100MB under the mount's config
Python	Mount(vfs, capacity="100MB"), add_mount(..., capacity=)	RAMVFS(capacity="100MB"), DiskVFS(root=..., capacity="1GB"), RedisVFS(url=..., capacity="100MB")
TypeScript	new Mount(vfs, { capacity }), addMount(..., { capacity })	new RAMVFS({ capacity: '100MB' }), new DiskVFS({ root, capacity }), new RedisVFS({ url, capacity }), new OPFSVFS({ root, capacity })
Server clone or load override, dsh mount block	took capacity	no capacity key; the override's own config carries it
Backends	RAM only	RAM, disk, Redis, and OPFS in the browser

mounts:
  /data:
    vfs: ram
    mode: write
    config:
      capacity: 100MB

ws = Workspace({"/data": RAMVFS(capacity="100MB")}, mode=MountMode.WRITE)

const ws = new Workspace({ '/data': new RAMVFS({ capacity: '100MB' }) }, { mode: MountMode.WRITE })

No capacity means no cap, as before.

What a user sees

• Unchanged:
  • A write past the cap fails with EDQUOT, "Disk quota exceeded", and the rest of the line still runs.
  • The HTTP status is still 507.
  • echo and printf are still all or nothing, and seq keeps what it wrote before the refusal.
  • A store already over its cap keeps its data. Reads, removals and shrinking writes still work.
  • df and stat -f show the cap as the store's size.
• Mounting no longer changes the cap. Mounting, unmounting and add_mount leave it alone. Every mount of one store shares its cap, because the cap belongs to the store.
• Sizes use one parser. capacity goes through the same size parser as cache.limit and a runtime's max_memory: 4096, 512K, 100MB, 1g, with binary units. configuration.mdx has one Sizes section that all three link to.
• Snapshots keep the cap in the store's config, so loading a snapshot rebuilds it with no special case. An override brings its own capacity, or none.
• Disk counts the folder at the first write or the first df. It counts again after a write from outside mirage, such as a native program, and on every df.

Known limitations (documented)

• In Python, a store with a capacity can't yet be exposed through FUSE or FSKit. Trying it fails with mount '/data/': a store with a capacity cannot be served over fuse yet.
  • The reason: Python FUSE serves from an event loop of its own, and the check-then-write is only safe on one loop.
  • NFS is read-only, so it is allowed.
  • TypeScript has one loop, so it is not affected.
• Each workspace counts its own writes. Two workspaces on one disk folder, Redis key prefix or OPFS directory can together store more than the cap.

How it works now

• No locks and no new threads. StorageUsage (limit, used, pending) is synchronous. Each check runs in the same step on the event loop as the change it guards, so parallel writers in one workspace can't both take the last free bytes. A smoke test with 2 bytes free and 20 parallel one-byte writes landed exactly 2, on RAM, disk and Redis.
• Removed:
  • The per-workspace ledger.
  • store_change and its threading.Lock.
  • workspace/mount/capacity and core/ram/usage.
  • The mount-level cap, along with binding and releasing it on unmount, close and failed construction.
• RAM keeps its file table counted (RAMFiles), so it never needs a recount. Streams hold bytes before a chunk is written and land them after.
• Disk, Redis and OPFS share one charge() helper. It reserves the growth before the write and records the real size after it.
• Both languages move together. The layout, symbol, barrel, cycle and spec parity gates pass.

Docs

• configuration.mdx has a ## Capacity section.
• The RAM, disk and Redis setup pages each have one line pointing to it.
• The HTTP 507 row now says "store".
• The in-app snapshot paragraphs are split into short bullets.
• The dsh mount block lists vfs, mode and config.