@kyneta/sqlite-store 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Duane Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# @kyneta/sqlite-store
+
+SQLite storage backend for `@kyneta/exchange` — universal persistent storage for every deployment target.
+
+## Installation
+
+```sh
+pnpm add @kyneta/sqlite-store
+```
+
+Peer dependencies: `@kyneta/exchange`, `@kyneta/schema`, `@kyneta/sql-store-core`.
+
+You also need a SQLite binding of your choice — this package has **zero opinion** about which one you use. It works with any object conforming to the `SqliteAdapter` interface.
+
+## Usage
+
+### With `better-sqlite3` (Node.js)
+
+```ts
+import Database from "better-sqlite3"
+import { Exchange } from "@kyneta/exchange"
+import { createSqliteStore, fromBetterSqlite3 } from "@kyneta/sqlite-store"
+
+const db = new Database("./data/exchange.db")
+const store = createSqliteStore(fromBetterSqlite3(db))
+
+const exchange = new Exchange({
+  stores: [store],
+  // ...
+})
+```
+
+### With `bun:sqlite` (Bun)
+
+```ts
+import { Database } from "bun:sqlite"
+import { Exchange } from "@kyneta/exchange"
+import { createSqliteStore, fromBunSqlite } from "@kyneta/sqlite-store"
+
+const db = new Database("./data/exchange.db")
+const store = createSqliteStore(fromBunSqlite(db))
+
+const exchange = new Exchange({
+  stores: [store],
+  // ...
+})
+```
+
+### With Cloudflare Durable Objects
+
+DO's `ctx.storage.sql.exec(sql, ...params)` already returns an iterable cursor, so the adapter is essentially pass-through:
+
+```ts
+import { SqliteStore, type SqliteAdapter } from "@kyneta/sqlite-store"
+
+function fromCloudflareDoSql(ctx: DurableObjectState): SqliteAdapter {
+  return {
+    exec: (sql, ...params) => { ctx.storage.sql.exec(sql, ...params) },
+    iterate: (sql, ...params) => ctx.storage.sql.exec(sql, ...params),
+    // DO request handlers are implicitly transactional — each request runs
+    // atomically against storage. `transaction` just runs the function.
+    transaction: (fn) => fn(),
+    // DO storage doesn't have an explicit close — the actor lifecycle owns it.
+    close: () => {},
+  }
+}
+
+// In your DO class:
+const store = new SqliteStore(fromCloudflareDoSql(this.ctx))
+```
+
+### With any other binding
+
+Any object conforming to `SqliteAdapter` works:
+
+```ts
+import { SqliteStore, type SqliteAdapter } from "@kyneta/sqlite-store"
+
+const adapter: SqliteAdapter = {
+  exec(sql, ...params) { /* execute a write statement */ },
+  iterate(sql, ...params) { /* return an Iterable of rows (lazy) */ },
+  transaction(fn) { /* execute fn inside a transaction, return result */ },
+  close() { /* release resources */ },
+}
+
+const store = new SqliteStore(adapter)
+```
+
+## `SqliteAdapter` interface
+
+```ts
+interface SqliteAdapter {
+  exec(sql: string, ...params: unknown[]): void
+  iterate<T = Record<string, unknown>>(
+    sql: string,
+    ...params: unknown[]
+  ): Iterable<T>
+  transaction<R>(fn: () => R): R
+  close(): void
+}
+```
+
+Four methods: `exec` (write), `iterate` (read, returns a lazy `Iterable<T>`), `transaction` (atomic batch), `close` (release).
+
+## Recommended setup for `better-sqlite3` and `bun:sqlite`
+
+Enable WAL mode before constructing the store. Without it, readers block on writes:
+
+```ts
+const db = new Database("./data/exchange.db")
+db.exec("PRAGMA journal_mode = WAL")
+db.exec("PRAGMA synchronous = NORMAL")
+```
+
+Not needed for Cloudflare DO — the platform manages durability.
+
+## Options
+
+### `tables`
+
+```ts
+const store = new SqliteStore(adapter, {
+  tables: { meta: "app_meta", records: "app_records" },
+})
+```
+
+Default: `{ meta: "kyneta_meta", records: "kyneta_records" }`. Either or both names may be overridden.
+
+Use `tables` when co-locating Exchange tables alongside application tables in the same SQLite database (for example, in a Cloudflare Durable Object that also stores application state), or when running multiple isolated Exchange instances in one database with distinct table-name pairs.
+
+## Migration from v1.x
+
+`v2.0.0` replaces the `tablePrefix` option with an explicit `tables` pair, and changes the default table names from `meta` / `records` to `kyneta_meta` / `kyneta_records`. There is no compatibility shim.
+
+```ts
+// v1.x
+new SqliteStore(adapter)                                  // tables: meta, records
+new SqliteStore(adapter, { tablePrefix: "app_" })         // tables: app_meta, app_records
+
+// v2.0
+new SqliteStore(adapter)                                  // tables: kyneta_meta, kyneta_records
+new SqliteStore(adapter, {
+  tables: { meta: "app_meta", records: "app_records" },
+})
+```
+
+If you have existing data under the v1.x default names (`meta` / `records`), pass `tables: { meta: "meta", records: "records" }` explicitly to keep using them, or rename the tables via `ALTER TABLE`.
+
+## Schema
+
+The store creates two tables on first use:
+
+- **`tables.meta`** (default `kyneta_meta`) — materialized metadata index. `doc_id TEXT PRIMARY KEY`, `data TEXT NOT NULL` (JSON-encoded `StoreMeta`). `WITHOUT ROWID`.
+- **`tables.records`** (default `kyneta_records`) — per-document append-only record stream. Composite primary key `(doc_id, seq)`. Binary `Uint8Array` payloads are stored in a `BLOB` column; string/JSON payloads in a `TEXT` column. `WITHOUT ROWID`.
+
+## Store interface
+
+See the [`Store` interface](../../src/store/store.ts) in `@kyneta/exchange` for the full contract. Seven methods: `append`, `loadAll`, `replace`, `delete`, `currentMeta`, `listDocIds`, `close`.
+
+## Testing
+
+The package passes the full `describeStore` conformance suite (17 contract tests) exported from `@kyneta/exchange/testing`, plus SQLite-specific tests for close/reopen persistence, sequence number continuity, replace atomicity, adapter factories, and `tables` isolation.
+
+## See also
+
+- [`@kyneta/sql-store-core`](../sql-core/) — pure helpers shared with `postgres-store` and `prisma-store`.
+- [`@kyneta/postgres-store`](../postgres/) — async-native Postgres backend.
+- [`@kyneta/prisma-store`](../prisma/) — backend that takes a caller-supplied `PrismaClient`.

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { DocId, Store, StoreMeta, StoreRecord } from "@kyneta/exchange";
+import { TableNames } from "@kyneta/sql-store-core";
+
+//#region src/index.d.ts
+/**
+ * `iterate` returns `Iterable<T>` rather than `T[]` so `loadAll` can
+ * stream million-record stores without materializing them all in
+ * memory. Cloudflare DO's `ctx.storage.sql.exec` returns a cursor for
+ * the same reason; this shape is chosen to pass through.
+ */
+interface SqliteAdapter {
+  exec(sql: string, ...params: unknown[]): void;
+  iterate<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Iterable<T>;
+  transaction<R>(fn: () => R): R;
+  close(): void;
+}
+/**
+ * Wrap a `better-sqlite3` Database as a `SqliteAdapter`.
+ *
+ * @example
+ * ```typescript
+ * import Database from "better-sqlite3"
+ * import { SqliteStore, fromBetterSqlite3 } from "@kyneta/sqlite-store"
+ *
+ * const db = new Database("exchange.db")
+ * const store = new SqliteStore(fromBetterSqlite3(db))
+ * ```
+ */
+declare function fromBetterSqlite3(db: BetterSqlite3Database): SqliteAdapter;
+/**
+ * Wrap a `bun:sqlite` Database as a `SqliteAdapter`.
+ *
+ * @example
+ * ```typescript
+ * import { Database } from "bun:sqlite"
+ * import { SqliteStore, fromBunSqlite } from "@kyneta/sqlite-store"
+ *
+ * const db = new Database("exchange.db")
+ * const store = new SqliteStore(fromBunSqlite(db))
+ * ```
+ */
+declare function fromBunSqlite(db: BunSqliteDatabase): SqliteAdapter;
+/** Structural type for a `better-sqlite3` Database instance. */
+interface BetterSqlite3Database {
+  prepare(sql: string): {
+    run(...params: unknown[]): unknown;
+    iterate(...params: unknown[]): IterableIterator<unknown>;
+  };
+  transaction<R>(fn: () => R): () => R;
+  close(): void;
+}
+/** Structural type for a `bun:sqlite` Database instance. */
+interface BunSqliteDatabase {
+  run(sql: string, ...params: unknown[]): void;
+  query(sql: string): {
+    iterate(...params: unknown[]): IterableIterator<unknown>;
+  };
+  transaction<R>(fn: () => R): () => R;
+  close(): void;
+}
+interface SqliteStoreOptions {
+  /**
+   * Override the default table names (`kyneta_meta` and `kyneta_records`).
+   *
+   * Use when co-locating Exchange tables alongside application tables in
+   * the same SQLite database, or when running multiple isolated Exchange
+   * instances in one database. Either or both names may be overridden.
+   */
+  tables?: Partial<TableNames>;
+}
+declare class SqliteStore implements Store {
+  #private;
+  constructor(adapter: SqliteAdapter, options?: SqliteStoreOptions);
+  append(docId: DocId, record: StoreRecord): Promise<void>;
+  loadAll(docId: DocId): AsyncIterable<StoreRecord>;
+  replace(docId: DocId, records: StoreRecord[]): Promise<void>;
+  delete(docId: DocId): Promise<void>;
+  currentMeta(docId: DocId): Promise<StoreMeta | null>;
+  listDocIds(prefix?: string): AsyncIterable<DocId>;
+  close(): Promise<void>;
+}
+declare function createSqliteStore(adapter: SqliteAdapter, options?: SqliteStoreOptions): Store;
+//#endregion
+export { SqliteAdapter, SqliteStore, SqliteStoreOptions, createSqliteStore, fromBetterSqlite3, fromBunSqlite };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;AAmCA;;;;UAAiB,aAAA;EACf,IAAA,CAAK,GAAA,aAAgB,MAAA;EACrB,OAAA,KAAY,MAAA,mBACV,GAAA,aACG,MAAA,cACF,QAAA,CAAS,CAAA;EACZ,WAAA,IAAe,EAAA,QAAU,CAAA,GAAI,CAAA;EAC7B,KAAA;AAAA;;;;;;;;;;;;;iBAmBc,iBAAA,CAAkB,EAAA,EAAI,qBAAA,GAAwB,aAAA;;;;;;AAA9D;;;;;;;iBAgCgB,aAAA,CAAc,EAAA,EAAI,iBAAA,GAAoB,aAAA;;UAyB5C,qBAAA;EACR,OAAA,CAAQ,GAAA;IACN,GAAA,IAAO,MAAA;IACP,OAAA,IAAW,MAAA,cAAoB,gBAAA;EAAA;EAEjC,WAAA,IAAe,EAAA,QAAU,CAAA,SAAU,CAAA;EACnC,KAAA;AAAA;;UAIQ,iBAAA;EACR,GAAA,CAAI,GAAA,aAAgB,MAAA;EACpB,KAAA,CAAM,GAAA;IACJ,OAAA,IAAW,MAAA,cAAoB,gBAAA;EAAA;EAEjC,WAAA,IAAe,EAAA,QAAU,CAAA,SAAU,CAAA;EACnC,KAAA;AAAA;AAAA,UAOe,kBAAA;EAtBP;;;;;;;EA8BR,MAAA,GAAS,OAAA,CAAQ,UAAA;AAAA;AAAA,cAON,WAAA,YAAuB,KAAA;EAAA;cAKtB,OAAA,EAAS,aAAA,EAAe,OAAA,GAAS,kBAAA;EA6BvC,MAAA,CAAO,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,WAAA,GAAc,OAAA;EAkC1C,OAAA,CAAQ,KAAA,EAAO,KAAA,GAAQ,aAAA,CAAc,WAAA;EAStC,OAAA,CAAQ,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,WAAA,KAAgB,OAAA;EAoC/C,MAAA,CAAO,KAAA,EAAO,KAAA,GAAQ,OAAA;EActB,WAAA,CAAY,KAAA,EAAO,KAAA,GAAQ,OAAA,CAAQ,SAAA;EASlC,UAAA,CAAW,MAAA,YAAkB,aAAA,CAAc,KAAA;EAe5C,KAAA,CAAA,GAAS,OAAA;AAAA;AAAA,iBAsBD,iBAAA,CACd,OAAA,EAAS,aAAA,EACT,OAAA,GAAU,kBAAA,GACT,KAAA"}

