@catalyst-cloud/replicate 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/replicate",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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,10 +25,10 @@
     "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:*",
+    "@catalyst-cloud/typescript-config": "0.0.0",
     "@types/node": "^25.9.3",
     "typescript": "^5.6.3",
     "vitest": "^2.1.8"

package/src/replicate.ts

@@ -51,19 +51,28 @@ 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;
+  /**
+   * CTC-393 — reported when `applyDelta` receives a delta for an entity this client's BUNDLED schema
+   * does not recognize AT ALL (the whole table is unknown, not merely a missing column). Never fires
+   * when the entity resolves. See {@link applyDelta}'s own doc for why this replaces a throw.
+   */
+  onUnknownEntity?: (entity: string) => void;
 }
 
 function quoteIdent(ident: string): string {
@@ -74,10 +83,40 @@ 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).
+ * upsert rejected by the updated_at guard, or a delete of an already-absent row, returns false).
+ *
+ * ⛔ CTC-393 — NEVER THROWS, including on an unknown entity. It used to: an entity this client's
+ * bundled schema does not recognize AT ALL (the mirror started emitting a table this client predates
+ * — the exact shape of a NEW replicated entity rolling out to a fleet that upgrades independently)
+ * threw, and on the CURRENT SDK caller (catalyst-replica.ts) that throw propagates out of the SAME
+ * `engine.transaction(...)` callback that also calls `setCursor` — so the transaction rolls back,
+ * the cursor never advances past that seq, and the daemon's transport holds every LATER frame behind
+ * the hole (CTL-1402's own contiguity guarantee: "never delivers a frame beyond deliveredSeq+1").
+ * One new entity type permanently wedges an ENTIRE replica, silently, with no resync path — the
+ * exact review finding (CTC-393 / the closed PR #290) this fix closes.
+ *
+ * An unknown entity now returns `false` (nothing written — there is nowhere to put it) and reports
+ * via `opts.onUnknownEntity`, mirroring `onDroppedColumns`'s existing graceful-degrade posture. NO
+ * CALLER CHANGE IS REQUIRED for safety: `onUnknownEntity` is optional, so the EXISTING SDK code path
+ * (which doesn't set it) already gets the correct behavior — `setCursor` runs, the cursor advances,
+ * `recordApplyResult("skipped", ...)` fires — the moment this package version is on the fleet.
  */
 export function applyDelta<B>(
   db: ReplicaWriteDb<B>,
@@ -86,7 +125,10 @@ export function applyDelta<B>(
   opts?: ApplyOptions,
 ): boolean {
   const meta = metaFor(change.entity);
-  if (!meta) throw new Error(`applyDelta: unknown entity ${String(change.entity)}`);
+  if (!meta) {
+    opts?.onUnknownEntity?.(change.entity);
+    return false;
+  }
   // 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);
@@ -102,17 +144,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.