sh3-core 0.7.5 → 0.8.0

package/dist/documents/sync/handle.d.ts

@@ -0,0 +1,11 @@
+import type { SyncEngine } from './engine';
+import type { SyncRegistry } from './registry';
+import { type SyncHandle } from './types';
+interface SyncHandleDeps {
+    tenantId: string;
+    connectorId: string;
+    engine: SyncEngine;
+    registry: SyncRegistry;
+}
+export declare function createSyncHandle(deps: SyncHandleDeps): SyncHandle;
+export {};

package/dist/documents/sync/handle.js

@@ -0,0 +1,79 @@
+/*
+ * SyncHandle factory — binds tenantId + connectorId, validates scope
+ * grants per call, and fans {kind:'tenant'} scopes across the granted
+ * shard/path scopes before delegating to the engine.
+ */
+import { ScopeNotGrantedError, } from './types';
+function scopeContains(parent, child) {
+    if (parent.kind === 'tenant')
+        return true;
+    if (parent.kind === 'shard') {
+        if (child.kind === 'shard')
+            return parent.shardId === child.shardId;
+        if (child.kind === 'path')
+            return parent.shardId === child.shardId;
+        return false;
+    }
+    // parent.kind === 'path'
+    if (child.kind === 'path')
+        return child.shardId === parent.shardId && child.prefix.startsWith(parent.prefix);
+    return false;
+}
+export function createSyncHandle(deps) {
+    const { connectorId, engine, registry } = deps;
+    async function currentGrants() {
+        const records = await registry.list(connectorId);
+        return records.map((r) => r.scope);
+    }
+    async function requireScope(requested) {
+        const grants = await currentGrants();
+        const matching = grants.filter((g) => scopeContains(g, requested));
+        if (matching.length === 0)
+            throw new ScopeNotGrantedError(requested);
+        if (requested.kind === 'tenant') {
+            // Expand into the set of sub-scopes the connector is granted.
+            const concrete = grants.filter((g) => g.kind === 'shard' || g.kind === 'path');
+            return concrete.length > 0 ? concrete : [requested];
+        }
+        return [requested];
+    }
+    return {
+        connectorId,
+        async grantedScopes() {
+            return currentGrants();
+        },
+        async getManifest(scope) {
+            var _a;
+            const concreteScopes = await requireScope(scope);
+            const out = [];
+            if (scope.kind === 'tenant' && ((_a = concreteScopes[0]) === null || _a === void 0 ? void 0 : _a.kind) !== 'tenant') {
+                for (const s of concreteScopes)
+                    out.push(...await engine.getManifest(connectorId, s));
+            }
+            else {
+                out.push(...await engine.getManifest(connectorId, scope));
+            }
+            return out;
+        },
+        async changesSince(scope, cursor) {
+            await requireScope(scope);
+            return engine.changesSince(scope, cursor);
+        },
+        async ack(scope, cursor) {
+            await requireScope(scope);
+            await engine.ack(connectorId, scope, cursor);
+        },
+        async apply(scope, entry, opts) {
+            await requireScope(scope);
+            return engine.apply(connectorId, scope, entry, opts);
+        },
+        async applyBatch(scope, manifest, opts) {
+            await requireScope(scope);
+            return engine.applyBatch(connectorId, scope, manifest, opts);
+        },
+        async forget(scope, path) {
+            await requireScope(scope);
+            await engine.forget(scope, path);
+        },
+    };
+}

package/dist/documents/sync/handle.test.d.ts

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

