sh3-core 0.19.6 → 0.20.2

package/dist/documents/browse.d.ts

@@ -91,6 +91,23 @@ export interface BrowseCapability {
      * `typeof ctx.browse.deleteFrom === 'function'`.
      */
     deleteFrom?(shardId: string, path: string): Promise<void>;
+    /**
+     * Copy or move a document from the active tenant to another scope.
+     * Available only when the caller declares both `documents:browse` and
+     * `documents:write`. Used for transferring documents between a user's
+     * personal scope and a project scope (or vice versa).
+     *
+     * When `opts.delete` is true, the source document is removed after
+     * copying (effectively a move/transfer). Default: false (copy only).
+     *
+     * Absent (undefined) on the capability object when `documents:write`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.transferToScope === 'function'`.
+     */
+    transferToScope?(shardId: string, path: string, targetScope: string, opts?: {
+        targetShardId?: string;
+        delete?: boolean;
+    }): Promise<void>;
 }
 export interface BrowseCapabilityOptions {
     /** When true, the returned capability exposes `readFrom`. */
@@ -98,4 +115,4 @@ export interface BrowseCapabilityOptions {
     /** When true, the returned capability exposes `writeTo`. */
     canWrite: boolean;
 }
-export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend, options?: BrowseCapabilityOptions): BrowseCapability;
+export declare function createBrowseCapability(getTenantId: () => string, backend: DocumentBackend, options?: BrowseCapabilityOptions): BrowseCapability;

package/dist/documents/browse.js

@@ -4,33 +4,39 @@
  * Exposed on ShardContext as `ctx.browse` when the shard declares the
  * 'documents:browse' permission. Read-only: writes still flow through
  * the owning shard's own ctx.documents() handle.
+ *
+ * Tenant id is resolved lazily via a callback so that the browse
+ * capability automatically follows the active scope (personal tenant
+ * vs. active project). The callback is wired by the framework at
+ * shard activation time.
  */
 import { documentChanges } from './notifications';
