@catalyst-cloud/sdk 0.6.0 → 0.8.0

package/dist/replica/browser/ports.d.ts

@@ -0,0 +1,39 @@
+import type { Database } from "@sqlite.org/sqlite-wasm";
+import type { SqlExecutor, SqlValue } from "@catalyst-cloud/read-model";
+/**
+ * The write port the delta-apply path (apply.ts) drives. `run` executes a mutation with positional `?`
+ * bindings and reports whether it changed a row (mirrors bun:sqlite's `db.query(sql).run(...).changes`);
+ * `get` runs a single-row read; `transaction` wraps a unit of work in BEGIN/COMMIT (ROLLBACK on throw)
+ * so a snapshot seed lands atomically — exactly the guarantee host-sync gets from bun's `db.transaction`.
+ */
+export interface ReplicaDb {
+    /** Execute a mutation; returns the number of rows changed (sqlite3_changes()). */
+    run(sql: string, ...bindings: SqlValue[]): number;
+    /** Run a single-row query; returns the first row as an object, or undefined. */
+    get(sql: string, ...bindings: SqlValue[]): Record<string, SqlValue> | undefined;
+    /** Wrap `fn` in a transaction (BEGIN/COMMIT; ROLLBACK + rethrow on error). */
+    transaction<T>(fn: () => T): T;
+}
+/** Coerce a wire JSON value to a sqlite-wasm-bindable scalar. Booleans → 0/1, nested objects → JSON
+ *  text, undefined/null → null. Mirrors the node engine's `toBindable` so both replicas store the
+ *  same bytes for the same wire row. */
+export declare function toBindable(v: unknown): SqlValue;
+/** The opened replica: the raw OO1 handle plus the three typed ports the worker drives. */
+export interface OpenedReplica {
+    /** read-model read seam — buildIssuesView/buildIssueDetail/buildPullsView run over this UNCHANGED. */
+    readonly read: SqlExecutor;
+    /** delta-apply write seam — apply.ts (the host-sync twin) routes through this. */
+    readonly write: ReplicaDb;
+    /** the underlying OO1 db handle (for close / capacity introspection). */
+    readonly db: Database;
+    /** release the handle (under OPFS SAHPool this frees the SyncAccessHandles for another tab). */
+    close(): void;
+}
+/**
+ * Build the three ports over an ALREADY-OPEN OO1 database, bring its schema up to date by applying the
+ * SHARED migration bundle (the same `MIRROR_MIGRATIONS` the DO + daemon use), and create the host-only
+ * `sync_meta` cursor table. Pure over the handle — the production opener (sqlite-db.ts, OPFS SAHPool)
+ * and the test opener (`:memory:`) both route through here, so the ports can never drift between them.
+ */
+export declare function buildOpenedReplica(db: Database): OpenedReplica;
+//# sourceMappingURL=ports.d.ts.map

package/dist/replica/browser/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../../src/replica/browser/ports.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAIxE;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAClD,gFAAgF;IAChF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAC;IAChF,8EAA8E;IAC9E,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CAChC;AAED;;wCAEwC;AACxC,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,QAAQ,CAa/C;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,sGAAsG;IACtG,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,gGAAgG;IAChG,KAAK,IAAI,IAAI,CAAC;CACf;AAuBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,GAAG,aAAa,CAsF9D"}

package/dist/replica/browser/ports.js

