pi-mega-compact 0.20.10 → 0.20.12

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

@@ -0,0 +1,217 @@
+/**
+ * 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,
+  type CrystalFailureCode,
+  type CrystalKeyResult,
+  type CrystalKeyV1,
+  type DagSpan,
+} 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: string[], value: string): void {
+  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: DagSpan, b: DagSpan): number {
+  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: readonly DagSpan[]): readonly DagSpan[] {
+  return [...spans].sort(compareSpans);
+}
+
+/** A range is malformed if either bound runs backwards or a byte bound is negative. */
+function isMalformed(s: DagSpan): boolean {
+  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: DagSpan, b: DagSpan): boolean {
+  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: readonly DagSpan[]): readonly CrystalFailureCode[] {
+  const codes = new Set<CrystalFailureCode>();
+  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: CrystalFailureCode[] = [
+    "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: readonly DagSpan[]): string {
+  const h = createHash("sha256");
+  for (const s of sortSpans(spans)) {
+    const parts: string[] = [];
+    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: CrystalKeyV1): string {
+  const parts: string[] = [];
+  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: CrystalKeyV1): CrystalKeyResult {
+  const codes = validateRanges(key.sourceRanges);
+  if (codes.length > 0) return { ok: false, codes };
+
+  const normalized: CrystalKeyV1 = {
+    ...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: CrystalKeyV1, b: CrystalKeyV1): boolean {
+  const ea = encodeCrystalKey(a);
+  const eb = encodeCrystalKey(b);
+  return ea.ok && eb.ok && ea.keyDigest === eb.keyDigest;
+}

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

@@ -0,0 +1,213 @@
+/**
+ * vector-cortex/cache/store.ts — content-addressed, write-once crystal store
+ * (VC7A).
+ *
+ * WRITE ONCE, NEVER OVERWRITE. A key that already holds bytes is final. Writing
+ * the SAME bytes again is accepted and idempotent (two concurrent renders raced;
+ * both are right). Writing DIFFERENT bytes under the same key returns
+ * `CRY_KEY_COLLISION` and the stored crystal is left exactly as it was.
+ *
+ * Why refuse rather than take the newer bytes? Because the key already names
+ * everything the render depended on — covered ranges, their digest, the validated
+ * dependency high-water, the renderer, the profile. If two renders of that same
+ * identity disagree, the renderer is NOT deterministic, and that is a bug to
+ * surface loudly, not to paper over by picking a winner. Last-write-wins would
+ * make the failure invisible and let a corrupted render silently displace a good
+ * one. So the store is a one-way ratchet per key.
+ *
+ * CONTENT ADDRESSED. Every crystal carries the SHA-256 of exactly its own bytes
+ * (bare lowercase hex, matching `ExactShardV1.digest`), recomputed HERE from the
+ * bytes rather than trusted from the caller — a caller-supplied digest would let
+ * a mismatched pair be stored and later "verify" against itself.
+ *
+ * ATOMIC COMMIT (the crash invariant). Writes go through a staging slot and are
+ * only published by `commit`. A write interrupted before commit leaves the
+ * staging entry orphaned and the visible map untouched, so `read` can never
+ * observe a partial crystal. On restart, `recover()` DISCARDS staged entries —
+ * it never promotes them — and a fresh write then produces exactly one valid
+ * crystal. This models the real filesystem shape (write temp file → fsync →
+ * rename) without doing any I/O here: persistence is the runtime's job, and
+ * `src/` stays storage-free and pure (PREVENT-PI-004).
+ *
+ * MODE C. `setAvailable(false)` marks the store unavailable: reads serve nothing
+ * and writes refuse with `CRY_STORE_UNAVAILABLE`. Mode C is a real triad state,
+ * not an error path — the caller must fall back to a fresh render and disclose
+ * that nothing came from cache.
+ *
+ * No console, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { createHash } from "node:crypto";
+
+import type {
+  CrystalMode,
+  CrystalStoreStats,
+  CrystalV1,
+  CrystalWriteResult,
+} from "./types.js";
+
+/** SHA-256 over bytes, BARE lowercase hex (the content address). */
+export function contentAddress(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Byte equality without allocating — a length check first, then a scan. */
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * An in-memory, content-addressed, write-once crystal store.
+ *
+ * Deliberately holds no filesystem handle: the process-local map IS the store as
+ * far as `src/` is concerned, and durability is layered on by the runtime. That
+ * keeps the write-once/collision arithmetic testable end-to-end with real
+ * modules and no I/O mocking.
+ */
+export class CrystalStore {
+  /** Published crystals, keyed by canonical key digest. */
+  private readonly committed = new Map<string, CrystalV1>();
+  /** Staged-but-uncommitted writes — invisible to `read` until committed. */
+  private readonly staged = new Map<string, CrystalV1>();
+  private available = true;
+  private hits = 0;
+  private misses = 0;
+  private hitBytes = 0;
+  private writes = 0;
+  private duplicateWrites = 0;
+  private collisions = 0;
+
+  /** Freeze a crystal object for a key/bytes pair (digest computed here). */
+  static freeze(keyDigest: string, bytes: Uint8Array, key: CrystalV1["key"]): CrystalV1 {
+    const copy = new Uint8Array(bytes);
+    return {
+      schema: "crystal-v1",
+      keyDigest,
+      bytes: copy,
+      contentDigest: contentAddress(copy),
+      byteCount: copy.length,
+      key,
+    };
+  }
+
+  /** Toggle store availability (mode C when false). */
+  setAvailable(value: boolean): void {
+    this.available = value;
+  }
+
+  isAvailable(): boolean {
+    return this.available;
+  }
+
+  /**
+   * Stage a write without publishing it. Returns the staging handle (the key
+   * digest) so a test — or a crash — can leave it uncommitted.
+   */
+  stage(crystal: CrystalV1): CrystalWriteResult {
+    if (!this.available) {
+      return { ok: false, code: "CRY_STORE_UNAVAILABLE", contentDigest: crystal.contentDigest };
+    }
+    this.staged.set(crystal.keyDigest, crystal);
+    return { ok: true, written: false, contentDigest: crystal.contentDigest };
+  }
+
+  /**
+   * Publish a staged write. Enforces write-once at the commit point: an existing
+   * key with identical bytes is idempotent, with different bytes is a collision
+   * and is NEVER overwritten.
+   */
+  commit(keyDigest: string): CrystalWriteResult {
+    const pending = this.staged.get(keyDigest);
+    if (pending === undefined) {
+      return { ok: false, code: "CRY_STORE_UNAVAILABLE", contentDigest: "" };
+    }
+    this.staged.delete(keyDigest);
+    if (!this.available) {
+      return { ok: false, code: "CRY_STORE_UNAVAILABLE", contentDigest: pending.contentDigest };
+    }
+    const existing = this.committed.get(keyDigest);
+    if (existing !== undefined) {
+      if (bytesEqual(existing.bytes, pending.bytes)) {
+        this.duplicateWrites += 1;
+        return { ok: true, written: false, contentDigest: existing.contentDigest };
+      }
+      this.collisions += 1;
+      return { ok: false, code: "CRY_KEY_COLLISION", contentDigest: existing.contentDigest };
+    }
+    this.committed.set(keyDigest, pending);
+    this.writes += 1;
+    return { ok: true, written: true, contentDigest: pending.contentDigest };
+  }
+
+  /** Stage + commit in one step (the normal path). */
+  write(crystal: CrystalV1): CrystalWriteResult {
+    const staged = this.stage(crystal);
+    if (!staged.ok) return staged;
+    return this.commit(crystal.keyDigest);
+  }
+
+  /**
+   * Restart recovery: DISCARD every staged entry. A write interrupted before
+   * commit is never promoted — a fresh write afterwards produces exactly one
+   * valid crystal. Returns how many partial writes were dropped.
+   */
+  recover(): number {
+    const dropped = this.staged.size;
+    this.staged.clear();
+    return dropped;
+  }
+
+  /** Read a committed crystal. Mode C (unavailable) serves nothing. */
+  read(keyDigest: string): CrystalV1 | undefined {
+    if (!this.available) {
+      this.misses += 1;
+      return undefined;
+    }
+    const found = this.committed.get(keyDigest);
+    if (found === undefined) {
+      this.misses += 1;
+      return undefined;
+    }
+    this.hits += 1;
+    this.hitBytes += found.byteCount;
+    return found;
+  }
+
+  /** Whether a key holds a committed crystal (does not count as a read). */
+  has(keyDigest: string): boolean {
+    return this.available && this.committed.has(keyDigest);
+  }
+
+  /** Number of writes staged but not yet committed (0 after `recover`). */
+  pendingCount(): number {
+    return this.staged.size;
+  }
+
+  /**
+   * The triad mode the store is currently in: C when unavailable, A once a read
+   * has been served from the store, B while every read has forced a fresh render.
+   */
+  mode(): CrystalMode {
+    if (!this.available) return "C";
+    return this.hits > 0 ? "A" : "B";
+  }
+
+  /** Reader-only aggregate for the dashboard seam — counts and bytes only. */
+  stats(): CrystalStoreStats {
+    let totalBytes = 0;
+    for (const c of this.committed.values()) totalBytes += c.byteCount;
+    return {
+      mode: this.mode(),
+      crystalCount: this.committed.size,
+      totalBytes,
+      hits: this.hits,
+      misses: this.misses,
+      hitBytes: this.hitBytes,
+      writes: this.writes,
+      duplicateWrites: this.duplicateWrites,
+      collisions: this.collisions,
+    };
+  }
+}

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 };