pi-mega-compact 0.20.21 → 0.20.23

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

@@ -11,12 +11,19 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
 import { VC4C_ENABLED } from "../../src/config.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
+import { countVcEvents, vcCount } from "./vc-event-counts.js";
 import type { VectorCortexReconstructView } from "./api-contracts/vector-cortex.js";
 
+// Closure attempt/rejection events emitted by src/vector-cortex/heal/emit.ts.
+const RECONSTRUCT_EVENTS = [
+  "vector_cortex_closure_optimized",
+  "vector_cortex_closure_proof_rejected",
+] as const;
+
 export function handleVectorCortexReconstruct(
   req: IncomingMessage,
   res: ServerResponse,
-  _ctx: RouteContext,
+  ctx: RouteContext,
 ): boolean {
   const url = req.url ?? "";
   const path = url.split("?")[0] ?? url;
@@ -26,10 +33,11 @@ export function handleVectorCortexReconstruct(
     return true;
   }
   const enabled = VC4C_ENABLED();
+  const counts = countVcEvents(ctx.stateDir, RECONSTRUCT_EVENTS);
   const body: VectorCortexReconstructView = {
     enabled,
-    closureAttempts: 0,
-    closureRejections: 0,
+    closureAttempts: vcCount(counts, "vector_cortex_closure_optimized"),
+    closureRejections: vcCount(counts, "vector_cortex_closure_proof_rejected"),
     validatedCount: 0,
     invalidatedCount: 0,
     spanTotal: 0,

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

@@ -25,8 +25,16 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
 import { VC6C_ENABLED } from "../../src/config.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
+import { countVcEvents, vcCount } from "./vc-event-counts.js";
 import type { VectorCortexRepairView } from "./api-contracts/vector-cortex.js";
 
+// Actual event names emitted by src/vector-cortex/heal/repair-emit.ts.
+const REPAIR_EVENTS = [
+  "vector_cortex_repair_planned",
+  "vector_cortex_repair_pointer_switched",
+  "vector_cortex_repair_backoff",
+] as const;
+
 /**
  * Reader-only GET /api/vector-cortex/repair (VC6C).
  *
@@ -38,7 +46,7 @@ import type { VectorCortexRepairView } from "./api-contracts/vector-cortex.js";
 export function handleVectorCortexRepair(
   req: IncomingMessage,
   res: ServerResponse,
-  _ctx: RouteContext,
+  ctx: RouteContext,
 ): boolean {
   const url = req.url ?? "";
   const path = url.split("?")[0] ?? url;
@@ -49,6 +57,7 @@ export function handleVectorCortexRepair(
   }
 
   const enabled = VC6C_ENABLED();
+  const counts = countVcEvents(ctx.stateDir, REPAIR_EVENTS);
   // Flag-off routes to mode C: with VC6C off no self-healing controller runs at
   // all, so neither the targeted rebuild (mode A) nor the full deterministic
   // rebuild (mode B) path is available. Mode C is exactly the spec's "derived
@@ -59,10 +68,10 @@ export function handleVectorCortexRepair(
   const body: VectorCortexRepairView = {
     enabled,
     mode,
-    repairAttempts: 0,
-    repairsPlanned: 0,
-    pointersSwitched: 0,
-    backoffs: 0,
+    repairAttempts: vcCount(counts, "vector_cortex_repair_planned"),
+    repairsPlanned: vcCount(counts, "vector_cortex_repair_planned"),
+    pointersSwitched: vcCount(counts, "vector_cortex_repair_pointer_switched"),
+    backoffs: vcCount(counts, "vector_cortex_repair_backoff"),
     lastBackoffMs: null,
     lastFailure: null,
     updatedAt: new Date().toISOString(),

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

@@ -22,15 +22,22 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
 import { VC4A_ENABLED } from "../../src/config.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
+import { countVcEvents, vcCount } from "./vc-event-counts.js";
 import type { VectorCortexShardsView } from "./api-contracts/vector-cortex.js";
 
+// Actual events emitted by src/vector-cortex/shards/manifest.ts. VC4A has no
+// per-tier (semantic/exact) write event — the manifest build is the single
+// shard-write signal — so semanticCount is wired to it and exactCount stays 0
+// until a per-tier write event exists.
+const SHARD_EVENTS = ["vector_cortex_shard_manifest_built"] as const;
+
 /**
  * Reader-only GET /api/vector-cortex/shards (VC4A).
  */
 export function handleVectorCortexShards(
   req: IncomingMessage,
   res: ServerResponse,
-  _ctx: RouteContext,
+  ctx: RouteContext,
 ): boolean {
   const url = req.url ?? "";
   const path = url.split("?")[0] ?? url;
@@ -42,11 +49,13 @@ export function handleVectorCortexShards(
   }
 
   const enabled = VC4A_ENABLED();
+  const counts = countVcEvents(ctx.stateDir, SHARD_EVENTS);
   const body: VectorCortexShardsView = {
     enabled,
-    // No durable shard manifest is staged yet in this sprint (pure in-memory
-    // partition), so the aggregates are truthfully zero.
-    semanticCount: 0,
+    // The manifest-build event is the only VC4A shard-write signal; semanticCount
+    // reflects manifests built and exactCount stays 0 (no per-tier write event
+    // distinguishes exact shards in events.log yet).
+    semanticCount: vcCount(counts, "vector_cortex_shard_manifest_built"),
     exactCount: 0,
     byteTotal: 0,
     protectedByteTotal: 0,

package/extensions/dashboard-server/vc-event-counts.ts

@@ -0,0 +1,67 @@
+/**
+ * dashboard-server/vc-event-counts.ts — lightweight events.log tail reader for
+ * the Vector Cortex dashboard routes.
+ *
+ * The VC event reporters in `src/vector-cortex/*` emit structured JSON events
+ * (one per line) into the per-repo `events.log`. Instead of the dashboard
+ * hardcoding zero for aggregate counters, this module reads the event tail and
+ * counts real occurrences of named events. It is the single shared seam so every
+ * route stays a small, thin consumer and the counting logic lives in one place
+ * (extensions/ 400-line soft-as-hard split trigger).
+ *
+ * NEVER throws: a missing/unreadable file degrades to an empty Map, malformed
+ * lines are skipped silently, and only the `.event` string field is inspected —
+ * no payload, bytes, span ids, digests, or ledger text ever leaves this module
+ * (SECURITY_PRIVACY, reader-only aggregate).
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process file read only), PREVENT-011
+ * (no `any`).
+ */
+
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+
+/**
+ * Count occurrences of the given named events within the last `maxLines` of the
+ * per-repo events.log adjacent to `stateDir`. Returns a Map keyed by event name;
+ * a missing/unreadable log or zero matching lines yields an empty Map. Best-effort
+ * and non-fatal by construction (matches the non-fatal-stores invariant).
+ */
+export function countVcEvents(
+  stateDir: string,
+  eventNames: readonly string[],
+  maxLines = 10000,
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  let raw: string;
+  try {
+    raw = readFileSync(join(stateDir, "events.log"), "utf-8");
+  } catch {
+    // Missing or unreadable log → nothing to count, never throw.
+    return counts;
+  }
+  // Walk only the tail: split into lines and keep the last `maxLines`.
+  const lines = raw.split("\n");
+  const start = Math.max(0, lines.length - maxLines);
+  const wanted = new Set(eventNames);
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i] as string;
+    if (line.length === 0) continue;
+    let ev: { event?: unknown } | null = null;
+    try {
+      ev = JSON.parse(line) as { event?: unknown };
+    } catch {
+      // Malformed line — skip silently, never break the reader.
+      continue;
+    }
+    if (typeof ev?.event === "string" && wanted.has(ev.event)) {
+      counts.set(ev.event, (counts.get(ev.event) ?? 0) + 1);
+    }
+  }
+  return counts;
+}
+
+/** Read a value from an event-count map, defaulting to 0 when absent. */
+export function vcCount(counts: Map<string, number>, name: string): number {
+  return counts.get(name) ?? 0;
+}

package/extensions/mega-dashboard.ts

@@ -25,6 +25,8 @@ export interface DashboardSnapshot {
   presetTier: string;
   /** Live 0–1 pressure ratio (currentTokens / thresholdTokens). */
   pressure: number;
+  /** VC0A: count of eval-observer latency samples (0 when disabled/absent). */
+  vcObserverSamples: number;
   config: {
     fastGatePct: number;
     thresholdTokens: number;

package/extensions/mega-events/context-handler/afterCompact.ts

@@ -28,12 +28,17 @@ import { assignNewMemoriesIncremental } from "../../../src/wiki/index.js";
 import { TrigramEmbedder } from "../../../src/embedder.js";
 import type { EmbeddedChunk } from "../../../src/topics/types.js";
 import type { MegaConfig } from "../../mega-config.js";
+import { reportClosureOptimized } from "../../../src/vector-cortex/heal/emit.js";
+import { reportRepairPlanned } from "../../../src/vector-cortex/heal/repair-emit.js";
+import { VC6A_ENABLED, VC6C_ENABLED } from "../../../src/config/vector-cortex.js";
 
 /** Shape of the compact result consumed by the epoch/maintenance writes. */
 interface CompactResult {
 	checkpointId?: string;
 	compactedFrom: number;
 	summary: string;
+	tokenEstimate?: number;
+	originalTokenEstimate?: number;
 }
 
 /**
@@ -253,4 +258,45 @@ export async function persistEpochAndMaintain(
 			runtime.logger.warn("db-mirror-epoch-fail", { error: String(e) });
 		}
 	}
+
+	// VC6 Heal lifecycle emits (post-compact). Wiring stubs — dashboard graph +
+	// event counts move; real gap detection/rebuild is a future sprint.
+	// VC6A: closure-optimization savings from the compact token delta.
+	const savings = Math.max(
+		0,
+		(ran.result.originalTokenEstimate ?? 0) - (ran.result.tokenEstimate ?? 0),
+	);
+	if (VC6A_ENABLED()) {
+		try {
+			reportClosureOptimized(
+				(name, payload) =>
+					runtime.appendEvent(name, payload as Record<string, unknown>),
+				{
+					sessionId: runtime.rt.sessionId,
+					removed: 0,
+					retained: ran.result.compactedFrom,
+					savings,
+				},
+			);
+		} catch {
+			/* non-fatal: VC6A heal emit never breaks compaction */
+		}
+	}
+	// VC6C: repair-planner placeholder (no real gap detection yet).
+	if (VC6C_ENABLED()) {
+		try {
+			reportRepairPlanned(
+				(name, payload) =>
+					runtime.appendEvent(name, payload as Record<string, unknown>),
+				{
+					subsystem: "post_compact",
+					generation: 1,
+					backoffMs: 0,
+					gapSize: 0,
+				},
+			);
+		} catch {
+			/* non-fatal: VC6C heal emit never breaks compaction */
+		}
+	}
 }

package/extensions/mega-events/context-handler/pipelineRun.ts

@@ -19,6 +19,9 @@ import { pressureFromPct, pressureRatio } from "../../mega-config.js";
 import type { MegaRuntime } from "../../mega-runtime.js";
 import type { MegaConfig } from "../../mega-config.js";
 import type { TailResultFn } from "./gateCheck.js";
+import { recordCompactLatency } from "../../mega-runtime/vc-observer.js";
+import { decideLivePath } from "../../mega-runtime/vector-cortex-live.js";
+import { VC5C_ENABLED } from "../../../src/config/vector-cortex.js";
 
 /** The non-skipped variant of the runCompact result. */
 export type RanResult = Extract<RunCompactResult, { skipped: false }>;
@@ -45,6 +48,32 @@ export function invokePipeline(
 		tailResult: TailResultFn;
 	},
 ): PipelineOutcome {
+	// VC5C: emit the rollout decision per compact event (observability seam).
+	// vcGate/vcHardFaults are not yet declared on MegaRuntime.rt — cast to the
+	// rollout shapes. Best-effort + non-fatal; decision does NOT gate behavior yet.
+	if (VC5C_ENABLED()) {
+		try {
+			const decision = decideLivePath(runtime.rt.sessionId, {
+				emit: runtime.appendEvent.bind(runtime),
+				currentGate:
+					(runtime.rt as { vcGate?: 0 | 1 | 2 | 3 | 4 }).vcGate ?? 0,
+				hardFaults:
+					(runtime.rt as { vcHardFaults?: import("../../../src/vector-cortex/rollout/types.js").RolloutHardFault[] })
+						.vcHardFaults ?? [],
+			});
+			runtime.appendEvent("vector_cortex_rollout_decision", {
+				sessionId: runtime.rt.sessionId,
+				vcActive: decision.vcActive,
+				forcedPreVc: decision.forcedPreVc,
+				mode: decision.mode,
+				bucket: decision.bucket,
+				gateIndex: decision.gateIndex,
+				promotionBlocked: decision.promotionBlocked,
+			});
+		} catch {
+			/* non-fatal: rollout decision emission never breaks compaction */
+		}
+	}
 	// Adaptive compression (Fix E): scale compression strength + keepFrom depth
 	// with how close we are to the model context limit. Null-safe: when the
 	// token-fallback path ran (pct unavailable) use the token-basis pressure
@@ -53,9 +82,19 @@ export function invokePipeline(
 		opts.pct != null
 			? pressureFromPct(opts.pct)
 			: pressureRatio(opts.currentTokens, runtime.effectiveThreshold);
+	const t0 = Date.now();
 	const ran = runCompact(pi, runtime, config, ctx, opts.messages, {
 		compressionPressure: pressure,
 	});
+	// VC0A: record compact latency on the eval observer (mode A) on every
+	// outcome so the dashboard histogram reflects real data. No-op when the
+	// observer is absent (flag off / construction failure).
+	recordCompactLatency(
+		runtime,
+		Date.now() - t0,
+		runtime.rt.sessionId,
+		runtime.rt.compactCount,
+	);
 	// D.3: skip paths fall back to replay instead of returning empty.
 	// If runCompact skipped and we have a valid trimCache, replay it
 	// (free stability win) — otherwise defer to the next event.

package/extensions/mega-runtime/dashboard-snapshot.ts

@@ -39,6 +39,9 @@ export interface SnapshotBuildContext {
 	readonly pressureBand: string;
 	readonly pressure: number;
 	readonly effectiveThreshold: number;
+	/** VC0A: count of latency samples the eval observer histogram should show
+	 *  (0 when the observer is absent / flag off). */
+	readonly vcObserverSamples?: number;
 	readonly statusKey: string | undefined;
 	readonly lastCtxTokens: number | null;
 	readonly lastCtxPercent: number | null;
@@ -76,6 +79,7 @@ export function buildDashboardSnapshot(ctx: SnapshotBuildContext): DashboardSnap
 		tier: ctx.pressureBand,
 		presetTier: ctx.config.tier,
 		pressure: ctx.pressure,
+		vcObserverSamples: ctx.vcObserverSamples ?? 0,
 		config: {
 			fastGatePct: ctx.config.fastGatePct,
 			thresholdTokens: ctx.effectiveThreshold,
@@ -132,17 +136,17 @@ export function buildDashboardSnapshot(ctx: SnapshotBuildContext): DashboardSnap
 		repo: ctx.repo,
 		compression: {
 			session: {
-				tokensIn: ctx.rt.tokensSaved + (ctx.st.totalTokenEstimate - ctx.st.originalTokens),
+				tokensIn: ctx.st.originalTokens,
 				tokensOut: ctx.st.totalTokenEstimate,
 				tokensFreed: ctx.rt.tokensSaved,
-				compressionPct: ctx.rt.tokensSaved / Math.max(1, ctx.rt.tokensSaved + (ctx.st.totalTokenEstimate - ctx.st.originalTokens)),
+				compressionPct: ctx.rt.tokensSaved / Math.max(1, ctx.st.originalTokens),
 				dedupPct: ctx.rt.dedupAttempts > 0 ? ctx.rt.dedupSkips / ctx.rt.dedupAttempts : 0,
 			},
 			repo: {
-				tokensIn: ctx.repo.tokensSaved + (ctx.repo.totalTokenEstimate - ctx.repo.originalTokens),
+				tokensIn: ctx.repo.originalTokens,
 				tokensOut: ctx.repo.totalTokenEstimate,
 				tokensFreed: ctx.repo.tokensSaved,
-				compressionPct: ctx.repo.tokensSaved / Math.max(1, ctx.repo.tokensSaved + (ctx.repo.totalTokenEstimate - ctx.repo.originalTokens)),
+				compressionPct: ctx.repo.tokensSaved / Math.max(1, ctx.repo.originalTokens),
 				dedupPct: ctx.repo.dedupAttempts > 0 ? ctx.repo.dedupCollapsed / ctx.repo.dedupAttempts : 0,
 			},
 		},
@@ -155,7 +159,9 @@ export function buildDashboardSnapshot(ctx: SnapshotBuildContext): DashboardSnap
 			// per-session in rt and there's no cumulative counter yet.
 			total: ctx.repo.dedupCollapsed,
 			sessionTokensSaved: ctx.rt.cacheHitTokens,
-			totalTokensSaved: ctx.repo.dedupCollapsed > 0 ? ctx.repo.dedupCollapsed * 100 : 0,
+			// Cumulative tokens saved across all sessions in this repo —
+			// was a placeholder (dedupCollapsed * 100).
+			totalTokensSaved: ctx.repo.tokensSaved,
 		},
 		compacts: {
 			session: ctx.rt.compactCount,
@@ -168,7 +174,7 @@ export function buildDashboardSnapshot(ctx: SnapshotBuildContext): DashboardSnap
 			},
 			cacheHit: {
 				sessionSec: ctx.rt.cacheHitTokens / 1000,
-				totalSec: (ctx.repo.dedupCollapsed * 100) / 1000,
+				totalSec: ctx.repo.tokensSaved / 1000,
 			},
 		},
 		model: ctx.currentModel

package/extensions/mega-runtime/runtime-snapshot.ts

@@ -42,6 +42,7 @@ import type { Dashboard } from "../mega-dashboard.js";
 import type { WidgetData } from "./widget.js";
 import { computeMegaSnapshot } from "./snapshot.js";
 import { buildDashboardSnapshot } from "./dashboard-snapshot.js";
+import { getVcObserver } from "./vc-observer.js";
 import {
 	type RuntimeHelpersContext,
 	materialSigImpl,
@@ -65,6 +66,10 @@ export interface RuntimeSnapshotContext extends RuntimeHelpersContext {
 	store: VectorStore;
 	config: MegaConfig;
 	dashboard: Dashboard;
+	// VC0A: appendEvent + currentStateDir are consumed by getVcObserver()
+	// (vc-observer.ts WeakMap cache) to surface how many latency samples the
+	// dashboard histogram should expect.
+	appendEvent(event: string, fields: Record<string, unknown>): void;
 	currentStateDir: string;
 	widgetData: WidgetData | null;
 	/** v0.8.5: material-change signature; read + written by snapshot(). Public so
@@ -164,6 +169,7 @@ export function snapshotImpl(
 			pressureBand: self.pressureBand,
 			pressure: self.pressure,
 			effectiveThreshold: self.effectiveThreshold,
+			vcObserverSamples: getVcObserver(self)?.rows().length ?? 0,
 			statusKey: self.statusKey,
 			lastCtxTokens: self.lastCtxTokens,
 			lastCtxPercent: self.lastCtxPercent,

package/extensions/mega-runtime/vc-observer.ts

@@ -0,0 +1,120 @@
+/**
+ * vc-observer.ts — VC0A mode-A eval observer wiring for MegaRuntime.
+ *
+ * Bridges the pure in-memory EvalObserver (src/vector-cortex/eval/observer.ts)
+ * into the production runtime: every recorded compact/recall latency sample is
+ * both emitted to events.log (via MegaRuntime.appendEvent) and appended to the
+ * redacted evaluation.jsonl (via appendEvalRow) so the Vector Cortex dashboard
+ * "Observer" histogram reads real data instead of an empty file.
+ *
+ * All wiring is gated on VC0A_ENABLED() (MEGACOMPACT_VC0A). Flag-off and any
+ * construction/persistence error are non-fatal (PREVENT-PI-004: local FS only,
+ * no network) and degrade to a null observer — byte-identical to the
+ * predecessor (mode C). PREVENT-011: no `any` type.
+ *
+ * Follows the capture-model.ts / append-event.ts pattern: a context interface +
+ * free functions + a thin delegate. No import-time side effects — merely
+ * importing these functions is inert regardless of the flag.
+ */
+
+import { VC0A_ENABLED } from "../../src/config.js";
+import { createEvalObserver } from "../../src/vector-cortex/eval/observer.js";
+import type { EvalObserver } from "../../src/vector-cortex/eval/observer.js";
+import { appendEvalRow } from "../../src/vector-cortex/eval/persist.js";
+
+// ---------------------------------------------------------------------- types
+
+/** The slice of `MegaRuntime` the observer bridge reads/writes. */
+export interface VcObserverContext {
+	appendEvent(event: string, fields: Record<string, unknown>): void;
+	readonly currentStateDir: string;
+}
+
+// ------------------------------------------------------------- construction
+
+/**
+ * Build the production-wired eval observer (mode A) if the VC0A flag is on.
+ * Returns null when the flag is off or on any construction error (non-fatal).
+ * The returned observer is a thin, best-effort observability seam that never
+ * breaks the agent loop.
+ */
+export function createVcObserver(self: VcObserverContext): EvalObserver | null {
+	if (!VC0A_ENABLED()) return null;
+	try {
+		return createEvalObserver({
+			emit: self.appendEvent.bind(self),
+			persist: (sample) => appendEvalRow(self.currentStateDir, [sample]),
+		});
+	} catch {
+		/* non-fatal observability — never break the agent loop */
+		return null;
+	}
+}
+
+// ---------------------------------------------------------------- weak cache
+
+/**
+ * Module-level observer cache keyed by the runtime object. Avoids adding a
+ * `vcObserver` field to MegaRuntime (keeping runtime.ts under its soft limit
+ * — no field, no constructor line, no import bloat). One observer per runtime
+ * instance, lazily built on the first latency recording.
+ */
+const observerCache = new WeakMap<object, EvalObserver | null>();
+
+/** Lazily create + cache the observer for the given runtime context. */
+export function getVcObserver(self: VcObserverContext): EvalObserver | null {
+	let obs = observerCache.get(self);
+	if (obs === undefined) {
+		obs = createVcObserver(self);
+		observerCache.set(self, obs);
+	}
+	return obs;
+}
+
+// ---------------------------------------------------------------- reporting
+
+/** Record a compact latency sample on the observer (no-op when absent). */
+export function recordCompactLatency(
+	self: VcObserverContext,
+	elapsedMs: number,
+	sessionId: string,
+	epoch: number,
+): void {
+	const obs = getVcObserver(self);
+	if (obs == null) return;
+	try {
+		obs.record({
+			session: sessionId,
+			seq: epoch,
+			event: "compact",
+			value: elapsedMs,
+			unit: "ms",
+			mode: "A",
+		});
+	} catch {
+		/* non-fatal observability */
+	}
+}
+
+/** Record a recall latency sample on the observer (no-op when absent). */
+export function recordRecallLatency(
+	self: VcObserverContext,
+	elapsedMs: number,
+	sessionId: string,
+	epoch: number,
+): void {
+	const obs = getVcObserver(self);
+	if (obs == null) return;
+	try {
+		obs.record({
+			session: sessionId,
+			seq: epoch,
+			event: "recall",
+			value: elapsedMs,
+			unit: "ms",
+			mode: "A",
+		});
+	} catch {
+		/* non-fatal observability */
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.21",
+  "version": "0.20.23",
   "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/vector-cortex/platform/_cross-language-fixture.ts

@@ -0,0 +1,83 @@
+/**
+ * platform/_cross-language-fixture.ts — VC8C cross-language fixture I/O.
+ *
+ * Reads conformance fixtures from the v2 `cross-language/` domain and decodes
+ * them into the REAL production types (`ParityReportV1`, `EngineAbiV1`,
+ * `NeutralRecord`) so `selectEngine` and the framing round-trip run against
+ * the committed corpus — no mocks, no stubs.
+ *
+ * Mirrors `_diagnostics-fixture.ts` (VC7C) and `_adaptive-fixture.ts` (VC8B).
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ParityReportV1 } from "./types.js";
+
+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);
+}
+
+const DIR = join(repoRoot(here), "conformance", "vector-cortex", "v2", "cross-language");
+
+/** Read + parse one cross-language conformance fixture by ID. */
+export function crossLanguageFixture(id: string): Record<string, unknown> {
+  const raw = readFileSync(join(DIR, `${id}.json`), "utf8");
+  return JSON.parse(raw);
+}
+
+// ── Cross-language golden / error fixture shape ───────────────────────────────
+
+interface CrossLangFx {
+  id: string;
+  fixtureId: string;
+  kind: string;
+  assertion: string;
+  inputHex: string;
+  expected: { ok: boolean; code?: string };
+  expectedFailureCode: string | null;
+  expectedOutputHex: string;
+}
+
+/** Read a numbered or named cross-language fixture as a typed CrossLangFx. */
+export function xlangFx(id: string): CrossLangFx {
+  return crossLanguageFixture(id) as unknown as CrossLangFx;
+}
+
+/** Build a ParityReportV1 whose matrix has exactly one failing row at `badIndex`. */
+export function reportWithMatrixFailure(
+  badIndex: number,
+  code: string,
+  digest: string,
+  platform: string,
+): ParityReportV1 {
+  const matrix = Array.from({ length: 30 }, (_, i) => ({
+    fixtureId: `RUST-${String(i + 1).padStart(3, "0")}`,
+    ok: i === badIndex ? false : true,
+    code: i === badIndex ? code : null,
+  }));
+  return {
+    schema: "parity-report-v1",
+    artifactUrl: "file:///local/rad",
+    commit: "0".repeat(40),
+    cargoLockDigest: "a".repeat(64),
+    artifactCargoLockDigest: digest,
+    platform,
+    matrix,
+  };
+}
+
+/** Build a fully-qualified ParityReportV1 (all matrix rows ok). */
+export function okReport(digest: string, platform: string): ParityReportV1 {
+  return reportWithMatrixFailure(-1, "", digest, platform);
+}