pi-mega-compact 0.20.12 → 0.20.14

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

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";