pi-mega-compact 0.16.3 → 0.17.0

package/dist/extensions/mega-runtime/vector-cortex-safety.js

@@ -0,0 +1,100 @@
+/**
+ * vector-cortex-safety.ts — VC0C live safety envelope (VC0C, task 4 + 5).
+ *
+ * Owns the live triad selection BEFORE provider invocation: select mode A
+ * (optimized/learned), then independent mode B (deterministic local spool
+ * deriving directly from authority), then unchanged mode C (continuity, not
+ * semantic completeness — C uses only the exact current transcript and reports
+ * that limitation). A manual reset clears cooldown but NEVER evidence.
+ *
+ * This adapter composes the resilience seams (`resilience/breaker.ts`,
+ * `resilience/spool.ts`, `resilience/emit.ts`) into the health/reset API the
+ * dashboard owns (`GET /api/vector-cortex/health`, admin
+ * `POST /api/vector-cortex/breakers/reset`). It is the pi-runtime-adjacent shell;
+ * all durable state is owned by the src/ resilience modules. Non-fatal: any
+ * breaker/spool noise degrades to mode C (unchanged host transcript), and the
+ * agent loop is never broken.
+ *
+ * Local-only (PREVENT-PI-004); no `any` (PREVENT-011); no console.log — events
+ * go through the injected resilience reporter / Logger.
+ *
+ * LIVENESS HONESTY (VC0C-Q01/Q06): the breaker composed here is PER-PROCESS /
+ * IN-MEMORY and EPHEMERAL — `createVectorCortexSafety` builds a fresh instance on
+ * every dashboard request (GET /health, POST /reset). There is NO persistent
+ * breaker runtime and NO live producer wiring (the real circuit-breaker that runs
+ * around the actual compaction loop is DEFERRED to the producer-wiring sprint,
+ * carried VC0B-I08 -> VC0D). Consequently GET /health always reflects a brand-new
+ * CLOSED_A instance and POST /reset mutates an instance that vanishes when the
+ * request returns: the endpoints are ILLUSTRATIVE until VC0D wires a persistent
+ * instance. The health payload therefore carries `stateSource:"ephemeral"` so the
+ * dashboard/README never present it as a live breaker. Frontier-frozen / spool-lag
+ * are owned by the DURABLE spool but have no live per-session handle here, so they
+ * are surfaced as static/non-live until VC0D (with authorityOutage mirrored from
+ * the host context when supplied).
+ */
+import { join } from "node:path";
+import { createResilienceReporter } from "../../src/vector-cortex/resilience/emit.js";
+import { createBreaker } from "../../src/vector-cortex/resilience/breaker.js";
+import { createSpool } from "../../src/vector-cortex/resilience/spool.js";
+import { BREAKER_WINDOW_MS, VC0C_ENABLED } from "../../src/config/vector-cortex.js";
+/** Build the live safety envelope, wiring the emit seam into the breaker. */
+export function createVectorCortexSafety(ctx, emit) {
+    const reporter = createResilienceReporter(emit);
+    const wallNow = ctx.wallNow ?? (() => new Date().toISOString());
+    const breaker = createBreaker({ now: ctx.now, reporter, wallNow });
+    const spool = createSpool({
+        dir: join(ctx.stateDir, "spool"),
+        authorityOutage: ctx.authorityOutage,
+        // Wire the resilience emit seam (incl. vector_cortex_frontier_frozen) into
+        // the mode-B spool so a real authority-frontier freeze is observable.
+        reporter,
+    });
+    return {
+        spool,
+        select(provider) {
+            const { subsystem, inputDigest, runA, runB, runC, validate } = provider;
+            // Thin delegation to the breaker: it selects the highest healthy mode
+            // (A, else independent B, else unchanged C) BEFORE provider invocation and
+            // records the attempt/trip. Across invocations A-failure demotes to B and
+            // B-failure demotes to C (continuity — unchanged transcript).
+            return breaker.execute(subsystem, inputDigest, { A: runA, B: runB, C: runC }, validate);
+        },
+        health() {
+            const rec = breaker.snapshot("provider");
+            const enabled = VC0C_ENABLED();
+            // LIVENESS HONESTY (VC0C-Q01/Q06): this breaker is created fresh per request
+            // and is ephemeral — declare it explicitly so the dashboard never presents it
+            // as a live breaker. `authorityOutage` is mirrored from the host context when
+            // supplied (otherwise false). `frontierFrozen` (rec.frozenFrontier) and
+            // `spoolLag` are owned by the DURABLE spool, which has no live per-session
+            // handle here — they stay static/no-op until VC0D wires a persistent breaker
+            // instance; stateSource:"ephemeral" is the signal that they are not live.
+            return {
+                enabled,
+                mode: rec.state === "MANUAL_HALT" ? "C" : rec.state === "CLOSED_A" ? "A" : "B",
+                state: rec.state,
+                subsystem: "provider",
+                sinceMs: rec.transitionedAtMs,
+                reason: rec.manualReason,
+                windowMs: BREAKER_WINDOW_MS,
+                probeCount: rec.probeCount,
+                backoffDelayMs: rec.retryDelayMs,
+                frontierFrozen: rec.frozenFrontier,
+                authorityOutage: ctx.authorityOutage?.() ?? false,
+                spoolLag: 0,
+                attempts: rec.attempts,
+                failures: rec.failures,
+                p95Ms: rec.p95Ms,
+                failureRate: rec.failureRate,
+                updatedAt: wallNow(),
+                stateSource: "ephemeral",
+            };
+        },
+        reset(subsystem) {
+            return breaker.reset(subsystem);
+        },
+        halt(reason) {
+            return breaker.manualHalt(reason);
+        },
+    };
+}

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

