sh3-core 0.20.1 → 0.20.2

package/dist/documents/backends.d.ts

@@ -13,6 +13,12 @@ export declare class MemoryDocumentBackend implements DocumentBackend {
         shardId: string;
     }>>;
     readMeta(tenantId: string, shardId: string, path: string): Promise<DocStatus | null>;
+    mkdir(tenantId: string, shardId: string, path: string): Promise<void>;
+    rmdir(tenantId: string, shardId: string, path: string, opts: {
+        recursive: boolean;
+    }): Promise<void>;
+    renameFolder(tenantId: string, shardId: string, oldPath: string, newPath: string): Promise<void>;
+    listFolders(tenantId: string, shardId: string, prefix: string): Promise<string[]>;
 }
 export declare class IndexedDBDocumentBackend implements DocumentBackend {
     #private;
@@ -26,4 +32,10 @@ export declare class IndexedDBDocumentBackend implements DocumentBackend {
     listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
         shardId: string;
     }>>;
+    mkdir(tenantId: string, shardId: string, path: string): Promise<void>;
+    rmdir(tenantId: string, shardId: string, path: string, opts: {
+        recursive: boolean;
+    }): Promise<void>;
+    renameFolder(tenantId: string, shardId: string, oldPath: string, newPath: string): Promise<void>;
+    listFolders(tenantId: string, shardId: string, prefix: string): Promise<string[]>;
 }

package/dist/documents/backends.js

