sh3-core 0.11.4 → 0.11.7

package/dist/documents/backends.test.js

@@ -1,5 +1,6 @@
+import 'fake-indexeddb/auto';
 import { describe, it, expect } from 'vitest';
-import { MemoryDocumentBackend } from './backends';
+import { MemoryDocumentBackend, IndexedDBDocumentBackend } from './backends';
 describe('DocumentBackend tenant-wide primitives', () => {
     it('listAllShards returns every shard that has content for a tenant', async () => {
         const be = new MemoryDocumentBackend();
@@ -31,3 +32,70 @@ describe('DocumentBackend tenant-wide primitives', () => {
         expect(await be.listAllShards('ghost')).toEqual([]);
     });
 });
+describe('MemoryDocumentBackend.rename', () => {
+    it('moves content from oldPath to newPath', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 's1', 'old.txt', 'hello');
+        await be.rename('t1', 's1', 'old.txt', 'new.txt');
+        expect(await be.read('t1', 's1', 'new.txt')).toBe('hello');
+        expect(await be.read('t1', 's1', 'old.txt')).toBeNull();
+        expect(await be.exists('t1', 's1', 'new.txt')).toBe(true);
+        expect(await be.exists('t1', 's1', 'old.txt')).toBe(false);
+    });
+    it('preserves size and lastModified semantics on the new key', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 's1', 'old.txt', 'hello');
+        const before = await be.list('t1', 's1');
+        await be.rename('t1', 's1', 'old.txt', 'new.txt');
+        const after = await be.list('t1', 's1');
+        expect(after).toHaveLength(1);
+        expect(after[0].path).toBe('new.txt');
+        expect(after[0].size).toBe(before[0].size);
+    });
+    it('throws when newPath already exists; original content unchanged', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 's1', 'old.txt', 'src');
+        await be.write('t1', 's1', 'new.txt', 'target');
+        await expect(be.rename('t1', 's1', 'old.txt', 'new.txt'))
+            .rejects.toThrow(/already exists/);
+        expect(await be.read('t1', 's1', 'new.txt')).toBe('target');
+        expect(await be.read('t1', 's1', 'old.txt')).toBe('src');
+    });
+    it('throws when oldPath does not exist', async () => {
+        const be = new MemoryDocumentBackend();
+        await expect(be.rename('t1', 's1', 'ghost.txt', 'new.txt'))
+            .rejects.toThrow(/not found/);
+    });
+    it('respects tenant + shard isolation', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 's1', 'a.txt', 'one');
+        await be.write('t2', 's1', 'a.txt', 'two');
+        await be.rename('t1', 's1', 'a.txt', 'b.txt');
+        expect(await be.read('t1', 's1', 'b.txt')).toBe('one');
+        expect(await be.read('t2', 's1', 'a.txt')).toBe('two');
+        expect(await be.read('t2', 's1', 'b.txt')).toBeNull();
+    });
+});
+describe('IndexedDBDocumentBackend.rename', () => {
+    it('moves content from oldPath to newPath atomically', async () => {
+        const be = new IndexedDBDocumentBackend();
+        await be.write('t1', 's1', 'old.txt', 'hello');
+        await be.rename('t1', 's1', 'old.txt', 'new.txt');
+        expect(await be.read('t1', 's1', 'new.txt')).toBe('hello');
+        expect(await be.read('t1', 's1', 'old.txt')).toBeNull();
+    });
+    it('throws when newPath already exists; original content unchanged', async () => {
+        const be = new IndexedDBDocumentBackend();
+        await be.write('t1', 's1', 'old.txt', 'src');
+        await be.write('t1', 's1', 'new.txt', 'target');
+        await expect(be.rename('t1', 's1', 'old.txt', 'new.txt'))
+            .rejects.toThrow(/already exists/);
+        expect(await be.read('t1', 's1', 'new.txt')).toBe('target');
+        expect(await be.read('t1', 's1', 'old.txt')).toBe('src');
+    });
+    it('throws when oldPath does not exist', async () => {
+        const be = new IndexedDBDocumentBackend();
+        await expect(be.rename('t1', 's1', 'ghost.txt', 'new.txt'))
+            .rejects.toThrow(/not found/);
+    });
+});

