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

package/dist/server/index.js

@@ -6739,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.2";
+const VERSION = "0.15.0-alpha.3";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -9047,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.
@@ -9054,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
  *
@@ -9156,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). */
@@ -15156,9 +15216,10 @@ function nextTurn() {
  *
  * 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`). That ordering is per namespace instance
- * only; nothing orders writes across tabs or devices - that would take a
- * compare-and-swap at the server.
+ * 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) {
@@ -15362,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);
@@ -15528,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.
      *
@@ -15600,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
@@ -15905,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);
@@ -15956,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;
         }
@@ -16016,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);
@@ -16056,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;
         }
@@ -16118,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) {
@@ -16172,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;
         }
@@ -16187,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);
@@ -16267,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);
@@ -16331,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
@@ -16372,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);
@@ -16411,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. */
@@ -16456,6 +16644,7 @@ 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 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
@@ -16474,7 +16663,9 @@ class VfsNamespace {
                 awaited = inFlight;
                 await inFlight.catch(() => { });
             }
-            if (awaited) {
+            // 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
@@ -16498,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
@@ -16515,7 +16706,7 @@ class VfsNamespace {
                     throw new VfsCorruptRecordError(id, path, err.message);
                 throw err;
             }
-            return this.readRecord(id, key, value, path);
+            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
@@ -16524,6 +16715,9 @@ class VfsNamespace {
                 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;
     }
@@ -16534,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);
@@ -16590,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;
         }
@@ -16624,15 +16840,62 @@ class VfsNamespace {
             // 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.
-            if (this.writing.get(dir.id) === write)
-                this.cache.delete(dir.id);
+            //
+            // 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.
@@ -16660,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;
         });
     }
     /**
@@ -16775,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.
@@ -16973,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;
     }
     /**
@@ -17972,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)));
@@ -19325,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) {
@@ -19485,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);
         }
@@ -19593,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;