@syncular/client 0.15.42 → 0.15.44

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(

package/src/worker-host.ts

@@ -334,6 +334,17 @@ export class SyncClientHandle {
     });
   }
 
+  /**
+   * @internal — whether `close()` has run.
+   *
+   * A follower keeps a blocking `acquire` outstanding for the whole time it is a
+   * follower, so its promotion can fire long after the application has discarded
+   * the handle. The promotion path consults this before opening anything.
+   */
+  get __isClosed(): boolean {
+    return this.#closed;
+  }
+
   /** @internal — swap this handle from follower to leader (promotion). */
   __becomeLeader(core: LeaderCore): void {
     this.#follower?.close();
@@ -1020,6 +1031,14 @@ async function bootFollower(
       await lease.release();
       return;
     }
+    if (handle.__isClosed) {
+      // The application discarded this handle while it was queued for
+      // leadership. Promoting now would open a database nobody is holding and
+      // then keep the lock forever, so no other tab could ever take over.
+      // Release instead, and let the next waiter have it.
+      await lease.release();
+      return;
+    }
     // The follower saw the departing leader's epoch; the new leader must
     // strictly exceed it so stale replies/events are discarded everywhere.
     const nextEpoch = follower.maxEpochSeen + 1;
@@ -1058,6 +1077,13 @@ async function bootFollower(
             }
           : {}),
       });
+      if (handle.__isClosed) {
+        // Closed while the worker was starting. `close()` already ran and found
+        // no core to shut down, so this one would leak: tear it down here rather
+        // than hand it to a discarded handle. `close(true)` releases the lease.
+        await core.close(true);
+        return;
+      }
       handle.__becomeLeader(core);
     } catch {
       // Promotion failed to spawn a worker — release so the next tab tries.