@kyneta/prisma-store 1.8.0 → 2.0.0

package/README.md

@@ -15,10 +15,10 @@ Peer dependencies: `@kyneta/exchange`, `@kyneta/schema`, `@kyneta/sql-store-core
 Copy [`schema.prisma.example`](./schema.prisma.example) into your existing `schema.prisma` and run `prisma generate` and `prisma migrate dev`:
 
 ```prisma
-model KynetaMeta {
+model KynetaDocMeta {
   docId String @id @map("doc_id")
   data  Json
-  @@map("kyneta_meta")
+  @@map("kyneta_doc_meta")
 }
 
 model KynetaRecord {
@@ -30,19 +30,25 @@ model KynetaRecord {
   @@id([docId, seq])
   @@map("kyneta_records")
 }
+
+model KynetaStoreMeta {
+  key   String @id
+  value Json
+  @@map("kyneta_store_meta")
+}
 ```
 
-Both models work on Postgres (`Json` → JSONB, `Bytes` → BYTEA), SQLite (`Json` → TEXT, `Bytes` → BLOB), and MySQL (`Json` → JSON, `Bytes` → LONGBLOB).
+All models work on Postgres (`Json` → JSONB, `Bytes` → BYTEA), SQLite (`Json` → TEXT, `Bytes` → BLOB), and MySQL (`Json` → JSON, `Bytes` → LONGBLOB). `KynetaStoreMeta` holds store-global metadata (the on-disk format version), distinct from the per-document `KynetaDocMeta`.
 
 ## Usage
 
 ```ts
 import { PrismaClient } from "@prisma/client"
 import { Exchange } from "@kyneta/exchange"
-import { PrismaStore } from "@kyneta/prisma-store"
+import { createPrismaStore } from "@kyneta/prisma-store"
 
 const prisma = new PrismaClient()
-const store = new PrismaStore({ client: prisma })
+const store = await createPrismaStore({ client: prisma })
 
 const exchange = new Exchange({
   stores: [store],
@@ -54,13 +60,16 @@ const exchange = new Exchange({
 // await prisma.$disconnect()
 ```
 
-The model accessors default to `prisma.kynetaMeta` and `prisma.kynetaRecord` (matching `model KynetaMeta` / `model KynetaRecord`). To use different model names:
+`createPrismaStore` runs the **store-format gate** on open: it stamps a `{ major, minor }` version into `KynetaStoreMeta` and, on a later open, throws `StoreFormatVersionError` for an incompatible major or an unversioned store that already holds documents. No automatic migration is performed. (The bare `new PrismaStore({ client })` constructor skips the gate.)
+
+The model accessors default to `prisma.kynetaDocMeta`, `prisma.kynetaRecord`, and `prisma.kynetaStoreMeta` (matching the model names above). To use different model names:
 
 ```ts
-const store = new PrismaStore({
+const store = await createPrismaStore({
   client: prisma,
-  metaModel: "appMeta",      // matches `model AppMeta`
-  recordModel: "appRecord",  // matches `model AppRecord`
+  metaModel: "appDocMeta",        // matches `model AppDocMeta`
+  recordModel: "appRecord",       // matches `model AppRecord`
+  storeMetaModel: "appStoreMeta", // matches `model AppStoreMeta`
 })
 ```
 

package/dist/index.d.ts

@@ -4,10 +4,12 @@ import { DocId, Store, StoreMeta, StoreRecord } from "@kyneta/exchange";
 interface PrismaStoreOptions {
   /** The PrismaClient. Pass `prisma` directly. */
   client: unknown;
-  /** Property name on the client. Default matches `model KynetaMeta`. */
+  /** Property name on the client. Default matches `model KynetaDocMeta`. */
   metaModel?: string;
   /** Property name on the client. Default matches `model KynetaRecord`. */
   recordModel?: string;
+  /** Property name on the client. Default matches `model KynetaStoreMeta`. */
+  storeMetaModel?: string;
 }
 declare class PrismaStore implements Store {
   #private;
@@ -19,11 +21,14 @@ declare class PrismaStore implements Store {
   currentMeta(docId: DocId): Promise<StoreMeta | null>;
   listDocIds(prefix?: string): AsyncIterable<DocId>;
   close(): Promise<void>;
+  /** Construct + run the store-format gate. Used by `createPrismaStore`. */
+  static open(options: PrismaStoreOptions): Promise<Store>;
 }
 /**
- * Async only for ergonomic parity with `createPostgresStore` — does
- * no schema validation. Prisma's typed accessors enforce model presence
- * at compile time; runtime failures surface on first call.
+ * Does no schema validation (Prisma's typed accessors enforce model
+ * presence at compile time; runtime failures surface on first call), but
+ * does run the store-format gate on open: it stamps a brand-new store,
+ * accepts a compatible one, or throws `StoreFormatVersionError`.
  */
 declare function createPrismaStore(options: PrismaStoreOptions): Promise<Store>;
 //#endregion

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;UAqFiB,kBAAA;;EAEf,MAAA;EAFiC;EAKjC,SAAA;EALiC;EAQjC,WAAA;AAAA;AAAA,cAOW,WAAA,YAAuB,KAAA;EAAA;cAMtB,OAAA,EAAS,kBAAA;EAgCf,MAAA,CAAO,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,WAAA,GAAc,OAAA;EAqC1C,OAAA,CAAQ,KAAA,EAAO,KAAA,GAAQ,aAAA,CAAc,WAAA;EAetC,OAAA,CAAQ,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,WAAA,KAAgB,OAAA;EAmC/C,MAAA,CAAO,KAAA,EAAO,KAAA,GAAQ,OAAA;EAStB,WAAA,CAAY,KAAA,EAAO,KAAA,GAAQ,OAAA,CAAQ,SAAA;EAMlC,UAAA,CAAW,MAAA,YAAkB,aAAA,CAAc,KAAA;EAiB5C,KAAA,CAAA,GAAS,OAAA;AAAA;;;;;;iBAsCK,iBAAA,CACpB,OAAA,EAAS,kBAAA,GACR,OAAA,CAAQ,KAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;UA2GiB,kBAAA;;EAEf,MAAA;EAFiC;EAKjC,SAAA;EALiC;EAQjC,WAAA;EAHA;EAMA,cAAA;AAAA;AAAA,cAOW,WAAA,YAAuB,KAAA;EAAA;cAOtB,OAAA,EAAS,kBAAA;EAuCf,MAAA,CAAO,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,WAAA,GAAc,OAAA;EAqC1C,OAAA,CAAQ,KAAA,EAAO,KAAA,GAAQ,aAAA,CAAc,WAAA;EAetC,OAAA,CAAQ,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,WAAA,KAAgB,OAAA;EAmC/C,MAAA,CAAO,KAAA,EAAO,KAAA,GAAQ,OAAA;EAStB,WAAA,CAAY,KAAA,EAAO,KAAA,GAAQ,OAAA,CAAQ,SAAA;EAMlC,UAAA,CAAW,MAAA,YAAkB,aAAA,CAAc,KAAA;EAiB5C,KAAA,CAAA,GAAS,OAAA;EAlF6B;EAAA,OAiI/B,IAAA,CAAK,OAAA,EAAS,kBAAA,GAAqB,OAAA,CAAQ,KAAA;AAAA;;;;;;;iBAyCpC,iBAAA,CACpB,OAAA,EAAS,kBAAA,GACR,OAAA,CAAQ,KAAA"}

package/dist/index.js

@@ -1,19 +1,24 @@
-import { SeqNoTracker } from "@kyneta/exchange";
-import { fromRow, planAppend, planReplace } from "@kyneta/sql-store-core";
+import { STORE_META_FORMAT_KEY, SeqNoTracker, StoreFormatVersionError, decideStoreFormat, parseStoreFormat } from "@kyneta/exchange";
+import { STORE_FORMAT_VERSION, fromRow, planAppend, planReplace } from "@kyneta/sql-store-core";
 //#region src/index.ts
-var PrismaStore = class {
+var PrismaStore = class PrismaStore {
 	#client;
 	#seqNos = new SeqNoTracker();
 	#metaModelName;
 	#recordModelName;
+	#storeMetaModelName;
 	constructor(options) {
 		this.#client = options.client;
-		this.#metaModelName = options.metaModel ?? "kynetaMeta";
+		this.#metaModelName = options.metaModel ?? "kynetaDocMeta";
 		this.#recordModelName = options.recordModel ?? "kynetaRecord";
+		this.#storeMetaModelName = options.storeMetaModel ?? "kynetaStoreMeta";
 	}
 	get #meta() {
 		return this.#client[this.#metaModelName];
 	}
+	get #storeMeta() {
+		return this.#client[this.#storeMetaModelName];
+	}
 	get #records() {
 		return this.#client[this.#recordModelName];
 	}
@@ -118,6 +123,41 @@ var PrismaStore = class {
 		for (const r of rows) yield r.docId;
 	}
 	async close() {}
+	async #assertFormat() {
+		const row = await this.#storeMeta.findUnique({ where: { key: STORE_META_FORMAT_KEY } });
+		const parsed = row === null ? null : parseStoreFormat(parseMetaData(row.value));
+		if (parsed === "malformed") throw new StoreFormatVersionError({
+			reason: "malformed-version",
+			backend: "prisma",
+			stored: null,
+			current: STORE_FORMAT_VERSION
+		});
+		const decision = decideStoreFormat({
+			current: STORE_FORMAT_VERSION,
+			stored: parsed,
+			storeHasData: await this.#meta.count() > 0
+		});
+		if (decision.action === "refuse") throw new StoreFormatVersionError({
+			reason: decision.reason,
+			backend: "prisma",
+			stored: parsed,
+			current: STORE_FORMAT_VERSION
+		});
+		if (decision.action === "stamp") await this.#storeMeta.upsert({
+			where: { key: STORE_META_FORMAT_KEY },
+			create: {
+				key: STORE_META_FORMAT_KEY,
+				value: decision.value
+			},
+			update: { value: decision.value }
+		});
+	}
+	/** Construct + run the store-format gate. Used by `createPrismaStore`. */
+	static async open(options) {
+		const store = new PrismaStore(options);
+		await store.#assertFormat();
+		return store;
+	}
 };
 /**
 * Prisma's `Json` field arrives parsed on Postgres/MySQL but as a raw
@@ -141,12 +181,13 @@ function prefixUpperBound(prefix) {
 	return null;
 }
 /**
-* Async only for ergonomic parity with `createPostgresStore` — does
-* no schema validation. Prisma's typed accessors enforce model presence
-* at compile time; runtime failures surface on first call.
+* Does no schema validation (Prisma's typed accessors enforce model
+* presence at compile time; runtime failures surface on first call), but
+* does run the store-format gate on open: it stamps a brand-new store,
+* accepts a compatible one, or throws `StoreFormatVersionError`.
 */
 async function createPrismaStore(options) {
-	return new PrismaStore(options);
+	return PrismaStore.open(options);
 }
 //#endregion
 export { PrismaStore, createPrismaStore };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["#client","#seqNos","#metaModelName","#recordModelName","#meta","#records","#txModels"],"sources":["../src/index.ts"],"sourcesContent":["// Prisma-based Store backend.\n//\n// Why `unknown`-typed client: capturing Prisma's generic typed\n// accessors without a hard dep on `@prisma/client` types is brittle,\n// and depending on them pins this package to one Prisma major. The\n// trade is less compile-time safety inside this package (one cast to\n// the structural interfaces below) for version portability across\n// Prisma releases. Caller's call site stays fully typed.\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} from \"@kyneta/sql-store-core\"\n\n// ---------------------------------------------------------------------------\n// Internal structural types — narrow shapes for the Prisma methods we use\n// ---------------------------------------------------------------------------\n\ninterface MetaRow {\n  docId: string\n  data: unknown\n}\n\ninterface RecordRow {\n  docId: string\n  seq: number\n  kind: string\n  payload: string | null\n  blob: Uint8Array | null\n}\n\ninterface MetaModel {\n  findUnique(args: { where: { docId: string } }): Promise<MetaRow | null>\n  findMany(args: {\n    where?: { docId?: { gte?: string; lt?: string } }\n    select: { docId: true }\n  }): Promise<Array<{ docId: string }>>\n  upsert(args: {\n    where: { docId: string }\n    create: { docId: string; data: unknown }\n    update: { data: unknown }\n  }): Promise<MetaRow>\n  delete(args: { where: { docId: string } }): Promise<unknown>\n  deleteMany(args: { where: { docId: string } }): Promise<unknown>\n}\n\ninterface RecordModel {\n  findMany(args: {\n    where: { docId: string }\n    orderBy: { seq: \"asc\" }\n  }): Promise<RecordRow[]>\n  create(args: { data: RecordRow }): Promise<unknown>\n  deleteMany(args: { where: { docId: string } }): Promise<unknown>\n  aggregate(args: {\n    where: { docId: string }\n    _max: { seq: true }\n  }): Promise<{ _max: { seq: number | null } }>\n}\n\ninterface PrismaClientLike {\n  $transaction<R>(fn: (tx: PrismaTransactionLike) => Promise<R>): Promise<R>\n}\n\n/**\n * Real Prisma's `tx` exposes the same model accessors as the client.\n * Indexed by string so caller-chosen model names (via `metaModel` /\n * `recordModel` options) resolve through the same lookup path.\n */\ninterface PrismaTransactionLike {\n  readonly [k: string]: unknown\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface PrismaStoreOptions {\n  /** The PrismaClient. Pass `prisma` directly. */\n  client: unknown\n\n  /** Property name on the client. Default matches `model KynetaMeta`. */\n  metaModel?: string\n\n  /** Property name on the client. Default matches `model KynetaRecord`. */\n  recordModel?: string\n}\n\n// ---------------------------------------------------------------------------\n// PrismaStore\n// ---------------------------------------------------------------------------\n\nexport class PrismaStore implements Store {\n  readonly #client: PrismaClientLike\n  readonly #seqNos = new SeqNoTracker()\n  readonly #metaModelName: string\n  readonly #recordModelName: string\n\n  constructor(options: PrismaStoreOptions) {\n    this.#client = options.client as PrismaClientLike\n    this.#metaModelName = options.metaModel ?? \"kynetaMeta\"\n    this.#recordModelName = options.recordModel ?? \"kynetaRecord\"\n  }\n\n  get #meta(): MetaModel {\n    return (this.#client as unknown as Record<string, unknown>)[\n      this.#metaModelName\n    ] as MetaModel\n  }\n\n  get #records(): RecordModel {\n    return (this.#client as unknown as Record<string, unknown>)[\n      this.#recordModelName\n    ] as RecordModel\n  }\n\n  #txModels(tx: PrismaTransactionLike): {\n    meta: MetaModel\n    records: RecordModel\n  } {\n    return {\n      meta: tx[this.#metaModelName] as MetaModel,\n      records: tx[this.#recordModelName] as RecordModel,\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 result = await this.#records.aggregate({\n        where: { docId },\n        _max: { seq: true },\n      })\n      return result._max.seq ?? null\n    })\n\n    const plan = planAppend(docId, record, existingMeta, seq)\n\n    await this.#client.$transaction(async tx => {\n      const { meta, records } = this.#txModels(tx)\n\n      if (plan.upsertMeta !== null) {\n        const dataValue = JSON.parse(plan.upsertMeta.data) as unknown\n        await meta.upsert({\n          where: { docId },\n          create: { docId, data: dataValue },\n          update: { data: dataValue },\n        })\n      }\n\n      const { row } = plan.insertRecord\n      await records.create({\n        data: {\n          docId,\n          seq: plan.insertRecord.seq,\n          kind: row.kind,\n          payload: row.payload,\n          blob: row.blob,\n        },\n      })\n    })\n  }\n\n  async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {\n    const rows = await this.#records.findMany({\n      where: { docId },\n      orderBy: { seq: \"asc\" },\n    })\n    for (const r of rows) {\n      const row: RowShape = {\n        kind: r.kind === \"meta\" ? \"meta\" : \"entry\",\n        payload: r.payload as string,\n        blob: r.blob ?? null,\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    await this.#client.$transaction(async tx => {\n      const { meta, records: recordsModel } = this.#txModels(tx)\n\n      await recordsModel.deleteMany({ where: { docId } })\n\n      for (const { seq, row } of plan.records) {\n        await recordsModel.create({\n          data: {\n            docId,\n            seq,\n            kind: row.kind,\n            payload: row.payload,\n            blob: row.blob,\n          },\n        })\n      }\n\n      const dataValue = JSON.parse(plan.upsertMeta.data) as unknown\n      await meta.upsert({\n        where: { docId },\n        create: { docId, data: dataValue },\n        update: { data: dataValue },\n      })\n    })\n\n    // Must run after commit. A `$transaction` rejection (failed COMMIT\n    // or callback throw) propagates past this line; cache stays\n    // unmutated. Inside the callback would corrupt it on rollback.\n    this.#seqNos.reset(docId, records.length - 1)\n  }\n\n  async delete(docId: DocId): Promise<void> {\n    await this.#client.$transaction(async tx => {\n      const { meta, records } = this.#txModels(tx)\n      await records.deleteMany({ where: { docId } })\n      await meta.deleteMany({ where: { docId } })\n    })\n    this.#seqNos.remove(docId)\n  }\n\n  async currentMeta(docId: DocId): Promise<StoreMeta | null> {\n    const row = await this.#meta.findUnique({ where: { docId } })\n    if (row === null) return null\n    return parseMetaData(row.data) as StoreMeta\n  }\n\n  async *listDocIds(prefix?: string): AsyncIterable<DocId> {\n    if (prefix === undefined) {\n      const rows = await this.#meta.findMany({ select: { docId: true } })\n      for (const r of rows) yield r.docId\n      return\n    }\n\n    const upper = prefixUpperBound(prefix)\n    const rows = await this.#meta.findMany({\n      where: {\n        docId: upper === null ? { gte: prefix } : { gte: prefix, lt: upper },\n      },\n      select: { docId: true },\n    })\n    for (const r of rows) yield r.docId\n  }\n\n  async close(): Promise<void> {\n    // Caller owns the lifecycle (`prisma.$disconnect()`).\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Prisma's `Json` field arrives parsed on Postgres/MySQL but as a raw\n * string on SQLite — the only place where the underlying database\n * type leaks through Prisma's abstraction.\n */\nfunction parseMetaData(value: unknown): unknown {\n  if (typeof value === \"string\") return JSON.parse(value)\n  return value\n}\n\nfunction prefixUpperBound(prefix: string): string | null {\n  if (prefix.length === 0) return null\n  const codes = Array.from(prefix)\n  for (let i = codes.length - 1; i >= 0; i--) {\n    const ch = codes[i] as string\n    const code = ch.codePointAt(0) as number\n    if (code < 0x10ffff) {\n      const next = String.fromCodePoint(code + 1)\n      return codes.slice(0, i).join(\"\") + next\n    }\n  }\n  return null\n}\n\n/**\n * Async only for ergonomic parity with `createPostgresStore` — does\n * no schema validation. Prisma's typed accessors enforce model presence\n * at compile time; runtime failures surface on first call.\n */\nexport async function createPrismaStore(\n  options: PrismaStoreOptions,\n): Promise<Store> {\n  return new PrismaStore(options)\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["#client","#seqNos","#metaModelName","#recordModelName","#storeMetaModelName","#meta","#storeMeta","#records","#txModels","#assertFormat"],"sources":["../src/index.ts"],"sourcesContent":["// Prisma-based Store backend.\n//\n// Why `unknown`-typed client: capturing Prisma's generic typed\n// accessors without a hard dep on `@prisma/client` types is brittle,\n// and depending on them pins this package to one Prisma major. The\n// trade is less compile-time safety inside this package (one cast to\n// the structural interfaces below) for version portability across\n// Prisma releases. Caller's call site stays fully typed.\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  STORE_FORMAT_VERSION,\n} from \"@kyneta/sql-store-core\"\n\n// ---------------------------------------------------------------------------\n// Internal structural types — narrow shapes for the Prisma methods we use\n// ---------------------------------------------------------------------------\n\ninterface MetaRow {\n  docId: string\n  data: unknown\n}\n\ninterface RecordRow {\n  docId: string\n  seq: number\n  kind: string\n  payload: string | null\n  blob: Uint8Array | null\n}\n\ninterface MetaModel {\n  findUnique(args: { where: { docId: string } }): Promise<MetaRow | null>\n  findMany(args: {\n    where?: { docId?: { gte?: string; lt?: string } }\n    select: { docId: true }\n  }): Promise<Array<{ docId: string }>>\n  upsert(args: {\n    where: { docId: string }\n    create: { docId: string; data: unknown }\n    update: { data: unknown }\n  }): Promise<MetaRow>\n  delete(args: { where: { docId: string } }): Promise<unknown>\n  deleteMany(args: { where: { docId: string } }): Promise<unknown>\n  // Empty-store probe for the store-format gate (does any document exist).\n  count(): Promise<number>\n}\n\ninterface StoreMetaRow {\n  key: string\n  value: unknown\n}\n\n/** Store-global metadata model — keyed by an opaque `key`, not a `docId`. */\ninterface StoreMetaModel {\n  findUnique(args: { where: { key: string } }): Promise<StoreMetaRow | null>\n  upsert(args: {\n    where: { key: string }\n    create: { key: string; value: unknown }\n    update: { value: unknown }\n  }): Promise<StoreMetaRow>\n}\n\ninterface RecordModel {\n  findMany(args: {\n    where: { docId: string }\n    orderBy: { seq: \"asc\" }\n  }): Promise<RecordRow[]>\n  create(args: { data: RecordRow }): Promise<unknown>\n  deleteMany(args: { where: { docId: string } }): Promise<unknown>\n  aggregate(args: {\n    where: { docId: string }\n    _max: { seq: true }\n  }): Promise<{ _max: { seq: number | null } }>\n}\n\ninterface PrismaClientLike {\n  $transaction<R>(fn: (tx: PrismaTransactionLike) => Promise<R>): Promise<R>\n}\n\n/**\n * Real Prisma's `tx` exposes the same model accessors as the client.\n * Indexed by string so caller-chosen model names (via `metaModel` /\n * `recordModel` options) resolve through the same lookup path.\n */\ninterface PrismaTransactionLike {\n  readonly [k: string]: unknown\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface PrismaStoreOptions {\n  /** The PrismaClient. Pass `prisma` directly. */\n  client: unknown\n\n  /** Property name on the client. Default matches `model KynetaDocMeta`. */\n  metaModel?: string\n\n  /** Property name on the client. Default matches `model KynetaRecord`. */\n  recordModel?: string\n\n  /** Property name on the client. Default matches `model KynetaStoreMeta`. */\n  storeMetaModel?: string\n}\n\n// ---------------------------------------------------------------------------\n// PrismaStore\n// ---------------------------------------------------------------------------\n\nexport class PrismaStore implements Store {\n  readonly #client: PrismaClientLike\n  readonly #seqNos = new SeqNoTracker()\n  readonly #metaModelName: string\n  readonly #recordModelName: string\n  readonly #storeMetaModelName: string\n\n  constructor(options: PrismaStoreOptions) {\n    this.#client = options.client as PrismaClientLike\n    this.#metaModelName = options.metaModel ?? \"kynetaDocMeta\"\n    this.#recordModelName = options.recordModel ?? \"kynetaRecord\"\n    this.#storeMetaModelName = options.storeMetaModel ?? \"kynetaStoreMeta\"\n  }\n\n  get #meta(): MetaModel {\n    return (this.#client as unknown as Record<string, unknown>)[\n      this.#metaModelName\n    ] as MetaModel\n  }\n\n  get #storeMeta(): StoreMetaModel {\n    return (this.#client as unknown as Record<string, unknown>)[\n      this.#storeMetaModelName\n    ] as StoreMetaModel\n  }\n\n  get #records(): RecordModel {\n    return (this.#client as unknown as Record<string, unknown>)[\n      this.#recordModelName\n    ] as RecordModel\n  }\n\n  #txModels(tx: PrismaTransactionLike): {\n    meta: MetaModel\n    records: RecordModel\n  } {\n    return {\n      meta: tx[this.#metaModelName] as MetaModel,\n      records: tx[this.#recordModelName] as RecordModel,\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 result = await this.#records.aggregate({\n        where: { docId },\n        _max: { seq: true },\n      })\n      return result._max.seq ?? null\n    })\n\n    const plan = planAppend(docId, record, existingMeta, seq)\n\n    await this.#client.$transaction(async tx => {\n      const { meta, records } = this.#txModels(tx)\n\n      if (plan.upsertMeta !== null) {\n        const dataValue = JSON.parse(plan.upsertMeta.data) as unknown\n        await meta.upsert({\n          where: { docId },\n          create: { docId, data: dataValue },\n          update: { data: dataValue },\n        })\n      }\n\n      const { row } = plan.insertRecord\n      await records.create({\n        data: {\n          docId,\n          seq: plan.insertRecord.seq,\n          kind: row.kind,\n          payload: row.payload,\n          blob: row.blob,\n        },\n      })\n    })\n  }\n\n  async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {\n    const rows = await this.#records.findMany({\n      where: { docId },\n      orderBy: { seq: \"asc\" },\n    })\n    for (const r of rows) {\n      const row: RowShape = {\n        kind: r.kind === \"meta\" ? \"meta\" : \"entry\",\n        payload: r.payload as string,\n        blob: r.blob ?? null,\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    await this.#client.$transaction(async tx => {\n      const { meta, records: recordsModel } = this.#txModels(tx)\n\n      await recordsModel.deleteMany({ where: { docId } })\n\n      for (const { seq, row } of plan.records) {\n        await recordsModel.create({\n          data: {\n            docId,\n            seq,\n            kind: row.kind,\n            payload: row.payload,\n            blob: row.blob,\n          },\n        })\n      }\n\n      const dataValue = JSON.parse(plan.upsertMeta.data) as unknown\n      await meta.upsert({\n        where: { docId },\n        create: { docId, data: dataValue },\n        update: { data: dataValue },\n      })\n    })\n\n    // Must run after commit. A `$transaction` rejection (failed COMMIT\n    // or callback throw) propagates past this line; cache stays\n    // unmutated. Inside the callback would corrupt it on rollback.\n    this.#seqNos.reset(docId, records.length - 1)\n  }\n\n  async delete(docId: DocId): Promise<void> {\n    await this.#client.$transaction(async tx => {\n      const { meta, records } = this.#txModels(tx)\n      await records.deleteMany({ where: { docId } })\n      await meta.deleteMany({ where: { docId } })\n    })\n    this.#seqNos.remove(docId)\n  }\n\n  async currentMeta(docId: DocId): Promise<StoreMeta | null> {\n    const row = await this.#meta.findUnique({ where: { docId } })\n    if (row === null) return null\n    return parseMetaData(row.data) as StoreMeta\n  }\n\n  async *listDocIds(prefix?: string): AsyncIterable<DocId> {\n    if (prefix === undefined) {\n      const rows = await this.#meta.findMany({ select: { docId: true } })\n      for (const r of rows) yield r.docId\n      return\n    }\n\n    const upper = prefixUpperBound(prefix)\n    const rows = await this.#meta.findMany({\n      where: {\n        docId: upper === null ? { gte: prefix } : { gte: prefix, lt: upper },\n      },\n      select: { docId: true },\n    })\n    for (const r of rows) yield r.docId\n  }\n\n  async close(): Promise<void> {\n    // Caller owns the lifecycle (`prisma.$disconnect()`).\n  }\n\n  // Bootstrap reader: stamp/accept/refuse the store-format marker on open.\n  // A `static open` reaches this private method so the gate stays internal.\n  async #assertFormat(): Promise<void> {\n    const row = await this.#storeMeta.findUnique({\n      where: { key: STORE_META_FORMAT_KEY },\n    })\n    const parsed =\n      row === null ? null : parseStoreFormat(parseMetaData(row.value))\n    if (parsed === \"malformed\") {\n      throw new StoreFormatVersionError({\n        reason: \"malformed-version\",\n        backend: \"prisma\",\n        stored: null,\n        current: STORE_FORMAT_VERSION,\n      })\n    }\n\n    const docCount = await this.#meta.count()\n\n    const decision = decideStoreFormat({\n      current: STORE_FORMAT_VERSION,\n      stored: parsed,\n      storeHasData: docCount > 0,\n    })\n\n    if (decision.action === \"refuse\") {\n      throw new StoreFormatVersionError({\n        reason: decision.reason,\n        backend: \"prisma\",\n        stored: parsed,\n        current: STORE_FORMAT_VERSION,\n      })\n    }\n    if (decision.action === \"stamp\") {\n      await this.#storeMeta.upsert({\n        where: { key: STORE_META_FORMAT_KEY },\n        create: { key: STORE_META_FORMAT_KEY, value: decision.value },\n        update: { value: decision.value },\n      })\n    }\n  }\n\n  /** Construct + run the store-format gate. Used by `createPrismaStore`. */\n  static async open(options: PrismaStoreOptions): Promise<Store> {\n    const store = new PrismaStore(options)\n    await store.#assertFormat()\n    return store\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Prisma's `Json` field arrives parsed on Postgres/MySQL but as a raw\n * string on SQLite — the only place where the underlying database\n * type leaks through Prisma's abstraction.\n */\nfunction parseMetaData(value: unknown): unknown {\n  if (typeof value === \"string\") return JSON.parse(value)\n  return value\n}\n\nfunction prefixUpperBound(prefix: string): string | null {\n  if (prefix.length === 0) return null\n  const codes = Array.from(prefix)\n  for (let i = codes.length - 1; i >= 0; i--) {\n    const ch = codes[i] as string\n    const code = ch.codePointAt(0) as number\n    if (code < 0x10ffff) {\n      const next = String.fromCodePoint(code + 1)\n      return codes.slice(0, i).join(\"\") + next\n    }\n  }\n  return null\n}\n\n/**\n * Does no schema validation (Prisma's typed accessors enforce model\n * presence at compile time; runtime failures surface on first call), but\n * does run the store-format gate on open: it stamps a brand-new store,\n * accepts a compatible one, or throws `StoreFormatVersionError`.\n */\nexport async function createPrismaStore(\n  options: PrismaStoreOptions,\n): Promise<Store> {\n  return PrismaStore.open(options)\n}\n"],"mappings":";;;AA6HA,IAAa,cAAb,MAAa,YAA6B;CACxC;CACA,UAAmB,IAAI,aAAa;CACpC;CACA;CACA;CAEA,YAAY,SAA6B;EACvC,KAAKA,UAAU,QAAQ;EACvB,KAAKE,iBAAiB,QAAQ,aAAa;EAC3C,KAAKC,mBAAmB,QAAQ,eAAe;EAC/C,KAAKC,sBAAsB,QAAQ,kBAAkB;CACvD;CAEA,IAAIC,QAAmB;EACrB,OAAQ,KAAKL,QACX,KAAKE;CAET;CAEA,IAAII,aAA6B;EAC/B,OAAQ,KAAKN,QACX,KAAKI;CAET;CAEA,IAAIG,WAAwB;EAC1B,OAAQ,KAAKP,QACX,KAAKG;CAET;CAEA,UAAU,IAGR;EACA,OAAO;GACL,MAAM,GAAG,KAAKD;GACd,SAAS,GAAG,KAAKC;EACnB;CACF;CAMA,MAAM,OAAO,OAAc,QAAoC;EAU7D,MAAM,OAAO,WAAW,OAAO,QAAQ,MATZ,KAAK,YAAY,KAAK,GASI,MARnC,KAAKF,QAAQ,KAAK,OAAO,YAAY;GAKrD,QAAO,MAJc,KAAKM,SAAS,UAAU;IAC3C,OAAO,EAAE,MAAM;IACf,MAAM,EAAE,KAAK,KAAK;GACpB,CAAC,GACa,KAAK,OAAO;EAC5B,CAAC,CAEuD;EAExD,MAAM,KAAKP,QAAQ,aAAa,OAAM,OAAM;GAC1C,MAAM,EAAE,MAAM,YAAY,KAAKQ,UAAU,EAAE;GAE3C,IAAI,KAAK,eAAe,MAAM;IAC5B,MAAM,YAAY,KAAK,MAAM,KAAK,WAAW,IAAI;IACjD,MAAM,KAAK,OAAO;KAChB,OAAO,EAAE,MAAM;KACf,QAAQ;MAAE;MAAO,MAAM;KAAU;KACjC,QAAQ,EAAE,MAAM,UAAU;IAC5B,CAAC;GACH;GAEA,MAAM,EAAE,QAAQ,KAAK;GACrB,MAAM,QAAQ,OAAO,EACnB,MAAM;IACJ;IACA,KAAK,KAAK,aAAa;IACvB,MAAM,IAAI;IACV,SAAS,IAAI;IACb,MAAM,IAAI;GACZ,EACF,CAAC;EACH,CAAC;CACH;CAEA,OAAO,QAAQ,OAA0C;EACvD,MAAM,OAAO,MAAM,KAAKD,SAAS,SAAS;GACxC,OAAO,EAAE,MAAM;GACf,SAAS,EAAE,KAAK,MAAM;EACxB,CAAC;EACD,KAAK,MAAM,KAAK,MAMd,MAAM,QAAQ;GAJZ,MAAM,EAAE,SAAS,SAAS,SAAS;GACnC,SAAS,EAAE;GACX,MAAM,EAAE,QAAQ;EAEF,CAAC;CAErB;CAEA,MAAM,QAAQ,OAAc,SAAuC;EAEjE,MAAM,OAAO,YAAY,SAAS,MADP,KAAK,YAAY,KAAK,CACH;EAE9C,MAAM,KAAKP,QAAQ,aAAa,OAAM,OAAM;GAC1C,MAAM,EAAE,MAAM,SAAS,iBAAiB,KAAKQ,UAAU,EAAE;GAEzD,MAAM,aAAa,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;GAElD,KAAK,MAAM,EAAE,KAAK,SAAS,KAAK,SAC9B,MAAM,aAAa,OAAO,EACxB,MAAM;IACJ;IACA;IACA,MAAM,IAAI;IACV,SAAS,IAAI;IACb,MAAM,IAAI;GACZ,EACF,CAAC;GAGH,MAAM,YAAY,KAAK,MAAM,KAAK,WAAW,IAAI;GACjD,MAAM,KAAK,OAAO;IAChB,OAAO,EAAE,MAAM;IACf,QAAQ;KAAE;KAAO,MAAM;IAAU;IACjC,QAAQ,EAAE,MAAM,UAAU;GAC5B,CAAC;EACH,CAAC;EAKD,KAAKP,QAAQ,MAAM,OAAO,QAAQ,SAAS,CAAC;CAC9C;CAEA,MAAM,OAAO,OAA6B;EACxC,MAAM,KAAKD,QAAQ,aAAa,OAAM,OAAM;GAC1C,MAAM,EAAE,MAAM,YAAY,KAAKQ,UAAU,EAAE;GAC3C,MAAM,QAAQ,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;GAC7C,MAAM,KAAK,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;EAC5C,CAAC;EACD,KAAKP,QAAQ,OAAO,KAAK;CAC3B;CAEA,MAAM,YAAY,OAAyC;EACzD,MAAM,MAAM,MAAM,KAAKI,MAAM,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;EAC5D,IAAI,QAAQ,MAAM,OAAO;EACzB,OAAO,cAAc,IAAI,IAAI;CAC/B;CAEA,OAAO,WAAW,QAAuC;EACvD,IAAI,WAAW,KAAA,GAAW;GACxB,MAAM,OAAO,MAAM,KAAKA,MAAM,SAAS,EAAE,QAAQ,EAAE,OAAO,KAAK,EAAE,CAAC;GAClE,KAAK,MAAM,KAAK,MAAM,MAAM,EAAE;GAC9B;EACF;EAEA,MAAM,QAAQ,iBAAiB,MAAM;EACrC,MAAM,OAAO,MAAM,KAAKA,MAAM,SAAS;GACrC,OAAO,EACL,OAAO,UAAU,OAAO,EAAE,KAAK,OAAO,IAAI;IAAE,KAAK;IAAQ,IAAI;GAAM,EACrE;GACA,QAAQ,EAAE,OAAO,KAAK;EACxB,CAAC;EACD,KAAK,MAAM,KAAK,MAAM,MAAM,EAAE;CAChC;CAEA,MAAM,QAAuB,CAE7B;CAIA,MAAMI,gBAA+B;EACnC,MAAM,MAAM,MAAM,KAAKH,WAAW,WAAW,EAC3C,OAAO,EAAE,KAAK,sBAAsB,EACtC,CAAC;EACD,MAAM,SACJ,QAAQ,OAAO,OAAO,iBAAiB,cAAc,IAAI,KAAK,CAAC;EACjE,IAAI,WAAW,aACb,MAAM,IAAI,wBAAwB;GAChC,QAAQ;GACR,SAAS;GACT,QAAQ;GACR,SAAS;EACX,CAAC;EAKH,MAAM,WAAW,kBAAkB;GACjC,SAAS;GACT,QAAQ;GACR,cAAc,MALO,KAAKD,MAAM,MAAM,IAKb;EAC3B,CAAC;EAED,IAAI,SAAS,WAAW,UACtB,MAAM,IAAI,wBAAwB;GAChC,QAAQ,SAAS;GACjB,SAAS;GACT,QAAQ;GACR,SAAS;EACX,CAAC;EAEH,IAAI,SAAS,WAAW,SACtB,MAAM,KAAKC,WAAW,OAAO;GAC3B,OAAO,EAAE,KAAK,sBAAsB;GACpC,QAAQ;IAAE,KAAK;IAAuB,OAAO,SAAS;GAAM;GAC5D,QAAQ,EAAE,OAAO,SAAS,MAAM;EAClC,CAAC;CAEL;;CAGA,aAAa,KAAK,SAA6C;EAC7D,MAAM,QAAQ,IAAI,YAAY,OAAO;EACrC,MAAM,MAAMG,cAAc;EAC1B,OAAO;CACT;AACF;;;;;;AAWA,SAAS,cAAc,OAAyB;CAC9C,IAAI,OAAO,UAAU,UAAU,OAAO,KAAK,MAAM,KAAK;CACtD,OAAO;AACT;AAEA,SAAS,iBAAiB,QAA+B;CACvD,IAAI,OAAO,WAAW,GAAG,OAAO;CAChC,MAAM,QAAQ,MAAM,KAAK,MAAM;CAC/B,KAAK,IAAI,IAAI,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK;EAE1C,MAAM,OADK,MAAM,GACD,YAAY,CAAC;EAC7B,IAAI,OAAO,SAAU;GACnB,MAAM,OAAO,OAAO,cAAc,OAAO,CAAC;GAC1C,OAAO,MAAM,MAAM,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI;EACtC;CACF;CACA,OAAO;AACT;;;;;;;AAQA,eAAsB,kBACpB,SACgB;CAChB,OAAO,YAAY,KAAK,OAAO;AACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyneta/prisma-store",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "Prisma-based storage backend for @kyneta/exchange",
   "author": "Duane Johnson",
   "license": "MIT",
@@ -31,18 +31,18 @@
   },
   "peerDependencies": {
     "@prisma/client": "^5.0.0 || ^6.0.0",
-    "@kyneta/exchange": "^1.8.0",
-    "@kyneta/schema": "^1.8.0",
-    "@kyneta/sql-store-core": "^1.8.0"
+    "@kyneta/schema": "^2.0.0",
+    "@kyneta/exchange": "^2.0.0",
+    "@kyneta/sql-store-core": "^2.0.0"
   },
   "devDependencies": {
     "@types/node": "^22",
     "tsdown": "^0.22.0",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17",
-    "@kyneta/sql-store-core": "^1.8.0",
-    "@kyneta/exchange": "^1.8.0",
-    "@kyneta/schema": "^1.8.0"
+    "@kyneta/exchange": "^2.0.0",
+    "@kyneta/sql-store-core": "^2.0.0",
+    "@kyneta/schema": "^2.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/schema.prisma.example

@@ -1,18 +1,20 @@
 // @kyneta/prisma-store — canonical Prisma schema fragment.
 //
 // Copy these models into your existing schema.prisma. The model
-// accessors (e.g. `prisma.kynetaMeta`, `prisma.kynetaRecord`) are
-// what you pass into the PrismaStore constructor.
+// accessors (e.g. `prisma.kynetaDocMeta`, `prisma.kynetaRecord`,
+// `prisma.kynetaStoreMeta`) are what you pass into the PrismaStore
+// constructor.
 //
-// Both models work on Postgres (Json → JSONB, Bytes → BYTEA),
+// All models work on Postgres (Json → JSONB, Bytes → BYTEA),
 // SQLite (Json → TEXT, Bytes → BLOB), and MySQL (Json → JSON,
 // Bytes → LONGBLOB). Round-trip through `loadAll` is portable across
 // these targets.
 
-model KynetaMeta {
+// Per-document metadata, keyed by doc_id.
+model KynetaDocMeta {
   docId String @id @map("doc_id")
   data  Json
-  @@map("kyneta_meta")
+  @@map("kyneta_doc_meta")
 }
 
 model KynetaRecord {
@@ -24,3 +26,11 @@ model KynetaRecord {
   @@id([docId, seq])
   @@map("kyneta_records")
 }
+
+// Store-global metadata, keyed by an opaque key (not a doc_id). Holds the
+// on-disk format version under key 'format'; stamped and gated on open.
+model KynetaStoreMeta {
+  key   String @id
+  value Json
+  @@map("kyneta_store_meta")
+}

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

@@ -7,8 +7,8 @@
 // integration tests in tests/integration. Here we only verify:
 //
 // 1. PrismaStore accepts a structurally-typed accessor object.
-// 2. The model names default to `kynetaMeta` / `kynetaRecord`,
-//    overridable via options.
+// 2. The model names default to `kynetaDocMeta` / `kynetaRecord` /
+//    `kynetaStoreMeta`, overridable via options.
 // 3. Append, currentMeta, loadAll, listDocIds, delete, replace each
 //    call the expected mock methods with the expected args.
 //
@@ -19,16 +19,17 @@
 import type { StoreMeta } from "@kyneta/exchange"
 import { SYNC_AUTHORITATIVE } from "@kyneta/schema"
 import { describe, expect, it } from "vitest"
-import { PrismaStore } from "../index.js"
+import { createPrismaStore, PrismaStore } from "../index.js"
 
 const baseMeta: StoreMeta = {
   replicaType: ["plain", 1, 0] as const,
-  syncProtocol: SYNC_AUTHORITATIVE,
+  syncMode: SYNC_AUTHORITATIVE,
   schemaHash: "00test",
 }
 
 interface MockState {
   metas: Map<string, unknown>
+  storeMetas: Map<string, unknown>
   records: Array<{
     docId: string
     seq: number
@@ -79,6 +80,25 @@ function makeMockClient(state: MockState): unknown {
       state.metas.delete(args.where.docId)
       return null
     },
+    async count() {
+      return state.metas.size
+    },
+  }
+
+  const storeMetaModel = {
+    async findUnique(args: { where: { key: string } }) {
+      const value = state.storeMetas.get(args.where.key)
+      if (value === undefined) return null
+      return { key: args.where.key, value }
+    },
+    async upsert(args: {
+      where: { key: string }
+      create: { key: string; value: unknown }
+      update: { value: unknown }
+    }) {
+      state.storeMetas.set(args.where.key, args.update.value)
+      return { key: args.where.key, value: args.update.value }
+    },
   }
 
   const recordModel = {
@@ -120,8 +140,9 @@ function makeMockClient(state: MockState): unknown {
   // those wrappings inside the transaction too, mirroring real Prisma's
   // behavior where `tx` exposes the same model accessors as the client.
   const client: Record<string, unknown> = {
-    kynetaMeta: metaModel,
+    kynetaDocMeta: metaModel,
     kynetaRecord: recordModel,
+    kynetaStoreMeta: storeMetaModel,
   }
   client.$transaction = async <R>(
     fn: (tx: unknown) => Promise<R>,
@@ -144,7 +165,7 @@ function makeMockClient(state: MockState): unknown {
 }
 
 function freshState(): MockState {
-  return { metas: new Map(), records: [], txCalls: 0 }
+  return { metas: new Map(), storeMetas: new Map(), records: [], txCalls: 0 }
 }
 
 describe("PrismaStore — structural mock", () => {
@@ -250,7 +271,7 @@ describe("PrismaStore — structural mock", () => {
     // visible both at the top level and inside transactions.
     const base = makeMockClient(state) as Record<string, unknown>
     const renamed: Record<string, unknown> = {
-      app_meta: base.kynetaMeta,
+      app_meta: base.kynetaDocMeta,
       app_record: base.kynetaRecord,
     }
     renamed.$transaction = async (fn: (tx: unknown) => Promise<unknown>) =>
@@ -304,3 +325,29 @@ describe("PrismaStore — structural mock", () => {
     expect(state.records).toHaveLength(1)
   })
 })
+
+describe("PrismaStore — store-format gate", () => {
+  it("createPrismaStore stamps a fresh store, then accepts it on reopen", async () => {
+    const state = freshState()
+    await createPrismaStore({ client: makeMockClient(state) })
+    expect(state.storeMetas.get("format")).toEqual({ major: 1, minor: 0 })
+
+    // Reopen against the same state: the marker round-trips, no throw.
+    await expect(
+      createPrismaStore({ client: makeMockClient(state) }),
+    ).resolves.toBeDefined()
+  })
+
+  it("refuses a store whose stamped major is incompatible", async () => {
+    const state = freshState()
+    state.storeMetas.set("format", { major: 99, minor: 0 })
+    state.metas.set("doc-1", {}) // store already holds a document
+
+    await expect(
+      createPrismaStore({ client: makeMockClient(state) }),
+    ).rejects.toMatchObject({
+      name: "StoreFormatVersionError",
+      reason: "incompatible-major",
+    })
+  })
+})

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"
@@ -19,6 +23,7 @@ import {
   planAppend,
   planReplace,
   type RowShape,
+  STORE_FORMAT_VERSION,
 } from "@kyneta/sql-store-core"
 
 // ---------------------------------------------------------------------------
@@ -51,6 +56,23 @@ interface MetaModel {
   }): Promise<MetaRow>
   delete(args: { where: { docId: string } }): Promise<unknown>
   deleteMany(args: { where: { docId: string } }): Promise<unknown>
+  // Empty-store probe for the store-format gate (does any document exist).
+  count(): Promise<number>
+}
+
+interface StoreMetaRow {
+  key: string
+  value: unknown
+}
+
+/** Store-global metadata model — keyed by an opaque `key`, not a `docId`. */
+interface StoreMetaModel {
+  findUnique(args: { where: { key: string } }): Promise<StoreMetaRow | null>
+  upsert(args: {
+    where: { key: string }
+    create: { key: string; value: unknown }
+    update: { value: unknown }
+  }): Promise<StoreMetaRow>
 }
 
 interface RecordModel {
@@ -87,11 +109,14 @@ export interface PrismaStoreOptions {
   /** The PrismaClient. Pass `prisma` directly. */
   client: unknown
 
-  /** Property name on the client. Default matches `model KynetaMeta`. */
+  /** Property name on the client. Default matches `model KynetaDocMeta`. */
   metaModel?: string
 
   /** Property name on the client. Default matches `model KynetaRecord`. */
   recordModel?: string
+
+  /** Property name on the client. Default matches `model KynetaStoreMeta`. */
+  storeMetaModel?: string
 }
 
 // ---------------------------------------------------------------------------
@@ -103,11 +128,13 @@ export class PrismaStore implements Store {
   readonly #seqNos = new SeqNoTracker()
   readonly #metaModelName: string
   readonly #recordModelName: string
+  readonly #storeMetaModelName: string
 
   constructor(options: PrismaStoreOptions) {
     this.#client = options.client as PrismaClientLike
-    this.#metaModelName = options.metaModel ?? "kynetaMeta"
+    this.#metaModelName = options.metaModel ?? "kynetaDocMeta"
     this.#recordModelName = options.recordModel ?? "kynetaRecord"
+    this.#storeMetaModelName = options.storeMetaModel ?? "kynetaStoreMeta"
   }
 
   get #meta(): MetaModel {
@@ -116,6 +143,12 @@ export class PrismaStore implements Store {
     ] as MetaModel
   }
 
+  get #storeMeta(): StoreMetaModel {
+    return (this.#client as unknown as Record<string, unknown>)[
+      this.#storeMetaModelName
+    ] as StoreMetaModel
+  }
+
   get #records(): RecordModel {
     return (this.#client as unknown as Record<string, unknown>)[
       this.#recordModelName
@@ -258,6 +291,55 @@ export class PrismaStore implements Store {
   async close(): Promise<void> {
     // Caller owns the lifecycle (`prisma.$disconnect()`).
   }
+
+  // Bootstrap reader: stamp/accept/refuse the store-format marker on open.
+  // A `static open` reaches this private method so the gate stays internal.
+  async #assertFormat(): Promise<void> {
+    const row = await this.#storeMeta.findUnique({
+      where: { key: STORE_META_FORMAT_KEY },
+    })
+    const parsed =
+      row === null ? null : parseStoreFormat(parseMetaData(row.value))
+    if (parsed === "malformed") {
+      throw new StoreFormatVersionError({
+        reason: "malformed-version",
+        backend: "prisma",
+        stored: null,
+        current: STORE_FORMAT_VERSION,
+      })
+    }
+
+    const docCount = await this.#meta.count()
+
+    const decision = decideStoreFormat({
+      current: STORE_FORMAT_VERSION,
+      stored: parsed,
+      storeHasData: docCount > 0,
+    })
+
+    if (decision.action === "refuse") {
+      throw new StoreFormatVersionError({
+        reason: decision.reason,
+        backend: "prisma",
+        stored: parsed,
+        current: STORE_FORMAT_VERSION,
+      })
+    }
+    if (decision.action === "stamp") {
+      await this.#storeMeta.upsert({
+        where: { key: STORE_META_FORMAT_KEY },
+        create: { key: STORE_META_FORMAT_KEY, value: decision.value },
+        update: { value: decision.value },
+      })
+    }
+  }
+
+  /** Construct + run the store-format gate. Used by `createPrismaStore`. */
+  static async open(options: PrismaStoreOptions): Promise<Store> {
+    const store = new PrismaStore(options)
+    await store.#assertFormat()
+    return store
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -289,12 +371,13 @@ function prefixUpperBound(prefix: string): string | null {
 }
 
 /**
- * Async only for ergonomic parity with `createPostgresStore` — does
- * no schema validation. Prisma's typed accessors enforce model presence
- * at compile time; runtime failures surface on first call.
+ * Does no schema validation (Prisma's typed accessors enforce model
+ * presence at compile time; runtime failures surface on first call), but
+ * does run the store-format gate on open: it stamps a brand-new store,
+ * accepts a compatible one, or throws `StoreFormatVersionError`.
  */
 export async function createPrismaStore(
   options: PrismaStoreOptions,
 ): Promise<Store> {
-  return new PrismaStore(options)
+  return PrismaStore.open(options)
 }