pi-mega-compact 0.20.8 → 0.20.10

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

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

@@ -0,0 +1,227 @@
+/**
+ * vector-cortex/heal/repair-types.ts — VC6C self-healing derived controller.
+ *
+ * VC6B answered "when a node's bytes are gone, WHERE do they come from?". VC6C
+ * answers the question one level up: when a DERIVED subsystem (topology, shards,
+ * closure) has fallen BEHIND the durable authority, how do we notice, and how do
+ * we catch it up without ever risking the authority itself?
+ *
+ * THE AUTHORITY IS READ-ONLY, ALWAYS. The controller compares each derived
+ * source's high-water to the durable authority high-water and plans work. It has
+ * no write path to the authority — not a guarded one, not an admin one. Derived
+ * state is disposable and can always be rebuilt from the byte ledger; the
+ * authority is not, so the repair path is deliberately one-directional. This is
+ * why `RepairState` carries `authorityHighWater` as a plain readonly field and
+ * why no function in `controller.ts` returns anything that could be applied to it.
+ *
+ * NEVER READ PAST THE AUTHORITY (TRIAD_RESILIENCE §frontier). A derived builder
+ * may not read beyond the durable CONTIGUOUS authority high-water. During an
+ * authority outage that high-water FREEZES even though the spool keeps accepting
+ * frames — so a derived subsystem that is "behind" a frozen frontier is CORRECT,
+ * not broken, and planning a rebuild against the spool tail would materialize
+ * frames that are not yet durable. `detectGaps` therefore treats
+ * `authorityFrozen` as a hard stop (`HEAL_REPAIR_AUTHORITY_FROZEN`) rather than
+ * as a large gap to chase. After the drain, catch-up resumes from the OLD
+ * high-water; it never jumps to the tail.
+ *
+ * REBUILD IS COPY-THEN-SWITCH, NEVER IN-PLACE. `rebuild.ts` materializes a NEW
+ * generation, verifies its root digest, and only then flips the pointer. A failed
+ * verification keeps the old pointer and DELETES NO EVIDENCE: the corrupt
+ * generation stays on disk to be inspected. An in-place repair would, by
+ * construction, destroy the only copy of the thing that was about to be proven
+ * wrong.
+ *
+ * RATE LIMIT + BACKOFF ARE THE BLAST RADIUS. A subsystem that fails to rebuild
+ * will fail again, usually instantly, so an unbounded retry loop turns one broken
+ * shard into a CPU-saturating rebuild storm. One rebuild per subsystem per 5
+ * minutes bounds the steady state, and the deterministic exponential backoff
+ * (30s * 2^attempt, capped at 15 min, ±10% jitter derived from the SUBSYSTEM
+ * DIGEST rather than `Math.random`) bounds the failure state while keeping the
+ * schedule reproducible in a fixture.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no clock, no
+ * network (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import type { ShardRange } from "../shards/types.js";
+import type { EventV2 } from "../ledger/types.js";
+
+/** The triad mode, mirroring TRIAD_RESILIENCE (A targeted / B full / C disable). */
+export type Mode = "A" | "B" | "C";
+
+/**
+ * A derived subsystem name (e.g. "topology", "shards", "closure").
+ *
+ * Deliberately a plain string rather than a closed union: the set of derived
+ * subsystems grows every sprint, and a union here would force an unrelated
+ * contract edit (and a conformance-corpus regeneration) every time a new derived
+ * tier is added. The subsystem name is also the jitter seed, so it must be stable.
+ */
+export type RepairSubsystem = string;
+
+/**
+ * A planned rebuild for ONE subsystem.
+ *
+ * `range` is the gap to rebuild — derived high-water (exclusive) to authority
+ * high-water (inclusive) — so a plan is self-describing: an operator can read the
+ * exact seq window that will be materialized. `generation` is the NEW generation
+ * the rebuild will write into (never the live one). `backoffMs` is the delay
+ * BEFORE the plan may execute, and `scheduledAt` is the monotonic timestamp it
+ * becomes eligible.
+ */
+export interface RepairPlanV1 {
+  readonly schema: "repair-plan-v1";
+  readonly subsystem: RepairSubsystem;
+  /** The seq/byte window to rebuild (derived high-water .. authority high-water). */
+  readonly range: ShardRange;
+  /** The NEW generation number the rebuild materializes into. */
+  readonly generation: number;
+  /** Deterministic delay before this plan is eligible to run. */
+  readonly backoffMs: number;
+  /** Monotonic ms at which the plan becomes eligible (`now + backoffMs`). */
+  readonly scheduledAt: bigint;
+}
+
+/**
+ * A repair lifecycle record. Emitted as a structured event AND retained for the
+ * dashboard's repair state, so it carries identity and counters only — never a
+ * rebuilt byte, never a node id, never transcript text (SECURITY_PRIVACY).
+ */
+export interface RepairEventV1 {
+  readonly schema: "repair-event-v1";
+  readonly subsystem: RepairSubsystem;
+  /**
+   * `planned`          — a gap was detected and a rebuild scheduled.
+   * `pointer-switched` — a verified generation became live (the ONLY success).
+   * `backoff`          — a rebuild was suppressed (rate limit) or failed and is
+   *                      now waiting out its exponential delay.
+   */
+  readonly kind: "planned" | "pointer-switched" | "backoff";
+  readonly generation: number;
+  /** Monotonic ms of the transition. */
+  readonly ts: bigint;
+}
+
+/** VC6C failure codes (registered HEAL codes). */
+export type RepairFailureCode =
+  /**
+   * The authority high-water is frozen (outage). Derived state is CORRECTLY
+   * behind and must not chase the spool tail — planning is refused, not delayed.
+   */
+  | "HEAL_REPAIR_AUTHORITY_FROZEN"
+  /** A rebuilt generation's root digest does not match — pointer NOT switched. */
+  | "HEAL_REPAIR_DIGEST_MISMATCH"
+  /** The rebuild itself could not produce a generation (mode C disable). */
+  | "HEAL_REBUILD_FAILED"
+  /** A second rebuild for this subsystem inside the 5-minute window. */
+  | "HEAL_REPAIR_RATE_LIMITED";
+
+/**
+ * The controller's view of ONE derived subsystem.
+ *
+ * `authorityHighWater` is READ, never written (see the file header). `mode`
+ * records which triad arm this subsystem is currently served by, so a subsystem
+ * already in mode C (derived state disabled) is not repeatedly re-planned.
+ */
+export interface RepairState {
+  readonly subsystem: RepairSubsystem;
+  /** How far the derived source has been built (inclusive seq). */
+  readonly derivedHighWater: bigint;
+  /** Durable CONTIGUOUS authority high-water (inclusive seq). Read-only. */
+  readonly authorityHighWater: bigint;
+  /** Monotonic ms of the last rebuild, or null if never rebuilt. */
+  readonly lastRebuildAt: bigint | null;
+  /** The CURRENT live generation. A plan targets `generation + 1`. */
+  readonly generation: number;
+  /** Which triad arm currently serves this subsystem. */
+  readonly mode: Mode;
+  /**
+   * Consecutive failed rebuild attempts, the exponent in `30s * 2^attempt`.
+   * Reset to 0 on a successful pointer switch.
+   */
+  readonly failedAttempts?: number;
+  /**
+   * True while the durable authority frontier is frozen (outage). A frozen
+   * authority makes a derived lag EXPECTED, so no plan may be produced.
+   */
+  readonly authorityFrozen?: boolean;
+}
+
+/** The gap-detection + planning surface. Pure: no clock of its own, no I/O. */
+export interface RepairController {
+  /** Plan a rebuild for every subsystem with a real, actionable gap. */
+  readonly detectGaps: (
+    states: readonly RepairState[],
+    nowMs: bigint,
+  ) => readonly RepairPlanV1[];
+  /** Build a single plan for one subsystem's gap. */
+  readonly planRebuild: (state: RepairState, nowMs: bigint) => RepairPlanV1;
+}
+
+/**
+ * One rebuild per subsystem per 5 minutes. Bounds a rebuild storm: a subsystem
+ * that fails will fail again immediately, and without this an unhealthy tier
+ * would saturate the box re-materializing the same broken generation.
+ */
+export const REPAIR_RATE_LIMIT_MS = 5 * 60_000;
+
+/**
+ * Exponential backoff base/cap, matching the breaker's retry rule
+ * (TRIAD_RESILIENCE): `30s * 2^attempt`, capped at 15 minutes.
+ */
+export const REPAIR_BACKOFF_BASE_MS = 30_000;
+export const REPAIR_BACKOFF_CAP_MS = 15 * 60_000;
+
+/**
+ * ±10% deterministic jitter. Derived from the SUBSYSTEM DIGEST, not a PRNG, so
+ * two subsystems desynchronize (no thundering herd) while any single subsystem's
+ * schedule stays reproducible in a fixture.
+ */
+export const REPAIR_BACKOFF_JITTER = 0.1;
+
+/**
+ * Registered VC6C conformance ID range (HEAL-031..045), continuing VC6B's
+ * HEAL-016..030. The acceptance test reads these rows from the v2 manifest and
+ * asserts each returns its manifest `ok`/`code`.
+ */
+export const REPAIR_IDS: readonly string[] = Array.from(
+  { length: 15 },
+  (_v, i) => `HEAL-${String(i + 31).padStart(3, "0")}`,
+);
+
+/** Named VC6C conformance assertions (the sprint's headline rows). */
+export const REPAIR_NAMED_IDS = [
+  "HEAL-GAP-001",
+  "HEAL-RATE-002",
+  "HEAL-SWITCH-003",
+] as const;
+
+/** The three structured events the VC6C reporter emits. */
+export type RepairEventName =
+  | "vector_cortex_repair_planned"
+  | "vector_cortex_repair_pointer_switched"
+  | "vector_cortex_repair_backoff";
+
+/**
+ * Reader-only dashboard aggregate. Counters and the runtime mode only — no
+ * subsystem payload, no rebuilt bytes, no gap ranges, no high-water marks, no
+ * root digests (SECURITY_PRIVACY).
+ *
+ * Field names mirror `VectorCortexRepairView` in
+ * `extensions/dashboard-server/api-contracts/vector-cortex-heal.ts` EXACTLY.
+ * The dashboard contract is the shipped shape; keeping a differently-named
+ * mirror here would guarantee a silent drift the compiler could never catch,
+ * since the route builds its body from the extensions-side type.
+ */
+export interface RepairView {
+  readonly enabled: boolean;
+  readonly mode: Mode;
+  readonly repairAttempts: number;
+  readonly repairsPlanned: number;
+  readonly pointersSwitched: number;
+  readonly backoffs: number;
+  readonly lastBackoffMs: number | null;
+  readonly lastFailure: RepairFailureCode | null;
+}
+
+export type { EventV2, ShardRange };

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