@@ -0,0 +1,144 @@
+// replica/browser/ports.ts — the three typed ports the browser replica drives over a sqlite-wasm OO1
+// `Database`, split from the OPFS opener (sqlite-db.ts) so the SAME port-building code serves BOTH the
+// production OPFS SAHPool DB and a plain `:memory:` DB in node-side tests (sqlite-wasm runs fine under
+// node — no OPFS required to exercise seed/apply/query logic).
+//
+// The whole point of ADR-0002 is "one query, four runtimes": the read-model's `SqlExecutor` and the
+// schema package's `MigrationDb` are structural interfaces the DO (Workers SqlStorage), the host-sync
+// daemon (bun:sqlite), and the browser all satisfy. This file is the browser adapter — the exact
+// counterpart to the SDK node engine (src/replica/engine.ts), plus a small write port for the
+// delta-apply path.
+//
+//   • SqlExecutor (read)   — read-model: exec(q, ...binds).toArray() → object rows.
+//   • MigrationDb (migrate)— schema: exec(sql) + query(sql) (no bindings).
+//   • ReplicaDb (write)    — run/get with positional bindings, for the apply path (apply.ts).
+import { applyMigrations, MIRROR_MIGRATIONS } from "@catalyst-cloud/schema";
+import { migrationsChangeRowShape } from "../migration-shape.js";
+/** Coerce a wire JSON value to a sqlite-wasm-bindable scalar. Booleans → 0/1, nested objects → JSON
+ *  text, undefined/null → null. Mirrors the node engine's `toBindable` so both replicas store the
+ *  same bytes for the same wire row. */
+export function toBindable(v) {
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v === "boolean")
+        return v ? 1 : 0;
+    if (typeof v === "string" || typeof v === "number")
+        return v;
+    // bigint is outside the read-model SqlValue union (no column needs it) — coerce to number.
+    if (typeof v === "bigint")
+        return Number(v);
+    if (v instanceof ArrayBuffer)
+        return v;
+    if (v instanceof Uint8Array) {
+        // Copy to a standalone ArrayBuffer (the view may be a slice of a larger buffer).
+        return v.slice().buffer;
+    }
+    // Nested object/array (shouldn't occur — DO rows are flat scalars) → JSON text rather than throw.
+    return JSON.stringify(v);
+}
+/** A sqlite-wasm bindable array, narrowed to what the read-model/apply paths actually bind. */
+function bindArgs(bindings) {
+    return bindings.length > 0 ? bindings : undefined;
+}
+/**
+ * Read the persisted cursor straight off the handle, before the write port exists.
+ *
+ * The row-shape check below runs inside `buildOpenedReplica`, so apply.ts's `getCursor(db.write)` is not
+ * available yet — and it must stay that way: apply.ts imports the shared replicate helpers, and pulling
+ * that graph in here just to read one row would invert the layering this file exists to keep flat.
+ */
+function readCursorRow(db) {
+    const rows = db.exec("SELECT value FROM sync_meta WHERE key = 'cursor'", {
+        rowMode: "object",
+        returnValue: "resultRows",
+    });
+    const v = rows[0]?.value;
+    return typeof v === "string" ? v : null;
+}
+/**
+ * Build the three ports over an ALREADY-OPEN OO1 database, bring its schema up to date by applying the
+ * SHARED migration bundle (the same `MIRROR_MIGRATIONS` the DO + daemon use), and create the host-only
+ * `sync_meta` cursor table. Pure over the handle — the production opener (sqlite-db.ts, OPFS SAHPool)
+ * and the test opener (`:memory:`) both route through here, so the ports can never drift between them.
+ */
+export function buildOpenedReplica(db) {
+    // read-model SqlExecutor — the load-bearing ADR-0002 proof in the browser. exec(query, ...binds)
+    // returns object rows keyed by SELECTed column alias, which buildIssuesView/etc consume directly.
+    const read = {
+        exec: (query, ...bindings) => ({
+            toArray: () => db.exec(query, {
+                bind: bindArgs(bindings),
+                rowMode: "object",
+                returnValue: "resultRows",
+            }),
+        }),
+    };
+    // Write port — positional-binding mutations + single-row reads + a transaction wrapper.
+    const write = {
+        run: (sql, ...bindings) => {
+            db.exec(sql, { bind: bindArgs(bindings) });
+            // sqlite3_changes() via the OO1 helper — how many rows the last statement touched.
+            return db.changes();
+        },
+        get: (sql, ...bindings) => {
+            const rows = db.exec(sql, {
+                bind: bindArgs(bindings),
+                rowMode: "object",
+                returnValue: "resultRows",
+            });
+            return rows[0];
+        },
+        transaction: (fn) => {
+            db.exec("BEGIN");
+            try {
+                const out = fn();
+                db.exec("COMMIT");
+                return out;
+            }
+            catch (err) {
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch {
+                    // ROLLBACK can throw if the txn already aborted — swallow so the original error surfaces.
+                }
+                throw err;
+            }
+        },
+    };
+    // Apply the cross-surface mirror migrations via the ~3-line MigrationDb adapter (node-engine twin).
+    // exec runs ONE statement; query returns object rows. No bindings — the runner inlines its only literal.
+    const migrationAdapter = {
+        exec: (sql) => {
+            db.exec(sql);
+        },
+        query: (sql) => db.exec(sql, { rowMode: "object", returnValue: "resultRows" }),
+    };
+    const { appliedTags } = applyMigrations(migrationAdapter, MIRROR_MIGRATIONS);
+    // Host-only bookkeeping table (NOT in the DO mirror schema, so not in the bundle) — the cursor.
+    // Identical to the node engine's SYNC_META_DDL.
+    db.exec("CREATE TABLE IF NOT EXISTS sync_meta (key TEXT PRIMARY KEY, value TEXT)");
+    // CTC-127's browser twin (CTC-114 review, KtI). A migration that adds a column or a table leaves a
+    // WARM replica's existing rows holding NULL for it forever — deltas only carry CHANGED rows, so
+    // nothing ever backfills them. Dropping the cursor makes the client's warm-start check read cold and
+    // take the /snapshot path exactly once. The node replica has done this since CTC-127; without it the
+    // browser bites on the FIRST row-shape migration after 0.8.0.
+    //
+    // On the `cursor != null` guard: it is DEFENCE IN DEPTH, not the thing that makes this correct.
+    // What makes it correct is that `applyMigrations` reports only the tags it applied THIS call —
+    // verified: 9 on a cold database, 0 on a re-open — so a fully-migrated warm tab evaluates the
+    // predicate over an EMPTY list and never reaches the delete. (An earlier reading of this had the
+    // guard preventing a re-download on every warm reload; that is not what happens, because the
+    // predicate is already false there. It is kept because it costs one indexed lookup and it is what
+    // holds the line if the runner's contract ever changes to report all known tags.)
+    if (readCursorRow(db) != null && migrationsChangeRowShape(appliedTags)) {
+        db.exec("DELETE FROM sync_meta WHERE key = 'cursor'");
+    }
+    return {
+        read,
+        write,
+        db,
+        close: () => db.close(),
+    };
+}
+//# sourceMappingURL=ports.js.map

