pi-mega-compact 0.16.3 → 0.17.1

package/src/vector-cortex/conformance/runner.ts

@@ -0,0 +1,165 @@
+/**
+ * vector-cortex/conformance/runner.ts — v2 conformance runner (VC1C).
+ *
+ * Dispatches a conformance case STRICTLY by domain/version (no inference, no
+ * partial output on unknown) and compares both the canonical success bytes and
+ * the expected failure code. Owns `DowngradeReport`.
+ *
+ * The runner is triad-shaped (mode A client):
+ *   A = this manifest runner over the real algorithms;
+ *   B = an independent exact fixture reader (invertible digest recheck);
+ *   C = reject any unknown domain/version WITHOUT partial output.
+ *
+ * Downgrade export: `exporter` produces a new legacy copy that never edits
+ * authority data; the resulting `DowngradeReport` is deterministic — a second
+ * run yields a byte-identical report digest (CONF-DOWN-003).
+ *
+ * No network, no side effects on authority (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { CONF_FAIL, type FixtureManifestEntry } from "./manifest.js";
+import {
+  createConformanceReporter,
+  type ConformanceReporter,
+} from "./emit.js";
+
+/** A registered conformance algorithm handler for a (domain, tuple) key. */
+export interface ConformanceHandler {
+  /**
+   * Run the case. `fixture` is the raw parsed fixture object. Returns ok with a
+   * canonical output digest (the success bytes), or a failure code.
+   */
+  run(
+    entry: FixtureManifestEntry,
+    fixture: unknown,
+  ): { ok: true; outputBytes: Uint8Array; outputDigest: string } | { ok: false; code: string };
+}
+
+/**
+ * The deterministic downgrade-export report. `reportDigest` is a SHA-256 over
+ * the canonical JSON of the report body, so a repeated export is byte-identical.
+ */
+export interface DowngradeReport {
+  readonly schema: "downgrade-report-v1";
+  readonly exportedCopyId: string;
+  readonly copiedCount: number;
+  readonly unrepresentableIds: readonly string[];
+  readonly reportDigest: string;
+}
+
+/** A minimal exporter: produces a new legacy copy and its deterministic report. */
+export interface DowngradeExporter {
+  /** Run the export once. Must never edit the authority data it reads. */
+  exportOnce(): DowngradeReport;
+}
+
+/**
+ * Result of dispatching a conformance case: success bytes (mode A/B) or the
+ * exact expected failure code (mode C rejects unknown without partial output).
+ */
+export type CaseResult =
+  | { ok: true; outputDigest: string; algorithm: string }
+  | { ok: false; code: string; algorithm: string };
+
+const UNKNOWN_DOMAIN = "CONF_UNKNOWN_DOMAIN";
+const UNKNOWN_VERSION = "CONF_UNKNOWN_VERSION";
+/**
+ * The runner-pinned expectation mismatch code: a dispatched handler returned an
+ * outcome that contradicts the manifest entry's frozen expectation (the wrong
+ * failure code, or a success/failure parity error). This is the runner's own
+ * cross-check (task 5: "compare both success bytes and expected failure code"),
+ * distinct from the domain's own failure codes.
+ */
+const EXPECTATION_MISMATCH = "CONF_EXPECTATION_MISMATCH";
+
+export { UNKNOWN_DOMAIN, UNKNOWN_VERSION, EXPECTATION_MISMATCH };
+
+/**
+ * Run one conformance case by dispatching strictly on `(domain, algorithmTuple)`.
+ * If no handler is registered for the exact domain/algorithms, returns
+ * `CONF_UNKNOWN_DOMAIN`/`CONF_UNKNOWN_VERSION` WITHOUT partial output.
+ *
+ * After dispatch the runner cross-checks the handler's outcome against the
+ * manifest entry's frozen expectation (task 5):
+ *   - failure expected (`entry.failureCode` set): the handler must return
+ *     `ok:false` with that exact code, else `CONF_EXPECTATION_MISMATCH`;
+ *   - success expected (`entry.expected === "ok"`): the handler must return
+ *     `ok:true`, and when the manifest pins an `expectedOutputDigest` the
+ *     handler's `outputDigest` must match it, else `CONF_DIGEST_DRIFT`.
+ */
+export function runConformanceCase(
+  entry: FixtureManifestEntry,
+  handlers: ReadonlyMap<string, ConformanceHandler>,
+  fixture: unknown,
+  reporter: ConformanceReporter = createConformanceReporter(),
+): CaseResult {
+  const key = `${entry.domain}::${entry.algorithmTuple.join(";")}`;
+  const handler = handlers.get(key);
+  let result: CaseResult;
+  if (!handler) {
+    if (entry.domain === "") {
+      result = { ok: false, code: UNKNOWN_DOMAIN, algorithm: entry.algorithm };
+    } else {
+      result = { ok: false, code: UNKNOWN_VERSION, algorithm: entry.algorithm };
+    }
+  } else {
+    const out = handler.run(entry, fixture);
+    if (out.ok) {
+      // Success expected? The manifest entry pins the expected success bytes.
+      if (entry.expected !== "ok") {
+        result = { ok: false, code: EXPECTATION_MISMATCH, algorithm: entry.algorithm };
+      } else if (
+        entry.expectedOutputDigest !== undefined &&
+        out.outputDigest !== entry.expectedOutputDigest
+      ) {
+        result = { ok: false, code: CONF_FAIL.DIGEST_DRIFT, algorithm: entry.algorithm };
+      } else {
+        result = { ok: true, outputDigest: out.outputDigest, algorithm: entry.algorithm };
+      }
+    } else {
+      // Failure expected? The manifest entry pins the exact failure code.
+      if (entry.failureCode !== undefined && out.code === entry.failureCode) {
+        result = { ok: false, code: out.code, algorithm: entry.algorithm };
+      } else {
+        result = { ok: false, code: EXPECTATION_MISMATCH, algorithm: entry.algorithm };
+      }
+    }
+  }
+  reporter.caseChecked({
+    id: entry.id,
+    domain: entry.domain,
+    algorithm: entry.algorithm,
+    ok: result.ok,
+    ...(result.ok ? { outputDigest: result.outputDigest } : { code: result.code }),
+  });
+  return result;
+}
+
+/**
+ * Build a dispatch key for a (domain, algorithmTuple) pair. Callers register
+ * handlers under this key.
+ */
+export function handlerKey(
+  domain: string,
+  algorithmTuple: readonly string[],
+): string {
+  return `${domain}::${algorithmTuple.join(";")}`;
+}
+
+/**
+ * Run a downgrade export and recompute its report digest deterministically.
+ * A second invocation produces a byte-identical report (CONF-DOWN-003).
+ */
+export function runDowngradeExport(
+  exporter: DowngradeExporter,
+  reporter: ConformanceReporter = createConformanceReporter(),
+): DowngradeReport {
+  const report = exporter.exportOnce();
+  reporter.downgradeWritten({
+    exportedCopyId: report.exportedCopyId,
+    copiedCount: report.copiedCount,
+    unrepresentableIds: report.unrepresentableIds,
+    reportDigest: report.reportDigest,
+  });
+  return report;
+}

