pi-mega-compact 0.20.9 → 0.20.10

package/extensions/dashboard-client/src/tabs/VectorCortexTab.tsx

@@ -19,6 +19,7 @@ import {
 	fetchVectorCortexRollout,
 	fetchVectorCortexClosureProof,
 	fetchVectorCortexRestore,
+	fetchVectorCortexRepair,
 	fetchVectorCortexShards,
 	fetchVectorCortexTopology,
 	resetVectorCortexBreaker,
@@ -32,6 +33,7 @@ import {
 	type VectorCortexRolloutView,
 	type VectorCortexClosureProofView,
 	type VectorCortexRestoreView,
+	type VectorCortexRepairView,
 	type VectorCortexShardsView,
 	type VectorCortexTopologyView,
 } from "../api/vector-cortex";
@@ -42,6 +44,11 @@ import { VectorCortexRenderCard } from "./VectorCortexRenderCard";
 import { VectorCortexRolloutCard } from "./VectorCortexRolloutCard";
 import { VectorCortexClosureCard } from "./VectorCortexClosureCard";
 import { VectorCortexRestoreCard } from "./VectorCortexRestoreCard";
+import { VectorCortexRepairCard } from "./VectorCortexRepairCard";
+import {
+	VectorCortexShardsCard,
+	VectorCortexReconstructCard,
+} from "./VectorCortexShardsCard";
 import { VectorCortexPlansCard } from "./VectorCortexPlansCard";
 import { VectorCortexTopologyCard } from "./VectorCortexTopologyCard";
 import { VectorCortexLedgerCard } from "./VectorCortexLedgerCard";
@@ -71,6 +78,7 @@ export default function VectorCortexTab(): React.ReactElement {
 	const [rollout, setRollout] = useState<VectorCortexRolloutView | null>(null);
 	const [closureProof, setClosureProof] = useState<VectorCortexClosureProofView | null>(null);
 	const [restore, setRestore] = useState<VectorCortexRestoreView | null>(null);
+	const [repair, setRepair] = useState<VectorCortexRepairView | null>(null);
 
 	const poll = useCallback(() => {
 		fetchVectorCortexEvaluation()
@@ -112,6 +120,9 @@ export default function VectorCortexTab(): React.ReactElement {
 		fetchVectorCortexRestore().then(setRestore).catch(() => {
 			/* exact-source-restoration card is best-effort (VC6B) */
 		});
+		fetchVectorCortexRepair().then(setRepair).catch(() => {
+			/* self-healing derived-state card is best-effort (VC6C) */
+		});
 	}, []);
 
 	useEffect(() => {
@@ -263,71 +274,14 @@ export default function VectorCortexTab(): React.ReactElement {
 				</CardContent>
 			</Card>
 			<VectorCortexTopologyCard topology={topology} query={query} />
-			<Card>
-				<CardHeader>
-					<div className="flex items-center justify-between">
-						<CardTitle>Dual-Tier Shards (VC4A)</CardTitle>
-						{shards?.enabled ? (
-							<Badge variant="success">ACTIVE</Badge>
-						) : (
-							<Badge variant="danger">OFF</Badge>
-						)}
-				</div>
-				</CardHeader>
-				<CardContent>
-					{!shards?.enabled ? (
-						<div className="vc-empty">Dual-tier shards disabled (VC4A off).</div>
-					) : (
-						<>
-							<div className="grid grid-cols-2 gap-4 md:grid-cols-4">
-								<Metric label="Semantic shards" value={String(shards.semanticCount)} />
-								<Metric label="Exact shards" value={String(shards.exactCount)} />
-								<Metric label="Byte total" value={String(shards.byteTotal)} />
-								<Metric label="Protected bytes" value={String(shards.protectedByteTotal)} />
-							</div>
-							<div className="mt-3 text-xs text-muted-foreground">
-								Reader-only count/byte aggregate; staged in-memory this sprint.
-							</div>
-						</>
-					)}
-				</CardContent>
-			</Card>
-			<Card>
-				<CardHeader>
-					<div className="flex items-center justify-between">
-						<CardTitle>Reconstruction Fidelity (VC4C)</CardTitle>
-						{reconstruct?.enabled ? (
-							<Badge variant="success">ACTIVE</Badge>
-						) : (
-							<Badge variant="danger">OFF</Badge>
-						)}
-					</div>
-				</CardHeader>
-				<CardContent>
-					{!reconstruct?.enabled ? (
-						<div className="vc-empty">Reconstruction fidelity disabled (VC4C off).</div>
-					) : (
-						<>
-							<div className="grid grid-cols-2 gap-4 md:grid-cols-4">
-								<Metric label="Closure attempts" value={String(reconstruct.closureAttempts)} />
-								<Metric label="Closure rejections" value={String(reconstruct.closureRejections)} />
-								<Metric label="Validated" value={String(reconstruct.validatedCount)} />
-								<Metric label="Invalidated" value={String(reconstruct.invalidatedCount)} />
-								<Metric label="Span total" value={String(reconstruct.spanTotal)} />
-								<Metric label="Byte total" value={String(reconstruct.byteTotal)} />
-							</div>
-							<div className="mt-3 text-xs text-muted-foreground">
-								Reader-only closure/validation aggregate; staged in-memory this sprint.
-							</div>
-						</>
-					)}
-				</CardContent>
-			</Card>
+			<VectorCortexShardsCard view={shards} />
+			<VectorCortexReconstructCard view={reconstruct} />
 			<VectorCortexPlansCard view={plans} />
 			<VectorCortexRenderCard view={render} />
 			<VectorCortexRolloutCard view={rollout} />
 			<VectorCortexClosureCard view={closureProof} />
 			<VectorCortexRestoreCard view={restore} />
+			<VectorCortexRepairCard view={repair} />
 			<VectorCortexLedgerCard ledger={ledger} />
 		</div>
 	);

package/extensions/dashboard-client/src/types/vector-cortex.ts

@@ -225,6 +225,23 @@ export interface VectorCortexRestoreView {
   updatedAt: string;
 }
 
+/**
+ * Reader-only self-healing derived-state view (VC6C). Counts + HEAL_REPAIR_*
+ * codes only — there is no payload endpoint, so no subsystem source bytes, gap
+ * ranges, high-water marks, root digests, or ledger text ever reach the client.
+ */
+export interface VectorCortexRepairView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  repairAttempts: number;
+  repairsPlanned: number;
+  pointersSwitched: number;
+  backoffs: number;
+  lastBackoffMs: number | null;
+  lastFailure: string | null;
+  updatedAt: string;
+}
+
 /** Reader-only closure-optimization diagnostics view (VC6A). Aggregate only. */
 export interface VectorCortexClosureProofView {
   enabled: boolean;

package/extensions/dashboard-server/api-contracts/vector-cortex-heal.ts

@@ -71,3 +71,41 @@ export interface VectorCortexRestoreView {
   /** ISO timestamp of the snapshot. */
   readonly updatedAt: string;
 }
+
+/**
+ * Reader-only self-healing derived-state diagnostics view for
+ * GET /api/vector-cortex/repair (VC6C).
+ *
+ * COUNTS + ERROR CODES ONLY. Like the restore view, this surface deliberately
+ * carries no payload: no subsystem source bytes, no rebuilt derived rows, no
+ * subsystem names paired with their gap ranges, no high-water values, no root
+ * digests, and no ledger text (SECURITY_PRIVACY — a diagnostic surface never
+ * renders the authority's contents). Only the controller's rebuild counters,
+ * the backoff schedule's observable timing, and the last HEAL_REPAIR_* failure
+ * code are exposed; the per-subsystem gap detail lives in the structured event
+ * log, not the dashboard.
+ */
+export interface VectorCortexRepairView {
+  /** Whether the VC6C self-healing derived-controller flag is enabled. */
+  readonly enabled: boolean;
+  /**
+   * Runtime triad mode: "A" targeted single-subsystem rebuild, "B" full
+   * deterministic rebuild (ambiguous gap), "C" derived state disabled (both
+   * rebuild paths failed, or the controller is not running at all).
+   */
+  readonly mode: "A" | "B" | "C";
+  /** Total rebuild attempts started by the controller (event counter). */
+  readonly repairAttempts: number;
+  /** Rebuilds planned after gap detection, before rate limiting (counter). */
+  readonly repairsPlanned: number;
+  /** Rebuilds that reached a verified atomic pointer switch (counter). */
+  readonly pointersSwitched: number;
+  /** Attempts deferred by the rate limiter / exponential backoff (counter). */
+  readonly backoffs: number;
+  /** Most recent deterministic backoff delay in ms, or null if none yet. */
+  readonly lastBackoffMs: number | null;
+  /** Last failure reason (a HEAL_REPAIR_* code), or null if none yet. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}

package/extensions/dashboard-server/api-contracts/vector-cortex.ts

@@ -377,4 +377,5 @@ export interface VectorCortexLedgerView {
 export type {
   VectorCortexClosureProofView,
   VectorCortexRestoreView,
+  VectorCortexRepairView,
 } from "./vector-cortex-heal.js";

package/extensions/dashboard-server/route-dispatch.ts

@@ -57,6 +57,9 @@ import {
 	handleVectorCortexClosureProof,
 	handleVectorCortexRestore,
 } from "./routes.js";
+// VC6C repair lives in its own module (routes-vector-cortex-repair.ts) so the
+// heal route file stays well under the 400-line extension soft limit.
+import { handleVectorCortexRepair } from "./routes-vector-cortex-repair.js";
 
 /**
  * Dispatch a request through every registered route handler.
@@ -110,5 +113,6 @@ export function dispatchRoutes(
 	if (handleVectorCortexRollout(req, res, ctx)) return true;
 	if (handleVectorCortexClosureProof(req, res, ctx)) return true;
 	if (handleVectorCortexRestore(req, res, ctx)) return true;
+	if (handleVectorCortexRepair(req, res, ctx)) return true;
 	return false;
 }

package/extensions/dashboard-server/routes-rag-settings-vector-cortex.ts

@@ -150,5 +150,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Exact source restoration: restores the original bytes of closure spans ONLY from an exact shard (mode A) or a verified ledger range scan (mode B) — never inferred, reconstructed, or paraphrased from embeddings or semantic text. Requests are hard-bounded at 64 spans / 4MiB (HEAL_RESTORE_LIMIT); every span's SHA-256 is recomputed and bytes are inserted only after all requested span metadata validates, so a single bad span fails the whole request closed (HEAL_RESTORE_DIGEST_MISMATCH, HEAL_RESTORE_RANGE_MISMATCH). When no exact source exists (HEAL_RESTORE_SOURCE_MISSING) the old context is omitted and the loss is disclosed (mode C) rather than filled in. OFF = byte-identical predecessor (VC6A).",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC6C",
+			"VC6C Self-Healing Derived State",
+			"Self-healing derived-state controller: detects gaps between each derived subsystem's high-water mark and the durable authority high-water, then rebuilds derived state by copy -> root-digest verification -> atomic pointer switch, so a partially rebuilt subsystem is never made visible. A targeted single-subsystem rebuild is mode A; an ambiguous gap escalates to a full deterministic rebuild (mode B); if both rebuild paths fail the derived state is disabled rather than served stale (mode C). Rebuilds are rate-limited to one per subsystem per 5 minutes with deterministic exponential backoff, so a persistently failing subsystem cannot spin. OFF = byte-identical predecessor (VC6B); no controller runs, so the dashboard reports mode C.",
+			true,
+		),
 	],
 };

package/extensions/dashboard-server/routes-vector-cortex-repair.ts

@@ -0,0 +1,72 @@
+/**
+ * dashboard-server/routes-vector-cortex-repair.ts — VC6C self-healing
+ * derived-state dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/repair returning the self-healing
+ * controller's aggregate diagnostics: whether the flag is enabled, the runtime
+ * triad mode, cumulative rebuild/pointer-switch/backoff counters, the last
+ * deterministic backoff delay, and the last HEAL_REPAIR_* failure code.
+ *
+ * COUNTS + ERROR CODES ONLY. NEVER exposes subsystem source bytes, rebuilt
+ * derived rows, per-subsystem gap ranges, high-water marks, root digests, or
+ * ledger text (reader-only, SECURITY_PRIVACY — the per-subsystem gap detail
+ * lives in the structured event log, not the dashboard). There is no mutation
+ * seam here either: rebuilds are driven by the controller's own gap detection,
+ * never by a dashboard request, so non-GET is rejected outright.
+ *
+ * Split into its own file (rather than grown into routes-vector-cortex-heal.ts)
+ * to keep every extensions/ file well under the 400-line soft-as-hard limit.
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + codes only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC6C_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexRepairView } from "./api-contracts/vector-cortex.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/repair (VC6C).
+ *
+ * Counts and HEAL_REPAIR_* codes only — this is a static reader-only aggregate
+ * seam (same shape as the VC6A/VC6B handlers): there is no payload endpoint and
+ * never will be, so no subsystem bytes, gap ranges, high-water marks, or root
+ * digests can leak here.
+ */
+export function handleVectorCortexRepair(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/repair") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC6C_ENABLED();
+  // Flag-off routes to mode C: with VC6C off no self-healing controller runs at
+  // all, so neither the targeted rebuild (mode A) nor the full deterministic
+  // rebuild (mode B) path is available. Mode C is exactly the spec's "derived
+  // state disabled" outcome — the honest OFF view is that derived state is not
+  // being healed, rather than implying a rebuild path that is not wired.
+  // Mirrors how VC6B's OFF view reports the disclose-loss mode it actually takes.
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexRepairView = {
+    enabled,
+    mode,
+    repairAttempts: 0,
+    repairsPlanned: 0,
+    pointersSwitched: 0,
+    backoffs: 0,
+    lastBackoffMs: null,
+    lastFailure: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.9",
+  "version": "0.20.10",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex.ts

@@ -241,6 +241,23 @@ export const VC6A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6A");
  */
 export const VC6B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6B");
 
+/**
+ * VC6C — self-healing derived controller. Default ON. `MEGACOMPACT_VC6C=0`
+ * disables and is byte-identical to the predecessor (VC6B): the `detectGaps` /
+ * `planRebuild` / `rebuildGeneration` / `switchPointer` arithmetic STILL RUNS (it
+ * is PURE — a high-water comparison plus a SHA-256 root-digest check, with an
+ * INJECTED clock and no storage or network), but the
+ * `vector_cortex_repair_planned` / `vector_cortex_repair_pointer_switched` /
+ * `vector_cortex_repair_backoff` events are never emitted and the dashboard
+ * repair diagnostics seam is suppressed. Flag OFF gates the reporter + dashboard
+ * seam, never the gap-detection/rebuild arithmetic (in particular, an unverified
+ * pointer switch stays refused with the flag off), so flag-off
+ * outbound/predecessor golden bytes match exactly. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring VC4A/VC4B/VC4C/VC5A/VC5B/VC5C/VC6A/VC6B.
+ */
+export const VC6C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6C");
+
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/src/config.ts

@@ -171,6 +171,7 @@ export {
   VC5C_ENABLED,
   VC6A_ENABLED,
   VC6B_ENABLED,
+  VC6C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/heal/_repair-fixture.ts

@@ -0,0 +1,138 @@
+/**
+ * heal/_repair-fixture.ts — conformance fixture I/O for VC6C healing-controller rows.
+ *
+ * Sibling of `_restore-fixture.ts` (VC6B) and `_acceptance-fixture.ts` (VC6A);
+ * split out so no loader approaches the 300-line soft limit and so the
+ * BigInt/base64 decoding lives next to the contract it reconstitutes.
+ *
+ * DECODING IS THE POINT. Fixtures are canonical JSON, which cannot express
+ * bigints or bytes, so the corpus stores numeric `nowMs` / high-waters and
+ * base64 source bytes. These loaders turn those back into the REAL `RepairState`
+ * / `RebuildInput` objects the production controller consumes — no mocks, no
+ * stubs, no parallel "test shape". A lossy decode would make the digests or the
+ * planned ranges disagree and the acceptance test would fail loudly.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+
+import type { Mode, RepairState } from "./repair-types.js";
+import type { RebuildInput } from "./rebuild.js";
+import { V2, readManifest } from "./_acceptance-fixture.js";
+
+/** A subsystem state as it appears in JSON: high-waters are numbers, not bigints. */
+export interface RepairFxState {
+  subsystem: string;
+  derivedHighWater: number;
+  authorityHighWater: number;
+  lastRebuildAt: number | null;
+  generation: number;
+  mode: Mode;
+  failedAttempts?: number;
+  authorityFrozen?: boolean;
+}
+
+export interface RepairFxRebuild {
+  subsystem: string;
+  generation: number;
+  currentGeneration: number;
+  sourceBytesBase64: string;
+  expectedDigest: string;
+  triadMode: Mode;
+}
+
+export interface RepairFxBackoff {
+  subsystem: string;
+  attempts: number[];
+}
+
+export interface RepairFxInput {
+  scenario: string;
+  /** Which real entry point the acceptance test drives. */
+  mode: "detect" | "backoff" | "rebuild";
+  /** The INJECTED monotonic clock — VC6C never reads a real clock. */
+  nowMs: number;
+  states: RepairFxState[];
+  rebuild?: RepairFxRebuild;
+  backoff?: RepairFxBackoff;
+}
+
+export interface RepairFxExpected {
+  ok: boolean;
+  code?: string;
+  plannedCount: number;
+  /** Exact [seqStart, seqEnd] of each plan, in plan order. */
+  ranges: number[][];
+  switched?: boolean;
+  generation?: number;
+  semanticLossStated?: boolean;
+  monotonic?: boolean;
+  capped?: boolean;
+  idempotent?: boolean;
+}
+
+export interface RepairFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: RepairFxInput;
+  expected: RepairFxExpected;
+}
+
+/** Read one registered healing-controller fixture (asserting it IS registered). */
+export function repairFixture(id: string): RepairFx {
+  const m = readManifest();
+  const row = m.fixtures.find(
+    (f) => f.id === id && f.path.startsWith("healing-controller/"),
+  );
+  assert.ok(row, `fixture ${id} registered under healing-controller/ in manifest`);
+  return JSON.parse(readFileSync(join(V2, row!.path), "utf8")) as RepairFx;
+}
+
+/** JSON numbers -> the bigint fields `RepairState` declares. */
+export function decodeState(s: RepairFxState): RepairState {
+  return {
+    subsystem: s.subsystem,
+    derivedHighWater: BigInt(s.derivedHighWater),
+    authorityHighWater: BigInt(s.authorityHighWater),
+    lastRebuildAt: s.lastRebuildAt === null ? null : BigInt(s.lastRebuildAt),
+    generation: s.generation,
+    mode: s.mode,
+    ...(s.failedAttempts !== undefined ? { failedAttempts: s.failedAttempts } : {}),
+    ...(s.authorityFrozen !== undefined ? { authorityFrozen: s.authorityFrozen } : {}),
+  };
+}
+
+/** Reconstitute a real `RebuildInput` from its fixture row. */
+export function decodeRebuild(r: RepairFxRebuild): RebuildInput {
+  return {
+    subsystem: r.subsystem,
+    range: {
+      sessionId: r.subsystem,
+      seqStart: 0n,
+      seqEnd: 0n,
+      byteStart: 0,
+      byteEnd: 0,
+    },
+    generation: r.generation,
+    sourceBytes: new Uint8Array(Buffer.from(r.sourceBytesBase64, "base64")),
+    expectedDigest: r.expectedDigest,
+  };
+}
+
+/** Flag-pinned wrapper: VC6C gated by MEGACOMPACT_VC6C (defaults ON). */
+export function withVc6cFlagsOn(fn: () => void): () => void {
+  return (): void => {
+    const saved = process.env.MEGACOMPACT_VC6C;
+    process.env.MEGACOMPACT_VC6C = "1";
+    try {
+      fn();
+    } finally {
+      if (saved === undefined) delete process.env.MEGACOMPACT_VC6C;
+      else process.env.MEGACOMPACT_VC6C = saved;
+    }
+  };
+}

package/src/vector-cortex/heal/controller.ts

@@ -0,0 +1,189 @@
+/**
+ * vector-cortex/heal/controller.ts — VC6C gap detection + rebuild planning.
+ *
+ * Compares each derived subsystem's high-water to the durable authority
+ * high-water and emits a `RepairPlanV1` for every gap that is real, actionable,
+ * and not rate-limited. The controller DECIDES; `rebuild.ts` executes.
+ *
+ * THE AUTHORITY IS NEVER WRITTEN. Every function here takes `RepairState` (whose
+ * `authorityHighWater` is readonly) and returns plans. There is no code path,
+ * guarded or otherwise, that mutates authority — derived state is rebuildable,
+ * authority is not, so repair is strictly one-directional.
+ *
+ * FOUR REASONS NOT TO PLAN, in priority order. The order is the contract: a
+ * frozen authority outranks a rate limit, because "the frontier is not real yet"
+ * is a statement about CORRECTNESS while "you rebuilt recently" is only about
+ * pacing. Reporting RATE_LIMITED during an outage would tell an operator to wait
+ * five minutes for a rebuild that must never happen at all.
+ *
+ *   1. AUTHORITY FROZEN. During an outage the durable high-water freezes while
+ *      the spool keeps accepting frames (TRIAD_RESILIENCE §frontier). A derived
+ *      subsystem behind a frozen frontier is CORRECT, so we refuse to plan rather
+ *      than chase the spool tail and materialize non-durable frames.
+ *   2. NO GAP. `derived >= authority` — nothing to do. Note `>`: a derived source
+ *      AHEAD of authority is not repaired by rebuilding a backwards range (that
+ *      would produce an inverted range); it is left alone for the breaker.
+ *   3. MODE C. Derived state is disabled for this subsystem. Re-planning a
+ *      subsystem whose derived tier is intentionally off is a rebuild loop.
+ *   4. RATE LIMITED. One rebuild per subsystem per 5 minutes.
+ *
+ * DETERMINISTIC JITTER. The ±10% spread comes from a SHA-256 of the subsystem
+ * name plus the attempt, never `Math.random`. Two subsystems desynchronize (no
+ * thundering herd) while a single subsystem's schedule is byte-reproducible — a
+ * fixture can pin `backoffMs` exactly, which a PRNG would make untestable.
+ *
+ * PURE. `node:crypto` is the only dependency beyond types: no storage, no
+ * console, no network, and no clock — `nowMs` is always injected, which is what
+ * makes the fake-clock restart fixtures possible (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { createHash } from "node:crypto";
+
+import type {
+  RepairPlanV1,
+  RepairState,
+  RepairSubsystem,
+  ShardRange,
+} from "./repair-types.js";
+import {
+  REPAIR_BACKOFF_BASE_MS,
+  REPAIR_BACKOFF_CAP_MS,
+  REPAIR_BACKOFF_JITTER,
+  REPAIR_RATE_LIMIT_MS,
+} from "./repair-types.js";
+
+/**
+ * A stable fraction in [0,1) derived from the subsystem name + attempt.
+ *
+ * Uses the first 6 hex digits (24 bits) of SHA-256 — plenty of spread for a ±10%
+ * window, and small enough to stay exact in a float64 division.
+ */
+function digestFraction(subsystem: RepairSubsystem, attempt: number): number {
+  const hex = createHash("sha256")
+    .update(`${subsystem}:${attempt}`)
+    .digest("hex")
+    .slice(0, 6);
+  return parseInt(hex, 16) / 0x1000000;
+}
+
+/**
+ * Deterministic exponential backoff: `30s * 2^attempt`, capped at 15 minutes,
+ * then spread by ±10% seeded from the subsystem digest.
+ *
+ * The cap is applied BEFORE the jitter so the jitter is a spread around the cap
+ * rather than a way to exceed it; the result is floored to an integer ms so the
+ * value is exactly representable in JSON (a fixture pins it verbatim).
+ *
+ * `attempt` is clamped at 0 and at 30: `2^attempt` for an unclamped large attempt
+ * would reach Infinity, and `Infinity * jitter` is NaN — a NaN backoff would
+ * schedule a plan that is never eligible and silently wedge the subsystem.
+ */
+export function computeBackoff(subsystem: RepairSubsystem, attempt: number): number {
+  const safe = Math.min(Math.max(Math.floor(attempt), 0), 30);
+  const raw = REPAIR_BACKOFF_BASE_MS * 2 ** safe;
+  const capped = Math.min(raw, REPAIR_BACKOFF_CAP_MS);
+  // Map [0,1) onto [-1,+1) then scale to the ±10% window.
+  const spread = (digestFraction(subsystem, safe) * 2 - 1) * REPAIR_BACKOFF_JITTER;
+  return Math.max(0, Math.floor(capped * (1 + spread)));
+}
+
+/**
+ * True when this subsystem rebuilt less than 5 minutes ago.
+ *
+ * A subsystem that has NEVER rebuilt (`lastRebuildAt === null`) is never rate
+ * limited — the first repair after a restart must not be delayed by the absence
+ * of history.
+ */
+export function isRateLimited(
+  lastRebuildAt: bigint | null,
+  nowMs: bigint,
+): boolean {
+  if (lastRebuildAt === null) return false;
+  return lastRebuildAt + BigInt(REPAIR_RATE_LIMIT_MS) > nowMs;
+}
+
+/**
+ * The seq window a rebuild must cover: the first UNBUILT seq through the
+ * authority frontier, inclusive.
+ *
+ * Byte bounds are intentionally 0..0. VC6C plans in SEQ space — the controller
+ * knows how far each derived tier has been built, but byte offsets belong to the
+ * shard/ledger layer that executes the rebuild. Inventing byte bounds here would
+ * be fabricating a fact the controller does not have.
+ */
+function gapRange(state: RepairState): ShardRange {
+  return {
+    sessionId: state.subsystem,
+    seqStart: state.derivedHighWater + 1n,
+    seqEnd: state.authorityHighWater,
+    byteStart: 0,
+    byteEnd: 0,
+  };
+}
+
+/**
+ * Build the plan for one subsystem's gap.
+ *
+ * Always targets `generation + 1`: a rebuild NEVER writes into the live
+ * generation, so a failed or half-written rebuild cannot corrupt what is
+ * currently being served (see `rebuild.ts` copy-then-switch).
+ *
+ * Exported for direct unit testing and for callers that have already decided a
+ * plan is warranted; `detectGaps` is the guarded entry point that applies the
+ * four refusal rules first.
+ */
+export function planRebuild(state: RepairState, nowMs: bigint): RepairPlanV1 {
+  const backoffMs = computeBackoff(state.subsystem, state.failedAttempts ?? 0);
+  return {
+    schema: "repair-plan-v1",
+    subsystem: state.subsystem,
+    range: gapRange(state),
+    generation: state.generation + 1,
+    backoffMs,
+    scheduledAt: nowMs + BigInt(backoffMs),
+  };
+}
+
+/**
+ * True when a subsystem is eligible for a rebuild plan (the four refusal rules).
+ * Ordering matters — see the file header.
+ */
+export function isPlannable(state: RepairState, nowMs: bigint): boolean {
+  if (state.authorityFrozen === true) return false;
+  if (state.derivedHighWater >= state.authorityHighWater) return false;
+  if (state.mode === "C") return false;
+  if (isRateLimited(state.lastRebuildAt, nowMs)) return false;
+  return true;
+}
+
+/**
+ * Detect derived gaps and plan a rebuild for each eligible subsystem.
+ *
+ * Output order follows INPUT order, not subsystem name: the caller controls
+ * priority (a topology gap may matter more than a closure gap), and re-sorting
+ * here would silently override that. Never throws — an unplannable subsystem is
+ * simply absent from the result, so a single wedged tier cannot stop the others
+ * from healing (PRACTICES: non-fatal).
+ */
+export function detectGaps(
+  states: readonly RepairState[],
+  nowMs: bigint,
+): readonly RepairPlanV1[] {
+  const plans: RepairPlanV1[] = [];
+  for (const state of states) {
+    if (!isPlannable(state, nowMs)) continue;
+    plans.push(planRebuild(state, nowMs));
+  }
+  return plans;
+}
+
+/**
+ * The bound controller surface. A plain object (not a class): there is no
+ * instance state to hold — every input, including the clock, is injected.
+ */
+export function createRepairController(): {
+  readonly detectGaps: typeof detectGaps;
+  readonly planRebuild: typeof planRebuild;
+} {
+  return { detectGaps, planRebuild };
+}