@catalyst-cloud/replicate 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/replicate",
-  "version": "0.1.2",
+  "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",
@@ -25,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/src/replicate.ts

@@ -51,18 +51,21 @@ export interface ReplicaChange {
  * `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).
+ * `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 {
-  /** 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. */
+  /** 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) 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. */
+  /** 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;
 }
 
@@ -74,6 +77,21 @@ 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
@@ -102,17 +120,19 @@ function applyUpsert<B>(
 ): 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;
+  // 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));
-    if (dropped.length > 0) {
-      opts.onDroppedColumns?.(table, dropped);
-      cols = 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.