package/src/vector-cortex/conformance/triadB-reader.ts

@@ -0,0 +1,110 @@
+/**
+ * conformance/triadB-reader.ts — TRIAD-B independent exact reader (VC1C).
+ *
+ * Deliberately shares NO code and NO cached-seed instance with the runner
+ * modules (l1-minhash-v2.ts / l1-lsh-v2.ts). It re-derives the minhash-v2
+ * signature and 64 bucket keys from first principles, using only the PUBLISHED
+ * (a,b) seed pairs passed in (read by the caller from
+ * conformance/.../minhash/seeds-v2.json — the table authored independently by
+ * scripts/gen-fixtures/minhash.mjs, the same process that produced the frozen
+ * fixture bytes). Because B shares no subroutine with the runner, a systematic
+ * error in the runner's splitmix64 / seed-derivation / signature arithmetic
+ * cannot satisfy both triad A and triad B.
+ *
+ * Pure compute, no deps, no storage, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { createHash } from "node:crypto";
+
+const MASK64 = 0xffffffffffffffffn;
+const P = (1n << 61n) - 1n; // 2^61 - 1
+const SLOTS = 256;
+const U64 = 8;
+const BANDS = 64;
+
+/** A published (a, b) seed pair as decimal strings (exactness beyond 2^53). */
+export interface PublishedSeedPair {
+  readonly a: string;
+  readonly b: string;
+}
+
+/** 64-bit FNV-1a over UTF-8 bytes or a raw byte buffer (own, independent loop). */
+function fnv1a64(input: string | Uint8Array): bigint {
+  let h = 0xcbf29ce484222325n;
+  for (const b of Buffer.from(input)) {
+    h = ((h ^ BigInt(b)) * 0x100000001b3n) & MASK64;
+  }
+  return h;
+}
+
+/**
+ * Re-derive the 2048-byte minhash-v2 signature and (optionally) the 64 LSH
+ * bucket keys for `text` within `session`, from published seed pairs only —
+ * never the runner module.
+ */
+export function independentReaderV2(
+  text: string,
+  session: string,
+  seedPairs: readonly PublishedSeedPair[],
+  withBuckets: boolean,
+): { bytes: Uint8Array; digest: string; buckets: string[] } {
+  // Normalization: ANSI-strip, NFC, case-fold, CRLF->LF, whitespace collapse,
+  // 32K cap — mirrored from the frozen VC1C spec.
+  let norm = (text || "")
+    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+    .normalize("NFC")
+    .toLowerCase()
+    .replace(/\r\n?/g, "\n")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (norm.length > 32768) norm = norm.slice(0, 32768);
+
+  // Five-code-point shingles (deduped, capped at 50_000).
+  const grams: bigint[] = [];
+  if (norm.length > 0) {
+    const cps = Array.from(norm);
+    const seen = new Set<bigint>();
+    const short = cps.length < 5;
+    for (let i = 0; i < (short ? 1 : cps.length - 4); i++) {
+      const h = short ? fnv1a64(norm) : fnv1a64(cps.slice(i, i + 5).join(""));
+      if (!seen.has(h)) {
+        seen.add(h);
+        grams.push(h);
+      }
+      if (!short && seen.size >= 50000) break;
+    }
+  }
+
+  // Signature: slot i = min over shingles of (a_i*x + b_i) mod p (exact BigInt).
+  const sig = new Array<bigint>(SLOTS).fill(P);
+  for (let i = 0; i < SLOTS && grams.length > 0; i++) {
+    const pair = seedPairs[i] as PublishedSeedPair;
+    const a = BigInt(pair.a);
+    const b = BigInt(pair.b);
+    let min = P;
+    for (const x of grams) {
+      const h = (a * x + b) % P;
+      if (h < min) min = h;
+    }
+    sig[i] = min;
+  }
+
+  // Own 256 x u64 little-endian encoder.
+  const buf = Buffer.allocUnsafe(SLOTS * U64);
+  for (let i = 0; i < SLOTS; i++) buf.writeBigUInt64LE(sig[i] as bigint, i * U64);
+  const bytes = new Uint8Array(buf);
+  const digest = createHash("sha256").update(bytes).digest("hex");
+
+  // 64 buckets: FNV-1a over `<session>|v2|` + each 32-byte band (LE hex).
+  const buckets: string[] = [];
+  if (withBuckets) {
+    const prefix = Buffer.from(`${session}|v2|`, "utf8");
+    for (let band = 0; band < BANDS; band++) {
+      const bandBytes = Buffer.from(bytes.slice(band * 32, band * 32 + 32));
+      const out = Buffer.allocUnsafe(U64);
+      out.writeBigUInt64LE(fnv1a64(Buffer.concat([prefix, bandBytes])), 0);
+      buckets.push(`b${band}:${out.toString("hex")}`);
+    }
+  }
+  return { bytes, digest, buckets };
+}

