@kyneta/sqlite-store 1.7.0 → 2.0.0

package/README.md

@@ -120,38 +120,39 @@ Not needed for Cloudflare DO — the platform manages durability.
 
 ```ts
 const store = new SqliteStore(adapter, {
-  tables: { meta: "app_meta", records: "app_records" },
+  tables: { docMeta: "app_doc_meta", records: "app_records", storeMeta: "app_store_meta" },
 })
 ```
 
-Default: `{ meta: "kyneta_meta", records: "kyneta_records" }`. Either or both names may be overridden.
+Default: `{ docMeta: "kyneta_doc_meta", records: "kyneta_records", storeMeta: "kyneta_store_meta" }`. Any subset of 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.
+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 sets.
 
 ## 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.
+The current API uses `tables: { docMeta, records, storeMeta }` (replacing v1.x's `tablePrefix`), defaulting to `kyneta_doc_meta` / `kyneta_records` / `kyneta_store_meta`. 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
+// current
+new SqliteStore(adapter)  // tables: kyneta_doc_meta, kyneta_records, kyneta_store_meta
 new SqliteStore(adapter, {
-  tables: { meta: "app_meta", records: "app_records" },
+  tables: { docMeta: "app_doc_meta", records: "app_records", storeMeta: "app_store_meta" },
 })
 ```
 
-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`.
+To keep using existing table names, pass them explicitly via the `tables` option, or rename via `ALTER TABLE`.
 
 ## Schema
 
-The store creates two tables on first use:
+The store creates three 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.docMeta`** (default `kyneta_doc_meta`) — per-document 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`.
+- **`tables.storeMeta`** (default `kyneta_store_meta`) — store-global metadata. `key TEXT PRIMARY KEY`, `value TEXT NOT NULL`. Holds the on-disk format version (under `key = "format"`), gated on open. `WITHOUT ROWID`.
 
 ## Store interface
 

package/dist/index.d.ts

@@ -60,11 +60,12 @@ interface BunSqliteDatabase {
 }
 interface SqliteStoreOptions {
   /**
-   * Override the default table names (`kyneta_meta` and `kyneta_records`).
+   * Override the default table names (`kyneta_doc_meta`, `kyneta_records`,
+   * `kyneta_store_meta`).
    *
    * 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.
+   * instances in one database. Any subset of names may be overridden.
    */
   tables?: Partial<TableNames>;
 }

package/dist/index.d.ts.map

@@ -1 +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;;;;;AAnBpE;AAmBP;;;;;;;iBAgCgB,aAAA,CAAc,EAAA,EAAI,iBAAA,GAAoB,aAAa;AAhCQ;AAAA,UAyDjE,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;AA/BiE;AAAA,UAmCzD,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,OAAO,CAAC,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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;AAwCA;;;;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;;;;;AAnBpE;AAmBP;;;;;;;iBAgCgB,aAAA,CAAc,EAAA,EAAI,iBAAA,GAAoB,aAAa;AAhCQ;AAAA,UAyDjE,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;AA/BiE;AAAA,UAmCzD,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;;;;;;;;EA+BR,MAAA,GAAS,OAAO,CAAC,UAAA;AAAA;AAAA,cAON,WAAA,YAAuB,KAAA;EAAA;cAKtB,OAAA,EAAS,aAAA,EAAe,OAAA,GAAS,kBAAA;EAgFvC,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

@@ -1,5 +1,5 @@
-import { SeqNoTracker } from "@kyneta/exchange";
-import { fromRow, planAppend, planReplace, resolveTables } from "@kyneta/sql-store-core";
+import { STORE_META_FORMAT_KEY, SeqNoTracker, StoreFormatVersionError, decideStoreFormat, parseStoreFormat } from "@kyneta/exchange";
+import { STORE_FORMAT_VERSION, fromRow, planAppend, planReplace, resolveTables } from "@kyneta/sql-store-core";
 //#region src/index.ts
 /**
 * Wrap a `better-sqlite3` Database as a `SqliteAdapter`.
@@ -65,10 +65,11 @@ var SqliteStore = class {
 		this.#adapter = adapter;
 		this.#tables = resolveTables(options);
 		this.#ensureSchema();
+		this.#assertFormat();
 	}
 	#ensureSchema() {
 		this.#adapter.exec(`
-      CREATE TABLE IF NOT EXISTS ${this.#tables.meta} (
+      CREATE TABLE IF NOT EXISTS ${this.#tables.docMeta} (
         doc_id  TEXT PRIMARY KEY,
         data    TEXT NOT NULL
       ) WITHOUT ROWID
@@ -83,6 +84,35 @@ var SqliteStore = class {
         PRIMARY KEY (doc_id, seq)
       ) WITHOUT ROWID
     `);
+		this.#adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.#tables.storeMeta} (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      ) WITHOUT ROWID
+    `);
+	}
+	#assertFormat() {
+		const [row] = this.#adapter.iterate(`SELECT value FROM ${this.#tables.storeMeta} WHERE key = ?`, STORE_META_FORMAT_KEY);
+		const parsed = row === void 0 ? null : parseStoreFormat(row.value);
+		if (parsed === "malformed") throw new StoreFormatVersionError({
+			reason: "malformed-version",
+			backend: "sqlite",
+			stored: null,
+			current: STORE_FORMAT_VERSION
+		});
+		const [hasData] = this.#adapter.iterate(`SELECT 1 AS one FROM ${this.#tables.docMeta} LIMIT 1`);
+		const decision = decideStoreFormat({
+			current: STORE_FORMAT_VERSION,
+			stored: parsed,
+			storeHasData: hasData !== void 0
+		});
+		if (decision.action === "refuse") throw new StoreFormatVersionError({
+			reason: decision.reason,
+			backend: "sqlite",
+			stored: parsed,
+			current: STORE_FORMAT_VERSION
+		});
+		if (decision.action === "stamp") this.#adapter.exec(`INSERT INTO ${this.#tables.storeMeta} (key, value) VALUES (?, ?)`, STORE_META_FORMAT_KEY, JSON.stringify(decision.value));
 	}
 	async append(docId, record) {
 		const plan = planAppend(docId, record, await this.currentMeta(docId), await this.#seqNos.next(docId, async () => {
@@ -90,7 +120,7 @@ var SqliteStore = class {
 			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);
+			if (plan.upsertMeta !== null) this.#adapter.exec(`INSERT OR REPLACE INTO ${this.#tables.docMeta} (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);
 		});
@@ -103,24 +133,24 @@ var SqliteStore = class {
 		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.#adapter.exec(`INSERT OR REPLACE INTO ${this.#tables.docMeta} (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.#adapter.exec(`DELETE FROM ${this.#tables.docMeta} 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);
+		const [row] = this.#adapter.iterate(`SELECT data FROM ${this.#tables.docMeta} 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}`);
+		const rows = prefix !== void 0 ? this.#adapter.iterate(`SELECT doc_id FROM ${this.#tables.docMeta} WHERE doc_id LIKE ? ESCAPE '\\'`, `${escapeLike(prefix)}%`) : this.#adapter.iterate(`SELECT doc_id FROM ${this.#tables.docMeta}`);
 		for (const row of rows) yield row.doc_id;
 	}
 	async close() {

package/dist/index.js.map

@@ -1 +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;CAC1E,OAAO;EACL,KAAK,KAAa,GAAG,QAAyB;GAC5C,GAAG,QAAQ,GAAG,EAAE,IAAI,GAAG,MAAM;EAC/B;EACA,QACE,KACA,GAAG,QACU;GACb,OAAO,GAAG,QAAQ,GAAG,EAAE,QAAQ,GAAG,MAAM;EAC1C;EACA,YAAe,IAAgB;GAC7B,OAAO,GAAG,YAAY,EAAE,EAAE;EAC5B;EACA,QAAc;GACZ,GAAG,MAAM;EACX;CACF;AACF;;;;;;;;;;;;;AAcA,SAAgB,cAAc,IAAsC;CAClE,OAAO;EACL,KAAK,KAAa,GAAG,QAAyB;GAC5C,GAAG,IAAI,KAAK,GAAG,MAAM;EACvB;EACA,QACE,KACA,GAAG,QACU;GACb,OAAO,GAAG,MAAM,GAAG,EAAE,QAAQ,GAAG,MAAM;EACxC;EACA,YAAe,IAAgB;GAC7B,OAAO,GAAG,YAAY,EAAE,EAAE;EAC5B;EACA,QAAc;GACZ,GAAG,MAAM;EACX;CACF;AACF;AA6CA,IAAa,cAAb,MAA0C;CACxC;CACA,UAAmB,IAAI,aAAa;CACpC;CAEA,YAAY,SAAwB,UAA8B,CAAC,GAAG;EACpE,KAAKA,WAAW;EAChB,KAAKE,UAAU,cAAc,OAAO;EACpC,KAAKC,cAAc;CACrB;CAEA,gBAAsB;EACpB,KAAKH,SAAS,KAAK;mCACY,KAAKE,QAAQ,KAAK;;;;KAIhD;EACD,KAAKF,SAAS,KAAK;mCACY,KAAKE,QAAQ,QAAQ;;;;;;;;KAQnD;CACH;CAMA,MAAM,OAAO,OAAc,QAAoC;EAU7D,MAAM,OAAO,WAAW,OAAO,QAAQ,MATZ,KAAK,YAAY,KAAK,GASI,MARnC,KAAKD,QAAQ,KAAK,OAAO,YAAY;GACrD,MAAM,CAAC,OAAO,KAAKD,SAAS,QAC1B,mCAAmC,KAAKE,QAAQ,QAAQ,oBACxD,KACF;GACA,OAAO,KAAK,WAAW;EACzB,CAAC,CAEuD;EAIxD,KAAKF,SAAS,kBAAkB;GAC9B,IAAI,KAAK,eAAe,MACtB,KAAKA,SAAS,KACZ,0BAA0B,KAAKE,QAAQ,KAAK,gCAC5C,OACA,KAAK,WAAW,IAClB;GAEF,MAAM,EAAE,QAAQ,KAAK;GACrB,KAAKF,SAAS,KACZ,eAAe,KAAKE,QAAQ,QAAQ,6DACpC,OACA,KAAK,aAAa,KAClB,IAAI,MACJ,IAAI,SACJ,IAAI,IACN;EACF,CAAC;CACH;CAEA,OAAO,QAAQ,OAA0C;EACvD,KAAK,MAAM,OAAO,KAAKF,SAAS,QAC9B,mCAAmC,KAAKE,QAAQ,QAAQ,iCACxD,KACF,GACE,MAAM,QAAQ,GAAG;CAErB;CAEA,MAAM,QAAQ,OAAc,SAAuC;EAEjE,MAAM,OAAO,YAAY,SAAS,MADP,KAAK,YAAY,KAAK,CACH;EAE9C,KAAKF,SAAS,kBAAkB;GAC9B,KAAKA,SAAS,KACZ,eAAe,KAAKE,QAAQ,QAAQ,oBACpC,KACF;GAEA,KAAK,MAAM,EAAE,KAAK,SAAS,KAAK,SAC9B,KAAKF,SAAS,KACZ,eAAe,KAAKE,QAAQ,QAAQ,6DACpC,OACA,KACA,IAAI,MACJ,IAAI,SACJ,IAAI,IACN;GAGF,KAAKF,SAAS,KACZ,0BAA0B,KAAKE,QAAQ,KAAK,gCAC5C,OACA,KAAK,WAAW,IAClB;EACF,CAAC;EAOD,KAAKD,QAAQ,MAAM,OAAO,QAAQ,SAAS,CAAC;CAC9C;CAEA,MAAM,OAAO,OAA6B;EACxC,KAAKD,SAAS,kBAAkB;GAC9B,KAAKA,SAAS,KACZ,eAAe,KAAKE,QAAQ,QAAQ,oBACpC,KACF;GACA,KAAKF,SAAS,KACZ,eAAe,KAAKE,QAAQ,KAAK,oBACjC,KACF;EACF,CAAC;EACD,KAAKD,QAAQ,OAAO,KAAK;CAC3B;CAEA,MAAM,YAAY,OAAyC;EACzD,MAAM,CAAC,OAAO,KAAKD,SAAS,QAC1B,oBAAoB,KAAKE,QAAQ,KAAK,oBACtC,KACF;EACA,IAAI,QAAQ,KAAA,GAAW,OAAO;EAC9B,OAAO,KAAK,MAAM,IAAI,IAAI;CAC5B;CAEA,OAAO,WAAW,QAAuC;EACvD,MAAM,OACJ,WAAW,KAAA,IACP,KAAKF,SAAS,QACZ,sBAAsB,KAAKE,QAAQ,KAAK,mCACxC,GAAG,WAAW,MAAM,EAAE,EACxB,IACA,KAAKF,SAAS,QACZ,sBAAsB,KAAKE,QAAQ,MACrC;EACN,KAAK,MAAM,OAAO,MAChB,MAAM,IAAI;CAEd;CAEA,MAAM,QAAuB;EAC3B,KAAKF,SAAS,MAAM;CACtB;AACF;;;;;;AAWA,SAAS,WAAW,OAAuB;CACzC,OAAO,MAAM,QAAQ,YAAW,OAAM,KAAK,IAAI;AACjD;AAMA,SAAgB,kBACd,SACA,SACO;CACP,OAAO,IAAI,YAAY,SAAS,OAAO;AACzC"}
+{"version":3,"file":"index.js","names":["#adapter","#seqNos","#tables","#ensureSchema","#assertFormat"],"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  decideStoreFormat,\n  parseStoreFormat,\n  SeqNoTracker,\n  STORE_META_FORMAT_KEY,\n  type Store,\n  StoreFormatVersionError,\n  type StoreMeta,\n  type StoreRecord,\n} from \"@kyneta/exchange\"\nimport {\n  fromRow,\n  planAppend,\n  planReplace,\n  type RowShape,\n  resolveTables,\n  STORE_FORMAT_VERSION,\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_doc_meta`, `kyneta_records`,\n   * `kyneta_store_meta`).\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. Any subset of 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    this.#assertFormat()\n  }\n\n  #ensureSchema(): void {\n    this.#adapter.exec(`\n      CREATE TABLE IF NOT EXISTS ${this.#tables.docMeta} (\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    this.#adapter.exec(`\n      CREATE TABLE IF NOT EXISTS ${this.#tables.storeMeta} (\n        key   TEXT PRIMARY KEY,\n        value TEXT NOT NULL\n      ) WITHOUT ROWID\n    `)\n  }\n\n  // Bootstrap reader: consult the store-format marker before trusting any\n  // bytes. Stamps a brand-new store, accepts a compatible one, or throws.\n  #assertFormat(): void {\n    const [row] = this.#adapter.iterate<{ value: string }>(\n      `SELECT value FROM ${this.#tables.storeMeta} WHERE key = ?`,\n      STORE_META_FORMAT_KEY,\n    )\n    const parsed = row === undefined ? null : parseStoreFormat(row.value)\n    if (parsed === \"malformed\") {\n      throw new StoreFormatVersionError({\n        reason: \"malformed-version\",\n        backend: \"sqlite\",\n        stored: null,\n        current: STORE_FORMAT_VERSION,\n      })\n    }\n\n    const [hasData] = this.#adapter.iterate<{ one: number }>(\n      `SELECT 1 AS one FROM ${this.#tables.docMeta} LIMIT 1`,\n    )\n\n    const decision = decideStoreFormat({\n      current: STORE_FORMAT_VERSION,\n      stored: parsed,\n      storeHasData: hasData !== undefined,\n    })\n\n    if (decision.action === \"refuse\") {\n      throw new StoreFormatVersionError({\n        reason: decision.reason,\n        backend: \"sqlite\",\n        stored: parsed,\n        current: STORE_FORMAT_VERSION,\n      })\n    }\n    if (decision.action === \"stamp\") {\n      this.#adapter.exec(\n        `INSERT INTO ${this.#tables.storeMeta} (key, value) VALUES (?, ?)`,\n        STORE_META_FORMAT_KEY,\n        JSON.stringify(decision.value),\n      )\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.docMeta} (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.docMeta} (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.docMeta} 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.docMeta} 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.docMeta} WHERE doc_id LIKE ? ESCAPE '\\\\'`,\n            `${escapeLike(prefix)}%`,\n          )\n        : this.#adapter.iterate<{ doc_id: string }>(\n            `SELECT doc_id FROM ${this.#tables.docMeta}`,\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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyneta/sqlite-store",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "description": "SQLite storage backend for @kyneta/exchange — universal persistent storage",
   "author": "Duane Johnson",
   "license": "MIT",
@@ -28,9 +28,9 @@
     }
   },
   "peerDependencies": {
-    "@kyneta/exchange": "^1.7.0",
-    "@kyneta/schema": "^1.7.0",
-    "@kyneta/sql-store-core": "^1.7.0"
+    "@kyneta/exchange": "^2.0.0",
+    "@kyneta/schema": "^2.0.0",
+    "@kyneta/sql-store-core": "^2.0.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",
@@ -39,9 +39,9 @@
     "tsdown": "^0.22.0",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17",
-    "@kyneta/sql-store-core": "^1.7.0",
-    "@kyneta/schema": "^1.7.0",
-    "@kyneta/exchange": "^1.7.0"
+    "@kyneta/exchange": "^2.0.0",
+    "@kyneta/schema": "^2.0.0",
+    "@kyneta/sql-store-core": "^2.0.0"
   },
   "scripts": {
     "build": "tsdown",

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

@@ -3,51 +3,18 @@
 import * as fs from "node:fs"
 import * as os from "node:os"
 import * as path from "node:path"
+import { StoreFormatVersionError } from "@kyneta/exchange"
 import {
   collectAll,
   describeStore,
+  makeArmedFault,
   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
-    },
-  }
-}
+import { fromBetterSqlite3, SqliteStore } from "../index.js"
 
 // ---------------------------------------------------------------------------
 // Temp file management
@@ -95,8 +62,8 @@ describeStore(
       const file = makeTmpFile()
       const db = new Database(file)
       const base = fromBetterSqlite3(db)
-      const { adapter, arm } = makeFaultyAdapter(base)
-      const store = new SqliteStore(adapter)
+      const { proxy, arm } = makeArmedFault(base, { exec: 1 })
+      const store = new SqliteStore(proxy)
       return {
         store,
         injectFault: arm,
@@ -117,10 +84,18 @@ describeStore(
       const adapter = fromBetterSqlite3(db)
       return {
         storeA: new SqliteStore(adapter, {
-          tables: { meta: "a_meta", records: "a_records" },
+          tables: {
+            docMeta: "a_meta",
+            records: "a_records",
+            storeMeta: "a_store_meta",
+          },
         }),
         storeB: new SqliteStore(adapter, {
-          tables: { meta: "b_meta", records: "b_records" },
+          tables: {
+            docMeta: "b_meta",
+            records: "b_records",
+            storeMeta: "b_store_meta",
+          },
         }),
         // Both stores share `adapter`; closing it once tears down both.
         cleanup: async () => {
@@ -237,10 +212,18 @@ describe("SqliteStore — tables isolation", () => {
     const adapter = fromBetterSqlite3(db)
 
     const store1 = new SqliteStore(adapter, {
-      tables: { meta: "app1_meta", records: "app1_records" },
+      tables: {
+        docMeta: "app1_meta",
+        records: "app1_records",
+        storeMeta: "app1_store_meta",
+      },
     })
     const store2 = new SqliteStore(adapter, {
-      tables: { meta: "app2_meta", records: "app2_records" },
+      tables: {
+        docMeta: "app2_meta",
+        records: "app2_records",
+        storeMeta: "app2_store_meta",
+      },
     })
 
     await store1.append("doc-1", makeMetaRecord())
@@ -287,3 +270,53 @@ describe("SqliteStore — listDocIds with LIKE-special characters", () => {
     await store.close()
   })
 })
+
+// Capture the error thrown by a (synchronous) store open, for asserting its
+// typed `reason` discriminant — the class alone can't distinguish refusals.
+function captureError(open: () => unknown): unknown {
+  try {
+    open()
+    return undefined
+  } catch (e) {
+    return e
+  }
+}
+
+describe("SqliteStore — store-format gate", () => {
+  it("refuses a store whose stamped major is incompatible", () => {
+    const db = new Database(":memory:")
+    // First open stamps {major:1,minor:0}. Keep the connection open — an
+    // in-memory db's data lives only while the connection is open.
+    new SqliteStore(fromBetterSqlite3(db))
+    // Tamper the marker to a future major.
+    db.prepare(
+      "UPDATE kyneta_store_meta SET value = ? WHERE key = 'format'",
+    ).run(JSON.stringify({ major: 99, minor: 0 }))
+
+    const err = captureError(() => new SqliteStore(fromBetterSqlite3(db)))
+    expect(err).toBeInstanceOf(StoreFormatVersionError)
+    expect((err as StoreFormatVersionError).reason).toBe("incompatible-major")
+    db.close()
+  })
+
+  it("refuses an unversioned store that already holds documents", () => {
+    const db = new Database(":memory:")
+    // Hand-create the doc-meta + records tables (no store_meta marker) and
+    // insert a document row — simulating a foreign / pre-marker store.
+    db.exec(`
+      CREATE TABLE kyneta_doc_meta (doc_id TEXT PRIMARY KEY, data TEXT NOT NULL) WITHOUT ROWID;
+      CREATE TABLE kyneta_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;
+      INSERT INTO kyneta_doc_meta (doc_id, data) VALUES ('doc-1', '{}');
+    `)
+
+    const err = captureError(() => new SqliteStore(fromBetterSqlite3(db)))
+    expect(err).toBeInstanceOf(StoreFormatVersionError)
+    expect((err as StoreFormatVersionError).reason).toBe(
+      "unversioned-existing-data",
+    )
+    db.close()
+  })
+})

package/src/index.ts

@@ -9,8 +9,12 @@
 
 import {
   type DocId,
+  decideStoreFormat,
+  parseStoreFormat,
   SeqNoTracker,
+  STORE_META_FORMAT_KEY,
   type Store,
+  StoreFormatVersionError,
   type StoreMeta,
   type StoreRecord,
 } from "@kyneta/exchange"
@@ -20,6 +24,7 @@ import {
   planReplace,
   type RowShape,
   resolveTables,
+  STORE_FORMAT_VERSION,
   type TableNames,
 } from "@kyneta/sql-store-core"
 
@@ -141,11 +146,12 @@ interface BunSqliteDatabase {
 
 export interface SqliteStoreOptions {
   /**
-   * Override the default table names (`kyneta_meta` and `kyneta_records`).
+   * Override the default table names (`kyneta_doc_meta`, `kyneta_records`,
+   * `kyneta_store_meta`).
    *
    * 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.
+   * instances in one database. Any subset of names may be overridden.
    */
   tables?: Partial<TableNames>
 }
