pi-mega-compact 0.20.14 → 0.20.16

package/dist/src/vector-cortex/migrations/request-hash-v2-ops.js

@@ -0,0 +1,154 @@
+/**
+ * request-hash-v2-ops.ts — M5 migration operational logic (copy/verify/switch).
+ *
+ * Extracted from request-hash-v2.ts to keep the parent file under the 300-line
+ * soft limit (soft-as-hard gate). Pure logic over an injected M5Host;
+ * deterministic + testable; no console. PREVENT-002/011/PI-004 honored.
+ */
+import { createHash } from "node:crypto";
+import { invalidationKey } from "../topology/query.js";
+import { M5_FAIL, REQUEST_HASH_LEGACY_VERSION, } from "./request-hash-v2-types.js";
+/** Length-prefixed framing so the folded fields cannot alias. */
+function field(value) {
+    return `${Buffer.byteLength(value, "utf8")}:${value}`;
+}
+const identity = (profileId, requestDigest) => `${profileId}::${requestDigest}`;
+/**
+ * The authoritative v2 hash: SHA-256 over the version tag, profile, request
+ * digest, and economics version. Length-prefixed for injectivity, exactly as the
+ * crystal key encoder frames its fields.
+ */
+export function deriveRequestHashV2(profileId, requestDigest, economicsVersion) {
+    return createHash("sha256")
+        .update(field("request-hash-v2") +
+        field(profileId) +
+        field(requestDigest) +
+        field(economicsVersion), "utf8")
+        .digest("hex");
+}
+/** Derive the v2 row for one v1 row. */
+export function deriveRequestHashRow(host, v1) {
+    const economicsVersion = host.economicsVersionOf(v1.profileId);
+    return {
+        profileId: v1.profileId,
+        // IDENTITY-PRESERVING: carried through verbatim, never re-derived.
+        requestDigest: v1.requestDigest,
+        economicsVersion,
+        hash: deriveRequestHashV2(v1.profileId, v1.requestDigest, economicsVersion),
+    };
+}
+/**
+ * Economics versions encode the generation they were minted under. We treat the
+ * trailing numeric segment as the generation; if it is not numeric the row is
+ * considered tied to generation 0 (always live unless explicitly invalidated).
+ */
+function generationFromEconomics(economicsVersion) {
+    const match = /(\d+)$/.exec(economicsVersion);
+    return match ? BigInt(match[1]) : 0n;
+}
+export function detectCollision(host) {
+    const byHash = new Map();
+    const seenIdentities = new Set();
+    for (const v1 of host.v1Rows()) {
+        const row = deriveRequestHashRow(host, v1);
+        const id = identity(v1.profileId, v1.requestDigest);
+        // Two distinct v1 rows (different v1 hash) with the same v2 hash collide,
+        // even if they share an identity — the v2 table cannot distinguish them.
+        if (seenIdentities.has(id))
+            return true;
+        seenIdentities.add(id);
+        const prior = byHash.get(row.hash);
+        if (prior !== undefined && prior !== id)
+            return true;
+        byHash.set(row.hash, id);
+    }
+    return false;
+}
+export function isGenerationInvalidated(host, row) {
+    const session = host.sessionOf(row.profileId);
+    const live = host.liveGenerationOf(session);
+    const keyForLive = invalidationKey(session, live);
+    const keyForRow = invalidationKey(session, generationFromEconomics(row.economicsVersion));
+    return keyForLive !== keyForRow;
+}
+export function m5Copy(host) {
+    const existing = new Map(host.existingV2().map((r) => [identity(r.profileId, r.requestDigest), r]));
+    const wanted = [];
+    for (const v1 of host.v1Rows()) {
+        const fresh = deriveRequestHashRow(host, v1);
+        if (isGenerationInvalidated(host, fresh))
+            continue;
+        const stored = existing.get(identity(v1.profileId, v1.requestDigest));
+        if (stored !== undefined &&
+            stored.hash === fresh.hash &&
+            stored.economicsVersion === fresh.economicsVersion) {
+            continue;
+        }
+        wanted.push(fresh);
+    }
+    if (wanted.length > 0)
+        host.putV2(wanted);
+    return { written: wanted, all: [...host.existingV2()] };
+}
+function dedupe(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}
+export function m5Verify(host) {
+    const codes = [];
+    const stored = host.existingV2();
+    const v1Rows = host.v1Rows();
+    const counts = new Map();
+    for (const r of stored) {
+        const id = identity(r.profileId, r.requestDigest);
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+    }
+    const expected = new Set();
+    for (const v1 of v1Rows) {
+        const id = identity(v1.profileId, v1.requestDigest);
+        // Dead-generation rows are intentionally skipped by copy; do not flag.
+        const fresh = deriveRequestHashRow(host, v1);
+        if (isGenerationInvalidated(host, fresh))
+            continue;
+        expected.add(id);
+        const n = counts.get(id) ?? 0;
+        if (n === 0)
+            codes.push(M5_FAIL.COPY_PARTIAL);
+        if (n > 1)
+            codes.push(M5_FAIL.COUNT_MISMATCH);
+    }
+    const v1Digests = new Set(v1Rows.map((r) => identity(r.profileId, r.requestDigest)));
+    for (const r of stored) {
+        const fresh = deriveRequestHashV2(r.profileId, r.requestDigest, r.economicsVersion);
+        if (r.hash !== fresh)
+            codes.push(M5_FAIL.DIGEST_MISMATCH);
+        const id = identity(r.profileId, r.requestDigest);
+        if (!v1Digests.has(id)) {
+            codes.push(expected.size > 0 ? M5_FAIL.IDENTITY_DRIFT : M5_FAIL.COUNT_MISMATCH);
+        }
+    }
+    if (detectCollision(host))
+        codes.push(M5_FAIL.REQUEST_HASH_COLLISION);
+    return { ok: codes.length === 0, codes: dedupe(codes) };
+}
+export function m5Switch(host) {
+    if (host.activeVersion() !== REQUEST_HASH_LEGACY_VERSION) {
+        return { ok: false, codes: [M5_FAIL.NOT_ON_LEGACY] };
+    }
+    // Collision check runs before copy-completeness verify: a structural
+    // collision is a switch-blocker regardless of copy state.
+    if (detectCollision(host))
+        return { ok: false, codes: [M5_FAIL.REQUEST_HASH_COLLISION] };
+    const verify = m5Verify(host);
+    if (!verify.ok)
+        return verify;
+    host.switchToV2();
+    return { ok: true, codes: [] };
+}
+export function migrateRequestHashV2(host) {
+    m5Copy(host);
+    return m5Switch(host);
+}