@@ -0,0 +1,81 @@
+/**
+ * config/vector-cortex.ts — vector-cortex feature flags + breaker/triad constants.
+ *
+ * Every sprint ships one positive `MEGACOMPACT_<SPRINT>` flag, default ON and
+ * `=0`/`_DISABLED` off. Flag-OFF is byte-identical to the predecessor sprint's
+ * behavior (for VC0A: mode C — observer absent, zero evaluation writes).
+ *
+ * The breaker/triad constants (TRIAD_RESILIENCE.md) live here so VC0C consumes
+ * them without re-declaring the ownership boundary. Pi-agnostic, dependency-free.
+ */
+/** Positive sprint flag: `=0` or `_DISABLED=true` disables (default ON). */
+function sprintFlag(name) {
+    const v = process.env[name];
+    if (v === "0" || v === "false")
+        return false;
+    const disabled = process.env[name + "_DISABLED"];
+    if (disabled === "true" || disabled === "1")
+        return false;
+    return true;
+}
+/** VC0A — baseline observability (MetricEventV1 / AnnotationV1). Default ON. */
+export const VC0A_ENABLED = () => sprintFlag("MEGACOMPACT_VC0A");
+/**
+ * VC0B — replay correctness (ReplayCutV2 / ReplayReportV2, M3 effective-cut-v2).
+ * Default ON. `MEGACOMPACT_VC0B=0` disables and is byte-identical to the
+ * predecessor (legacy capped-replay behavior preserved; the v2 cut/replay is
+ * only consulted on the vector-cortex path).
+ */
+export const VC0B_ENABLED = () => sprintFlag("MEGACOMPACT_VC0B");
+/**
+ * VC1A — canonical byte events (EventV2 / EventCodec).
+ * Default ON. `MEGACOMPACT_VC1A=0` disables and is byte-identical to the
+ * predecessor (mode C: ledger absent, current transcript codec unchanged).
+ * The single real consumer is the ledger emit seam (`ledger/emit.ts`): flag OFF
+ * gates zero observability writes.
+ */
+export const VC1A_ENABLED = () => sprintFlag("MEGACOMPACT_VC1A");
+/**
+ * VC1B — occurrence ledger + tool identity + compat journal (LedgerReader/
+ * Writer/Admin, CompatJournalV1, M2 occurrence-v2 migration).
+ * Default ON. `MEGACOMPACT_VC1B=0` disables and is byte-identical to the
+ * predecessor (mode C: the neutral occurrence ledger is not written, no
+ * journal rows, zero `vector_cortex_occurrence_appended` emissions). The real
+ * consumers are the ledger write integration seam and the compat-journal
+ * switch seam.
+ */
+export const VC1B_ENABLED = () => sprintFlag("MEGACOMPACT_VC1B");
+/**
+ * VC0C — live safety envelope (TriadResult / Breaker / KillDecision + durable
+ * spool). Default ON. `MEGACOMPACT_VC0C=0` disables and is byte-identical to
+ * the predecessor (mode C: selected before provider invocation, unchanged host
+ * transcript, breaker/spool idle and emitting nothing). The single real
+ * consumer is the resilience emit seam + the safety adapter's triad selection.
+ */
+export const VC0C_ENABLED = () => sprintFlag("MEGACOMPACT_VC0C");
+// ---------------------------------------------------------------------------
+// Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
+// Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.
+// ---------------------------------------------------------------------------
+/** Rolling eligibility window (milliseconds). */
+export const BREAKER_WINDOW_MS = 60_000;
+/** Minimum attempts before a breaker may trip or promote. */
+export const BREAKER_MIN_ATTEMPTS = 20;
+/** Performance trip: ≥ this many failures in window, or ≥ this fraction. */
+export const BREAKER_PERF_FAILURES = 5;
+export const BREAKER_PERF_FAILURE_RATE = 0.1;
+/** Correctness trip trips on the first correctness failure. */
+export const BREAKER_CORRECTNESS_FAILURES = 1;
+/** Cooldown before an open breaker may probe (milliseconds). */
+export const BREAKER_COOLDOWN_MS = 30_000;
+/** Consecutive successful probes required to advance a state. */
+export const BREAKER_PROBE_COUNT = 3;
+/** Exponential retry base: 30s * 2^attempt, capped, ±10% jitter. */
+export const BREAKER_RETRY_BASE_MS = 30_000;
+export const BREAKER_RETRY_CAP_MS = 15 * 60_000;
+export const BREAKER_RETRY_JITTER = 0.1;
+/** Promotion hysteresis: failure rate must be < this and p95 within budget. */
+export const BREAKER_HYSTERESIS_FAILURE_RATE = 0.02;
+export const BREAKER_HYSTERESIS_BUDGET_P95_MS = 50;
+/** Minimum healthy residence before a further promotion (milliseconds). */
+export const BREAKER_MIN_HEALTHY_RESIDENCE_MS = 5 * 60_000;

