pi-mega-compact 0.20.14 → 0.20.16

package/dist/config/vector-cortex.js

@@ -191,6 +191,26 @@ export const VC7A_ENABLED = () => sprintFlag("MEGACOMPACT_VC7A");
  * EXCLUDED_SETTINGS), mirroring VC4A..VC7A.
  */
 export const VC7B_ENABLED = () => 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 = () => 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 { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

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

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+export {};

package/dist/extensions/dashboard-server/route-dispatch.js

@@ -20,6 +20,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.
  * Returns true if a handler claimed the request (ended the response).
@@ -117,5 +121,7 @@ export function dispatchRoutes(req, res, ctx) {
         return true;
     if (handleVectorCortexEconomics(req, res, ctx))
         return true;
+    if (handleVectorCortexDiagnostics(req, res, ctx))
+        return true;
     return false;
 }

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

@@ -44,5 +44,6 @@ export const VECTOR_CORTEX_SETTINGS = {
         boolDirect("MEGACOMPACT_VC6C", "VC6C Self-Healing Derived State", "Self-healing derived-state controller: detects gaps between each derived subsystem's high-water mark and the durable authority high-water, then rebuilds derived state by copy -> root-digest verification -> atomic pointer switch, so a partially rebuilt subsystem is never made visible. A targeted single-subsystem rebuild is mode A; an ambiguous gap escalates to a full deterministic rebuild (mode B); if both rebuild paths fail the derived state is disabled rather than served stale (mode C). Rebuilds are rate-limited to one per subsystem per 5 minutes with deterministic exponential backoff, so a persistently failing subsystem cannot spin. OFF = byte-identical predecessor (VC6B); no controller runs, so the dashboard reports mode C.", true),
         boolDirect("MEGACOMPACT_VC7A", "VC7A Frozen Range Crystals", "Frozen range crystals: caches a rendered prompt under an IMMUTABLE key built from the source ranges it covers, the digest of those covered bytes, the validated durable dependency high-water, and the renderer + provider profile — and deliberately NOT the global ledger frontier, so an unrelated append leaves the key unchanged instead of invalidating every crystal on every turn. Any covered-byte, dependency, renderer, or profile change invalidates 100%. Ranges are sorted by source start and overlapping ranges are rejected (CRY_RANGE_OVERLAP) rather than merged. The store is content-addressed and write-once: identical bytes re-written are idempotent, but a same-key/different-bytes write returns CRY_KEY_COLLISION and never overwrites, surfacing renderer non-determinism instead of hiding it. A store hit is mode A, a miss/collision forces a fresh deterministic render (mode B), and an unavailable store bypasses the cache entirely (mode C). OFF = byte-identical predecessor (VC6C); the crystal/store arithmetic still runs, only the reporter + dashboard seam is suppressed.", true),
         boolDirect("MEGACOMPACT_VC7B", "VC7B Provider Cache Economics", "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/dist/extensions/dashboard-server/routes-vector-cortex-diagnostics.js

@@ -0,0 +1,68 @@
+/**
+ * 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 { VC7C_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.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, res, _ctx) {
+    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 = enabled ? "A" : "C";
+    const body = {
+        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/dist/src/config/vector-cortex.js

@@ -191,6 +191,26 @@ export const VC7A_ENABLED = () => sprintFlag("MEGACOMPACT_VC7A");
  * EXCLUDED_SETTINGS), mirroring VC4A..VC7A.
  */
 export const VC7B_ENABLED = () => 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 = () => 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 { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/vector-cortex/cache/_diagnostics-fixture.js

@@ -0,0 +1,31 @@
+/**
+ * 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) {
+    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(value, fn) {
+    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/dist/src/vector-cortex/cache/breaker.js

@@ -0,0 +1,110 @@
+/**
+ * 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 } from "../resilience/breaker-core.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) {
+    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) {
+    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) {
+    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, breaker) {
+    const tripKind = tripKindForMiss(missClass);
+    if (!shouldBlockServe(missClass)) {
+        return { block: false, fallbackMode: breaker.modeFor(CACHE_SUBSYSTEM), tripKind };
+    }
+    const record = 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 };
+}

package/dist/src/vector-cortex/cache/diagnostics-emit.js

@@ -0,0 +1,64 @@
+/**
+ * cache/diagnostics-emit.ts — VC7C reporter seam (FLAG-GATED).
+ *
+ * Mirrors `./economics-emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit`, and the two event names the sprint spec requires verbatim:
+ *   - `vector_cortex_cache_miss_classified` — a miss was classified.
+ *   - `vector_cortex_cache_serve_blocked` — a cache serve was blocked by a
+ *     breaker condition before it could answer from a stale/invalid identity.
+ *
+ * FLAG SEMANTICS. `classifyMiss` (`./diagnostics.ts`) is PURE and runs REGARDLESS
+ * of `MEGACOMPACT_VC7C`. The flag gates ONLY this reporting + dashboard seam:
+ * with the flag off the classifier still returns the SAME class, the breaker
+ * still blocks the SAME serve — we just do not announce them under the VC7C
+ * event namespace, and the dashboard reports `enabled:false` + mode C. That is
+ * what makes flag-off byte-identical to the predecessor (VC7B): the arithmetic
+ * and the correctness decision are never skipped, only the emission. (NOTE the
+ * asymmetry vs VC7B: VC7B gated pure telemetry; here the blocked-serve DECISION
+ * is a correctness behavior and is never flag-gated — only its announcement is.)
+ *
+ * PAYLOAD DISCIPLINE. These events carry the `missClass` and the payload-free
+ * `evidence` booleans/counts (see `./diagnostics-types.ts`) — never a session
+ * id, never a covered range, never a request or covered digest. The classifier
+ * is payload-free by construction, so there is no slot to leak into
+ * (SECURITY_PRIVACY — the exact ledger is not diagnostic data).
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+import { VC7C_ENABLED } from "../../config/vector-cortex.js";
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit, fn) {
+    if (emit === undefined)
+        return;
+    try {
+        fn(emit);
+    }
+    catch {
+        // Non-fatal: a reporting failure must never break the agent loop.
+    }
+}
+/** Report a classified miss. Gated only by the reporter/dashboard flag. */
+export function reportCacheMissClassified(emit, diagnostic) {
+    if (!VC7C_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_cache_miss_classified", {
+        ts: undefined,
+        event: "vector_cortex_cache_miss_classified",
+        schema: diagnostic.schema,
+        missClass: diagnostic.missClass,
+        evidence: diagnostic.evidence,
+    }));
+}
+/** Report a cache serve that was blocked before answering. Gated by the flag. */
+export function reportCacheServeBlocked(emit, blocked) {
+    if (!VC7C_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_cache_serve_blocked", {
+        ts: undefined,
+        event: "vector_cortex_cache_serve_blocked",
+        missClass: blocked.missClass,
+        triadState: blocked.triadState,
+        reason: blocked.reason,
+    }));
+}

