pi-mega-compact 0.20.14 → 0.20.16

package/extensions/dashboard-client/src/tabs/VectorCortexTab.tsx

@@ -4,46 +4,19 @@
  * GET /api/vector-cortex/evaluation. VC0C (task 5): live safety envelope health
  * card (breaker state, window/probe/backoff, durable spool frontier/lag) from
  * GET /api/vector-cortex/health plus an admin "reset cooldown" action. Polls
- * every 5s.
+ * every 5s via useVectorCortexPoll.
  */
 
-import { useState, useEffect, useCallback } from "react";
+import { useState } from "react";
 import {
-	fetchVectorCortexEvaluation,
-	fetchVectorCortexHealth,
-	fetchVectorCortexLedger,
-	fetchVectorCortexQuery,
-	fetchVectorCortexReconstruct,
-	fetchVectorCortexPlans,
-	fetchVectorCortexRender,
-	fetchVectorCortexRollout,
-	fetchVectorCortexClosureProof,
-	fetchVectorCortexRestore,
-	fetchVectorCortexRepair,
-	fetchVectorCortexCrystals,
-	fetchVectorCortexEconomics,
-	fetchVectorCortexShards,
-	fetchVectorCortexTopology,
 	resetVectorCortexBreaker,
-	type VectorCortexEvaluationSummary,
+	fetchVectorCortexHealth,
 	type VectorCortexHealthCard,
-	type VectorCortexLedgerView,
-	type VectorCortexQueryView,
-	type VectorCortexReconstructView,
-	type VectorCortexPlansView,
-	type VectorCortexRenderView,
-	type VectorCortexRolloutView,
-	type VectorCortexClosureProofView,
-	type VectorCortexRestoreView,
-	type VectorCortexRepairView,
-	type VectorCortexCrystalsView,
-	type VectorCortexEconomicsView,
-	type VectorCortexShardsView,
-	type VectorCortexTopologyView,
 } from "../api/vector-cortex";
 import { Card, CardContent, CardHeader, CardTitle } from "../components/ui/card";
 import { Badge } from "../components/ui/badge";
 import { Metric } from "./VectorCortexMetric";
+import { useVectorCortexPoll } from "./useVectorCortexPoll";
 import { VectorCortexRenderCard } from "./VectorCortexRenderCard";
 import { VectorCortexRolloutCard } from "./VectorCortexRolloutCard";
 import { VectorCortexClosureCard } from "./VectorCortexClosureCard";
@@ -51,6 +24,7 @@ import { VectorCortexRestoreCard } from "./VectorCortexRestoreCard";
 import { VectorCortexRepairCard } from "./VectorCortexRepairCard";
 import { VectorCortexCrystalsCard } from "./VectorCortexCrystalsCard";
 import { VectorCortexEconomicsCard } from "./VectorCortexEconomicsCard";
