pi-mega-compact 0.20.14 → 0.20.15

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/route-dispatch.js

@@ -20,6 +20,7 @@ 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.
 /**
  * Dispatch a request through every registered route handler.
  * Returns true if a handler claimed the request (ended the response).

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/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/migrations/request-hash-v2-ops.js

@@ -0,0 +1,143 @@
+/**
+ * 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();
+    for (const v1 of host.v1Rows()) {
+        const row = deriveRequestHashRow(host, v1);
+        const prior = byHash.get(row.hash);
+        if (prior !== undefined &&
+            prior !== identity(v1.profileId, v1.requestDigest)) {
+            return true;
+        }
+        byHash.set(row.hash, identity(v1.profileId, v1.requestDigest));
+    }
+    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);
+        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] };
+    }
+    const verify = m5Verify(host);
+    if (!verify.ok)
+        return verify;
+    if (detectCollision(host))
+        return { ok: false, codes: [M5_FAIL.REQUEST_HASH_COLLISION] };
+    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/migrations/request-hash-v2-ops.js

@@ -0,0 +1,143 @@
+/**
+ * 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();
+    for (const v1 of host.v1Rows()) {
+        const row = deriveRequestHashRow(host, v1);
+        const prior = byHash.get(row.hash);
+        if (prior !== undefined &&
+            prior !== identity(v1.profileId, v1.requestDigest)) {
+            return true;
+        }
+        byHash.set(row.hash, identity(v1.profileId, v1.requestDigest));
+    }
+    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);
+        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] };
+    }
+    const verify = m5Verify(host);
+    if (!verify.ok)
+        return verify;
+    if (detectCollision(host))
+        return { ok: false, codes: [M5_FAIL.REQUEST_HASH_COLLISION] };
+    host.switchToV2();
+    return { ok: true, codes: [] };
+}
+export function migrateRequestHashV2(host) {
+    m5Copy(host);
+    return m5Switch(host);
+}

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