pi-mega-compact 0.20.7 → 0.20.9

package/src/vector-cortex/heal/closure-opt.ts

@@ -0,0 +1,266 @@
+/**
+ * vector-cortex/heal/closure-opt.ts — VC6A deterministic transitive reduction
+ * over the ALREADY-MANDATORY VC4C closure.
+ *
+ * WHAT THIS DOES NOT DO: it does not close anything and it does not change which
+ * nodes are selected. `closeSelection` (VC4C) has already run and produced the
+ * mandatory set; CONTRACTS §plan and closure is explicit that "VC6 only
+ * optimizes restoration/self-healing". This module takes that closed set and
+ * shrinks the EDGE PLAN used to justify/re-walk it.
+ *
+ * THE REDUCTION. Requirements flow prerequisite `from` → dependent `to`, and
+ * closure walks them BACKWARD (selecting `to` pulls in `from`). So the
+ * requirement relation is `to ⇒ from`. If `c ⇒ b` and `b ⇒ a` are both in the
+ * plan, then a third edge `c ⇒ a` adds nothing: walking `c` already reaches `a`
+ * through `b`. That third edge is transitively implied and is the only kind of
+ * edge this module removes.
+ *
+ * WHAT IS NEVER REMOVED (task 3):
+ *   - a `tool-pair` edge          — the pair is atomic (PREVENT-PI-002);
+ *   - any edge touching an anchor — the floor is preserved (PREVENT-PI-001);
+ *   - a `contradicts` edge        — the resolver reads it directly, so removing
+ *                                   it would change the resolved set;
+ *   - a SOLE dependency edge      — the only edge pulling its prerequisite in.
+ * Every considered edge — retained or removed — is recorded in the proof, so the
+ * verifier can replay the decision rather than trust it.
+ *
+ * DETERMINISM. Vertices and edges are sorted by ID BYTES (the same bytewise
+ * comparator `reconstruct/closure.ts` uses), the reachability search drains a
+ * sorted worklist, and every emitted array is sorted. Two graphs that differ
+ * only in input order produce byte-identical proofs.
+ *
+ * PURITY. No storage, no console, no clock, no network (PREVENT-PI-004 /
+ * PREVENT-011). The FLAG DOES NOT GATE THIS ARITHMETIC: `MEGACOMPACT_VC6A=0`
+ * gates the reporter + dashboard seam only (see `emit.ts`), exactly as
+ * VC5B/VC5C do, so flag-off is byte-identical to the predecessor.
+ */
+
+import type { ClosureEdge, ClosureGraph, ClosureResult } from "../reconstruct/types.js";
+import type { ClosureProofRow, ClosureProofV2, RetainReason } from "./types.js";
+
+/** Bytewise id comparator — identical to `reconstruct/closure.ts::sortedIds`. */
+function byBytes(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Total order over edges: `from`, then `to`, then `kind` — all bytewise. */
+function compareEdges(x: ClosureEdge, y: ClosureEdge): number {
+  return byBytes(x.from, y.from) || byBytes(x.to, y.to) || byBytes(x.kind, y.kind);
+}
+
+/** Sorted copy of an edge list (never mutates the caller's array). */
+function sortedEdges(edges: readonly ClosureEdge[]): ClosureEdge[] {
+  return [...edges].sort(compareEdges);
+}
+
+/**
+ * The requirement adjacency of a plan: for a dependent node, which prerequisites
+ * it pulls in. Mirrors `reconstruct/closure.ts::buildRequirements` — `depends`
+ * walks backward to the prerequisite, `tool-pair` walks BOTH ways because a pair
+ * is atomic. `contradicts` never pulls a node in and is therefore absent here
+ * (it is still protected from removal; it simply is not a traversal edge).
+ */
+function requirementAdjacency(edges: readonly ClosureEdge[]): Map<string, string[]> {
+  const adj = new Map<string, string[]>();
+  const add = (key: string, value: string): void => {
+    const list = adj.get(key);
+    if (list === undefined) adj.set(key, [value]);
+    else list.push(value);
+  };
+  for (const e of edges) {
+    if (e.kind === "depends") add(e.to, e.from);
+    else if (e.kind === "tool-pair") {
+      add(e.to, e.from);
+      add(e.from, e.to);
+    }
+  }
+  for (const list of adj.values()) list.sort(byBytes);
+  return adj;
+}
+
+/**
+ * Is `target` reachable from `start` through the requirement adjacency WITHOUT
+ * using the direct `start ⇒ target` hop? Returns the witnessing intermediate
+ * vertex (the first hop of the detour, bytewise-smallest) or `null`.
+ *
+ * This is the "alternate path exists" test that licenses a removal. The direct
+ * hop is excluded so an edge can never justify its own removal; a cycle simply
+ * revisits `seen` and terminates.
+ */
+function alternatePathVia(
+  adj: ReadonlyMap<string, string[]>,
+  start: string,
+  target: string,
+): string | null {
+  // First hops other than the direct one, in bytewise order so the witness is
+  // deterministic when several detours exist.
+  const firstHops = (adj.get(start) ?? []).filter((n) => n !== target);
+  for (const hop of firstHops) {
+    // Breadth-first from this hop; `seen` excludes `start` so a detour that
+    // loops back through the origin cannot be counted as progress.
+    const seen = new Set<string>([start]);
+    const worklist: string[] = [hop];
+    while (worklist.length > 0) {
+      worklist.sort(byBytes);
+      const current = worklist.shift();
+      if (current === undefined) break;
+      if (current === target) return hop;
+      if (seen.has(current)) continue;
+      seen.add(current);
+      for (const next of adj.get(current) ?? []) {
+        if (!seen.has(next)) worklist.push(next);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Is `target` reachable from `start` using ONLY the edges in `others` (a path of
+ * length >= 2, never the direct hop)? Returns the bytewise-smallest first-hop
+ * vertex (the witness `via`) or `null`.
+ *
+ * The transitive-reduction correctness rule: an edge `start ⇒ target` is
+ * redundant only if a length>=2 path exists through the OTHER edges. Crucially
+ * we EXCLUDE the edge under consideration, so removing one edge never invalidates
+ * the witness used to justify removing ANOTHER — a plain single-pass check over
+ * the full adjacency over-removes (HEAL-PROTECT-002: a tool pair backs two
+ * depends edges that would each look implied by the full graph but only survive
+ * together).
+ */
+function alternatePathExcluding(
+  others: readonly ClosureEdge[],
+  start: string,
+  target: string,
+): string | null {
+  const adj = requirementAdjacency(others);
+  return alternatePathVia(adj, start, target);
+}
+
+/** The set of node ids marked as anchor-floor members in the graph. */
+function anchorIds(graph: ClosureGraph): Set<string> {
+  const out = new Set<string>();
+  for (const n of graph.nodes) if (n.anchor === true) out.add(n.id);
+  return out;
+}
+
+/**
+ * Count how many `depends` edges pull in each prerequisite. A prerequisite with
+ * exactly one such edge has a SOLE dependency edge: removing it would drop the
+ * prerequisite from the closure entirely, so it is protected regardless of any
+ * alternate path.
+ */
+function dependsFanIn(edges: readonly ClosureEdge[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const e of edges) {
+    if (e.kind !== "depends") continue;
+    counts.set(e.from, (counts.get(e.from) ?? 0) + 1);
+  }
+  return counts;
+}
+
+/**
+ * Classify a NON-removable edge, or return `null` when the edge is an ordinary
+ * `depends` edge that removal is at least allowed to consider.
+ *
+ * Order matters and is deliberate: the strongest structural guarantee is
+ * reported first, so a tool-pair edge that also touches an anchor is recorded as
+ * `tool-pair` and the proof reads as the reason a reviewer would give.
+ */
+function protectedReason(
+  edge: ClosureEdge,
+  anchors: ReadonlySet<string>,
+  fanIn: ReadonlyMap<string, number>,
+): RetainReason | null {
+  if (edge.kind === "tool-pair") return "tool-pair";
+  if (edge.kind === "contradicts") return "contradiction";
+  if (anchors.has(edge.from) || anchors.has(edge.to)) return "anchor";
+  if ((fanIn.get(edge.from) ?? 0) <= 1) return "sole-dependency";
+  return null;
+}
+
+/** Input to one optimization run: the graph plus the conservative VC4C result. */
+export interface ClosureOptInput {
+  readonly graph: ClosureGraph;
+  /** The ALREADY-COMPUTED conservative closure (VC4C `closeSelection`). */
+  readonly conservative: ClosureResult;
+}
+
+/**
+ * Optimize the already-mandatory closure by transitive reduction (task 2).
+ *
+ * Only edges INSIDE the closed selection are considered: an edge touching an
+ * unselected node is not part of the traversal plan for this closure at all, so
+ * it is neither retained nor removed — it is simply out of scope and produces no
+ * proof row.
+ *
+ * `selected` is copied through UNCHANGED. That is the whole safety property: the
+ * optimizer is allowed to make the plan cheaper, never to make it smaller.
+ */
+export function optimizeClosure(input: ClosureOptInput): ClosureProofV2 {
+  const { graph, conservative } = input;
+  const selected = new Set(conservative.selected);
+  const anchors = anchorIds(graph);
+
+  // Consider only in-selection edges, in deterministic bytewise order.
+  const considered = sortedEdges(
+    graph.edges.filter((e) => selected.has(e.from) && selected.has(e.to)),
+  );
+  const fanIn = dependsFanIn(considered);
+
+  const rows: ClosureProofRow[] = [];
+  const retained: ClosureEdge[] = [];
+  const removed: ClosureEdge[] = [];
+
+  for (const e of considered) {
+    const guard = protectedReason(e, anchors, fanIn);
+    if (guard !== null) {
+      // Protected: retained unconditionally, EVEN WHEN an alternate path exists
+      // (HEAL-PROTECT-002). The reason names the guarantee, not the topology.
+      rows.push({ from: e.from, to: e.to, kind: e.kind, decision: "retained", reason: guard });
+      retained.push(e);
+      continue;
+    }
+    // Ordinary `depends` edge: removable iff the requirement it carries is
+    // already carried by a longer path `to ⇒ via ⇒ ... ⇒ from` through the OTHER
+    // edges (the edge under test is excluded so removals stay mutually valid).
+    const others = considered.filter((o) => o !== e);
+    const via = alternatePathExcluding(others, e.to, e.from);
+    if (via === null) {
+      rows.push({
+        from: e.from,
+        to: e.to,
+        kind: e.kind,
+        decision: "retained",
+        reason: "no-alternate-path",
+      });
+      retained.push(e);
+      continue;
+    }
+    rows.push({
+      from: e.from,
+      to: e.to,
+      kind: e.kind,
+      decision: "removed",
+      reason: "transitively-implied",
+      via,
+    });
+    removed.push(e);
+  }
+
+  return {
+    schema: "closure-proof-v2",
+    sessionId: graph.sessionId,
+    selected: [...conservative.selected],
+    retainedEdges: sortedEdges(retained),
+    removedEdges: sortedEdges(removed),
+    rows,
+    conservativeTraversals: considered.length,
+    optimizedTraversals: retained.length,
+  };
+}
+
+// Metrics + VC6B handoff (traversal savings, RestoreHintV1) live in the
+// delegate-shell sibling `closure-metrics.ts` to keep this core reduction
+// algorithm under the 300-line soft limit.
+export { traversalSavings, restoreHints } from "./closure-metrics.js";

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

@@ -0,0 +1,93 @@
+/**
+ * vector-cortex/heal/emit.ts — VC6A event reporter seam (task 5).
+ *
+ * Mirrors `../rollout/emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit` (so unit tests stay pure — they pass `undefined` and inspect
+ * nothing), and two event names required verbatim by the sprint spec:
+ *   - `vector_cortex_closure_optimized`   — emitted when a proof is produced.
+ *   - `vector_cortex_closure_proof_rejected` — emitted when verification fails.
+ *
+ * FLAG SEMANTICS (the invariant VC5B/VC5C established). The optimizer and
+ * verifier are PURE arithmetic and run REGARDLESS of the flag. The flag gates
+ * ONLY the reporting + dashboard seam: when `MEGACOMPACT_VC6A=0` we still compute
+ * the proof (needed for byte-identical parity with the predecessor), we just do
+ * not emit the VC6A-namespaced events. This is what makes flag-off byte-identical
+ * to VC5C — the arithmetic is never skipped, only the announcement.
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+
+import { VC6A_ENABLED } from "../../config/vector-cortex.js";
+import type { HealEventName } from "./types.js";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type HealEmit = (name: string, payload: unknown) => void;
+
+/**
+ * Run `fn` only when an emit is available, swallowing and logging nothing on
+ * failure (PRACTICES: non-fatal stores). `fn` receives the emit so callers need
+ * not null-check.
+ */
+function safe(emit: HealEmit | undefined, fn: (emit: HealEmit) => void): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** The event names VC6A emits, exported for the dashboard seam and tests. */
+export const HEAL_EVENT_NAMES: readonly HealEventName[] = [
+  "vector_cortex_closure_optimized",
+  "vector_cortex_closure_proof_rejected",
+] as const;
+
+/**
+ * Report a successful optimization. `MEGACOMPACT_VC6A=0` suppresses the VC6A
+ * event (flag-off parity) but does not affect the computation that produced
+ * `proof`.
+ */
+export function reportClosureOptimized(
+  emit: HealEmit | undefined,
+  payload: {
+    readonly sessionId: string;
+    readonly removed: number;
+    readonly retained: number;
+    readonly savings: number;
+  },
+): void {
+  if (!VC6A_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_closure_optimized", {
+      ts: undefined,
+      event: "vector_cortex_closure_optimized",
+      sessionId: payload.sessionId,
+      removedEdges: payload.removed,
+      retainedEdges: payload.retained,
+      traversalSavings: payload.savings,
+    }),
+  );
+}
+
+/** Report a rejected proof. Suppressed under flag-off, like the above. */
+export function reportProofRejected(
+  emit: HealEmit | undefined,
+  payload: {
+    readonly sessionId: string;
+    readonly reason: string;
+    readonly mode: "B" | "C";
+  },
+): void {
+  if (!VC6A_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_closure_proof_rejected", {
+      ts: undefined,
+      event: "vector_cortex_closure_proof_rejected",
+      sessionId: payload.sessionId,
+      reason: payload.reason,
+      fallbackMode: payload.mode,
+    }),
+  );
+}

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

@@ -0,0 +1,234 @@
+/**
+ * vector-cortex/heal/proof.ts — VC6A proof verifier (task 4).
+ *
+ * The optimizer (`closure-opt.ts`) is PURE and cheap, but a proof is cheap to
+ * LIE about: a buggy or tampered producer could ship a proof that removes an
+ * edge the conservative closure actually needs. The verifier does not trust the
+ * proof — it REPLAYS it against the conservative oracle from scratch.
+ *
+ * REPLAY. From the conservative `ClosureResult` we rebuild the requirement
+ * adjacency (`to ⇒ from` for `depends`, both directions for `tool-pair`) over
+ * the in-selection edges — exactly the relation `closure-opt` reduced over.
+ * For every row the proof claims to REMOVE, the verifier independently confirms
+ * the same alternate path exists. For every row it claims to RETAIN, it confirms
+ * the protection reason holds (or that no alternate path exists). Any row that
+ * fails its own predicate is a witness violation.
+ *
+ * SELECTED-SET DIVERGENCE (the cardinal sin). The proof must contain the SAME
+ * selected set as the conservative oracle, byte for byte. Closure optimization
+ * is allowed to make the plan cheaper, never smaller — so if the proof's
+ * `selected` differs from the oracle's, that is `HEAL_PROOF_SET_MISMATCH` and the
+ * repaired triad must fall back to mode B (the conservative closure) and
+ * ultimately C (VC5C's legacy prompt) if even that fails.
+ *
+ * PURE / DETERMINISTIC / LOCAL, like everything in `heal/`: no storage, no
+ * console, no clock, no network (PREVENT-PI-004 / PREVENT-011). The verifier
+ * reads only types and the two ClosureEdge/ClosureGraph/ClosureResult shapes.
+ */
+
+import type { ClosureGraph, ClosureResult } from "../reconstruct/types.js";
+import type {
+  ClosureProofRow,
+  ClosureProofV2,
+  HealFailureCode,
+  HealMode,
+  HealTriadOutcome,
+  ProofVerification,
+} from "./types.js";
+
+/** Bytewise id comparator — matches `closure-opt.ts` / `reconstruct/closure.ts`. */
+function byBytes(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Requirement adjacency over an edge list, identical to `closure-opt`. */
+function requirementAdjacency(edges: readonly ClosureProofRow[]): Map<string, string[]> {
+  const adj = new Map<string, string[]>();
+  const add = (key: string, value: string): void => {
+    const list = adj.get(key);
+    if (list === undefined) adj.set(key, [value]);
+    else list.push(value);
+  };
+  for (const row of edges) {
+    if (row.kind === "contradicts") continue; // not a traversal edge
+    if (row.kind === "depends") add(row.to, row.from);
+    else if (row.kind === "tool-pair") {
+      add(row.to, row.from);
+      add(row.from, row.to);
+    }
+  }
+  for (const list of adj.values()) list.sort(byBytes);
+  return adj;
+}
+
+/** Does a detour `start ⇒ via ⇒ ... ⇒ target` exist, excluding the direct hop? */
+function alternatePathVia(
+  adj: ReadonlyMap<string, string[]>,
+  start: string,
+  target: string,
+): string | null {
+  for (const hop of (adj.get(start) ?? []).filter((n) => n !== target)) {
+    const seen = new Set<string>([start]);
+    const worklist: string[] = [hop];
+    while (worklist.length > 0) {
+      worklist.sort(byBytes);
+      const current = worklist.shift();
+      if (current === undefined) break;
+      if (current === target) return hop;
+      if (seen.has(current)) continue;
+      seen.add(current);
+      for (const next of adj.get(current) ?? []) {
+        if (!seen.has(next)) worklist.push(next);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Verify a `ClosureProofV2` produced for an already-closed graph.
+ *
+ * Returns `{ ok: true, selected }` when the replay confirms the optimized plan is
+ * provably equivalent to the conservative closure — mode A may be used. On any
+ * divergence it returns `{ ok: false, codes }` listing every failure code; the
+ * caller routes to mode B (conservative) and, if that also fails, mode C (legacy,
+ * with `semanticLossStated`). The verifier is idempotent — replaying the same
+ * proof twice yields the same verdict, which `vc6a-acceptance.test.ts` asserts.
+ */
+export function verifyProof(
+  proof: ClosureProofV2,
+  conservative: ClosureResult,
+  graph?: ClosureGraph,
+): ProofVerification {
+  const codes: HealFailureCode[] = [];
+  const inSelection = new Set(conservative.selected);
+  const anchors = new Set(
+    (graph?.nodes ?? []).filter((n) => n.anchor === true).map((n) => n.id),
+  );
+
+  // 1. Selected-set divergence is the hard gate (task 4: HEAL_PROOF_SET_MISMATCH).
+  const oracleSelected = [...conservative.selected].sort(byBytes);
+  const proofSelected = [...proof.selected].sort(byBytes);
+  const selectedMatch =
+    oracleSelected.length === proofSelected.length &&
+    oracleSelected.every((id, i) => id === proofSelected[i]);
+  if (!selectedMatch) codes.push("HEAL_PROOF_SET_MISMATCH");
+
+  // 2. Re-check each row against its own predicate. For a removal, the witness
+  //    is validated against the OTHER rows (the reduced graph), so a removal
+  //    never justifies another's witness — this catches both a missing-witness
+  //    removal (HEAL-PROOF-003) and a protected edge that was removed
+  //    (HEAL_PROOF_PROTECTED_REMOVED).
+
+  for (const row of proof.rows) {
+    // Out-of-scope rows (touch an unselected node) should never have been
+    // emitted; treat as a witness violation so a malformed proof fails loudly.
+    if (!inSelection.has(row.from) || !inSelection.has(row.to)) {
+      codes.push("HEAL_PROOF_WITNESS_INVALID");
+      continue;
+    }
+    if (row.decision === "removed") {
+      // A removal MUST carry a witness and the witness MUST still validate
+      // against the OTHER rows (the reduced graph) — never the row itself, so a
+      // removal never justifies another's witness (matches the optimizer's
+      // exclusion rule).
+      if (row.via === undefined) {
+        codes.push("HEAL_PROOF_WITNESS_INVALID");
+        continue;
+      }
+      const others = proof.rows.filter((r) => r !== row);
+      const witness = alternatePathVia(requirementAdjacency(others), row.to, row.from);
+      if (witness === null) {
+        codes.push("HEAL_PROOF_WITNESS_INVALID");
+        continue;
+      }
+      if (anchors.has(row.from) || anchors.has(row.to)) {
+        // Topology says removable, but an anchor edge is NEVER removable.
+        codes.push("HEAL_PROOF_PROTECTED_REMOVED");
+        continue;
+      }
+      if (row.kind === "tool-pair" || row.kind === "contradicts") {
+        // Both are protected regardless of topology.
+        codes.push("HEAL_PROOF_PROTECTED_REMOVED");
+      }
+    } else {
+      // A retained plain depends edge that claims `no-alternate-path` but
+      // actually HAS one (through the other rows) is an internal inconsistency:
+      // the optimizer kept a removable edge without removing it. The proof is
+      // internally contradictory, so it fails replay.
+      if (row.kind === "depends" && row.reason === "no-alternate-path") {
+        const others = proof.rows.filter((r) => r !== row);
+        const hasPath = alternatePathVia(requirementAdjacency(others), row.to, row.from);
+        if (hasPath !== null) codes.push("HEAL_PROOF_WITNESS_INVALID");
+      }
+    }
+  }
+
+  // 3. Completeness: every in-selection edge the optimizer considered must appear
+  //    in the proof. A dropped row (the unique-injection test drops one) surfaces
+  //    as HEAL_PROOF_INCOMPLETE even if the remaining rows replay fine — the proof
+  //    must account for EVERY considered edge. `conservativeTraversals` is the
+  //    optimizer's own record of how many edges it fed through, so `rows.length`
+  //    must equal it exactly.
+  if (proof.rows.length < proof.conservativeTraversals) {
+    codes.push("HEAL_PROOF_INCOMPLETE");
+  }
+
+  if (codes.length === 0) {
+    return { ok: true, selected: proofSelected };
+  }
+  return { ok: false, codes: [...new Set(codes)] };
+}
+
+/**
+ * Drive the A/B/C resilient triad for one closure (task 5 wiring; VC6A exposes
+ * the decision; the actual selection/budget work is VC4C/VC5A respectively).
+ *
+ *  - A: the optimized proof verified cleanly → ship the optimized plan.
+ *  - B: proof rejected → fall back to the conservative VC4C closure (no opt).
+ *  - C: B also failed (should not happen for a sound conservative closure) →
+ *       state the legacy prompt path with `semanticLossStated`.
+ *
+ * This is PURE: it returns the verdict and which mode to use; it does not emit,
+ * store, or touch the network. The emit seam (`emit.ts`) consumes the outcome.
+ */
+export function selectHealMode(
+  proof: ClosureProofV2,
+  conservative: ClosureResult,
+  graph?: ClosureGraph,
+): HealTriadOutcome {
+  const verification = verifyProof(proof, conservative, graph);
+  if (verification.ok) {
+    return {
+      mode: "A" as HealMode,
+      proof,
+      selected: [...proof.selected],
+      codes: [],
+      semanticLossStated: false,
+    };
+  }
+  // Mode B: conservative closure is sound by construction (it is the oracle the
+  // proof was measured against). Use it directly.
+  return {
+    mode: "B" as HealMode,
+    proof: null,
+    selected: [...conservative.selected],
+    codes: verification.codes,
+    semanticLossStated: false,
+  };
+}
+
+/**
+ * Convenience for the rare B-failure path: if even the conservative oracle's
+ * selection cannot be honored, state the legacy prompt and MARK semantic loss.
+ * Mode C is the last resort and the only place semantic loss is ever admitted.
+ */
+export function legacyFallback(conservative: ClosureResult, reason: HealFailureCode): HealTriadOutcome {
+  return {
+    mode: "C" as HealMode,
+    proof: null,
+    selected: [...conservative.selected],
+    codes: [reason, "HEAL_CLOSURE_REJECTED"],
+    semanticLossStated: true,
+  };
+}

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