package/dist/replica/browser/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../../src/replica/browser/ports.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,uGAAuG;AACvG,uGAAuG;AACvG,+DAA+D;AAC/D,EAAE;AACF,oGAAoG;AACpG,sGAAsG;AACtG,iGAAiG;AACjG,8FAA8F;AAC9F,oBAAoB;AACpB,EAAE;AACF,oFAAoF;AACpF,2EAA2E;AAC3E,8FAA8F;AAI9F,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAoB,MAAM,wBAAwB,CAAC;AAC9F,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAiBjE;;wCAEwC;AACxC,MAAM,UAAU,UAAU,CAAC,CAAU;IACnC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IAC7D,2FAA2F;IAC3F,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5C,IAAI,CAAC,YAAY,WAAW;QAAE,OAAO,CAAC,CAAC;IACvC,IAAI,CAAC,YAAY,UAAU,EAAE,CAAC;QAC5B,iFAAiF;QACjF,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC;IAC1B,CAAC;IACD,kGAAkG;IAClG,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAcD,+FAA+F;AAC/F,SAAS,QAAQ,CAAC,QAAoB;IACpC,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,EAAY;IACjC,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,kDAAkD,EAAE;QACvE,OAAO,EAAE,QAAQ;QACjB,WAAW,EAAE,YAAY;KAC1B,CAA+B,CAAC;IACjC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC;IACzB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAY;IAC7C,iGAAiG;IACjG,kGAAkG;IAClG,MAAM,IAAI,GAAgB;QACxB,IAAI,EAAE,CAAC,KAAa,EAAE,GAAG,QAAoB,EAAE,EAAE,CAAC,CAAC;YACjD,OAAO,EAAE,GAAG,EAAE,CACZ,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE;gBACb,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC;gBACxB,OAAO,EAAE,QAAQ;gBACjB,WAAW,EAAE,YAAY;aAC1B,CAA+B;SACnC,CAAC;KACH,CAAC;IAEF,wFAAwF;IACxF,MAAM,KAAK,GAAc;QACvB,GAAG,EAAE,CAAC,GAAW,EAAE,GAAG,QAAoB,EAAE,EAAE;YAC5C,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAC3C,mFAAmF;YACnF,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;QACtB,CAAC;QACD,GAAG,EAAE,CAAC,GAAW,EAAE,GAAG,QAAoB,EAAE,EAAE;YAC5C,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;gBACxB,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC;gBACxB,OAAO,EAAE,QAAQ;gBACjB,WAAW,EAAE,YAAY;aAC1B,CAA+B,CAAC;YACjC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;QACD,WAAW,EAAE,CAAI,EAAW,EAAK,EAAE;YACjC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACjB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,EAAE,EAAE,CAAC;gBACjB,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAClB,OAAO,GAAG,CAAC;YACb,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC;oBACH,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBACtB,CAAC;gBAAC,MAAM,CAAC;oBACP,0FAA0F;gBAC5F,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;IAEF,oGAAoG;IACpG,yGAAyG;IACzG,MAAM,gBAAgB,GAAgB;QACpC,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE;YACZ,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QACD,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CACb,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,CAE5D;KACJ,CAAC;IACF,MAAM,EAAE,WAAW,EAAE,GAAG,eAAe,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,CAAC;IAE7E,gGAAgG;IAChG,gDAAgD;IAChD,EAAE,CAAC,IAAI,CAAC,yEAAyE,CAAC,CAAC;IAEnF,mGAAmG;IACnG,gGAAgG;IAChG,qGAAqG;IACrG,qGAAqG;IACrG,8DAA8D;IAC9D,EAAE;IACF,gGAAgG;IAChG,+FAA+F;IAC/F,8FAA8F;IAC9F,iGAAiG;IACjG,6FAA6F;IAC7F,kGAAkG;IAClG,kFAAkF;IAClF,IAAI,aAAa,CAAC,EAAE,CAAC,IAAI,IAAI,IAAI,wBAAwB,CAAC,WAAW,CAAC,EAAE,CAAC;QACvE,EAAE,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IACxD,CAAC;IAED,OAAO;QACL,IAAI;QACJ,KAAK;QACL,EAAE;QACF,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/replica/browser/protocol.d.ts

