@catalyst-cloud/sdk 0.1.0 → 0.2.0

package/dist/replica/engine.d.ts.map

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

package/dist/replica/engine.js

@@ -0,0 +1,216 @@
+// @catalyst-cloud/sdk/node — the portable sqlite ENGINE seam + the injected driver factories.
+//
+// CatalystReplica never statically imports a sqlite driver: that is how it avoids hard-depping one.
+// It defines one tiny portable `ReplicaEngine` — the union of replicate's `ReplicaWriteDb` (run/get),
+// read-model's `SqlExecutor` (all), and schema's `MigrationDb` (exec/query) primitives, plus a
+// per-engine `toBindable` (wire JSON → engine-bindable) and `transaction`/`close`. CatalystReplica
+// adapts THIS one object into the three ports it needs.
+//
+// Drivers are INJECTED, not imported. The SDK ships three factory adapters, each dynamic-import()ing
+// its driver only when called:
+//   • bunSqliteEngine(dbPath)        — `await import("bun:sqlite")` (runtime builtin → never in package.json)
+//   • nodeSqliteEngine(dbPath)       — `await import("node:sqlite")` { DatabaseSync } (Node >=22.5, builtin)
+//   • betterSqlite3Engine(driver, …) — the consumer passes `import Database from "better-sqlite3"`
+//     (an OPTIONAL peer, never statically imported here).
+// Any other driver (D1, sql.js, …) is supported by passing a custom `ReplicaEngine`.
+// Load RUNTIME-BUILTIN drivers (`bun:sqlite` / `node:sqlite`) via `createRequire`, NOT a literal
+// `import("…")`. Vite/vitest and esbuild rewrite (and break) a literal dynamic import of a builtin —
+// they strip the `node:`/`bun:` prefix and fail to resolve a bare `sqlite`; and a `new Function`
+// import throws "dynamic import callback was not specified" under node ESM. `require` of a builtin is
+// untouched by the bundler and resolves natively on both node and Bun. This keeps the drivers OUT of
+// package.json (they are platform builtins) and loaded only when a factory is called.
+import { createRequire } from "node:module";
+const requireBuiltin = createRequire(import.meta.url);
+/** Require a RUNTIME-BUILTIN driver module; the type is supplied by the caller via `typeof import(...)`. */
+function importBuiltin(specifier) {
+    return Promise.resolve(requireBuiltin(specifier));
+}
+/** Coerce a wire JSON value to a node/bun-bindable scalar. Booleans → 0/1, blobs → Uint8Array, nested
+ *  object/array → JSON text (DO rows are flat scalars; this just keeps one odd field from wedging sync). */
+function toBindable(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "bigint")
+        return value;
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    return JSON.stringify(value);
+}
+/** Fold a driver into the portable engine. `all`/`run`/`get` re-prepare per call (bounded read path,
+ *  and applyDelta's SQL varies per row anyway, so statement caching would not help). */
+function makeEngine(driver) {
+    return {
+        handle: driver.handle,
+        exec: (sql) => driver.exec(sql),
+        all: (sql, ...bindings) => driver.prepare(sql).all(...bindings),
+        run: (sql, ...bindings) => driver.prepare(sql).run(...bindings),
+        get: (sql, ...bindings) => driver.prepare(sql).get(...bindings),
+        transaction: (fn) => driver.transaction(fn),
+        toBindable,
+        close: () => driver.close(),
+    };
+}
+/**
+ * `bun:sqlite` engine. `db.query(sql)` prepares; `.run().changes` is the write count; WAL keeps
+ * concurrent readers non-blocking. `bun:sqlite` is a Bun runtime builtin → dynamic-imported, never a
+ * package.json dependency.
+ *
+ * The WRITER opens read-write + WAL. The READER (`readonly`) opens `{ readonly: true }` and sets
+ * `busy_timeout = 250` instead of WAL — exactly how CTL's replica-read.mjs opens the same file: under
+ * the single-writer/many-reader topology (ADR-0008) a checkpoint can briefly hold the lock, so a
+ * reader waits a beat rather than failing. A readonly handle runs NO migrations and rejects writes at
+ * the sqlite layer.
+ */
+async function openBun(dbPath, readonly) {
+    const { Database } = await importBuiltin("bun:sqlite");
+    const db = readonly ? new Database(dbPath, { readonly: true }) : new Database(dbPath);
+    try {
+        db.run(readonly ? "PRAGMA busy_timeout = 250" : "PRAGMA journal_mode = WAL");
+    }
+    catch {
+        // :memory: rejects WAL on some builds; busy_timeout is harmless either way.
+    }
+    return makeEngine({
+        handle: db,
+        exec: (sql) => db.exec(sql),
+        prepare: (sql) => {
+            const st = db.query(sql);
+            return {
+                all: (...b) => st.all(...b),
+                get: (...b) => (st.get(...b) ?? undefined),
+                run: (...b) => st.run(...b).changes,
+            };
+        },
+        transaction: (fn) => db.transaction(fn)(),
+        close: () => db.close(),
+    });
+}
+export function bunSqliteEngine(dbPath) {
+    return openBun(dbPath, false);
+}
+/** Read-only `bun:sqlite` engine (`{ readonly: true }` + `busy_timeout`). See {@link openBun}. */
+export function bunSqliteReadonlyEngine(dbPath) {
+    return openBun(dbPath, true);
+}
+/**
+ * `node:sqlite` engine (Node >=22.5; may need `--experimental-sqlite` on some 22.x). `DatabaseSync`
+ * has no `.transaction()` helper, so we wrap BEGIN/COMMIT/ROLLBACK. Also a runtime builtin → never a
+ * package.json dependency. The `readonly` variant opens `{ readOnly: true }` (node:sqlite's spelling)
+ * + `busy_timeout`; see {@link openBun} for the read-only rationale.
+ */
+async function openNode(dbPath, readonly) {
+    const { DatabaseSync } = await importBuiltin("node:sqlite");
+    const db = readonly ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
+    try {
+        db.exec(readonly ? "PRAGMA busy_timeout = 250" : "PRAGMA journal_mode = WAL");
+    }
+    catch {
+        // :memory: cannot WAL — harmless; busy_timeout is allowed on a readonly handle.
+    }
+    return makeEngine({
+        handle: db,
+        exec: (sql) => db.exec(sql),
+        prepare: (sql) => {
+            const st = db.prepare(sql);
+            return {
+                all: (...b) => st.all(...b),
+                get: (...b) => (st.get(...b) ?? undefined),
+                run: (...b) => Number(st.run(...b).changes),
+            };
+        },
+        transaction: (fn) => {
+            db.exec("BEGIN");
+            try {
+                const out = fn();
+                db.exec("COMMIT");
+                return out;
+            }
+            catch (err) {
+                db.exec("ROLLBACK");
+                throw err;
+            }
+        },
+        close: () => db.close(),
+    });
+}
+export function nodeSqliteEngine(dbPath) {
+    return openNode(dbPath, false);
+}
+/** Read-only `node:sqlite` engine (`{ readOnly: true }` + `busy_timeout`). See {@link openNode}. */
+export function nodeSqliteReadonlyEngine(dbPath) {
+    return openNode(dbPath, true);
+}
+/**
+ * `better-sqlite3` engine. The consumer passes the driver constructor (`import Database from
+ * "better-sqlite3"`) so the SDK never statically imports it — it stays an OPTIONAL peer the consumer's
+ * bundler resolves. Synchronous (the driver is already loaded), so no dynamic import here. The
+ * `readonly` variant opens `{ readonly: true }` + `busy_timeout`; see {@link openBun}.
+ */
+function openBetter(driver, dbPath, readonly) {
+    const db = readonly ? new driver(dbPath, { readonly: true }) : new driver(dbPath);
+    try {
+        db.pragma(readonly ? "busy_timeout = 250" : "journal_mode = WAL");
+    }
+    catch {
+        // :memory: cannot WAL — harmless; busy_timeout is allowed on a readonly handle.
+    }
+    return makeEngine({
+        handle: db,
+        exec: (sql) => db.exec(sql),
+        prepare: (sql) => {
+            const st = db.prepare(sql);
+            return {
+                all: (...b) => st.all(...b),
+                get: (...b) => (st.get(...b) ?? undefined),
+                run: (...b) => Number(st.run(...b).changes),
+            };
+        },
+        transaction: (fn) => db.transaction(fn)(),
+        close: () => db.close(),
+    });
+}
+export function betterSqlite3Engine(driver, dbPath) {
+    return openBetter(driver, dbPath, false);
+}
+/** Read-only `better-sqlite3` engine (`{ readonly: true }` + `busy_timeout`). See {@link openBetter}. */
+export function betterSqlite3ReadonlyEngine(driver, dbPath) {
+    return openBetter(driver, dbPath, true);
+}
+/**
+ * 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 async function autoDetectEngine(dbPath) {
+    if (typeof globalThis.Bun !== "undefined") {
+        return bunSqliteEngine(dbPath);
+    }
+    try {
+        return await nodeSqliteEngine(dbPath);
+    }
+    catch (err) {
+        throw new Error("CatalystReplica: no sqlite engine available — pass opts.engine. " +
+            "Auto-detect needs Bun (bun:sqlite) or Node >=22.5 (node:sqlite). " +
+            `Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** READ-ONLY counterpart of {@link autoDetectEngine}: Bun → `bunSqliteReadonlyEngine`; else
+ *  `nodeSqliteReadonlyEngine`. Used by `CatalystReplica.openReadOnly` when no engine is injected. */
+export async function autoDetectReadonlyEngine(dbPath) {
+    if (typeof globalThis.Bun !== "undefined") {
+        return bunSqliteReadonlyEngine(dbPath);
+    }
+    try {
+        return await nodeSqliteReadonlyEngine(dbPath);
+    }
+    catch (err) {
+        throw new Error("CatalystReplica: no read-only sqlite engine available — pass opts.engine. " +
+            "Auto-detect needs Bun (bun:sqlite) or Node >=22.5 (node:sqlite). " +
+            `Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/replica/engine.js.map

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

package/dist/replica/writer-lock.d.ts

@@ -0,0 +1,27 @@
+import type { LogLevel } from "../live-sync-client.js";
+/** Config for the single-writer guard. Passed as `CatalystReplicaOptions.writerGuard`. */
+export interface WriterGuardOptions {
+    /** Disable the guard entirely (claim nothing). Default false — the guard is ON for file replicas. */
+    disabled?: boolean;
+    /** Steal an existing LIVE lock instead of throwing (the configurable override). Default false. */
+    override?: boolean;
+    /** A lock with no heartbeat newer than this many ms is treated as abandoned + reclaimed. Default 15000. */
+    staleMs?: number;
+    /** How often the owning writer rewrites its heartbeat. Default max(1000, staleMs/3). */
+    heartbeatMs?: number;
+}
+/** A claimed writer lock. `release()` stops the heartbeat and removes the file if still ours. Idempotent. */
+export interface WriterLockHandle {
+    /** The sidecar lock file path (`dbPath + '.writer.lock'`). */
+    readonly path: string;
+    release(): void;
+}
+type Logger = (level: LogLevel, msg: string, extra?: unknown) => void;
+/**
+ * Best-effort claim sole ownership of `dbPath` for a writer. Returns a {@link WriterLockHandle} (or
+ * `null` when the guard is disabled or `dbPath` is in-memory). Throws a clear error when another LIVE
+ * writer already holds the lock and `override` is not set.
+ */
+export declare function claimWriterLock(dbPath: string, opts: WriterGuardOptions, log?: Logger): WriterLockHandle | null;
+export {};
+//# sourceMappingURL=writer-lock.d.ts.map

package/dist/replica/writer-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-lock.d.ts","sourceRoot":"","sources":["../../src/replica/writer-lock.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,0FAA0F;AAC1F,MAAM,WAAW,kBAAkB;IACjC,qGAAqG;IACrG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2GAA2G;IAC3G,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,6GAA6G;AAC7G,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,IAAI,IAAI,CAAC;CACjB;AAWD,KAAK,MAAM,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AA4BtE;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,EACxB,GAAG,CAAC,EAAE,MAAM,GACX,gBAAgB,GAAG,IAAI,CA0EzB"}

package/dist/replica/writer-lock.js

@@ -0,0 +1,125 @@
+// @catalyst-cloud/sdk/node — the single-writer guard for a CatalystReplica writer (CTC-113).
+//
+// The managed replica is single-writer/many-reader (ADR-0008): ONE process owns the SQLite file and
+// applies the change feed; everyone else opens it READ-ONLY (`CatalystReplica.openReadOnly`). Two
+// concurrent WRITERS on the same file would race the cursor + truncate-and-reseed and silently
+// diverge. This guard makes that mistake LOUD: when a writer `start()`s it best-effort claims sole
+// ownership of `dbPath` via a sidecar lock file `dbPath + '.writer.lock'` carrying `{pid, owner,
+// heartbeat}`. A second live writer on the same path throws a clear error instead of corrupting the
+// replica.
+//
+// LIMITS — this is deliberately ADVISORY, not a hard OS lock:
+//   • It is cooperative: it only stops OTHER CatalystReplica writers. A raw `new Database(path)` from
+//     unrelated code is not blocked (use OS file locking / WAL for that).
+//   • Liveness has two signals. The HEARTBEAT (a timestamp rewritten on an interval) is the portable,
+//     cross-host signal — a lock older than `staleMs` with no heartbeat is treated as abandoned and
+//     reclaimed. The PID probe (`process.kill(pid,0)`) only means anything SAME-HOST; cross-host or
+//     when it can't probe, it conservatively assumes the holder is alive and relies on the heartbeat.
+//   • A hard `kill -9` can leave a stale lock until `staleMs` elapses; the next writer reclaims it.
+//   • `:memory:` (and `file::memory:`) replicas are per-connection, never shared, so the guard is a
+//     no-op for them.
+import * as fs from "node:fs";
+const DEFAULT_STALE_MS = 15_000;
+function readLock(lockPath) {
+    try {
+        const rec = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (rec && typeof rec.pid === "number" && typeof rec.heartbeat === "number")
+            return rec;
+        return null;
+    }
+    catch {
+        return null; // absent, partial write, or garbage → treat as no lock
+    }
+}
+/** SAME-HOST liveness probe. Returns true when it cannot tell (assume the holder is alive — the
+ *  heartbeat staleness check is the portable signal that ultimately reclaims a dead lock). */
+function pidAlive(pid) {
+    const proc = globalThis.process;
+    if (!proc?.kill || !pid)
+        return true;
+    try {
+        proc.kill(pid, 0); // signal 0 = existence check, never delivered
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ESRCH")
+            return false; // no such process
+        return true; // EPERM: exists but owned by another user → alive
+    }
+}
+/**
+ * Best-effort claim sole ownership of `dbPath` for a writer. Returns a {@link WriterLockHandle} (or
+ * `null` when the guard is disabled or `dbPath` is in-memory). Throws a clear error when another LIVE
+ * writer already holds the lock and `override` is not set.
+ */
+export function claimWriterLock(dbPath, opts, log) {
+    if (opts.disabled)
+        return null;
+    if (!dbPath || dbPath === ":memory:" || dbPath.startsWith("file::memory:"))
+        return null;
+    const lockPath = `${dbPath}.writer.lock`;
+    const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+    const heartbeatMs = opts.heartbeatMs ?? Math.max(1000, Math.floor(staleMs / 3));
+    const pid = globalThis.process?.pid ?? 0;
+    const owner = `${pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    const serialize = () => JSON.stringify({ pid, owner, heartbeat: Date.now() });
+    const writeFresh = () => fs.writeFileSync(lockPath, serialize());
+    // Atomic exclusive create: wins the claim outright if no file exists.
+    let created = false;
+    try {
+        const fd = fs.openSync(lockPath, "wx");
+        fs.writeSync(fd, serialize());
+        fs.closeSync(fd);
+        created = true;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    if (!created) {
+        const existing = readLock(lockPath);
+        const held = existing != null && Date.now() - existing.heartbeat < staleMs && pidAlive(existing.pid);
+        if (held && !opts.override) {
+            throw new Error(`CatalystReplica: another writer owns this replica at ${dbPath} ` +
+                `(pid=${existing.pid}, last heartbeat ${Date.now() - existing.heartbeat}ms ago). ` +
+                `Only ONE writer may hold a replica file (ADR-0008 single-writer/many-reader); open it ` +
+                `read-only with CatalystReplica.openReadOnly() instead. Pass writerGuard:{override:true} ` +
+                `to take it over, or writerGuard:{disabled:true} to skip the check. NOTE: this guard is ` +
+                `advisory (a sidecar ${lockPath}), not a hard OS lock.`);
+        }
+        log?.("warn", held
+            ? `writer-lock: overriding a live writer at ${lockPath} (writerGuard.override)`
+            : `writer-lock: reclaiming a stale/abandoned lock at ${lockPath}`);
+        writeFresh();
+    }
+    // Keep the lock fresh so peers see it's alive; unref so it never holds the event loop open.
+    const timer = setInterval(() => {
+        try {
+            writeFresh();
+        }
+        catch (err) {
+            log?.("warn", "writer-lock heartbeat failed", err);
+        }
+    }, heartbeatMs);
+    timer.unref?.();
+    let released = false;
+    return {
+        path: lockPath,
+        release() {
+            if (released)
+                return;
+            released = true;
+            clearInterval(timer);
+            const cur = readLock(lockPath);
+            if (cur && cur.owner === owner) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // already gone — fine
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=writer-lock.js.map

package/dist/replica/writer-lock.js.map

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

package/dist/types.d.ts

@@ -1,11 +1,10 @@
-/** The tenant id. Also the Mirror DO name. `"tenant-0"` is Ryan's own workspace (Phase 0). */
+/** The tenant id (also the mirror's name). `"tenant-0"` is an example tenant. */
 export type AccountId = string;
 /**
- * Canonical mirror table names — the `entity` field in change_log + the change-feed wire.
+ * Canonical mirror table names — the `entity` field on the change-feed wire.
  *
- * Mirrors @catalyst-cloud/types `EntityName` exactly. The runtime list `ENTITY_NAMES` below is the
- * same set as an array so the contract test can assert membership at runtime (a bare `type` alias
- * erases to nothing and can't be checked).
+ * The runtime list `ENTITY_NAMES` below is the same set as an array so the contract test can assert
+ * membership at runtime (a bare `type` alias erases to nothing and can't be checked).
  */
 export type EntityName = "issues" | "labels" | "users" | "issue_labels" | "relations" | "issue_history" | "projects" | "cycles" | "initiatives" | "project_initiatives" | "comments" | "pull_requests" | "check_runs" | "commit_statuses" | "reviews";
 /**
@@ -14,28 +13,28 @@ export type EntityName = "issues" | "labels" | "users" | "issue_labels" | "relat
  * the contract test asserts the two agree.
  */
 export declare const ENTITY_NAMES: readonly ["issues", "labels", "users", "issue_labels", "relations", "issue_history", "projects", "cycles", "initiatives", "project_initiatives", "comments", "pull_requests", "check_runs", "commit_statuses", "reviews"];
-/** change_log.op — the change-feed wire contract. */
+/** The change op — the change-feed wire contract. */
 export type ChangeOp = "upsert" | "delete";
 /** The `ChangeOp` union as a runtime array (same lockstep contract as `ENTITY_NAMES`). */
 export declare const CHANGE_OPS: readonly ["upsert", "delete"];
 /**
- * A live change frame off the `/connect` WebSocket — the exact shape `apps/mirror/src/do/ws.ts`
- * broadcasts and replays. One row of the change_log, serialized.
+ * A live change frame off the `/connect` WebSocket — the exact shape the service broadcasts and
+ * replays. One change from the feed, serialized.
  */
 export interface ChangeFrame {
     type: "change";
     accountId: AccountId;
-    /** The change_log seq — the monotonic cursor the replica advances to. */
+    /** The feed sequence — the monotonic cursor the replica advances to. */
     seq: number;
     entity: EntityName;
-    /** The change_log.entity_id — the PK (composite PKs joined with ':'). */
+    /** The entity's primary key (composite PKs joined with ':'). */
     entityId: string;
     op: ChangeOp;
     /** The full normalized row for "upsert"; absent / partial for "delete". */
     row?: Record<string, unknown>;
 }
 /**
- * The underflow control frame: the consumer's cursor predates the DO's retained change_log ring →
+ * The underflow control frame: the consumer's cursor predates the service's retained change buffer →
  * the consumer must re-seed from a full /snapshot.
  */
 export interface ResyncFrame {
@@ -44,14 +43,14 @@ export interface ResyncFrame {
 }
 /**
  * The catch-up request the consumer sends on every (re)connect: "replay everything after this
- * cursor, in seq order". The DO answers with the missed `ChangeFrame`s, or a `ResyncFrame` if `after`
- * predates the retained ring (cursor underflow).
+ * cursor, in seq order". The service answers with the missed `ChangeFrame`s, or a `ResyncFrame` if
+ * `after` predates the retained buffer (cursor underflow).
  */
 export interface SyncFrame {
     type: "sync";
-    /** The durable cursor: the last change_log.seq the consumer has applied (-1 if none). */
+    /** The durable cursor: the last feed seq the consumer has applied (-1 if none). */
     after: number;
 }
-/** Any frame the DO can push to a consumer over `/connect`. */
+/** Any frame the service can push to a consumer over `/connect`. */
 export type ServerFrame = ChangeFrame | ResyncFrame;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAcA,8FAA8F;AAC9F,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,cAAc,GACd,WAAW,GACX,eAAe,GACf,UAAU,GACV,QAAQ,GACR,aAAa,GACb,qBAAqB,GACrB,UAAU,GACV,eAAe,GACf,YAAY,GACZ,iBAAiB,GACjB,SAAS,CAAC;AAEd;;;;GAIG;AACH,eAAO,MAAM,YAAY,2NAgBiB,CAAC;AAE3C,qDAAqD;AACrD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3C,0FAA0F;AAC1F,eAAO,MAAM,UAAU,+BAA8D,CAAC;AAEtF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,QAAQ,CAAC;IACb,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAUA,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,cAAc,GACd,WAAW,GACX,eAAe,GACf,UAAU,GACV,QAAQ,GACR,aAAa,GACb,qBAAqB,GACrB,UAAU,GACV,eAAe,GACf,YAAY,GACZ,iBAAiB,GACjB,SAAS,CAAC;AAEd;;;;GAIG;AACH,eAAO,MAAM,YAAY,2NAgBiB,CAAC;AAE3C,qDAAqD;AACrD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3C,0FAA0F;AAC1F,eAAO,MAAM,UAAU,+BAA8D,CAAC;AAEtF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,QAAQ,CAAC;IACb,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC"}

package/dist/types.js

@@ -1,16 +1,12 @@
 // catalyst-cloud-sdk wire types — the change-feed contract, SELF-CONTAINED.
 //
-// This file is a deliberate, byte-for-byte copy of the portable wire contract from the
-// catalyst-cloud monorepo's @catalyst-cloud/types package (packages/types/src/index.ts): the
-// `EntityName` table-name union, the `ChangeOp` op union, and the change/sync/resync frame shapes
-// the Mirror Durable Object broadcasts over `/connect`. The SDK is published standalone, so it must
-// NOT depend on the internal @catalyst-cloud/types workspace package — instead it owns its own copy
-// of the contract, and a contract test (test/contract.test.ts) pins the literal members so any drift
-// from the monorepo is caught.
+// The `EntityName` table-name union, the `ChangeOp` op union, and the change/sync/resync frame shapes
+// the catalyst-cloud service broadcasts over `/connect`. The SDK is published standalone and owns its
+// own copy of this contract; a contract test (test/contract.test.ts) pins the literal members so any
+// drift is caught.
 //
-// Like @catalyst-cloud/types, this module is Cloudflare-Workers-free and DOM-free: it is pure type
-// declarations + plain JS runtime constants, so it imports cleanly into a browser bundle, a node/bun
-// app, and a Worker alike.
+// This module is free of any runtime-specific or DOM imports — pure type declarations + plain JS
+// runtime constants — so it imports cleanly into a browser bundle or a node/bun app alike.
 /**
  * The `EntityName` union as a runtime array, in the SAME ORDER as the type above. Frozen so consumers
  * (and the contract test) can iterate the canonical table set. Kept in lockstep with `EntityName` —

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,uFAAuF;AACvF,6FAA6F;AAC7F,kGAAkG;AAClG,oGAAoG;AACpG,oGAAoG;AACpG,qGAAqG;AACrG,+BAA+B;AAC/B,EAAE;AACF,mGAAmG;AACnG,qGAAqG;AACrG,2BAA2B;AA6B3B;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,cAAc;IACd,WAAW;IACX,eAAe;IACf,UAAU;IACV,QAAQ;IACR,aAAa;IACb,qBAAqB;IACrB,UAAU;IACV,eAAe;IACf,YAAY;IACZ,iBAAiB;IACjB,SAAS;CAC+B,CAAC;AAK3C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAwC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,sGAAsG;AACtG,sGAAsG;AACtG,qGAAqG;AACrG,mBAAmB;AACnB,EAAE;AACF,iGAAiG;AACjG,2FAA2F;AA4B3F;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,cAAc;IACd,WAAW;IACX,eAAe;IACf,UAAU;IACV,QAAQ;IACR,aAAa;IACb,qBAAqB;IACrB,UAAU;IACV,eAAe;IACf,YAAY;IACZ,iBAAiB;IACjB,SAAS;CAC+B,CAAC;AAK3C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAwC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/sdk",
-  "version": "0.1.0",
-  "description": "Isomorphic (browser + node/bun) read-layer-over-WebSocket client for the catalyst-cloud change-feed (ADR-0008/0009).",
+  "version": "0.2.0",
+  "description": "Keep a live local copy of your Linear and GitHub project data — pushed in real time, without polling rate limits or webhook tunnels.",
   "license": "MIT",
   "author": "Coalesce Labs",
   "homepage": "https://github.com/coalesce-labs/catalyst-cloud-sdk#readme",
@@ -24,6 +24,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "default": "./dist/node.js"
     }
   },
   "files": [
@@ -51,5 +56,22 @@
   "devDependencies": {
     "typescript": "^5.6.3",
     "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "@catalyst-cloud/read-model": "^0.1.0",
+    "@catalyst-cloud/replicate": "^0.1.0",
+    "@catalyst-cloud/schema": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@sqlite.org/sqlite-wasm": "*",
+    "better-sqlite3": "*"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@sqlite.org/sqlite-wasm": {
+      "optional": true
+    }
   }
 }