+import { VectorCortexDiagnosticsCard } from "./VectorCortexDiagnosticsCard";
 import {
 	VectorCortexShardsCard,
 	VectorCortexReconstructCard,
@@ -69,81 +43,10 @@ function ModeChip({ mode, count }: { mode: string; count: number }): React.React
 }
 
 export default function VectorCortexTab(): React.ReactElement {
-	const [data, setData] = useState<VectorCortexEvaluationSummary | null>(null);
-	const [err, setError] = useState<string | null>(null);
-	const [loading, setLoading] = useState(true);
-	const [health, setHealth] = useState<VectorCortexHealthCard | null>(null);
+	const [poll, refetch] = useVectorCortexPoll();
 	const [resetMsg, setResetMsg] = useState<string | null>(null);
-	const [ledger, setLedger] = useState<VectorCortexLedgerView | null>(null);
-	const [topology, setTopology] = useState<VectorCortexTopologyView | null>(null);
-	const [query, setQuery] = useState<VectorCortexQueryView | null>(null);
-	const [shards, setShards] = useState<VectorCortexShardsView | null>(null);
-	const [reconstruct, setReconstruct] = useState<VectorCortexReconstructView | null>(null);
-	const [plans, setPlans] = useState<VectorCortexPlansView | null>(null);
-	const [render, setRender] = useState<VectorCortexRenderView | null>(null);
-	const [rollout, setRollout] = useState<VectorCortexRolloutView | null>(null);
-	const [closureProof, setClosureProof] = useState<VectorCortexClosureProofView | null>(null);
-	const [restore, setRestore] = useState<VectorCortexRestoreView | null>(null);
-	const [repair, setRepair] = useState<VectorCortexRepairView | null>(null);
-	const [crystals, setCrystals] = useState<VectorCortexCrystalsView | null>(null);
-	const [economics, setEconomics] = useState<VectorCortexEconomicsView | null>(null);
-
-	const poll = useCallback(() => {
-		fetchVectorCortexEvaluation()
-			.then(setData)
-			.catch((e: unknown) =>
-				setError(e instanceof Error ? e.message : String(e)),
-			)
-			.finally(() => setLoading(false));
-		fetchVectorCortexHealth().then(setHealth).catch(() => {
-			/* health card is best-effort (VC0C) */
-		});
-		fetchVectorCortexLedger().then(setLedger).catch(() => {
-			/* ledger card is best-effort (VC1B) */
-		});
-		fetchVectorCortexTopology().then(setTopology).catch(() => {
-			/* topology card is best-effort (VC3A) */
-		});
-		fetchVectorCortexQuery().then(setQuery).catch(() => {
-			/* query diagnostics card is best-effort (VC3C) */
-		});
-		fetchVectorCortexShards().then(setShards).catch(() => {
-			/* dual-tier shards card is best-effort (VC4A) */
-		});
-		fetchVectorCortexReconstruct().then(setReconstruct).catch(() => {
-			/* reconstruction-fidelity card is best-effort (VC4C) */
-		});
-		fetchVectorCortexPlans().then(setPlans).catch(() => {
-			/* plan manifest card is best-effort (VC5A) */
-		});
-		fetchVectorCortexRender().then(setRender).catch(() => {
-			/* render conformance card is best-effort (VC5B) */
-		});
-		fetchVectorCortexRollout().then(setRollout).catch(() => {
-			/* rollout card is best-effort (VC5C) */
-		});
-		fetchVectorCortexClosureProof().then(setClosureProof).catch(() => {
-			/* closure-optimization card is best-effort (VC6A) */
-		});
-		fetchVectorCortexRestore().then(setRestore).catch(() => {
-			/* exact-source-restoration card is best-effort (VC6B) */
-		});
-		fetchVectorCortexRepair().then(setRepair).catch(() => {
-			/* self-healing derived-state card is best-effort (VC6C) */
-		});
-		fetchVectorCortexCrystals().then(setCrystals).catch(() => {
-			/* frozen-range-crystal card is best-effort (VC7A) */
-		});
-		fetchVectorCortexEconomics().then(setEconomics).catch(() => {
-			/* provider-cache-economics card is best-effort (VC7B) */
-		});
-	}, []);
 
-	useEffect(() => {
-		poll();
-		const id = setInterval(poll, 5000);
-		return () => clearInterval(id);
-	}, [poll]);
+	const { loading, error, data, health } = poll;
 
 	const onReset = () => {
 		resetVectorCortexBreaker("provider")
@@ -153,7 +56,7 @@ export default function VectorCortexTab(): React.ReactElement {
 				);
 				return fetchVectorCortexHealth();
 			})
-			.then(setHealth)
+			.then((h: VectorCortexHealthCard | null) => { void h; refetch(); })
 			.catch((e: unknown) =>
 				setResetMsg(e instanceof Error ? e.message : String(e)),
 			);
@@ -161,8 +64,8 @@ export default function VectorCortexTab(): React.ReactElement {
 
 	if (loading && !data)
 		return <div className="vc-loading">Loading vector-cortex evaluation…</div>;
-	if (err && !data)
-		return <div className="vc-error">Error: {err}</div>;
+	if (error && !data)
+		return <div className="vc-error">Error: {error}</div>;
 	if (!data)
 		return <div className="vc-empty">No evaluation data available.</div>;
 
@@ -281,24 +184,25 @@ export default function VectorCortexTab(): React.ReactElement {
 								}
 							/>
 							<Metric label="Spool lag" value={String(health.spoolLag)} />
-								<Metric label="Encoder mode" value={health.encoderMode} />
-								<Metric label="Encoder asset" value={health.encoderAssetDigest ? health.encoderAssetDigest.slice(0, 12) : "none"} />
+							<Metric label="Encoder mode" value={health.encoderMode} />
+							<Metric label="Encoder asset" value={health.encoderAssetDigest ? health.encoderAssetDigest.slice(0, 12) : "none"} />
 						</div>
 					)}
 				</CardContent>
 			</Card>
