@loro-dev/flock-sqlite 0.1.0

package/src/index.ts

@@ -0,0 +1,1040 @@
+import { openStore, type UniStoreConnection } from "@loro-dev/unisqlite";
+import { computeDigest, type DigestRow } from "./digest";
+import {
+  compareBytes,
+  decodeKeyParts,
+  encodeKeyParts,
+  keyToString,
+  prefixUpperBound,
+} from "./key-encoding";
+import type {
+  EntryClock,
+  Event,
+  EventBatch,
+  ExportBundle,
+  ExportHooks,
+  ExportOptions,
+  ExportPayload,
+  ExportRecord,
+  ImportDecision,
+  ImportHooks,
+  ImportOptions,
+  ImportReport,
+  KeyPart,
+  MetadataMap,
+  PutHooks,
+  PutWithMetaOptions,
+  EventListener,
+  ScanBound,
+  ScanOptions,
+  ScanRow,
+  Value,
+  VersionVector,
+  VersionVectorEntry,
+} from "./types";
+
+type ClockRow = {
+  physical: number;
+  logical: number;
+  peer: string;
+};
+
+type KvRow = {
+  key: Uint8Array;
+  data: string | null;
+  metadata: string | null;
+  physical: number;
+  logical: number;
+  peer: string;
+};
+
+type ExportQueryRow = KvRow;
+
+type PutOperation = {
+  key: KeyPart[];
+  payload: ExportPayload;
+  now?: number;
+  skipSameValue: boolean;
+  source: string;
+  clock?: EntryClock;
+  eventSink?: Array<{ key: KeyPart[]; payload: ExportPayload; source: string }>;
+};
+
+const textEncoder = new TextEncoder();
+const structuredCloneFn: (<T>(value: T) => T) | undefined =
+  (globalThis as typeof globalThis & { structuredClone?: <T>(value: T) => T }).structuredClone;
+
+function utf8ByteLength(value: string): number {
+  return textEncoder.encode(value).length;
+}
+
+function isValidPeerId(peerId: unknown): peerId is string {
+  return typeof peerId === "string" && utf8ByteLength(peerId) < 128;
+}
+
+function createRandomPeerId(): string {
+  const id = new Uint8Array(32);
+  const cryptoAny = typeof crypto !== "undefined" ? (crypto as any) : undefined;
+  if (cryptoAny?.getRandomValues) {
+    cryptoAny.getRandomValues(id);
+  } else if (cryptoAny?.randomBytes) {
+    const buf: Uint8Array = cryptoAny.randomBytes(32);
+    id.set(buf);
+  } else {
+    for (let i = 0; i < 32; i += 1) {
+      id[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(id, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function normalizePeerId(peerId?: string): string {
+  if (peerId === undefined) {
+    return createRandomPeerId();
+  }
+  if (!isValidPeerId(peerId)) {
+    throw new TypeError("peerId must be a UTF-8 string under 128 bytes");
+  }
+  return peerId;
+}
+
+function cloneJson<T>(value: T): T {
+  if (value === undefined) {
+    return value;
+  }
+  if (structuredCloneFn) {
+    return structuredCloneFn(value);
+  }
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function cloneMetadata(metadata: unknown): MetadataMap | undefined {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return undefined;
+  }
+  return cloneJson(metadata as MetadataMap);
+}
+
+function assignPayload(target: ExportPayload, source?: ExportPayload | void): void {
+  if (!source || typeof source !== "object") {
+    return;
+  }
+  if ("data" in source) {
+    const value = source.data;
+    target.data = value === undefined ? undefined : cloneJson(value);
+  }
+  if ("metadata" in source) {
+    target.metadata = cloneMetadata(source.metadata);
+  }
+}
+
+function clonePayload(payload: ExportPayload | undefined): ExportPayload {
+  const result: ExportPayload = {};
+  assignPayload(result, payload);
+  return result;
+}
+
+function mergePayload(base: ExportPayload, update?: ExportPayload | void): ExportPayload {
+  const result = clonePayload(base);
+  assignPayload(result, update);
+  return result;
+}
+
+function buildRecord(clock: EntryClock, payload: ExportPayload): ExportRecord {
+  const record: ExportRecord = {
+    c: formatClock(clock),
+  };
+  if (payload.data !== undefined) {
+    record.d = cloneJson(payload.data);
+  }
+  const metadata = cloneMetadata(payload.metadata);
+  if (metadata !== undefined) {
+    record.m = metadata;
+  }
+  return record;
+}
+
+function normalizeImportDecision(decision: ImportDecision): { accept: boolean; reason?: string } {
+  if (!decision || typeof decision !== "object") {
+    return { accept: true };
+  }
+  if ("accept" in decision) {
+    if (!decision.accept) {
+      return { accept: false, reason: decision.reason ?? "rejected" };
+    }
+    return { accept: true };
+  }
+  return { accept: true };
+}
+
+function isExportOptions(arg: VersionVector | ExportOptions | undefined): arg is ExportOptions {
+  return (
+    typeof arg === "object" &&
+    arg !== null &&
+    (Object.prototype.hasOwnProperty.call(arg, "hooks") ||
+      Object.prototype.hasOwnProperty.call(arg, "from") ||
+      Object.prototype.hasOwnProperty.call(arg, "pruneTombstonesBefore") ||
+      Object.prototype.hasOwnProperty.call(arg, "peerId"))
+  );
+}
+
+function isImportOptions(arg: ExportBundle | ImportOptions): arg is ImportOptions {
+  return typeof arg === "object" && arg !== null && Object.prototype.hasOwnProperty.call(arg, "bundle");
+}
+
+function parseMetadata(json: string | null): MetadataMap | undefined {
+  if (!json) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(json);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as MetadataMap;
+    }
+  } catch {
+    // ignored
+  }
+  return undefined;
+}
+
+function parseData(json: string | null): Value | undefined {
+  if (json === null || json === undefined) {
+    return undefined;
+  }
+  return JSON.parse(json) as Value;
+}
+
+function parseClockString(raw: string): EntryClock {
+  const parts = raw.split(",");
+  if (parts.length < 3) {
+    return { physicalTime: 0, logicalCounter: 0, peerId: "" };
+  }
+  const physical = Number(parts[0]);
+  const logical = Number(parts[1]);
+  const peerId = parts.slice(2).join(",");
+  return {
+    physicalTime: Number.isFinite(physical) ? physical : 0,
+    logicalCounter: Number.isFinite(logical) ? Math.trunc(logical) : 0,
+    peerId: isValidPeerId(peerId) ? peerId : "",
+  };
+}
+
+function formatClock(clock: EntryClock): string {
+  return `${clock.physicalTime},${clock.logicalCounter},${clock.peerId}`;
+}
+
+function compareClock(a: EntryClock, b: EntryClock): number {
+  if (a.physicalTime !== b.physicalTime) {
+    return a.physicalTime > b.physicalTime ? 1 : -1;
+  }
+  if (a.logicalCounter !== b.logicalCounter) {
+    return a.logicalCounter > b.logicalCounter ? 1 : -1;
+  }
+  if (a.peerId === b.peerId) {
+    return 0;
+  }
+  return a.peerId > b.peerId ? 1 : -1;
+}
+
+function normalizeVersionEntry(entry?: VersionVectorEntry): VersionVectorEntry | undefined {
+  if (!entry) return undefined;
+  const { physicalTime, logicalCounter } = entry;
+  if (!Number.isFinite(physicalTime) || !Number.isFinite(logicalCounter)) {
+    return undefined;
+  }
+  return {
+    physicalTime: physicalTime,
+    logicalCounter: Math.trunc(logicalCounter),
+  };
+}
+
+function keyMatchesPrefix(key: Uint8Array, prefix: Uint8Array): boolean {
+  if (prefix.length === 0) {
+    return true;
+  }
+  if (key.length < prefix.length) {
+    return false;
+  }
+  for (let i = 0; i < prefix.length; i += 1) {
+    if (key[i] !== prefix[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function toDigestRows(rows: KvRow[]): Promise<DigestRow[]> {
+  return rows.map((row) => ({
+    key: row.key,
+    data: row.data,
+    metadata: row.metadata,
+    physical: row.physical,
+    logical: row.logical,
+    peer: row.peer,
+  }));
+}
+
+export type FlockSQLiteOptions = {
+  path: string;
+  peerId?: string;
+  connection?: UniStoreConnection;
+  tablePrefix?: string;
+};
+
+type TableNames = {
+  kv: string;
+  overridden: string;
+  meta: string;
+  idxKvPeerClock: string;
+  idxOverriddenKey: string;
+  idxOverriddenSupersededAt: string;
+};
+
+function normalizeTablePrefix(prefix?: string): string {
+  if (!prefix) return "";
+  if (typeof prefix !== "string") {
+    throw new TypeError("tablePrefix must be a string");
+  }
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) {
+    throw new TypeError("tablePrefix must start with a letter/underscore and use only letters, digits, or underscores");
+  }
+  return prefix;
+}
+
+function buildTableNames(prefix: string): TableNames {
+  return {
+    kv: `${prefix}kv`,
+    overridden: `${prefix}overridden`,
+    meta: `${prefix}meta`,
+    idxKvPeerClock: `${prefix}idx_kv_peer_clock_key`,
+    idxOverriddenKey: `${prefix}idx_overridden_key`,
+    idxOverriddenSupersededAt: `${prefix}idx_overridden_superseded_at`,
+  };
+}
+
+export class FlockSQLite {
+  private db: UniStoreConnection;
+  private peerIdValue: string;
+  private vv: Map<string, VersionVectorEntry>;
+  private maxHlc: { physicalTime: number; logicalCounter: number };
+  private listeners: Set<EventListener>;
+  private tables: TableNames;
+
+  private constructor(db: UniStoreConnection, peerId: string, vv: Map<string, VersionVectorEntry>, maxHlc: { physicalTime: number; logicalCounter: number }, tables: TableNames) {
+    this.db = db;
+    this.peerIdValue = peerId;
+    this.vv = vv;
+    this.maxHlc = maxHlc;
+    this.listeners = new Set();
+    this.tables = tables;
+  }
+
+  static async open(options: FlockSQLiteOptions): Promise<FlockSQLite> {
+    const db = options.connection ?? (await openStore({ path: options.path }));
+    const prefix = normalizeTablePrefix(options.tablePrefix);
+    const tables = buildTableNames(prefix);
+    await FlockSQLite.ensureSchema(db, tables);
+    const peerId = await FlockSQLite.resolvePeerId(db, tables, options.peerId);
+    const { vv, maxHlc } = await FlockSQLite.loadVersionState(db, tables);
+    return new FlockSQLite(db, peerId, vv, maxHlc, tables);
+  }
+
+  static async fromJson(options: FlockSQLiteOptions & { bundle: ExportBundle }): Promise<FlockSQLite> {
+    const flock = await FlockSQLite.open(options);
+    await flock.importJson(options.bundle);
+    return flock;
+  }
+
+  async close(): Promise<void> {
+    await this.db.close();
+  }
+
+  private static async ensureSchema(db: UniStoreConnection, tables: TableNames): Promise<void> {
+    await db.exec(`
+      CREATE TABLE IF NOT EXISTS ${tables.kv} (
+        key BLOB PRIMARY KEY,
+        data TEXT NULL,
+        metadata TEXT NULL,
+        physical REAL NOT NULL,
+        logical INTEGER NOT NULL,
+        peer TEXT NOT NULL
+      )`);
+    await db.exec(`
+      CREATE TABLE IF NOT EXISTS ${tables.overridden} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        key BLOB,
+        data TEXT NULL,
+        metadata TEXT NULL,
+        physical REAL NOT NULL,
+        logical INTEGER NOT NULL,
+        peer TEXT NOT NULL,
+        superseded_at INTEGER DEFAULT (unixepoch())
+      )`);
+    await db.exec(`CREATE TABLE IF NOT EXISTS ${tables.meta} (peer_id TEXT)`);
+    await db.exec(
+      `CREATE INDEX IF NOT EXISTS ${tables.idxKvPeerClock} ON ${tables.kv}(peer, physical, logical, key)`,
+    );
+    await db.exec(
+      `CREATE INDEX IF NOT EXISTS ${tables.idxOverriddenKey} ON ${tables.overridden}(key)`,
+    );
+    await db.exec(
+      `CREATE INDEX IF NOT EXISTS ${tables.idxOverriddenSupersededAt} ON ${tables.overridden}(superseded_at)`,
+    );
+  }
+
+  private static async resolvePeerId(db: UniStoreConnection, tables: TableNames, provided?: string): Promise<string> {
+    const normalized = normalizePeerId(provided);
+    const rows = await db.query<{ peer_id: string }>(`SELECT peer_id FROM ${tables.meta} LIMIT 1`);
+    if (rows.length > 0 && typeof rows[0]?.peer_id === "string") {
+      const existing = rows[0].peer_id;
+      if (provided && existing !== normalized) {
+        await db.run(`UPDATE ${tables.meta} SET peer_id = ?`, [normalized]);
+        return normalized;
+      }
+      return normalizePeerId(existing);
+    }
+    await db.exec(`DELETE FROM ${tables.meta}`);
+    await db.run(`INSERT INTO ${tables.meta}(peer_id) VALUES (?)`, [normalized]);
+    return normalized;
+  }
+
+  private static async loadVersionState(db: UniStoreConnection, tables: TableNames): Promise<{ vv: Map<string, VersionVectorEntry>; maxHlc: { physicalTime: number; logicalCounter: number } }> {
+    const vv = new Map<string, VersionVectorEntry>();
+    const rows = await db.query<ClockRow>(
+      `SELECT peer, MAX(physical) AS physical, MAX(logical) AS logical FROM ${tables.kv} GROUP BY peer`,
+    );
+    for (const row of rows) {
+      if (!row || typeof row.peer !== "string") continue;
+      const entry = normalizeVersionEntry({
+        physicalTime: Number(row.physical ?? 0),
+        logicalCounter: Number(row.logical ?? 0),
+      });
+      if (entry) {
+        vv.set(row.peer, entry);
+      }
+    }
+    const maxRow = await db.query<ClockRow>(
+      `SELECT physical, logical FROM ${tables.kv} ORDER BY physical DESC, logical DESC LIMIT 1`,
+    );
+    const first = maxRow[0];
+    const maxHlc =
+      first && Number.isFinite(first.physical) && Number.isFinite(first.logical)
+        ? { physicalTime: Number(first.physical), logicalCounter: Number(first.logical) }
+        : { physicalTime: 0, logicalCounter: 0 };
+    return { vv, maxHlc };
+  }
+
+  private bumpVersion(clock: EntryClock): void {
+    const current = this.vv.get(clock.peerId);
+    if (!current || compareClock(clock, { ...current, peerId: clock.peerId }) > 0) {
+      this.vv.set(clock.peerId, {
+        physicalTime: clock.physicalTime,
+        logicalCounter: clock.logicalCounter,
+      });
+    }
+    if (
+      this.maxHlc.physicalTime < clock.physicalTime ||
+      (this.maxHlc.physicalTime === clock.physicalTime &&
+        this.maxHlc.logicalCounter < clock.logicalCounter)
+    ) {
+      this.maxHlc = { physicalTime: clock.physicalTime, logicalCounter: clock.logicalCounter };
+    }
+  }
+
+  private allocateClock(now?: number): EntryClock {
+    const timestamp = now ?? Date.now();
+    let physical = this.maxHlc.physicalTime;
+    let logical = this.maxHlc.logicalCounter;
+    if (timestamp > physical) {
+      physical = timestamp;
+      logical = 0;
+    } else {
+      logical = logical + 1;
+    }
+    return { physicalTime: physical, logicalCounter: logical, peerId: this.peerIdValue };
+  }
+
+  private async applyOperation(operation: PutOperation): Promise<boolean> {
+    const keyBytes = encodeKeyParts(operation.key);
+    const clock = operation.clock ?? this.allocateClock(operation.now);
+    const payload = mergePayload(operation.payload, {});
+    const dataJson = payload.data === undefined ? null : JSON.stringify(payload.data);
+    const metadataJson = payload.metadata === undefined ? null : JSON.stringify(payload.metadata);
+    let applied = false;
+
+    await this.db.asyncTransaction(async (tx) => {
+      const existingRows = await tx.query<KvRow>(
+        `SELECT key, data, metadata, physical, logical, peer FROM ${this.tables.kv} WHERE key = ? LIMIT 1`,
+        [keyBytes],
+      );
+      if (existingRows.length > 0) {
+        const existing = existingRows[0];
+        const existingClock: EntryClock = {
+          physicalTime: Number(existing.physical ?? 0),
+          logicalCounter: Number(existing.logical ?? 0),
+          peerId: String(existing.peer ?? ""),
+        };
+        const cmp = compareClock(clock, existingClock);
+        const existingData = existing.data ?? null;
+        const existingMeta = existing.metadata ?? null;
+        const samePayload =
+          operation.skipSameValue &&
+          dataJson === existingData &&
+          metadataJson === existingMeta;
+        if (samePayload) {
+          return;
+        }
+        if (cmp < 0) {
+          await tx.run(
+            `INSERT INTO ${this.tables.overridden}(key, data, metadata, physical, logical, peer) VALUES (?, ?, ?, ?, ?, ?)`,
+            [keyBytes, dataJson, metadataJson, clock.physicalTime, clock.logicalCounter, clock.peerId],
+          );
+          return;
+        }
+        if (cmp > 0) {
+          await tx.run(
+            `INSERT INTO ${this.tables.overridden}(key, data, metadata, physical, logical, peer) VALUES (?, ?, ?, ?, ?, ?)`,
+            [
+              keyBytes,
+              existing.data ?? null,
+              existing.metadata ?? null,
+              existing.physical ?? 0,
+              existing.logical ?? 0,
+              existing.peer ?? "",
+            ],
+          );
+        } else {
+          return;
+        }
+      }
+      await tx.run(
+        `INSERT INTO ${this.tables.kv}(key, data, metadata, physical, logical, peer)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(key) DO UPDATE SET
+           data=excluded.data,
+           metadata=excluded.metadata,
+           physical=excluded.physical,
+           logical=excluded.logical,
+           peer=excluded.peer`,
+        [keyBytes, dataJson, metadataJson, clock.physicalTime, clock.logicalCounter, clock.peerId],
+      );
+      applied = true;
+    });
+
+    this.bumpVersion(clock);
+    if (applied) {
+      const eventPayload = {
+        key: operation.key.slice(),
+        payload,
+        source: operation.source,
+      };
+      if (operation.eventSink) {
+        operation.eventSink.push(eventPayload);
+      } else {
+        this.emitEvents(operation.source, [eventPayload]);
+      }
+    }
+    return applied;
+  }
+
+  private emitEvents(
+    source: string,
+    events: Array<{ key: KeyPart[]; payload: ExportPayload }>,
+  ): void {
+    if (this.listeners.size === 0 || events.length === 0) {
+      return;
+    }
+    const batch: EventBatch = {
+      source,
+      events: events.map((event): Event => ({
+        key: cloneJson(event.key),
+        value: event.payload.data !== undefined ? cloneJson(event.payload.data) : undefined,
+        metadata: cloneMetadata(event.payload.metadata),
+        payload: clonePayload(event.payload),
+      })),
+    };
+    this.listeners.forEach((listener) => {
+      listener(batch);
+    });
+  }
+
+  async put(key: KeyPart[], value: Value, now?: number): Promise<void> {
+    await this.applyOperation({
+      key,
+      payload: { data: cloneJson(value) },
+      now,
+      skipSameValue: true,
+      source: "local",
+    });
+  }
+
+  async putWithMeta(key: KeyPart[], value: Value, options: PutWithMetaOptions = {}): Promise<void> {
+    const basePayload: ExportPayload = { data: cloneJson(value) };
+    if (options.metadata) {
+      basePayload.metadata = cloneMetadata(options.metadata);
+    }
+    const hooks = options.hooks?.transform;
+    if (hooks) {
+      const working = clonePayload(basePayload);
+      const transformed = await hooks({ key: key.slice(), now: options.now }, working);
+      const finalPayload = mergePayload(basePayload, transformed ?? working);
+      if (finalPayload.data === undefined) {
+        throw new TypeError("putWithMeta requires a data value");
+      }
+      await this.applyOperation({
+        key,
+        payload: finalPayload,
+        now: options.now,
+        skipSameValue: true,
+        source: "local",
+      });
+      return;
+    }
+    await this.applyOperation({
+      key,
+      payload: basePayload,
+      now: options.now,
+      skipSameValue: true,
+      source: "local",
+    });
+  }
+
+  async delete(key: KeyPart[], now?: number): Promise<void> {
+    await this.applyOperation({
+      key,
+      payload: {},
+      now,
+      skipSameValue: true,
+      source: "local",
+    });
+  }
+
+  async set(key: KeyPart[], value: Value, now?: number): Promise<void> {
+    await this.put(key, value, now);
+  }
+
+  async setPeerId(peerId: string): Promise<void> {
+    const normalized = normalizePeerId(peerId);
+    await this.db.exec(`DELETE FROM ${this.tables.meta}`);
+    await this.db.run(`INSERT INTO ${this.tables.meta}(peer_id) VALUES (?)`, [normalized]);
+    this.peerIdValue = normalized;
+  }
+
+  async get(key: KeyPart[]): Promise<Value | undefined> {
+    const keyBytes = encodeKeyParts(key);
+    const rows = await this.db.query<KvRow>(
+      `SELECT data FROM ${this.tables.kv} WHERE key = ? LIMIT 1`,
+      [keyBytes],
+    );
+    const row = rows[0];
+    if (!row) return undefined;
+    return parseData(row.data);
+  }
+
+  async getMvr(key: KeyPart[]): Promise<Value[]> {
+    const rows = await this.scan({ prefix: key });
+    const values: Value[] = [];
+    for (const row of rows) {
+      if (row.raw.d !== true) continue;
+      if (row.key.length !== key.length + 1) continue;
+      values.push(row.key[row.key.length - 1]);
+    }
+    return values;
+  }
+
+  async putMvr(key: KeyPart[], value: Value, now?: number): Promise<void> {
+    if (value === null || typeof value === "object") {
+      throw new TypeError("putMvr only accepts scalar values");
+    }
+    const existing = await this.scan({ prefix: key });
+    for (const row of existing) {
+      if (row.raw.d === true) {
+        await this.delete(row.key, now);
+      }
+    }
+    const composite = key.slice();
+    composite.push(value);
+    await this.put(composite, true, now);
+  }
+
+  private buildScanBounds(
+    options: ScanOptions,
+  ): { where: string[]; params: unknown[]; empty?: boolean; postFilter?: (bytes: Uint8Array) => boolean } {
+    let lower: { value: Uint8Array; inclusive: boolean } | undefined;
+    let upper: { value: Uint8Array; inclusive: boolean } | undefined;
+    let prefixFilter: Uint8Array | undefined;
+
+    const applyLower = (candidate: { value: Uint8Array; inclusive: boolean }) => {
+      if (!lower) {
+        lower = candidate;
+        return;
+      }
+      const cmp = compareBytes(candidate.value, lower.value);
+      if (cmp > 0) {
+        lower = candidate;
+      } else if (cmp === 0) {
+        lower = { value: lower.value, inclusive: lower.inclusive && candidate.inclusive };
+      }
+    };
+
+    const applyUpper = (candidate: { value: Uint8Array; inclusive: boolean }) => {
+      if (!upper) {
+        upper = candidate;
+        return;
+      }
+      const cmp = compareBytes(candidate.value, upper.value);
+      if (cmp < 0) {
+        upper = candidate;
+      } else if (cmp === 0) {
+        upper = { value: upper.value, inclusive: upper.inclusive && candidate.inclusive };
+      }
+    };
+
+    try {
+      if (options.prefix) {
+        const prefixBytes = encodeKeyParts(options.prefix);
+        prefixFilter = prefixBytes;
+        applyLower({ value: prefixBytes, inclusive: true });
+        const upperPrefix = prefixUpperBound(prefixBytes);
+        if (upperPrefix) {
+          applyUpper({ value: upperPrefix, inclusive: false });
+        }
+      }
+      if (options.start && options.start.kind !== "unbounded") {
+        applyLower({
+          value: encodeKeyParts(options.start.key),
+          inclusive: options.start.kind === "inclusive",
+        });
+      }
+      if (options.end && options.end.kind !== "unbounded") {
+        applyUpper({
+          value: encodeKeyParts(options.end.key),
+          inclusive: options.end.kind === "inclusive",
+        });
+      }
+    } catch {
+      return { where: [], params: [], empty: true };
+    }
+
+    const where: string[] = [];
+    const params: unknown[] = [];
+    if (lower) {
+      where.push(`key ${lower.inclusive ? ">=" : ">"} ?`);
+      params.push(lower.value);
+    }
+    if (upper) {
+      where.push(`key ${upper.inclusive ? "<=" : "<"} ?`);
+      params.push(upper.value);
+    }
+    const postFilter = prefixFilter
+      ? ((pf: Uint8Array) => (bytes: Uint8Array) => keyMatchesPrefix(bytes, pf))(prefixFilter)
+      : undefined;
+    return { where, params, postFilter };
+  }
+
+  async scan(options: ScanOptions = {}): Promise<ScanRow[]> {
+    const bounds = this.buildScanBounds(options);
+    if (bounds.empty) {
+      return [];
+    }
+    const clauses = bounds.where.length > 0 ? `WHERE ${bounds.where.join(" AND ")}` : "";
+    const rows = await this.db.query<KvRow>(
+      `SELECT key, data, metadata, physical, logical, peer FROM ${this.tables.kv} ${clauses} ORDER BY key ASC`,
+      bounds.params as [],
+    );
+    const result: ScanRow[] = [];
+    for (const row of rows) {
+      const keyBytes = row.key;
+      if (bounds.postFilter && !bounds.postFilter(keyBytes)) {
+        continue;
+      }
+      const key = decodeKeyParts(keyBytes);
+      const clock: EntryClock = {
+        physicalTime: Number(row.physical ?? 0),
+        logicalCounter: Number(row.logical ?? 0),
+        peerId: String(row.peer ?? ""),
+      };
+      const payload: ExportPayload = {};
+      const data = parseData(row.data);
+      if (data !== undefined) payload.data = data;
+      const metadata = parseMetadata(row.metadata);
+      if (metadata !== undefined) payload.metadata = metadata;
+      const raw = buildRecord(clock, payload);
+      result.push({ key, raw, value: payload.data });
+    }
+    return result;
+  }
+
+  version(): VersionVector {
+    const vv: VersionVector = {};
+    for (const [peer, clock] of this.vv.entries()) {
+      vv[peer] = { ...clock };
+    }
+    return vv;
+  }
+
+  peerId(): string {
+    return this.peerIdValue;
+  }
+
+  getMaxPhysicalTime(): number {
+    return this.maxHlc.physicalTime;
+  }
+
+  private async exportInternal(from?: VersionVector, pruneTombstonesBefore?: number, peerId?: string): Promise<ExportBundle> {
+    const normalizedFrom = new Map<string, VersionVectorEntry>();
+    if (from) {
+      for (const [peer, entry] of Object.entries(from)) {
+        const normalized = normalizeVersionEntry(entry);
+        if (normalized) {
+          normalizedFrom.set(peer, normalized);
+        }
+      }
+    }
+
+    const entries: Record<string, ExportRecord> = {};
+
+    const peers = peerId ? [peerId] : Array.from(this.vv.keys());
+    const peersToExport: Array<{ peer: string; fromEntry?: VersionVectorEntry }> = [];
+    for (const peer of peers) {
+      const localEntry = this.vv.get(peer);
+      const fromEntry = normalizedFrom.get(peer);
+      if (
+        localEntry &&
+        fromEntry &&
+        (localEntry.physicalTime < fromEntry.physicalTime ||
+          (localEntry.physicalTime === fromEntry.physicalTime &&
+            localEntry.logicalCounter <= fromEntry.logicalCounter))
+      ) {
+        // Remote is already up to date for this peer.
+        continue;
+      }
+      peersToExport.push({ peer, fromEntry });
+    }
+
+    if (peerId && peersToExport.every((p) => p.peer !== peerId)) {
+      peersToExport.push({ peer: peerId, fromEntry: normalizedFrom.get(peerId) });
+    }
+
+    if (peersToExport.length === 0) {
+      return { version: 0, entries };
+    }
+
+    for (const target of peersToExport) {
+      const params: unknown[] = [target.peer];
+      let clause = "WHERE peer = ?";
+      if (target.fromEntry) {
+        clause += " AND physical >= ?";
+        params.push(target.fromEntry.physicalTime);
+      }
+      const rows = await this.db.query<ExportQueryRow>(
+        `SELECT key, data, metadata, physical, logical, peer FROM ${this.tables.kv} ${clause} ORDER BY physical, logical, key`,
+        params as [],
+      );
+      for (const row of rows) {
+        const clock: EntryClock = {
+          physicalTime: Number(row.physical ?? 0),
+          logicalCounter: Number(row.logical ?? 0),
+          peerId: String(row.peer ?? ""),
+        };
+        const fromEntry = target.fromEntry;
+        if (
+          fromEntry &&
+          (clock.physicalTime < fromEntry.physicalTime ||
+            (clock.physicalTime === fromEntry.physicalTime &&
+              clock.logicalCounter <= fromEntry.logicalCounter))
+        ) {
+          continue;
+        }
+        if (
+          pruneTombstonesBefore !== undefined &&
+          Number.isFinite(pruneTombstonesBefore) &&
+          row.data === null &&
+          clock.physicalTime < pruneTombstonesBefore
+        ) {
+          continue;
+        }
+        const payload: ExportPayload = {};
+        const data = parseData(row.data);
+        if (data !== undefined) payload.data = data;
+        const metadata = parseMetadata(row.metadata);
+        if (metadata !== undefined) payload.metadata = metadata;
+        const keyParts = decodeKeyParts(row.key);
+        entries[keyToString(keyParts)] = buildRecord(clock, payload);
+      }
+    }
+    return { version: 0, entries };
+  }
+
+  private async exportWithHooks(options: ExportOptions): Promise<ExportBundle> {
+    const base = await this.exportInternal(options.from, options.pruneTombstonesBefore, options.peerId);
+    const transform = options.hooks?.transform;
+    if (!transform) {
+      return base;
+    }
+    const result: ExportBundle = { version: base.version, entries: {} };
+    for (const [key, record] of Object.entries(base.entries)) {
+      const clock = parseClockString(record.c);
+      const context = {
+        key: JSON.parse(key) as KeyPart[],
+        clock,
+        raw: { ...record },
+      };
+      const basePayload: ExportPayload = {};
+      if (record.d !== undefined) basePayload.data = cloneJson(record.d);
+      const meta = cloneMetadata(record.m);
+      if (meta !== undefined) basePayload.metadata = meta;
+      const working = clonePayload(basePayload);
+      const transformed = await transform(context, working);
+      const finalPayload = mergePayload(basePayload, transformed ?? working);
+      result.entries[key] = buildRecord(clock, finalPayload);
+    }
+    return result;
+  }
+
+  exportJson(): Promise<ExportBundle>;
+  exportJson(from: VersionVector): Promise<ExportBundle>;
+  exportJson(from: VersionVector, pruneTombstonesBefore: number): Promise<ExportBundle>;
+  exportJson(options: ExportOptions): Promise<ExportBundle>;
+  exportJson(arg?: VersionVector | ExportOptions, pruneTombstonesBefore?: number): Promise<ExportBundle> {
+    if (isExportOptions(arg)) {
+      return this.exportWithHooks(arg);
+    }
+    return this.exportInternal(arg, pruneTombstonesBefore);
+  }
+
+  private async importInternal(bundle: ExportBundle): Promise<ImportReport> {
+    if (bundle.version !== 0) {
+      throw new TypeError("Unsupported bundle version");
+    }
+    let accepted = 0;
+    const skipped: Array<{ key: KeyPart[]; reason: string }> = [];
+    const appliedEvents: Array<{ key: KeyPart[]; payload: ExportPayload; source: string }> = [];
+    for (const [keyString, record] of Object.entries(bundle.entries)) {
+      let keyParts: KeyPart[];
+      try {
+        const parsed = JSON.parse(keyString);
+        keyParts = Array.isArray(parsed) ? (parsed as KeyPart[]) : [];
+      } catch {
+        skipped.push({ key: [], reason: "invalid key" });
+        continue;
+      }
+      const clock = parseClockString(record.c);
+      const payload: ExportPayload = {};
+      if (record.d !== undefined) payload.data = cloneJson(record.d);
+      const metadata = cloneMetadata(record.m);
+      if (metadata !== undefined) payload.metadata = metadata;
+      accepted += 1;
+      await this.applyOperation({
+        key: keyParts,
+        payload,
+        clock,
+        skipSameValue: false,
+        source: "import",
+        eventSink: appliedEvents,
+      });
+    }
+    if (appliedEvents.length > 0) {
+      this.emitEvents("import", appliedEvents);
+    }
+    return { accepted, skipped };
+  }
+
+  async importJson(bundle: ExportBundle): Promise<ImportReport>;
+  async importJson(options: ImportOptions): Promise<ImportReport>;
+  async importJson(arg: ExportBundle | ImportOptions): Promise<ImportReport> {
+    if (isImportOptions(arg)) {
+      const preprocess = arg.hooks?.preprocess;
+      const working = preprocess ? { version: arg.bundle.version, entries: { ...arg.bundle.entries } } : arg.bundle;
+      const skipped: Array<{ key: KeyPart[]; reason: string }> = [];
+      if (preprocess) {
+        for (const [key, record] of Object.entries(working.entries)) {
+          const contextKey = JSON.parse(key) as KeyPart[];
+          const clock = parseClockString(record.c);
+          const payload: ExportPayload = {};
+          if (record.d !== undefined) payload.data = cloneJson(record.d);
+          const metadata = cloneMetadata(record.m);
+          if (metadata !== undefined) payload.metadata = metadata;
+          const decision = await preprocess(
+            { key: contextKey, clock, raw: record },
+            clonePayload(payload),
+          );
+          const normalized = normalizeImportDecision(decision);
+          if (!normalized.accept) {
+            skipped.push({ key: contextKey, reason: normalized.reason ?? "rejected" });
+            delete working.entries[key];
+          } else {
+            working.entries[key] = buildRecord(clock, payload);
+          }
+        }
+      }
+      const baseReport = await this.importInternal(working);
+      return { accepted: baseReport.accepted, skipped: skipped.concat(baseReport.skipped) };
+    }
+    return this.importInternal(arg);
+  }
+
+  async importJsonStr(json: string): Promise<ImportReport> {
+    const parsed = JSON.parse(json) as ExportBundle;
+    return this.importJson(parsed);
+  }
+
+  async digest(): Promise<string> {
+    const rows = await this.db.query<KvRow>(
+      `SELECT key, data, metadata, physical, logical, peer FROM ${this.tables.kv} ORDER BY key ASC`,
+    );
+    const digestRows = await toDigestRows(rows);
+    return computeDigest(digestRows);
+  }
+
+  async kvToJson(): Promise<ExportBundle> {
+    return this.exportInternal();
+  }
+
+  async merge(other: FlockSQLite): Promise<void> {
+    const bundle = await other.exportJson();
+    await this.importJson(bundle);
+  }
+
+  static async checkConsistency(a: FlockSQLite, b: FlockSQLite): Promise<boolean> {
+    const [digestA, digestB] = await Promise.all([a.digest(), b.digest()]);
+    return digestA === digestB;
+  }
+
+  checkInvariants(): void {
+    // Placeholder: SQLite-backed implementation does not yet expose internal invariants.
+  }
+
+  subscribe(listener: (batch: EventBatch) => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+}
+
+export type {
+  Event,
+  EventBatch,
+  ExportBundle,
+  ExportHooks,
+  ExportOptions,
+  ExportPayload,
+  ExportRecord,
+  ImportHooks,
+  ImportOptions,
+  ImportReport,
+  KeyPart,
+  MetadataMap,
+  PutHooks,
+  PutWithMetaOptions,
+  ScanBound,
+  ScanOptions,
+  ScanRow,
+  Value,
+  VersionVector,
+  VersionVectorEntry,
+};
+
+export { FlockSQLite as Flock };
+export type { EventListener };