-export function createBrowseCapability(tenantId, backend, options = { canRead: false, canWrite: false }) {
+export function createBrowseCapability(getTenantId, backend, options = { canRead: false, canWrite: false }) {
     const capability = {
-        listDocuments: () => backend.listAllDocuments(tenantId),
-        listShards: () => backend.listAllShards(tenantId),
+        listDocuments: () => backend.listAllDocuments(getTenantId()),
+        listShards: () => backend.listAllShards(getTenantId()),
         watchDocuments: (callback) => documentChanges.subscribe((change) => {
-            if (change.tenantId !== tenantId)
+            if (change.tenantId !== getTenantId())
                 return;
             callback(change);
         }),
     };
     if (options.canRead) {
-        capability.readFrom = (shardId, path) => backend.read(tenantId, shardId, path);
+        capability.readFrom = (shardId, path) => backend.read(getTenantId(), shardId, path);
         capability.statusFrom = async (shardId, path) => {
             if (!backend.readMeta)
                 return null;
-            return backend.readMeta(tenantId, shardId, path);
+            return backend.readMeta(getTenantId(), shardId, path);
         };
         capability.readBranchFrom = async (shardId, path, origin) => {
             if (!backend.readBranch)
                 return null;
-            return backend.readBranch(tenantId, shardId, path, origin);
+            return backend.readBranch(getTenantId(), shardId, path, origin);
         };
     }
     if (options.canWrite) {
         capability.writeTo = async (shardId, path, content) => {
+            const tenantId = getTenantId();
             const existed = await backend.exists(tenantId, shardId, path);
             await backend.write(tenantId, shardId, path, content);
             documentChanges.emit({
@@ -43,6 +49,7 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
         capability.resolveConflictFrom = async (shardId, path, choice) => {
             if (!backend.resolve)
                 throw new Error('Backend does not support resolveConflict');
+            const tenantId = getTenantId();
             await backend.resolve(tenantId, shardId, path, choice);
             documentChanges.emit({ type: 'update', path, tenantId, shardId });
         };
@@ -50,6 +57,7 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
             if ((opts === null || opts === void 0 ? void 0 : opts.newShardId) !== undefined) {
                 throw new Error('Cross-shard move is not yet supported (ADR-018 amendment 2026-04-27)');
             }
+            const tenantId = getTenantId();
             await backend.rename(tenantId, shardId, oldPath, newPath);
             documentChanges.emit({
                 type: 'rename',
@@ -60,12 +68,37 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
             });
         };
         capability.deleteFrom = async (shardId, path) => {
+            const tenantId = getTenantId();
             const existed = await backend.exists(tenantId, shardId, path);
             await backend.delete(tenantId, shardId, path);
             if (existed) {
                 documentChanges.emit({ type: 'delete', path, tenantId, shardId });
             }
         };
+        capability.transferToScope = async (shardId, path, targetScope, opts) => {
+            var _a;
+            const tenantId = getTenantId();
+            if (targetScope === tenantId) {
+                throw new Error('targetScope must differ from the active tenant');
+            }
+            const targetShard = (_a = opts === null || opts === void 0 ? void 0 : opts.targetShardId) !== null && _a !== void 0 ? _a : shardId;
+            const content = await backend.read(tenantId, shardId, path);
+            if (content === null) {
+                throw new Error(`Document not found at ${shardId}/${path} in scope ${tenantId}`);
+            }
+            const existed = await backend.exists(targetScope, targetShard, path);
+            await backend.write(targetScope, targetShard, path, content);
+            documentChanges.emit({
+                type: existed ? 'update' : 'create',
+                path,
+                tenantId: targetScope,
+                shardId: targetShard,
+            });
+            if (opts === null || opts === void 0 ? void 0 : opts.delete) {
+                await backend.delete(tenantId, shardId, path);
+                documentChanges.emit({ type: 'delete', path, tenantId, shardId });
+            }
+        };
     }
     return capability;
 }

package/dist/documents/browse.test.js

@@ -7,7 +7,7 @@ describe('BrowseCapability', () => {
         const be = new MemoryDocumentBackend();
         await be.write('t1', 'a', 'x.txt', '1');
         await be.write('t1', 'b', 'y.txt', '22');
-        const browse = createBrowseCapability('t1', be);
+        const browse = createBrowseCapability(() => 't1', be);
         const docs = await browse.listDocuments();
         expect(docs.map((d) => d.shardId).sort()).toEqual(['a', 'b']);
     });
@@ -15,12 +15,12 @@ describe('BrowseCapability', () => {
         const be = new MemoryDocumentBackend();
         await be.write('t1', 'a', 'x.txt', '1');
         await be.write('t1', 'b', 'y.txt', '2');
-        const browse = createBrowseCapability('t1', be);
+        const browse = createBrowseCapability(() => 't1', be);
         expect((await browse.listShards()).sort()).toEqual(['a', 'b']);
     });
     it('watchDocuments fires with shardId on tenant-wide emits; filters other tenants', () => {
         const be = new MemoryDocumentBackend();
-        const browse = createBrowseCapability('t1', be);
+        const browse = createBrowseCapability(() => 't1', be);
         const cb = vi.fn();
         const unsub = browse.watchDocuments(cb);
         documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
@@ -31,7 +31,7 @@ describe('BrowseCapability', () => {
     });
     it('watchDocuments unsubscribe stops callbacks', () => {
         const be = new MemoryDocumentBackend();
-        const browse = createBrowseCapability('t1', be);
+        const browse = createBrowseCapability(() => 't1', be);
         const cb = vi.fn();
         const unsub = browse.watchDocuments(cb);
         unsub();
@@ -41,46 +41,46 @@ describe('BrowseCapability', () => {
     describe('readFrom (documents:read gate)', () => {
         it('is absent when canRead is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
             expect(browse.readFrom).toBeUndefined();
         });
         it('is present when canRead is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(typeof browse.readFrom).toBe('function');
         });
         it('reads content from a foreign shard namespace', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 'other', 'notes/ideas.md', 'hello');
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.readFrom('other', 'notes/ideas.md')).toBe('hello');
         });
         it('returns null when the foreign document does not exist', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.readFrom('other', 'nope.txt')).toBeNull();
         });
         it('never crosses tenants: a t1 capability cannot read t2 docs', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t2', 's', 'secret.txt', 'hidden');
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.readFrom('s', 'secret.txt')).toBeNull();
         });
     });
     describe('writeTo (documents:write gate)', () => {
         it('is absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
             expect(browse.writeTo).toBeUndefined();
         });
         it('is present when canWrite is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             expect(typeof browse.writeTo).toBe('function');
         });
         it('writes into the target shard namespace and emits a create change', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await browse.writeTo('target-shard', 'notes/ideas.md', 'hello');
@@ -93,7 +93,7 @@ describe('BrowseCapability', () => {
         it('emits update (not create) when overwriting an existing document', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 'target-shard', 'a.txt', 'v1');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await browse.writeTo('target-shard', 'a.txt', 'v2');
@@ -105,7 +105,7 @@ describe('BrowseCapability', () => {
         });
         it('never crosses tenants: cannot be tricked into writing into tenant b', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await browse.writeTo('s', 'a.txt', 'x');
             expect(await be.read('t1', 's', 'a.txt')).toBe('x');
             expect(await be.read('t2', 's', 'a.txt')).toBeNull();
@@ -114,7 +114,7 @@ describe('BrowseCapability', () => {
     describe('read + write combined', () => {
         it('round-trips content through readFrom after writeTo', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: true });
             await browse.writeTo('shard-x', 'doc.txt', 'roundtrip');
             expect(await browse.readFrom('shard-x', 'doc.txt')).toBe('roundtrip');
         });
@@ -122,13 +122,13 @@ describe('BrowseCapability', () => {
     describe('statusFrom / readBranchFrom (documents:read gate)', () => {
         it('absent when canRead is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
             expect(browse.statusFrom).toBeUndefined();
             expect(browse.readBranchFrom).toBeUndefined();
         });
         it('present when canRead is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(typeof browse.statusFrom).toBe('function');
             expect(typeof browse.readBranchFrom).toBe('function');
         });
@@ -144,13 +144,13 @@ describe('BrowseCapability', () => {
                 listAllDocuments: vi.fn(async () => []),
                 readMeta: vi.fn(async (...args) => { calls.push(args); return null; }),
             };
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             await browse.statusFrom('other', 'a.txt');
             expect(calls[0]).toEqual(['t1', 'other', 'a.txt']);
         });
         it('statusFrom returns null when backend has no readMeta', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.statusFrom('other', 'a.txt')).toBeNull();
         });
         it('readBranchFrom delegates to backend.readBranch with tenant baked in', async () => {
@@ -165,32 +165,32 @@ describe('BrowseCapability', () => {
                 listAllDocuments: vi.fn(async () => []),
                 readBranch: vi.fn(async (...args) => { calls.push(args); return 'x'; }),
             };
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             const out = await browse.readBranchFrom('other', 'a.txt', 'peer-1');
             expect(out).toBe('x');
             expect(calls[0]).toEqual(['t1', 'other', 'a.txt', 'peer-1']);
         });
         it('readBranchFrom returns null when backend has no readBranch', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.readBranchFrom('other', 'a.txt', 'peer-1')).toBeNull();
         });
     });
     describe('renameFrom (documents:write gate)', () => {
         it('absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
             expect(browse.renameFrom).toBeUndefined();
         });
         it('present when canWrite is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             expect(typeof browse.renameFrom).toBe('function');
         });
         it('renames in the target shard namespace and emits a rename event', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 'target-shard', 'old.txt', 'hello');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await browse.renameFrom('target-shard', 'old.txt', 'new.txt');
@@ -210,7 +210,7 @@ describe('BrowseCapability', () => {
         it('never crosses tenants: cannot be tricked into renaming in tenant b', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t2', 's', 'old.txt', 'hidden');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await expect(browse.renameFrom('s', 'old.txt', 'new.txt'))
                 .rejects.toThrow(/not found/);
             expect(await be.read('t2', 's', 'old.txt')).toBe('hidden');
@@ -218,7 +218,7 @@ describe('BrowseCapability', () => {
         it('throws when opts.newShardId is provided (cross-shard move reserved)', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 's1', 'old.txt', 'hello');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await expect(browse.renameFrom('s1', 'old.txt', 'new.txt', { newShardId: 's2' })).rejects.toThrow(/Cross-shard move is not yet supported/);
             expect(await be.read('t1', 's1', 'old.txt')).toBe('hello');
         });
@@ -226,12 +226,12 @@ describe('BrowseCapability', () => {
     describe('resolveConflictFrom (documents:write gate)', () => {
         it('absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(browse.resolveConflictFrom).toBeUndefined();
         });
         it('present when canWrite is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             expect(typeof browse.resolveConflictFrom).toBe('function');
         });
         it('delegates to backend.resolve with tenant baked in and emits an update', async () => {
@@ -246,7 +246,7 @@ describe('BrowseCapability', () => {
                 listAllDocuments: vi.fn(async () => []),
                 resolve: vi.fn(async (...args) => { calls.push(args); }),
             };
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((e) => events.push(e));
             await browse.resolveConflictFrom('other', 'a.txt', { origin: 'peer-1' });
@@ -258,7 +258,7 @@ describe('BrowseCapability', () => {
         });
         it('throws if backend does not support resolve', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await expect(browse.resolveConflictFrom('other', 'a.txt', { origin: 'peer-1' }))
                 .rejects.toThrow(/does not support resolveConflict/);
         });
@@ -266,18 +266,18 @@ describe('BrowseCapability', () => {
     describe('deleteFrom (documents:write gate)', () => {
         it('absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(browse.deleteFrom).toBeUndefined();
         });
         it('present when canWrite is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             expect(typeof browse.deleteFrom).toBe('function');
         });
         it('deletes from the target shard namespace and emits a delete event', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 'target-shard', 'a.txt', 'hello');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await browse.deleteFrom('target-shard', 'a.txt');
@@ -289,7 +289,7 @@ describe('BrowseCapability', () => {
         });
         it('is idempotent on missing paths and emits no event', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await expect(browse.deleteFrom('target-shard', 'nope.txt')).resolves.toBeUndefined();
@@ -299,7 +299,7 @@ describe('BrowseCapability', () => {
         it('never crosses tenants: a t1 capability cannot delete t2 docs', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t2', 's', 'secret.txt', 'hidden');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await browse.deleteFrom('s', 'secret.txt');
             expect(await be.read('t2', 's', 'secret.txt')).toBe('hidden');
         });

package/dist/documents/config.d.ts

@@ -1,5 +1,11 @@
 import type { DocumentBackend } from './types';
+/** Host-only. Register a callback that resolves the active project scope.
+ *  When non-null and returns a string, that string overrides the static
+ *  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

@@ -5,18 +5,35 @@
  * calls __setActiveScope and __setDocumentBackend before bootstrap() to
  * configure multi-scope routing and swap backends (e.g. Tauri FS).
  *
+ * Project scope: when a project is active (sessionState.activeProjectId),
+ * the scope resolver returns the project id so all document operations
+ * operate on the project's virtual tenant instead of the user's personal
+ * scope. The resolver is wired by createShell after bootstrap.
+ *
  * Defaults: scopeId='local' (single-user self-hosted), backend=IndexedDB.
  */
 import { IndexedDBDocumentBackend } from './backends';
 const DEFAULT_SCOPE = 'local';
 let scopeId = DEFAULT_SCOPE;
 let backend = new IndexedDBDocumentBackend();
+let scopeResolver = null;
+/** Host-only. Register a callback that resolves the active project scope.
+ *  When non-null and returns a string, that string overrides the static
+ *  scopeId for all document operations. Wired by createShell after bootstrap. */
+export function __setScopeResolver(resolver) {
+    scopeResolver = resolver;
+}
 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 scopeId;
+    return getActiveScopeId();
 }
 export function getDocumentBackend() {
     return backend;

package/dist/documents/handle.js

@@ -31,36 +31,43 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
             return true;
         return options.extensions.some((ext) => path.endsWith(ext));
     }
-    function emitChange(type, path) {
-        documentChanges.emit({ type, path, tenantId, shardId });
+    function resolveTenant(opts) {
+        var _a;
+        return (_a = opts === null || opts === void 0 ? void 0 : opts.scope) !== null && _a !== void 0 ? _a : tenantId;
+    }
+    function emitChange(type, path, tid) {
+        documentChanges.emit({ type, path, tenantId: tid, shardId });
     }
     const handle = {
-        async list() {
-            const all = await backend.list(tenantId, shardId);
+        async list(opts) {
+            const tid = resolveTenant(opts);
+            const all = await backend.list(tid, shardId);
             if (!options.extensions || options.extensions.length === 0)
                 return all;
             return all.filter((meta) => matchesExtensions(meta.path));
         },
-        async read(path) {
-            const content = await backend.read(tenantId, shardId, path);
+        async read(path, opts) {
+            const content = await backend.read(resolveTenant(opts), shardId, path);
             if (content === null)
                 return null;
             // Phase 1: text format only. Binary returns as-is from the backend
             // but the handle types it as string for text-format handles.
             return typeof content === 'string' ? content : new TextDecoder().decode(content);
         },
-        async write(path, content) {
-            const existed = await backend.exists(tenantId, shardId, path);
-            await backend.write(tenantId, shardId, path, content);
-            emitChange(existed ? 'update' : 'create', path);
+        async write(path, content, opts) {
+            const tid = resolveTenant(opts);
+            const existed = await backend.exists(tid, shardId, path);
+            await backend.write(tid, shardId, path, content);
+            emitChange(existed ? 'update' : 'create', path, tid);
         },
-        async delete(path) {
-            const existed = await backend.exists(tenantId, shardId, path);
-            await backend.delete(tenantId, shardId, path);
+        async delete(path, opts) {
+            const tid = resolveTenant(opts);
+            const existed = await backend.exists(tid, shardId, path);
+            await backend.delete(tid, shardId, path);
             if (existed)
-                emitChange('delete', path);
+                emitChange('delete', path, tid);
         },
-        async rename(oldPath, newPath) {
+        async rename(oldPath, newPath, opts) {
             if (!matchesExtensions(newPath)) {
                 throw new Error(`Cannot rename to ${newPath}: violates handle extensions filter`);
             }
@@ -69,15 +76,56 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
                     throw new Error(`Cannot rename: active autosave on ${oldPath}; flush and dispose first`);
                 }
             }
-            await backend.rename(tenantId, shardId, oldPath, newPath);
+            const tid = resolveTenant(opts);
+            await backend.rename(tid, shardId, oldPath, newPath);
             documentChanges.emit({
                 type: 'rename',
                 path: newPath,
                 oldPath,
-                tenantId,
+                tenantId: tid,
+                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);
         },