sh3-core 0.8.1 → 0.9.0

package/dist/documents/sync/conflicts.js

@@ -1,77 +0,0 @@
-/*
- * Conflict resolution — dispatches the caller-supplied (or default)
- * policy, writes .sync-conflict-* artifacts when required, and tracks
- * per-(connectorId, path) base hashes for three-way comparisons.
- */
-import { readJson, writeJson } from './serialization';
-const BASES_PREFIX = 'bases/';
-function baseKey(connectorId, shardId, path) {
-    return `${BASES_PREFIX}${encodeURIComponent(connectorId)}__${shardId}__${encodeURIComponent(path)}.json`;
-}
-function isArtifactName(name) {
-    return /\.sync-conflict-[^.]+-\d+$/.test(name);
-}
-export class ConflictManager {
-    constructor(backend, tenantId) {
-        this.backend = backend;
-        this.tenantId = tenantId;
-    }
-    async resolve(policy, input) {
-        const p = typeof policy === 'function' ? await policy({
-            path: input.path, shardId: input.shardId,
-            localHash: input.localHash, remoteHash: input.remoteHash, baseHash: input.baseHash,
-        }) : policy;
-        switch (p) {
-            case 'remote-wins': return { action: 'apply-remote' };
-            case 'local-wins': return { action: 'skip' };
-            case 'keep-both': {
-                const asPath = `${input.path}.incoming-${input.connectorId}-${Date.now()}`;
-                return { action: 'apply-remote', asPath };
-            }
-            case 'default':
-            default: {
-                const ts = Date.now();
-                const artifact = `${input.path}.sync-conflict-${input.connectorId}-${ts}`;
-                if (input.remoteContent !== undefined) {
-                    await this.backend.write(this.tenantId, input.shardId, artifact, input.remoteContent);
-                }
-                const resolution = {
-                    path: input.path,
-                    shardId: input.shardId,
-                    localHash: input.localHash,
-                    remoteHash: input.remoteHash,
-                    conflictArtifactPath: artifact,
-                    base: input.baseHash ? { hash: input.baseHash } : undefined,
-                };
-                return { action: 'conflict', resolution };
-            }
-        }
-    }
-    async getBaseHash(connectorId, shardId, path) {
-        return readJson(this.backend, this.tenantId, baseKey(connectorId, shardId, path));
-    }
-    async setBaseHash(connectorId, shardId, path, hash) {
-        await writeJson(this.backend, this.tenantId, baseKey(connectorId, shardId, path), hash);
-    }
-    async listConflicts(shardId) {
-        const metas = await this.backend.list(this.tenantId, shardId);
-        const out = [];
-        for (const m of metas) {
-            const name = m.path;
-            if (!isArtifactName(name))
-                continue;
-            const m2 = /^(.*)\.sync-conflict-([^-]+)-(\d+)$/.exec(name);
-            if (!m2)
-                continue;
-            const originalPath = m2[1];
-            out.push({
-                path: originalPath,
-                shardId,
-                localHash: '',
-                remoteHash: '',
-                conflictArtifactPath: name,
-            });
-        }
-        return out;
-    }
-}

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

