pi-mega-compact 0.20.70 → 0.20.72

package/src/vector-cortex/livewire/livewire-live.ts

@@ -0,0 +1,223 @@
+/**
+ * vector-cortex/livewire/livewire-live.ts — LIVEWIRE in-process live state.
+ *
+ * Holds the LIVE subsystem objects for ONE stateDir: the VC7A `CrystalStore`,
+ * the VC7C cache breaker, the per-miss-class tallies, the VC8B shadow metrics,
+ * and the VC7B economics computed bit. This is the object the RUNTIME accumulates
+ * into (`recordMiss`, `recordServeBlocked`, `recordShadowRun`, ...) and that the
+ * reader-only dashboard routes snapshot out of. Kept separate from the registry
+ * (which owns the per-stateDir `Map` + persistence) so neither file crosses the
+ * 300-line soft-as-hard gate.
+ *
+ * AGGREGATE-FIRST, COUNTS ONLY. `snapshotOf` projects the live objects down to
+ * the SECURITY_PRIVACY-safe `LivewireSnapshot` (counts + codes + triad mode) that
+ * gets persisted and rendered. No session id, digest, range, profile id, bytes,
+ * or prompt text can pass through ANY of these fields.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any`. Non-fatal: every derive is
+ * a pure read.
+ */
+
+import { CrystalStore } from "../cache/store.js";
+import { createCacheBreaker } from "../cache/breaker.js";
+import type { MissClass } from "../cache/diagnostics-types.js";
+import { validateProfileEconomics } from "../provider/economics.js";
+import { BASE_PROVIDER_PROFILES } from "../provider/registry.js";
+import type {
+  LivewireDiagnosticsAggregate,
+  LivewireEconomicsAggregate,
+  LivewirePolicyAggregate,
+  LivewireSnapshot,
+} from "./livewire-types.js";
+
+/** One VC7C miss classification tally (in-process, counts only). */
+export interface LivewireDiagnosticsRecord {
+  readonly tallies: { [K in MissClass]: number };
+  serveBlocked: number;
+  /**
+   * Observable breaker state (CLOSED_A / OPEN_B / ... / MANUAL_HALT). Tracked as
+   * a field so it survives process restart: the runtime syncs it from the live
+   * breaker when persisting, and a reader process restores it from the snapshot
+   * (a fresh in-process breaker is always CLOSED_A, which would be misleading).
+   */
+  breakerState: string;
+  lastFailure: string | null;
+}
+
+/** One VC7B economics record (computed bit + profile tallies + last failure). */
+export interface LivewireEconomicsRecord {
+  computed: boolean;
+  /** Provider profiles that declare cache economics (static from BASE_PROFILES). */
+  profileCount: number;
+  /** Exclusions that carry a proving fixture id (static from BASE_PROFILES). */
+  provenExclusions: number;
+  /** Exclusions rejected for lacking a fixture id (static from BASE_PROFILES). */
+  unprovenExclusions: number;
+  lastFailure: string | null;
+}
+
+/**
+ * Static VC7B economics profile tallies derived from the base provider registry.
+ * `profileCount` counts profiles that declare economics; `provenExclusions` /
+ * `unprovenExclusions` tally the exclusion sets validated against the fixture
+ * rule. This is PURE (no storage/clock/network) and identical regardless of the
+ * `MEGACOMPACT_VC7B` flag — only the emission/route seam is flag-gated.
+ */
+function baseEconomicsTallies(): {
+  profileCount: number;
+  provenExclusions: number;
+  unprovenExclusions: number;
+} {
+  let profileCount = 0;
+  let provenExclusions = 0;
+  let unprovenExclusions = 0;
+  for (const bundle of BASE_PROVIDER_PROFILES) {
+    const econ = bundle.profile.economics;
+    if (econ === null) continue;
+    profileCount += 1;
+    const codes = validateProfileEconomics(bundle.profile, econ);
+    const failed = new Set(codes);
+    for (const _ex of bundle.profile.excludedJsonPointers) {
+      if (failed.has("ECON_EXCLUSION_UNPROVEN")) {
+        unprovenExclusions += 1;
+      } else {
+        provenExclusions += 1;
+      }
+    }
+  }
+  return { profileCount, provenExclusions, unprovenExclusions };
+}
+
+/** One VC8B shadow-policy record (metrics + active pressure version). */
+export interface LivewireShadowRecord {
+  shadowDecisions: number;
+  clampedDecisions: number;
+  rejectedInputs: number;
+  liveMutations: number;
+  pressureVersion: 1 | 2;
+  lastFailure: string | null;
+}
+
+/** The live, in-process state for one stateDir. */
+export interface LivewireLiveState {
+  readonly crystalStore: CrystalStore;
+  readonly breaker: ReturnType<typeof createCacheBreaker>;
+  readonly diagnostics: LivewireDiagnosticsRecord;
+  readonly economics: LivewireEconomicsRecord;
+  readonly shadow: LivewireShadowRecord;
+}
+
+/** A zeroed per-class tally map. */
+function zeroTallies(): LivewireDiagnosticsRecord["tallies"] {
+  return {
+    profile: 0,
+    range: 0,
+    dependency: 0,
+    request: 0,
+    generation: 0,
+    unknown: 0,
+  };
+}
+
+/** Build a fresh (empty) live state with real subsystem objects. */
+export function createLiveState(): LivewireLiveState {
+  const econTallies = baseEconomicsTallies();
+  return {
+    crystalStore: new CrystalStore(),
+    breaker: createCacheBreaker(),
+    diagnostics: {
+      tallies: zeroTallies(),
+      serveBlocked: 0,
+      breakerState: "CLOSED_A",
+      lastFailure: null,
+    },
+    economics: {
+      computed: false,
+      profileCount: econTallies.profileCount,
+      provenExclusions: econTallies.provenExclusions,
+      unprovenExclusions: econTallies.unprovenExclusions,
+      lastFailure: null,
+    },
+    shadow: {
+      shadowDecisions: 0,
+      clampedDecisions: 0,
+      rejectedInputs: 0,
+      liveMutations: 0,
+      pressureVersion: 1,
+      lastFailure: null,
+    },
+  };
+}
+
+/** Project the live state down to the persisted, reader-only aggregate. */
+export function snapshotOf(state: LivewireLiveState): LivewireSnapshot {
+  const crystals = state.crystalStore.stats();
+  const diag: LivewireDiagnosticsAggregate = {
+    profileMisses: state.diagnostics.tallies.profile,
+    rangeMisses: state.diagnostics.tallies.range,
+    dependencyMisses: state.diagnostics.tallies.dependency,
+    requestMisses: state.diagnostics.tallies.request,
+    generationMisses: state.diagnostics.tallies.generation,
+    unknownMisses: state.diagnostics.tallies.unknown,
+    serveBlocked: state.diagnostics.serveBlocked,
+    breakerState: state.diagnostics.breakerState,
+    lastFailure: state.diagnostics.lastFailure,
+  };
+  const econ: LivewireEconomicsAggregate = {
+    profileCount: state.economics.profileCount,
+    provenExclusions: state.economics.provenExclusions,
+    unprovenExclusions: state.economics.unprovenExclusions,
+    computed: state.economics.computed,
+    lastFailure: state.economics.lastFailure,
+  };
+  const policy: LivewirePolicyAggregate = {
+    shadowDecisions: state.shadow.shadowDecisions,
+    clampedDecisions: state.shadow.clampedDecisions,
+    rejectedInputs: state.shadow.rejectedInputs,
+    liveMutations: state.shadow.liveMutations,
+    pressureVersion: state.shadow.pressureVersion,
+    lastFailure: state.shadow.lastFailure,
+  };
+  return {
+    schema: "vector-cortex-livewire-v1",
+    crystals: {
+      mode: crystals.mode,
+      crystalCount: crystals.crystalCount,
+      totalBytes: crystals.totalBytes,
+      hits: crystals.hits,
+      misses: crystals.misses,
+      hitBytes: crystals.hitBytes,
+      writes: crystals.writes,
+      duplicateWrites: crystals.duplicateWrites,
+      collisions: crystals.collisions,
+    },
+    diagnostics: diag,
+    economics: econ,
+    policy,
+  };
+}
+
+/** Seed a fresh live state's CUMULATIVE counters from a persisted snapshot. */
+export function rehydrateLive(state: LivewireLiveState, snap: LivewireSnapshot): void {
+  state.crystalStore.rehydrate(snap.crystals);
+  state.diagnostics.tallies.profile = snap.diagnostics.profileMisses;
+  state.diagnostics.tallies.range = snap.diagnostics.rangeMisses;
+  state.diagnostics.tallies.dependency = snap.diagnostics.dependencyMisses;
+  state.diagnostics.tallies.request = snap.diagnostics.requestMisses;
+  state.diagnostics.tallies.generation = snap.diagnostics.generationMisses;
+  state.diagnostics.tallies.unknown = snap.diagnostics.unknownMisses;
+  state.diagnostics.serveBlocked = snap.diagnostics.serveBlocked;
+  state.diagnostics.breakerState = snap.diagnostics.breakerState;
+  state.diagnostics.lastFailure = snap.diagnostics.lastFailure;
+  state.economics.computed = snap.economics.computed;
+  state.economics.profileCount = snap.economics.profileCount;
+  state.economics.provenExclusions = snap.economics.provenExclusions;
+  state.economics.unprovenExclusions = snap.economics.unprovenExclusions;
+  state.economics.lastFailure = snap.economics.lastFailure;
+  state.shadow.shadowDecisions = snap.policy.shadowDecisions;
+  state.shadow.clampedDecisions = snap.policy.clampedDecisions;
+  state.shadow.rejectedInputs = snap.policy.rejectedInputs;
+  state.shadow.liveMutations = snap.policy.liveMutations;
+  state.shadow.pressureVersion = snap.policy.pressureVersion;
+  state.shadow.lastFailure = snap.policy.lastFailure;
+}

