@indigoai-us/hq-cloud 6.14.50 → 6.15.1

package/src/sync/state-store.ts

@@ -1,727 +0,0 @@
-/**
- * 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;
-}