@catalyst-cloud/sdk 0.1.0 → 0.2.0

package/dist/replica/catalyst-replica.d.ts

@@ -0,0 +1,153 @@
+import { type SqlExecutor, type IssueView, type IssueDetailView, type PullView, type ProjectView, type ProjectDetailView, type InitiativeView, type InitiativeDetailView } from "@catalyst-cloud/read-model";
+import { type AuthStrategy, type LiveSyncStatus, type LogLevel, type WebSocketFactory } from "../live-sync-client.js";
+import { type EngineFactory, type ReplicaEngine } from "./engine.js";
+import { type WriterGuardOptions } from "./writer-lock.js";
+export interface CatalystReplicaOptions {
+    /** http(s) origin incl. any path prefix (…/api/v1); the scheme is swapped to ws(s) for /connect. */
+    baseUrl: string;
+    /** Tenant id = mirror name → `?account=` on every feed request. */
+    account: string;
+    /** How to authorize: {kind:'token',token} (host bearer rides /connect as ?token= and /snapshot as
+     *  Authorization) | {kind:'cookie'} (same-origin session cookie). */
+    auth: AuthStrategy;
+    /** File path or ':memory:'. */
+    dbPath: string;
+    /** INJECTED sqlite engine, or a factory over dbPath. Default = auto-detect (bun:sqlite, else node:sqlite). */
+    engine?: ReplicaEngine | EngineFactory;
+    /** The connect route. Default '/connect'. */
+    connectPath?: string;
+    /** Snapshot/changes fetch. Default global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Fired after each applied delta (live frame OR a completed seed) — a refetch hook. */
+    onChange?: () => void;
+    /** Connection lifecycle, for UI/logging. */
+    onStatus?: (status: LiveSyncStatus) => void;
+    /** Base reconnect backoff in ms. Default 1000. */
+    backoffMs?: number;
+    /** Reconnect backoff ceiling in ms. Default 30_000. */
+    maxBackoffMs?: number;
+    /** Injectable WebSocket factory (tests). Defaults to the runtime global WebSocket. */
+    wsFactory?: WebSocketFactory;
+    /** Optional structured logger; defaults to console. */
+    log?: (level: LogLevel, msg: string, extra?: unknown) => void;
+    /**
+     * Single-writer guard (a sidecar `dbPath + '.writer.lock'`). On `start()` the writer best-effort
+     * claims sole ownership of the file; a second LIVE writer on the same path makes `start()` throw a
+     * clear error (single-writer/many-reader, ADR-0008). Advisory, not a hard OS lock; a no-op for
+     * `:memory:`. Default: enabled. Set `{ disabled: true }` to skip, `{ override: true }` to steal.
+     */
+    writerGuard?: WriterGuardOptions;
+}
+/**
+ * Options for a READ-ONLY reader ({@link CatalystReplica.openReadOnly}). A reader needs only the file
+ * path (+ optional injected engine / logger): no `baseUrl`, `account`, or `auth`, because it opens NO
+ * socket and pulls NO snapshot.
+ */
+export interface CatalystReplicaReadOnlyOptions {
+    /** File path to an EXISTING writer-seeded replica. `:memory:` makes no sense for a reader (a fresh,
+     *  empty, per-connection DB) and is rejected. */
+    dbPath: string;
+    /** INJECTED read-only sqlite engine or a factory over dbPath. Default = auto-detect READ-ONLY
+     *  (bun:sqlite/node:sqlite opened `{ readonly: true }`). Pass a writable engine at your own risk. */
+    engine?: ReplicaEngine | EngineFactory;
+    /** Optional structured logger; defaults to console. */
+    log?: (level: LogLevel, msg: string, extra?: unknown) => void;
+}
+export declare class CatalystReplica {
+    private readonly opts;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly log;
+    private engine;
+    private writeDb;
+    private sqlExecutor;
+    private client;
+    /** In-memory high-water of the last seq persisted, so each frame avoids re-reading the cursor row. */
+    private highWater;
+    private _status;
+    private started;
+    private closed;
+    /** READ-ONLY mode (opened via {@link CatalystReplica.openReadOnly}): no migrations, no seed, no
+     *  socket; `start()` is a no-op and the write path is unreachable. */
+    private readonlyMode;
+    /** The claimed single-writer lock (writers only; null for readers / `:memory:` / disabled). */
+    private writerLock;
+    /** Resolved on the first 'live' status (start() = caught-up + ready to read); rejected on close /
+     *  an initial seed failure. */
+    private liveResolve;
+    private liveReject;
+    constructor(opts: CatalystReplicaOptions);
+    /**
+     * Open a CatalystReplica as a READ-ONLY READER over a file another process owns as the WRITER
+     * (single-writer/many-reader, ADR-0008). The sqlite handle is opened read-only (`{ readonly: true }`
+     * + `busy_timeout`), so the reader runs NO migrations, pulls NO /snapshot, opens NO LiveSyncClient,
+     * and the write path is unreachable — it only serves the synchronous `build*View` reads, `.sql`,
+     * `.handle`, and `.cursor` off whatever the writer has already persisted. There is no live tailing:
+     * the reader sees the file's committed state at read time (a fresh `issues()` re-queries, so it
+     * reflects the writer's latest committed rows).
+     *
+     * Async because the default engine dynamic-imports its sqlite driver; once it resolves the replica
+     * is already open, so `start()` on the returned reader is a no-op.
+     */
+    static openReadOnly(opts: CatalystReplicaReadOnlyOptions): Promise<CatalystReplica>;
+    /**
+     * Open + migrate the replica, then open the live socket. Resolves when the replica is caught-up and
+     * ready to read (first 'live'); background sync continues until close(). A cold tenant stream-seeds
+     * /snapshot first (via the injected reseed inside LiveSyncClient.start), so 'live' implies
+     * seed-complete. NOTE: there is no built-in timeout — a stalled /snapshot or unreachable host can
+     * delay 'live'; drive progress via onStatus.
+     */
+    start(): Promise<void>;
+    /** Stop the socket, release the writer lock, close the DB. Idempotent. Rejects a still-pending
+     *  start(). On a reader: no socket/lock to release — just closes the read-only handle. */
+    close(): Promise<void>;
+    /** The read-model SqlExecutor over the replica. `buildIssuesView(replica.sql, …)` is unchanged. */
+    get sql(): SqlExecutor;
+    issues(opts?: {
+        limit?: number;
+        offset?: number;
+    }): IssueView[];
+    issue(identifier: string): IssueDetailView | null;
+    pulls(opts?: {
+        limit?: number;
+        offset?: number;
+    }): PullView[];
+    projects(opts?: {
+        limit?: number;
+        offset?: number;
+    }): ProjectView[];
+    project(id: string): ProjectDetailView | null;
+    initiatives(opts?: {
+        limit?: number;
+        offset?: number;
+    }): InitiativeView[];
+    initiative(id: string): InitiativeDetailView | null;
+    /** The durable change-feed cursor (sync_meta), or null before the first seed. */
+    get cursor(): number | null;
+    /** The connection lifecycle status. */
+    get status(): LiveSyncStatus;
+    /** The raw driver Database the SDK owns — for `drizzle(replica.handle, { schema: mirrorSchema })`. */
+    get handle(): unknown;
+    private resolveEngine;
+    /**
+     * Open the read-only engine and wire ONLY the read ports — no migrations, no `sync_meta` DDL, no
+     * snapshot, no LiveSyncClient. The write-facing `writeDb` is a read-capable shim whose `run` throws,
+     * so reads (`sql`/`build*View`/`cursor`) work but any accidental write path is unreachable AND the
+     * underlying sqlite handle is itself read-only.
+     */
+    private openReadOnlyInternal;
+    private handleStatus;
+    private clearLiveDeferred;
+    /** Land one delta + advance the durable cursor atomically (a crash can't skip a seq), then signal. */
+    private applyFrame;
+    /**
+     * Stream-seed the replica from /snapshot and return the fresh cursor. Streams `response.body` as
+     * NDJSON (chunked, batched transactions) so a large tenant never materializes the whole snapshot in
+     * memory — the OOM fix vs host-sync's buffered seed. The cursor row is DELETED up front so an
+     * interrupted seed self-heals (getCursor → null → re-seed on the next start), preserving host-sync's
+     * atomic truncate+apply+setCursor safety without holding one giant transaction.
+     */
+    private seedFromSnapshot;
+    private feedHeaders;
+}
+//# sourceMappingURL=catalyst-replica.d.ts.map

