sh3-core 0.7.5 → 0.8.0

package/dist/documents/sync/components/SyncGrantPicker.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+  import { getDocumentBackend, getTenantId } from '../../config';
+  import { __grantInternal } from '../registry';
+  import type { SyncScope } from '../types';
+
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    connectorId: string;
+    scope: SyncScope;
+    onGranted?: () => void;
+    onCancel?: () => void;
+    rationale?: Snippet;
+  }
+
+  let { connectorId, scope, onGranted, onCancel, rationale }: Props = $props();
+
+  let pending = $state(false);
+  let error = $state<string | null>(null);
+
+  function describe(s: SyncScope): string {
+    switch (s.kind) {
+      case 'tenant': return 'all your documents across every shard';
+      case 'shard':  return `all documents for shard "${s.shardId}"`;
+      case 'path':   return `documents under "${s.prefix}" in shard "${s.shardId}"`;
+    }
+  }
+
+  async function confirm() {
+    pending = true;
+    error = null;
+    try {
+      await __grantInternal(getDocumentBackend(), getTenantId(), connectorId, scope);
+      onGranted?.();
+    } catch (e) {
+      error = e instanceof Error ? e.message : String(e);
+    } finally {
+      pending = false;
+    }
+  }
+</script>
+
+<section class="sync-grant-picker" part="container">
+  <header part="header">
+    <h3 part="title">Grant sync access</h3>
+  </header>
+  <p part="summary">
+    <strong>{connectorId}</strong> is requesting access to {describe(scope)}.
+  </p>
+  {#if rationale}{@render rationale()}{/if}
+  {#if error}
+    <p class="error" part="error">{error}</p>
+  {/if}
+  <footer part="actions">
+    <button type="button" disabled={pending} onclick={() => onCancel?.()} part="cancel">Cancel</button>
+    <button type="button" disabled={pending} onclick={confirm} part="confirm">Grant</button>
+  </footer>
+</section>
+
+<style>
+  .sync-grant-picker {
+    display: grid;
+    gap: 0.75rem;
+    padding: 1rem;
+    border: 1px solid var(--sh3-border, #444);
+    border-radius: 6px;
+  }
+  .error { color: var(--sh3-error, #c00); }
+  footer { display: flex; gap: 0.5rem; justify-content: flex-end; }
+</style>

package/dist/documents/sync/components/SyncGrantPicker.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { SyncScope } from '../types';
+import type { Snippet } from 'svelte';
+interface Props {
+    connectorId: string;
+    scope: SyncScope;
+    onGranted?: () => void;
+    onCancel?: () => void;
+    rationale?: Snippet;
+}
+declare const SyncGrantPicker: import("svelte").Component<Props, {}, "">;
+type SyncGrantPicker = ReturnType<typeof SyncGrantPicker>;
+export default SyncGrantPicker;

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

@@ -0,0 +1,30 @@
+import type { DocumentBackend } from '../types';
+import type { ConflictPolicy, ConflictResolution } from './types';
+interface ConflictInput {
+    connectorId: string;
+    shardId: string;
+    path: string;
+    localHash: string;
+    remoteHash: string;
+    remoteContent?: string | ArrayBuffer;
+    baseHash?: string;
+}
+export type ConflictAction = {
+    action: 'apply-remote';
+    asPath?: string;
+} | {
+    action: 'skip';
+} | {
+    action: 'conflict';
+    resolution: ConflictResolution;
+};
+export declare class ConflictManager {
+    private backend;
+    private tenantId;
+    constructor(backend: DocumentBackend, tenantId: string);
+    resolve(policy: ConflictPolicy, input: ConflictInput): Promise<ConflictAction>;
+    getBaseHash(connectorId: string, shardId: string, path: string): Promise<string | null>;
+    setBaseHash(connectorId: string, shardId: string, path: string, hash: string): Promise<void>;
+    listConflicts(shardId: string): Promise<ConflictResolution[]>;
+}
+export {};

package/dist/documents/sync/conflicts.js

@@ -0,0 +1,77 @@
+/*
+ * 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.d.ts

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

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

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

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

@@ -0,0 +1,188 @@
+/*
+ * 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.d.ts

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

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

@@ -0,0 +1,169 @@
+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');
+        });
+    });
+});