pi-mega-compact 0.20.13 → 0.20.15

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, 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/_economics-fixture.js

@@ -0,0 +1,41 @@
+/**
+ * cache/_economics-fixture.ts — conformance fixture I/O for VC7B economics rows.
+ *
+ * Sibling of `./_crystal-fixture.ts`, same job for a different corpus: turn
+ * canonical JSON back into the REAL production types the economics / compiler /
+ * experiments modules consume. Fixtures cannot express bigints, so token counts
+ * stored as numbers are converted here — if that conversion were lossy the
+ * computed digests would diverge and the acceptance rows would fail loudly.
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE
+ * `ProviderEconomicsV1` / `CacheUsageV1` / `CacheExperimentV1` and are fed
+ * verbatim into `validateProfileEconomics`, `computeEconomics`, `compileCrystalBoundaries`,
+ * and `assignExperiment`.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import { V2, readManifest } from "../heal/_acceptance-fixture.js";
+/** Read one registered cache-economics fixture (asserting it IS registered). */
+export function economicsFixture(id) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith("cache-economics/"));
+    assert.ok(row, `fixture ${id} registered under cache-economics/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+/** Flag-pinned wrapper: VC7B gated by MEGACOMPACT_VC7B (defaults ON). */
+export function withVc7bFlag(value, fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC7B;
+        process.env.MEGACOMPACT_VC7B = value;
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC7B;
+            else
+                process.env.MEGACOMPACT_VC7B = saved;
+        }
+    };
+}

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

@@ -0,0 +1,201 @@
+/**
+ * vector-cortex/cache/compiler.ts — VC7B provider-safe crystal boundary compiler.
+ *
+ * A provider caches a PREFIX of the request. So where you cut the prompt into
+ * cacheable segments determines whether anything is reusable at all: cut too
+ * finely and every segment falls under the provider's `minPrefix` and nothing is
+ * cacheable; cut in the wrong place and a segment that changes every turn sits
+ * in front of one that never changes, invalidating everything behind it. This
+ * file turns validated source ranges plus a profile's limits into boundaries
+ * that the provider can actually cache.
+ *
+ * THE ONE INVARIANT THAT OUTRANKS EVERYTHING: THE COMPILER NEVER CHANGES
+ * REQUEST IDENTITY. It selects where boundaries FALL; it never reorders, never
+ * merges across a session, never drops a range, never rewrites bytes. The
+ * concatenation of the compiled boundaries covers exactly the same ranges, in
+ * exactly the same canonical order, as the input — so the VC5B canonical request
+ * digest and the VC7A crystal key are byte-identical before and after
+ * compilation. `boundariesPreserveIdentity()` states this as an executable
+ * check, and the acceptance suite runs it on every compiled row. If compilation
+ * could alter identity it would be a cache-poisoning engine rather than an
+ * optimizer: two different conversations could compile to one cache key.
+ *
+ * WHY MERGE FORWARD, AND ONLY WITHIN A SESSION. Ranges below `minPrefix` are not
+ * independently cacheable, so the compiler merges each undersized range into the
+ * one that FOLLOWS it in canonical order — forward, so the merged segment keeps
+ * the earlier range's start and the prefix relationship is preserved. Merging is
+ * confined to a single session because ranges from different sessions cover
+ * disjoint byte streams; a cross-session segment would claim a contiguity that
+ * does not exist. A trailing undersized run with nothing to merge into is
+ * emitted as its own boundary marked `cacheable: false` — reported honestly as
+ * uncacheable rather than padded, dropped, or silently attached backwards.
+ *
+ * BOUNDED. `maxSegments` caps the output so a caller-shaped range list cannot be
+ * turned into an unbounded segmentation (`COMP_SEGMENT_LIMIT`).
+ *
+ * PURE. No clock, no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011). Runs identically with `MEGACOMPACT_VC7B` on or off — the flag
+ * gates only the reporter/dashboard seam in `./economics-emit.ts`.
+ */
+import { createHash } from "node:crypto";
+import { compareSpans, sortSpans, validateRanges } from "./crystal.js";
+/** Conventional default limits (4 bytes/token is the usual English estimate). */
+export const DEFAULT_COMPILER_LIMITS = {
+    minPrefix: 1024,
+    maxSegments: 64,
+    bytesPerToken: 4,
+};
+/** Covered bytes of one range. */
+function spanBytes(s) {
+    return s.endByte - s.startByte;
+}
+/**
+ * Byte→token estimate. Deliberately a floor: under-estimating tokens can only
+ * make the compiler MORE conservative about calling a segment cacheable, which
+ * fails safe (a wrongly-cacheable segment would be priced as a hit it never got).
+ */
+export function tokensForBytes(bytes, bytesPerToken) {
+    return Math.floor(bytes / bytesPerToken);
+}
+/** `sha256:` digest over a segment's ranges — length-prefixed, so injective. */
+function boundaryDigest(ranges) {
+    const h = createHash("sha256");
+    for (const s of ranges) {
+        const parts = [
+            s.sessionId,
+            s.startSeq.toString(),
+            s.endSeq.toString(),
+            String(s.startByte),
+            String(s.endByte),
+            s.digest,
+        ];
+        for (const p of parts)
+            h.update(`${Buffer.byteLength(p, "utf8")}:${p}`, "utf8");
+    }
+    return `sha256:${h.digest("hex")}`;
+}
+/** Build one boundary from a contiguous same-session run of ranges. */
+function makeBoundary(ranges, limits) {
+    const byteCount = ranges.reduce((n, s) => n + spanBytes(s), 0);
+    const tokenCount = tokensForBytes(byteCount, limits.bytesPerToken);
+    const first = ranges[0];
+    return {
+        schema: "crystal-boundary-v1",
+        sessionId: first === undefined ? "" : first.sessionId,
+        ranges,
+        byteCount,
+        tokenCount,
+        cacheable: tokenCount >= limits.minPrefix,
+        digest: boundaryDigest(ranges),
+    };
+}
+function validLimits(l) {
+    return (Number.isSafeInteger(l.minPrefix) &&
+        l.minPrefix >= 0 &&
+        Number.isSafeInteger(l.maxSegments) &&
+        l.maxSegments > 0 &&
+        Number.isSafeInteger(l.bytesPerToken) &&
+        l.bytesPerToken >= 1);
+}
+/**
+ * Compile validated ranges into provider-safe cache boundaries.
+ *
+ * Ranges are first put in canonical order (the SAME `sortSpans` order the VC7A
+ * key encoder uses — sharing the comparator is what keeps the two subsystems
+ * from disagreeing about what "canonical" means). They are then grouped by
+ * session, and within each session an undersized run is merged FORWARD until it
+ * meets `minPrefix`.
+ *
+ * Identity is verified before returning: the flattened output must equal the
+ * canonical input exactly. That check should never fire — it is a guard against
+ * a future edit to the merge loop quietly reordering or dropping a range.
+ */
+export function compileCrystalBoundaries(ranges, limits = DEFAULT_COMPILER_LIMITS) {
+    if (!validLimits(limits))
+        return { ok: false, codes: ["COMP_LIMIT_INVALID"] };
+    // Reuse VC7A's validator verbatim: the compiler must never accept a range set
+    // the crystal key would reject, or the two would disagree about what is legal.
+    const rangeCodes = validateRanges(ranges);
+    if (rangeCodes.length > 0)
+        return { ok: false, codes: ["COMP_RANGE_INVALID"] };
+    const sorted = sortSpans(ranges);
+    const boundaries = [];
+    let run = [];
+    const flushRun = () => {
+        if (run.length > 0) {
+            boundaries.push(makeBoundary(run, limits));
+            run = [];
+        }
+    };
+    for (const span of sorted) {
+        const head = run[0];
+        // A session change always closes the run: a boundary never spans sessions,
+        // because two sessions' byte streams are not contiguous with each other.
+        if (head !== undefined && head.sessionId !== span.sessionId)
+            flushRun();
+        run.push(span);
+        const bytes = run.reduce((n, s) => n + spanBytes(s), 0);
+        // Close as soon as the run is independently cacheable; anything smaller keeps
+        // absorbing the next range (merge-forward).
+        if (tokensForBytes(bytes, limits.bytesPerToken) >= limits.minPrefix)
+            flushRun();
+    }
+    // A trailing undersized run has nothing left to merge into: emit it honestly
+    // as a non-cacheable boundary rather than padding or dropping it.
+    flushRun();
+    if (boundaries.length > limits.maxSegments) {
+        return { ok: false, codes: ["COMP_SEGMENT_LIMIT"] };
+    }
+    if (!boundariesPreserveIdentity(sorted, boundaries)) {
+        return { ok: false, codes: ["COMP_IDENTITY_DRIFT"] };
+    }
+    let cacheableCount = 0;
+    let cacheableTokens = 0;
+    for (const b of boundaries) {
+        if (b.cacheable) {
+            cacheableCount += 1;
+            cacheableTokens += b.tokenCount;
+        }
+    }
+    return { ok: true, boundaries, cacheableCount, cacheableTokens };
+}
+/**
+ * The executable form of the sprint's headline invariant: flattening the
+ * compiled boundaries must reproduce the canonical input ranges EXACTLY — same
+ * ranges, same order, same pinned digests.
+ *
+ * Comparison is field-by-field on identity (session, seq bounds, byte bounds,
+ * digest), never by count or by digest alone: a compiler bug that swapped two
+ * equal-length ranges would keep the count and the byte total identical while
+ * changing what the request means.
+ */
+export function boundariesPreserveIdentity(input, boundaries) {
+    const flat = [];
+    for (const b of boundaries)
+        flat.push(...b.ranges);
+    const canonical = sortSpans(input);
+    if (flat.length !== canonical.length)
+        return false;
+    for (let i = 0; i < flat.length; i += 1) {
+        const a = flat[i];
+        const b = canonical[i];
+        if (a === undefined || b === undefined)
+            return false;
+        if (compareSpans(a, b) !== 0)
+            return false;
+        // compareSpans intentionally ignores the pinned digest (it orders by source
+        // position). Identity includes the covered bytes, so check it explicitly.
+        if (a.digest !== b.digest)
+            return false;
+    }
+    return true;
+}
+/**
+ * Compile the ranges of an existing crystal key. Returns the boundaries plus the
+ * UNCHANGED key: compilation is an optimization of how the render is segmented,
+ * never a re-keying. Returning the same key object makes that explicit at the
+ * call site — a caller cannot accidentally pick up a "compiled key" that differs.
+ */
+export function compileForKey(key, limits = DEFAULT_COMPILER_LIMITS) {
+    return { key, compiled: compileCrystalBoundaries(key.sourceRanges, limits) };
+}

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

@@ -0,0 +1,85 @@
+/**
+ * vector-cortex/cache/economics-emit.ts — VC7B event reporter seam.
+ *
+ * Mirrors `./crystal-emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit` (unit tests pass `undefined` and stay pure), and the two event
+ * names the sprint spec requires verbatim:
+ *   - `vector_cortex_cache_experiment_assigned` — a session entered an arm.
+ *   - `vector_cortex_cache_economics_estimated` — net savings were computed.
+ *
+ * FLAG SEMANTICS. `computeEconomics`, `compileCrystalBoundaries` and
+ * `assignExperiment` are PURE and run REGARDLESS of `MEGACOMPACT_VC7B`. The flag
+ * gates ONLY this reporting + dashboard seam: with the flag off a session still
+ * hashes to the SAME arm, the compiler still produces the SAME boundaries, and
+ * the same net savings are still computed — we just do not announce them under
+ * the VC7B event namespace, and the dashboard reports `enabled:false` + mode C.
+ * That is what makes flag-off byte-identical to VC7A: the arithmetic is never
+ * skipped, only the emission.
+ *
+ * PAYLOAD DISCIPLINE. These events carry the ARM, the BUCKET, integer money
+ * AGGREGATES, and the evidence label — never a session id, never covered ranges,
+ * never frozen bytes, never a request or covered digest. A session id here would
+ * re-identify a user's conversation in a log file, and the bucket already carries
+ * everything needed to audit the split (SECURITY_PRIVACY — the exact ledger is
+ * not diagnostic data). The `evidence` label travels WITH every economics event
+ * so a downstream aggregator can never mistake a shadow estimate for a measured,
+ * randomized result.
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+import { VC7B_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.
+    }
+}
+/** The event names VC7B emits, exported for the dashboard seam and tests. */
+export const ECONOMICS_EVENT_NAMES = [
+    "vector_cortex_cache_experiment_assigned",
+    "vector_cortex_cache_economics_estimated",
+];
+/**
+ * Report a session's experiment assignment.
+ *
+ * Arm + bucket + source only. The bucket is sufficient to audit that the split
+ * is being honored; the SESSION ID is deliberately absent so the event log
+ * cannot be used to reconstruct who was in which arm.
+ */
+export function reportCacheExperimentAssigned(emit, payload) {
+    if (!VC7B_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_cache_experiment_assigned", {
+        ts: undefined,
+        event: "vector_cortex_cache_experiment_assigned",
+        experimentId: payload.experimentId,
+        arm: payload.arm,
+        bucket: payload.bucket,
+        source: payload.source,
+    }));
+}
+/**
+ * Report computed cache economics.
+ *
+ * Integer micro-unit aggregates plus the evidence label. `netSavings` may be
+ * NEGATIVE and is reported as such — a cache that lost money is the outcome this
+ * telemetry exists to surface, so it is never clamped on the way out.
+ */
+export function reportCacheEconomicsEstimated(emit, payload) {
+    if (!VC7B_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_cache_economics_estimated", {
+        ts: undefined,
+        event: "vector_cortex_cache_economics_estimated",
+        profileId: payload.profileId,
+        netSavings: payload.netSavings,
+        tokenSavings: payload.tokenSavings,
+        evidence: payload.evidence,
+    }));
+}

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

@@ -0,0 +1,56 @@
+/**
+ * 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:
+ *
+ *   - 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, 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 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.
+ *
+ * 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.
+ *
+ * PREVENT-002/011/PI-004 honored.
+ */
+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/src/vector-cortex/provider/economics-ids.js

@@ -0,0 +1,29 @@
+/**
+ * vector-cortex/provider/economics-ids.ts — VC7B conformance ID registrations.
+ *
+ * Extracted from economics.ts to keep that file under the 300-line soft limit
+ * (soft-as-hard gate). The ID ranges and named rows are pure data — splitting
+ * them out mirrors how vector-cortex-breakers.ts was extracted from
+ * vector-cortex.ts. economics.ts re-exports them so no consumer import path
+ * changes.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * Registered VC7B cache-economics conformance ID range (CACHE-001..015). The
+ * acceptance aggregator reads these rows from the v2 manifest and asserts each
+ * returns its manifest `ok`/`code`.
+ */
+export const CACHE_IDS = Array.from({ length: 15 }, (_v, i) => `CACHE-${String(i + 1).padStart(3, "0")}`);
+/**
+ * Registered VC7B provider-economics conformance rows (PRO-024..030), continuing
+ * VC7A's PRO-016..023. These pin the ECONOMICS half of a provider profile:
+ * pricing validity, the exclusion-proof rule, and TTL/min-prefix eligibility.
+ */
+export const ECONOMICS_PROVIDER_IDS = Array.from({ length: 7 }, (_v, i) => `PRO-${String(i + 24).padStart(3, "0")}`);
+/** Named VC7B conformance assertions (the sprint's headline rows). */
+export const ECONOMICS_NAMED_IDS = [
+    "CACHE-COST-001",
+    "CACHE-EXCLUDE-002",
+    "CACHE-RANDOM-003",
+];