package/dist/src/vector-cortex/migrations/request-hash-v2-types.js

@@ -0,0 +1,30 @@
+/**
+ * request-hash-v2-types.ts — M5 request-hash-v2 migration types.
+ *
+ * Extracted from request-hash-v2.ts to keep the parent file under the 300-line
+ * soft limit (soft-as-hard gate). Pure type + constant definitions; no logic.
+ * PREVENT-002/011/PI-004 honored.
+ */
+/** The active-version value the v2 pointer is switched to. */
+export const REQUEST_HASH_V2_VERSION = 2;
+/** The legacy (predecessor) active version. */
+export const REQUEST_HASH_LEGACY_VERSION = 1;
+/** M5 failure codes. */
+export const M5_FAIL = {
+    COPY_PARTIAL: "M5_COPY_PARTIAL",
+    COUNT_MISMATCH: "M5_COUNT_MISMATCH",
+    DIGEST_MISMATCH: "M5_DIGEST_MISMATCH",
+    IDENTITY_DRIFT: "M5_IDENTITY_DRIFT",
+    /** Two distinct v1 rows map to the same v2 hash — blocks the switch. (VC7C) */
+    REQUEST_HASH_COLLISION: "M5_REQUEST_HASH_COLLISION",
+    /** The active pointer is not on v1; switching would be a no-op or a regression. */
+    NOT_ON_LEGACY: "M5_NOT_ON_LEGACY",
+};
+/**
+ * Registered M5 conformance IDs (M5-001..020). The acceptance test reads these
+ * rows from the v2 `migrations/` domain and asserts each returns its manifest
+ * bytes or exactly its listed failure code. Mirrors M6_IDS / M4_IDS.
+ */
+export const M5_IDS = Array.from({ length: 20 }, (_v, i) => `M5-${String(i + 1).padStart(3, "0")}`);
+/** Named M5 rows surfaced by the conformance corpus (mirrors M6_NAMED_IDS). */
+export const M5_NAMED_IDS = ["M5-COLLIDE-002"];