package/dist/documents/sync/handle.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { MemoryDocumentBackend } from '../backends';
+import { SyncEngine } from './engine';
+import { createSyncHandle } from './handle';
+import { createSyncRegistry, __grantInternal } from './registry';
+import { hashContent } from './hash';
+import { ScopeNotGrantedError } from './types';
+async function setup() {
+    const backend = new MemoryDocumentBackend();
+    const engine = new SyncEngine(backend, 'tenant-a');
+    await engine.init();
+    const registry = createSyncRegistry(backend, 'tenant-a');
+    const handle = createSyncHandle({ tenantId: 'tenant-a', connectorId: 'conn-A', engine, registry });
+    return { backend, engine, registry, handle };
+}
+describe('createSyncHandle', () => {
+    it('grantedScopes returns [] when no grants exist', async () => {
+        const { handle } = await setup();
+        expect(await handle.grantedScopes()).toEqual([]);
+    });
+    it('allows apply within a granted shard scope', async () => {
+        const { backend, handle } = await setup();
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'shard', shardId: 's1' });
+        const h = await hashContent('x');
+        const out = await handle.apply({ kind: 'shard', shardId: 's1' }, {
+            path: 'a.md', shardId: 's1', op: 'upsert',
+            content: 'x', remoteHash: h, remoteMtime: 1,
+        });
+        expect(out.status).toBe('applied');
+    });
+    it('throws ScopeNotGrantedError when scope is not granted', async () => {
+        const { handle } = await setup();
+        await expect(handle.apply({ kind: 'shard', shardId: 's2' }, {
+            path: 'a.md', shardId: 's2', op: 'upsert',
+            content: 'x', remoteHash: 'h', remoteMtime: 1,
+        })).rejects.toBeInstanceOf(ScopeNotGrantedError);
+    });
+    it('revocation between calls takes effect immediately', async () => {
+        const { backend, registry, handle } = await setup();
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'shard', shardId: 's1' });
+        await handle.getManifest({ kind: 'shard', shardId: 's1' });
+        await registry.revoke('conn-A', { kind: 'shard', shardId: 's1' });
+        await expect(handle.getManifest({ kind: 'shard', shardId: 's1' })).rejects.toBeInstanceOf(ScopeNotGrantedError);
+    });
+    it('tenant scope expands to granted shard scopes for getManifest', async () => {
+        const { backend, handle } = await setup();
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'shard', shardId: 's1' });
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'shard', shardId: 's2' });
+        await backend.write('tenant-a', 's1', 'a.md', 'A');
+        await backend.write('tenant-a', 's2', 'b.md', 'B');
+        // Grant also tenant scope itself:
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'tenant' });
+        const m = await handle.getManifest({ kind: 'tenant' });
+        expect(m.map((e) => `${e.shardId}:${e.path}`).sort()).toEqual(['s1:a.md', 's2:b.md']);
+    });
+});

package/dist/documents/sync/hash.d.ts

@@ -0,0 +1 @@
+export declare function hashContent(content: string | ArrayBuffer): Promise<string>;

package/dist/documents/sync/hash.js

@@ -0,0 +1,13 @@
+/*
+ * Content hashing for the sync subsystem. sha-256 via SubtleCrypto,
+ * truncated to 16 hex chars — enough for collision resistance at
+ * per-user document scale while keeping manifest entries small.
+ */
+export async function hashContent(content) {
+    const buf = typeof content === 'string' ? new TextEncoder().encode(content) : new Uint8Array(content);
+    const digest = await crypto.subtle.digest('SHA-256', buf);
+    const hex = Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return hex.slice(0, 16);
+}

package/dist/documents/sync/hash.test.d.ts

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

package/dist/documents/sync/hash.test.js

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { hashContent } from './hash';
+describe('hashContent', () => {
+    it('produces a 16-char lowercase hex string', async () => {
+        const h = await hashContent('hello');
+        expect(h).toMatch(/^[0-9a-f]{16}$/);
+    });
+    it('is deterministic for the same input', async () => {
+        expect(await hashContent('abc')).toBe(await hashContent('abc'));
+    });
+    it('differs for different inputs', async () => {
+        expect(await hashContent('abc')).not.toBe(await hashContent('abcd'));
+    });
+    it('handles ArrayBuffer input', async () => {
+        const buf = new TextEncoder().encode('hello').buffer;
+        const hStr = await hashContent('hello');
+        const hBuf = await hashContent(buf);
+        expect(hStr).toBe(hBuf);
+    });
+});

package/dist/documents/sync/index.d.ts

