@catalyst-cloud/replicate 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/replicate",
-  "version": "0.1.0",
+  "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",
@@ -21,7 +21,8 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
     "@catalyst-cloud/schema": "^0.1.0"

package/src/index.ts

@@ -5,5 +5,5 @@
 // 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";
-export type { ReplicaWriteDb, ReplicaChange, ToBindable } from "./replicate";
+export { applyDelta, truncateReplica, getCursor, setCursor } from "./replicate.js";
+export type { ReplicaWriteDb, ReplicaChange, ToBindable, ApplyOptions } from "./replicate.js";

package/src/replicate.ts

@@ -44,6 +44,28 @@ export interface ReplicaChange {
   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, '""')}"`;
 }
@@ -61,11 +83,14 @@ 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);
+  return applyUpsert(db, change, meta, toBindable, opts);
 }
 
 function applyUpsert<B>(
@@ -73,9 +98,22 @@ function applyUpsert<B>(
   change: ReplicaChange,
   meta: TableMeta,
   toBindable: ToBindable<B>,
+  opts?: ApplyOptions,
 ): boolean {
   const table = change.entity;
-  const cols = Object.keys(change.row);
+  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);