package/dist/replica/catalyst-replica.d.ts.map

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

package/dist/replica/catalyst-replica.js

@@ -0,0 +1,409 @@
+// @catalyst-cloud/sdk/node — CatalystReplica: host-sync's writer + read seam behind ONE import.
+//
+// Composed from the published @catalyst-cloud/{schema,read-model,replicate} packages + the SDK's own
+// LiveSyncClient. It is the drop-in replacement for the hand-rolled writer loop in apps/host-sync
+// (apply.ts + sync-client.ts + live-client.ts + read-adapter.ts), now engine-generic:
+//
+//   start()  = open DB (injected engine, default bun:sqlite/node:sqlite auto-detect)
+//            → applyMigrations(MIRROR_MIGRATIONS) + sync_meta DDL
+//            → open LiveSyncClient: if cursor==null it STREAM-seeds /snapshot (the injected reseed),
+//              then replays {type:"sync", after:cursor}, applyDelta + cursor per frame; {type:"resync"}
+//              re-seeds. RESOLVES WHEN FIRST 'live' (caught-up + ready to read); background sync
+//              continues until close(). This is the deliberate fork from the raw transport's
+//              resolve-on-stop.
+//   reads    = SYNCHRONOUS over the read-model SqlExecutor (node/bun sqlite is sync). The
+//              `buildIssuesView(replica.sql, …)` calls are LITERALLY unchanged.
+//
+// Reads, writes, migrations, cursor and wire semantics are byte-identical to host-sync because this
+// runs the SAME @catalyst-cloud/read-model builders over the SAME @catalyst-cloud/replicate write path
+// and the SAME @catalyst-cloud/schema MIRROR_MIGRATIONS.
+import { applyMigrations, MIRROR_MIGRATIONS } from "@catalyst-cloud/schema";
+import { applyDelta, truncateReplica, getCursor, setCursor, } from "@catalyst-cloud/replicate";
+import { buildIssuesView, buildIssueDetail, buildPullsView, buildProjectsView, buildProjectDetail, buildInitiativesView, buildInitiativeDetail, } from "@catalyst-cloud/read-model";
+import { LiveSyncClient, stripTrailingSlashes, } from "../live-sync-client.js";
+import { autoDetectEngine, autoDetectReadonlyEngine, } from "./engine.js";
+import { claimWriterLock, } from "./writer-lock.js";
+/** Host-sync bookkeeping table (NOT part of the DO mirror schema, so not in MIRROR_MIGRATIONS): the
+ *  change-feed cursor, so a restart resumes from the live `{type:"sync", after}` replay (or /changes)
+ *  instead of a full /snapshot every boot. */
+const SYNC_META_DDL = `CREATE TABLE IF NOT EXISTS sync_meta (
+  key TEXT PRIMARY KEY, value TEXT
+);`;
+/** Rows per streamed seed transaction — bounds memory + fsync so a large tenant never OOMs the node/bun
+ *  process the way host-sync's buffered `await res.text()` + `split("\n")` snapshot would. */
+const SEED_BATCH_ROWS = 1000;
+export class CatalystReplica {
+    opts;
+    baseUrl;
+    fetchImpl;
+    log;
+    engine = null;
+    writeDb = null;
+    sqlExecutor = null;
+    client = null;
+    /** In-memory high-water of the last seq persisted, so each frame avoids re-reading the cursor row. */
+    highWater = 0;
+    _status = "connecting";
+    started = false;
+    closed = false;
+    /** READ-ONLY mode (opened via {@link CatalystReplica.openReadOnly}): no migrations, no seed, no
+     *  socket; `start()` is a no-op and the write path is unreachable. */
+    readonlyMode = false;
+    /** The claimed single-writer lock (writers only; null for readers / `:memory:` / disabled). */
+    writerLock = null;
+    /** Resolved on the first 'live' status (start() = caught-up + ready to read); rejected on close /
+     *  an initial seed failure. */
+    liveResolve = null;
+    liveReject = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.baseUrl = stripTrailingSlashes(opts.baseUrl);
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.log =
+            opts.log ??
+                ((lvl, msg, extra) => console[lvl === "error" ? "error" : "log"](`[catalyst-replica] ${msg}`, extra ?? ""));
+    }
+    /**
+     * Open a CatalystReplica as a READ-ONLY READER over a file another process owns as the WRITER
+     * (single-writer/many-reader, ADR-0008). The sqlite handle is opened read-only (`{ readonly: true }`
+     * + `busy_timeout`), so the reader runs NO migrations, pulls NO /snapshot, opens NO LiveSyncClient,
+     * and the write path is unreachable — it only serves the synchronous `build*View` reads, `.sql`,
+     * `.handle`, and `.cursor` off whatever the writer has already persisted. There is no live tailing:
+     * the reader sees the file's committed state at read time (a fresh `issues()` re-queries, so it
+     * reflects the writer's latest committed rows).
+     *
+     * Async because the default engine dynamic-imports its sqlite driver; once it resolves the replica
+     * is already open, so `start()` on the returned reader is a no-op.
+     */
+    static async openReadOnly(opts) {
+        if (!opts.dbPath || opts.dbPath === ":memory:" || opts.dbPath.startsWith("file::memory:")) {
+            throw new Error("CatalystReplica.openReadOnly: a reader needs a FILE path to a writer-seeded replica; " +
+                "':memory:' is a fresh per-connection DB with nothing to read.");
+        }
+        // Reuse the writer constructor with placeholders for the connect-only fields (never touched in
+        // read-only mode), then open the read-only engine eagerly.
+        const replica = new CatalystReplica({
+            baseUrl: "readonly://local",
+            account: "",
+            auth: { kind: "cookie" },
+            dbPath: opts.dbPath,
+            engine: opts.engine,
+            log: opts.log,
+        });
+        await replica.openReadOnlyInternal(opts);
+        return replica;
+    }
+    /**
+     * Open + migrate the replica, then open the live socket. Resolves when the replica is caught-up and
+     * ready to read (first 'live'); background sync continues until close(). A cold tenant stream-seeds
+     * /snapshot first (via the injected reseed inside LiveSyncClient.start), so 'live' implies
+     * seed-complete. NOTE: there is no built-in timeout — a stalled /snapshot or unreachable host can
+     * delay 'live'; drive progress via onStatus.
+     */
+    async start() {
+        // A reader is already open (openReadOnly opened the engine); start() is an inert no-op.
+        if (this.readonlyMode)
+            return;
+        if (this.closed)
+            throw new Error("CatalystReplica: start() after close()");
+        if (this.started)
+            throw new Error("CatalystReplica: start() already called");
+        this.started = true;
+        // Single-writer guard: claim sole ownership of the file BEFORE opening it, so a second concurrent
+        // writer rejects here instead of racing the cursor/seed. A no-op for ':memory:' or when disabled.
+        this.writerLock = claimWriterLock(this.opts.dbPath, this.opts.writerGuard ?? {}, this.log);
+        const engine = await this.resolveEngine();
+        this.engine = engine;
+        this.writeDb = {
+            run: (sql, ...bindings) => engine.run(sql, ...bindings),
+            get: (sql, ...bindings) => engine.get(sql, ...bindings),
+        };
+        this.sqlExecutor = {
+            exec: (query, ...bindings) => ({
+                toArray: () => engine.all(query, ...bindings.map(engine.toBindable)),
+            }),
+        };
+        // Migrate via the ~3-line MigrationDb adapter, then add the host-only cursor table.
+        const migrationDb = {
+            exec: (sql) => engine.exec(sql),
+            query: (sql) => engine.all(sql),
+        };
+        applyMigrations(migrationDb, MIRROR_MIGRATIONS);
+        engine.exec(SYNC_META_DDL);
+        this.highWater = getCursor(this.writeDb) ?? 0;
+        this.client = new LiveSyncClient({
+            baseUrl: this.baseUrl,
+            accountId: this.opts.account,
+            connectPath: this.opts.connectPath,
+            auth: this.opts.auth,
+            reseed: () => this.seedFromSnapshot(),
+            getCursor: () => getCursor(this.writeDb),
+            onChange: (frame) => this.applyFrame(frame),
+            onStatus: (status) => this.handleStatus(status),
+            backoffMs: this.opts.backoffMs,
+            maxBackoffMs: this.opts.maxBackoffMs,
+            wsFactory: this.opts.wsFactory,
+            log: this.log,
+        });
+        return new Promise((resolve, reject) => {
+            this.liveResolve = resolve;
+            this.liveReject = reject;
+            // The transport's start() resolves only on stop() ("runs forever"); we fork on first 'live'.
+            // Run it in the background and surface an initial seed/connect failure as a start() rejection.
+            void this.client.start().catch((err) => {
+                const rej = this.liveReject;
+                this.clearLiveDeferred();
+                rej?.(err);
+            });
+        });
+    }
+    /** Stop the socket, release the writer lock, close the DB. Idempotent. Rejects a still-pending
+     *  start(). On a reader: no socket/lock to release — just closes the read-only handle. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.client?.stop();
+        const rej = this.liveReject;
+        this.clearLiveDeferred();
+        rej?.(new Error("CatalystReplica: closed before first 'live'"));
+        try {
+            this.writerLock?.release();
+        }
+        catch (err) {
+            this.log("warn", "writer-lock release threw", err);
+        }
+        this.writerLock = null;
+        try {
+            this.engine?.close();
+        }
+        catch (err) {
+            this.log("warn", "engine close threw", err);
+        }
+    }
+    // ── Reads ───────────────────────────────────────────────────────────────────────────────────────
+    /** The read-model SqlExecutor over the replica. `buildIssuesView(replica.sql, …)` is unchanged. */
+    get sql() {
+        if (!this.sqlExecutor)
+            throw new Error("CatalystReplica: call start() before reading");
+        return this.sqlExecutor;
+    }
+    issues(opts) {
+        return buildIssuesView(this.sql, opts?.limit, opts?.offset);
+    }
+    issue(identifier) {
+        return buildIssueDetail(this.sql, identifier);
+    }
+    pulls(opts) {
+        return buildPullsView(this.sql, opts?.limit, opts?.offset);
+    }
+    projects(opts) {
+        return buildProjectsView(this.sql, opts?.limit, opts?.offset);
+    }
+    project(id) {
+        return buildProjectDetail(this.sql, id);
+    }
+    initiatives(opts) {
+        return buildInitiativesView(this.sql, opts?.limit, opts?.offset);
+    }
+    initiative(id) {
+        return buildInitiativeDetail(this.sql, id);
+    }
+    /** The durable change-feed cursor (sync_meta), or null before the first seed. */
+    get cursor() {
+        return this.writeDb ? getCursor(this.writeDb) : null;
+    }
+    /** The connection lifecycle status. */
+    get status() {
+        return this._status;
+    }
+    /** The raw driver Database the SDK owns — for `drizzle(replica.handle, { schema: mirrorSchema })`. */
+    get handle() {
+        return this.engine?.handle;
+    }
+    // ── Internals ─────────────────────────────────────────────────────────────────────────────────
+    async resolveEngine() {
+        const e = this.opts.engine;
+        if (e === undefined)
+            return autoDetectEngine(this.opts.dbPath);
+        if (typeof e === "function")
+            return e(this.opts.dbPath);
+        return e;
+    }
+    /**
+     * Open the read-only engine and wire ONLY the read ports — no migrations, no `sync_meta` DDL, no
+     * snapshot, no LiveSyncClient. The write-facing `writeDb` is a read-capable shim whose `run` throws,
+     * so reads (`sql`/`build*View`/`cursor`) work but any accidental write path is unreachable AND the
+     * underlying sqlite handle is itself read-only.
+     */
+    async openReadOnlyInternal(opts) {
+        this.readonlyMode = true;
+        this.started = true; // already open → start() is a no-op
+        const e = opts.engine;
+        const engine = e === undefined
+            ? await autoDetectReadonlyEngine(opts.dbPath)
+            : typeof e === "function"
+                ? await e(opts.dbPath)
+                : e;
+        this.engine = engine;
+        this.sqlExecutor = {
+            exec: (query, ...bindings) => ({
+                toArray: () => engine.all(query, ...bindings.map(engine.toBindable)),
+            }),
+        };
+        // Read-capable cursor access; `run` is poisoned so the write path can never fire on a reader.
+        this.writeDb = {
+            get: (sql, ...bindings) => engine.get(sql, ...bindings),
+            run: () => {
+                throw new Error("CatalystReplica: this replica is READ-ONLY (opened via openReadOnly)");
+            },
+        };
+        this._status = "live"; // a reader is "live" the moment it is open (it has no socket)
+    }
+    handleStatus(status) {
+        this._status = status;
+        if (status === "live" && this.liveResolve) {
+            const res = this.liveResolve;
+            this.clearLiveDeferred();
+            res();
+        }
+        try {
+            this.opts.onStatus?.(status);
+        }
+        catch (err) {
+            this.log("warn", "onStatus handler threw", err);
+        }
+    }
+    clearLiveDeferred() {
+        this.liveResolve = null;
+        this.liveReject = null;
+    }
+    /** Land one delta + advance the durable cursor atomically (a crash can't skip a seq), then signal. */
+    applyFrame(frame) {
+        const engine = this.engine;
+        const writeDb = this.writeDb;
+        if (!engine || !writeDb)
+            return;
+        try {
+            engine.transaction(() => {
+                applyDelta(writeDb, { entity: frame.entity, op: frame.op, row: frame.row ?? {}, entityId: frame.entityId }, engine.toBindable);
+                // Advance to the seq we SAW (not just applied), so a stale-but-newer-seq delta still moves the
+                // cursor forward and a reconnect doesn't re-request it.
+                if (frame.seq > this.highWater)
+                    setCursor(writeDb, frame.seq, engine.toBindable);
+            });
+            if (frame.seq > this.highWater)
+                this.highWater = frame.seq;
+            try {
+                this.opts.onChange?.();
+            }
+            catch (err) {
+                this.log("warn", "onChange handler threw", err);
+            }
+        }
+        catch (err) {
+            this.log("error", `apply failed for ${frame.entity} seq=${frame.seq}`, err);
+        }
+    }
+    /**
+     * Stream-seed the replica from /snapshot and return the fresh cursor. Streams `response.body` as
+     * NDJSON (chunked, batched transactions) so a large tenant never materializes the whole snapshot in
+     * memory — the OOM fix vs host-sync's buffered seed. The cursor row is DELETED up front so an
+     * interrupted seed self-heals (getCursor → null → re-seed on the next start), preserving host-sync's
+     * atomic truncate+apply+setCursor safety without holding one giant transaction.
+     */
+    async seedFromSnapshot() {
+        const engine = this.engine;
+        const writeDb = this.writeDb;
+        const url = `${this.baseUrl}/snapshot?account=${encodeURIComponent(this.opts.account)}`;
+        const res = await this.fetchImpl(url, { headers: this.feedHeaders() });
+        if (!res.ok)
+            throw new Error(`/snapshot ${res.status}`);
+        // Invalidate the cursor BEFORE truncating so a crash mid-seed re-seeds rather than going live over
+        // an empty replica from a stale cursor.
+        engine.run("DELETE FROM sync_meta WHERE key = 'cursor'");
+        engine.transaction(() => truncateReplica(writeDb));
+        let cursor = 0;
+        let batch = [];
+        const flush = () => {
+            if (batch.length === 0)
+                return;
+            const rows = batch;
+            batch = [];
+            engine.transaction(() => {
+                for (const rec of rows) {
+                    if (rec.entity === undefined)
+                        continue;
+                    applyDelta(writeDb, { entity: rec.entity, op: rec.op ?? "upsert", row: rec.row ?? {} }, engine.toBindable);
+                }
+            });
+        };
+        let rowCount = 0;
+        for await (const line of iterateNdjson(res)) {
+            const rec = JSON.parse(line);
+            if (typeof rec.cursor === "number") {
+                cursor = rec.cursor; // the FINAL line carries the cursor
+                continue;
+            }
+            batch.push(rec);
+            rowCount++;
+            if (batch.length >= SEED_BATCH_ROWS)
+                flush();
+        }
+        flush();
+        engine.transaction(() => setCursor(writeDb, cursor, engine.toBindable));
+        this.highWater = cursor;
+        this.log("info", `snapshot seeded (${rowCount} rows), cursor=${cursor}`);
+        try {
+            this.opts.onChange?.();
+        }
+        catch (err) {
+            this.log("warn", "onChange handler threw", err);
+        }
+        return cursor;
+    }
+    feedHeaders() {
+        const h = { accept: "application/x-ndjson" };
+        if (this.opts.auth.kind === "token")
+            h["authorization"] = `Bearer ${this.opts.auth.token}`;
+        return h;
+    }
+}
+/**
+ * Iterate an NDJSON Response as non-empty lines. Streams `response.body` (chunked + partial-line
+ * buffered) when present — the production path that never buffers the whole snapshot; falls back to a
+ * buffered `await res.text()` when the body is absent (e.g. a test fetch stand-in).
+ */
+async function* iterateNdjson(res) {
+    const body = res.body;
+    if (body && typeof body.getReader === "function") {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            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);
+                if (line.length > 0)
+                    yield line;
+            }
+        }
+        buf += decoder.decode();
+        if (buf.length > 0) {
+            for (const line of buf.split("\n"))
+                if (line.length > 0)
+                    yield line;
+        }
+        return;
+    }
+    const text = await res.text();
+    for (const line of text.split("\n"))
+        if (line.length > 0)
+            yield line;
+}
+//# sourceMappingURL=catalyst-replica.js.map

