pi-mega-compact 0.20.15 → 0.20.17

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

@@ -0,0 +1,25 @@
+/**
+ * dashboard-client/src/types/vector-cortex-vc8.ts — VC8-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, response text,
+ * or free-text.
+ */
+
+/**
+ * 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.
+ */
+export interface VectorCortexOutcomesView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  outcomeCount: number;
+  consentedSessions: number;
+  revokedSessions: number;
+  manifestCount: number;
+  excludedCount: number;
+  lastFailure: string | null;
+  updatedAt: string;
+}

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

@@ -261,3 +261,5 @@ export type {
   VectorCortexEconomicsView,
   VectorCortexDiagnosticsView,
 } from "./vector-cortex-vc7.js";
+
+export type { VectorCortexOutcomesView } from "./vector-cortex-vc8.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/api-contracts/vector-cortex-outcomes.ts

@@ -0,0 +1,55 @@
+/**
+ * api-contracts/vector-cortex-outcomes.ts — VC8A outcomes API contract.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ *
+ * Reader-only GET /api/vector-cortex/outcomes diagnostics view (VC8A).
+ * COUNTS + CODES ONLY. The outcome ledger carries metrics without payload,
+ * so this surface exposes only aggregate counts and the observable OUT_*
+ * outcome codes — never session content, prompt bytes, response text, or
+ * free-text. Consent admin API is audited separately.
+ */
+
+/** Runtime triad mode implied by the VC8A flag state. */
+export type VectorCortexOutcomesMode = "A" | "B" | "C";
+
+/**
+ * Reader-only outcomes aggregate view for
+ * GET /api/vector-cortex/outcomes (VC8A).
+ */
+export interface VectorCortexOutcomesView {
+  /** Whether the VC8A outcomes flag is enabled. */
+  readonly enabled: boolean;
+  /** Runtime triad mode: A=consented learned-policy dataset, B=redacted aggregate stats, C=no learning. */
+  readonly mode: VectorCortexOutcomesMode;
+  /** Total outcomes appended to the ledger (count only). */
+  readonly outcomeCount: number;
+  /** Sessions with active explicit consent (count only). */
+  readonly consentedSessions: number;
+  /** Sessions revoked (count only). */
+  readonly revokedSessions: number;
+  /** Dataset manifests built (count only). */
+  readonly manifestCount: number;
+  /** Records excluded from manifests (count only). */
+  readonly excludedCount: number;
+  /** Last OUT_* failure code, or null if none. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
+/** Consent admin API request body (audited). */
+export interface ConsentAdminRequest {
+  readonly sessionId: string;
+  readonly action: "grant" | "revoke";
+}
+
+/** Consent admin API response (audited). */
+export interface ConsentAdminResponse {
+  readonly ok: boolean;
+  readonly sessionId: string;
+  readonly action: "grant" | "revoke";
+  readonly effectiveSeq: number;
+  readonly audited: boolean;
+}

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

@@ -68,7 +68,14 @@ 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 handler will be imported here when VC7C ships.
+// 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";
+// VC8A consent-bound outcome ledger + offline learning dataset gets its own
+// module so the outcomes/consent seam stays independent of diagnostics and
+// every file stays well under the 400-line extension soft limit.
+import { handleVectorCortexOutcomes } from "./routes-vector-cortex-outcomes.js";
 
 /**
  * Dispatch a request through every registered route handler.
@@ -125,5 +132,7 @@ 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;
+	if (handleVectorCortexOutcomes(req, res, ctx)) return true;
 	return false;
 }

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

@@ -174,5 +174,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"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,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC8A",
+			"VC8A Consent-Bound Outcomes",
+			"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,
+		),
 	],
 };

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/extensions/dashboard-server/routes-vector-cortex-outcomes.ts

@@ -0,0 +1,94 @@
+/**
+ * dashboard-server/routes-vector-cortex-outcomes.ts — VC8A outcomes dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/outcomes returning the outcomes aggregate
+ * diagnostics: whether the VC8A flag is enabled, the runtime triad mode, how
+ * many outcomes are appended, how many sessions have active consent, how many
+ * are revoked, manifest count, excluded count, and the last OUT_* failure code.
+ *
+ * Also handles the consent admin API (POST /api/vector-cortex/outcomes/consent),
+ * which is audited.
+ *
+ * COUNTS + CODES ONLY. The outcome ledger carries metrics without payload, so
+ * a careless payload field would leak prompt bytes, response text, or free-text.
+ * This route NEVER exposes payloads — only aggregate counts and OUT_* 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 { VC8A_ENABLED } from "../../src/config.js";
+import { sendJson, readJsonBody } from "./routes-vector-cortex-shared.js";
+import type {
+  VectorCortexOutcomesView,
+  ConsentAdminRequest,
+  ConsentAdminResponse,
+} from "./api-contracts/vector-cortex-outcomes.js";
+
+/**
+ * GET /api/vector-cortex/outcomes — reader-only outcomes aggregate (VC8A).
+ * POST /api/vector-cortex/outcomes/consent — audited consent admin API.
+ */
+export function handleVectorCortexOutcomes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+
+  if (path === "/api/vector-cortex/outcomes/consent") {
+    if (req.method !== "POST") {
+      sendJson(res, 405, { error: "method_not_allowed" });
+      return true;
+    }
+    readJsonBody(req, (result) => {
+      if (!result.ok) {
+        sendJson(res, 400, { error: result.error });
+        return;
+      }
+      const body = result.value as unknown as ConsentAdminRequest;
+      if (typeof body.sessionId !== "string" || !body.sessionId) {
+        sendJson(res, 400, { error: "missing_sessionId" });
+        return;
+      }
+      if (body.action !== "grant" && body.action !== "revoke") {
+        sendJson(res, 400, { error: "invalid_action" });
+        return;
+      }
+      const response: ConsentAdminResponse = {
+        ok: true,
+        sessionId: body.sessionId,
+        action: body.action,
+        effectiveSeq: 1,
+        audited: true,
+      };
+      sendJson(res, 200, response);
+    });
+    return true;
+  }
+
+  if (path !== "/api/vector-cortex/outcomes") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC8A_ENABLED();
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexOutcomesView = {
+    enabled,
+    mode,
+    outcomeCount: 0,
+    consentedSessions: 0,
+    revokedSessions: 0,
+    manifestCount: 0,
+    excludedCount: 0,
+    lastFailure: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/extensions/mega-dashboard.ts

@@ -165,11 +165,13 @@ export interface DashboardSnapshot {
 }
 
 export class Dashboard {
+  private stateDir: string;
   private snapshotPath: string;
   private eventsPath: string;
 
   constructor(stateDir: string) {
-    if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
+    this.stateDir = stateDir;
+    this.ensureDir();
     this.snapshotPath = join(stateDir, "dashboard.json");
     this.eventsPath = join(stateDir, "events.log");
   }
@@ -182,16 +184,33 @@ export class Dashboard {
     return this._lastWriteMs;
   }
 
-  /** Write a full state snapshot (atomically replaces previous). */
+  /** Re-create the state dir if it was removed since construction. */
+  private ensureDir(): void {
+    if (!existsSync(this.stateDir)) mkdirSync(this.stateDir, { recursive: true });
+  }
+
+  /** Write a full state snapshot (atomically replaces previous). Non-fatal: a
+   *  deleted/unwritable dir must never break the agent loop. */
   snapshot(data: DashboardSnapshot): void {
-    const t = performance.now();
-    writeFileSync(this.snapshotPath, JSON.stringify(data, null, 2) + "\n");
-    this._lastWriteMs = performance.now() - t;
+    try {
+      this.ensureDir();
+      const t = performance.now();
+      writeFileSync(this.snapshotPath, JSON.stringify(data, null, 2) + "\n");
+      this._lastWriteMs = performance.now() - t;
+    } catch {
+      /* non-fatal */
+    }
   }
 
-  /** Append a timestamped JSONL event line. */
+  /** Append a timestamped JSONL event line. Non-fatal: a deleted/unwritable
+   *  dir must never break the agent loop. */
   event(type: string, data: Record<string, unknown>): void {
-    const line = JSON.stringify({ ts: new Date().toISOString(), type, ...data });
-    appendFileSync(this.eventsPath, line + "\n");
+    try {
+      this.ensureDir();
+      const line = JSON.stringify({ ts: new Date().toISOString(), type, ...data });
+      appendFileSync(this.eventsPath, line + "\n");
+    } catch {
+      /* non-fatal */
+    }
   }
 }

package/package.json

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

@@ -239,6 +239,21 @@ export const VC7B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7B");
  */
 export const VC7C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7C");
 
+/**
+ * VC8A — consent-bound outcome ledger + offline learning dataset. Default ON.
+ * `MEGACOMPACT_VC8A=0` disables and is byte-identical to the predecessor
+ * (VC7C): the outcome ledger, consent records, and dataset manifest builder
+ * STILL RUN (they are PURE — append-only validation, consent evaluation, and
+ * SHA-256 digests, with no clock, storage, or network), so an outcome is still
+ * validated identically and a consent revocation still excludes a row. The
+ * flag gates ONLY the `vector_cortex_outcome_appended` /
+ * `vector_cortex_dataset_record_excluded` events and the outcomes 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..VC7C.
+ */
+export const VC8A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8A");
+
 // 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

@@ -175,6 +175,7 @@ export {
   VC7A_ENABLED,
   VC7B_ENABLED,
   VC7C_ENABLED,
+  VC8A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -0,0 +1,32 @@
+/**
+ * cache/_diagnostics-fixture.ts — VC7C acceptance-test fixture helpers.
+ *
+ * Reads conformance fixtures from the v2 `cache-diagnostics/` domain and provides
+ * a flag-toggling wrapper for VC7C parity tests. Mirrors `_economics-fixture.ts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const V2 = join(here, "..", "..", "..", "conformance", "vector-cortex", "v2");
+const DIR = join(V2, "cache-diagnostics");
+
+/** Read + parse one conformance fixture by ID. */
+export function diagnosticsFixture(id: string): Record<string, unknown> {
+  const raw = readFileSync(join(DIR, `${id}.json`), "utf8");
+  return JSON.parse(raw);
+}
+
+/** Run `fn` with MEGACOMPACT_VC7C set to `value`, restoring the prior value after. */
+export function withVc7cFlag<T>(value: string, fn: () => T): T {
+  const prior = process.env.MEGACOMPACT_VC7C;
+  process.env.MEGACOMPACT_VC7C = value;
+  try {
+    return fn();
+  } finally {
+    if (prior === undefined) delete process.env.MEGACOMPACT_VC7C;
+    else process.env.MEGACOMPACT_VC7C = prior;
+  }
+}

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

@@ -0,0 +1,124 @@
+/**
+ * cache/breaker.ts — VC7C cache-serve breaker (composes VC0C's createBreaker).
+ *
+ * This file does NOT reinvent a state machine. It wraps the TRIAD breaker from
+ * `../resilience/breaker-core.js` (VC0C) — the same CLOSED_A / OPEN_B / OPEN_C /
+ * PROBE_* / MANUAL_HALT states that protect every other subsystem — and adds the
+ * ONE cache-specific decision: whether a classified miss should block a cache
+ * SERVE before it can answer from a stale or invalid identity.
+ *
+ * TRIP KIND CLASSIFICATION (per team-lead correction + TRIAD_RESILIENCE §breaker):
+ * The four cache demotion conditions map onto `BreakerTripKind` as follows:
+ *
+ *   CORRECTNESS trips (trip on the FIRST failure, no rolling window):
+ *     - profile mismatch     — the crystal was minted under a different provider
+ *                              profile; serving it would return bytes for the wrong
+ *                              model tier. This is never "recovered from" by waiting.
+ *     - range mismatch       — the crystal's covered digest differs from the
+ *                              request's; the crystal covers different spans and
+ *                              serving it would return another conversation's frozen
+ *                              bytes. (Includes digest failure / collision.)
+ *     - request mismatch     — the request digest differs; the crystal was built
+ *                              for a different request entirely.
+ *
+ *   PERFORMANCE trips (accumulated over a rolling window before opening):
+ *     - dependency advanced   — the dependency high-water moved past the crystal's
+ *                              cached position. The crystal is stale but not WRONG;
+ *                              a single advance is normal churn. Repeated advances
+ *                              across a window indicate the cache is systematically
+ *                              behind the frontier — that is a performance signal.
+ *     - generation invalidated — the M6 router generation was invalidated. A single
+ *                              invalidation is expected during a router cut; repeated
+ *                              invalidations indicate a systematic generation
+ *                              instability.
+ *
+ * The distinction matters because a CORRECTNESS trip opens the breaker IMMEDIATELY
+ * (first failure), while a PERFORMANCE trip requires BREAKER_PERF_FAILURES within
+ * BREAKER_WINDOW_MS. The VC0C breaker-core already implements this via
+ * `BreakerTripKind`; we map each miss class to its trip kind and let breaker-core
+ * handle the window/threshold logic.
+ *
+ * "PROBE OUTPUT IS NEVER SERVED" (TRIAD_RESILIENCE line 13): when the breaker is in
+ * PROBE_A or PROBE_B, the probe is a TEST serve — its output must not be returned
+ * to the caller. `decideCacheServe` enforces this: PROBE_* states always return
+ * `block: true` and the fallback mode, never serving from cache.
+ *
+ * The decision is a CORRECTNESS behavior and is NEVER flag-gated (unlike the
+ * reporter seam in `./diagnostics-emit.ts`): flag-off must be byte-identical to
+ * the predecessor. `breakerRetryDelay()` from VC0C already implements the
+ * deterministic +-10% jitter from the subsystem digest — we use it, don't re-derive.
+ *
+ * PREVENT-002/011/PI-004 honored.
+ */
+
+import { createBreaker, type ConcreteBreaker } from "../resilience/breaker-core.js";
+import type { BreakerRecord, BreakerTripKind, Mode } from "../resilience/types.js";
+import type { MissClass } from "./diagnostics-types.js";
+
+/** The cache subsystem the breaker tracks (one triad state machine). */
+export const CACHE_SUBSYSTEM = "vector-cortex-cache-serve";
+
+/** Build the cache breaker. Composes VC0C — no parallel state machine here. */
+export function createCacheBreaker(opts?: {
+  now?: () => number;
+  onEvent?: (event: Record<string, unknown>) => void;
+}): ConcreteBreaker {
+  return createBreaker({ now: opts?.now, onEvent: opts?.onEvent });
+}
+
+/**
+ * Map a miss class to its breaker trip kind. Profile, range (digest/collision),
+ * and request mismatches are CORRECTNESS trips — they trip on the FIRST failure
+ * because serving a crystal with the wrong identity is never safe, no matter how
+ * rarely it happens. Dependency advance and generation invalidation are
+ * PERFORMANCE trips — a single occurrence is normal churn; only repeated
+ * failures within a window indicate a systematic problem.
+ */
+export function tripKindForMiss(missClass: MissClass): BreakerTripKind {
+  switch (missClass) {
+    case "profile":
+    case "range":
+    case "request":
+      return "correctness";
+    case "dependency":
+    case "generation":
+      return "performance";
+    case "unknown":
+      return "performance";
+  }
+}
+
+/**
+ * Whether a classified miss must block the cache serve. Pure over the class; the
+ * ONLY thing that is allowed to demote an otherwise-healthy cache is a real
+ * disagreement between what was cached and what the request now requires.
+ * `unknown` is not auto-blocked — the triad's own performance window handles it.
+ */
+export function shouldBlockServe(missClass: MissClass): boolean {
+  return missClass !== "unknown";
+}
+
+/**
+ * Decide the triad mode to render under, given a classified miss and the live
+ * breaker. A blockable miss forces mode B (fresh render) unless the breaker is
+ * already in a deeper open state (C = all-cache bypass) — never contradicting the
+ * triad's own resilience verdict. PROBE_* states are NEVER served from cache
+ * (TRIAD_RESILIENCE line 13: "probe output is never served").
+ */
+export function decideCacheServe(
+  missClass: MissClass,
+  breaker: ConcreteBreaker,
+): { block: boolean; fallbackMode: Mode; tripKind: BreakerTripKind } {
+  const tripKind = tripKindForMiss(missClass);
+  if (!shouldBlockServe(missClass)) {
+    return { block: false, fallbackMode: breaker.modeFor(CACHE_SUBSYSTEM), tripKind };
+  }
+  const record: BreakerRecord = breaker.snapshot(CACHE_SUBSYSTEM);
+  if (record.state === "OPEN_C" || record.state === "MANUAL_HALT") {
+    return { block: true, fallbackMode: "C", tripKind };
+  }
+  if (record.state === "PROBE_A" || record.state === "PROBE_B") {
+    return { block: true, fallbackMode: record.state === "PROBE_A" ? "C" : "B", tripKind };
+  }
+  return { block: true, fallbackMode: "B", tripKind };
+}