package/src/vector-cortex/livewire/livewire-registry.ts

@@ -0,0 +1,91 @@
+/**
+ * vector-cortex/livewire/livewire-registry.ts — per-stateDir LIWIRE registry.
+ *
+ * The single seam the runtime and the reader-only dashboard routes BOTH access.
+ * It owns a `Map<stateDir, LivewireLiveState>` (one live subsystem cluster per
+ * repo) and lazily opens a state on first access, rehydrating its cumulative
+ * counters from the persisted aggregate snapshot (`livewire-snapshot.ts`) so a
+ * freshly-spawned process — e.g. the dashboard server — reports the same counts
+ * the runtime has already accumulated.
+ *
+ * The runtime WRITES through this registry (see `livewire-runtime.ts`): each
+ * mutation persists a reduced, count-only snapshot. The routes READ through
+ * `livewireOf(stateDir)` and call the pure `snapshotOf`. There is no other path.
+ *
+ * BEST-EFFORT + NON-FATAL. `openLivewire` never throws: persistence failures are
+ * swallowed by the snapshot layer and state is always returned. PREVENT-PI-004
+ * (local in-process Map + filesystem only), PREVENT-011 (no `any`).
+ */
+
+import type { LivewireSnapshot } from "./livewire-types.js";
+import {
+  createLiveState,
+  rehydrateLive,
+  snapshotOf,
+  type LivewireLiveState,
+} from "./livewire-live.js";
+import {
+  loadLivewireSnapshot,
+  saveLivewireSnapshot,
+} from "./livewire-snapshot.js";
+
+/** The per-stateDir registry (process-local; a fresh process starts empty). */
+const REGISTRY = new Map<string, LivewireLiveState>();
+
+/** Optional structured logger for best-effort failure events. */
+export type LivewireLogger = (line: unknown) => void;
+
+let activeLogger: LivewireLogger | undefined;
+
+/**
+ * Bind the structured logger the snapshot layer uses for its non-fatal write
+ * failures. The runtime calls this once at startup with its JSON logger.
+ */
+export function setLivewireLogger(logger: LivewireLogger | undefined): void {
+  activeLogger = logger;
+}
+
+/**
+ * Open (or return the cached) live state for a stateDir. Lazy: on first access
+ * it rehydrates from the persisted aggregate so a separate dashboard process
+ * reflects prior runtime work. Never throws.
+ */
+export function livewireOf(stateDir: string): LivewireLiveState {
+  const cached = REGISTRY.get(stateDir);
+  if (cached !== undefined) return cached;
+  const state = createLiveState();
+  const snap = loadLivewireSnapshot(stateDir);
+  if (snap !== null) rehydrateLive(state, snap);
+  REGISTRY.set(stateDir, state);
+  return state;
+}
+
+/**
+ * Persist a state's reduced aggregate (counts + codes only). Best-effort and
+ * non-fatal. Called by the runtime after every mutation so the snapshot stays
+ * fresh for any reader process.
+ */
+export function persistLivewire(state: LivewireLiveState, stateDir: string): void {
+  saveLivewireSnapshot(stateDir, snapshotOf(state), activeLogger);
+}
+
+/** Persist the live state for a stateDir (convenience over open + persist). */
+export function flushLivewire(stateDir: string): void {
+  const state = REGISTRY.get(stateDir);
+  if (state === undefined) return;
+  persistLivewire(state, stateDir);
+}
+
+/**
+ * Build the reader aggregate for one stateDir WITHOUT persisting — the reader
+ * seam the dashboard routes call. Reads the live state (rehydrated from disk on
+ * first access) and projects it to the count-only snapshot.
+ */
+export function readLivewireSnapshot(stateDir: string): LivewireSnapshot {
+  return snapshotOf(livewireOf(stateDir));
+}
+
+/** For tests: drop the registry so a fresh stateDir is fully rehydrated. */
+export function _resetLivewireRegistryForTests(): void {
+  REGISTRY.clear();
+}

