@syncular/client 0.15.40 → 0.15.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.40",
+  "version": "0.15.43",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,7 +89,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.40"
+    "@syncular/core": "0.15.43"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -100,7 +100,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.40",
+    "@syncular/server": "0.15.43",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -558,6 +558,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;
   readonly #hasBlobs: boolean;
@@ -2124,53 +2134,62 @@ 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),
-                )
+        // 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: OutboxCommit[] = [];
+        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],
+                ),
               );
-            });
-          })
-          // 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);
+              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) continue;
@@ -2296,6 +2315,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');
@@ -2575,6 +2597,9 @@ export class SyncClient {
       // 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',
       );
@@ -2625,6 +2650,7 @@ export class SyncClient {
         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.
@@ -2998,6 +3024,7 @@ export class SyncClient {
     sentCommits: readonly OutboxCommit[],
     sentSubs: readonly SubscriptionRecord[] | undefined,
     mode: 'pull' | 'delta',
+    resetEpoch: number = this.#localResetEpoch,
   ): Promise<SyncSummary> {
     const summary = emptySummary(sentCommits.length);
     const commitsById = new Map(
@@ -3258,7 +3285,12 @@ export class SyncClient {
             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,
@@ -3315,7 +3347,14 @@ 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 };
@@ -3331,6 +3370,12 @@ export class SyncClient {
   ): boolean {
     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".
@@ -3427,6 +3472,15 @@ export class SyncClient {
     return true;
   }
 
+  #outboxCommitExists(clientCommitId: string): boolean {
+    return (
+      this.#db.query(
+        'SELECT 1 FROM _syncular_outbox WHERE client_commit_id = ? LIMIT 1',
+        [clientCommitId],
+      ).length > 0
+    );
+  }
+
   #decodeServerRow(
     tableName: string | undefined,
     payload: Uint8Array,

package/src/encryption.ts

@@ -13,11 +13,13 @@ import {
   DecryptError,
   decryptValue,
   encryptValue,
+  KEY_LENGTH,
   type NonceSource,
   type PlainValue,
   type RowColumn,
   type RowValue,
 } from '@syncular/core';
+import { ClientSyncError } from './errors';
 import type { CompiledClientTable } from './schema';
 
 /**
@@ -59,12 +61,29 @@ export interface EncryptionKeyringConfig {
   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 function encryptionConfigFromKeyring(
   keyring: EncryptionKeyringConfig,
 ): EncryptionConfig {
+  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/src/reactive-store.ts

@@ -850,10 +850,16 @@ 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/src/realtime-supervisor.ts

@@ -53,8 +53,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. */
@@ -215,6 +225,7 @@ export class RealtimeSupervisor {
   readonly #connectivity?: RealtimeSupervisorOptions['connectivity'];
   readonly #lifecycle?: RealtimeSupervisorOptions['lifecycle'];
   readonly #protection?: RealtimeSupervisorOptions['protection'];
+  readonly #sharedTransport: boolean;
   readonly #scheduleTimer: NonNullable<RealtimeSupervisorOptions['schedule']>;
   readonly #random: () => number;
   readonly #initialDelayMs: number;
@@ -247,6 +258,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(
@@ -304,6 +316,7 @@ export class RealtimeSupervisor {
     this.#unsubscribeLifecycle?.();
     this.#unsubscribeProtection?.();
     this.#publish({ phase: 'stopped', attempt: 0 });
+    this.#listeners.clear();
     if (disconnect) this.#disconnect();
   }
 
@@ -336,7 +349,9 @@ export class RealtimeSupervisor {
     ) {
       return 'offline';
     }
-    if (this.#lifecycle?.current() === 'background') return 'background';
+    if (!this.#sharedTransport && this.#lifecycle?.current() === 'background') {
+      return 'background';
+    }
     return undefined;
   }
 
@@ -410,43 +425,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(): void {
+    if (this.#connecting || this.#connected || this.#transportConnected) {
+      return;
+    }
+    this.#disconnect();
+  }
+
   async #connect(): Promise<void> {
     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: number): Promise<void> {
     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;
     }
@@ -459,20 +508,25 @@ 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();
   }
@@ -497,8 +551,13 @@ export class RealtimeSupervisor {
       if (disconnect) 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);
@@ -506,8 +565,10 @@ export class RealtimeSupervisor {
     }
     if (snapshot.host.realtime === 'connected') {
       this.#transportConnected = true;
-      if (this.#connecting) return;
-      this.#connected = false;
+      // 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;
       void this.#adoptConnectedTransport();
       return;
     }
@@ -566,12 +627,22 @@ export class RealtimeSupervisor {
   }
 }
 
-/** 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<T extends RealtimeSupervisorClient>(
   client: T,
   options?: RealtimeSupervisorOptions,
 ): T {
-  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/src/schema.ts

@@ -342,6 +342,22 @@ function createSyncedTable(
 
 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: ClientDatabase,
   table: CompiledClientTable,
@@ -371,18 +387,58 @@ function createFtsProjection(
   ].join(', ');
   const deleteFor = (value: string) =>
     `DELETE FROM ${quoteIdent(index.name)} WHERE ${quoteIdent(FTS_SOURCE_ID_COLUMN)} = ${value}`;
+  const deleteDisplaced = (select: string) =>
+    `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)})`;
+  // 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 ${replacementExists} BEGIN ${deleteFor(newSourceId)}; END`,
+    `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`,
@@ -393,6 +449,19 @@ function createFtsProjection(
   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(

package/src/worker-entry.ts

@@ -42,6 +42,7 @@ import {
   type WorkerErrorShape,
   type WorkerInitConfig,
   type WorkerInitResult,
+  type WorkerMethod,
   type WorkerToMainMessage,
 } from './worker-protocol';
 
@@ -491,9 +492,22 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     },
   };
 
+  // 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: ReadonlySet<WorkerMethod> = new Set<WorkerMethod>([
+    'purgeLocalData',
+    'rebootstrapLocalData',
+  ]);
+
   async function dispatch(message: WorkerCallMessage): Promise<unknown> {
     const method = api[message.method] as (...args: unknown[]) => unknown;
-    return await method.apply(api, message.args as unknown[]);
+    const invoke = () => method.apply(api, message.args as unknown[]);
+    if (syncChainMethods.has(message.method)) {
+      return await serializedSync(async () => invoke());
+    }
+    return await invoke();
   }
 
   function run(