package/src/vector-cortex/eval/annotations.ts

@@ -0,0 +1,70 @@
+/**
+ * vector-cortex/eval/annotations.ts — redaction metadata + JSONL serialization.
+ *
+ * Payload bytes, prompts, and exact ledger text are NEVER serialized. Before a
+ * JSONL line is written, each such field is replaced by a SHA-256 digest + byte
+ * count + redaction kind (EVAL-REDACT-002: prompt bytes never appear in JSONL).
+ * The redaction journal is itself the AnnotationV1 output.
+ *
+ * Uses node:crypto for the digest (pure local math, PREVENT-PI-004 safe).
+ */
+
+import { createHash } from "node:crypto";
+import type { AnnotationV1 } from "./types.js";
+
+export type RedactKind = "payload" | "prompt" | "ledger";
+
+/** A raw content field awaiting redaction before serialization. */
+export interface RawContent {
+  /** Field name in the original annotation. */
+  readonly field: string;
+  /** Kind of content — determines the redaction reason. */
+  readonly kind: RedactKind;
+  /** Original bytes; digested, never serialized. */
+  readonly bytes: Uint8Array;
+}
+
+/** Canonical serialization of an annotation: digest/count metadata only. */
+export interface SerializedAnnotation {
+  readonly jsonl: string;
+  readonly annotation: AnnotationV1;
+}
+
+/** SHA-256 over bytes, unpadded base64 (conformance canonical binary form). */
+export function digestBytes(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("base64");
+}
+
+/** Replace every raw content field with its digest/count metadata. */
+export function redactAnnotation(
+  itemId: string,
+  contents: ReadonlyArray<RawContent>,
+): AnnotationV1 {
+  const redactions = contents.map((c) => ({
+    field: c.field,
+    digest: digestBytes(c.bytes),
+    bytes: c.bytes.byteLength,
+    kind: c.kind,
+  }));
+  return {
+    itemId,
+    redactions,
+    redactedCount: redactions.length,
+  };
+}
+
+/**
+ * Serialize one set of raw contents to a single redacted JSONL line. Returns
+ * the annotation with its digest metadata and the JSONL text; the raw bytes
+ * never appear in the returned string.
+ */
+export function serializeRedactedJsonl(
+  itemId: string,
+  contents: ReadonlyArray<RawContent>,
+): SerializedAnnotation {
+  const annotation = redactAnnotation(itemId, contents);
+  return {
+    annotation,
+    jsonl: `${JSON.stringify(annotation)}\n`,
+  };
+}