@@ -16,7 +16,7 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _MemoryDocumentBackend_store, _IndexedDBDocumentBackend_instances, _IndexedDBDocumentBackend_dbPromise, _IndexedDBDocumentBackend_db, _IndexedDBDocumentBackend_tx;
+var _MemoryDocumentBackend_store, _MemoryDocumentBackend_folders, _IndexedDBDocumentBackend_instances, _IndexedDBDocumentBackend_dbPromise, _IndexedDBDocumentBackend_db, _IndexedDBDocumentBackend_tx, _IndexedDBDocumentBackend_txOn;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -29,6 +29,7 @@ function keyPrefix(tenantId, shardId) {
 export class MemoryDocumentBackend {
     constructor() {
         _MemoryDocumentBackend_store.set(this, new Map());
+        _MemoryDocumentBackend_folders.set(this, new Set()); // composite keys: `${tenant}/${shard}/${path}`
     }
     async read(tenantId, shardId, path) {
         const entry = __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").get(compositeKey(tenantId, shardId, path));
@@ -111,14 +112,111 @@ export class MemoryDocumentBackend {
             return null;
         return { exists: true, version: 1, syncMode: 'sync', syncState: 'synced' };
     }
+    async mkdir(tenantId, shardId, path) {
+        if (__classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").has(compositeKey(tenantId, shardId, path))) {
+            throw new Error(`Cannot mkdir ${path}: a document occupies this path`);
+        }
+        __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f").add(compositeKey(tenantId, shardId, path));
+    }
+    async rmdir(tenantId, shardId, path, opts) {
+        const folderKey = compositeKey(tenantId, shardId, path);
+        const docPrefix = folderKey + '/';
+        const docDescendants = [];
+        const folderDescendants = [];
+        for (const key of __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").keys()) {
+            if (key.startsWith(docPrefix))
+                docDescendants.push(key);
+        }
+        for (const key of __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f")) {
+            if (key === folderKey)
+                continue;
+            if (key.startsWith(docPrefix))
+                folderDescendants.push(key);
+        }
+        if (!opts.recursive && (docDescendants.length > 0 || folderDescendants.length > 0)) {
+            throw new Error(`Cannot rmdir ${path}: folder is not empty`);
+        }
+        for (const k of docDescendants)
+            __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").delete(k);
+        for (const k of folderDescendants)
+            __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f").delete(k);
+        __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f").delete(folderKey);
+    }
+    async renameFolder(tenantId, shardId, oldPath, newPath) {
+        const oldFolderKey = compositeKey(tenantId, shardId, oldPath);
+        const newFolderKey = compositeKey(tenantId, shardId, newPath);
+        const oldDocPrefix = oldFolderKey + '/';
+        const oldHasExplicit = __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f").has(oldFolderKey);
+        const oldHasImplicit = [...__classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").keys()].some((k) => k.startsWith(oldDocPrefix)) ||
+            [...__classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f")].some((k) => k.startsWith(oldDocPrefix));
+        if (!oldHasExplicit && !oldHasImplicit) {
+            throw new Error(`Cannot rename folder ${oldPath}: does not exist`);
+        }
+        const newDocPrefix = newFolderKey + '/';
+        const newHasExplicit = __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f").has(newFolderKey);
+        const newHasImplicit = [...__classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").keys()].some((k) => k.startsWith(newDocPrefix)) ||
+            [...__classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f")].some((k) => k.startsWith(newDocPrefix));
+        if (newHasExplicit || newHasImplicit) {
+            throw new Error(`Cannot rename folder to ${newPath}: already exists`);
+        }
+        // Rewrite docs
+        const docMoves = [];
+        for (const [key, entry] of __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f")) {
+            if (key.startsWith(oldDocPrefix)) {
+                const rewritten = newFolderKey + '/' + key.slice(oldDocPrefix.length);
+                docMoves.push([key, rewritten, entry]);
+            }
+        }
+        for (const [oldKey, newKey, entry] of docMoves) {
+            __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").delete(oldKey);
+            __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").set(newKey, Object.assign(Object.assign({}, entry), { lastModified: Date.now() }));
+        }
+        // Rewrite folders
+        const folderMoves = [];
+        for (const key of __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f")) {
+            if (key === oldFolderKey) {
+                folderMoves.push([key, newFolderKey]);
+            }
+            else if (key.startsWith(oldDocPrefix)) {
+                folderMoves.push([key, newFolderKey + '/' + key.slice(oldDocPrefix.length)]);
+            }
+        }
+        for (const [oldKey, newKey] of folderMoves) {
+            __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f").delete(oldKey);
+            __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f").add(newKey);
+        }
+    }
+    async listFolders(tenantId, shardId, prefix) {
+        const basePrefix = prefix
+            ? compositeKey(tenantId, shardId, prefix) + '/'
+            : keyPrefix(tenantId, shardId);
+        const out = new Set();
+        for (const key of __classPrivateFieldGet(this, _MemoryDocumentBackend_folders, "f")) {
+            if (!key.startsWith(basePrefix))
+                continue;
+            const rest = key.slice(basePrefix.length);
+            const slash = rest.indexOf('/');
+            out.add(slash >= 0 ? rest.slice(0, slash) : rest);
+        }
+        for (const key of __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").keys()) {
+            if (!key.startsWith(basePrefix))
+                continue;
+            const rest = key.slice(basePrefix.length);
+            const slash = rest.indexOf('/');
+            if (slash >= 0)
+                out.add(rest.slice(0, slash));
+        }
+        return [...out].sort();
+    }
 }
-_MemoryDocumentBackend_store = new WeakMap();
+_MemoryDocumentBackend_store = new WeakMap(), _MemoryDocumentBackend_folders = new WeakMap();
 // ---------------------------------------------------------------------------
 // IndexedDBDocumentBackend
 // ---------------------------------------------------------------------------
 const IDB_NAME = 'sh3-documents';
 const IDB_STORE = 'docs';
-const IDB_VERSION = 2;
+const IDB_FOLDERS = 'folders';
+const IDB_VERSION = 3;
 export class IndexedDBDocumentBackend {
     constructor() {
         _IndexedDBDocumentBackend_instances.add(this);
@@ -274,6 +372,123 @@ export class IndexedDBDocumentBackend {
             req.onerror = () => reject(req.error);
         });
     }
+    async mkdir(tenantId, shardId, path) {
+        const docKey = compositeKey(tenantId, shardId, path);
+        const exists = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.getKey(docKey));
+        if (exists !== undefined) {
+            throw new Error(`Cannot mkdir ${path}: a document occupies this path`);
+        }
+        await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_txOn).call(this, IDB_FOLDERS, 'readwrite', (s) => s.put(1, docKey));
+    }
+    async rmdir(tenantId, shardId, path, opts) {
+        const folderKey = compositeKey(tenantId, shardId, path);
+        const docPrefix = folderKey + '/';
+        const upper = docPrefix + '￿';
+        const docKeys = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.getAllKeys(IDBKeyRange.bound(docPrefix, upper, false, false)));
+        const folderKeys = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_txOn).call(this, IDB_FOLDERS, 'readonly', (s) => s.getAllKeys(IDBKeyRange.bound(docPrefix, upper, false, false)));
+        if (!opts.recursive && (docKeys.length > 0 || folderKeys.length > 0)) {
+            throw new Error(`Cannot rmdir ${path}: folder is not empty`);
+        }
+        const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction([IDB_STORE, IDB_FOLDERS], 'readwrite');
+            const docStore = tx.objectStore(IDB_STORE);
+            const folderStore = tx.objectStore(IDB_FOLDERS);
+            for (const k of docKeys)
+                docStore.delete(k);
+            for (const k of folderKeys)
+                folderStore.delete(k);
+            folderStore.delete(folderKey);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    async renameFolder(tenantId, shardId, oldPath, newPath) {
+        const oldFolderKey = compositeKey(tenantId, shardId, oldPath);
+        const newFolderKey = compositeKey(tenantId, shardId, newPath);
+        const oldPrefix = oldFolderKey + '/';
+        const newPrefix = newFolderKey + '/';
+        const upperOld = oldPrefix + '￿';
+        const upperNew = newPrefix + '￿';
+        const [oldDocs, oldFolders, oldExplicit, newDocs, newFolders, newExplicit] = await Promise.all([
+            __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.getAllKeys(IDBKeyRange.bound(oldPrefix, upperOld, false, false))),
+            __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_txOn).call(this, IDB_FOLDERS, 'readonly', (s) => s.getAllKeys(IDBKeyRange.bound(oldPrefix, upperOld, false, false))),
+            __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_txOn).call(this, IDB_FOLDERS, 'readonly', (s) => s.getKey(oldFolderKey)),
+            __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.getAllKeys(IDBKeyRange.bound(newPrefix, upperNew, false, false))),
+            __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_txOn).call(this, IDB_FOLDERS, 'readonly', (s) => s.getAllKeys(IDBKeyRange.bound(newPrefix, upperNew, false, false))),
+            __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_txOn).call(this, IDB_FOLDERS, 'readonly', (s) => s.getKey(newFolderKey)),
+        ]);
+        if (oldDocs.length === 0 && oldFolders.length === 0 && oldExplicit === undefined) {
+            throw new Error(`Cannot rename folder ${oldPath}: does not exist`);
+        }
+        if (newDocs.length > 0 || newFolders.length > 0 || newExplicit !== undefined) {
+            throw new Error(`Cannot rename folder to ${newPath}: already exists`);
+        }
+        // Read doc entries with values via cursor
+        const docEntries = await new Promise((resolve, reject) => {
+            __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this).then((db) => {
+                const tx = db.transaction(IDB_STORE, 'readonly');
+                const store = tx.objectStore(IDB_STORE);
+                const req = store.openCursor(IDBKeyRange.bound(oldPrefix, upperOld, false, false));
+                const acc = [];
+                req.onsuccess = () => {
+                    const cursor = req.result;
+                    if (cursor) {
+                        acc.push({ key: cursor.key, value: cursor.value });
+                        cursor.continue();
+                    }
+                    else {
+                        resolve(acc);
+                    }
+                };
+                req.onerror = () => reject(req.error);
+            });
+        });
+        const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction([IDB_STORE, IDB_FOLDERS], 'readwrite');
+            const docStore = tx.objectStore(IDB_STORE);
+            const folderStore = tx.objectStore(IDB_FOLDERS);
+            for (const { key, value } of docEntries) {
+                const rewritten = newFolderKey + '/' + key.slice(oldPrefix.length);
+                docStore.delete(key);
+                docStore.put(Object.assign(Object.assign({}, value), { lastModified: Date.now() }), rewritten);
+            }
+            if (oldExplicit !== undefined) {
+                folderStore.delete(oldFolderKey);
+            }
+            folderStore.put(1, newFolderKey);
+            for (const k of oldFolders) {
+                const oldKeyStr = k;
+                const rewritten = newFolderKey + '/' + oldKeyStr.slice(oldPrefix.length);
+                folderStore.delete(k);
+                folderStore.put(1, rewritten);
+            }
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    async listFolders(tenantId, shardId, prefix) {
+        const basePrefix = prefix
+            ? compositeKey(tenantId, shardId, prefix) + '/'
+            : keyPrefix(tenantId, shardId);
+        const upper = basePrefix + '￿';
+        const out = new Set();
+        const folderKeys = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_txOn).call(this, IDB_FOLDERS, 'readonly', (s) => s.getAllKeys(IDBKeyRange.bound(basePrefix, upper, false, false)));
+        for (const k of folderKeys) {
+            const rest = k.slice(basePrefix.length);
+            const slash = rest.indexOf('/');
+            out.add(slash >= 0 ? rest.slice(0, slash) : rest);
+        }
+        const docKeys = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.getAllKeys(IDBKeyRange.bound(basePrefix, upper, false, false)));
+        for (const k of docKeys) {
+            const rest = k.slice(basePrefix.length);
+            const slash = rest.indexOf('/');
+            if (slash >= 0)
+                out.add(rest.slice(0, slash));
+        }
+        return [...out].sort();
+    }
 }
 _IndexedDBDocumentBackend_dbPromise = new WeakMap(), _IndexedDBDocumentBackend_instances = new WeakSet(), _IndexedDBDocumentBackend_db = function _IndexedDBDocumentBackend_db() {
     if (!__classPrivateFieldGet(this, _IndexedDBDocumentBackend_dbPromise, "f")) {
@@ -284,6 +499,9 @@ _IndexedDBDocumentBackend_dbPromise = new WeakMap(), _IndexedDBDocumentBackend_i
                 if (!db.objectStoreNames.contains(IDB_STORE)) {
                     db.createObjectStore(IDB_STORE);
                 }
+                if (!db.objectStoreNames.contains(IDB_FOLDERS)) {
+                    db.createObjectStore(IDB_FOLDERS);
+                }
             };
             req.onsuccess = () => resolve(req.result);
             req.onerror = () => reject(req.error);
@@ -301,4 +519,13 @@ async function _IndexedDBDocumentBackend_tx(mode, fn) {
         req.onsuccess = () => resolve(req.result);
         req.onerror = () => reject(req.error);
     });