package/src/vector-cortex/livewire/livewire-runtime.ts

@@ -0,0 +1,117 @@
+/**
+ * vector-cortex/livewire/livewire-runtime.ts — LIVEWIRE runtime accumulation seam.
+ *
+ * The WRITE side of LIVEWIRE: the runtime calls these methods wherever the
+ * corresponding subsystem path actually runs, and each call accumulates into the
+ * per-stateDir live state and persists a reduced count-only snapshot (best-effort,
+ * non-fatal). This is the seam that turns the pure VC7A/VC7B/VC7C/VC8B arithmetic
+ * into LIVE dashboard state.
+ *
+ * FLAG SEMANTICS (mirrors every other VC writer): these methods run REGARDLESS of
+ * the corresponding `MEGACOMPACT_VC*` flag — the arithmetic is never skipped, and
+ * a miss is still classified / a write still stored exactly as before. Only the
+ * dashboard REPORT seam (`routes-vector-cortex-*.ts`) is flag-gated: with the
+ * flag off a route returns the legacy `deferredReason` (byte-identical to the
+ * predecessor). The reporter emit seams in `cache/*-emit.ts` / `controller/
+ * policy-emit.ts` remain the event-announcement gate.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any`. Every write is best-effort.
+ */
+
+import type { MissClass, MissObservation } from "../cache/diagnostics-types.js";
+import { classifyMiss } from "../cache/diagnostics.js";
+import { shouldBlockServe } from "../cache/breaker.js";
+import type { CrystalV1, CrystalWriteResult } from "../cache/types.js";
+import type { ShadowResult } from "../controller/types.js";
+import { livewireOf, persistLivewire } from "./livewire-registry.js";
+
+/**
+ * Record a VC7A crystal WRITE attempt (write-once + collision arithmetic). The
+ * caller passes the fully-formed `CrystalV1`; the store returns the write result
+ * (first-write / idempotent / collision). The dashboard's `stats()` reflects it.
+ *
+ * @returns the store's write verdict, forwarded so the runtime can act on a
+ *          collision without re-deriving it.
+ */
+export function recordCrystalWrite(stateDir: string, crystal: CrystalV1): CrystalWriteResult {
+  const state = livewireOf(stateDir);
+  const result = state.crystalStore.write(crystal);
+  persistLivewire(state, stateDir);
+  return result;
+}
+
+/**
+ * Record a VC7A crystal READ attempt. Returns the stored crystal (or undefined
+ * on a miss / mode C), mirroring `CrystalStore.read` so the cache-serve path can
+ * use this seam entirely.
+ */
+export function readCrystal(stateDir: string, keyDigest: string): CrystalV1 | undefined {
+  const state = livewireOf(stateDir);
+  const found = state.crystalStore.read(keyDigest);
+  persistLivewire(state, stateDir);
+  return found;
+}
+
+/**
+ * Record a VC7C miss observation: classify it into its exclusive class and tally
+ * it. When the class demands the cache serve be demoted BEFORE answering, the
+ * `serveBlocked` counter is also incremented. The live breaker state itself is
+ * driven by the real cache-serve path (through `breaker.execute`), not here; this
+ * seam only observes and tallies.
+ *
+ * @returns the exclusive class the observation was tallied under.
+ */
+export function observeCacheMiss(stateDir: string, observation: MissObservation): MissClass {
+  const state = livewireOf(stateDir);
+  const missClass = classifyMiss(observation).missClass;
+  state.diagnostics.tallies[missClass] += 1;
+  if (shouldBlockServe(missClass)) state.diagnostics.serveBlocked += 1;
+  persistLivewire(state, stateDir);
+  return missClass;
+}
+
+/**
+ * Record a VC7C cache serve that the breaker demoted BEFORE answering. Talls the
+ * `serveBlocked` counter the diagnostics card surfaces.
+ */
+export function recordServeBlocked(stateDir: string): void {
+  const state = livewireOf(stateDir);
+  state.diagnostics.serveBlocked += 1;
+  persistLivewire(state, stateDir);
+}
+
+/**
+ * Record a VC8B shadow evaluation run: accumulate its decision metrics so the
+ * policy card reports how many shadow decisions were evaluated / clamped /
+ * rejected and how many live mutations the shadow proved (structurally 0).
+ */
+export function recordShadowRun(stateDir: string, result: ShadowResult): void {
+  const state = livewireOf(stateDir);
+  state.shadow.shadowDecisions += result.metrics.evaluated;
+  state.shadow.clampedDecisions += result.metrics.clamped;
+  state.shadow.rejectedInputs += result.metrics.rejected;
+  state.shadow.liveMutations += result.metrics.liveMutations;
+  persistLivewire(state, stateDir);
+}
+
+/**
+ * Set the active M7 pressure version (1 = legacy, 2 = migrated). The runtime
+ * calls this after a successful `migratePressureV2` so the policy card reflects
+ * the live migration state rather than a hardcoded 1.
+ */
+export function setPressureVersion(stateDir: string, version: 1 | 2): void {
+  const state = livewireOf(stateDir);
+  state.shadow.pressureVersion = version;
+  persistLivewire(state, stateDir);
+}
+
+/**
+ * Mark that VC7B cache economics have actually been computed at runtime (the
+ * `computed` bit drives the economics card's `hasData`). The runtime calls this
+ * after the first real `computeEconomics` over observed usage.
+ */
+export function markEconomicsComputed(stateDir: string): void {
+  const state = livewireOf(stateDir);
+  state.economics.computed = true;
+  persistLivewire(state, stateDir);
+}