package/dist/src/vector-cortex/cache/diagnostics-types.js

@@ -0,0 +1,15 @@
+/**
+ * cache/diagnostics-types.ts — VC7C cache miss-diagnostic contract types.
+ *
+ * Single source of truth for the miss-classification vocabulary. Kept separate
+ * from the arithmetic (`diagnostics.ts`) so the dashboard client, the emit layer
+ * and the acceptance test all import ONE definition. No logic here; pure types
+ * + the registered ID lists. PREVENT-011 honored (no `any`).
+ */
+/** Registered conformance IDs (CACHE-016..030). */
+export const CACHE_DIAGNOSTIC_IDS = Array.from({ length: 15 }, (_v, i) => `CACHE-${String(i + 16).padStart(3, "0")}`);
+/** Named headlines surfaced by the conformance corpus. */
+export const CACHE_DIAGNOSTIC_NAMED_IDS = [
+    "CACHE-MISS-001",
+    "CACHE-STALE-003",
+];

package/dist/src/vector-cortex/cache/diagnostics.js

@@ -0,0 +1,97 @@
+/**
+ * cache/diagnostics.ts — VC7C pure miss classification (flag-independent).
+ *
+ * The classifier is PURE arithmetic: given a `MissObservation` it returns
+ * exactly ONE `MissClass` and the payload-free `MissEvidence`. It is NOT gated by
+ * MEGACOMPACT_VC7C — flag-off must be byte-identical to the predecessor, so the
+ * SAME class a user sees today, they see tomorrow. The flag gates only the
+ * reporter/dashboard seam (see `diagnostics-emit.ts`).
+ *
+ * Exclusive ranking: profile -> range -> dependency -> request -> generation ->
+ * unknown. First match wins; the ranking itself is the contract and is pinned by
+ * CACHE-016..030. "Absence is not a mismatch": a cold key (null cached fields)
+ * classifies `unknown`, never `profile`. PREVENT-002/011/PI-004 honored.
+ */
+/** A cached field is present iff it is non-null. */
+function isPresent(value) {
+    return value !== null;
+}
+/**
+ * Clamp the dependency delta to a non-negative, safe-integer count. A request
+ * BEHIND the cached frontier is not an advance (delta 0); a huge advance
+ * saturates rather than losing precision.
+ */
+function advanceDelta(request, cached) {
+    if (cached === null)
+        return { advanced: false, delta: 0 };
+    if (request <= cached)
+        return { advanced: false, delta: 0 };
+    const diff = request - cached;
+    if (diff > BigInt(Number.MAX_SAFE_INTEGER)) {
+        return { advanced: true, delta: Number.MAX_SAFE_INTEGER };
+    }
+    return { advanced: true, delta: Number(diff) };
+}
+/** Collect the payload-free evidence from one observation. */
+export function collectEvidence(o) {
+    const profileMismatch = isPresent(o.cachedProfileId) &&
+        isPresent(o.cachedProfileVersion) &&
+        (o.cachedProfileId !== o.requestProfileId ||
+            o.cachedProfileVersion !== o.requestProfileVersion);
+    const rangeMismatch = (isPresent(o.cachedCoveredDigest) &&
+        o.cachedCoveredDigest !== o.requestCoveredDigest) ||
+        (isPresent(o.cachedRangeCount) &&
+            o.cachedRangeCount !== o.requestedRangeCount);
+    const dep = advanceDelta(o.requestDependencyHighWater, o.cachedDependencyHighWater);
+    const requestMismatch = isPresent(o.cachedRequestDigest) &&
+        o.cachedRequestDigest !== o.requestDigest;
+    const absent = !isPresent(o.cachedProfileId) &&
+        !isPresent(o.cachedCoveredDigest) &&
+        !isPresent(o.cachedRequestDigest) &&
+        !isPresent(o.cachedDependencyHighWater);
+    return {
+        profileMismatch,
+        rangeMismatch,
+        dependencyAdvanced: dep.advanced,
+        requestMismatch,
+        generationInvalidated: o.generationInvalidated,
+        requestedRangeCount: o.requestedRangeCount,
+        // Nothing was cached when the observation is absent, so a stale
+        // cachedRangeCount on the observation is not real — report 0.
+        cachedRangeCount: o.cachedRangeCount === null || absent ? 0 : o.cachedRangeCount,
+        dependencyDelta: dep.delta,
+        absent,
+    };
+}
+/** The exclusive ranking: first true cause wins. */
+export function classFor(e) {
+    if (e.profileMismatch)
+        return "profile";
+    if (e.rangeMismatch)
+        return "range";
+    if (e.dependencyAdvanced)
+        return "dependency";
+    if (e.requestMismatch)
+        return "request";
+    if (e.generationInvalidated)
+        return "generation";
+    return "unknown";
+}
+/** Classify one observation: exactly one deterministic class. */
+export function classifyMiss(o) {
+    const evidence = collectEvidence(o);
+    return {
+        schema: "cache-diagnostic-v1",
+        missClass: classFor(evidence),
+        evidence,
+    };
+}
+/**
+ * A miss a caller can self-heal on the next turn (re-fetch under a fresh
+ * profile / a new generation), so a triad recovery path may treat it as
+ * transient. Only profile + generation qualify; the rest are hard mismatches.
+ * An `unknown` miss is NEVER transient.
+ */
+export function isTransientMiss(d) {
+    return d.missClass === "profile" || d.missClass === "generation";
+}