+}, _IndexedDBDocumentBackend_txOn = async function _IndexedDBDocumentBackend_txOn(storeName, mode, fn) {
+    const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, mode);
+        const store = tx.objectStore(storeName);
+        const req = fn(store);
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
 };

package/dist/documents/backends.test.js

@@ -1,5 +1,5 @@
 import 'fake-indexeddb/auto';
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { MemoryDocumentBackend, IndexedDBDocumentBackend } from './backends';
 describe('DocumentBackend tenant-wide primitives', () => {
     it('listAllShards returns every shard that has content for a tenant', async () => {
@@ -99,3 +99,149 @@ describe('IndexedDBDocumentBackend.rename', () => {
             .rejects.toThrow(/not found/);
     });
 });
+describe('MemoryDocumentBackend folder ops', () => {
+    let backend;
+    beforeEach(() => { backend = new MemoryDocumentBackend(); });
+    it('mkdir creates an empty folder visible via listFolders', async () => {
+        await backend.mkdir('t', 's', 'a');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['a']);
+    });
+    it('mkdir is a no-op if the folder already exists', async () => {
+        await backend.mkdir('t', 's', 'a');
+        await backend.mkdir('t', 's', 'a');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['a']);
+    });
+    it('mkdir throws if a document occupies the path', async () => {
+        await backend.write('t', 's', 'a', 'content');
+        await expect(backend.mkdir('t', 's', 'a')).rejects.toThrow();
+    });
+    it('listFolders surfaces folders implied by document paths', async () => {
+        await backend.write('t', 's', 'sub/a.md', 'x');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['sub']);
+    });
+    it('listFolders merges explicit and implicit folders without duplicates', async () => {
+        await backend.mkdir('t', 's', 'sub');
+        await backend.write('t', 's', 'sub/a.md', 'x');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['sub']);
+    });
+    it('listFolders with prefix returns immediate children', async () => {
+        await backend.mkdir('t', 's', 'a/b');
+        await backend.mkdir('t', 's', 'a/c');
+        await backend.write('t', 's', 'a/d/x.md', 'x');
+        const children = await backend.listFolders('t', 's', 'a');
+        expect(children.sort()).toEqual(['b', 'c', 'd']);
+    });
+    it('rmdir on non-empty folder without recursive throws', async () => {
+        await backend.write('t', 's', 'a/x.md', 'x');
+        await expect(backend.rmdir('t', 's', 'a', { recursive: false })).rejects.toThrow();
+    });
+    it('rmdir on empty folder without recursive succeeds', async () => {
+        await backend.mkdir('t', 's', 'a');
+        await backend.rmdir('t', 's', 'a', { recursive: false });
+        expect(await backend.listFolders('t', 's', '')).toEqual([]);
+    });
+    it('rmdir recursive removes folder and all descendants', async () => {
+        await backend.write('t', 's', 'a/x.md', 'x');
+        await backend.write('t', 's', 'a/b/y.md', 'y');
+        await backend.mkdir('t', 's', 'a/empty');
+        await backend.rmdir('t', 's', 'a', { recursive: true });
+        expect(await backend.listFolders('t', 's', '')).toEqual([]);
+        expect(await backend.list('t', 's')).toEqual([]);
+    });
+    it('renameFolder rewrites all descendant doc paths', async () => {
+        await backend.write('t', 's', 'old/x.md', 'x');
+        await backend.write('t', 's', 'old/sub/y.md', 'y');
+        await backend.renameFolder('t', 's', 'old', 'new');
+        const docs = (await backend.list('t', 's')).map((d) => d.path).sort();
+        expect(docs).toEqual(['new/sub/y.md', 'new/x.md']);
+    });
+    it('renameFolder rewrites empty subfolders too', async () => {
+        await backend.mkdir('t', 's', 'old/empty');
+        await backend.renameFolder('t', 's', 'old', 'new');
+        expect((await backend.listFolders('t', 's', 'new')).sort()).toEqual(['empty']);
+    });
+    it('renameFolder throws if newPath already exists', async () => {
+        await backend.mkdir('t', 's', 'a');
+        await backend.mkdir('t', 's', 'b');
+        await expect(backend.renameFolder('t', 's', 'a', 'b')).rejects.toThrow();
+    });
+    it('renameFolder throws if oldPath does not exist', async () => {
+        await expect(backend.renameFolder('t', 's', 'missing', 'b')).rejects.toThrow();
+    });
+});
+describe('IndexedDBDocumentBackend folder ops', () => {
+    let backend;
+    let t;
+    let s;
+    beforeEach(() => {
+        backend = new IndexedDBDocumentBackend();
+        t = 'tenant_' + Math.random().toString(36).slice(2, 10);
+        s = 'shard_' + Math.random().toString(36).slice(2, 10);
+    });
+    it('mkdir creates an empty folder visible via listFolders', async () => {
+        await backend.mkdir(t, s, 'a');
+        expect(await backend.listFolders(t, s, '')).toEqual(['a']);
+    });
+    it('mkdir is a no-op if the folder already exists', async () => {
+        await backend.mkdir(t, s, 'a');
+        await backend.mkdir(t, s, 'a');
+        expect(await backend.listFolders(t, s, '')).toEqual(['a']);
+    });
+    it('mkdir throws if a document occupies the path', async () => {
+        await backend.write(t, s, 'a', 'content');
+        await expect(backend.mkdir(t, s, 'a')).rejects.toThrow();
+    });
+    it('listFolders surfaces folders implied by document paths', async () => {
+        await backend.write(t, s, 'sub/a.md', 'x');
+        expect(await backend.listFolders(t, s, '')).toEqual(['sub']);
+    });
+    it('listFolders merges explicit and implicit folders without duplicates', async () => {
+        await backend.mkdir(t, s, 'sub');
+        await backend.write(t, s, 'sub/a.md', 'x');
+        expect(await backend.listFolders(t, s, '')).toEqual(['sub']);
+    });
+    it('listFolders with prefix returns immediate children', async () => {
+        await backend.mkdir(t, s, 'a/b');
+        await backend.mkdir(t, s, 'a/c');
+        await backend.write(t, s, 'a/d/x.md', 'x');
+        const children = await backend.listFolders(t, s, 'a');
+        expect(children.sort()).toEqual(['b', 'c', 'd']);
+    });
+    it('rmdir on non-empty folder without recursive throws', async () => {
+        await backend.write(t, s, 'a/x.md', 'x');
+        await expect(backend.rmdir(t, s, 'a', { recursive: false })).rejects.toThrow();
+    });
+    it('rmdir on empty folder without recursive succeeds', async () => {
+        await backend.mkdir(t, s, 'a');
+        await backend.rmdir(t, s, 'a', { recursive: false });
+        expect(await backend.listFolders(t, s, '')).toEqual([]);
+    });
+    it('rmdir recursive removes folder and all descendants', async () => {
+        await backend.write(t, s, 'a/x.md', 'x');
+        await backend.write(t, s, 'a/b/y.md', 'y');
+        await backend.mkdir(t, s, 'a/empty');
+        await backend.rmdir(t, s, 'a', { recursive: true });
+        expect(await backend.listFolders(t, s, '')).toEqual([]);
+        expect(await backend.list(t, s)).toEqual([]);
+    });
+    it('renameFolder rewrites all descendant doc paths', async () => {
+        await backend.write(t, s, 'old/x.md', 'x');
+        await backend.write(t, s, 'old/sub/y.md', 'y');
+        await backend.renameFolder(t, s, 'old', 'new');
+        const docs = (await backend.list(t, s)).map((d) => d.path).sort();
+        expect(docs).toEqual(['new/sub/y.md', 'new/x.md']);
+    });
+    it('renameFolder rewrites empty subfolders too', async () => {
+        await backend.mkdir(t, s, 'old/empty');
+        await backend.renameFolder(t, s, 'old', 'new');
+        expect((await backend.listFolders(t, s, 'new')).sort()).toEqual(['empty']);
+    });
+    it('renameFolder throws if newPath already exists', async () => {
+        await backend.mkdir(t, s, 'a');
+        await backend.mkdir(t, s, 'b');
+        await expect(backend.renameFolder(t, s, 'a', 'b')).rejects.toThrow();
+    });
+    it('renameFolder throws if oldPath does not exist', async () => {
+        await expect(backend.renameFolder(t, s, 'missing', 'b')).rejects.toThrow();
+    });
+});

