pi-mega-compact 0.20.9 → 0.20.11

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 };
+}

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

@@ -0,0 +1,200 @@
+/**
+ * vector-cortex/heal/rebuild.ts — VC6C generation rebuild + atomic pointer switch.
+ *
+ * Executes what `controller.ts` planned: materialize a NEW generation, verify its
+ * root digest, and only then flip the live pointer.
+ *
+ * COPY, VERIFY, SWITCH — in that order, always.
+ *
+ *   1. COPY. The rebuild writes into `plan.generation` (always `current + 1`),
+ *      never into the live generation. The thing currently being served is never
+ *      the thing being modified, so a crash mid-rebuild leaves a complete old
+ *      generation and a partial new one — never a torn live one.
+ *   2. VERIFY. The new generation's root digest must equal the digest the plan
+ *      pinned. This is the ONLY gate on the pointer.
+ *   3. SWITCH. `switchPointer` moves the pointer iff verification passed.
+ *
+ * A FAILED VERIFICATION DELETES NO EVIDENCE. On mismatch we keep the old pointer
+ * AND leave the new generation on disk. That is deliberate: the corrupt
+ * generation is the only artifact that can explain WHY the rebuild was wrong, and
+ * a self-healing system that tidies up its failures is a system that cannot be
+ * debugged. Cleanup is a separate, explicit operator action.
+ *
+ * CRASH SAFETY IS A CONSEQUENCE OF THE ORDER, NOT AN EXTRA STEP. The pointer is
+ * the single atomic commit point. Kill the process after step 1 or 2 and the old
+ * pointer is still live, so the next start serves the prior generation and simply
+ * re-plans — the orphaned generation is inert. This is what
+ * `rebuild-chaos.test.ts` pins.
+ *
+ * THE TRIAD (independent algorithms, per TRIAD_RESILIENCE).
+ *   A — TARGETED: rebuild only `plan.range`, reusing the prior generation for
+ *       everything outside it. Cheap; needs a healthy prior generation.
+ *   B — FULL DETERMINISTIC: re-derive the whole subsystem from the byte ledger,
+ *       reusing NOTHING. Independent of A: it shares no index, no prior
+ *       generation, and no incremental state, so a bug or corruption that breaks
+ *       A cannot break B the same way.
+ *   C — DISABLE DERIVED STATE: no rebuild at all. Mode C is a real outcome, not
+ *       an error path, and it MUST state its loss of old semantic context — the
+ *       subsystem serves nothing rather than serving something wrong.
+ *
+ * PURE. `node:crypto` only — no storage, no console, no clock, no network
+ * (PREVENT-PI-004 / PREVENT-011). Callers own persistence; this module owns the
+ * decision and the digest arithmetic, which is what makes it fixture-testable.
+ */
+
+import { createHash } from "node:crypto";
+
+import type { Mode, RepairFailureCode, ShardRange } from "./repair-types.js";
+
+/**
+ * Everything a rebuild needs. `sourceBytes` is the materialized content of the
+ * new generation; `expectedDigest` is the root digest the plan pinned and the
+ * ONLY thing that authorizes a pointer switch.
+ */
+export interface RebuildInput {
+  readonly subsystem: string;
+  readonly range: ShardRange;
+  /** The NEW generation being written (never the live one). */
+  readonly generation: number;
+  /** The rebuilt generation's content. */
+  readonly sourceBytes: Uint8Array;
+  /** Root digest, BARE lowercase hex (the ExactShardV1.digest convention). */
+  readonly expectedDigest: string;
+}
+
+/**
+ * The rebuild verdict.
+ *
+ * The failure arm still carries `generation` so the caller can name the orphaned
+ * generation in a log or an operator prompt — the evidence is retained, so its
+ * identity must be reportable.
+ */
+export type RebuildResult =
+  | {
+      readonly ok: true;
+      readonly generation: number;
+      /** The VERIFIED root digest (equals `expectedDigest`). */
+      readonly digest: string;
+      readonly mode: Mode;
+    }
+  | {
+      readonly ok: false;
+      readonly code: RepairFailureCode;
+      readonly generation: number;
+      readonly mode: Mode;
+      /** Set on mode C: the caller MUST be told derived context is gone. */
+      readonly semanticLossStated?: boolean;
+    };
+
+/** The outcome of a pointer switch: which generation is live afterwards. */
+export interface PointerSwitch {
+  readonly switched: boolean;
+  /** The live generation AFTER the attempt (unchanged when `switched` is false). */
+  readonly generation: number;
+}
+
+/** Root digest of a generation's bytes: SHA-256, bare lowercase hex. */
+export function rootDigest(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Materialize + verify one generation.
+ *
+ * Hashes the rebuilt bytes and compares to the pinned root digest. A mismatch
+ * returns `HEAL_REPAIR_DIGEST_MISMATCH` and — critically — the caller must NOT
+ * switch the pointer; `switchPointer` enforces that structurally by requiring the
+ * verified flag.
+ *
+ * An EMPTY rebuild is a failure, not an empty success: a generation with no bytes
+ * would hash to the digest of nothing, and if a plan ever pinned that digest an
+ * empty rebuild would "verify" and the pointer would flip to nothing at all. It
+ * is reported as `HEAL_REBUILD_FAILED` because the rebuild produced no artifact.
+ */
+export function rebuildGeneration(
+  input: RebuildInput,
+  mode: Mode = "A",
+): RebuildResult {
+  if (input.sourceBytes.length === 0) {
+    return {
+      ok: false,
+      code: "HEAL_REBUILD_FAILED",
+      generation: input.generation,
+      mode,
+    };
+  }
+  const digest = rootDigest(input.sourceBytes);
+  if (digest !== input.expectedDigest) {
+    // Evidence retained: the caller keeps the generation on disk for inspection.
+    return {
+      ok: false,
+      code: "HEAL_REPAIR_DIGEST_MISMATCH",
+      generation: input.generation,
+      mode,
+    };
+  }
+  return { ok: true, generation: input.generation, digest, mode };
+}
+
+/**
+ * The atomic commit point: flip the live pointer iff the new generation verified.
+ *
+ * `verified` is a required argument rather than something re-derived here, so a
+ * caller cannot switch the pointer without having gone through
+ * `rebuildGeneration` — "switch without verifying" is not expressible.
+ *
+ * A non-monotonic switch is also refused: the new generation must be strictly
+ * greater than the current one. Replaying a stale plan after a restart would
+ * otherwise roll the pointer BACKWARDS onto an older generation, silently
+ * un-healing the subsystem.
+ */
+export function switchPointer(
+  currentGen: number,
+  newGen: number,
+  verified: boolean,
+): PointerSwitch {
+  if (!verified) return { switched: false, generation: currentGen };
+  if (newGen <= currentGen) return { switched: false, generation: currentGen };
+  return { switched: true, generation: newGen };
+}
+
+/**
+ * Apply the triad arm for a rebuild.
+ *
+ * A and B run the same verification (a digest is a digest) but are reached by
+ * INDEPENDENT production paths: A reuses the prior generation and rebuilds only
+ * the planned range, while B re-derives everything from the byte ledger sharing
+ * no index or incremental state with A. C performs no rebuild at all and states
+ * its loss.
+ */
+export function applyTriad(mode: Mode, input: RebuildInput): RebuildResult {
+  if (mode === "C") {
+    // Derived state disabled: no rebuild, and the loss of old semantic context
+    // is DISCLOSED rather than papered over with a stale or partial generation.
+    return {
+      ok: false,
+      code: "HEAL_REBUILD_FAILED",
+      generation: input.generation,
+      mode: "C",
+      semanticLossStated: true,
+    };
+  }
+  return rebuildGeneration(input, mode);
+}
+
+/**
+ * Convenience: rebuild then switch, returning both halves.
+ *
+ * The pointer moves only on a verified rebuild, so a failed verification yields
+ * `switched:false` with the ORIGINAL generation still live and the new (corrupt)
+ * generation left intact on disk for inspection.
+ */
+export function rebuildAndSwitch(
+  input: RebuildInput,
+  currentGen: number,
+  mode: Mode = "A",
+): { readonly result: RebuildResult; readonly pointer: PointerSwitch } {
+  const result = applyTriad(mode, input);
+  const pointer = switchPointer(currentGen, input.generation, result.ok);
+  return { result, pointer };
+}

package/src/vector-cortex/heal/repair-emit.ts

@@ -0,0 +1,118 @@
+/**
+ * vector-cortex/heal/repair-emit.ts — VC6C event reporter seam.
+ *
+ * Mirrors `./restore-emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit`, and the three event names the sprint spec requires verbatim:
+ *   - `vector_cortex_repair_planned`         — a gap was detected, rebuild queued.
+ *   - `vector_cortex_repair_pointer_switched`— a verified generation went live.
+ *   - `vector_cortex_repair_backoff`         — suppressed (rate limit) or failed.
+ *
+ * FLAG SEMANTICS. `detectGaps` / `planRebuild` / `rebuildGeneration` /
+ * `switchPointer` are PURE arithmetic and run REGARDLESS of `MEGACOMPACT_VC6C`.
+ * The flag gates ONLY this reporting + dashboard seam: with the flag off we still
+ * detect gaps, still verify digests, and still refuse unverified pointer
+ * switches — we just do not announce it under the VC6C event namespace. That is
+ * what makes flag-off byte-identical to VC6B: the computation is never skipped,
+ * only the emission.
+ *
+ * PAYLOAD DISCIPLINE. These events carry the SUBSYSTEM NAME, generation numbers,
+ * timings, and codes — never rebuilt bytes, never a root digest of user content,
+ * never a seq range's contents. The subsystem name is an operator-facing
+ * identifier ("topology"), not user data. A repair event is exactly the place
+ * where an unguarded `payload` field would leak a rebuilt transcript into a log.
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+
+import { VC6C_ENABLED } from "../../config/vector-cortex.js";
+import type { Mode, RepairEventName, RepairFailureCode } from "./repair-types.js";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type RepairEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit: RepairEmit | undefined, fn: (emit: RepairEmit) => void): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** The event names VC6C emits, exported for the dashboard seam and tests. */
+export const REPAIR_EVENT_NAMES: readonly RepairEventName[] = [
+  "vector_cortex_repair_planned",
+  "vector_cortex_repair_pointer_switched",
+  "vector_cortex_repair_backoff",
+] as const;
+
+/** Report a planned rebuild: which subsystem, which generation, what delay. */
+export function reportRepairPlanned(
+  emit: RepairEmit | undefined,
+  payload: {
+    readonly subsystem: string;
+    readonly generation: number;
+    readonly backoffMs: number;
+    readonly gapSize: number;
+  },
+): void {
+  if (!VC6C_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_repair_planned", {
+      ts: undefined,
+      event: "vector_cortex_repair_planned",
+      subsystem: payload.subsystem,
+      generation: payload.generation,
+      backoffMs: payload.backoffMs,
+      gapSize: payload.gapSize,
+    }),
+  );
+}
+
+/** Report the atomic commit: a verified generation became live. */
+export function reportRepairPointerSwitched(
+  emit: RepairEmit | undefined,
+  payload: {
+    readonly subsystem: string;
+    readonly fromGeneration: number;
+    readonly toGeneration: number;
+    readonly mode: Mode;
+  },
+): void {
+  if (!VC6C_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_repair_pointer_switched", {
+      ts: undefined,
+      event: "vector_cortex_repair_pointer_switched",
+      subsystem: payload.subsystem,
+      fromGeneration: payload.fromGeneration,
+      toGeneration: payload.toGeneration,
+      mode: payload.mode,
+    }),
+  );
+}
+
+/** Report a suppressed or failed rebuild now waiting out its backoff. */
+export function reportRepairBackoff(
+  emit: RepairEmit | undefined,
+  payload: {
+    readonly subsystem: string;
+    readonly code: RepairFailureCode;
+    readonly backoffMs: number;
+    readonly attempt: number;
+  },
+): void {
+  if (!VC6C_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_repair_backoff", {
+      ts: undefined,
+      event: "vector_cortex_repair_backoff",
+      subsystem: payload.subsystem,
+      code: payload.code,
+      backoffMs: payload.backoffMs,
+      attempt: payload.attempt,
+    }),
+  );
+}