@indigoai-us/hq-cloud 6.14.49 → 6.15.0

package/src/sync/state-store.ts

@@ -0,0 +1,727 @@
+/**
+ * Durable per-scope state store for the realtime-sync v2 protocol.
+ *
+ * The store intentionally has no knowledge of journal or sync domain records.
+ * Callers supply a reducer; this keeps the on-disk framing/recovery boundary
+ * small while allowing later protocol units to append their own typed records.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const SNAPSHOT_MAGIC = Buffer.from("HQSNAP3\0", "ascii");
+const WAL_MAGIC = Buffer.from("HQWAL3\0\0", "ascii");
+const FRAME_MAGIC = 0x48515733;
+const SNAPSHOT_HEADER_BYTES = 8 + 8 + 4 + 32 + 32;
+const WAL_HEADER_BYTES = 8 + 8 + 32 + 32;
+const FRAME_PREFIX_BYTES = 4 + 4;
+const FRAME_FIXED_BODY_BYTES = 8 + 2 + 2 + 4 + 4 + 32;
+const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+const LOCK_RETRY_MS = 10;
+const LOCK_TIMEOUT_MS = 5_000;
+
+export interface StateStoreRecord<T = unknown> {
+  sequence: number;
+  type: number;
+  flags: number;
+  payload: T;
+}
+
+export interface StateStoreOptions<T> {
+  rootDir: string;
+  scopeId: string;
+  initialState: T;
+  reduce: (state: T, record: StateStoreRecord) => T;
+  /** Compact after this many WAL records. Defaults to 256. */
+  maxRecordsBeforeCompaction?: number;
+}
+
+interface SnapshotPayload<T> {
+  lastRecordSequence: number;
+  state: T;
+}
+
+interface Generation<T> {
+  generation: number;
+  state: T;
+  lastRecordSequence: number;
+  recordCount: number;
+}
+
+export class StateStoreCorruptionError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(`state-store corruption: ${message}`, options);
+    this.name = "StateStoreCorruptionError";
+  }
+}
+
+class StateStoreLockError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(`state-store lock: ${message}`, options);
+    this.name = "StateStoreLockError";
+  }
+}
+
+/** A recovered v3 store. `append` is the ordinary hot path. */
+export class StateStore<T> {
+  readonly stateDir: string;
+  readonly scopeDigest: Buffer;
+  readonly wasCreated: boolean;
+  private generation: number;
+  private state: T;
+  private lastRecordSequence: number;
+  private recordCount: number;
+
+  private constructor(
+    private readonly options: StateStoreOptions<T> & { maxRecordsBeforeCompaction: number },
+    recovered: Generation<T>,
+    wasCreated: boolean,
+  ) {
+    this.scopeDigest = digestScope(options.scopeId);
+    this.stateDir = stateDirectory(options.rootDir, this.scopeDigest);
+    this.generation = recovered.generation;
+    this.state = recovered.state;
+    this.lastRecordSequence = recovered.lastRecordSequence;
+    this.recordCount = recovered.recordCount;
+    this.wasCreated = wasCreated;
+  }
+
+  static exists(rootDir: string, scopeId: string): boolean {
+    const dir = stateDirectory(rootDir, digestScope(scopeId));
+    try {
+      return fs.readdirSync(dir).some((name) => /^snapshot-\d+\.bin$/.test(name));
+    } catch (error) {
+      if (isMissing(error)) return false;
+      throw new Error(`state-store: cannot inspect ${dir}`, { cause: error });
+    }
+  }
+
+  static open<T>(options: StateStoreOptions<T>): StateStore<T> {
+    if (!options.scopeId) throw new Error("state-store: scopeId is required");
+    const normalized: StateStoreOptions<T> & { maxRecordsBeforeCompaction: number } = {
+      ...options,
+      maxRecordsBeforeCompaction: options.maxRecordsBeforeCompaction ?? 256,
+    };
+    if (normalized.maxRecordsBeforeCompaction < 1) {
+      throw new Error("state-store: maxRecordsBeforeCompaction must be positive");
+    }
+    const scopeDigest = digestScope(normalized.scopeId);
+    const dir = stateDirectory(normalized.rootDir, scopeDigest);
+    fs.mkdirSync(dir, { recursive: true });
+    cleanupUnpublishedInitialGeneration(dir);
+    const generations = readGenerations(dir, scopeDigest, normalized.reduce);
+    if (generations.length > 0) {
+      return new StateStore(normalized, generations[0]!, false);
+    }
+
+    const initial: Generation<T> = {
+      generation: 1,
+      state: normalized.initialState,
+      lastRecordSequence: 0,
+      recordCount: 0,
+    };
+    writeGeneration(dir, scopeDigest, initial);
+    writeCurrentPointer(dir, initial.generation);
+    return new StateStore(normalized, initial, true);
+  }
+
+  getState(): T {
+    return this.state;
+  }
+
+  getGeneration(): number {
+    return this.generation;
+  }
+
+  getLastRecordSequence(): number {
+    return this.lastRecordSequence;
+  }
+
+  append(type: number, payload: unknown, flags = 0): StateStoreRecord {
+    assertUint16(type, "record type");
+    assertUint16(flags, "record flags");
+    return withScopeLock(this.stateDir, () => {
+      this.refreshFromDisk();
+      const record: StateStoreRecord = {
+        sequence: this.lastRecordSequence + 1,
+        type,
+        flags,
+        payload,
+      };
+      if (!Number.isSafeInteger(record.sequence)) {
+        throw new Error("state-store: record sequence exceeds safe integer range");
+      }
+      // Validate reducer acceptance before making this frame durable.
+      const nextState = this.options.reduce(this.state, record);
+      appendDurably(walPath(this.stateDir, this.generation), encodeFrame(record));
+      this.state = nextState;
+      this.lastRecordSequence = record.sequence;
+      this.recordCount++;
+      if (this.recordCount >= this.options.maxRecordsBeforeCompaction) this.compactUnlocked();
+      return record;
+    });
+  }
+
+  /** Create G+1 without ever merging two generations during recovery. */
+  compact(): void {
+    withScopeLock(this.stateDir, () => {
+      this.refreshFromDisk();
+      this.compactUnlocked();
+    });
+  }
+
+  private refreshFromDisk(): void {
+    const recovered = readGenerations(this.stateDir, this.scopeDigest, this.options.reduce);
+    if (recovered.length === 0) {
+      throw new StateStoreCorruptionError("no valid generation remains while appending");
+    }
+    const current = recovered[0]!;
+    this.generation = current.generation;
+    this.state = current.state;
+    this.lastRecordSequence = current.lastRecordSequence;
+    this.recordCount = current.recordCount;
+  }
+
+  private compactUnlocked(): void {
+    const next: Generation<T> = {
+      generation: highestGenerationOnDisk(this.stateDir) + 1,
+      state: this.state,
+      lastRecordSequence: this.lastRecordSequence,
+      recordCount: 0,
+    };
+    writeGeneration(this.stateDir, this.scopeDigest, next);
+    writeCurrentPointer(this.stateDir, next.generation);
+    pruneGenerations(this.stateDir, [this.generation, next.generation]);
+    this.generation = next.generation;
+    this.recordCount = 0;
+  }
+}
+
+function readGenerations<T>(
+  dir: string,
+  scopeDigest: Buffer,
+  reduce: StateStoreOptions<T>["reduce"],
+): Generation<T>[] {
+  const names = fs.readdirSync(dir);
+  const generations = names
+    .map((name) => /^snapshot-(\d+)\.bin$/.exec(name)?.[1])
+    .filter((value): value is string => value !== undefined)
+    .map(Number)
+    .filter(Number.isSafeInteger)
+    .sort((a, b) => b - a);
+  const recovered: Generation<T>[] = [];
+  const errors: Error[] = [];
+  for (const generation of generations) {
+    try {
+      recovered.push(readGeneration(dir, scopeDigest, generation!, reduce));
+    } catch (error) {
+      if (!(error instanceof StateStoreCorruptionError)) {
+        throw new Error(`state-store: reducer rejected generation ${generation}`, { cause: error });
+      }
+      errors.push(error);
+    }
+  }
+  if (recovered.length === 0 && generations.length > 0) {
+    throw new StateStoreCorruptionError("no valid snapshot/WAL generation remains", {
+      cause: errors[0],
+    });
+  }
+  return recovered;
+}
+
+function readGeneration<T>(
+  dir: string,
+  scopeDigest: Buffer,
+  generation: number,
+  reduce: StateStoreOptions<T>["reduce"],
+): Generation<T> {
+  const snapshot = readSnapshot<T>(snapshotPath(dir, generation), scopeDigest, generation);
+  const parsed = readWal(
+    walPath(dir, generation),
+    scopeDigest,
+    generation,
+    snapshot.lastRecordSequence,
+  );
+  let state = snapshot.state;
+  for (const record of parsed.records) state = reduce(state, record);
+  return {
+    generation,
+    state,
+    lastRecordSequence: parsed.lastRecordSequence,
+    recordCount: parsed.records.length,
+  };
+}
+
+function writeGeneration<T>(dir: string, scopeDigest: Buffer, generation: Generation<T>): void {
+  const snapshot = encodeSnapshot(generation.generation, scopeDigest, {
+    lastRecordSequence: generation.lastRecordSequence,
+    state: generation.state,
+  });
+  const destination = snapshotPath(dir, generation.generation);
+  writeDurableTempThenRename(dir, destination, snapshot);
+  const header = encodeWalHeader(generation.generation, scopeDigest);
+  writeNewDurably(walPath(dir, generation.generation), header);
+}
+
+function readSnapshot<T>(filePath: string, scopeDigest: Buffer, generation: number): SnapshotPayload<T> {
+  let bytes: Buffer;
+  try {
+    bytes = fs.readFileSync(filePath);
+  } catch (error) {
+    throw new StateStoreCorruptionError(`cannot read snapshot generation ${generation}`, { cause: error });
+  }
+  if (bytes.length < SNAPSHOT_HEADER_BYTES) {
+    throw new StateStoreCorruptionError(`snapshot generation ${generation} has a torn header`);
+  }
+  if (!bytes.subarray(0, 8).equals(SNAPSHOT_MAGIC)) {
+    throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid magic`);
+  }
+  if (readU64(bytes, 8) !== generation) {
+    throw new StateStoreCorruptionError(`snapshot generation ${generation} has a generation mismatch`);
+  }
+  const payloadLength = bytes.readUInt32BE(16);
+  if (bytes.length !== SNAPSHOT_HEADER_BYTES + payloadLength) {
+    throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid payload length`);
+  }
+  if (!bytes.subarray(20, 52).equals(scopeDigest)) {
+    throw new StateStoreCorruptionError(`snapshot generation ${generation} has a scope digest mismatch`);
+  }
+  const expected = sha256(bytes.subarray(0, 52 + payloadLength));
+  if (!expected.equals(bytes.subarray(52 + payloadLength))) {
+    throw new StateStoreCorruptionError(`snapshot generation ${generation} has a bad checksum`);
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(bytes.subarray(52, 52 + payloadLength).toString("utf8"));
+  } catch (error) {
+    throw new StateStoreCorruptionError(`snapshot generation ${generation} has invalid JSON`, { cause: error });
+  }
+  if (!isSnapshotPayload(decoded)) {
+    throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid state payload`);
+  }
+  return decoded as SnapshotPayload<T>;
+}
+
+function readWal(
+  filePath: string,
+  scopeDigest: Buffer,
+  generation: number,
+  snapshotSequence: number,
+): { records: StateStoreRecord[]; lastRecordSequence: number } {
+  let bytes: Buffer;
+  try {
+    bytes = fs.readFileSync(filePath);
+  } catch (error) {
+    throw new StateStoreCorruptionError(`cannot read WAL generation ${generation}`, { cause: error });
+  }
+  verifyWalHeader(bytes, scopeDigest, generation);
+  const records: StateStoreRecord[] = [];
+  let offset = WAL_HEADER_BYTES;
+  let sequence = snapshotSequence;
+  while (offset < bytes.length) {
+    const parsed = decodeFrame(bytes, offset);
+    if (parsed.kind === "torn") {
+      truncateWal(filePath, offset);
+      break;
+    }
+    if (parsed.record.sequence !== sequence + 1) {
+      throw new StateStoreCorruptionError(`WAL generation ${generation} has non-contiguous record sequence`);
+    }
+    records.push(parsed.record);
+    sequence = parsed.record.sequence;
+    offset = parsed.nextOffset;
+  }
+  return { records, lastRecordSequence: sequence };
+}
+
+function verifyWalHeader(bytes: Buffer, scopeDigest: Buffer, generation: number): void {
+  if (bytes.length < WAL_HEADER_BYTES) {
+    throw new StateStoreCorruptionError(`WAL generation ${generation} has a torn header`);
+  }
+  if (!bytes.subarray(0, 8).equals(WAL_MAGIC)) {
+    throw new StateStoreCorruptionError(`WAL generation ${generation} has an invalid magic`);
+  }
+  if (readU64(bytes, 8) !== generation) {
+    throw new StateStoreCorruptionError(`WAL generation ${generation} has a generation mismatch`);
+  }
+  if (!bytes.subarray(16, 48).equals(scopeDigest)) {
+    throw new StateStoreCorruptionError(`WAL generation ${generation} has a scope digest mismatch`);
+  }
+  if (!sha256(bytes.subarray(0, 48)).equals(bytes.subarray(48, 80))) {
+    throw new StateStoreCorruptionError(`WAL generation ${generation} has a bad header checksum`);
+  }
+}
+
+type DecodedFrame = { kind: "frame"; record: StateStoreRecord; nextOffset: number } | { kind: "torn" };
+
+function decodeFrame(bytes: Buffer, offset: number): DecodedFrame {
+  if (bytes.length - offset < FRAME_PREFIX_BYTES) return { kind: "torn" };
+  if (bytes.readUInt32BE(offset) !== FRAME_MAGIC) {
+    throw new StateStoreCorruptionError("WAL has an invalid frame magic");
+  }
+  const frameLength = bytes.readUInt32BE(offset + 4);
+  if (frameLength < FRAME_FIXED_BODY_BYTES || frameLength > MAX_FRAME_BYTES) {
+    throw new StateStoreCorruptionError("WAL has an invalid frame length");
+  }
+  const available = bytes.length - offset - FRAME_PREFIX_BYTES;
+  if (available < frameLength) {
+    // A torn write cannot supply the complete declared payload. If it does,
+    // but the outer length disagrees, the length prefix was corrupted rather
+    // than the writer being interrupted.
+    if (available >= 16) {
+      const declaredPayloadLength = bytes.readUInt32BE(offset + FRAME_PREFIX_BYTES + 12);
+      const declaredFrameLength = FRAME_FIXED_BODY_BYTES + declaredPayloadLength;
+      if (declaredFrameLength <= available && declaredFrameLength !== frameLength) {
+        throw new StateStoreCorruptionError("WAL frame length prefix is corrupt");
+      }
+    }
+    return { kind: "torn" };
+  }
+  const body = bytes.subarray(offset + FRAME_PREFIX_BYTES, offset + FRAME_PREFIX_BYTES + frameLength);
+  const payloadLength = body.readUInt32BE(12);
+  if (frameLength !== FRAME_FIXED_BODY_BYTES + payloadLength) {
+    throw new StateStoreCorruptionError("WAL frame length does not match payload length");
+  }
+  const payload = body.subarray(16, 16 + payloadLength);
+  const storedCrc = body.readUInt32BE(16 + payloadLength);
+  const crcBytes = body.subarray(0, 16 + payloadLength);
+  if (crc32c(crcBytes) !== storedCrc) {
+    throw new StateStoreCorruptionError("WAL frame has a bad CRC32C");
+  }
+  const checksumInput = body.subarray(0, 20 + payloadLength);
+  if (!sha256(checksumInput).equals(body.subarray(20 + payloadLength))) {
+    throw new StateStoreCorruptionError("WAL frame has a bad SHA-256 checksum");
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(payload.toString("utf8"));
+  } catch (error) {
+    throw new StateStoreCorruptionError("WAL frame has invalid JSON", { cause: error });
+  }
+  return {
+    kind: "frame",
+    record: { sequence: readU64(body, 0), type: body.readUInt16BE(8), flags: body.readUInt16BE(10), payload: value },
+    nextOffset: offset + FRAME_PREFIX_BYTES + frameLength,
+  };
+}
+
+function encodeSnapshot<T>(generation: number, scopeDigest: Buffer, payload: SnapshotPayload<T>): Buffer {
+  const data = Buffer.from(canonicalJson(payload), "utf8");
+  const header = Buffer.alloc(52);
+  SNAPSHOT_MAGIC.copy(header, 0);
+  writeU64(header, generation, 8);
+  header.writeUInt32BE(data.length, 16);
+  scopeDigest.copy(header, 20);
+  return Buffer.concat([header, data, sha256(Buffer.concat([header, data]))]);
+}
+
+function encodeWalHeader(generation: number, scopeDigest: Buffer): Buffer {
+  const header = Buffer.alloc(48);
+  WAL_MAGIC.copy(header, 0);
+  writeU64(header, generation, 8);
+  scopeDigest.copy(header, 16);
+  return Buffer.concat([header, sha256(header)]);
+}
+
+function encodeFrame(record: StateStoreRecord): Buffer {
+  const payload = Buffer.from(canonicalJson(record.payload), "utf8");
+  if (payload.length > MAX_FRAME_BYTES - FRAME_FIXED_BODY_BYTES) {
+    throw new Error("state-store: record payload exceeds WAL frame limit");
+  }
+  const withoutChecksums = Buffer.alloc(16 + payload.length);
+  writeU64(withoutChecksums, record.sequence, 0);
+  withoutChecksums.writeUInt16BE(record.type, 8);
+  withoutChecksums.writeUInt16BE(record.flags, 10);
+  withoutChecksums.writeUInt32BE(payload.length, 12);
+  payload.copy(withoutChecksums, 16);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32c(withoutChecksums), 0);
+  const checksum = sha256(Buffer.concat([withoutChecksums, crc]));
+  const prefix = Buffer.alloc(FRAME_PREFIX_BYTES);
+  prefix.writeUInt32BE(FRAME_MAGIC, 0);
+  prefix.writeUInt32BE(withoutChecksums.length + crc.length + checksum.length, 4);
+  return Buffer.concat([prefix, withoutChecksums, crc, checksum]);
+}
+
+function appendDurably(filePath: string, bytes: Buffer): void {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(filePath, "a");
+    writeAllSync(fd, bytes);
+    fs.fdatasyncSync(fd);
+  } catch (error) {
+    throw new Error(`state-store: append and fdatasync failed for ${filePath}`, { cause: error });
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function writeNewDurably(filePath: string, bytes: Buffer): void {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(filePath, "wx");
+    writeAllSync(fd, bytes);
+    fs.fdatasyncSync(fd);
+  } catch (error) {
+    throw new Error(`state-store: durable create failed for ${filePath}`, { cause: error });
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function writeDurableTempThenRename(dir: string, destination: string, bytes: Buffer): void {
+  const temporary = path.join(dir, `.${path.basename(destination)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(temporary, "wx");
+    writeAllSync(fd, bytes);
+    fs.fdatasyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(temporary, destination);
+    fsyncDirectory(dir);
+  } catch (error) {
+    if (fd !== undefined) fs.closeSync(fd);
+    try { fs.rmSync(temporary, { force: true }); } catch { /* preserve the primary durable-write error */ }
+    throw new Error(`state-store: snapshot write/rename failed for ${destination}`, { cause: error });
+  }
+}
+
+function writeCurrentPointer(dir: string, generation: number): void {
+  const pointer = path.join(dir, "current");
+  writeDurableTempThenRename(dir, pointer, Buffer.from(`${generation}\n`, "ascii"));
+}
+
+function writeAllSync(fd: number, bytes: Buffer): void {
+  let offset = 0;
+  while (offset < bytes.length) {
+    const written = fs.writeSync(fd, bytes, offset, bytes.length - offset);
+    if (written <= 0) throw new Error("state-store: short write made no progress");
+    offset += written;
+  }
+}
+
+function withScopeLock<T>(dir: string, action: () => T): T {
+  const lockPath = path.join(dir, "append.lock");
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let fd: number | undefined;
+  while (fd === undefined) {
+    try {
+      fd = fs.openSync(lockPath, "wx");
+      fs.writeFileSync(fd, String(process.pid));
+      fs.fdatasyncSync(fd);
+    } catch (error) {
+      if (!isAlreadyExists(error)) {
+        throw new StateStoreLockError(`cannot acquire ${lockPath}`, { cause: error });
+      }
+      if (removeDeadLock(lockPath)) continue;
+      if (Date.now() >= deadline) {
+        throw new StateStoreLockError(`timed out acquiring ${lockPath}`);
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+    }
+  }
+  let result: T | undefined;
+  let actionError: unknown;
+  try {
+    result = action();
+  } catch (error) {
+    actionError = error;
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.unlinkSync(lockPath);
+  } catch (error) {
+    throw new StateStoreLockError(`cannot release ${lockPath}`, { cause: error });
+  }
+  if (actionError !== undefined) throw actionError;
+  return result as T;
+}
+
+function removeDeadLock(lockPath: string): boolean {
+  let pid: number;
+  try {
+    pid = Number(fs.readFileSync(lockPath, "utf8"));
+  } catch (error) {
+    return isMissing(error);
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") return false;
+  }
+  try {
+    fs.unlinkSync(lockPath);
+    return true;
+  } catch (error) {
+    return isMissing(error);
+  }
+}
+
+function truncateWal(filePath: string, boundary: number): void {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(filePath, "r+");
+    fs.ftruncateSync(fd, boundary);
+    fs.fdatasyncSync(fd);
+  } catch (error) {
+    throw new Error(`state-store: failed to truncate torn WAL tail at ${filePath}`, { cause: error });
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function fsyncDirectory(dir: string): void {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(dir, "r");
+    fs.fsyncSync(fd);
+  } catch (error) {
+    if (isUnsupportedDirectoryFsync(error)) return;
+    throw new Error(`state-store: directory fsync failed for ${dir}`, { cause: error });
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function stateDirectory(rootDir: string, scopeDigest: Buffer): string {
+  return path.join(rootDir, "sync-state-v3", scopeDigest.toString("hex"));
+}
+
+function snapshotPath(dir: string, generation: number): string {
+  return path.join(dir, `snapshot-${generation}.bin`);
+}
+
+function walPath(dir: string, generation: number): string {
+  return path.join(dir, `wal-${generation}.bin`);
+}
+
+function highestGenerationOnDisk(dir: string): number {
+  return fs.readdirSync(dir)
+    .map((name) => /^(?:snapshot|wal)-(\d+)\.bin$/.exec(name)?.[1])
+    .filter((value): value is string => value !== undefined)
+    .map(Number)
+    .filter(Number.isSafeInteger)
+    .reduce((highest, generation) => Math.max(highest, generation), 0);
+}
+
+function pruneGenerations(dir: string, retain: number[]): void {
+  const retained = new Set(retain);
+  for (const name of fs.readdirSync(dir)) {
+    const match = /^(?:snapshot|wal)-(\d+)\.bin$/.exec(name);
+    if (!match) continue;
+    const generation = Number(match[1]);
+    if (!retained.has(generation)) {
+      try {
+        fs.unlinkSync(path.join(dir, name));
+      } catch (error) {
+        throw new Error(`state-store: failed to prune obsolete generation ${generation}`, { cause: error });
+      }
+    }
+  }
+  fsyncDirectory(dir);
+}
+
+function cleanupUnpublishedInitialGeneration(dir: string): void {
+  if (fs.existsSync(path.join(dir, "current"))) return;
+  const initialSnapshot = snapshotPath(dir, 1);
+  const initialWal = walPath(dir, 1);
+  if (fs.existsSync(initialSnapshot) && !fs.existsSync(initialWal)) {
+    try {
+      fs.unlinkSync(initialSnapshot);
+      fsyncDirectory(dir);
+    } catch (error) {
+      throw new Error("state-store: failed to clean unpublished initial snapshot", { cause: error });
+    }
+  }
+  if (!fs.existsSync(initialSnapshot) && fs.existsSync(initialWal)) {
+    try {
+      fs.unlinkSync(initialWal);
+      fsyncDirectory(dir);
+    } catch (error) {
+      throw new Error("state-store: failed to clean unpublished initial WAL", { cause: error });
+    }
+  }
+}
+
+function digestScope(scopeId: string): Buffer {
+  return sha256(Buffer.from(scopeId, "utf8"));
+}
+
+function sha256(value: Buffer): Buffer {
+  return crypto.createHash("sha256").update(value).digest();
+}
+
+function writeU64(target: Buffer, value: number, offset: number): void {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("state-store: invalid u64 value");
+  target.writeBigUInt64BE(BigInt(value), offset);
+}
+
+function readU64(source: Buffer, offset: number): number {
+  const value = source.readBigUInt64BE(offset);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new StateStoreCorruptionError("u64 exceeds JavaScript safe integer range");
+  return Number(value);
+}
+
+function assertUint16(value: number, name: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffff) throw new Error(`state-store: ${name} must be a u16`);
+}
+
+function isSnapshotPayload(value: unknown): value is SnapshotPayload<unknown> {
+  return typeof value === "object" && value !== null &&
+    Number.isSafeInteger((value as { lastRecordSequence?: unknown }).lastRecordSequence) &&
+    (value as { lastRecordSequence: number }).lastRecordSequence >= 0 &&
+    Object.hasOwn(value, "state");
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function isAlreadyExists(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as NodeJS.ErrnoException).code === "EEXIST";
+}
+
+function isUnsupportedDirectoryFsync(error: unknown): boolean {
+  const code = typeof error === "object" && error !== null
+    ? (error as NodeJS.ErrnoException).code
+    : undefined;
+  return code === "EINVAL" || code === "ENOTSUP" || code === "EOPNOTSUPP" || code === "EPERM";
+}
+
+/** RFC 8785-compatible JSON for the plain JSON values persisted by this store. */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("state-store: JSON numbers must be finite");
+    return Object.is(value, -0) ? "0" : JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item, index) => {
+      if (!(index in value) || item === undefined) throw new Error("state-store: JSON arrays cannot be sparse or undefined");
+      return canonicalJson(item);
+    }).join(",")}]`;
+  }
+  if (typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype) {
+    const object = value as Record<string, unknown>;
+    return `{${Object.keys(object).sort().map((key) => {
+      const item = object[key];
+      if (item === undefined) throw new Error(`state-store: JSON property ${key} is undefined`);
+      return `${JSON.stringify(key)}:${canonicalJson(item)}`;
+    }).join(",")}}`;
+  }
+  throw new Error("state-store: payload must be a plain JSON value");
+}
+
+// Castagnoli CRC32C, tableless to avoid a new dependency in the hot path.
+function crc32c(bytes: Buffer): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ (0x82f63b78 & -(crc & 1));
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}