@@ -0,0 +1,94 @@
+/**
+ * vector-cortex/heal/restore-emit.ts — VC6B event reporter seam.
+ *
+ * Mirrors `./emit.ts`: a thin `safe()` wrapper around an optional injected
+ * `emit` (unit tests pass `undefined` and stay pure), and the two event names the
+ * sprint spec requires verbatim:
+ *   - `vector_cortex_source_restored`         — a restore batch completed.
+ *   - `vector_cortex_restore_digest_rejected` — a source failed its digest check.
+ *
+ * FLAG SEMANTICS. `restoreSources` / `verifyRestored` are PURE arithmetic and run
+ * REGARDLESS of `MEGACOMPACT_VC6B`. The flag gates ONLY this reporting +
+ * dashboard seam: with the flag off we still restore and still verify, we just do
+ * not announce it under the VC6B event namespace. That is what makes flag-off
+ * byte-identical to VC6A — the computation is never skipped, only the emission.
+ *
+ * PAYLOAD DISCIPLINE. These events carry COUNTS and MODES only — never restored
+ * bytes, never node text, never a digest of user content. The exact ledger is not
+ * diagnostic data (SECURITY_PRIVACY), and a restoration event is exactly the
+ * place where an unguarded `payload` field would leak the entire transcript into
+ * a log file.
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+
+import { VC6B_ENABLED } from "../../config/vector-cortex.js";
+import type { RestoreEventName, RestoreFailureCode } from "./restore-types.js";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type RestoreEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit: RestoreEmit | undefined, fn: (emit: RestoreEmit) => void): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** The event names VC6B emits, exported for the dashboard seam and tests. */
+export const RESTORE_EVENT_NAMES: readonly RestoreEventName[] = [
+  "vector_cortex_source_restored",
+  "vector_cortex_restore_digest_rejected",
+] as const;
+
+/**
+ * Report a completed restoration. Counts and mode only — enough to see whether
+ * the shard index is serving reads (mode A) or every span is falling through to
+ * a ledger scan (mode B), without disclosing what was restored.
+ */
+export function reportSourceRestored(
+  emit: RestoreEmit | undefined,
+  payload: {
+    readonly sessionId: string;
+    readonly restoredCount: number;
+    readonly missingCount: number;
+    readonly mode: "A" | "B" | "C";
+  },
+): void {
+  if (!VC6B_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_source_restored", {
+      ts: undefined,
+      event: "vector_cortex_source_restored",
+      sessionId: payload.sessionId,
+      restoredCount: payload.restoredCount,
+      missingCount: payload.missingCount,
+      mode: payload.mode,
+    }),
+  );
+}
+
+/** Report a rejected source (digest/limit/range). Suppressed under flag-off. */
+export function reportRestoreDigestRejected(
+  emit: RestoreEmit | undefined,
+  payload: {
+    readonly sessionId: string;
+    readonly code: RestoreFailureCode;
+    readonly mode: "A" | "B" | "C";
+  },
+): void {
+  if (!VC6B_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_restore_digest_rejected", {
+      ts: undefined,
+      event: "vector_cortex_restore_digest_rejected",
+      sessionId: payload.sessionId,
+      code: payload.code,
+      mode: payload.mode,
+    }),
+  );
+}