pi-mega-compact 0.16.2 → 0.17.0

package/dist/src/vector-cortex/resilience/spool-core.js

@@ -0,0 +1,347 @@
+/**
+ * vector-cortex/resilience/spool-core.ts — VC0C durable spool implementation (VC0C).
+ *
+ * Implementation file behind the `spool.ts` factory barrel. See spool.ts for the
+ * public surface; this file owns the TRIAD_RESILIENCE §spool append/fsync/ack
+ * protocol.
+ *
+ * Implements TRIAD_RESILIENCE.md §Spool protocol as the mode-B independent,
+ * deterministic, local disk spool that derives directly from authority:
+ *
+ *   - One spool file per session: `spool-<session>.spool` under a state dir.
+ *   - Header records schema, session, first sequence, and the prior durable
+ *     contiguous high-water.
+ *   - Frames are length-prefixed binary records carrying seq + eventId +
+ *     original bytes + SHA-256 + CRC32C (Castagnoli). A frame is FSYNC'd to disk
+ *     before the writer acknowledges `SPOOLED`; only a durable ledger commit
+ *     (after `drain` inserts into authority and the ledger is fsynced) returns
+ *     `SPOOL_COMMITTED` and advances the contiguous high-water.
+ *   - `drain` strictly sorts frames by `(seq, eventId)`, rejects gaps/conflicts,
+ *     inserts idempotently by `(eventId, digest)`, appends an fsynced ack frame,
+ *     then advances contiguous high-water. A duplicate with the same id+digest is
+ *     acknowledged (`SPOOL_IDEMPOTENT_ACK`); the same id with a DIFFERENT digest
+ *     is `SPOOL_MANUAL_HALT`.
+ *   - Crash before an ack safely replays: on reopen, frames after the last ack
+ *     are re-drained (the ack frame carries the committed seq).
+ *   - A derived builder may never read beyond the durable contiguous authority
+ *     high-water; during an authority outage the high-water freezes (drain cannot
+ *     commit) even while the spool keeps accepting frames.
+ *
+ * LOCAL ONLY: filesystem + node:crypto, zero network (PREVENT-PI-004); no `any`
+ * (PREVENT-011); synchronous durable writes (fsyncSync) per the spec.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import { basename, join } from "node:path";
+export const SPOOL_SCHEMA = "spool-v1";
+/** Sentinel eventId of an acknowledgement frame (carries the committed seq). */
+export const ACK_EVENT_ID = "__ack__";
+/** Fixed on-disk width of the digest field: "sha256:" + 64 hex chars = 71 bytes. */
+export const DIGEST_FIELD_LEN = "sha256:".length + 64;
+/** CRC32C (Castagnoli) table — seeded once. */
+const CRC_TABLE = (() => {
+    const t = new Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0x82f63b78 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32c(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function createSpool(opts) {
+    mkdirSync(opts.dir, { recursive: true });
+    const bySession = new Map();
+    return {
+        session(session) {
+            let s = bySession.get(session);
+            if (!s) {
+                s = new SessionSpoolImpl(join(opts.dir, `spool-${basename(session)}.spool`), session, opts);
+                bySession.set(session, s);
+            }
+            return s;
+        },
+    };
+}
+/**
+ * Durably manages one session's spool file. Fully synchronous: every append is
+ * fsynced before acknowledging; every committed drain appends+fsyncs an ack
+ * frame. Reopen parses the header + frames, stops at a torn trailing frame
+ * (crash mid-write => unacknowledged tail), and drains only frames strictly
+ * beyond the recovered contiguous high-water — crash before ack safely replays.
+ */
+class SessionSpoolImpl {
+    session;
+    file;
+    outage;
+    reporter;
+    header;
+    frames = [];
+    ackedSeq;
+    frontierFrozen = false;
+    constructor(file, session, opts) {
+        this.file = file;
+        this.session = session;
+        this.outage = opts.authorityOutage ?? (() => false);
+        this.reporter = opts.reporter;
+        mkdirSync(join(file, ".."), { recursive: true });
+        if (existsSync(file)) {
+            const parsed = this.readExisting();
+            this.header = parsed.header;
+            this.frames = parsed.frames;
+            this.ackedSeq = parsed.highWater;
+        }
+        else {
+            this.header = { schema: SPOOL_SCHEMA, session, firstSeq: 1, priorHighWater: "0" };
+            this.ackedSeq = 0n;
+            this.writeHeader();
+        }
+    }
+    writeHeader() {
+        const fd = openSync(this.file, "a");
+        try {
+            writeSync(fd, Buffer.from(encodeHeader(this.header), "utf8"));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /** Reopen: parse header + frames; recover the last contiguous ack high-water. */
+    readExisting() {
+        const raw = readFileSync(this.file);
+        const nl = raw.indexOf(10);
+        if (nl < 0) {
+            return { header: { schema: SPOOL_SCHEMA, session: this.session, firstSeq: 1, priorHighWater: "0" }, frames: [], highWater: 0n };
+        }
+        const header = parseHeader(raw.subarray(0, nl).toString("utf8"));
+        let highWater = BigInt(header.priorHighWater);
+        const frames = [];
+        let off = nl + 1;
+        for (;;) {
+            if (off >= raw.length)
+                break;
+            const f = tryParseFrame(raw.subarray(off));
+            if (!f)
+                break; // torn/unacknowledged tail — stop, replay from last ack
+            const frame = { ...f, session: this.session };
+            if (frame.eventId === ACK_EVENT_ID) {
+                highWater = frame.seq; // ack frame carries the committed seq
+            }
+            else {
+                frames.push(frame);
+            }
+            const len = raw.readUInt32LE(off);
+            off += 4 + len;
+        }
+        // Only frames strictly beyond the recovered high-water need re-drain.
+        const unacked = frames.filter((f) => f.seq > highWater);
+        return { header, frames: unacked, highWater };
+    }
+    append(input) {
+        const digest = input.digest ?? `sha256:${sha256Hex(input.bytes)}`;
+        const frame = {
+            session: this.session,
+            seq: input.seq,
+            eventId: input.eventId,
+            digest,
+            bytes: input.bytes,
+            crc32c: crc32c(input.bytes),
+        };
+        const framed = encodeFrame(frame);
+        // Fsync BEFORE acknowledging SPOOLED.
+        const fd = openSync(this.file, "a");
+        try {
+            writeSync(fd, framed, 0, framed.length);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        this.frames.push(frame);
+        return { verdict: "SPOOLED", seq: input.seq };
+    }
+    drain(insert) {
+        const tail = this.frames;
+        if (tail.length === 0)
+            return { verdict: "SPOOL_COMMITTED", committedSeq: this.ackedSeq };
+        // Strictly sort by (seq, eventId). NOTE: we do NOT clear this.frames up front
+        // (VC0C-Q04) — the queue is only cleared once every insert has succeeded and
+        // the ack is durably appended. If any insert throws (rather than returning a
+        // conflict), the unacked tail must be retained for a later retry, not dropped.
+        const sorted = [...tail].sort(compareFrames);
+        let committed = this.ackedSeq;
+        for (const f of sorted) {
+            if (f.seq !== committed + 1n) {
+                // Gap: requeue everything beyond the last committed seq and halt.
+                this.frames = sorted.filter((x) => x.seq > committed);
+                return { verdict: "SPOOL_MANUAL_HALT", committedSeq: committed, reason: `TRI_SPOOL_GAP expected ${committed + 1n} got ${f.seq}` };
+            }
+            let outcome;
+            try {
+                outcome = insert(this.session, f.seq, f.eventId, f.digest, f.bytes);
+            }
+            catch {
+                // Authority insert THREW (e.g. a transient authority write error). This is
+                // NON-FATAL: requeue the unacked tail and halt, mirroring the manual-halt
+                // path, instead of propagating (a propagating throw would lose the frames
+                // and leave a retry seeing SPOOL_COMMITTED-with-nothing-processed).
+                this.frames = sorted.filter((x) => x.seq > committed);
+                return { verdict: "SPOOL_MANUAL_HALT", committedSeq: committed, reason: "TRI_SPOOL_INSERT_THROW" };
+            }
+            if (outcome === "committed" || outcome === "idempotent") {
+                committed = f.seq;
+            }
+            else {
+                this.frames = sorted.filter((x) => x.seq > committed);
+                return { verdict: "SPOOL_MANUAL_HALT", committedSeq: committed, reason: "TRI_SPOOL_CONFLICT conflicting digest" };
+            }
+        }
+        // All frames committed: clear the in-memory queue, then durably commit by
+        // appending+fsyncing an ack frame and advancing the high-water.
+        this.frames = [];
+        this.appendAck(committed);
+        this.ackedSeq = committed;
+        return { verdict: "SPOOL_COMMITTED", committedSeq: committed };
+    }
+    appendAck(seq) {
+        const frame = {
+            session: this.session,
+            seq,
+            eventId: ACK_EVENT_ID,
+            digest: `sha256:${sha256Hex(new Uint8Array(0))}`,
+            bytes: new Uint8Array(0),
+            crc32c: crc32c(new Uint8Array(0)),
+        };
+        const framed = encodeFrame(frame);
+        const fd = openSync(this.file, "a");
+        try {
+            writeSync(fd, framed, 0, framed.length);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    highWater() {
+        // The contiguous authority high-water advances ONLY on a durable ack
+        // (appendAck after a successful drain commit). During authority outage drain
+        // cannot commit, so ackedSeq naturally freezes here — an explicit outage
+        // branch would return the same value and was dead code (VC0C-Q05). The
+        // freeze/outage SIGNAL is the `frozen()`/`frontierFrozen` flag, not this
+        // scalar; frames appended during outage remain in the unacked tail.
+        return this.ackedSeq;
+    }
+    frozen() {
+        return this.frontierFrozen || this.outage();
+    }
+    freezeFrontier() {
+        const firstFreeze = !this.frontierFrozen && !this.outage();
+        this.frontierFrozen = true;
+        // Emit vector_cortex_frontier_frozen only on an actual freeze transition
+        // (once per outage; flag-gated + non-fatal inside the reporter). No event on
+        // an already-frozen or authority-outage-covered frontier. flag OFF => no-op.
+        if (firstFreeze) {
+            this.reporter?.frontierFrozen({
+                session: this.session,
+                committedSeq: String(this.ackedSeq),
+                frozenHighWater: String(this.ackedSeq),
+            });
+        }
+        return this.ackedSeq;
+    }
+}
+function compareFrames(a, b) {
+    if (a.seq !== b.seq)
+        return a.seq < b.seq ? -1 : 1;
+    return a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0;
+}
+function encodeHeader(h) {
+    return `${JSON.stringify(h)}\n`;
+}
+function parseHeader(line) {
+    const raw = JSON.parse(line);
+    if (raw.schema !== SPOOL_SCHEMA)
+        throw new Error("TRI_SPOOL_SCHEMA");
+    return raw;
+}
+/**
+ * Encode one binary frame: [u32 len][seq i64][eventId UTF-8 NUL][bytes][NUL][digest][u32 crc32c].
+ * The digest field is DIGEST_FIELD_LEN bytes ("sha256:" + 64 hex = 71) — sizing it
+ * to fit the FULL digest string is load-bearing for read-side verification
+ * (VC0C-Q03): a 64-byte cap silently truncated Buffer.write, so the stored digest
+ * could never match the recomputed value and every frame would be rejected on read.
+ * body length = 8 + eventId.length + 1 + bytes.length + 1 + DIGEST_FIELD_LEN + 4.
+ */
+function encodeFrame(f) {
+    const idBuf = Buffer.from(f.eventId, "utf8");
+    const bodyLen = 8 + idBuf.length + 1 + f.bytes.length + 1 + DIGEST_FIELD_LEN + 4;
+    const body = Buffer.alloc(bodyLen);
+    let o = 0;
+    body.writeBigInt64LE(BigInt(f.seq), o);
+    o += 8;
+    idBuf.copy(body, o);
+    o += idBuf.length;
+    body[o] = 0;
+    o += 1;
+    Buffer.from(f.bytes).copy(body, o);
+    o += f.bytes.length;
+    body[o] = 0;
+    o += 1;
+    body.write(f.digest, o, "utf8");
+    o += DIGEST_FIELD_LEN;
+    body.writeUInt32LE(f.crc32c, o);
+    o += 4;
+    const lenBuf = Buffer.alloc(4);
+    lenBuf.writeUInt32LE(bodyLen, 0);
+    return Buffer.concat([lenBuf, body]);
+}
+/**
+ * Parse a length-prefixed frame; returns null for a torn/truncated tail OR a
+ * CRYPTOGRAPHIC INTEGRITY MISMATCH (VC0C-Q03). The stored SHA-256 digest and
+ * CRC32C are recomputed over the parsed bytes and compared — a same-length bit
+ * flip must not survive reopen and be drained/committed. A mismatch is treated
+ * like a torn tail: `readExisting` stops there and the frame is NOT accepted —
+ * it remains unacknowledged, so replay/requeue preserves it rather than
+ * silently committing corrupted bytes.
+ */
+function tryParseFrame(buf) {
+    if (buf.length < 4)
+        return null;
+    const len = buf.readUInt32LE(0);
+    if (buf.length < 4 + len)
+        return null; // torn
+    const body = buf.subarray(4, 4 + len);
+    let o = 0;
+    const seq = body.readBigInt64LE(o);
+    o += 8;
+    const idEnd = body.indexOf(0, o);
+    if (idEnd < 0)
+        return null;
+    const eventId = body.subarray(o, idEnd).toString("utf8");
+    o = idEnd + 1;
+    const bytesStart = o;
+    const nul2 = body.indexOf(0, o);
+    if (nul2 < 0)
+        return null;
+    const bytes = new Uint8Array(body.subarray(bytesStart, nul2));
+    o = nul2 + 1;
+    const digest = body.subarray(o, o + DIGEST_FIELD_LEN).toString("utf8");
+    const storedCrc = body.readUInt32LE(o + DIGEST_FIELD_LEN);
+    // Recompute and verify — write-only integrity would let a same-length bit flip
+    // drain/commit silently. Return null (treat as torn/corrupt) on mismatch.
+    if (digest !== `sha256:${sha256Hex(bytes)}` || storedCrc !== crc32c(bytes)) {
+        return null;
+    }
+    return { session: "", seq, eventId, digest, bytes, crc32c: storedCrc };
+}

package/dist/src/vector-cortex/resilience/spool.js

@@ -0,0 +1,12 @@
+/**
+ * vector-cortex/resilience/spool.ts — VC0C durable spool barrel (VC0C).
+ *
+ * Thin barrel over the append/fsync/ack spool implementation in `spool-core.ts`
+ * (delegate-shell + impl-file split keeps the frequently-touched file small).
+ * Re-exports the public `createSpool` factory, the mode-B spool/session types,
+ * and the SHA-256 / CRC32C helpers for the safety adapter and tests.
+ *
+ * Full protocol semantics live in spool-core.ts (TRIAD_RESILIENCE §spool).
+ * Local-only, no network (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+export { createSpool, SPOOL_SCHEMA, ACK_EVENT_ID, crc32c, sha256Hex } from "./spool-core.js";

package/dist/src/vector-cortex/resilience/types.js

@@ -0,0 +1,32 @@
+/**
+ * vector-cortex/resilience/types.ts — VC0C breaker/triad contracts (VC0C).
+ *
+ * Owns `Mode`, `TriadResult<T>`, `BreakerRecord`, `KillDecision`, and the
+ * `Breaker` circuit-breaker seam from CONTRACTS.md §TriadResult and breaker
+ * seam, plus the durable spool record shapes. Pure type/schema definitions +
+ * small pure predicates (no storage, no console, no network, no side effects —
+ * PREVENT-PI-004 / PREVENT-011). The live state machine lives in
+ * `breaker.ts`/`spool.ts`; the safety adapter selects A→B→C in
+ * `extensions/mega-runtime/vector-cortex-safety.ts`.
+ *
+ * Triad semantics (TRIAD_RESILIENCE.md): A is optimized/learned; B is
+ * deterministic/local and derives directly from authority; C is continuity, not
+ * semantic completeness — it uses only the exact current transcript and reports
+ * that limitation.
+ */
+/**
+ * Registered TRI conformance ID range (TRI-001..030). The acceptance test reads
+ * these rows from the v2 `resilience/` domain and asserts each returns its
+ * manifest bytes or exactly its listed failure code. TRI-001..015 are owned by
+ * VC0C (window/probe/hysteresis/cooldown transitions); TRI-016..030 span the
+ * spool protocol (frame, drain, gap, digest conflict, ack crash, frozen
+ * frontier). Mirrors EVT_IDS / CUT_IDS / M3_IDS.
+ */
+export const TRI_IDS = [
+    "TRI-001", "TRI-002", "TRI-003", "TRI-004", "TRI-005",
+    "TRI-006", "TRI-007", "TRI-008", "TRI-009", "TRI-010",
+    "TRI-011", "TRI-012", "TRI-013", "TRI-014", "TRI-015",
+    "TRI-016", "TRI-017", "TRI-018", "TRI-019", "TRI-020",
+    "TRI-021", "TRI-022", "TRI-023", "TRI-024", "TRI-025",
+    "TRI-026", "TRI-027", "TRI-028", "TRI-029", "TRI-030",
+];

package/dist/vector-cortex/eval/annotations.js

@@ -0,0 +1,41 @@
+/**
+ * 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";
+/** SHA-256 over bytes, unpadded base64 (conformance canonical binary form). */
+export function digestBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("base64");
+}
+/** Replace every raw content field with its digest/count metadata. */
+export function redactAnnotation(itemId, contents) {
+    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, contents) {
+    const annotation = redactAnnotation(itemId, contents);
+    return {
+        annotation,
+        jsonl: `${JSON.stringify(annotation)}\n`,
+    };
+}

package/dist/vector-cortex/eval/metrics.js

@@ -0,0 +1,86 @@
+/**
+ * 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";
+/** Inclusive-boundary bucket edges, with a sentinel past the largest edge. */
+const EDGES = LATENCY_BUCKETS;
+const OVERFLOW_INDEX = EDGES.length;
+/** Histogram cell counts aligned to EDGES, plus a trailing overflow cell. */
+export function emptyHistogram() {
+    return new Array(EDGES.length + 1).fill(0);
+}
+/** True when a sample carries a latency (`unit === "ms"`) datum. */
+export function isLatencySample(m) {
+    return m.unit === "ms";
+}
+/** Bucket a latency ms value into a cell index (0..EDGES.length, last=overflow). */
+export function bucketIndex(value) {
+    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) {
+    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) {
+    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) {
+    return {
+        rows: sortCanonical(rows),
+        histogram: bucketHistogram(rows),
+        rejects: [],
+    };
+}

package/dist/vector-cortex/eval/observer.js

@@ -0,0 +1,61 @@
+/**
+ * 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";
+/**
+ * Build a structured observer (mode A). Best-effort: emitting never throws
+ * into the extension path (non-fatal observability).
+ */
+export function createEvalObserver(opts) {
+    const rows = [];
+    function emit(event, fields) {
+        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) {
+    return buildMetrics(result.rows());
+}

package/dist/vector-cortex/eval/persist.js

@@ -0,0 +1,67 @@
+/**
+ * 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";
+/** Location of the redacted evaluation JSONL under a state dir. */
+export function evalJsonlPath(stateDir) {
+    return join(stateDir, "vector-cortex", "evaluation.jsonl");
+}
+/** Append one redacted metric row as a canonical JSON line (append-only). */
+export function appendEvalRow(stateDir, row) {
+    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) {
+    const out = [];
+    let raw;
+    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);
+            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);
+            }
+        }
+        catch {
+            /* malformed line — skip; EVAL_JSONL_TRUNCATED surfaced by caller */
+        }
+    }
+    return out;
+}

package/dist/vector-cortex/eval/reader.js

@@ -0,0 +1,29 @@
+/**
+ * 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";
+/** Aggregate rows into a reader-only summary (histogram + per-mode counts). */
+export function summarizeEvalRows(rows) {
+    const byMode = { A: 0, B: 0, C: 0 };
+    for (const r of rows)
+        byMode[r.mode] += 1;
+    const metrics = buildMetrics(rows);
+    return {
+        samples: rows.length,
+        byMode,
+        histogram: {
+            edges: metrics.histogram.edges,
+            cells: metrics.histogram.cells,
+            overflow: metrics.histogram.overflow,
+            total: metrics.histogram.total,
+        },
+    };
+}