Class WalCheckpointValve

src/db/wal-valve.ts:80–290

}

export class WalCheckpointValve {
  private timer: ReturnType<typeof setInterval> | null = null;
  private inflight: Promise<void> | null = null;
  /** Writer pause in progress (hard cap breached): passes loop until a full backfill. */
  private pause: Promise<void> | null = null;
  /**
   * WAL file size observed when a checkpoint last reported the ENTIRE WAL
   * backfilled. Growth is measured against this baseline — see the header
   * comment for why absolute size cannot be used.
   */
  private sizeAtLastFullBackfill = 0;
  private readonly softBytes: number;
  private readonly hardBytes: number;
  private readonly fileCapBytes: number;

  /**
   * Futility latch: consecutive backfill give-ups (a reader pinning the WAL)
   * disable further writer pauses for a cooldown, so a pinned phase degrades
   * to the pre-valve behavior (unbounded WAL, folded when the pinner exits)
   * instead of burning a 20-pass checkpoint attempt — each pass a worker
   * thread + fresh connection — at EVERY over-cap boundary. That churn is
   * what turned a pinned kernel-scale resolution from slow into OOM-killed
   * (§7a.1 run 1: 22GB WAL, exit 137 at an envelope the pre-fix build
   * survived).
   */
  private consecutiveGiveUps = 0;
  private futileUntil = 0;

  constructor(
    private readonly db: DatabaseConnection,
    softMb: number = resolveWalValveMb(process.env.CODEGRAPH_WAL_VALVE_MB),
    private readonly intervalMs: number = CHECK_INTERVAL_MS,
    log: (msg: string) => void = () => {}
  ) {
    this.softBytes = softMb * 1024 * 1024;
    this.hardBytes = this.softBytes * HARD_CAP_MULTIPLIER;
    this.fileCapBytes = this.softBytes * FILE_CAP_MULTIPLIER;
    // CODEGRAPH_WAL_VALVE_DEBUG=1 surfaces valve decisions to stderr without
    // needing the caller's verbose plumbing — the observability gap that let
    // §7a.1 run 1 fail silently (give-ups were verbose-gated and invisible).
    this.log = process.env.CODEGRAPH_WAL_VALVE_DEBUG
      ? (m) => console.error(`[wal-valve] ${m}`)
      : log;
  }

  private readonly log: (msg: string) => void;

  private mb(n: number): string {
    return `${Math.round(n / 1024 / 1024)}MB`;
  }

  /** Un-backfilled growth estimate: bytes the WAL has grown past the last full backfill. */
  private growthBytes(): number {
    return this.db.getWalSizeBytes() - this.sizeAtLastFullBackfill;
  }

  /** Begin watching the WAL. Idempotent; the timer never holds the loop open. */
  start(): void {