pi-mega-compact 0.20.10 → 0.20.12

package/dist/config/vector-cortex-breakers.js

@@ -0,0 +1,31 @@
+/**
+ * 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/dist/config/vector-cortex.js

@@ -237,29 +237,20 @@ export const VC6B_ENABLED = () => sprintFlag("MEGACOMPACT_VC6B");
  * mirroring VC4A/VC4B/VC4C/VC5A/VC5B/VC5C/VC6A/VC6B.
  */
 export const VC6C_ENABLED = () => sprintFlag("MEGACOMPACT_VC6C");
-// ---------------------------------------------------------------------------
-// Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
-// Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.
-// ---------------------------------------------------------------------------
-/** 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;
+/**
+ * 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 = () => sprintFlag("MEGACOMPACT_VC7A");
+// 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/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, 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 "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, 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 "./config/vector-cortex.js";

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

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export {};

package/dist/extensions/dashboard-server/route-dispatch.js

@@ -12,6 +12,10 @@ import { handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGame
 // 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.
  * Returns true if a handler claimed the request (ended the response).
@@ -105,5 +109,7 @@ export function dispatchRoutes(req, res, ctx) {
         return true;
     if (handleVectorCortexRepair(req, res, ctx))
         return true;
+    if (handleVectorCortexCrystals(req, res, ctx))
+        return true;
     return false;
 }

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

@@ -42,5 +42,6 @@ export const VECTOR_CORTEX_SETTINGS = {
         boolDirect("MEGACOMPACT_VC6A", "VC6A Advanced Closure Optimization", "Advanced closure optimization: deterministically reduces the already-mandatory VC4C closure by transitive reduction over depends edges, emitting a ClosureProofV2 receipt per closure and a verifier that replays reductions against the conservative oracle (HEAL_PROOF_SET_MISMATCH on selected-set divergence). Protected edges (tool-pair / anchor / contradiction / sole-dependency) are never removed. The optimized selected set is byte-identical to the conservative closure. OFF = byte-identical predecessor (VC5C); arithmetic runs, only the reporter + dashboard seam is suppressed.", true),
         boolDirect("MEGACOMPACT_VC6B", "VC6B Exact Source Restoration", "Exact source restoration: restores the original bytes of closure spans ONLY from an exact shard (mode A) or a verified ledger range scan (mode B) — never inferred, reconstructed, or paraphrased from embeddings or semantic text. Requests are hard-bounded at 64 spans / 4MiB (HEAL_RESTORE_LIMIT); every span's SHA-256 is recomputed and bytes are inserted only after all requested span metadata validates, so a single bad span fails the whole request closed (HEAL_RESTORE_DIGEST_MISMATCH, HEAL_RESTORE_RANGE_MISMATCH). When no exact source exists (HEAL_RESTORE_SOURCE_MISSING) the old context is omitted and the loss is disclosed (mode C) rather than filled in. OFF = byte-identical predecessor (VC6A).", true),
         boolDirect("MEGACOMPACT_VC6C", "VC6C Self-Healing Derived State", "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/dist/extensions/dashboard-server/routes-vector-cortex-crystals.js

@@ -0,0 +1,65 @@
+/**
+ * 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 { VC7A_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.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, res, _ctx) {
+    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 = enabled ? "A" : "C";
+    const body = {
+        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/dist/src/config/vector-cortex-breakers.js

@@ -0,0 +1,31 @@
+/**
+ * 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/dist/src/config/vector-cortex.js

@@ -237,29 +237,20 @@ export const VC6B_ENABLED = () => sprintFlag("MEGACOMPACT_VC6B");
  * mirroring VC4A/VC4B/VC4C/VC5A/VC5B/VC5C/VC6A/VC6B.
  */
 export const VC6C_ENABLED = () => sprintFlag("MEGACOMPACT_VC6C");