package/dist/documents/browse.d.ts

@@ -58,6 +58,24 @@ export interface BrowseCapability {
     resolveConflictFrom?(shardId: string, path: string, choice: 'local' | 'remote' | {
         origin: string;
     } | string): Promise<void>;
+    /**
+     * Rename a document in another shard's namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:write`. Emits a `'rename'`
+     * `DocumentChange` so other shards and the file-explorer pick up
+     * the move. Tenant-scoped — cannot cross tenants.
+     *
+     * The optional `opts.newShardId` parameter is reserved for a future
+     * cross-shard move operation per ADR-018 amendment 2026-04-27 and
+     * throws at runtime if provided.
+     *
+     * Absent (undefined) on the capability object when `documents:write`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.renameFrom === 'function'`.
+     */
+    renameFrom?(shardId: string, oldPath: string, newPath: string, opts?: {
+        newShardId?: string;
+    }): Promise<void>;
 }
 export interface BrowseCapabilityOptions {
     /** When true, the returned capability exposes `readFrom`. */

package/dist/documents/browse.js

@@ -46,6 +46,19 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
             await backend.resolve(tenantId, shardId, path, choice);
             documentChanges.emit({ type: 'update', path, tenantId, shardId });
         };
+        capability.renameFrom = async (shardId, oldPath, newPath, opts) => {
+            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)');
+            }
+            await backend.rename(tenantId, shardId, oldPath, newPath);
+            documentChanges.emit({
+                type: 'rename',
+                path: newPath,
+                oldPath,
+                tenantId,
+                shardId,
+            });
+        };
     }
     return capability;
 }

package/dist/documents/browse.test.js

@@ -176,6 +176,53 @@ describe('BrowseCapability', () => {
             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 });
