pi-mega-compact 0.20.9 → 0.20.11

package/extensions/dashboard-client/src/tabs/VectorCortexTab.tsx

@@ -19,6 +19,7 @@ import {
 	fetchVectorCortexRollout,
 	fetchVectorCortexClosureProof,
 	fetchVectorCortexRestore,
+	fetchVectorCortexRepair,
 	fetchVectorCortexShards,
 	fetchVectorCortexTopology,
 	resetVectorCortexBreaker,
@@ -32,6 +33,7 @@ import {
 	type VectorCortexRolloutView,
 	type VectorCortexClosureProofView,
 	type VectorCortexRestoreView,
+	type VectorCortexRepairView,
 	type VectorCortexShardsView,
 	type VectorCortexTopologyView,
 } from "../api/vector-cortex";
@@ -42,6 +44,11 @@ import { VectorCortexRenderCard } from "./VectorCortexRenderCard";
 import { VectorCortexRolloutCard } from "./VectorCortexRolloutCard";
 import { VectorCortexClosureCard } from "./VectorCortexClosureCard";
 import { VectorCortexRestoreCard } from "./VectorCortexRestoreCard";
+import { VectorCortexRepairCard } from "./VectorCortexRepairCard";
+import {
+	VectorCortexShardsCard,
+	VectorCortexReconstructCard,
+} from "./VectorCortexShardsCard";
 import { VectorCortexPlansCard } from "./VectorCortexPlansCard";
 import { VectorCortexTopologyCard } from "./VectorCortexTopologyCard";
 import { VectorCortexLedgerCard } from "./VectorCortexLedgerCard";
@@ -71,6 +78,7 @@ export default function VectorCortexTab(): React.ReactElement {
 	const [rollout, setRollout] = useState<VectorCortexRolloutView | null>(null);
 	const [closureProof, setClosureProof] = useState<VectorCortexClosureProofView | null>(null);
 	const [restore, setRestore] = useState<VectorCortexRestoreView | null>(null);
+	const [repair, setRepair] = useState<VectorCortexRepairView | null>(null);
 
 	const poll = useCallback(() => {
 		fetchVectorCortexEvaluation()
@@ -112,6 +120,9 @@ export default function VectorCortexTab(): React.ReactElement {
 		fetchVectorCortexRestore().then(setRestore).catch(() => {
 			/* exact-source-restoration card is best-effort (VC6B) */
 		});
+		fetchVectorCortexRepair().then(setRepair).catch(() => {
+			/* self-healing derived-state card is best-effort (VC6C) */
+		});
 	}, []);
 
 	useEffect(() => {
@@ -263,71 +274,14 @@ export default function VectorCortexTab(): React.ReactElement {
 				</CardContent>
 			</Card>
 			<VectorCortexTopologyCard topology={topology} query={query} />
-			<Card>
-				<CardHeader>
-					<div className="flex items-center justify-between">
-						<CardTitle>Dual-Tier Shards (VC4A)</CardTitle>
-						{shards?.enabled ? (
-							<Badge variant="success">ACTIVE</Badge>
-						) : (
-							<Badge variant="danger">OFF</Badge>
-						)}
-				</div>
-				</CardHeader>
-				<CardContent>
-					{!shards?.enabled ? (
-						<div className="vc-empty">Dual-tier shards disabled (VC4A off).</div>
-					) : (
-						<>
-							<div className="grid grid-cols-2 gap-4 md:grid-cols-4">
-								<Metric label="Semantic shards" value={String(shards.semanticCount)} />
-								<Metric label="Exact shards" value={String(shards.exactCount)} />
-								<Metric label="Byte total" value={String(shards.byteTotal)} />
-								<Metric label="Protected bytes" value={String(shards.protectedByteTotal)} />
-							</div>
-							<div className="mt-3 text-xs text-muted-foreground">
-								Reader-only count/byte aggregate; staged in-memory this sprint.
-							</div>
-						</>
-					)}
-				</CardContent>
-			</Card>
-			<Card>
-				<CardHeader>
-					<div className="flex items-center justify-between">
-						<CardTitle>Reconstruction Fidelity (VC4C)</CardTitle>
-						{reconstruct?.enabled ? (
-							<Badge variant="success">ACTIVE</Badge>
-						) : (
-							<Badge variant="danger">OFF</Badge>
-						)}
-					</div>
-				</CardHeader>
-				<CardContent>
-					{!reconstruct?.enabled ? (
-						<div className="vc-empty">Reconstruction fidelity disabled (VC4C off).</div>
-					) : (
-						<>
-							<div className="grid grid-cols-2 gap-4 md:grid-cols-4">
-								<Metric label="Closure attempts" value={String(reconstruct.closureAttempts)} />
-								<Metric label="Closure rejections" value={String(reconstruct.closureRejections)} />
-								<Metric label="Validated" value={String(reconstruct.validatedCount)} />
-								<Metric label="Invalidated" value={String(reconstruct.invalidatedCount)} />
-								<Metric label="Span total" value={String(reconstruct.spanTotal)} />
-								<Metric label="Byte total" value={String(reconstruct.byteTotal)} />
-							</div>
-							<div className="mt-3 text-xs text-muted-foreground">
-								Reader-only closure/validation aggregate; staged in-memory this sprint.
-							</div>
-						</>
-					)}
-				</CardContent>
-			</Card>
+			<VectorCortexShardsCard view={shards} />
+			<VectorCortexReconstructCard view={reconstruct} />
 			<VectorCortexPlansCard view={plans} />
 			<VectorCortexRenderCard view={render} />
 			<VectorCortexRolloutCard view={rollout} />
 			<VectorCortexClosureCard view={closureProof} />
 			<VectorCortexRestoreCard view={restore} />
+			<VectorCortexRepairCard view={repair} />
 			<VectorCortexLedgerCard ledger={ledger} />
 		</div>
 	);

package/extensions/dashboard-client/src/types/vector-cortex.ts

@@ -225,6 +225,23 @@ export interface VectorCortexRestoreView {
   updatedAt: string;
 }
 
+/**
+ * Reader-only self-healing derived-state view (VC6C). Counts + HEAL_REPAIR_*
+ * codes only — there is no payload endpoint, so no subsystem source bytes, gap
+ * ranges, high-water marks, root digests, or ledger text ever reach the client.
+ */
+export interface VectorCortexRepairView {
+  enabled: boolean;
+  mode: "A" | "B" | "C";
+  repairAttempts: number;
+  repairsPlanned: number;
+  pointersSwitched: number;
+  backoffs: number;
+  lastBackoffMs: number | null;
+  lastFailure: string | null;
+  updatedAt: string;
+}
+
 /** Reader-only closure-optimization diagnostics view (VC6A). Aggregate only. */
 export interface VectorCortexClosureProofView {
   enabled: boolean;

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

@@ -71,3 +71,41 @@ export interface VectorCortexRestoreView {
   /** ISO timestamp of the snapshot. */
   readonly updatedAt: string;
 }
+
+/**
+ * Reader-only self-healing derived-state diagnostics view for
+ * GET /api/vector-cortex/repair (VC6C).
+ *
+ * COUNTS + ERROR CODES ONLY. Like the restore view, this surface deliberately
+ * carries no payload: no subsystem source bytes, no rebuilt derived rows, no
+ * subsystem names paired with their gap ranges, no high-water values, no root
+ * digests, and no ledger text (SECURITY_PRIVACY — a diagnostic surface never
+ * renders the authority's contents). Only the controller's rebuild counters,
+ * the backoff schedule's observable timing, and the last HEAL_REPAIR_* failure
+ * code are exposed; the per-subsystem gap detail lives in the structured event
+ * log, not the dashboard.
+ */
+export interface VectorCortexRepairView {
+  /** Whether the VC6C self-healing derived-controller flag is enabled. */
+  readonly enabled: boolean;
+  /**
+   * Runtime triad mode: "A" targeted single-subsystem rebuild, "B" full
+   * deterministic rebuild (ambiguous gap), "C" derived state disabled (both
+   * rebuild paths failed, or the controller is not running at all).
+   */
+  readonly mode: "A" | "B" | "C";
+  /** Total rebuild attempts started by the controller (event counter). */
+  readonly repairAttempts: number;
+  /** Rebuilds planned after gap detection, before rate limiting (counter). */
+  readonly repairsPlanned: number;
+  /** Rebuilds that reached a verified atomic pointer switch (counter). */
+  readonly pointersSwitched: number;
+  /** Attempts deferred by the rate limiter / exponential backoff (counter). */
+  readonly backoffs: number;
+  /** Most recent deterministic backoff delay in ms, or null if none yet. */
+  readonly lastBackoffMs: number | null;
+  /** Last failure reason (a HEAL_REPAIR_* code), or null if none yet. */
+  readonly lastFailure: string | null;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}

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

@@ -377,4 +377,5 @@ export interface VectorCortexLedgerView {
 export type {
   VectorCortexClosureProofView,
   VectorCortexRestoreView,
+  VectorCortexRepairView,
 } from "./vector-cortex-heal.js";

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

@@ -57,6 +57,9 @@ import {
 	handleVectorCortexClosureProof,
 	handleVectorCortexRestore,
 } from "./routes.js";
+// 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";
 
 /**
  * Dispatch a request through every registered route handler.
@@ -110,5 +113,6 @@ export function dispatchRoutes(
 	if (handleVectorCortexRollout(req, res, ctx)) return true;
 	if (handleVectorCortexClosureProof(req, res, ctx)) return true;
 	if (handleVectorCortexRestore(req, res, ctx)) return true;
+	if (handleVectorCortexRepair(req, res, ctx)) return true;
 	return false;
 }

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

@@ -150,5 +150,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"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,
+		),
 	],
 };

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

@@ -0,0 +1,72 @@
+/**
+ * dashboard-server/routes-vector-cortex-repair.ts — VC6C self-healing
+ * derived-state dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/repair returning the self-healing
+ * controller's aggregate diagnostics: whether the flag is enabled, the runtime
+ * triad mode, cumulative rebuild/pointer-switch/backoff counters, the last
+ * deterministic backoff delay, and the last HEAL_REPAIR_* failure code.
+ *
+ * COUNTS + ERROR CODES ONLY. NEVER exposes subsystem source bytes, rebuilt
+ * derived rows, per-subsystem gap ranges, high-water marks, root digests, or
+ * ledger text (reader-only, SECURITY_PRIVACY — the per-subsystem gap detail
+ * lives in the structured event log, not the dashboard). There is no mutation
+ * seam here either: rebuilds are driven by the controller's own gap detection,
+ * never by a dashboard request, so non-GET is rejected outright.
+ *
+ * Split into its own file (rather than grown into routes-vector-cortex-heal.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 { VC6C_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexRepairView } from "./api-contracts/vector-cortex.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/repair (VC6C).
+ *
+ * Counts and HEAL_REPAIR_* codes only — this is a static reader-only aggregate
+ * seam (same shape as the VC6A/VC6B handlers): there is no payload endpoint and
+ * never will be, so no subsystem bytes, gap ranges, high-water marks, or root
+ * digests can leak here.
+ */
+export function handleVectorCortexRepair(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/repair") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC6C_ENABLED();
+  // Flag-off routes to mode C: with VC6C off no self-healing controller runs at
+  // all, so neither the targeted rebuild (mode A) nor the full deterministic
+  // rebuild (mode B) path is available. Mode C is exactly the spec's "derived
+  // state disabled" outcome — the honest OFF view is that derived state is not
+  // being healed, rather than implying a rebuild path that is not wired.
+  // Mirrors how VC6B's OFF view reports the disclose-loss mode it actually takes.
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexRepairView = {
+    enabled,
+    mode,
+    repairAttempts: 0,
+    repairsPlanned: 0,
+    pointersSwitched: 0,
+    backoffs: 0,
+    lastBackoffMs: null,
+    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.9",
+  "version": "0.20.11",
   "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.ts

@@ -241,6 +241,23 @@ export const VC6A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6A");
  */
 export const VC6B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6B");
 
+/**
+ * VC6C — self-healing derived controller. Default ON. `MEGACOMPACT_VC6C=0`
+ * disables and is byte-identical to the predecessor (VC6B): the `detectGaps` /
+ * `planRebuild` / `rebuildGeneration` / `switchPointer` arithmetic STILL RUNS (it
+ * is PURE — a high-water comparison plus a SHA-256 root-digest check, with an
+ * INJECTED clock and no storage or network), but the
+ * `vector_cortex_repair_planned` / `vector_cortex_repair_pointer_switched` /
+ * `vector_cortex_repair_backoff` events are never emitted and the dashboard
+ * repair diagnostics seam is suppressed. Flag OFF gates the reporter + dashboard
+ * seam, never the gap-detection/rebuild arithmetic (in particular, an unverified
+ * pointer switch stays refused with the flag off), 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/VC4B/VC4C/VC5A/VC5B/VC5C/VC6A/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.

package/src/config.ts

@@ -171,6 +171,7 @@ export {
   VC5C_ENABLED,
   VC6A_ENABLED,
   VC6B_ENABLED,
+  VC6C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -0,0 +1,206 @@
+/**
+ * vector-cortex/cache/types.ts — VC7A frozen range crystal contract.
+ *
+ * A CRYSTAL is a frozen, immutable rendering of a bounded set of source ranges.
+ * VC5B proved a render is deterministic; VC7A makes that determinism REUSABLE by
+ * freezing the rendered bytes under a key that names exactly what they depend on.
+ *
+ * THE IDENTITY RULE (the whole sprint in one sentence). A crystal is keyed by
+ * the source ranges it COVERS, the digest of those covered bytes, the VALIDATED
+ * dependency high-water it was rendered against, and the renderer/profile that
+ * produced it — and by NOTHING ELSE. In particular the GLOBAL LEDGER FRONTIER is
+ * deliberately excluded from identity. That exclusion is the point: appending an
+ * unrelated turn advances the global frontier on every single request, so a key
+ * that included it would invalidate every crystal continuously and the cache
+ * would never hit. Conversely, the four fields that ARE in the key are precisely
+ * the ones whose change would make the frozen bytes WRONG:
+ *
+ *   - covered ranges / `coveredDigest` — different bytes render differently;
+ *   - `dependencyHighWater`            — a dependency that has since advanced
+ *                                        may contradict what was frozen;
+ *   - `rendererVersion`                — a renderer change changes the output;
+ *   - `profileId` + `profileVersion`   — a provider profile changes framing.
+ *
+ * So: unrelated append leaves the key UNCHANGED (CRY-FRONTIER-001); one covered
+ * byte, one dependency tick, one renderer bump, or one profile bump invalidates
+ * it 100% (CRY-COVERED-002 / CRY-DEP-003).
+ *
+ * VALIDATED, NOT OBSERVED, HIGH-WATER. `dependencyHighWater` is the DURABLE
+ * contiguous authority high-water the render was VALIDATED against, not whatever
+ * the writer happened to see. TRIAD_RESILIENCE freezes the derived high-water
+ * during an authority outage precisely so a crystal cannot be minted claiming
+ * evidence the authority has not durably accepted.
+ *
+ * DIGEST CONVENTIONS (three fields, two shapes — do not mix them).
+ *   - `DagSpan.digest` and `CrystalKeyV1.coveredDigest` are `sha256:<hex>`, WITH
+ *     the prefix (they name COVERED SOURCE BYTES, matching the DAG span
+ *     convention the ranges themselves carry).
+ *   - `CrystalKeyV1.requestDigest` is BARE lowercase hex, matching
+ *     `RenderManifestV1.requestDigest`.
+ *   - `CrystalV1.contentDigest` (the store's content address) is BARE lowercase
+ *     hex, matching `ExactShardV1.digest`.
+ * Mixing these would either make every lookup miss or — far worse — make a
+ * prefix-stripped comparison accidentally succeed across granularities.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import type { DagSpan } from "../prompt-dag/types.js";
+
+/**
+ * The immutable identity of a frozen crystal.
+ *
+ * Every field here is an IDENTITY field: changing any one of them yields a
+ * different key, and the key is stable under any change to a field NOT listed
+ * here (most importantly the global ledger frontier).
+ */
+export interface CrystalKeyV1 {
+  /** Provider profile that framed the render (VC5B `ProviderProfile.id`). */
+  readonly profileId: string;
+  /** Profile version — a profile bump must invalidate frozen bytes. */
+  readonly profileVersion: string;
+  /** Digest of the canonical request shape, BARE lowercase hex (VC5B). */
+  readonly requestDigest: string;
+  /** The source ranges this crystal covers. Sorted + disjoint (see `crystal.ts`). */
+  readonly sourceRanges: readonly DagSpan[];
+  /** Digest over the covered ranges' pinned digests, `sha256:` prefixed. */
+  readonly coveredDigest: string;
+  /** VALIDATED durable dependency high-water — never the global frontier. */
+  readonly dependencyHighWater: bigint;
+  /** Renderer version that produced the frozen bytes (VC5B renderer). */
+  readonly rendererVersion: string;
+}
+
+/**
+ * A frozen crystal: immutable bytes plus the manifest that explains them.
+ *
+ * `bytes` are the rendered output verbatim. `contentDigest` is the SHA-256 of
+ * exactly those bytes (bare lowercase hex) and is what makes the store
+ * CONTENT-ADDRESSED: two writers who independently render the same key must
+ * produce the same digest, and if they do not, one of them is wrong and the
+ * store refuses rather than picking a winner (`CRY_KEY_COLLISION`).
+ */
+export interface CrystalV1 {
+  readonly schema: "crystal-v1";
+  /** Canonical encoding of the key (see `encodeCrystalKey`). */
+  readonly keyDigest: string;
+  /** The frozen rendered bytes, verbatim and immutable. */
+  readonly bytes: Uint8Array;
+  /** SHA-256 over `bytes`, BARE lowercase hex (the content address). */
+  readonly contentDigest: string;
+  /** Byte length of `bytes`, carried so readers need not touch the payload. */
+  readonly byteCount: number;
+  /** The identity this crystal was frozen under. */
+  readonly key: CrystalKeyV1;
+}
+
+/** VC7A failure codes (registered CRY codes). */
+export type CrystalFailureCode =
+  /** Two covered ranges in the same session overlap — identity is ambiguous. */
+  | "CRY_RANGE_OVERLAP"
+  /** A key already exists with DIFFERENT bytes; the store never overwrites. */
+  | "CRY_KEY_COLLISION"
+  /** A covered range is malformed (reversed/negative seq or byte bounds). */
+  | "CRY_RANGE_INVALID"
+  /** The key names no covered ranges — a crystal must cover something. */
+  | "CRY_RANGE_EMPTY"
+  /** The key exceeds the covered-range or aggregate-byte bound. */
+  | "CRY_KEY_LIMIT"
+  /** The store is unavailable — triad mode C, nothing is served from cache. */
+  | "CRY_STORE_UNAVAILABLE";
+
+/** The verdict of canonical key encoding. */
+export type CrystalKeyResult =
+  | { readonly ok: true; readonly keyDigest: string; readonly key: CrystalKeyV1 }
+  | { readonly ok: false; readonly codes: readonly CrystalFailureCode[] };
+
+/**
+ * The verdict of a store write.
+ *
+ * `written` distinguishes a FIRST write from an idempotent re-write of identical
+ * bytes: both are `ok`, because re-freezing the same crystal is legitimate (two
+ * concurrent renders raced), but only the first actually stored anything. A
+ * different-bytes write is never `ok` and never mutates the stored crystal.
+ */
+export type CrystalWriteResult =
+  | { readonly ok: true; readonly written: boolean; readonly contentDigest: string }
+  | { readonly ok: false; readonly code: CrystalFailureCode; readonly contentDigest: string };
+
+/**
+ * Runtime triad mode for the crystal path (TRIAD_RESILIENCE).
+ *
+ *   A — the crystal store answered the read (the fast, normal path);
+ *   B — a miss or a collision forced a FRESH deterministic render. This is an
+ *       INDEPENDENT algorithm: no crystal, no store index, the renderer runs
+ *       from the plan exactly as it would have before VC7A existed;
+ *   C — the store is unavailable, so the cache is BYPASSED entirely. Mode C
+ *       serves nothing from cache and states the loss of old semantic context;
+ *       it never substitutes a stale or partially-written crystal.
+ */
+export type CrystalMode = "A" | "B" | "C";
+
+/** Reader-only aggregate for GET /api/vector-cortex/cache-crystals. */
+export interface CrystalStoreStats {
+  readonly mode: CrystalMode;
+  /** Distinct crystals currently held. */
+  readonly crystalCount: number;
+  /** Aggregate frozen bytes held (sum of `byteCount`). */
+  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 stored 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;
+}
+
+/**
+ * Maximum covered ranges in one key. A key is caller-shaped input; this bound
+ * exists so a single lookup cannot be turned into an unbounded sort/hash of
+ * attacker-chosen ranges (CRY_KEY_LIMIT).
+ */
+export const CRYSTAL_LIMIT_RANGES = 256;
+
+/** Maximum aggregate covered bytes across a key's ranges (8 MiB). */
+export const CRYSTAL_LIMIT_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Registered VC7A crystal conformance ID range (CRY-001..015). The acceptance
+ * aggregator reads these rows from the v2 manifest and asserts each returns its
+ * manifest `ok`/`code`.
+ */
+export const CRYSTAL_IDS: readonly string[] = Array.from(
+  { length: 15 },
+  (_v, i) => `CRY-${String(i + 1).padStart(3, "0")}`,
+);
+
+/**
+ * Registered VC7A provider-identity conformance rows (PRO-016..023), continuing
+ * VC5B's PRO-001..015. These pin the PROFILE half of crystal identity: a profile
+ * or renderer bump must invalidate, and a profile-irrelevant change must not.
+ */
+export const CRYSTAL_PROVIDER_IDS: readonly string[] = Array.from(
+  { length: 8 },
+  (_v, i) => `PRO-${String(i + 16).padStart(3, "0")}`,
+);
+
+/** Named VC7A conformance assertions (the sprint's headline rows). */
+export const CRYSTAL_NAMED_IDS = [
+  "CRY-FRONTIER-001",
+  "CRY-COVERED-002",
+  "CRY-DEP-003",
+] as const;
+
+/** The two structured events the VC7A reporter emits. */
+export type CrystalEventName =
+  | "vector_cortex_crystal_written"
+  | "vector_cortex_crystal_collision";
+
+export type { DagSpan };