-			<VectorCortexTopologyCard topology={topology} query={query} />
-			<VectorCortexShardsCard view={shards} />
-			<VectorCortexReconstructCard view={reconstruct} />
-			<VectorCortexPlansCard view={plans} />
-			<VectorCortexRenderCard view={render} />
-			<VectorCortexRolloutCard view={rollout} />
-			<VectorCortexClosureCard view={closureProof} />
-			<VectorCortexRestoreCard view={restore} />
-			<VectorCortexRepairCard view={repair} />
-			<VectorCortexCrystalsCard view={crystals} />
-			<VectorCortexEconomicsCard view={economics} />
-			<VectorCortexLedgerCard ledger={ledger} />
+			<VectorCortexTopologyCard topology={poll.topology} query={poll.query} />
+			<VectorCortexShardsCard view={poll.shards} />
+			<VectorCortexReconstructCard view={poll.reconstruct} />
+			<VectorCortexPlansCard view={poll.plans} />
+			<VectorCortexRenderCard view={poll.render} />
+			<VectorCortexRolloutCard view={poll.rollout} />
+			<VectorCortexClosureCard view={poll.closureProof} />
+			<VectorCortexRestoreCard view={poll.restore} />
+			<VectorCortexRepairCard view={poll.repair} />
+			<VectorCortexCrystalsCard view={poll.crystals} />
+			<VectorCortexEconomicsCard view={poll.economics} />
+			<VectorCortexDiagnosticsCard view={poll.diagnostics} />
+			<VectorCortexLedgerCard ledger={poll.ledger} />
 		</div>
 	);
 }

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