+            expect(browse.renameFrom).toBeUndefined();
+        });
+        it('present when canWrite is true', () => {
+            const be = new MemoryDocumentBackend();
+            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 events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.renameFrom('target-shard', 'old.txt', 'new.txt');
+            expect(await be.read('t1', 'target-shard', 'new.txt')).toBe('hello');
+            expect(await be.read('t1', 'target-shard', 'old.txt')).toBeNull();
+            expect(events).toEqual([
+                {
+                    type: 'rename',
+                    path: 'new.txt',
+                    oldPath: 'old.txt',
+                    tenantId: 't1',
+                    shardId: 'target-shard',
+                },
+            ]);
+            unsub();
+        });
+        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 });
+            await expect(browse.renameFrom('s', 'old.txt', 'new.txt'))
+                .rejects.toThrow(/not found/);
+            expect(await be.read('t2', 's', 'old.txt')).toBe('hidden');
+        });
+        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 });
+            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');
+        });
+    });
     describe('resolveConflictFrom (documents:write gate)', () => {
         it('absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();

package/dist/documents/handle.js

@@ -58,6 +58,24 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
             await backend.delete(tenantId, shardId, path);
             emitChange('delete', path);
         },
+        async rename(oldPath, newPath) {
+            if (!matchesExtensions(newPath)) {
+                throw new Error(`Cannot rename to ${newPath}: violates handle extensions filter`);
+            }
+            for (const ctrl of controllers) {
+                if (ctrl.path === oldPath) {
+                    throw new Error(`Cannot rename: active autosave on ${oldPath}; flush and dispose first`);
+                }
+            }
+            await backend.rename(tenantId, shardId, oldPath, newPath);
+            documentChanges.emit({
+                type: 'rename',
+                path: newPath,
+                oldPath,
+                tenantId,
+                shardId,
+            });
+        },
         async exists(path) {
             return backend.exists(tenantId, shardId, path);
         },
@@ -135,6 +153,11 @@ class AutosaveControllerImpl {
     get dirty() {
         return __classPrivateFieldGet(this, _AutosaveControllerImpl_dirty, "f");
     }
+    /** Path this controller writes to. Exposed so DocumentHandle.rename
+     *  can refuse if a controller is active on the rename source. */
+    get path() {
+        return __classPrivateFieldGet(this, _AutosaveControllerImpl_path, "f");
+    }
     update(content) {
         if (__classPrivateFieldGet(this, _AutosaveControllerImpl_disposed, "f"))
             return;

package/dist/documents/handle.test.js

@@ -22,6 +22,7 @@ describe('DocumentHandle.status()', () => {
             async read() { return null; },
             async write() { },
             async delete() { },
+            async rename() { },
             async list() { return []; },
             async exists() { return false; },
             async listAllShards() { return []; },
@@ -38,6 +39,7 @@ describe('DocumentHandle.resolveConflict()', () => {
             async read() { return null; },
             async write() { },
             async delete() { },
+            async rename() { },
             async list() { return []; },
             async exists() { return false; },
             async listAllShards() { return []; },
@@ -60,6 +62,7 @@ describe('DocumentHandle.readBranch()', () => {
             async read() { return null; },
             async write() { },
             async delete() { },
+            async rename() { },
             async list() { return []; },
             async exists() { return false; },
             async listAllShards() { return []; },
@@ -76,6 +79,7 @@ describe('DocumentHandle.readBranch()', () => {
             async read() { return null; },
             async write() { },
             async delete() { },
+            async rename() { },
             async list() { return []; },
             async exists() { return false; },
             async listAllShards() { return []; },
@@ -90,3 +94,50 @@ describe('DocumentHandle.readBranch()', () => {
         await expect(handle.readBranch('a.txt', 'peer-1')).rejects.toThrow(/readBranch/);
     });
 });
+describe('DocumentHandle.rename', () => {
+    it('moves the doc and emits one rename event', async () => {
+        const { backend, handle } = harness();
+        await handle.write('old.txt', 'hello');
+        const events = [];
+        const unsub = (await import('./notifications')).documentChanges.subscribe((c) => events.push(c));
+        await handle.rename('old.txt', 'new.txt');
+        expect(await backend.read('tenant1', 'shard1', 'new.txt')).toBe('hello');
+        expect(await backend.read('tenant1', 'shard1', 'old.txt')).toBeNull();
+        expect(events.at(-1)).toEqual({
+            type: 'rename',
+            path: 'new.txt',
+            oldPath: 'old.txt',
+            tenantId: 'tenant1',
+            shardId: 'shard1',
+        });
+        unsub();
+    });
+    it('throws when an autosave controller is active on oldPath', async () => {
+        const { handle } = harness();
+        await handle.write('old.txt', 'v1');
+        const ctrl = handle.autosave('old.txt', { debounceMs: 10000 });
+        ctrl.update('v2');
+        await expect(handle.rename('old.txt', 'new.txt'))
+            .rejects.toThrow(/active autosave/);
+        await ctrl.dispose();
+    });
+    it('does not throw when an autosave controller exists for an unrelated path', async () => {
+        const { handle } = harness();
+        await handle.write('old.txt', 'src');
+        await handle.write('other.txt', 'unrelated');
+        const ctrl = handle.autosave('other.txt', { debounceMs: 10000 });
+        ctrl.update('still-unrelated');
+        await expect(handle.rename('old.txt', 'new.txt')).resolves.toBeUndefined();
+        await ctrl.dispose();
+    });
+    it('throws when newPath violates the handle extensions filter', async () => {
+        const backend = new MemoryDocumentBackend();
+        const handle = createDocumentHandle('t1', 's1', backend, {
+            format: 'text',
+            extensions: ['.txt'],
+        });
+        await handle.write('a.txt', 'hi');
+        await expect(handle.rename('a.txt', 'a.md'))
+            .rejects.toThrow(/extensions/);
+    });
+});

package/dist/documents/http-backend.d.ts

@@ -31,4 +31,5 @@ export declare class HttpDocumentBackend implements DocumentBackend {
         origin: string;
     } | string): Promise<void>;
     readBranch(tenantId: string, shardId: string, path: string, origin: string): Promise<string | null>;
+    rename(tenantId: string, shardId: string, oldPath: string, newPath: string): Promise<void>;
 }

package/dist/documents/http-backend.js

@@ -119,6 +119,25 @@ export class HttpDocumentBackend {
             throw new Error(`readBranch failed: ${res.status}`);
         return res.text();
     }
+    async rename(tenantId, shardId, oldPath, newPath) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${oldPath}/rename`;
+        const headers = Object.assign(Object.assign({}, __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this)), { 'Content-Type': 'application/json' });
+        const res = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ to: newPath }),
+            credentials: 'include',
+        });
+        if (res.status === 404) {
+            throw new Error(`Document not found at ${oldPath}`);
+        }
+        if (res.status === 409) {
+            throw new Error(`Document already exists at ${newPath}`);
+        }
+        if (!res.ok) {
+            throw new Error(`Document rename failed: ${res.status}`);
+        }
+    }
 }
 _HttpDocumentBackend_baseUrl = new WeakMap(), _HttpDocumentBackend_apiKey = new WeakMap(), _HttpDocumentBackend_instances = new WeakSet(), _HttpDocumentBackend_authHeaders = function _HttpDocumentBackend_authHeaders() {
     if (!__classPrivateFieldGet(this, _HttpDocumentBackend_apiKey, "f"))

package/dist/documents/http-backend.test.js

@@ -37,3 +37,45 @@ describe('HttpDocumentBackend.readBranch', () => {
         expect(calls[0]).toContain('origin=peer%20with%20space');
     });
 });
+describe('HttpDocumentBackend.rename', () => {
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it('POSTs to /api/docs/.../rename with { to } body and Authorization header', async () => {
+        var _a, _b, _c;
+        const calls = [];
+        globalThis.fetch = (async (url, init) => {
+            calls.push({ url: String(url), init });
+            return new Response(JSON.stringify({ ok: true, version: 2 }), { status: 200 });
+        });
+        const be = new HttpDocumentBackend('http://x', 'apikey-1');
+        await be.rename('t1', 'shard', 'old.txt', 'new.txt');
+        expect(calls).toHaveLength(1);
+        expect(calls[0].url).toBe('http://x/api/docs/t1/shard/old.txt/rename');
+        expect((_a = calls[0].init) === null || _a === void 0 ? void 0 : _a.method).toBe('POST');
+        const headers = (_b = calls[0].init) === null || _b === void 0 ? void 0 : _b.headers;
+        expect(headers === null || headers === void 0 ? void 0 : headers['Authorization']).toBe('Bearer apikey-1');
+        expect(headers === null || headers === void 0 ? void 0 : headers['Content-Type']).toBe('application/json');
+        expect(JSON.parse(String((_c = calls[0].init) === null || _c === void 0 ? void 0 : _c.body))).toEqual({ to: 'new.txt' });
+    });
+    it('throws "not found" on 404', async () => {
+        globalThis.fetch = (async () => new Response(null, { status: 404 }));
+        const be = new HttpDocumentBackend('http://x', 'apikey-1');
+        await expect(be.rename('t1', 'shard', 'ghost.txt', 'new.txt'))
+            .rejects.toThrow(/not found/);
+    });
+    it('throws "already exists" on 409', async () => {
+        globalThis.fetch = (async () => new Response(JSON.stringify({ error: 'Document already exists at new.txt' }), {
+            status: 409,
+        }));
+        const be = new HttpDocumentBackend('http://x', 'apikey-1');
+        await expect(be.rename('t1', 'shard', 'old.txt', 'new.txt'))
+            .rejects.toThrow(/already exists/);
+    });
+    it('throws on other non-2xx errors', async () => {
+        globalThis.fetch = (async () => new Response('boom', { status: 500 }));
+        const be = new HttpDocumentBackend('http://x', 'apikey-1');
+        await expect(be.rename('t1', 'shard', 'old.txt', 'new.txt'))
+            .rejects.toThrow(/rename failed/i);
+    });
+});

package/dist/documents/types.d.ts

@@ -72,11 +72,25 @@ export interface DocumentMeta {
 }
 /** Change notification payload delivered to watch callbacks. */
 export interface DocumentChange {
-    type: 'create' | 'update' | 'delete';
+    type: 'create' | 'update' | 'delete' | 'rename';
+    /**
+     * For 'create' / 'update' / 'delete', the affected document path.
+     * For 'rename', the new path the document now lives at.
+     */
     path: string;
+    /**
+     * Populated only when type === 'rename'. The path the document
+     * used to live at before the rename.
+     */
+    oldPath?: string;
     tenantId: string;
     shardId: string;
 }
+/** Type guard: narrows a DocumentChange to the rename variant. */
+export declare function isRename(change: DocumentChange): change is DocumentChange & {
+    type: 'rename';
+    oldPath: string;
+};
 import type { DocStatus } from './sync-types';
 /**
  * File-oriented backend for the document zone.
@@ -97,6 +111,13 @@ export interface DocumentBackend {
     write(tenantId: string, shardId: string, path: string, content: string | ArrayBuffer): Promise<void>;
     /** Delete a document. No-op if the document does not exist. */
     delete(tenantId: string, shardId: string, path: string): Promise<void>;
+    /**
+     * Rename a document within a single shard's namespace. Atomic at the
+     * backend's storage tier. Throws if newPath already exists or if oldPath
+     * does not. Single-document only — does not interpret trailing slashes
+     * as folder semantics.
+     */
+    rename(tenantId: string, shardId: string, oldPath: string, newPath: string): Promise<void>;
     /** List all documents stored for this tenant + shard combination. */
     list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
     /** Return true if the document at `path` exists. */
@@ -147,6 +168,13 @@ export interface DocumentHandle {
     write(path: string, content: string): Promise<void>;
     /** Delete a document. */
     delete(path: string): Promise<void>;
+    /**
+     * Rename a document. Throws if there is an active autosave controller
+     * for oldPath (caller must flush and dispose first). Throws if newPath
+     * already exists or if oldPath does not. Subject to the handle's
+     * extensions filter — newPath must satisfy the filter.
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
     /** Check existence without reading content. */
     exists(path: string): Promise<boolean>;
     /** Fetch sync-state metadata for a path. Null if the doc does not exist. */

package/dist/documents/types.js

@@ -45,3 +45,7 @@ export const PERMISSION_DOCUMENTS_READ = 'documents:read';
  * `browse`.
  */
 export const PERMISSION_DOCUMENTS_WRITE = 'documents:write';
+/** Type guard: narrows a DocumentChange to the rename variant. */
+export function isRename(change) {
+    return change.type === 'rename';
+}

package/dist/documents/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/documents/types.test.js

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { isRename } from './types';
+describe('isRename type guard', () => {
+    it('returns true for a rename event with oldPath', () => {
+        const change = {
+            type: 'rename',
+            path: 'new.txt',
+            oldPath: 'old.txt',
+            tenantId: 't1',
+            shardId: 's1',
+        };
+        expect(isRename(change)).toBe(true);
+    });
+    it('returns false for create/update/delete', () => {
+        const base = { path: 'a.txt', tenantId: 't1', shardId: 's1' };
+        expect(isRename(Object.assign(Object.assign({}, base), { type: 'create' }))).toBe(false);
+        expect(isRename(Object.assign(Object.assign({}, base), { type: 'update' }))).toBe(false);
+        expect(isRename(Object.assign(Object.assign({}, base), { type: 'delete' }))).toBe(false);
+    });
+});