pi-mega-compact 0.20.13 → 0.20.14

package/dist/src/vector-cortex/provider/experiments.js

@@ -0,0 +1,166 @@
+/**
+ * vector-cortex/provider/experiments.ts — VC7B session-level cache experiments.
+ *
+ * To claim a cache strategy CAUSED a saving you need a randomized comparison,
+ * not a before/after. This file assigns each session to an experiment arm and
+ * guarantees the two properties that make the resulting telemetry admissible as
+ * causal evidence.
+ *
+ * 1. STABLE, JOURNAL-FREE ASSIGNMENT. The arm is a pure function of
+ *    `sha256(experimentId, sessionId)` — NOT a random draw recorded in a
+ *    journal. So the assignment survives anything: process restart, a lost or
+ *    corrupted journal, a different host, a replay months later. This is the
+ *    sprint's unique failure-injection case (lose the journal after the first
+ *    event, restart, and the same arm must come back), and a hash-derived arm
+ *    passes it by construction rather than by careful recovery code. A journal
+ *    can still be kept as an audit trail, but nothing DEPENDS on it.
+ *
+ *    The corollary matters just as much: every event in one session shares one
+ *    arm (CACHE-RANDOM-003). If a session could drift between arms mid-flight,
+ *    its rows would appear in both arms of the comparison and the contrast would
+ *    be measuring nothing.
+ *
+ * 2. RANDOMIZED ⇒ CAUSAL; EVERYTHING ELSE ⇒ ESTIMATE. Hashing a session id is
+ *    randomization only when the id itself is unpredictable and every session is
+ *    eligible. A FORCED arm (operator override), a SHADOW arm (computed but not
+ *    served), and a non-randomized rollout are all labeled `estimate` and are
+ *    excluded from causal intervals by `isCausallyAdmissible`. Shadow numbers are
+ *    genuinely useful — they are just not evidence of an effect.
+ *
+ * WHY 10_000 BUCKETS. Bucket granularity bounds how finely traffic can be split;
+ * 10k gives 0.01% resolution, matching VC5C's rollout bucketing so the two
+ * subsystems partition traffic on the same scale rather than on quietly
+ * different ones.
+ *
+ * PURE. No clock, no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011). `assignedAt` is an INJECTED timestamp, never `Date.now()` read
+ * here, so assignment is fully reproducible in tests and replays. Runs
+ * identically with `MEGACOMPACT_VC7B` on or off.
+ */
+import { createHash } from "node:crypto";
+/** The registered arms, in canonical bucket order. */
+export const EXPERIMENT_ARMS = ["A", "B", "C"];
+/** Bucket space: 10k buckets = 0.01% resolution (matches VC5C rollout). */
+export const EXPERIMENT_BUCKETS = 10_000;
+/** Even three-way split (the default): 3334 / 3333 / 3333 = 10000. */
+export const EVEN_SPLIT = { A: 3334, B: 3333, C: 3333 };
+/**
+ * Length-prefixed field framing, identical in spirit to the crystal key encoder:
+ * `<byteLength>:<value>` makes the concatenation injective, so experiment
+ * `"a"` + session `"b:c"` cannot collide with experiment `"a:b"` + session `"c"`.
+ * Without it, two different (experiment, session) pairs could share a bucket and
+ * a session could appear to switch arms when an experiment is renamed.
+ */
+function field(value) {
+    return `${Buffer.byteLength(value, "utf8")}:${value}`;
+}
+/**
+ * The stable bucket for a session: the low 32 bits of
+ * `sha256(experimentId, sessionId)`, modulo the bucket space.
+ *
+ * Deterministic and storage-free — this is what makes a lost assignment journal
+ * a non-event. Reading 4 bytes (rather than the whole digest) keeps the value in
+ * exact integer range; SHA-256's avalanche means any 32 bits are equidistributed.
+ */
+export function experimentBucket(experimentId, sessionId) {
+    const h = createHash("sha256")
+        .update(field(experimentId) + field(sessionId), "utf8")
+        .digest();
+    return h.readUInt32BE(0) % EXPERIMENT_BUCKETS;
+}
+/** Validate that a split covers the bucket space exactly once. */
+export function validateSplit(split) {
+    for (const n of [split.A, split.B, split.C]) {
+        if (!Number.isSafeInteger(n) || n < 0)
+            return false;
+    }
+    return split.A + split.B + split.C === EXPERIMENT_BUCKETS;
+}
+/**
+ * Map a bucket to an arm under a split. Arms occupy contiguous bucket ranges in
+ * the fixed order A, B, C, so the mapping is stable: widening arm C's share can
+ * never reshuffle a session already sitting in arm A.
+ */
+export function armForBucket(bucket, split) {
+    if (bucket < split.A)
+        return "A";
+    if (bucket < split.A + split.B)
+        return "B";
+    return "C";
+}
+/**
+ * Assign a session to an experiment arm.
+ *
+ * The default path is `randomized`: bucket = stable hash, arm = bucket's range.
+ * Passing `forced` overrides the arm and downgrades the source (and therefore
+ * causal admissibility) — the bucket is still computed and reported so the
+ * override remains auditable against what the session WOULD have got.
+ *
+ * `assignedAt` is injected by the caller. Assignment is a pure function of its
+ * arguments, so the same session always yields the same arm no matter when, or
+ * how many times, it is asked.
+ */
+export function assignExperiment(input) {
+    const codes = [];
+    if (input.experimentId.trim() === "" || input.sessionId.trim() === "") {
+        codes.push("EXP_ID_INVALID");
+    }
+    const split = input.split ?? EVEN_SPLIT;
+    if (!validateSplit(split))
+        codes.push("EXP_SPLIT_INVALID");
+    if (input.forced !== undefined && !EXPERIMENT_ARMS.includes(input.forced)) {
+        codes.push("EXP_ARM_UNKNOWN");
+    }
+    if (codes.length > 0)
+        return { ok: false, codes };
+    const bucket = experimentBucket(input.experimentId, input.sessionId);
+    const natural = armForBucket(bucket, split);
+    const arm = input.forced ?? natural;
+    // Precedence: a forced arm is self-selected, so it is never causal even when
+    // it happens to agree with the natural arm. Shadow is likewise non-causal.
+    const source = input.forced !== undefined ? "forced" : input.shadow === true ? "shadow" : "randomized";
+    return {
+        ok: true,
+        assignment: {
+            schema: "cache-experiment-v1",
+            experimentId: input.experimentId,
+            sessionId: input.sessionId,
+            arm,
+            bucket,
+            source,
+            assignedAt: input.assignedAt,
+        },
+    };
+}
+/**
+ * Whether an assignment's telemetry may enter a causal interval.
+ *
+ * ONLY `randomized`. This single predicate is what keeps forced and shadow rows
+ * out of the causal aggregate; every consumer computing an interval must filter
+ * through it rather than re-deriving the rule.
+ */
+export function isCausallyAdmissible(a) {
+    return a.source === "randomized";
+}
+/**
+ * Keep only causally admissible assignments. The complement is not discarded by
+ * the caller — it is reported as `estimate` — but it never reaches an interval.
+ */
+export function causalOnly(assignments) {
+    return assignments.filter(isCausallyAdmissible);
+}
+/**
+ * Whether every assignment for one session agrees on the arm (CACHE-RANDOM-003).
+ * A session that appears in two arms would contaminate both sides of the
+ * comparison, so this is asserted directly rather than assumed.
+ */
+export function sessionArmsConsistent(assignments) {
+    const bySession = new Map();
+    for (const a of assignments) {
+        const seen = bySession.get(a.sessionId);
+        if (seen !== undefined && seen !== a.arm)
+            return false;
+        bySession.set(a.sessionId, a.arm);
+    }
+    return true;
+}

package/dist/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/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/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/vector-cortex/migrations/request-hash-v2.js

@@ -0,0 +1,161 @@
+/**
+ * vector-cortex/migrations/request-hash-v2.ts — M5 request-hash-v2, COPY +
+ * VALIDATE ONLY (VC7B). The switch lands in VC7C.
+ *
+ * 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:     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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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;
+}

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