sh3-core 0.7.5 → 0.8.1

package/dist/documents/backends.js

@@ -62,6 +62,36 @@ export class MemoryDocumentBackend {
     async exists(tenantId, shardId, path) {
         return __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").has(compositeKey(tenantId, shardId, path));
     }
+    async listAllShards(tenantId) {
+        const prefix = `${tenantId}/`;
+        const shards = new Set();
+        for (const key of __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").keys()) {
+            if (!key.startsWith(prefix))
+                continue;
+            const rest = key.slice(prefix.length);
+            const slash = rest.indexOf('/');
+            if (slash < 0)
+                continue;
+            shards.add(rest.slice(0, slash));
+        }
+        return [...shards];
+    }
+    async listAllDocuments(tenantId) {
+        const prefix = `${tenantId}/`;
+        const out = [];
+        for (const [key, entry] of __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f")) {
+            if (!key.startsWith(prefix))
+                continue;
+            const rest = key.slice(prefix.length);
+            const slash = rest.indexOf('/');
+            if (slash < 0)
+                continue;
+            const shardId = rest.slice(0, slash);
+            const path = rest.slice(slash + 1);
+            out.push({ shardId, path, size: entry.size, lastModified: entry.lastModified });
+        }
+        return out;
+    }
 }
 _MemoryDocumentBackend_store = new WeakMap();
 // ---------------------------------------------------------------------------
@@ -126,6 +156,63 @@ export class IndexedDBDocumentBackend {
         const result = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.getKey(key));
         return result !== undefined;
     }
+    async listAllShards(tenantId) {
+        const prefix = `${tenantId}/`;
+        const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const store = tx.objectStore(IDB_STORE);
+            const range = IDBKeyRange.bound(prefix, prefix + '\uffff', false, false);
+            const req = store.openKeyCursor(range);
+            const shards = new Set();
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (cursor) {
+                    const rest = cursor.key.slice(prefix.length);
+                    const slash = rest.indexOf('/');
+                    if (slash >= 0)
+                        shards.add(rest.slice(0, slash));
+                    cursor.continue();
+                }
+                else {
+                    resolve([...shards]);
+                }
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async listAllDocuments(tenantId) {
+        const prefix = `${tenantId}/`;
+        const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const store = tx.objectStore(IDB_STORE);
+            const range = IDBKeyRange.bound(prefix, prefix + '\uffff', false, false);
+            const req = store.openCursor(range);
+            const out = [];
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (cursor) {
+                    const rest = cursor.key.slice(prefix.length);
+                    const slash = rest.indexOf('/');
+                    if (slash >= 0) {
+                        const entry = cursor.value;
+                        out.push({
+                            shardId: rest.slice(0, slash),
+                            path: rest.slice(slash + 1),
+                            size: entry.size,
+                            lastModified: entry.lastModified,
+                        });
+                    }
+                    cursor.continue();
+                }
+                else {
+                    resolve(out);
+                }
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
 }
 _IndexedDBDocumentBackend_dbPromise = new WeakMap(), _IndexedDBDocumentBackend_instances = new WeakSet(), _IndexedDBDocumentBackend_db = function _IndexedDBDocumentBackend_db() {
     if (!__classPrivateFieldGet(this, _IndexedDBDocumentBackend_dbPromise, "f")) {

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

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

package/dist/documents/backends.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { MemoryDocumentBackend } from './backends';
+describe('DocumentBackend tenant-wide primitives', () => {
+    it('listAllShards returns every shard that has content for a tenant', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'shard-a', 'x.txt', 'a');
+        await be.write('t1', 'shard-b', 'y.txt', 'b');
+        await be.write('t1', 'shard-b', 'nested/z.txt', 'bb');
+        await be.write('t2', 'shard-c', 'z.txt', 'c');
+        const shards = await be.listAllShards('t1');
+        expect(shards.sort()).toEqual(['shard-a', 'shard-b']);
+        const other = await be.listAllShards('t2');
+        expect(other).toEqual(['shard-c']);
+    });
+    it('listAllDocuments returns docs with shardId attached across the tenant', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'shard-a', 'x.txt', 'a');
+        await be.write('t1', 'shard-b', 'nested/y.txt', 'bb');
+        await be.write('t2', 'shard-c', 'z.txt', 'c');
+        const docs = await be.listAllDocuments('t1');
+        expect(docs).toHaveLength(2);
+        expect(docs.map((d) => `${d.shardId}/${d.path}`).sort()).toEqual([
+            'shard-a/x.txt',
+            'shard-b/nested/y.txt',
+        ]);
+    });
+    it('listAllDocuments returns an empty array for an unknown tenant', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'shard-a', 'x.txt', 'a');
+        expect(await be.listAllDocuments('ghost')).toEqual([]);
+        expect(await be.listAllShards('ghost')).toEqual([]);
+    });
+});