@@ -0,0 +1,6 @@
+export type { SyncScope, SyncHandle, ManifestEntry, ApplyEntry, ApplyOpts, ApplyOutcome, ApplyBatchResult, ConflictPolicy, ConflictResolution, ConflictContext, JournalEntry, ChangePage, GrantRecord, } from './types';
+export { PERMISSION_DOCUMENTS_SYNC, SYNC_RESERVED_SHARD_ID, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './types';
+export { createSyncRegistry, type SyncRegistry } from './registry';
+export { getSyncBundle } from './singleton';
+export { default as SyncGrantPicker } from './components/SyncGrantPicker.svelte';
+export { default as DocumentSyncExplorer } from './components/DocumentSyncExplorer.svelte';

package/dist/documents/sync/index.js

@@ -0,0 +1,12 @@
+/*
+ * Document Sync API — public surface.
+ *
+ * Connector shards consume this module via the main sh3-core barrel.
+ * The __grantInternal helper is intentionally NOT re-exported here;
+ * it is imported directly by SyncGrantPicker.svelte only.
+ */
+export { PERMISSION_DOCUMENTS_SYNC, SYNC_RESERVED_SHARD_ID, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './types';
+export { createSyncRegistry } from './registry';
+export { getSyncBundle } from './singleton';
+export { default as SyncGrantPicker } from './components/SyncGrantPicker.svelte';
+export { default as DocumentSyncExplorer } from './components/DocumentSyncExplorer.svelte';

package/dist/documents/sync/journal.d.ts

@@ -0,0 +1,30 @@
+import type { DocumentBackend } from '../types';
+import type { ChangePage, JournalEntry, SyncScope } from './types';
+export declare class Journal {
+    #private;
+    private backend;
+    private tenantId;
+    constructor(backend: DocumentBackend, tenantId: string, opts?: {
+        segmentSize?: number;
+        pageSize?: number;
+    });
+    init(): Promise<void>;
+    static encodeCursor(seq: number, version: number): string;
+    static decodeCursor(cursor: string): {
+        seq: number;
+        version: number;
+    } | null;
+    append(entry: Omit<JournalEntry, 'seq' | 'ts'>): Promise<JournalEntry>;
+    oldestRetainedSeq(): Promise<number>;
+    changesSince(scope: SyncScope, cursor?: string): Promise<ChangePage>;
+    getCursor(connectorId: string): Promise<string | null>;
+    ackCursor(connectorId: string, cursor: string): Promise<void>;
+    dropCursor(connectorId: string): Promise<void>;
+    listCursors(): Promise<Array<{
+        connectorId: string;
+        cursor: string;
+    }>>;
+    minSeqAckedByAll(connectorIds: string[]): Promise<number>;
+    /** Test-only: simulate truncating all segments whose entries are <= uptoSeq. */
+    __truncateForTest(uptoSeq: number): Promise<void>;
+}

package/dist/documents/sync/journal.js

@@ -0,0 +1,179 @@
+/*
+ * Change journal for the sync subsystem.
+ *
+ * Append-only per-tenant sequence of JournalEntry, stored as JSON
+ * segments under journal/<n>.json. Cursors are opaque "<seq>:<version>"
+ * strings; version matches the journal's truncation epoch. A cursor with
+ * an older version whose seq < oldestSeq means the connector has fallen
+ * behind retained history.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    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 __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Journal_meta, _Journal_segmentSize, _Journal_pageSize;
+import { readJson, writeJson, deletePath, listJsonPaths } from './serialization';
+const META_PATH = 'journal/meta.json';
+const SEGMENT_PREFIX = 'journal/seg-';
+const CURSOR_PREFIX = 'cursors/';
+const DEFAULT_SEGMENT_SIZE = 500;
+const DEFAULT_PAGE_SIZE = 100;
+function segmentPath(i) {
+    return `${SEGMENT_PREFIX}${i}.json`;
+}
+function cursorPath(connectorId) {
+    return `${CURSOR_PREFIX}${encodeURIComponent(connectorId)}.json`;
+}
+function matchesScope(entry, scope) {
+    switch (scope.kind) {
+        case 'tenant': return true;
+        case 'shard': return entry.shardId === scope.shardId;
+        case 'path': return entry.shardId === scope.shardId && entry.path.startsWith(scope.prefix);
+    }
+}
+export class Journal {
+    constructor(backend, tenantId, opts = {}) {
+        var _a, _b;
+        this.backend = backend;
+        this.tenantId = tenantId;
+        _Journal_meta.set(this, { currentSeq: 0, currentSegment: 0, oldestSegment: 0, version: 0 });
+        _Journal_segmentSize.set(this, void 0);
+        _Journal_pageSize.set(this, void 0);
+        __classPrivateFieldSet(this, _Journal_segmentSize, (_a = opts.segmentSize) !== null && _a !== void 0 ? _a : DEFAULT_SEGMENT_SIZE, "f");
+        __classPrivateFieldSet(this, _Journal_pageSize, (_b = opts.pageSize) !== null && _b !== void 0 ? _b : DEFAULT_PAGE_SIZE, "f");
+    }
+    async init() {
+        const meta = await readJson(this.backend, this.tenantId, META_PATH);
+        if (meta)
+            __classPrivateFieldSet(this, _Journal_meta, meta, "f");
+    }
+    static encodeCursor(seq, version) {
+        return `${seq}:${version}`;
+    }
+    static decodeCursor(cursor) {
+        const m = /^(\d+):(\d+)$/.exec(cursor);
+        if (!m)
+            return null;
+        return { seq: Number(m[1]), version: Number(m[2]) };
+    }
+    async append(entry) {
+        var _a;
+        const seq = __classPrivateFieldGet(this, _Journal_meta, "f").currentSeq + 1;
+        const full = Object.assign(Object.assign({}, entry), { seq, ts: Date.now() });
+        const segIdx = __classPrivateFieldGet(this, _Journal_meta, "f").currentSegment;
+        const current = (_a = (await readJson(this.backend, this.tenantId, segmentPath(segIdx)))) !== null && _a !== void 0 ? _a : [];
+        current.push(full);
+        await writeJson(this.backend, this.tenantId, segmentPath(segIdx), current);
+        __classPrivateFieldGet(this, _Journal_meta, "f").currentSeq = seq;
+        if (current.length >= __classPrivateFieldGet(this, _Journal_segmentSize, "f")) {
+            __classPrivateFieldGet(this, _Journal_meta, "f").currentSegment = segIdx + 1;
+        }
+        await writeJson(this.backend, this.tenantId, META_PATH, __classPrivateFieldGet(this, _Journal_meta, "f"));
+        return full;
+    }
+    async oldestRetainedSeq() {
+        const first = await readJson(this.backend, this.tenantId, segmentPath(__classPrivateFieldGet(this, _Journal_meta, "f").oldestSegment));
+        if (!first || first.length === 0)
+            return 0;
+        return first[0].seq;
+    }
+    async changesSince(scope, cursor) {
+        var _a;
+        let startSeq = 0;
+        if (cursor) {
+            const decoded = Journal.decodeCursor(cursor);
+            if (!decoded)
+                return { entries: [], nextCursor: cursor, hasMore: false };
+            const oldest = await this.oldestRetainedSeq();
+            if (decoded.version < __classPrivateFieldGet(this, _Journal_meta, "f").version && decoded.seq < oldest) {
+                return { entries: [], nextCursor: cursor, hasMore: false, truncated: true };
+            }
+            startSeq = decoded.seq;
+        }
+        const out = [];
+        let lastSeq = startSeq;
+        let hasMore = false;
+        for (let seg = __classPrivateFieldGet(this, _Journal_meta, "f").oldestSegment; seg <= __classPrivateFieldGet(this, _Journal_meta, "f").currentSegment; seg++) {
+            const entries = (_a = (await readJson(this.backend, this.tenantId, segmentPath(seg)))) !== null && _a !== void 0 ? _a : [];
+            for (const e of entries) {
+                if (e.seq <= startSeq)
+                    continue;
+                if (!matchesScope(e, scope)) {
+                    lastSeq = e.seq;
+                    continue;
+                }
+                if (out.length >= __classPrivateFieldGet(this, _Journal_pageSize, "f")) {
+                    hasMore = true;
+                    break;
+                }
+                out.push(e);
+                lastSeq = e.seq;
+            }
+            if (hasMore)
+                break;
+        }
+        return {
+            entries: out,
+            nextCursor: Journal.encodeCursor(lastSeq, __classPrivateFieldGet(this, _Journal_meta, "f").version),
+            hasMore,
+        };
+    }
+    async getCursor(connectorId) {
+        return readJson(this.backend, this.tenantId, cursorPath(connectorId));
+    }
+    async ackCursor(connectorId, cursor) {
+        await writeJson(this.backend, this.tenantId, cursorPath(connectorId), cursor);
+    }
+    async dropCursor(connectorId) {
+        await deletePath(this.backend, this.tenantId, cursorPath(connectorId));
+    }
+    async listCursors() {
+        const paths = await listJsonPaths(this.backend, this.tenantId, CURSOR_PREFIX);
+        const out = [];
+        for (const p of paths) {
+            const cursor = await readJson(this.backend, this.tenantId, p);
+            if (cursor === null)
+                continue;
+            const id = decodeURIComponent(p.slice(CURSOR_PREFIX.length, -'.json'.length));
+            out.push({ connectorId: id, cursor });
+        }
+        return out;
+    }
+    async minSeqAckedByAll(connectorIds) {
+        if (connectorIds.length === 0)
+            return 0;
+        let min = Infinity;
+        for (const id of connectorIds) {
+            const c = await this.getCursor(id);
+            const decoded = c ? Journal.decodeCursor(c) : null;
+            const seq = decoded ? decoded.seq : 0;
+            if (seq < min)
+                min = seq;
+        }
+        return min === Infinity ? 0 : min;
+    }
+    /** Test-only: simulate truncating all segments whose entries are <= uptoSeq. */
+    async __truncateForTest(uptoSeq) {
+        var _a;
+        for (let seg = __classPrivateFieldGet(this, _Journal_meta, "f").oldestSegment; seg <= __classPrivateFieldGet(this, _Journal_meta, "f").currentSegment; seg++) {
+            const entries = (_a = (await readJson(this.backend, this.tenantId, segmentPath(seg)))) !== null && _a !== void 0 ? _a : [];
+            const last = entries[entries.length - 1];
+            if (last && last.seq <= uptoSeq) {
+                await deletePath(this.backend, this.tenantId, segmentPath(seg));
+                __classPrivateFieldGet(this, _Journal_meta, "f").oldestSegment = seg + 1;
+            }
+            else
+                break;
+        }
+        __classPrivateFieldGet(this, _Journal_meta, "f").version += 1;
+        await writeJson(this.backend, this.tenantId, META_PATH, __classPrivateFieldGet(this, _Journal_meta, "f"));
+    }
+}
+_Journal_meta = new WeakMap(), _Journal_segmentSize = new WeakMap(), _Journal_pageSize = new WeakMap();

package/dist/documents/sync/journal.test.d.ts

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

package/dist/documents/sync/journal.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../backends';
+import { Journal } from './journal';
+describe('Journal', () => {
+    let backend;
+    let journal;
+    beforeEach(async () => {
+        backend = new MemoryDocumentBackend();
+        journal = new Journal(backend, 'tenant-a', { segmentSize: 3 });
+        await journal.init();
+    });
+    it('starts with no entries', async () => {
+        const page = await journal.changesSince({ kind: 'tenant' });
+        expect(page.entries).toEqual([]);
+        expect(page.hasMore).toBe(false);
+    });
+    it('appends and reads entries', async () => {
+        await journal.append({ shardId: 's1', path: 'a.md', op: 'upsert', hash: 'h1' });
+        await journal.append({ shardId: 's1', path: 'b.md', op: 'upsert', hash: 'h2' });
+        const page = await journal.changesSince({ kind: 'tenant' });
+        expect(page.entries.map((e) => e.path)).toEqual(['a.md', 'b.md']);
+        expect(page.entries[0].seq).toBe(1);
+        expect(page.entries[1].seq).toBe(2);
+    });
+    it('filters by shard scope', async () => {
+        await journal.append({ shardId: 's1', path: 'a.md', op: 'upsert', hash: 'h1' });
+        await journal.append({ shardId: 's2', path: 'b.md', op: 'upsert', hash: 'h2' });
+        const scoped = { kind: 'shard', shardId: 's1' };
+        const page = await journal.changesSince(scoped);
+        expect(page.entries.map((e) => e.path)).toEqual(['a.md']);
+    });
+    it('filters by path prefix', async () => {
+        await journal.append({ shardId: 's1', path: 'docs/x.md', op: 'upsert', hash: 'h1' });
+        await journal.append({ shardId: 's1', path: 'notes/y.md', op: 'upsert', hash: 'h2' });
+        const scoped = { kind: 'path', shardId: 's1', prefix: 'docs/' };
+        const page = await journal.changesSince(scoped);
+        expect(page.entries.map((e) => e.path)).toEqual(['docs/x.md']);
+    });
+    it('resumes from a cursor', async () => {
+        for (let i = 0; i < 5; i++) {
+            await journal.append({ shardId: 's1', path: `f${i}.md`, op: 'upsert', hash: `h${i}` });
+        }
+        const first = await journal.changesSince({ kind: 'tenant' });
+        // Walk through pages until end.
+        let cursor = first.nextCursor;
+        const seen = [...first.entries];
+        let hasMore = first.hasMore;
+        while (hasMore) {
+            const next = await journal.changesSince({ kind: 'tenant' }, cursor);
+            seen.push(...next.entries);
+            cursor = next.nextCursor;
+            hasMore = next.hasMore;
+        }
+        expect(seen.map((e) => e.seq)).toEqual([1, 2, 3, 4, 5]);
+    });
+    it('persists cursors per connector and returns only new entries after ack', async () => {
+        await journal.append({ shardId: 's1', path: 'a.md', op: 'upsert', hash: 'h1' });
+        const p1 = await journal.changesSince({ kind: 'tenant' });
+        await journal.ackCursor('conn-A', p1.nextCursor);
+        await journal.append({ shardId: 's1', path: 'b.md', op: 'upsert', hash: 'h2' });
+        const saved = await journal.getCursor('conn-A');
+        const p2 = await journal.changesSince({ kind: 'tenant' }, saved !== null && saved !== void 0 ? saved : undefined);
+        expect(p2.entries.map((e) => e.path)).toEqual(['b.md']);
+    });
+    it('reports truncated=true when a cursor predates oldest retained seq', async () => {
+        // Force many segments then truncate
+        for (let i = 0; i < 10; i++) {
+            await journal.append({ shardId: 's1', path: `f${i}.md`, op: 'upsert', hash: `h${i}` });
+        }
+        // Simulate truncation up to seq 6.
+        await journal.__truncateForTest(6);
+        const stale = Journal.encodeCursor(2, 0); // old version
+        const page = await journal.changesSince({ kind: 'tenant' }, stale);
+        expect(page.truncated).toBe(true);
+        expect(page.entries).toEqual([]);
+    });
+    it('minSeqAckedByAll returns the lowest acked seq across registered cursors', async () => {
+        await journal.append({ shardId: 's1', path: 'a.md', op: 'upsert', hash: 'h1' });
+        await journal.append({ shardId: 's1', path: 'b.md', op: 'upsert', hash: 'h2' });
+        await journal.append({ shardId: 's1', path: 'c.md', op: 'upsert', hash: 'h3' });
+        await journal.ackCursor('conn-A', Journal.encodeCursor(3, 0));
+        await journal.ackCursor('conn-B', Journal.encodeCursor(1, 0));
+        expect(await journal.minSeqAckedByAll(['conn-A', 'conn-B'])).toBe(1);
+        expect(await journal.minSeqAckedByAll(['conn-A'])).toBe(3);
+        expect(await journal.minSeqAckedByAll([])).toBe(0);
+    });
+});

package/dist/documents/sync/registry.d.ts

@@ -0,0 +1,10 @@
+import type { DocumentBackend } from '../types';
+import type { ConflictResolution, GrantRecord, SyncScope } from './types';
+export declare function __grantInternal(backend: DocumentBackend, tenantId: string, connectorId: string, scope: SyncScope): Promise<void>;
+export interface SyncRegistry {
+    list(connectorId?: string): Promise<GrantRecord[]>;
+    revoke(connectorId: string, scope: SyncScope): Promise<void>;
+    listConflicts(shardId: string): Promise<ConflictResolution[]>;
+    listAllConnectorIds(): Promise<string[]>;
+}
+export declare function createSyncRegistry(backend: DocumentBackend, tenantId: string): SyncRegistry;

package/dist/documents/sync/registry.js

@@ -0,0 +1,66 @@
+/*
+ * Grant registry — public surface (revoke/list/listConflicts) for
+ * connectors, plus __grantInternal used only by the core-owned
+ * SyncGrantPicker component. Connectors do not import __grantInternal.
+ */
+import { readJson, writeJson, deletePath, listJsonPaths } from './serialization';
+import { ConflictManager } from './conflicts';
+const GRANTS_PREFIX = 'grants/';
+function grantPath(connectorId) {
+    return `${GRANTS_PREFIX}${encodeURIComponent(connectorId)}.json`;
+}
+function scopesEqual(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    if (a.kind === 'tenant')
+        return true;
+    if (a.kind === 'shard' && b.kind === 'shard')
+        return a.shardId === b.shardId;
+    if (a.kind === 'path' && b.kind === 'path')
+        return a.shardId === b.shardId && a.prefix === b.prefix;
+    return false;
+}
+export async function __grantInternal(backend, tenantId, connectorId, scope) {
+    var _a;
+    const existing = (_a = (await readJson(backend, tenantId, grantPath(connectorId)))) !== null && _a !== void 0 ? _a : [];
+    if (existing.some((g) => scopesEqual(g.scope, scope)))
+        return;
+    existing.push({ connectorId, scope, grantedAt: Date.now() });
+    await writeJson(backend, tenantId, grantPath(connectorId), existing);
+}
+export function createSyncRegistry(backend, tenantId) {
+    const conflicts = new ConflictManager(backend, tenantId);
+    async function readGrants(connectorId) {
+        var _a;
+        return (_a = (await readJson(backend, tenantId, grantPath(connectorId)))) !== null && _a !== void 0 ? _a : [];
+    }
+    return {
+        async list(connectorId) {
+            if (connectorId)
+                return readGrants(connectorId);
+            const paths = await listJsonPaths(backend, tenantId, GRANTS_PREFIX);
+            const out = [];
+            for (const p of paths) {
+                const arr = await readJson(backend, tenantId, p);
+                if (arr)
+                    out.push(...arr);
+            }
+            return out;
+        },
+        async revoke(connectorId, scope) {
+            const grants = await readGrants(connectorId);
+            const next = grants.filter((g) => !scopesEqual(g.scope, scope));
+            if (next.length === 0)
+                await deletePath(backend, tenantId, grantPath(connectorId));
+            else
+                await writeJson(backend, tenantId, grantPath(connectorId), next);
+        },
+        async listConflicts(shardId) {
+            return conflicts.listConflicts(shardId);
+        },
+        async listAllConnectorIds() {
+            const paths = await listJsonPaths(backend, tenantId, GRANTS_PREFIX);
+            return paths.map((p) => decodeURIComponent(p.slice(GRANTS_PREFIX.length, -'.json'.length)));
+        },
+    };
+}

package/dist/documents/sync/registry.test.d.ts

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

package/dist/documents/sync/registry.test.js

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { MemoryDocumentBackend } from '../backends';
+import { createSyncRegistry, __grantInternal } from './registry';
+describe('syncRegistry', () => {
+    let backend;
+    let reg;
+    beforeEach(() => {
+        backend = new MemoryDocumentBackend();
+        reg = createSyncRegistry(backend, 'tenant-a');
+    });
+    it('list returns [] when nothing granted', async () => {
+        expect(await reg.list()).toEqual([]);
+    });
+    it('__grantInternal records and list returns it', async () => {
+        vi.useFakeTimers().setSystemTime(new Date(1000));
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'tenant' });
+        const all = await reg.list();
+        expect(all).toEqual([
+            { connectorId: 'conn-A', scope: { kind: 'tenant' }, grantedAt: 1000 },
+        ]);
+        vi.useRealTimers();
+    });
+    it('list filters by connectorId', async () => {
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'shard', shardId: 's1' });
+        await __grantInternal(backend, 'tenant-a', 'conn-B', { kind: 'tenant' });
+        const a = await reg.list('conn-A');
+        expect(a).toHaveLength(1);
+        expect(a[0].connectorId).toBe('conn-A');
+    });
+    it('revoke removes one scope, leaving other grants intact', async () => {
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'shard', shardId: 's1' });
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'shard', shardId: 's2' });
+        await reg.revoke('conn-A', { kind: 'shard', shardId: 's1' });
+        const all = await reg.list('conn-A');
+        expect(all.map((g) => g.scope.shardId)).toEqual(['s2']);
+    });
+    it('__grantInternal is idempotent for same scope', async () => {
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'tenant' });
+        await __grantInternal(backend, 'tenant-a', 'conn-A', { kind: 'tenant' });
+        expect((await reg.list('conn-A')).length).toBe(1);
+    });
+});

package/dist/documents/sync/serialization.d.ts

@@ -0,0 +1,5 @@
+import type { DocumentBackend } from '../types';
+export declare function readJson<T>(backend: DocumentBackend, tenantId: string, path: string): Promise<T | null>;
+export declare function writeJson(backend: DocumentBackend, tenantId: string, path: string, value: unknown): Promise<void>;
+export declare function deletePath(backend: DocumentBackend, tenantId: string, path: string): Promise<void>;
+export declare function listJsonPaths(backend: DocumentBackend, tenantId: string, prefix: string): Promise<string[]>;