@@ -0,0 +1,123 @@
+/**
+ * useVectorCortexPoll — extracted from VectorCortexTab to keep the tab under
+ * the 400-line soft limit. Fetches all vector-cortex reader views in parallel
+ * every 5s; each fetch is best-effort (a failure sets its slice to null/state).
+ */
+import { useState, useEffect, useCallback } from "react";
+import {
+	fetchVectorCortexEvaluation,
+	fetchVectorCortexHealth,
+	fetchVectorCortexLedger,
+	fetchVectorCortexQuery,
+	fetchVectorCortexReconstruct,
+	fetchVectorCortexPlans,
+	fetchVectorCortexRender,
+	fetchVectorCortexRollout,
+	fetchVectorCortexClosureProof,
+	fetchVectorCortexRestore,
+	fetchVectorCortexRepair,
+	fetchVectorCortexCrystals,
+	fetchVectorCortexEconomics,
+	fetchVectorCortexDiagnostics,
+	fetchVectorCortexShards,
+	fetchVectorCortexTopology,
+	type VectorCortexEvaluationSummary,
+	type VectorCortexHealthCard,
+	type VectorCortexLedgerView,
+	type VectorCortexQueryView,
+	type VectorCortexReconstructView,
+	type VectorCortexPlansView,
+	type VectorCortexRenderView,
+	type VectorCortexRolloutView,
+	type VectorCortexClosureProofView,
+	type VectorCortexRestoreView,
+	type VectorCortexRepairView,
+	type VectorCortexCrystalsView,
+	type VectorCortexEconomicsView,
+	type VectorCortexDiagnosticsView,
+	type VectorCortexShardsView,
+	type VectorCortexTopologyView,
+} from "../api/vector-cortex";
+
+export interface VectorCortexPollState {
+	loading: boolean;
+	error: string | null;
+	data: VectorCortexEvaluationSummary | null;
+	health: VectorCortexHealthCard | null;
+	ledger: VectorCortexLedgerView | null;
+	topology: VectorCortexTopologyView | null;
+	query: VectorCortexQueryView | null;
+	shards: VectorCortexShardsView | null;
+	reconstruct: VectorCortexReconstructView | null;
+	plans: VectorCortexPlansView | null;
+	render: VectorCortexRenderView | null;
+	rollout: VectorCortexRolloutView | null;
+	closureProof: VectorCortexClosureProofView | null;
+	restore: VectorCortexRestoreView | null;
+	repair: VectorCortexRepairView | null;
+	crystals: VectorCortexCrystalsView | null;
+	economics: VectorCortexEconomicsView | null;
+	diagnostics: VectorCortexDiagnosticsView | null;
+}
+
+export function useVectorCortexPoll(): [
+	VectorCortexPollState,
+	() => void,
+] {
+	const [state, setState] = useState<VectorCortexPollState>({
+		loading: true,
+		error: null,
+		data: null,
+		health: null,
+		ledger: null,
+		topology: null,
+		query: null,
+		shards: null,
+		reconstruct: null,
+		plans: null,
+		render: null,
+		rollout: null,
+		closureProof: null,
+		restore: null,
+		repair: null,
+		crystals: null,
+		economics: null,
+		diagnostics: null,
+	});
+
+	const poll = useCallback(() => {
+		setState((prev) => ({ ...prev, loading: true }));
+		fetchVectorCortexEvaluation()
+			.then((data) => setState((prev) => ({ ...prev, data, loading: false, error: null })))
+			.catch((e: unknown) =>
+				setState((prev) => ({
+					...prev,
+					loading: false,
+					error: e instanceof Error ? e.message : String(e),
+				})),
+			);
+		fetchVectorCortexHealth().then((health) => setState((p) => ({ ...p, health }))).catch(() => {});
+		fetchVectorCortexLedger().then((ledger) => setState((p) => ({ ...p, ledger }))).catch(() => {});
+		fetchVectorCortexTopology().then((topology) => setState((p) => ({ ...p, topology }))).catch(() => {});
+		fetchVectorCortexQuery().then((query) => setState((p) => ({ ...p, query }))).catch(() => {});
+		fetchVectorCortexShards().then((shards) => setState((p) => ({ ...p, shards }))).catch(() => {});
+		fetchVectorCortexReconstruct().then((reconstruct) => setState((p) => ({ ...p, reconstruct }))).catch(() => {});
+		fetchVectorCortexPlans().then((plans) => setState((p) => ({ ...p, plans }))).catch(() => {});
+		fetchVectorCortexRender().then((render) => setState((p) => ({ ...p, render }))).catch(() => {});
+		fetchVectorCortexRollout().then((rollout) => setState((p) => ({ ...p, rollout }))).catch(() => {});
+		fetchVectorCortexClosureProof().then((closureProof) => setState((p) => ({ ...p, closureProof }))).catch(() => {});
+		fetchVectorCortexRestore().then((restore) => setState((p) => ({ ...p, restore }))).catch(() => {});
+		fetchVectorCortexRepair().then((repair) => setState((p) => ({ ...p, repair }))).catch(() => {});
+		fetchVectorCortexCrystals().then((crystals) => setState((p) => ({ ...p, crystals }))).catch(() => {});
+		fetchVectorCortexEconomics().then((economics) => setState((p) => ({ ...p, economics }))).catch(() => {});
+		fetchVectorCortexDiagnostics().then((diagnostics) => setState((p) => ({ ...p, diagnostics }))).catch(() => {});
+	}, []);
+
+	useEffect(() => {
+		poll();
+		const id = setInterval(poll, 5000);
+		return () => clearInterval(id);
+	}, [poll]);
+
+	return [state, poll];
+}

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

@@ -0,0 +1,63 @@
+/**
+ * dashboard-client/src/types/vector-cortex-vc7.ts — VC7-era client view types.
+ *
+ * Extracted from vector-cortex.ts to keep the parent file under the 300-line
+ * soft limit (soft-as-hard gate). Each interface mirrors a reader-only server
+ * API contract: counts + codes only, never prompt payloads, digests, or session
+ * bytes.
+ */
+
+/**
+ * Reader-only frozen-crystal cache view (VC7A). Counts + byte volumes + CRY_*
+ * codes only — a crystal is a rendered prompt, so no frozen bytes, covered
+ * ranges, digests, or session ids ever reach the client.
+ */
+export interface VectorCortexCrystalsView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  crystalCount: number;
+  totalBytes: number;
+  hits: number;
+  misses: number;
+  hitBytes: number;
+  writes: number;
+  duplicateWrites: number;
+  collisions: number;
+  lastFailure: string | null;
+  updatedAt: string;
+}
+
+/**
+ * Reader-only cache-economics diagnostics view (VC7B). Counts + ECON_* codes only
+ * — never prices, digests, ranges, or session ids.
+ */
+export interface VectorCortexEconomicsView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  profileCount: number;
+  provenExclusions: number;
+  unprovenExclusions: number;
+  lastFailure: string | null;
+  updatedAt: string;
+}
+
+/**
+ * Reader-only cache miss-diagnostics view (VC7C). One count per EXCLUSIVE miss
+ * class plus breaker state and CACHE_* / M5_* codes only — a miss diagnostic would
+ * otherwise carry the missed request itself, so no request payload, request
+ * digest, covered range, span digest, or session id ever reaches the client.
+ */
+export interface VectorCortexDiagnosticsView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  profileMisses: number;
+  rangeMisses: number;
+  dependencyMisses: number;
+  requestMisses: number;
+  generationMisses: number;
+  unknownMisses: number;
+  serveBlocked: number;
+  breakerState: string;
+  lastFailure: string | null;
+  updatedAt: string;
+}

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

