pi-mega-compact 0.20.18 → 0.20.20

package/extensions/dashboard-client/src/tabs/useVectorCortexPoll.ts

@@ -20,6 +20,8 @@ import {
 	fetchVectorCortexEconomics,
 	fetchVectorCortexDiagnostics,
 	fetchVectorCortexOutcomes,
+	fetchVectorCortexPolicy,
+	fetchVectorCortexPlatform,
 	fetchVectorCortexShards,
 	fetchVectorCortexTopology,
 	type VectorCortexEvaluationSummary,
@@ -37,6 +39,8 @@ import {
 	type VectorCortexEconomicsView,
 	type VectorCortexDiagnosticsView,
 	type VectorCortexOutcomesView,
+	type VectorCortexPolicyView,
+	type VectorCortexPlatformView,
 	type VectorCortexShardsView,
 	type VectorCortexTopologyView,
 } from "../api/vector-cortex";
@@ -61,6 +65,8 @@ export interface VectorCortexPollState {
 	economics: VectorCortexEconomicsView | null;
 	diagnostics: VectorCortexDiagnosticsView | null;
 	outcomes: VectorCortexOutcomesView | null;
+	policy: VectorCortexPolicyView | null;
+	platform: VectorCortexPlatformView | null;
 }
 
 export function useVectorCortexPoll(): [
@@ -87,6 +93,8 @@ export function useVectorCortexPoll(): [
 		economics: null,
 		diagnostics: null,
 		outcomes: null,
+		policy: null,
+		platform: null,
 	});
 
 	const poll = useCallback(() => {
@@ -116,6 +124,8 @@ export function useVectorCortexPoll(): [
 		fetchVectorCortexEconomics().then((economics) => setState((p) => ({ ...p, economics }))).catch(() => {});
 		fetchVectorCortexDiagnostics().then((diagnostics) => setState((p) => ({ ...p, diagnostics }))).catch(() => {});
 		fetchVectorCortexOutcomes().then((outcomes) => setState((p) => ({ ...p, outcomes }))).catch(() => {});
+		fetchVectorCortexPolicy().then((policy) => setState((p) => ({ ...p, policy }))).catch(() => {});
+		fetchVectorCortexPlatform().then((platform) => setState((p) => ({ ...p, platform }))).catch(() => {});
 	}, []);
 
 	useEffect(() => {

package/extensions/dashboard-client/src/types/vector-cortex-vc8.ts

@@ -8,7 +8,7 @@
  */
 
 /**
- * Reader-only outcomes aggregate view (VC8A). Counts + OUT_* codes only —
+ * Reader-only outcomes aggregate view (VC8A). Counts + OUT_ codes only —
  * the outcome ledger carries metrics without payload, so no prompt bytes,
  * response text, free-text, or session content ever reaches the client.
  */
@@ -23,3 +23,36 @@ export interface VectorCortexOutcomesView {
   lastFailure: string | null;
   updatedAt: string;
 }
+
+/**
+ * Reader-only shadow adaptive policy aggregate view (VC8B). Counts + POL_ and
+ * M7_ codes only — the policy engine carries no payload, so no prompt bytes,
+ * session content, or free-text ever reaches the client.
+ */
+export interface VectorCortexPolicyView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  shadowDecisions: number;
+  clampedDecisions: number;
+  rejectedInputs: number;
+  liveMutations: number;
+  pressureVersion: number;
+  lastFailure: string | null;
+  updatedAt: string;
+}
+
+/**
+ * Reader-only engine parity/selection aggregate view (VC8C). Counts + RUST_
+ * codes only — the selector carries no payload, so no artifact bytes, output
+ * bytes, or free-text ever reaches the client.
+ */
+export interface VectorCortexPlatformView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  fixtureCount: number;
+  passed: number;
+  failed: number;
+  externalRunnerConfigured: boolean;
+  lastFailure: string | null;
+  updatedAt: string;
+}

package/extensions/dashboard-client/src/types/vector-cortex.ts

@@ -262,4 +262,4 @@ export type {
   VectorCortexDiagnosticsView,
 } from "./vector-cortex-vc7.js";
 
-export type { VectorCortexOutcomesView } from "./vector-cortex-vc8.js";
+export type { VectorCortexOutcomesView, VectorCortexPolicyView, VectorCortexPlatformView } from "./vector-cortex-vc8.js";

package/extensions/dashboard-server/api-contracts/vector-cortex-platform.ts

@@ -0,0 +1,34 @@
+/**
+ * api-contracts/vector-cortex-platform.ts — VC8C engine parity/selection API contract.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ *
+ * Reader-only GET /api/vector-cortex/platform diagnostics view (VC8C).
+ * COUNTS + CODES ONLY. The selector carries no payload — this surface exposes
+ * only the engine selection mode, parity counts, and machine codes, never
+ * artifact bytes, output bytes, or free-text.
+ */
+
+/** Runtime triad mode implied by the VC8C flag state. */
+export type VectorCortexPlatformMode = "A" | "B" | "C";
+
+/** Reader-only engine parity/selection aggregate view for GET /api/vector-cortex/platform. */
+export interface VectorCortexPlatformView {
+  /** Whether the VC8C platform flag is enabled. */
+  readonly enabled: boolean;
+  /** Runtime triad mode: A=qualified external Rust, B=TS reference, C=legacy path. */
+  readonly mode: VectorCortexPlatformMode;
+  /** Total fixtures in the parity matrix (count only). */
+  readonly fixtureCount: number;
+  /** Fixtures that passed byte-equal comparison (count only). */
+  readonly passed: number;
+  /** Fixtures that mismatched (count only). */
+  readonly failed: number;
+  /** Whether an external Rust runner is configured (boolean, no path). */
+  readonly externalRunnerConfigured: boolean;
+  /** Last RUST_ failure code, or null if none. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}

package/extensions/dashboard-server/api-contracts/vector-cortex-policy.ts

@@ -0,0 +1,36 @@
+/**
+ * api-contracts/vector-cortex-policy.ts — VC8B shadow adaptive policy API contract.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ *
+ * Reader-only GET /api/vector-cortex/policy diagnostics view (VC8B).
+ * COUNTS + CODES ONLY. The policy engine carries no payload — this surface
+ * exposes only aggregate decision counts and machine codes, never session
+ * content, prompt bytes, or free-text.
+ */
+
+/** Runtime triad mode implied by the VC8B flag state. */
+export type VectorCortexPolicyMode = "A" | "B" | "C";
+
+/** Reader-only policy + shadow aggregate view for GET /api/vector-cortex/policy. */
+export interface VectorCortexPolicyView {
+  /** Whether the VC8B policy flag is enabled. */
+  readonly enabled: boolean;
+  /** Runtime triad mode: A=shadow candidate, B=static calibrated, C=fixed legacy. */
+  readonly mode: VectorCortexPolicyMode;
+  /** Total shadow decisions evaluated (count only). */
+  readonly shadowDecisions: number;
+  /** Decisions whose budget was clamped at a bound (count only). */
+  readonly clampedDecisions: number;
+  /** Shadow rejections (unknown pressure / bad bounds) (count only). */
+  readonly rejectedInputs: number;
+  /** Live mutations detected (structurally always 0). */
+  readonly liveMutations: number;
+  /** M7 migration state: active pressure version (1 or 2). */
+  readonly pressureVersion: number;
+  /** Last POL_ or M7_ failure code, or null if none. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}

package/extensions/dashboard-server/route-dispatch.ts

@@ -77,6 +77,16 @@ import { handleVectorCortexDiagnostics } from "./routes-vector-cortex-diagnostic
 // every file stays well under the 400-line extension soft limit.
 import { handleVectorCortexOutcomes } from "./routes-vector-cortex-outcomes.js";
 
+// VC8B shadow adaptive policy + M7 pressure-v2 gets its own module so the
+// policy/shadow seam stays independent and every file stays well under the
+// 400-line extension soft limit.
+import { handleVectorCortexPolicy } from "./routes-vector-cortex-policy.js";
+
+// VC8C canary selection + external Rust parity gets its own module so the
+// platform/selection seam stays independent and every file stays well under
+// the 400-line extension soft limit.
+import { handleVectorCortexPlatform } from "./routes-vector-cortex-platform.js";
+
 /**
  * Dispatch a request through every registered route handler.
  * Returns true if a handler claimed the request (ended the response).
@@ -134,5 +144,7 @@ export function dispatchRoutes(
 	if (handleVectorCortexEconomics(req, res, ctx)) return true;
 	if (handleVectorCortexDiagnostics(req, res, ctx)) return true;
 	if (handleVectorCortexOutcomes(req, res, ctx)) return true;
+	if (handleVectorCortexPolicy(req, res, ctx)) return true;
+	if (handleVectorCortexPlatform(req, res, ctx)) return true;
 	return false;
 }

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

@@ -180,5 +180,17 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Consent-bound outcome ledger and offline learning dataset. Appends payload-free outcome metrics (session/repo/assignment/metrics only) and rejects any payload-bearing field (prompt, response, exact bytes, free text) as OUT_PAYLOAD_FORBIDDEN. Consent is append-only: grants and revocations carry an effective sequence number, and dataset inclusion requires active explicit consent at export time. Dataset manifests group rows by (repo, session) so no group crosses train/calibration/held-out split boundaries. Revocations disappear from future manifests. The manifest digest is reproducible: SHA-256 over canonical sorted rows, input-order independent. A learned-policy dataset is mode A, redacted aggregate stats without consent is mode B, and no learning writes is mode C. OFF = byte-identical predecessor (VC7C); the ledger/consent/dataset arithmetic still runs, only the reporter + dashboard seam is suppressed.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC8B",
+			"VC8B Shadow Adaptive Policy",
+			"Bounded shadow adaptive policy + M7 pressure-v2 migration. Policy actions are from a finite set (admit/dampen/defer/escalate/reject) chosen deterministically by the canonical pressure level; token budgets are clamped into a configured window after the pressure factor. Unknown pressure labels are rejected as POL_PRESSURE_UNKNOWN, never coerced to a neighbour. The shadow engine is structurally incapable of affecting the live path: inputs are deep-copied, the canonical prompt digest is pinned before and after to prove non-mutation, and liveMutations is always zero. M7 migrates legacy pressure labels to the v2 canonical five by copy/validate/switch; an unknown label blocks the switch and keeps the legacy pointer (M7_PRESSURE_UNKNOWN). A shadow decision is mode A, static calibrated policy is mode B (forced by invalid A), and fixed legacy thresholds is mode C (forced by M7 or B failure). OFF = byte-identical predecessor (VC8A); the policy/shadow/migration arithmetic still runs, only the reporter + dashboard seam is suppressed.",
+			true,
+		),
+		boolDirect(
+			"MEGACOMPACT_VC8C",
+			"VC8C Canary Platform + Rust Parity",
+			"Canary selection and external Rust parity. The selector admits a qualified external Rust artifact only when ABI version, URL metadata, commit, Cargo.lock digest, and platform all match evidence; a Cargo.lock digest mismatch rejects the artifact (RUST_CARGO_DIGEST_MISMATCH). The cross-conformance runner exchanges length-framed neutral records over a local stdin/stdout channel — a subprocess, never a URL (PREVENT-PI-004). A parity mismatch selects TS mode B. A qualified external artifact is mode A, TS reference is mode B, legacy path is mode C. OFF = byte-identical predecessor (VC8B); the selector and cross-conformance arithmetic still run, only the reporter + dashboard seam is suppressed.",
+			true,
+		),
 	],
 };

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

@@ -0,0 +1,52 @@
+/**
+ * dashboard-server/routes-vector-cortex-platform.ts — VC8C platform dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/platform returning the engine parity/selection
+ * aggregate diagnostics: whether the VC8C flag is enabled, the runtime triad mode,
+ * how many fixtures are in the parity matrix, how many passed, how many failed,
+ * whether an external runner is configured, and the last RUST_ failure code.
+ *
+ * COUNTS + CODES ONLY. The selector carries no payload, so this route NEVER
+ * exposes artifact bytes, output bytes, or free-text — only aggregate counts and
+ * machine codes.
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + codes only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC8C_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexPlatformView } from "./api-contracts/vector-cortex-platform.js";
+
+/** GET /api/vector-cortex/platform — reader-only engine parity/selection aggregate (VC8C). */
+export function handleVectorCortexPlatform(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+
+  if (path !== "/api/vector-cortex/platform") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC8C_ENABLED();
+  const mode: VectorCortexPlatformView["mode"] = enabled ? "A" : "C";
+  const body: VectorCortexPlatformView = {
+    enabled,
+    mode,
+    fixtureCount: 0,
+    passed: 0,
+    failed: 0,
+    externalRunnerConfigured: process.env.MEGACOMPACT_RUST_RUNNER !== undefined,
+    lastFailure: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * dashboard-server/routes-vector-cortex-policy.ts — VC8B policy dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/policy returning the shadow adaptive
+ * policy aggregate diagnostics: whether the VC8B flag is enabled, the runtime
+ * triad mode, how many shadow decisions were evaluated, how many were clamped
+ * at a bound, how many were rejected (unknown pressure / bad bounds), the
+ * live-mutation count (structurally always 0), the active pressure version,
+ * and the last POL_ or M7_ failure code.
+ *
+ * COUNTS + CODES ONLY. The policy engine carries no payload, so this route
+ * NEVER exposes prompt bytes, session content, or free-text — only aggregate
+ * counts and machine codes.
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + codes only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC8B_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexPolicyView } from "./api-contracts/vector-cortex-policy.js";
+
+/** GET /api/vector-cortex/policy — reader-only policy + shadow aggregate (VC8B). */
+export function handleVectorCortexPolicy(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+
+  if (path !== "/api/vector-cortex/policy") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC8B_ENABLED();
+  const mode: VectorCortexPolicyView["mode"] = enabled ? "A" : "C";
+  const body: VectorCortexPolicyView = {
+    enabled,
+    mode,
+    shadowDecisions: 0,
+    clampedDecisions: 0,
+    rejectedInputs: 0,
+    liveMutations: 0,
+    pressureVersion: 1,
+    lastFailure: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.18",
+  "version": "0.20.20",
   "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-vc8c.ts

@@ -0,0 +1,33 @@
+/**
+ * config/vector-cortex-vc8c.ts — VC8C canary-selection sprint flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-breakers.ts and
+ * vector-cortex-early.ts were. This is the CANARY-SELECTION flag (external Rust
+ * parity / engine triad A/B/C). vector-cortex.ts re-exports it below so no
+ * consumer import path changes.
+ *
+ * The split is purely mechanical: VC8C_ENABLED is byte-identical in name,
+ * semantics, and default to the definition it replaces, and vector-cortex.ts
+ * re-exports it so every existing `from "./config/vector-cortex.js"` import
+ * keeps resolving unchanged.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * VC8C — canary selection + external Rust parity (EngineAbiV1 / ParityReportV1).
+ * Default ON. `MEGACOMPACT_VC8C=0` disables and is byte-identical to the
+ * predecessor (VC8B): the engine selector and the cross-conformance runner
+ * STILL RUN (they are PURE — ABI/evidence matching plus neutral length-framed
+ * byte comparison, with no clock, storage, or network), so a qualified external
+ * artifact is still accepted and a parity mismatch still demotes to mode B with
+ * the flag off. The flag gates ONLY the
+ * `vector_cortex_engine_parity_checked` / `vector_cortex_engine_selection_demoted`
+ * events and the engine parity/selection dashboard seam, which reports
+ * `enabled:false` + mode C when off. This flag MUST also be a dashboard SETTINGS
+ * toggle (visible in config UI, never in EXCLUDED_SETTINGS), mirroring VC4A..VC8B.
+ */
+export const VC8C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8C");

package/src/config/vector-cortex.ts

@@ -254,6 +254,27 @@ export const VC7C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7C");
  */
 export const VC8A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8A");
 
+/**
+ * VC8B — bounded shadow adaptive policy + M7 pressure-v2. Default ON.
+ * `MEGACOMPACT_VC8B=0` disables and is byte-identical to the predecessor
+ * (VC8A): the policy engine, shadow evaluator, and M7 migration STILL RUN
+ * (they are PURE — action validation, budget clamping, pressure canonicalization
+ * and copy/validate/switch, with no clock, storage, or network), so a budget is
+ * still clamped identically and an unknown pressure label is still rejected. The
+ * flag gates ONLY the `vector_cortex_shadow_decision_recorded` /
+ * `vector_cortex_policy_action_rejected` events and the policy dashboard seam,
+ * which reports `enabled:false` + mode C when off. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring VC4A..VC8A.
+ */
+export const VC8B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8B");
+
+// VC8C (canary selection + external Rust parity) extracted to
+// vector-cortex-vc8c.ts to keep this file under the 300-line soft limit.
+// Re-exported here so every existing `from "./config/vector-cortex.js"`
+// import keeps resolving unchanged.
+export { VC8C_ENABLED } from "./vector-cortex-vc8c.js";
+
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker) extracted to
 // vector-cortex-breakers.ts to keep this file under the 300-line soft limit.
 export {

package/src/config.ts

@@ -176,6 +176,8 @@ export {
   VC7B_ENABLED,
   VC7C_ENABLED,
   VC8A_ENABLED,
+  VC8B_ENABLED,
+  VC8C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/cache/_diagnostics-fixture.ts

@@ -1,16 +1,42 @@
 /**
- * cache/_diagnostics-fixture.ts — VC7C acceptance-test fixture helpers.
+ * cache/_diagnostics-fixture.ts — VC7C conformance fixture I/O + host builders.
  *
- * Reads conformance fixtures from the v2 `cache-diagnostics/` domain and provides
- * a flag-toggling wrapper for VC7C parity tests. Mirrors `_economics-fixture.ts`.
+ * Reads conformance fixtures from the v2 `cache-diagnostics/` domain, decodes
+ * them into the REAL production types (`MissObservation`, `M5Host`) and feeds
+ * them verbatim into `classifyMiss` / `migrateRequestHashV2`. Fixtures store
+ * bigints as JSON numbers — converted here (lossy conversion would break
+ * digests and the acceptance rows would fail loudly).
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE
+ * `MissObservation` / `M5Host` and drive the production functions directly.
+ * Mirrors `_economics-fixture.ts`.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import type { MissObservation } from "./diagnostics-types.js";
+import type {
+  M5Host,
+  RequestHashV1Row,
+  RequestHashV2Row,
+} from "../migrations/request-hash-v2-types.js";
+
 const here = dirname(fileURLToPath(import.meta.url));
-const V2 = join(here, "..", "..", "..", "conformance", "vector-cortex", "v2");
+
+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 V2 = join(repoRoot(here), "conformance", "vector-cortex", "v2");
 const DIR = join(V2, "cache-diagnostics");
 
 /** Read + parse one conformance fixture by ID. */
@@ -30,3 +56,135 @@ export function withVc7cFlag<T>(value: string, fn: () => T): T {
     else process.env.MEGACOMPACT_VC7C = prior;
   }
 }
+
+// ── Cache-diagnostic fixture types (CACHE-016..030 + named) ──────────────────
+
+interface CacheFxInput {
+  scenario: string;
+  observe: {
+    requestProfileId: string;
+    requestProfileVersion: string;
+    cachedProfileId: string | null;
+    cachedProfileVersion: string | null;
+    requestCoveredDigest: string;
+    cachedCoveredDigest: string | null;
+    requestedRangeCount: number;
+    cachedRangeCount: number | null;
+    requestDigest: string;
+    cachedRequestDigest: string | null;
+    requestDependencyHighWater: number;
+    cachedDependencyHighWater: number | null;
+    generationInvalidated: boolean;
+  };
+}
+
+interface CacheFxExpected {
+  ok: boolean;
+  missClass: string;
+  evidence: {
+    profileMismatch: boolean;
+    rangeMismatch: boolean;
+    dependencyAdvanced: boolean;
+    requestMismatch: boolean;
+    generationInvalidated: boolean;
+    requestedRangeCount: number;
+    cachedRangeCount: number;
+    dependencyDelta: number;
+    absent: boolean;
+  };
+}
+
+export interface CacheFx {
+  id: string;
+  assertion: string;
+  input: CacheFxInput;
+  expected: CacheFxExpected;
+}
+
+/** Read a cache-diagnostic fixture as a typed CacheFx. */
+export function cacheFx(id: string): CacheFx {
+  return diagnosticsFixture(id) as unknown as CacheFx;
+}
+
+/** Decode the fixture's JSON observe into the production MissObservation. */
+export function toObservation(fx: CacheFx): MissObservation {
+  const o = fx.input.observe;
+  return {
+    requestProfileId: o.requestProfileId,
+    requestProfileVersion: o.requestProfileVersion,
+    cachedProfileId: o.cachedProfileId,
+    cachedProfileVersion: o.cachedProfileVersion,
+    requestCoveredDigest: o.requestCoveredDigest,
+    cachedCoveredDigest: o.cachedCoveredDigest,
+    requestedRangeCount: o.requestedRangeCount,
+    cachedRangeCount: o.cachedRangeCount,
+    requestDigest: o.requestDigest,
+    cachedRequestDigest: o.cachedRequestDigest,
+    requestDependencyHighWater: BigInt(o.requestDependencyHighWater),
+    cachedDependencyHighWater:
+      o.cachedDependencyHighWater === null
+        ? null
+        : BigInt(o.cachedDependencyHighWater),
+    generationInvalidated: o.generationInvalidated,
+  };
+}
+
+// ── M5 fixture types (M5-001..020 + M5-COLLIDE-002) ─────────────────────────
+
+interface M5FxInput {
+  scenario: string;
+  v1Rows: readonly { profileId: string; requestDigest: string; hash: string }[];
+  econVersionOf: Record<string, string>;
+  activeVersion: number;
+  sessionOf: Record<string, string>;
+  liveGenerationOf: Record<string, number>;
+}
+
+interface M5FxExpected {
+  ok: boolean;
+  codes: string[];
+  activeVersionAfter: number;
+}
+
+export interface M5Fx {
+  id: string;
+  assertion: string;
+  input: M5FxInput;
+  expected: M5FxExpected;
+}
+
+/** Read an M5 fixture as a typed M5Fx. */
+export function m5Fx(id: string): M5Fx {
+  return diagnosticsFixture(id) as unknown as M5Fx;
+}
+
+/** Build an in-memory M5Host from the fixture input. */
+export function toM5Host(
+  fx: M5Fx,
+): M5Host & { activeVersionAfter: number } {
+  const v1Rows: RequestHashV1Row[] = fx.input.v1Rows.map((r) => ({
+    profileId: r.profileId,
+    requestDigest: r.requestDigest,
+    hash: r.hash,
+  }));
+  const v2Rows: RequestHashV2Row[] = [];
+  let activeVersion = fx.input.activeVersion;
+
+  const host: M5Host & { activeVersionAfter: number } = {
+    v1Rows: () => v1Rows,
+    economicsVersionOf: (p) => fx.input.econVersionOf[p] ?? "econ-1",
+    sessionOf: (p) => fx.input.sessionOf[p] ?? "s1",
+    liveGenerationOf: (s) =>
+      BigInt(fx.input.liveGenerationOf[s] ?? 0),
+    existingV2: () => v2Rows,
+    putV2: (rows) => v2Rows.push(...rows),
+    activeVersion: () => activeVersion,
+    switchToV2: () => {
+      activeVersion = 2;
+    },
+    get activeVersionAfter() {
+      return activeVersion;
+    },
+  };
+  return host;
+}

package/src/vector-cortex/cache/diagnostics.ts

@@ -45,17 +45,32 @@ function advanceDelta(
 
 /** Collect the payload-free evidence from one observation. */
 export function collectEvidence(o: MissObservation): MissEvidence {
+  // Absence is computed first: "absence is not a mismatch" means a cold key
+  // (null cached fields) classifies `unknown`, never `profile`/`range`/etc.
+  // The cachedRangeCount on a cold key is 0 by convention (not a real count),
+  // so it must not trigger a range mismatch even though isPresent(0) is true.
+  const absent =
+    !isPresent(o.cachedProfileId) &&
+    !isPresent(o.cachedCoveredDigest) &&
+    !isPresent(o.cachedRequestDigest) &&
+    !isPresent(o.cachedDependencyHighWater);
+
   const profileMismatch =
     isPresent(o.cachedProfileId) &&
     isPresent(o.cachedProfileVersion) &&
     (o.cachedProfileId !== o.requestProfileId ||
       o.cachedProfileVersion !== o.requestProfileVersion);
 
+  // Guard with !absent: a cold key's cachedRangeCount is 0 by convention (not
+  // a real count), so it must not fire a range mismatch even though
+  // isPresent(0) is true. The covered-digest arm is already null-safe but
+  // the rangeCount arm is not — !absent covers both uniformly.
   const rangeMismatch =
-    (isPresent(o.cachedCoveredDigest) &&
+    !absent &&
+    ((isPresent(o.cachedCoveredDigest) &&
       o.cachedCoveredDigest !== o.requestCoveredDigest) ||
-    (isPresent(o.cachedRangeCount) &&
-      o.cachedRangeCount !== o.requestedRangeCount);
+      (isPresent(o.cachedRangeCount) &&
+        o.cachedRangeCount !== o.requestedRangeCount));
 
   const dep = advanceDelta(
     o.requestDependencyHighWater,
@@ -66,12 +81,6 @@ export function collectEvidence(o: MissObservation): MissEvidence {
     isPresent(o.cachedRequestDigest) &&
     o.cachedRequestDigest !== o.requestDigest;
 
-  const absent =
-    !isPresent(o.cachedProfileId) &&
-    !isPresent(o.cachedCoveredDigest) &&
-    !isPresent(o.cachedRequestDigest) &&
-    !isPresent(o.cachedDependencyHighWater);
-
   return {
     profileMismatch,
     rangeMismatch,