@catalyst-cloud/replicate 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/replicate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -29,7 +25,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@catalyst-cloud/schema": "^0.1.0"
+    "@catalyst-cloud/schema": "^0.1.3"
   },
   "devDependencies": {
     "@catalyst-cloud/typescript-config": "workspace:*",

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,242 @@
+// @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.
+ *
+ * `applyUpsert` DROPS any row key the client's schema lacks — 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). This filtering is AUTOMATIC: `knownColumns` DEFAULTS to the bundled schema's columns
+ * (`TableMeta.columns`), so no caller has to wire anything — these options are purely for OVERRIDE
+ * (a caller that wants PRAGMA-accurate columns) and for the `onDroppedColumns` drift signal.
+ */
+export interface ApplyOptions {
+  /** OVERRIDE the automatic default (the bundled schema's columns) with the columns the LOCAL table
+   *  actually has, for the delta's `entity`. Row keys outside the set are dropped before the INSERT; PK
+   *  columns are always local, so they are never dropped. Omit to use the bundled-schema default. */
+  knownColumns?: ReadonlySet<string>;
+  /** Reported (per apply, under the default OR an explicit `knownColumns`) with the row keys dropped
+   *  because the client's schema 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];
+}
+
+/**
+ * CTC-127: per-entity known-column Sets, built ONCE from the BUNDLED schema (`TableMeta.columns`, the
+ * same getTableConfig-derived columns the replica's `applyMigrations` migrates the DB to). This is the
+ * AUTOMATIC default `knownColumns` for `applyUpsert` — so a mirror emitting a column this client's
+ * schema doesn't have yet is handled with ZERO per-caller wiring (no call site can forget it). A client
+ * bundles its `@catalyst-cloud/replicate` and `@catalyst-cloud/schema` together, so this set is exactly
+ * "the columns this client knows".
+ */
+const KNOWN_COLUMNS: Record<string, ReadonlySet<string>> = Object.fromEntries(
+  Object.entries(MIRROR_TABLE_META).map(([entity, m]) => [
+    entity,
+    new Set((m as TableMeta).columns),
+  ]),
+);
+
+/**
+ * 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 (AUTOMATIC): drop any row key the local schema lacks — a column the mirror
+  // added ahead of this client's bundled schema. Without this the INSERT would name a nonexistent
+  // column and SQLite throws `no such column` (errno:1), stranding the row stale. `knownColumns`
+  // DEFAULTS to the bundled schema's columns (KNOWN_COLUMNS), so this protects EVERY caller with no
+  // wiring; an explicit `opts.knownColumns` OVERRIDES it (e.g. PRAGMA-accurate columns). `cols.every`
+  // short-circuits allocation-free in the common no-drift case. The `known.size > 0` guard falls back
+  // to legacy bind-all if the map is somehow empty (schema version skew) — the SAFE direction (never
+  // strips a row to PK-only). PK columns are always local, so the conflict target is never dropped.
+  const known = opts?.knownColumns ?? KNOWN_COLUMNS[table];
+  if (known && known.size > 0 && !cols.every((c) => known.has(c))) {
+    const dropped = cols.filter((c) => !known.has(c));
+    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)));
-}