pi-mega-compact 0.20.7 → 0.20.9

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

@@ -0,0 +1,103 @@
+/**
+ * dashboard-server/routes-vector-cortex-heal.ts — VC6A closure-optimization and
+ * VC6B exact-source-restoration dashboard routes.
+ *
+ * Reader-only GET /api/vector-cortex/closure-proof returning aggregate-only
+ * closure diagnostics: whether the flag is enabled, the runtime triad mode, and
+ * cumulative edge/traversal counters. NEVER exposes per-edge proof rows, the
+ * closed selection, node ids, or any source payload (reader-only, SECURITY_PRIVACY
+ * — the detailed proof lives in the structured event log, not the dashboard).
+ *
+ * When the flag is OFF (`MEGACOMPACT_VC6A=0`) the runtime falls back to mode B
+ * (the conservative VC4C closure, no reduction) — that is exactly the spec's
+ * fallback rule — so `mode:"B"` + `enabled:false` is the byte-stable OFF view.
+ *
+ * Reader-only GET /api/vector-cortex/restore (VC6B) returns restore COUNTS and
+ * HEAL_RESTORE_* error codes only. There is NO payload endpoint for restoration,
+ * ever — no restored bytes, span ids, node ids, byte ranges, or ledger text.
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + mode only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC6A_ENABLED, VC6B_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type {
+  VectorCortexClosureProofView,
+  VectorCortexRestoreView,
+} from "./api-contracts/vector-cortex.js";
+
+/** Reader-only GET /api/vector-cortex/closure-proof (VC6A). */
+export function handleVectorCortexClosureProof(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/closure-proof") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC6A_ENABLED();
+  // Flag-off routes to mode B (conservative closure, no reduction) per spec.
+  const mode: "A" | "B" | "C" = enabled ? "A" : "B";
+  const body: VectorCortexClosureProofView = {
+    enabled,
+    mode,
+    optimizations: 0,
+    proofRejections: 0,
+    retainedEdgeTotal: 0,
+    removedEdgeTotal: 0,
+    conservativeTraversalTotal: 0,
+    optimizedTraversalTotal: 0,
+    lastRejection: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}
+
+/**
+ * Reader-only GET /api/vector-cortex/restore (VC6B).
+ *
+ * Counts and HEAL_RESTORE_* codes only — this is a static reader-only aggregate
+ * seam (same shape as the VC6A handler): there is no payload endpoint and never
+ * will be, so no restored bytes/span ids/node ids/ledger text can leak here.
+ */
+export function handleVectorCortexRestore(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/restore") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC6B_ENABLED();
+  // Flag-off routes to mode C: with VC6B off there is no exact-restoration path
+  // at all, so the honest OFF view is the disclose-loss mode (old context is
+  // omitted rather than inferred) — mirroring how VC6A's OFF view reports the
+  // conservative fallback it actually takes.
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexRestoreView = {
+    enabled,
+    mode,
+    restoreAttempts: 0,
+    restoredCount: 0,
+    missingCount: 0,
+    digestRejections: 0,
+    lastRejection: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

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

@@ -9,6 +9,8 @@
  *   VC0C health/reset-> routes-vector-cortex-health.ts(GET  /health, POST /breakers/reset)
  *   VC1B ledger      -> routes-vector-cortex-ledger.ts (GET  /ledger)
  *   VC3A topology    -> routes-vector-cortex-topology.ts(GET /topology)
+ *   VC6A closure     -> routes-vector-cortex-heal.ts   (GET  /closure-proof)
+ *   VC6B restore     -> routes-vector-cortex-heal.ts   (GET  /restore)
  *
  * Guardrails: PREVENT-PI-004 (local filesystem read only), PREVENT-011 (no
  * `any`), reader-only aggregates (never payloads/prompts/ledger text).
@@ -25,3 +27,7 @@ export { handleVectorCortexReconstruct } from "./routes-vector-cortex-reconstruc
 export { handleVectorCortexPlans } from "./routes-vector-cortex-plans.js";
 export { handleVectorCortexRender } from "./routes-vector-cortex-render.js";
 export { handleVectorCortexRollout } from "./routes-vector-cortex-rollout.js";
+export {
+	handleVectorCortexClosureProof,
+	handleVectorCortexRestore,
+} from "./routes-vector-cortex-heal.js";

package/extensions/dashboard-server/routes.ts

@@ -53,4 +53,6 @@ export {
 	handleVectorCortexPlans,
 	handleVectorCortexRender,
 	handleVectorCortexRollout,
+	handleVectorCortexClosureProof,
+	handleVectorCortexRestore,
 } from "./routes-vector-cortex.js";

package/extensions/dashboard-server/server.ts

@@ -26,51 +26,8 @@ import { createRequire } from "node:module";
 import { NEW_UI } from "../../src/config.js";
 import { log, setLogPath, setDashboardServerVersion } from "./state.js";
 import { detectTailscaleIP } from "./tailscale.js";
-import {
-	buildRouteContext,
-	handleIndex,
-	handleRepoIndex,
-	handleEvents,
-	handleGameState,
-	handleGameScores,
-	handlePerf,
-	handlePerfSamples,
-	handleAchievements,
-	handleSessions,
-	handleTopics,
-	handleTurns,
-	handleMaintenance,
-	handleProviderCache,
-	handleCacheStripes,
-	handleMemoryStatus,
-	handleSetupStatus,
-	handleSetupDetect,
-	handleSetupConfigure,
-	handleMemoryMap,
-	handleRaptorTree,
-	handleRaptorBuildHistory,
-	handleContextHealth,
-	handleCachePoison,
-	handleHealthSettings,
-	handleEmbedderHealth,
-	handleRagSettings,
-	handleRagMetrics,
-	handleModelThresholds,
-	handleWiki,
-	handleVectorCortexEvaluation,
-	handleVectorCortexHealth,
-	handleVectorCortexBreakersReset,
-	handleVectorCortexLedger,
-	handleVectorCortexTopology,
-	handleVectorCortexQuery,
-	handleVectorCortexShards,
-	handleVectorCortexResidual,
-	handleVectorCortexReconstruct,
-	handleVectorCortexPlans,
-	handleVectorCortexRender,
-	handleVectorCortexRollout,
-	handleStatic,
-} from "./routes.js";
+import { buildRouteContext, handleStatic } from "./routes.js";
+import { dispatchRoutes } from "./route-dispatch.js";
 
 export async function launchDashboardServer(
 	stateDir: string,
@@ -276,47 +233,7 @@ export async function launchDashboardServer(
 		}
 
 		// Dispatch — each handler returns true if it ended the response.
-		if (handleIndex(req, res, ctx)) return;
-		if (handleRepoIndex(req, res, ctx)) return;
-		if (handleEvents(req, res, ctx)) return;
-		if (handleGameState(req, res, ctx)) return;
-		if (handleGameScores(req, res, ctx)) return;
-		if (handlePerfSamples(req, res, ctx)) return;
-		if (handlePerf(req, res, ctx)) return;
-		if (handleAchievements(req, res, ctx)) return;
-		if (handleSessions(req, res, ctx)) return;
-		if (handleTopics(req, res, ctx)) return;
-		if (handleTurns(req, res, ctx)) return;
-		if (handleMaintenance(req, res, ctx)) return;
-		if (handleProviderCache(req, res, ctx)) return;
-		if (handleMemoryStatus(req, res, ctx)) return;
-		if (handleCacheStripes(req, res, ctx)) return;
-		if (handleSetupStatus(req, res, ctx)) return;
-		if (handleSetupDetect(req, res, ctx)) return;
-		if (handleSetupConfigure(req, res, ctx)) return;
-		if (handleMemoryMap(req, res, ctx)) return;
-		if (handleRaptorTree(req, res, ctx)) return;
-		if (handleRaptorBuildHistory(req, res, ctx)) return;
-		if (handleContextHealth(req, res, ctx)) return;
-		if (handleCachePoison(req, res, ctx)) return;
-		if (handleHealthSettings(req, res, ctx)) return;
-		if (handleEmbedderHealth(req, res, ctx)) return;
-		if (handleRagSettings(req, res, ctx)) return;
-		if (handleRagMetrics(req, res, ctx)) return;
-		if (handleModelThresholds(req, res, ctx)) return;
-		if (handleWiki(req, res, ctx)) return;
-		if (handleVectorCortexEvaluation(req, res, ctx)) return;
-		if (handleVectorCortexHealth(req, res, ctx)) return;
-		if (handleVectorCortexBreakersReset(req, res, ctx)) return;
-		if (handleVectorCortexLedger(req, res, ctx)) return;
-		if (handleVectorCortexTopology(req, res, ctx)) return;
-		if (handleVectorCortexQuery(req, res, ctx)) return;
-		if (handleVectorCortexShards(req, res, ctx)) return;
-		if (handleVectorCortexResidual(req, res, ctx)) return;
-		if (handleVectorCortexReconstruct(req, res, ctx)) return;
-		if (handleVectorCortexPlans(req, res, ctx)) return;
-		if (handleVectorCortexRender(req, res, ctx)) return;
-	if (handleVectorCortexRollout(req, res, ctx)) return;
+		if (dispatchRoutes(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.7",
+  "version": "0.20.9",
   "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

@@ -214,6 +214,33 @@ export const VC5B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5B");
  */
 export const VC5C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5C");
 
+/**
+ * VC6A — advanced closure optimization. Default ON. `MEGACOMPACT_VC6A=0`
+ * disables and is byte-identical to the predecessor (VC5C): the `optimizeClosure`
+ * transitive-reduction arithmetic STILL RUNS (it is PURE), but the
+ * `vector_cortex_closure_optimized` / `vector_cortex_closure_proof_rejected`
+ * events are never emitted and the dashboard closure diagnostics seam is
+ * suppressed. Flag OFF gates the reporter + dashboard seam, never the arithmetic,
+ * 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.
+ */
+export const VC6A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6A");
+
+/**
+ * VC6B — exact source restoration. Default ON. `MEGACOMPACT_VC6B=0` disables and
+ * is byte-identical to the predecessor (VC6A): the `restoreSources` /
+ * `verifyRestored` arithmetic STILL RUNS (it is PURE — an exact-source read plus
+ * a SHA-256 comparison, with no clock, storage, or network), but the
+ * `vector_cortex_source_restored` / `vector_cortex_restore_digest_rejected`
+ * events are never emitted and the dashboard restoration diagnostics seam is
+ * suppressed. Flag OFF gates the reporter + dashboard seam, never the
+ * restore/verify arithmetic, 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.
+ */
+export const VC6B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6B");
+
 // ---------------------------------------------------------------------------
 // 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

@@ -169,6 +169,8 @@ export {
   VC5A_ENABLED,
   VC5B_ENABLED,
   VC5C_ENABLED,
+  VC6A_ENABLED,
+  VC6B_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -0,0 +1,108 @@
+/**
+ * heal/_acceptance-fixture.ts — conformance fixture I/O for VC6A closure
+ * optimization acceptance rows.
+ *
+ * Reads the v2 conformance manifest + the per-sprint closure-optimization
+ * fixture files, and exposes the `HealFx` shape the acceptance aggregator
+ * drives. No mocks/stubs: the fixtures are the committed canonical corpus, fed
+ * verbatim into `closeSelection` → `optimizeClosure` → `verifyProof`.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function repoRoot(from: string): string {
+  let dir = from;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, "conformance", "vector-cortex"))) return dir;
+    const next = dirname(dir);
+    if (next === dir) break;
+    dir = next;
+  }
+  throw new Error("conformance corpus not found above " + from);
+}
+export const REPO_ROOT = repoRoot(HERE);
+export const V2 = join(REPO_ROOT, "conformance", "vector-cortex", "v2");
+
+export interface ManifestRow {
+  id: string;
+  path: string;
+  algorithm: string;
+  expected: string;
+}
+
+export interface HealFxGraphNode {
+  id: string;
+  kind: string;
+  tokenEstimate: number;
+  anchor?: boolean;
+}
+export interface HealFxGraphEdge {
+  from: string;
+  to: string;
+  kind: "depends" | "tool-pair" | "contradicts";
+}
+export interface HealFxGraph {
+  sessionId: string;
+  nodes: HealFxGraphNode[];
+  edges: HealFxGraphEdge[];
+  resolutions?: Array<{ loserId: string; winnerId: string }>;
+}
+export interface HealFxInput {
+  graph: HealFxGraph;
+  scenario: string;
+  seeds: string[];
+}
+export interface HealFxExpected {
+  ok: boolean;
+  code?: string;
+  removedEdges: number;
+  retainedEdges: number;
+  selectedMatch: boolean;
+  protectedRetained: number;
+  deterministic?: boolean;
+}
+export interface HealFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: HealFxInput;
+  expected: HealFxExpected;
+}
+
+export function readManifest(): { fixtures: ManifestRow[] } {
+  return JSON.parse(readFileSync(join(V2, "manifest.json"), "utf8")) as {
+    fixtures: ManifestRow[];
+  };
+}
+
+function readFixture(id: string, prefix: "closure-optimization"): HealFx {
+  const m = readManifest();
+  const row = m.fixtures.find((f) => f.id === id && f.path.startsWith(`${prefix}/`));
+  assert.ok(row, `fixture ${id} registered under ${prefix}/ in manifest`);
+  return JSON.parse(readFileSync(join(V2, row.path), "utf8")) as HealFx;
+}
+
+export function healFixture(id: string): HealFx {
+  return readFixture(id, "closure-optimization");
+}
+
+/** Flag-pinned wrapper: VC6A gated by MEGACOMPACT_VC6A (defaults ON). */
+export function withFlagsOn(fn: () => void): () => void {
+  return (): void => {
+    const saved = process.env.MEGACOMPACT_VC6A;
+    process.env.MEGACOMPACT_VC6A = "1";
+    try {
+      fn();
+    } finally {
+      if (saved === undefined) delete process.env.MEGACOMPACT_VC6A;
+      else process.env.MEGACOMPACT_VC6A = saved;
+    }
+  };
+}

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

@@ -0,0 +1,163 @@
+/**
+ * heal/_restore-fixture.ts — conformance fixture I/O for VC6B restoration rows.
+ *
+ * Sibling of `_acceptance-fixture.ts` (which owns the VC6A closure-optimization
+ * rows); split out so neither file approaches the 300-line soft limit and so the
+ * base64/BigInt decoding lives next to the contract it reconstitutes.
+ *
+ * DECODING IS THE POINT. Fixtures are canonical JSON, which cannot express bytes
+ * or bigints, so the corpus stores `originalBytesBase64` + numeric `seq`. These
+ * loaders turn those back into the REAL `ExactShardV1` / `EventV2` objects the
+ * production readers consume — no mocks, no stubs, no parallel "test shape". If
+ * the decode were lossy the digests would not match and the acceptance test would
+ * fail loudly, which is exactly the guarantee we want from a byte-identity sprint.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+
+import type { EventV2, ExactShardV1, ShardRange } from "./restore-types.js";
+import { V2, readManifest } from "./_acceptance-fixture.js";
+
+/** A `ShardRange` as it appears in JSON: `seq` bounds are numbers, not bigints. */
+export interface RestoreFxRange {
+  sessionId: string;
+  seqStart: number;
+  seqEnd: number;
+  byteStart: number;
+  byteEnd: number;
+}
+
+export interface RestoreFxSpan {
+  nodeId: string;
+  range: RestoreFxRange;
+  digest: string;
+}
+
+export interface RestoreFxShard {
+  sessionId: string;
+  range: RestoreFxRange;
+  originalBytesBase64: string;
+  digest: string;
+  byteCount: number;
+  case: "tool-pair" | "anchor" | "invalid-utf8" | "anchor+invalid";
+}
+
+export interface RestoreFxEvent {
+  sessionId: string;
+  seq: number;
+  eventId: string;
+  role: "policy" | "user" | "assistant" | "tool";
+  kind: string;
+  originalBytesBase64: string;
+  bytesDigest: string;
+  occurredAtMs: number;
+  toolCallId?: string;
+}
+
+export interface RestoreFxInput {
+  scenario: string;
+  sessionId: string;
+  request: { spans: RestoreFxSpan[] };
+  exactShards: RestoreFxShard[];
+  ledgerEvents: RestoreFxEvent[];
+}
+
+export interface RestoreFxExpected {
+  ok: boolean;
+  code?: string;
+  restoredCount: number;
+  missingCount: number;
+  mode: "A" | "B" | "C";
+}
+
+export interface RestoreFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: RestoreFxInput;
+  expected: RestoreFxExpected;
+}
+
+/** Read one registered restoration fixture (asserting it IS registered). */
+export function restorationFixture(id: string): RestoreFx {
+  const m = readManifest();
+  const row = m.fixtures.find((f) => f.id === id && f.path.startsWith("restoration/"));
+  assert.ok(row, `fixture ${id} registered under restoration/ in manifest`);
+  return JSON.parse(readFileSync(join(V2, row!.path), "utf8")) as RestoreFx;
+}
+
+/** base64 -> exact bytes, byte-for-byte (invalid UTF-8 included). */
+export function decodeBytes(base64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+
+/** JSON number seq bounds -> the bigint bounds `ShardRange` declares. */
+export function decodeRange(r: RestoreFxRange): ShardRange {
+  return {
+    sessionId: r.sessionId,
+    seqStart: BigInt(r.seqStart),
+    seqEnd: BigInt(r.seqEnd),
+    byteStart: r.byteStart,
+    byteEnd: r.byteEnd,
+  };
+}
+
+/** Reconstitute a real `ExactShardV1` from its fixture row. */
+export function decodeShard(s: RestoreFxShard): ExactShardV1 {
+  return {
+    schema: "exact-shard-v1",
+    sessionId: s.sessionId,
+    range: decodeRange(s.range),
+    kind: "exact",
+    originalBytes: decodeBytes(s.originalBytesBase64),
+    digest: s.digest,
+    byteCount: s.byteCount,
+    case: s.case,
+  };
+}
+
+/**
+ * Reconstitute a real `EventV2`. `utf8` is re-derived by strict classification
+ * (never lossy replacement) so an invalid-UTF-8 fixture produces the
+ * `{valid:false, base64}` discriminant the VC1A contract requires.
+ */
+export function decodeEvent(e: RestoreFxEvent): EventV2 {
+  const bytes = decodeBytes(e.originalBytesBase64);
+  let utf8: EventV2["utf8"];
+  try {
+    utf8 = { valid: true, text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+  } catch {
+    utf8 = { valid: false, base64: e.originalBytesBase64 };
+  }
+  return {
+    schema: "event-v2",
+    sessionId: e.sessionId,
+    seq: BigInt(e.seq),
+    eventId: e.eventId,
+    role: e.role,
+    kind: e.kind,
+    originalBytes: bytes,
+    bytesDigest: e.bytesDigest as EventV2["bytesDigest"],
+    utf8,
+    ...(e.toolCallId !== undefined ? { toolCallId: e.toolCallId } : {}),
+    occurredAtMs: BigInt(e.occurredAtMs),
+  };
+}
+
+/** Flag-pinned wrapper: VC6B gated by MEGACOMPACT_VC6B (defaults ON). */
+export function withVc6bFlagsOn(fn: () => void): () => void {
+  return (): void => {
+    const saved = process.env.MEGACOMPACT_VC6B;
+    process.env.MEGACOMPACT_VC6B = "1";
+    try {
+      fn();
+    } finally {
+      if (saved === undefined) delete process.env.MEGACOMPACT_VC6B;
+      else process.env.MEGACOMPACT_VC6B = saved;
+    }
+  };
+}

package/src/vector-cortex/heal/_vc6b-helpers.ts

@@ -0,0 +1,55 @@
+/**
+ * heal/_vc6b-helpers.ts — shared decode/run helpers for VC6B acceptance tests.
+ *
+ * Extracted from vc6b-acceptance.test.ts so no single test file crosses the
+ * 300-line soft limit (soft-as-hard gate). Each sibling test file imports from
+ * here rather than duplicating the decode/runReal logic.
+ */
+
+import { createHash } from "node:crypto";
+
+import type {
+  RestoreReader,
+  RestoreRequestV1,
+  RestoreResultV1,
+} from "./restore-types.js";
+import { restoreSources } from "./restore.js";
+import { verifyRestored } from "./verify.js";
+import type { RestoreFx } from "./_restore-fixture.js";
+import { decodeRange, decodeShard, decodeEvent } from "./_restore-fixture.js";
+
+export const enc = (s: string): Uint8Array => new Uint8Array(Buffer.from(s));
+export const hex = (b: Uint8Array): string =>
+  createHash("sha256").update(b).digest("hex");
+
+export function decodeFx(fx: RestoreFx): {
+  request: RestoreRequestV1;
+  reader: RestoreReader;
+} {
+  return {
+    request: {
+      schema: "restore-request-v1",
+      sessionId: fx.input.sessionId,
+      spans: fx.input.request.spans.map((s) => ({
+        nodeId: s.nodeId,
+        range: decodeRange(s.range),
+        digest: s.digest,
+      })),
+    },
+    reader: {
+      exactShards: fx.input.exactShards.map(decodeShard),
+      ledgerEvents: fx.input.ledgerEvents.map(decodeEvent),
+    },
+  };
+}
+
+export function runReal(fx: RestoreFx): {
+  request: RestoreRequestV1;
+  reader: RestoreReader;
+  result: RestoreResultV1;
+  verification: ReturnType<typeof verifyRestored>;
+} {
+  const { request, reader } = decodeFx(fx);
+  const result = restoreSources(request, reader);
+  return { request, reader, result, verification: verifyRestored(result, request) };
+}

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

@@ -0,0 +1,73 @@
+/**
+ * vector-cortex/heal/closure-metrics.ts — VC6A closure proof metrics + handoff.
+ *
+ * Pure read-only derivations over a `ClosureProofV2`: traversal savings (the
+ * sprint's >=20% median acceptance bar) and the `RestoreHintV1` list VC6B
+ * consumes. Extracted from `closure-opt.ts` (delegate-shell) to keep the core
+ * reduction algorithm under the 300-line soft limit.
+ *
+ * PURE / DETERMINISTIC / LOCAL: no storage, no clock, no network (PREVENT-PI-004
+ * / PREVENT-011). Identity only — never source bytes or prompt text
+ * (SECURITY_PRIVACY).
+ */
+
+import type { ClosureGraph } from "../reconstruct/types.js";
+import type { ClosureProofV2, RestoreHintV1, RetainReason } 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;
+}
+
+/** Anchor id set from a graph (matches `closure-opt.ts`). */
+function anchorIds(graph: ClosureGraph): Set<string> {
+  return new Set(graph.nodes.filter((n) => n.anchor === true).map((n) => n.id));
+}
+
+/**
+ * Traversal savings as a fraction in [0,1]: how much of the conservative edge
+ * walk the optimized plan avoids. A plan with nothing to remove scores 0 (not a
+ * failure — a chain graph is already minimal). The sprint's acceptance bar is a
+ * >=20% MEDIAN over the corpus, never a per-graph floor.
+ */
+export function traversalSavings(proof: ClosureProofV2): number {
+  if (proof.conservativeTraversals === 0) return 0;
+  const saved = proof.conservativeTraversals - proof.optimizedTraversals;
+  return saved / proof.conservativeTraversals;
+}
+
+/**
+ * Derive the `RestoreHintV1` list VC6B consumes (the sprint's declared handoff:
+ * "VC6B receives missing-source hints and proof").
+ *
+ * One hint per selected node that a RETAINED edge reaches, naming the cheapest
+ * (bytewise-first) retained prerequisite and whether the node is protected.
+ * Identity only — never source bytes or prompt text (SECURITY_PRIVACY).
+ */
+export function restoreHints(proof: ClosureProofV2, graph: ClosureGraph): readonly RestoreHintV1[] {
+  const anchors = anchorIds(graph);
+  const best = new Map<string, { from: string; reason: RetainReason }>();
+  for (const row of proof.rows) {
+    if (row.decision !== "retained") continue;
+    const reason = row.reason as RetainReason;
+    const existing = best.get(row.to);
+    if (existing === undefined || byBytes(row.from, existing.from) < 0) {
+      best.set(row.to, { from: row.from, reason });
+    }
+  }
+  const hints: RestoreHintV1[] = [];
+  for (const nodeId of [...proof.selected].sort(byBytes)) {
+    const hit = best.get(nodeId);
+    const isToolPair = proof.retainedEdges.some(
+      (e) => e.kind === "tool-pair" && (e.from === nodeId || e.to === nodeId),
+    );
+    hints.push({
+      schema: "restore-hint-v1",
+      nodeId,
+      viaEdgeFrom: hit?.from,
+      protectedNode: anchors.has(nodeId) || isToolPair,
+      reason: hit?.reason ?? (anchors.has(nodeId) ? "anchor" : "no-alternate-path"),
+    });
+  }
+  return hints;
+}