@@ -163,11 +169,12 @@ export class SqliteStore implements Store {
     this.#adapter = adapter
     this.#tables = resolveTables(options)
     this.#ensureSchema()
+    this.#assertFormat()
   }
 
   #ensureSchema(): void {
     this.#adapter.exec(`
-      CREATE TABLE IF NOT EXISTS ${this.#tables.meta} (
+      CREATE TABLE IF NOT EXISTS ${this.#tables.docMeta} (
         doc_id  TEXT PRIMARY KEY,
         data    TEXT NOT NULL
       ) WITHOUT ROWID
@@ -182,6 +189,56 @@ export class SqliteStore implements Store {
         PRIMARY KEY (doc_id, seq)
       ) WITHOUT ROWID
     `)
+    this.#adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.#tables.storeMeta} (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      ) WITHOUT ROWID
+    `)
+  }
+
+  // Bootstrap reader: consult the store-format marker before trusting any
+  // bytes. Stamps a brand-new store, accepts a compatible one, or throws.
+  #assertFormat(): void {
+    const [row] = this.#adapter.iterate<{ value: string }>(
+      `SELECT value FROM ${this.#tables.storeMeta} WHERE key = ?`,
+      STORE_META_FORMAT_KEY,
+    )
+    const parsed = row === undefined ? null : parseStoreFormat(row.value)
+    if (parsed === "malformed") {
+      throw new StoreFormatVersionError({
+        reason: "malformed-version",
+        backend: "sqlite",
+        stored: null,
+        current: STORE_FORMAT_VERSION,
+      })
+    }
+
+    const [hasData] = this.#adapter.iterate<{ one: number }>(
+      `SELECT 1 AS one FROM ${this.#tables.docMeta} LIMIT 1`,
+    )
+
+    const decision = decideStoreFormat({
+      current: STORE_FORMAT_VERSION,
+      stored: parsed,
+      storeHasData: hasData !== undefined,
+    })
+
+    if (decision.action === "refuse") {
+      throw new StoreFormatVersionError({
+        reason: decision.reason,
+        backend: "sqlite",
+        stored: parsed,
+        current: STORE_FORMAT_VERSION,
+      })
+    }
+    if (decision.action === "stamp") {
+      this.#adapter.exec(
+        `INSERT INTO ${this.#tables.storeMeta} (key, value) VALUES (?, ?)`,
+        STORE_META_FORMAT_KEY,
+        JSON.stringify(decision.value),
+      )
+    }
   }
 
   // -------------------------------------------------------------------------
