@kyneta/leveldb-store 1.8.0 → 2.0.0

package/README.md

@@ -18,7 +18,7 @@ import { createLevelDBStore } from "@kyneta/leveldb-store/server"
 
 const exchange = new Exchange({
   identity: { peerId: "my-server", name: "server" },
-  stores: [createLevelDBStore("./data/exchange-db")],
+  stores: [await createLevelDBStore("./data/exchange-db")],
   transports: [networkTransport],
 })
 
@@ -32,28 +32,32 @@ That's it. The Exchange handles hydration (loading from storage on `get()` / `re
 
 ### `createLevelDBStore(dbPath)`
 
-Factory function that returns a `Store`. The `dbPath` is the directory where LevelDB stores its files.
+Async factory that opens the database, runs the store-format gate (see below), and resolves to a `Store`. The `dbPath` is the directory where LevelDB stores its files. `await` it before passing to the `Exchange`.
 
 ```ts
 import { createLevelDBStore } from "@kyneta/leveldb-store/server"
 
-const store = createLevelDBStore("./data/exchange-db")
+const store = await createLevelDBStore("./data/exchange-db")
 ```
 
 ### `LevelDBStore`
 
-The class implementing the `Store` interface. Use `createLevelDBStore` for most cases; use the class directly if you need access to `close()` outside of the Exchange lifecycle.
+The class implementing the `Store` interface. Use `createLevelDBStore` (or `LevelDBStore.open(dbPath)`) for most cases — both are async and run the store-format gate. The bare `new LevelDBStore(dbPath)` constructor opens the database **without** the gate and is for advanced use only.
 
 ```ts
 import { LevelDBStore } from "@kyneta/leveldb-store/server"
 
-const store = new LevelDBStore("./data/exchange-db")
+const store = await LevelDBStore.open("./data/exchange-db")
 
 // ... use with Exchange ...
 
 await store.close() // release file handles
 ```
 
+### Store-format gate
+
+On open, the store stamps a `{ major, minor }` format version into a `store-meta\x00` key namespace (separate from the per-doc `doc-meta\x00` keys), and on subsequent opens refuses — with `StoreFormatVersionError` — a store whose stamped major is incompatible with the running build, or an unversioned store that already holds documents. No automatic migration is performed.
+
 ### Binary Codec
 
 The module also exports `encodeStoreEntry` and `decodeStoreEntry` for the compact binary envelope format. These are pure functions — useful for debugging, migration scripts, or building custom tooling over the LevelDB data files.
@@ -99,7 +103,7 @@ Flags byte layout:
 
 ### Atomicity
 
-`replace()` uses LevelDB's batch operation to atomically delete all existing entries and write the single replacement. A concurrent reader never observes an empty intermediate state.
+Every write commits through a single LevelDB `batch`. `append()` of a metadata record commits the materialized index update and the record together, so a crash can never leave the `doc-meta` index advanced past its backing record (an entry-record append is a single record write). `replace()` atomically deletes all existing entries and writes the replacements. A concurrent reader never observes a partial intermediate state.
 
 ## Testing
 

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import { DocId, Store, StoreMeta, StoreRecord } from "@kyneta/exchange";
+import { ClassicLevel } from "classic-level";
 
 //#region src/index.d.ts
 declare function encodeStoreRecord(record: StoreRecord): Uint8Array;
 declare function decodeStoreRecord(bytes: Uint8Array): StoreRecord;
 declare class LevelDBStore implements Store {
   #private;
-  constructor(dbPath: string);
+  constructor(dbPathOrDb: string | ClassicLevel<string, Uint8Array>);
   currentMeta(docId: DocId): Promise<StoreMeta | null>;
   append(docId: DocId, record: StoreRecord): Promise<void>;
   loadAll(docId: DocId): AsyncIterable<StoreRecord>;
@@ -13,11 +14,15 @@ declare class LevelDBStore implements Store {
   delete(docId: DocId): Promise<void>;
   listDocIds(prefix?: string): AsyncIterable<DocId>;
   close(): Promise<void>;
+  /** Open the store and run the store-format gate. Used by `createLevelDBStore`. */
+  static open(dbPathOrDb: string | ClassicLevel<string, Uint8Array>): Promise<Store>;
 }
 /**
  * Create a LevelDB storage backend for server-side persistence.
  *
- * Returns a `Store` — pass directly to `Exchange({ stores: [...] })`.
+ * Async: it opens the database and runs the store-format gate (stamping a
+ * brand-new store, accepting a compatible one, or throwing
+ * `StoreFormatVersionError`). `await` it before passing to the `Exchange`.
  *
  * @param dbPath - Directory path where LevelDB stores its files
  *
@@ -26,11 +31,11 @@ declare class LevelDBStore implements Store {
  * import { createLevelDBStore } from "@kyneta/leveldb-store"
  *
  * const exchange = new Exchange({
- *   stores: [createLevelDBStore("./data/exchange-db")],
+ *   stores: [await createLevelDBStore("./data/exchange-db")],
  * })
  * ```
  */
-declare function createLevelDBStore(dbPath: string): Store;
+declare function createLevelDBStore(dbPath: string): Promise<Store>;
 //#endregion
 export { LevelDBStore, createLevelDBStore, decodeStoreRecord, encodeStoreRecord };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;iBAuDgB,iBAAA,CAAkB,MAAA,EAAQ,WAAA,GAAc,UAAU;AAAA,iBAmClD,iBAAA,CAAkB,KAAA,EAAO,UAAA,GAAa,WAAW;AAAA,cAsEpD,YAAA,YAAwB,KAAA;EAAA;cAIvB,MAAA;EAUN,WAAA,CAAY,KAAA,EAAO,KAAA,GAAQ,OAAA,CAAQ,SAAA;EAUnC,MAAA,CAAO,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,WAAA,GAAc,OAAA;EA0B1C,OAAA,CAAQ,KAAA,EAAO,KAAA,GAAQ,aAAA,CAAc,WAAA;EAUtC,OAAA,CAAQ,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,WAAA,KAAgB,OAAA;EA2C/C,MAAA,CAAO,KAAA,EAAO,KAAA,GAAQ,OAAA;EAoBrB,UAAA,CAAW,MAAA,YAAkB,aAAA,CAAc,KAAA;EAW5C,KAAA,CAAA,GAAS,OAAA;AAAA;;;;;;;AA5MgD;AAsEjE;;;;;;;;;iBA+JgB,kBAAA,CAAmB,MAAA,WAAiB,KAAK"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;iBA4EgB,iBAAA,CAAkB,MAAA,EAAQ,WAAA,GAAc,UAAU;AAAA,iBAmClD,iBAAA,CAAkB,KAAA,EAAO,UAAA,GAAa,WAAW;AAAA,cAwHpD,YAAA,YAAwB,KAAA;EAAA;cAOvB,UAAA,WAAqB,YAAA,SAAqB,UAAA;EAWhD,WAAA,CAAY,KAAA,EAAO,KAAA,GAAQ,OAAA,CAAQ,SAAA;EAUnC,MAAA,CAAO,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,WAAA,GAAc,OAAA;EA0B1C,OAAA,CAAQ,KAAA,EAAO,KAAA,GAAQ,aAAA,CAAc,WAAA;EAUtC,OAAA,CAAQ,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,WAAA,KAAgB,OAAA;EA2C/C,MAAA,CAAO,KAAA,EAAO,KAAA,GAAQ,OAAA;EAoBrB,UAAA,CAAW,MAAA,YAAkB,aAAA,CAAc,KAAA;EAW5C,KAAA,CAAA,GAAS,OAAA;EAlQgB;EAAA,OA4TlB,IAAA,CACX,UAAA,WAAqB,YAAA,SAAqB,UAAA,IACzC,OAAA,CAAQ,KAAA;AAAA;;;;;AA9ToD;AAwHjE;;;;;;;;;;;;;iBAyOgB,kBAAA,CAAmB,MAAA,WAAiB,OAAO,CAAC,KAAA"}

package/dist/index.js

@@ -1,10 +1,15 @@
-import { SeqNoTracker, resolveMetaFromBatch, validateAppend } from "@kyneta/exchange";
+import { STORE_META_FORMAT_KEY, SeqNoTracker, StoreFormatVersionError, decideStoreFormat, parseStoreFormat, resolveMetaFromBatch, validateAppend } from "@kyneta/exchange";
 import { ClassicLevel } from "classic-level";
 //#region src/index.ts
 const SEP = "\0";
