@catalyst-cloud/replicate 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/replicate",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",
@@ -10,17 +10,13 @@
     "directory": "packages/replicate"
   },
   "files": [
-    "dist"
+    "src"
   ],
   "publishConfig": {
     "access": "public"
   },
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
+    ".": "./src/index.ts"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/{dist/index.js → src/index.ts}

@@ -4,4 +4,6 @@
 // lands a change-feed record into a local SQLite replica over the portable `ReplicaWriteDb` handle, so
 // the IDENTICAL apply logic runs unchanged in the host-sync bun:sqlite replica and the browser OPFS
 // wasm replica — collapsing the two hand-maintained `apply.ts` twins into one source of truth.
+
 export { applyDelta, truncateReplica, getCursor, setCursor } from "./replicate.js";
+export type { ReplicaWriteDb, ReplicaChange, ToBindable, ApplyOptions } from "./replicate.js";

package/src/replicate.ts

@@ -0,0 +1,222 @@
+// @catalyst-cloud/replicate — the runtime-agnostic replica WRITE path (ADR-0002). The write
+// counterpart to @catalyst-cloud/read-model: one `applyDelta` (+ cursor + truncate) that lands a
+// change-feed record into a local SQLite replica, schema-driven from the one Drizzle SSOT
+// (@catalyst-cloud/schema MIRROR_TABLE_META). The host-sync bun:sqlite replica and the browser OPFS
+// wasm replica BOTH route through this — collapsing the two hand-maintained `apply.ts` twins into one,
+// so they can never drift. Dependency-free / runtime-agnostic by design (NO bun:sqlite / node imports);
+// the runtime engine adapts to the portable `ReplicaWriteDb` handle, exactly as the read-model's
+// `SqlExecutor` is adapted per runtime.
+//
+// WIRE CONTRACT (shared — see apps/mirror/src/do/changefeed.ts):
+//   • op:"upsert"  → row is the FULL normalized DO row; INSERT … ON CONFLICT(pk) DO UPDATE, last-write-
+//                    wins by updated_at where present (DO NOTHING for a pure-join row like issue_labels).
+//   • op:"delete"  → soft-delete (set removed_at) on tables with a removed_at column, else hard-delete;
+//                    the PK is recovered from the row's PK columns or by splitting entityId on ':'.
+
+import { MIRROR_TABLE_META, type TableMeta } from "@catalyst-cloud/schema";
+
+/**
+ * The portable replica WRITE seam — the write counterpart to read-model's `SqlExecutor`. bun:sqlite
+ * (host-sync) and sqlite-wasm (browser OPFS) each satisfy it via a thin adapter. Generic over the
+ * bindable type `B` because the two engines coerce binary/bigint differently (bun binds Uint8Array /
+ * bigint; wasm binds ArrayBuffer / number) — the runtime supplies its own `toBindable` so every bound
+ * value is already a `B`.
+ */
+export interface ReplicaWriteDb<B> {
+  /** Execute a parameterized mutation; return the number of rows changed (sqlite3_changes()). */
+  run(sql: string, ...bindings: B[]): number;
+  /** Run a single-row query; return the first row as an object, or undefined. */
+  get(sql: string, ...bindings: B[]): Record<string, B> | undefined;
+}
+
+/** Coerce ONE wire JSON value to the runtime's bindable scalar `B` (booleans → 0/1, etc.). Runtime-
+ *  specific (binary/bigint differ per engine), so it is injected rather than baked in. */
+export type ToBindable<B> = (value: unknown) => B;
+
+/** One change-feed record (a /snapshot line or a /changes row). accountId/seq are the caller's concern.
+ *  `entity` is widened to string here (the runtime callers pass their stricter EntityName). */
+export interface ReplicaChange {
+  entity: string;
+  op: "upsert" | "delete";
+  /** Full normalized row for "upsert"; for "delete" may be `{}` or carry just the PK columns. */
+  row: Record<string, unknown>;
+  /** The change_log.entity_id — the PK (composite PKs joined with ':'). Required to apply a delete. */
+  entityId?: string;
+}
+
+/**
+ * Forward-compatibility options for applying a delta (CTC-127). The mirror (server) and the replica
+ * (client) upgrade INDEPENDENTLY — the server is often AHEAD, emitting a normalized row with columns a
+ * migration added that this client's schema doesn't have yet. Without this, `applyUpsert` would
+ * `INSERT INTO <table> (…, <new_col>, …)` and SQLite throws `no such column` (SQLITE_ERROR / errno:1),
+ * leaving that row permanently stale in the replica.
+ *
+ * When `knownColumns` is supplied (the columns the LOCAL table actually has), `applyUpsert` DROPS any
+ * row key not in the set — storing what it can and ignoring what it can't, so a server ahead of the
+ * client degrades gracefully instead of poisoning the apply. Client-ahead is already safe (a column
+ * the server hasn't started emitting is simply absent from the row → not set). Omit `knownColumns` for
+ * the legacy behavior (bind every key; a drifted column throws).
+ */
+export interface ApplyOptions {
+  /** The columns the LOCAL replica table has, for the delta's `entity`. Row keys outside this set are
+   *  dropped before the INSERT. PK columns are always local, so they are never dropped. */
+  knownColumns?: ReadonlySet<string>;
+  /** Reported (per apply) with the row keys dropped because the local table lacks them, so the caller
+   *  can warn-once / surface the cloud→client schema drift. Never fires when nothing was dropped. */
+  onDroppedColumns?: (table: string, dropped: readonly string[]) => void;
+}
+
+function quoteIdent(ident: string): string {
+  return `"${ident.replace(/"/g, '""')}"`;
+}
+
+function metaFor(entity: string): TableMeta | undefined {
+  return (MIRROR_TABLE_META as Record<string, TableMeta>)[entity];
+}
+
+/**
+ * Apply ONE change-feed record to the replica. Returns true iff a row was actually written (a stale
+ * upsert rejected by the updated_at guard, or a delete of an already-absent row, returns false). Never
+ * throws on a well-formed record; throws only on an unknown entity (malformed wire data).
+ */
+export function applyDelta<B>(
+  db: ReplicaWriteDb<B>,
+  change: ReplicaChange,
+  toBindable: ToBindable<B>,
+  opts?: ApplyOptions,
+): boolean {
+  const meta = metaFor(change.entity);
+  if (!meta) throw new Error(`applyDelta: unknown entity ${String(change.entity)}`);
+  // A delete keys on PK columns only (always present in the local schema), so it needs no
+  // forward-compat column filtering — only the upsert path binds the full wire row.
+  if (change.op === "delete") return applyDelete(db, change, meta, toBindable);
+  return applyUpsert(db, change, meta, toBindable, opts);
+}
+
+function applyUpsert<B>(
+  db: ReplicaWriteDb<B>,
+  change: ReplicaChange,
+  meta: TableMeta,
+  toBindable: ToBindable<B>,
+  opts?: ApplyOptions,
+): boolean {
+  const table = change.entity;
+  let cols = Object.keys(change.row);
+  // CTC-127 forward-compat: when the caller passes the local table's columns, drop any row key the
+  // local schema lacks (a mirror ahead of this client emits columns a migration added). Dropping them
+  // stores what we can instead of throwing `no such column`. PK columns are always local, so this can
+  // never strip the conflict target. Reported so the caller can warn-once about the drift.
+  if (opts?.knownColumns) {
+    const known = opts.knownColumns;
+    const dropped = cols.filter((c) => !known.has(c));
+    if (dropped.length > 0) {
+      opts.onDroppedColumns?.(table, dropped);
+      cols = cols.filter((c) => known.has(c));
+    }
+  }
+  if (cols.length === 0) return false; // malformed wire upsert — skip rather than emit invalid SQL.
+
+  const pkSet = new Set<string>(meta.pk);
+  const nonPkCols = cols.filter((c) => !pkSet.has(c));
+  const hasUpdatedAt = cols.includes("updated_at");
+
+  const colList = cols.map(quoteIdent).join(", ");
+  const placeholders = cols.map(() => "?").join(", ");
+  const conflictTarget = meta.pk.map(quoteIdent).join(", ");
+
+  let conflictClause: string;
+  if (nonPkCols.length === 0) {
+    // Pure join/edge row (issue_labels): PK is the whole row — no-op on conflict.
+    conflictClause = `ON CONFLICT(${conflictTarget}) DO NOTHING`;
+  } else {
+    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`
+      : "";
+    conflictClause = `ON CONFLICT(${conflictTarget}) DO UPDATE SET ${setClause}${guard}`;
+  }
+
+  const sql = `INSERT INTO ${quoteIdent(table)} (${colList}) VALUES (${placeholders}) ${conflictClause}`;
+  return db.run(sql, ...cols.map((c) => toBindable(change.row[c]))) > 0;
+}
+
+function applyDelete<B>(
+  db: ReplicaWriteDb<B>,
+  change: ReplicaChange,
+  meta: TableMeta,
+  toBindable: ToBindable<B>,
+): boolean {
+  const table = change.entity;
+
+  const pkVals = pkValuesFor(change, meta, toBindable);
+  if (!pkVals) return false; // can't locate the row → nothing to do.
+
+  const where = meta.pk.map((c) => `${quoteIdent(c)} = ?`).join(" AND ");
+
+  if (meta.softDelete) {
+    // Soft-delete: set removed_at, but only if currently live (idempotent re-delete is a no-op).
+    return (
+      db.run(
+        `UPDATE ${quoteIdent(table)} SET removed_at = ? WHERE ${where} AND removed_at IS NULL`,
+        toBindable(Date.now()),
+        ...pkVals,
+      ) > 0
+    );
+  }
+
+  // Hard-delete (join/edge/GitHub tables have no removed_at).
+  return db.run(`DELETE FROM ${quoteIdent(table)} WHERE ${where}`, ...pkVals) > 0;
+}
+
+/** Resolve the PK column values for a delete from the row's PK fields first, then entityId, else null.
+ *  Every value is routed through `toBindable` so the result is uniformly `B[]`. */
+function pkValuesFor<B>(
+  change: ReplicaChange,
+  meta: TableMeta,
+  toBindable: ToBindable<B>,
+): B[] | null {
+  const fromRow = meta.pk.map((c) => change.row[c]);
+  if (fromRow.every((v) => v !== undefined && v !== null)) {
+    return fromRow.map(toBindable);
+  }
+  if (change.entityId != null) {
+    const parts = change.entityId.split(":");
+    if (parts.length === meta.pk.length) return parts.map((p) => toBindable(p));
+  }
+  return null;
+}
+
+/**
+ * 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.
+ */
+export function truncateReplica<B>(db: ReplicaWriteDb<B>): void {
+  for (const entity of Object.keys(MIRROR_TABLE_META)) {
+    db.run(`DELETE FROM ${quoteIdent(entity)}`);
+  }
+}
+
+/** Read the persisted change-feed cursor (or null if a snapshot has never completed). */
+export function getCursor<B>(db: ReplicaWriteDb<B>): number | null {
+  const row = db.get("SELECT value FROM sync_meta WHERE key = 'cursor'");
+  if (!row) return null;
+  const n = Number(row["value"]);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Persist the change-feed cursor (the last applied change_log.seq). */
+export function setCursor<B>(
+  db: ReplicaWriteDb<B>,
+  cursor: number,
+  toBindable: ToBindable<B>,
+): void {
+  db.run(
+    "INSERT INTO sync_meta (key, value) VALUES (?, ?) " +
+      "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+    toBindable("cursor"),
+    toBindable(String(cursor)),
+  );
+}

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-export { applyDelta, truncateReplica, getCursor, setCursor } from "./replicate.js";
-export type { ReplicaWriteDb, ReplicaChange, ToBindable } from "./replicate.js";

package/dist/replicate.d.ts

@@ -1,41 +0,0 @@
-/**
- * The portable replica WRITE seam — the write counterpart to read-model's `SqlExecutor`. bun:sqlite
- * (host-sync) and sqlite-wasm (browser OPFS) each satisfy it via a thin adapter. Generic over the
- * bindable type `B` because the two engines coerce binary/bigint differently (bun binds Uint8Array /
- * bigint; wasm binds ArrayBuffer / number) — the runtime supplies its own `toBindable` so every bound
- * value is already a `B`.
- */
-export interface ReplicaWriteDb<B> {
-    /** Execute a parameterized mutation; return the number of rows changed (sqlite3_changes()). */
-    run(sql: string, ...bindings: B[]): number;
-    /** Run a single-row query; return the first row as an object, or undefined. */
-    get(sql: string, ...bindings: B[]): Record<string, B> | undefined;
-}
-/** Coerce ONE wire JSON value to the runtime's bindable scalar `B` (booleans → 0/1, etc.). Runtime-
- *  specific (binary/bigint differ per engine), so it is injected rather than baked in. */
-export type ToBindable<B> = (value: unknown) => B;
-/** One change-feed record (a /snapshot line or a /changes row). accountId/seq are the caller's concern.
- *  `entity` is widened to string here (the runtime callers pass their stricter EntityName). */
-export interface ReplicaChange {
-    entity: string;
-    op: "upsert" | "delete";
-    /** Full normalized row for "upsert"; for "delete" may be `{}` or carry just the PK columns. */
-    row: Record<string, unknown>;
-    /** The change_log.entity_id — the PK (composite PKs joined with ':'). Required to apply a delete. */
-    entityId?: string;
-}
-/**
- * Apply ONE change-feed record to the replica. Returns true iff a row was actually written (a stale
- * upsert rejected by the updated_at guard, or a delete of an already-absent row, returns false). Never
- * throws on a well-formed record; throws only on an unknown entity (malformed wire data).
- */
-export declare function applyDelta<B>(db: ReplicaWriteDb<B>, change: ReplicaChange, toBindable: ToBindable<B>): boolean;
-/**
- * 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.
- */
-export declare function truncateReplica<B>(db: ReplicaWriteDb<B>): void;
-/** Read the persisted change-feed cursor (or null if a snapshot has never completed). */
-export declare function getCursor<B>(db: ReplicaWriteDb<B>): number | null;
-/** Persist the change-feed cursor (the last applied change_log.seq). */
-export declare function setCursor<B>(db: ReplicaWriteDb<B>, cursor: number, toBindable: ToBindable<B>): void;

package/dist/replicate.js

@@ -1,112 +0,0 @@
-// @catalyst-cloud/replicate — the runtime-agnostic replica WRITE path (ADR-0002). The write
-// counterpart to @catalyst-cloud/read-model: one `applyDelta` (+ cursor + truncate) that lands a
-// change-feed record into a local SQLite replica, schema-driven from the one Drizzle SSOT
-// (@catalyst-cloud/schema MIRROR_TABLE_META). The host-sync bun:sqlite replica and the browser OPFS
-// wasm replica BOTH route through this — collapsing the two hand-maintained `apply.ts` twins into one,
-// so they can never drift. Dependency-free / runtime-agnostic by design (NO bun:sqlite / node imports);
-// the runtime engine adapts to the portable `ReplicaWriteDb` handle, exactly as the read-model's
-// `SqlExecutor` is adapted per runtime.
-//
-// WIRE CONTRACT (shared — see apps/mirror/src/do/changefeed.ts):
-//   • op:"upsert"  → row is the FULL normalized DO row; INSERT … ON CONFLICT(pk) DO UPDATE, last-write-
-//                    wins by updated_at where present (DO NOTHING for a pure-join row like issue_labels).
-//   • op:"delete"  → soft-delete (set removed_at) on tables with a removed_at column, else hard-delete;
-//                    the PK is recovered from the row's PK columns or by splitting entityId on ':'.
-import { MIRROR_TABLE_META } from "@catalyst-cloud/schema";
-function quoteIdent(ident) {
-    return `"${ident.replace(/"/g, '""')}"`;
-}
-function metaFor(entity) {
-    return MIRROR_TABLE_META[entity];
-}
-/**
- * Apply ONE change-feed record to the replica. Returns true iff a row was actually written (a stale
- * upsert rejected by the updated_at guard, or a delete of an already-absent row, returns false). Never
- * throws on a well-formed record; throws only on an unknown entity (malformed wire data).
- */
-export function applyDelta(db, change, toBindable) {
-    const meta = metaFor(change.entity);
-    if (!meta)
-        throw new Error(`applyDelta: unknown entity ${String(change.entity)}`);
-    if (change.op === "delete")
-        return applyDelete(db, change, meta, toBindable);
-    return applyUpsert(db, change, meta, toBindable);
-}
-function applyUpsert(db, change, meta, toBindable) {
-    const table = change.entity;
-    const cols = Object.keys(change.row);
-    if (cols.length === 0)
-        return false; // malformed wire upsert — skip rather than emit invalid SQL.
-    const pkSet = new Set(meta.pk);
-    const nonPkCols = cols.filter((c) => !pkSet.has(c));
-    const hasUpdatedAt = cols.includes("updated_at");
-    const colList = cols.map(quoteIdent).join(", ");
-    const placeholders = cols.map(() => "?").join(", ");
-    const conflictTarget = meta.pk.map(quoteIdent).join(", ");
-    let conflictClause;
-    if (nonPkCols.length === 0) {
-        // Pure join/edge row (issue_labels): PK is the whole row — no-op on conflict.
-        conflictClause = `ON CONFLICT(${conflictTarget}) DO NOTHING`;
-    }
-    else {
-        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`
-            : "";
-        conflictClause = `ON CONFLICT(${conflictTarget}) DO UPDATE SET ${setClause}${guard}`;
-    }
-    const sql = `INSERT INTO ${quoteIdent(table)} (${colList}) VALUES (${placeholders}) ${conflictClause}`;
-    return db.run(sql, ...cols.map((c) => toBindable(change.row[c]))) > 0;
-}
-function applyDelete(db, change, meta, toBindable) {
-    const table = change.entity;
-    const pkVals = pkValuesFor(change, meta, toBindable);
-    if (!pkVals)
-        return false; // can't locate the row → nothing to do.
-    const where = meta.pk.map((c) => `${quoteIdent(c)} = ?`).join(" AND ");
-    if (meta.softDelete) {
-        // Soft-delete: set removed_at, but only if currently live (idempotent re-delete is a no-op).
-        return (db.run(`UPDATE ${quoteIdent(table)} SET removed_at = ? WHERE ${where} AND removed_at IS NULL`, toBindable(Date.now()), ...pkVals) > 0);
-    }
-    // Hard-delete (join/edge/GitHub tables have no removed_at).
-    return db.run(`DELETE FROM ${quoteIdent(table)} WHERE ${where}`, ...pkVals) > 0;
-}
-/** Resolve the PK column values for a delete from the row's PK fields first, then entityId, else null.
- *  Every value is routed through `toBindable` so the result is uniformly `B[]`. */
-function pkValuesFor(change, meta, toBindable) {
-    const fromRow = meta.pk.map((c) => change.row[c]);
-    if (fromRow.every((v) => v !== undefined && v !== null)) {
-        return fromRow.map(toBindable);
-    }
-    if (change.entityId != null) {
-        const parts = change.entityId.split(":");
-        if (parts.length === meta.pk.length)
-            return parts.map((p) => toBindable(p));
-    }
-    return null;
-}
-/**
- * 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.
- */
-export function truncateReplica(db) {
-    for (const entity of Object.keys(MIRROR_TABLE_META)) {
-        db.run(`DELETE FROM ${quoteIdent(entity)}`);
-    }
-}
-/** Read the persisted change-feed cursor (or null if a snapshot has never completed). */
-export function getCursor(db) {
-    const row = db.get("SELECT value FROM sync_meta WHERE key = 'cursor'");
-    if (!row)
-        return null;
-    const n = Number(row["value"]);
-    return Number.isFinite(n) ? n : null;
-}
-/** Persist the change-feed cursor (the last applied change_log.seq). */
-export function setCursor(db, cursor, toBindable) {
-    db.run("INSERT INTO sync_meta (key, value) VALUES (?, ?) " +
-        "ON CONFLICT(key) DO UPDATE SET value = excluded.value", toBindable("cursor"), toBindable(String(cursor)));
-}