@@ -205,7 +262,7 @@ export class SqliteStore implements Store {
     this.#adapter.transaction(() => {
       if (plan.upsertMeta !== null) {
         this.#adapter.exec(
-          `INSERT OR REPLACE INTO ${this.#tables.meta} (doc_id, data) VALUES (?, ?)`,
+          `INSERT OR REPLACE INTO ${this.#tables.docMeta} (doc_id, data) VALUES (?, ?)`,
           docId,
           plan.upsertMeta.data,
         )
@@ -253,7 +310,7 @@ export class SqliteStore implements Store {
       }
 
       this.#adapter.exec(
-        `INSERT OR REPLACE INTO ${this.#tables.meta} (doc_id, data) VALUES (?, ?)`,
+        `INSERT OR REPLACE INTO ${this.#tables.docMeta} (doc_id, data) VALUES (?, ?)`,
         docId,
         plan.upsertMeta.data,
       )
@@ -274,7 +331,7 @@ export class SqliteStore implements Store {
         docId,
       )
       this.#adapter.exec(
-        `DELETE FROM ${this.#tables.meta} WHERE doc_id = ?`,
+        `DELETE FROM ${this.#tables.docMeta} WHERE doc_id = ?`,
         docId,
       )
     })
@@ -283,7 +340,7 @@ export class SqliteStore implements Store {
 
   async currentMeta(docId: DocId): Promise<StoreMeta | null> {
     const [row] = this.#adapter.iterate<{ data: string }>(
-      `SELECT data FROM ${this.#tables.meta} WHERE doc_id = ?`,
+      `SELECT data FROM ${this.#tables.docMeta} WHERE doc_id = ?`,
       docId,
     )
     if (row === undefined) return null
@@ -294,11 +351,11 @@ export class SqliteStore implements Store {
     const rows =
       prefix !== undefined
         ? this.#adapter.iterate<{ doc_id: string }>(
-            `SELECT doc_id FROM ${this.#tables.meta} WHERE doc_id LIKE ? ESCAPE '\\'`,
+            `SELECT doc_id FROM ${this.#tables.docMeta} WHERE doc_id LIKE ? ESCAPE '\\'`,
             `${escapeLike(prefix)}%`,
           )
         : this.#adapter.iterate<{ doc_id: string }>(
-            `SELECT doc_id FROM ${this.#tables.meta}`,
+            `SELECT doc_id FROM ${this.#tables.docMeta}`,
           )
     for (const row of rows) {
       yield row.doc_id