@@ -1,71 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { MemoryDocumentBackend } from '../backends';
-import { ConflictManager } from './conflicts';
-describe('ConflictManager', () => {
-    let backend;
-    let mgr;
-    beforeEach(() => {
-        backend = new MemoryDocumentBackend();
-        mgr = new ConflictManager(backend, 'tenant-a');
-    });
-    it('remote-wins: returns apply-remote=true', async () => {
-        const r = await mgr.resolve('remote-wins', {
-            connectorId: 'c1', shardId: 's1', path: 'a.md',
-            localHash: 'L', remoteHash: 'R',
-        });
-        expect(r).toEqual({ action: 'apply-remote' });
-    });
-    it('local-wins: returns skip', async () => {
-        const r = await mgr.resolve('local-wins', {
-            connectorId: 'c1', shardId: 's1', path: 'a.md',
-            localHash: 'L', remoteHash: 'R',
-        });
-        expect(r).toEqual({ action: 'skip' });
-    });
-    it('keep-both: returns apply-remote with renamed path', async () => {
-        vi.useFakeTimers().setSystemTime(new Date(10000));
-        const r = await mgr.resolve('keep-both', {
-            connectorId: 'c1', shardId: 's1', path: 'a.md',
-            localHash: 'L', remoteHash: 'R',
-        });
-        expect(r).toEqual({ action: 'apply-remote', asPath: 'a.md.incoming-c1-10000' });
-        vi.useRealTimers();
-    });
-    it('default: writes .sync-conflict artifact, keeps local, returns resolution', async () => {
-        vi.useFakeTimers().setSystemTime(new Date(20000));
-        const r = await mgr.resolve('default', {
-            connectorId: 'c1', shardId: 's1', path: 'dir/a.md',
-            localHash: 'L', remoteHash: 'R', remoteContent: 'REMOTE',
-        });
-        expect(r.action).toBe('conflict');
-        if (r.action !== 'conflict')
-            throw new Error('unreachable');
-        expect(r.resolution.conflictArtifactPath).toBe('dir/a.md.sync-conflict-c1-20000');
-        // Artifact was written to the backend under the target shard.
-        const read = await backend.read('tenant-a', 's1', 'dir/a.md.sync-conflict-c1-20000');
-        expect(read).toBe('REMOTE');
-        vi.useRealTimers();
-    });
-    it('function policy dispatches to returned action', async () => {
-        const r = await mgr.resolve(async () => 'remote-wins', {
-            connectorId: 'c1', shardId: 's1', path: 'a.md',
-            localHash: 'L', remoteHash: 'R',
-        });
-        expect(r).toEqual({ action: 'apply-remote' });
-    });
-    it('stores and retrieves base hash per (connector, shard, path)', async () => {
-        await mgr.setBaseHash('c1', 's1', 'a.md', 'H1');
-        expect(await mgr.getBaseHash('c1', 's1', 'a.md')).toBe('H1');
-        expect(await mgr.getBaseHash('c2', 's1', 'a.md')).toBeNull();
-    });
-    it('lists .sync-conflict-* artifacts within a shard', async () => {
-        await backend.write('tenant-a', 's1', 'a.md.sync-conflict-c1-1', 'x');
-        await backend.write('tenant-a', 's1', 'b.md.sync-conflict-c2-2', 'y');
-        await backend.write('tenant-a', 's1', 'c.md', 'regular');
-        const list = await mgr.listConflicts('s1');
-        expect(list.map((c) => c.conflictArtifactPath).sort()).toEqual([
-            'a.md.sync-conflict-c1-1',
-            'b.md.sync-conflict-c2-2',
-        ]);
-    });
-});

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

@@ -1,19 +0,0 @@
-import type { DocumentBackend } from '../types';
-import type { ApplyBatchResult, ApplyEntry, ApplyOpts, ApplyOutcome, ChangePage, ManifestEntry, SyncScope } from './types';
-import { Journal } from './journal';
-export declare class SyncEngine {
-    #private;
-    private backend;
-    private tenantId;
-    constructor(backend: DocumentBackend, tenantId: string, opts?: {
-        segmentSize?: number;
-    });
-    init(): Promise<void>;
-    get journal(): Journal;
-    getManifest(_connectorId: string, scope: SyncScope): Promise<ManifestEntry[]>;
-    changesSince(scope: SyncScope, cursor?: string): Promise<ChangePage>;
-    ack(connectorId: string, _scope: SyncScope, cursor: string): Promise<void>;
-    apply(connectorId: string, scope: SyncScope, entry: ApplyEntry, opts?: ApplyOpts): Promise<ApplyOutcome>;
-    applyBatch(connectorId: string, scope: SyncScope, manifest: ApplyEntry[], opts?: ApplyOpts): Promise<ApplyBatchResult>;
-    forget(scope: SyncScope, path: string): Promise<void>;
-}

package/dist/documents/sync/engine.js

