@kyneta/leveldb-store 1.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,137 @@
+# @kyneta/leveldb-store
+
+Server-side persistent storage for `@kyneta/exchange`, backed by [LevelDB](https://github.com/google/leveldb) via [`classic-level`](https://github.com/Level/classic-level).
+
+Implements the `Store` interface — pass directly to `Exchange({ stores: [...] })` for automatic document persistence and hydration.
+
+## Install
+
+```sh
+pnpm add @kyneta/leveldb-store
+```
+
+## Quick Start
+
+```ts
+import { Exchange } from "@kyneta/exchange"
+import { createLevelDBStore } from "@kyneta/leveldb-store/server"
+
+const exchange = new Exchange({
+  identity: { peerId: "my-server", name: "server" },
+  stores: [createLevelDBStore("./data/exchange-db")],
+  transports: [networkTransport],
+})
+
+// Documents are automatically persisted on mutation and hydrated on restart.
+const doc = exchange.get("my-doc", TodoDoc)
+```
+
+That's it. The Exchange handles hydration (loading from storage on `get()` / `replicate()`) and persistence (saving incremental deltas via `onStateAdvanced`) — no manual save/load needed.
+
+## API
+
+### `createLevelDBStore(dbPath)`
+
+Factory function that returns a `Store`. The `dbPath` is the directory where LevelDB stores its files.
+
+```ts
+import { createLevelDBStore } from "@kyneta/leveldb-store/server"
+
+const store = 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.
+
+```ts
+import { LevelDBStore } from "@kyneta/leveldb-store/server"
+
+const store = new LevelDBStore("./data/exchange-db")
+
+// ... use with Exchange ...
+
+await store.close() // release file handles
+```
+
+### 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.
+
+```ts
+import { encodeStoreEntry, decodeStoreEntry } from "@kyneta/leveldb-store/server"
+
+const bytes = encodeStoreEntry(entry)  // StoreEntry → Uint8Array
+const entry = decodeStoreEntry(bytes)  // Uint8Array → StoreEntry
+```
+
+## Design
+
+### Key-Space
+
+Keys follow the [FoundationDB convention](https://apple.github.io/foundationdb/developer-guide.html#key-and-value-sizes) — null-byte (`\x00`) separated prefixes:
+
+| Key pattern | Value |
+|---|---|
+| `meta\x00{docId}` | JSON-encoded `DocMetadata` |
+| `entry\x00{docId}\x00{seqNo}` | Binary-encoded `StoreEntry` |
+
+The `\x00` separator cannot appear in valid UTF-8 strings, so no docId validation is needed — the key-space imposes zero constraints on callers. Documents with overlapping name prefixes (e.g. `doc` vs `doc-extra`) are fully isolated.
+
+### Sequence Numbers
+
+Each document maintains a monotonic sequence counter for entry ordering. SeqNos are zero-padded to 10 digits, supporting up to 10 billion entries per document.
+
+On reboot, the max seqNo for a document is lazily discovered via a single reverse-iterator seek on first `append` — no full scan needed.
+
+### Binary Envelope
+
+Entries are stored in a compact binary format (not JSON) for minimal overhead:
+
+```
+[1 byte flags] [4 bytes version length BE] [N bytes version UTF-8] [remaining: payload data]
+```
+
+Flags byte layout:
+- bit 0: kind (0 = entirety, 1 = since)
+- bit 1: encoding (0 = json, 1 = binary)
+- bit 2: data type (0 = string, 1 = Uint8Array)
+
+### 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.
+
+## Testing
+
+The package passes the full `Store` conformance suite from `@kyneta/exchange/testing`, plus LevelDB-specific tests for close/reopen persistence and binary codec edge cases.
+
+```sh
+pnpm test
+```
+
+To use the conformance suite for your own `Store` implementation:
+
+```ts
+import { describeStore } from "@kyneta/exchange/testing"
+
+describeStore(
+  "MyStore",
+  () => new MyStore(),
+  async (store) => { /* cleanup */ },
+)
+```
+
+## Peer Dependencies
+
+```json
+{
+  "peerDependencies": {
+    "@kyneta/exchange": "^1.1.0",
+    "@kyneta/schema": "^1.1.0"
+  }
+}
+```
+
+## License
+
+MIT

package/dist/server.d.ts

@@ -0,0 +1,37 @@
+import { Store, StoreEntry } from '@kyneta/exchange/src/store/store.js';
+import { DocId } from '@kyneta/exchange/src/types.js';
+import { DocMetadata } from '@kyneta/schema';
+
+declare function encodeStoreEntry(entry: StoreEntry): Uint8Array;
+declare function decodeStoreEntry(bytes: Uint8Array): StoreEntry;
+declare class LevelDBStore implements Store {
+    #private;
+    constructor(dbPath: string);
+    lookup(docId: DocId): Promise<DocMetadata | null>;
+    ensureDoc(docId: DocId, metadata: DocMetadata): Promise<void>;
+    append(docId: DocId, entry: StoreEntry): Promise<void>;
+    loadAll(docId: DocId): AsyncIterable<StoreEntry>;
+    replace(docId: DocId, entry: StoreEntry): Promise<void>;
+    delete(docId: DocId): Promise<void>;
+    listDocIds(): AsyncIterable<DocId>;
+    close(): Promise<void>;
+}
+/**
+ * Create a LevelDB storage backend for server-side persistence.
+ *
+ * Returns a `Store` — pass directly to `Exchange({ stores: [...] })`.
+ *
+ * @param dbPath - Directory path where LevelDB stores its files
+ *
+ * @example
+ * ```typescript
+ * import { createLevelDBStore } from "@kyneta/leveldb-store/server"
+ *
+ * const exchange = new Exchange({
+ *   stores: [createLevelDBStore("./data/exchange-db")],
+ * })
+ * ```
+ */
+declare function createLevelDBStore(dbPath: string): Store;
+
+export { LevelDBStore, createLevelDBStore, decodeStoreEntry, encodeStoreEntry };

package/dist/server.js

@@ -0,0 +1,186 @@
+// src/server.ts
+import { ClassicLevel } from "classic-level";
+var SEP = "\0";
+var META_PREFIX = `meta${SEP}`;
+var ENTRY_PREFIX = `entry${SEP}`;
+var SEQ_PAD = 10;
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function encodeStoreEntry(entry) {
+  const { payload, version } = entry;
+  let flags = 0;
+  if (payload.kind === "since") flags |= 1;
+  if (payload.encoding === "binary") flags |= 2;
+  const isDataBinary = payload.data instanceof Uint8Array;
+  if (isDataBinary) flags |= 4;
+  const versionBytes = encoder.encode(version);
+  const dataBytes = isDataBinary ? payload.data : encoder.encode(payload.data);
+  const buf = new Uint8Array(1 + 4 + versionBytes.length + dataBytes.length);
+  const view = new DataView(buf.buffer);
+  buf[0] = flags;
+  view.setUint32(1, versionBytes.length, false);
+  buf.set(versionBytes, 5);
+  buf.set(dataBytes, 5 + versionBytes.length);
+  return buf;
+}
+function decodeStoreEntry(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const flags = bytes[0];
+  const kind = (flags & 1) !== 0 ? "since" : "entirety";
+  const encoding = (flags & 2) !== 0 ? "binary" : "json";
+  const isDataBinary = (flags & 4) !== 0;
+  const versionLen = view.getUint32(1, false);
+  const version = decoder.decode(bytes.subarray(5, 5 + versionLen));
+  const dataStart = 5 + versionLen;
+  const rawData = bytes.subarray(dataStart);
+  const data = isDataBinary ? new Uint8Array(rawData) : decoder.decode(rawData);
+  return {
+    payload: { kind, encoding, data },
+    version
+  };
+}
+function metaKey(docId) {
+  return `${META_PREFIX}${docId}`;
+}
+function entryPrefix(docId) {
+  return `${ENTRY_PREFIX}${docId}${SEP}`;
+}
+function entryKey(docId, seqNo) {
+  return `${entryPrefix(docId)}${String(seqNo).padStart(SEQ_PAD, "0")}`;
+}
+function parseDocIdFromMetaKey(key) {
+  return key.slice(META_PREFIX.length);
+}
+function parseSeqNoFromEntryKey(key, docId) {
+  const prefix = entryPrefix(docId);
+  return Number.parseInt(key.slice(prefix.length), 10);
+}
+var LevelDBStore = class {
+  #db;
+  #seqNos = /* @__PURE__ */ new Map();
+  constructor(dbPath) {
+    this.#db = new ClassicLevel(dbPath, {
+      valueEncoding: "binary"
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Private — seqNo management
+  // -------------------------------------------------------------------------
+  /**
+   * Get the next seqNo for a doc. On first call after reboot, discovers
+   * the max existing seqNo via a single reverse-iterator seek.
+   */
+  async #nextSeqNo(docId) {
+    const cached = this.#seqNos.get(docId);
+    if (cached !== void 0) {
+      const next2 = cached + 1;
+      this.#seqNos.set(docId, next2);
+      return next2;
+    }
+    const prefix = entryPrefix(docId);
+    let maxSeq = -1;
+    for await (const key of this.#db.keys({
+      gte: prefix,
+      lt: `${prefix}\xFF`,
+      reverse: true,
+      limit: 1
+    })) {
+      maxSeq = parseSeqNoFromEntryKey(key, docId);
+    }
+    const next = maxSeq + 1;
+    this.#seqNos.set(docId, next);
+    return next;
+  }
+  // -------------------------------------------------------------------------
+  // Store interface
+  // -------------------------------------------------------------------------
+  async lookup(docId) {
+    try {
+      const raw = await this.#db.get(metaKey(docId));
+      return JSON.parse(decoder.decode(raw));
+    } catch (error) {
+      if (error.code === "LEVEL_NOT_FOUND") return null;
+      throw error;
+    }
+  }
+  async ensureDoc(docId, metadata) {
+    try {
+      await this.#db.get(metaKey(docId));
+    } catch (error) {
+      if (error.code === "LEVEL_NOT_FOUND") {
+        await this.#db.put(
+          metaKey(docId),
+          encoder.encode(JSON.stringify(metadata))
+        );
+        return;
+      }
+      throw error;
+    }
+  }
+  async append(docId, entry) {
+    const seq = await this.#nextSeqNo(docId);
+    await this.#db.put(entryKey(docId, seq), encodeStoreEntry(entry));
+  }
+  async *loadAll(docId) {
+    const prefix = entryPrefix(docId);
+    for await (const value of this.#db.values({
+      gte: prefix,
+      lt: `${prefix}\xFF`
+    })) {
+      yield decodeStoreEntry(value);
+    }
+  }
+  async replace(docId, entry) {
+    const prefix = entryPrefix(docId);
+    const keysToDelete = [];
+    for await (const key of this.#db.keys({
+      gte: prefix,
+      lt: `${prefix}\xFF`
+    })) {
+      keysToDelete.push(key);
+    }
+    const ops = keysToDelete.map((key) => ({ type: "del", key }));
+    ops.push({
+      type: "put",
+      key: entryKey(docId, 0),
+      value: encodeStoreEntry(entry)
+    });
+    await this.#db.batch(ops);
+    this.#seqNos.set(docId, 0);
+  }
+  async delete(docId) {
+    const prefix = entryPrefix(docId);
+    const keysToDelete = [metaKey(docId)];
+    for await (const key of this.#db.keys({
+      gte: prefix,
+      lt: `${prefix}\xFF`
+    })) {
+      keysToDelete.push(key);
+    }
+    await this.#db.batch(
+      keysToDelete.map((key) => ({ type: "del", key }))
+    );
+    this.#seqNos.delete(docId);
+  }
+  async *listDocIds() {
+    for await (const key of this.#db.keys({
+      gte: META_PREFIX,
+      lt: `${META_PREFIX}\xFF`
+    })) {
+      yield parseDocIdFromMetaKey(key);
+    }
+  }
+  async close() {
+    await this.#db.close();
+  }
+};
+function createLevelDBStore(dbPath) {
+  return new LevelDBStore(dbPath);
+}
+export {
+  LevelDBStore,
+  createLevelDBStore,
+  decodeStoreEntry,
+  encodeStoreEntry
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.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 DocMetadata\n//   entry\\x00{docId}\\x00{seqNo}       → binary-encoded StoreEntry\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 10-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 type { Store, StoreEntry } from \"@kyneta/exchange/src/store/store.js\"\nimport type { DocId } from \"@kyneta/exchange/src/types.js\"\nimport type { DocMetadata } from \"@kyneta/schema\"\nimport { ClassicLevel } from \"classic-level\"\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\nconst SEP = \"\\x00\"\nconst META_PREFIX = `meta${SEP}`\nconst ENTRY_PREFIX = `entry${SEP}`\nconst SEQ_PAD = 10\n\n// ---------------------------------------------------------------------------\n// Binary envelope — pure encode/decode for StoreEntry\n// ---------------------------------------------------------------------------\n\n// Flags byte layout:\n//   bit 0: kind        (0 = entirety, 1 = since)\n//   bit 1: encoding    (0 = json, 1 = binary)\n//   bit 2: data type   (0 = string, 1 = Uint8Array)\n//\n// Layout: [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 encodeStoreEntry(entry: StoreEntry): Uint8Array {\n  const { payload, version } = entry\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 decodeStoreEntry(bytes: Uint8Array): StoreEntry {\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)\n\n  const flags = bytes[0]!\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    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 entryPrefix(docId: DocId): string {\n  return `${ENTRY_PREFIX}${docId}${SEP}`\n}\n\nfunction entryKey(docId: DocId, seqNo: number): string {\n  return `${entryPrefix(docId)}${String(seqNo).padStart(SEQ_PAD, \"0\")}`\n}\n\nfunction parseDocIdFromMetaKey(key: string): DocId {\n  return key.slice(META_PREFIX.length)\n}\n\nfunction parseSeqNoFromEntryKey(key: string, docId: DocId): number {\n  const prefix = entryPrefix(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: Map<DocId, number> = new Map()\n\n  constructor(dbPath: string) {\n    this.#db = new ClassicLevel(dbPath, {\n      valueEncoding: \"binary\",\n    })\n  }\n\n  // -------------------------------------------------------------------------\n  // Private — seqNo management\n  // -------------------------------------------------------------------------\n\n  /**\n   * Get the next seqNo for a doc. On first call after reboot, discovers\n   * the max existing seqNo via a single reverse-iterator seek.\n   */\n  async #nextSeqNo(docId: DocId): Promise<number> {\n    const cached = this.#seqNos.get(docId)\n    if (cached !== undefined) {\n      const next = cached + 1\n      this.#seqNos.set(docId, next)\n      return next\n    }\n\n    // Lazy discovery: reverse iterate to find the highest existing seqNo\n    const prefix = entryPrefix(docId)\n    let maxSeq = -1\n    for await (const key of this.#db.keys({\n      gte: prefix,\n      lt: `${prefix}\\xff`,\n      reverse: true,\n      limit: 1,\n    })) {\n      maxSeq = parseSeqNoFromEntryKey(key, docId)\n    }\n\n    const next = maxSeq + 1\n    this.#seqNos.set(docId, next)\n    return next\n  }\n\n  // -------------------------------------------------------------------------\n  // Store interface\n  // -------------------------------------------------------------------------\n\n  async lookup(docId: DocId): Promise<DocMetadata | null> {\n    try {\n      const raw = await this.#db.get(metaKey(docId))\n      return JSON.parse(decoder.decode(raw)) as DocMetadata\n    } catch (error: any) {\n      if (error.code === \"LEVEL_NOT_FOUND\") return null\n      throw error\n    }\n  }\n\n  async ensureDoc(docId: DocId, metadata: DocMetadata): Promise<void> {\n    try {\n      await this.#db.get(metaKey(docId))\n      // Already exists — no-op (first call wins)\n    } catch (error: any) {\n      if (error.code === \"LEVEL_NOT_FOUND\") {\n        await this.#db.put(\n          metaKey(docId),\n          encoder.encode(JSON.stringify(metadata)),\n        )\n        return\n      }\n      throw error\n    }\n  }\n\n  async append(docId: DocId, entry: StoreEntry): Promise<void> {\n    const seq = await this.#nextSeqNo(docId)\n    await this.#db.put(entryKey(docId, seq), encodeStoreEntry(entry))\n  }\n\n  async *loadAll(docId: DocId): AsyncIterable<StoreEntry> {\n    const prefix = entryPrefix(docId)\n    for await (const value of this.#db.values({\n      gte: prefix,\n      lt: `${prefix}\\xff`,\n    })) {\n      yield decodeStoreEntry(value)\n    }\n  }\n\n  async replace(docId: DocId, entry: StoreEntry): Promise<void> {\n    const prefix = entryPrefix(docId)\n\n    // Collect 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 entries + write the single replacement\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    ops.push({\n      type: \"put\",\n      key: entryKey(docId, 0),\n      value: encodeStoreEntry(entry),\n    })\n    await this.#db.batch(ops)\n\n    // Reset seqNo counter\n    this.#seqNos.set(docId, 0)\n  }\n\n  async delete(docId: DocId): Promise<void> {\n    const prefix = entryPrefix(docId)\n\n    // Collect entry 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.delete(docId)\n  }\n\n  async *listDocIds(): AsyncIterable<DocId> {\n    for await (const key of this.#db.keys({\n      gte: META_PREFIX,\n      lt: `${META_PREFIX}\\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/server\"\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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","names":["next"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kyneta/leveldb-store",
+  "version": "1.1.0",
+  "description": "LevelDB storage backend for @kyneta/exchange — server-side persistent storage",
+  "author": "Duane Johnson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halecraft/kyneta",
+    "directory": "packages/exchange/storage-adapters/leveldb"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./src/*": "./src/*"
+  },
+  "peerDependencies": {
+    "@kyneta/exchange": "^1.1.0",
+    "@kyneta/schema": "^1.1.0"
+  },
+  "dependencies": {
+    "classic-level": "^1.4.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.17",
+    "@kyneta/exchange": "^1.1.0",
+    "@kyneta/schema": "^1.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "verify logic",
+    "verify": "verify"
+  }
+}

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

@@ -0,0 +1,207 @@
+// leveldb-storage — conformance + LevelDB-specific tests.
+//
+// Runs the reusable Store conformance suite against
+// LevelDBStore, plus LevelDB-specific tests for
+// close+reopen persistence and encode/decode edge cases.
+
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import type { StoreEntry } from "@kyneta/exchange/src/store/store.js"
+import {
+  collectAll,
+  describeStore,
+  makeEntry,
+  plainMetadata,
+} from "@kyneta/exchange/src/testing/store-conformance.js"
+import { afterAll, describe, expect, it } from "vitest"
+import { decodeStoreEntry, encodeStoreEntry, LevelDBStore } from "../server.js"
+
+// ---------------------------------------------------------------------------
+// Temp directory management
+// ---------------------------------------------------------------------------
+
+const tmpDirs: string[] = []
+
+function makeTmpDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "kyneta-leveldb-test-"))
+  tmpDirs.push(dir)
+  return dir
+}
+
+afterAll(() => {
+  for (const dir of tmpDirs) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true })
+    } catch {
+      // best-effort cleanup
+    }
+  }
+})
+
+// ---------------------------------------------------------------------------
+// Conformance suite — validates the full Store contract
+// ---------------------------------------------------------------------------
+
+describeStore(
+  "LevelDBStore",
+  () => new LevelDBStore(makeTmpDir()),
+  async backend => {
+    if (backend.close) await backend.close()
+  },
+)
+
+// ---------------------------------------------------------------------------
+// LevelDB-specific tests
+// ---------------------------------------------------------------------------
+
+describe("LevelDBStore — close + reopen", () => {
+  it("data persists across close and reopen on the same path", async () => {
+    const dir = makeTmpDir()
+
+    // Phase 1: write data then close
+    const backend1 = new LevelDBStore(dir)
+    await backend1.ensureDoc("doc-1", plainMetadata)
+    await backend1.append("doc-1", makeEntry("entirety", "v1"))
+    await backend1.append("doc-1", makeEntry("since", "v2"))
+    await backend1.close()
+
+    // Phase 2: reopen and verify
+    const backend2 = new LevelDBStore(dir)
+    expect(await backend2.lookup("doc-1")).toEqual(plainMetadata)
+
+    const entries = await collectAll(backend2.loadAll("doc-1"))
+    expect(entries).toHaveLength(2)
+    expect(entries[0]!.version).toBe("v1")
+    expect(entries[1]!.version).toBe("v2")
+    await backend2.close()
+  })
+
+  it("append after reopen continues with correct seqNo ordering", async () => {
+    const dir = makeTmpDir()
+
+    const backend1 = new LevelDBStore(dir)
+    await backend1.ensureDoc("doc-1", plainMetadata)
+    await backend1.append("doc-1", makeEntry("entirety", "v1"))
+    await backend1.append("doc-1", makeEntry("since", "v2"))
+    await backend1.close()
+
+    // Reopen and append more
+    const backend2 = new LevelDBStore(dir)
+    await backend2.append("doc-1", makeEntry("since", "v3"))
+
+    const entries = await collectAll(backend2.loadAll("doc-1"))
+    expect(entries).toHaveLength(3)
+    expect(entries[0]!.version).toBe("v1")
+    expect(entries[1]!.version).toBe("v2")
+    expect(entries[2]!.version).toBe("v3")
+    await backend2.close()
+  })
+
+  it("replace then reopen preserves the single entry", async () => {
+    const dir = makeTmpDir()
+
+    const backend1 = new LevelDBStore(dir)
+    await backend1.ensureDoc("doc-1", plainMetadata)
+    await backend1.append("doc-1", makeEntry("since", "v1"))
+    await backend1.append("doc-1", makeEntry("since", "v2"))
+    await backend1.replace("doc-1", makeEntry("entirety", "v3"))
+    await backend1.close()
+
+    const backend2 = new LevelDBStore(dir)
+    const entries = await collectAll(backend2.loadAll("doc-1"))
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.version).toBe("v3")
+    await backend2.close()
+  })
+
+  it("listDocIds works after reopen", async () => {
+    const dir = makeTmpDir()
+
+    const backend1 = new LevelDBStore(dir)
+    await backend1.ensureDoc("alpha", plainMetadata)
+    await backend1.ensureDoc("beta", plainMetadata)
+    await backend1.ensureDoc("gamma", plainMetadata)
+    await backend1.close()
+
+    const backend2 = new LevelDBStore(dir)
+    const docIds = await collectAll(backend2.listDocIds())
+    expect(docIds.sort()).toEqual(["alpha", "beta", "gamma"])
+    await backend2.close()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// encode/decode round-trip — pure function unit tests
+// ---------------------------------------------------------------------------
+
+describe("encodeStoreEntry / decodeStoreEntry", () => {
+  it("round-trips a JSON string payload (entirety)", () => {
+    const entry: StoreEntry = {
+      payload: {
+        kind: "entirety",
+        encoding: "json",
+        data: '{"hello":"world"}',
+      },
+      version: "42",
+    }
+    const decoded = decodeStoreEntry(encodeStoreEntry(entry))
+    expect(decoded).toEqual(entry)
+  })
+
+  it("round-trips a binary Uint8Array payload (since)", () => {
+    const bytes = new Uint8Array([0x00, 0x01, 0x02, 0xff, 0xfe])
+    const entry: StoreEntry = {
+      payload: { kind: "since", encoding: "binary", data: bytes },
+      version: "v7",
+    }
+    const decoded = decodeStoreEntry(encodeStoreEntry(entry))
+    expect(decoded.version).toBe("v7")
+    expect(decoded.payload.kind).toBe("since")
+    expect(decoded.payload.encoding).toBe("binary")
+    expect(decoded.payload.data).toBeInstanceOf(Uint8Array)
+    expect(decoded.payload.data).toEqual(bytes)
+  })
+
+  it("handles empty string data", () => {
+    const entry: StoreEntry = {
+      payload: { kind: "entirety", encoding: "json", data: "" },
+      version: "v0",
+    }
+    const decoded = decodeStoreEntry(encodeStoreEntry(entry))
+    expect(decoded).toEqual(entry)
+  })
+
+  it("handles empty Uint8Array data", () => {
+    const entry: StoreEntry = {
+      payload: { kind: "since", encoding: "binary", data: new Uint8Array(0) },
+      version: "v0",
+    }
+    const decoded = decodeStoreEntry(encodeStoreEntry(entry))
+    expect(decoded.payload.data).toBeInstanceOf(Uint8Array)
+    expect((decoded.payload.data as Uint8Array).length).toBe(0)
+  })
+
+  it("handles empty version string", () => {
+    const entry: StoreEntry = {
+      payload: { kind: "entirety", encoding: "json", data: "{}" },
+      version: "",
+    }
+    const decoded = decodeStoreEntry(encodeStoreEntry(entry))
+    expect(decoded.version).toBe("")
+    expect(decoded.payload.data).toBe("{}")
+  })
+
+  it("handles large binary payload", () => {
+    const largeData = new Uint8Array(100_000)
+    for (let i = 0; i < largeData.length; i++) {
+      largeData[i] = i % 256
+    }
+    const entry: StoreEntry = {
+      payload: { kind: "entirety", encoding: "binary", data: largeData },
+      version: "large-v1",
+    }
+    const decoded = decodeStoreEntry(encodeStoreEntry(entry))
+    expect(decoded.payload.data).toEqual(largeData)
+  })
+})

package/src/server.ts

@@ -0,0 +1,295 @@
+// server — LevelDB storage backend for @kyneta/exchange.
+//
+// Implements the Store interface using classic-level.
+//
+// Key-space design (FoundationDB convention — \x00 null-byte separator):
+//   meta\x00{docId}                    → JSON-encoded DocMetadata
+//   entry\x00{docId}\x00{seqNo}       → binary-encoded StoreEntry
+//
+// The \x00 separator cannot appear in valid UTF-8 strings, so no docId
+// validation is needed — the key-space imposes zero constraints on callers.
+//
+// SeqNo is a zero-padded 10-digit monotonic counter per doc, tracked in
+// memory. On reboot, the max seqNo for a doc is lazily discovered via a
+// single reverse-iterator seek on first append.
+
+import type { Store, StoreEntry } from "@kyneta/exchange/src/store/store.js"
+import type { DocId } from "@kyneta/exchange/src/types.js"
+import type { DocMetadata } from "@kyneta/schema"
+import { ClassicLevel } from "classic-level"
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const SEP = "\x00"
+const META_PREFIX = `meta${SEP}`
+const ENTRY_PREFIX = `entry${SEP}`
+const SEQ_PAD = 10
+
+// ---------------------------------------------------------------------------
+// Binary envelope — pure encode/decode for StoreEntry
+// ---------------------------------------------------------------------------
+
+// Flags byte layout:
+//   bit 0: kind        (0 = entirety, 1 = since)
+//   bit 1: encoding    (0 = json, 1 = binary)
+//   bit 2: data type   (0 = string, 1 = Uint8Array)
+//
+// Layout: [1 byte flags] [4 bytes version length BE] [N bytes version UTF-8] [remaining: payload data]
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+export function encodeStoreEntry(entry: StoreEntry): Uint8Array {
+  const { payload, version } = entry
+
+  let flags = 0
+  if (payload.kind === "since") flags |= 0x01
+  if (payload.encoding === "binary") flags |= 0x02
+
+  const isDataBinary = payload.data instanceof Uint8Array
+  if (isDataBinary) flags |= 0x04
+
+  const versionBytes = encoder.encode(version)
+  const dataBytes = isDataBinary
+    ? (payload.data as Uint8Array)
+    : encoder.encode(payload.data as string)
+
+  const buf = new Uint8Array(1 + 4 + versionBytes.length + dataBytes.length)
+  const view = new DataView(buf.buffer)
+
+  buf[0] = flags
+  view.setUint32(1, versionBytes.length, false) // big-endian
+  buf.set(versionBytes, 5)
+  buf.set(dataBytes, 5 + versionBytes.length)
+
+  return buf
+}
+
+export function decodeStoreEntry(bytes: Uint8Array): StoreEntry {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+
+  const flags = bytes[0]!
+  const kind = (flags & 0x01) !== 0 ? "since" : "entirety"
+  const encoding = (flags & 0x02) !== 0 ? "binary" : "json"
+  const isDataBinary = (flags & 0x04) !== 0
+
+  const versionLen = view.getUint32(1, false)
+  const version = decoder.decode(bytes.subarray(5, 5 + versionLen))
+
+  const dataStart = 5 + versionLen
+  const rawData = bytes.subarray(dataStart)
+
+  const data: string | Uint8Array = isDataBinary
+    ? new Uint8Array(rawData)
+    : decoder.decode(rawData)
+
+  return {
+    payload: { kind, encoding, data },
+    version,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Key helpers
+// ---------------------------------------------------------------------------
+
+function metaKey(docId: DocId): string {
+  return `${META_PREFIX}${docId}`
+}
+
+function entryPrefix(docId: DocId): string {
+  return `${ENTRY_PREFIX}${docId}${SEP}`
+}
+
+function entryKey(docId: DocId, seqNo: number): string {
+  return `${entryPrefix(docId)}${String(seqNo).padStart(SEQ_PAD, "0")}`
+}
+
+function parseDocIdFromMetaKey(key: string): DocId {
+  return key.slice(META_PREFIX.length)
+}
+
+function parseSeqNoFromEntryKey(key: string, docId: DocId): number {
+  const prefix = entryPrefix(docId)
+  return Number.parseInt(key.slice(prefix.length), 10)
+}
+
+// ---------------------------------------------------------------------------
+// LevelDBStore
+// ---------------------------------------------------------------------------
+
+export class LevelDBStore implements Store {
+  readonly #db: ClassicLevel<string, Uint8Array>
+  readonly #seqNos: Map<DocId, number> = new Map()
+
+  constructor(dbPath: string) {
+    this.#db = new ClassicLevel(dbPath, {
+      valueEncoding: "binary",
+    })
+  }
+
+  // -------------------------------------------------------------------------
+  // Private — seqNo management
+  // -------------------------------------------------------------------------
+
+  /**
+   * Get the next seqNo for a doc. On first call after reboot, discovers
+   * the max existing seqNo via a single reverse-iterator seek.
+   */
+  async #nextSeqNo(docId: DocId): Promise<number> {
+    const cached = this.#seqNos.get(docId)
+    if (cached !== undefined) {
+      const next = cached + 1
+      this.#seqNos.set(docId, next)
+      return next
+    }
+
+    // Lazy discovery: reverse iterate to find the highest existing seqNo
+    const prefix = entryPrefix(docId)
+    let maxSeq = -1
+    for await (const key of this.#db.keys({
+      gte: prefix,
+      lt: `${prefix}\xff`,
+      reverse: true,
+      limit: 1,
+    })) {
+      maxSeq = parseSeqNoFromEntryKey(key, docId)
+    }
+
+    const next = maxSeq + 1
+    this.#seqNos.set(docId, next)
+    return next
+  }
+
+  // -------------------------------------------------------------------------
+  // Store interface
+  // -------------------------------------------------------------------------
+
+  async lookup(docId: DocId): Promise<DocMetadata | null> {
+    try {
+      const raw = await this.#db.get(metaKey(docId))
+      return JSON.parse(decoder.decode(raw)) as DocMetadata
+    } catch (error: any) {
+      if (error.code === "LEVEL_NOT_FOUND") return null
+      throw error
+    }
+  }
+
+  async ensureDoc(docId: DocId, metadata: DocMetadata): Promise<void> {
+    try {
+      await this.#db.get(metaKey(docId))
+      // Already exists — no-op (first call wins)
+    } catch (error: any) {
+      if (error.code === "LEVEL_NOT_FOUND") {
+        await this.#db.put(
+          metaKey(docId),
+          encoder.encode(JSON.stringify(metadata)),
+        )
+        return
+      }
+      throw error
+    }
+  }
+
+  async append(docId: DocId, entry: StoreEntry): Promise<void> {
+    const seq = await this.#nextSeqNo(docId)
+    await this.#db.put(entryKey(docId, seq), encodeStoreEntry(entry))
+  }
+
+  async *loadAll(docId: DocId): AsyncIterable<StoreEntry> {
+    const prefix = entryPrefix(docId)
+    for await (const value of this.#db.values({
+      gte: prefix,
+      lt: `${prefix}\xff`,
+    })) {
+      yield decodeStoreEntry(value)
+    }
+  }
+
+  async replace(docId: DocId, entry: StoreEntry): Promise<void> {
+    const prefix = entryPrefix(docId)
+
+    // Collect keys to delete
+    const keysToDelete: string[] = []
+    for await (const key of this.#db.keys({
+      gte: prefix,
+      lt: `${prefix}\xff`,
+    })) {
+      keysToDelete.push(key)
+    }
+
+    // Atomic batch: delete all existing entries + write the single replacement
+    const ops: Array<
+      | { type: "del"; key: string }
+      | { type: "put"; key: string; value: Uint8Array }
+    > = keysToDelete.map(key => ({ type: "del" as const, key }))
+    ops.push({
+      type: "put",
+      key: entryKey(docId, 0),
+      value: encodeStoreEntry(entry),
+    })
+    await this.#db.batch(ops)
+
+    // Reset seqNo counter
+    this.#seqNos.set(docId, 0)
+  }
+
+  async delete(docId: DocId): Promise<void> {
+    const prefix = entryPrefix(docId)
+
+    // Collect entry keys to delete
+    const keysToDelete: string[] = [metaKey(docId)]
+    for await (const key of this.#db.keys({
+      gte: prefix,
+      lt: `${prefix}\xff`,
+    })) {
+      keysToDelete.push(key)
+    }
+
+    await this.#db.batch(
+      keysToDelete.map(key => ({ type: "del" as const, key })),
+    )
+
+    // Remove from in-memory seqNo tracker
+    this.#seqNos.delete(docId)
+  }
+
+  async *listDocIds(): AsyncIterable<DocId> {
+    for await (const key of this.#db.keys({
+      gte: META_PREFIX,
+      lt: `${META_PREFIX}\xff`,
+    })) {
+      yield parseDocIdFromMetaKey(key)
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.#db.close()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a LevelDB storage backend for server-side persistence.
+ *
+ * Returns a `Store` — pass directly to `Exchange({ stores: [...] })`.
+ *
+ * @param dbPath - Directory path where LevelDB stores its files
+ *
+ * @example
+ * ```typescript
+ * import { createLevelDBStore } from "@kyneta/leveldb-store/server"
+ *
+ * const exchange = new Exchange({
+ *   stores: [createLevelDBStore("./data/exchange-db")],
+ * })
+ * ```
+ */
+export function createLevelDBStore(dbPath: string): Store {
+  return new LevelDBStore(dbPath)
+}