@catalyst-cloud/replicate 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/replicate",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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.3"
+    "@catalyst-cloud/schema": "0.1.10"
   },
   "devDependencies": {
     "@catalyst-cloud/typescript-config": "workspace:*",

package/src/replicate.ts

@@ -67,6 +67,12 @@ export interface ApplyOptions {
    *  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 {
@@ -94,8 +100,23 @@ const KNOWN_COLUMNS: Record<string, ReadonlySet<string>> = Object.fromEntries(
 
 /**
  * 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>,
@@ -104,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);