@muhkoo/connect 0.15.0-alpha.1 → 0.15.0-alpha.3

package/dist/browser/index.js

@@ -5862,6 +5862,34 @@ class ReedSolomonCodec {
 const SHARD_BATCH_WINDOW_MS = 6;
 /** Hashes per batch. Must not exceed what the server will accept. */
 const SHARD_BATCH_MAX = 256;
+/**
+ * Expected response bytes per batch, which a batch is split to stay under.
+ *
+ * The server refuses a batch above 24 MiB of shard bytes with a 413, and the
+ * reads in a refused batch fail. Counting hashes alone, about 25 one-MiB
+ * shards in one window - a few large files read at once - drew it. This
+ * leaves the server's ceiling well clear.
+ */
+const SHARD_BATCH_BUDGET_BYTES = 16 * 1024 * 1024;
+/** An entry's JSON around its base64: the quoted hash, a colon, quotes and a comma, rounded up. */
+const SHARD_BATCH_ENTRY_BYTES = 128;
+/**
+ * What a shard adds to a batch's response: base64 is 4 bytes for every 3.
+ *
+ * A shard whose size the caller did not give counts as its entry alone, so
+ * reads without sizes batch by count, as they always have — kept for the
+ * pinned "many concurrent reads → ONE request" test
+ * (`shard-batching.test.ts`). No SDK read path is size-less today:
+ * `FileStorage.readChunk` always passes `shardSize`. The server reads and
+ * base64-encodes every shard before it checks the total
+ * (`ShardsController.ts`), so a very large size-less batch can fail with a
+ * 5xx before the client ever sees a 413. The split in `sendShardBatch` is a
+ * best-effort net for that case, not a guarantee.
+ */
+function batchCost(size) {
+    const bytes = typeof size === "number" && Number.isFinite(size) && size > 0 ? size : 0;
+    return Math.ceil(bytes / 3) * 4 + SHARD_BATCH_ENTRY_BYTES;
+}
 /** Decode base64 without `atob`'s per-character loop cost on large shards. */
 function bytesFromBase64(b64) {
     const binary = atob(b64);
@@ -5889,7 +5917,7 @@ class ShardClient {
     pathPrefix;
     fetchFn;
     cache;
-    /** Hashes waiting for the next batch, each with everyone awaiting it. */
+    /** Hashes waiting for the next batch, each with everyone awaiting it and its size if a caller gave it. */
     pendingShards;
     batchTimer;
     /** False once the server is known not to have the batch route. */
@@ -6038,8 +6066,11 @@ class ShardClient {
     /**
      * Fetch a shard by hash. Throws if the server returns a non-200; returns
      * `null` for 404 so callers can distinguish "missing" from "errored".
+     *
+     * `size`, the shard's byte length when known (a manifest's `shardSize`),
+     * lets concurrent reads be batched within what the server will send.
      */
-    async getShard(hash) {
+    async getShard(hash, opts = {}) {
         // Cache-first: a hit is content-verified by construction (key == hash).
         if (this.cache) {
             const cached = await this.cache.get(hash);
@@ -6048,7 +6079,7 @@ class ShardClient {
         }
         // No peers → straight to origin.
         if (!this.peers)
-            return this.fetchFromOrigin(hash);
+            return this.fetchFromOrigin(hash, opts.size);
         // HEDGED RACE: prefer a peer (saves origin egress) but never let a slow
         // or missing peer stall delivery — give the peer a short head start, then
         // start origin in parallel and take whichever returns the block first.
@@ -6079,7 +6110,7 @@ class ShardClient {
                     clearTimeout(timer);
                     timer = null;
                 }
-                this.fetchFromOrigin(hash).then(win, fail);
+                this.fetchFromOrigin(hash, opts.size).then(win, fail);
             };
             timer = setTimeout(startOrigin, HEDGE_MS);
             peers.getBlock(hash).then((b) => {
@@ -6113,16 +6144,17 @@ class ShardClient {
      * Falls back permanently to one-at-a-time if the server has no batch route,
      * so a new SDK keeps working against an older deployment.
      */
-    fetchFromOrigin(hash) {
+    fetchFromOrigin(hash, size) {
         if (!this.batchSupported)
             return this.fetchOneFromOrigin(hash);
         return new Promise((resolve, reject) => {
-            const waiting = this.pendingShards.get(hash);
-            if (waiting) {
-                waiting.push({ resolve, reject });
+            const pending = this.pendingShards.get(hash);
+            if (pending) {
+                pending.waiters.push({ resolve, reject });
+                pending.size ??= size;
                 return;
             }
-            this.pendingShards.set(hash, [{ resolve, reject }]);
+            this.pendingShards.set(hash, { size, waiters: [{ resolve, reject }] });
             if (this.batchTimer === null) {
                 this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);
             }
@@ -6133,17 +6165,33 @@ class ShardClient {
         this.batchTimer = null;
         if (this.pendingShards.size === 0)
             return;
-        const hashes = [...this.pendingShards.keys()].slice(0, SHARD_BATCH_MAX);
-        const waiters = hashes.map((h) => {
-            const w = this.pendingShards.get(h);
+        // As many as fit: at most SHARD_BATCH_MAX hashes, and a response
+        // expected to stay within SHARD_BATCH_BUDGET_BYTES. One that does not
+        // fit is skipped for a smaller one behind it. The first always goes,
+        // so a shard over the budget by itself is fetched alone.
+        const waiters = [];
+        let cost = 0;
+        for (const [h, pending] of this.pendingShards) {
+            if (waiters.length === SHARD_BATCH_MAX)
+                break;
+            const next = batchCost(pending.size);
+            if (waiters.length > 0 && cost + next > SHARD_BATCH_BUDGET_BYTES)
+                continue;
+            waiters.push([h, pending.waiters]);
+            cost += next;
+        }
+        for (const [h] of waiters)
             this.pendingShards.delete(h);
-            return [h, w];
-        });
-        // Anything over the cap waits for the next window rather than being
-        // dropped or silently truncated.
+        // Anything over the cap or the budget waits for the next window
+        // rather than being dropped or silently truncated.
         if (this.pendingShards.size > 0 && this.batchTimer === null) {
             this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);
         }
+        await this.sendShardBatch(waiters);
+    }
+    /** POST one batch and settle everyone waiting on it. Never throws. */
+    async sendShardBatch(waiters) {
+        const hashes = waiters.map(([h]) => h);
         let shards;
         try {
             const res = await this.fetchFn(`${this.baseUrl}${this.pathPrefix}/batch`, {
@@ -6151,6 +6199,21 @@ class ShardClient {
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ hashes }),
             });
+            if (res.status === 413 && waiters.length > 1) {
+                // Too large for the server after all: a size was not given,
+                // or was wrong. Ask for each half on its own. Halving reaches
+                // one hash per batch within log2(n) levels, and one hash the
+                // server refuses is an error like any other, below.
+                // Release the body first: under undici (the CLI, Node), an
+                // unread body holds the connection until garbage collection.
+                await res.body?.cancel().catch(() => { });
+                const half = Math.ceil(waiters.length / 2);
+                await Promise.all([
+                    this.sendShardBatch(waiters.slice(0, half)),
+                    this.sendShardBatch(waiters.slice(half)),
+                ]);
+                return;
+            }
             if (res.status === 404 || res.status === 405) {
                 // No batch route on this deployment. Stop trying, and serve
                 // everyone individually — including the batch we just gathered.
@@ -6526,7 +6589,8 @@ class FileStorage {
         const fetched = new Array(total).fill(null);
         const fetchInto = async (indexes) => {
             await this.runWithConcurrency(indexes.map((i) => async () => {
-                fetched[i] = await this.shards.getShard(manifest.shardHashes[i]);
+                // The size keeps a batch of concurrent reads within what the server will send.
+                fetched[i] = await this.shards.getShard(manifest.shardHashes[i], { size: manifest.shardSize });
             }));
         };
         await fetchInto(Array.from({ length: dataCount }, (_, i) => i));
@@ -6675,7 +6739,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.15.0-alpha.1";
+const VERSION = "0.15.0-alpha.3";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -8983,6 +9047,45 @@ class StorageCipher {
     }
 }
 
+/** The server's cap on `prefix`, in code points (accelerator `personalKv/list.ts`). */
+const MAX_SERVER_PREFIX_CHARS = 1024;
+/**
+ * The server handed back a cursor it had already given, so following it would
+ * page forever. A fault in the answer, not a failure to reach the server: the
+ * offline layer rethrows it instead of falling back to its cache.
+ */
+class RepeatedCursorError extends Error {
+    constructor() {
+        super("personal-space list: the server repeated a cursor; stopping instead of looping");
+        this.name = "RepeatedCursorError";
+    }
+}
+/** Every key under `prefix` ("" = every key), in the server's order. */
+async function listPersonalKeys(http, path, prefix) {
+    // A prefix over the server's cap would be refused with a 400. Every list
+    // was whole before the key index, so ask for everything instead; the
+    // caller filters. (`length` first: code points never outnumber units.)
+    const sent = prefix.length > MAX_SERVER_PREFIX_CHARS && [...prefix].length > MAX_SERVER_PREFIX_CHARS ? "" : prefix;
+    const keys = [];
+    const seen = new Set();
+    let cursor = null;
+    for (;;) {
+        const res = await http.post(path, cursor === null ? { prefix: sent } : { prefix: sent, cursor });
+        keys.push(...(res?.keys ?? []));
+        // Annotated: without it TypeScript infers `next` through `cursor` and
+        // the request body above, a loop it reports as TS7022.
+        const next = typeof res?.cursor === "string" && res.cursor !== "" ? res.cursor : null;
+        if (next === null)
+            return keys;
+        // A server (or a cache in front of one) that hands back a cursor it
+        // already gave would have this page forever.
+        if (seen.has(next))
+            throw new RepeatedCursorError();
+        seen.add(next);
+        cursor = next;
+    }
+}
+
 /**
  * `client.kv` — per-user key/value storage backed by the accelerator's personal
  * space.
@@ -8990,6 +9093,7 @@ class StorageCipher {
  *   await client.kv.set('todos', id, { title, completed })
  *   const todo = await client.kv.get('todos', id)
  *   const ids  = await client.kv.list('todos')
+ *   const keys = await client.kv.keys('todos/')   // full keys, any prefix
  *   await client.kv.delete('todos', id)
  *   const off  = client.kv.on('change', e => …)   // realtime, cross-device
  *
@@ -9092,25 +9196,45 @@ class KvNamespace {
             return true; // optimistic
         }
     }
-    /** List the ids present in `collection`. */
+    /**
+     * List the ids present in `collection`. The server filters by
+     * `${collection}/` and pages; values are not fetched.
+     */
     async list(collection) {
         const prefix = `${collection}/`;
+        return (await this.keys(prefix)).map((k) => k.slice(prefix.length));
+    }
+    /**
+     * Every key in the signed-in user's personal space that starts with
+     * `prefix` (all of them when it is ""), as full keys: `todos/t1`, not
+     * `t1`. Values are not fetched. The personal space is shared by every
+     * app the user signs into, so expect keys you did not write: the VFS's
+     * `vfs/…`, version control's `vcs/…`, the SDK's own `chat-keys` and
+     * `space-keys/…`.
+     *
+     * The local `startsWith` filter stays on purpose: a server older than
+     * the key index ignores `prefix` and returns every key.
+     */
+    async keys(prefix = "") {
         const offline = this.deps.offline;
-        const fromKeys = (keys) => keys.filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
-        if (!offline?.enabled) {
-            const res = await this.deps.http.post(this.spacePath("/list"), {});
-            return fromKeys(res.keys ?? []);
-        }
+        const under = (keys) => [...new Set(keys.filter((k) => k.startsWith(prefix)))];
+        const remote = () => listPersonalKeys(this.deps.http, this.spacePath("/list"), prefix);
+        if (!offline?.enabled)
+            return under(await remote());
         try {
-            const res = await this.deps.http.post(this.spacePath("/list"), {});
+            const fromServer = await remote();
             // Union with cached live keys so un-synced offline creates still show.
-            const cached = await offline.liveKeys(this.commitment());
-            return [...new Set([...(res.keys ?? []), ...cached].filter((k) => k.startsWith(prefix)))].map((k) => k.slice(prefix.length));
+            return under([...fromServer, ...(await offline.liveKeys(this.commitment(), prefix))]);
         }
         catch (err) {
-            if (err instanceof HttpError)
+            // A refusal, or a server that repeats its cursor, is an answer,
+            // not an outage: falling back would hand back a partial list as
+            // if it were whole. Only a failure to reach the server (even
+            // mid-paging) falls back to the cache, as a failed list did
+            // before paging.
+            if (err instanceof HttpError || err instanceof RepeatedCursorError)
                 throw err;
-            return fromKeys(await offline.liveKeys(this.commitment()));
+            return under(await offline.liveKeys(this.commitment(), prefix));
         }
     }
     /** Reserved — server-side query is deferred (see the overhaul plan). */
@@ -15082,11 +15206,20 @@ function nextTurn() {
  * Every mutation is a read-modify-write of exactly ONE directory record, so a
  * write cannot leave the tree half-updated: either the parent names the new
  * child or it does not. Two tabs writing different directories never conflict;
- * two tabs writing the SAME directory resolve last-writer-wins at the personal
- * space, which carries an HLC per key. Orphaned records (a directory whose
- * parent entry lost the race) are unreachable rather than corrupting — they
- * cost storage until a future sweep, which is the trade this shape makes in
+ * two tabs (or devices) writing the SAME directory are last-writer-wins. A VFS
+ * write sends no HLC and the personal space has no compare-and-swap: it applies
+ * puts of one key in the order they arrive, so whichever arrives last is kept,
+ * and the other tab's edit is lost. Orphaned records (a directory whose parent
+ * entry lost the race) are unreachable rather than corrupting — they cost
+ * storage until a future sweep, which is the trade this shape makes in
  * exchange for single-record writes.
+ *
+ * Within ONE tab, writes of a record are queued and sent one at a time, in the
+ * order they were made, and a read that has to fetch a record waits for its
+ * write in flight (see `writing`). Every edit of a record is made to one
+ * in-memory copy of it, and that copy is what is written (see `mutate`). All
+ * of this is per namespace instance only; nothing orders writes across tabs
+ * or devices - that would take a compare-and-swap at the server.
  */
 /** Refuse a directory at `path` if it would be deeper than MAX_DEPTH from the root. */
 function assertWritableDepth(path) {
@@ -15290,6 +15423,32 @@ function assertNotHidden(dir, name, path) {
         throw new VfsConflictError(`${printable(path, 1024)} already exists, but this version cannot read it; a recursive delete removes it`);
     }
 }
+/**
+ * Is `now` still the entry an operation read at a name before it waited on
+ * something? The same kind and id, and for a file the same version; a move
+ * mark set or cleared in between does not count. Absent both times is the same.
+ * Where a decision rests on the mark, `markedMeanwhile` checks that as well.
+ */
+function sameEntry(before, now) {
+    if (!before || !now)
+        return before === now;
+    if (before.kind !== now.kind || before.id !== now.id)
+        return false;
+    return before.kind === "dir" || (now.kind === "file" && now.manifest.id === before.manifest.id);
+}
+/**
+ * Has a move marked the entry at a name since an operation read it there
+ * unmarked? Then a move of it is under way - see `DirEntry.moving` - and it is
+ * about to be named in a second place, which a decision made from the unmarked
+ * read did not allow for.
+ */
+function markedMeanwhile(before, now) {
+    return now.moving === true && before.moving !== true;
+}
+/** Refuse a write because another write changed `path` while this one waited. See `VfsNamespace.mutate`. */
+function changedMeanwhile(path) {
+    return new VfsConflictError(`${path} was changed by another write while this one was in progress; nothing was written over 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);
@@ -15456,8 +15615,25 @@ class VfsNamespace {
      * The file tree re-lists constantly while typing, and every miss is a
      * network round trip plus a decrypt. Invalidated precisely on write rather
      * than by TTL — a stale directory listing shows files that are not there.
+     *
+     * What a cached read resolves to is also THE copy of that record: the one
+     * every edit of it is made to, and the one written. See `mutate`.
      */
     cache = new Map();
+    /**
+     * Bumped by `clearCache`, which is for a change of identity.
+     *
+     * A read or write begun before it can finish after it, and what it read
+     * or wrote belongs to whoever was signed in before. So every record
+     * carries the generation it was read under, and none goes into the cache,
+     * or is edited as the cache's copy, under another.
+     */
+    generation = 0;
+    /**
+     * The record each promise in `cache` resolved to, and each write in
+     * `writing` is sending: what `editable` finds without waiting.
+     */
+    copyOf = new WeakMap();
     /**
      * The write of each directory record still in flight, by id.
      *
@@ -15467,7 +15643,9 @@ class VfsNamespace {
      * that is often the one sent first. Then the earlier write, sealed before
      * the later edit was made, undoes it. That is how a file deleted forever
      * from the Trash, while the move that put it there was still being
-     * written, came back. So each write waits for the one before it.
+     * written, came back. So each write waits for the one before it, and a
+     * read that has to fetch the record waits for its write too: see
+     * `openDirById`.
      */
     writing = new Map();
     historyLimit;
@@ -15526,6 +15704,9 @@ class VfsNamespace {
      * identity's directories to another would be the worst possible bug here.
      */
     clearCache() {
+        // Whatever is still being read or written for the identity before
+        // stays out of the cache from here on: see `generation`.
+        this.generation++;
         this.cache.clear();
         this.rootKey = null;
         this._cwd = "/"; // a different identity's tree has different directories
@@ -15831,21 +16012,26 @@ class VfsNamespace {
         assertValidName(name);
         await this.mkdir(dirname(target), { recursive: true });
         const parent = await this.openDir(dirname(target));
-        const prior = entryIn(parent.node, name);
-        if (prior?.kind === "dir")
+        if (entryIn(parent.node, name)?.kind === "dir")
             throw new VfsConflictError(`${target} is a directory`);
         await this.deps.content.retain(manifest);
-        const entry = {
-            kind: "file",
-            id: prior?.id ?? newId(),
-            manifest,
-            size,
-            mtime: Date.now(),
-            versions: asCount(prior?.versions),
-            // Still half of an interrupted move, if it was: see DirEntry.moving.
-            ...(prior?.moving === true ? { moving: true } : {}),
-        };
+        let entry;
         await this.mutate(parent, (node) => {
+            // Whatever is at the name now, after the wait above, is what
+            // this replaces - and what it takes the id and history from.
+            const prior = entryIn(node, name);
+            if (prior?.kind === "dir")
+                throw new VfsConflictError(`${target} is a directory`);
+            entry = {
+                kind: "file",
+                id: prior?.id ?? newId(),
+                manifest,
+                size,
+                mtime: Date.now(),
+                versions: asCount(prior?.versions),
+                // Still half of an interrupted move, if it was: see DirEntry.moving.
+                ...(prior?.moving === true ? { moving: true } : {}),
+            };
             node.entries[name] = entry;
         });
         return toStat(target, name, entry);
@@ -15882,7 +16068,7 @@ class VfsNamespace {
             else {
                 if (!isLast && !opts.recursive)
                     throw new VfsNotFoundError(current);
-                await this.createDir(current, name);
+                await this.createDir(current, name, next, opts.recursive === true);
             }
             current = next;
         }
@@ -15942,12 +16128,22 @@ class VfsNamespace {
         let versions = asCount(prior?.versions);
         if (prior)
             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 } : {}),
-        };
+        let entry;
         await this.mutate(parent, (node) => {
+            // The version just pushed onto the history was `prior`. If
+            // another write has replaced or removed it since, it is not the
+            // version this one overwrites, and writing on regardless would
+            // lose that write - from the file, and from its history.
+            const now = entryIn(node, name);
+            if (now?.kind === "dir")
+                throw new VfsConflictError(`${target} is a directory`);
+            if (!sameEntry(prior, now))
+                throw changedMeanwhile(target);
+            entry = {
+                kind: "file", id, manifest, size, mtime: Date.now(), versions,
+                // Still half of an interrupted move, if it was: see DirEntry.moving.
+                ...(now?.moving === true ? { moving: true } : {}),
+            };
             node.entries[name] = entry;
         });
         return toStat(target, name, entry);
@@ -15982,7 +16178,7 @@ class VfsNamespace {
             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]);
+            await this.mutate(parent, (_node, record) => void delete record.hidden[name]);
             this.warn(`removed ${where} without clearing out what it held: this version cannot read it`);
             return;
         }
@@ -16044,6 +16240,16 @@ class VfsNamespace {
         // 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) => {
+            // What is let go of below is what `entry` held. Gone since, it
+            // was let go of already; replaced, the name holds something this
+            // delete has not read. Marked since, a move of it has begun, and
+            // what it holds is about to be named somewhere `elsewhere` did
+            // not see - if it was looked for at all.
+            const now = entryIn(node, name);
+            if (!now)
+                throw new VfsNotFoundError(target);
+            if (!sameEntry(entry, now) || markedMeanwhile(entry, now))
+                throw changedMeanwhile(target);
             delete node.entries[name];
         });
         if (elsewhere === null) {
@@ -16098,11 +16304,30 @@ class VfsNamespace {
         // 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));
+        // Both ends were looked at before the waits above, and another write
+        // may have changed either since: replaced the entry being moved, or
+        // put something at the destination. Moving on regardless would write
+        // the old entry over the new one, or this one over the other. Or
+        // marked the entry: another move of it has begun. Taking it as well
+        // would name it in two places, and each move would unmark its own.
+        const take = (node) => {
+            const now = entryIn(node, srcName);
+            if (!now || !sameEntry(entry, now) || markedMeanwhile(entry, now))
+                throw changedMeanwhile(src);
+            return now;
+        };
+        const free = (node, record) => {
+            if (entryIn(node, dstName))
+                throw new VfsConflictError(`${dst} already exists`);
+            assertNotHidden(record, dstName, dst);
+        };
         if (dstParent.id === srcParent.id) {
             // One record, so one write: the move happens entirely or not at all.
-            await edit(dirname(src), (node) => {
+            await edit(dirname(src), (node, record) => {
+                const moved = take(node);
+                free(node, record);
                 delete node.entries[srcName];
-                node.entries[dstName] = { ...entry, mtime: Date.now() };
+                node.entries[dstName] = { ...moved, mtime: Date.now() };
             });
             return;
         }
@@ -16113,14 +16338,31 @@ class VfsNamespace {
         // 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() }));
+        let moved = entry;
+        if (!marked) {
+            await edit(dirname(src), (node) => {
+                moved = take(node);
+                node.entries[srcName] = { ...moved, moving: true };
+            });
+        }
+        await edit(dirname(dst), (node, record) => {
+            free(node, record);
+            node.entries[dstName] = { ...moved, 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]);
+        await edit(dirname(src), (node) => {
+            // Gone already leaves nothing to detach. Replaced, it is not this
+            // entry to take away: the move stops here, in both places. Not
+            // `take`: the entry is marked by now, by this move or the earlier
+            // one it finishes.
+            const now = entryIn(node, srcName);
+            if (now && !sameEntry(entry, now))
+                throw changedMeanwhile(src);
+            delete node.entries[srcName];
+        });
         if (!marked) {
             await edit(dirname(dst), (node) => {
                 const landed = entryIn(node, dstName);
@@ -16193,13 +16435,19 @@ class VfsNamespace {
         // 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 gen = this.generation;
         const run = (write) => ({
-            from: src, to: dst, write, entries: this.maxEntries, pathChars: this.maxPathChars, reached: new Map(), sinceTurn: 0,
+            from: src, to: dst, write, entries: this.maxEntries, pathChars: this.maxPathChars, reached: new Map(), sinceTurn: 0, gen,
         });
         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) => {
+        await this.mutate(dstParent, (node, record) => {
+            // Looked at before the copy was made, which takes as long as the
+            // tree is big: another write may have taken the name since.
+            if (entryIn(node, dstName))
+                throw new VfsConflictError(`${dst} already exists`);
+            assertNotHidden(record, dstName, dst);
             node.entries[dstName] = copied;
         });
         return toStat(dst, dstName, copied);
@@ -16220,8 +16468,11 @@ class VfsNamespace {
      * Delete metadata records no longer reachable from the root.
      *
      * These accumulate because every write touches exactly one record: if two
-     * tabs edit the same directory, last-writer-wins at the personal space can
-     * leave a child whose parent entry lost the race. Unreachable is harmless —
+     * tabs or devices edit the same directory, the personal space keeps
+     * whichever put arrives last (a VFS write sends no HLC, and the space
+     * applies puts of one key in arrival order), which can leave a child whose
+     * parent entry lost the race. The per-record write queue (`writing`) only
+     * orders writes within one tab. Unreachable is harmless —
      * it is invisible and undecryptable-by-nobody — but it costs storage, so
      * this reclaims it.
      *
@@ -16254,8 +16505,10 @@ class VfsNamespace {
         }
         // 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.
-        const mine = (await this.deps.store.list()).filter((k) => /^vfs\/[dh]\//.test(k));
+        // reached beyond its own namespace would be a data-loss bug. The store
+        // is asked for `vfs/` only; the regex stays, because `vfs/space` is
+        // under `vfs/` too and a store may ignore the prefix.
+        const mine = (await this.deps.store.list("vfs/")).filter((k) => /^vfs\/[dh]\//.test(k));
         const orphans = mine.filter((k) => !reachable.has(k));
         // A root that read as EMPTY while orphans exist is the shape of a failed
         // load, not of a fresh filesystem — deleting here would wipe a tree we
@@ -16295,16 +16548,21 @@ class VfsNamespace {
         if (!version)
             throw new VfsNotFoundError(`${target} version ${index}`);
         const versions = await this.pushHistory(parent, name, entry, target, version.manifest);
-        const restored = {
-            kind: "file",
-            id: entry.id,
-            manifest: version.manifest,
-            size: asCount(version.size),
-            mtime: Date.now(),
-            versions,
-            ...(entry.moving === true ? { moving: true } : {}),
-        };
+        let restored;
         await this.mutate(parent, (node) => {
+            // As for writeFile: the version pushed onto the history was `entry`.
+            const now = entryIn(node, name);
+            if (!sameEntry(entry, now))
+                throw changedMeanwhile(target);
+            restored = {
+                kind: "file",
+                id: entry.id,
+                manifest: version.manifest,
+                size: asCount(version.size),
+                mtime: Date.now(),
+                versions,
+                ...(now?.moving === true ? { moving: true } : {}),
+            };
             node.entries[name] = restored;
         });
         return toStat(target, name, restored);
@@ -16334,8 +16592,15 @@ class VfsNamespace {
         const seed = this.deps.seed();
         if (!seed)
             throw new VfsLockedError();
-        if (!this.rootKey)
-            this.rootKey = await deriveRootKey(seed);
+        if (!this.rootKey) {
+            const gen = this.generation;
+            const key = await deriveRootKey(seed);
+            // Derived from the seed of whoever was signed in before a
+            // clearCache: start again, with the seed of whoever is now.
+            if (gen !== this.generation)
+                return this.root();
+            this.rootKey = key;
+        }
         return this.openDirById(ROOT_ID, this.rootKey, "/");
     }
     /** Open a directory by path, creating nothing. Throws if it is missing. */
@@ -16379,7 +16644,44 @@ class VfsNamespace {
         // every concurrent reader to miss and fire its own request for the same
         // record — which is how loading one project turned into thousands of
         // identical `vfs/d/<id>` fetches, most of them in flight at once.
-        const pending = (async () => {
+        const gen = this.generation;
+        // Reads `pending` only after its first `await`: before that, the const is not yet initialised.
+        const load = async () => {
+            // Not while a write of this record is still in flight: see
+            // `writing`. Our own writes echo back over the personal-space
+            // socket, and `watch` drops the record each one names, so a read
+            // can miss with the write still on its way - and the store would
+            // answer with the copy from BEFORE it. An edit made to that copy
+            // is queued behind the write, and then stored over it. So wait
+            // for the latest write queued, which waits on every one before it,
+            // to land or fail - and then for any queued while this read
+            // waited, since the one it waited for may have failed with that
+            // one still on its way. A record with no write in flight is
+            // fetched at once.
+            let awaited;
+            for (let inFlight = this.writing.get(id); inFlight && inFlight !== awaited; inFlight = this.writing.get(id)) {
+                awaited = inFlight;
+                await inFlight.catch(() => { });
+            }
+            // Not after a clearCache, though: the cache now is the next
+            // identity's, and this read only answers whoever asked for it.
+            if (awaited && gen === this.generation) {
+                // A write that landed put the record it wrote back in the
+                // cache, and the next edit of this directory is made to that.
+                // Answer with it rather than fetch a second copy: two copies
+                // of one record, each edited and written, undo each other's
+                // edits. When the cache holds nothing else - the write failed,
+                // or a change since has dropped the record - ask the store.
+                const now = this.cache.get(id);
+                if (now && now !== pending)
+                    return now;
+                // Empty, when the write failed: it dropped what the cache held,
+                // and after an echo that was this very read. Put it back before
+                // asking the store, so a read that comes in meanwhile shares
+                // this copy instead of fetching a second one.
+                if (!now)
+                    this.cache.set(id, pending);
+            }
             const raw = await this.deps.store.get(dirKey(id));
             // An absent record is an EMPTY directory, not an error: the root
             // exists before anything has been written to it, and a directory is
@@ -16387,7 +16689,7 @@ class VfsNamespace {
             // appearing.
             if (raw === null || raw === undefined) {
                 const node = { v: 1, entries: emptyEntries(), mtime: Date.now() };
-                return { id, key, path, node, hidden: Object.create(null) };
+                return { id, key, path, node, hidden: Object.create(null), gen };
             }
             // Present but unopenable is NOT absent. `unseal` folds the two
             // together, which suits a record that can simply be rebuilt; a
@@ -16404,14 +16706,18 @@ class VfsNamespace {
                     throw new VfsCorruptRecordError(id, path, err.message);
                 throw err;
             }
-            return this.readRecord(id, key, value, path);
-        })().catch((err) => {
+            return this.readRecord(id, key, value, gen, path);
+        };
+        const pending = load().catch((err) => {
             // A failed read must not be remembered, or one blip poisons the
             // directory for the life of the session.
             if (this.cache.get(id) === pending)
                 this.cache.delete(id);
             throw err;
         });
+        // Registered before anyone else can wait on it, so it is known by
+        // the time any of them goes on to edit the record: see `editable`.
+        pending.then((dir) => void this.copyOf.set(pending, dir), () => { });
         this.cache.set(id, pending);
         return pending;
     }
@@ -16422,7 +16728,7 @@ class VfsNamespace {
      * 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) {
+    readRecord(id, key, value, gen, path) {
         const problem = recordProblem(value);
         if (problem)
             throw new VfsCorruptRecordError(id, path, problem);
@@ -16478,25 +16784,47 @@ class VfsNamespace {
             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 };
+        return { id, key, path, node: { ...top, entries }, hidden, gen };
     }
-    /** Apply an edit to a directory record and persist it. */
+    /**
+     * Apply an edit to a directory record and persist it.
+     *
+     * `dir` says which record - its id, key and path - and nothing more. The
+     * edit is made to THE copy of that record (see `editable`), which `dir`
+     * may no longer be, and that copy is what is written. Editing whichever
+     * copy the caller held let two copies of one record exist at once: an
+     * overwrite held its directory across storing the old version's
+     * history, a write of the directory failed meanwhile and dropped it from
+     * the cache, and a save that then read a second copy and stored it,
+     * successfully, was undone when the overwrite stored the first.
+     *
+     * So `edit` must take what it writes from the record it is given, not
+     * from anything read off `dir` before an await - and re-check whatever it
+     * relies on from then, throwing if another write changed it. Returning
+     * false writes nothing after all.
+     */
     async mutate(dir, edit) {
-        edit(dir.node);
-        dir.node.mtime = Date.now();
+        // At once when the copy is to hand, which it almost always is, so
+        // that what the caller checked just before is still true when the
+        // edit is made.
+        const target = this.editable(dir) ?? await this.reopen(dir);
+        if (edit(target.node, target) === false)
+            return;
+        target.node.mtime = Date.now();
         // 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];
+        for (const name of Object.keys(target.hidden)) {
+            if (Object.hasOwn(target.node.entries, name))
+                delete target.hidden[name];
         }
         // Not sent until any earlier write of this record has landed: see
         // `writing`. Whether that one worked or not, this one still goes.
-        const before = this.writing.get(dir.id);
-        const send = () => this.writeRecord(dir);
+        const before = this.writing.get(target.id);
+        const send = () => this.writeRecord(target);
         const write = before ? before.then(send, send) : send();
-        this.writing.set(dir.id, write);
+        this.copyOf.set(write, target);
+        this.writing.set(target.id, write);
         try {
             await write;
         }
@@ -16506,14 +16834,68 @@ class VfsNamespace {
             // 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);
+            //
+            // Unless a later write of this record is already queued. It
+            // seals the record as it stands when it is sent, this edit
+            // included, so the cache shows what is about to be stored, and
+            // dropping it would only send readers to the store for an older
+            // copy. If that write fails too, it drops the cache itself.
+            //
+            // Nor from a cache cleared since: that is the next identity's.
+            if (this.writing.get(target.id) === write && target.gen === this.generation)
+                this.cache.delete(target.id);
             throw err;
         }
         finally {
-            if (this.writing.get(dir.id) === write)
-                this.writing.delete(dir.id);
+            if (this.writing.get(target.id) === write)
+                this.writing.delete(target.id);
         }
-        this.cache.set(dir.id, Promise.resolve(dir));
+        this.adopt(target);
+    }
+    /**
+     * The copy of `dir`'s record that edits are made to, if there is one
+     * without waiting: the one the cache holds, once read.
+     *
+     * Failing that, the one a write in flight is sending. The record was
+     * dropped from the cache - a change was reported, our own write's echo
+     * among them - and a read that came in since is waiting for that write,
+     * to answer with this very copy if it lands (see `openDirById`); if it
+     * fails, the write an edit now queues behind it carries the copy instead.
+     *
+     * Undefined when the record is not cached and nothing is writing it, or
+     * it is still being read: `reopen` waits for that. A record read before
+     * `clearCache` is edited as it is, as it always was. It is not the copy of
+     * anything the cache holds now, and must not be handed the next identity's.
+     */
+    editable(dir) {
+        if (dir.gen !== this.generation)
+            return dir;
+        const cached = this.cache.get(dir.id);
+        const write = this.writing.get(dir.id);
+        const copy = (cached && this.copyOf.get(cached)) ?? (write && this.copyOf.get(write));
+        return copy?.gen === this.generation ? copy : undefined;
+    }
+    /**
+     * Read `dir`'s record - the cached read, or a fetch made once any write of
+     * it in flight has settled - and then find the copy edits are made to.
+     */
+    async reopen(dir) {
+        for (;;) {
+            await this.openDirById(dir.id, dir.key, dir.path);
+            // What that read answered with, unless a change has dropped it
+            // from the cache again since: then read it again.
+            const copy = this.editable(dir);
+            if (copy)
+                return copy;
+        }
+    }
+    /** Make `dir` the cached copy of its record - unless the cache has been cleared since it was read. */
+    adopt(dir) {
+        if (dir.gen !== this.generation)
+            return;
+        const cached = Promise.resolve(dir);
+        this.copyOf.set(cached, dir);
+        this.cache.set(dir.id, cached);
     }
     /**
      * Seal a directory record as it stands NOW and put it in the store.
@@ -16541,12 +16923,24 @@ class VfsNamespace {
         }
         await this.deps.store.put(dirKey(dir.id), sealed);
     }
-    async createDir(parentPath, name) {
+    /** For `mkdir`: name a new, empty directory `path` in the one at `parentPath`. */
+    async createDir(parentPath, name, path, recursive) {
         assertValidName(name);
         const parent = await this.openDir(parentPath);
         const entry = { kind: "dir", id: newId(), key: toBase64(newDirKey()), mtime: Date.now() };
-        await this.mutate(parent, (node) => {
+        await this.mutate(parent, (node, record) => {
+            // mkdir looked before the wait above. A directory made there
+            // since, by another `mkdir -p` of the same path - files saved
+            // at once into a new folder - is kept, not replaced: whatever
+            // was saved into it would go with it.
+            const now = entryIn(node, name);
+            if (now?.kind === "dir" && recursive)
+                return false;
+            if (now)
+                throw new VfsConflictError(`${path} ${now.kind === "dir" ? "already exists" : "is a file"}`);
+            assertNotHidden(record, name, path);
             node.entries[name] = entry;
+            return true;
         });
     }
     /**
@@ -16656,8 +17050,15 @@ class VfsNamespace {
             // 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])));
+            if (name === undefined)
+                return;
+            await this.mutate(dir, (node) => {
+                const now = entryIn(node, name);
+                if (now?.id !== id || now.moving !== true)
+                    return false;
+                node.entries[name] = unmarked(now);
+                return true;
+            });
         }
         catch {
             // It stays marked.
@@ -16854,9 +17255,9 @@ class VfsNamespace {
         }
         if (!run.write)
             return clone;
-        const open = { id: clone.id, key: fromBase64(clone.key), node, hidden: Object.create(null) };
+        const open = { id: clone.id, key: fromBase64(clone.key), node, hidden: Object.create(null), gen: run.gen };
         await this.deps.store.put(dirKey(open.id), await seal(open.key, node));
-        this.cache.set(open.id, Promise.resolve(open));
+        this.adopt(open);
         return clone;
     }
     /**
@@ -17853,8 +18254,11 @@ class Repo {
     async expand(prefix) {
         if (!/^[0-9a-f]{4,}$/.test(prefix))
             return null;
-        const keys = await this.deps.store.list();
         const wanted = objectKey(this.slug, prefix);
+        // Only the keys under the abbreviation (usually none or one), not the
+        // whole personal space. The filter below stays, for a store that
+        // ignores the prefix.
+        const keys = await this.deps.store.list(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)));
@@ -19206,11 +19610,15 @@ class KvCache {
         const local = (await this.store.get("kv-cache", k)) ?? emptyRegister();
         await this.store.put("kv-cache", k, mergeRegister(local, incoming));
     }
-    /** Non-tombstoned full keys for a commitment (used for offline `list`). */
-    async liveKeys(commitment) {
-        const prefix = `${commitment}|`;
-        const rows = await this.store.prefix("kv-cache", prefix);
-        return rows.filter((r) => !r.value.deleted).map((r) => r.key.slice(prefix.length));
+    /**
+     * Non-tombstoned full keys for a commitment that start with `prefix` (all
+     * of them by default), for offline `list`. The store scans the key range
+     * `${commitment}|${prefix}`, so other collections are never read.
+     */
+    async liveKeys(commitment, prefix = "") {
+        const scope = `${commitment}|`;
+        const rows = await this.store.prefix("kv-cache", scope + prefix);
+        return rows.filter((r) => !r.value.deleted).map((r) => r.key.slice(scope.length));
     }
     /** Queue a kv mutation for replay on reconnect. */
     async enqueue(method, args, hlc, clientId) {
@@ -19366,13 +19774,17 @@ class Client {
     /** Shared in-flight recovery so a burst of 401s triggers one re-auth. */
     recoverInFlight = null;
     constructor(options = {}) {
-        // Build stamp — always logged (independent of logLevel) so the running
-        // build is identifiable in the console. Catches stale cached bundles
-        // during development; bump `VERSION` (and package.json) each build.
-        try {
-            console.info(`[@muhkoo/connect] initialized — v${VERSION}`);
+        // Build stamp — logged (independent of logLevel) so the running build
+        // is identifiable in the console. Catches stale cached bundles during
+        // development; bump `VERSION` (and package.json) each build.
+        // Browser console only: in Node it lands on stdout, in front of a
+        // CLI's own output (`muhkoo kv ls --json | jq`).
+        if (typeof window !== "undefined" && typeof document !== "undefined") {
+            try {
+                console.info(`[@muhkoo/connect] initialized — v${VERSION}`);
+            }
+            catch { /* console may be unavailable in some runtimes */ }
         }
-        catch { /* console may be unavailable in some runtimes */ }
         if (options.logLevel && typeof globalThis.appLogger?.setLevel === "function") {
             globalThis.appLogger.setLevel(options.logLevel);
         }
@@ -19474,12 +19886,13 @@ class Client {
                     throw new Error("client.vfs: no session — sign in first.");
                 await this.http.del(`/api/personal/${encodeURIComponent(c)}/kv/${encodeURIComponent(key)}`);
             },
-            list: async () => {
+            list: async (prefix) => {
                 const c = this.session.commitment;
                 if (!c)
                     throw new Error("client.vfs: no session — sign in first.");
-                const res = await this.http.post(`/api/personal/${encodeURIComponent(c)}/list`, {});
-                return res?.keys ?? [];
+                // The server filters by prefix and pages. An older server ignores
+                // the prefix and returns every key, which is why callers filter.
+                return listPersonalKeys(this.http, `/api/personal/${encodeURIComponent(c)}/list`, prefix ?? "");
             },
         };
         let contentSpace = null;