-const META_PREFIX = `meta${SEP}`;
+const DOC_META_PREFIX = `doc-meta${SEP}`;
 const RECORD_PREFIX = `record${SEP}`;
 const SEQ_PAD = 16;
+const STORE_FORMAT_KEY = `${`store-meta${SEP}`}${STORE_META_FORMAT_KEY}`;
+const STORE_FORMAT_VERSION = {
+	major: 1,
+	minor: 0
+};
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 function encodeStoreRecord(record) {
@@ -61,8 +66,8 @@ function decodeStoreRecord(bytes) {
 		version
 	};
 }
-function metaKey(docId) {
-	return `${META_PREFIX}${docId}`;
+function docMetaKey(docId) {
+	return `${DOC_META_PREFIX}${docId}`;
 }
 function recordPrefix(docId) {
 	return `${RECORD_PREFIX}${docId}${SEP}`;
@@ -70,31 +75,57 @@ function recordPrefix(docId) {
 function recordKey(docId, seqNo) {
 	return `${recordPrefix(docId)}${String(seqNo).padStart(SEQ_PAD, "0")}`;
 }
-function parseDocIdFromMetaKey(key) {
-	return key.slice(META_PREFIX.length);
+function parseDocIdFromDocMetaKey(key) {
+	return key.slice(DOC_META_PREFIX.length);
 }
 function parseSeqNoFromRecordKey(key, docId) {
 	const prefix = recordPrefix(docId);
 	return Number.parseInt(key.slice(prefix.length), 10);
 }
-var LevelDBStore = class {
+function encodeDocMeta(meta) {
+	return encoder.encode(JSON.stringify(meta));
+}
+function decodeDocMeta(bytes) {
+	return JSON.parse(decoder.decode(bytes));
+}
+/**
+* Pure: validate the record against existing meta and return the LevelDB batch
+* ops to write. Mirrors sql-core's `planAppend` (the gather/plan/execute split,
+* jj:pzuytnvo). An entry record yields a single record `put`; a meta record
+* adds the doc-meta index `put`, and the two commit together in one batch.
+* `validateAppend` throws on an entry-before-meta violation — a pure,
+* input-deterministic throw.
+*/
+function planAppend(docId, record, existingMeta, seq) {
+	const resolved = validateAppend(docId, record, existingMeta);
+	const ops = [{
+		type: "put",
+		key: recordKey(docId, seq),
+		value: encodeStoreRecord(record)
+	}];
+	if (resolved !== null) ops.push({
+		type: "put",
+		key: docMetaKey(docId),
+		value: encodeDocMeta(resolved)
+	});
+	return ops;
+}
+var LevelDBStore = class LevelDBStore {
 	#db;
 	#seqNos = new SeqNoTracker();
-	constructor(dbPath) {
-		this.#db = new ClassicLevel(dbPath, { valueEncoding: "binary" });
+	constructor(dbPathOrDb) {
+		this.#db = typeof dbPathOrDb === "string" ? new ClassicLevel(dbPathOrDb, { valueEncoding: "binary" }) : dbPathOrDb;
 	}
 	async currentMeta(docId) {
 		try {
-			const raw = await this.#db.get(metaKey(docId));
-			return JSON.parse(decoder.decode(raw));
+			return decodeDocMeta(await this.#db.get(docMetaKey(docId)));
 		} catch (error) {
 			if (error.code === "LEVEL_NOT_FOUND") return null;
 			throw error;
 		}
 	}
 	async append(docId, record) {
-		const resolved = validateAppend(docId, record, await this.currentMeta(docId));
-		if (resolved !== null) await this.#db.put(metaKey(docId), encoder.encode(JSON.stringify(resolved)));
+		const existingMeta = await this.currentMeta(docId);
 		const seq = await this.#seqNos.next(docId, async () => {
 			const prefix = recordPrefix(docId);
 			for await (const key of this.#db.keys({
@@ -105,7 +136,7 @@ var LevelDBStore = class {
 			})) return parseSeqNoFromRecordKey(key, docId);
 			return null;
 		});
-		await this.#db.put(recordKey(docId, seq), encodeStoreRecord(record));
+		await this.#db.batch(planAppend(docId, record, existingMeta, seq));
 	}
 	async *loadAll(docId) {
 		const prefix = recordPrefix(docId);
@@ -133,15 +164,15 @@ var LevelDBStore = class {
 		});
 		ops.push({
 			type: "put",
-			key: metaKey(docId),
-			value: encoder.encode(JSON.stringify(resolved))
+			key: docMetaKey(docId),
+			value: encodeDocMeta(resolved)
 		});
 		await this.#db.batch(ops);
 		this.#seqNos.reset(docId, records.length - 1);
 	}
 	async delete(docId) {
 		const prefix = recordPrefix(docId);
-		const keysToDelete = [metaKey(docId)];
+		const keysToDelete = [docMetaKey(docId)];
 		for await (const key of this.#db.keys({
 			gte: prefix,
 			lt: `${prefix}\xff`
@@ -153,20 +184,66 @@ var LevelDBStore = class {
 		this.#seqNos.remove(docId);
 	}
 	async *listDocIds(prefix) {
-		const rangePrefix = prefix !== void 0 ? `${META_PREFIX}${prefix}` : META_PREFIX;
+		const rangePrefix = prefix !== void 0 ? `${DOC_META_PREFIX}${prefix}` : DOC_META_PREFIX;
 		for await (const key of this.#db.keys({
 			gte: rangePrefix,
 			lt: `${rangePrefix}\xff`
-		})) yield parseDocIdFromMetaKey(key);
+		})) yield parseDocIdFromDocMetaKey(key);
 	}
 	async close() {
 		await this.#db.close();
 	}
+	async #assertFormat() {
+		let parsed = null;
+		try {
+			const raw = await this.#db.get(STORE_FORMAT_KEY);
+			parsed = parseStoreFormat(decoder.decode(raw));
+		} catch (error) {
+			if (error.code !== "LEVEL_NOT_FOUND") throw error;
+		}
+		if (parsed === "malformed") throw new StoreFormatVersionError({
+			reason: "malformed-version",
+			backend: "leveldb",
+			stored: null,
+			current: STORE_FORMAT_VERSION
+		});
+		let hasData = false;
+		for await (const _key of this.#db.keys({
+			gte: DOC_META_PREFIX,
+			lt: `${DOC_META_PREFIX}\xff`,
+			limit: 1
+		})) hasData = true;
+		const decision = decideStoreFormat({
+			current: STORE_FORMAT_VERSION,
+			stored: parsed,
+			storeHasData: hasData
+		});
+		if (decision.action === "refuse") throw new StoreFormatVersionError({
+			reason: decision.reason,
+			backend: "leveldb",
+			stored: parsed,
+			current: STORE_FORMAT_VERSION
+		});
+		if (decision.action === "stamp") await this.#db.put(STORE_FORMAT_KEY, encoder.encode(JSON.stringify(decision.value)));
+	}
+	/** Open the store and run the store-format gate. Used by `createLevelDBStore`. */
+	static async open(dbPathOrDb) {
+		const store = new LevelDBStore(dbPathOrDb);
+		try {
+			await store.#assertFormat();
+		} catch (error) {
+			await store.#db.close();
+			throw error;
+		}
+		return store;
+	}
 };
 /**
 * Create a LevelDB storage backend for server-side persistence.
 *
-* Returns a `Store` — pass directly to `Exchange({ stores: [...] })`.
+* Async: it opens the database and runs the store-format gate (stamping a
+* brand-new store, accepting a compatible one, or throwing
+* `StoreFormatVersionError`). `await` it before passing to the `Exchange`.
 *
 * @param dbPath - Directory path where LevelDB stores its files
 *
@@ -175,12 +252,12 @@ var LevelDBStore = class {
 * import { createLevelDBStore } from "@kyneta/leveldb-store"
 *
 * const exchange = new Exchange({
-*   stores: [createLevelDBStore("./data/exchange-db")],
+*   stores: [await createLevelDBStore("./data/exchange-db")],
 * })
 * ```
 */
 function createLevelDBStore(dbPath) {
-	return new LevelDBStore(dbPath);
+	return LevelDBStore.open(dbPath);
 }
 //#endregion
 export { LevelDBStore, createLevelDBStore, decodeStoreRecord, encodeStoreRecord };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["#db","#seqNos"],"sources":["../src/index.ts"],"sourcesContent":["// server — LevelDB storage backend for @kyneta/exchange.\n//\n// Implements the Store interface using classic-level.\n//\n// Key-space design (FoundationDB convention — \\x00 null-byte separator):\n//   meta\\x00{docId}                       → JSON-encoded StoreMeta (materialized index)\n//   record\\x00{docId}\\x00{seqNo}          → binary-encoded StoreRecord (unified stream)\n//\n// The \\x00 separator cannot appear in valid UTF-8 strings, so no docId\n// validation is needed — the key-space imposes zero constraints on callers.\n//\n// SeqNo is a zero-padded 16-digit monotonic counter per doc, tracked in\n// memory. On reboot, the max seqNo for a doc is lazily discovered via a\n// single reverse-iterator seek on first append.\n\nimport {\n  type DocId,\n  resolveMetaFromBatch,\n  SeqNoTracker,\n  type Store,\n  type StoreMeta,\n  type StoreRecord,\n  validateAppend,\n} from \"@kyneta/exchange\"\nimport { ClassicLevel } from \"classic-level\"\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\nconst SEP = \"\\x00\"\nconst META_PREFIX = `meta${SEP}`\nconst RECORD_PREFIX = `record${SEP}`\nconst SEQ_PAD = 16\n\n// ---------------------------------------------------------------------------\n// Binary envelope v2 — pure encode/decode for StoreRecord\n// ---------------------------------------------------------------------------\n\n// Flags byte layout:\n//   bit 0: payload kind     (0 = entirety, 1 = since) — entry records only\n//   bit 1: encoding         (0 = json, 1 = binary) — entry records only\n//   bit 2: data type        (0 = string, 1 = Uint8Array) — entry records only\n//   bit 3: record kind      (0 = entry, 1 = meta)\n//   bit 7: future-format    (0 = current format, reserved)\n//\n// Meta records (bit 3 = 1):\n//   [1 byte flags] [remaining: JSON-encoded StoreMeta]\n//\n// Entry records (bit 3 = 0):\n//   [1 byte flags] [4 bytes version length BE] [N bytes version UTF-8] [remaining: payload data]\n\nconst encoder = new TextEncoder()\nconst decoder = new TextDecoder()\n\nexport function encodeStoreRecord(record: StoreRecord): Uint8Array {\n  if (record.kind === \"meta\") {\n    const metaBytes = encoder.encode(JSON.stringify(record.meta))\n    const buf = new Uint8Array(1 + metaBytes.length)\n    buf[0] = 0x08 // bit 3 set (meta)\n    buf.set(metaBytes, 1)\n    return buf\n  }\n\n  // Entry record\n  const { payload, version } = record\n\n  let flags = 0\n  if (payload.kind === \"since\") flags |= 0x01\n  if (payload.encoding === \"binary\") flags |= 0x02\n\n  const isDataBinary = payload.data instanceof Uint8Array\n  if (isDataBinary) flags |= 0x04\n\n  const versionBytes = encoder.encode(version)\n  const dataBytes = isDataBinary\n    ? (payload.data as Uint8Array)\n    : encoder.encode(payload.data as string)\n\n  const buf = new Uint8Array(1 + 4 + versionBytes.length + dataBytes.length)\n  const view = new DataView(buf.buffer)\n\n  buf[0] = flags\n  view.setUint32(1, versionBytes.length, false) // big-endian\n  buf.set(versionBytes, 5)\n  buf.set(dataBytes, 5 + versionBytes.length)\n\n  return buf\n}\n\nexport function decodeStoreRecord(bytes: Uint8Array): StoreRecord {\n  const flagByte = bytes[0]\n  if (flagByte === undefined) throw new Error(\"empty store record bytes\")\n  const flags = flagByte\n\n  // Check future-format flag (bit 7)\n  if ((flags & 0x80) !== 0) {\n    throw new Error(\"unknown store record format (future-format bit set)\")\n  }\n\n  const isMeta = (flags & 0x08) !== 0\n\n  if (isMeta) {\n    const metaJson = decoder.decode(bytes.subarray(1))\n    return { kind: \"meta\", meta: JSON.parse(metaJson) as StoreMeta }\n  }\n\n  // Entry record\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)\n\n  const kind = (flags & 0x01) !== 0 ? \"since\" : \"entirety\"\n  const encoding = (flags & 0x02) !== 0 ? \"binary\" : \"json\"\n  const isDataBinary = (flags & 0x04) !== 0\n\n  const versionLen = view.getUint32(1, false)\n  const version = decoder.decode(bytes.subarray(5, 5 + versionLen))\n\n  const dataStart = 5 + versionLen\n  const rawData = bytes.subarray(dataStart)\n\n  const data: string | Uint8Array = isDataBinary\n    ? new Uint8Array(rawData)\n    : decoder.decode(rawData)\n\n  return {\n    kind: \"entry\",\n    payload: { kind, encoding, data },\n    version,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Key helpers\n// ---------------------------------------------------------------------------\n\nfunction metaKey(docId: DocId): string {\n  return `${META_PREFIX}${docId}`\n}\n\nfunction recordPrefix(docId: DocId): string {\n  return `${RECORD_PREFIX}${docId}${SEP}`\n}\n\nfunction recordKey(docId: DocId, seqNo: number): string {\n  return `${recordPrefix(docId)}${String(seqNo).padStart(SEQ_PAD, \"0\")}`\n}\n\nfunction parseDocIdFromMetaKey(key: string): DocId {\n  return key.slice(META_PREFIX.length)\n}\n\nfunction parseSeqNoFromRecordKey(key: string, docId: DocId): number {\n  const prefix = recordPrefix(docId)\n  return Number.parseInt(key.slice(prefix.length), 10)\n}\n\n// ---------------------------------------------------------------------------\n// LevelDBStore\n// ---------------------------------------------------------------------------\n\nexport class LevelDBStore implements Store {\n  readonly #db: ClassicLevel<string, Uint8Array>\n  readonly #seqNos = new SeqNoTracker()\n\n  constructor(dbPath: string) {\n    this.#db = new ClassicLevel(dbPath, {\n      valueEncoding: \"binary\",\n    })\n  }\n\n  // -------------------------------------------------------------------------\n  // Store interface\n  // -------------------------------------------------------------------------\n\n  async currentMeta(docId: DocId): Promise<StoreMeta | null> {\n    try {\n      const raw = await this.#db.get(metaKey(docId))\n      return JSON.parse(decoder.decode(raw)) as StoreMeta\n    } catch (error: any) {\n      if (error.code === \"LEVEL_NOT_FOUND\") return null\n      throw error\n    }\n  }\n\n  async append(docId: DocId, record: StoreRecord): Promise<void> {\n    const existingMeta = await this.currentMeta(docId)\n    const resolved = validateAppend(docId, record, existingMeta)\n\n    if (resolved !== null) {\n      await this.#db.put(\n        metaKey(docId),\n        encoder.encode(JSON.stringify(resolved)),\n      )\n    }\n\n    const seq = await this.#seqNos.next(docId, async () => {\n      const prefix = recordPrefix(docId)\n      for await (const key of this.#db.keys({\n        gte: prefix,\n        lt: `${prefix}\\xff`,\n        reverse: true,\n        limit: 1,\n      })) {\n        return parseSeqNoFromRecordKey(key, docId)\n      }\n      return null\n    })\n    await this.#db.put(recordKey(docId, seq), encodeStoreRecord(record))\n  }\n\n  async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {\n    const prefix = recordPrefix(docId)\n    for await (const value of this.#db.values({\n      gte: prefix,\n      lt: `${prefix}\\xff`,\n    })) {\n      yield decodeStoreRecord(value)\n    }\n  }\n\n  async replace(docId: DocId, records: StoreRecord[]): Promise<void> {\n    const existingMeta = await this.currentMeta(docId)\n\n    // Resolve validates: at least one meta present, immutable fields match.\n    const resolved = resolveMetaFromBatch(records, existingMeta)\n\n    const prefix = recordPrefix(docId)\n\n    // Collect existing record keys to delete\n    const keysToDelete: string[] = []\n    for await (const key of this.#db.keys({\n      gte: prefix,\n      lt: `${prefix}\\xff`,\n    })) {\n      keysToDelete.push(key)\n    }\n\n    // Atomic batch: delete all existing records, write replacements, upsert meta\n    const ops: Array<\n      | { type: \"del\"; key: string }\n      | { type: \"put\"; key: string; value: Uint8Array }\n    > = keysToDelete.map(key => ({ type: \"del\" as const, key }))\n\n    for (let i = 0; i < records.length; i++) {\n      ops.push({\n        type: \"put\",\n        key: recordKey(docId, i),\n        value: encodeStoreRecord(records[i]!),\n      })\n    }\n\n    ops.push({\n      type: \"put\",\n      key: metaKey(docId),\n      value: encoder.encode(JSON.stringify(resolved)),\n    })\n\n    await this.#db.batch(ops)\n\n    // Reset seqNo counter to the last written index\n    this.#seqNos.reset(docId, records.length - 1)\n  }\n\n  async delete(docId: DocId): Promise<void> {\n    const prefix = recordPrefix(docId)\n\n    // Collect record keys to delete\n    const keysToDelete: string[] = [metaKey(docId)]\n    for await (const key of this.#db.keys({\n      gte: prefix,\n      lt: `${prefix}\\xff`,\n    })) {\n      keysToDelete.push(key)\n    }\n\n    await this.#db.batch(\n      keysToDelete.map(key => ({ type: \"del\" as const, key })),\n    )\n\n    // Remove from in-memory seqNo tracker\n    this.#seqNos.remove(docId)\n  }\n\n  async *listDocIds(prefix?: string): AsyncIterable<DocId> {\n    const rangePrefix =\n      prefix !== undefined ? `${META_PREFIX}${prefix}` : META_PREFIX\n    for await (const key of this.#db.keys({\n      gte: rangePrefix,\n      lt: `${rangePrefix}\\xff`,\n    })) {\n      yield parseDocIdFromMetaKey(key)\n    }\n  }\n\n  async close(): Promise<void> {\n    await this.#db.close()\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory function\n// ---------------------------------------------------------------------------\n\n/**\n * Create a LevelDB storage backend for server-side persistence.\n *\n * Returns a `Store` — pass directly to `Exchange({ stores: [...] })`.\n *\n * @param dbPath - Directory path where LevelDB stores its files\n *\n * @example\n * ```typescript\n * import { createLevelDBStore } from \"@kyneta/leveldb-store\"\n *\n * const exchange = new Exchange({\n *   stores: [createLevelDBStore(\"./data/exchange-db\")],\n * })\n * ```\n */\nexport function createLevelDBStore(dbPath: string): Store {\n  return new LevelDBStore(dbPath)\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["#db","#seqNos","#assertFormat"],"sources":["../src/index.ts"],"sourcesContent":["// server — LevelDB storage backend for @kyneta/exchange.\n//\n// Implements the Store interface using classic-level.\n//\n// Key-space design (FoundationDB convention — \\x00 null-byte separator):\n//   doc-meta\\x00{docId}                   → JSON-encoded StoreMeta (materialized index)\n//   record\\x00{docId}\\x00{seqNo}          → binary-encoded StoreRecord (unified stream)\n//   store-meta\\x00{key}                   → store-global metadata (e.g. format version)\n//\n// The \\x00 separator cannot appear in valid UTF-8 strings, so no docId\n// validation is needed — the key-space imposes zero constraints on callers.\n//\n// SeqNo is a zero-padded 16-digit monotonic counter per doc, tracked in\n// memory. On reboot, the max seqNo for a doc is lazily discovered via a\n// single reverse-iterator seek on first append.\n\nimport {\n  type DocId,\n  decideStoreFormat,\n  parseStoreFormat,\n  resolveMetaFromBatch,\n  SeqNoTracker,\n  STORE_META_FORMAT_KEY,\n  type Store,\n  type StoreFormatVersion,\n  StoreFormatVersionError,\n  type StoreMeta,\n  type StoreRecord,\n  validateAppend,\n} from \"@kyneta/exchange\"\nimport { ClassicLevel } from \"classic-level\"\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\nconst SEP = \"\\x00\"\nconst DOC_META_PREFIX = `doc-meta${SEP}`\nconst RECORD_PREFIX = `record${SEP}`\nconst SEQ_PAD = 16\n\n// Store-global metadata namespace, keyed `store-meta\\x00{key}`. It sorts\n// above `doc-meta\\x00` ('d' < 's') and `record\\x00` ('r' < 's'), so it is\n// outside every `doc-meta`/`record` iteration range and needs no filtering.\n// Do not relocate it into those ranges. The on-disk format version lives at\n// `store-meta\\x00format`. This is read by a bootstrap reader on open, never\n// through the Store interface. Context: jj:uvssotsy.\nconst STORE_META_PREFIX = `store-meta${SEP}`\nconst STORE_FORMAT_KEY = `${STORE_META_PREFIX}${STORE_META_FORMAT_KEY}`\n\n// LevelDB owns its own on-disk format version (its binary envelope), gated on\n// open via `decideStoreFormat`. Distinct from the envelope's per-record bit-7\n// guard (`decodeStoreRecord`): bit-7 guards one record's decode; this marker\n// guards opening the store at all.\nconst STORE_FORMAT_VERSION: StoreFormatVersion = { major: 1, minor: 0 }\n\n// ---------------------------------------------------------------------------\n// Binary envelope v2 — pure encode/decode for StoreRecord\n// ---------------------------------------------------------------------------\n\n// Flags byte layout:\n//   bit 0: payload kind     (0 = entirety, 1 = since) — entry records only\n//   bit 1: encoding         (0 = json, 1 = binary) — entry records only\n//   bit 2: data type        (0 = string, 1 = Uint8Array) — entry records only\n//   bit 3: record kind      (0 = entry, 1 = meta)\n//   bit 7: future-format    (0 = current format, reserved)\n//\n// Meta records (bit 3 = 1):\n//   [1 byte flags] [remaining: JSON-encoded StoreMeta]\n//\n// Entry records (bit 3 = 0):\n//   [1 byte flags] [4 bytes version length BE] [N bytes version UTF-8] [remaining: payload data]\n\nconst encoder = new TextEncoder()\nconst decoder = new TextDecoder()\n\nexport function encodeStoreRecord(record: StoreRecord): Uint8Array {\n  if (record.kind === \"meta\") {\n    const metaBytes = encoder.encode(JSON.stringify(record.meta))\n    const buf = new Uint8Array(1 + metaBytes.length)\n    buf[0] = 0x08 // bit 3 set (meta)\n    buf.set(metaBytes, 1)\n    return buf\n  }\n\n  // Entry record\n  const { payload, version } = record\n\n  let flags = 0\n  if (payload.kind === \"since\") flags |= 0x01\n  if (payload.encoding === \"binary\") flags |= 0x02\n\n  const isDataBinary = payload.data instanceof Uint8Array\n  if (isDataBinary) flags |= 0x04\n\n  const versionBytes = encoder.encode(version)\n  const dataBytes = isDataBinary\n    ? (payload.data as Uint8Array)\n    : encoder.encode(payload.data as string)\n\n  const buf = new Uint8Array(1 + 4 + versionBytes.length + dataBytes.length)\n  const view = new DataView(buf.buffer)\n\n  buf[0] = flags\n  view.setUint32(1, versionBytes.length, false) // big-endian\n  buf.set(versionBytes, 5)\n  buf.set(dataBytes, 5 + versionBytes.length)\n\n  return buf\n}\n\nexport function decodeStoreRecord(bytes: Uint8Array): StoreRecord {\n  const flagByte = bytes[0]\n  if (flagByte === undefined) throw new Error(\"empty store record bytes\")\n  const flags = flagByte\n\n  // Check future-format flag (bit 7)\n  if ((flags & 0x80) !== 0) {\n    throw new Error(\"unknown store record format (future-format bit set)\")\n  }\n\n  const isMeta = (flags & 0x08) !== 0\n\n  if (isMeta) {\n    const metaJson = decoder.decode(bytes.subarray(1))\n    return { kind: \"meta\", meta: JSON.parse(metaJson) as StoreMeta }\n  }\n\n  // Entry record\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)\n\n  const kind = (flags & 0x01) !== 0 ? \"since\" : \"entirety\"\n  const encoding = (flags & 0x02) !== 0 ? \"binary\" : \"json\"\n  const isDataBinary = (flags & 0x04) !== 0\n\n  const versionLen = view.getUint32(1, false)\n  const version = decoder.decode(bytes.subarray(5, 5 + versionLen))\n\n  const dataStart = 5 + versionLen\n  const rawData = bytes.subarray(dataStart)\n\n  const data: string | Uint8Array = isDataBinary\n    ? new Uint8Array(rawData)\n    : decoder.decode(rawData)\n\n  return {\n    kind: \"entry\",\n    payload: { kind, encoding, data },\n    version,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Key helpers\n// ---------------------------------------------------------------------------\n\nfunction docMetaKey(docId: DocId): string {\n  return `${DOC_META_PREFIX}${docId}`\n}\n\nfunction recordPrefix(docId: DocId): string {\n  return `${RECORD_PREFIX}${docId}${SEP}`\n}\n\nfunction recordKey(docId: DocId, seqNo: number): string {\n  return `${recordPrefix(docId)}${String(seqNo).padStart(SEQ_PAD, \"0\")}`\n}\n\nfunction parseDocIdFromDocMetaKey(key: string): DocId {\n  return key.slice(DOC_META_PREFIX.length)\n}\n\nfunction parseSeqNoFromRecordKey(key: string, docId: DocId): number {\n  const prefix = recordPrefix(docId)\n  return Number.parseInt(key.slice(prefix.length), 10)\n}\n\n// ---------------------------------------------------------------------------\n// Write planning — pure gather/plan/execute split (mirrors sql-core)\n// ---------------------------------------------------------------------------\n\ntype BatchOp =\n  | { readonly type: \"put\"; readonly key: string; readonly value: Uint8Array }\n  | { readonly type: \"del\"; readonly key: string }\n\n// Pure StoreMeta JSON envelope, shared by the writers (append/replace) and the\n// reader (currentMeta). The store-format marker keeps its own JSON.stringify —\n// it serializes a StoreFormatVersion, not a StoreMeta.\nfunction encodeDocMeta(meta: StoreMeta): Uint8Array {\n  return encoder.encode(JSON.stringify(meta))\n}\nfunction decodeDocMeta(bytes: Uint8Array): StoreMeta {\n  return JSON.parse(decoder.decode(bytes)) as StoreMeta\n}\n\n/**\n * Pure: validate the record against existing meta and return the LevelDB batch\n * ops to write. Mirrors sql-core's `planAppend` (the gather/plan/execute split,\n * jj:pzuytnvo). An entry record yields a single record `put`; a meta record\n * adds the doc-meta index `put`, and the two commit together in one batch.\n * `validateAppend` throws on an entry-before-meta violation — a pure,\n * input-deterministic throw.\n */\nfunction planAppend(\n  docId: DocId,\n  record: StoreRecord,\n  existingMeta: StoreMeta | null,\n  seq: number,\n): BatchOp[] {\n  const resolved = validateAppend(docId, record, existingMeta)\n  const ops: BatchOp[] = [\n    {\n      type: \"put\",\n      key: recordKey(docId, seq),\n      value: encodeStoreRecord(record),\n    },\n  ]\n  if (resolved !== null) {\n    ops.push({\n      type: \"put\",\n      key: docMetaKey(docId),\n      value: encodeDocMeta(resolved),\n    })\n  }\n  return ops\n}\n\n// ---------------------------------------------------------------------------\n// LevelDBStore\n// ---------------------------------------------------------------------------\n\nexport class LevelDBStore implements Store {\n  readonly #db: ClassicLevel<string, Uint8Array>\n  readonly #seqNos = new SeqNoTracker()\n\n  // Accepts a path (constructs a ClassicLevel) or an already-built handle. The\n  // handle form is the test seam for fault injection — production callers pass\n  // a path via `createLevelDBStore` / `open`. jj:pzuytnvo\n  constructor(dbPathOrDb: string | ClassicLevel<string, Uint8Array>) {\n    this.#db =\n      typeof dbPathOrDb === \"string\"\n        ? new ClassicLevel(dbPathOrDb, { valueEncoding: \"binary\" })\n        : dbPathOrDb\n  }\n\n  // -------------------------------------------------------------------------\n  // Store interface\n  // -------------------------------------------------------------------------\n\n  async currentMeta(docId: DocId): Promise<StoreMeta | null> {\n    try {\n      const raw = await this.#db.get(docMetaKey(docId))\n      return decodeDocMeta(raw)\n    } catch (error: any) {\n      if (error.code === \"LEVEL_NOT_FOUND\") return null\n      throw error\n    }\n  }\n\n  async append(docId: DocId, record: StoreRecord): Promise<void> {\n    const existingMeta = await this.currentMeta(docId)\n\n    // SeqNoTracker.next advances the in-memory counter before the write lands.\n    // On a caught write failure the counter runs one ahead of disk → a benign\n    // sparse seqNo (records are range-scanned, not indexed contiguously); it\n    // self-heals on reopen via the cold-start seek. Context: jj:pzuytnvo.\n    const seq = await this.#seqNos.next(docId, async () => {\n      const prefix = recordPrefix(docId)\n      for await (const key of this.#db.keys({\n        gte: prefix,\n        lt: `${prefix}\\xff`,\n        reverse: true,\n        limit: 1,\n      })) {\n        return parseSeqNoFromRecordKey(key, docId)\n      }\n      return null\n    })\n\n    // Single atomic batch: an entry append is a one-op batch (record only); a\n    // meta append commits the record and the doc-meta index together, so a\n    // crash never advances the index past its backing record. jj:pzuytnvo\n    await this.#db.batch(planAppend(docId, record, existingMeta, seq))\n  }\n\n  async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {\n    const prefix = recordPrefix(docId)\n    for await (const value of this.#db.values({\n      gte: prefix,\n      lt: `${prefix}\\xff`,\n    })) {\n      yield decodeStoreRecord(value)\n    }\n  }\n\n  async replace(docId: DocId, records: StoreRecord[]): Promise<void> {\n    const existingMeta = await this.currentMeta(docId)\n\n    // Resolve validates: at least one meta present, immutable fields match.\n    const resolved = resolveMetaFromBatch(records, existingMeta)\n\n    const prefix = recordPrefix(docId)\n\n    // Collect existing record keys to delete\n    const keysToDelete: string[] = []\n    for await (const key of this.#db.keys({\n      gte: prefix,\n      lt: `${prefix}\\xff`,\n    })) {\n      keysToDelete.push(key)\n    }\n\n    // Atomic batch: delete all existing records, write replacements, upsert meta\n    const ops: BatchOp[] = keysToDelete.map(key => ({\n      type: \"del\" as const,\n      key,\n    }))\n\n    for (let i = 0; i < records.length; i++) {\n      ops.push({\n        type: \"put\",\n        key: recordKey(docId, i),\n        value: encodeStoreRecord(records[i]!),\n      })\n    }\n\n    ops.push({\n      type: \"put\",\n      key: docMetaKey(docId),\n      value: encodeDocMeta(resolved),\n    })\n\n    await this.#db.batch(ops)\n\n    // Reset seqNo counter to the last written index\n    this.#seqNos.reset(docId, records.length - 1)\n  }\n\n  async delete(docId: DocId): Promise<void> {\n    const prefix = recordPrefix(docId)\n\n    // Collect record keys to delete\n    const keysToDelete: string[] = [docMetaKey(docId)]\n    for await (const key of this.#db.keys({\n      gte: prefix,\n      lt: `${prefix}\\xff`,\n    })) {\n      keysToDelete.push(key)\n    }\n\n    await this.#db.batch(\n      keysToDelete.map(key => ({ type: \"del\" as const, key })),\n    )\n\n    // Remove from in-memory seqNo tracker\n    this.#seqNos.remove(docId)\n  }\n\n  async *listDocIds(prefix?: string): AsyncIterable<DocId> {\n    const rangePrefix =\n      prefix !== undefined ? `${DOC_META_PREFIX}${prefix}` : DOC_META_PREFIX\n    for await (const key of this.#db.keys({\n      gte: rangePrefix,\n      lt: `${rangePrefix}\\xff`,\n    })) {\n      yield parseDocIdFromDocMetaKey(key)\n    }\n  }\n\n  async close(): Promise<void> {\n    await this.#db.close()\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  // A `static open` reaches this private method so the gate stays internal.\n  async #assertFormat(): Promise<void> {\n    let parsed: StoreFormatVersion | \"malformed\" | null = null\n    try {\n      const raw = await this.#db.get(STORE_FORMAT_KEY)\n      parsed = parseStoreFormat(decoder.decode(raw))\n    } catch (error: any) {\n      if (error.code !== \"LEVEL_NOT_FOUND\") throw error\n      // absent → parsed stays null\n    }\n    if (parsed === \"malformed\") {\n      throw new StoreFormatVersionError({\n        reason: \"malformed-version\",\n        backend: \"leveldb\",\n        stored: null,\n        current: STORE_FORMAT_VERSION,\n      })\n    }\n\n    // Empty-store probe: does any doc-meta key exist?\n    let hasData = false\n    for await (const _key of this.#db.keys({\n      gte: DOC_META_PREFIX,\n      lt: `${DOC_META_PREFIX}\\xff`,\n      limit: 1,\n    })) {\n      hasData = true\n    }\n\n    const decision = decideStoreFormat({\n      current: STORE_FORMAT_VERSION,\n      stored: parsed,\n      storeHasData: hasData,\n    })\n\n    if (decision.action === \"refuse\") {\n      throw new StoreFormatVersionError({\n        reason: decision.reason,\n        backend: \"leveldb\",\n        stored: parsed,\n        current: STORE_FORMAT_VERSION,\n      })\n    }\n    if (decision.action === \"stamp\") {\n      await this.#db.put(\n        STORE_FORMAT_KEY,\n        encoder.encode(JSON.stringify(decision.value)),\n      )\n    }\n  }\n\n  /** Open the store and run the store-format gate. Used by `createLevelDBStore`. */\n  static async open(\n    dbPathOrDb: string | ClassicLevel<string, Uint8Array>,\n  ): Promise<Store> {\n    const store = new LevelDBStore(dbPathOrDb)\n    try {\n      await store.#assertFormat()\n    } catch (error) {\n      // A refused store must not leak its file handle / lock.\n      await store.#db.close()\n      throw error\n    }\n    return store\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory function\n// ---------------------------------------------------------------------------\n\n/**\n * Create a LevelDB storage backend for server-side persistence.\n *\n * Async: it opens the database and runs the store-format gate (stamping a\n * brand-new store, accepting a compatible one, or throwing\n * `StoreFormatVersionError`). `await` it before passing to the `Exchange`.\n *\n * @param dbPath - Directory path where LevelDB stores its files\n *\n * @example\n * ```typescript\n * import { createLevelDBStore } from \"@kyneta/leveldb-store\"\n *\n * const exchange = new Exchange({\n *   stores: [await createLevelDBStore(\"./data/exchange-db\")],\n * })\n * ```\n */\nexport function createLevelDBStore(dbPath: string): Promise<Store> {\n  return LevelDBStore.open(dbPath)\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyneta/leveldb-store",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "LevelDB storage backend for @kyneta/exchange — server-side persistent storage",
   "author": "Duane Johnson",
   "license": "MIT",
@@ -28,8 +28,8 @@
     }
   },
   "peerDependencies": {
-    "@kyneta/exchange": "^1.8.0",
-    "@kyneta/schema": "^1.8.0"
+    "@kyneta/exchange": "^2.0.0",
+    "@kyneta/schema": "^2.0.0"
   },
   "dependencies": {
     "classic-level": "^1.4.1"
@@ -39,8 +39,8 @@
     "tsdown": "^0.22.0",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17",
-    "@kyneta/exchange": "^1.8.0",
-    "@kyneta/schema": "^1.8.0"
+    "@kyneta/exchange": "^2.0.0",
+    "@kyneta/schema": "^2.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/__tests__/leveldb-storage.test.ts

@@ -11,13 +11,20 @@ import type { StoreRecord } from "@kyneta/exchange"
 import {
   collectAll,
   describeStore,
+  makeArmedFault,
   makeBinaryEntryRecord,
   makeEntryRecord,
   makeMetaRecord,
   plainMeta,
 } from "@kyneta/exchange/testing"
+import { ClassicLevel } from "classic-level"
 import { afterAll, describe, expect, it } from "vitest"
-import { decodeStoreRecord, encodeStoreRecord, LevelDBStore } from "../index.js"
+import {
+  createLevelDBStore,
+  decodeStoreRecord,
+  encodeStoreRecord,
+  LevelDBStore,
+} from "../index.js"
 
 // ---------------------------------------------------------------------------
 // Temp directory management
@@ -45,10 +52,43 @@ afterAll(() => {
 // Conformance suite — validates the full Store contract
 // ---------------------------------------------------------------------------
 
-describeStore("LevelDBStore", () => new LevelDBStore(makeTmpDir()), {
+describeStore("LevelDBStore", () => createLevelDBStore(makeTmpDir()), {
   cleanup: async backend => {
     await backend.close()
   },
+  // Atomicity property: wrap the raw ClassicLevel so the Nth write op fails.
+  // Op-weighting (put = 1, batch = ops.length) makes the harness's
+  // injectFault(2) land inside the meta-append's 2-op batch, so the throw fires
+  // before the atomic batch commits — nothing leaks. jj:pzuytnvo
+  faultFactory: async () => {
+    const dir = makeTmpDir()
+    const raw = new ClassicLevel<string, Uint8Array>(dir, {
+      valueEncoding: "binary",
+    })
+    const { proxy, arm } = makeArmedFault(raw, {
+      put: 1,
+      batch: ops => (ops as readonly unknown[]).length,
+    })
+    const store = await LevelDBStore.open(proxy)
+    return {
+      store,
+      injectFault: arm,
+      // LevelDB takes a single-process directory lock, so the fresh store
+      // cannot open a second handle on `dir` while `raw` is live — release it
+      // first, then reopen non-faulting on the same dir.
+      freshStore: async () => {
+        await raw.close()
+        return createLevelDBStore(dir)
+      },
+      cleanup: async () => {
+        try {
+          await raw.close()
+        } catch {
+          // already closed by freshStore
+        }
+      },
+    }
+  },
 })
 
 // ---------------------------------------------------------------------------
@@ -60,14 +100,14 @@ describe("LevelDBStore — close + reopen", () => {
     const dir = makeTmpDir()
 
     // Phase 1: write data then close
-    const backend1 = new LevelDBStore(dir)
+    const backend1 = await createLevelDBStore(dir)
     await backend1.append("doc-1", makeMetaRecord())
     await backend1.append("doc-1", makeEntryRecord("entirety", "v1"))
     await backend1.append("doc-1", makeEntryRecord("since", "v2"))
     await backend1.close()
 
     // Phase 2: reopen and verify
-    const backend2 = new LevelDBStore(dir)
+    const backend2 = await createLevelDBStore(dir)
     expect(await backend2.currentMeta("doc-1")).toEqual(plainMeta)
 
     const records = await collectAll(backend2.loadAll("doc-1"))
@@ -87,14 +127,14 @@ describe("LevelDBStore — close + reopen", () => {
   it("append after reopen continues with correct seqNo ordering", async () => {
     const dir = makeTmpDir()
 
-    const backend1 = new LevelDBStore(dir)
+    const backend1 = await createLevelDBStore(dir)
     await backend1.append("doc-1", makeMetaRecord())
     await backend1.append("doc-1", makeEntryRecord("entirety", "v1"))
     await backend1.append("doc-1", makeEntryRecord("since", "v2"))
     await backend1.close()
 
     // Reopen and append more
-    const backend2 = new LevelDBStore(dir)
+    const backend2 = await createLevelDBStore(dir)
     await backend2.append("doc-1", makeEntryRecord("since", "v3"))
 
     const records = await collectAll(backend2.loadAll("doc-1"))
@@ -115,7 +155,7 @@ describe("LevelDBStore — close + reopen", () => {
   it("replace then reopen preserves the replacement records", async () => {
     const dir = makeTmpDir()
 
-    const backend1 = new LevelDBStore(dir)
+    const backend1 = await createLevelDBStore(dir)
     await backend1.append("doc-1", makeMetaRecord())
     await backend1.append("doc-1", makeEntryRecord("since", "v1"))
     await backend1.append("doc-1", makeEntryRecord("since", "v2"))
@@ -125,7 +165,7 @@ describe("LevelDBStore — close + reopen", () => {
     ])
     await backend1.close()
 
-    const backend2 = new LevelDBStore(dir)
+    const backend2 = await createLevelDBStore(dir)
     const records = await collectAll(backend2.loadAll("doc-1"))
     expect(records).toHaveLength(2)
     expect(records[0]?.kind).toBe("meta")
@@ -139,19 +179,54 @@ describe("LevelDBStore — close + reopen", () => {
   it("listDocIds works after reopen", async () => {
     const dir = makeTmpDir()
 
-    const backend1 = new LevelDBStore(dir)
+    const backend1 = await createLevelDBStore(dir)
     await backend1.append("alpha", makeMetaRecord())
     await backend1.append("beta", makeMetaRecord())
     await backend1.append("gamma", makeMetaRecord())
     await backend1.close()
 
-    const backend2 = new LevelDBStore(dir)
+    const backend2 = await createLevelDBStore(dir)
     const docIds = await collectAll(backend2.listDocIds())
     expect(docIds.sort()).toEqual(["alpha", "beta", "gamma"])
     await backend2.close()
   })
 })
 
+// ---------------------------------------------------------------------------
+// Store-format gate
+// ---------------------------------------------------------------------------
+
+describe("LevelDBStore — store-format gate", () => {
+  it("refuses an incompatible major and releases the lock so the dir reopens", async () => {
+    const dir = makeTmpDir()
+
+    // First open stamps {major:1,minor:0}; then corrupt it to a future major.
+    const backend1 = await createLevelDBStore(dir)
+    await backend1.append("doc-1", makeMetaRecord())
+    await backend1.close()
+
+    const raw = new ClassicLevel<string, Uint8Array>(dir, {
+      valueEncoding: "binary",
+    })
+    await raw.put(
+      "store-meta\x00format",
+      new TextEncoder().encode(JSON.stringify({ major: 99, minor: 0 })),
+    )
+    await raw.close()
+
+    // Open twice. Each must refuse *through the gate* with the major-mismatch
+    // reason. A refused open that leaked its handle would hold the LevelDB
+    // lock, so the second open would reject with a lock error — which has no
+    // `reason` and would fail this match.
+    const refusal = {
+      name: "StoreFormatVersionError",
+      reason: "incompatible-major",
+    }
+    await expect(createLevelDBStore(dir)).rejects.toMatchObject(refusal)
+    await expect(createLevelDBStore(dir)).rejects.toMatchObject(refusal)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // encode/decode round-trip — pure function unit tests
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -3,8 +3,9 @@
 // Implements the Store interface using classic-level.
 //
 // Key-space design (FoundationDB convention — \x00 null-byte separator):
-//   meta\x00{docId}                       → JSON-encoded StoreMeta (materialized index)
+//   doc-meta\x00{docId}                   → JSON-encoded StoreMeta (materialized index)
 //   record\x00{docId}\x00{seqNo}          → binary-encoded StoreRecord (unified stream)
+//   store-meta\x00{key}                   → store-global metadata (e.g. format version)
 //
 // The \x00 separator cannot appear in valid UTF-8 strings, so no docId
 // validation is needed — the key-space imposes zero constraints on callers.
@@ -15,9 +16,14 @@
 
 import {
   type DocId,
+  decideStoreFormat,
+  parseStoreFormat,
   resolveMetaFromBatch,
   SeqNoTracker,
+  STORE_META_FORMAT_KEY,
   type Store,
+  type StoreFormatVersion,
+  StoreFormatVersionError,
   type StoreMeta,
   type StoreRecord,
   validateAppend,
@@ -29,10 +35,25 @@ import { ClassicLevel } from "classic-level"
 // ---------------------------------------------------------------------------
 
 const SEP = "\x00"
-const META_PREFIX = `meta${SEP}`
+const DOC_META_PREFIX = `doc-meta${SEP}`
 const RECORD_PREFIX = `record${SEP}`
 const SEQ_PAD = 16
 
+// Store-global metadata namespace, keyed `store-meta\x00{key}`. It sorts
+// above `doc-meta\x00` ('d' < 's') and `record\x00` ('r' < 's'), so it is
+// outside every `doc-meta`/`record` iteration range and needs no filtering.
+// Do not relocate it into those ranges. The on-disk format version lives at
+// `store-meta\x00format`. This is read by a bootstrap reader on open, never
+// through the Store interface. Context: jj:uvssotsy.
+const STORE_META_PREFIX = `store-meta${SEP}`
+const STORE_FORMAT_KEY = `${STORE_META_PREFIX}${STORE_META_FORMAT_KEY}`
+
+// LevelDB owns its own on-disk format version (its binary envelope), gated on
+// open via `decideStoreFormat`. Distinct from the envelope's per-record bit-7
+// guard (`decodeStoreRecord`): bit-7 guards one record's decode; this marker
+// guards opening the store at all.
+const STORE_FORMAT_VERSION: StoreFormatVersion = { major: 1, minor: 0 }
+
 // ---------------------------------------------------------------------------
 // Binary envelope v2 — pure encode/decode for StoreRecord
 // ---------------------------------------------------------------------------
@@ -133,8 +154,8 @@ export function decodeStoreRecord(bytes: Uint8Array): StoreRecord {
 // Key helpers
 // ---------------------------------------------------------------------------
 
-function metaKey(docId: DocId): string {
-  return `${META_PREFIX}${docId}`
+function docMetaKey(docId: DocId): string {
+  return `${DOC_META_PREFIX}${docId}`
 }
 
 function recordPrefix(docId: DocId): string {
@@ -145,8 +166,8 @@ function recordKey(docId: DocId, seqNo: number): string {
   return `${recordPrefix(docId)}${String(seqNo).padStart(SEQ_PAD, "0")}`
 }
 
-function parseDocIdFromMetaKey(key: string): DocId {
-  return key.slice(META_PREFIX.length)
+function parseDocIdFromDocMetaKey(key: string): DocId {
+  return key.slice(DOC_META_PREFIX.length)
 }
 
 function parseSeqNoFromRecordKey(key: string, docId: DocId): number {
@@ -154,6 +175,56 @@ function parseSeqNoFromRecordKey(key: string, docId: DocId): number {
   return Number.parseInt(key.slice(prefix.length), 10)
 }
 
+// ---------------------------------------------------------------------------
+// Write planning — pure gather/plan/execute split (mirrors sql-core)
+// ---------------------------------------------------------------------------
+
+type BatchOp =
+  | { readonly type: "put"; readonly key: string; readonly value: Uint8Array }
+  | { readonly type: "del"; readonly key: string }
+
+// Pure StoreMeta JSON envelope, shared by the writers (append/replace) and the
+// reader (currentMeta). The store-format marker keeps its own JSON.stringify —
+// it serializes a StoreFormatVersion, not a StoreMeta.
+function encodeDocMeta(meta: StoreMeta): Uint8Array {
+  return encoder.encode(JSON.stringify(meta))
+}
+function decodeDocMeta(bytes: Uint8Array): StoreMeta {
+  return JSON.parse(decoder.decode(bytes)) as StoreMeta
+}
+
+/**
+ * Pure: validate the record against existing meta and return the LevelDB batch
+ * ops to write. Mirrors sql-core's `planAppend` (the gather/plan/execute split,
+ * jj:pzuytnvo). An entry record yields a single record `put`; a meta record
+ * adds the doc-meta index `put`, and the two commit together in one batch.
+ * `validateAppend` throws on an entry-before-meta violation — a pure,
+ * input-deterministic throw.
+ */
+function planAppend(
+  docId: DocId,
+  record: StoreRecord,
+  existingMeta: StoreMeta | null,
+  seq: number,
+): BatchOp[] {
+  const resolved = validateAppend(docId, record, existingMeta)
+  const ops: BatchOp[] = [
+    {
+      type: "put",
+      key: recordKey(docId, seq),
+      value: encodeStoreRecord(record),
+    },
+  ]
+  if (resolved !== null) {
+    ops.push({
+      type: "put",
+      key: docMetaKey(docId),
+      value: encodeDocMeta(resolved),
+    })
+  }
+  return ops
+}
+
 // ---------------------------------------------------------------------------
 // LevelDBStore
 // ---------------------------------------------------------------------------
@@ -162,10 +233,14 @@ export class LevelDBStore implements Store {
   readonly #db: ClassicLevel<string, Uint8Array>
   readonly #seqNos = new SeqNoTracker()
 
-  constructor(dbPath: string) {
-    this.#db = new ClassicLevel(dbPath, {
-      valueEncoding: "binary",
-    })
+  // Accepts a path (constructs a ClassicLevel) or an already-built handle. The
+  // handle form is the test seam for fault injection — production callers pass
+  // a path via `createLevelDBStore` / `open`. jj:pzuytnvo
+  constructor(dbPathOrDb: string | ClassicLevel<string, Uint8Array>) {
+    this.#db =
+      typeof dbPathOrDb === "string"
+        ? new ClassicLevel(dbPathOrDb, { valueEncoding: "binary" })
+        : dbPathOrDb
   }
 
   // -------------------------------------------------------------------------
@@ -174,8 +249,8 @@ export class LevelDBStore implements Store {
 
   async currentMeta(docId: DocId): Promise<StoreMeta | null> {
     try {
-      const raw = await this.#db.get(metaKey(docId))
-      return JSON.parse(decoder.decode(raw)) as StoreMeta
+      const raw = await this.#db.get(docMetaKey(docId))
+      return decodeDocMeta(raw)
     } catch (error: any) {
       if (error.code === "LEVEL_NOT_FOUND") return null
       throw error
@@ -184,15 +259,11 @@ export class LevelDBStore implements Store {
 
   async append(docId: DocId, record: StoreRecord): Promise<void> {
     const existingMeta = await this.currentMeta(docId)
-    const resolved = validateAppend(docId, record, existingMeta)
-
-    if (resolved !== null) {
-      await this.#db.put(
-        metaKey(docId),
-        encoder.encode(JSON.stringify(resolved)),
-      )
-    }
 
+    // SeqNoTracker.next advances the in-memory counter before the write lands.
+    // On a caught write failure the counter runs one ahead of disk → a benign
+    // sparse seqNo (records are range-scanned, not indexed contiguously); it
+    // self-heals on reopen via the cold-start seek. Context: jj:pzuytnvo.
     const seq = await this.#seqNos.next(docId, async () => {
       const prefix = recordPrefix(docId)
       for await (const key of this.#db.keys({
@@ -205,7 +276,11 @@ export class LevelDBStore implements Store {
       }
       return null
     })
-    await this.#db.put(recordKey(docId, seq), encodeStoreRecord(record))
+
+    // Single atomic batch: an entry append is a one-op batch (record only); a
+    // meta append commits the record and the doc-meta index together, so a
+    // crash never advances the index past its backing record. jj:pzuytnvo
+    await this.#db.batch(planAppend(docId, record, existingMeta, seq))
   }
 
   async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {
@@ -236,10 +311,10 @@ export class LevelDBStore implements Store {
     }
 
     // Atomic batch: delete all existing records, write replacements, upsert meta
-    const ops: Array<
-      | { type: "del"; key: string }
-      | { type: "put"; key: string; value: Uint8Array }
-    > = keysToDelete.map(key => ({ type: "del" as const, key }))
+    const ops: BatchOp[] = keysToDelete.map(key => ({
+      type: "del" as const,
+      key,
+    }))
 
     for (let i = 0; i < records.length; i++) {
       ops.push({
@@ -251,8 +326,8 @@ export class LevelDBStore implements Store {
 
     ops.push({
       type: "put",
-      key: metaKey(docId),
-      value: encoder.encode(JSON.stringify(resolved)),
+      key: docMetaKey(docId),
+      value: encodeDocMeta(resolved),
     })
 
     await this.#db.batch(ops)
@@ -265,7 +340,7 @@ export class LevelDBStore implements Store {
     const prefix = recordPrefix(docId)
 
     // Collect record keys to delete
-    const keysToDelete: string[] = [metaKey(docId)]
+    const keysToDelete: string[] = [docMetaKey(docId)]
     for await (const key of this.#db.keys({
       gte: prefix,
       lt: `${prefix}\xff`,
@@ -283,18 +358,86 @@ export class LevelDBStore implements Store {
 
   async *listDocIds(prefix?: string): AsyncIterable<DocId> {
     const rangePrefix =
-      prefix !== undefined ? `${META_PREFIX}${prefix}` : META_PREFIX
+      prefix !== undefined ? `${DOC_META_PREFIX}${prefix}` : DOC_META_PREFIX
     for await (const key of this.#db.keys({
       gte: rangePrefix,
       lt: `${rangePrefix}\xff`,
     })) {
-      yield parseDocIdFromMetaKey(key)
+      yield parseDocIdFromDocMetaKey(key)
     }
   }
 
   async close(): Promise<void> {
     await this.#db.close()
   }
+
+  // Bootstrap reader: consult the store-format marker before trusting any
+  // bytes. Stamps a brand-new store, accepts a compatible one, or throws.
+  // A `static open` reaches this private method so the gate stays internal.
+  async #assertFormat(): Promise<void> {
+    let parsed: StoreFormatVersion | "malformed" | null = null
+    try {
+      const raw = await this.#db.get(STORE_FORMAT_KEY)
+      parsed = parseStoreFormat(decoder.decode(raw))
+    } catch (error: any) {
+      if (error.code !== "LEVEL_NOT_FOUND") throw error
+      // absent → parsed stays null
+    }
+    if (parsed === "malformed") {
+      throw new StoreFormatVersionError({
+        reason: "malformed-version",
+        backend: "leveldb",
+        stored: null,
+        current: STORE_FORMAT_VERSION,
+      })
+    }
+
+    // Empty-store probe: does any doc-meta key exist?
+    let hasData = false
+    for await (const _key of this.#db.keys({
+      gte: DOC_META_PREFIX,
+      lt: `${DOC_META_PREFIX}\xff`,
+      limit: 1,
+    })) {
+      hasData = true
+    }
+
+    const decision = decideStoreFormat({
+      current: STORE_FORMAT_VERSION,
+      stored: parsed,
+      storeHasData: hasData,
+    })
+
+    if (decision.action === "refuse") {
+      throw new StoreFormatVersionError({
+        reason: decision.reason,
+        backend: "leveldb",
+        stored: parsed,
+        current: STORE_FORMAT_VERSION,
+      })
+    }
+    if (decision.action === "stamp") {
+      await this.#db.put(
+        STORE_FORMAT_KEY,
+        encoder.encode(JSON.stringify(decision.value)),
+      )
+    }
+  }
+
+  /** Open the store and run the store-format gate. Used by `createLevelDBStore`. */
+  static async open(
+    dbPathOrDb: string | ClassicLevel<string, Uint8Array>,
+  ): Promise<Store> {
+    const store = new LevelDBStore(dbPathOrDb)
+    try {
+      await store.#assertFormat()
+    } catch (error) {
+      // A refused store must not leak its file handle / lock.
+      await store.#db.close()
+      throw error
+    }
+    return store
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -304,7 +447,9 @@ export class LevelDBStore implements Store {
 /**
  * Create a LevelDB storage backend for server-side persistence.
  *
- * Returns a `Store` — pass directly to `Exchange({ stores: [...] })`.
+ * Async: it opens the database and runs the store-format gate (stamping a
+ * brand-new store, accepting a compatible one, or throwing
+ * `StoreFormatVersionError`). `await` it before passing to the `Exchange`.
  *
  * @param dbPath - Directory path where LevelDB stores its files
  *
@@ -313,10 +458,10 @@ export class LevelDBStore implements Store {
  * import { createLevelDBStore } from "@kyneta/leveldb-store"
  *
  * const exchange = new Exchange({
- *   stores: [createLevelDBStore("./data/exchange-db")],
+ *   stores: [await createLevelDBStore("./data/exchange-db")],
  * })
  * ```
  */
-export function createLevelDBStore(dbPath: string): Store {
-  return new LevelDBStore(dbPath)
+export function createLevelDBStore(dbPath: string): Promise<Store> {
+  return LevelDBStore.open(dbPath)
 }