package/dist/documents/browse.d.ts

@@ -0,0 +1,12 @@
+import type { DocumentBackend, DocumentChange, DocumentMeta } from './types';
+export interface BrowseCapability {
+    /** Every document in the tenant across all shards, each tagged with its owning shardId. */
+    listDocuments(): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
+    /** Subscribe to tenant-wide document changes. Returns an unsubscribe. */
+    watchDocuments(callback: (change: DocumentChange) => void): () => void;
+    /** Enumerate shard ids with at least one document in the tenant. */
+    listShards(): Promise<string[]>;
+}
+export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend): BrowseCapability;

package/dist/documents/browse.js

@@ -0,0 +1,19 @@
+/*
+ * BrowseCapability — tenant-wide document observation surface.
+ *
+ * Exposed on ShardContext as `ctx.browse` when the shard declares the
+ * 'documents:browse' permission. Read-only: writes still flow through
+ * the owning shard's own ctx.documents() handle.
+ */
+import { documentChanges } from './notifications';
+export function createBrowseCapability(tenantId, backend) {
+    return {
+        listDocuments: () => backend.listAllDocuments(tenantId),
+        listShards: () => backend.listAllShards(tenantId),
+        watchDocuments: (callback) => documentChanges.subscribe((change) => {
+            if (change.tenantId !== tenantId)
+                return;
+            callback(change);
+        }),
+    };
+}

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

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

package/dist/documents/browse.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi } from 'vitest';
+import { MemoryDocumentBackend } from './backends';
+import { createBrowseCapability } from './browse';
+import { documentChanges } from './notifications';
+describe('BrowseCapability', () => {
+    it('lists documents tenant-wide with shardId attached', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'a', 'x.txt', '1');
+        await be.write('t1', 'b', 'y.txt', '22');
+        const browse = createBrowseCapability('t1', be);
+        const docs = await browse.listDocuments();
+        expect(docs.map((d) => d.shardId).sort()).toEqual(['a', 'b']);
+    });
+    it('listShards enumerates tenant shards', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'a', 'x.txt', '1');
+        await be.write('t1', 'b', 'y.txt', '2');
+        const browse = createBrowseCapability('t1', be);
+        expect((await browse.listShards()).sort()).toEqual(['a', 'b']);
+    });
+    it('watchDocuments fires with shardId on tenant-wide emits; filters other tenants', () => {
+        const be = new MemoryDocumentBackend();
+        const browse = createBrowseCapability('t1', be);
+        const cb = vi.fn();
+        const unsub = browse.watchDocuments(cb);
+        documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
+        documentChanges.emit({ type: 'create', path: 'g.txt', tenantId: 't2', shardId: 's2' });
+        expect(cb).toHaveBeenCalledTimes(1);
+        expect(cb).toHaveBeenCalledWith(expect.objectContaining({ shardId: 's1', path: 'f.txt', tenantId: 't1' }));
+        unsub();
+    });
+    it('watchDocuments unsubscribe stops callbacks', () => {
+        const be = new MemoryDocumentBackend();
+        const browse = createBrowseCapability('t1', be);
+        const cb = vi.fn();
+        const unsub = browse.watchDocuments(cb);
+        unsub();
+        documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
+        expect(cb).not.toHaveBeenCalled();
+    });
+});

package/dist/documents/handle.js

@@ -18,6 +18,8 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _AutosaveControllerImpl_instances, _AutosaveControllerImpl_handle, _AutosaveControllerImpl_path, _AutosaveControllerImpl_debounceMs, _AutosaveControllerImpl_pending, _AutosaveControllerImpl_timer, _AutosaveControllerImpl_dirty, _AutosaveControllerImpl_disposed, _AutosaveControllerImpl_scheduleFlush, _AutosaveControllerImpl_clearTimer;
 import { documentChanges } from './notifications';