@@ -0,0 +1,129 @@
+import type { IssueView, IssueDetailView, PullView } from "@catalyst-cloud/read-model";
+/** A change-feed record as it rides the wire — the shape both /snapshot data lines and /changes rows
+ *  decode to (accountId/seq are bookkeeping the worker tracks separately). Mirrors host-sync's
+ *  ChangeRecord (apps/host-sync/src/apply.ts) field-for-field so the apply path is a true twin. */
+export interface WireChange {
+    entity: string;
+    op: "upsert" | "delete";
+    row: Record<string, unknown>;
+    /** change_log.entity_id — the PK (composite PKs joined with ':'); required to apply a delete. */
+    entityId?: string;
+}
+/** Open the OPFS SAHPool DB and bring its schema up to date (applyMigrations + sync_meta). Idempotent. */
+export interface OpenRequest {
+    type: "open";
+    /** Absolute OPFS db path (SAHPool requires a leading slash). */
+    dbPath: string;
+    /** OPFS directory the SAHPool VFS manages (one per app to avoid cross-engine collisions). */
+    directory: string;
+    /**
+     * Opaque TENANT FENCE for the persisted database (CTC-114 review).
+     *
+     * `dbPath`/`directory` default to constants, so every tenant on an origin opens the SAME OPFS
+     * database. The warm-start path skips `/snapshot` whenever the persisted cursor is non-null — so
+     * after the cookie user changes, or the app starts a replica for a different `accountId`, the
+     * previous tenant's rows stayed queryable and no delta could ever remove them (deltas only carry
+     * changes, never "forget everything you knew").
+     *
+     * The worker compares this against the value stored in `sync_meta` and, on a mismatch, truncates
+     * the replica and clears the cursor so the client cold-starts into a fresh snapshot. Comparing at
+     * OPEN is what makes it a fence: it happens before any read can be served.
+     */
+    identity: string;
+}
+/**
+ * Batched streaming seed (CTC-132) — replaces the one-shot `SeedRequest`. The snapshot rides in across
+ * MANY messages so no layer buffers the whole ~74 MB body: `seedBegin` opens one transaction and
+ * truncates, each `seedBatch` applies a bounded page, `seedCommit` sets the cursor and COMMITs, and
+ * `seedAbort` rolls back on error. The worker holds one open `SeedSession` for the duration.
+ */
+export interface SeedBeginRequest {
+    type: "seedBegin";
+}
+export interface SeedBatchRequest {
+    type: "seedBatch";
+    rows: WireChange[];
+}
+export interface SeedCommitRequest {
+    type: "seedCommit";
+    cursor: number;
+}
+export interface SeedAbortRequest {
+    type: "seedAbort";
+}
+/** Apply a batch of live deltas (each a /changes row) and advance the cursor to the max seq seen. */
+export interface ApplyChangesRequest {
+    type: "applyChanges";
+    changes: Array<WireChange & {
+        seq: number;
+    }>;
+}
+/** Read the issues list view locally (buildIssuesView over the OPFS replica). */
+export interface QueryIssuesRequest {
+    type: "queryIssues";
+    limit?: number;
+    offset?: number;
+}
+/** Read one issue's detail view locally (buildIssueDetail). */
+export interface QueryIssueDetailRequest {
+    type: "queryIssueDetail";
+    identifier: string;
+}
+/** Read the pull-requests view locally (buildPullsView). */
+export interface QueryPullsRequest {
+    type: "queryPulls";
+    limit?: number;
+    offset?: number;
+}
+/** Read the persisted change-feed cursor (or null if no snapshot has ever completed). */
+export interface GetCursorRequest {
+    type: "getCursor";
+}
+/**
+ * Close the DB cleanly BEFORE the Worker is terminated (CTC-114). `worker.terminate()` alone drops the
+ * OPFS SyncAccessHandles by process kill; an explicit close releases them cooperatively so the next
+ * boot (same tab reload, or another tab winning the Web Lock) doesn't race a not-yet-released pool.
+ */
+export interface CloseRequest {
+    type: "close";
+}
+export type ReplicaRequest = OpenRequest | SeedBeginRequest | SeedBatchRequest | SeedCommitRequest | SeedAbortRequest | ApplyChangesRequest | QueryIssuesRequest | QueryIssueDetailRequest | QueryPullsRequest | GetCursorRequest | CloseRequest;
+/** Every request carries an `id`; the worker echoes it so the client can settle the matching promise. */
+export interface Envelope<T extends ReplicaRequest = ReplicaRequest> {
+    id: number;
+    request: T;
+}
+/** A successful reply, discriminated on the originating request `type`. `result` shape follows from it. */
+export interface ReplicaOk {
+    id: number;
+    ok: true;
+    /** The reply payload — view rows, a cursor, an applied count, or null/void for open/seed. */
+    result: unknown;
+}
+/** A failed reply — the worker never throws across the boundary; it serializes the message. */
+export interface ReplicaErr {
+    id: number;
+    ok: false;
+    error: string;
+}
+export type ReplicaResponse = ReplicaOk | ReplicaErr;
+/** Result of an applyChanges call — how many rows actually landed and the cursor afterwards. */
+export interface ApplyChangesResult {
+    applied: number;
+    cursor: number;
+}
+/** Strongly-typed result lookup so the client can cast a reply by the request type it sent. */
+export interface ResultMap {
+    open: void;
+    seedBegin: void;
+    seedBatch: void;
+    seedCommit: number;
+    seedAbort: void;
+    applyChanges: ApplyChangesResult;
+    queryIssues: IssueView[];
+    queryIssueDetail: IssueDetailView | null;
+    queryPulls: PullView[];
+    getCursor: number | null;
+    close: void;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/replica/browser/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/replica/browser/protocol.ts"],"names":[],"mappings":"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"}

package/dist/replica/browser/protocol.js

@@ -0,0 +1,12 @@
+// replica/protocol.ts — the typed RPC contract between the main thread and the OPFS replica Worker
+// (CTC-51, ADR-0002 browser twin of apps/host-sync). The SAHPool VFS only works inside a Web Worker
+// (OPFS SyncAccessHandles are Worker-only — see EXTERNAL recipe / sqlite.org persistence docs), so the
+// whole replica DB lives in db.worker.ts and the main-thread client (replica-client.ts) talks to it
+// over postMessage. This module is the SINGLE source of truth for those message shapes — imported by
+// both sides so a request and its response can never drift.
+//
+// The wire records (snapshot lines / change lines) are the SAME change-feed contract host-sync's
+// sync-client.ts consumes; the read results are the SAME read-model view types the DO + daemon return.
+// Nothing here imports sqlite-wasm or bun:sqlite, so it stays runtime-agnostic and tree-shakes cleanly.
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/replica/browser/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/replica/browser/protocol.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,oGAAoG;AACpG,uGAAuG;AACvG,oGAAoG;AACpG,qGAAqG;AACrG,4DAA4D;AAC5D,EAAE;AACF,iGAAiG;AACjG,uGAAuG;AACvG,wGAAwG"}

package/dist/replica/browser/seed-read-gate.d.ts

@@ -0,0 +1,13 @@
+export declare class SeedReadGate {
+    /** Resolvers for reads deferred during the current seed; drained on settle(). */
+    private waiters;
+    /**
+     * Return a promise a read should await before touching the DB. When no seed is open the caller passes
+     * `seeding=false` and gets an already-resolved promise (zero overhead on the hot read path); while a
+     * seed is open it resolves only once settle() runs.
+     */
+    whenReadable(seeding: boolean): Promise<void>;
+    /** Release every read deferred during the just-finished seed — call on BOTH commit and abort. */
+    settle(): void;
+}
+//# sourceMappingURL=seed-read-gate.d.ts.map

package/dist/replica/browser/seed-read-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-read-gate.d.ts","sourceRoot":"","sources":["../../../src/replica/browser/seed-read-gate.ts"],"names":[],"mappings":"AAeA,qBAAa,YAAY;IACvB,iFAAiF;IACjF,OAAO,CAAC,OAAO,CAAyB;IAExC;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C,iGAAiG;IACjG,MAAM,IAAI,IAAI;CAKf"}

package/dist/replica/browser/seed-read-gate.js

@@ -0,0 +1,36 @@
+// replica/seed-read-gate.ts — the Worker's mid-seed READ gate (CTC-132 review finding).
+//
+// The batched streaming seed (seedBegin → seedBatch* → seedCommit/seedAbort) holds ONE SQLite
+// transaction open across many Worker messages, and the replica's read + write adapters share the same
+// sqlite-wasm handle. So a query RPC (queryIssues/queryIssueDetail/queryPulls) that interleaves BETWEEN
+// seedBatch messages would run against the truncated, partially-repopulated transaction and briefly
+// hand the UI incomplete results — a regression from the old synchronous one-shot seed, which no read
+// could interleave. We can't simply REJECT such reads: both consumers (use-replica-issues.ts refetch +
+// onChanged) treat any query rejection as a hard "Replica error". So we DEFER them instead — a read that
+// arrives mid-seed waits until the seed settles, then runs against a COMPLETE database. Both terminal
+// paths leave a complete DB: commit publishes the fresh snapshot; abort ROLLBACKs to the prior complete
+// snapshot. Either way a released read sees whole data, never a partial one.
+//
+// Pure + injectable so it is unit-testable (test/seed-read-gate.test.ts) without the wasm/OPFS Worker.
+export class SeedReadGate {
+    /** Resolvers for reads deferred during the current seed; drained on settle(). */
+    waiters = [];
+    /**
+     * Return a promise a read should await before touching the DB. When no seed is open the caller passes
+     * `seeding=false` and gets an already-resolved promise (zero overhead on the hot read path); while a
+     * seed is open it resolves only once settle() runs.
+     */
+    whenReadable(seeding) {
+        if (!seeding)
+            return Promise.resolve();
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    /** Release every read deferred during the just-finished seed — call on BOTH commit and abort. */
+    settle() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const resolve of waiters)
+            resolve();
+    }
+}
+//# sourceMappingURL=seed-read-gate.js.map