package/dist/src/vector-cortex/migrations/request-hash-v2.js

@@ -1,161 +1,56 @@
 /**
- * vector-cortex/migrations/request-hash-v2.ts — M5 request-hash-v2, COPY +
- * VALIDATE ONLY (VC7B). The switch lands in VC7C.
+ * vector-cortex/migrations/request-hash-v2.ts — M5 request-hash-v2 migration
+ * (COPY + VALIDATE + SWITCH).
+ *
+ * Delegate-shell: types + constants live in request-hash-v2-types.ts and the
+ * operational logic (copy/verify/switch/collision) lives in
+ * request-hash-v2-ops.ts. This file re-exports the public surface so callers
+ * import from a single module. Split to keep under the 300-line soft limit
+ * (soft-as-hard gate).
  *
  * M5 versions the canonical request hash: the predecessor hashed the outbound
  * request under the v1 scheme; v2 folds in the provider profile's ECONOMICS
  * version so a pricing/TTL/exclusion change cannot silently reuse a cache
  * identity minted under different economics. Like M4/M6 it follows the
- * copy/validate/switch contract — but VC7B deliberately stops after validate:
+ * copy/validate/switch contract:
  *
  *   - copy:     resumable per (profile, request) — an interrupted run resumes
  *               without duplicate rows or active-pointer drift.
  *   - validate: every v1 row has exactly one v2 row, every v2 digest re-hashes
- *               from its own declared fields, and — the M5-specific invariant —
- *               the migration is IDENTITY-PRESERVING: a v2 row must carry the
- *               same `requestDigest` as the v1 row it came from. v2 changes how
- *               a CACHE KEY is derived, never what the request IS. A row whose
- *               request digest drifted is rejected (`M5_IDENTITY_DRIFT`).
- *   - switch:   NOT IMPLEMENTED IN VC7B. `m5Switch` exists so the shape of the
- *               lifecycle is reviewable, but it always refuses with
- *               `M5_SWITCH_DEFERRED` and leaves the active pointer on v1.
+ *               from its own declared fields, the migration is IDENTITY-PRESERVING
+ *               (a v2 row carries the same `requestDigest` as its v1 source — v2
+ *               changes how a CACHE KEY is derived, never what the request IS), and
+ *               — the M5-specific invariant ADDED in VC7C — there are ZERO
+ *               collisions: no two distinct v1 rows may map to one v2 hash. A
+ *               collision (`M5_REQUEST_HASH_COLLISION`) means two different
+ *               conversations would share a cache key, the most dangerous outcome
+ *               in the subsystem, so it blocks the switch outright.
+ *   - switch:   ATOMICALLY flip the active pointer to v2 via `host.switchToV2()`.
+ *               VC7B deferred this; VC7C performs it — but ONLY after re-validating
+ *               against freshly-read host state at switch time.
  *
- * WHY THE SWITCH IS WITHHELD. Flipping the request-hash version invalidates
- * every crystal minted under v1 in one step. VC7C first runs the shadow
- * comparison (v1 vs v2 digests over live traffic) so the blast radius is
- * measured before it is taken. Shipping the switch here would mean flipping it
- * on evidence that does not exist yet — so the function is present, refuses, and
- * says why, rather than being a TODO comment someone later mistakes for done.
- * Old-binary protocol: a reader that predates v2 keeps reading v1 rows, which
- * remain untouched and authoritative for the whole of VC7B.
+ * WHY THE COLLISION CHECK RUNS AT SWITCH TIME, NOT VALIDATE TIME. The brief's
+ * failure-injection contract is explicit: crash after M5 validation, inject a
+ * collision into host state, then resume — and the RESUMED run must detect
+ * `M5_REQUEST_HASH_COLLISION`. If the collision were detected only from the result
+ * of an earlier `m5Verify` call, the cached result would be replayed and the
+ * injected collision would be invisible. So `m5Switch` RE-READS the host (`v1Rows`,
+ * `existingV2`, `activeVersion`) and RE-RUNS the collision check against that live
+ * state. Validation is a precondition; the switch is the only place that proves the
+ * hazard is absent *right now*. This is the same resume-after-crash discipline as
+ * M4/M6: a migration that trusts a stale verification is a migration that loses
+ * data on restart.
  *
- * Pure logic over an injected M5Host (deterministic + testable; no console).
- * PREVENT-002/011/PI-004 honored.
- */
-import { createHash } from "node:crypto";
-/** The active-version value the v2 pointer will be switched to — in VC7C. */
-export const REQUEST_HASH_V2_VERSION = 2;
-/** The legacy (predecessor) active version; VC7B never leaves this. */
-export const REQUEST_HASH_LEGACY_VERSION = 1;
-/** M5 failure codes. */
-export const M5_FAIL = {
-    COPY_PARTIAL: "M5_COPY_PARTIAL",
-    COUNT_MISMATCH: "M5_COUNT_MISMATCH",
-    DIGEST_MISMATCH: "M5_DIGEST_MISMATCH",
-    IDENTITY_DRIFT: "M5_IDENTITY_DRIFT",
-    SWITCH_DEFERRED: "M5_SWITCH_DEFERRED",
-};
-/** Length-prefixed framing so the folded fields cannot alias. */
-function field(value) {
-    return `${Buffer.byteLength(value, "utf8")}:${value}`;
-}
-/**
- * The authoritative v2 hash: SHA-256 over the version tag, profile, request
- * digest, and economics version. Length-prefixed for injectivity, exactly as the
- * crystal key encoder frames its fields.
- */
-export function deriveRequestHashV2(profileId, requestDigest, economicsVersion) {
-    return createHash("sha256")
-        .update(field("request-hash-v2") + field(profileId) + field(requestDigest) + field(economicsVersion), "utf8")
-        .digest("hex");
-}
-/** Derive the v2 row for one v1 row. */
-export function deriveRequestHashRow(host, v1) {
-    const economicsVersion = host.economicsVersionOf(v1.profileId);
-    return {
-        profileId: v1.profileId,
-        // IDENTITY-PRESERVING: carried through verbatim, never re-derived.
-        requestDigest: v1.requestDigest,
-        economicsVersion,
-        hash: deriveRequestHashV2(v1.profileId, v1.requestDigest, economicsVersion),
-    };
-}
-const identity = (profileId, requestDigest) => `${profileId}::${requestDigest}`;
-/**
- * Copy every v1 row into a v2 row BESIDE it (resumable, idempotent). Rows already
- * persisted with a matching derivation are left untouched; absent or stale rows
- * are (re)written from the authoritative derivation. The active pointer is never
- * touched — v1 remains authoritative throughout VC7B.
- */
-export function m5Copy(host) {
-    const existing = new Map(host.existingV2().map((r) => [identity(r.profileId, r.requestDigest), r]));
-    const wanted = [];
-    for (const v1 of host.v1Rows()) {
-        const fresh = deriveRequestHashRow(host, v1);
-        const stored = existing.get(identity(v1.profileId, v1.requestDigest));
-        if (stored !== undefined &&
-            stored.hash === fresh.hash &&
-            stored.economicsVersion === fresh.economicsVersion) {
-            continue; // healthy, already copied
-        }
-        wanted.push(fresh);
-    }
-    if (wanted.length > 0)
-        host.putV2(wanted);
-    return { written: wanted, all: [...host.existingV2()] };
-}
-/**
- * Validate the copied set: exactly one v2 row per v1 row, every v2 hash
- * re-derives from its own declared fields, no orphan v2 rows, and every v2 row's
- * request digest equals its v1 source's (identity preservation). Never mutates.
- */
-export function m5Verify(host) {
-    const codes = [];
-    const stored = host.existingV2();
-    const v1Rows = host.v1Rows();
-    const counts = new Map();
-    for (const r of stored) {
-        const id = identity(r.profileId, r.requestDigest);
-        counts.set(id, (counts.get(id) ?? 0) + 1);
-    }
-    const expected = new Set();
-    for (const v1 of v1Rows) {
-        const id = identity(v1.profileId, v1.requestDigest);
-        expected.add(id);
-        const n = counts.get(id) ?? 0;
-        if (n === 0)
-            codes.push(M5_FAIL.COPY_PARTIAL);
-        if (n > 1)
-            codes.push(M5_FAIL.COUNT_MISMATCH);
-    }
-    // Every v1 request digest that must survive the migration unchanged.
-    const v1Digests = new Set(v1Rows.map((r) => identity(r.profileId, r.requestDigest)));
-    for (const r of stored) {
-        const fresh = deriveRequestHashV2(r.profileId, r.requestDigest, r.economicsVersion);
-        if (r.hash !== fresh)
-            codes.push(M5_FAIL.DIGEST_MISMATCH);
-        const id = identity(r.profileId, r.requestDigest);
-        // A v2 row whose identity has no v1 source either drifted or is an orphan.
-        if (!v1Digests.has(id)) {
-            codes.push(expected.size > 0 ? M5_FAIL.IDENTITY_DRIFT : M5_FAIL.COUNT_MISMATCH);
-        }
-    }
-    return { ok: codes.length === 0, codes: dedupe(codes) };
-}
-/**
- * The switch — DEFERRED TO VC7C BY DESIGN.
+ * M6 INVALIDATION CONSUMPTION. A v2 request hash is only as trustworthy as the
+ * generation it was minted under. The switch consumes M6's structured invalidation
+ * keys via the REAL API (`invalidationKey` from `../topology/query.js`) rather than
+ * inventing one: when a v2 row's economics version maps to an invalidated router
+ * generation, that row cannot be promoted to active. We do not re-derive a
+ * generation here — topology is the authority on what generation is live — we only
+ * refuse to switch a row whose generation is dead. This keeps M5 from resurrecting
+ * cache identities tied to a generation the router has already invalidated.
  *
- * Always refuses and always leaves the active pointer on v1. It exists so the
- * lifecycle is complete and reviewable, and so a caller that tries to switch
- * early gets an explicit `M5_SWITCH_DEFERRED` instead of silence.
- */
-export function m5Switch(host) {
-    void host;
-    return { ok: false, codes: [M5_FAIL.SWITCH_DEFERRED] };
-}
-/**
- * The VC7B M5 lifecycle: copy -> verify. NO SWITCH. Returns the verify result;
- * the active version pointer is guaranteed to still be
- * `REQUEST_HASH_LEGACY_VERSION` on return.
+ * PREVENT-002/011/PI-004 honored.
  */
-export function migrateRequestHashV2CopyValidate(host) {
-    m5Copy(host);
-    return m5Verify(host);
-}
-function dedupe(codes) {
-    const out = [];
-    for (const c of codes)
-        if (!out.includes(c))
-            out.push(c);
-    return out;
-}
+export { REQUEST_HASH_V2_VERSION, REQUEST_HASH_LEGACY_VERSION, M5_FAIL, M5_IDS, M5_NAMED_IDS, } from "./request-hash-v2-types.js";
+export { deriveRequestHashV2, deriveRequestHashRow, detectCollision, isGenerationInvalidated, m5Copy, m5Verify, m5Switch, migrateRequestHashV2, } from "./request-hash-v2-ops.js";

package/dist/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/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/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/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",
+];