pi-mega-compact 0.20.70 → 0.20.71

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 {

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

@@ -18,6 +18,7 @@
 
 import {
   PRO_PROFILE_UNKNOWN,
+  type ProviderEconomicsV1,
   type ProviderProfileBundle,
   type ProviderProfileResult,
   type ProviderProfileV1,
@@ -60,6 +61,7 @@ function profile(
   id: string,
   version: string,
   excludedJsonPointers: ProviderProfileV1["excludedJsonPointers"],
+  economics: ProviderProfileV1["economics"],
 ): ProviderProfileV1 {
   return {
     schema: "provider-profile-v1",
@@ -67,42 +69,111 @@ function profile(
     version,
     hashMode: "entire-canonical-request",
     excludedJsonPointers,
+    economics,
   };
 }
 
+/**
+ * Build integer micro-unit economics for a base profile (VC7B). A cache WRITE
+ * costs more than an uncached token, a cache READ costs less — the standard
+ * provider-prompt-cache shape. `exclusionFixtureId` mirrors the profile's own
+ * exclusion fixture (or null when the profile has none to prove).
+ */
+function econ(
+  id: string,
+  version: string,
+  exclusionFixtureId: string | null,
+  values: {
+    basePrice: number;
+    readPrice: number;
+    writePrice: number;
+    ttlMs: number;
+    minPrefix: number;
+  },
+): ProviderEconomicsV1 {
+  return {
+    schema: "provider-economics-v1",
+    profileId: id,
+    profileVersion: version,
+    basePrice: values.basePrice,
+    readPrice: values.readPrice,
+    writePrice: values.writePrice,
+    ttlMs: values.ttlMs,
+    minPrefix: values.minPrefix,
+    exclusionFixtureId,
+  };
+}
+
+/** Representative integer micro-unit economics for the Anthropic opus base tier. */
+const OPUS_ECON: ProviderEconomicsV1 = econ(
+  "anthropic-claude-opus",
+  "v1",
+  null,
+  { basePrice: 15, readPrice: 2, writePrice: 19, ttlMs: 300_000, minPrefix: 1024 },
+);
+
+/** Representative integer micro-unit economics for the Anthropic sonnet base tier. */
+const SONNET_ECON: ProviderEconomicsV1 = econ(
+  "anthropic-claude-sonnet",
+  "v1",
+  null,
+  { basePrice: 3, readPrice: 0, writePrice: 4, ttlMs: 300_000, minPrefix: 1024 },
+);
+
+/** Representative integer micro-unit economics for the OpenAI gpt base tier. */
+const GPT_ECON: ProviderEconomicsV1 = econ(
+  "openai-gpt",
+  "v1",
+  null,
+  { basePrice: 5, readPrice: 1, writePrice: 6, ttlMs: 300_000, minPrefix: 1024 },
+);
+
+/** The gemini profile's versioned, fixture-proven exclusion. */
+const GEMINI_EXCLUSIONS: ProviderProfileV1["excludedJsonPointers"] = [
+  {
+    pointer: "/requestId",
+    fixtureId: "PRO-EXCLUDE-010",
+    proofDigest: "sha256:excluded-request-id-proof",
+  },
+];
+
+/** Representative integer micro-unit economics for the gemini base tier. */
+const GEMINI_ECON: ProviderEconomicsV1 = econ(
+  "google-gemini",
+  "v1",
+  "PRO-EXCLUDE-010",
+  { basePrice: 3, readPrice: 1, writePrice: 4, ttlMs: 300_000, minPrefix: 1024 },
+);
+
 /**
  * The fixture-backed base profiles. Each entry is the REAL bundle the renderer
  * resolves; the parallel conformance fixtures prove the cache-identity behavior.
  */
 const BASE_PROFILES: readonly ProviderProfileBundle[] = [
   {
-    profile: profile("anthropic-claude-opus", "v1", []),
+    profile: profile("anthropic-claude-opus", "v1", [], OPUS_ECON),
     role: BASE_ROLE,
     tool: BASE_TOOL,
     cache: baseCache(["systemPromptPrepend", "tools", "nodes"]),
   },
   {
-    profile: profile("anthropic-claude-sonnet", "v1", []),
+    profile: profile("anthropic-claude-sonnet", "v1", [], SONNET_ECON),
     role: BASE_ROLE,
     tool: BASE_TOOL,
     cache: baseCache(["systemPromptPrepend", "tools", "nodes"]),
   },
   {
-    profile: profile("openai-gpt", "v1", []),
+    profile: profile("openai-gpt", "v1", [], GPT_ECON),
     role: BASE_ROLE,
     tool: BASE_TOOL,
     cache: baseCache(["systemPromptPrepend", "tools", "nodes"]),
   },
   {
     // A profile that proves a fixture-excluded pointer: a provider whose
-    // request-id header cannot affect cache identity. Excluded + versioned.
-    profile: profile("google-gemini", "v1", [
-      {
-        pointer: "/requestId",
-        fixtureId: "PRO-EXCLUDE-010",
-        proofDigest: "sha256:excluded-request-id-proof",
-      },
-    ]),
+    // request-id header cannot affect cache identity. Excluded + versioned, and
+    // the exclusion fixture id is carried into economics so the proof is
+    // honored (an unproven exclusion would fail economics validation).
+    profile: profile("google-gemini", "v1", GEMINI_EXCLUSIONS, GEMINI_ECON),
     role: BASE_ROLE,
     tool: BASE_TOOL,
     cache: baseCache(["systemPromptPrepend", "tools", "nodes"]),

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

@@ -35,6 +35,37 @@ export interface ProviderProfileExclusion {
   readonly proofDigest: string;
 }
 
+/**
+ * Cache economics attached to a provider profile (VC7B).
+ *
+ * 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 `economics.ts` 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;
+}
+
 /**
  * The provider-profile contract. A renderer consumes a profile to decide how the
  * rendered prompt is serialized into the canonical outbound request without
@@ -47,6 +78,12 @@ export interface ProviderProfileV1 {
   readonly hashMode: ProviderHashMode;
   /** Versioned, fixture-proven exclusions (empty = hash the whole request). */
   readonly excludedJsonPointers: readonly ProviderProfileExclusion[];
+  /**
+   * VC7B cache economics pricing this profile's frozen-render reuse. Every base
+   * profile carries economics so the cache-economics aggregate is computable
+   * without a side table; a profile WITHOUT economics is simply never cached.
+   */
+  readonly economics: ProviderEconomicsV1 | null;
 }
 
 /**