@catalyst-cloud/replicate 0.1.48 → 0.1.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/replicate",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "type": "module",
   "description": "Runtime-agnostic replica write path — applyDelta / truncateReplica / cursor over a portable ReplicaWriteDb (ADR-0002). Shared by the host-sync bun:sqlite replica and the browser OPFS replica so the two apply paths can't drift.",
   "license": "MIT",
@@ -25,11 +25,11 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@catalyst-cloud/schema": "0.1.54"
+    "@catalyst-cloud/schema": "0.1.55"
   },
   "devDependencies": {
     "@catalyst-cloud/typescript-config": "workspace:*",
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.5.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
   }

package/src/replicate.ts

@@ -79,6 +79,16 @@ function quoteIdent(ident: string): string {
   return `"${ident.replace(/"/g, '""')}"`;
 }
 
+/**
+ * Columns the REPLICA stamps itself rather than copying from the wire — the same self-stamped rule the
+ * mirror's upsert guard documents (apps/mirror/src/do/upsert.ts, CTC-279). `synced_at` is written by
+ * the replica's own apply loop, never by the mirror, so it carries no information about whether the
+ * SOURCE row changed: including it in the equal-timestamp content diff below would make the diff
+ * vacuously true for every delivery and turn every duplicate into a write (and a `changes > 0` report)
+ * — defeating the guard the diff exists to narrow. Excluded from the COMPARISON, not from the write.
+ */
+const SELF_STAMPED_COLUMNS = new Set(["synced_at"]);
+
 function metaFor(entity: string): TableMeta | undefined {
   return (MIRROR_TABLE_META as Record<string, TableMeta>)[entity];
 }
@@ -176,10 +186,46 @@ function applyUpsert<B>(
     const setClause = nonPkCols
       .map((c) => `${quoteIdent(c)} = excluded.${quoteIdent(c)}`)
       .join(", ");
-    // Last-write-wins by updated_at — mirrors the DO's guard so out-of-order deltas can't regress.
-    const guard = hasUpdatedAt
-      ? ` WHERE excluded.updated_at > ${quoteIdent(table)}.updated_at`
-      : "";
+    // Last-write-wins by updated_at — mirrors the DO's guard (apps/mirror/src/do/upsert.ts) so
+    // out-of-order deltas can't regress.
+    //
+    // CTC-1885 — the guard now carries the mirror's EQUAL-TIMESTAMP content-diff arm, ported from that
+    // file's CTC-673 rule, because a delta's `updated_at` is the PROVIDER's event time and does not
+    // necessarily advance when the row changes. The exact case: CTC-1885's rename cascade re-stamps
+    // `issues.state` / `team_workflow_mapping.linear_state_name` while DELIBERATELY preserving the
+    // source `updated_at` (advancing it would corrupt freshness, board ranking, and last-write-wins
+    // ordering). Under the old strict `>` alone, that correction was dropped here forever — the stored
+    // row's own updated_at never moves either, so no later delta could ever repair it. Parity with the
+    // mirror writer means a correction the mirror accepted lands on the replica too.
+    let guard = "";
+    if (hasUpdatedAt) {
+      // (1) strictly newer always wins — unchanged, and still the load-bearing drop of a stale
+      //     out-of-order delivery;
+      // (2) OR equal timestamp AND at least one non-PK SOURCE column arrives non-null and different
+      //     (a byte-identical redelivery stays a no-op; an incoming null is never a difference — a
+      //     list-shaped feed omitting a field must not erase the resolved value the row holds);
+      // (3) the equal-timestamp arm NEVER fires on a stored tombstone — a redelivered pre-delete
+      //     upsert carrying `removed_at: null` must not resurrect a deleted object the provider can
+      //     no longer correct.
+      // `IS` / `IS NOT` (not `=` / `<>`) so every comparison is NULL-safe. `updated_at` itself is
+      // excluded from the diff: inside the equal-timestamp arm the two are equal by construction.
+      // Self-stamped columns are excluded for the reason in SELF_STAMPED_COLUMNS's doc.
+      const diffCols = nonPkCols.filter((c) => !SELF_STAMPED_COLUMNS.has(c) && c !== "updated_at");
+      const sameStampDiff = diffCols
+        .map(
+          (c) =>
+            `(excluded.${quoteIdent(c)} IS NOT NULL AND ${quoteIdent(table)}.${quoteIdent(c)} IS NOT excluded.${quoteIdent(c)})`,
+        )
+        .join(" OR ");
+      const tombstoneGuard = cols.includes("removed_at")
+        ? ` AND ${quoteIdent(table)}.removed_at IS NULL`
+        : "";
+      const sameStampButChanged =
+        diffCols.length > 0
+          ? ` OR (excluded.updated_at IS ${quoteIdent(table)}.updated_at${tombstoneGuard} AND (${sameStampDiff}))`
+          : "";
+      guard = ` WHERE excluded.updated_at > ${quoteIdent(table)}.updated_at${sameStampButChanged}`;
+    }
     conflictClause = `ON CONFLICT(${conflictTarget}) DO UPDATE SET ${setClause}${guard}`;
   }
 