package/dist/index.js

@@ -0,0 +1,144 @@
+import { SeqNoTracker } from "@kyneta/exchange";
+import { fromRow, planAppend, planReplace, resolveTables } from "@kyneta/sql-store-core";
+//#region src/index.ts
+/**
+* Wrap a `better-sqlite3` Database as a `SqliteAdapter`.
+*
+* @example
+* ```typescript
+* import Database from "better-sqlite3"
+* import { SqliteStore, fromBetterSqlite3 } from "@kyneta/sqlite-store"
+*
+* const db = new Database("exchange.db")
+* const store = new SqliteStore(fromBetterSqlite3(db))
+* ```
+*/
+function fromBetterSqlite3(db) {
+	return {
+		exec(sql, ...params) {
+			db.prepare(sql).run(...params);
+		},
+		iterate(sql, ...params) {
+			return db.prepare(sql).iterate(...params);
+		},
+		transaction(fn) {
+			return db.transaction(fn)();
+		},
+		close() {
+			db.close();
+		}
+	};
+}
+/**
+* Wrap a `bun:sqlite` Database as a `SqliteAdapter`.
+*
+* @example
+* ```typescript
+* import { Database } from "bun:sqlite"
+* import { SqliteStore, fromBunSqlite } from "@kyneta/sqlite-store"
+*
+* const db = new Database("exchange.db")
+* const store = new SqliteStore(fromBunSqlite(db))
+* ```
+*/
+function fromBunSqlite(db) {
+	return {
+		exec(sql, ...params) {
+			db.run(sql, ...params);
+		},
+		iterate(sql, ...params) {
+			return db.query(sql).iterate(...params);
+		},
+		transaction(fn) {
+			return db.transaction(fn)();
+		},
+		close() {
+			db.close();
+		}
+	};
+}
+var SqliteStore = class {
+	#adapter;
+	#seqNos = new SeqNoTracker();
+	#tables;
+	constructor(adapter, options = {}) {
+		this.#adapter = adapter;
+		this.#tables = resolveTables(options);
+		this.#ensureSchema();
+	}
+	#ensureSchema() {
+		this.#adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.#tables.meta} (
+        doc_id  TEXT PRIMARY KEY,
+        data    TEXT NOT NULL
+      ) WITHOUT ROWID
+    `);
+		this.#adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.#tables.records} (
+        doc_id  TEXT    NOT NULL,
+        seq     INTEGER NOT NULL,
+        kind    TEXT    NOT NULL,
+        payload TEXT,
+        blob    BLOB,
+        PRIMARY KEY (doc_id, seq)
+      ) WITHOUT ROWID
+    `);
+	}
+	async append(docId, record) {
+		const plan = planAppend(docId, record, await this.currentMeta(docId), await this.#seqNos.next(docId, async () => {
+			const [row] = this.#adapter.iterate(`SELECT MAX(seq) AS max_seq FROM ${this.#tables.records} WHERE doc_id = ?`, docId);
+			return row?.max_seq ?? null;
+		}));
+		this.#adapter.transaction(() => {
+			if (plan.upsertMeta !== null) this.#adapter.exec(`INSERT OR REPLACE INTO ${this.#tables.meta} (doc_id, data) VALUES (?, ?)`, docId, plan.upsertMeta.data);
+			const { row } = plan.insertRecord;
+			this.#adapter.exec(`INSERT INTO ${this.#tables.records} (doc_id, seq, kind, payload, blob) VALUES (?, ?, ?, ?, ?)`, docId, plan.insertRecord.seq, row.kind, row.payload, row.blob);
+		});
+	}
+	async *loadAll(docId) {
+		for (const row of this.#adapter.iterate(`SELECT kind, payload, blob FROM ${this.#tables.records} WHERE doc_id = ? ORDER BY seq`, docId)) yield fromRow(row);
+	}
+	async replace(docId, records) {
+		const plan = planReplace(records, await this.currentMeta(docId));
+		this.#adapter.transaction(() => {
+			this.#adapter.exec(`DELETE FROM ${this.#tables.records} WHERE doc_id = ?`, docId);
+			for (const { seq, row } of plan.records) this.#adapter.exec(`INSERT INTO ${this.#tables.records} (doc_id, seq, kind, payload, blob) VALUES (?, ?, ?, ?, ?)`, docId, seq, row.kind, row.payload, row.blob);
+			this.#adapter.exec(`INSERT OR REPLACE INTO ${this.#tables.meta} (doc_id, data) VALUES (?, ?)`, docId, plan.upsertMeta.data);
+		});
+		this.#seqNos.reset(docId, records.length - 1);
+	}
+	async delete(docId) {
+		this.#adapter.transaction(() => {
+			this.#adapter.exec(`DELETE FROM ${this.#tables.records} WHERE doc_id = ?`, docId);
+			this.#adapter.exec(`DELETE FROM ${this.#tables.meta} WHERE doc_id = ?`, docId);
+		});
+		this.#seqNos.remove(docId);
+	}
+	async currentMeta(docId) {
+		const [row] = this.#adapter.iterate(`SELECT data FROM ${this.#tables.meta} WHERE doc_id = ?`, docId);
+		if (row === void 0) return null;
+		return JSON.parse(row.data);
+	}
+	async *listDocIds(prefix) {
+		const rows = prefix !== void 0 ? this.#adapter.iterate(`SELECT doc_id FROM ${this.#tables.meta} WHERE doc_id LIKE ? ESCAPE '\\'`, `${escapeLike(prefix)}%`) : this.#adapter.iterate(`SELECT doc_id FROM ${this.#tables.meta}`);
+		for (const row of rows) yield row.doc_id;
+	}
+	async close() {
+		this.#adapter.close();
+	}
+};
+/**
+* SQLite's LIKE treats `%` and `_` as wildcards. Escape them (and the
+* escape char itself) so doc IDs containing those characters are
+* matched literally. The query declares `ESCAPE '\'`.
+*/
+function escapeLike(value) {
+	return value.replace(/[%_\\]/g, (ch) => `\\${ch}`);
+}
+function createSqliteStore(adapter, options) {
+	return new SqliteStore(adapter, options);
+}
+//#endregion
+export { SqliteStore, createSqliteStore, fromBetterSqlite3, fromBunSqlite };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#adapter","#seqNos","#tables","#ensureSchema"],"sources":["../src/index.ts"],"sourcesContent":["// SQLite Store backend.\n//\n// Why a thin adapter rather than a direct better-sqlite3 dependency: the\n// adapter shape is deliberately synchronous because every supported\n// SQLite binding is sync (better-sqlite3, bun:sqlite, Cloudflare DO's\n// ctx.storage.sql). Forcing async here would dilute that ergonomics for\n// no benefit, since postgres-store and prisma-store get their own\n// async-native packages.\n\nimport {\n  type DocId,\n  SeqNoTracker,\n  type Store,\n  type StoreMeta,\n  type StoreRecord,\n} from \"@kyneta/exchange\"\nimport {\n  fromRow,\n  planAppend,\n  planReplace,\n  type RowShape,\n  resolveTables,\n  type TableNames,\n} from \"@kyneta/sql-store-core\"\n\n// ---------------------------------------------------------------------------\n// SqliteAdapter — minimal synchronous database interface\n// ---------------------------------------------------------------------------\n\n/**\n * `iterate` returns `Iterable<T>` rather than `T[]` so `loadAll` can\n * stream million-record stores without materializing them all in\n * memory. Cloudflare DO's `ctx.storage.sql.exec` returns a cursor for\n * the same reason; this shape is chosen to pass through.\n */\nexport interface SqliteAdapter {\n  exec(sql: string, ...params: unknown[]): void\n  iterate<T = Record<string, unknown>>(\n    sql: string,\n    ...params: unknown[]\n  ): Iterable<T>\n  transaction<R>(fn: () => R): R\n  close(): void\n}\n\n// ---------------------------------------------------------------------------\n// Adapter factories\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a `better-sqlite3` Database as a `SqliteAdapter`.\n *\n * @example\n * ```typescript\n * import Database from \"better-sqlite3\"\n * import { SqliteStore, fromBetterSqlite3 } from \"@kyneta/sqlite-store\"\n *\n * const db = new Database(\"exchange.db\")\n * const store = new SqliteStore(fromBetterSqlite3(db))\n * ```\n */\nexport function fromBetterSqlite3(db: BetterSqlite3Database): SqliteAdapter {\n  return {\n    exec(sql: string, ...params: unknown[]): void {\n      db.prepare(sql).run(...params)\n    },\n    iterate<T = Record<string, unknown>>(\n      sql: string,\n      ...params: unknown[]\n    ): Iterable<T> {\n      return db.prepare(sql).iterate(...params) as IterableIterator<T>\n    },\n    transaction<R>(fn: () => R): R {\n      return db.transaction(fn)()\n    },\n    close(): void {\n      db.close()\n    },\n  }\n}\n\n/**\n * Wrap a `bun:sqlite` Database as a `SqliteAdapter`.\n *\n * @example\n * ```typescript\n * import { Database } from \"bun:sqlite\"\n * import { SqliteStore, fromBunSqlite } from \"@kyneta/sqlite-store\"\n *\n * const db = new Database(\"exchange.db\")\n * const store = new SqliteStore(fromBunSqlite(db))\n * ```\n */\nexport function fromBunSqlite(db: BunSqliteDatabase): SqliteAdapter {\n  return {\n    exec(sql: string, ...params: unknown[]): void {\n      db.run(sql, ...params)\n    },\n    iterate<T = Record<string, unknown>>(\n      sql: string,\n      ...params: unknown[]\n    ): Iterable<T> {\n      return db.query(sql).iterate(...params) as IterableIterator<T>\n    },\n    transaction<R>(fn: () => R): R {\n      return db.transaction(fn)()\n    },\n    close(): void {\n      db.close()\n    },\n  }\n}\n\n// Minimal structural types for the two primary SQLite bindings.\n// These avoid a hard dependency on `better-sqlite3` or `bun:sqlite` types\n// at runtime — the caller provides the concrete database instance.\n\n/** Structural type for a `better-sqlite3` Database instance. */\ninterface BetterSqlite3Database {\n  prepare(sql: string): {\n    run(...params: unknown[]): unknown\n    iterate(...params: unknown[]): IterableIterator<unknown>\n  }\n  transaction<R>(fn: () => R): () => R\n  close(): void\n}\n\n/** Structural type for a `bun:sqlite` Database instance. */\ninterface BunSqliteDatabase {\n  run(sql: string, ...params: unknown[]): void\n  query(sql: string): {\n    iterate(...params: unknown[]): IterableIterator<unknown>\n  }\n  transaction<R>(fn: () => R): () => R\n  close(): void\n}\n\n// ---------------------------------------------------------------------------\n// SqliteStore options\n// ---------------------------------------------------------------------------\n\nexport interface SqliteStoreOptions {\n  /**\n   * Override the default table names (`kyneta_meta` and `kyneta_records`).\n   *\n   * Use when co-locating Exchange tables alongside application tables in\n   * the same SQLite database, or when running multiple isolated Exchange\n   * instances in one database. Either or both names may be overridden.\n   */\n  tables?: Partial<TableNames>\n}\n\n// ---------------------------------------------------------------------------\n// SqliteStore\n// ---------------------------------------------------------------------------\n\nexport class SqliteStore implements Store {\n  readonly #adapter: SqliteAdapter\n  readonly #seqNos = new SeqNoTracker()\n  readonly #tables: TableNames\n\n  constructor(adapter: SqliteAdapter, options: SqliteStoreOptions = {}) {\n    this.#adapter = adapter\n    this.#tables = resolveTables(options)\n    this.#ensureSchema()\n  }\n\n  #ensureSchema(): void {\n    this.#adapter.exec(`\n      CREATE TABLE IF NOT EXISTS ${this.#tables.meta} (\n        doc_id  TEXT PRIMARY KEY,\n        data    TEXT NOT NULL\n      ) WITHOUT ROWID\n    `)\n    this.#adapter.exec(`\n      CREATE TABLE IF NOT EXISTS ${this.#tables.records} (\n        doc_id  TEXT    NOT NULL,\n        seq     INTEGER NOT NULL,\n        kind    TEXT    NOT NULL,\n        payload TEXT,\n        blob    BLOB,\n        PRIMARY KEY (doc_id, seq)\n      ) WITHOUT ROWID\n    `)\n  }\n\n  // -------------------------------------------------------------------------\n  // Store interface\n  // -------------------------------------------------------------------------\n\n  async append(docId: DocId, record: StoreRecord): Promise<void> {\n    const existingMeta = await this.currentMeta(docId)\n    const seq = await this.#seqNos.next(docId, async () => {\n      const [row] = this.#adapter.iterate<{ max_seq: number | null }>(\n        `SELECT MAX(seq) AS max_seq FROM ${this.#tables.records} WHERE doc_id = ?`,\n        docId,\n      )\n      return row?.max_seq ?? null\n    })\n\n    const plan = planAppend(docId, record, existingMeta, seq)\n\n    // Both writes must commit together or neither — a crash between\n    // them used to leave meta updated with no corresponding row.\n    this.#adapter.transaction(() => {\n      if (plan.upsertMeta !== null) {\n        this.#adapter.exec(\n          `INSERT OR REPLACE INTO ${this.#tables.meta} (doc_id, data) VALUES (?, ?)`,\n          docId,\n          plan.upsertMeta.data,\n        )\n      }\n      const { row } = plan.insertRecord\n      this.#adapter.exec(\n        `INSERT INTO ${this.#tables.records} (doc_id, seq, kind, payload, blob) VALUES (?, ?, ?, ?, ?)`,\n        docId,\n        plan.insertRecord.seq,\n        row.kind,\n        row.payload,\n        row.blob,\n      )\n    })\n  }\n\n  async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {\n    for (const row of this.#adapter.iterate<RowShape>(\n      `SELECT kind, payload, blob FROM ${this.#tables.records} WHERE doc_id = ? ORDER BY seq`,\n      docId,\n    )) {\n      yield fromRow(row)\n    }\n  }\n\n  async replace(docId: DocId, records: StoreRecord[]): Promise<void> {\n    const existingMeta = await this.currentMeta(docId)\n    const plan = planReplace(records, existingMeta)\n\n    this.#adapter.transaction(() => {\n      this.#adapter.exec(\n        `DELETE FROM ${this.#tables.records} WHERE doc_id = ?`,\n        docId,\n      )\n\n      for (const { seq, row } of plan.records) {\n        this.#adapter.exec(\n          `INSERT INTO ${this.#tables.records} (doc_id, seq, kind, payload, blob) VALUES (?, ?, ?, ?, ?)`,\n          docId,\n          seq,\n          row.kind,\n          row.payload,\n          row.blob,\n        )\n      }\n\n      this.#adapter.exec(\n        `INSERT OR REPLACE INTO ${this.#tables.meta} (doc_id, data) VALUES (?, ?)`,\n        docId,\n        plan.upsertMeta.data,\n      )\n    })\n\n    // Must run after the transaction commits. If `transaction()` throws,\n    // control jumps past this line; the cache stays unmutated. Moving\n    // this inside the callback or before the call would corrupt the\n    // cache on rollback — the next append would compute a seq that\n    // collides with restored rows on the (doc_id, seq) primary key.\n    this.#seqNos.reset(docId, records.length - 1)\n  }\n\n  async delete(docId: DocId): Promise<void> {\n    this.#adapter.transaction(() => {\n      this.#adapter.exec(\n        `DELETE FROM ${this.#tables.records} WHERE doc_id = ?`,\n        docId,\n      )\n      this.#adapter.exec(\n        `DELETE FROM ${this.#tables.meta} WHERE doc_id = ?`,\n        docId,\n      )\n    })\n    this.#seqNos.remove(docId)\n  }\n\n  async currentMeta(docId: DocId): Promise<StoreMeta | null> {\n    const [row] = this.#adapter.iterate<{ data: string }>(\n      `SELECT data FROM ${this.#tables.meta} WHERE doc_id = ?`,\n      docId,\n    )\n    if (row === undefined) return null\n    return JSON.parse(row.data) as StoreMeta\n  }\n\n  async *listDocIds(prefix?: string): AsyncIterable<DocId> {\n    const rows =\n      prefix !== undefined\n        ? this.#adapter.iterate<{ doc_id: string }>(\n            `SELECT doc_id FROM ${this.#tables.meta} WHERE doc_id LIKE ? ESCAPE '\\\\'`,\n            `${escapeLike(prefix)}%`,\n          )\n        : this.#adapter.iterate<{ doc_id: string }>(\n            `SELECT doc_id FROM ${this.#tables.meta}`,\n          )\n    for (const row of rows) {\n      yield row.doc_id\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#adapter.close()\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * SQLite's LIKE treats `%` and `_` as wildcards. Escape them (and the\n * escape char itself) so doc IDs containing those characters are\n * matched literally. The query declares `ESCAPE '\\'`.\n */\nfunction escapeLike(value: string): string {\n  return value.replace(/[%_\\\\]/g, ch => `\\\\${ch}`)\n}\n\n// ---------------------------------------------------------------------------\n// Factory function\n// ---------------------------------------------------------------------------\n\nexport function createSqliteStore(\n  adapter: SqliteAdapter,\n  options?: SqliteStoreOptions,\n): Store {\n  return new SqliteStore(adapter, options)\n}\n"],"mappings":";;;;;;;;;;;;;;;AA6DA,SAAgB,kBAAkB,IAA0C;AAC1E,QAAO;EACL,KAAK,KAAa,GAAG,QAAyB;AAC5C,MAAG,QAAQ,IAAI,CAAC,IAAI,GAAG,OAAO;;EAEhC,QACE,KACA,GAAG,QACU;AACb,UAAO,GAAG,QAAQ,IAAI,CAAC,QAAQ,GAAG,OAAO;;EAE3C,YAAe,IAAgB;AAC7B,UAAO,GAAG,YAAY,GAAG,EAAE;;EAE7B,QAAc;AACZ,MAAG,OAAO;;EAEb;;;;;;;;;;;;;;AAeH,SAAgB,cAAc,IAAsC;AAClE,QAAO;EACL,KAAK,KAAa,GAAG,QAAyB;AAC5C,MAAG,IAAI,KAAK,GAAG,OAAO;;EAExB,QACE,KACA,GAAG,QACU;AACb,UAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,GAAG,OAAO;;EAEzC,YAAe,IAAgB;AAC7B,UAAO,GAAG,YAAY,GAAG,EAAE;;EAE7B,QAAc;AACZ,MAAG,OAAO;;EAEb;;AA8CH,IAAa,cAAb,MAA0C;CACxC;CACA,UAAmB,IAAI,cAAc;CACrC;CAEA,YAAY,SAAwB,UAA8B,EAAE,EAAE;AACpE,QAAA,UAAgB;AAChB,QAAA,SAAe,cAAc,QAAQ;AACrC,QAAA,cAAoB;;CAGtB,gBAAsB;AACpB,QAAA,QAAc,KAAK;mCACY,MAAA,OAAa,KAAK;;;;MAI/C;AACF,QAAA,QAAc,KAAK;mCACY,MAAA,OAAa,QAAQ;;;;;;;;MAQlD;;CAOJ,MAAM,OAAO,OAAc,QAAoC;EAU7D,MAAM,OAAO,WAAW,OAAO,QATV,MAAM,KAAK,YAAY,MAAM,EACtC,MAAM,MAAA,OAAa,KAAK,OAAO,YAAY;GACrD,MAAM,CAAC,OAAO,MAAA,QAAc,QAC1B,mCAAmC,MAAA,OAAa,QAAQ,oBACxD,MACD;AACD,UAAO,KAAK,WAAW;IACvB,CAEuD;AAIzD,QAAA,QAAc,kBAAkB;AAC9B,OAAI,KAAK,eAAe,KACtB,OAAA,QAAc,KACZ,0BAA0B,MAAA,OAAa,KAAK,gCAC5C,OACA,KAAK,WAAW,KACjB;GAEH,MAAM,EAAE,QAAQ,KAAK;AACrB,SAAA,QAAc,KACZ,eAAe,MAAA,OAAa,QAAQ,6DACpC,OACA,KAAK,aAAa,KAClB,IAAI,MACJ,IAAI,SACJ,IAAI,KACL;IACD;;CAGJ,OAAO,QAAQ,OAA0C;AACvD,OAAK,MAAM,OAAO,MAAA,QAAc,QAC9B,mCAAmC,MAAA,OAAa,QAAQ,iCACxD,MACD,CACC,OAAM,QAAQ,IAAI;;CAItB,MAAM,QAAQ,OAAc,SAAuC;EAEjE,MAAM,OAAO,YAAY,SADJ,MAAM,KAAK,YAAY,MAAM,CACH;AAE/C,QAAA,QAAc,kBAAkB;AAC9B,SAAA,QAAc,KACZ,eAAe,MAAA,OAAa,QAAQ,oBACpC,MACD;AAED,QAAK,MAAM,EAAE,KAAK,SAAS,KAAK,QAC9B,OAAA,QAAc,KACZ,eAAe,MAAA,OAAa,QAAQ,6DACpC,OACA,KACA,IAAI,MACJ,IAAI,SACJ,IAAI,KACL;AAGH,SAAA,QAAc,KACZ,0BAA0B,MAAA,OAAa,KAAK,gCAC5C,OACA,KAAK,WAAW,KACjB;IACD;AAOF,QAAA,OAAa,MAAM,OAAO,QAAQ,SAAS,EAAE;;CAG/C,MAAM,OAAO,OAA6B;AACxC,QAAA,QAAc,kBAAkB;AAC9B,SAAA,QAAc,KACZ,eAAe,MAAA,OAAa,QAAQ,oBACpC,MACD;AACD,SAAA,QAAc,KACZ,eAAe,MAAA,OAAa,KAAK,oBACjC,MACD;IACD;AACF,QAAA,OAAa,OAAO,MAAM;;CAG5B,MAAM,YAAY,OAAyC;EACzD,MAAM,CAAC,OAAO,MAAA,QAAc,QAC1B,oBAAoB,MAAA,OAAa,KAAK,oBACtC,MACD;AACD,MAAI,QAAQ,KAAA,EAAW,QAAO;AAC9B,SAAO,KAAK,MAAM,IAAI,KAAK;;CAG7B,OAAO,WAAW,QAAuC;EACvD,MAAM,OACJ,WAAW,KAAA,IACP,MAAA,QAAc,QACZ,sBAAsB,MAAA,OAAa,KAAK,mCACxC,GAAG,WAAW,OAAO,CAAC,GACvB,GACD,MAAA,QAAc,QACZ,sBAAsB,MAAA,OAAa,OACpC;AACP,OAAK,MAAM,OAAO,KAChB,OAAM,IAAI;;CAId,MAAM,QAAuB;AAC3B,QAAA,QAAc,OAAO;;;;;;;;AAazB,SAAS,WAAW,OAAuB;AACzC,QAAO,MAAM,QAAQ,YAAW,OAAM,KAAK,KAAK;;AAOlD,SAAgB,kBACd,SACA,SACO;AACP,QAAO,IAAI,YAAY,SAAS,QAAQ"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kyneta/sqlite-store",
+  "version": "1.5.0",
+  "description": "SQLite storage backend for @kyneta/exchange — universal persistent storage",
+  "author": "Duane Johnson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halecraft/kyneta",
+    "directory": "packages/exchange/stores/sqlite"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./src": "./src/index.ts",
+    "./src/*": "./src/*"
+  },
+  "peerDependencies": {
+    "@kyneta/exchange": "^1.5.0",
+    "@kyneta/schema": "^1.5.0",
+    "@kyneta/sql-store-core": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22",
+    "better-sqlite3": "^11.9.1",
+    "tsdown": "^0.21.9",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.17",
+    "@kyneta/sql-store-core": "^1.5.0",
+    "@kyneta/exchange": "^1.5.0",
+    "@kyneta/schema": "^1.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "verify logic",
+    "verify": "verify"
+  }
+}