-// ---------------------------------------------------------------------------
-// Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
-// Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.
-// ---------------------------------------------------------------------------
-/** 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;
+/**
+ * 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 = () => sprintFlag("MEGACOMPACT_VC7A");
+// 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/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, 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 "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, 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 "./config/vector-cortex.js";

package/dist/src/vector-cortex/cache/_crystal-fixture.js

@@ -0,0 +1,71 @@
+/**
+ * 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 { computeCoveredDigest } from "./crystal.js";
+import { V2, readManifest } from "../heal/_acceptance-fixture.js";
+/** Read one registered cache-crystal fixture (asserting it IS registered). */
+export function crystalFixture(id) {
+    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"));
+}
+/** JSON number seq bounds -> the bigint bounds `DagSpan` declares. */
+export function decodeSpan(s) {
+    return {
+        sessionId: s.sessionId,
+        startSeq: BigInt(s.startSeq),
+        endSeq: BigInt(s.endSeq),
+        startByte: s.startByte,
+        endByte: s.endByte,
+        digest: s.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) {
+    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, fn) {
+    return () => {
+        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/dist/src/vector-cortex/cache/crystal-emit.js

@@ -0,0 +1,76 @@
+/**
+ * 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";
+/** 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 VC7A emits, exported for the dashboard seam and tests. */
+export const CRYSTAL_EVENT_NAMES = [
+    "vector_cortex_crystal_written",
+    "vector_cortex_crystal_collision",
+];
+/**
+ * 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, payload) {
+    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, payload) {
+    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,
+    }));
+}

package/dist/src/vector-cortex/cache/crystal.js

@@ -0,0 +1,201 @@
+/**
+ * vector-cortex/cache/crystal.ts — canonical crystal key encoding (VC7A).
+ *
+ * Turns a `CrystalKeyV1` into a single stable digest. Everything about the
+ * encoding exists to make two properties simultaneously true:
+ *
+ *   1. IDENTICAL INPUTS ⇒ IDENTICAL KEY, regardless of how the caller ordered
+ *      its ranges or which host produced them. Hence the explicit sort and the
+ *      length-prefixed field framing below.
+ *   2. ANY IDENTITY CHANGE ⇒ DIFFERENT KEY, with no accidental aliasing. Hence
+ *      length prefixes rather than delimiters: a delimiter-joined encoding lets
+ *      an attacker (or an unlucky session name) push a separator into a field
+ *      and forge a collision — `("a|b", "c")` and `("a", "b|c")` hash the same.
+ *      Prefixing every variable-length field with its byte length makes the
+ *      encoding injective, so a collision requires an actual SHA-256 collision.
+ *
+ * WHAT IS DELIBERATELY ABSENT. The global ledger frontier. It is not a
+ * parameter, it is not readable from here, and there is no code path that could
+ * fold it in. An unrelated append advances the frontier constantly; including it
+ * would invalidate every crystal on every turn and the cache would never hit.
+ * The key covers what the render DEPENDED ON, not what the world has since done.
+ *
+ * OVERLAP IS REJECTED, NOT MERGED. Two overlapping ranges in the same session
+ * make "the covered bytes" ambiguous: the overlap region would be hashed twice,
+ * and if the two spans pinned different digests the key would silently encode a
+ * contradiction. `CRY_RANGE_OVERLAP` fails the key closed instead. Ranges in
+ * DIFFERENT sessions never conflict — they cover disjoint byte streams by
+ * construction — so cross-session keys are legal and common.
+ *
+ * PURE. No clock, no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011). Runs identically with `MEGACOMPACT_VC7A` on or off — the flag
+ * gates only the reporter/dashboard seam in `crystal-emit.ts`.
+ */
+import { createHash } from "node:crypto";
+import { CRYSTAL_LIMIT_BYTES, CRYSTAL_LIMIT_RANGES, } from "./types.js";
+/** Encoding version, folded into the digest so a future change cannot alias. */
+const KEY_ENCODING_VERSION = "crystal-key-v1";
+/**
+ * Length-prefixed field append. `<byteLength>:<bytes>` makes the concatenation
+ * injective, so no combination of field contents can impersonate another.
+ */
+function field(parts, value) {
+    parts.push(`${Buffer.byteLength(value, "utf8")}:${value}`);
+}
+/**
+ * Total order over covered ranges: session, then start seq, then start byte.
+ *
+ * Ordering by SOURCE START (not by insertion, not by digest) is what makes the
+ * key independent of how the planner happened to enumerate its spans. `sessionId`
+ * leads because seq numbers are only comparable within a session.
+ */
+export function compareSpans(a, b) {
+    if (a.sessionId !== b.sessionId)
+        return a.sessionId < b.sessionId ? -1 : 1;
+    if (a.startSeq !== b.startSeq)
+        return a.startSeq < b.startSeq ? -1 : 1;
+    if (a.startByte !== b.startByte)
+        return a.startByte - b.startByte;
+    if (a.endSeq !== b.endSeq)
+        return a.endSeq < b.endSeq ? -1 : 1;
+    return a.endByte - b.endByte;
+}
+/** Sort covered ranges into canonical order (never mutates the input array). */
+export function sortSpans(spans) {
+    return [...spans].sort(compareSpans);
+}
+/** A range is malformed if either bound runs backwards or a byte bound is negative. */
+function isMalformed(s) {
+    return (s.endSeq < s.startSeq ||
+        s.startByte < 0 ||
+        s.endByte < s.startByte ||
+        !Number.isSafeInteger(s.startByte) ||
+        !Number.isSafeInteger(s.endByte));
+}
+/**
+ * Byte-range overlap between two spans of the SAME session. Byte bounds are
+ * half-open (`[startByte, endByte)`), so touching ranges (`a.end === b.start`)
+ * are adjacent, not overlapping, and are legal.
+ */
+function overlaps(a, b) {
+    return a.sessionId === b.sessionId && a.startByte < b.endByte && b.startByte < a.endByte;
+}
+/**
+ * Validate covered ranges: non-empty, bounded, well-formed, and disjoint within
+ * each session. Returns deduplicated codes in a deterministic order.
+ */
+export function validateRanges(spans) {
+    const codes = new Set();
+    if (spans.length === 0)
+        codes.add("CRY_RANGE_EMPTY");
+    if (spans.length > CRYSTAL_LIMIT_RANGES)
+        codes.add("CRY_KEY_LIMIT");
+    let totalBytes = 0;
+    for (const s of spans) {
+        if (isMalformed(s))
+            codes.add("CRY_RANGE_INVALID");
+        else
+            totalBytes += s.endByte - s.startByte;
+    }
+    if (totalBytes > CRYSTAL_LIMIT_BYTES)
+        codes.add("CRY_KEY_LIMIT");
+    // Sorted order makes overlap a neighbour check within each session run.
+    const sorted = sortSpans(spans);
+    for (let i = 1; i < sorted.length; i += 1) {
+        const prev = sorted[i - 1];
+        const cur = sorted[i];
+        if (prev !== undefined && cur !== undefined && overlaps(prev, cur)) {
+            codes.add("CRY_RANGE_OVERLAP");
+            break;
+        }
+    }
+    const order = [
+        "CRY_RANGE_EMPTY",
+        "CRY_RANGE_INVALID",
+        "CRY_RANGE_OVERLAP",
+        "CRY_KEY_LIMIT",
+    ];
+    return order.filter((c) => codes.has(c));
+}
+/**
+ * The covered-bytes digest: SHA-256 over the SORTED ranges' identities and their
+ * pinned span digests, `sha256:` prefixed (matching the `DagSpan.digest`
+ * convention the ranges themselves carry).
+ *
+ * The span digests are what make this sensitive to a single covered BYTE: the
+ * ranges alone would be identical if a byte inside an unchanged range mutated,
+ * but the span's pinned digest would not be (CRY-COVERED-002).
+ */
+export function computeCoveredDigest(spans) {
+    const h = createHash("sha256");
+    for (const s of sortSpans(spans)) {
+        const parts = [];
+        field(parts, s.sessionId);
+        field(parts, s.startSeq.toString());
+        field(parts, s.endSeq.toString());
+        field(parts, String(s.startByte));
+        field(parts, String(s.endByte));
+        field(parts, s.digest);
+        h.update(parts.join(""), "utf8");
+    }
+    return `sha256:${h.digest("hex")}`;
+}
+/**
+ * Canonical key bytes. Field order is fixed and every field is length-prefixed;
+ * the ranges are emitted in canonical sort order with an explicit count so a
+ * key with N ranges can never encode the same bytes as one with M.
+ */
+export function encodeCrystalKeyBytes(key) {
+    const parts = [];
+    field(parts, KEY_ENCODING_VERSION);
+    field(parts, key.profileId);
+    field(parts, key.profileVersion);
+    field(parts, key.requestDigest);
+    field(parts, key.rendererVersion);
+    field(parts, key.dependencyHighWater.toString());
+    field(parts, key.coveredDigest);
+    const sorted = sortSpans(key.sourceRanges);
+    field(parts, String(sorted.length));
+    for (const s of sorted) {
+        field(parts, s.sessionId);
+        field(parts, s.startSeq.toString());
+        field(parts, s.endSeq.toString());
+        field(parts, String(s.startByte));
+        field(parts, String(s.endByte));
+        field(parts, s.digest);
+    }
+    return parts.join("");
+}
+/**
+ * Build the canonical key digest for a crystal identity.
+ *
+ * The returned `key` carries the ranges in canonical sorted order and the
+ * RE-DERIVED `coveredDigest`, so a caller that supplied a stale or wrong covered
+ * digest cannot mint a key that disagrees with its own ranges. The digest itself
+ * is bare lowercase hex (it addresses an identity, not source bytes).
+ */
+export function encodeCrystalKey(key) {
+    const codes = validateRanges(key.sourceRanges);
+    if (codes.length > 0)
+        return { ok: false, codes };
+    const normalized = {
+        ...key,
+        sourceRanges: sortSpans(key.sourceRanges),
+        coveredDigest: computeCoveredDigest(key.sourceRanges),
+    };
+    const keyDigest = createHash("sha256")
+        .update(encodeCrystalKeyBytes(normalized), "utf8")
+        .digest("hex");
+    return { ok: true, keyDigest, key: normalized };
+}
+/**
+ * Whether two identities are the same crystal. Used by invalidation fixtures to
+ * state the sprint invariant directly: the key changes IFF an identity field
+ * changes — an unrelated frontier append is not an identity field, so it cannot
+ * appear here at all.
+ */
+export function sameCrystalKey(a, b) {
+    const ea = encodeCrystalKey(a);
+    const eb = encodeCrystalKey(b);
+    return ea.ok && eb.ok && ea.keyDigest === eb.keyDigest;
+}