+import { notifyJournal } from './journal-hook';
+import { hashContent } from './sync/hash';
 const DEFAULT_DEBOUNCE_MS = 1000;
 /**
  * Create a document handle scoped to a tenant, shard, and file filter.
@@ -53,10 +55,13 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
             const existed = await backend.exists(tenantId, shardId, path);
             await backend.write(tenantId, shardId, path, content);
             emitChange(existed ? 'update' : 'create', path);
+            const hash = await hashContent(content);
+            await notifyJournal({ shardId, path, op: 'upsert', hash });
         },
         async delete(path) {
             await backend.delete(tenantId, shardId, path);
             emitChange('delete', path);
+            await notifyJournal({ shardId, path, op: 'delete', hash: null });
         },
         async exists(path) {
             return backend.exists(tenantId, shardId, path);

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

@@ -19,4 +19,8 @@ export declare class HttpDocumentBackend implements DocumentBackend {
     delete(tenantId: string, shardId: string, path: string): Promise<void>;
     list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
     exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+    listAllShards(tenantId: string): Promise<string[]>;
+    listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
 }

package/dist/documents/http-backend.js

@@ -70,6 +70,20 @@ export class HttpDocumentBackend {
         const res = await fetch(url, { method: 'HEAD' });
         return res.ok;
     }
+    async listAllShards(tenantId) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/_shards`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`listAllShards failed: ${res.status}`);
+        return res.json();
+    }
+    async listAllDocuments(tenantId) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/_all`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`listAllDocuments failed: ${res.status}`);
+        return res.json();
+    }
 }
 _HttpDocumentBackend_baseUrl = new WeakMap(), _HttpDocumentBackend_apiKey = new WeakMap(), _HttpDocumentBackend_instances = new WeakSet(), _HttpDocumentBackend_authHeaders = function _HttpDocumentBackend_authHeaders() {
     if (!__classPrivateFieldGet(this, _HttpDocumentBackend_apiKey, "f"))

package/dist/documents/index.d.ts

@@ -4,3 +4,4 @@ export { HttpDocumentBackend } from './http-backend';
 export { createDocumentHandle } from './handle';
 export { documentChanges } from './notifications';
 export { getTenantId, getDocumentBackend, __setTenantId, __setDocumentBackend, } from './config';
+export * from './sync';

package/dist/documents/index.js

@@ -6,3 +6,4 @@ export { HttpDocumentBackend } from './http-backend';
 export { createDocumentHandle } from './handle';
 export { documentChanges } from './notifications';
 export { getTenantId, getDocumentBackend, __setTenantId, __setDocumentBackend, } from './config';
+export * from './sync';

package/dist/documents/journal-hook.d.ts

@@ -0,0 +1,6 @@
+import type { JournalEntry } from './sync/types';
+type Appender = (entry: Omit<JournalEntry, 'seq' | 'ts'>) => Promise<void>;
+export declare function setJournalAppender(fn: Appender): void;
+export declare function clearJournalAppender(): void;
+export declare function notifyJournal(entry: Omit<JournalEntry, 'seq' | 'ts'>): Promise<void>;
+export {};

package/dist/documents/journal-hook.js

@@ -0,0 +1,16 @@
+/*
+ * Journal appender hook — lets the sync engine subscribe to regular
+ * shard writes/deletes without creating an import cycle between the
+ * document handle and the sync subsystem.
+ */
+let appender = null;
+export function setJournalAppender(fn) {
+    appender = fn;
+}
+export function clearJournalAppender() {
+    appender = null;
+}
+export async function notifyJournal(entry) {
+    if (appender)
+        await appender(entry);
+}

package/dist/documents/sync/activate-integration.test.d.ts

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

package/dist/documents/sync/activate-integration.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../backends';
+import { __setDocumentBackend, __setTenantId } from '../config';
+import { __resetShardRegistryForTest, registerShard, activateShard } from '../../shards/activate.svelte';
+import { __resetSyncBundlesForTest } from './singleton';
+import { PERMISSION_DOCUMENTS_SYNC } from './types';
+describe('ctx.sync() gating', () => {
+    beforeEach(() => {
+        __resetShardRegistryForTest();
+        __resetSyncBundlesForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setTenantId('tenant-a');
+    });
+    it('is undefined without documents:sync permission', async () => {
+        let captured;
+        const shard = {
+            manifest: { id: 's-none', version: '0', views: [] },
+            activate: async (ctx) => { captured = ctx; },
+        };
+        registerShard(shard);
+        await activateShard('s-none');
+        expect(captured.sync).toBeUndefined();
+    });
+    it('is a function when documents:sync is declared', async () => {
+        let captured;
+        const shard = {
+            manifest: { id: 's-sync', version: '0', views: [], permissions: [PERMISSION_DOCUMENTS_SYNC] },
+            activate: async (ctx) => { captured = ctx; },
+        };
+        registerShard(shard);
+        await activateShard('s-sync');
+        expect(typeof captured.sync).toBe('function');
+        const h = captured.sync();
+        expect(h.connectorId).toBe('s-sync');
+        expect(await h.grantedScopes()).toEqual([]);
+    });
+});

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