package/src/__tests__/sqlite-store.test.ts

@@ -0,0 +1,289 @@
+// sqlite-store — conformance + SQLite-specific tests.
+
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import {
+  collectAll,
+  describeStore,
+  makeEntryRecord,
+  makeMetaRecord,
+  plainMeta,
+} from "@kyneta/exchange/testing"
+import Database from "better-sqlite3"
+import { afterAll, describe, expect, it } from "vitest"
+import { fromBetterSqlite3, type SqliteAdapter, SqliteStore } from "../index.js"
+
+/**
+ * Why `arm(n)` instead of a constructor-time `failOnNth`: schema DDL
+ * runs `exec` during `SqliteStore` construction. We need the counter
+ * latent until after the priming append succeeds, so the conformance
+ * test can target a specific subsequent write call.
+ */
+function makeFaultyAdapter(base: SqliteAdapter): {
+  adapter: SqliteAdapter
+  arm: (n: number) => void
+} {
+  let armed: number | null = null
+  let count = 0
+  const adapter: SqliteAdapter = {
+    exec(sql, ...params) {
+      if (armed !== null) {
+        count += 1
+        if (count === armed) {
+          throw new Error(`fault-injected: exec call #${count}`)
+        }
+      }
+      base.exec(sql, ...params)
+    },
+    iterate: base.iterate.bind(base),
+    transaction: base.transaction.bind(base),
+    close: base.close.bind(base),
+  }
+  return {
+    adapter,
+    arm: n => {
+      armed = n
+      count = 0
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Temp file management
+// ---------------------------------------------------------------------------
+
+const tmpDirs: string[] = []
+
+function makeTmpFile(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "kyneta-sqlite-test-"))
+  const file = path.join(dir, "test.db")
+  tmpDirs.push(dir)
+  return file
+}
+
+afterAll(() => {
+  for (const dir of tmpDirs) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true })
+    } catch {
+      // best-effort cleanup
+    }
+  }
+})
+
+// ---------------------------------------------------------------------------
+// Conformance suite — validates the full Store contract (17 tests)
+// ---------------------------------------------------------------------------
+
+describeStore(
+  "SqliteStore",
+  () => {
+    const db = new Database(":memory:")
+    return new SqliteStore(fromBetterSqlite3(db))
+  },
+  {
+    cleanup: async backend => {
+      await backend.close()
+    },
+    // The harness counts only after `arm(n)`, so schema DDL during
+    // `SqliteStore` construction (a sequence of `exec` calls) doesn't
+    // trip the counter. A meta-record append issues 2 execs (meta
+    // upsert + record insert) inside one transaction; arming n=2 fires
+    // mid-transaction so rollback is observable.
+    faultFactory: async () => {
+      const file = makeTmpFile()
+      const db = new Database(file)
+      const base = fromBetterSqlite3(db)
+      const { adapter, arm } = makeFaultyAdapter(base)
+      const store = new SqliteStore(adapter)
+      return {
+        store,
+        injectFault: arm,
+        // freshStore opens a separate connection on the same file. The
+        // primary `db` connection is used by `store`; the fresh one is
+        // independent so its lifecycle is the caller's.
+        freshStore: async () => {
+          const freshDb = new Database(file)
+          return new SqliteStore(fromBetterSqlite3(freshDb))
+        },
+        cleanup: async () => {
+          await store.close()
+        },
+      }
+    },
+    isolationFactory: async () => {
+      const db = new Database(":memory:")
+      const adapter = fromBetterSqlite3(db)
+      return {
+        storeA: new SqliteStore(adapter, {
+          tables: { meta: "a_meta", records: "a_records" },
+        }),
+        storeB: new SqliteStore(adapter, {
+          tables: { meta: "b_meta", records: "b_records" },
+        }),
+        // Both stores share `adapter`; closing it once tears down both.
+        cleanup: async () => {
+          adapter.close()
+        },
+      }
+    },
+  },
+)
+
+// ---------------------------------------------------------------------------
+// SQLite-specific tests
+// ---------------------------------------------------------------------------
+
+describe("SqliteStore — persistence across close + reopen", () => {
+  it("data, metadata, and seq numbers survive close and reopen", async () => {
+    const file = makeTmpFile()
+
+    const db1 = new Database(file)
+    const store1 = new SqliteStore(fromBetterSqlite3(db1))
+    await store1.append("doc-1", makeMetaRecord())
+    await store1.append("doc-1", makeEntryRecord("entirety", "v1"))
+    await store1.append("doc-1", makeEntryRecord("since", "v2"))
+    await store1.close()
+
+    // Reopen, verify persisted data, then append and verify seq continuity
+    const db2 = new Database(file)
+    const store2 = new SqliteStore(fromBetterSqlite3(db2))
+    expect(await store2.currentMeta("doc-1")).toEqual(plainMeta)
+
+    await store2.append("doc-1", makeEntryRecord("since", "v3"))
+
+    const records = await collectAll(store2.loadAll("doc-1"))
+    expect(records).toHaveLength(4)
+    const versions = records
+      .filter(r => r.kind === "entry")
+      .map(r => (r as { kind: "entry"; version: string }).version)
+    expect(versions).toEqual(["v1", "v2", "v3"])
+    await store2.close()
+  })
+})
+
+describe("SqliteStore — adapter factory", () => {
+  it("fromBetterSqlite3 exec, iterate, and transaction round-trip", () => {
+    const db = new Database(":memory:")
+    const adapter = fromBetterSqlite3(db)
+
+    adapter.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)")
+    adapter.exec("INSERT INTO test (id, value) VALUES (?, ?)", 1, "hello")
+    adapter.exec("INSERT INTO test (id, value) VALUES (?, ?)", 2, "world")
+
+    const rows = Array.from(
+      adapter.iterate<{ id: number; value: string }>(
+        "SELECT * FROM test ORDER BY id",
+      ),
+    )
+    expect(rows).toEqual([
+      { id: 1, value: "hello" },
+      { id: 2, value: "world" },
+    ])
+
+    adapter.close()
+  })
+
+  it("iterate releases the statement on early termination", () => {
+    // Without proper iterator-return semantics, better-sqlite3 throws
+    // "This statement is busy" on the second iterate call below.
+    const db = new Database(":memory:")
+    const adapter = fromBetterSqlite3(db)
+
+    adapter.exec("CREATE TABLE test (id INTEGER PRIMARY KEY)")
+    adapter.exec("INSERT INTO test VALUES (1), (2), (3)")
+
+    const [first] = adapter.iterate<{ id: number }>(
+      "SELECT id FROM test ORDER BY id",
+    )
+    expect(first?.id).toBe(1)
+
+    const all = Array.from(
+      adapter.iterate<{ id: number }>("SELECT id FROM test ORDER BY id"),
+    )
+    expect(all).toHaveLength(3)
+
+    adapter.close()
+  })
+
+  it("fromBetterSqlite3 transaction rolls back on throw", () => {
+    const db = new Database(":memory:")
+    const adapter = fromBetterSqlite3(db)
+
+    adapter.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)")
+    adapter.exec("INSERT INTO test (id, value) VALUES (?, ?)", 1, "original")
+
+    expect(() =>
+      adapter.transaction(() => {
+        adapter.exec("UPDATE test SET value = ? WHERE id = ?", "modified", 1)
+        throw new Error("rollback")
+      }),
+    ).toThrow("rollback")
+
+    const [row] = adapter.iterate<{ value: string }>(
+      "SELECT value FROM test WHERE id = ?",
+      1,
+    )
+    expect(row?.value).toBe("original")
+
+    adapter.close()
+  })
+})
+
+describe("SqliteStore — tables isolation", () => {
+  it("two stores with different table names coexist in the same database", async () => {
+    const db = new Database(":memory:")
+    const adapter = fromBetterSqlite3(db)
+
+    const store1 = new SqliteStore(adapter, {
+      tables: { meta: "app1_meta", records: "app1_records" },
+    })
+    const store2 = new SqliteStore(adapter, {
+      tables: { meta: "app2_meta", records: "app2_records" },
+    })
+
+    await store1.append("doc-1", makeMetaRecord())
+    await store1.append("doc-1", makeEntryRecord("entirety", "v1-app1"))
+
+    await store2.append("doc-1", makeMetaRecord())
+    await store2.append("doc-1", makeEntryRecord("entirety", "v1-app2"))
+
+    const records1 = await collectAll(store1.loadAll("doc-1"))
+    const records2 = await collectAll(store2.loadAll("doc-1"))
+
+    expect(records1).toHaveLength(2)
+    expect(records2).toHaveLength(2)
+
+    const entry1 = records1.find(r => r.kind === "entry")
+    const entry2 = records2.find(r => r.kind === "entry")
+
+    if (entry1?.kind === "entry") expect(entry1.version).toBe("v1-app1")
+    if (entry2?.kind === "entry") expect(entry2.version).toBe("v1-app2")
+
+    adapter.close()
+  })
+})
+
+describe("SqliteStore — listDocIds with LIKE-special characters", () => {
+  it("prefix containing % and _ matches literally, not as wildcards", async () => {
+    const db = new Database(":memory:")
+    const store = new SqliteStore(fromBetterSqlite3(db))
+
+    // Create docs with tricky names
+    await store.append("100%_done", makeMetaRecord())
+    await store.append("100_other", makeMetaRecord())
+    await store.append("100xyz", makeMetaRecord())
+    await store.append("other", makeMetaRecord())
+
+    // "100%" should match only "100%_done", not "100_other" or "100xyz"
+    const matched = await collectAll(store.listDocIds("100%"))
+    expect(matched).toEqual(["100%_done"])
+
+    // "100_" should match only "100_other", not "100%_done" or "100xyz"
+    const matched2 = await collectAll(store.listDocIds("100_"))
+    expect(matched2).toEqual(["100_other"])
+
+    await store.close()
+  })
+})