@@ -256,36 +256,8 @@ export interface VectorCortexClosureProofView {
   updatedAt: string;
 }
 
-/**
- * Reader-only frozen-crystal cache view (VC7A). Counts + byte volumes + CRY_*
- * codes only — a crystal is a rendered prompt, so no frozen bytes, covered
- * ranges, digests, or session ids ever reach the client.
- */
-export interface VectorCortexCrystalsView {
-  enabled: boolean;
-  mode: "A" | "B" | "C";
-  crystalCount: number;
-  totalBytes: number;
-  hits: number;
-  misses: number;
-  hitBytes: number;
-  writes: number;
-  duplicateWrites: number;
-  collisions: number;
-  lastFailure: string | null;
-  updatedAt: string;
-}
-
-/**
- * Reader-only cache-economics diagnostics view (VC7B). Counts + ECON_* codes only
- * — never prices, digests, ranges, or session ids.
- */
-export interface VectorCortexEconomicsView {
-  enabled: boolean;
-  mode: "A" | "B" | "C";
-  profileCount: number;
-  provenExclusions: number;
-  unprovenExclusions: number;
-  lastFailure: string | null;
-  updatedAt: string;
-}
+export type {
+  VectorCortexCrystalsView,
+  VectorCortexEconomicsView,
+  VectorCortexDiagnosticsView,
+} from "./vector-cortex-vc7.js";

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