package/dist/replica/browser/seed-read-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-read-gate.js","sourceRoot":"","sources":["../../../src/replica/browser/seed-read-gate.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,EAAE;AACF,8FAA8F;AAC9F,uGAAuG;AACvG,wGAAwG;AACxG,oGAAoG;AACpG,sGAAsG;AACtG,uGAAuG;AACvG,yGAAyG;AACzG,sGAAsG;AACtG,wGAAwG;AACxG,6EAA6E;AAC7E,EAAE;AACF,uGAAuG;AAEvG,MAAM,OAAO,YAAY;IACvB,iFAAiF;IACzE,OAAO,GAAsB,EAAE,CAAC;IAExC;;;;OAIG;IACH,YAAY,CAAC,OAAgB;QAC3B,IAAI,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QACvC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACpE,CAAC;IAED,iGAAiG;IACjG,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,KAAK,MAAM,OAAO,IAAI,OAAO;YAAE,OAAO,EAAE,CAAC;IAC3C,CAAC;CACF"}

package/dist/replica/browser/seed-session.d.ts

@@ -0,0 +1,23 @@
+import type { ReplicaDb } from "./ports.js";
+import type { WireChange } from "./protocol.js";
+/** The three replica write primitives the seed drives, injected so tests can fake them. */
+export interface SeedOps {
+    truncate: (db: ReplicaDb) => void;
+    apply: (db: ReplicaDb, rec: WireChange) => boolean;
+    setCursor: (db: ReplicaDb, cursor: number) => void;
+}
+export declare class SeedSession {
+    private readonly db;
+    private readonly ops;
+    private open;
+    constructor(db: ReplicaDb, ops: SeedOps);
+    /** Open the transaction and wipe the replica (but not sync_meta) so the fresh snapshot replaces it. */
+    begin(): void;
+    /** Apply one bounded batch of rows into the open transaction. */
+    batch(rows: WireChange[]): void;
+    /** Persist the terminal cursor, then COMMIT the whole seed atomically. Returns the cursor. */
+    commit(cursor: number): number;
+    /** Roll back a partial seed on error — leaves the prior cursor (sync_meta) intact. Idempotent. */
+    abort(): void;
+}
+//# sourceMappingURL=seed-session.d.ts.map

