@quereus/plugin-sync 0.3.1

package/dist/src/metadata/tombstones.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Tombstone tracking for deletion synchronization.
+ *
+ * When a row is deleted, a tombstone is created with the deletion HLC.
+ * Tombstones prevent deleted rows from being resurrected by older writes.
+ */
+import type { SqlValue } from '@quereus/quereus';
+import type { KVStore, WriteBatch } from '@quereus/plugin-store';
+import { type HLC } from '../clock/hlc.js';
+/**
+ * Tombstone record.
+ */
+export interface Tombstone {
+    hlc: HLC;
+    createdAt: number;
+}
+/**
+ * Serialize a tombstone for storage.
+ * Format: 26 bytes HLC + 8 bytes createdAt
+ */
+export declare function serializeTombstone(tombstone: Tombstone): Uint8Array;
+/**
+ * Deserialize a tombstone from storage.
+ */
+export declare function deserializeTombstone(buffer: Uint8Array): Tombstone;
+/**
+ * Tombstone store operations.
+ */
+export declare class TombstoneStore {
+    private readonly kv;
+    private readonly tombstoneTTL;
+    constructor(kv: KVStore, tombstoneTTL: number);
+    /**
+     * Get the tombstone for a row, if it exists.
+     */
+    getTombstone(schemaName: string, tableName: string, pk: SqlValue[]): Promise<Tombstone | undefined>;
+    /**
+     * Create a tombstone for a deleted row.
+     */
+    setTombstone(schemaName: string, tableName: string, pk: SqlValue[], hlc: HLC): Promise<void>;
+    /**
+     * Set tombstone in a batch.
+     */
+    setTombstoneBatch(batch: WriteBatch, schemaName: string, tableName: string, pk: SqlValue[], hlc: HLC): void;
+    /**
+     * Delete a tombstone (used when resurrecting a row).
+     */
+    deleteTombstone(schemaName: string, tableName: string, pk: SqlValue[]): Promise<void>;
+    /**
+     * Check if a row is deleted and the deletion should block a write.
+     * Returns true if the row is deleted and the incoming HLC is older than the deletion.
+     */
+    isDeletedAndBlocking(schemaName: string, tableName: string, pk: SqlValue[], incomingHLC: HLC, allowResurrection: boolean): Promise<boolean>;
+    /**
+     * Prune expired tombstones.
+     * Returns the number of tombstones deleted.
+     */
+    pruneExpired(schemaName: string, tableName: string): Promise<number>;
+    /**
+     * Get all tombstones for a table (for sync).
+     */
+    getAllTombstones(schemaName: string, tableName: string): AsyncIterable<{
+        pk: SqlValue[];
+        tombstone: Tombstone;
+    }>;
+}
+//# sourceMappingURL=tombstones.d.ts.map

package/dist/src/metadata/tombstones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tombstones.d.ts","sourceRoot":"","sources":["../../../src/metadata/tombstones.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,KAAK,GAAG,EAA4C,MAAM,iBAAiB,CAAC;AAGrF;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,CASnE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAKlE;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBADZ,EAAE,EAAE,OAAO,EACX,YAAY,EAAE,MAAM;IAGvC;;OAEG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,GACb,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAOjC;;OAEG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,GAAG,EAAE,GAAG,GACP,OAAO,CAAC,IAAI,CAAC;IAMhB;;OAEG;IACH,iBAAiB,CACf,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,GAAG,EAAE,GAAG,GACP,IAAI;IAMP;;OAEG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,GACb,OAAO,CAAC,IAAI,CAAC;IAKhB;;;OAGG;IACG,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,QAAQ,EAAE,EACd,WAAW,EAAE,GAAG,EAChB,iBAAiB,EAAE,OAAO,GACzB,OAAO,CAAC,OAAO,CAAC;IAanB;;;OAGG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB1E;;OAEG;IACI,gBAAgB,CACrB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,aAAa,CAAC;QAAE,EAAE,EAAE,QAAQ,EAAE,CAAC;QAAC,SAAS,EAAE,SAAS,CAAA;KAAE,CAAC;CAc3D"}

