pi-mega-compact 0.20.11 → 0.20.13

package/extensions/dashboard-server/api-contracts/vector-cortex-cache.ts

@@ -0,0 +1,53 @@
+/**
+ * api-contracts/vector-cortex-cache.ts — VC7A frozen-range-crystal API contract.
+ *
+ * Split from vector-cortex-heal.ts (a separate concern, not a size overflow):
+ * crystals are a derived CACHE, not a repair path, and keeping the contract in
+ * its own file leaves both well under the 400-line extension limit as VC7B lands.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ */
+
+/**
+ * Reader-only frozen-crystal cache diagnostics view for
+ * GET /api/vector-cortex/cache-crystals (VC7A).
+ *
+ * COUNTS + BYTES ONLY. A crystal IS a rendered prompt, which makes this the one
+ * surface where an unguarded payload field would dump the entire framed
+ * conversation into the dashboard. So the view carries no frozen bytes, no
+ * covered source ranges, no span or covered digests, no session ids, and no
+ * request digests (SECURITY_PRIVACY — the exact ledger is not diagnostic data).
+ * Only aggregate counters and the observable byte volumes are exposed; per-key
+ * detail lives in the structured event log, not here.
+ */
+export interface VectorCortexCrystalsView {
+  /** Whether the VC7A frozen-range-crystal flag is enabled. */
+  readonly enabled: boolean;
+  /**
+   * Runtime triad mode: "A" crystal store hit, "B" miss/collision forced a
+   * fresh deterministic render, "C" store unavailable so the cache is bypassed
+   * and nothing is served from it.
+   */
+  readonly mode: "A" | "B" | "C";
+  /** Distinct crystals currently held by the store. */
+  readonly crystalCount: number;
+  /** Aggregate frozen bytes held across all crystals. */
+  readonly totalBytes: number;
+  /** Reads answered from the store (mode A). */
+  readonly hits: number;
+  /** Reads with no stored crystal, forcing a fresh render (mode B). */
+  readonly misses: number;
+  /** Bytes served from hits — the cache's observable benefit. */
+  readonly hitBytes: number;
+  /** First writes that actually published a crystal. */
+  readonly writes: number;
+  /** Idempotent re-writes of byte-identical crystals. */
+  readonly duplicateWrites: number;
+  /** Same-key, different-bytes writes refused (CRY_KEY_COLLISION). */
+  readonly collisions: number;
+  /** Last failure reason (a CRY_* code), or null if none yet. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}

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

@@ -60,6 +60,10 @@ import {
 // VC6C repair lives in its own module (routes-vector-cortex-repair.ts) so the
 // heal route file stays well under the 400-line extension soft limit.
 import { handleVectorCortexRepair } from "./routes-vector-cortex-repair.js";
+// VC7A frozen-range crystals likewise get their own module so the cache seam
+// 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";
 
 /**
  * Dispatch a request through every registered route handler.
@@ -114,5 +118,6 @@ export function dispatchRoutes(
 	if (handleVectorCortexClosureProof(req, res, ctx)) return true;
 	if (handleVectorCortexRestore(req, res, ctx)) return true;
 	if (handleVectorCortexRepair(req, res, ctx)) return true;
+	if (handleVectorCortexCrystals(req, res, ctx)) return true;
 	return false;
 }

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

@@ -156,5 +156,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Self-healing derived-state controller: detects gaps between each derived subsystem's high-water mark and the durable authority high-water, then rebuilds derived state by copy -> root-digest verification -> atomic pointer switch, so a partially rebuilt subsystem is never made visible. A targeted single-subsystem rebuild is mode A; an ambiguous gap escalates to a full deterministic rebuild (mode B); if both rebuild paths fail the derived state is disabled rather than served stale (mode C). Rebuilds are rate-limited to one per subsystem per 5 minutes with deterministic exponential backoff, so a persistently failing subsystem cannot spin. OFF = byte-identical predecessor (VC6B); no controller runs, so the dashboard reports mode C.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC7A",
+			"VC7A Frozen Range Crystals",
+			"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,
+		),
 	],
 };

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

@@ -0,0 +1,74 @@
+/**
+ * dashboard-server/routes-vector-cortex-crystals.ts — VC7A frozen-range-crystal
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/cache-crystals returning the crystal
+ * store's aggregate diagnostics: whether the flag is enabled, the runtime triad
+ * mode, how many crystals are held and at what byte volume, hit/miss/hit-byte
+ * counters, write/duplicate/collision counters, and the last CRY_* failure code.
+ *
+ * COUNTS + BYTES + ERROR CODES ONLY. A crystal is a FROZEN RENDERED PROMPT, so
+ * this is the surface where a careless payload field would leak the whole framed
+ * conversation. It NEVER exposes frozen bytes, covered ranges, span or covered
+ * digests, request digests, session ids, or key digests (reader-only,
+ * SECURITY_PRIVACY — per-key detail belongs in the structured event log). There
+ * is no mutation seam either: crystals are written by the render path, never by
+ * a dashboard request, and the store is write-once by construction, so a
+ * dashboard-driven write could not overwrite anything even if it existed.
+ * Non-GET is rejected outright.
+ *
+ * Split into its own file (rather than grown into routes-vector-cortex-repair.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 { VC7A_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexCrystalsView } from "./api-contracts/vector-cortex-cache.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/cache-crystals (VC7A).
+ *
+ * Counts, byte volumes, and CRY_* codes only — a static reader-only aggregate
+ * seam with the same shape as the VC6A/VC6B/VC6C handlers.
+ */
+export function handleVectorCortexCrystals(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/cache-crystals") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC7A_ENABLED();
+  // Flag-off routes to mode C: with VC7A off nothing is served from the crystal
+  // cache, which is exactly the spec's "cache bypass" outcome. Reporting A (hit)
+  // or B (fresh render forced by a miss) would imply a cache path that is not
+  // wired at all. Mirrors how VC6C's OFF view reports the mode it actually takes.
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexCrystalsView = {
+    enabled,
+    mode,
+    crystalCount: 0,
+    totalBytes: 0,
+    hits: 0,
+    misses: 0,
+    hitBytes: 0,
+    writes: 0,
+    duplicateWrites: 0,
+    collisions: 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.11",
+  "version": "0.20.13",
   "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-breakers.ts

@@ -0,0 +1,32 @@
+/**
+ * config/vector-cortex-breakers.ts — breaker state machine constants.
+ *
+ * Extracted from vector-cortex.ts to keep that file under the 300-line soft
+ * limit (soft-as-hard gate). These constants are normative in
+ * TRIAD_RESILIENCE.md §breaker and consumed by VC0C's breaker seam.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/** Rolling eligibility window (milliseconds). */
+export const BREAKER_WINDOW_MS = 60_000;
+/** Minimum attempts before a breaker may trip or promote. */
+export const BREAKER_MIN_ATTEMPTS = 20;
+/** Performance trip: ≥ this many failures in window, or ≥ this fraction. */
+export const BREAKER_PERF_FAILURES = 5;
+export const BREAKER_PERF_FAILURE_RATE = 0.1;
+/** Correctness trip trips on the first correctness failure. */
+export const BREAKER_CORRECTNESS_FAILURES = 1;
+/** Cooldown before an open breaker may probe (milliseconds). */
+export const BREAKER_COOLDOWN_MS = 30_000;
+/** Consecutive successful probes required to advance a state. */
+export const BREAKER_PROBE_COUNT = 3;
+/** Exponential retry base: 30s * 2^attempt, capped, ±10% jitter. */
+export const BREAKER_RETRY_BASE_MS = 30_000;
+export const BREAKER_RETRY_CAP_MS = 15 * 60_000;
+export const BREAKER_RETRY_JITTER = 0.1;
+/** Promotion hysteresis: failure rate must be < this and p95 within budget. */
+export const BREAKER_HYSTERESIS_FAILURE_RATE = 0.02;
+export const BREAKER_HYSTERESIS_BUDGET_P95_MS = 50;
+/** Minimum healthy residence before a further promotion (milliseconds). */
+export const BREAKER_MIN_HEALTHY_RESIDENCE_MS = 5 * 60_000;

package/src/config/vector-cortex.ts

@@ -258,30 +258,35 @@ export const VC6B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6B");
  */
 export const VC6C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6C");
 
-// ---------------------------------------------------------------------------
-// Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
-// Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.
-// ---------------------------------------------------------------------------
+/**
+ * VC7A — frozen range crystals. Default ON. `MEGACOMPACT_VC7A=0` disables and is
+ * byte-identical to the predecessor (VC6C): the `encodeCrystalKey` /
+ * `CrystalStore` arithmetic STILL RUNS (it is PURE — a canonical length-prefixed
+ * encoding plus SHA-256, with no clock, storage, or network), so a crystal is
+ * keyed identically and a same-key/different-bytes write is still refused with
+ * the flag off. The flag gates ONLY the `vector_cortex_crystal_written` /
+ * `vector_cortex_crystal_collision` events and the cache-crystals dashboard seam,
+ * which reports `enabled:false` + mode C when off. Flag OFF never gates the
+ * crystal/store arithmetic, so flag-off outbound/predecessor golden bytes match
+ * exactly. This flag MUST also be a dashboard SETTINGS toggle (visible in config
+ * UI, never in EXCLUDED_SETTINGS), mirroring VC4A..VC6C.
+ */
+export const VC7A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC7A");
 
-/** Rolling eligibility window (milliseconds). */
-export const BREAKER_WINDOW_MS = 60_000;
-/** Minimum attempts before a breaker may trip or promote. */
-export const BREAKER_MIN_ATTEMPTS = 20;
-/** Performance trip: ≥ this many failures in window, or ≥ this fraction. */
-export const BREAKER_PERF_FAILURES = 5;
-export const BREAKER_PERF_FAILURE_RATE = 0.1;
-/** Correctness trip trips on the first correctness failure. */
-export const BREAKER_CORRECTNESS_FAILURES = 1;
-/** Cooldown before an open breaker may probe (milliseconds). */
-export const BREAKER_COOLDOWN_MS = 30_000;
-/** Consecutive successful probes required to advance a state. */
-export const BREAKER_PROBE_COUNT = 3;
-/** Exponential retry base: 30s * 2^attempt, capped, ±10% jitter. */
-export const BREAKER_RETRY_BASE_MS = 30_000;
-export const BREAKER_RETRY_CAP_MS = 15 * 60_000;
-export const BREAKER_RETRY_JITTER = 0.1;
-/** Promotion hysteresis: failure rate must be < this and p95 within budget. */
-export const BREAKER_HYSTERESIS_FAILURE_RATE = 0.02;
-export const BREAKER_HYSTERESIS_BUDGET_P95_MS = 50;
-/** Minimum healthy residence before a further promotion (milliseconds). */
-export const BREAKER_MIN_HEALTHY_RESIDENCE_MS = 5 * 60_000;
+// 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 {
+  BREAKER_WINDOW_MS,
+  BREAKER_MIN_ATTEMPTS,
+  BREAKER_PERF_FAILURES,
+  BREAKER_PERF_FAILURE_RATE,
+  BREAKER_CORRECTNESS_FAILURES,
+  BREAKER_COOLDOWN_MS,
+  BREAKER_PROBE_COUNT,
+  BREAKER_RETRY_BASE_MS,
+  BREAKER_RETRY_CAP_MS,
+  BREAKER_RETRY_JITTER,
+  BREAKER_HYSTERESIS_FAILURE_RATE,
+  BREAKER_HYSTERESIS_BUDGET_P95_MS,
+  BREAKER_MIN_HEALTHY_RESIDENCE_MS,
+} from "./vector-cortex-breakers.js";

package/src/config.ts

@@ -172,6 +172,7 @@ export {
   VC6A_ENABLED,
   VC6B_ENABLED,
   VC6C_ENABLED,
+  VC7A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -0,0 +1,126 @@
+/**
+ * cache/_crystal-fixture.ts — conformance fixture I/O for VC7A crystal rows.
+ *
+ * Sibling of `../heal/_restore-fixture.ts`, same job for a different corpus:
+ * turn canonical JSON back into the REAL production types the cache modules
+ * consume. Fixtures cannot express bigints, so `dependencyHighWater` and the
+ * span seq bounds are stored as numbers and converted here — if that conversion
+ * were lossy the encoded keys would diverge and the acceptance rows would fail
+ * loudly, which is exactly the guarantee an identity sprint needs.
+ *
+ * No mocks, no stubs, no parallel "test shape": the decoded objects ARE
+ * `CrystalKeyV1` / `DagSpan` and are fed verbatim into `encodeCrystalKey` and
+ * `CrystalStore`.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+
+import type { CrystalKeyV1, DagSpan } from "./types.js";
+import { computeCoveredDigest } from "./crystal.js";
+import { V2, readManifest } from "../heal/_acceptance-fixture.js";
+
+/** A `DagSpan` as it appears in JSON: seq bounds are numbers, not bigints. */
+export interface CrystalFxSpan {
+  sessionId: string;
+  startSeq: number;
+  endSeq: number;
+  startByte: number;
+  endByte: number;
+  digest: string;
+}
+
+export interface CrystalFxKey {
+  profileId: string;
+  profileVersion: string;
+  requestDigest: string;
+  rendererVersion: string;
+  dependencyHighWater: number;
+  sourceRanges: CrystalFxSpan[];
+}
+
+export interface CrystalFxInput {
+  scenario: "key" | "compare" | "store";
+  mode: string;
+  key: CrystalFxKey;
+  other?: CrystalFxKey;
+  unrelatedAppend?: CrystalFxSpan;
+  bytes?: string;
+  secondBytes?: string;
+}
+
+export interface CrystalFxExpected {
+  ok: boolean;
+  code?: string;
+  sameKey?: boolean;
+  written?: boolean;
+  crystalCount?: number;
+  rangeCount?: number;
+  sortedSessions?: string[];
+  sortedStartBytes?: number[];
+  mode?: "A" | "B" | "C";
+}
+
+export interface CrystalFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: CrystalFxInput;
+  expected: CrystalFxExpected;
+}
+
+/** Read one registered cache-crystal fixture (asserting it IS registered). */
+export function crystalFixture(id: string): CrystalFx {
+  const m = readManifest();
+  const row = m.fixtures.find((f) => f.id === id && f.path.startsWith("cache-crystals/"));
+  assert.ok(row, `fixture ${id} registered under cache-crystals/ in manifest`);
+  return JSON.parse(readFileSync(join(V2, row!.path), "utf8")) as CrystalFx;
+}
+
+/** JSON number seq bounds -> the bigint bounds `DagSpan` declares. */
+export function decodeSpan(s: CrystalFxSpan): DagSpan {
+  return {
+    sessionId: s.sessionId,
+    startSeq: BigInt(s.startSeq),
+    endSeq: BigInt(s.endSeq),
+    startByte: s.startByte,
+    endByte: s.endByte,
+    digest: s.digest as DagSpan["digest"],
+  };
+}
+
+/**
+ * Reconstitute a real `CrystalKeyV1`. `coveredDigest` is DERIVED from the ranges
+ * rather than carried in the corpus: the covered digest is a function of the
+ * ranges, so storing it would let a fixture assert a self-inconsistent identity
+ * that the encoder would silently re-derive anyway.
+ */
+export function decodeKey(k: CrystalFxKey): CrystalKeyV1 {
+  const sourceRanges = k.sourceRanges.map(decodeSpan);
+  return {
+    profileId: k.profileId,
+    profileVersion: k.profileVersion,
+    requestDigest: k.requestDigest,
+    rendererVersion: k.rendererVersion,
+    dependencyHighWater: BigInt(k.dependencyHighWater),
+    sourceRanges,
+    coveredDigest: computeCoveredDigest(sourceRanges),
+  };
+}
+
+/** Flag-pinned wrapper: VC7A gated by MEGACOMPACT_VC7A (defaults ON). */
+export function withVc7aFlag(value: string, fn: () => void): () => void {
+  return (): void => {
+    const saved = process.env.MEGACOMPACT_VC7A;
+    process.env.MEGACOMPACT_VC7A = value;
+    try {
+      fn();
+    } finally {
+      if (saved === undefined) delete process.env.MEGACOMPACT_VC7A;
+      else process.env.MEGACOMPACT_VC7A = saved;
+    }
+  };
+}

package/src/vector-cortex/cache/crystal-emit.ts

@@ -0,0 +1,99 @@
+/**
+ * vector-cortex/cache/crystal-emit.ts — VC7A event reporter seam.
+ *
+ * Mirrors `../heal/restore-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_crystal_written`   — a crystal was frozen and published.
+ *   - `vector_cortex_crystal_collision` — a same-key, different-bytes write was
+ *                                         refused.
+ *
+ * FLAG SEMANTICS. `encodeCrystalKey` and every `CrystalStore` operation are PURE
+ * and run REGARDLESS of `MEGACOMPACT_VC7A`. The flag gates ONLY this reporting +
+ * dashboard seam: with the flag off we still key crystals identically, still
+ * write once, and still refuse collisions — we just do not announce it under the
+ * VC7A event namespace, and the dashboard reports `enabled:false` + mode C. That
+ * is what makes flag-off byte-identical to VC6C: the arithmetic is never skipped,
+ * only the emission.
+ *
+ * PAYLOAD DISCIPLINE. These events carry the KEY DIGEST, byte COUNTS, and the
+ * failure code — never the frozen bytes, never covered source text, never the
+ * span digests of user content. A crystal is a rendered prompt: an unguarded
+ * `payload` field here would dump the entire framed conversation into a log file
+ * (SECURITY_PRIVACY — the exact ledger is not diagnostic data).
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+
+import { VC7A_ENABLED } from "../../config/vector-cortex.js";
+import type { CrystalEventName, CrystalFailureCode, CrystalMode } from "./types.js";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type CrystalEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit: CrystalEmit | undefined, fn: (emit: CrystalEmit) => void): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** The event names VC7A emits, exported for the dashboard seam and tests. */
+export const CRYSTAL_EVENT_NAMES: readonly CrystalEventName[] = [
+  "vector_cortex_crystal_written",
+  "vector_cortex_crystal_collision",
+] as const;
+
+/**
+ * Report a published crystal. Key digest + byte count + mode only — enough to
+ * see whether the cache is filling and being hit, without disclosing what was
+ * frozen.
+ */
+export function reportCrystalWritten(
+  emit: CrystalEmit | undefined,
+  payload: {
+    readonly keyDigest: string;
+    readonly byteCount: number;
+    readonly mode: CrystalMode;
+  },
+): void {
+  if (!VC7A_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_crystal_written", {
+      ts: undefined,
+      event: "vector_cortex_crystal_written",
+      keyDigest: payload.keyDigest,
+      byteCount: payload.byteCount,
+      mode: payload.mode,
+    }),
+  );
+}
+
+/**
+ * Report a refused write. A collision means two renders of the SAME identity
+ * disagreed — a determinism bug — so the code is surfaced rather than swallowed.
+ * Suppressed under flag-off.
+ */
+export function reportCrystalCollision(
+  emit: CrystalEmit | undefined,
+  payload: {
+    readonly keyDigest: string;
+    readonly code: CrystalFailureCode;
+    readonly mode: CrystalMode;
+  },
+): void {
+  if (!VC7A_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_crystal_collision", {
+      ts: undefined,
+      event: "vector_cortex_crystal_collision",
+      keyDigest: payload.keyDigest,
+      code: payload.code,
+      mode: payload.mode,
+    }),
+  );
+}