package/dist/replica/browser/seed-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-session.d.ts","sourceRoot":"","sources":["../../../src/replica/browser/seed-session.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,2FAA2F;AAC3F,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC;IACnD,SAAS,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED,qBAAa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJtB,OAAO,CAAC,IAAI,CAAS;gBAGF,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,OAAO;IAG/B,uGAAuG;IACvG,KAAK,IAAI,IAAI;IAQb,iEAAiE;IACjE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI;IAK/B,8FAA8F;IAC9F,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAQ9B,kGAAkG;IAClG,KAAK,IAAI,IAAI;CAUd"}

package/dist/replica/browser/seed-session.js

@@ -0,0 +1,57 @@
+// replica/seed-session.ts — the pure transaction state machine behind the batched OPFS seed (CTC-132).
+//
+// The streamed seed spans MULTIPLE Worker messages (seedBegin → seedBatch* → seedCommit / seedAbort),
+// so — unlike the old one-shot `seed` that ran inside a single callback-scoped `transaction()` — the
+// SQLite transaction must stay open ACROSS those messages. This class owns that: it opens the txn +
+// truncates on `begin`, applies rows per `batch`, and sets the cursor + COMMITs on `commit` (or
+// ROLLBACKs on `abort`). The Worker (db.worker.ts) is single-threaded and messages are serialized, so
+// the open transaction is safe between batches.
+//
+// The truncate/apply/setCursor ops are INJECTED so this seam is unit-testable against a fake ReplicaDb
+// (test/seed-session.test.ts); the Worker passes the real apply.ts bindings.
+export class SeedSession {
+    db;
+    ops;
+    open = false;
+    constructor(db, ops) {
+        this.db = db;
+        this.ops = ops;
+    }
+    /** Open the transaction and wipe the replica (but not sync_meta) so the fresh snapshot replaces it. */
+    begin() {
+        this.db.run("BEGIN");
+        // Mark open BEFORE truncate: once BEGIN succeeds the transaction is live, so abort() must be able
+        // to ROLLBACK it even if truncate throws mid-begin (else the txn leaks). CTC-132 review finding A.
+        this.open = true;
+        this.ops.truncate(this.db);
+    }
+    /** Apply one bounded batch of rows into the open transaction. */
+    batch(rows) {
+        if (!this.open)
+            throw new Error("seedBatch before seedBegin");
+        for (const rec of rows)
+            this.ops.apply(this.db, rec);
+    }
+    /** Persist the terminal cursor, then COMMIT the whole seed atomically. Returns the cursor. */
+    commit(cursor) {
+        if (!this.open)
+            throw new Error("seedCommit before seedBegin");
+        this.ops.setCursor(this.db, cursor);
+        this.db.run("COMMIT");
+        this.open = false;
+        return cursor;
+    }
+    /** Roll back a partial seed on error — leaves the prior cursor (sync_meta) intact. Idempotent. */
+    abort() {
+        if (this.open) {
+            try {
+                this.db.run("ROLLBACK");
+            }
+            catch {
+                // ROLLBACK can throw if the txn already aborted — swallow so the original error surfaces.
+            }
+            this.open = false;
+        }
+    }
+}
+//# sourceMappingURL=seed-session.js.map