package/src/vector-cortex/livewire/livewire-snapshot.ts

@@ -0,0 +1,108 @@
+/**
+ * vector-cortex/livewire/livewire-snapshot.ts — LIVEWIRE aggregate persistence.
+ *
+ * The four LV subsytems are in-process live objects, but the dashboard server may
+ * run in a SEPARATE process from the runtime that accumulates the counts. To keep
+ * the reader-only routes honest when they run in their own process, this module
+ * persists a COUNT-ONLY aggregate snapshot (`vector-cortex-livewire.json`) to the
+ * per-repo `stateDir`, and `openLivewire` rehydrates a fresh process from it on
+ * first access. This is the same DR-snapshot philosophy as the legacy JSON
+ * checkpoints, but reduced to counts + codes (SECURITY_PRIVACY — see these types).
+ *
+ * BEST-EFFORT + NON-FATAL. A failed write is logged as a structured event and
+ * never breaks the agent loop; a missing/unreadable snapshot reads as null and
+ * the process starts from zero (matches the non-fatal-stores invariant). Every
+ * write is atomic-ish: the JSON is fully serialized to a temp name then renamed
+ * so a reader never observes a partial snapshot.
+ *
+ * PREVENT-PI-004: local filesystem read/write only, no network. PREVENT-011: no
+ * `any`.
+ */
+
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { LivewireSnapshot } from "./livewire-types.js";
+
+/** The snapshot filename in the per-repo stateDir (counts + codes only). */
+export const LIVEWIRE_SNAPSHOT_FILE = "vector-cortex-livewire.json";
+
+/** Resolve the snapshot path for a stateDir. */
+export function livewireSnapshotPath(stateDir: string): string {
+  return join(stateDir, LIVEWIRE_SNAPSHOT_FILE);
+}
+
+/**
+ * Best-effort type guard over a parsed snapshot. Rejects anything that is not
+ * the exact aggregate shape so a corrupted or stale file cannot poison the
+ * rehydrated counters.
+ */
+function isSnapshot(value: unknown): value is LivewireSnapshot {
+  if (typeof value !== "object" || value === null) return false;
+  const s = value as Record<string, unknown>;
+  return (
+    s.schema === "vector-cortex-livewire-v1" &&
+    typeof s.crystals === "object" &&
+    s.crystals !== null &&
+    typeof s.diagnostics === "object" &&
+    s.diagnostics !== null &&
+    typeof s.economics === "object" &&
+    s.economics !== null &&
+    typeof s.policy === "object" &&
+    s.policy !== null
+  );
+}
+
+/**
+ * Read the persisted aggregate for a stateDir, or null when absent/unreadable/
+ * malformed. Best-effort and non-fatal by construction.
+ */
+export function loadLivewireSnapshot(stateDir: string): LivewireSnapshot | null {
+  const path = livewireSnapshotPath(stateDir);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isSnapshot(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best-effort write of the aggregate snapshot (atomic rename). Never throws to
+ * the caller: a persistence failure logs a structured event and is swallowed.
+ *
+ * @param logger  optional structured logger `(line: unknown) => void`; when
+ *                omitted no event is emitted (tests pass `undefined`).
+ */
+export function saveLivewireSnapshot(
+  stateDir: string,
+  snapshot: LivewireSnapshot,
+  logger?: (line: unknown) => void,
+): void {
+  const dir = stateDir;
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const path = livewireSnapshotPath(dir);
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(snapshot), "utf-8");
+    renameSync(tmp, path);
+  } catch (err) {
+    if (logger !== undefined) {
+      try {
+        logger({
+          ts: new Date().toISOString(),
+          event: "vector_cortex_livewire_snapshot_write_failed",
+          stateDir,
+          reason: err instanceof Error ? err.message : String(err),
+        });
+      } catch {
+        // A failing logger must not recurse into another failure.
+      }
+    }
+  }
+}

