@helipod/docstore-do-sqlite 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @helipod/docstore-do-sqlite
+
+The MVCC `DocStore` over a **Cloudflare Durable Object's** embedded SQLite (`ctx.storage.sql`) — the
+Cloudflare-native Tier 0 storage backend. Slice 2 of the DO-native host program
+(`docs/superpowers/plans/2026-03-20-cloudflare-do-native-host-roadmap.md`).
+
+DO-SQLite *is* SQLite, so the MVCC document-log implementation is reused **verbatim** from
+[`@helipod/docstore-sqlite`](../docstore-sqlite) (`SqliteDocStore`). This package adds only the one
+new thing: a `DatabaseAdapter` (`DoSqliteAdapter`) that drives the DO's synchronous SQL API.
+
+```ts
+import { SqliteDocStore } from "@helipod/docstore-sqlite";
+import { DoSqliteAdapter } from "@helipod/docstore-do-sqlite";
+
+// inside a Durable Object (the Slice 3 host wires this up):
+const adapter = new DoSqliteAdapter({
+  sql: ctx.storage.sql,
+  transactionSync: ctx.storage.transactionSync.bind(ctx.storage),
+});
+const store = new SqliteDocStore(adapter);
+await store.setupSchema();
+```
+
+## Design notes
+
+### Injection, not import (neutrality)
+
+The engine must never know it is on Cloudflare. So the adapter is **handed** the DO's SQL surface as
+constructor input — `{ sql, transactionSync }` pulled off `ctx.storage` by the host — exactly as the
+`node`/`bun`/`pg` adapters are constructed with their drivers. This package references **no**
+Cloudflare type: the injected surface is declared as minimal structural interfaces (`SqlStorageLike`
+etc.), which a real DO's typed `ctx.storage.sql` (`SqlStorage` from `@cloudflare/workers-types`)
+satisfies by width — mirroring how `bun-adapter.ts` declares its `bun:sqlite` shape inline to avoid a
+build dependency. Nothing above this leaf package imports a Cloudflare primitive.
+
+### The 10 GB ceiling → a typed error, not a crash
+
+A Durable Object's embedded SQLite is capped at **10 GB per object**; a write past that limit
+hard-fails with `SQLITE_FULL`. The adapter classifies **only** that failure into a typed
+[`DatabaseFullError`](./src/errors.ts) (`code: "DATABASE_FULL"`, original error kept as `cause`) so a
+host can catch it and react (shed the write, reshard, alert) instead of seeing an opaque driver throw.
+Every other error — notably the `SQLITE_CONSTRAINT` that the conflict-strategy contract relies on to
+reject a duplicate `(id, ts)` — propagates untouched.
+
+Cloudflare does not document a stable error *code* for the limit, so `isDatabaseFullError` matches the
+SQLite `SQLITE_FULL` result-code family and its canonical "database or disk is full" message,
+deliberately narrow so it never mislabels an unrelated failure. Reaching 10 GB is not reachable in a
+unit test, so the classifier is tested directly against a synthetic `SQLITE_FULL`-shaped error (and
+proven to pass a constraint error through).
+
+### Three DO-SQLite deviations the adapter absorbs
+
+1. **No `BEGIN`/`COMMIT`/`SAVEPOINT` via `exec`.** DO-SQLite rejects transaction-control SQL; the only
+   atomic primitive is `ctx.storage.transactionSync(fn)`. `transaction()` delegates to it (it does
+   **not** emit `BEGIN`/`COMMIT` the way the node/bun adapters do). This is why `transactionSync` is a
+   required constructor input, not optional.
+2. **Values are `ArrayBuffer | string | number | null`.** BLOB columns read back as `ArrayBuffer`
+   (re-wrapped to `Uint8Array` on the read path, so the DocStore sees the same blobs as every other
+   adapter); INTEGER columns read back as `number` (there is no `setReadBigInts`/`safeIntegers` mode).
+3. **`bigint` is not a documented binding type.** The DocStore binds logical timestamps as `bigint`;
+   the bind path narrows them to `number` before `sql.exec`.
+
+### Why `number` timestamps are lossless here
+
+Helipod's only INTEGER columns are logical timestamps (a per-store monotonic `MAX(ts)+1` counter
+seeded at 1) and millisecond wall-clocks. Both stay far under `Number.MAX_SAFE_INTEGER` (2^53) in
+every reachable state — a single DO would need ~9 quadrillion commits to overflow. Document ids and
+index keys are BLOBs, never integers. The bind path throws loudly rather than silently truncate if a
+value ever exceeds the safe range.
+
+## Test fidelity — what is (and is not) proven
+
+This package passes the **full shared docstore conformance suite**
+(`@helipod/docstore/test-support/conformance` — the identical contract SQLite/Postgres/PGlite run),
+driving `SqliteDocStore` over `DoSqliteAdapter`.
+
+**Fidelity level: API-shape conformance against a faithful in-process `SqlStorage` stand-in — NOT a
+real Durable Object run.** The suite runs against `test/memory-sql-storage.ts`, a stand-in backed by
+Node's built-in `node:sqlite` that reproduces the DO SQL surface the adapter actually depends on:
+
+- a **synchronous** `exec(query, ...bindings)` returning a cursor with `toArray()` / `rowsWritten`;
+- a `transactionSync(fn)` that is the sole atomicity primitive;
+- BLOB results returned as **`ArrayBuffer`** (forcing the adapter's `ArrayBuffer → Uint8Array` wrap);
+- INTEGER results returned as **`number`**;
+- **rejection of `bigint` bindings** (forcing the adapter's `bigint → number` narrowing);
+- `exec` refusing `BEGIN`/`COMMIT`/`ROLLBACK`/`SAVEPOINT` (forcing use of `transactionSync`).
+
+Because the stand-in enforces exactly the constraints a real DO imposes, a green suite proves the
+adapter speaks the DO SQL contract correctly. It does **not** prove behavior inside a real DO
+runtime (workerd) — SQLite version quirks, the real `SQLITE_FULL` message text, and 10 GB behavior are
+unverified here.
+
+**Follow-on (deferred, like the container smoke was for `serve`):** run this same conformance suite
+inside a real Durable Object via `@cloudflare/vitest-pool-workers` (`runInDurableObject`) once the DO
+host lands (Slice 3). That is the gold-standard gate; wiring `vitest-pool-workers` (workerd + wrangler
+config + a separate vitest project) was out of scope for this leaf-adapter slice.

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { DatabaseAdapter, SqlValue, PreparedStatement } from '@helipod/docstore-sqlite';
+export { DatabaseAdapter, PreparedStatement, RunResult, SqlRow, SqlValue, SqliteDocStore } from '@helipod/docstore-sqlite';
+
+/**
+ * `DatabaseAdapter` backed by a **Durable Object's** embedded SQLite (`ctx.storage.sql`) — the
+ * Cloudflare-native Tier 0 storage backend (Slice 2 of the DO-native host program;
+ * `docs/superpowers/plans/2026-03-20-cloudflare-do-native-host-roadmap.md`). DO-SQLite's SQL API is
+ * **synchronous** (`sql.exec(query, ...bindings)` returns a cursor synchronously), which is a direct
+ * structural match for the existing synchronous `DatabaseAdapter` contract — an easier fit than the
+ * async Postgres adapter.
+ *
+ * ## Injection, not import (the neutrality invariant)
+ * The engine must NEVER know it is on Cloudflare. So this adapter takes the DO's SQL surface as
+ * CONSTRUCTOR INPUT — a `{ sql, transactionSync }` pair the DO host (Slice 3) pulls off its own
+ * `ctx.storage` and hands in — exactly as `docstore-sqlite`/`docstore-postgres` are constructed with
+ * their drivers. Nothing above this leaf ever references a Cloudflare type.
+ *
+ * The injected surface is declared here as minimal STRUCTURAL interfaces (`SqlStorageLike` /
+ * `SqlStorageCursorLike` / a `transactionSync` closure runner) — mirroring `bun-adapter.ts`, which
+ * declares its `bun:sqlite` shape inline "to avoid a build dependency". A real DO's typed
+ * `ctx.storage.sql` (`SqlStorage` from `@cloudflare/workers-types`) and `ctx.storage.transactionSync`
+ * structurally satisfy these, so the host wires them in with zero casts and this package needs no
+ * `@cloudflare/workers-types` dependency of its own.
+ *
+ * ## The three DO-SQLite deviations from a normal SQLite driver (all handled here)
+ * 1. **No `BEGIN`/`COMMIT`/`SAVEPOINT` via `exec`.** DO-SQLite rejects transaction-control SQL; the
+ *    only way to get an atomic multi-statement unit is `ctx.storage.transactionSync(fn)`. So
+ *    `transaction()` delegates to the injected `transactionSync` — it does NOT emit `BEGIN`/`COMMIT`
+ *    the way `node-adapter`/`bun-adapter` do.
+ * 2. **Values are `ArrayBuffer | string | number | null`.** BLOB columns read back as `ArrayBuffer`
+ *    (not `Uint8Array`), and INTEGER columns read back as `number` (there is no `bigint`/safe-integer
+ *    read mode like `setReadBigInts`/`safeIntegers`). The read path re-wraps `ArrayBuffer → Uint8Array`
+ *    so the DocStore sees the same `Uint8Array` blobs every other adapter yields; integers stay
+ *    `number` and the DocStore's `asBigInt` widens them (see the precision note below).
+ * 3. **Bindings are `ArrayBuffer | ArrayBufferView | string | number | null` — `bigint` is NOT a
+ *    documented binding type.** The DocStore binds logical timestamps as `bigint`; the bind path
+ *    narrows those to `number` before they reach `sql.exec`.
+ *
+ * ## The `bigint`/`number` precision note (why `number` is safe here)
+ * Helipod's only INTEGER columns are logical timestamps (`ts`/`prev_ts`/`commit_ts` — a per-store
+ * monotonic `MAX(ts)+1` counter seeded at 1) and millisecond wall-clocks (`created_at`/`updated_at`).
+ * Both stay far under `Number.MAX_SAFE_INTEGER` (2^53): a single DO would need ~9 quadrillion commits
+ * to overflow, and ms-time overflows in year ~+287000. Document ids and index keys are BLOBs, never
+ * integers. So round-tripping timestamps through `number` is lossless in every reachable state — and
+ * the bind path throws loudly rather than silently truncate if a value ever exceeds the safe range.
+ *
+ * ## The 10 GB ceiling
+ * A write past a Durable Object's hard 10 GB limit fails with `SQLITE_FULL`; the adapter classifies
+ * that ONE failure into a typed `DatabaseFullError` (see `errors.ts`) instead of an opaque throw,
+ * while every other error (constraint violations, etc.) propagates untouched.
+ */
+
+/** A DO-SQLite scalar, both as a binding and as a result cell:
+ *  `ArrayBuffer | string | number | null` (Cloudflare's `SqlStorageValue`). We additionally accept
+ *  `ArrayBufferView` as a binding, which the SQL API also takes for BLOBs. */
+type DoSqlValue = ArrayBuffer | ArrayBufferView | string | number | null;
+/** The synchronous cursor `SqlStorage.exec` returns. We only need `toArray()` (materialize rows)
+ *  and `rowsWritten` (for `RunResult.changes`); the fuller DO cursor (`one`/`raw`/`next`/iteration/
+ *  `columnNames`/`rowsRead`) is a structural superset and satisfies this by width. */
+interface SqlStorageCursorLike {
+    toArray(): Record<string, DoSqlValue>[];
+    /** Rows actually written by the statement — DO-SQLite's counterpart to SQLite's `changes()`
+     *  (0 for an `INSERT OR IGNORE` that ignored). */
+    readonly rowsWritten: number;
+}
+/** The narrow slice of Cloudflare's `SqlStorage` (`ctx.storage.sql`) this adapter drives. */
+interface SqlStorageLike {
+    exec(query: string, ...bindings: DoSqlValue[]): SqlStorageCursorLike;
+}
+/** `ctx.storage.transactionSync` — runs `closure` inside ONE synchronous SQLite transaction, rolling
+ *  back if it throws. This is DO-SQLite's ONLY transaction primitive (explicit `BEGIN`/`COMMIT` SQL
+ *  is rejected), so the adapter cannot fabricate atomicity without it. */
+type TransactionSyncFn = <T>(closure: () => T) => T;
+interface DoSqliteOptions {
+    /** The DO's SQL handle — `ctx.storage.sql`. */
+    sql: SqlStorageLike;
+    /** The DO's synchronous transaction runner — `ctx.storage.transactionSync` (bind it to
+     *  `ctx.storage`). Required: without it there is no way to make a multi-statement commit atomic. */
+    transactionSync: TransactionSyncFn;
+}
+declare class DoSqliteAdapter implements DatabaseAdapter {
+    private readonly sql;
+    private readonly transactionSyncFn;
+    constructor(options: DoSqliteOptions);
+    /** Issue one `sql.exec`, converting bindings and classifying a 10 GB `SQLITE_FULL` failure into a
+     *  typed `DatabaseFullError`. The single chokepoint every `exec`/statement call funnels through, so
+     *  the full-storage classification lives in exactly one place. */
+    execRaw(sqlText: string, params: readonly SqlValue[]): SqlStorageCursorLike;
+    exec(sql: string): void;
+    prepare(sql: string): PreparedStatement;
+    transaction<T>(fn: () => T): T;
+    close(): void;
+}
+
+/**
+ * The one storage-full failure mode a DO-SQLite adapter has that neither `node:sqlite` nor
+ * `bun:sqlite` share: a Durable Object's embedded SQLite is capped at **10 GB per object** and a
+ * write past that ceiling hard-fails with `SQLITE_FULL` (see
+ * `docs/dev/research/cloudflare-do-native-host.md`). Rather than let that surface as an opaque,
+ * driver-shaped throw, the adapter classifies it into this ONE typed error so a host (Slice 3) can
+ * catch it and react (shed the write, reshard, page an operator) — the same "typed, not a crash"
+ * discipline `docstore-postgres` applies to its `ReadOnlyStoreError`.
+ *
+ * Only a genuine capacity/disk-full failure is wrapped; a `SQLITE_CONSTRAINT` (e.g. the duplicate
+ * `(id, ts)` the conflict-strategy contract relies on rejecting) passes straight through untouched.
+ */
+declare class DatabaseFullError extends Error {
+    /** The original driver error, preserved so the host never loses the underlying detail.
+     *  `override` because ES2022's `Error` already declares an optional `cause`. */
+    readonly cause: unknown;
+    /** Stable, machine-checkable discriminant — a host can branch on this without instanceof across
+     *  a bundling/isolate boundary. */
+    readonly code: "DATABASE_FULL";
+    constructor(message: string, 
+    /** The original driver error, preserved so the host never loses the underlying detail.
+     *  `override` because ES2022's `Error` already declares an optional `cause`. */
+    cause: unknown);
+}
+/**
+ * Does this driver error signal the DO-SQLite 10 GB ceiling (`SQLITE_FULL`)? Cloudflare does not
+ * document a stable error CODE for the limit (the SQL API just surfaces SQLite's own text), so we
+ * match on the SQLite `SQLITE_FULL` primary-result-code family and its canonical message —
+ * "database or disk is full" — while deliberately NOT matching `SQLITE_CONSTRAINT`/`SQLITE_BUSY`/etc.
+ * A false negative here degrades gracefully (the raw error still propagates, just untyped); a false
+ * positive would mislabel an unrelated failure, so the patterns are kept narrow and full-specific.
+ */
+declare function isDatabaseFullError(err: unknown): boolean;
+
+export { DatabaseFullError, DoSqliteAdapter, type DoSqliteOptions, type SqlStorageCursorLike, type SqlStorageLike, type TransactionSyncFn, isDatabaseFullError };

package/dist/index.js

@@ -0,0 +1,107 @@
+// src/errors.ts
+var DatabaseFullError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "DatabaseFullError";
+  }
+  cause;
+  /** Stable, machine-checkable discriminant — a host can branch on this without instanceof across
+   *  a bundling/isolate boundary. */
+  code = "DATABASE_FULL";
+};
+function isDatabaseFullError(err) {
+  const code = err?.code;
+  if (typeof code === "string" && code.toUpperCase().includes("SQLITE_FULL")) return true;
+  const message = err?.message;
+  if (typeof message !== "string") return false;
+  return /\bSQLITE_FULL\b/i.test(message) || /database or disk is full/i.test(message);
+}
+
+// src/do-adapter.ts
+function toDoBinding(v) {
+  if (typeof v === "bigint") {
+    if (v > 9007199254740991n || v < -9007199254740991n) {
+      throw new RangeError(
+        `[docstore-do-sqlite] integer ${v} exceeds Number.MAX_SAFE_INTEGER; DO-SQLite has no bigint binding type, so it cannot be bound without precision loss`
+      );
+    }
+    return Number(v);
+  }
+  return v;
+}
+function fromDoValue(v) {
+  if (v instanceof ArrayBuffer) return new Uint8Array(v);
+  if (ArrayBuffer.isView(v)) return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+  return v;
+}
+function rowFromDo(row) {
+  const out = {};
+  for (const key in row) out[key] = fromDoValue(row[key]);
+  return out;
+}
+var DoStatement = class {
+  constructor(adapter, sqlText) {
+    this.adapter = adapter;
+    this.sqlText = sqlText;
+  }
+  adapter;
+  sqlText;
+  run(...params) {
+    const cursor = this.adapter.execRaw(this.sqlText, params);
+    cursor.toArray();
+    return { changes: cursor.rowsWritten, lastInsertRowid: 0 };
+  }
+  get(...params) {
+    const rows = this.adapter.execRaw(this.sqlText, params).toArray();
+    return rows.length > 0 ? rowFromDo(rows[0]) : void 0;
+  }
+  all(...params) {
+    return this.adapter.execRaw(this.sqlText, params).toArray().map(rowFromDo);
+  }
+};
+var DoSqliteAdapter = class {
+  sql;
+  transactionSyncFn;
+  constructor(options) {
+    this.sql = options.sql;
+    this.transactionSyncFn = options.transactionSync;
+  }
+  /** Issue one `sql.exec`, converting bindings and classifying a 10 GB `SQLITE_FULL` failure into a
+   *  typed `DatabaseFullError`. The single chokepoint every `exec`/statement call funnels through, so
+   *  the full-storage classification lives in exactly one place. */
+  execRaw(sqlText, params) {
+    try {
+      return this.sql.exec(sqlText, ...params.map(toDoBinding));
+    } catch (err) {
+      if (isDatabaseFullError(err)) {
+        throw new DatabaseFullError(
+          "[docstore-do-sqlite] the Durable Object's 10 GB SQLite limit was reached (SQLITE_FULL)",
+          err
+        );
+      }
+      throw err;
+    }
+  }
+  exec(sql) {
+    this.execRaw(sql, []).toArray();
+  }
+  prepare(sql) {
+    return new DoStatement(this, sql);
+  }
+  transaction(fn) {
+    return this.transactionSyncFn(fn);
+  }
+  close() {
+  }
+};
+
+// src/index.ts
+import { SqliteDocStore } from "@helipod/docstore-sqlite";
+export {
+  DatabaseFullError,
+  DoSqliteAdapter,
+  SqliteDocStore,
+  isDatabaseFullError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/do-adapter.ts","../src/index.ts"],"sourcesContent":["/**\n * The one storage-full failure mode a DO-SQLite adapter has that neither `node:sqlite` nor\n * `bun:sqlite` share: a Durable Object's embedded SQLite is capped at **10 GB per object** and a\n * write past that ceiling hard-fails with `SQLITE_FULL` (see\n * `docs/dev/research/cloudflare-do-native-host.md`). Rather than let that surface as an opaque,\n * driver-shaped throw, the adapter classifies it into this ONE typed error so a host (Slice 3) can\n * catch it and react (shed the write, reshard, page an operator) — the same \"typed, not a crash\"\n * discipline `docstore-postgres` applies to its `ReadOnlyStoreError`.\n *\n * Only a genuine capacity/disk-full failure is wrapped; a `SQLITE_CONSTRAINT` (e.g. the duplicate\n * `(id, ts)` the conflict-strategy contract relies on rejecting) passes straight through untouched.\n */\nexport class DatabaseFullError extends Error {\n  /** Stable, machine-checkable discriminant — a host can branch on this without instanceof across\n   *  a bundling/isolate boundary. */\n  readonly code = \"DATABASE_FULL\" as const;\n\n  constructor(\n    message: string,\n    /** The original driver error, preserved so the host never loses the underlying detail.\n     *  `override` because ES2022's `Error` already declares an optional `cause`. */\n    override readonly cause: unknown,\n  ) {\n    super(message);\n    this.name = \"DatabaseFullError\";\n  }\n}\n\n/**\n * Does this driver error signal the DO-SQLite 10 GB ceiling (`SQLITE_FULL`)? Cloudflare does not\n * document a stable error CODE for the limit (the SQL API just surfaces SQLite's own text), so we\n * match on the SQLite `SQLITE_FULL` primary-result-code family and its canonical message —\n * \"database or disk is full\" — while deliberately NOT matching `SQLITE_CONSTRAINT`/`SQLITE_BUSY`/etc.\n * A false negative here degrades gracefully (the raw error still propagates, just untyped); a false\n * positive would mislabel an unrelated failure, so the patterns are kept narrow and full-specific.\n */\nexport function isDatabaseFullError(err: unknown): boolean {\n  const code = (err as { code?: unknown } | null)?.code;\n  // SQLite exposes the primary result code as the string \"SQLITE_FULL\" on `err.code` in most\n  // bindings; some (and the DO SQL API) only carry it in the message. Check both.\n  if (typeof code === \"string\" && code.toUpperCase().includes(\"SQLITE_FULL\")) return true;\n  const message = (err as { message?: unknown } | null)?.message;\n  if (typeof message !== \"string\") return false;\n  return /\\bSQLITE_FULL\\b/i.test(message) || /database or disk is full/i.test(message);\n}\n","/**\n * `DatabaseAdapter` backed by a **Durable Object's** embedded SQLite (`ctx.storage.sql`) — the\n * Cloudflare-native Tier 0 storage backend (Slice 2 of the DO-native host program;\n * `docs/superpowers/plans/2026-03-20-cloudflare-do-native-host-roadmap.md`). DO-SQLite's SQL API is\n * **synchronous** (`sql.exec(query, ...bindings)` returns a cursor synchronously), which is a direct\n * structural match for the existing synchronous `DatabaseAdapter` contract — an easier fit than the\n * async Postgres adapter.\n *\n * ## Injection, not import (the neutrality invariant)\n * The engine must NEVER know it is on Cloudflare. So this adapter takes the DO's SQL surface as\n * CONSTRUCTOR INPUT — a `{ sql, transactionSync }` pair the DO host (Slice 3) pulls off its own\n * `ctx.storage` and hands in — exactly as `docstore-sqlite`/`docstore-postgres` are constructed with\n * their drivers. Nothing above this leaf ever references a Cloudflare type.\n *\n * The injected surface is declared here as minimal STRUCTURAL interfaces (`SqlStorageLike` /\n * `SqlStorageCursorLike` / a `transactionSync` closure runner) — mirroring `bun-adapter.ts`, which\n * declares its `bun:sqlite` shape inline \"to avoid a build dependency\". A real DO's typed\n * `ctx.storage.sql` (`SqlStorage` from `@cloudflare/workers-types`) and `ctx.storage.transactionSync`\n * structurally satisfy these, so the host wires them in with zero casts and this package needs no\n * `@cloudflare/workers-types` dependency of its own.\n *\n * ## The three DO-SQLite deviations from a normal SQLite driver (all handled here)\n * 1. **No `BEGIN`/`COMMIT`/`SAVEPOINT` via `exec`.** DO-SQLite rejects transaction-control SQL; the\n *    only way to get an atomic multi-statement unit is `ctx.storage.transactionSync(fn)`. So\n *    `transaction()` delegates to the injected `transactionSync` — it does NOT emit `BEGIN`/`COMMIT`\n *    the way `node-adapter`/`bun-adapter` do.\n * 2. **Values are `ArrayBuffer | string | number | null`.** BLOB columns read back as `ArrayBuffer`\n *    (not `Uint8Array`), and INTEGER columns read back as `number` (there is no `bigint`/safe-integer\n *    read mode like `setReadBigInts`/`safeIntegers`). The read path re-wraps `ArrayBuffer → Uint8Array`\n *    so the DocStore sees the same `Uint8Array` blobs every other adapter yields; integers stay\n *    `number` and the DocStore's `asBigInt` widens them (see the precision note below).\n * 3. **Bindings are `ArrayBuffer | ArrayBufferView | string | number | null` — `bigint` is NOT a\n *    documented binding type.** The DocStore binds logical timestamps as `bigint`; the bind path\n *    narrows those to `number` before they reach `sql.exec`.\n *\n * ## The `bigint`/`number` precision note (why `number` is safe here)\n * Helipod's only INTEGER columns are logical timestamps (`ts`/`prev_ts`/`commit_ts` — a per-store\n * monotonic `MAX(ts)+1` counter seeded at 1) and millisecond wall-clocks (`created_at`/`updated_at`).\n * Both stay far under `Number.MAX_SAFE_INTEGER` (2^53): a single DO would need ~9 quadrillion commits\n * to overflow, and ms-time overflows in year ~+287000. Document ids and index keys are BLOBs, never\n * integers. So round-tripping timestamps through `number` is lossless in every reachable state — and\n * the bind path throws loudly rather than silently truncate if a value ever exceeds the safe range.\n *\n * ## The 10 GB ceiling\n * A write past a Durable Object's hard 10 GB limit fails with `SQLITE_FULL`; the adapter classifies\n * that ONE failure into a typed `DatabaseFullError` (see `errors.ts`) instead of an opaque throw,\n * while every other error (constraint violations, etc.) propagates untouched.\n */\nimport type { DatabaseAdapter, PreparedStatement, RunResult, SqlRow, SqlValue } from \"@helipod/docstore-sqlite\";\nimport { DatabaseFullError, isDatabaseFullError } from \"./errors\";\n\n/** A DO-SQLite scalar, both as a binding and as a result cell:\n *  `ArrayBuffer | string | number | null` (Cloudflare's `SqlStorageValue`). We additionally accept\n *  `ArrayBufferView` as a binding, which the SQL API also takes for BLOBs. */\ntype DoSqlValue = ArrayBuffer | ArrayBufferView | string | number | null;\n\n/** The synchronous cursor `SqlStorage.exec` returns. We only need `toArray()` (materialize rows)\n *  and `rowsWritten` (for `RunResult.changes`); the fuller DO cursor (`one`/`raw`/`next`/iteration/\n *  `columnNames`/`rowsRead`) is a structural superset and satisfies this by width. */\nexport interface SqlStorageCursorLike {\n  toArray(): Record<string, DoSqlValue>[];\n  /** Rows actually written by the statement — DO-SQLite's counterpart to SQLite's `changes()`\n   *  (0 for an `INSERT OR IGNORE` that ignored). */\n  readonly rowsWritten: number;\n}\n\n/** The narrow slice of Cloudflare's `SqlStorage` (`ctx.storage.sql`) this adapter drives. */\nexport interface SqlStorageLike {\n  exec(query: string, ...bindings: DoSqlValue[]): SqlStorageCursorLike;\n}\n\n/** `ctx.storage.transactionSync` — runs `closure` inside ONE synchronous SQLite transaction, rolling\n *  back if it throws. This is DO-SQLite's ONLY transaction primitive (explicit `BEGIN`/`COMMIT` SQL\n *  is rejected), so the adapter cannot fabricate atomicity without it. */\nexport type TransactionSyncFn = <T>(closure: () => T) => T;\n\nexport interface DoSqliteOptions {\n  /** The DO's SQL handle — `ctx.storage.sql`. */\n  sql: SqlStorageLike;\n  /** The DO's synchronous transaction runner — `ctx.storage.transactionSync` (bind it to\n   *  `ctx.storage`). Required: without it there is no way to make a multi-statement commit atomic. */\n  transactionSync: TransactionSyncFn;\n}\n\n/** Narrow a DocStore-side binding (`SqlValue`) to what DO-SQLite's `exec` accepts. The only real work\n *  is `bigint → number` (DO has no bigint binding type); `Uint8Array` blobs and everything else pass\n *  through. Throws — rather than silently truncating — if a `bigint` exceeds the 2^53 safe range\n *  (unreachable for Helipod's monotonic-counter timestamps; see the module note). */\nfunction toDoBinding(v: SqlValue): DoSqlValue {\n  if (typeof v === \"bigint\") {\n    if (v > 9007199254740991n || v < -9007199254740991n) {\n      throw new RangeError(\n        `[docstore-do-sqlite] integer ${v} exceeds Number.MAX_SAFE_INTEGER; DO-SQLite has no ` +\n          `bigint binding type, so it cannot be bound without precision loss`,\n      );\n    }\n    return Number(v);\n  }\n  return v;\n}\n\n/** Re-wrap a DO-SQLite result cell into the `SqlValue` shape the DocStore expects. The one\n *  transformation that matters: BLOB columns come back as `ArrayBuffer`, but the DocStore reads them\n *  as `Uint8Array` (`internal_id`/`key`) — so wrap `ArrayBuffer → Uint8Array`. Integers stay `number`\n *  (the DocStore's `asBigInt` widens them); strings/null pass through. */\nfunction fromDoValue(v: DoSqlValue): SqlValue {\n  if (v instanceof ArrayBuffer) return new Uint8Array(v);\n  // A DO cursor only ever yields ArrayBuffer for blobs, but a faithful stand-in (or a future runtime)\n  // could hand back an ArrayBufferView; normalize that too so downstream never sees a stray view.\n  if (ArrayBuffer.isView(v)) return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);\n  return v;\n}\n\nfunction rowFromDo(row: Record<string, DoSqlValue>): SqlRow {\n  const out: SqlRow = {};\n  for (const key in row) out[key] = fromDoValue(row[key]!);\n  return out;\n}\n\n/** A `PreparedStatement` over DO-SQLite. DO-SQLite has no persistent prepared-statement handle on the\n *  `SqlStorage` surface (and caches compiled SQL by text internally), so each `run`/`get`/`all` simply\n *  re-issues `sql.exec(this.sql, ...bindings)`. The DocStore still caches these wrapper objects, so the\n *  SQL text is built once per query — the same statement-cache ergonomics `node`/`bun` get. */\nclass DoStatement implements PreparedStatement {\n  constructor(\n    private readonly adapter: DoSqliteAdapter,\n    private readonly sqlText: string,\n  ) {}\n\n  run(...params: SqlValue[]): RunResult {\n    const cursor = this.adapter.execRaw(this.sqlText, params);\n    // DO-SQLite writes are counted by `rowsWritten`; `lastInsertRowid` has no meaning on the\n    // WITHOUT ROWID tables the DocStore uses (and the DocStore never reads it), so report 0.\n    cursor.toArray(); // force execution so `rowsWritten` is populated even with no RETURNING rows\n    return { changes: cursor.rowsWritten, lastInsertRowid: 0 };\n  }\n\n  get(...params: SqlValue[]): SqlRow | undefined {\n    const rows = this.adapter.execRaw(this.sqlText, params).toArray();\n    return rows.length > 0 ? rowFromDo(rows[0]!) : undefined;\n  }\n\n  all(...params: SqlValue[]): SqlRow[] {\n    return this.adapter.execRaw(this.sqlText, params).toArray().map(rowFromDo);\n  }\n}\n\nexport class DoSqliteAdapter implements DatabaseAdapter {\n  private readonly sql: SqlStorageLike;\n  private readonly transactionSyncFn: TransactionSyncFn;\n\n  constructor(options: DoSqliteOptions) {\n    this.sql = options.sql;\n    this.transactionSyncFn = options.transactionSync;\n  }\n\n  /** Issue one `sql.exec`, converting bindings and classifying a 10 GB `SQLITE_FULL` failure into a\n   *  typed `DatabaseFullError`. The single chokepoint every `exec`/statement call funnels through, so\n   *  the full-storage classification lives in exactly one place. */\n  execRaw(sqlText: string, params: readonly SqlValue[]): SqlStorageCursorLike {\n    try {\n      return this.sql.exec(sqlText, ...params.map(toDoBinding));\n    } catch (err) {\n      if (isDatabaseFullError(err)) {\n        throw new DatabaseFullError(\n          \"[docstore-do-sqlite] the Durable Object's 10 GB SQLite limit was reached (SQLITE_FULL)\",\n          err,\n        );\n      }\n      throw err;\n    }\n  }\n\n  exec(sql: string): void {\n    // `exec()` carries DDL (the multi-statement schema) and other no-result side effects. DO-SQLite's\n    // `sql.exec` runs a multi-statement string in one call (bindings only apply to a single statement),\n    // so no splitting is needed here. Materialize to surface any FULL error synchronously.\n    this.execRaw(sql, []).toArray();\n  }\n\n  prepare(sql: string): PreparedStatement {\n    return new DoStatement(this, sql);\n  }\n\n  transaction<T>(fn: () => T): T {\n    // DO-SQLite's ONLY atomic primitive — explicit BEGIN/COMMIT SQL is rejected. A throw inside `fn`\n    // propagates out of `transactionSync`, which rolls the whole transaction back (matching the\n    // BEGIN/ROLLBACK contract the node/bun adapters implement by hand).\n    return this.transactionSyncFn(fn);\n  }\n\n  close(): void {\n    // A Durable Object's storage lifecycle is owned by the runtime, not the adapter: there is no\n    // handle to close and no file to release (unlike node/bun's on-disk databases). The DocStore's\n    // graceful-shutdown `close()` still flows here, so this is an intentional no-op.\n  }\n}\n","/**\n * `@helipod/docstore-do-sqlite` — the MVCC `DocStore` over a **Durable Object's** embedded SQLite\n * (`ctx.storage.sql`), via a `DatabaseAdapter` that the DO host injects. The Cloudflare-native Tier 0\n * storage backend; the engine never imports a Cloudflare type — the adapter is handed the DO's SQL\n * surface as constructor input, exactly like the `node`/`bun`/`pg` adapters.\n *\n * The MVCC `DocStore` implementation itself is REUSED verbatim from `@helipod/docstore-sqlite`\n * (`SqliteDocStore`) — DO-SQLite is SQLite, so only the driver seam differs. Construct as:\n *\n * ```ts\n * import { SqliteDocStore } from \"@helipod/docstore-sqlite\";\n * import { DoSqliteAdapter } from \"@helipod/docstore-do-sqlite\";\n *\n * // inside a Durable Object:\n * const adapter = new DoSqliteAdapter({\n *   sql: ctx.storage.sql,\n *   transactionSync: ctx.storage.transactionSync.bind(ctx.storage),\n * });\n * const store = new SqliteDocStore(adapter);\n * await store.setupSchema();\n * ```\n */\nexport { DoSqliteAdapter } from \"./do-adapter\";\nexport type {\n  DoSqliteOptions,\n  SqlStorageLike,\n  SqlStorageCursorLike,\n  TransactionSyncFn,\n} from \"./do-adapter\";\nexport { DatabaseFullError, isDatabaseFullError } from \"./errors\";\n\n// Re-exported for ergonomics so a DO host can construct the whole store from one import. The MVCC\n// document-log logic lives in `@helipod/docstore-sqlite`; DO-SQLite reuses it unchanged.\nexport { SqliteDocStore } from \"@helipod/docstore-sqlite\";\nexport type { DatabaseAdapter, PreparedStatement, RunResult, SqlValue, SqlRow } from \"@helipod/docstore-sqlite\";\n"],"mappings":";AAYO,IAAM,oBAAN,cAAgC,MAAM;AAAA,EAK3C,YACE,SAGkB,OAClB;AACA,UAAM,OAAO;AAFK;AAGlB,SAAK,OAAO;AAAA,EACd;AAAA,EAJoB;AAAA;AAAA;AAAA,EANX,OAAO;AAWlB;AAUO,SAAS,oBAAoB,KAAuB;AACzD,QAAM,OAAQ,KAAmC;AAGjD,MAAI,OAAO,SAAS,YAAY,KAAK,YAAY,EAAE,SAAS,aAAa,EAAG,QAAO;AACnF,QAAM,UAAW,KAAsC;AACvD,MAAI,OAAO,YAAY,SAAU,QAAO;AACxC,SAAO,mBAAmB,KAAK,OAAO,KAAK,4BAA4B,KAAK,OAAO;AACrF;;;AC4CA,SAAS,YAAY,GAAyB;AAC5C,MAAI,OAAO,MAAM,UAAU;AACzB,QAAI,IAAI,qBAAqB,IAAI,CAAC,mBAAmB;AACnD,YAAM,IAAI;AAAA,QACR,gCAAgC,CAAC;AAAA,MAEnC;AAAA,IACF;AACA,WAAO,OAAO,CAAC;AAAA,EACjB;AACA,SAAO;AACT;AAMA,SAAS,YAAY,GAAyB;AAC5C,MAAI,aAAa,YAAa,QAAO,IAAI,WAAW,CAAC;AAGrD,MAAI,YAAY,OAAO,CAAC,EAAG,QAAO,IAAI,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU;AACrF,SAAO;AACT;AAEA,SAAS,UAAU,KAAyC;AAC1D,QAAM,MAAc,CAAC;AACrB,aAAW,OAAO,IAAK,KAAI,GAAG,IAAI,YAAY,IAAI,GAAG,CAAE;AACvD,SAAO;AACT;AAMA,IAAM,cAAN,MAA+C;AAAA,EAC7C,YACmB,SACA,SACjB;AAFiB;AACA;AAAA,EAChB;AAAA,EAFgB;AAAA,EACA;AAAA,EAGnB,OAAO,QAA+B;AACpC,UAAM,SAAS,KAAK,QAAQ,QAAQ,KAAK,SAAS,MAAM;AAGxD,WAAO,QAAQ;AACf,WAAO,EAAE,SAAS,OAAO,aAAa,iBAAiB,EAAE;AAAA,EAC3D;AAAA,EAEA,OAAO,QAAwC;AAC7C,UAAM,OAAO,KAAK,QAAQ,QAAQ,KAAK,SAAS,MAAM,EAAE,QAAQ;AAChE,WAAO,KAAK,SAAS,IAAI,UAAU,KAAK,CAAC,CAAE,IAAI;AAAA,EACjD;AAAA,EAEA,OAAO,QAA8B;AACnC,WAAO,KAAK,QAAQ,QAAQ,KAAK,SAAS,MAAM,EAAE,QAAQ,EAAE,IAAI,SAAS;AAAA,EAC3E;AACF;AAEO,IAAM,kBAAN,MAAiD;AAAA,EACrC;AAAA,EACA;AAAA,EAEjB,YAAY,SAA0B;AACpC,SAAK,MAAM,QAAQ;AACnB,SAAK,oBAAoB,QAAQ;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA,EAKA,QAAQ,SAAiB,QAAmD;AAC1E,QAAI;AACF,aAAO,KAAK,IAAI,KAAK,SAAS,GAAG,OAAO,IAAI,WAAW,CAAC;AAAA,IAC1D,SAAS,KAAK;AACZ,UAAI,oBAAoB,GAAG,GAAG;AAC5B,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,QACF;AAAA,MACF;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,KAAK,KAAmB;AAItB,SAAK,QAAQ,KAAK,CAAC,CAAC,EAAE,QAAQ;AAAA,EAChC;AAAA,EAEA,QAAQ,KAAgC;AACtC,WAAO,IAAI,YAAY,MAAM,GAAG;AAAA,EAClC;AAAA,EAEA,YAAe,IAAgB;AAI7B,WAAO,KAAK,kBAAkB,EAAE;AAAA,EAClC;AAAA,EAEA,QAAc;AAAA,EAId;AACF;;;ACnKA,SAAS,sBAAsB;","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@helipod/docstore-do-sqlite",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "FSL-1.1-Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./test-support": {
+      "types": "./test/memory-sql-storage.ts",
+      "default": "./test/memory-sql-storage.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "test/memory-sql-storage.ts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@helipod/docstore-sqlite": "0.1.0"
+  },
+  "devDependencies": {
+    "@helipod/docstore": "0.1.0",
+    "@helipod/id-codec": "0.1.0",
+    "@helipod/index-key-codec": "0.1.0",
+    "@helipod/values": "0.1.0",
+    "@types/node": "^22.10.5",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helipod-sh/helipod.git",
+    "directory": "packages/docstore-do-sqlite"
+  },
+  "homepage": "https://github.com/helipod-sh/helipod"
+}