package/dist/src/metadata/tombstones.js

@@ -0,0 +1,125 @@
+/**
+ * Tombstone tracking for deletion synchronization.
+ *
+ * When a row is deleted, a tombstone is created with the deletion HLC.
+ * Tombstones prevent deleted rows from being resurrected by older writes.
+ */
+import { serializeHLC, deserializeHLC, compareHLC } from '../clock/hlc.js';
+import { buildTombstoneKey, buildTombstoneScanBounds, decodePK } from './keys.js';
+/**
+ * Serialize a tombstone for storage.
+ * Format: 26 bytes HLC + 8 bytes createdAt
+ */
+export function serializeTombstone(tombstone) {
+    const result = new Uint8Array(34);
+    const hlcBytes = serializeHLC(tombstone.hlc);
+    result.set(hlcBytes, 0);
+    const view = new DataView(result.buffer);
+    view.setBigUint64(26, BigInt(tombstone.createdAt), false);
+    return result;
+}
+/**
+ * Deserialize a tombstone from storage.
+ */
+export function deserializeTombstone(buffer) {
+    const hlc = deserializeHLC(buffer.slice(0, 26));
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    const createdAt = Number(view.getBigUint64(26, false));
+    return { hlc, createdAt };
+}
+/**
+ * Tombstone store operations.
+ */
+export class TombstoneStore {
+    kv;
+    tombstoneTTL;
+    constructor(kv, tombstoneTTL) {
+        this.kv = kv;
+        this.tombstoneTTL = tombstoneTTL;
+    }
+    /**
+     * Get the tombstone for a row, if it exists.
+     */
+    async getTombstone(schemaName, tableName, pk) {
+        const key = buildTombstoneKey(schemaName, tableName, pk);
+        const data = await this.kv.get(key);
+        if (!data)
+            return undefined;
+        return deserializeTombstone(data);
+    }
+    /**
+     * Create a tombstone for a deleted row.
+     */
+    async setTombstone(schemaName, tableName, pk, hlc) {
+        const key = buildTombstoneKey(schemaName, tableName, pk);
+        const tombstone = { hlc, createdAt: Date.now() };
+        await this.kv.put(key, serializeTombstone(tombstone));
+    }
+    /**
+     * Set tombstone in a batch.
+     */
+    setTombstoneBatch(batch, schemaName, tableName, pk, hlc) {
+        const key = buildTombstoneKey(schemaName, tableName, pk);
+        const tombstone = { hlc, createdAt: Date.now() };
+        batch.put(key, serializeTombstone(tombstone));
+    }
+    /**
+     * Delete a tombstone (used when resurrecting a row).
+     */
+    async deleteTombstone(schemaName, tableName, pk) {
+        const key = buildTombstoneKey(schemaName, tableName, pk);
+        await this.kv.delete(key);
+    }
+    /**
+     * Check if a row is deleted and the deletion should block a write.
+     * Returns true if the row is deleted and the incoming HLC is older than the deletion.
+     */
+    async isDeletedAndBlocking(schemaName, tableName, pk, incomingHLC, allowResurrection) {
+        const tombstone = await this.getTombstone(schemaName, tableName, pk);
+        if (!tombstone)
+            return false;
+        if (allowResurrection) {
+            // Resurrection allowed: only block if incoming is older
+            return compareHLC(incomingHLC, tombstone.hlc) <= 0;
+        }
+        else {
+            // No resurrection: any tombstone blocks writes
+            return true;
+        }
+    }
+    /**
+     * Prune expired tombstones.
+     * Returns the number of tombstones deleted.
+     */
+    async pruneExpired(schemaName, tableName) {
+        const bounds = buildTombstoneScanBounds(schemaName, tableName);
+        const now = Date.now();
+        const batch = this.kv.batch();
+        let count = 0;
+        for await (const entry of this.kv.iterate(bounds)) {
+            const tombstone = deserializeTombstone(entry.value);
+            if (now - tombstone.createdAt > this.tombstoneTTL) {
+                batch.delete(entry.key);
+                count++;
+            }
+        }
+        await batch.write();
+        return count;
+    }
+    /**
+     * Get all tombstones for a table (for sync).
+     */
+    async *getAllTombstones(schemaName, tableName) {
+        const bounds = buildTombstoneScanBounds(schemaName, tableName);
+        for await (const entry of this.kv.iterate(bounds)) {
+            // Extract PK from key: tb:{schema}.{table}:{pk_json}
+            const keyStr = new TextDecoder().decode(entry.key);
+            const firstColon = keyStr.indexOf(':');
+            const secondColon = keyStr.indexOf(':', firstColon + 1);
+            const pkJson = keyStr.slice(secondColon + 1);
+            const pk = decodePK(pkJson);
+            yield { pk, tombstone: deserializeTombstone(entry.value) };
+        }
+    }
+}
+//# sourceMappingURL=tombstones.js.map