package/dist/replica/browser/seed-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-session.js","sourceRoot":"","sources":["../../../src/replica/browser/seed-session.ts"],"names":[],"mappings":"AAAA,uGAAuG;AACvG,EAAE;AACF,sGAAsG;AACtG,qGAAqG;AACrG,oGAAoG;AACpG,gGAAgG;AAChG,sGAAsG;AACtG,gDAAgD;AAChD,EAAE;AACF,uGAAuG;AACvG,6EAA6E;AAY7E,MAAM,OAAO,WAAW;IAIH;IACA;IAJX,IAAI,GAAG,KAAK,CAAC;IAErB,YACmB,EAAa,EACb,GAAY;QADZ,OAAE,GAAF,EAAE,CAAW;QACb,QAAG,GAAH,GAAG,CAAS;IAC5B,CAAC;IAEJ,uGAAuG;IACvG,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrB,kGAAkG;QAClG,mGAAmG;QACnG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,IAAkB;QACtB,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC9D,KAAK,MAAM,GAAG,IAAI,IAAI;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACvD,CAAC;IAED,8FAA8F;IAC9F,MAAM,CAAC,MAAc;QACnB,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAC/D,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,kGAAkG;IAClG,KAAK;QACH,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC;gBACH,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC1B,CAAC;YAAC,MAAM,CAAC;gBACP,0FAA0F;YAC5F,CAAC;YACD,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;CACF"}

package/dist/replica/browser/snapshot-stream.d.ts

@@ -0,0 +1,24 @@
+import type { WireChange } from "./protocol.js";
+/** One server /snapshot page; the memory/round-trip knob (mirrors the server-side PAGE_SIZE, CTC-63). */
+export declare const SEED_BATCH_ROWS = 1000;
+/** A yielded item: a bounded batch of rows, or the terminal cursor (always the LAST item). */
+export type SnapshotItem = {
+    kind: "batch";
+    rows: WireChange[];
+} | {
+    kind: "cursor";
+    cursor: number;
+};
+/**
+ * Decode a /snapshot NDJSON body stream into bounded batches of `WireChange` rows, yielding a final
+ * `{kind:"cursor"}` item once the terminal cursor line is seen. Throws if the stream ends before a
+ * terminal cursor line (a truncated snapshot must not be mistaken for a complete one).
+ *
+ * At most `batchSize` rows plus the current partial line are held in memory at any moment.
+ */
+export declare function streamSnapshotBatches(body: ReadableStream<Uint8Array>, batchSize?: number, 
+/** Fired after every non-terminal `read()` — i.e. whenever the body actually delivered bytes. The
+ *  seed's idle timeout re-arms on this, which is what distinguishes a slow-but-live ~100 MB snapshot
+ *  from a stalled one. Optional, so every existing caller compiles unchanged. */
+onChunk?: () => void): AsyncGenerator<SnapshotItem>;
+//# sourceMappingURL=snapshot-stream.d.ts.map

package/dist/replica/browser/snapshot-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-stream.d.ts","sourceRoot":"","sources":["../../../src/replica/browser/snapshot-stream.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,yGAAyG;AACzG,eAAO,MAAM,eAAe,OAAO,CAAC;AAepC,8FAA8F;AAC9F,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,UAAU,EAAE,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAOvC;;;;;;GAMG;AACH,wBAAuB,qBAAqB,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,SAAS,GAAE,MAAwB;AACnC;;iFAEiF;AACjF,OAAO,CAAC,EAAE,MAAM,IAAI,GACnB,cAAc,CAAC,YAAY,CAAC,CA4E9B"}

package/dist/replica/browser/snapshot-stream.js