package/test/memory-sql-storage.ts

@@ -0,0 +1,134 @@
+/**
+ * A FAITHFUL in-process stand-in for a Durable Object's SQL surface (`ctx.storage.sql` +
+ * `ctx.storage.transactionSync`), backed by Node's built-in `node:sqlite`. It exists so the shared
+ * docstore conformance suite can run against `DoSqliteAdapter` under plain Node/vitest — WITHOUT a
+ * real Durable Object (which would need `@cloudflare/vitest-pool-workers`, workerd, and a wrangler
+ * config; deferred to the Slice 3 host, see this package's README).
+ *
+ * "Faithful" is the whole point: this stand-in deliberately reproduces the exact DO-SQLite CONSTRAINTS
+ * the adapter must cope with, so that a passing suite actually exercises the adapter's DO-specific
+ * code paths rather than papering over them. Specifically it:
+ *   - is SYNCHRONOUS (`exec` returns a cursor synchronously; `transactionSync` runs its closure now);
+ *   - returns BLOB columns as `ArrayBuffer` (not `Uint8Array`) — forcing the adapter's read-path wrap;
+ *   - returns INTEGER columns as `number` — as DO-SQLite does (no bigint read mode);
+ *   - REJECTS `bigint` bindings — DO-SQLite has no bigint binding type, so this proves the adapter
+ *     narrows `bigint → number` before binding;
+ *   - REJECTS `BEGIN`/`COMMIT`/`ROLLBACK`/`SAVEPOINT` through `exec` — as DO-SQLite does, proving the
+ *     adapter routes atomicity through `transactionSync`, never through transaction-control SQL;
+ *   - exposes `rowsWritten` on the cursor (DO-SQLite's counterpart to SQLite's `changes()`).
+ *
+ * What it does NOT reproduce: a real workerd SQLite build, the real `SQLITE_FULL` text at 10 GB, or
+ * hibernation. Those are the province of the deferred real-DO E2E.
+ */
+import { createRequire } from "node:module";
+import type { SqlStorageLike, SqlStorageCursorLike, TransactionSyncFn } from "../src/do-adapter";
+
+// Load `node:sqlite` lazily via createRequire — same pattern the node adapter uses — so importing
+// this module never eagerly resolves the (experimental) builtin unless a stand-in is constructed.
+interface NodeStmt {
+  all(...params: unknown[]): Record<string, unknown>[];
+}
+interface NodeDb {
+  exec(sql: string): void;
+  prepare(sql: string): NodeStmt;
+  close(): void;
+}
+
+type DoSqlValue = ArrayBuffer | ArrayBufferView | string | number | null;
+
+/** Re-shape a `node:sqlite` result cell to what a DO cursor would yield: BLOBs as `ArrayBuffer`
+ *  (node:sqlite hands back a `Uint8Array`/`Buffer`), everything else unchanged. */
+function toDoResultValue(v: unknown): DoSqlValue {
+  if (v instanceof ArrayBuffer) return v;
+  if (ArrayBuffer.isView(v)) {
+    // Copy out the exact byte window into a fresh, plain ArrayBuffer (node:sqlite yields a
+    // Uint8Array/Buffer for blobs; `.slice()` copies and its `.buffer` is a plain ArrayBuffer).
+    const bytes = new Uint8Array(v.buffer as ArrayBuffer, v.byteOffset, v.byteLength);
+    return bytes.slice().buffer;
+  }
+  if (typeof v === "bigint") return Number(v); // node:sqlite may widen; DO always yields number
+  return v as DoSqlValue;
+}
+
+function toDoRow(row: Record<string, unknown>): Record<string, DoSqlValue> {
+  const out: Record<string, DoSqlValue> = {};
+  for (const key in row) out[key] = toDoResultValue(row[key]);
+  return out;
+}
+
+class MemoryCursor implements SqlStorageCursorLike {
+  constructor(
+    private readonly rows: Record<string, DoSqlValue>[],
+    readonly rowsWritten: number,
+  ) {}
+  toArray(): Record<string, DoSqlValue>[] {
+    return this.rows;
+  }
+}
+
+// DO-SQLite forbids transaction-control statements through `exec`. Match on the leading keyword so
+// the stand-in rejects them exactly as the real API does, forcing atomicity through transactionSync.
+const TXN_CONTROL = /^\s*(begin|commit|rollback|savepoint|release)\b/i;
+
+export class MemorySqlStorage implements SqlStorageLike {
+  private readonly db: NodeDb;
+
+  constructor() {
+    const nodeRequire = createRequire(import.meta.url);
+    const { DatabaseSync } = nodeRequire("node:sqlite") as { DatabaseSync: new (path: string) => NodeDb };
+    this.db = new DatabaseSync(":memory:");
+    this.db.exec("PRAGMA foreign_keys = ON;");
+  }
+
+  exec(query: string, ...bindings: DoSqlValue[]): SqlStorageCursorLike {
+    if (TXN_CONTROL.test(query)) {
+      throw new Error(
+        `[memory-sql-storage] DO-SQLite rejects transaction-control statements via exec(): ${query.trim().slice(0, 40)}` +
+          ` — use transactionSync() instead`,
+      );
+    }
+    for (const b of bindings) {
+      if (typeof b === "bigint") {
+        throw new TypeError("[memory-sql-storage] DO-SQLite has no bigint binding type");
+      }
+    }
+
+    // A multi-statement string (the schema DDL) is only ever passed with zero bindings. `node:sqlite`'s
+    // prepare() silently compiles just the FIRST statement of such a string, so route it through
+    // db.exec() (which runs them all) — mirroring DO-SQLite, where a multi-statement exec runs every
+    // statement and yields an empty result. Detection: an inner `;` (the DocStore's single prepared
+    // statements never contain one; the schema has many).
+    const trimmed = query.trim().replace(/;\s*$/, "");
+    if (bindings.length === 0 && trimmed.includes(";")) {
+      this.db.exec(query);
+      return new MemoryCursor([], 0);
+    }
+
+    const stmt = this.db.prepare(trimmed);
+    const rows = stmt.all(...bindings); // executes; returns [] for a write with no RETURNING
+    // `changes()` reflects the row count of the most recent INSERT/UPDATE/DELETE on this connection —
+    // DO-SQLite's `rowsWritten`. (Irrelevant/stale after a pure SELECT, which the adapter ignores.)
+    const changes = Number(this.db.prepare("SELECT changes() AS c").all()[0]!.c as number | bigint);
+    return new MemoryCursor(rows.map(toDoRow), changes);
+  }
+
+  /** `ctx.storage.transactionSync` — the sole atomicity primitive. Implemented with real
+   *  BEGIN/COMMIT/ROLLBACK issued DIRECTLY on the underlying connection (bypassing our own `exec`
+   *  guard, which is what forbids the adapter from doing this). No nesting is needed: the DocStore
+   *  never nests `transaction()` calls. */
+  transactionSync: TransactionSyncFn = (closure) => {
+    this.db.exec("BEGIN");
+    try {
+      const result = closure();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (e) {
+      this.db.exec("ROLLBACK");
+      throw e;
+    }
+  };
+
+  close(): void {
+    this.db.close();
+  }
+}