package/dist/src/metadata/tombstones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tombstones.js","sourceRoot":"","sources":["../../../src/metadata/tombstones.ts"],"names":[],"mappings":"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"}

package/dist/src/sync/events.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Sync event types for reactive UI integration.
+ *
+ * These events allow applications to react to sync state changes,
+ * remote data updates, and conflict resolution.
+ */
+import type { SqlValue } from '@quereus/quereus';
+import type { HLC } from '../clock/hlc.js';
+import type { SiteId } from '../clock/site.js';
+import type { Change } from './protocol.js';
+/**
+ * Fired when remote changes are applied locally.
+ */
+export interface RemoteChangeEvent {
+    /** Origin replica */
+    readonly siteId: SiteId;
+    /** Transaction ID */
+    readonly transactionId: string;
+    /** Changes that were applied */
+    readonly changes: Change[];
+    /** When changes were applied locally */
+    readonly appliedAt: HLC;
+}
+/**
+ * Fired when local changes are made.
+ */
+export interface LocalChangeEvent {
+    /** Transaction ID */
+    readonly transactionId: string;
+    /** Changes made locally */
+    readonly changes: Change[];
+    /** True if not yet synced to any peer */
+    readonly pendingSync: boolean;
+}
+/**
+ * Fired when a conflict is resolved.
+ */
+export interface ConflictEvent {
+    /** Table where conflict occurred */
+    readonly table: string;
+    /** Primary key of the row */
+    readonly pk: SqlValue[];
+    /** Column where conflict occurred */
+    readonly column: string;
+    /** Local value that was in conflict */
+    readonly localValue: SqlValue;
+    /** Remote value that was in conflict */
+    readonly remoteValue: SqlValue;
+    /** Which value won */
+    readonly winner: 'local' | 'remote';
+    /** HLC of the winning value */
+    readonly winningHLC: HLC;
+}
+/**
+ * Sync connection state.
+ */
+export type SyncState = {
+    readonly status: 'disconnected';
+} | {
+    readonly status: 'connecting';
+} | {
+    readonly status: 'syncing';
+    readonly progress: number;
+} | {
+    readonly status: 'synced';
+    readonly lastSyncHLC: HLC;
+} | {
+    readonly status: 'error';
+    readonly error: Error;
+};
+/**
+ * Unsubscribe function returned by event listeners.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Sync event emitter for reactive UI integration.
+ */
+export interface SyncEventEmitter {
+    /**
+     * Subscribe to remote change events.
+     * Fired when changes from another replica are applied locally.
+     */
+    onRemoteChange(listener: (event: RemoteChangeEvent) => void): Unsubscribe;
+    /**
+     * Subscribe to local change events.
+     * Fired when local mutations occur.
+     */
+    onLocalChange(listener: (event: LocalChangeEvent) => void): Unsubscribe;
+    /**
+     * Subscribe to sync state changes.
+     * Fired when connection state changes.
+     */
+    onSyncStateChange(listener: (state: SyncState) => void): Unsubscribe;
+    /**
+     * Subscribe to conflict resolution events.
+     * Fired when a conflict is resolved via LWW.
+     */
+    onConflictResolved(listener: (event: ConflictEvent) => void): Unsubscribe;
+}
+/**
+ * Default implementation of SyncEventEmitter.
+ */
+export declare class SyncEventEmitterImpl implements SyncEventEmitter {
+    private remoteChangeListeners;
+    private localChangeListeners;
+    private syncStateListeners;
+    private conflictListeners;
+    onRemoteChange(listener: (event: RemoteChangeEvent) => void): Unsubscribe;
+    onLocalChange(listener: (event: LocalChangeEvent) => void): Unsubscribe;
+    onSyncStateChange(listener: (state: SyncState) => void): Unsubscribe;
+    onConflictResolved(listener: (event: ConflictEvent) => void): Unsubscribe;
+    emitRemoteChange(event: RemoteChangeEvent): void;
+    emitLocalChange(event: LocalChangeEvent): void;
+    emitSyncStateChange(state: SyncState): void;
+    emitConflictResolved(event: ConflictEvent): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/src/sync/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/sync/events.ts"],"names":[],"mappings":"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"}

package/dist/src/sync/events.js

@@ -0,0 +1,56 @@
+/**
+ * Sync event types for reactive UI integration.
+ *
+ * These events allow applications to react to sync state changes,
+ * remote data updates, and conflict resolution.
+ */
+// ============================================================================
+// Event Emitter Implementation
+// ============================================================================
+/**
+ * Default implementation of SyncEventEmitter.
+ */
+export class SyncEventEmitterImpl {
+    remoteChangeListeners = new Set();
+    localChangeListeners = new Set();
+    syncStateListeners = new Set();
+    conflictListeners = new Set();
+    onRemoteChange(listener) {
+        this.remoteChangeListeners.add(listener);
+        return () => this.remoteChangeListeners.delete(listener);
+    }
+    onLocalChange(listener) {
+        this.localChangeListeners.add(listener);
+        return () => this.localChangeListeners.delete(listener);
+    }
+    onSyncStateChange(listener) {
+        this.syncStateListeners.add(listener);
+        return () => this.syncStateListeners.delete(listener);
+    }
+    onConflictResolved(listener) {
+        this.conflictListeners.add(listener);
+        return () => this.conflictListeners.delete(listener);
+    }
+    // Internal emit methods
+    emitRemoteChange(event) {
+        for (const listener of this.remoteChangeListeners) {
+            listener(event);
+        }
+    }
+    emitLocalChange(event) {
+        for (const listener of this.localChangeListeners) {
+            listener(event);
+        }
+    }
+    emitSyncStateChange(state) {
+        for (const listener of this.syncStateListeners) {
+            listener(state);
+        }
+    }
+    emitConflictResolved(event) {
+        for (const listener of this.conflictListeners) {
+            listener(event);
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/src/sync/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/sync/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyGH,+EAA+E;AAC/E,+BAA+B;AAC/B,+EAA+E;AAE/E;;GAEG;AACH,MAAM,OAAO,oBAAoB;IACvB,qBAAqB,GAAG,IAAI,GAAG,EAAsC,CAAC;IACtE,oBAAoB,GAAG,IAAI,GAAG,EAAqC,CAAC;IACpE,kBAAkB,GAAG,IAAI,GAAG,EAA8B,CAAC;IAC3D,iBAAiB,GAAG,IAAI,GAAG,EAAkC,CAAC;IAEtE,cAAc,CAAC,QAA4C;QACzD,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3D,CAAC;IAED,aAAa,CAAC,QAA2C;QACvD,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED,iBAAiB,CAAC,QAAoC;QACpD,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED,kBAAkB,CAAC,QAAwC;QACzD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvD,CAAC;IAED,wBAAwB;IAExB,gBAAgB,CAAC,KAAwB;QACvC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,qBAAqB,EAAE,CAAC;YAClD,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,eAAe,CAAC,KAAuB;QACrC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,oBAAoB,EAAE,CAAC;YACjD,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,mBAAmB,CAAC,KAAgB;QAClC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC/C,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,oBAAoB,CAAC,KAAoB;QACvC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC9C,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,8 @@
+/**
+ * Sync module exports.
+ */
+export * from './protocol.js';
+export * from './manager.js';
+export * from './events.js';
+export * from './sync-manager-impl.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/sync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC"}

package/dist/src/sync/index.js

@@ -0,0 +1,8 @@
+/**
+ * Sync module exports.
+ */
+export * from './protocol.js';
+export * from './manager.js';
+export * from './events.js';
+export * from './sync-manager-impl.js';
+//# sourceMappingURL=index.js.map

package/dist/src/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC"}

package/dist/src/sync/manager.d.ts

@@ -0,0 +1,146 @@
+/**
+ * SyncManager - main API for sync operations.
+ *
+ * This interface defines the transport-agnostic sync API.
+ * Applications implement their own transport layer and call these methods.
+ */
+import type { HLC } from '../clock/hlc.js';
+import type { SiteId } from '../clock/site.js';
+import type { ApplyResult, ChangeSet, Snapshot, SnapshotChunk, SnapshotProgress } from './protocol.js';
+/**
+ * Main sync manager interface.
+ *
+ * This is the primary API for sync operations. Applications use this to:
+ * - Get changes to send to peers
+ * - Apply changes received from peers
+ * - Manage sync state
+ */
+export interface SyncManager {
+    /**
+     * Get this replica's site ID.
+     */
+    getSiteId(): SiteId;
+    /**
+     * Get current HLC for state comparison.
+     */
+    getCurrentHLC(): HLC;
+    /**
+     * Get all changes since a peer's last known state.
+     *
+     * @param peerSiteId - The peer requesting changes
+     * @param sinceHLC - The peer's last known HLC (omit for full sync)
+     * @returns Array of change sets to send to the peer
+     */
+    getChangesSince(peerSiteId: SiteId, sinceHLC?: HLC): Promise<ChangeSet[]>;
+    /**
+     * Apply changes received from a peer.
+     *
+     * Changes are applied atomically per transaction.
+     * Conflicts are resolved using column-level LWW.
+     *
+     * @param changes - Change sets received from a peer
+     * @returns Statistics about what was applied
+     */
+    applyChanges(changes: ChangeSet[]): Promise<ApplyResult>;
+    /**
+     * Check if delta sync is possible with a peer.
+     *
+     * Returns false if:
+     * - Tombstone TTL has expired for relevant data
+     * - Peer's last sync is too old
+     * - Full snapshot is required
+     *
+     * @param peerSiteId - The peer to check
+     * @param sinceHLC - The peer's last known HLC
+     */
+    canDeltaSync(peerSiteId: SiteId, sinceHLC: HLC): Promise<boolean>;
+    /**
+     * Get a full snapshot for initial sync or TTL expiration recovery.
+     *
+     * This includes all current data and schema state.
+     */
+    getSnapshot(): Promise<Snapshot>;
+    /**
+     * Apply a full snapshot (replaces all local data).
+     *
+     * Used for initial sync or when delta sync is not possible.
+     *
+     * @param snapshot - Full snapshot from a peer
+     */
+    applySnapshot(snapshot: Snapshot): Promise<void>;
+    /**
+     * Update the last sync state for a peer.
+     *
+     * Called after successfully syncing with a peer.
+     *
+     * @param peerSiteId - The peer we synced with
+     * @param hlc - The HLC we synced up to
+     */
+    updatePeerSyncState(peerSiteId: SiteId, hlc: HLC): Promise<void>;
+    /**
+     * Get the last sync state for a peer.
+     *
+     * @param peerSiteId - The peer to check
+     * @returns The last HLC we synced to, or undefined if never synced
+     */
+    getPeerSyncState(peerSiteId: SiteId): Promise<HLC | undefined>;
+    /**
+     * Prune expired tombstones.
+     *
+     * Should be called periodically to clean up old tombstones.
+     * Returns the number of tombstones pruned.
+     */
+    pruneTombstones(): Promise<number>;
+    /**
+     * Stream a snapshot as chunks for memory-efficient transfer.
+     *
+     * Use this instead of getSnapshot() for large databases.
+     * Chunks are yielded in order and can be sent over any streaming transport.
+     *
+     * @param chunkSize - Max column version entries per chunk (default: 1000)
+     */
+    getSnapshotStream(chunkSize?: number): AsyncIterable<SnapshotChunk>;
+    /**
+     * Apply a streamed snapshot.
+     *
+     * Processes chunks as they arrive, minimizing memory usage.
+     * Supports resumption via checkpoint tracking.
+     *
+     * @param chunks - Async iterable of snapshot chunks
+     * @param onProgress - Optional progress callback
+     */
+    applySnapshotStream(chunks: AsyncIterable<SnapshotChunk>, onProgress?: (progress: SnapshotProgress) => void): Promise<void>;
+    /**
+     * Get a resumable checkpoint for an in-progress snapshot.
+     *
+     * Used to resume an interrupted snapshot transfer.
+     *
+     * @param snapshotId - The snapshot ID to get checkpoint for
+     */
+    getSnapshotCheckpoint(snapshotId: string): Promise<SnapshotCheckpoint | undefined>;
+    /**
+     * Resume a snapshot transfer from a checkpoint.
+     *
+     * @param checkpoint - Previously saved checkpoint
+     */
+    resumeSnapshotStream(checkpoint: SnapshotCheckpoint): AsyncIterable<SnapshotChunk>;
+}
+/**
+ * Checkpoint for resumable snapshot transfers.
+ */
+export interface SnapshotCheckpoint {
+    readonly snapshotId: string;
+    readonly siteId: SiteId;
+    readonly hlc: HLC;
+    /** Last completed table index. */
+    readonly lastTableIndex: number;
+    /** Last completed entry within current table. */
+    readonly lastEntryIndex: number;
+    /** Tables completed so far. */
+    readonly completedTables: string[];
+    /** Total entries processed. */
+    readonly entriesProcessed: number;
+    /** Timestamp when checkpoint was created. */
+    readonly createdAt: number;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/src/sync/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/sync/manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEvG;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,SAAS,IAAI,MAAM,CAAC;IAEpB;;OAEG;IACH,aAAa,IAAI,GAAG,CAAC;IAErB;;;;;;OAMG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAE1E;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD;;;;;;;;;;OAUG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElE;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjC;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;;;;;OAOG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC;IAE/D;;;;;OAKG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAMnC;;;;;;;OAOG;IACH,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;IAEpE;;;;;;;;OAQG;IACH,mBAAmB,CACjB,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,EACpC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,GAChD,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAEnF;;;;OAIG;IACH,oBAAoB,CAAC,UAAU,EAAE,kBAAkB,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;CACpF;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,kCAAkC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/src/sync/manager.js

@@ -0,0 +1,8 @@
+/**
+ * SyncManager - main API for sync operations.
+ *
+ * This interface defines the transport-agnostic sync API.
+ * Applications implement their own transport layer and call these methods.
+ */
+export {};
+//# sourceMappingURL=manager.js.map

package/dist/src/sync/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/sync/manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}