package/src/vector-cortex/livewire/livewire-types.ts

@@ -0,0 +1,84 @@
+/**
+ * vector-cortex/livewire/livewire-types.ts — LIVEWIRE aggregate snapshot types.
+ *
+ * LIVEWIRE wires the four complete-but-unwired Vector Cortex subsystems into the
+ * runtime so their dashboard routes report LIVE state instead of hardcoded
+ * "deferred" zeros. This module is the SINGLE SOURCE OF TRUTH for the persisted
+ * aggregate snapshot shape (counts + codes ONLY) and for the per-stateDir
+ * live-state records the routes read.
+ *
+ * SECURITY_PRIVACY: every field here is a count, a code, or a finite triad mode.
+ * There is deliberately NO string slot for a session id, a request/crystal
+ * digest, a covered range, frozen bytes, a profile id, or ledger content — a
+ * crystal IS a frozen rendered prompt, so the card that reports on it must never
+ * be able to carry one. The snapshot is the SAME reduced shape, so nothing secret
+ * reaches disk either.
+ *
+ * PREVENT-PI-004: type definitions only, no network code. PREVENT-011: no `any`.
+ */
+
+/** Triad mode shared by the crystals / diagnostics / economics cards. */
+export type LivewireMode = "A" | "B" | "C";
+
+/** VC7A crystal aggregate — mirrors `CrystalStoreStats` one-for-one. */
+export interface LivewireCrystalAggregate {
+  readonly mode: LivewireMode;
+  readonly crystalCount: number;
+  readonly totalBytes: number;
+  readonly hits: number;
+  readonly misses: number;
+  readonly hitBytes: number;
+  readonly writes: number;
+  readonly duplicateWrites: number;
+  readonly collisions: number;
+}
+
+/** VC7C per-miss-class tallies + breaker observable state. */
+export interface LivewireDiagnosticsAggregate {
+  readonly profileMisses: number;
+  readonly rangeMisses: number;
+  readonly dependencyMisses: number;
+  readonly requestMisses: number;
+  readonly generationMisses: number;
+  readonly unknownMisses: number;
+  readonly serveBlocked: number;
+  /** Breaker observable state name (CLOSED_A / OPEN_B / ... / MANUAL_HALT). */
+  readonly breakerState: string;
+  /** Last CACHE/M5 code, or null. */
+  readonly lastFailure: string | null;
+}
+
+/** VC7B economics aggregate — static profile tallies + computed bit. */
+export interface LivewireEconomicsAggregate {
+  /** Provider profiles that declare cache economics. */
+  readonly profileCount: number;
+  /** Exclusions that carry a proving fixture id. */
+  readonly provenExclusions: number;
+  /** Exclusions rejected for lacking a fixture id. */
+  readonly unprovenExclusions: number;
+  /** True once the runtime has actually run `computeEconomics` at least once. */
+  readonly computed: boolean;
+  /** Last ECON_* code, or null. */
+  readonly lastFailure: string | null;
+}
+
+/** VC8B shadow-policy aggregate — maps 1:1 to the policy card fields. */
+export interface LivewirePolicyAggregate {
+  readonly shadowDecisions: number;
+  readonly clampedDecisions: number;
+  readonly rejectedInputs: number;
+  readonly liveMutations: number;
+  /** Active pressure version (1 legacy / 2 migrated). */
+  readonly pressureVersion: 1 | 2;
+  /** Last POL_ or M7_ code, or null. */
+  readonly lastFailure: string | null;
+}
+
+/** The persisted, restart-surviving aggregate for one stateDir. */
+export interface LivewireSnapshot {
+  readonly schema: "vector-cortex-livewire-v1";
+  readonly crystals: LivewireCrystalAggregate;
+  readonly diagnostics: LivewireDiagnosticsAggregate;
+  readonly economics: LivewireEconomicsAggregate;
+  readonly policy: LivewirePolicyAggregate;
+}

