pi-mega-compact 0.20.13 → 0.20.15

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

@@ -0,0 +1,176 @@
+/**
+ * vector-cortex/provider/economics.ts — VC7B cache economics (ProviderProfileV1
+ * extension).
+ *
+ * VC7A proved a render can be FROZEN and reused. VC7B answers the question that
+ * immediately follows: is reusing it actually WORTH IT? Provider prompt caching
+ * is not free — a cache WRITE typically costs MORE than an uncached token, and a
+ * cache READ costs less. So a cache is profitable only when a written prefix is
+ * read back enough times, before its TTL expires, to repay the write premium.
+ * This file is that arithmetic and nothing else.
+ *
+ * THE NET-SAVINGS MODEL. For a prefix of `cachedTokens` tokens:
+ *
+ *   baseline (no cache) = cachedTokens * basePrice * (writes + hits)
+ *   actual (cached)     = cachedTokens * (writePrice * writes + readPrice * hits)
+ *   netSavings          = baseline - actual
+ *
+ * A NEGATIVE `netSavings` is a real, expected, and important outcome: it means
+ * the cache LOST money (a prefix written once and never re-read always does, by
+ * exactly the write premium). We report it rather than clamping it at zero,
+ * because a floor at zero would make every rollout look free and would hide the
+ * single failure mode this sprint exists to detect.
+ *
+ * EXACT ARITHMETIC, NO FLOATS IN THE MONEY PATH. Prices are integer
+ * MICRO-UNITS per token (1e-6 of the provider's currency unit), never floating
+ * point. `0.1 + 0.2 !== 0.3` is not an acceptable property for a cost ledger, and
+ * accumulating float error across millions of tokens produces aggregates that
+ * silently disagree with the provider's own bill. All money is integer; only the
+ * derived RATIO is a float, and it is finite-guarded.
+ *
+ * EVERY EXCLUSION NEEDS A FIXTURE (the sprint's headline safety rule). A provider
+ * profile may declare that some request field does not affect cache identity —
+ * but an UNPROVEN exclusion is how you get silent cache poisoning: the renderer
+ * folds a field the provider actually keys on, two different requests collapse to
+ * one cache entry, and one conversation is served another's prefix. So an
+ * exclusion without a `fixtureId` (or with a blank one) is REJECTED here —
+ * `ECON_EXCLUSION_UNPROVEN` — rather than trusted. There is no override.
+ *
+ * ESTIMATE VS MEASURED. Every result is labeled. Only telemetry from a
+ * RANDOMIZED live assignment may be called `measured` and fed into a causal
+ * interval; shadow or non-randomized numbers are `estimate` and are excluded
+ * from causal aggregates (see `experiments.ts`). Mixing the two would let a
+ * self-selected population masquerade as a controlled experiment.
+ *
+ * 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 `../cache/economics-emit.ts`.
+ */
+/** A non-negative safe integer — the only shape money and counts may take. */
+function isCount(n) {
+    return Number.isSafeInteger(n) && n >= 0;
+}
+/**
+ * Validate a profile's economics, enforcing the exclusion-proof rule.
+ *
+ * An exclusion claims "this field cannot affect provider cache identity". That
+ * claim is only as good as the fixture that proves it, so a profile carrying
+ * exclusions MUST name a `exclusionFixtureId`, and every individual exclusion
+ * must carry its own `fixtureId` too (VC5B already models that field; VC7B makes
+ * a blank one fatal instead of decorative). Returns deduplicated codes in a
+ * deterministic order.
+ */
+export function validateEconomics(econ, exclusions) {
+    const codes = new Set();
+    for (const n of [econ.basePrice, econ.readPrice, econ.writePrice, econ.ttlMs, econ.minPrefix]) {
+        if (!isCount(n))
+            codes.add("ECON_PRICE_INVALID");
+    }
+    // The headline rule: exclusions without a proving fixture are never trusted.
+    if (exclusions.length > 0) {
+        const id = econ.exclusionFixtureId;
+        if (id === null || id.trim() === "")
+            codes.add("ECON_EXCLUSION_UNPROVEN");
+        for (const ex of exclusions) {
+            if (ex.fixtureId.trim() === "")
+                codes.add("ECON_EXCLUSION_UNPROVEN");
+        }
+    }
+    const order = ["ECON_EXCLUSION_UNPROVEN", "ECON_PRICE_INVALID"];
+    return order.filter((c) => codes.has(c));
+}
+/**
+ * Validate a profile + its economics together. Convenience over
+ * `validateEconomics` for callers holding a whole `ProviderProfileV1`: the
+ * exclusion list is read from the profile itself, so the two can never disagree.
+ */
+export function validateProfileEconomics(profile, econ) {
+    return validateEconomics(econ, profile.excludedJsonPointers);
+}
+/**
+ * Hits required for ONE write to break even.
+ *
+ * One write costs `(writePrice - basePrice)` extra per token; each subsequent
+ * hit saves `(basePrice - readPrice)` per token. So break-even is the ceiling of
+ * premium/discount. Returns `null` when the cache can NEVER pay for itself
+ * (a read that costs at least as much as an uncached token) — reporting a huge
+ * number there would imply "just get more hits", which is false.
+ * Returns 0 when writing is already free or cheaper than not caching.
+ */
+export function breakEvenHits(econ) {
+    const premium = econ.writePrice - econ.basePrice;
+    const discount = econ.basePrice - econ.readPrice;
+    if (premium <= 0)
+        return 0;
+    if (discount <= 0)
+        return null;
+    return Math.ceil(premium / discount);
+}
+/**
+ * Compute net cache savings for observed (or shadow) usage.
+ *
+ * Pure integer arithmetic in micro-units. The only float is `savingsRatio`, and
+ * it is zero-guarded so a zero baseline yields 0 rather than NaN/Infinity — the
+ * sprint invariant is that every reported aggregate is FINITE.
+ *
+ * `evidence` is supplied by the caller and simply carried through: this function
+ * cannot know whether its inputs came from a randomized arm, and guessing would
+ * be exactly the mislabeling the causal rules forbid.
+ */
+export function computeEconomics(econ, usage, evidence) {
+    const codes = [];
+    for (const n of [econ.basePrice, econ.readPrice, econ.writePrice, econ.ttlMs, econ.minPrefix]) {
+        if (!isCount(n)) {
+            codes.push("ECON_PRICE_INVALID");
+            break;
+        }
+    }
+    for (const n of [usage.cachedTokens, usage.writeCount, usage.hitCount]) {
+        if (!isCount(n)) {
+            codes.push("ECON_USAGE_INVALID");
+            break;
+        }
+    }
+    if (codes.length > 0)
+        return { ok: false, codes };
+    const { cachedTokens, writeCount, hitCount } = usage;
+    const baselineCost = cachedTokens * econ.basePrice * (writeCount + hitCount);
+    const actualCost = cachedTokens * (econ.writePrice * writeCount + econ.readPrice * hitCount);
+    // Exactness is the whole point of the integer model: if any product leaves the
+    // safe-integer range the result is silently wrong, so we fail instead.
+    if (!Number.isSafeInteger(baselineCost) || !Number.isSafeInteger(actualCost)) {
+        return { ok: false, codes: ["ECON_OVERFLOW"] };
+    }
+    const netSavings = baselineCost - actualCost;
+    // Tokens served at the discounted read price — the cache's token-level benefit,
+    // independent of price (a hit re-reads the whole prefix).
+    const tokenSavings = cachedTokens * hitCount;
+    const savingsRatio = baselineCost === 0 ? 0 : netSavings / baselineCost;
+    return {
+        ok: true,
+        result: {
+            profileId: econ.profileId,
+            baselineCost,
+            actualCost,
+            netSavings,
+            tokenSavings,
+            savingsRatio,
+            breakEvenHits: breakEvenHits(econ),
+            evidence,
+        },
+    };
+}
+/**
+ * Whether a prefix is eligible to be cached at all: it must meet the profile's
+ * minimum prefix, and it must still be within TTL. A prefix below `minPrefix` is
+ * not "a small win", it is not cacheable by the provider at all.
+ */
+export function isCacheEligible(econ, prefixTokens, ageMs) {
+    if (!isCount(prefixTokens) || !isCount(ageMs))
+        return false;
+    return prefixTokens >= econ.minPrefix && ageMs < econ.ttlMs;
+}
+// Conformance ID ranges + named rows extracted to economics-ids.ts to keep this
+// file under the 300-line soft limit (soft-as-hard gate). Re-exported here so no
+// consumer import path changes.
+export { CACHE_IDS, ECONOMICS_PROVIDER_IDS, ECONOMICS_NAMED_IDS, } from "./economics-ids.js";

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,
+    }));
+}