dsh-hashline-edit 0.2.0 → 0.2.2

package/src/store-janitor.ts

@@ -0,0 +1,539 @@
+/**
+ * The store janitor — the store's PERIODIC maintenance item, wired to the lifecycle events that are
+ * OFF the tool-call hot path. Ticket #90; the open-time half is `src/hash-store.ts`'s stamp-gated
+ * sweep, which this module REUSES rather than restates (see the exported `*_SQL` predicates there).
+ *
+ * WHAT ONE RUN DOES, in order, and why that order:
+ * 1. THROTTLE — `due(db, JANITOR_META_KEY, intervalMs, now)`, the primitives the served-mirror
+ *    prune already uses (#87c). Not due means the run ends here, having issued no DELETE and no
+ *    `PRAGMA quick_check`. The interval is resolved from the shared config ladder
+ *    (`src/store-config.ts`), defaulting to a day.
+ * 2. GC — foreign-generation, dangling and expired rows, deleted in statements of at most
+ *    `batchSize` rows. Expiry covers BOTH terminal states (ADR-0045): a retired lease past its
+ *    1-hour grace and an ACTIVE lease past the 7-day session TTL.
+ *    Batching is about HOLD TIME, not statement count: one unbounded DELETE scans and holds the write
+ *    lock for its whole scan, so a rival writer waits on a maintenance pass; a loop of bounded
+ *    statements releases the lock between batches and lets a rival interleave. The batch width
+ *    defaults to 64, the width the snapshot store already deletes in (`STAT_BATCH`).
+ * 3. MARK — `markRun` records the run, and it is written BEFORE the deep check because a
+ *    detected failure may close this connection (step 4).
+ * 4. DEEP CHECK — the open path's own `PRAGMA quick_check` (`isHealthy`, never reimplemented), on a
+ *    store the fast path no longer checks (PR #101 replaced it there with the header smoke check).
+ *    A failing check routes into `healUnhealthyStore`, the janitor's orchestration over the one
+ *    `quarantineStore` primitive; the open path's own recovery is its other caller.
+ *
+ * NO CHECKPOINT HERE, deliberately: `shutdownDb` owns `PRAGMA wal_checkpoint(TRUNCATE)`, registered
+ * once by `openStore` on `exit`, `SIGINT` and `SIGTERM`. The janitor therefore adds no second
+ * checkpoint site and no second owner of the same WAL; its writes ride the WAL and are truncated by
+ * the close path that already truncates it, and `wal_checkpoint(TRUNCATE)` on an already-truncated
+ * WAL is a no-op. One writer, one checkpoint, measured on close — see the report for the WAL numbers.
+ *
+ * THE #90 / #100 BOUNDARY, stated here in this module's own header. Issue #100's three clauses, its
+ * own words: "not detected at open, not quarantined at use, not healed on reopen."
+ * - CLOSED HERE: "not detected at open" — the fast path stopped running `PRAGMA quick_check` (#87c),
+ *   so page-level damage was detected by nothing at all; this janitor detects it periodically, on a
+ *   store the fast path accepts.
+ * - CLOSED HERE: "not healed on reopen" — a detected failure routes into the SAME quarantine-and-
+ *   rebuild the open path performs (`healUnhealthyStore`), so the store is rebuilt rather than left
+ *   damaged until someone deletes it by hand.
+ * - LEFT TO #100: "not quarantined at use" — nothing triggers on the FIRST FAILING STATEMENT. A
+ *   statement that hits a damaged page still surfaces its own error and leaves the file damaged until
+ *   the next janitor run. That is a USE-TIME trigger, #100's own scope; this module must not grow a
+ *   half-implemented one, and it does not.
+ */
+
+import type { DatabaseSync } from "node:sqlite";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  DANGLING_LEASE_SQL,
+  EXPIRED_ACTIVE_LEASE_SQL,
+  FOREIGN_GENERATION_LEASE_SQL,
+  FOREIGN_GENERATION_SNAPSHOT_SQL,
+  ORPHAN_LINEAGE_SQL,
+  healUnhealthyStore,
+  isHealthy,
+  loadHashStore,
+  servedLeaseExpiryCutoff,
+} from "./hash-store.js";
+import { isBusyError, markRun, due, withBusyRetry } from "./store-kernel/index.js";
+import { resolveStoreJanitorSettings, type StoreJanitorSettings } from "./store-kernel/settings.js";
+import type { ConfigOnWarn } from "./json-config.js";
+import { VACUUM_RETIRED_PIN_MS } from "./snapshot-store";
+import { diagnosticsLogPath, reportDiagnostic, reportInfo, reportWarning } from "./diagnostics.js";
+import {
+  JANITOR_WARNING_PREFIX,
+  formatJanitorWarning,
+  type JanitorWarning,
+} from "./store-janitor-warning.js";
+
+/**
+ * The `meta` key recording when the janitor last ran — the janitor's OWN row, exactly as the stamp
+ * comment in `src/hash-store.ts` requires: due-ness instants never enter the store's identity stamp.
+ */
+export const JANITOR_META_KEY = "janitor_at";
+
+/**
+ * The lifecycle events the janitor is wired to: the two that are OFF the tool-call hot path.
+ * `session_shutdown` (reason quit|reload|new|resume|fork) had no consumer in this repo before this
+ * module, so it is wired deliberately: it is the one event that fires while a session's work is
+ * finished and before the runtime is torn down, which is where a maintenance pass belongs.
+ *
+ * NEVER SUBSCRIBE THIS JANITOR TO — the hot path, where a janitor run would be paid by every tool
+ * call of the session and could hold the write lock a call is waiting on:
+ *   `tool_call`, `tool_result`, `tool_execution_start`, `tool_execution_update`,
+ *   `tool_execution_end`, `context`, `before_provider_request`.
+ * These are forbidden, not merely unused: a run there is the latency regression #90 exists to avoid,
+ * so a future reader adding one must see that it is prohibited rather than think it is untried.
+ * A background timer is not an option either: the extension API exposes no idle timer and no
+ * `deactivate` event, so a timer-based trigger is impossible rather than unimplemented.
+ */
+export const JANITOR_EVENTS = ["session_start", "session_shutdown"] as const;
+
+/** The rows one janitor run removed, per family. */
+interface JanitorDeletions {
+  readonly snapshots: number;
+  readonly lineage: number;
+  readonly leases: number;
+  /** Lease rows removed for expiry: active past the session TTL plus retired past the grace. */
+  readonly expiredLeases: number;
+}
+
+/**
+ * What the compaction step did (ADR-0046). `freeBytesBefore` is the reclaimable page space the
+ * sweep left behind; `reclaimedBytes` is the logical file space the VACUUM actually returned.
+ * `reason` is present exactly when `ran` is false, so a caller can tell "nothing to do" from
+ * "contended" from "failed" without parsing prose.
+ */
+interface CompactionOutcome {
+  readonly ran: boolean;
+  readonly reason?:
+    | "skipped"
+    | "in-transaction"
+    | "no-free-pages"
+    | "below-threshold"
+    | "busy"
+    | "failed";
+  readonly freeBytesBefore: number;
+  readonly reclaimedBytes: number;
+  /** The failure text when `reason` is `"failed"`; the log line carries the same message. */
+  readonly error?: string;
+}
+
+export interface JanitorOutcome {
+  /** Whether the run happened at all. `false` means the throttle or the mode said no. */
+  readonly ran: boolean;
+  readonly reason?: "off" | "throttled";
+  readonly deleted: JanitorDeletions;
+  readonly compacted: CompactionOutcome;
+  /** Whether the run's deep check found the store damaged (only ever set on a run that happened). */
+  readonly deepCheckFailed: boolean;
+  /** Whether the store was handed to the open path's quarantine-and-rebuild. */
+  readonly rebuilt: boolean;
+}
+
+const NOTHING_DELETED: JanitorDeletions = {
+  snapshots: 0,
+  lineage: 0,
+  leases: 0,
+  expiredLeases: 0,
+};
+
+const NOTHING_COMPACTED: CompactionOutcome = {
+  ran: false,
+  reason: "skipped",
+  freeBytesBefore: 0,
+  reclaimedBytes: 0,
+};
+
+function skipped(reason: "off" | "throttled"): JanitorOutcome {
+  return {
+    ran: false,
+    reason,
+    deleted: NOTHING_DELETED,
+    compacted: NOTHING_COMPACTED,
+    deepCheckFailed: false,
+    rebuilt: false,
+  };
+}
+
+/**
+ * Delete every row a predicate names, at most `batchSize` rows per statement, returning the count.
+ * The statement is re-prepared per batch so no state is held between them, and each batch carries
+ * the store's own busy budget (`withBusyRetry`) rather than the janitor inventing a retry.
+ *
+ * WHY `rowid IN (SELECT rowid ... LIMIT ?)`: `DELETE ... LIMIT` needs a SQLite build option this
+ * runtime does not guarantee, while every table here is an ordinary rowid table, so the bounded
+ * delete is spelled with a subquery instead. `table` admits only `JanitorTable` members, so the
+ * two interpolated table slots cannot name a table no call site passes (#105 rider).
+ *
+ * A short final batch ends the loop: no statement re-reads rows it could have deleted twice, because
+ * nothing in this store re-creates foreign-generation or expired rows while a janitor run is open.
+ */
+/** The only tables the janitor's batched deletes may name (#105 rider). */
+type JanitorTable = "file_snapshots" | "line_lineage" | "served_leases";
+
+function deleteInBatches(
+  db: DatabaseSync,
+  table: JanitorTable,
+  predicate: string,
+  params: readonly (string | number)[],
+  batchSize: number,
+): number {
+  const sql = `DELETE FROM ${table} WHERE rowid IN (SELECT rowid FROM ${table} WHERE ${predicate} LIMIT ?)`;
+  let deleted = 0;
+  for (;;) {
+    const changes = withBusyRetry(() => {
+      const result = db.prepare(sql).run(...params, batchSize);
+      return Number(result.changes);
+    });
+    deleted += changes;
+    if (changes < batchSize) return deleted;
+  }
+}
+
+/**
+ * ONE janitor run against an OPEN store, with `now` injected so the throttle is judged from the
+ * caller's clock rather than from whatever the host's is doing. Sync on purpose: every statement it
+ * issues is synchronous, so a caller can drive it from a test without touching the event loop.
+ */
+export function runJanitor(input: {
+  readonly db: DatabaseSync;
+  readonly now: number;
+  readonly settings: StoreJanitorSettings;
+  /**
+   * Injection seam for the reclaim floor (ADR-0046): tests use a small value to exercise a VACUUM
+   * on a tiny store. Production omits it and takes `STORE_COMPACT_MIN_FREE_BYTES`.
+   */
+  readonly compactMinFreeBytes?: number;
+}): JanitorOutcome {
+  const { db, now, settings } = input;
+  if (settings.mode === "off") return skipped("off");
+  if (!due(db, JANITOR_META_KEY, settings.intervalMs, now)) return skipped("throttled");
+
+  const batchSize = settings.batchSize;
+  // WHY: the generation family, in the sweep's own order: leases are swept before the snapshots they
+  // WHY: name (a lease whose snapshot a later batch removes is swept as dangling), and lineage after
+  // WHY: the snapshots that cascade it. All four predicates are the sweep's, imported — not restated.
+  const deletions = collectGarbage(db, now, batchSize);
+  // WHY: (ADR-0046) a GC pass leaves free pages in the file; compaction is the only step that gives
+  // WHY: them back to the filesystem. It runs after the sweep, in autocommit, on this maintenance
+  // WHY: boundary — never inside a read/edit transaction — and it defers rather than waits when a
+  // WHY: rival writer holds the store. A failed sweep skips it: a damaged store is the deep check's
+  // WHY: business, and VACUUM on damage can only fail again.
+  const compacted =
+    deletions === undefined
+      ? NOTHING_COMPACTED
+      : compactStore(db, input.compactMinFreeBytes ?? STORE_COMPACT_MIN_FREE_BYTES);
+
+  // WHY: the mark is written only by a run whose GC COMPLETED: the primitives' contract is that
+  // WHY: "ran" means "did something", and a sweep that threw did not — so a failed sweep stays due
+  // WHY: and is retried at the next lifecycle event instead of being hidden for a full interval.
+  // WHY: the mark precedes the deep check because a detected failure may close this connection.
+  if (deletions !== undefined) markRun(db, JANITOR_META_KEY, now);
+
+  // WHY: the deep check runs even when the GC threw, and that ordering is the point of ticket #100:
+  // WHY: a store whose pages are damaged is exactly a store the GC may fail on, and detection must
+  // WHY: not be conditional on the cleanup it is meant to trigger a heal for.
+  return {
+    ran: true,
+    deleted: deletions ?? NOTHING_DELETED,
+    compacted,
+    deepCheckFailed: !isHealthy(db),
+    rebuilt: false,
+  };
+}
+
+/**
+ * The janitor's cleanup half: foreign-generation and expired rows, in bounded batches. `undefined`
+ * means a statement threw, which the caller reports as "nothing was removed" — a store damaged
+ * enough to fail a DELETE is the case the deep check exists for, so the failure is swallowed here
+ * and reported there rather than thrown out of a lifecycle hook.
+ */
+function collectGarbage(
+  db: DatabaseSync,
+  now: number,
+  batchSize: number,
+): JanitorDeletions | undefined {
+  try {
+    const leases = deleteInBatches(
+      db,
+      "served_leases",
+      FOREIGN_GENERATION_LEASE_SQL,
+      [],
+      batchSize,
+    );
+    const snapshots = deleteInBatches(
+      db,
+      "file_snapshots",
+      FOREIGN_GENERATION_SNAPSHOT_SQL,
+      [],
+      batchSize,
+    );
+    const lineage = deleteInBatches(db, "line_lineage", ORPHAN_LINEAGE_SQL, [], batchSize);
+    const dangling = deleteInBatches(db, "served_leases", DANGLING_LEASE_SQL, [], batchSize);
+    // WHY: (ADR-0045) hard expiry makes an ACTIVE lease past the session TTL a dead row: it has no
+    // WHY: resolution authority and no pin authority, but it still inflated every lease index and the
+    // WHY: vacuum's per-snapshot EXISTS probe. It is deleted AFTER the dangling sweep (a dead lease
+    // WHY: whose snapshot was evicted is already gone) and in the same bounded, off-path manner.
+    const expiredActive = deleteInBatches(
+      db,
+      "served_leases",
+      EXPIRED_ACTIVE_LEASE_SQL,
+      [servedLeaseExpiryCutoff(now)],
+      batchSize,
+    );
+    const expiredRetired = deleteInBatches(
+      db,
+      "served_leases",
+      "retired_at IS NOT NULL AND retired_at < ?",
+      [now - VACUUM_RETIRED_PIN_MS],
+      batchSize,
+    );
+    return {
+      snapshots,
+      lineage,
+      leases: leases + dangling,
+      expiredLeases: expiredActive + expiredRetired,
+    };
+  } catch (error) {
+    // SAFETY: a failed sweep removes nothing and is retried by the next due run; the deep check below
+    // SAFETY: is what decides whether this store needs the open path's recovery instead.
+    reportDiagnostic("store-janitor", "[store-janitor] GC pass failed:", error);
+    return undefined;
+  }
+}
+
+/**
+ * WHY these numbers: a VACUUM rewrites the whole database, so its cost scales with the FILE while its
+ * benefit scales with the FREE PAGES. A quarter-free file amortises the rewrite; below that, a big
+ * store would be rewritten for a few reclaimed pages. The megabyte floor keeps a tiny store from
+ * paying a rewrite for one free page, and the 100 ms start budget means a contended compaction
+ * defers to the next maintenance pass instead of stalling a session behind a rival writer.
+ */
+const STORE_COMPACT_MIN_FREE_RATIO = 0.25;
+const STORE_COMPACT_MIN_FREE_BYTES = 1024 * 1024;
+const STORE_COMPACT_BUSY_TIMEOUT_MS = 100;
+
+function pragmaNumber(db: DatabaseSync, sql: string): number {
+  const row = db.prepare(sql).get() as Record<string, unknown> | undefined;
+  const value = row === undefined ? undefined : Object.values(row)[0];
+  return typeof value === "number" ? value : 0;
+}
+
+/**
+ * Reclaim free pages into the file after a maintenance sweep (ADR-0046).
+ *
+ * One `VACUUM` in autocommit, gated on the reclaimable share, with a SHORT busy budget for STARTING
+ * it: if a rival writer holds the store the pass returns `busy` and the next maintenance pass
+ * retries. The VACUUM itself is not interruptible once started (SQLite owns it); the janitor never
+ * runs on the tool path, so a tool call never triggers this rewrite, and the store's existing busy
+ * budget covers a concurrent writer for the duration. Any failure is reported through the OUTCOME
+ * and never thrown out of a lifecycle hook.
+ *
+ * WHY this function writes NOTHING itself — neither console nor log: a console call here cannot see
+ * the per-event surface map, so it would print on `session_shutdown` too, where the console is
+ * already torn down (#199). The warning pipeline renders this outcome on the surface its event owns,
+ * and the record it writes carries the reason and the error text.
+ */
+function compactStore(db: DatabaseSync, minFreeBytes: number): CompactionOutcome {
+  // WHY: VACUUM cannot run inside a transaction. The janitor runs in autocommit, so this is a
+  // WHY: defensive deferral for a caller that hands in a transaction, not an expected path.
+  // SAFETY: node:sqlite exposes `isTransaction` at runtime although DatabaseSync's public type omits it;
+  // SAFETY: a missing flag reads as autocommit, which is the janitor's own normal state.
+  const inTransaction = (db as unknown as { isTransaction?: boolean }).isTransaction === true;
+  if (inTransaction) {
+    return { ran: false, reason: "in-transaction", freeBytesBefore: 0, reclaimedBytes: 0 };
+  }
+  const pageSize = pragmaNumber(db, "PRAGMA page_size");
+  const pagesBefore = pragmaNumber(db, "PRAGMA page_count");
+  const freePages = pragmaNumber(db, "PRAGMA freelist_count");
+  const freeBytesBefore = freePages * pageSize;
+  if (freePages === 0) {
+    return { ran: false, reason: "no-free-pages", freeBytesBefore: 0, reclaimedBytes: 0 };
+  }
+  const totalBytes = pagesBefore * pageSize;
+  if (
+    freeBytesBefore < minFreeBytes ||
+    (totalBytes > 0 && freeBytesBefore / totalBytes < STORE_COMPACT_MIN_FREE_RATIO)
+  ) {
+    return { ran: false, reason: "below-threshold", freeBytesBefore, reclaimedBytes: 0 };
+  }
+
+  const previousTimeout = pragmaNumber(db, "PRAGMA busy_timeout");
+  try {
+    db.exec(`PRAGMA busy_timeout = ${STORE_COMPACT_BUSY_TIMEOUT_MS}`);
+    db.exec("VACUUM");
+  } catch (error) {
+    if (isBusyError(error)) {
+      return { ran: false, reason: "busy", freeBytesBefore, reclaimedBytes: 0 };
+    }
+    return {
+      ran: false,
+      reason: "failed",
+      freeBytesBefore,
+      reclaimedBytes: 0,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    try {
+      db.exec(`PRAGMA busy_timeout = ${previousTimeout}`);
+    } catch (error) {
+      // SAFETY: best-effort restore — the compaction outcome is authoritative, and the next open
+      // SAFETY: re-applies the store's own busy timeout. Log-only, never the console: this catch is
+      // SAFETY: reachable from the shutdown surface, where the console is already torn down (#199).
+      reportDiagnostic("store-janitor", "[store-janitor] failed to restore busy timeout:", error);
+    }
+  }
+  const pagesAfter = pragmaNumber(db, "PRAGMA page_count");
+  const reclaimedBytes = Math.max(0, (pagesBefore - pagesAfter) * pageSize);
+  return { ran: true, freeBytesBefore, reclaimedBytes };
+}
+
+export interface JanitorPassOptions {
+  /** The directory the config ladder resolves against; defaults to the process cwd. */
+  readonly cwd?: string;
+  /** The instant the throttle and the retirement grace are judged at; defaults to `Date.now()`. */
+  readonly now?: number;
+  /** Resolved knobs, for a caller that already read them (and for tests). */
+  readonly settings?: StoreJanitorSettings;
+  /** The open store, for a caller that already holds one (and for tests). */
+  readonly db?: DatabaseSync;
+  readonly onWarn?: ConfigOnWarn;
+  /** The heal step, injectable so a test can observe a detected failure without damaging a store. */
+  readonly heal?: () => Promise<boolean>;
+}
+
+/**
+ * A full janitor pass: resolve the knobs, open the store if the caller has none, run once, and hand a
+ * damaged store to the open path's recovery. Never throws for a store problem — the caller here is a
+ * lifecycle hook, and a maintenance item must not break the session it runs in.
+ */
+export async function janitorPass(options: JanitorPassOptions = {}): Promise<JanitorOutcome> {
+  const settings =
+    options.settings ?? resolveStoreJanitorSettings(options.cwd ?? process.cwd(), options.onWarn);
+  // WHY: the early return: mode `off` means "leave this store untouched", so it must not even OPEN
+  // WHY: the store — an open is the store's own maintenance boundary (sweep, TTL prune, vacuum).
+  if (settings.mode === "off") return skipped("off");
+
+  const db = options.db ?? (await loadHashStore()).db;
+  const outcome = runJanitor({ db, now: options.now ?? Date.now(), settings });
+  if (!outcome.ran || !outcome.deepCheckFailed) return outcome;
+
+  const healed = await (options.heal ?? (() => healUnhealthyStore()))();
+  return { ...outcome, rebuilt: healed };
+}
+
+export interface JanitorHookDeps {
+  /** The pass one lifecycle event triggers; overridden in tests so wiring can be observed. */
+  readonly runJanitor: () => Promise<JanitorOutcome>;
+}
+
+/**
+ * WHERE one event's warning may appear. `session_start` runs while the session is live, so the
+ * operator sees the console; `session_shutdown` runs as the runtime tears that console down, so only
+ * the log survives. Modelled as a value because "which surface" is the whole rule, and a boolean
+ * would leave a reader to infer it from the event name.
+ */
+type JanitorWarningSurface = "console" | "log";
+
+/** The surface each wired event publishes on. Keyed by the tuple, so a new event cannot be silent. */
+const WARNING_SURFACE_BY_EVENT: Record<(typeof JANITOR_EVENTS)[number], JanitorWarningSurface> = {
+  session_start: "console",
+  session_shutdown: "log",
+};
+
+/**
+ * Render one run's warning and publish it on `surface`. The TRIGGER is not re-derived here: the
+ * formatter owns "did anything observable happen" (#197), so `null` is the only decision left — and
+ * it means write nothing, on either surface.
+ *
+ * WHY the log path is resolved here and handed down: the formatter is pure by contract (#197), and a
+ * module that read the state root itself could not be tested without one. Resolving it at the call
+ * site also means the damaged-store shape points at the file this process is actually writing.
+ *
+ * WHY the level picks the sink helper (`reportInfo` / `reportWarning`) rather than `reportDiagnostic`:
+ * that one writes level `error`, and a routine cleanup filed as an error would make the log's
+ * severity column lie about the run it describes.
+ */
+function publishJanitorWarning(outcome: JanitorOutcome, surface: JanitorWarningSurface): void {
+  const warning = formatJanitorWarning(outcome, { logPath: diagnosticsLogPath() });
+  if (warning === null) return;
+  if (surface === "console") printJanitorWarning(warning);
+  const report = warning.level === "info" ? reportInfo : reportWarning;
+  // WHY: one record joined by newlines — the damaged-store lines stay separate so a reader can quote
+  // WHY: one alone, and a JSONL record escapes the breaks while keeping every line intact.
+  report("store-janitor", recordBody(outcome, warning));
+}
+
+/**
+ * The record body: the rendered lines, plus — for a FAILED compaction only — the exception's own
+ * message. WHY the extra line: the rendered shape points at this log for details, so the log must
+ * carry them; WHY only here and not on the console: the console line stays short because the
+ * exception text is diagnostic evidence, not operator prose.
+ */
+function recordBody(outcome: JanitorOutcome, warning: JanitorWarning): string {
+  const error = outcome.compacted.reason === "failed" ? outcome.compacted.error : undefined;
+  return [
+    ...warning.lines,
+    ...(error === undefined ? [] : [`${JANITOR_WARNING_PREFIX} Error: ${error}`]),
+  ].join("\n");
+}
+
+/**
+ * The console half, which only `session_start` has. `warn` goes to `console.error` because that is
+ * this repo's console habit for an operator-visible problem (`console.warn` appears nowhere in
+ * `src/`); the severity that matters is the diagnostic record's, not which fd the line lands on.
+ *
+ * Never throws: the session's own work must not fail because a surface refused a warning, and a
+ * console the host has already detached is exactly the shutdown case this module must survive.
+ */
+function printJanitorWarning(warning: JanitorWarning): void {
+  try {
+    for (const line of warning.lines) {
+      if (warning.level === "info") console.info(line);
+      else console.error(line);
+    }
+  } catch {
+    // SAFETY: best-effort notice — the diagnostics record written next is the surface that survives.
+  }
+}
+
+/**
+ * Wire the janitor to `JANITOR_EVENTS`. Both handlers run the same best-effort pass and differ only in
+ * where they publish its warning: a failure is reported to the log and swallowed, because the
+ * session's own work must not fail with maintenance.
+ *
+ * WHY `session_shutdown` is wired even though the runtime is being torn down: on `quit` the exit path
+ * still runs `shutdownDb` (the WAL checkpoint's single owner), and the pass itself is synchronous
+ * SQLite work with no awaits of its own inside the run — a handler that cannot finish simply leaves
+ * the throttle row unwritten, and the next session_start runs the sweep instead.
+ */
+export function registerJanitorHooks(
+  pi: ExtensionAPI,
+  overrides: Partial<JanitorHookDeps> = {},
+): void {
+  const deps: JanitorHookDeps = {
+    runJanitor: () => janitorPass(),
+    ...overrides,
+  };
+  const handlerFor = (surface: JanitorWarningSurface) => async (): Promise<void> => {
+    try {
+      publishJanitorWarning(await deps.runJanitor(), surface);
+    } catch (error) {
+      // SAFETY: best-effort maintenance — a failed janitor run leaves the store exactly as it was
+      // SAFETY: (every step is idempotent and its own work is its own throttle record), so the
+      // SAFETY: session continues and the next lifecycle event retries. The publish step itself
+      // SAFETY: cannot throw (see `printJanitorWarning`), so this catch stays the pass's alone.
+      reportDiagnostic("store-janitor", "[store-janitor] maintenance pass failed:", error);
+    }
+  };
+  // SAFETY: `pi.on` is typed per event name while `JANITOR_EVENTS` is a runtime tuple, so the
+  // SAFETY: registration needs the same string-key widening the entry point already uses; the
+  // SAFETY: handler's `(event, ctx) => Promise<void>` shape is what every lifecycle event accepts.
+  const register = (pi as unknown as { on: (event: string, handler: () => Promise<void>) => void })
+    .on;
+  for (const event of JANITOR_EVENTS) {
+    // SAFETY: narrowed to the handler signature the widened `on` above declares.
+    register.call(pi, event, handlerFor(WARNING_SURFACE_BY_EVENT[event]));
+  }
+}