@@ -0,0 +1,99 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import SyncGrantPicker from './SyncGrantPicker.svelte';
+  import { createSyncRegistry, type SyncRegistry } from '../registry';
+  import { getDocumentBackend, getTenantId } from '../../config';
+  import type { GrantRecord, SyncScope, ConflictResolution } from '../types';
+
+  interface Props {
+    /** Optional connector-specific filter; if omitted, shows everything. */
+    connectorId?: string;
+    /** Shard IDs whose conflict artifacts should be listed. */
+    conflictShardIds?: string[];
+    /** Pending grant request, if any — embeds the picker when set. */
+    pendingRequest?: { connectorId: string; scope: SyncScope };
+  }
+
+  let { connectorId, conflictShardIds = [], pendingRequest }: Props = $props();
+
+  let registry: SyncRegistry | null = $state(null);
+  let grants: GrantRecord[] = $state([]);
+  let conflicts: ConflictResolution[] = $state([]);
+
+  async function refresh() {
+    if (!registry) return;
+    grants = await registry.list(connectorId);
+    const all: ConflictResolution[] = [];
+    for (const shardId of conflictShardIds) {
+      all.push(...await registry.listConflicts(shardId));
+    }
+    conflicts = all;
+  }
+
+  onMount(async () => {
+    registry = createSyncRegistry(getDocumentBackend(), getTenantId());
+    await refresh();
+  });
+
+  async function revoke(record: GrantRecord) {
+    if (!registry) return;
+    await registry.revoke(record.connectorId, record.scope);
+    await refresh();
+  }
+
+  function describeScope(s: SyncScope): string {
+    if (s.kind === 'tenant') return 'entire tenant';
+    if (s.kind === 'shard') return `shard:${s.shardId}`;
+    return `shard:${s.shardId}/${s.prefix}`;
+  }
+</script>
+
+<section class="document-sync-explorer" part="container">
+  <h2 part="title">Document Sync</h2>
+
+  {#if pendingRequest}
+    <SyncGrantPicker
+      connectorId={pendingRequest.connectorId}
+      scope={pendingRequest.scope}
+      onGranted={refresh}
+    />
+  {/if}
+
+  <h3 part="subtitle">Granted scopes</h3>
+  {#if grants.length === 0}
+    <p part="empty">No scopes granted yet.</p>
+  {:else}
+    <ul part="grants">
+      {#each grants as g}
+        <li>
+          <span part="grant-connector">{g.connectorId}</span>
+          <span part="grant-scope">{describeScope(g.scope)}</span>
+          <button type="button" onclick={() => revoke(g)} part="revoke">Revoke</button>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+
+  <h3 part="subtitle">Conflicts</h3>
+  {#if conflicts.length === 0}
+    <p part="empty">No active conflicts.</p>
+  {:else}
+    <ul part="conflicts">
+      {#each conflicts as c}
+        <li>
+          <code part="conflict-path">{c.shardId}:{c.path}</code>
+          <small part="conflict-artifact">{c.conflictArtifactPath}</small>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</section>
+
+<style>
+  .document-sync-explorer {
+    display: grid;
+    gap: 0.75rem;
+  }
+  ul { list-style: none; padding: 0; margin: 0; }
+  li { display: flex; gap: 0.5rem; align-items: center; }
+</style>

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

@@ -0,0 +1,15 @@
+import type { SyncScope } from '../types';
+interface Props {
+    /** Optional connector-specific filter; if omitted, shows everything. */
+    connectorId?: string;
+    /** Shard IDs whose conflict artifacts should be listed. */
+    conflictShardIds?: string[];
+    /** Pending grant request, if any — embeds the picker when set. */
+    pendingRequest?: {
+        connectorId: string;
+        scope: SyncScope;
+    };
+}
+declare const DocumentSyncExplorer: import("svelte").Component<Props, {}, "">;
+type DocumentSyncExplorer = ReturnType<typeof DocumentSyncExplorer>;
+export default DocumentSyncExplorer;

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 {};