@interop/wallet-core 0.1.0

package/dist/sync/engine.js

@@ -0,0 +1,188 @@
+import { runPull } from './pull.js';
+import { runPush } from './push.js';
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_BASE_DELAY_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 60_000;
+function defaultSchedule(fn, delayMs) {
+    const timer = setTimeout(fn, delayMs);
+    return () => clearTimeout(timer);
+}
+export class SyncEngine {
+    deps;
+    status = 'idle';
+    batchSize;
+    baseDelayMs;
+    maxDelayMs;
+    schedule;
+    random;
+    running = false;
+    rerunRequested = false;
+    stopped = false;
+    failureCount = 0;
+    currentRun = null;
+    abortController = null;
+    cancelRetry = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.batchSize = deps.batchSize ?? DEFAULT_BATCH_SIZE;
+        this.baseDelayMs = deps.backoff?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+        this.maxDelayMs = deps.backoff?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+        this.schedule = deps.schedule ?? defaultSchedule;
+        this.random = deps.random ?? Math.random;
+    }
+    /**
+     * Requests a sync. Single-flight: if a cycle is in flight this only flags a
+     * rerun (so writes that land mid-cycle are not lost) and resolves with the
+     * in-flight run; otherwise it starts a fresh run. Never rejects -- failures
+     * settle into `status = 'error'` plus a scheduled backoff retry, per the
+     * local-first invariant (sync must never surface as a rejected write).
+     *
+     * @returns {Promise<void>}
+     */
+    sync() {
+        if (this.stopped) {
+            return Promise.resolve();
+        }
+        if (this.running && this.currentRun !== null) {
+            this.rerunRequested = true;
+            return this.currentRun;
+        }
+        this.currentRun = this.run();
+        return this.currentRun;
+    }
+    /**
+     * Stops the engine: aborts any in-flight cycle (the injected signal unwinds
+     * pull/push between pages/rows), cancels a pending retry, and resets to idle.
+     * The caller drops the cached agents/ciphers so key material does not outlive
+     * the unlocked session.
+     */
+    stop() {
+        this.stopped = true;
+        this.abortController?.abort();
+        this.clearRetry();
+        this.setStatus('idle');
+    }
+    async run() {
+        this.running = true;
+        this.clearRetry();
+        this.setStatus('syncing');
+        const controller = new AbortController();
+        this.abortController = controller;
+        const { signal } = controller;
+        try {
+            do {
+                this.rerunRequested = false;
+                await this.runCycle(signal);
+            } while (this.rerunRequested && !signal.aborted && !this.stopped);
+            if (!signal.aborted && !this.stopped) {
+                this.failureCount = 0;
+                this.setStatus('synced');
+            }
+        }
+        catch {
+            // Local-first: an engine failure is never fatal. A stop-driven abort is
+            // not an error; any other failure flips to `error` and schedules a retry.
+            if (!signal.aborted && !this.stopped) {
+                this.setStatus('error');
+                this.scheduleRetry();
+            }
+        }
+        finally {
+            this.running = false;
+            this.currentRun = null;
+        }
+    }
+    /**
+     * One full replication cycle. On the very first run (never migrated) it pulls
+     * before the sweep so existing local rows hash-link to any bodies already on
+     * the server -- the sweep then only encrypts genuinely-new records
+     * (re-encrypting an existing one would mint a different content id and leave a
+     * permanent server duplicate). The unlinked-record sweep (`runLazyMigration`)
+     * runs on EVERY cycle, not just the first, so records that enter the replica
+     * outside the synced write path -- an import, or a write whose minting failed
+     * and fell back to a plain insert -- are still picked up and pushed (it is a
+     * cheap no-op when there are none). Steady state is sweep-then-push-then-pull:
+     * our own writes echo back in the same cycle's pull, idempotently.
+     */
+    async runCycle(signal) {
+        await this.deps.ensureProvisioned();
+        if (signal.aborted) {
+            return;
+        }
+        const firstCycle = !(await this.deps.isMigrated());
+        if (firstCycle) {
+            await this.pull(signal);
+            if (signal.aborted) {
+                return;
+            }
+        }
+        await this.deps.runLazyMigration(signal);
+        if (signal.aborted) {
+            return;
+        }
+        if (firstCycle) {
+            await this.deps.stampMigrated();
+            if (signal.aborted) {
+                return;
+            }
+        }
+        const { conflictsResolved } = await runPush({
+            port: this.deps.port,
+            store: this.deps.store,
+            resolveConflict: this.deps.resolveConflict,
+            signal
+        });
+        if (signal.aborted) {
+            return;
+        }
+        // A resolved last-write-wins conflict may leave a row dirty (local-wins
+        // re-encrypt); rerun this run so the re-push settles instead of waiting for
+        // the next external trigger. Idempotent once the conflict clears.
+        if (conflictsResolved > 0) {
+            this.rerunRequested = true;
+        }
+        const applied = await this.pull(signal);
+        if (signal.aborted) {
+            return;
+        }
+        await this.deps.stampLastSynced();
+        if (applied > 0) {
+            this.deps.onPullApplied?.();
+        }
+    }
+    async pull(signal) {
+        const { applied } = await runPull({
+            port: this.deps.port,
+            store: this.deps.store,
+            batchSize: this.batchSize,
+            decryptDoc: this.deps.decryptDoc,
+            signal
+        });
+        return applied;
+    }
+    scheduleRetry() {
+        const capped = Math.min(this.baseDelayMs * 2 ** this.failureCount, this.maxDelayMs);
+        // Full jitter over the first half of the interval keeps N engines from
+        // retrying in lockstep.
+        const delay = capped + capped * 0.5 * this.random();
+        this.failureCount += 1;
+        this.cancelRetry = this.schedule(() => {
+            this.cancelRetry = null;
+            void this.sync();
+        }, delay);
+    }
+    clearRetry() {
+        if (this.cancelRetry !== null) {
+            this.cancelRetry();
+            this.cancelRetry = null;
+        }
+    }
+    setStatus(status) {
+        if (this.status === status) {
+            return;
+        }
+        this.status = status;
+        this.deps.onStatusChange?.(status);
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/sync/engine.js.map

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

package/dist/sync/index.d.ts

@@ -0,0 +1,33 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/sync` subpath: the WAS replication engine core --
+ * the correctness-critical, cross-replica byte-compatibility surface two
+ * WAS-enabled wallet apps share.
+ *
+ * - The wire contract and port seam (`WasSyncPort`, `SyncCheckpoint`, `WireDoc`,
+ *   `Json`, `DocCipher`, `MasterState`, and the `WasSyncConflictError` /
+ *   `WasSyncNotFoundError` signals) come from `@interop/was-client/sync` and are
+ *   re-exported here so an engine consumer imports one package.
+ * - `SyncStore` / `SyncedRow` / `ProjectionAction` / `ResolveConflict` are the
+ *   replica-side persistence seam.
+ * - `runPull` / `projectionForDoc`, `runPush`, and `SyncEngine` are the pull,
+ *   push, and orchestration algorithms.
+ * - `SyncedCollectionSpec` is the generic per-collection spec shape a concrete
+ *   registry implements.
+ *
+ * The RxDB adapter (the web wallet's driver) is intentionally not part of this
+ * subpath in v0: that app keeps its own `replicateRxCollection` driver, and its
+ * metadata (`putMeta` / `metaVersion`) push half stays driver-side. See
+ * `push.ts` for why the metadata half is left out of the shared core.
+ */
+export { WasSyncConflictError, WasSyncNotFoundError } from '@interop/was-client/sync';
+export type { Json, SyncCheckpoint, WireDoc, MasterState, WasSyncPort, DocCipher } from '@interop/was-client/sync';
+export type { SyncStore, SyncedRow, ProjectionAction, ResolveConflict } from './types.js';
+export { runPull, projectionForDoc } from './pull.js';
+export { runPush, formatEtag } from './push.js';
+export { SyncEngine } from './engine.js';
+export type { SyncEngineDeps, SyncStatus } from './engine.js';
+export type { SyncedCollectionSpec } from './collections.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,0BAA0B,CAAA;AACjC,YAAY,EACV,IAAI,EACJ,cAAc,EACd,OAAO,EACP,WAAW,EACX,WAAW,EACX,SAAS,EACV,MAAM,0BAA0B,CAAA;AAEjC,YAAY,EACV,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,eAAe,EAChB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7D,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/sync/index.js

@@ -0,0 +1,29 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/sync` subpath: the WAS replication engine core --
+ * the correctness-critical, cross-replica byte-compatibility surface two
+ * WAS-enabled wallet apps share.
+ *
+ * - The wire contract and port seam (`WasSyncPort`, `SyncCheckpoint`, `WireDoc`,
+ *   `Json`, `DocCipher`, `MasterState`, and the `WasSyncConflictError` /
+ *   `WasSyncNotFoundError` signals) come from `@interop/was-client/sync` and are
+ *   re-exported here so an engine consumer imports one package.
+ * - `SyncStore` / `SyncedRow` / `ProjectionAction` / `ResolveConflict` are the
+ *   replica-side persistence seam.
+ * - `runPull` / `projectionForDoc`, `runPush`, and `SyncEngine` are the pull,
+ *   push, and orchestration algorithms.
+ * - `SyncedCollectionSpec` is the generic per-collection spec shape a concrete
+ *   registry implements.
+ *
+ * The RxDB adapter (the web wallet's driver) is intentionally not part of this
+ * subpath in v0: that app keeps its own `replicateRxCollection` driver, and its
+ * metadata (`putMeta` / `metaVersion`) push half stays driver-side. See
+ * `push.ts` for why the metadata half is left out of the shared core.
+ */
+export { WasSyncConflictError, WasSyncNotFoundError } from '@interop/was-client/sync';
+export { runPull, projectionForDoc } from './pull.js';
+export { runPush, formatEtag } from './push.js';
+export { SyncEngine } from './engine.js';
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,0BAA0B,CAAA;AAiBjC,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/dist/sync/pull.d.ts

@@ -0,0 +1,68 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The pull side of the WAS replication engine core: iterate the `changes` feed
+ * from the stored checkpoint, decrypt each document to a projection action
+ * OUTSIDE the store transaction, and hand each page to the store to apply
+ * atomically.
+ *
+ * All I/O is through the injected {@link WasSyncPort} and {@link SyncStore};
+ * decryption is the injected `decryptDoc`. No environment-specific imports, so
+ * the loop runs identically in the browser, Node, and React Native.
+ *
+ * Cross-replica invariants this loop and the RxDB `createPullHandler` in the web
+ * wallet's driver both hold, so the two replicas resume the same feed the same
+ * way:
+ * - Omit `checkpoint` entirely on the first pull (never send `null`).
+ * - Empty page (`checkpoint: null`, "no change") keeps the PRIOR checkpoint --
+ *   never overwrite it with `null`, or the feed restarts from the beginning.
+ * - A tombstone deletes the projected row; a live document decrypts its `data`
+ *   body to the payload to upsert.
+ */
+import type { Json, ProjectionAction, SyncStore, WasSyncPort, WireDoc } from './types.js';
+/**
+ * Maps one pulled wire document to the projection action for the decrypted
+ * read-model. A tombstone deletes the projected row; a live document decrypts
+ * its `data` body to the payload to upsert. A live document with no body (should
+ * not occur on an encrypted collection) is a no-op.
+ *
+ * Decryption runs here, outside the store transaction, so a slow/failing decrypt
+ * never holds the store's write lock. A document whose body cannot be decrypted
+ * (legacy plaintext row, corrupt/foreign envelope, key mismatch) is skipped with
+ * a `none` projection rather than throwing: the body is still stored and the
+ * checkpoint advances past it, so one poison document can never permanently
+ * wedge the feed for the whole replica.
+ *
+ * @param doc {WireDoc}
+ * @param decryptDoc {(envelope: Json) => Promise<Json>}
+ * @returns {Promise<ProjectionAction>}
+ */
+export declare function projectionForDoc(doc: WireDoc, decryptDoc: (envelope: Json) => Promise<Json>): Promise<ProjectionAction>;
+/**
+ * Runs the pull loop to exhaustion for one feed. Fetches a page from the current
+ * checkpoint, decrypts it to projections, and applies it (upserts + projection +
+ * checkpoint advance) in one exclusive store transaction. Terminates on a short
+ * page (caught up) or an empty page (no change -- the prior checkpoint is kept,
+ * never overwritten with `null`). Honors `signal` between pages so a lock drops
+ * the loop promptly; a mid-loop abort leaves each already-applied page intact
+ * and the feed resumable.
+ *
+ * @param options {object}
+ * @param options.port {WasSyncPort}
+ * @param options.store {SyncStore}
+ * @param options.batchSize {number}     pull `limit` (server clamps at 1000)
+ * @param options.decryptDoc {(envelope: Json) => Promise<Json>}
+ * @param [options.signal] {AbortSignal}
+ * @returns {Promise<{ applied: number }>}   documents applied across all pages
+ */
+export declare function runPull({ port, store, batchSize, decryptDoc, signal }: {
+    port: WasSyncPort;
+    store: SyncStore;
+    batchSize: number;
+    decryptDoc: (envelope: Json) => Promise<Json>;
+    signal?: AbortSignal;
+}): Promise<{
+    applied: number;
+}>;
+//# sourceMappingURL=pull.d.ts.map

package/dist/sync/pull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../src/sync/pull.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EACV,IAAI,EACJ,gBAAgB,EAEhB,SAAS,EACT,WAAW,EACX,OAAO,EACR,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,CAAC,QAAQ,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,GAC5C,OAAO,CAAC,gBAAgB,CAAC,CAiB3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,OAAO,CAAC,EAC5B,IAAI,EACJ,KAAK,EACL,SAAS,EACT,UAAU,EACV,MAAM,EACP,EAAE;IACD,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,EAAE,SAAS,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,CAAC,QAAQ,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA8C/B"}

package/dist/sync/pull.js

@@ -0,0 +1,92 @@
+/**
+ * Maps one pulled wire document to the projection action for the decrypted
+ * read-model. A tombstone deletes the projected row; a live document decrypts
+ * its `data` body to the payload to upsert. A live document with no body (should
+ * not occur on an encrypted collection) is a no-op.
+ *
+ * Decryption runs here, outside the store transaction, so a slow/failing decrypt
+ * never holds the store's write lock. A document whose body cannot be decrypted
+ * (legacy plaintext row, corrupt/foreign envelope, key mismatch) is skipped with
+ * a `none` projection rather than throwing: the body is still stored and the
+ * checkpoint advances past it, so one poison document can never permanently
+ * wedge the feed for the whole replica.
+ *
+ * @param doc {WireDoc}
+ * @param decryptDoc {(envelope: Json) => Promise<Json>}
+ * @returns {Promise<ProjectionAction>}
+ */
+export async function projectionForDoc(doc, decryptDoc) {
+    if (doc._deleted) {
+        return { kind: 'delete' };
+    }
+    if (doc.data === undefined || doc.data === null) {
+        return { kind: 'none' };
+    }
+    try {
+        const payload = await decryptDoc(doc.data);
+        return { kind: 'upsert', payload };
+    }
+    catch (err) {
+        console.warn(`Skipping undecryptable synced document "${doc.id}" (no projection):`, err);
+        return { kind: 'none' };
+    }
+}
+/**
+ * Runs the pull loop to exhaustion for one feed. Fetches a page from the current
+ * checkpoint, decrypts it to projections, and applies it (upserts + projection +
+ * checkpoint advance) in one exclusive store transaction. Terminates on a short
+ * page (caught up) or an empty page (no change -- the prior checkpoint is kept,
+ * never overwritten with `null`). Honors `signal` between pages so a lock drops
+ * the loop promptly; a mid-loop abort leaves each already-applied page intact
+ * and the feed resumable.
+ *
+ * @param options {object}
+ * @param options.port {WasSyncPort}
+ * @param options.store {SyncStore}
+ * @param options.batchSize {number}     pull `limit` (server clamps at 1000)
+ * @param options.decryptDoc {(envelope: Json) => Promise<Json>}
+ * @param [options.signal] {AbortSignal}
+ * @returns {Promise<{ applied: number }>}   documents applied across all pages
+ */
+export async function runPull({ port, store, batchSize, decryptDoc, signal }) {
+    let applied = 0;
+    for (;;) {
+        if (signal?.aborted) {
+            break;
+        }
+        const checkpoint = await store.getCheckpoint();
+        const { documents, checkpoint: next } = await port.query({
+            // Omit `checkpoint` entirely on the first pull.
+            ...(checkpoint !== undefined && { checkpoint }),
+            limit: batchSize
+        });
+        // Empty page ("no change") -- or a defensively-guarded null checkpoint on a
+        // non-empty page: keep the prior checkpoint so the feed does not restart.
+        if (documents.length === 0 || next === null) {
+            break;
+        }
+        const projections = new Map();
+        for (const doc of documents) {
+            projections.set(doc.id, await projectionForDoc(doc, decryptDoc));
+        }
+        // A lock/stop between decrypt and apply drops this page (checkpoint not
+        // advanced), leaving it to a clean re-pull -- cheaper than holding the write
+        // lock across the abort check.
+        if (signal?.aborted) {
+            break;
+        }
+        await store.applyPulledPage({
+            documents,
+            checkpoint: next,
+            projections
+        });
+        applied += documents.length;
+        // Short page: the server had fewer than a full batch left, so we are caught
+        // up. A full page means there may be more -- loop with the new checkpoint.
+        if (documents.length < batchSize) {
+            break;
+        }
+    }
+    return { applied };
+}
+//# sourceMappingURL=pull.js.map

package/dist/sync/pull.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull.js","sourceRoot":"","sources":["../../src/sync/pull.ts"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAY,EACZ,UAA6C;IAE7C,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;IAC3B,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IACzB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,IAAY,CAAC,CAAA;QAClD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CACV,2CAA2C,GAAG,CAAC,EAAE,oBAAoB,EACrE,GAAG,CACJ,CAAA;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IACzB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,EAC5B,IAAI,EACJ,KAAK,EACL,SAAS,EACT,UAAU,EACV,MAAM,EAOP;IACC,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,SAAS,CAAC;QACR,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAK;QACP,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,aAAa,EAAE,CAAA;QAC9C,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC;YACvD,gDAAgD;YAChD,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;YAC/C,KAAK,EAAE,SAAS;SACjB,CAAC,CAAA;QAEF,4EAA4E;QAC5E,0EAA0E;QAC1E,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAC5C,MAAK;QACP,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,GAAG,EAA4B,CAAA;QACvD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,gBAAgB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAA;QAClE,CAAC;QAED,wEAAwE;QACxE,6EAA6E;QAC7E,+BAA+B;QAC/B,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAK;QACP,CAAC;QAED,MAAM,KAAK,CAAC,eAAe,CAAC;YAC1B,SAAS;YACT,UAAU,EAAE,IAAsB;YAClC,WAAW;SACZ,CAAC,CAAA;QACF,OAAO,IAAI,SAAS,CAAC,MAAM,CAAA;QAE3B,4EAA4E;QAC5E,2EAA2E;QAC3E,IAAI,SAAS,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;YACjC,MAAK;QACP,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAA;AACpB,CAAC"}

package/dist/sync/push.d.ts

@@ -0,0 +1,55 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The push side of the WAS replication engine core: fan each dirty local row out
+ * to a conditional WAS write, then reconcile per the content-addressed conflict
+ * table.
+ *
+ * On a content-addressed collection an id's `data` never mutates, so a live row
+ * only ever pushes as a create (`If-None-Match: *`) and a tombstone as a delete;
+ * there is no update path. A mutable (last-write-wins) collection pushes a live
+ * row as a create while never-acked (`version 0`) and as an in-place update
+ * (`If-Match`) once acked, and settles a `412` through its injected
+ * {@link ResolveConflict} policy.
+ *
+ * This loop covers the CONTENT sub-resource only (`data` / `version`, at
+ * `PUT/DELETE /:id`). It does not drive the independently-versioned METADATA
+ * sub-resource (`custom` / `metaVersion`, at `PUT /:id/meta`): a replica that
+ * syncs user-writable metadata (the web wallet's RxDB driver, via
+ * `WasSyncPort.putMeta`) keeps that half in its own push handler. It is left out
+ * of this core deliberately -- none of the wallet Space collections
+ * (`private-credentials`, `public-credentials`, `wallet-activity`, `contacts`,
+ * `contacts-history`) versions its metadata independently of its content, so
+ * folding a `putMeta` diff into this loop would add an untested code path with
+ * no collection to exercise it. The `WasSyncPort.putMeta` capability stays
+ * optional on the port for the driver that needs it.
+ */
+import { formatEtag } from '@interop/was-client/sync';
+import type { ResolveConflict, SyncStore, WasSyncPort } from './types.js';
+export { formatEtag };
+/**
+ * Pushes every dirty row for one feed, sequentially (bounds sockets/CPU, and
+ * keeps conflict reconciliation deterministic). Honors `signal` between rows.
+ * A non-conflict error from any row propagates so the engine aborts the cycle
+ * and backs off; already-pushed rows in the batch stay settled.
+ *
+ * @param options {object}
+ * @param options.port {WasSyncPort}
+ * @param options.store {SyncStore}
+ * @param [options.resolveConflict] {ResolveConflict}   mutable-collection policy
+ * @param [options.signal] {AbortSignal}
+ * @returns {Promise<{ pushed: number; conflictsResolved: number }>}   dirty rows
+ *   processed this cycle, and how many invoked the LWW resolver (a positive
+ *   count means the caller should rerun so a local-wins re-push settles)
+ */
+export declare function runPush({ port, store, resolveConflict, signal }: {
+    port: WasSyncPort;
+    store: SyncStore;
+    resolveConflict?: ResolveConflict;
+    signal?: AbortSignal;
+}): Promise<{
+    pushed: number;
+    conflictsResolved: number;
+}>;
+//# sourceMappingURL=push.d.ts.map

package/dist/sync/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../../src/sync/push.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,KAAK,EAAQ,eAAe,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAM/E,OAAO,EAAE,UAAU,EAAE,CAAA;AAoJrB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,OAAO,CAAC,EAC5B,IAAI,EACJ,KAAK,EACL,eAAe,EACf,MAAM,EACP,EAAE;IACD,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,EAAE,SAAS,CAAA;IAChB,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC,CAwBzD"}