@muhkoo/connect 0.14.0-alpha.8 → 0.14.0-alpha.9

package/dist/browser/index.js

@@ -1127,7 +1127,7 @@ const AES_GCM_KEY_BYTES = 32;
 /** Length of the AES-GCM IV in bytes (WebCrypto-recommended). */
 const AES_GCM_IV_BYTES$1 = 12;
 /** Length of the AES-GCM authentication tag in bytes (appended to ciphertext). */
-const AES_GCM_TAG_BYTES = 16;
+const AES_GCM_TAG_BYTES$1 = 16;
 /**
  * Encrypt `plaintext` under a 32-byte AES-256 key with the supplied 12-byte
  * IV. Returns ciphertext with the 16-byte GCM tag appended (so the output
@@ -6481,7 +6481,7 @@ async function parseOrThrow(response, op) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.14.0-alpha.8";
+const VERSION = "0.14.0-alpha.9";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -12506,6 +12506,171 @@ class AccessTokensNamespace {
     }
 }
 
+/**
+ * Absolute POSIX paths for the VFS.
+ *
+ * A path is a lookup route, not a stored value: nothing in the metadata records
+ * a full path, only a name inside its parent directory. That is what makes
+ * renaming or moving a directory a single-record edit instead of a rewrite of
+ * every descendant.
+ */
+/** Absolute, single leading slash, no `.` / `..`, no trailing slash. Root is `/`. */
+function normalizePath(input) {
+    const out = [];
+    for (const part of input.split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..")
+            out.pop();
+        else
+            out.push(part);
+    }
+    return "/" + out.join("/");
+}
+/** Path split into its segments. `/` yields `[]`. */
+function segments(path) {
+    return normalizePath(path).split("/").filter(Boolean);
+}
+/**
+ * Resolve `path` against a working directory, POSIX-style.
+ *
+ * An absolute path ignores the cwd; a relative one hangs off it; `..` climbs
+ * and stops at the root rather than escaping it. This is the single place
+ * relativity is interpreted, so every VFS method behaves the same way — a
+ * filesystem where `cat a.txt` and `list("a")` disagreed about what "here"
+ * means would be worse than having no cwd at all.
+ */
+function resolveFrom(cwd, path) {
+    if (path.startsWith("/"))
+        return normalizePath(path);
+    return normalizePath(`${cwd}/${path}`);
+}
+function dirname(path) {
+    const p = normalizePath(path);
+    const i = p.lastIndexOf("/");
+    return i <= 0 ? "/" : p.slice(0, i);
+}
+function basename(path) {
+    const p = normalizePath(path);
+    return p.slice(p.lastIndexOf("/") + 1);
+}
+function join(...parts) {
+    return normalizePath(parts.join("/"));
+}
+/**
+ * Is `path` inside `dir` (at any depth)? A directory is never "under" itself,
+ * which is what makes it usable as the guard against moving a directory into
+ * its own subtree.
+ */
+function isUnder(path, dir) {
+    const p = normalizePath(path);
+    const d = normalizePath(dir);
+    if (p === d)
+        return false;
+    return d === "/" ? true : p.startsWith(d + "/");
+}
+/**
+ * Reject names that would make a path ambiguous or unrepresentable.
+ *
+ * `/` would forge a nesting level, and `.` / `..` would resolve to a different
+ * directory on the next lookup — a file literally named `..` could never be
+ * addressed again.
+ */
+/** The longest a single entry name may be. Matches the common filesystem limit. */
+const MAX_NAME_BYTES = 255;
+/**
+ * Control characters, C1 controls and bidi overrides.
+ *
+ * Built once, not per call: `isSafeName` runs for every entry of every
+ * record read.
+ */
+const CONTROL_OR_BIDI = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
+const CONTROL_OR_BIDI_ALL = new RegExp(CONTROL_OR_BIDI.source, "g");
+const utf8 = new TextEncoder();
+/**
+ * A string from a record, made fit to print: cut to `max` characters, then
+ * every control or bidi character written as a `\uXXXX` escape.
+ *
+ * For values that end up in an error message or a warning - a record id, a
+ * format version. The CLI prints messages as they are, so a raw escape
+ * sequence there would run in the user's terminal: clear lines, rewrite
+ * what was printed above it, or set the clipboard. Names do not need this;
+ * `isSafeName` refuses them outright.
+ */
+function printable(value, max = Infinity) {
+    const cut = value.length > max ? `${value.slice(0, max)}...` : value;
+    return cut.replace(CONTROL_OR_BIDI_ALL, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+/**
+ * Is this a name we are willing to store, and to hand back as a path segment?
+ *
+ * This is the READ-side check as much as the write-side one, and the read side
+ * is the one that matters: a directory record is sealed with a key that any
+ * holder of the master seed can derive, so its contents are not necessarily
+ * something this SDK wrote. A name arriving from a record is input.
+ *
+ * What each rule is for:
+ *  - `/` and backslash would become path structure. Backslash is a separator on
+ *    Windows, which makes it traversal there and an odd filename elsewhere.
+ *  - `.` and `..` navigate rather than name.
+ *  - NUL terminates a path in every syscall that takes one.
+ *  - Other control characters and bidi overrides let a name print as something
+ *    other than what it is - the classic way a file passes review.
+ *  - A length cap, because nothing else imposes one.
+ */
+function isSafeName(name) {
+    if (!name || name === "." || name === "..")
+        return false;
+    if (name.includes("/") || name.includes(String.fromCharCode(92)))
+        return false;
+    if (CONTROL_OR_BIDI.test(name))
+        return false;
+    return utf8.encode(name).length <= MAX_NAME_BYTES;
+}
+function assertValidName(name) {
+    if (!name)
+        throw new Error("VFS: name cannot be empty");
+    if (!isSafeName(name))
+        throw new Error(`VFS: ${JSON.stringify(name)} is not a usable name`);
+}
+/**
+ * MIME type for a filename.
+ *
+ * Stored with the content rather than guessed at read time, because whatever
+ * eventually serves these bytes — a preview, a static host — sends this as the
+ * `Content-Type`, and a browser will refuse to run a module or apply a
+ * stylesheet labelled `application/octet-stream`.
+ */
+function contentTypeFor(name) {
+    const ext = name.slice(name.lastIndexOf(".") + 1).toLowerCase();
+    switch (ext) {
+        case "html":
+        case "htm": return "text/html; charset=utf-8";
+        case "css": return "text/css; charset=utf-8";
+        case "js":
+        case "mjs":
+        case "jsx": return "text/javascript; charset=utf-8";
+        case "ts":
+        case "tsx": return "text/typescript; charset=utf-8";
+        case "json": return "application/json; charset=utf-8";
+        case "md": return "text/markdown; charset=utf-8";
+        case "txt": return "text/plain; charset=utf-8";
+        case "svg": return "image/svg+xml";
+        case "png": return "image/png";
+        case "jpg":
+        case "jpeg": return "image/jpeg";
+        case "gif": return "image/gif";
+        case "webp": return "image/webp";
+        case "avif": return "image/avif";
+        case "ico": return "image/x-icon";
+        case "woff2": return "font/woff2";
+        case "woff": return "font/woff";
+        case "wasm": return "application/wasm";
+        case "map": return "application/json";
+        default: return "application/octet-stream";
+    }
+}
+
 /**
  * Wire types for the VFS metadata layer.
  *
@@ -12576,6 +12741,92 @@ class VfsConflictError extends Error {
         this.name = "VfsConflictError";
     }
 }
+/**
+ * Raised when a directory record cannot be read: it does not decrypt or parse
+ * with the key its parent holds, or it does but is not a shape this SDK can
+ * read - not an object, a version other than 1, `entries` missing or not a map.
+ *
+ * Thrown, never read as an empty directory. The next write into an "empty"
+ * directory would seal an empty record over the real one, and a record this
+ * version cannot read may simply be one a NEWER version wrote. Nor is the
+ * directory skipped: a sync that cannot see a subtree reads its absence as a
+ * deletion. The record is left exactly as stored; a recursive delete
+ * (`delete(path, { recursive: true })`) detaches it when the user wants it
+ * gone.
+ */
+class VfsCorruptRecordError extends Error {
+    /** The record's id - `dirKey(id)` is where it is stored. */
+    id;
+    /** The path it was reached through, when known. A moved subtree can have two. */
+    path;
+    constructor(id, path, reason) {
+        // The id comes out of a parent entry, which anything holding the seed
+        // can write. It is kept raw on `.id` for code, and escaped here for the
+        // terminal a CLI prints this to. `reason` is built by this SDK.
+        const where = `${printable(path ?? "a directory")} (record ${printable(id, 40)})`;
+        // The root has no parent to be detached from; advising a delete that
+        // is refused would leave the user with nothing that works.
+        const remedy = id === ROOT_ID
+            ? "It is the root of this filesystem, so it cannot be deleted; nothing has been changed."
+            : "It has been left as stored; remove it with a recursive delete.";
+        super(`VFS: ${where} cannot be read: ${reason}. ${remedy}`);
+        this.name = "VfsCorruptRecordError";
+        this.id = id;
+        this.path = path;
+    }
+}
+/**
+ * Raised when a walk or a copy would go past a size or depth ceiling, or a
+ * write would put a directory deeper than a walk reads.
+ *
+ * Thrown rather than returning what was gathered so far, because every caller
+ * of a walk treats a path that is missing from the result as a path that does
+ * not exist - and a sync then plans a deletion for it. A tree this large or
+ * deep is almost always one built to be expensive to read: directory records
+ * can point at the same directory many times over, so a handful of tiny
+ * records can describe more paths than there are atoms.
+ */
+class VfsLimitError extends Error {
+    /**
+     * Which ceiling was hit: total entries, total characters of path text,
+     * nesting depth, or - for a copy - how many places one directory may
+     * appear. Entries alone do not bound memory - a name may be 255 bytes, so
+     * one path can be ~16KB - which is why path text has its own.
+     */
+    limit;
+    /** The ceiling itself. */
+    max;
+    /** Where the operation started, or for a write what it was asked to write. */
+    path;
+    /**
+     * Where the ceiling was reached: the directory being listed, or for depth
+     * the entry one level too deep. Walking the tree to find the culprit would
+     * hit the same ceiling, so this is the only pointer the caller gets.
+     */
+    at;
+    constructor(limit, max, path, at, doing = "walking") {
+        const what = {
+            entries: `it holds more than ${max} entries`,
+            pathChars: `its paths add up to more than ${max} characters`,
+            depth: `it is nested more than ${max} directories deep`,
+            shared: `one directory appears in it more than ${max} times`,
+        }[limit];
+        // The location is made of names that passed isSafeName, so it is safe
+        // to print; it is shortened only because a deep one can run to 16KB.
+        // Worded for whoever reads it - a CLI prints it as it is - rather than
+        // in terms of the SDK call.
+        const shown = at.length > 200 ? `${at.slice(0, 200)}...` : at;
+        const remedy = doing === "writing"
+            ? ""
+            : " If you do not recognise what is there, remove it with a recursive delete.";
+        super(`VFS: stopped ${doing} ${path}: ${what} (reached at ${shown}).${remedy}`);
+        this.name = "VfsLimitError";
+        this.limit = limit;
+        this.max = max;
+        this.path = path;
+        this.at = at;
+    }
+}
 
 /**
  * Sealing for VFS metadata records.
@@ -12587,6 +12838,8 @@ class VfsConflictError extends Error {
  * record would hand over the keys to its files.
  */
 const AES_GCM_IV_BYTES = 12;
+/** The GCM tag appended to every ciphertext, so the shortest one there can be. */
+const AES_GCM_TAG_BYTES = 16;
 const AES_KEY_BYTES = 32;
 function toBase64(bytes) {
     let s = "";
@@ -12651,157 +12904,70 @@ async function unseal(key, record) {
     const plaintext = await decryptAesGcm(key, fromBase64(r.iv), fromBase64(r.ct));
     return JSON.parse(new TextDecoder().decode(plaintext));
 }
-
-/**
- * Absolute POSIX paths for the VFS.
- *
- * A path is a lookup route, not a stored value: nothing in the metadata records
- * a full path, only a name inside its parent directory. That is what makes
- * renaming or moving a directory a single-record edit instead of a rewrite of
- * every descendant.
- */
-/** Absolute, single leading slash, no `.` / `..`, no trailing slash. Root is `/`. */
-function normalizePath(input) {
-    const out = [];
-    for (const part of input.split("/")) {
-        if (part === "" || part === ".")
-            continue;
-        if (part === "..")
-            out.pop();
-        else
-            out.push(part);
+/** Raised by `openSealed` when the stored value itself is at fault. `message` says how. */
+class SealedRecordError extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = "SealedRecordError";
     }
-    return "/" + out.join("/");
-}
-/** Path split into its segments. `/` yields `[]`. */
-function segments(path) {
-    return normalizePath(path).split("/").filter(Boolean);
 }
 /**
- * Resolve `path` against a working directory, POSIX-style.
+ * `unseal` for a record that must not be guessed at.
  *
- * An absolute path ignores the cwd; a relative one hangs off it; `..` climbs
- * and stops at the root rather than escaping it. This is the single place
- * relativity is interpreted, so every VFS method behaves the same way — a
- * filesystem where `cat a.txt` and `list("a")` disagreed about what "here"
- * means would be worse than having no cwd at all.
- */
-function resolveFrom(cwd, path) {
-    if (path.startsWith("/"))
-        return normalizePath(path);
-    return normalizePath(`${cwd}/${path}`);
-}
-function dirname(path) {
-    const p = normalizePath(path);
-    const i = p.lastIndexOf("/");
-    return i <= 0 ? "/" : p.slice(0, i);
-}
-function basename(path) {
-    const p = normalizePath(path);
-    return p.slice(p.lastIndexOf("/") + 1);
-}
-function join(...parts) {
-    return normalizePath(parts.join("/"));
-}
-/**
- * Is `path` inside `dir` (at any depth)? A directory is never "under" itself,
- * which is what makes it usable as the guard against moving a directory into
- * its own subtree.
+ * Throws SealedRecordError for everything that is wrong WITH THE STORED VALUE:
+ * not an envelope, not base64, the wrong size, a ciphertext that does not
+ * authenticate under `key`, plaintext that is not JSON. Every one of those
+ * surfaced before as a bare DOMException or SyntaxError naming nothing.
+ *
+ * Anything else - no WebCrypto in this runtime, say - is rethrown untouched.
+ * Blaming the record for a failure of the runtime would tell the user a
+ * healthy directory is corrupt, and invite them to delete it.
  */
-function isUnder(path, dir) {
-    const p = normalizePath(path);
-    const d = normalizePath(dir);
-    if (p === d)
-        return false;
-    return d === "/" ? true : p.startsWith(d + "/");
+async function openSealed(key, record) {
+    const r = record;
+    if (!r || typeof r !== "object" || Array.isArray(r) || typeof r.iv !== "string" || typeof r.ct !== "string") {
+        throw new SealedRecordError("it is not a sealed record");
+    }
+    let iv;
+    let ct;
+    try {
+        iv = fromBase64(r.iv);
+        ct = fromBase64(r.ct);
+    }
+    catch {
+        throw new SealedRecordError("its envelope is not base64");
+    }
+    // Checked here rather than left to the cipher, whose complaints about
+    // either are indistinguishable from its complaints about the runtime.
+    if (iv.length !== AES_GCM_IV_BYTES || ct.length < AES_GCM_TAG_BYTES) {
+        throw new SealedRecordError("its envelope is the wrong size");
+    }
+    let plaintext;
+    try {
+        plaintext = await decryptAesGcm(key, iv, ct);
+    }
+    catch (err) {
+        // What the WebCrypto spec requires for a tag that does not verify:
+        // a different key, or bytes that were altered.
+        if (err?.name !== "OperationError")
+            throw err;
+        throw new SealedRecordError("it does not decrypt with the key it should");
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(plaintext));
+    }
+    catch {
+        throw new SealedRecordError("it decrypts, but not to a record");
+    }
 }
+
 /**
- * Reject names that would make a path ambiguous or unrepresentable.
+ * Glob matching for VFS paths.
  *
- * `/` would forge a nesting level, and `.` / `..` would resolve to a different
- * directory on the next lookup — a file literally named `..` could never be
- * addressed again.
- */
-/** The longest a single entry name may be. Matches the common filesystem limit. */
-const MAX_NAME_BYTES = 255;
-/**
- * Is this a name we are willing to store, and to hand back as a path segment?
- *
- * This is the READ-side check as much as the write-side one, and the read side
- * is the one that matters: a directory record is sealed with a key that any
- * holder of the master seed can derive, so its contents are not necessarily
- * something this SDK wrote. A name arriving from a record is input.
- *
- * What each rule is for:
- *  - `/` and backslash would become path structure. Backslash is a separator on
- *    Windows, which makes it traversal there and an odd filename elsewhere.
- *  - `.` and `..` navigate rather than name.
- *  - NUL terminates a path in every syscall that takes one.
- *  - Other control characters and bidi overrides let a name print as something
- *    other than what it is - the classic way a file passes review.
- *  - A length cap, because nothing else imposes one.
- */
-function isSafeName(name) {
-    if (!name || name === "." || name === "..")
-        return false;
-    if (name.includes("/") || name.includes(String.fromCharCode(92)))
-        return false;
-    const CONTROL_OR_BIDI = new RegExp("[\\u0000-\\u001f\\u007f-\\u009f\\u202a-\\u202e\\u2066-\\u2069]");
-    if (CONTROL_OR_BIDI.test(name))
-        return false;
-    return new TextEncoder().encode(name).length <= MAX_NAME_BYTES;
-}
-function assertValidName(name) {
-    if (!name)
-        throw new Error("VFS: name cannot be empty");
-    if (!isSafeName(name))
-        throw new Error(`VFS: ${JSON.stringify(name)} is not a usable name`);
-}
-/**
- * MIME type for a filename.
- *
- * Stored with the content rather than guessed at read time, because whatever
- * eventually serves these bytes — a preview, a static host — sends this as the
- * `Content-Type`, and a browser will refuse to run a module or apply a
- * stylesheet labelled `application/octet-stream`.
- */
-function contentTypeFor(name) {
-    const ext = name.slice(name.lastIndexOf(".") + 1).toLowerCase();
-    switch (ext) {
-        case "html":
-        case "htm": return "text/html; charset=utf-8";
-        case "css": return "text/css; charset=utf-8";
-        case "js":
-        case "mjs":
-        case "jsx": return "text/javascript; charset=utf-8";
-        case "ts":
-        case "tsx": return "text/typescript; charset=utf-8";
-        case "json": return "application/json; charset=utf-8";
-        case "md": return "text/markdown; charset=utf-8";
-        case "txt": return "text/plain; charset=utf-8";
-        case "svg": return "image/svg+xml";
-        case "png": return "image/png";
-        case "jpg":
-        case "jpeg": return "image/jpeg";
-        case "gif": return "image/gif";
-        case "webp": return "image/webp";
-        case "avif": return "image/avif";
-        case "ico": return "image/x-icon";
-        case "woff2": return "font/woff2";
-        case "woff": return "font/woff";
-        case "wasm": return "application/wasm";
-        case "map": return "application/json";
-        default: return "application/octet-stream";
-    }
-}
-
-/**
- * Glob matching for VFS paths.
- *
- * A deliberately small dialect — `*`, `**`, `?`, and `{a,b}` — because these
- * cover what a project actually asks for (`**\/*.tsx`, `src/*.css`) and every
- * addition beyond them is a new way for a pattern to mean something the caller
- * did not expect.
+ * A deliberately small dialect — `*`, `**`, `?`, and `{a,b}` — because these
+ * cover what a project actually asks for (`**\/*.tsx`, `src/*.css`) and every
+ * addition beyond them is a new way for a pattern to mean something the caller
+ * did not expect.
  */
 /** `*` stops at a separator; `**` crosses them. That distinction is the whole point. */
 function globToRegExp(pattern) {
@@ -12848,6 +13014,118 @@ function escapeLiteral(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Bounds shared by the VFS walkers and version control's history walks.
+ *
+ * Internal: `src/api.ts` re-exports everything in `VfsNamespace.ts`, and none
+ * of this is public API.
+ */
+/**
+ * How deep a tree may be before a walk refuses it, counted in directories
+ * below where the walk starts - and how deep, counted from the root, any
+ * directory may be written.
+ *
+ * Well past anything a real project needs. Refusing means THROWING a
+ * VfsLimitError: this used to stop quietly and return the shallower part,
+ * which a sync reads as "everything deeper was deleted". Writes are held to it
+ * from the root so that no walk, from anywhere, is refused a tree this SDK
+ * wrote; version control holds a checkout to it too.
+ */
+const MAX_DEPTH = 64;
+/**
+ * The most entries one walk, copy or read of history may visit, unless the
+ * namespace was constructed with other limits.
+ *
+ * A cycle guard cannot bound a walk on its own: records can name the same
+ * directory twice without any cycle (D0 -> {a, b} -> D1 -> {a, b} -> ...), and
+ * every level doubles the paths - sixty-four levels of that is 2^64 paths from
+ * sixty-four tiny records. Repository trees are the same: every hash can be
+ * genuine and each level still double the paths. A tree past the budget is
+ * thrown on rather than half-read.
+ *
+ * Half a million is a very large real project. It was a million, which fits
+ * one walk in a 512MB heap, but `vcs status` holds a commit's paths and the
+ * working tree's changes at once, both chosen by whoever planted them: two
+ * sides of a million, every path a change, is two million paths of output,
+ * and ended within 9MB of a 512MB heap even compared as it was walked.
+ */
+const DEFAULT_MAX_ENTRIES = 500_000;
+/**
+ * The most characters of path text one walk or read of history may produce,
+ * summed over its paths.
+ *
+ * The entry budget alone does not bound memory, because the attacker chooses
+ * how big each entry is: a name may be 255 bytes and a tree 64 levels deep, so
+ * one path can be ~16KB, and every path is its own string. Forty-odd small
+ * records of long names stayed under the entry budget and still asked for
+ * ~11GB. This allows an average of 64 characters a path at the entry
+ * ceiling - 32MB of text, or 64MB in names a JS engine stores two bytes a
+ * character - which a real project reaches only if it is near that ceiling
+ * anyway.
+ */
+const DEFAULT_MAX_PATH_CHARS = 64 * DEFAULT_MAX_ENTRIES;
+/** The furthest from 1970, either way, a Date can be, in milliseconds. */
+const MAX_TIME = 8.64e15;
+/**
+ * Directory records one walk fetches at once - in TOTAL, not per directory.
+ *
+ * Sized for the network, not for memory. What ran a walk out of memory was
+ * in-flight VISITS over cached records, and the walk now visits one
+ * directory at a time; this bounds FETCHES, each holding at most one record -
+ * 128MB sealed if all 64 are as big as a Durable Object value may be. Every
+ * get is its own request, and a cold walk of D directories costs at least
+ * D / WALK_CONCURRENCY round trips on top of one per level: at 30ms a get, a
+ * 333-directory project took 1.46s with 8, 0.49s with 32 and 0.37s with 64,
+ * against 0.25s for the old walk, which had up to 225 gets in flight on the
+ * same tree. Separate from FileStorage's shard concurrency, which it once
+ * matched: shards are batched, and records are not.
+ */
+const WALK_CONCURRENCY = 64;
+/**
+ * How many entries a walk visits between turns of the event loop.
+ *
+ * Once its records are cached a walk never waits on anything, and a chain of
+ * promise continuations runs to the end before any timer, input event or
+ * signal handler is let in. A few hundred thousand entries is seconds of that:
+ * a frozen tab, or a `vfs mount` that ignores Ctrl-C. Each turn costs a
+ * fraction of a millisecond, which at this spacing a real project never
+ * notices. Version control's history walks use it too.
+ */
+const YIELD_EVERY = 8192;
+/**
+ * Let the event loop run - timers, I/O, input, signal handlers - before
+ * carrying on.
+ *
+ * `setImmediate` is Node's turn of the loop, and a MessageChannel message is
+ * a browser's: a task queued behind whatever is already waiting, which is
+ * the point. Not `scheduler.yield()`, although Chromium has it: its
+ * continuation is scheduled AHEAD of tasks already queued at the same
+ * priority, and timers, postMessage and socket messages are such tasks - a
+ * cached walk yielding through it gave a 1ms interval no ticks in 2s. And a
+ * bare `setTimeout(0)` only when there is nothing else: a browser clamps a
+ * timer set from inside another to 4ms, and in a hidden tab runs it about
+ * once a second, or once a minute after five minutes hidden.
+ *
+ * In Node a MessagePort with a listener would also keep the process alive,
+ * which is one more reason `setImmediate` comes first.
+ */
+function nextTurn() {
+    const g = globalThis;
+    if (typeof g.setImmediate === "function")
+        return new Promise((resolve) => g.setImmediate(resolve));
+    if (typeof MessageChannel === "function") {
+        return new Promise((resolve) => {
+            const channel = new MessageChannel();
+            channel.port1.onmessage = () => {
+                channel.port1.close();
+                resolve();
+            };
+            channel.port2.postMessage(null);
+        });
+    }
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
 /**
  * `client.vfs` — a real filesystem over Muhkoo primitives.
  *
@@ -12867,47 +13145,365 @@ function escapeLiteral(s) {
  * cost storage until a future sweep, which is the trade this shape makes in
  * exchange for single-record writes.
  */
+/** Refuse a directory at `path` if it would be deeper than MAX_DEPTH from the root. */
+function assertWritableDepth(path) {
+    const parts = segments(path);
+    if (parts.length <= MAX_DEPTH)
+        return;
+    throw new VfsLimitError("depth", MAX_DEPTH, path, `/${parts.slice(0, MAX_DEPTH + 1).join("/")}`, "writing");
+}
+const DEFAULT_HISTORY_LIMIT = 20;
 /**
- * How deep a tree may be before we stop walking it.
+ * The one pool of record fetches a walk has, `limit` wide.
+ *
+ * The walk itself visits one directory at a time, so it never holds more than
+ * its current path. What keeps a real tree from being listed one round trip at
+ * a time is reading ahead: every record the walk opens, and every record read
+ * ahead, is scanned ONCE for subdirectories not yet fetched, and those are
+ * fetched while the walk works. The most recently opened record is scanned
+ * first, which is roughly the order a depth-first walk wants them in.
+ *
+ * What it holds is per distinct RECORD - a record scanned, a read that failed
+ * - never per visit, so a record a fan-out reaches a million times costs it
+ * one entry. The walk's own reads come out of the same pool, and go first:
+ * when every slot is reading ahead, the walk takes the next one to come free.
+ * A successful read lands in the namespace's record cache, which is where the
+ * walk looks when it gets there.
+ */
+class ReadAhead {
+    limit;
+    list;
+    cached;
+    fetch;
+    inFlight = 0;
+    stopped = false;
+    /** The walk, waiting for a slot. It reads one directory at a time, so there is only ever one. */
+    waiting = null;
+    /** Records whose subdirectories are still to be looked at, the most recently opened last. */
+    toScan = [];
+    /** Every record scanned so far, so none is scanned twice. */
+    scanned = new Set();
+    /**
+     * Reads ahead that failed. The cache forgets a failed read so that one
+     * blip does not poison a directory for the session; kept here, the walk
+     * reports the failure when it gets there instead of asking again.
+     */
+    failed = new Map();
+    constructor(limit, list, cached, fetch) {
+        this.limit = limit;
+        this.list = list;
+        this.cached = cached;
+        this.fetch = fetch;
+    }
+    /** A record the walk has opened. `children` is its listing, when the walk already has one. */
+    scan(dir, path, children) {
+        this.queue(dir, path, children);
+        this.fill();
+    }
+    /** The walk is over, however it ended: start nothing more. */
+    stop() {
+        this.stopped = true;
+        this.toScan.length = 0;
+    }
+    /** The record the walk needs now: read ahead already, or fetched in the next free slot. */
+    async open(entry, path) {
+        const failed = this.failed.get(entry.id);
+        if (failed)
+            return failed;
+        if (this.cached(entry.id))
+            return this.fetch(entry, path);
+        if (this.inFlight < this.limit)
+            return this.start(entry, path);
+        // Every slot is reading ahead. The next one to come free is handed to
+        // the walk rather than to more reading ahead.
+        await new Promise((resolve) => (this.waiting = resolve));
+        if (!this.cached(entry.id))
+            return this.start(entry, path, true);
+        // Read ahead in the meantime after all: give the slot back.
+        this.inFlight--;
+        this.fill();
+        return this.fetch(entry, path);
+    }
+    queue(dir, path, children) {
+        if (this.stopped || this.scanned.has(dir.id))
+            return;
+        this.scanned.add(dir.id);
+        this.toScan.push({ path, children: children ?? this.list(dir), next: 0 });
+    }
+    /** `held`: the slot was handed over, and is already counted. */
+    start(entry, path, held = false) {
+        if (!held)
+            this.inFlight++;
+        const pending = this.fetch(entry, path);
+        pending.then((dir) => {
+            this.queue(dir, path);
+            this.release();
+        }, () => {
+            this.failed.set(entry.id, pending);
+            this.release();
+        });
+        return pending;
+    }
+    release() {
+        const walk = this.waiting;
+        if (walk) {
+            this.waiting = null;
+            walk(); // the slot passes to the walk, still counted
+            return;
+        }
+        this.inFlight--;
+        this.fill();
+    }
+    fill() {
+        while (!this.stopped && this.inFlight < this.limit) {
+            const top = this.toScan[this.toScan.length - 1];
+            if (!top)
+                return;
+            if (top.next >= top.children.length) {
+                this.toScan.pop();
+                continue;
+            }
+            const { name, entry } = top.children[top.next++];
+            if (entry.kind !== "dir" || this.cached(entry.id) || this.failed.has(entry.id))
+                continue;
+            void this.start(entry, join(top.path, name));
+        }
+    }
+}
+/** An entry without its move mark. See `DirEntry.moving`. */
+function unmarked(entry) {
+    const { moving: _moving, ...rest } = entry;
+    return rest;
+}
+function hasAncestor(chain, id) {
+    for (let at = chain; at; at = at.up)
+        if (at.id === id)
+            return true;
+    return false;
+}
+/**
+ * The length of `join(dir, name)`, without building it.
  *
- * Well past anything a real project needs, and low enough that a malformed or
- * hostile record cannot spend the caller's memory before the cycle guard sees a
- * repeat.
+ * Only for a name that passed isSafeName, which join cannot rewrite. Lets a
+ * walk charge for a directory's paths BEFORE it makes any of them.
  */
-const MAX_DEPTH = 64;
+function childPathLength(dir, name) {
+    return (dir === "/" ? 1 : dir.length + 1) + name.length;
+}
+/**
+ * `join(dir, name)`, for the same names: what join would return, without
+ * splitting and re-joining the whole path for every entry of a walk.
+ */
+function childPath(dir, name) {
+    return dir === "/" ? `/${name}` : `${dir}/${name}`;
+}
 /**
- * How many directories `walk` lists at once.
+ * The most places one directory may appear in a tree that is being copied.
+ *
+ * A copy writes a record per directory VISITED, and a record can name the same
+ * directory any number of times: three records - one naming a second 300
+ * times, that one naming a third 300 times - are 90,000 sealed writes, each a
+ * round trip, all inside the entry budget. In a real tree a directory is in
+ * one place, or in two after a move that was interrupted between attaching
+ * and detaching; four allows for one of those inside another.
+ */
+const MAX_SHARED = 4;
+/**
+ * An entry map with no prototype.
+ *
+ * Every `DirNode.entries` must be one of these. An ordinary object - which is
+ * what JSON.parse and `{}` both produce - answers `entries["constructor"]` with
+ * the inherited Object constructor, a phantom entry no listing ever shows, and
+ * treats `entries["__proto__"] = entry` as a prototype change rather than a new
+ * key, so JSON.stringify drops it and a write that reported success stored
+ * nothing. Those are real folder and file names; the map has to hold them
+ * rather than the names being refused.
+ */
+function emptyEntries() {
+    return Object.create(null);
+}
+/**
+ * Look a name up among a directory's OWN entries.
  *
- * Enough to hide per-request latency on a wide tree; low enough that a big
- * project does not open a request per directory. Browsers cap concurrency per
- * origin anyway, so a larger number mostly moves the queue.
+ * Belt and braces alongside the null-prototype map: a node built somewhere that
+ * forgot `emptyEntries()` still cannot resolve a name to something inherited.
+ */
+function entryIn(node, name) {
+    return Object.hasOwn(node.entries, name) ? node.entries[name] : undefined;
+}
+/**
+ * Refuse to put anything at `name` in `dir` when an entry this version cannot
+ * read is already there.
+ *
+ * For every operation that refuses an existing destination - rename, copy,
+ * mkdir, including the parents writeFile creates. A hidden entry is not a free
+ * name: it may be a newer SDK's, and replacing it would erase it with no word
+ * to anyone. writeFile and writeManifest DO replace one, because putting their
+ * file at that exact name is what they were asked to do, and a recursive
+ * delete of that exact name removes one.
+ */
+function assertNotHidden(dir, name, path) {
+    if (Object.hasOwn(dir.hidden, name)) {
+        throw new VfsConflictError(`${printable(path, 1024)} already exists, but this version cannot read it; a recursive delete removes it`);
+    }
+}
+/** A JSON object, as opposed to null, an array or a scalar. */
+function isObject$1(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Numbers from a record, made into numbers. The record may not be something
+ * this SDK wrote, and these go straight to callers typed as numbers - the CLI
+ * formats `mtime` with `new Date(mtime).toISOString()`, which throws on
+ * "yesterday", on an object and on 1e300. Anything else reads as 0.
  */
-/** Directory records fetched in parallel while walking.
+const asTime = (value) => typeof value === "number" && Math.abs(value) <= MAX_TIME ? value : 0;
+const asCount = (value) => (Number.isSafeInteger(value) && value >= 0 ? value : 0);
+/** Open a sealed value with the first of `keys` that opens it, or say why none did. */
+async function openWithAny(raw, keys) {
+    let problem = "there is no key to open it with";
+    for (const key of keys) {
+        try {
+            return { value: await openSealed(key, raw), key };
+        }
+        catch (err) {
+            if (!(err instanceof SealedRecordError))
+                throw err;
+            problem = err.message;
+        }
+    }
+    return { problem };
+}
+/**
+ * How deeply a value in a directory record may nest objects and arrays.
  *
- *  Kept at 8 alongside the shard read concurrency. Raising both to 24/16 was
- *  neither better nor worse once enough samples were taken — the spread between
- *  runs is wider than the difference between the settings — so this stays at the
- *  simpler value. See FileStorage's note. */
-const WALK_CONCURRENCY = 8;
+ * Far past anything this SDK writes - an entry, its manifest, its chunks and
+ * their fields are five levels - and far short of where JSON.stringify's
+ * recursion gives out. JSON.parse has no such limit, so a record can hold a
+ * value that parses and can never be written back.
+ */
+const MAX_NESTING = 32;
+/** Does `value` nest objects or arrays more than `max` levels deep? Not recursive: that is the point. */
+function nestedDeeperThan(value, max) {
+    const pending = [[value, 1]];
+    for (let next = pending.pop(); next; next = pending.pop()) {
+        const [at, depth] = next;
+        if (typeof at !== "object" || at === null)
+            continue;
+        if (depth > max)
+            return true;
+        for (const child of Object.values(at))
+            if (typeof child === "object" && child !== null)
+                pending.push([child, depth + 1]);
+    }
+    return false;
+}
 /**
- * `Promise.all` with a ceiling, preserving input order.
+ * A decrypted history record as this version reads it, and how many versions
+ * it left out.
+ *
+ * Checked like a directory record, and for the same reasons: anything holding
+ * the seed can write one. A version is kept only with a manifest that has an
+ * id - `history` lists versions and `restore` takes one by its place in that
+ * list, so the two must leave out the same ones - and nothing nested past
+ * MAX_NESTING is kept, because the record is written back on every save and
+ * JSON.stringify cannot write it. Anything else is an empty history, as it
+ * always was.
+ */
+function readableHistory(value) {
+    if (!isObject$1(value) || !Array.isArray(value.versions))
+        return { record: { v: 1, versions: [] }, dropped: 0 };
+    // No prototype, as for a directory record's fields.
+    const record = Object.create(null);
+    for (const [field, fieldValue] of Object.entries(value)) {
+        if (field !== "versions" && !nestedDeeperThan(fieldValue, MAX_NESTING))
+            record[field] = fieldValue;
+    }
+    const versions = value.versions.filter((version) => isObject$1(version) && isObject$1(version.manifest) && typeof version.manifest.id === "string" &&
+        !nestedDeeperThan(version, MAX_NESTING));
+    record.versions = versions;
+    return { record: record, dropped: value.versions.length - versions.length };
+}
+/**
+ * Why a decrypted directory record cannot be read, or null when it can.
  *
- * Results are written back BY INDEX rather than pushed as they settle, so the
- * output order matches the input regardless of which finishes first — which is
- * what lets `walk` parallelise without changing what it returns.
+ * `unseal` returns whatever JSON.parse produced, and the record may have been
+ * written by anything holding the seed, or by a newer version of this SDK. An
+ * unknown `v` is refused outright rather than read on a best-effort basis:
+ * reading it as v1 and writing it back would silently downgrade it.
  */
-async function mapLimit(items, limit, fn) {
-    if (items.length <= 1)
-        return items.length ? [await fn(items[0])] : [];
-    const out = new Array(items.length);
-    let next = 0;
-    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
-        for (let i = next++; i < items.length; i = next++)
-            out[i] = await fn(items[i]);
-    }));
+function recordProblem(value) {
+    if (!isObject$1(value))
+        return "it is not an object";
+    if (value.v !== 1) {
+        const v = typeof value.v === "number" || typeof value.v === "string"
+            ? printable(String(value.v), 32)
+            : typeof value.v;
+        return `it has format version ${v}, and this version reads only 1`;
+    }
+    if (!isObject$1(value.entries))
+        return "its entries are missing or not a map";
+    return null;
+}
+/**
+ * What an entry id looks like: `newId()` mints 22 characters of unpadded
+ * base64 with `+` and `/` dropped, and the root's id is "root". A little
+ * looser than that, never looser than a store key can carry.
+ *
+ * The id is not just a label. `dirKey(id)` and `historyKey(id)` are store
+ * keys, and Client's store puts the key in a URL: a lone surrogate made
+ * encodeURIComponent throw, and an id past the Durable Object's 2048-byte key
+ * limit got a 500 - from every walk above the entry, and from every attempt
+ * to delete it, for good.
+ */
+const ENTRY_ID = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * Is this an entry this version knows how to follow?
+ *
+ * Every entry needs an id this SDK could have minted - see ENTRY_ID. A file
+ * needs a manifest with an id of its own - version control tells versions
+ * apart by it, and skips an entry without one, so the working tree must skip
+ * it too or the two disagree about what is there. A directory needs a key
+ * that is really an AES-256 key, because every walk decodes it and a bad one
+ * would throw from somewhere far less helpful. Anything else - an unknown
+ * kind, a missing field, a bare scalar - is not an error in the RECORD, only
+ * in that one entry, and hiding one entry is the same outcome as someone
+ * deleting it.
+ */
+function readableEntry(value) {
+    if (!isObject$1(value) || typeof value.id !== "string" || !ENTRY_ID.test(value.id))
+        return false;
+    if (value.kind === "file")
+        return isObject$1(value.manifest) && typeof value.manifest.id === "string";
+    if (value.kind !== "dir" || typeof value.key !== "string")
+        return false;
+    try {
+        return fromBase64(value.key).length === 32;
+    }
+    catch {
+        return false; // not base64 at all
+    }
+}
+/**
+ * Every entry a directory references that this version can FOLLOW - the
+ * visible ones, plus any set aside only because its NAME is unusable.
+ *
+ * For sweep and purge, which must account for everything a record points at
+ * rather than show it: an entry hidden for its name is still a directory whose
+ * records are reachable, or a file whose content the directory owns.
+ */
+function followable(dir) {
+    const out = Object.entries(dir.node.entries);
+    // A null name: the entry is followed, but no path is ever built from it.
+    for (const value of Object.values(dir.hidden))
+        if (readableEntry(value))
+            out.push([null, value]);
     return out;
 }
-const DEFAULT_HISTORY_LIMIT = 20;
+/** How many of a directory's hidden entries this version cannot follow at all. */
+function unfollowable(dir) {
+    return Object.values(dir.hidden).filter((value) => !readableEntry(value)).length;
+}
 class VfsNamespace {
     deps;
     rootKey = null;
@@ -12920,9 +13516,13 @@ class VfsNamespace {
      */
     cache = new Map();
     historyLimit;
+    maxEntries;
+    maxPathChars;
     constructor(deps) {
         this.deps = deps;
         this.historyLimit = deps.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+        this.maxEntries = deps.limits?.entries ?? DEFAULT_MAX_ENTRIES;
+        this.maxPathChars = deps.limits?.pathChars ?? DEFAULT_MAX_PATH_CHARS;
     }
     /**
      * The working directory relative paths resolve against.
@@ -13022,9 +13622,24 @@ class VfsNamespace {
     }
     // ---- reads --------------------------------------------------------------
     async exists(path) {
+        // The root has no entry of its own, so `find` cannot see it — and
+        // answering false here told `vfs mount` at "/" that the whole remote
+        // tree was missing on every pass. It always exists once the filesystem
+        // can be opened; opening it is also what makes a locked VFS throw
+        // rather than reassure.
+        if (this.resolve(path) === "/") {
+            await this.root();
+            return true;
+        }
         return (await this.find(path)) !== null;
     }
     async stat(path) {
+        // The root, as `exists` sees it: a directory, there whenever the
+        // filesystem can be opened. The two used to disagree about it.
+        if (this.resolve(path) === "/") {
+            const root = await this.root();
+            return { path: "/", name: "", kind: "dir", size: 0, mtime: asTime(root.node.mtime), versions: 0 };
+        }
         const found = await this.find(path);
         if (!found)
             throw new VfsNotFoundError(this.resolve(path));
@@ -13034,22 +13649,20 @@ class VfsNamespace {
     async list(path = ".") {
         const dir = await this.openDir(path);
         const base = this.resolve(path);
+        return this.children(dir).map(({ name, entry }) => toStat(join(base, name), name, entry));
+    }
+    /**
+     * A directory's entries in listing order: directories first, then by name.
+     * Shared by `list` and `walk`, so a walk's output order is exactly the order
+     * of the listings it is made of.
+     */
+    children(dir) {
+        // No name check here: `readRecord` has already set every unusable name
+        // aside, once per record. Checking here instead ran a regex, an encode
+        // and a warning per entry on EVERY visit - and a walk may visit one
+        // record a great many times - while charging none of it to the budget.
         return Object.entries(dir.node.entries)
-            // Validate the name HERE, where it is read.
-            //
-            // A directory record is sealed under a key derivable from the master
-            // seed, so its contents are not necessarily something this SDK
-            // wrote, and the write-side check never sees them. An unusable name
-            // is dropped rather than thrown on: one bad entry must not make the
-            // whole directory unlistable, and callers walk this output straight
-            // into filesystem paths.
-            .filter(([name]) => {
-            if (isSafeName(name))
-                return true;
-            this.warn(`ignoring entry with an unusable name in ${base}`);
-            return false;
-        })
-            .map(([name, entry]) => toStat(join(base, name), name, entry))
+            .map(([name, entry]) => ({ name, kind: entry.kind, entry }))
             .sort(byDirsThenName);
     }
     warn(message) {
@@ -13063,42 +13676,153 @@ class VfsNamespace {
      *
      * Deliberately separate from `list`: this walks the whole subtree, which is
      * one fetch per directory. Fine for a project, wrong as a default.
+     *
+     * Throws VfsLimitError past the entry budget or the depth ceiling, and
+     * VfsCorruptRecordError for a directory it cannot read, rather than
+     * returning part of the tree. Skips (with a warning) a directory that is
+     * one of its own ancestors.
      */
     async walk(path = ".") {
+        return (await this.walkEntries(path)).filter((e) => e.kind === "file").map((e) => e.path);
+    }
+    /**
+     * Every entry under a prefix - directories as well as files - depth-first,
+     * each directory just before its contents. `walk` is this with the
+     * directories filtered out, so the two can never disagree about what is in
+     * a tree; version control uses this one because a commit records empty
+     * directories too.
+     */
+    async walkEntries(path = ".") {
+        const out = [];
+        await this.eachEntry(path, (stat) => void out.push(stat));
+        return out;
+    }
+    /**
+     * `walkEntries` without the list: `visit` is called with each entry in
+     * the same order, and for a file with its manifest - the handle
+     * `statManifest` gives, without resolving the path all over again, which
+     * on a deep tree cost far more than the walk itself. Null for a directory.
+     *
+     * For a caller that does not need every entry at once. Version control
+     * compares the working tree with a commit as it goes, where holding the
+     * whole walk beside the whole commit, and a map of one beside a map of
+     * the other, ran a 512MB heap out of memory inside the default budgets.
+     * The same guards and budgets as `walk`, which is built on this.
+     */
+    async eachEntry(path, visit) {
         /**
-         * Sibling directories are listed CONCURRENTLY.
+         * One directory at a time, depth-first, with the records it is about to
+         * need fetched ahead of it.
          *
-         * Each `list` is a round trip for one directory record, and walking them
-         * one after another cost the sum of those latencies: measured against a
-         * real project, the walk alone was 1–2.1s before a single file had been
-         * read. Directories are independent, so there was never a reason to
-         * queue them.
+         * Everything a walk holds is its current path - and `walkEntries`
+         * its output, which is why a caller comparing as it goes uses this
+         * instead. It used to list sibling directories concurrently, each one fanning out into
+         * its own children the same way, eight at a time PER DIRECTORY - so
+         * eight per level, multiplying down the tree. Records are cached by id,
+         * so on a planted fan-out nothing ever waited, and every visit up to
+         * the entry budget was in flight at once, each with its own copy of
+         * the ancestor set: 29 records inside both default budgets ran a 3GB
+         * heap out of memory. The budgets count OUTPUT; only the shape of the
+         * traversal bounds what is held while producing it.
          *
-         * Order is preserved exactly. Each entry maps to its own slice of the
-         * result and the slices are concatenated in listing order, so the output
-         * is identical to the depth-first version — callers and tests that
-         * depend on it are unaffected, and only the timing changes.
+         * Round trips still overlap. Walking directories one after another
+         * cost the sum of their latencies - 1-2.1s against a real project
+         * before a single file had been read - so ReadAhead keeps up to
+         * WALK_CONCURRENCY fetches going for the directories the walk will
+         * reach next, and the walk's own reads come out of the same pool.
+         *
+         * Directories are opened by the id and key their parent holds, not by
+         * re-resolving each path from the root, which is what lets the cycle
+         * guard below work on IDENTITY. It used to be a set of paths, and a
+         * record whose two entries both point back at itself produces a fresh
+         * path at every level - /loop/a, /loop/b, /loop/a/a - so it never fired
+         * and 2^64 visits ran the process out of memory.
          */
-        const seen = new Set();
-        const visit = async (dirPath, depth) => {
-            if (depth > MAX_DEPTH) {
-                this.warn(`stopping at ${dirPath}: deeper than ${MAX_DEPTH} levels`);
-                return [];
-            }
-            // Claimed BEFORE the first await, so two concurrent visits to the
-            // same directory cannot both get past this. A record whose entry
-            // points back at an ancestor would otherwise recurse forever, and
-            // nothing in the format prevents one.
-            if (seen.has(dirPath)) {
-                this.warn(`stopping at ${dirPath}: already visited (the tree contains a cycle)`);
-                return [];
-            }
-            seen.add(dirPath);
-            const entries = await this.list(dirPath);
-            const slices = await mapLimit(entries, WALK_CONCURRENCY, async (entry) => entry.kind === "dir" ? visit(entry.path, depth + 1) : [entry.path]);
-            return slices.flat();
+        const start = this.resolve(path);
+        const opened = await this.openChain(start);
+        if (!opened)
+            throw new VfsNotFoundError(start);
+        // Bounded here, not by the cycle guard, which cannot see a tree that
+        // fans out without ever looping - in entries, and in the characters of
+        // the paths those entries become, since that is what the result holds.
+        let budget = this.maxEntries;
+        let chars = this.maxPathChars;
+        // Directories already reported as cycles. A fan-out can reach one
+        // record hundreds of thousands of times, and a warning per visit is a
+        // line per path in the user's terminal.
+        const reported = new Set();
+        // The id of every directory from the root down to the one being
+        // listed. It starts with the chain above `start`, so a pointer back
+        // above where the walk began is a cycle too, and a subtree's walk
+        // agrees with the same subtree in a walk of the root. Added to and
+        // taken from as the walk goes down and back up; never copied.
+        const onPath = new Set(opened.chain);
+        const stack = [];
+        const ahead = new ReadAhead(WALK_CONCURRENCY, (dir) => this.children(dir), (id) => this.cache.has(id), (entry, at) => this.openDirById(entry.id, fromBase64(entry.key), at));
+        /** Charge for a directory's listing, and make it the walk's current one. True when it is time to yield. */
+        const enter = (dir, dirPath) => {
+            const children = this.children(dir);
+            const turn = Math.floor(budget / YIELD_EVERY);
+            budget -= children.length;
+            if (budget < 0)
+                throw new VfsLimitError("entries", this.maxEntries, start, dirPath);
+            // Charged before any of these paths is built.
+            for (const { name } of children)
+                chars -= childPathLength(dirPath, name);
+            if (chars < 0)
+                throw new VfsLimitError("pathChars", this.maxPathChars, start, dirPath);
+            stack.push({ id: dir.id, path: dirPath, children, next: 0 });
+            ahead.scan(dir, dirPath, children);
+            return Math.floor(budget / YIELD_EVERY) !== turn;
         };
-        return visit(this.resolve(path), 0);
+        try {
+            // One continuation, so a yield parks the whole walk and not one
+            // branch of it while the rest carry on.
+            if (enter(opened.dir, start))
+                await nextTurn();
+            while (stack.length) {
+                const frame = stack[stack.length - 1];
+                if (frame.next === frame.children.length) {
+                    stack.pop();
+                    // The bottom frame is `start`, which is part of the chain.
+                    if (stack.length)
+                        onPath.delete(frame.id);
+                    continue;
+                }
+                const { name, entry } = frame.children[frame.next++];
+                const at = childPath(frame.path, name);
+                if (entry.kind !== "dir") {
+                    visit(toStat(at, name, entry), entry.manifest);
+                    continue;
+                }
+                // A directory that is one of ITS OWN ancestors is a true cycle:
+                // everything in it is already on this branch. Only the path
+                // above this entry counts - not every directory seen so far -
+                // because rename() deliberately leaves a moved subtree reachable
+                // from two parents, and both paths must keep appearing.
+                if (onPath.has(entry.id)) {
+                    if (!reported.has(entry.id)) {
+                        reported.add(entry.id);
+                        this.warn(`skipping ${at}: it is one of its own ancestors (the tree contains a cycle)`);
+                    }
+                    continue;
+                }
+                // Thrown, not truncated: a sync reads a missing path as a
+                // deleted one. The frames are the levels below `start`.
+                if (stack.length > MAX_DEPTH)
+                    throw new VfsLimitError("depth", MAX_DEPTH, start, at);
+                const child = await ahead.open(entry, at);
+                visit(toStat(at, name, entry), null);
+                onPath.add(entry.id);
+                if (enter(child, at))
+                    await nextTurn();
+            }
+        }
+        finally {
+            // However it ended. A walk that failed must not leave fetches
+            // running in the background after the caller has moved on.
+            ahead.stop();
+        }
     }
     async readFile(path) {
         const entry = await this.expectFile(path);
@@ -13152,7 +13876,7 @@ class VfsNamespace {
         assertValidName(name);
         await this.mkdir(dirname(target), { recursive: true });
         const parent = await this.openDir(dirname(target));
-        const prior = parent.node.entries[name];
+        const prior = entryIn(parent.node, name);
         if (prior?.kind === "dir")
             throw new VfsConflictError(`${target} is a directory`);
         await this.deps.content.retain(manifest);
@@ -13162,7 +13886,9 @@ class VfsNamespace {
             manifest,
             size,
             mtime: Date.now(),
-            versions: prior?.versions ?? 0,
+            versions: asCount(prior?.versions),
+            // Still half of an interrupted move, if it was: see DirEntry.moving.
+            ...(prior?.moving === true ? { moving: true } : {}),
         };
         await this.mutate(parent, (node) => {
             node.entries[name] = entry;
@@ -13178,13 +13904,20 @@ class VfsNamespace {
         const target = this.resolve(path);
         if (target === "/")
             return;
+        // Before anything is created. This is also the whole of the check for
+        // writeFile and writeManifest: a file may sit in the deepest
+        // directory, and they create its parent through here.
+        assertWritableDepth(target);
         const parts = segments(target);
         let current = "/";
         for (let i = 0; i < parts.length; i++) {
             const name = parts[i];
             const isLast = i === parts.length - 1;
             const next = join(current, name);
-            const existing = (await this.openDir(current)).node.entries[name];
+            const dir = await this.openDir(current);
+            const existing = entryIn(dir.node, name);
+            if (!existing)
+                assertNotHidden(dir, name, next);
             if (existing) {
                 if (existing.kind === "file")
                     throw new VfsConflictError(`${next} is a file`);
@@ -13199,6 +13932,38 @@ class VfsNamespace {
             current = next;
         }
     }
+    /**
+     * Refuse now what creating these directories with `mkdir -p` would refuse
+     * part way: one deeper than MAX_DEPTH, or a name on the way held by an
+     * entry this version cannot read. Writes nothing.
+     *
+     * For an operation that removes things before it writes - a checkout -
+     * so that a refusal comes before anything is gone. A FILE in the way is
+     * not refused: such an operation removes those first.
+     */
+    async assertCreatable(dirs) {
+        let checked = 0;
+        for (const target of new Set([...dirs].map((dir) => this.resolve(dir)))) {
+            assertWritableDepth(target);
+            let dir = await this.root();
+            let at = "/";
+            for (const name of segments(target)) {
+                at = join(at, name);
+                const entry = entryIn(dir.node, name);
+                if (!entry) {
+                    assertNotHidden(dir, name, at);
+                    break; // everything below it is to be created
+                }
+                if (entry.kind !== "dir")
+                    break;
+                dir = await this.openDirById(entry.id, fromBase64(entry.key), at);
+            }
+            // Once the tree has been walked every record is cached, and nothing
+            // here waits on anything.
+            if (++checked % YIELD_EVERY === 0)
+                await nextTurn();
+        }
+    }
     /**
      * Write a file, creating parent directories as needed.
      *
@@ -13218,14 +13983,18 @@ class VfsNamespace {
             type: opts.type ?? contentTypeFor(name),
         });
         const parent = await this.openDir(parentPath);
-        const prior = parent.node.entries[name];
+        const prior = entryIn(parent.node, name);
         if (prior?.kind === "dir")
             throw new VfsConflictError(`${target} is a directory`);
         const id = prior?.id ?? newId();
-        let versions = prior?.versions ?? 0;
+        let versions = asCount(prior?.versions);
         if (prior)
-            versions = await this.pushHistory(parent, id, prior);
-        const entry = { kind: "file", id, manifest, size, mtime: Date.now(), versions };
+            versions = await this.pushHistory(parent, name, prior, target, manifest);
+        const entry = {
+            kind: "file", id, manifest, size, mtime: Date.now(), versions,
+            // Still half of an interrupted move, if it was: see DirEntry.moving.
+            ...(prior?.moving === true ? { moving: true } : {}),
+        };
         await this.mutate(parent, (node) => {
             node.entries[name] = entry;
         });
@@ -13234,36 +14003,110 @@ class VfsNamespace {
     /**
      * Delete a file, or a directory when `recursive`.
      *
-     * `keepContent` removes the entry WITHOUT releasing its shards. A checkout
-     * needs that: the file is leaving the working tree, but commits still
-     * reference the same manifest, and releasing would free content history
-     * depends on.
+     * `keepContent` removes the entry WITHOUT releasing its shards - or, for
+     * a directory, the shards of anything in it. A checkout needs that: the
+     * file is leaving the working tree, but commits still reference the same
+     * manifest, and releasing would free content history depends on.
      */
     async delete(path, opts = {}) {
         const target = this.resolve(path);
         if (target === "/")
             throw new VfsConflictError("the root directory cannot be deleted");
         const name = basename(target);
-        const parent = await this.openDir(dirname(target));
-        const entry = parent.node.entries[name];
-        if (!entry)
-            throw new VfsNotFoundError(target);
-        if (entry.kind === "dir") {
-            const child = await this.openDirById(entry.id, fromBase64(entry.key));
-            const empty = Object.keys(child.node.entries).length === 0;
-            if (!empty && !opts.recursive)
-                throw new VfsConflictError(`${target} is not empty`);
-            await this.purge(child);
-        }
-        else if (opts.keepContent) {
-            await this.deps.store.delete(historyKey(entry.id)).catch(() => { });
+        const opened = await this.openChain(dirname(target));
+        if (!opened)
+            throw new VfsNotFoundError(dirname(target));
+        const parent = opened.dir;
+        const entry = entryIn(parent.node, name);
+        if (!entry) {
+            if (!Object.hasOwn(parent.hidden, name))
+                throw new VfsNotFoundError(target);
+            // An entry this version cannot read, asked for by its exact name.
+            // It may be a newer version's, and what it holds cannot be known,
+            // so only a recursive delete removes it - and only detaches it,
+            // letting go of nothing: a leak is the safe way to be wrong. The
+            // way to clear a name that mkdir, rename, copy and a checkout
+            // refuse, short of deleting everything around it.
+            const where = printable(target, 1024);
+            if (!opts.recursive)
+                throw new VfsConflictError(`${where} cannot be read by this version; a recursive delete removes it`);
+            await this.mutate(parent, () => void delete parent.hidden[name]);
+            this.warn(`removed ${where} without clearing out what it held: this version cannot read it`);
+            return;
         }
-        else {
-            await this.releaseFile(parent, entry);
+        // Every directory above the target, the root first. None of them is
+        // part of what is being deleted, whatever an entry below says.
+        const above = new Set(opened.chain);
+        // Three steps, in this order: read everything the delete will touch,
+        // detach the entry, then let go of what it held.
+        //
+        // Letting go came first once, and the entry was detached last. Any
+        // failure in between - a network error, most simply - left the entry
+        // in place with some of its content already released, and the obvious
+        // next step, trying again, released that content a SECOND time.
+        // Content is reference-counted and shared by copies, so that freed
+        // bytes another file still used. Now a failure before the detach has
+        // changed nothing, and nothing after it can fail: releasing is
+        // best-effort, and a leak is the safe way to be wrong.
+        let doomed = [];
+        // Whether any of it is half of an interrupted move. See below.
+        let moving = entry.kind === "file" && entry.moving === true;
+        if (entry.kind === "dir" && above.has(entry.id)) {
+            // The entry IS a pointer to a directory above it - the root, or
+            // this entry's own parent. Removing the pointer is what was asked
+            // for; clearing out what it points at would delete everything
+            // around the target, the target included.
+            if (!opts.recursive)
+                throw new VfsConflictError(`${target} is not empty`);
+            this.warn(`detaching ${target} without clearing it out: it is a directory above it in the tree`);
+        }
+        else if (entry.kind === "dir") {
+            const child = await this.openDirById(entry.id, fromBase64(entry.key), target).catch((err) => {
+                // An unreadable directory must still be removable, or the user
+                // is stuck with an error they can do nothing about. Its subtree
+                // cannot be enumerated, so it is detached rather than purged and
+                // whatever it holds is left for sweep(). Only when asked for
+                // recursively: without that we cannot know it is empty.
+                if (!(err instanceof VfsCorruptRecordError) || !opts.recursive)
+                    throw err;
+                this.warn(`detaching ${target} without clearing it out: its record cannot be read`);
+                return null;
+            });
+            if (child) {
+                // Entries this version cannot read still count: calling the
+                // directory empty would delete them along with it.
+                const empty = !Object.keys(child.node.entries).length && !Object.keys(child.hidden).length;
+                if (!empty && !opts.recursive)
+                    throw new VfsConflictError(`${target} is not empty`);
+                const found = await this.subtree(child, target, above);
+                doomed = found.dirs;
+                moving = entry.moving === true || found.moving;
+            }
         }
+        // A move between two directories that was interrupted leaves what it
+        // moved named in both, and letting go of it here would take it from
+        // the other copy: the directory record purged with every file in it,
+        // or a file's content and history released. Only a marked entry can
+        // be one of those (see `rename`), so only then is the whole tree
+        // read, once, to find out what is still named elsewhere. Still before
+        // anything changes: a failure here leaves the tree as it was.
+        const elsewhere = moving ? await this.namedElsewhere(parent.id, name) : undefined;
         await this.mutate(parent, (node) => {
             delete node.entries[name];
         });
+        if (elsewhere === null) {
+            // Part of the tree cannot be read, so it is unknown whether the
+            // other copy is in it. Keeping what may be its contents costs
+            // storage until a sweep; letting go of them could lose them.
+            this.warn(`detached ${target} but kept what it held: a move of it was interrupted, and part of the tree cannot be read to find the other copy`);
+            return;
+        }
+        if (entry.kind === "dir")
+            await this.purge(doomed, elsewhere, opts.keepContent);
+        else
+            await this.letGo(new Map([[entry.id, [{ dir: parent, entry }]]]), elsewhere, opts.keepContent);
+        if (elsewhere && entry.moving === true)
+            await this.settle(entry.id, elsewhere);
     }
     /**
      * Move or rename. Works across directories, which is the same operation:
@@ -13271,7 +14114,8 @@ class VfsNamespace {
      *
      * A directory move is O(1) regardless of how much is inside it — the
      * subtree records are not touched at all, because nothing in them records
-     * its own path.
+     * its own path. Except a move to a DEEPER place, which reads the subtree
+     * first: what is below must still be inside MAX_DEPTH once it is moved.
      */
     async rename(from, to) {
         const src = this.resolve(from);
@@ -13282,28 +14126,83 @@ class VfsNamespace {
             throw new VfsConflictError("the root directory cannot be moved");
         if (isUnder(dst, src))
             throw new VfsConflictError(`cannot move ${src} into itself`);
+        const srcName = basename(src);
         const dstName = basename(dst);
         assertValidName(dstName);
         const srcParent = await this.openDir(dirname(src));
-        const entry = srcParent.node.entries[basename(src)];
+        const entry = entryIn(srcParent.node, srcName);
         if (!entry)
             throw new VfsNotFoundError(src);
+        if (entry.kind === "dir") {
+            assertWritableDepth(dst);
+            if (segments(dst).length > segments(src).length)
+                await this.assertFitsAt(src, dst);
+        }
         await this.mkdir(dirname(dst), { recursive: true });
         const dstParent = await this.openDir(dirname(dst));
-        if (dstParent.node.entries[dstName])
+        if (entryIn(dstParent.node, dstName))
             throw new VfsConflictError(`${dst} already exists`);
-        // Attach before detaching. If the second write fails the entry is
-        // reachable from both parents — visible and fixable. The other order
-        // would lose the subtree entirely.
-        const moved = { ...entry, mtime: Date.now() };
-        await this.mutate(dstParent, (node) => {
-            node.entries[dstName] = moved;
-        });
-        // Re-open: same-parent moves mutated the record we are about to edit.
-        const detachFrom = await this.openDir(dirname(src));
-        await this.mutate(detachFrom, (node) => {
-            delete node.entries[basename(src)];
-        });
+        assertNotHidden(dstParent, dstName, dst);
+        // Each record is re-opened before it is written: creating the
+        // destination's parents above may have written to the source's.
+        const edit = (path, change) => this.openDir(path).then((dir) => this.mutate(dir, change));
+        if (dstParent.id === srcParent.id) {
+            // One record, so one write: the move happens entirely or not at all.
+            await edit(dirname(src), (node) => {
+                delete node.entries[srcName];
+                node.entries[dstName] = { ...entry, mtime: Date.now() };
+            });
+            return;
+        }
+        // Two records, attached before detaching: interrupted, the entry is
+        // in both rather than in neither. Both copies are marked for as long
+        // as that can be so, because they share everything below them, and a
+        // delete of either would otherwise let go of the other's contents.
+        // An entry already marked is half of an earlier interrupted move, and
+        // keeps its mark.
+        const marked = entry.moving === true;
+        if (!marked)
+            await edit(dirname(src), (node) => void (node.entries[srcName] = { ...entry, moving: true }));
+        await edit(dirname(dst), (node) => void (node.entries[dstName] = { ...entry, moving: true, mtime: Date.now() }));
+        // A file's history is sealed with its directory's key, and from here
+        // on the directory that opens it is this one.
+        if (entry.kind === "file")
+            await this.rekeyHistory(entry.id, [srcParent.key], dstParent.key);
+        await edit(dirname(src), (node) => void delete node.entries[srcName]);
+        if (!marked) {
+            await edit(dirname(dst), (node) => {
+                const landed = entryIn(node, dstName);
+                if (landed?.id === entry.id)
+                    node.entries[dstName] = unmarked(landed);
+            });
+        }
+    }
+    /**
+     * Refuse to move the directory at `src` to `dst` when something in it
+     * would then be deeper than MAX_DEPTH from the root. Writes nothing.
+     *
+     * Measured only moving deeper, because it reads the whole subtree: one
+     * move of a 40-deep tree under a 30-deep directory was accepted when only
+     * the moved directory was measured, and every walk of the root threw from
+     * then on. A part that cannot be read cannot be measured, and does not
+     * stop the move - that record stops every walk above it already.
+     */
+    async assertFitsAt(src, dst) {
+        const room = MAX_DEPTH - segments(dst).length;
+        try {
+            await this.eachEntry(src, ({ kind, path }) => {
+                if (kind !== "dir")
+                    return;
+                const below = path.slice(src.length);
+                if (below.split("/").length - 1 <= room)
+                    return;
+                throw new VfsLimitError("depth", MAX_DEPTH, dst, dst + below, "writing");
+            });
+        }
+        catch (err) {
+            if (!(err instanceof VfsCorruptRecordError))
+                throw err;
+        }
     }
     /**
      * Copy a file or a directory tree.
@@ -13333,9 +14232,21 @@ class VfsNamespace {
         assertValidName(dstName);
         await this.mkdir(dirname(dst), { recursive: true });
         const dstParent = await this.openDir(dirname(dst));
-        if (dstParent.node.entries[dstName])
+        if (entryIn(dstParent.node, dstName))
             throw new VfsConflictError(`${dst} already exists`);
-        const copied = await this.cloneEntry(found.entry);
+        assertNotHidden(dstParent, dstName, dst);
+        // Twice over: a dry run first, which fetches and checks everything the
+        // copy will visit - cycles, depth, both budgets, unreadable records -
+        // and writes nothing. A copy that is going to fail then fails before
+        // its first write, instead of after up to a whole budget's worth of
+        // records and references, all left unreachable. The records are
+        // cached by then, so the real pass costs writes, not fetches.
+        const run = (write) => ({
+            from: src, to: dst, write, entries: this.maxEntries, pathChars: this.maxPathChars, reached: new Map(), sinceTurn: 0,
+        });
+        const depth = segments(dst).length;
+        await this.cloneEntry(found.entry, src, run(false), null, depth);
+        const copied = await this.cloneEntry(found.entry, src, run(true), null, depth);
         await this.mutate(dstParent, (node) => {
             node.entries[dstName] = copied;
         });
@@ -13368,25 +14279,27 @@ class VfsNamespace {
      */
     async sweep(opts = {}) {
         const root = await this.root();
-        const reachable = new Set();
-        const visit = async (dir) => {
-            // `reachable` was already the visited set - it just was not being
-            // TESTED before recursing, so a cycle looped forever. Here the
-            // consequence would have been worse than a hang: sweep decides what
-            // to delete, and it never got as far as deciding.
-            if (reachable.has(dirKey(dir.id)))
-                return;
-            reachable.add(dirKey(dir.id));
-            for (const entry of Object.values(dir.node.entries)) {
-                if (entry.kind === "dir") {
-                    await visit(await this.openDirById(entry.id, fromBase64(entry.key)));
-                }
-                else {
-                    reachable.add(historyKey(entry.id));
-                }
-            }
-        };
-        await visit(root);
+        // A record that cannot be read throws out of here, before anything is
+        // deleted: with part of the tree unknown, "unreachable" is a guess.
+        // Behind a name no path can reach, though, an unreadable record is one
+        // the user cannot delete either: it is counted with the entries this
+        // version cannot read - refused below unless forced - and, forced, kept
+        // and not followed. `references` follows entries hidden only for their
+        // NAME: what they point at is still referenced, and so not an orphan.
+        const named = await this.references();
+        const reachable = new Set([
+            ...[...named.dirs].map(dirKey),
+            ...[...named.files.keys()].map(historyKey),
+        ]);
+        const unreadable = named.unknown;
+        // The same caution for an ENTRY this version cannot read: a newer
+        // SDK's entry may be the only thing keeping some record reachable, and
+        // there is no way to follow it from here.
+        if (unreadable && !opts.force) {
+            throw new VfsConflictError(`refusing to sweep: ${unreadable} entr${unreadable === 1 ? "y" : "ies"} in this filesystem ` +
+                "cannot be read by this version, so what they reference is unknown; " +
+                "upgrade, or sweep with force to go ahead anyway");
+        }
         // Only ever consider OUR records: the personal space is shared with
         // chat keys, space keys and the legacy file mirror, and a sweep that
         // reached beyond its own namespace would be a data-loss bug.
@@ -13398,7 +14311,7 @@ class VfsNamespace {
         const rootEmpty = Object.keys(root.node.entries).length === 0;
         if (rootEmpty && orphans.length && !opts.force) {
             throw new VfsConflictError(`refusing to sweep ${orphans.length} record(s) with an empty root — ` +
-                "this looks like a failed load rather than an empty filesystem; pass { force: true } if it really is empty");
+                "this looks like a failed load rather than an empty filesystem; sweep with force if it really is empty");
         }
         for (const key of orphans)
             await this.deps.store.delete(key).catch(() => { });
@@ -13407,9 +14320,10 @@ class VfsNamespace {
     // ---- history ------------------------------------------------------------
     /** Prior versions of a file, newest first. One record fetch. */
     async history(path) {
-        const entry = await this.expectFile(path);
-        const record = await this.readHistory(await this.openDir(dirname(path)), entry.id);
-        return record.versions.map(({ size, mtime }) => ({ size, mtime }));
+        const target = this.resolve(path);
+        const entry = await this.expectFile(target);
+        const { record } = await this.readHistory(await this.openDir(dirname(target)), basename(target), entry, target);
+        return record.versions.map(({ size, mtime }) => ({ size: asCount(size), mtime: asTime(mtime) }));
     }
     /**
      * Restore a prior version, where 0 is the most recent one.
@@ -13421,21 +14335,22 @@ class VfsNamespace {
         const target = this.resolve(path);
         const name = basename(target);
         const parent = await this.openDir(dirname(target));
-        const entry = parent.node.entries[name];
+        const entry = entryIn(parent.node, name);
         if (!entry || entry.kind !== "file")
             throw new VfsNotFoundError(target);
-        const record = await this.readHistory(parent, entry.id);
+        const { record } = await this.readHistory(parent, name, entry, target);
         const version = record.versions[index];
         if (!version)
             throw new VfsNotFoundError(`${target} version ${index}`);
-        const versions = await this.pushHistory(parent, entry.id, entry);
+        const versions = await this.pushHistory(parent, name, entry, target, version.manifest);
         const restored = {
             kind: "file",
             id: entry.id,
             manifest: version.manifest,
-            size: version.size,
+            size: asCount(version.size),
             mtime: Date.now(),
             versions,
+            ...(entry.moving === true ? { moving: true } : {}),
         };
         await this.mutate(parent, (node) => {
             node.entries[name] = restored;
@@ -13460,7 +14375,7 @@ class VfsNamespace {
         if (!parent)
             return null;
         const name = basename(target);
-        const entry = parent.node.entries[name];
+        const entry = entryIn(parent.node, name);
         return entry ? { name, entry } : null;
     }
     async root() {
@@ -13469,7 +14384,7 @@ class VfsNamespace {
             throw new VfsLockedError();
         if (!this.rootKey)
             this.rootKey = await deriveRootKey(seed);
-        return this.openDirById(ROOT_ID, this.rootKey);
+        return this.openDirById(ROOT_ID, this.rootKey, "/");
     }
     /** Open a directory by path, creating nothing. Throws if it is missing. */
     async openDir(path) {
@@ -13479,16 +14394,29 @@ class VfsNamespace {
         return dir;
     }
     async openDirOrNull(path) {
+        return (await this.openChain(path))?.dir ?? null;
+    }
+    /** Open a directory by path, along with the id of every directory on the way to it. */
+    async openChain(path) {
         let dir = await this.root();
+        const chain = [dir.id];
+        let at = "/";
         for (const name of segments(this.resolve(path))) {
-            const entry = dir.node.entries[name];
+            const entry = entryIn(dir.node, name);
             if (!entry || entry.kind !== "dir")
                 return null;
-            dir = await this.openDirById(entry.id, fromBase64(entry.key));
+            at = join(at, name);
+            dir = await this.openDirById(entry.id, fromBase64(entry.key), at);
+            chain.push(dir.id);
         }
-        return dir;
+        return { dir, chain };
     }
-    openDirById(id, key) {
+    /**
+     * `path` is only for error messages. The cache is keyed by id, so when two
+     * paths reach one record - a move interrupted between attach and detach -
+     * the error names whichever asked first.
+     */
+    openDirById(id, key, path) {
         const hit = this.cache.get(id);
         if (hit)
             return hit;
@@ -13505,8 +14433,26 @@ class VfsNamespace {
             // exists before anything has been written to it, and a directory is
             // created by its parent naming it rather than by its own record
             // appearing.
-            const node = (await unseal(key, raw)) ?? { v: 1, entries: {}, mtime: Date.now() };
-            return { id, key, node };
+            if (raw === null || raw === undefined) {
+                const node = { v: 1, entries: emptyEntries(), mtime: Date.now() };
+                return { id, key, path, node, hidden: Object.create(null) };
+            }
+            // Present but unopenable is NOT absent. `unseal` folds the two
+            // together, which suits a record that can simply be rebuilt; a
+            // directory cannot, because rebuilding it means sealing an empty
+            // one over whatever is really there. And it is not a raw
+            // DOMException either: the typed error is what delete, purge and
+            // sweep know how to step around, and it names the record.
+            let value;
+            try {
+                value = await openSealed(key, raw);
+            }
+            catch (err) {
+                if (err instanceof SealedRecordError)
+                    throw new VfsCorruptRecordError(id, path, err.message);
+                throw err;
+            }
+            return this.readRecord(id, key, value, path);
         })().catch((err) => {
             // A failed read must not be remembered, or one blip poisons the
             // directory for the life of the session.
@@ -13517,11 +14463,110 @@ class VfsNamespace {
         this.cache.set(id, pending);
         return pending;
     }
+    /**
+     * Turn a decrypted record into an OpenDir, or throw.
+     *
+     * The record is THROWN on, never read as empty, when its shape is wrong -
+     * see VfsCorruptRecordError. An individual entry of the wrong shape is set
+     * aside in `hidden` instead: out of every read, but kept for the write.
+     */
+    readRecord(id, key, value, path) {
+        const problem = recordProblem(value);
+        if (problem)
+            throw new VfsCorruptRecordError(id, path, problem);
+        const { entries: stored, ...fields } = value;
+        // Anything nested past MAX_NESTING is dropped outright, not kept to be
+        // written back: JSON.stringify cannot write it, and every write to
+        // this directory - even deleting a sibling - would throw.
+        let dropped = 0;
+        // No prototype, like the entry map: a field named `__proto__` is a
+        // field to keep, not a prototype to set.
+        const top = Object.create(null);
+        for (const [field, fieldValue] of Object.entries(fields)) {
+            if (nestedDeeperThan(fieldValue, MAX_NESTING))
+                dropped++;
+            else
+                top[field] = fieldValue;
+        }
+        const entries = emptyEntries();
+        const hidden = Object.create(null);
+        let unnamed = 0;
+        let unreadable = 0;
+        for (const [name, entry] of Object.entries(stored)) {
+            if (nestedDeeperThan(entry, MAX_NESTING)) {
+                dropped++;
+                continue;
+            }
+            // The NAME is validated here, where it is read, as well as the
+            // entry. A directory record is sealed under a key derivable from
+            // the master seed, so its contents are not necessarily something
+            // this SDK wrote, and the write-side check never sees them. An
+            // unusable name is set aside rather than thrown on: one bad entry
+            // must not make the whole directory unlistable, and callers walk
+            // what is left straight into filesystem paths.
+            if (!isSafeName(name))
+                unnamed++;
+            else if (!readableEntry(entry))
+                unreadable++;
+            else {
+                entries[name] = entry;
+                continue;
+            }
+            hidden[name] = entry;
+        }
+        if (unnamed || unreadable || dropped) {
+            // Once per record fetched, however often a walk comes back to it.
+            // Names are left out: they are exactly the ones not fit to print.
+            const count = (n) => `${n} entr${n === 1 ? "y" : "ies"}`;
+            const what = [
+                unnamed && `${count(unnamed)} with an unusable name`,
+                unreadable && `${count(unreadable)} this version cannot read`,
+                dropped && `${dropped} value${dropped === 1 ? "" : "s"} nested too deeply to keep`,
+            ].filter(Boolean).join(" and ");
+            this.warn(`ignoring ${what} in ${path ?? `record ${printable(id, 40)}`}`);
+        }
+        // A v1 record's unknown top-level fields survive a write too.
+        return { id, key, path, node: { ...top, entries }, hidden };
+    }
     /** Apply an edit to a directory record and persist it. */
     async mutate(dir, edit) {
         edit(dir.node);
         dir.node.mtime = Date.now();
-        await this.deps.store.put(dirKey(dir.id), await seal(dir.key, dir.node));
+        // A write to a hidden entry's exact name replaces it: that name now
+        // means what this version wrote. Forgetting the old one here is also
+        // what stops a later delete of the replacement from resurrecting it.
+        for (const name of Object.keys(dir.hidden)) {
+            if (Object.hasOwn(dir.node.entries, name))
+                delete dir.hidden[name];
+        }
+        const stored = Object.keys(dir.hidden).length
+            ? { ...dir.node, entries: Object.assign(Object.create(null), dir.hidden, dir.node.entries) }
+            : dir.node;
+        try {
+            let sealed;
+            try {
+                sealed = await seal(dir.key, stored);
+            }
+            catch (err) {
+                // JSON.stringify's own failures: a value too deeply nested to
+                // write. Reading drops those from a stored record, so this is
+                // what the write itself was given.
+                if (!(err instanceof RangeError || err instanceof TypeError))
+                    throw err;
+                const where = dir.path ?? `the directory stored as record ${printable(dir.id, 40)}`;
+                throw new VfsConflictError(`cannot write to ${where}: it would hold a value nested too deeply to store`);
+            }
+            await this.deps.store.put(dirKey(dir.id), sealed);
+        }
+        catch (err) {
+            // The edit above was made in place, on the very object the cache
+            // holds. Left there after a failed write, the cache would show a
+            // change the store never took - a deleted file gone from every
+            // listing while it is still stored, and a retry told it does not
+            // exist. Drop it, so the next read asks the store.
+            this.cache.delete(dir.id);
+            throw err;
+        }
         this.cache.set(dir.id, Promise.resolve(dir));
     }
     async createDir(parentPath, name) {
@@ -13532,80 +14577,421 @@ class VfsNamespace {
             node.entries[name] = entry;
         });
     }
-    /** Recursively remove a subtree's records. Best-effort: unreachable ≠ fatal. */
-    async purge(dir, seen = new Set()) {
-        // A record that references an ancestor would otherwise recurse forever:
-        // the id is only removed from the cache AFTER the loop, so re-entering
-        // it hits the same cached record every time.
-        if (seen.has(dir.id))
+    /**
+     * Every directory record in a subtree, each once, opened - and nothing
+     * changed. The first half of a recursive delete; see `delete`.
+     *
+     * Once per id, so a record that references another inside the subtree
+     * cannot recurse forever, and a subtree reachable twice is not released
+     * twice. And never a directory in `above` - the root and everything else
+     * on the way down to the target - nor the root by any route. Deduplicating
+     * alone let an entry naming the root pull the whole filesystem into the
+     * delete, the root record included; a walk shows the same pointer as a
+     * cycle and skips it, so this skips it too.
+     *
+     * `moving` says whether anything in it is marked as half of an
+     * interrupted move, which is what makes a delete look for the other half.
+     */
+    async subtree(top, target, above) {
+        const found = new Map([[top.id, top]]);
+        const pending = [top];
+        let spared = 0;
+        let moving = false;
+        for (let dir = pending.pop(); dir; dir = pending.pop()) {
+            for (const [, entry] of followable(dir)) {
+                if (entry.moving === true)
+                    moving = true;
+                if (entry.kind !== "dir" || found.has(entry.id))
+                    continue;
+                if (entry.id === ROOT_ID || above.has(entry.id)) {
+                    spared++;
+                    continue;
+                }
+                const child = await this.openDirById(entry.id, fromBase64(entry.key)).catch((err) => {
+                    // The caller asked for this whole subtree to go. One part
+                    // of it being unreadable is no reason to refuse the rest:
+                    // skip that part and leave it to sweep(). Any OTHER failure
+                    // stops the delete here, before anything has been released.
+                    if (!(err instanceof VfsCorruptRecordError))
+                        throw err;
+                    this.warn("skipping an unreadable directory while deleting its parent");
+                    return null;
+                });
+                if (!child)
+                    continue;
+                found.set(child.id, child);
+                pending.push(child);
+            }
+        }
+        if (spared) {
+            // Counted, not named: the entry may be one whose name is not fit to print.
+            const what = spared === 1 ? "a directory that is" : `${spared} directories that are`;
+            this.warn(`leaving ${what} above ${target} in the tree alone while deleting it`);
+        }
+        return { dirs: [...found.values()], moving };
+    }
+    /**
+     * Delete these records and let go of every file in them. The second half
+     * of a recursive delete, run only once the subtree is detached. Cannot
+     * throw: every step is best-effort, because unreachable is not fatal.
+     *
+     * With `elsewhere` - what the rest of the tree still names, read because
+     * something here is half of an interrupted move - a record still named
+     * elsewhere is kept, and so is a file.
+     */
+    async purge(dirs, elsewhere, keepContent = false) {
+        const gone = dirs.filter((dir) => !elsewhere?.dirs.has(dir.id));
+        // By file id: two entries with one id are one file, holding one
+        // reference to its content, however many directories name it.
+        const files = new Map();
+        for (const dir of gone) {
+            for (const [, entry] of followable(dir)) {
+                if (entry.kind !== "file")
+                    continue;
+                let copies = files.get(entry.id);
+                if (!copies)
+                    files.set(entry.id, (copies = []));
+                copies.push({ dir, entry });
+            }
+        }
+        await this.letGo(files, elsewhere, keepContent);
+        for (const dir of gone) {
+            this.cache.delete(dir.id);
+            await this.deps.store.delete(dirKey(dir.id)).catch(() => { });
+        }
+        if (!elsewhere)
+            return;
+        for (const dir of gone) {
+            for (const [, entry] of followable(dir))
+                if (entry.moving === true)
+                    await this.settle(entry.id, elsewhere);
+        }
+    }
+    /**
+     * Unmark what is left of an interrupted move once a delete has removed
+     * the other copy. Marked, a file keeps every version that falls off its
+     * history, because the other copy might hold it - for good, once there
+     * is no other copy - and every delete of the entry, or of a directory
+     * above it, reads the whole tree. Only when exactly one marked copy is
+     * left: more, and they are still shared. Best-effort, like everything
+     * after a detach; failing, it stays marked, which costs only that.
+     */
+    async settle(id, elsewhere) {
+        const holding = elsewhere.marked.get(id);
+        if (holding?.length !== 1)
             return;
-        seen.add(dir.id);
-        for (const entry of Object.values(dir.node.entries)) {
-            if (entry.kind === "dir") {
-                await this.purge(await this.openDirById(entry.id, fromBase64(entry.key)), seen);
+        try {
+            // Opened again: this delete may have written to it since the tree was read.
+            const dir = await this.openDirById(holding[0].id, holding[0].key);
+            const name = Object.keys(dir.node.entries).find((n) => dir.node.entries[n].id === id && dir.node.entries[n].moving === true);
+            if (name !== undefined)
+                await this.mutate(dir, (node) => void (node.entries[name] = unmarked(node.entries[name])));
+        }
+        catch {
+            // It stays marked.
+        }
+    }
+    /**
+     * Let go of files that are leaving the tree: each one's content, every
+     * version its history holds, and the history record. Best-effort, like
+     * everything after a detach.
+     *
+     * A file id still named elsewhere is one file with two names, left by an
+     * interrupted move: its content and history belong to the name that is
+     * staying, and all that changes hands is the key its history opens with.
+     * `keepContent` keeps every file's content and drops only its history
+     * record, as a checkout needs.
+     */
+    async letGo(files, elsewhere, keepContent = false) {
+        for (const [id, copies] of files) {
+            const keys = copies.map(({ dir }) => dir.key);
+            const staying = elsewhere?.files.get(id);
+            if (staying)
+                await this.rekeyHistory(id, keys, staying.key).catch(() => { });
+            else if (keepContent)
+                await this.deps.store.delete(historyKey(id)).catch(() => { });
+            else
+                await this.releaseFile(id, copies);
+        }
+    }
+    /**
+     * What the tree still names with one entry left out: every directory
+     * record, and every file id with a directory that holds it. Null when
+     * part of the tree cannot be read or followed, so the answer is unknown.
+     */
+    async namedElsewhere(dir, name) {
+        try {
+            const named = await this.references({ dir, name });
+            return named.unknown ? null : named;
+        }
+        catch (err) {
+            if (err instanceof VfsCorruptRecordError)
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Everything reachable from the root: every directory record's id and
+     * key, and every file id with a directory that names it - following the
+     * entries hidden only for their name, which still reference what they
+     * point at. `skip` leaves one entry out: one about to be detached.
+     *
+     * Fetches up to WALK_CONCURRENCY records at once, each record once
+     * however often it is named. Throws VfsCorruptRecordError for a record a
+     * path reaches that cannot be read, unless `lenient`. `unknown` counts
+     * what could not be followed at all: an entry this version cannot read,
+     * and a record behind an unusable name that does not open - which no path
+     * can reach, and so no recursive delete can remove - or, `lenient`, any
+     * record that does not open.
+     */
+    async references(skip, opts = {}) {
+        const root = await this.root();
+        const dirs = new Set([root.id]);
+        const keys = [];
+        const files = new Map();
+        const marked = new Map();
+        let unknown = 0;
+        let sinceTurn = 0;
+        const pending = [];
+        const scan = (dir, path) => {
+            keys.push(dir.key);
+            unknown += unfollowable(dir);
+            for (const [name, entry] of followable(dir)) {
+                if (skip && dir.id === skip.dir && name === skip.name)
+                    continue;
+                sinceTurn++;
+                if (entry.moving === true) {
+                    let holding = marked.get(entry.id);
+                    if (!holding)
+                        marked.set(entry.id, (holding = []));
+                    holding.push(dir);
+                }
+                if (entry.kind === "file") {
+                    if (!files.has(entry.id))
+                        files.set(entry.id, dir);
+                }
+                else if (!dirs.has(entry.id)) {
+                    dirs.add(entry.id);
+                    // No path is ever built from an unusable name.
+                    const at = name === null || path === undefined ? undefined : join(path, name);
+                    pending.push({ entry, path: at, named: name !== null });
+                }
             }
-            else {
-                await this.releaseFile(dir, entry);
+        };
+        scan(root, "/");
+        const inFlight = new Set();
+        let failure = null;
+        let next = 0;
+        while (!failure && (next < pending.length || inFlight.size)) {
+            while (next < pending.length && inFlight.size < WALK_CONCURRENCY) {
+                const { entry, path, named } = pending[next++];
+                const task = this.openDirById(entry.id, fromBase64(entry.key), path)
+                    .then((child) => scan(child, path), (err) => {
+                    // Behind a name no path can reach, an unreadable
+                    // record is one more thing whose references are
+                    // unknown, and not followed.
+                    if ((opts.lenient || !named) && err instanceof VfsCorruptRecordError)
+                        unknown++;
+                    else
+                        failure ??= { err };
+                })
+                    .finally(() => inFlight.delete(task));
+                inFlight.add(task);
+            }
+            await Promise.race(inFlight);
+            // Once records are cached nothing here waits: let the rest of the
+            // program run, as a walk does.
+            if (sinceTurn >= YIELD_EVERY) {
+                sinceTurn = 0;
+                await nextTurn();
             }
         }
-        this.cache.delete(dir.id);
-        await this.deps.store.delete(dirKey(dir.id)).catch(() => { });
+        if (failure)
+            throw failure.err;
+        return { dirs, keys, files, marked, unknown };
     }
     /**
      * Deep-copy an entry. Files reuse their manifest (no bytes move); each
      * directory gets a fresh id and key, so the copy is independent of the
      * original — writing into one must never appear in the other.
+     *
+     * `at` is the entry's SOURCE path, and `depth` how many directories deep
+     * from the root the copy of it will be. With `run.write` false this is the
+     * dry run: every check, no reference taken and no record stored.
      */
-    async cloneEntry(entry, seen = new Set()) {
+    async cloneEntry(entry, at, run, ancestors, depth) {
         if (entry.kind === "file") {
             // Same bytes, second owner: take a reference so deleting either one
             // leaves the other readable.
-            await this.deps.content.retain(entry.manifest);
+            if (run.write)
+                await this.deps.content.retain(entry.manifest);
             return { kind: "file", id: newId(), manifest: entry.manifest, size: entry.size, mtime: Date.now(), versions: 0 };
         }
         // The most expensive walker to leave unguarded: it mints a NEW id, key
         // and stored record at every level, so a cyclic tree does not merely
         // hang - it writes records to the store, and to the user's bill, in an
         // unbounded loop.
-        if (seen.has(entry.id) || seen.size > MAX_DEPTH) {
-            throw new VfsConflictError("VFS: refusing to copy a directory that contains a cycle");
-        }
-        seen.add(entry.id);
-        const source = await this.openDirById(entry.id, fromBase64(entry.key));
+        //
+        // Separate guards, because they catch different shapes. A directory
+        // that is one of its own ANCESTORS is a cycle. Depth is counted per
+        // branch, at the destination, from the root, as for any write - the
+        // old guard compared the total number of directories seen against the
+        // depth limit, and so refused any ordinary tree with more than 64. The budgets, shared by the whole copy, bound a tree
+        // that fans out into the same subtree without ever looping; they are
+        // the walk's ceilings, so a tree too big to walk is not copied into a
+        // second one. And a directory reached in more than MAX_SHARED places
+        // is refused outright, because below the budgets that fan-out still
+        // turns a few records into a vast number of writes. A subtree
+        // reachable twice is copied twice, as it should be.
+        if (hasAncestor(ancestors, entry.id)) {
+            throw new VfsConflictError("refusing to copy a directory that contains a cycle");
+        }
+        if (depth > MAX_DEPTH) {
+            // About the destination, like any write refused for depth: the
+            // source is fine where it is, so it is neither named nor offered
+            // up for deleting.
+            throw new VfsLimitError("depth", MAX_DEPTH, run.to, run.to + at.slice(run.from.length), "writing");
+        }
+        const reached = (run.reached.get(entry.id) ?? 0) + 1;
+        if (reached > MAX_SHARED)
+            throw new VfsLimitError("shared", MAX_SHARED, run.from, at, "copying");
+        run.reached.set(entry.id, reached);
+        const source = await this.openDirById(entry.id, fromBase64(entry.key), at);
+        // Only visible entries: an unusable name or an unreadable entry is not
+        // carried into a fresh record. `readRecord` has set both aside already.
+        const children = Object.entries(source.node.entries);
+        run.entries -= children.length;
+        if (run.entries < 0)
+            throw new VfsLimitError("entries", this.maxEntries, run.from, at, "copying");
+        for (const [name] of children)
+            run.pathChars -= childPathLength(at, name);
+        if (run.pathChars < 0)
+            throw new VfsLimitError("pathChars", this.maxPathChars, run.from, at, "copying");
+        // The dry run, with every record cached, waits on nothing - like a
+        // walk, it lets the rest of the program run every so often.
+        run.sinceTurn += children.length;
+        if (run.sinceTurn >= YIELD_EVERY) {
+            run.sinceTurn = 0;
+            await nextTurn();
+        }
+        const inner = { id: entry.id, up: ancestors };
         const clone = { kind: "dir", id: newId(), key: toBase64(newDirKey()), mtime: Date.now() };
-        const node = { v: 1, entries: {}, mtime: Date.now() };
-        for (const [name, child] of Object.entries(source.node.entries)) {
-            // Names are validated on read everywhere else; a copy must not be
-            // the way a bad one is carried into a fresh record.
-            if (!isSafeName(name)) {
-                this.warn(`skipping entry with an unusable name while copying`);
-                continue;
-            }
-            node.entries[name] = await this.cloneEntry(child, seen);
+        const node = { v: 1, entries: emptyEntries(), mtime: Date.now() };
+        for (const [name, child] of children) {
+            node.entries[name] = await this.cloneEntry(child, join(at, name), run, inner, depth + 1);
         }
-        const open = { id: clone.id, key: fromBase64(clone.key), node };
+        if (!run.write)
+            return clone;
+        const open = { id: clone.id, key: fromBase64(clone.key), node, hidden: Object.create(null) };
         await this.deps.store.put(dirKey(open.id), await seal(open.key, node));
         this.cache.set(open.id, Promise.resolve(open));
         return clone;
     }
     /**
-     * Let go of a file's bytes: the current manifest and every retained
-     * version, then the history record itself.
+     * Let go of one file's bytes: its content, every version its history
+     * retains, and the history record itself.
+     *
+     * Each distinct manifest once. `copies` is every entry naming the file -
+     * two after an interrupted move, which may by now hold different
+     * versions - and `restore` puts a version back without taking a second
+     * reference, so its manifest is in the entry and in the history both.
+     * Releasing per mention released one reference twice, and so freed bytes
+     * a copy elsewhere, holding its own reference, still needed.
      */
-    async releaseFile(parent, entry) {
-        const record = await this.readHistory(parent, entry.id).catch(() => ({ v: 1, versions: [] }));
-        const manifests = [entry.manifest, ...record.versions.map((v) => v.manifest)];
-        for (const manifest of manifests)
+    async releaseFile(id, copies) {
+        const record = await this.openHistory(id, copies.map(({ dir }) => dir.key)).catch(() => null);
+        const manifests = new Map();
+        const versions = readableHistory(record?.value).record.versions;
+        for (const manifest of [...copies.map(({ entry }) => entry.manifest), ...versions.map((version) => version.manifest)]) {
+            if (!manifests.has(manifest.id))
+                manifests.set(manifest.id, manifest);
+        }
+        for (const manifest of manifests.values())
             await this.deps.content.release(manifest).catch(() => { });
-        await this.deps.store.delete(historyKey(entry.id)).catch(() => { });
+        await this.deps.store.delete(historyKey(id)).catch(() => { });
     }
-    async readHistory(parent, fileId) {
-        const raw = await this.deps.store.get(historyKey(fileId));
-        return (await unseal(parent.key, raw)) ?? { v: 1, versions: [] };
+    /**
+     * A file's history record, opened with the first of `keys` that opens
+     * it, and that key. Null when there is none, or none of them does.
+     */
+    async openHistory(id, keys) {
+        const raw = await this.deps.store.get(historyKey(id));
+        if (raw === null || raw === undefined)
+            return null;
+        const opened = await openWithAny(raw, keys);
+        return "problem" in opened ? null : opened;
     }
-    /** Push `entry` onto its history record. Returns the new version count. */
-    async pushHistory(parent, fileId, entry) {
-        const record = await this.readHistory(parent, fileId);
+    /**
+     * Seal a file's history with the key of the directory that holds it now.
+     *
+     * A history record is sealed with its directory's key, so a file moved
+     * to another directory carried a history its new directory could not
+     * open: every read of it, and every write to the file, failed from then
+     * on. Nothing to do when there is no history, when it opens with `to`
+     * already, or when none of the keys opens it.
+     */
+    async rekeyHistory(id, from, to) {
+        const opened = await this.openHistory(id, [to, ...from]);
+        if (!opened || opened.key === to)
+            return;
+        await this.deps.store.put(historyKey(id), await seal(to, readableHistory(opened.value).record));
+    }
+    /**
+     * The history of the file `entry` names as `name` in `parent`, and the
+     * key to seal it with from now on.
+     *
+     * A history is sealed with its directory's key - usually. The two halves
+     * of an interrupted move share one history, sealed with ONE of their
+     * directories' keys, and a file moved between directories by a version
+     * before `rename` re-sealed it still has its old directory's. So when the
+     * directory's own key does not open it, every key in the tree is tried,
+     * the other half's first: a read of the whole tree, and only then. It
+     * need not be read in full, or understood - an entry this version cannot
+     * follow may hide a key, but a key that opens the record is proof
+     * enough. Found, it is re-sealed with this directory's key, so the search
+     * is made once - except for half of a move, which keeps the key that
+     * opened it and so keeps working for both halves.
+     *
+     * No record, or a value that is not a sealed record at all, is an empty
+     * history, as it always was. One that no key opens is thrown on, with a
+     * message rather than a bare decryption error: writing an empty history
+     * over it would lose every version it holds.
+     */
+    async readHistory(parent, name, entry, path) {
+        const raw = await this.deps.store.get(historyKey(entry.id));
+        if (!isObject$1(raw) || typeof raw.iv !== "string" || typeof raw.ct !== "string") {
+            return { record: { v: 1, versions: [] }, key: parent.key };
+        }
+        let opened = await openWithAny(raw, [parent.key]);
+        let found = false;
+        if ("problem" in opened) {
+            const named = await this.references({ dir: parent.id, name }, { lenient: true });
+            const other = named.files.get(entry.id)?.key;
+            const keys = named.keys.filter((key) => key !== parent.key && key !== other);
+            const retry = await openWithAny(raw, other ? [other, ...keys] : keys);
+            if ("problem" in retry) {
+                throw new VfsConflictError(`the version history of ${path} cannot be read: ${opened.problem}. ` +
+                    "Nothing has been changed; a copy of the file starts a history of its own");
+            }
+            opened = retry;
+            found = true;
+        }
+        const { record, dropped } = readableHistory(opened.value);
+        if (dropped)
+            this.warn(`ignoring ${dropped} version${dropped === 1 ? "" : "s"} of ${path} this version cannot read`);
+        if (!found || entry.moving === true)
+            return { record, key: opened.key };
+        // Best-effort: failing, the next read searches again.
+        await this.deps.store.put(historyKey(entry.id), await seal(parent.key, record)).catch(() => { });
+        return { record, key: parent.key };
+    }
+    /**
+     * Push `entry` onto its history record. Returns the new version count.
+     * `next` is the manifest the entry will hold once the caller has written
+     * it.
+     */
+    async pushHistory(parent, name, entry, path, next) {
+        const { record, key } = await this.readHistory(parent, name, entry, path);
         record.versions.unshift({ manifest: entry.manifest, size: entry.size, mtime: entry.mtime });
         // Bounded, because this is a single stored value. Unchanged chunks are
         // deduped by the content-addressed shard store, so the cost of keeping
@@ -13614,9 +15000,26 @@ class VfsNamespace {
         record.versions = record.versions.slice(0, this.historyLimit);
         // A version that falls off the end is unreachable — release its shards
         // or the cap bounds the record's size while the storage grows forever.
-        for (const v of evicted)
-            await this.deps.content.release(v.manifest).catch(() => { });
-        await this.deps.store.put(historyKey(fileId), await seal(parent.key, record));
+        //
+        // Unless something still names it. `restore` puts a version back
+        // without a reference of its own, so a file holds ONE reference per
+        // distinct manifest however often its entry and history name it - see
+        // `releaseFile`. Releasing per mention freed the version a restore
+        // was bringing back, when it was the one pushed off the end, and a
+        // version the history still listed, when an older mention of it went.
+        // Half of an interrupted move lets go of nothing here: the other half
+        // shares this history, its entry may hold any of these, and finding it
+        // means reading the whole tree. A leak is the safe way to be wrong.
+        if (entry.moving !== true) {
+            const named = new Set([next.id, ...record.versions.map((version) => version.manifest.id)]);
+            for (const { manifest } of evicted) {
+                if (named.has(manifest.id))
+                    continue;
+                named.add(manifest.id); // and each once
+                await this.deps.content.release(manifest).catch(() => { });
+            }
+        }
+        await this.deps.store.put(historyKey(entry.id), await seal(key, record));
         return record.versions.length;
     }
 }
@@ -13625,9 +15028,9 @@ function toStat(path, name, entry) {
         path,
         name,
         kind: entry.kind,
-        size: entry.kind === "file" ? entry.size : 0,
-        mtime: entry.mtime,
-        versions: entry.kind === "file" ? (entry.versions ?? 0) : 0,
+        size: entry.kind === "file" ? asCount(entry.size) : 0,
+        mtime: asTime(entry.mtime),
+        versions: entry.kind === "file" ? asCount(entry.versions) : 0,
     };
 }
 /** Directories first, then alphabetical — what every file explorer does. */
@@ -13818,6 +15221,66 @@ class VcsError extends Error {
     }
 }
 
+/** What a hash looks like: SHA-256, lowercase hex. Anything else is not an address. */
+const HASH = /^[0-9a-f]{64}$/;
+/**
+ * What a branch name looks like - checked when a branch is created, and on
+ * every read of one. HEAD, the branch list and MERGE are not hashed, so
+ * anything holding the seed can put any name in them, and the names are
+ * printed by everything that shows a repository's state.
+ *
+ * At most 200 characters, because a name is also a store key -
+ * `vcs/<slug>/refs/<name>` - and the personal space answers a key past 2048
+ * bytes with a server error: a planted HEAD naming a longer branch turned
+ * every status, log and commit into a bare HttpError.
+ */
+const BRANCH = /^[A-Za-z0-9][A-Za-z0-9._\/-]{0,199}$/;
+const isHash = (value) => typeof value === "string" && HASH.test(value);
+const isBranch = (value) => typeof value === "string" && BRANCH.test(value);
+/** A JSON object, as opposed to null, an array or a scalar. */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Why a value is not a commit this version can read, or null when it is.
+ *
+ * A commit can be written by anything holding the seed and still match its
+ * hash, so matching proves nothing about its shape. Every reader takes these
+ * fields for granted: parents are walked as an array of addresses, `at` is
+ * sorted on, and message and author are handed to whatever prints them.
+ */
+function commitProblem(value) {
+    if (!isObject(value) || value.v !== 1)
+        return "it is not a commit this version can read";
+    if (!isHash(value.tree))
+        return "its tree is not an object hash";
+    if (!Array.isArray(value.parents) || !value.parents.every(isHash)) {
+        return "its parents are not a list of object hashes";
+    }
+    if (typeof value.message !== "string" || typeof value.author !== "string")
+        return "its message or author is not text";
+    // A time a Date can hold: `vcs log` prints it with toISOString, which
+    // throws on 1e300, and commits cannot be changed.
+    if (typeof value.at !== "number" || !(Math.abs(value.at) <= MAX_TIME))
+        return "its time is not a time";
+    return null;
+}
+/**
+ * Is this a tree entry the walkers can follow?
+ *
+ * Tree objects can be written by anything holding the seed, so a hash check
+ * proves only that the object is what its address says - not that it is a
+ * sensible tree. An unknown kind, a file with no manifest to read or compare,
+ * or a subtree "hash" that is not a hash is skipped; a skipped entry is the same
+ * outcome as someone deleting it.
+ */
+function readableTreeEntry(value) {
+    if (!isObject(value))
+        return false;
+    if (value.kind === "tree")
+        return typeof value.hash === "string" && HASH.test(value.hash);
+    return value.kind === "file" && isObject(value.manifest) && typeof value.manifest.id === "string";
+}
 /** A project's repository. One per `/apps/<slug>`. */
 /**
  * Types never worth attempting a three-way merge on.
@@ -13845,27 +15308,36 @@ function looksTextual(bytes) {
         return false;
     }
 }
-/** Compare two path → entry maps into a change list. */
-function comparePaths(before, after) {
-    const changes = [];
-    for (const [path, entry] of after) {
-        const was = before.get(path);
-        if (!was)
-            changes.push({ path, kind: "added" });
-        else if (was.manifest.id !== entry.manifest.id)
-            changes.push({ path, kind: "modified" });
-    }
-    for (const path of before.keys())
-        if (!after.has(path))
-            changes.push({ path, kind: "removed" });
-    return changes.sort((a, b) => (a.path < b.path ? -1 : 1));
-}
+/** Changes in path order, as `status` and `diff` return them. */
+const byPath = (a, b) => (a.path < b.path ? -1 : 1);
 class Repo {
     slug;
     deps;
+    maxEntries;
+    maxPathChars;
+    /**
+     * How many directories deep below the project a tree may nest. The
+     * working tree may be written MAX_DEPTH directories below the root, and
+     * the project itself is some of those: a deeper tree would check out into
+     * something no walk will read, and `status` - and every checkout after,
+     * which walks the tree first - would throw from then on.
+     */
+    maxTreeDepth;
     constructor(slug, deps) {
         this.slug = slug;
         this.deps = deps;
+        // Exactly one usable name. The working tree is `/apps/<slug>` and the
+        // repository key is derived from the slug, so `demo/` was a second
+        // repository over the same files - and, because commit() filed the
+        // walk's output under normalised paths and looked it up under the raw
+        // one, a repository whose commits were EMPTY trees. Checking one of
+        // those out deleted the project. Rejected rather than normalised: the
+        // SDK should not guess which project was meant.
+        if (!isSafeName(slug))
+            throw new VcsError(`"${printable(slug, 64)}" is not a project name`);
+        this.maxEntries = deps.limits?.entries ?? DEFAULT_MAX_ENTRIES;
+        this.maxPathChars = deps.limits?.pathChars ?? DEFAULT_MAX_PATH_CHARS;
+        this.maxTreeDepth = MAX_DEPTH - segments(this.root).length;
     }
     get root() {
         return `/apps/${this.slug}`;
@@ -13877,45 +15349,248 @@ class Repo {
         // Content-addressed, so re-writing an identical object is a no-op —
         // worth skipping because an unchanged directory is written on every
         // commit that touches any of its siblings.
+        //
+        // Skipped only when what is there really IS this object. The next
+        // tree's hash is predictable to anyone who can read the project, so a
+        // forgery can be planted at it in advance; trusting mere presence would
+        // make that tree unwritable for good, every later commit of the same
+        // content pointing at the forgery.
         const existing = await this.deps.store.get(objectKey(this.slug, hash));
-        if (existing)
+        if (existing && (await this.holds(existing, hash)))
             return { hash, created: false };
         await this.deps.store.put(objectKey(this.slug, hash), await seal(await this.deps.key(), value));
         return { hash, created: true };
     }
+    /** Does this stored record open to an object with this hash? */
+    async holds(raw, hash) {
+        try {
+            const value = await unseal(await this.deps.key(), raw);
+            return value !== null && (await hashObject(value)) === hash;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Fetch an object, and prove it is the one that was asked for.
+     *
+     * Content addressing is only a guarantee if the address is checked. Without
+     * this a stored object could claim any hash - including its own, so a tree
+     * could contain itself and `status` would follow it for ever. Every object
+     * this repository has ever written verifies: `put` hashes exactly the value
+     * it seals, `canonical` is independent of key order and drops `undefined`
+     * exactly as JSON does, and hashing has never been versioned.
+     */
     async get(hash) {
+        // Checked before it becomes a storage key: it may have come out of a
+        // tree or commit that something else wrote.
+        if (typeof hash !== "string" || !HASH.test(hash)) {
+            throw new VcsError("a reference in this repository is not an object hash");
+        }
+        const short = hash.slice(0, 8);
         const raw = await this.deps.store.get(objectKey(this.slug, hash));
-        const value = raw ? await unseal(await this.deps.key(), raw) : null;
-        if (!value)
-            throw new VcsError(`object ${hash.slice(0, 8)} is missing from this repository`);
+        if (raw === null || raw === undefined)
+            throw new VcsError(`object ${short} is missing from this repository`);
+        // Opened the way the working tree opens a directory record: a value
+        // that is not an envelope, does not decrypt, or is not JSON is named,
+        // rather than surfacing as a bare DOMException or SyntaxError.
+        let value;
+        try {
+            value = await openSealed(await this.deps.key(), raw);
+        }
+        catch (err) {
+            if (err instanceof SealedRecordError)
+                throw new VcsError(`object ${short} cannot be read: ${err.message}`);
+            throw err;
+        }
+        if (value === null)
+            throw new VcsError(`object ${short} is missing from this repository`);
+        let actual;
+        try {
+            actual = await hashObject(value);
+        }
+        catch (err) {
+            // JSON.parse takes nesting that hashing's recursion cannot.
+            if (err instanceof RangeError)
+                throw new VcsError(`object ${short} cannot be read: it is nested too deeply`);
+            throw err;
+        }
+        if (actual !== hash) {
+            throw new VcsError(`object ${short} does not match its hash: this repository did not write it, or it is corrupt`);
+        }
         return value;
     }
+    /** A commit, checked to be one. See `commitProblem`. */
+    async readCommit(hash) {
+        const value = await this.get(hash);
+        const problem = commitProblem(value);
+        if (problem)
+            throw new VcsError(`object ${hash.slice(0, 8)} is not a commit this version can read: ${problem}`);
+        return value;
+    }
+    /**
+     * Start a traversal of history: a budget shared by every branch of it, and
+     * a cache of the tree objects it has fetched.
+     *
+     * The cache matters for the same reason the budget does. Identical
+     * subtrees are one object, so a tree of honest-but-hostile shape is a
+     * handful of fetches and a vast number of paths; caching keeps it to the
+     * handful, and the budget stops the paths. It caches OBJECTS, never output
+     * - each name a shared subtree appears at is still listed.
+     */
+    treeWalk() {
+        const fetched = new Map();
+        let budget = this.maxEntries;
+        let chars = this.maxPathChars;
+        const refuse = (what) => new VcsError(`stopped reading history: ${what}, which no real project does - ` +
+            "the repository may have been tampered with");
+        return {
+            tree: (hash) => {
+                let hit = fetched.get(hash);
+                if (!hit)
+                    fetched.set(hash, (hit = this.readTree(hash)));
+                return hit;
+            },
+            spend: (prefix, names) => {
+                const turn = Math.floor(budget / YIELD_EVERY);
+                for (const name of names) {
+                    budget -= 1;
+                    chars -= prefix.length + 1 + name.length;
+                }
+                if (budget < 0)
+                    throw refuse(`it holds more than ${this.maxEntries} entries`);
+                if (chars < 0)
+                    throw refuse(`its paths add up to more than ${this.maxPathChars} characters`);
+                return Math.floor(budget / YIELD_EVERY) !== turn;
+            },
+            descend: (depth) => {
+                if (depth > this.maxTreeDepth)
+                    throw refuse(`it is nested more than ${this.maxTreeDepth} directories deep`);
+            },
+        };
+    }
+    /**
+     * A tree object's entries, checked and ready to walk.
+     *
+     * Returned in a null-prototype map, so a name like `constructor` is looked
+     * up as an entry and not found as an inherited property.
+     */
+    async readTree(hash) {
+        const tree = await this.get(hash);
+        if (!isObject(tree) || tree.v !== 1 || !isObject(tree.entries)) {
+            throw new VcsError(`object ${hash.slice(0, 8)} is not a tree this version can read`);
+        }
+        const entries = Object.create(null);
+        let skipped = 0;
+        for (const [name, entry] of Object.entries(tree.entries)) {
+            // The same name rule the working tree uses. A name is about to
+            // become a path - `../x` would be written outside the project on
+            // checkout - and the hash check says nothing about whether it is safe.
+            if (isSafeName(name) && readableTreeEntry(entry))
+                entries[name] = entry;
+            else
+                skipped++;
+        }
+        if (skipped) {
+            const what = `${skipped} unreadable entr${skipped === 1 ? "y" : "ies"}`;
+            console.warn(`[muhkoo/vcs] ignoring ${what} in tree ${hash.slice(0, 8)}`);
+        }
+        return entries;
+    }
     // ---- refs ---------------------------------------------------------------
+    /**
+     * A record that is not an object - HEAD, a branch ref, the branch list,
+     * MERGE - opened. Null when there is none; `problem` when there is one
+     * that does not open. What is inside is the caller's to check.
+     */
+    async openRecord(key) {
+        const raw = await this.deps.store.get(key);
+        if (raw === null || raw === undefined)
+            return null;
+        try {
+            return { value: await openSealed(await this.deps.key(), raw) };
+        }
+        catch (err) {
+            if (err instanceof SealedRecordError)
+                return { problem: err.message };
+            throw err;
+        }
+    }
     async head() {
-        const raw = await this.deps.store.get(headKey(this.slug));
-        const value = raw ? await unseal(await this.deps.key(), raw) : null;
-        return value ?? { branch: DEFAULT_BRANCH };
+        const record = await this.openRecord(headKey(this.slug));
+        if (!record)
+            return { branch: DEFAULT_BRANCH };
+        if ("value" in record) {
+            const { value } = record;
+            if (isObject(value) && !Object.hasOwn(value, "detached") && isBranch(value.branch)) {
+                return { branch: value.branch };
+            }
+            if (isObject(value) && !Object.hasOwn(value, "branch") && isHash(value.detached)) {
+                return { detached: value.detached };
+            }
+        }
+        // Checking out a branch or a commit with discardChanges writes a new
+        // HEAD without reading this one.
+        throw new VcsError(`HEAD cannot be read${"problem" in record ? `: ${record.problem}` : ""}; ` +
+            "check out a branch or a commit, discarding changes, to replace it");
     }
     async setHead(head) {
         await this.deps.store.put(headKey(this.slug), await seal(await this.deps.key(), head));
     }
     async readRef(name) {
-        const raw = await this.deps.store.get(refKey(this.slug, name));
-        return raw ? await unseal(await this.deps.key(), raw).then((v) => v?.commit ?? null) : null;
+        const ref = await this.refState(name);
+        if (ref !== "unreadable")
+            return ref;
+        throw new VcsError(`branch "${printable(name, 64)}" cannot be read: it does not name a commit; ` +
+            "create the branch again, at a commit, to replace it");
+    }
+    /** A branch's commit, null when there is no such branch, or "unreadable". */
+    async refState(name) {
+        const record = await this.openRecord(refKey(this.slug, name));
+        if (!record)
+            return null;
+        if ("value" in record && isObject(record.value) && isHash(record.value.commit))
+            return record.value.commit;
+        return "unreadable";
     }
     async writeRef(name, commit) {
         await this.deps.store.put(refKey(this.slug, name), await seal(await this.deps.key(), { commit }));
         // The personal space has no prefix listing, so branches are tracked in
         // an index. Kept append-only-ish: losing a name here loses the branch.
-        const names = new Set(await this.branches());
+        // An index that cannot be read at all is replaced rather than left to
+        // block every branch from now on; its names were lost already.
+        const index = await this.readIndex();
+        if (index === "unreadable")
+            console.warn("[muhkoo/vcs] replacing a branch list this version cannot read");
+        const names = new Set(index === "unreadable" ? [] : index);
         names.add(name);
         await this.deps.store.put(refsIndexKey(this.slug), await seal(await this.deps.key(), { names: [...names].sort() }));
     }
     /** Every branch name in this repository. */
     async branches() {
-        const raw = await this.deps.store.get(refsIndexKey(this.slug));
-        const value = raw ? await unseal(await this.deps.key(), raw) : null;
-        return value?.names ?? [];
+        const index = await this.readIndex();
+        if (index === "unreadable") {
+            throw new VcsError("the list of branches cannot be read; creating a branch replaces it");
+        }
+        return index;
+    }
+    /**
+     * The branch list, less any name a branch could not have been created
+     * with - left out with a warning, like an unreadable entry in a tree, so
+     * one planted name does not hide every real one.
+     */
+    async readIndex() {
+        const record = await this.openRecord(refsIndexKey(this.slug));
+        if (!record)
+            return [];
+        if (!("value" in record) || !isObject(record.value) || !Array.isArray(record.value.names))
+            return "unreadable";
+        const names = record.value.names.filter(isBranch);
+        const skipped = record.value.names.length - names.length;
+        if (skipped) {
+            console.warn(`[muhkoo/vcs] ignoring ${skipped} branch name${skipped === 1 ? "" : "s"} this version would not accept`);
+        }
+        return names;
     }
     /** The commit HEAD resolves to, or null in an empty repository. */
     async current() {
@@ -13942,7 +15617,7 @@ class Repo {
         const pending = parents ? null : await this.pendingMerge();
         const resolved = parents ?? (pending ? [parent, pending.theirs] : parent ? [parent] : []);
         if (!parents && !pending && parent) {
-            const previous = await this.get(parent);
+            const previous = await this.readCommit(parent);
             // An empty commit is almost always a mistake — the user believes
             // they saved something they did not.
             if (previous.tree === tree)
@@ -13972,38 +15647,80 @@ class Repo {
     }
     /** The other side of a merge that stopped for conflicts, if any. */
     async pendingMerge() {
-        const raw = await this.deps.store.get(mergeKey(this.slug));
-        return raw ? await unseal(await this.deps.key(), raw) : null;
+        const record = await this.openRecord(mergeKey(this.slug));
+        if (!record)
+            return null;
+        if ("value" in record && isObject(record.value) && isHash(record.value.theirs) && isBranch(record.value.name)) {
+            return { theirs: record.value.theirs, name: record.value.name };
+        }
+        throw new VcsError(`the merge in progress cannot be read${"problem" in record ? `: ${record.problem}` : ""}; ` +
+            "abort the merge to clear it");
+    }
+    /**
+     * Give up on a merge that stopped for conflicts: the next commit is an
+     * ordinary one, with one parent. The working tree is left as it is,
+     * conflict markers and all. To put it back, switch to the current branch
+     * with `discardChanges` — not `checkout`, which always leaves HEAD
+     * detached, so later commits would stop moving the branch.
+     *
+     * Also the way out when the record of the merge cannot be read, which
+     * would otherwise stop every commit.
+     */
+    async abortMerge() {
+        await this.deps.store.delete(mergeKey(this.slug));
     }
-    /** Write a directory and everything under it, returning the tree's hash. */
+    /**
+     * Write a directory and everything under it, returning the tree's hash.
+     *
+     * Reads the working tree through ONE `walkEntries`, rather than listing
+     * each directory by path and recursing. The recursion had no guard at all:
+     * a directory record that names itself - which anything holding the seed
+     * can plant - sent `commit` down /loop/loop/loop/... for ever. The walk has
+     * the cycle guard, the budget and the depth ceiling, so a commit records
+     * exactly the tree `status` compares it against.
+     */
     async writeTree(path) {
-        const entries = {};
-        for (const entry of await this.deps.vfs.list(path)) {
-            if (entry.kind === "dir") {
-                entries[entry.name] = { kind: "tree", hash: await this.writeTree(entry.path) };
-            }
-            else {
-                const stat = await this.deps.vfs.statManifest(entry.path);
-                entries[entry.name] = { kind: "file", manifest: stat.manifest, size: entry.size };
+        // Each file's manifest comes with the walk. Looking every file up
+        // again by path, from the root down, cost a planted deep tree 30s of
+        // CPU per commit on top of a walk of under a second.
+        const byParent = new Map();
+        await this.deps.vfs.eachEntry(path, (stat, manifest) => {
+            const parent = dirname(stat.path);
+            let siblings = byParent.get(parent);
+            if (!siblings)
+                byParent.set(parent, (siblings = []));
+            siblings.push({ stat, manifest });
+        });
+        const write = async (dir) => {
+            // No prototype: a file named `__proto__` would otherwise set the
+            // map's prototype instead of becoming an entry, and be left out of
+            // the commit without a word.
+            const entries = Object.create(null);
+            for (const { stat, manifest } of byParent.get(dir) ?? []) {
+                if (!manifest)
+                    entries[stat.name] = { kind: "tree", hash: await write(stat.path) };
+                else
+                    entries[stat.name] = { kind: "file", manifest, size: stat.size };
             }
-        }
-        const { hash, created } = await this.put({ v: 1, entries });
-        // A NEW tree means this directory's contents are newly recorded, so the
-        // repository takes its own reference to their content. Without it, a
-        // later working-tree delete frees shards the commit still needs and the
-        // history becomes unreadable.
-        //
-        // Retaining per new tree rather than per changed FILE slightly
-        // over-retains — an unchanged file in a directory whose sibling changed
-        // gets a second reference. That errs towards keeping content, which is
-        // the correct direction to err in.
-        if (created) {
-            for (const entry of Object.values(entries)) {
-                if (entry.kind === "file")
-                    await this.deps.vfs.retainManifest(entry.manifest);
+            const { hash, created } = await this.put({ v: 1, entries });
+            // A NEW tree means this directory's contents are newly recorded, so the
+            // repository takes its own reference to their content. Without it, a
+            // later working-tree delete frees shards the commit still needs and the
+            // history becomes unreadable.
+            //
+            // Retaining per new tree rather than per changed FILE slightly
+            // over-retains — an unchanged file in a directory whose sibling changed
+            // gets a second reference. That errs towards keeping content, which is
+            // the correct direction to err in.
+            if (created) {
+                for (const entry of Object.values(entries)) {
+                    if (entry.kind === "file")
+                        await this.deps.vfs.retainManifest(entry.manifest);
+                }
             }
-        }
-        return hash;
+            return hash;
+        };
+        return write(path);
     }
     // ---- history ------------------------------------------------------------
     /** Commits reachable from HEAD, newest first. */
@@ -14021,7 +15738,7 @@ class Repo {
             if (seen.has(hash))
                 continue;
             seen.add(hash);
-            const commit = await this.get(hash);
+            const commit = await this.readCommit(hash);
             out.push({
                 hash,
                 message: commit.message,
@@ -14042,28 +15759,34 @@ class Repo {
      * content-addressing the trees.
      */
     async diff(fromHash, toHash) {
-        const from = fromHash ? (await this.get(fromHash)).tree : null;
-        const to = (await this.get(toHash)).tree;
+        const from = fromHash ? (await this.readCommit(fromHash)).tree : null;
+        const to = (await this.readCommit(toHash)).tree;
         const changes = [];
-        await this.diffTrees(from, to, "", changes);
-        return changes.sort((a, b) => (a.path < b.path ? -1 : 1));
+        await this.diffTrees(from, to, "", changes, this.treeWalk(), 0);
+        return changes.sort(byPath);
     }
-    async diffTrees(fromHash, toHash, prefix, out) {
+    async diffTrees(fromHash, toHash, prefix, out, walk, depth) {
         if (fromHash === toHash)
             return; // identical subtrees: nothing below can differ
-        const from = fromHash ? await this.get(fromHash) : { entries: {} };
-        const to = toHash ? await this.get(toHash) : { entries: {} };
-        for (const name of new Set([...Object.keys(from.entries), ...Object.keys(to.entries)])) {
-            const a = from.entries[name];
-            const b = to.entries[name];
+        if (depth)
+            walk.descend(depth);
+        const none = Object.create(null);
+        const from = fromHash ? await walk.tree(fromHash) : none;
+        const to = toHash ? await walk.tree(toHash) : none;
+        const names = new Set([...Object.keys(from), ...Object.keys(to)]);
+        if (walk.spend(prefix, names))
+            await nextTurn();
+        for (const name of names) {
+            const a = from[name];
+            const b = to[name];
             const path = `${prefix}/${name}`;
             if (a && b && a.kind === "tree" && b.kind === "tree") {
-                await this.diffTrees(a.hash, b.hash, path, out);
+                await this.diffTrees(a.hash, b.hash, path, out, walk, depth + 1);
             }
             else if (a?.kind === "tree" || b?.kind === "tree") {
                 // A directory replaced by a file (or the reverse) — recurse both
                 // sides so every affected path is reported, not just the name.
-                await this.diffTrees(a?.kind === "tree" ? a.hash : null, b?.kind === "tree" ? b.hash : null, path, out);
+                await this.diffTrees(a?.kind === "tree" ? a.hash : null, b?.kind === "tree" ? b.hash : null, path, out, walk, depth + 1);
                 if (a?.kind === "file")
                     out.push({ path, kind: "removed" });
                 if (b?.kind === "file")
@@ -14098,17 +15821,29 @@ class Repo {
     async status() {
         const head = await this.current();
         const before = head ? await this.filesOf(head) : new Map();
-        const after = await this.workingFiles();
-        return comparePaths(before, after);
-    }
-    /** The working tree as a path → entry map, mirroring `filesOf`. */
-    async workingFiles() {
-        const out = new Map();
-        for (const abs of await this.deps.vfs.walk(this.root)) {
-            const stat = await this.deps.vfs.statManifest(abs);
-            out.set(abs.slice(this.root.length), { kind: "file", manifest: stat.manifest, size: stat.size });
-        }
-        return out;
+        // The working tree is compared as it is walked, and a path found on
+        // both sides leaves `before` as it goes, so all that is held at once
+        // is the commit's map and the changes. Walking the whole tree into a
+        // list, mapping that into a second map and diffing the two held every
+        // path three times over: a hostile HEAD and working tree, each inside
+        // both budgets, needed about 600MB.
+        const changes = [];
+        await this.deps.vfs.eachEntry(this.root, ({ path: abs }, manifest) => {
+            if (!manifest)
+                return; // a directory
+            const path = abs.slice(this.root.length);
+            const was = before.get(path);
+            if (!was) {
+                changes.push({ path, kind: "added" });
+                return;
+            }
+            if (was.manifest.id !== manifest.id)
+                changes.push({ path, kind: "modified" });
+            before.delete(path);
+        });
+        for (const path of before.keys())
+            changes.push({ path, kind: "removed" });
+        return changes.sort(byPath);
     }
     /**
      * Turn what a person typed into a commit hash.
@@ -14134,7 +15869,7 @@ class Repo {
         for (const step of steps.match(/\^|~\d+/g) ?? []) {
             const back = step === "^" ? 1 : Number(step.slice(1));
             for (let i = 0; i < back; i++) {
-                const parents = (await this.get(hash)).parents;
+                const parents = (await this.readCommit(hash)).parents;
                 if (!parents.length)
                     throw new VcsError(`"${rev}" reaches past the first commit`);
                 hash = parents[0]; // first parent: the branch you were on
@@ -14148,7 +15883,9 @@ class Repo {
             return null;
         const keys = await this.deps.store.list();
         const wanted = objectKey(this.slug, prefix);
-        const hits = keys.filter((k) => k.startsWith(wanted));
+        // Only keys that could be objects: a stray key under the prefix would
+        // otherwise make every abbreviation of it "ambiguous".
+        const hits = keys.filter((k) => k.startsWith(wanted) && HASH.test(k.slice(objectKey(this.slug, "").length)));
         // Ambiguous is an error, not a coin toss — acting on the wrong commit
         // is exactly the kind of mistake version control exists to prevent.
         if (hits.length > 1)
@@ -14158,7 +15895,7 @@ class Repo {
         const hash = hits[0].slice(objectKey(this.slug, "").length);
         // Objects include trees; only a commit is a valid revision.
         const object = await this.get(hash);
-        return object && "tree" in object ? hash : null;
+        return isObject(object) && "tree" in object ? hash : null;
     }
     /**
      * Put one file back to the way it was in a commit.
@@ -14185,16 +15922,37 @@ class Repo {
     }
     /** Make the working tree match a commit, leaving HEAD alone. */
     async materialise(commitHash) {
-        const commit = await this.get(commitHash);
-        const wanted = new Map();
-        await this.collect(commit.tree, "", wanted);
+        // Collected in full BEFORE anything is touched, so a tree that cannot
+        // be read throws with the working tree exactly as it was.
+        const wanted = await this.filesOf(commitHash);
+        // The working tree, read once. The walk reads ahead, and leaves every
+        // record cached for the check below - which, run first, opened each
+        // directory by path one round trip at a time, and in a fresh process
+        // asked to discard changes (so with no status read before it) doubled
+        // the checkout.
+        const present = await this.deps.vfs.walkEntries(this.root);
+        // Every directory the commit needs, checked the same way. mkdir
+        // refuses a name held by an entry this version cannot read; found only
+        // when the write came, that refusal landed after the deletions below -
+        // files gone, HEAD unchanged, and a message about a directory that
+        // listings said was not there.
+        await this.deps.vfs.assertCreatable(new Set([...wanted.keys()].map((path) => dirname(this.abs(path)))));
         // Remove what the commit does not have BEFORE writing what it does —
         // otherwise a file replaced by a directory of the same name collides.
-        for (const abs of await this.deps.vfs.walk(this.root)) {
-            const path = abs.slice(this.root.length);
+        for (const entry of present) {
             // keepContent: history still references these manifests.
-            if (!wanted.has(path))
-                await this.deps.vfs.delete(abs, { keepContent: true }).catch(() => { });
+            if (entry.kind === "file" && !wanted.has(entry.path.slice(this.root.length))) {
+                await this.deps.vfs.delete(entry.path, { keepContent: true }).catch(() => { });
+            }
+        }
+        // And the reverse: a directory where the commit has a FILE. Nothing in
+        // it is wanted - a path cannot be both - so the loop above has emptied
+        // it of files, but it is still there, and the file cannot be written
+        // over it.
+        for (const entry of present) {
+            if (entry.kind === "dir" && wanted.has(entry.path.slice(this.root.length))) {
+                await this.deps.vfs.delete(entry.path, { recursive: true, keepContent: true });
+            }
         }
         for (const [path, entry] of wanted) {
             await this.deps.vfs.writeManifest(this.abs(path), entry.manifest, entry.size);
@@ -14204,22 +15962,35 @@ class Repo {
     abs(path) {
         return `${this.root}${path}`;
     }
-    async collect(treeHash, prefix, out) {
-        const tree = await this.get(treeHash);
-        for (const [name, entry] of Object.entries(tree.entries)) {
+    async collect(treeHash, prefix, out, walk, depth = 0) {
+        const entries = await walk.tree(treeHash);
+        const names = Object.keys(entries);
+        if (walk.spend(prefix, names))
+            await nextTurn();
+        for (const name of names) {
+            const entry = entries[name];
             const path = `${prefix}/${name}`;
-            if (entry.kind === "tree")
-                await this.collect(entry.hash, path, out);
-            else
+            if (entry.kind === "tree") {
+                walk.descend(depth + 1);
+                await this.collect(entry.hash, path, out, walk, depth + 1);
+            }
+            else {
                 out.set(path, entry);
+            }
         }
     }
     // ---- branches -----------------------------------------------------------
     /** Create a branch at a commit (HEAD by default). Does not switch to it. */
     async branch(name, at) {
-        if (!/^[A-Za-z0-9][A-Za-z0-9._\/-]*$/.test(name))
-            throw new VcsError(`"${name}" is not a usable branch name`);
-        if (await this.readRef(name))
+        if (!isBranch(name))
+            throw new VcsError(`"${printable(name, 64)}" is not a usable branch name`);
+        // A ref that cannot be read is replaced, as a branch list that cannot
+        // be read is: every command that uses the branch reads it first, so
+        // this is the only way that name ever works again.
+        const existing = await this.refState(name);
+        if (existing === "unreadable")
+            console.warn(`[muhkoo/vcs] replacing branch "${name}", which cannot be read`);
+        else if (existing)
             throw new VcsError(`branch "${name}" already exists`);
         const commit = at ?? (await this.current());
         if (!commit)
@@ -14301,14 +16072,28 @@ class Repo {
             this.filesOf(theirs),
         ]);
         const conflicts = [];
-        for (const path of new Set([...ourFiles.keys(), ...theirFiles.keys(), ...baseFiles.keys()])) {
-            const b = baseFiles.get(path);
-            const o = ourFiles.get(path);
-            const t = theirFiles.get(path);
-            const conflict = await this.settlePath(path, b, o, t);
+        let sinceTurn = 0;
+        const settle = async (path) => {
+            const conflict = await this.settlePath(path, baseFiles.get(path), ourFiles.get(path), theirFiles.get(path));
             if (conflict)
                 conflicts.push(conflict);
-        }
+            // A path both sides agree on waits on nothing, so this loop is
+            // otherwise one chain of continuations: over a second at the
+            // default budgets, with nothing else let in.
+            if (++sinceTurn === YIELD_EVERY) {
+                sinceTurn = 0;
+                await nextTurn();
+            }
+        };
+        // Every path either side has, once - ours, then theirs - without
+        // building a set of them: three sides of half a million paths each is
+        // already most of what a merge holds. A path only the base has was
+        // deleted on both sides, which settles to nothing.
+        for (const path of ourFiles.keys())
+            await settle(path);
+        for (const path of theirFiles.keys())
+            if (!ourFiles.has(path))
+                await settle(path);
         if (conflicts.length) {
             // Record what to merge with, so finishing is just: fix the files,
             // then commit. Losing this would silently produce a commit with one
@@ -14384,7 +16169,7 @@ class Repo {
                 if (ancestors.has(hash))
                     continue;
                 ancestors.add(hash);
-                queue.push(...(await this.get(hash)).parents);
+                queue.push(...(await this.readCommit(hash)).parents);
             }
         };
         await collect(a);
@@ -14397,15 +16182,15 @@ class Repo {
             seen.add(hash);
             if (ancestors.has(hash))
                 return hash;
-            queue.push(...(await this.get(hash)).parents);
+            queue.push(...(await this.readCommit(hash)).parents);
         }
         return null;
     }
     /** Every file in a commit, by path. */
     async filesOf(commitHash) {
-        const commit = await this.get(commitHash);
+        const commit = await this.readCommit(commitHash);
         const out = new Map();
-        await this.collect(commit.tree, "", out);
+        await this.collect(commit.tree, "", out, this.treeWalk());
         return out;
     }
 }
@@ -14436,6 +16221,7 @@ class VcsNamespace {
                     return deriveRepoKey(seed, slug);
                 },
                 author: this.deps.author,
+                limits: this.deps.limits,
             });
             this.repos.set(slug, repo);
         }
@@ -16349,5 +18135,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
   default: loadRsWasm
 });
 
-export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES$1 as AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, CircuitIntegrityError, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_BRANCH, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, DevicePairingError, DeviceRevokedError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PINNED_CIRCUIT_DIGESTS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, ROOT_ID, Ready, ReauthRequiredError, ReedSolomonCodec, Repo, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VFS_ROOT_INFO, VaultUnavailableError, VcsError, VcsNamespace, VfsConflictError, VfsLockedError, VfsNamespace, VfsNotFoundError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes, configureDeviceStore, createPasskeyWithPrf, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultRpId, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, dirKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, evaluatePasskeyPrf, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$2 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, headKey, historyKey, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, loadDeviceIdentity, log, manifestToStat, materializeRow, merge3, merge3Text, mergeKey, mergeMap, mergeMessage, mergeRegister, messageKey, objectKey, pack, padHandle, pairingVerificationCode, passkeyPrfCapable, passkeySupported, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, refKey, refsIndexKey, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$2 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
+export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES$1 as AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES$1 as AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, CircuitIntegrityError, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_BRANCH, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, DevicePairingError, DeviceRevokedError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PINNED_CIRCUIT_DIGESTS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, ROOT_ID, Ready, ReauthRequiredError, ReedSolomonCodec, Repo, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VFS_ROOT_INFO, VaultUnavailableError, VcsError, VcsNamespace, VfsConflictError, VfsCorruptRecordError, VfsLimitError, VfsLockedError, VfsNamespace, VfsNotFoundError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes, configureDeviceStore, createPasskeyWithPrf, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultRpId, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, dirKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, evaluatePasskeyPrf, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$2 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, headKey, historyKey, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, loadDeviceIdentity, log, manifestToStat, materializeRow, merge3, merge3Text, mergeKey, mergeMap, mergeMessage, mergeRegister, messageKey, objectKey, pack, padHandle, pairingVerificationCode, passkeyPrfCapable, passkeySupported, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, refKey, refsIndexKey, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$2 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map