pi-mega-compact 0.20.13 → 0.20.14

package/extensions/dashboard-server/route-dispatch.ts

@@ -64,6 +64,10 @@ import { handleVectorCortexRepair } from "./routes-vector-cortex-repair.js";
 // stays independent of the heal/repair handlers and every file stays well under
 // the 400-line extension limit.
 import { handleVectorCortexCrystals } from "./routes-vector-cortex-crystals.js";
+// VC7B cache economics likewise get their own module so the economics seam stays
+// independent of the crystals handler and every file stays well under the
+// 400-line extension soft limit.
+import { handleVectorCortexEconomics } from "./routes-vector-cortex-economics.js";
 
 /**
  * Dispatch a request through every registered route handler.
@@ -119,5 +123,6 @@ export function dispatchRoutes(
 	if (handleVectorCortexRestore(req, res, ctx)) return true;
 	if (handleVectorCortexRepair(req, res, ctx)) return true;
 	if (handleVectorCortexCrystals(req, res, ctx)) return true;
+	if (handleVectorCortexEconomics(req, res, ctx)) return true;
 	return false;
 }

package/extensions/dashboard-server/routes-rag-settings-vector-cortex.ts

@@ -162,5 +162,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Frozen range crystals: caches a rendered prompt under an IMMUTABLE key built from the source ranges it covers, the digest of those covered bytes, the validated durable dependency high-water, and the renderer + provider profile — and deliberately NOT the global ledger frontier, so an unrelated append leaves the key unchanged instead of invalidating every crystal on every turn. Any covered-byte, dependency, renderer, or profile change invalidates 100%. Ranges are sorted by source start and overlapping ranges are rejected (CRY_RANGE_OVERLAP) rather than merged. The store is content-addressed and write-once: identical bytes re-written are idempotent, but a same-key/different-bytes write returns CRY_KEY_COLLISION and never overwrites, surfacing renderer non-determinism instead of hiding it. A store hit is mode A, a miss/collision forces a fresh deterministic render (mode B), and an unavailable store bypasses the cache entirely (mode C). OFF = byte-identical predecessor (VC6C); the crystal/store arithmetic still runs, only the reporter + dashboard seam is suppressed.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC7B",
+			"VC7B Provider Cache Economics",
+			"Provider cache economics: extends the VC5B provider registry with cache economics (read/write price, TTL, minimum prefix, and a mandatory exclusion fixture id). Answers whether reusing a frozen crystal is actually worth it — a cache WRITE typically costs more than an uncached token, so a cache only pays off once a written prefix is re-read enough times before TTL expiry. Net savings are reported (never clamped at zero, so a losing cache stays visible) and every exclusion MUST name a proving conformance fixture or it is rejected (ECON_EXCLUSION_UNPROVEN). A compiled crystal boundary still reuses the VC7A key unchanged, and a randomized session-level experiment assigns arms by a stable hash so a lost assignment journal re-derives the same arm. OFF = byte-identical predecessor (VC7A); the economics/compiler/experiment arithmetic still runs, only the reporter + dashboard seam is suppressed.",
+			true,
+		),
 	],
 };

package/extensions/dashboard-server/routes-vector-cortex-economics.ts

@@ -0,0 +1,68 @@
+/**
+ * dashboard-server/routes-vector-cortex-economics.ts — VC7B cache-economics
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/cache-economics returning the cache-
+ * economics aggregate diagnostics: whether the VC7B flag is enabled, the runtime
+ * triad mode, how many provider profiles carry economics, how many exclusions
+ * are proven vs unproven, and the last ECON_* failure code.
+ *
+ * COUNTS + CODES ONLY. Cache economics price a FROZEN RENDERED PROMPT's reuse,
+ * so a careless payload field would leak the frozen bytes, the covered ranges,
+ * the span/covered digests, the request digests, or session ids that identify
+ * the framed conversation. This route NEVER exposes frozen bytes, ranges,
+ * digests, session ids, or request digests — only aggregate counts and the
+ * observable ECON_* outcome code (reader-only, SECURITY_PRIVACY). There is no
+ * mutation seam: economics are computed by the render path, never by a dashboard
+ * request. Non-GET is rejected outright.
+ *
+ * Split into its own file (rather than grown into routes-vector-cortex-crystals.ts)
+ * to keep every extensions/ file well under the 400-line soft-as-hard limit.
+ *
+ * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
+ * `any`), reader-only aggregate (counts + codes only).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC7B_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexEconomicsView } from "./api-contracts/vector-cortex-economics.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/cache-economics (VC7B).
+ *
+ * Counts, profile tallies, and ECON_* codes only — a static reader-only
+ * aggregate seam with the same shape as the VC7A crystals handler.
+ */
+export function handleVectorCortexEconomics(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/cache-economics") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC7B_ENABLED();
+  // Flag-off routes to mode C: with VC7B off no cache economics are served, which
+  // is exactly the spec's "economics bypass" outcome. Reporting A (cached render
+  // priced) or B (fresh render priced) would imply an economics path that is not
+  // wired at all. Mirrors how VC6C/VC7A OFF views report the mode they take.
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexEconomicsView = {
+    enabled,
+    mode,
+    profileCount: 0,
+    provenExclusions: 0,
+    unprovenExclusions: 0,
+    lastFailure: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.13",
+  "version": "0.20.14",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex-early.ts

@@ -0,0 +1,99 @@
+/**
+ * config/vector-cortex-early.ts — VC0/VC1/VC2 phase sprint flags.
+ *
+ * Extracted from vector-cortex.ts to keep that file under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-breakers.ts was. These are
+ * the FOUNDATION-phase flags (observability, ledger, conformance, encoder); the
+ * VC3+ derived-state and prompt-path flags stay in vector-cortex.ts alongside
+ * the shared `sprintFlag` reader they are documented against.
+ *
+ * The split is purely mechanical: every flag below is byte-identical in name,
+ * semantics, and default to its previous definition, and vector-cortex.ts
+ * re-exports all of them so no consumer import path changes.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/** VC0A — baseline observability (MetricEventV1 / AnnotationV1). Default ON. */
+export const VC0A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0A");
+
+/**
+ * VC0B — replay correctness (ReplayCutV2 / ReplayReportV2, M3 effective-cut-v2).
+ * Default ON. `MEGACOMPACT_VC0B=0` disables and is byte-identical to the
+ * predecessor (legacy capped-replay behavior preserved; the v2 cut/replay is
+ * only consulted on the vector-cortex path).
+ */
+export const VC0B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0B");
+
+/**
+ * VC1A — canonical byte events (EventV2 / EventCodec).
+ * Default ON. `MEGACOMPACT_VC1A=0` disables and is byte-identical to the
+ * predecessor (mode C: ledger absent, current transcript codec unchanged).
+ * The single real consumer is the ledger emit seam (`ledger/emit.ts`): flag OFF
+ * gates zero observability writes.
+ */
+export const VC1A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1A");
+
+/**
+ * VC1B — occurrence ledger + tool identity + compat journal (LedgerReader/
+ * Writer/Admin, CompatJournalV1, M2 occurrence-v2 migration).
+ * Default ON. `MEGACOMPACT_VC1B=0` disables and is byte-identical to the
+ * predecessor (mode C: the neutral occurrence ledger is not written, no
+ * journal rows, zero `vector_cortex_occurrence_appended` emissions). The real
+ * consumers are the ledger write integration seam and the compat-journal
+ * switch seam.
+ */
+export const VC1B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1B");
+
+/**
+ * VC0C — live safety envelope (TriadResult / Breaker / KillDecision + durable
+ * spool). Default ON. `MEGACOMPACT_VC0C=0` disables and is byte-identical to
+ * the predecessor (mode C: selected before provider invocation, unchanged host
+ * transcript, breaker/spool idle and emitting nothing). The single real
+ * consumer is the resilience emit seam + the safety adapter's triad selection.
+ */
+export const VC0C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0C");
+
+/**
+ * VC1C — cross-language conformance v2 (FixtureManifestV2 / DowngradeReport /
+ * MinHashV2 + M4 minhash-v2 migration).
+ * Default ON. `MEGACOMPACT_VC1C=0` disables and is byte-identical to the
+ * predecessor (mode C: a v2 conformance runner that accepts authority fixtures
+ * and the manifest validator idle; the sync dedup scan stays on the v1 path;
+ * zero `vector_cortex_*` VC1C emissions). The real consumers are the conformance
+ * emit seam, the minhash-v2 backfill seam and the downgrade-export seam.
+ */
+export const VC1C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1C");
+
+/**
+ * VC2A — offline model runtime and asset decision (ModelManifestV1 /
+ * EncoderRuntime).
+ * Default ON. `MEGACOMPACT_VC2A=0` disables and is byte-identical to the
+ * predecessor (mode C: no asset manifest is read/verified, the encoder runtime
+ * idles in mode C, zero `vector_cortex_encoder_*` emissions; the trigram/lexical
+ * paths are unchanged). The real consumers are the encoder emit seam and the
+ * encoder runtime's A/B/C selection.
+ */
+export const VC2A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2A");
+
+/**
+ * VC2B — multi-head encoder (VectorSetV1 / HeadCalibrationDraft).
+ * Default ON. `MEGACOMPACT_VC2B=0` disables and is byte-identical to the
+ * predecessor (the encoder emits no per-head vectors and no fallback-selected
+ * event; the trigram/lexical paths themselves are unchanged and are the
+ * predecessor's mode-B/C producers). The real consumers are the encoder-heads
+ * emit seam and the multi-head encoder producers (heads/trigram/lexical).
+ */
+export const VC2B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2B");
+
+/**
+ * VC2C — encoder qualification + calibration (QualifiedEncoderV1 / CalibrationV1).
+ * Default ON. `MEGACOMPACT_VC2C=0` disables and is byte-identical to the
+ * predecessor (mode C: no qualification manifest is read or selected, the
+ * calibrate/select/fallback seams are idle, zero `vector_cortex_encoder_qualification_*`
+ * emissions; the trigram/lexical paths are unchanged). The real consumers are
+ * the encoder-qualification emit seam and the calibrate/select seams.
+ */
+export const VC2C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2C");

package/src/config/vector-cortex-flag.ts

@@ -0,0 +1,24 @@
+/**
+ * config/vector-cortex-flag.ts — the single positive sprint-flag reader.
+ *
+ * Extracted from vector-cortex.ts so the flag groups split across
+ * vector-cortex.ts and vector-cortex-early.ts share ONE definition of what
+ * "enabled" means. Duplicating this three-line function into each group would
+ * be the classic way a sprint flag silently acquires different off-semantics in
+ * different files; there is exactly one implementation and both groups import it.
+ *
+ * Semantics (unchanged, byte-identical to the original in-place definition):
+ * every sprint flag is POSITIVE and defaults ON. `MEGACOMPACT_<SPRINT>=0` or
+ * `=false` disables it, as does `MEGACOMPACT_<SPRINT>_DISABLED=true`/`=1`.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/** Positive sprint flag: `=0` or `_DISABLED=true` disables (default ON). */
+export function sprintFlag(name: string): boolean {
+  const v = process.env[name];
+  if (v === "0" || v === "false") return false;
+  const disabled = process.env[name + "_DISABLED"];
+  if (disabled === "true" || disabled === "1") return false;
+  return true;
+}

package/src/config/vector-cortex.ts

@@ -9,96 +9,22 @@
  * them without re-declaring the ownership boundary. Pi-agnostic, dependency-free.
  */
 
-/** Positive sprint flag: `=0` or `_DISABLED=true` disables (default ON). */
-function sprintFlag(name: string): boolean {
-  const v = process.env[name];
-  if (v === "0" || v === "false") return false;
-  const disabled = process.env[name + "_DISABLED"];
-  if (disabled === "true" || disabled === "1") return false;
-  return true;
-}
+import { sprintFlag } from "./vector-cortex-flag.js";
 
-/** VC0A — baseline observability (MetricEventV1 / AnnotationV1). Default ON. */
-export const VC0A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0A");
-
-/**
- * VC0B — replay correctness (ReplayCutV2 / ReplayReportV2, M3 effective-cut-v2).
- * Default ON. `MEGACOMPACT_VC0B=0` disables and is byte-identical to the
- * predecessor (legacy capped-replay behavior preserved; the v2 cut/replay is
- * only consulted on the vector-cortex path).
- */
-export const VC0B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0B");
-
-/**
- * VC1A — canonical byte events (EventV2 / EventCodec).
- * Default ON. `MEGACOMPACT_VC1A=0` disables and is byte-identical to the
- * predecessor (mode C: ledger absent, current transcript codec unchanged).
- * The single real consumer is the ledger emit seam (`ledger/emit.ts`): flag OFF
- * gates zero observability writes.
- */
-export const VC1A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1A");
-
-/**
- * VC1B — occurrence ledger + tool identity + compat journal (LedgerReader/
- * Writer/Admin, CompatJournalV1, M2 occurrence-v2 migration).
- * Default ON. `MEGACOMPACT_VC1B=0` disables and is byte-identical to the
- * predecessor (mode C: the neutral occurrence ledger is not written, no
- * journal rows, zero `vector_cortex_occurrence_appended` emissions). The real
- * consumers are the ledger write integration seam and the compat-journal
- * switch seam.
- */
-export const VC1B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1B");
-
-/**
- * VC0C — live safety envelope (TriadResult / Breaker / KillDecision + durable
- * spool). Default ON. `MEGACOMPACT_VC0C=0` disables and is byte-identical to
- * the predecessor (mode C: selected before provider invocation, unchanged host
- * transcript, breaker/spool idle and emitting nothing). The single real
- * consumer is the resilience emit seam + the safety adapter's triad selection.
- */
-export const VC0C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0C");
-
-/**
- * VC1C — cross-language conformance v2 (FixtureManifestV2 / DowngradeReport /
- * MinHashV2 + M4 minhash-v2 migration).
- * Default ON. `MEGACOMPACT_VC1C=0` disables and is byte-identical to the
- * predecessor (mode C: a v2 conformance runner that accepts authority fixtures
- * and the manifest validator idle; the sync dedup scan stays on the v1 path;
- * zero `vector_cortex_*` VC1C emissions). The real consumers are the conformance
- * emit seam, the minhash-v2 backfill seam and the downgrade-export seam.
- */
-export const VC1C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1C");
-
-/**
- * VC2A — offline model runtime and asset decision (ModelManifestV1 /
- * EncoderRuntime).
- * Default ON. `MEGACOMPACT_VC2A=0` disables and is byte-identical to the
- * predecessor (mode C: no asset manifest is read/verified, the encoder runtime
- * idles in mode C, zero `vector_cortex_encoder_*` emissions; the trigram/lexical
- * paths are unchanged). The real consumers are the encoder emit seam and the
- * encoder runtime's A/B/C selection.
- */
-export const VC2A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2A");
-
-/**
- * VC2B — multi-head encoder (VectorSetV1 / HeadCalibrationDraft).
- * Default ON. `MEGACOMPACT_VC2B=0` disables and is byte-identical to the
- * predecessor (the encoder emits no per-head vectors and no fallback-selected
- * event; the trigram/lexical paths themselves are unchanged and are the
- * predecessor's mode-B/C producers). The real consumers are the encoder-heads
- * emit seam and the multi-head encoder producers (heads/trigram/lexical).
- */
-export const VC2B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2B");
-
-/**
- * VC2C — encoder qualification + calibration (QualifiedEncoderV1 / CalibrationV1).
- * Default ON. `MEGACOMPACT_VC2C=0` disables and is byte-identical to the
- * predecessor (mode C: no qualification manifest is read or selected, the
- * calibrate/select/fallback seams are idle, zero `vector_cortex_encoder_qualification_*`
- * emissions; the trigram/lexical paths are unchanged). The real consumers are
- * the encoder-qualification emit seam and the calibrate/select seams.
- */
-export const VC2C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2C");
+// VC0/VC1/VC2 foundation-phase flags extracted to vector-cortex-early.ts to keep
+// this file under the 300-line soft limit. Re-exported here so every existing
+// `from "./config/vector-cortex.js"` import keeps resolving unchanged.
+export {
+  VC0A_ENABLED,
+  VC0B_ENABLED,
+  VC0C_ENABLED,
+  VC1A_ENABLED,
+  VC1B_ENABLED,
+  VC1C_ENABLED,
+  VC2A_ENABLED,
+  VC2B_ENABLED,
+  VC2C_ENABLED,
+} from "./vector-cortex-early.js";
 
 /**
  * VC3A — capability-gated cortex store (CortexReader/Writer/Admin, CortexRecordV1).
@@ -273,6 +199,25 @@ export const VC6C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6C");
  */
 export const VC7A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7A");
 
+/**
+ * VC7B — provider cache economics + crystal compiler. Default ON.
+ * `MEGACOMPACT_VC7B=0` disables and is byte-identical to the predecessor
+ * (VC7A): `computeEconomics`, `compileCrystalBoundaries` and `assignExperiment`
+ * STILL RUN (they are PURE — exact integer/rational arithmetic and a SHA-256
+ * session bucket, with no clock, storage, or network), so a session keeps its
+ * SAME experiment arm and the compiler keeps producing the SAME boundaries with
+ * the flag off. Crucially the compiler never changes request identity in either
+ * state, so the outbound canonical request — and therefore the VC7A crystal key
+ * and the predecessor golden bytes — are unaffected by this flag.
+ *
+ * The flag gates ONLY the `vector_cortex_cache_experiment_assigned` /
+ * `vector_cortex_cache_economics_estimated` events and the cache-economics
+ * dashboard seam, which reports `enabled:false` + mode C when off. This flag
+ * MUST also be a dashboard SETTINGS toggle (visible in config UI, never in
+ * EXCLUDED_SETTINGS), mirroring VC4A..VC7A.
+ */
+export const VC7B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7B");
+
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker) extracted to
 // vector-cortex-breakers.ts to keep this file under the 300-line soft limit.
 export {

package/src/config.ts

@@ -173,6 +173,7 @@ export {
   VC6B_ENABLED,
   VC6C_ENABLED,
   VC7A_ENABLED,
+  VC7B_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/cache/_economics-fixture.ts

@@ -0,0 +1,128 @@
+/**
+ * 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";
+
+/** A `ProviderProfileExclusion` as it appears in JSON. */
+export interface EconFxExclusion {
+  pointer: string;
+  fixtureId: string;
+  proofDigest: string;
+}
+
+/** A `ProviderProfileV1` as it appears in JSON (exclusions flattened). */
+export interface EconFxProfile {
+  profileId: string;
+  profileVersion: string;
+  exclusionFixtureId: string | null;
+  exclusions: readonly EconFxExclusion[];
+}
+
+/** A `CacheUsageV1` as it appears in JSON (matches `CacheUsageV1` exactly). */
+export interface EconFxUsage {
+  cachedTokens: number;
+  writeCount: number;
+  hitCount: number;
+}
+
+/** A compiler input range as it appears in JSON (matches `DagSpan` minus seq). */
+export interface EconFxCompilerRange {
+  sessionId: string;
+  startSeq: number;
+  endSeq: number;
+  startByte: number;
+  endByte: number;
+  digest: string;
+}
+
+export interface EconFxExperiment {
+  experimentId: string;
+  sessionId: string;
+  arm: "A" | "B" | "C";
+  source: "randomized" | "forced" | "shadow";
+}
+
+export interface EconFxInput {
+  scenario: "economics" | "exclusion" | "compile" | "experiment" | "eligibility";
+  mode: string;
+  economics?: ProviderEconomicsV1Lite;
+  profile?: EconFxProfile;
+  exclusion?: EconFxExclusion;
+  usage?: EconFxUsage;
+  prefixTokens?: number;
+  ageMs?: number;
+  ranges?: readonly EconFxCompilerRange[];
+  experiment?: EconFxExperiment;
+  repeatAssignments?: number;
+  loseJournalAfterFirst?: boolean;
+}
+
+export interface ProviderEconomicsV1Lite {
+  profileId: string;
+  profileVersion: string;
+  basePrice: number;
+  readPrice: number;
+  writePrice: number;
+  ttlMs: number;
+  minPrefix: number;
+  exclusionFixtureId: string | null;
+}
+
+export interface EconFxExpected {
+  ok: boolean;
+  code?: string;
+  netSavings?: number;
+  tokenSavings?: number;
+  breakEvenHits?: number | null;
+  eligible?: boolean;
+  identityPreserved?: boolean;
+  repeatArm?: "A" | "B" | "C";
+}
+
+export interface EconFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: EconFxInput;
+  expected: EconFxExpected;
+}
+
+/** Read one registered cache-economics fixture (asserting it IS registered). */
+export function economicsFixture(id: string): EconFx {
+  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")) as EconFx;
+}
+
+/** Flag-pinned wrapper: VC7B gated by MEGACOMPACT_VC7B (defaults ON). */
+export function withVc7bFlag(value: string, fn: () => void): () => void {
+  return (): void => {
+    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;
+    }
+  };
+}