@@ -1,188 +0,0 @@
-/*
- * SyncEngine — orchestrates manifest generation, apply pipeline, and
- * change notifications. Composes Journal, TombstoneStore, and
- * ConflictManager over a DocumentBackend. One instance per tenant.
- */
-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 _SyncEngine_instances, _SyncEngine_journal, _SyncEngine_tombstones, _SyncEngine_conflicts, _SyncEngine_applyUpsert, _SyncEngine_writeAndRecord, _SyncEngine_applyDelete, _SyncEngine_hasDivergedBase, _SyncEngine_shardsInScope, _SyncEngine_emit;
-import { documentChanges } from '../notifications';
-import { hashContent } from './hash';
-import { Journal } from './journal';
-import { TombstoneStore } from './tombstones';
-import { ConflictManager } from './conflicts';
-function scopeCovers(scope, shardId, path) {
-    switch (scope.kind) {
-        case 'tenant': return true;
-        case 'shard': return scope.shardId === shardId;
-        case 'path': return scope.shardId === shardId && path.startsWith(scope.prefix);
-    }
-}
-export class SyncEngine {
-    constructor(backend, tenantId, opts = {}) {
-        _SyncEngine_instances.add(this);
-        this.backend = backend;
-        this.tenantId = tenantId;
-        _SyncEngine_journal.set(this, void 0);
-        _SyncEngine_tombstones.set(this, void 0);
-        _SyncEngine_conflicts.set(this, void 0);
-        __classPrivateFieldSet(this, _SyncEngine_journal, new Journal(backend, tenantId, { segmentSize: opts.segmentSize }), "f");
-        __classPrivateFieldSet(this, _SyncEngine_tombstones, new TombstoneStore(backend, tenantId), "f");
-        __classPrivateFieldSet(this, _SyncEngine_conflicts, new ConflictManager(backend, tenantId), "f");
-    }
-    async init() {
-        await __classPrivateFieldGet(this, _SyncEngine_journal, "f").init();
-    }
-    get journal() { return __classPrivateFieldGet(this, _SyncEngine_journal, "f"); }
-    async getManifest(_connectorId, scope) {
-        const shardIds = await __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_shardsInScope).call(this, scope);
-        const entries = [];
-        for (const shardId of shardIds) {
-            const metas = await this.backend.list(this.tenantId, shardId);
-            for (const m of metas) {
-                if (!scopeCovers(scope, shardId, m.path))
-                    continue;
-                if (m.path.startsWith('.') || /\.sync-conflict-/.test(m.path))
-                    continue;
-                const raw = await this.backend.read(this.tenantId, shardId, m.path);
-                if (raw === null)
-                    continue;
-                const hash = await hashContent(raw);
-                entries.push({ path: m.path, shardId, hash, size: m.size, lastModified: m.lastModified });
-            }
-            const tombs = await __classPrivateFieldGet(this, _SyncEngine_tombstones, "f").listByShard(shardId);
-            for (const t of tombs) {
-                if (!scopeCovers(scope, shardId, t.path))
-                    continue;
-                entries.push({
-                    path: t.path, shardId, hash: t.lastHash, size: 0, lastModified: t.deletedAt,
-                    tombstone: { deletedAt: t.deletedAt },
-                });
-            }
-        }
-        return entries;
-    }
-    async changesSince(scope, cursor) {
-        return __classPrivateFieldGet(this, _SyncEngine_journal, "f").changesSince(scope, cursor);
-    }
-    async ack(connectorId, _scope, cursor) {
-        // Scope is informational — cursors are connector-wide, not scope-specific.
-        await __classPrivateFieldGet(this, _SyncEngine_journal, "f").ackCursor(connectorId, cursor);
-    }
-    async apply(connectorId, scope, entry, opts = {}) {
-        if (!scopeCovers(scope, entry.shardId, entry.path)) {
-            throw new Error(`ApplyEntry {${entry.shardId}:${entry.path}} falls outside scope`);
-        }
-        if (entry.op === 'upsert')
-            return __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_applyUpsert).call(this, connectorId, entry, opts);
-        return __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_applyDelete).call(this, connectorId, entry);
-    }
-    async applyBatch(connectorId, scope, manifest, opts = {}) {
-        const applied = [];
-        const skipped = [];
-        const conflicts = [];
-        for (const e of manifest) {
-            const out = await this.apply(connectorId, scope, e, opts);
-            if (out.status === 'applied')
-                applied.push({ path: e.path, shardId: e.shardId, newHash: out.newHash });
-            else if (out.status === 'skipped-identical')
-                skipped.push({ path: e.path, shardId: e.shardId, reason: 'identical' });
-            else
-                conflicts.push(out.resolution);
-        }
-        return { applied, skipped, conflicts };
-    }
-    async forget(scope, path) {
-        const shardIds = await __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_shardsInScope).call(this, scope);
-        for (const shardId of shardIds) {
-            if (!scopeCovers(scope, shardId, path))
-                continue;
-            await __classPrivateFieldGet(this, _SyncEngine_tombstones, "f").clear(shardId, path);
-        }
-    }
-}
-_SyncEngine_journal = new WeakMap(), _SyncEngine_tombstones = new WeakMap(), _SyncEngine_conflicts = new WeakMap(), _SyncEngine_instances = new WeakSet(), _SyncEngine_applyUpsert = 
-// ----- internals -----
-async function _SyncEngine_applyUpsert(connectorId, entry, opts) {
-    var _a, _b, _c;
-    const existing = await this.backend.read(this.tenantId, entry.shardId, entry.path);
-    const existed = existing !== null;
-    const localHash = existed ? await hashContent(existing) : null;
-    if (localHash !== null && localHash === entry.remoteHash) {
-        return { status: 'skipped-identical' };
-    }
-    const conflictTriggered = existed && ((opts.expectedLocalHash !== undefined && opts.expectedLocalHash !== localHash) ||
-        (opts.expectedLocalHash === undefined && await __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_hasDivergedBase).call(this, connectorId, entry, localHash)));
-    if (conflictTriggered) {
-        const baseHash = (_a = (await __classPrivateFieldGet(this, _SyncEngine_conflicts, "f").getBaseHash(connectorId, entry.shardId, entry.path))) !== null && _a !== void 0 ? _a : undefined;
-        const action = await __classPrivateFieldGet(this, _SyncEngine_conflicts, "f").resolve((_b = opts.onConflict) !== null && _b !== void 0 ? _b : 'default', {
-            connectorId,
-            shardId: entry.shardId,
-            path: entry.path,
-            localHash: localHash,
-            remoteHash: entry.remoteHash,
-            remoteContent: entry.content,
-            baseHash,
-        });
-        if (action.action === 'skip')
-            return { status: 'skipped-identical' };
-        if (action.action === 'conflict')
-            return { status: 'conflict', resolution: action.resolution };
-        // apply-remote — fall through to write (possibly under asPath)
-        const writePath = (_c = action.asPath) !== null && _c !== void 0 ? _c : entry.path;
-        return __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_writeAndRecord).call(this, connectorId, entry, writePath, existed);
-    }
-    return __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_writeAndRecord).call(this, connectorId, entry, entry.path, existed);
-}, _SyncEngine_writeAndRecord = async function _SyncEngine_writeAndRecord(connectorId, entry, writePath, existed) {
-    if (entry.content === undefined) {
-        throw new Error(`Upsert without content for ${entry.shardId}:${entry.path}`);
-    }
-    await this.backend.write(this.tenantId, entry.shardId, writePath, entry.content);
-    await __classPrivateFieldGet(this, _SyncEngine_tombstones, "f").clear(entry.shardId, writePath);
-    const newHash = await hashContent(entry.content);
-    await __classPrivateFieldGet(this, _SyncEngine_conflicts, "f").setBaseHash(connectorId, entry.shardId, writePath, newHash);
-    await __classPrivateFieldGet(this, _SyncEngine_journal, "f").append({ shardId: entry.shardId, path: writePath, op: 'upsert', hash: newHash });
-    __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_emit).call(this, { type: existed && writePath === entry.path ? 'update' : 'create', path: writePath, tenantId: this.tenantId, shardId: entry.shardId });
-    return { status: 'applied', newHash };
-}, _SyncEngine_applyDelete = async function _SyncEngine_applyDelete(connectorId, entry) {
-    const existing = await this.backend.read(this.tenantId, entry.shardId, entry.path);
-    if (existing === null) {
-        // Already gone. Record a tombstone anyway so manifests reflect the delete.
-        await __classPrivateFieldGet(this, _SyncEngine_tombstones, "f").record(entry.shardId, entry.path, entry.remoteHash, Date.now());
-        await __classPrivateFieldGet(this, _SyncEngine_journal, "f").append({ shardId: entry.shardId, path: entry.path, op: 'delete', hash: null });
-        return { status: 'applied', newHash: '' };
-    }
-    const lastHash = await hashContent(existing);
-    await this.backend.delete(this.tenantId, entry.shardId, entry.path);
-    await __classPrivateFieldGet(this, _SyncEngine_tombstones, "f").record(entry.shardId, entry.path, lastHash, Date.now());
-    await __classPrivateFieldGet(this, _SyncEngine_conflicts, "f").setBaseHash(connectorId, entry.shardId, entry.path, ''); // clear base
-    await __classPrivateFieldGet(this, _SyncEngine_journal, "f").append({ shardId: entry.shardId, path: entry.path, op: 'delete', hash: null });
-    __classPrivateFieldGet(this, _SyncEngine_instances, "m", _SyncEngine_emit).call(this, { type: 'delete', path: entry.path, tenantId: this.tenantId, shardId: entry.shardId });
-    return { status: 'applied', newHash: '' };
-}, _SyncEngine_hasDivergedBase = async function _SyncEngine_hasDivergedBase(connectorId, entry, localHash) {
-    const base = await __classPrivateFieldGet(this, _SyncEngine_conflicts, "f").getBaseHash(connectorId, entry.shardId, entry.path);
-    if (!base)
-        return false; // no prior base → treat as first-seen, apply
-    return base !== localHash; // local moved since we last wrote it
-}, _SyncEngine_shardsInScope = async function _SyncEngine_shardsInScope(scope) {
-    if (scope.kind === 'tenant') {
-        // Listing all shards under a tenant isn't part of DocumentBackend's
-        // contract. For now, we rely on callers passing {kind:'shard'} or
-        // {kind:'path'}; {kind:'tenant'} traversal is driven by registry
-        // listing at the handle layer. Return empty here as a placeholder
-        // — the handle expands tenant-scope into per-shard calls.
-        return [];
-    }
-    return [scope.shardId];
-}, _SyncEngine_emit = function _SyncEngine_emit(change) {
-    documentChanges.emit(change);
-};

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