package/dist/documents/config.d.ts

@@ -4,6 +4,8 @@ import type { DocumentBackend } from './types';
  *  scopeId for all document operations. Wired by createShell after bootstrap. */
 export declare function __setScopeResolver(resolver: (() => string | null) | null): void;
 export declare function getActiveScopeId(): string;
+/** The user's base (personal) tenant id — never overridden by the project resolver. */
+export declare function getPersonalScopeId(): string;
 /** @deprecated use getActiveScopeId — kept until callers migrate. */
 export declare function getTenantId(): string;
 export declare function getDocumentBackend(): DocumentBackend;

package/dist/documents/config.js

@@ -27,6 +27,10 @@ export function getActiveScopeId() {
     var _a;
     return (_a = scopeResolver === null || scopeResolver === void 0 ? void 0 : scopeResolver()) !== null && _a !== void 0 ? _a : scopeId;
 }
+/** The user's base (personal) tenant id — never overridden by the project resolver. */
+export function getPersonalScopeId() {
+    return scopeId;
+}
 /** @deprecated use getActiveScopeId — kept until callers migrate. */
 export function getTenantId() {
     return getActiveScopeId();

package/dist/documents/handle.js

@@ -86,6 +86,46 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
                 shardId,
             });
         },
+        async mkdir(path, opts) {
+            const tid = resolveTenant(opts);
+            await backend.mkdir(tid, shardId, path);
+            documentChanges.emit({ type: 'folder-create', path, tenantId: tid, shardId });
+        },
+        async rmdir(path, opts) {
+            var _a;
+            const recursive = (_a = opts === null || opts === void 0 ? void 0 : opts.recursive) !== null && _a !== void 0 ? _a : false;
+            if (recursive) {
+                const folderPrefix = path + '/';
+                for (const ctrl of controllers) {
+                    if (ctrl.path === path || ctrl.path.startsWith(folderPrefix)) {
+                        throw new Error(`Cannot rmdir ${path}: active autosave on ${ctrl.path}; flush and dispose first`);
+                    }
+                }
+            }
+            const tid = resolveTenant(opts);
+            await backend.rmdir(tid, shardId, path, { recursive });
+            documentChanges.emit({ type: 'folder-delete', path, tenantId: tid, shardId });
+        },
+        async renameFolder(oldPath, newPath, opts) {
+            const folderPrefix = oldPath + '/';
+            for (const ctrl of controllers) {
+                if (ctrl.path === oldPath || ctrl.path.startsWith(folderPrefix)) {
+                    throw new Error(`Cannot rename folder ${oldPath}: active autosave on ${ctrl.path}; flush and dispose first`);
+                }
+            }
+            const tid = resolveTenant(opts);
+            await backend.renameFolder(tid, shardId, oldPath, newPath);
+            documentChanges.emit({
+                type: 'folder-rename',
+                path: newPath,
+                oldPath,
+                tenantId: tid,
+                shardId,
+            });
+        },
+        async listFolders(prefix, opts) {
+            return backend.listFolders(resolveTenant(opts), shardId, prefix !== null && prefix !== void 0 ? prefix : '');
+        },
         async exists(path) {
             return backend.exists(tenantId, shardId, path);
         },