@@ -236,11 +282,56 @@ function pkValuesFor<B>(
 /**
  * Wipe every replica entity table (but NOT the host-only `sync_meta` cursor table). Called before
  * replaying a fresh /snapshot so a resync can't leave orphaned rows the new snapshot no longer contains.
+ *
+ * CTC-3051: a resync also repairs every FTS5 search index over a table it wipes, in three steps.
+ *  1. `rebuild` each index from its table while the rows are still there, so the index equals the
+ *     table whatever drift it held.
+ *  2. Delete the rows. Each delete trigger's FTS5 'delete' carries the row's current text, and after
+ *     step 1 it matches the entry exactly.
+ *  3. `delete-all` each index, which leaves it empty even if a trigger was missing or wrong.
+ *
+ * ⛔ THE REBUILD MUST RUN BEFORE THE ROWS GO. An index missing a row's entry (an interrupted first
+ * build, a lost trigger write) or holding stale text for it (an `INSERT OR REPLACE`) makes that row's
+ * 'delete' raise "database disk image is malformed", which rolls the DELETE back, and every retry of
+ * the resync then fails the same way. `delete-all` first does not help: the 'delete' against an
+ * emptied index throws too (measured in node:sqlite and bun:sqlite).
+ *
+ * The rebuild reads every row of each indexed table once. A replica's reads are local and unbilled,
+ * and the resync is about to rewrite every row anyway. The snapshot's inserts re-index each row through
+ * the insert trigger, and the caller then runs read-model's `rebuildSearchIndex` once the snapshot has
+ * applied.
  */
 export function truncateReplica<B>(db: ReplicaWriteDb<B>): void {
+  const indexes = searchIndexesOver(db, new Set(Object.keys(MIRROR_TABLE_META)));
+  for (const fts of indexes) {
+    db.run(`INSERT INTO ${quoteIdent(fts)}(${quoteIdent(fts)}) VALUES ('rebuild')`);
+  }
   for (const entity of Object.keys(MIRROR_TABLE_META)) {
     db.run(`DELETE FROM ${quoteIdent(entity)}`);
   }
+  for (const fts of indexes) {
+    db.run(`INSERT INTO ${quoteIdent(fts)}(${quoteIdent(fts)}) VALUES ('delete-all')`);
+  }
+}
+
+/**
+ * The external-content FTS5 tables in this store whose content table is in `tables`, read from
+ * sqlite_master (the read-model defines them; this package does not import it, so a store built by
+ * any read-model version is handled by what it holds). One row back: `ReplicaWriteDb.get` returns
+ * only the first row, so the names come as one JSON array.
+ */
+function searchIndexesOver<B>(db: ReplicaWriteDb<B>, tables: ReadonlySet<string>): string[] {
+  const row = db.get(
+    `SELECT json_group_array(json_array(name, sql)) AS j FROM sqlite_master
+      WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%' AND lower(sql) LIKE '%using fts5%'`,
+  );
+  const pairs = JSON.parse(String(row?.["j"] ?? "[]")) as [string, string][];
+  return pairs
+    .filter(([, ddl]) => {
+      const content = /content\s*=\s*'([^']*)'/i.exec(ddl)?.[1];
+      return content !== undefined && tables.has(content);
+    })
+    .map(([name]) => name);
 }
 
 /** Read the persisted change-feed cursor (or null if a snapshot has never completed). */