@syncular/client 0.15.42 → 0.15.44

package/README.md

@@ -85,7 +85,14 @@ installRealtimeSupervisor(handle, {
 It owns one connection attempt, retries initial failure and later socket loss
 with bounded exponential jitter, suspends while offline/background/protected,
 runs `syncUntilIdle()` before reporting `connected`, and cancels before
-`close()`. `realtimeSupervisorSnapshot()` and
+`close()`.
+
+Multi-tab handles share ONE leader socket across every tab, so pass
+`sharedTransport: true` (the templates do): backgrounding this tab then
+leaves the shared socket alone — a sibling tab may still be visible — while
+offline and protection continue to suspend. Each client accepts exactly one
+supervisor for its lifetime; a second `installRealtimeSupervisor` call
+throws. `realtimeSupervisorSnapshot()` and
 `subscribeRealtimeSupervisor()` expose only `phase`, `attempt`, and the bounded
 library delay for UI/diagnostics—never raw transport prose or identities.
 
@@ -350,9 +357,9 @@ visible. Reusing the same id returns `alreadyApplied: true` together with the
 original `retainedCommits` and `resetSubscriptions` counts. The core stores
 that counts-only receipt atomically with the reset, so an application crash
 after the SQLite commit but before its own acknowledgement does not turn the
-retry into a misleading zero-impact result. Markers written before Syncular
-0.15.36 cannot reconstruct their historical counts and preserve the former
-zero-count replay behavior. A malformed or unreadable persisted receipt fails
+retry into a misleading zero-impact result. Markers persisted in the legacy
+format carry no counts receipt; a retry against one of them keeps returning
+the zero-count result. A malformed or unreadable persisted receipt fails
 closed with the sanitized `sync.local_corrupt` client-local code and performs
 no reset. No receipt exposes ids, rows, scopes, or clinical values.
 

package/dist/client.js

@@ -110,6 +110,16 @@ export class SyncClient {
      * (the fast-bail the delta path reads).
      */
     #syncOutstanding = false;
+    /**
+     * Bumped by every local projection reset (`rebootstrapLocalData`). A sync
+     * round captures this epoch together with its subscription state; a
+     * mismatch at SUB_END means a reset landed while the round was in flight,
+     * so the captured cursors predate the rewind and persisting them would
+     * overwrite it and silently skip the fresh bootstrap. The Rust core is
+     * synchronous over `&mut self` and gets this fencing for free; the epoch
+     * restores the equivalent semantics across the round's await points.
+     */
+    #localResetEpoch = 0;
     /** Retry policy belongs to the operation that classified the failure. */
     #retryDelayMs = 250;
     #hasBlobs;
@@ -1409,38 +1419,49 @@ export class SyncClient {
         const rejectionCount = this.#rejections.length;
         try {
             return this.#applyBatch((batch) => {
-                const initialRowIds = this.#localPurgeRowIds(purge);
                 const targetsByTable = this.#localPurgeTargetsByTable(purge);
-                const doomed = listOutbox(this.#db)
-                    .filter((commit) => {
-                    const images = new Map(listOutboxBeforeImages(this.#db, commit.clientCommitId).map((image) => [image.opIndex, image]));
-                    return commit.operations.some((operation, opIndex) => {
-                        const targets = targetsByTable.get(operation.table);
-                        if (targets === undefined)
-                            return false;
-                        if (initialRowIds.get(operation.table)?.has(operation.rowId) ===
-                            true) {
-                            return true;
-                        }
-                        if (operation.values !== undefined &&
-                            targets.some((target) => localDataPurgeTargetMatches(target, operation.values ?? {}))) {
-                            return true;
-                        }
-                        const beforeValues = images.get(opIndex)?.values;
-                        return (beforeValues !== undefined &&
-                            targets.some((target) => localDataPurgeTargetMatches(target, beforeValues)));
-                    });
-                })
-                    // Reverse order is essential: each rollback restores its before-image;
-                    // removing newest-first prevents an older doomed write reappearing.
-                    .sort((a, b) => b.seq - a.seq);
-                for (const commit of doomed) {
-                    this.#rollbackFailedCommit(commit, batch);
+                // Doomed detection runs to fixpoint, matching the Rust core's rule:
+                // a commit is doomed when any of its ops touches a base-matching
+                // row. Base values only become visible here as rollbacks restore
+                // before-images and rebase later commits' images onto them (a
+                // stacked edit over a moved row initially shows the moved values),
+                // so each pass rolls back what it caught — newest-first, so an
+                // older doomed write never reappears — and re-scans until the
+                // outbox is stable.
+                const doomed = [];
+                let rowIds = this.#localPurgeRowIds(purge);
+                for (;;) {
+                    const caught = listOutbox(this.#db)
+                        .filter((commit) => {
+                        const images = new Map(listOutboxBeforeImages(this.#db, commit.clientCommitId).map((image) => [image.opIndex, image]));
+                        return commit.operations.some((operation, opIndex) => {
+                            const targets = targetsByTable.get(operation.table);
+                            if (targets === undefined)
+                                return false;
+                            if (rowIds.get(operation.table)?.has(operation.rowId) === true) {
+                                return true;
+                            }
+                            if (operation.values !== undefined &&
+                                targets.some((target) => localDataPurgeTargetMatches(target, operation.values ?? {}))) {
+                                return true;
+                            }
+                            const beforeValues = images.get(opIndex)?.values;
+                            return (beforeValues !== undefined &&
+                                targets.some((target) => localDataPurgeTargetMatches(target, beforeValues)));
+                        });
+                    })
+                        .sort((a, b) => b.seq - a.seq);
+                    if (caught.length === 0)
+                        break;
+                    for (const commit of caught) {
+                        this.#rollbackFailedCommit(commit, batch);
+                    }
+                    doomed.push(...caught);
+                    // Rollback may reveal a target row hidden by an optimistic delete
+                    // or move; the re-selected set drives both the next scan and the
+                    // final row deletion below.
+                    rowIds = this.#localPurgeRowIds(purge);
                 }
-                // Rollback may reveal a target row hidden by an optimistic delete or
-                // move, so select the final base/visible set only after doomed commits
-                // have been removed.
-                const rowIds = this.#localPurgeRowIds(purge);
                 let purgedRows = 0;
                 for (const [tableName, ids] of rowIds) {
                     if (ids.size === 0)
@@ -1551,6 +1572,9 @@ export class SyncClient {
             this.#needsPull = priorNeedsPull;
             throw error;
         }
+        // Fence any in-flight sync round: its captured subscription state now
+        // predates the rewind, so its SUB_END cursors must stay unpersisted.
+        this.#localResetEpoch += 1;
         if (!priorUpgrading)
             this.#config.onUpgrading?.(true);
         this.#config.onSyncNeeded?.('startup');
@@ -1785,6 +1809,9 @@ export class SyncClient {
             // the queue. `pushFrames` and `outbox` stay index-aligned for result
             // mapping.
             const { pushFrames, outbox, deferred } = await this.#encodeOutboxForPush();
+            // Captured together with the subscription state below: the response
+            // apply persists SUB_END cursors only while this epoch is current.
+            const resetEpoch = this.#localResetEpoch;
             const subs = loadSubscriptions(this.#db).filter((sub) => sub.status === 'active');
             const limits = this.#config.limits;
             const frames = [
@@ -1823,7 +1850,7 @@ export class SyncClient {
             if (message.msgKind !== 'response') {
                 throw new ClientSyncError('sync.invalid_request', 'transport returned a non-response message');
             }
-            const summary = await this.#processResponse(message, outbox, subs, 'pull');
+            const summary = await this.#processResponse(message, outbox, subs, 'pull', resetEpoch);
             // §4.8 E1: the push half may have drained commits that pinned rows of
             // a shrunk window unit — retry any deferred evictions now.
             this.#drainPendingEvictions();
@@ -2148,7 +2175,7 @@ export class SyncClient {
         this.#sendAck(Math.min(...cursors));
     }
     // -- response processing ------------------------------------------------------
-    async #processResponse(message, sentCommits, sentSubs, mode) {
+    async #processResponse(message, sentCommits, sentSubs, mode, resetEpoch = this.#localResetEpoch) {
         const summary = emptySummary(sentCommits.length);
         const commitsById = new Map(sentCommits.map((commit) => [commit.clientCommitId, commit]));
         const subsById = new Map((sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]));
@@ -2320,7 +2347,12 @@ export class SyncClient {
                     case 'SUB_END': {
                         if (section !== undefined &&
                             !section.skip &&
-                            section.sub !== undefined) {
+                            section.sub !== undefined &&
+                            // Reset fence: a rebootstrap that landed mid-round already
+                            // rewound this subscription's cursor; the captured SUB_END
+                            // state predates the rewind and must stay unpersisted so the
+                            // next round runs the fresh bootstrap.
+                            this.#localResetEpoch === resetEpoch) {
                             const applied = this.#finishSection(section.sub, section.start, frame.nextCursor, frame.bootstrapState, summary);
                             if (mode === 'delta' && applied) {
                                 deltaCursor = Math.max(deltaCursor, frame.nextCursor);
@@ -2367,7 +2399,12 @@ export class SyncClient {
             .map((sub) => sub.id);
         // §7.4.5: the reset is over once the first post-reset pull round leaves
         // no subscription mid-bootstrap — the tables are rebuilt and current.
-        if (this.#upgrading && mode === 'pull' && bootstrapping.length === 0) {
+        // The epoch check keeps a round that predates a mid-flight rebootstrap
+        // from declaring that reset finished before its bootstrap ran.
+        if (this.#upgrading &&
+            mode === 'pull' &&
+            bootstrapping.length === 0 &&
+            this.#localResetEpoch === resetEpoch) {
             this.#setUpgrading(false);
         }
         return { ...summary, bootstrapping };
@@ -2376,6 +2413,13 @@ export class SyncClient {
         const commit = commitsById.get(frame.clientCommitId);
         if (commit === undefined)
             return false;
+        // `commitsById` is the round's send-time snapshot. The commit can leave
+        // the outbox before this frame is handled — a local purge doomed it while
+        // the round was in flight, or an earlier duplicate frame in this response
+        // already drained it. Its recorded outcome stands, and skipping keeps the
+        // cached outbox count exact (a drain may only be counted once).
+        if (!this.#outboxCommitExists(frame.clientCommitId))
+            return false;
         if (frame.status === 'applied' || frame.status === 'cached') {
             // §6.3: applied and cached both drain the outbox — cached means
             // "already applied, you may have missed the ack".
@@ -2470,6 +2514,9 @@ export class SyncClient {
         summary.rejected.push(frame.clientCommitId);
         return true;
     }
+    #outboxCommitExists(clientCommitId) {
+        return (this.#db.query('SELECT 1 FROM _syncular_outbox WHERE client_commit_id = ? LIMIT 1', [clientCommitId]).length > 0);
+    }
     #decodeServerRow(tableName, payload) {
         if (tableName === undefined)
             return {};

package/dist/encryption.d.ts

@@ -43,7 +43,12 @@ export interface EncryptionKeyringConfig {
     readonly keys: Readonly<Record<string, Uint8Array>>;
     readonly keyIdColumns?: Readonly<Record<string, string>>;
 }
-/** Convert a portable keyring into the direct-client encryption contract. */
+/**
+ * Convert a portable keyring into the direct-client encryption contract.
+ * Key lengths are validated here, at install time: every side of the wire
+ * enforces {@link KEY_LENGTH}-byte keys, so a wrong-length key fails loud
+ * with a clear config error before any sync round runs.
+ */
 export declare function encryptionConfigFromKeyring(keyring: EncryptionKeyringConfig): EncryptionConfig;
 /**
  * Encrypt the encrypted columns of a positional row value array in place-safe

package/dist/encryption.js

@@ -8,11 +8,25 @@
  * bridge between the positional `RowValue[]` and the `@syncular/core` §5.11
  * envelope primitives.
  */
-import { DecryptError, decryptValue, encryptValue, } from '@syncular/core';
-/** Convert a portable keyring into the direct-client encryption contract. */
+import { DecryptError, decryptValue, encryptValue, KEY_LENGTH, } from '@syncular/core';
+import { ClientSyncError } from './errors.js';
+/**
+ * Convert a portable keyring into the direct-client encryption contract.
+ * Key lengths are validated here, at install time: every side of the wire
+ * enforces {@link KEY_LENGTH}-byte keys, so a wrong-length key fails loud
+ * with a clear config error before any sync round runs.
+ */
 export function encryptionConfigFromKeyring(keyring) {
+    for (const [keyId, key] of Object.entries(keyring.keys)) {
+        if (key.length !== KEY_LENGTH) {
+            throw new ClientSyncError('sync.invalid_request', `encryption key ${JSON.stringify(keyId)} must be ${KEY_LENGTH} bytes (AES-256), got ${key.length}`);
+        }
+    }
     return {
-        keyProvider: (keyId) => keyring.keys[keyId],
+        // Own-property lookup only: the keyId arrives from the wire envelope, so
+        // a prototype-chain name like "constructor" must read as a missing key
+        // and take the clean DecryptError path.
+        keyProvider: (keyId) => Object.hasOwn(keyring.keys, keyId) ? keyring.keys[keyId] : undefined,
         ...(keyring.keyIdColumns !== undefined
             ? { keyIdColumns: keyring.keyIdColumns }
             : {}),

package/dist/reactive-store.js

@@ -691,8 +691,15 @@ export class ReactiveClientStore {
             // Releasing a window is best-effort teardown. A resource owner may have
             // already closed the underlying worker/native handle before React effect
             // cleanup runs (notably during schema-changing HMR). Do not let that
-            // harmless ordering race escape as an unhandled rejection.
-            void Promise.resolve(this.client.setWindow(group.base, [])).catch(() => undefined);
+            // harmless ordering race escape as an unhandled rejection — and the
+            // interface permits a plain void return, so a closed handle may also
+            // throw synchronously; swallow that the same way.
+            try {
+                void Promise.resolve(this.client.setWindow(group.base, [])).catch(() => undefined);
+            }
+            catch {
+                // Same teardown race, surfaced synchronously.
+            }
         }
         this.#windowClaims.clear();
     }

package/dist/realtime-supervisor.d.ts

@@ -28,8 +28,18 @@ export interface RealtimeSupervisorSnapshot {
 export interface RealtimeSupervisorOptions {
     /** Host online/offline evidence. Unknown remains connectable and observable. */
     readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
-    /** Browser/native foreground evidence. Background always suspends the socket. */
+    /** Browser/native foreground evidence. Background suspends a tab-owned
+     * socket; with `sharedTransport` it only serves as a resume nudge. */
     readonly lifecycle?: RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
+    /**
+     * The client's realtime transport is shared with sibling tabs or webviews
+     * (multi-tab handles proxying to one leader socket, native cores behind
+     * several views). Backgrounding THIS view then keeps the socket open,
+     * because a sibling may still be visible and a follower's disconnect would
+     * tear down realtime for everyone. Offline and protection evidence still
+     * suspend.
+     */
+    readonly sharedTransport?: boolean;
     /** Publish preflight before draining keys so reconnect stops in the same turn. */
     readonly protection?: RealtimeSupervisorSignal<RealtimeSupervisorProtectionState>;
     /** Deterministic test/host timer seam. */
@@ -72,7 +82,12 @@ export declare class RealtimeSupervisor {
     start(): void;
     stop(): void;
 }
-/** Install one supervisor and make client disposal cancel it before close. */
+/**
+ * Install one supervisor and make client disposal cancel it before close.
+ * A client accepts exactly one supervisor for its lifetime; installing a
+ * second throws, because silently keeping the first would discard the second
+ * call's options.
+ */
 export declare function installRealtimeSupervisor<T extends RealtimeSupervisorClient>(client: T, options?: RealtimeSupervisorOptions): T;
 export declare function realtimeSupervisorSnapshot(client: object): RealtimeSupervisorSnapshot;
 export declare function subscribeRealtimeSupervisor(client: object, listener: () => void): () => void;

package/dist/realtime-supervisor.js

@@ -117,6 +117,7 @@ export class RealtimeSupervisor {
     #connectivity;
     #lifecycle;
     #protection;
+    #sharedTransport;
     #scheduleTimer;
     #random;
     #initialDelayMs;
@@ -144,6 +145,7 @@ export class RealtimeSupervisor {
         this.#connectivity = options.connectivity;
         this.#lifecycle = options.lifecycle;
         this.#protection = options.protection;
+        this.#sharedTransport = options.sharedTransport === true;
         this.#scheduleTimer = options.schedule ?? scheduleTimer;
         this.#random = options.random ?? Math.random;
         this.#initialDelayMs = boundedDelay(options.initialDelayMs, DEFAULT_INITIAL_DELAY_MS);
@@ -184,6 +186,7 @@ export class RealtimeSupervisor {
         this.#unsubscribeLifecycle?.();
         this.#unsubscribeProtection?.();
         this.#publish({ phase: 'stopped', attempt: 0 });
+        this.#listeners.clear();
         if (disconnect)
             this.#disconnect();
     }
@@ -214,8 +217,9 @@ export class RealtimeSupervisor {
             this.#connectivity?.current() === 'offline') {
             return 'offline';
         }
-        if (this.#lifecycle?.current() === 'background')
+        if (!this.#sharedTransport && this.#lifecycle?.current() === 'background') {
             return 'background';
+        }
         return undefined;
     }
     #canConnect() {
@@ -273,43 +277,77 @@ export class RealtimeSupervisor {
             this.#reconcileHostState();
             return;
         }
+        // Count an attempt only when this call actually schedules one. Repeated
+        // 'disconnected' diagnostics beside a pending retry keep the backoff and
+        // the worker-mode reconnect nudge intact.
+        if (this.#connected ||
+            this.#connecting ||
+            this.#cancelRetry !== undefined) {
+            return;
+        }
         const delay = this.#retryDelay();
         this.#attempt = Math.min(32, this.#attempt + 1);
         this.#schedule(delay);
     }
+    /**
+     * A superseded attempt observed a generation bump mid-flight. Whenever a
+     * newer generation is mid-connect or holds the transport, that generation
+     * owns the shared socket and the stale attempt leaves every field alone.
+     * With the supervisor otherwise quiescent (suspended or stopped), the
+     * socket this attempt opened is unwanted — release it.
+     */
+    #releaseSupersededSocket() {
+        if (this.#connecting || this.#connected || this.#transportConnected) {
+            return;
+        }
+        this.#disconnect();
+    }
     async #connect() {
         if (!this.#canConnect() || this.#connected || this.#connecting)
             return;
+        const generation = this.#generation;
         this.#connecting = true;
         this.#publish({ phase: 'connecting', attempt: this.#attempt });
-        const generation = this.#generation;
         let failed = false;
         try {
             await this.#client.connectRealtime();
+            if (generation !== this.#generation) {
+                this.#releaseSupersededSocket();
+                return;
+            }
             this.#transportConnected = true;
-            if (generation !== this.#generation || !this.#canConnect()) {
+            if (!this.#canConnect()) {
+                this.#transportConnected = false;
                 this.#disconnect();
                 return;
             }
             await this.#catchUpConnectedTransport(generation);
         }
         catch {
+            if (generation !== this.#generation) {
+                this.#releaseSupersededSocket();
+                return;
+            }
             failed = true;
             this.#connected = false;
             this.#transportConnected = false;
             this.#disconnect();
         }
         finally {
-            this.#connecting = false;
+            // A superseded attempt leaves the successor's in-flight state alone.
+            if (generation === this.#generation)
+                this.#connecting = false;
         }
         if (failed && generation === this.#generation)
             this.#scheduleRetry();
     }
     async #catchUpConnectedTransport(generation) {
         await this.#client.syncUntilIdle();
-        if (generation !== this.#generation ||
-            !this.#canConnect() ||
-            !this.#transportConnected) {
+        if (generation !== this.#generation) {
+            this.#releaseSupersededSocket();
+            return;
+        }
+        if (!this.#canConnect() || !this.#transportConnected) {
             this.#disconnect();
             return;
         }
@@ -321,22 +359,28 @@ export class RealtimeSupervisor {
         if (!this.#canConnect() || this.#connecting || !this.#transportConnected) {
             return;
         }
+        const generation = this.#generation;
         this.#connecting = true;
         this.#clearRetry();
         this.#publish({ phase: 'connecting', attempt: this.#attempt });
-        const generation = this.#generation;
         let failed = false;
         try {
             await this.#catchUpConnectedTransport(generation);
         }
         catch {
+            if (generation !== this.#generation) {
+                this.#releaseSupersededSocket();
+                return;
+            }
             failed = true;
             this.#connected = false;
             this.#transportConnected = false;
             this.#disconnect();
         }
         finally {
-            this.#connecting = false;
+            // A superseded adoption leaves the successor's in-flight state alone.
+            if (generation === this.#generation)
+                this.#connecting = false;
         }
         if (failed && generation === this.#generation)
             this.#scheduleRetry();
@@ -359,9 +403,14 @@ export class RealtimeSupervisor {
                 this.#disconnect();
             return;
         }
-        if (!this.#realtimeSupported)
-            return;
-        this.#realtimeSupported = true;
+        if (!this.#realtimeSupported) {
+            // A live socket is positive evidence the earlier 'unsupported' report
+            // was transient (a mid-restart or mis-detected capability probe), so it
+            // recovers the supervisor. Every other report keeps the latch closed.
+            if (snapshot.host.realtime !== 'connected')
+                return;
+            this.#realtimeSupported = true;
+        }
         const block = this.#hostBlock();
         if (block) {
             this.#suspend(block);
@@ -369,9 +418,11 @@ export class RealtimeSupervisor {
         }
         if (snapshot.host.realtime === 'connected') {
             this.#transportConnected = true;
-            if (this.#connecting)
+            // Steady state: diagnostics re-announce 'connected' on every sync
+            // round and subscription change. An already-adopted transport keeps
+            // its phase and skips the redundant catch-up.
+            if (this.#connecting || this.#connected)
                 return;
-            this.#connected = false;
             void this.#adoptConnectedTransport();
             return;
         }
@@ -428,10 +479,17 @@ export class RealtimeSupervisor {
         void Promise.resolve(this.#client.disconnectRealtime()).catch(() => undefined);
     }
 }
-/** Install one supervisor and make client disposal cancel it before close. */
+/**
+ * Install one supervisor and make client disposal cancel it before close.
+ * A client accepts exactly one supervisor for its lifetime; installing a
+ * second throws, because silently keeping the first would discard the second
+ * call's options.
+ */
 export function installRealtimeSupervisor(client, options) {
-    if (attachment(client))
-        return client;
+    if (attachment(client)) {
+        throw new Error('installRealtimeSupervisor: this client already has a supervisor; ' +
+            'install one supervisor per client lifetime');
+    }
     const supervisor = new RealtimeSupervisor(client, options);
     Object.defineProperty(client, REALTIME_SUPERVISOR_KEY, {
         configurable: false,

package/dist/schema.js

@@ -213,6 +213,22 @@ function createSyncedTable(db, table) {
     }
 }
 const FTS_SOURCE_ID_COLUMN = '_syncular_source_id';
+/**
+ * Create (or migrate) one contentful FTS5 projection for a table plus its
+ * synchronizing triggers. Every open drops and recreates the full trigger set
+ * (`_bi`, `_ai`, `_ad`, `_au`, and, when the table has a unique index, `_bu`),
+ * so existing databases pick up newly added guards. The BEFORE INSERT (`_bi`)
+ * and BEFORE UPDATE (`_bu`) guards remove projection rows for entries displaced
+ * by `INSERT OR REPLACE` / `UPDATE OR REPLACE` through the primary key or a
+ * secondary unique index — cases where SQLite does not reliably fire the AFTER
+ * DELETE trigger for the displaced row.
+ *
+ * Limitation: because a BEFORE trigger runs before SQLite resolves the
+ * conflict, an `OR IGNORE` write whose row is dropped still executes these
+ * displacement DELETEs, transiently removing the surviving row's projection
+ * entry. Syncular's mirror writes never use `OR IGNORE`; see the guard-block
+ * comment below for the full rationale.
+ */
 function createFtsProjection(db, table, index) {
     const existed = db.query("SELECT 1 AS present FROM sqlite_master WHERE type='table' AND name=?", [index.name]).length > 0;
     const indexedColumns = index.columns.map(quoteIdent);
@@ -230,18 +246,68 @@ function createFtsProjection(db, table, index) {
         ...index.columns.map((column) => `new.${quoteIdent(column)}`),
     ].join(', ');
     const deleteFor = (value) => `DELETE FROM ${quoteIdent(index.name)} WHERE ${quoteIdent(FTS_SOURCE_ID_COLUMN)} = ${value}`;
+    const deleteDisplaced = (select) => `DELETE FROM ${quoteIdent(index.name)} WHERE ${quoteIdent(FTS_SOURCE_ID_COLUMN)} IN (${select})`;
     // A clean insert cannot already have a projection row because the source
     // primary key is unique. Keep clean inserts linear by moving replacement
-    // cleanup behind an indexed source-table existence check. SQLite does not
-    // reliably invoke DELETE triggers for the row displaced by REPLACE.
-    for (const suffix of ['bi', 'ai', 'ad', 'au']) {
+    // cleanup behind indexed source-table existence checks. SQLite does not
+    // reliably invoke DELETE triggers for rows displaced by REPLACE, and a
+    // REPLACE can displace rows through TWO paths: the primary key AND any
+    // secondary UNIQUE index (a different-PK row whose unique key matches the
+    // incoming row). The BEFORE INSERT guard covers both for `INSERT OR REPLACE`;
+    // the mirroring BEFORE UPDATE guard covers `UPDATE OR REPLACE` that pushes a
+    // different-PK row out through a unique index (the AFTER UPDATE trigger only
+    // knows the updated row's own old/new ids, so it would leave that displaced
+    // row's projection entry behind as a ghost hit). Primary-key displacement by
+    // `UPDATE OR REPLACE` needs no BEFORE guard: the new pk equals the displaced
+    // row's pk, so the AFTER UPDATE delete of the new source id already clears it.
+    //
+    // Known limitation — `OR IGNORE`: a BEFORE trigger fires before SQLite
+    // resolves the conflict, and SQLite exposes no signal for the eventual
+    // resolution. So an `INSERT OR IGNORE` / `UPDATE OR IGNORE` whose row is
+    // dropped on conflict still runs these displacement DELETEs, removing the
+    // SURVIVING row's projection entry (a false negative until that row is next
+    // rewritten). Moving cleanup to AFTER triggers would dodge the no-op but
+    // reintroduce the REPLACE-doesn't-fire-DELETE gap and a full-projection scan
+    // per write, so the guards stay BEFORE. Syncular's own mirror writes use
+    // `INSERT … ON CONFLICT (pk) DO UPDATE` (apply.ts), which never takes the
+    // IGNORE path; only hand-written `OR IGNORE` against a mirror table is exposed.
+    for (const suffix of ['bi', 'ai', 'ad', 'au', 'bu']) {
         db.exec(`DROP TRIGGER IF EXISTS ${quoteIdent(`${index.name}_${suffix}`)}`);
     }
     const replacementExists = `EXISTS (SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = new.${quoteIdent(table.primaryKey)})`;
-    db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_bi`)} BEFORE INSERT ON ${quoteIdent(table.name)} WHEN ${replacementExists} BEGIN ${deleteFor(newSourceId)}; END`);
+    // Per secondary UNIQUE index: the different-PK rows about to be displaced
+    // via that unique key. `=` makes NULL unique values match nothing, which is
+    // exactly SQLite's unique-index semantics (NULLs never conflict).
+    const uniqueIndexes = table.indexes.filter((spec) => spec.unique);
+    const displacedByUnique = uniqueIndexes.map((spec) => {
+        const match = spec.columns
+            .map((column) => `${quoteIdent(column)} = new.${quoteIdent(column)}`)
+            .join(' AND ');
+        return `SELECT ${sourceId} FROM ${quoteIdent(table.name)} WHERE ${match} AND ${quoteIdent(table.primaryKey)} != new.${quoteIdent(table.primaryKey)}`;
+    });
+    const insertGuardCondition = [
+        replacementExists,
+        ...displacedByUnique.map((select) => `EXISTS (${select})`),
+    ].join(' OR ');
+    const insertGuardBody = [
+        deleteFor(newSourceId),
+        ...displacedByUnique.map(deleteDisplaced),
+    ].join('; ');
+    db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_bi`)} BEFORE INSERT ON ${quoteIdent(table.name)} WHEN ${insertGuardCondition} BEGIN ${insertGuardBody}; END`);
     db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_ai`)} AFTER INSERT ON ${quoteIdent(table.name)} BEGIN INSERT INTO ${quoteIdent(index.name)} (${projectionColumns}) VALUES (${newValues}); END`);
     db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_ad`)} AFTER DELETE ON ${quoteIdent(table.name)} BEGIN ${deleteFor(oldSourceId)}; END`);
     db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_au`)} AFTER UPDATE ON ${quoteIdent(table.name)} BEGIN ${deleteFor(oldSourceId)}; ${deleteFor(newSourceId)}; INSERT INTO ${quoteIdent(index.name)} (${projectionColumns}) VALUES (${newValues}); END`);
+    // BEFORE UPDATE guard for `UPDATE OR REPLACE`: clear the projection of any
+    // different-PK row about to be displaced through a secondary unique index by
+    // the new values. Only meaningful when the table has a unique index; with
+    // none, no update can displace a foreign row, so the trigger is omitted.
+    if (displacedByUnique.length > 0) {
+        const updateGuardCondition = displacedByUnique
+            .map((select) => `EXISTS (${select})`)
+            .join(' OR ');
+        const updateGuardBody = displacedByUnique.map(deleteDisplaced).join('; ');
+        db.exec(`CREATE TRIGGER ${quoteIdent(`${index.name}_bu`)} BEFORE UPDATE ON ${quoteIdent(table.name)} WHEN ${updateGuardCondition} BEGIN ${updateGuardBody}; END`);
+    }
     if (!existed) {
         db.exec(`INSERT INTO ${quoteIdent(index.name)} (${projectionColumns}) SELECT ${sourceId}, ${indexedColumns.join(', ')} FROM ${quoteIdent(table.name)}`);
     }

package/dist/worker-entry.js

@@ -391,9 +391,21 @@ export function startSyncWorker(overrides = {}) {
             database = undefined;
         },
     };
+    // Local purge/rebootstrap rewrite the same durable state an in-flight
+    // sync round captured at send time; running their RPCs on the sync chain
+    // orders them against RPC- and auto-driven rounds (the client core's
+    // reset fence covers hosts that call the core directly).
+    const syncChainMethods = new Set([
+        'purgeLocalData',
+        'rebootstrapLocalData',
+    ]);
     async function dispatch(message) {
         const method = api[message.method];
-        return await method.apply(api, message.args);
+        const invoke = () => method.apply(api, message.args);
+        if (syncChainMethods.has(message.method)) {
+            return await serializedSync(async () => invoke());
+        }
+        return await invoke();
     }
     function run(id, fn, transfer) {
         void (async () => {