package/src/vector-cortex/provider/economics.ts

@@ -47,38 +47,16 @@
  * gates only the reporter/dashboard seam in `../cache/economics-emit.ts`.
  */
 
-import type { ProviderProfileExclusion, ProviderProfileV1 } from "./types.js";
+import type {
+  ProviderEconomicsV1,
+  ProviderProfileExclusion,
+  ProviderProfileV1,
+} from "./types.js";
 
-/**
- * Cache economics attached to a provider profile.
- *
- * Prices are integer MICRO-UNITS PER TOKEN (1e-6 currency units), so a provider
- * charging $3.00 per million input tokens has `basePrice: 3`. Integers keep the
- * money path exact; see the file header for why floats are refused.
- */
-export interface ProviderEconomicsV1 {
-  readonly schema: "provider-economics-v1";
-  /** The `ProviderProfileV1.id` these economics belong to. */
-  readonly profileId: string;
-  /** Profile version — economics are versioned WITH the profile they price. */
-  readonly profileVersion: string;
-  /** Uncached price per token, integer micro-units. The savings baseline. */
-  readonly basePrice: number;
-  /** Cache-READ price per token, integer micro-units. Normally < basePrice. */
-  readonly readPrice: number;
-  /** Cache-WRITE price per token, integer micro-units. Normally > basePrice. */
-  readonly writePrice: number;
-  /** Cache entry lifetime in ms. A prefix older than this cannot be read back. */
-  readonly ttlMs: number;
-  /** Minimum cacheable prefix in tokens; a shorter prefix is never cached. */
-  readonly minPrefix: number;
-  /**
-   * Conformance fixture ID proving this profile's exclusion set is safe, or
-   * `null` when the profile declares NO exclusions (nothing to prove). A profile
-   * WITH exclusions and a null/blank id is rejected — see `validateEconomics`.
-   */
-  readonly exclusionFixtureId: string | null;
-}
+// `ProviderEconomicsV1` is defined in `./types.js` so it can ride on
+// `ProviderProfileV1` without a type-only module cycle. Re-exported forward here
+// so every existing consumer import path (`from "./economics.js"`) is unchanged.
+export type { ProviderEconomicsV1 } from "./types.js";
 
 /** Observed (or shadow) cache traffic for one economics computation. */
 export interface CacheUsageV1 {