package/src/vector-cortex/eval/metrics.ts

@@ -0,0 +1,113 @@
+/**
+ * vector-cortex/eval/metrics.ts — canonical metric ordering + fixed histogram.
+ *
+ * 1. Stable sort rows by `(session, seq, event)` — session string byte order,
+ *    then integer seq ascending, then event-name byte order as tiebreak
+ *    (EVAL-ORDER-003: equal seq rows use event-name order).
+ * 2. Bucket latency values at exactly 1/5/10/25/50/100/250ms with inclusive
+ *    boundaries (EVAL-BUCKET-001); values past 250ms kept in a separate
+ *    overflow bucket. Histogram totals are permutation-stable.
+ *
+ * Pure/no side effects (PREVENT-PI-004).
+ */
+
+import { LATENCY_BUCKETS } from "./types.js";
+import type { MetricEventV1, EvalReject } from "./types.js";
+
+/** Inclusive-boundary bucket edges, with a sentinel past the largest edge. */
+const EDGES: readonly number[] = LATENCY_BUCKETS;
+const OVERFLOW_INDEX = EDGES.length;
+
+/** Histogram cell counts aligned to EDGES, plus a trailing overflow cell. */
+export function emptyHistogram(): number[] {
+  return new Array<number>(EDGES.length + 1).fill(0);
+}
+
+/**
+ * Per-session histogram of `value` (when the sample is in `unit`), plus a
+ * non-latency count kept separate so totals are permutation-stable.
+ */
+export interface LatencyHistogram {
+  /** Cells: one per bucket edge, then overflow. Sum == counted latency samples. */
+  cells: number[];
+  /** Bucket label for each cell (overflow label is "250+" passed via >250). */
+  edges: readonly number[];
+  /** Number of latency samples that landed past the largest edge. */
+  overflow: number;
+  /** Total latency samples bucketed (cells sum). */
+  total: number;
+}
+
+export interface MetricsResult {
+  /** Rows in canonical `(session, seq, event)` order. */
+  readonly rows: readonly MetricEventV1[];
+  /** Per-session latency histograms (mode A observed). */
+  readonly histogram: LatencyHistogram;
+  /** Rejections encountered while validating streaming input. */
+  readonly rejects: readonly EvalReject[];
+}
+
+/** True when a sample carries a latency (`unit === "ms"`) datum. */
+export function isLatencySample(m: MetricEventV1): boolean {
+  return m.unit === "ms";
+}
+
+/** Bucket a latency ms value into a cell index (0..EDGES.length, last=overflow). */
+export function bucketIndex(value: number): number {
+  if (!Number.isFinite(value) || value < 0) return OVERFLOW_INDEX;
+  for (let i = 0; i < EDGES.length; i++) {
+    if (value <= EDGES[i]) return i; // inclusive upper boundary
+  }
+  return OVERFLOW_INDEX;
+}
+
+/**
+ * Bucket latency sample values across all rows into the fixed histogram.
+ * Overflow is kept separate (counted in `overflow` and the trailing cell).
+ */
+export function bucketHistogram(rows: readonly MetricEventV1[]): LatencyHistogram {
+  const cells = emptyHistogram();
+  let overflow = 0;
+  for (const m of rows) {
+    if (!isLatencySample(m)) continue;
+    const idx = bucketIndex(m.value);
+    cells[idx] += 1;
+    if (idx === EDGES.length) overflow += 1;
+  }
+  return {
+    cells,
+    edges: [...EDGES],
+    overflow,
+    total: cells.reduce((a, b) => a + b, 0),
+  };
+}
+
+/**
+ * Stable sort MetricEventV1 rows by `(session, seq, event)`:
+ *  - session: UTF-8 / JS string byte order;
+ *  - seq: ascending numeric;
+ *  - event: ascending string byte order (tiebreak for equal seq).
+ * Equal content stays separate occurrences (never deduplicated here).
+ */
+export function sortCanonical(rows: readonly MetricEventV1[]): MetricEventV1[] {
+  const out = [...rows];
+  out.sort((a, b) => {
+    const s = a.session < b.session ? -1 : a.session > b.session ? 1 : 0;
+    if (s !== 0) return s;
+    if (a.seq !== b.seq) return a.seq - b.seq;
+    return a.event < b.event ? -1 : a.event > b.event ? 1 : 0;
+  });
+  return out;
+}
+
+/**
+ * Assisted sort plus histogram, returning both under one result.
+ * The observer (mode A) calls this before JSONL serialization.
+ */
+export function buildMetrics(rows: readonly MetricEventV1[]): MetricsResult {
+  return {
+    rows: sortCanonical(rows),
+    histogram: bucketHistogram(rows),
+    rejects: [],
+  };
+}

