@catalyst-cloud/sdk 0.8.1 → 0.8.2

package/dist/replica/browser/sqlite-db.d.ts

@@ -1,5 +1,37 @@
 import { type OpenedReplica } from "./ports.js";
 export type { OpenedReplica } from "./ports.js";
+/**
+ * Is this throw "the bytes on disk are not a usable database"? (CTC-337)
+ *
+ * ⚠️ THE ALLOWLIST IS THE SAFETY PROPERTY, not the recovery it guards. A `true` here authorizes
+ * DESTROYING the pool, so it must match ONLY genuine corruption. In particular it must never match
+ * `NoModificationAllowedError` — that is a second tab (or a not-yet-released worker) holding the
+ * SyncAccessHandles, and wiping on it would delete a database another live tab is actively using,
+ * turning a self-healing recovery into data loss for someone else. Contention is transient and the
+ * caller retries; corruption is permanent and only a wipe clears it. Anything unrecognised RETHROWS.
+ */
+export declare function isCorruptDatabaseError(err: unknown): boolean;
+/** The slice of SAHPoolUtil the recovery needs — narrowed so a test can supply a fake pool. */
+export interface RecoverablePool {
+    OpfsSAHPoolDb: new (dbPath: string) => unknown;
+    wipeFiles: () => Promise<void>;
+}
+/**
+ * Open the database, and if the FILE ITSELF is corrupt, destroy it and open a fresh one — ONCE.
+ *
+ * Safe in a way it would not be for most databases: this replica is 100% DERIVED. Every row came from
+ * `/snapshot` plus the change feed, so the local copy holds nothing that does not exist upstream, and
+ * re-seeding is the ordinary cold-start path rather than a recovery hack.
+ *
+ * Without this, one corrupt page bricked the replica PERMANENTLY. The corruption survives reloads, so
+ * `start()` threw on every subsequent boot and the reader sat behind a red pill forever unless they
+ * knew to clear origin storage by hand — a disposable cache that could not dispose of itself. That is
+ * exactly how CTC-337 presented: `SQLITE_CORRUPT: database disk image is malformed`, every load.
+ *
+ * Retries exactly once. A second failure after a wipe is not corruption we can clear — it is a broken
+ * environment (no quota, VFS refusing to register) — and looping would turn it into a hang.
+ */
+export declare function openWithCorruptionRecovery(pool: RecoverablePool, dbPath: string, build: (db: unknown) => OpenedReplica, log?: (message: string) => void): Promise<OpenedReplica>;
 /**
  * Open the OPFS SAHPool replica at `dbPath` (absolute, leading slash REQUIRED) and bring its schema up
  * to date via the shared migration bundle. Async — wasm init + SAHPool acquire are async, unlike the

package/dist/replica/browser/sqlite-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-db.d.ts","sourceRoot":"","sources":["../../../src/replica/browser/sqlite-db.ts"],"names":[],"mappings":"AAaA,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEpE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAS3F"}
+{"version":3,"file":"sqlite-db.d.ts","sourceRoot":"","sources":["../../../src/replica/browser/sqlite-db.ts"],"names":[],"mappings":"AAaA,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEpE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAc5D;AAED,+FAA+F;AAC/F,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/C,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,aAAa,EACrC,GAAG,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAA6B,GACtD,OAAO,CAAC,aAAa,CAAC,CAaxB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAU3F"}

package/dist/replica/browser/sqlite-db.js

@@ -10,6 +10,59 @@
 // not the primary one.
 import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
 import { buildOpenedReplica } from "./ports.js";
+/**
+ * Is this throw "the bytes on disk are not a usable database"? (CTC-337)
+ *
+ * ⚠️ THE ALLOWLIST IS THE SAFETY PROPERTY, not the recovery it guards. A `true` here authorizes
+ * DESTROYING the pool, so it must match ONLY genuine corruption. In particular it must never match
+ * `NoModificationAllowedError` — that is a second tab (or a not-yet-released worker) holding the
+ * SyncAccessHandles, and wiping on it would delete a database another live tab is actively using,
+ * turning a self-healing recovery into data loss for someone else. Contention is transient and the
+ * caller retries; corruption is permanent and only a wipe clears it. Anything unrecognised RETHROWS.
+ */
+export function isCorruptDatabaseError(err) {
+    const text = err instanceof Error ? `${err.name}: ${err.message}` : typeof err === "string" ? err : "";
+    if (text === "")
+        return false;
+    // Explicit rather than relying on the absence of a corruption marker: this is the case that must
+    // not wipe, so it should be impossible to reach the allowlist below by accident.
+    if (/NoModificationAllowedError|InvalidStateError/i.test(text))
+        return false;
+    return (/SQLITE_CORRUPT/i.test(text) ||
+        /SQLITE_NOTADB/i.test(text) ||
+        /database disk image is malformed/i.test(text) ||
+        /file is not a database/i.test(text) ||
+        /malformed database schema/i.test(text));
+}
+/**
+ * Open the database, and if the FILE ITSELF is corrupt, destroy it and open a fresh one — ONCE.
+ *
+ * Safe in a way it would not be for most databases: this replica is 100% DERIVED. Every row came from
+ * `/snapshot` plus the change feed, so the local copy holds nothing that does not exist upstream, and
+ * re-seeding is the ordinary cold-start path rather than a recovery hack.
+ *
+ * Without this, one corrupt page bricked the replica PERMANENTLY. The corruption survives reloads, so
+ * `start()` threw on every subsequent boot and the reader sat behind a red pill forever unless they
+ * knew to clear origin storage by hand — a disposable cache that could not dispose of itself. That is
+ * exactly how CTC-337 presented: `SQLITE_CORRUPT: database disk image is malformed`, every load.
+ *
+ * Retries exactly once. A second failure after a wipe is not corruption we can clear — it is a broken
+ * environment (no quota, VFS refusing to register) — and looping would turn it into a hang.
+ */
+export async function openWithCorruptionRecovery(pool, dbPath, build, log = (m) => console.warn(m)) {
+    try {
+        return build(new pool.OpfsSAHPoolDb(dbPath));
+    }
+    catch (err) {
+        if (!isCorruptDatabaseError(err))
+            throw err;
+        // Loud on purpose. Healing silently would hide that corruption HAPPENED, and the RATE of it is
+        // the signal worth having — a replica that quietly re-seeds every session is a different bug.
+        log(`[replica] OPFS database ${dbPath} is corrupt (${String(err)}); wiping and re-seeding — the replica is derived, so nothing is lost`);
+        await pool.wipeFiles();
+        return build(new pool.OpfsSAHPoolDb(dbPath));
+    }
+}
 /**
  * Open the OPFS SAHPool replica at `dbPath` (absolute, leading slash REQUIRED) and bring its schema up
  * to date via the shared migration bundle. Async — wasm init + SAHPool acquire are async, unlike the
@@ -22,7 +75,6 @@ export async function openReplica(dbPath, directory) {
         initialCapacity: 6, // ≥ 2× the db count (one db + journals).
         directory, // one OPFS dir per app, so engines don't collide.
     });
-    const db = new poolUtil.OpfsSAHPoolDb(dbPath);
-    return buildOpenedReplica(db);
+    return openWithCorruptionRecovery(poolUtil, dbPath, (db) => buildOpenedReplica(db));
 }
 //# sourceMappingURL=sqlite-db.js.map

package/dist/replica/browser/sqlite-db.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-db.js","sourceRoot":"","sources":["../../../src/replica/browser/sqlite-db.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,mGAAmG;AACnG,sGAAsG;AACtG,0BAA0B;AAC1B,EAAE;AACF,qGAAqG;AACrG,kGAAkG;AAClG,kGAAkG;AAClG,qGAAqG;AACrG,uBAAuB;AAEvB,OAAO,iBAAiB,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,kBAAkB,EAAsB,MAAM,YAAY,CAAC;AAIpE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAc,EAAE,SAAiB;IACjE,MAAM,OAAO,GAAG,MAAM,iBAAiB,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAgB,MAAM,OAAO,CAAC,qBAAqB,CAAC;QAChE,WAAW,EAAE,KAAK,EAAE,8DAA8D;QAClF,eAAe,EAAE,CAAC,EAAE,yCAAyC;QAC7D,SAAS,EAAE,kDAAkD;KAC9D,CAAC,CAAC;IACH,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,kBAAkB,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"sqlite-db.js","sourceRoot":"","sources":["../../../src/replica/browser/sqlite-db.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,mGAAmG;AACnG,sGAAsG;AACtG,0BAA0B;AAC1B,EAAE;AACF,qGAAqG;AACrG,kGAAkG;AAClG,kGAAkG;AAClG,qGAAqG;AACrG,uBAAuB;AAEvB,OAAO,iBAAiB,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,kBAAkB,EAAsB,MAAM,YAAY,CAAC;AAIpE;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,MAAM,IAAI,GACR,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5F,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9B,iGAAiG;IACjG,iFAAiF;IACjF,IAAI,+CAA+C,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7E,OAAO,CACL,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;QAC5B,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3B,mCAAmC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC9C,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC;QACpC,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC,CACxC,CAAC;AACJ,CAAC;AAQD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,IAAqB,EACrB,MAAc,EACd,KAAqC,EACrC,MAAiC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAEvD,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;QAC5C,+FAA+F;QAC/F,8FAA8F;QAC9F,GAAG,CACD,2BAA2B,MAAM,gBAAgB,MAAM,CAAC,GAAG,CAAC,uEAAuE,CACpI,CAAC;QACF,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAc,EAAE,SAAiB;IACjE,MAAM,OAAO,GAAG,MAAM,iBAAiB,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAgB,MAAM,OAAO,CAAC,qBAAqB,CAAC;QAChE,WAAW,EAAE,KAAK,EAAE,8DAA8D;QAClF,eAAe,EAAE,CAAC,EAAE,yCAAyC;QAC7D,SAAS,EAAE,kDAAkD;KAC9D,CAAC,CAAC;IACH,OAAO,0BAA0B,CAAC,QAAsC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CACvF,kBAAkB,CAAC,EAA8C,CAAC,CACnE,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/sdk",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Keep a live local copy of your Linear and GitHub project data \u2014 pushed in real time, without polling rate limits or webhook tunnels.",
   "license": "MIT",
   "author": "Coalesce Labs",