@@ -1,169 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { MemoryDocumentBackend } from '../backends';
-import { documentChanges } from '../notifications';
-import { SyncEngine } from './engine';
-import { hashContent } from './hash';
-async function setup() {
-    const backend = new MemoryDocumentBackend();
-    const engine = new SyncEngine(backend, 'tenant-a', { segmentSize: 10 });
-    await engine.init();
-    return { backend, engine };
-}
-describe('SyncEngine', () => {
-    describe('apply upsert', () => {
-        it('writes when absent and returns applied with newHash', async () => {
-            const { backend, engine } = await setup();
-            const hash = await hashContent('hello');
-            const out = await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'hello', remoteHash: hash, remoteMtime: Date.now(),
-            });
-            expect(out).toEqual({ status: 'applied', newHash: hash });
-            expect(await backend.read('tenant-a', 's1', 'a.md')).toBe('hello');
-        });
-        it('skipped-identical when local hash already equals remote', async () => {
-            const { backend, engine } = await setup();
-            await backend.write('tenant-a', 's1', 'a.md', 'hello');
-            const hash = await hashContent('hello');
-            const out = await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'hello', remoteHash: hash, remoteMtime: Date.now(),
-            });
-            expect(out).toEqual({ status: 'skipped-identical' });
-        });
-        it('idempotent: second apply after first returns skipped-identical', async () => {
-            const { engine } = await setup();
-            const hash = await hashContent('hi');
-            const entry = { path: 'a.md', shardId: 's1', op: 'upsert', content: 'hi', remoteHash: hash, remoteMtime: 1 };
-            const first = await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, entry);
-            const second = await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, entry);
-            expect(first.status).toBe('applied');
-            expect(second.status).toBe('skipped-identical');
-        });
-        it('emits DocumentChange on applied upsert', async () => {
-            const { engine } = await setup();
-            const seen = [];
-            const unsub = documentChanges.subscribe((c) => seen.push(c));
-            const hash = await hashContent('hi');
-            await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'hi', remoteHash: hash, remoteMtime: 1,
-            });
-            unsub();
-            expect(seen.some((c) => c.shardId === 's1' && c.path === 'a.md' && c.type === 'create')).toBe(true);
-        });
-    });
-    describe('conflict', () => {
-        it('default policy creates .sync-conflict artifact and returns conflict', async () => {
-            const { backend, engine } = await setup();
-            await backend.write('tenant-a', 's1', 'a.md', 'local-version');
-            vi.useFakeTimers().setSystemTime(new Date(1234));
-            const out = await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'remote-version',
-                remoteHash: await hashContent('remote-version'),
-                remoteMtime: Date.now(),
-            }, { expectedLocalHash: 'STALE' });
-            if (out.status !== 'conflict')
-                throw new Error('expected conflict');
-            expect(out.resolution.conflictArtifactPath).toContain('.sync-conflict-conn-A-1234');
-            expect(await backend.read('tenant-a', 's1', 'a.md')).toBe('local-version');
-            vi.useRealTimers();
-        });
-        it('remote-wins overwrites silently', async () => {
-            const { backend, engine } = await setup();
-            await backend.write('tenant-a', 's1', 'a.md', 'local');
-            const out = await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'remote', remoteHash: await hashContent('remote'), remoteMtime: 1,
-            }, { expectedLocalHash: 'STALE', onConflict: 'remote-wins' });
-            expect(out.status).toBe('applied');
-            expect(await backend.read('tenant-a', 's1', 'a.md')).toBe('remote');
-        });
-        it('local-wins leaves local untouched', async () => {
-            const { backend, engine } = await setup();
-            await backend.write('tenant-a', 's1', 'a.md', 'local');
-            const out = await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'remote', remoteHash: await hashContent('remote'), remoteMtime: 1,
-            }, { expectedLocalHash: 'STALE', onConflict: 'local-wins' });
-            expect(out.status).toBe('skipped-identical');
-            expect(await backend.read('tenant-a', 's1', 'a.md')).toBe('local');
-        });
-    });
-    describe('apply delete & tombstones', () => {
-        it('delete records tombstone and removes content', async () => {
-            const { backend, engine } = await setup();
-            await backend.write('tenant-a', 's1', 'a.md', 'x');
-            const out = await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'delete',
-                remoteHash: '', remoteMtime: 1,
-            });
-            expect(out.status).toBe('applied');
-            expect(await backend.exists('tenant-a', 's1', 'a.md')).toBe(false);
-            const manifest = await engine.getManifest('conn-A', { kind: 'shard', shardId: 's1' });
-            expect(manifest.some((m) => m.path === 'a.md' && m.tombstone)).toBe(true);
-        });
-        it('upsert after delete clears the tombstone', async () => {
-            const { engine } = await setup();
-            await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'v1', remoteHash: await hashContent('v1'), remoteMtime: 1,
-            });
-            await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'delete',
-                remoteHash: '', remoteMtime: 2,
-            });
-            await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'v2', remoteHash: await hashContent('v2'), remoteMtime: 3,
-            });
-            const manifest = await engine.getManifest('conn-A', { kind: 'shard', shardId: 's1' });
-            const entry = manifest.find((m) => m.path === 'a.md');
-            expect(entry === null || entry === void 0 ? void 0 : entry.tombstone).toBeUndefined();
-        });
-        it('forget removes the tombstone', async () => {
-            const { engine } = await setup();
-            await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'upsert',
-                content: 'x', remoteHash: await hashContent('x'), remoteMtime: 1,
-            });
-            await engine.apply('conn-A', { kind: 'shard', shardId: 's1' }, {
-                path: 'a.md', shardId: 's1', op: 'delete',
-                remoteHash: '', remoteMtime: 2,
-            });
-            await engine.forget({ kind: 'shard', shardId: 's1' }, 'a.md');
-            const manifest = await engine.getManifest('conn-A', { kind: 'shard', shardId: 's1' });
-            expect(manifest.find((m) => m.path === 'a.md')).toBeUndefined();
-        });
-    });
-    describe('applyBatch', () => {
-        it('returns applied/skipped/conflicts breakdown', async () => {
-            const { backend, engine } = await setup();
-            await backend.write('tenant-a', 's1', 'already.md', 'same');
-            const hSame = await hashContent('same');
-            const hNew = await hashContent('new');
-            const hConflict = await hashContent('remote');
-            await backend.write('tenant-a', 's1', 'conflict.md', 'local');
-            const res = await engine.applyBatch('conn-A', { kind: 'shard', shardId: 's1' }, [
-                { path: 'already.md', shardId: 's1', op: 'upsert', content: 'same', remoteHash: hSame, remoteMtime: 1 },
-                { path: 'new.md', shardId: 's1', op: 'upsert', content: 'new', remoteHash: hNew, remoteMtime: 1 },
-                { path: 'conflict.md', shardId: 's1', op: 'upsert', content: 'remote', remoteHash: hConflict, remoteMtime: 1 },
-            ], { expectedLocalHash: undefined });
-            expect(res.applied.map((a) => a.path).sort()).toEqual(['conflict.md', 'new.md']);
-            expect(res.skipped.map((s) => s.path)).toEqual(['already.md']);
-            // First-seen with no expectedLocalHash and no prior base → apply without conflict.
-            expect(res.conflicts).toEqual([]);
-        });
-    });
-    describe('getManifest', () => {
-        it('returns live docs with hashes', async () => {
-            const { backend, engine } = await setup();
-            await backend.write('tenant-a', 's1', 'a.md', 'hello');
-            const manifest = await engine.getManifest('conn-A', { kind: 'shard', shardId: 's1' });
-            const entry = manifest.find((m) => m.path === 'a.md');
-            expect(entry === null || entry === void 0 ? void 0 : entry.hash).toBe(await hashContent('hello'));
-            expect(entry === null || entry === void 0 ? void 0 : entry.shardId).toBe('s1');
-        });
-    });
-});

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

@@ -1,11 +0,0 @@
-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

@@ -1,79 +0,0 @@
-/*
- * 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);
-        },
-    };
-}