package/src/vector-cortex/eval/observer.ts

@@ -0,0 +1,86 @@
+/**
+ * vector-cortex/eval/observer.ts — VC0A structured observer (triad mode A).
+ *
+ * Connects to the evaluation reader: accepts MetricEventV1 samples, maintains
+ * the canonical `(session, seq, event)` ordered set plus the fixed latency
+ * histogram, and emits two structured local events:
+ *   - vector_cortex_eval_sample_recorded   (one per accepted sample)
+ *   - vector_cortex_eval_redaction_rejected (when a redaction fails)
+ *
+ * Mode C (observer absent) is the responsibility of the caller: no observes(),
+ * no writes, byte-identical to the predecessor. This module never touches the
+ * network (PREVENT-PI-004) — it only manipulates in-memory rows and emits
+ * structured log lines through an injected logging callback so it stays
+ * pi-agnostic and deterministically testable.
+ */
+
+import { buildMetrics, sortCanonical } from "./metrics.js";
+import type { MetricEventV1 } from "./types.js";
+
+export interface EvalObserverOptions {
+  /** Callback emitting structured log lines (ts + event). Swallows errors. */
+  readonly emit: (event: string, fields: Record<string, unknown>) => void;
+  /**
+   * Optional persistence callback for one accepted sample (redacted metric
+   * row). The pure observer stays in-memory; a host supplies this to bridge
+   * the observer to disk JSONL for the separate-process dashboard reader.
+   * Swallows errors — best-effort, non-fatal.
+   */
+  readonly persist?: (sample: MetricEventV1) => void;
+}
+
+export interface EvalObserver {
+  /** Record one sample; emits vector_cortex_eval_sample_recorded. */
+  record(sample: MetricEventV1): void;
+  /** Report a redaction failure (raw content that could not be redacted). */
+  rejectRedaction(field: string, reason: string): void;
+  /** Canonical-ordered rows seen so far. */
+  rows(): readonly MetricEventV1[];
+}
+
+/**
+ * Build a structured observer (mode A). Best-effort: emitting never throws
+ * into the extension path (non-fatal observability).
+ */
+export function createEvalObserver(opts: EvalObserverOptions): EvalObserver {
+  const rows: MetricEventV1[] = [];
+
+  function emit(event: string, fields: Record<string, unknown>): void {
+    try {
+      opts.emit(event, fields);
+    } catch {
+      /* non-fatal observability — never break the agent loop */
+    }
+  }
+
+  return {
+    record(sample) {
+      rows.push(sample);
+      if (opts.persist) {
+        try {
+          opts.persist(sample);
+        } catch {
+          /* non-fatal observability */
+        }
+      }
+      emit("vector_cortex_eval_sample_recorded", {
+        session: sample.session,
+        seq: sample.seq,
+        event: sample.event,
+        unit: sample.unit,
+        mode: sample.mode,
+      });
+    },
+    rejectRedaction(field, reason) {
+      emit("vector_cortex_eval_redaction_rejected", { field, reason });
+    },
+    rows() {
+      return sortCanonical(rows);
+    },
+  };
+}
+
+/** Aggregate metrics result from an observer's rows (canonical + histogram). */
+export function observerMetrics(result: { rows: () => readonly MetricEventV1[] }) {
+  return buildMetrics(result.rows() as MetricEventV1[]);
+}