@@ -0,0 +1,76 @@
+/**
+ * api-contracts/vector-cortex-diagnostics.ts — VC7C cache-diagnostics API
+ * contract.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ *
+ * Reader-only GET /api/vector-cortex/cache-diagnostics view (VC7C).
+ *
+ * COUNTS + CODES ONLY, and this surface is the most dangerous one in the whole
+ * VC7 cache phase. A cache MISS DIAGNOSTIC exists to answer "why did this exact
+ * request not hit the cache?", and the honest answer is naturally phrased in
+ * terms of the very things that must never leave the process: the full request
+ * payload that was hashed, its RequestHashV2 digest, the covered source ranges,
+ * the span/covered digests, the provider profile digest and the session id that
+ * frames the conversation. Every one of those is precisely the evidence a
+ * debugger would want inline — which is exactly why an unguarded diagnostic
+ * field here leaks the framed conversation itself (SECURITY_PRIVACY). The
+ * classification is therefore projected down to a COUNT PER MISS CLASS before it
+ * ever reaches this contract: the class names are a closed enumeration fixed by
+ * the sprint, so a count discloses nothing about content.
+ *
+ * This view exposes ONLY:
+ *   - whether the VC7C flag is enabled and the runtime triad mode it implies;
+ *   - one count per exclusive miss class (profile, range, dependency, request,
+ *     generation, unknown) — classification is exclusive, so a single miss
+ *     increments exactly one of these six counters and they sum to the total;
+ *   - how many cache serves the breaker blocked (a count, never the blocked key
+ *     or the entry it would have served);
+ *   - the breaker's observable state and the last CACHE/M5 rejection code.
+ * Request payloads, request digests, covered ranges, span digests, profile
+ * digests, and session ids live in the structured event log / conformance
+ * corpus, never here.
+ */
+
+/** Runtime triad mode implied by the VC7C flag state. */
+export type VectorCortexDiagnosticsMode = "A" | "B" | "C";
+
+/**
+ * Reader-only cache-diagnostics view for
+ * GET /api/vector-cortex/cache-diagnostics (VC7C).
+ */
+export interface VectorCortexDiagnosticsView {
+  /** Whether the VC7C cache-diagnostics flag is enabled. */
+  readonly enabled: boolean;
+  /**
+   * Runtime triad mode: "A" a crystal was served from cache,
+   * "B" a fresh render was forced by a breaker condition,
+   * "C" all caches are bypassed (flag off, or render and cache diagnostics
+   * disagree) so nothing is served from cache.
+   */
+  readonly mode: VectorCortexDiagnosticsMode;
+  /** Misses classified as a provider-profile mismatch (count only). */
+  readonly profileMisses: number;
+  /** Misses classified as a covered-range mismatch (count only). */
+  readonly rangeMisses: number;
+  /** Misses classified as a dependency high-water mismatch (count only). */
+  readonly dependencyMisses: number;
+  /** Misses classified as a request (RequestHashV2) mismatch (count only). */
+  readonly requestMisses: number;
+  /** Misses classified as a stale/invalidated generation (count only). */
+  readonly generationMisses: number;
+  /** Misses no earlier class claimed — the terminal fallback (count only). */
+  readonly unknownMisses: number;
+  /**
+   * Cache serves the breaker demoted BEFORE serving, on collision, stale
+   * generation, digest failure, or profile mismatch (a count, never the key).
+   */
+  readonly serveBlocked: number;
+  /** Observable cache-breaker state (a state name, not a payload). */
+  readonly breakerState: string;
+  /** Last diagnostics rejection reason (a CACHE or M5 code), or null. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}

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

@@ -68,6 +68,10 @@ import { handleVectorCortexCrystals } from "./routes-vector-cortex-crystals.js";
 // independent of the crystals handler and every file stays well under the
 // 400-line extension soft limit.
 import { handleVectorCortexEconomics } from "./routes-vector-cortex-economics.js";
+// VC7C cache miss diagnostics + breakers gets its own module so the
+// diagnostics seam stays independent of economics and every file stays well
+// under the 400-line extension soft limit.
+import { handleVectorCortexDiagnostics } from "./routes-vector-cortex-diagnostics.js";
 
 /**
  * Dispatch a request through every registered route handler.
@@ -124,5 +128,6 @@ export function dispatchRoutes(
 	if (handleVectorCortexRepair(req, res, ctx)) return true;
 	if (handleVectorCortexCrystals(req, res, ctx)) return true;
 	if (handleVectorCortexEconomics(req, res, ctx)) return true;
+	if (handleVectorCortexDiagnostics(req, res, ctx)) return true;
 	return false;
 }

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

@@ -168,5 +168,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Provider cache economics: extends the VC5B provider registry with cache economics (read/write price, TTL, minimum prefix, and a mandatory exclusion fixture id). Answers whether reusing a frozen crystal is actually worth it — a cache WRITE typically costs more than an uncached token, so a cache only pays off once a written prefix is re-read enough times before TTL expiry. Net savings are reported (never clamped at zero, so a losing cache stays visible) and every exclusion MUST name a proving conformance fixture or it is rejected (ECON_EXCLUSION_UNPROVEN). A compiled crystal boundary still reuses the VC7A key unchanged, and a randomized session-level experiment assigns arms by a stable hash so a lost assignment journal re-derives the same arm. OFF = byte-identical predecessor (VC7A); the economics/compiler/experiment arithmetic still runs, only the reporter + dashboard seam is suppressed.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC7C",
+			"VC7C Cache Diagnostics & Breakers",
+			"Cache miss diagnostics + cache-level breakers + the completed M5 request-hash-v2 switch. Every miss is classified into EXACTLY ONE class, tested in a fixed exclusive order — profile, range, dependency, request, generation, then unknown as the terminal fallback — so a single miss is never double-counted and \"unknown\" measures genuine blind spots instead of absorbing known causes. Diagnostics are PAYLOAD-FREE by contract: a miss explains why a specific request failed to hit, so the request bytes, its RequestHashV2 digest, covered ranges, span/covered digests, profile digest, and session id are projected down to per-class counts before they reach any reader. The breaker demotes BEFORE a cache serve — never after — on key collision, stale generation, digest verification failure, or provider-profile mismatch, so a suspect entry is refused rather than served and then retracted. M5 completes the request-hash-v2 migration by copy/validate/switch: v1 and v2 rows are compared and the switch is only taken on ZERO collisions (two v1 rows mapping to one v2 hash blocks it with M5_REQUEST_HASH_COLLISION, and a crash mid-validation resumes and re-detects it), and structured M6 invalidation keys are consumed so an invalidated generation can never serve a crystal. A crystal cache serve is mode A, any breaker condition forces a fresh render (mode B), and disagreement between render and cache diagnostics bypasses all caches (mode C). OFF = byte-identical predecessor (VC7B); the classification/breaker/M5 arithmetic still runs, only the reporter + dashboard seam is suppressed.",
+			true,
+		),
 	],
 };

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

@@ -0,0 +1,77 @@
+/**
+ * dashboard-server/routes-vector-cortex-diagnostics.ts — VC7C cache-diagnostics
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/cache-diagnostics returning the cache miss
+ * classification aggregate: whether the VC7C flag is enabled, the runtime triad
+ * mode, one count per exclusive miss class (profile, range, dependency, request,
+ * generation, unknown), how many cache serves the breaker blocked, the breaker
+ * state, and the last CACHE/M5 failure code.
+ *
+ * COUNTS + CODES ONLY. A cache miss diagnostic answers "why did THIS request
+ * miss?", so the natural (and forbidden) payload is the request itself: the
+ * hashed request bytes, its RequestHashV2 digest, the covered source ranges, the
+ * span/covered digests, the provider profile digest, and the session id. This
+ * route NEVER exposes any of them — the classification is projected to a count
+ * per closed-enumeration class before it reaches the wire (reader-only,
+ * SECURITY_PRIVACY). There is no mutation seam: misses are classified and
+ * breakers are tripped by the cache serve path, never by a dashboard request,
+ * and in particular the breaker can NOT be reset through this route. Non-GET is
+ * rejected outright.
+ *
+ * Split into its own file (rather than grown into routes-vector-cortex-economics.ts)
+ * to keep every extensions/ file well under the 400-line soft-as-hard limit.
+ *
+ * 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 { VC7C_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexDiagnosticsView } from "./api-contracts/vector-cortex-diagnostics.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/cache-diagnostics (VC7C).
+ *
+ * Per-miss-class counts, breaker state, and CACHE and M5 codes only — a static
+ * reader-only aggregate seam with the same shape as the VC7B economics handler.
+ */
+export function handleVectorCortexDiagnostics(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/cache-diagnostics") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC7C_ENABLED();
+  // Flag-off routes to mode C: with VC7C off the diagnostics/breaker reporter is
+  // suppressed, so no cache serve is attested here and the surface reports the
+  // all-cache bypass outcome. Reporting A (crystal served) or B (fresh render
+  // forced by a breaker) would attest a cache decision this seam is not wired to
+  // observe. Mirrors how the VC7A/VC7B OFF views report the mode they take.
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexDiagnosticsView = {
+    enabled,
+    mode,
+    profileMisses: 0,
+    rangeMisses: 0,
+    dependencyMisses: 0,
+    requestMisses: 0,
+    generationMisses: 0,
+    unknownMisses: 0,
+    serveBlocked: 0,
+    breakerState: "closed",
+    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.14",
+  "version": "0.20.16",
   "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

@@ -218,6 +218,27 @@ export const VC7A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7A");
  */
 export const VC7B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7B");
 
+/**
+ * VC7C — cache miss diagnostics, cache-level breakers and the completed M5
+ * request-hash-v2 switch. Default ON. `MEGACOMPACT_VC7C=0` disables and is
+ * byte-identical to the predecessor (VC7B): the miss `classify`, the breaker
+ * demotion decision and the M5 request-hash-v2 ARITHMETIC STILL RUN (they are
+ * PURE — an exclusive ordered comparison over already-computed digests plus a
+ * canonical length-prefixed SHA-256, with no clock, storage, or network), so a
+ * miss is classified into the SAME single class, a collision / stale generation
+ * / digest failure / profile mismatch still demotes BEFORE any cache serve, and
+ * the v2 hash of a given request is unchanged with the flag off. A cache is
+ * never allowed to serve a stale or colliding entry merely because reporting is
+ * off — that would be a correctness change, not a reporting change.
+ *
+ * The flag gates ONLY the `vector_cortex_cache_miss_classified` /
+ * `vector_cortex_cache_serve_blocked` events and the cache-diagnostics 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..VC7B.
+ */
+export const VC7C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7C");
+
 // 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

@@ -174,6 +174,7 @@ export {
   VC6C_ENABLED,
   VC7A_ENABLED,
   VC7B_ENABLED,
+  VC7C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,