@@ -0,0 +1,113 @@
+// replica/snapshot-stream.ts — a pure, unit-testable streaming decoder for the /snapshot NDJSON feed
+// (CTC-132). It turns the response `ReadableStream<Uint8Array>` into BOUNDED batches of parsed
+// `WireChange` rows plus the terminal cursor, decoding incrementally with `TextDecoder({stream:true})`
+// and buffering only the current partial line — never the whole body, never a whole-array parse.
+//
+// This is the browser consumer's OOM fix: the old path did `await res.text()` on the ~74 MB body, then
+// `body.split("\n")` + a `JSON.parse` per line into a 44.5k-element array, then structured-cloned that
+// whole array across `postMessage`. Here at most `batchSize` rows (plus the current partial line) are
+// resident at once, so peak memory is O(batch), not O(snapshot).
+//
+// No OPFS / Worker import lives here on purpose — the module stays runtime-agnostic and tree-shakes
+// cleanly, and is fully covered in vitest/jsdom (test/snapshot-stream.test.ts).
+import { requirePositiveInt } from "./validate.js";
+/** One server /snapshot page; the memory/round-trip knob (mirrors the server-side PAGE_SIZE, CTC-63). */
+export const SEED_BATCH_ROWS = 1000;
+/** Discriminate the two wire line shapes on a numeric `cursor` field (the terminal line carries it). */
+function isCursorLine(o) {
+    return typeof o.cursor === "number";
+}
+/**
+ * Decode a /snapshot NDJSON body stream into bounded batches of `WireChange` rows, yielding a final
+ * `{kind:"cursor"}` item once the terminal cursor line is seen. Throws if the stream ends before a
+ * terminal cursor line (a truncated snapshot must not be mistaken for a complete one).
+ *
+ * At most `batchSize` rows plus the current partial line are held in memory at any moment.
+ */
+export async function* streamSnapshotBatches(body, batchSize = SEED_BATCH_ROWS, 
+/** Fired after every non-terminal `read()` — i.e. whenever the body actually delivered bytes. The
+ *  seed's idle timeout re-arms on this, which is what distinguishes a slow-but-live ~100 MB snapshot
+ *  from a stalled one. Optional, so every existing caller compiles unchanged. */
+onChunk) {
+    // Validate BEFORE reading a byte (CTC-114 review round 12). This helper is exported from
+    // `@catalyst-cloud/sdk/browser`, so `batchSize` is consumer-supplied. `NaN`/`Infinity` make
+    // `batch.length >= batchSize` permanently false, so no batch is ever yielded: every parsed row of a
+    // ~100 MB snapshot accumulates and is finally structured-cloned across the worker boundary in one
+    // message. The bounded-memory guarantee this module exists for would be gone, silently — and an OOM
+    // is exactly what CTC-132 introduced streaming to prevent.
+    requirePositiveInt("streamSnapshotBatches", "batchSize", batchSize);
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    let batch = [];
+    let sawCursor = false;
+    let cursor = 0;
+    // Parse one complete line. Data lines accumulate into `batch`; the terminal cursor line records the
+    // cursor. Returns a full batch to yield when the batch reaches `batchSize`, else null.
+    const handleLine = (line) => {
+        if (line.length === 0)
+            return null; // skip blank lines
+        const o = JSON.parse(line);
+        if (isCursorLine(o)) {
+            sawCursor = true;
+            cursor = o.cursor;
+            return null;
+        }
+        batch.push({ entity: o.entity, op: o.op, row: o.row });
+        if (batch.length >= batchSize) {
+            const full = batch;
+            batch = [];
+            return { kind: "batch", rows: full };
+        }
+        return null;
+    };
+    let completed = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            onChunk?.();
+            buf += decoder.decode(value, { stream: true });
+            let nl;
+            while ((nl = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                const emit = handleLine(line);
+                if (emit)
+                    yield emit;
+            }
+        }
+        // Flush any final line with no trailing newline (plus any bytes the decoder was still holding).
+        const tail = (buf + decoder.decode()).trim();
+        if (tail.length > 0) {
+            const emit = handleLine(tail);
+            if (emit)
+                yield emit;
+        }
+        // Emit the last partial batch before the cursor so the cursor is always the FINAL yielded item.
+        if (batch.length > 0)
+            yield { kind: "batch", rows: batch };
+        if (!sawCursor)
+            throw new Error("/snapshot stream ended without a terminal cursor line");
+        yield { kind: "cursor", cursor };
+        completed = true;
+    }
+    finally {
+        // On any ABNORMAL exit — a parse throw, a downstream `seedBatch` rejection, or an early consumer
+        // `return`/`break` — CANCEL the body so the ~74 MB /snapshot response and its Durable Object
+        // generator stop draining server-side; releaseLock alone leaves the underlying fetch stream live
+        // (CTC-132 review finding C). On normal completion the stream is already drained, so we only
+        // release the lock. reader.cancel() keeps the lock, so releaseLock() still runs on every path.
+        if (!completed) {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // The stream already errored/closed — nothing left to cancel; fall through to releaseLock.
+            }
+        }
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=snapshot-stream.js.map