package/dist/replica/catalyst-replica.js.map

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

package/dist/replica/engine.d.ts

@@ -0,0 +1,67 @@
+/** A bindable SQLite scalar on the node/bun side (booleans stored as 0/1 INTEGER; blobs as Uint8Array). */
+export type EngineBindable = string | number | bigint | null | Uint8Array;
+/**
+ * The portable sqlite engine the SDK owns and adapts. Generic over the bindable type `B` so a driver
+ * that binds binary/bigint differently can declare its own; the node/bun builtins use `EngineBindable`.
+ */
+export interface ReplicaEngine<B = unknown> {
+    /** Execute DDL / migration statement(s) for side effect (no rows). */
+    exec(sql: string): void;
+    /** Run a parameterized SELECT → rows as plain objects (reads + the migration ledger). */
+    all(sql: string, ...bindings: B[]): Record<string, B>[];
+    /** Run a parameterized mutation → sqlite3_changes() (rows written). */
+    run(sql: string, ...bindings: B[]): number;
+    /** Run a single-row query → the first row, or undefined. */
+    get(sql: string, ...bindings: B[]): Record<string, B> | undefined;
+    /** Run `fn` inside one atomic transaction (snapshot-seed batch / delta apply). */
+    transaction<T>(fn: () => T): T;
+    /** Coerce ONE wire JSON value to an engine-bindable scalar (bool → 0/1, blob/bigint per engine). */
+    toBindable: (value: unknown) => B;
+    /** Close the underlying database handle. */
+    close(): void;
+}
+/** A factory that opens a `ReplicaEngine` over `dbPath`. May be async (drivers are dynamic-imported). */
+export type EngineFactory = (dbPath: string) => ReplicaEngine | Promise<ReplicaEngine>;
+/** A `ReplicaEngine` plus the raw driver `handle` (exposed via CatalystReplica.handle for drizzle). */
+export type ReplicaEngineWithHandle = ReplicaEngine<EngineBindable> & {
+    readonly handle: unknown;
+};
+export declare function bunSqliteEngine(dbPath: string): Promise<ReplicaEngineWithHandle>;
+/** Read-only `bun:sqlite` engine (`{ readonly: true }` + `busy_timeout`). See {@link openBun}. */
+export declare function bunSqliteReadonlyEngine(dbPath: string): Promise<ReplicaEngineWithHandle>;
+export declare function nodeSqliteEngine(dbPath: string): Promise<ReplicaEngineWithHandle>;
+/** Read-only `node:sqlite` engine (`{ readOnly: true }` + `busy_timeout`). See {@link openNode}. */
+export declare function nodeSqliteReadonlyEngine(dbPath: string): Promise<ReplicaEngineWithHandle>;
+/** A statement handle the `better-sqlite3` default export hands back (typed structurally — no import). */
+interface BetterSqlite3Statement {
+    all(...bindings: unknown[]): unknown[];
+    get(...bindings: unknown[]): unknown;
+    run(...bindings: unknown[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+}
+/** The `better-sqlite3` Database surface this engine uses (typed structurally — no import / no peer pin). */
+interface BetterSqlite3Database {
+    prepare(sql: string): BetterSqlite3Statement;
+    exec(sql: string): void;
+    pragma(source: string): unknown;
+    transaction<Args extends unknown[], R>(fn: (...args: Args) => R): (...args: Args) => R;
+    close(): void;
+}
+/** `import Database from "better-sqlite3"` is structurally assignable to this constructor type. */
+export type BetterSqlite3Driver = new (path?: string, options?: unknown) => BetterSqlite3Database;
+export declare function betterSqlite3Engine(driver: BetterSqlite3Driver, dbPath: string): ReplicaEngineWithHandle;
+/** Read-only `better-sqlite3` engine (`{ readonly: true }` + `busy_timeout`). See {@link openBetter}. */
+export declare function betterSqlite3ReadonlyEngine(driver: BetterSqlite3Driver, dbPath: string): ReplicaEngineWithHandle;
+/**
+ * Auto-detect the default engine when `opts.engine` is omitted: Bun → `bunSqliteEngine`; else
+ * `node:sqlite` if available → `nodeSqliteEngine`; else throw a clear "pass opts.engine" error rather
+ * than pick an engine that resolves but breaks on first write.
+ */
+export declare function autoDetectEngine(dbPath: string): Promise<ReplicaEngineWithHandle>;
+/** READ-ONLY counterpart of {@link autoDetectEngine}: Bun → `bunSqliteReadonlyEngine`; else
+ *  `nodeSqliteReadonlyEngine`. Used by `CatalystReplica.openReadOnly` when no engine is injected. */
+export declare function autoDetectReadonlyEngine(dbPath: string): Promise<ReplicaEngineWithHandle>;
+export {};
+//# sourceMappingURL=engine.d.ts.map