package/dist/src/config.js

@@ -109,3 +109,9 @@ export const RAG_MEMORY_GRAPH = () => ragEnabled("MEGACOMPACT_MEMORY_GRAPH");
 export const RAG_HYDE_ENABLED = () => ragEnabled("MEGACOMPACT_HYDE");
 /** Spec 1: vbrainstorm visual design migration for the dashboard. */
 export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
+// ---------------------------------------------------------------------------
+// Vector-cortex flags + breaker constants (VC0A+). Positive sprint flags,
+// default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
+// so root consumers share one source of truth.
+// ---------------------------------------------------------------------------
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/vector-cortex/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/src/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/src/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/src/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/src/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,
+        },
+    };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * vector-cortex/eval/types.ts — MetricEventV1 / AnnotationV1 contract types
+ * and the registered EVAL conformance ID range (EVAL-001..010).
+ *
+ * Owned by VC0A (baseline observability). Consumes reviewer-accepted predecessor
+ * contracts and common contracts only. These are pure type/schema definitions —
+ * no runtime network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+/** Units the evaluator understands. Unknown units reject as EVAL_UNIT_UNKNOWN. */
+export const UNITS = ["ms", "bytes", "count", "ratio"];
+/**
+ * Histogram bucket edges for latency, in milliseconds, inclusive on both
+ * boundaries (EVAL-BUCKET-001): values at exactly 1ms and 250ms land in
+ * those buckets. Overflow (value > largest edge) is kept separate.
+ */
+export const LATENCY_BUCKETS = [1, 5, 10, 25, 50, 100, 250];
+/**
+ * Registered EVAL conformance ID range (EVAL-001..010). The acceptance test
+ * reads these rows from the v2 manifest and asserts their expected bytes/results.
+ * Registered BEFORE evaluation logic so the manifest/fixture seam is stable.
+ */
+export const EVAL_IDS = [
+    "EVAL-001",
+    "EVAL-002",
+    "EVAL-003",
+    "EVAL-004",
+    "EVAL-005",
+    "EVAL-006",
+    "EVAL-007",
+    "EVAL-008",
+    "EVAL-009",
+    "EVAL-010",
+];

package/dist/src/vector-cortex/ledger/adapter.js

@@ -0,0 +1,55 @@
+/**
+ * vector-cortex/ledger/adapter.ts — EventV2 ledger adapter (VC1A, task 5).
+ *
+ * A thin, pi-agnostic adapter combining the Mode-A codec, the canonical
+ * validator, and the VC1A emit seam so `vector_cortex_event_decoded` and
+ * `vector_cortex_event_validation_failed` are emitted by REAL code paths (not a
+ * hand-invoked reporter), gated by `VC1A_ENABLED()` inside `createLedgerReporter`.
+ *
+ * The live producer (wiring this into `extensions/mega-compact.ts` /
+ * `src/engine.ts`) is deferred to VC1C/VC1B (mirroring VC0B-I08); this sprint
+ * ships the seam + adapter as the clean single surface, with the acceptance
+ * aggregator exercising the real gated-emission path.
+ *
+ * Pure orchestration — no storage, no network, no side effects (PREVENT-PI-004).
+ */
+import { createEventCodec } from "./event-codec.js";
+import { validateEvents } from "./validator.js";
+import { createLedgerReporter } from "./emit.js";
+/** Build the ledger adapter over an injected emit callback (optional). */
+export function createLedgerAdapter(emit) {
+    const codec = createEventCodec();
+    const reporter = createLedgerReporter(emit);
+    return {
+        encode: (input) => codec.encode(input),
+        decode(event) {
+            const bytes = codec.decode(event);
+            reporter.eventDecoded({
+                session: event.sessionId,
+                seq: event.seq.toString(),
+                eventId: event.eventId,
+                bytes: bytes.length,
+                utf8Valid: event.utf8.valid,
+            });
+            return bytes;
+        },
+        validate(events) {
+            const result = validateEvents(events);
+            if (!result.ok) {
+                // Emit one event per failing occurrence with its REAL locator — a
+                // consumer of the feed can identify WHICH event failed (VC1A-I05).
+                for (const issue of result.issues) {
+                    reporter.validationFailed({
+                        session: issue.sessionId,
+                        seq: issue.seq.toString(),
+                        eventId: issue.eventId,
+                        code: issue.code,
+                    });
+                }
+            }
+            return result;
+        },
+        codec,
+        reporter,
+    };
+}