package/src/vector-cortex/eval/persist.ts

@@ -0,0 +1,73 @@
+/**
+ * vector-cortex/eval/persist.ts — redacted eval JSONL persistence (VC0A).
+ *
+ * Bridges the in-memory observer (mode A) and the dashboard reader (separate
+ * process) via a disk JSONL under the state dir. Writes are append-only and
+ * hold only MetricEventV1 metric rows plus redaction metadata — never payloads,
+ * prompts, or exact ledger text (EVAL-REDACT-002). Best-effort and non-fatal
+ * (PREVENT-PI-004: local filesystem only; no network).
+ *
+ * PREVENT-011: no `any` type.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { MetricEventV1 } from "./types.js";
+
+/** Location of the redacted evaluation JSONL under a state dir. */
+export function evalJsonlPath(stateDir: string): string {
+  return join(stateDir, "vector-cortex", "evaluation.jsonl");
+}
+
+/** Append one redacted metric row as a canonical JSON line (append-only). */
+export function appendEvalRow(
+  stateDir: string,
+  row: readonly MetricEventV1[],
+): void {
+  try {
+    const path = evalJsonlPath(stateDir);
+    mkdirSync(join(stateDir, "vector-cortex"), { recursive: true, mode: 0o700 });
+    // PER_EVAL_PERMISSION: 0600 file inherits state-dir permission policy.
+    writeFileSync(path, row.map((r) => `${JSON.stringify(r)}\n`).join(""), {
+      flag: "a",
+      mode: 0o600,
+    });
+    // guardrails-allow PREVENT-PI-004: local filesystem eval JSONL (no network)
+  } catch {
+    /* non-fatal observability — never break the agent loop */
+  }
+}
+
+/**
+ * Read every redacted metric row from the JSONL. Malformed or truncated final
+ * lines are skipped (callers surface EVAL_JSONL_TRUNCATED); the caller decides
+ * whether that is fatal. Returns an empty array when the file is absent.
+ */
+export function readEvalRows(stateDir: string): MetricEventV1[] {
+  const out: MetricEventV1[] = [];
+  let raw: string;
+  try {
+    raw = readFileSync(evalJsonlPath(stateDir), "utf8");
+  } catch {
+    return out;
+  }
+  for (const line of raw.split("\n")) {
+    if (line.trim().length === 0) continue;
+    try {
+      const parsed = JSON.parse(line) as Partial<MetricEventV1>;
+      if (
+        typeof parsed.session === "string" &&
+        typeof parsed.seq === "number" &&
+        typeof parsed.event === "string" &&
+        typeof parsed.value === "number" &&
+        typeof parsed.unit === "string" &&
+        (parsed.mode === "A" || parsed.mode === "B" || parsed.mode === "C")
+      ) {
+        out.push(parsed as MetricEventV1);
+      }
+    } catch {
+      /* malformed line — skip; EVAL_JSONL_TRUNCATED surfaced by caller */
+    }
+  }
+  return out;
+}