package/dist/documents/handle.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { MemoryDocumentBackend } from './backends';
 import { createDocumentHandle } from './handle';
 import { documentChanges } from './notifications';
@@ -28,6 +28,10 @@ describe('DocumentHandle.status()', () => {
             async exists() { return false; },
             async listAllShards() { return []; },
             async listAllDocuments() { return []; },
+            async mkdir() { },
+            async rmdir() { },
+            async renameFolder() { },
+            async listFolders() { return []; },
         };
         const handle = createDocumentHandle('t', 's', backend, { format: 'text' });
         await expect(handle.status('a.txt')).rejects.toThrow(/status/);
@@ -46,6 +50,10 @@ describe('DocumentHandle.resolveConflict()', () => {
             async listAllShards() { return []; },
             async listAllDocuments() { return []; },
             async resolve(t, s, p, c) { resolved.push({ t, s, p, c }); },
+            async mkdir() { },
+            async rmdir() { },
+            async renameFolder() { },
+            async listFolders() { return []; },
         };
         const handle = createDocumentHandle('tenant1', 'shard1', backend, { format: 'text' });
         await handle.resolveConflict('a.txt', 'local');
@@ -69,6 +77,10 @@ describe('DocumentHandle.readBranch()', () => {
             async listAllShards() { return []; },
             async listAllDocuments() { return []; },
             async readBranch(...args) { calls.push(args); return 'remote-content'; },
+            async mkdir() { },
+            async rmdir() { },
+            async renameFolder() { },
+            async listFolders() { return []; },
         };
         const handle = createDocumentHandle('tenant1', 'shard1', backend, { format: 'text' });
         const out = await handle.readBranch('a.txt', 'peer-1');
@@ -86,6 +98,10 @@ describe('DocumentHandle.readBranch()', () => {
             async listAllShards() { return []; },
             async listAllDocuments() { return []; },
             async readBranch() { return null; },
+            async mkdir() { },
+            async rmdir() { },
+            async renameFolder() { },
+            async listFolders() { return []; },
         };
         const handle = createDocumentHandle('t', 's', backend, { format: 'text' });
         expect(await handle.readBranch('a.txt', 'peer-1')).toBeNull();
@@ -164,3 +180,74 @@ describe('DocumentHandle.delete()', () => {
         unsub();
     });
 });
+describe('DocumentHandle folder ops', () => {
+    let backend;
+    let handle;
+    beforeEach(() => {
+        backend = new MemoryDocumentBackend();
+        handle = createDocumentHandle('t', 's', backend, { format: 'text' });
+    });
+    it('mkdir forwards to backend with bound tenant/shard', async () => {
+        await handle.mkdir('a');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['a']);
+    });
+    it('rmdir defaults recursive to false', async () => {
+        await handle.write('a/x.md', 'x');
+        await expect(handle.rmdir('a')).rejects.toThrow();
+    });
+    it('rmdir({recursive:true}) cascades', async () => {
+        await handle.write('a/x.md', 'x');
+        await handle.rmdir('a', { recursive: true });
+        expect(await handle.list()).toEqual([]);
+    });
+    it('renameFolder rewrites descendant paths', async () => {
+        await handle.write('old/x.md', 'x');
+        await handle.renameFolder('old', 'new');
+        const docs = (await handle.list()).map((d) => d.path).sort();
+        expect(docs).toEqual(['new/x.md']);
+    });
+    it('renameFolder refused when an autosave controller is inside the folder', async () => {
+        const ctrl = handle.autosave('a/x.md');
+        ctrl.update('content');
+        await expect(handle.renameFolder('a', 'b')).rejects.toThrow(/autosave/i);
+        await ctrl.dispose();
+    });
+    it('rmdir(recursive) refused when an autosave controller is inside the folder', async () => {
+        const ctrl = handle.autosave('a/x.md');
+        ctrl.update('content');
+        await expect(handle.rmdir('a', { recursive: true })).rejects.toThrow(/autosave/i);
+        await ctrl.dispose();
+    });
+    it('listFolders forwards to backend', async () => {
+        await handle.mkdir('a');
+        expect(await handle.listFolders()).toEqual(['a']);
+        expect(await handle.listFolders('a')).toEqual([]);
+    });
+    it('mkdir emits folder-create change event', async () => {
+        const events = [];
+        handle.watch((c) => events.push(c));
+        await handle.mkdir('a');
+        expect(events).toEqual([
+            { type: 'folder-create', path: 'a', tenantId: 't', shardId: 's' },
+        ]);
+    });
+    it('rmdir(recursive) emits a single folder-delete event', async () => {
+        await handle.write('a/x.md', 'x');
+        await handle.write('a/y.md', 'y');
+        const events = [];
+        handle.watch((c) => events.push(c));
+        await handle.rmdir('a', { recursive: true });
+        expect(events).toEqual([
+            { type: 'folder-delete', path: 'a', tenantId: 't', shardId: 's' },
+        ]);
+    });
+    it('renameFolder emits a single folder-rename event', async () => {
+        await handle.write('old/x.md', 'x');
+        const events = [];
+        handle.watch((c) => events.push(c));
+        await handle.renameFolder('old', 'new');
+        expect(events).toEqual([
+            { type: 'folder-rename', path: 'new', oldPath: 'old', tenantId: 't', shardId: 's' },
+        ]);
+    });
+});