package/src/index.ts

@@ -0,0 +1,335 @@
+// SQLite Store backend.
+//
+// Why a thin adapter rather than a direct better-sqlite3 dependency: the
+// adapter shape is deliberately synchronous because every supported
+// SQLite binding is sync (better-sqlite3, bun:sqlite, Cloudflare DO's
+// ctx.storage.sql). Forcing async here would dilute that ergonomics for
+// no benefit, since postgres-store and prisma-store get their own
+// async-native packages.
+
+import {
+  type DocId,
+  SeqNoTracker,
+  type Store,
+  type StoreMeta,
+  type StoreRecord,
+} from "@kyneta/exchange"
+import {
+  fromRow,
+  planAppend,
+  planReplace,
+  type RowShape,
+  resolveTables,
+  type TableNames,
+} from "@kyneta/sql-store-core"
+
+// ---------------------------------------------------------------------------
+// SqliteAdapter — minimal synchronous database interface
+// ---------------------------------------------------------------------------
+
+/**
+ * `iterate` returns `Iterable<T>` rather than `T[]` so `loadAll` can
+ * stream million-record stores without materializing them all in
+ * memory. Cloudflare DO's `ctx.storage.sql.exec` returns a cursor for
+ * the same reason; this shape is chosen to pass through.
+ */
+export interface SqliteAdapter {
+  exec(sql: string, ...params: unknown[]): void
+  iterate<T = Record<string, unknown>>(
+    sql: string,
+    ...params: unknown[]
+  ): Iterable<T>
+  transaction<R>(fn: () => R): R
+  close(): void
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a `better-sqlite3` Database as a `SqliteAdapter`.
+ *
+ * @example
+ * ```typescript
+ * import Database from "better-sqlite3"
+ * import { SqliteStore, fromBetterSqlite3 } from "@kyneta/sqlite-store"
+ *
+ * const db = new Database("exchange.db")
+ * const store = new SqliteStore(fromBetterSqlite3(db))
+ * ```
+ */
+export function fromBetterSqlite3(db: BetterSqlite3Database): SqliteAdapter {
+  return {
+    exec(sql: string, ...params: unknown[]): void {
+      db.prepare(sql).run(...params)
+    },
+    iterate<T = Record<string, unknown>>(
+      sql: string,
+      ...params: unknown[]
+    ): Iterable<T> {
+      return db.prepare(sql).iterate(...params) as IterableIterator<T>
+    },
+    transaction<R>(fn: () => R): R {
+      return db.transaction(fn)()
+    },
+    close(): void {
+      db.close()
+    },
+  }
+}
+
+/**
+ * Wrap a `bun:sqlite` Database as a `SqliteAdapter`.
+ *
+ * @example
+ * ```typescript
+ * import { Database } from "bun:sqlite"
+ * import { SqliteStore, fromBunSqlite } from "@kyneta/sqlite-store"
+ *
+ * const db = new Database("exchange.db")
+ * const store = new SqliteStore(fromBunSqlite(db))
+ * ```
+ */
+export function fromBunSqlite(db: BunSqliteDatabase): SqliteAdapter {
+  return {
+    exec(sql: string, ...params: unknown[]): void {
+      db.run(sql, ...params)
+    },
+    iterate<T = Record<string, unknown>>(
+      sql: string,
+      ...params: unknown[]
+    ): Iterable<T> {
+      return db.query(sql).iterate(...params) as IterableIterator<T>
+    },
+    transaction<R>(fn: () => R): R {
+      return db.transaction(fn)()
+    },
+    close(): void {
+      db.close()
+    },
+  }
+}
+
+// Minimal structural types for the two primary SQLite bindings.
+// These avoid a hard dependency on `better-sqlite3` or `bun:sqlite` types
+// at runtime — the caller provides the concrete database instance.
+
+/** Structural type for a `better-sqlite3` Database instance. */
+interface BetterSqlite3Database {
+  prepare(sql: string): {
+    run(...params: unknown[]): unknown
+    iterate(...params: unknown[]): IterableIterator<unknown>
+  }
+  transaction<R>(fn: () => R): () => R
+  close(): void
+}
+
+/** Structural type for a `bun:sqlite` Database instance. */
+interface BunSqliteDatabase {
+  run(sql: string, ...params: unknown[]): void
+  query(sql: string): {
+    iterate(...params: unknown[]): IterableIterator<unknown>
+  }
+  transaction<R>(fn: () => R): () => R
+  close(): void
+}
+
+// ---------------------------------------------------------------------------
+// SqliteStore options
+// ---------------------------------------------------------------------------
+
+export interface SqliteStoreOptions {
+  /**
+   * Override the default table names (`kyneta_meta` and `kyneta_records`).
+   *
+   * Use when co-locating Exchange tables alongside application tables in
+   * the same SQLite database, or when running multiple isolated Exchange
+   * instances in one database. Either or both names may be overridden.
+   */
+  tables?: Partial<TableNames>
+}
+
+// ---------------------------------------------------------------------------
+// SqliteStore
+// ---------------------------------------------------------------------------
+
+export class SqliteStore implements Store {
+  readonly #adapter: SqliteAdapter
+  readonly #seqNos = new SeqNoTracker()
+  readonly #tables: TableNames
+
+  constructor(adapter: SqliteAdapter, options: SqliteStoreOptions = {}) {
+    this.#adapter = adapter
+    this.#tables = resolveTables(options)
+    this.#ensureSchema()
+  }
+
+  #ensureSchema(): void {
+    this.#adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.#tables.meta} (
+        doc_id  TEXT PRIMARY KEY,
+        data    TEXT NOT NULL
+      ) WITHOUT ROWID
+    `)
+    this.#adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.#tables.records} (
+        doc_id  TEXT    NOT NULL,
+        seq     INTEGER NOT NULL,
+        kind    TEXT    NOT NULL,
+        payload TEXT,
+        blob    BLOB,
+        PRIMARY KEY (doc_id, seq)
+      ) WITHOUT ROWID
+    `)
+  }
+
+  // -------------------------------------------------------------------------
+  // Store interface
+  // -------------------------------------------------------------------------
+
+  async append(docId: DocId, record: StoreRecord): Promise<void> {
+    const existingMeta = await this.currentMeta(docId)
+    const seq = await this.#seqNos.next(docId, async () => {
+      const [row] = this.#adapter.iterate<{ max_seq: number | null }>(
+        `SELECT MAX(seq) AS max_seq FROM ${this.#tables.records} WHERE doc_id = ?`,
+        docId,
+      )
+      return row?.max_seq ?? null
+    })
+
+    const plan = planAppend(docId, record, existingMeta, seq)
+
+    // Both writes must commit together or neither — a crash between
+    // them used to leave meta updated with no corresponding row.
+    this.#adapter.transaction(() => {
+      if (plan.upsertMeta !== null) {
+        this.#adapter.exec(
+          `INSERT OR REPLACE INTO ${this.#tables.meta} (doc_id, data) VALUES (?, ?)`,
+          docId,
+          plan.upsertMeta.data,
+        )
+      }
+      const { row } = plan.insertRecord
+      this.#adapter.exec(
+        `INSERT INTO ${this.#tables.records} (doc_id, seq, kind, payload, blob) VALUES (?, ?, ?, ?, ?)`,
+        docId,
+        plan.insertRecord.seq,
+        row.kind,
+        row.payload,
+        row.blob,
+      )
+    })
+  }
+
+  async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {
+    for (const row of this.#adapter.iterate<RowShape>(
+      `SELECT kind, payload, blob FROM ${this.#tables.records} WHERE doc_id = ? ORDER BY seq`,
+      docId,
+    )) {
+      yield fromRow(row)
+    }
+  }
+
+  async replace(docId: DocId, records: StoreRecord[]): Promise<void> {
+    const existingMeta = await this.currentMeta(docId)
+    const plan = planReplace(records, existingMeta)
+
+    this.#adapter.transaction(() => {
+      this.#adapter.exec(
+        `DELETE FROM ${this.#tables.records} WHERE doc_id = ?`,
+        docId,
+      )
+
+      for (const { seq, row } of plan.records) {
+        this.#adapter.exec(
+          `INSERT INTO ${this.#tables.records} (doc_id, seq, kind, payload, blob) VALUES (?, ?, ?, ?, ?)`,
+          docId,
+          seq,
+          row.kind,
+          row.payload,
+          row.blob,
+        )
+      }
+
+      this.#adapter.exec(
+        `INSERT OR REPLACE INTO ${this.#tables.meta} (doc_id, data) VALUES (?, ?)`,
+        docId,
+        plan.upsertMeta.data,
+      )
+    })
+
+    // Must run after the transaction commits. If `transaction()` throws,
+    // control jumps past this line; the cache stays unmutated. Moving
+    // this inside the callback or before the call would corrupt the
+    // cache on rollback — the next append would compute a seq that
+    // collides with restored rows on the (doc_id, seq) primary key.
+    this.#seqNos.reset(docId, records.length - 1)
+  }
+
+  async delete(docId: DocId): Promise<void> {
+    this.#adapter.transaction(() => {
+      this.#adapter.exec(
+        `DELETE FROM ${this.#tables.records} WHERE doc_id = ?`,
+        docId,
+      )
+      this.#adapter.exec(
+        `DELETE FROM ${this.#tables.meta} WHERE doc_id = ?`,
+        docId,
+      )
+    })
+    this.#seqNos.remove(docId)
+  }
+
+  async currentMeta(docId: DocId): Promise<StoreMeta | null> {
+    const [row] = this.#adapter.iterate<{ data: string }>(
+      `SELECT data FROM ${this.#tables.meta} WHERE doc_id = ?`,
+      docId,
+    )
+    if (row === undefined) return null
+    return JSON.parse(row.data) as StoreMeta
+  }
+
+  async *listDocIds(prefix?: string): AsyncIterable<DocId> {
+    const rows =
+      prefix !== undefined
+        ? this.#adapter.iterate<{ doc_id: string }>(
+            `SELECT doc_id FROM ${this.#tables.meta} WHERE doc_id LIKE ? ESCAPE '\\'`,
+            `${escapeLike(prefix)}%`,
+          )
+        : this.#adapter.iterate<{ doc_id: string }>(
+            `SELECT doc_id FROM ${this.#tables.meta}`,
+          )
+    for (const row of rows) {
+      yield row.doc_id
+    }
+  }
+
+  async close(): Promise<void> {
+    this.#adapter.close()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * SQLite's LIKE treats `%` and `_` as wildcards. Escape them (and the
+ * escape char itself) so doc IDs containing those characters are
+ * matched literally. The query declares `ESCAPE '\'`.
+ */
+function escapeLike(value: string): string {
+  return value.replace(/[%_\\]/g, ch => `\\${ch}`)
+}
+
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+
+export function createSqliteStore(
+  adapter: SqliteAdapter,
+  options?: SqliteStoreOptions,
+): Store {
+  return new SqliteStore(adapter, options)
+}