package/src/vector-cortex/eval/reader.ts

@@ -0,0 +1,45 @@
+/**
+ * vector-cortex/eval/reader.ts — evaluation reader (aggregate-only).
+ *
+ * Reader-only capability: `summarizeEvalRows` collapses a set of MetricEventV1
+ * rows into an aggregate summary for the dashboard `GET /api/vector-cortex/
+ * evaluation` endpoint. No writable capability — the observer writes via its
+ * own path; this reader never mutates. Predecessor (flag-off / mode C) emits
+ * an empty summary byte-identical to "no data".
+ *
+ * Pure + local, zero network (PREVENT-PI-004).
+ */
+
+import { buildMetrics } from "./metrics.js";
+import type { MetricEventV1 } from "./types.js";
+
+export interface EvalSummary {
+  /** Samples aggregated. */
+  readonly samples: number;
+  /** Per-mode distribution (A/B/C). */
+  readonly byMode: Readonly<{ A: number; B: number; C: number }>;
+  /** Fixed latency histogram with its inclusive edges + separate overflow. */
+  readonly histogram: {
+    readonly edges: readonly number[];
+    readonly cells: readonly number[];
+    readonly overflow: number;
+    readonly total: number;
+  };
+}
+
+/** Aggregate rows into a reader-only summary (histogram + per-mode counts). */
+export function summarizeEvalRows(rows: readonly MetricEventV1[]): EvalSummary {
+  const byMode = { A: 0, B: 0, C: 0 };
+  for (const r of rows) byMode[r.mode] += 1;
+  const metrics = buildMetrics(rows as MetricEventV1[]);
+  return {
+    samples: rows.length,
+    byMode,
+    histogram: {
+      edges: metrics.histogram.edges,
+      cells: metrics.histogram.cells,
+      overflow: metrics.histogram.overflow,
+      total: metrics.histogram.total,
+    },
+  };
+}