pi-mega-compact 0.16.3 → 0.17.0

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

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

@@ -0,0 +1,89 @@
+/**
+ * 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).
+ */
+
+/**
+ * A single structured evaluation-sample observation.
+ *
+ * Ordering contract: canonical JSONL metric order is `(session, seq, event)`,
+ * i.e. stable sort by session, then integer seq, then event-name byte order.
+ */
+export interface MetricEventV1 {
+  /** Session identifier (opaque). */
+  readonly session: string;
+  /** Monotonic per-session sequence number (must not decrease within a session). */
+  readonly seq: number;
+  /** Event/measurement name (deterministic tiebreak within equal seq). */
+  readonly event: string;
+  /** Numeric value of the sample in `unit`. */
+  readonly value: number;
+  /** Measurement unit — must be a known unit (see UNITS); rejects unknowns. */
+  readonly unit: string;
+  /** Triad observer mode that produced this sample: "A" | "B" | "C". */
+  readonly mode: "A" | "B" | "C";
+}
+
+/** Units the evaluator understands. Unknown units reject as EVAL_UNIT_UNKNOWN. */
+export const UNITS = ["ms", "bytes", "count", "ratio"] as const;
+
+/** A single non-monotonic or unknown-unit rejection result. */
+export type EvalReject =
+  | { readonly code: "EVAL_ORDER_INVALID"; readonly seq: number; readonly session: string }
+  | { readonly code: "EVAL_UNIT_UNKNOWN"; readonly unit: string }
+  | { readonly code: "EVAL_JSONL_TRUNCATED" };
+
+/**
+ * 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] as const;
+
+/**
+ * AnnotationV1 redaction metadata. Before JSONL serialization, payload bytes,
+ * prompts, and exact ledger text are replaced by digest/count metadata so the
+ * exact content never appears in the serialized stream (EVAL-REDACT-002).
+ */
+export interface AnnotationV1 {
+  /** Annotation identifier (items are addressed via the corpus manifest). */
+  readonly itemId: string;
+  /** Redaction journal of every payload/prompt/ledger-text field redacted. */
+  readonly redactions: ReadonlyArray<{
+    /** Field name in the original annotation that was redacted. */
+    readonly field: string;
+    /** SHA-256 digest of the redacted bytes (standard base64; decodes to the
+     *  same hash as the conformance fixture's `digestHex` — see annotations.test). */
+    readonly digest: string;
+    /** Byte length of the redacted content, when known. */
+    readonly bytes: number;
+    /** Redaction reason: "payload" | "prompt" | "ledger" (all are digested). */
+    readonly kind: "payload" | "prompt" | "ledger";
+  }>;
+  /** Count of redacted occurrences across the annotation. */
+  readonly redactedCount: number;
+}
+
+/**
+ * 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",
+] as const;
+
+export type EvalId = (typeof EVAL_IDS)[number];

package/src/vector-cortex/ledger/adapter.ts

@@ -0,0 +1,71 @@
+/**
+ * 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, type LedgerReporter } from "./emit.js";
+import type { EventCodec, EventEncodeInput, EventV2, ValidationResult } from "./types.js";
+
+export interface LedgerAdapter {
+  /** Encode raw bytes into a V2 occurrence (digest + strict UTF-8 + NFC derived). */
+  readonly encode: (input: EventEncodeInput) => EventV2;
+  /** Byte-decode an occurrence, emitting `vector_cortex_event_decoded`. */
+  readonly decode: (event: EventV2) => Uint8Array;
+  /** Canonical-validate a batch, emitting `..._validation_failed` on failure. */
+  readonly validate: (events: readonly EventV2[]) => ValidationResult;
+  /** The underlying codec (for tests that need a bare codec). */
+  readonly codec: EventCodec;
+  /** The underlying reporter (flag OFF emits nothing). */
+  readonly reporter: LedgerReporter;
+}
+
+/** Build the ledger adapter over an injected emit callback (optional). */
+export function createLedgerAdapter(emit?: (event: string, fields: Record<string, unknown>) => void): LedgerAdapter {
+  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,
+  };
+}

package/src/vector-cortex/ledger/compat-journal.ts

@@ -0,0 +1,234 @@
+/**
+ * vector-cortex/ledger/compat-journal.ts — CompatJournalV1 (VC1B, task 4).
+ *
+ * The downgrade-safety journal. From v2 activation every accepted v2 append
+ * atomically appends a record holding the original bytes, IDs, and a legacy
+ * projection or an explicit `unrepresentable` marker. The journal tracks its own
+ * lifetime state (prepared → copied → validated → switched) so the M2
+ * downgrade is resumable: a crash mid-journal never corrupts v2, and a restart
+ * resumes idempotently (the unique failure-injection contract).
+ *
+ * `active()` is true once ANY v2 append has been journaled — an old binary may
+ * only open the exported legacy copy, never v2 directly, once the journal is
+ * active (CONTRACTS §Store). Unrepresentable rows (e.g. invalid UTF-8 bytes have
+ * no lossless legacy projection) are listed on prepare and carried through the
+ * copy/validate/switch lifecycle.
+ *
+ * Durable in the same isolated occurrence-v2 SQLite DB as the ledger rows
+ * (append-only provenance: journal records are never UPDATE'd; only the
+ * singleton state row advances phase). PREVENT-002 parameterized; PREVENT-011
+ * no `any`; PREVENT-PI-004 local filesystem only; no console.log.
+ */
+
+import { DatabaseSync } from "node:sqlite";
+import { createHash } from "node:crypto";
+import type { CompatJournalV1 } from "./store.js";
+
+/** Journal lifecycle phase (append-only; the singleton state row advances). */
+export type JournalPhase = "prepared" | "copied" | "validated" | "switched";
+
+/** Downgrade-phase validation failure codes (registered as conformance rows). */
+export const MIG_DOWN_FAIL = {
+  NOT_ACTIVE: "MIG_DOWN_NOT_ACTIVE",
+  PHASE_UNREACHED: "MIG_DOWN_PHASE_UNREACHED",
+  SEQ_REGRESSION: "MIG_DOWN_SEQ_REGRESSION",
+  DIGEST_MISMATCH: "MIG_DOWN_DIGEST_MISMATCH",
+  SWITCH_UNSAFE: "MIG_DOWN_SWITCH_UNSAFE",
+} as const;
+export type MigDownCode = (typeof MIG_DOWN_FAIL)[keyof typeof MIG_DOWN_FAIL];
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS compat_journal_v1 (
+  session             TEXT    NOT NULL,
+  seq                 INTEGER NOT NULL,
+  event_id            TEXT    NOT NULL,
+  digest              TEXT    NOT NULL,
+  kind                TEXT    NOT NULL,
+  legacy_projection   TEXT,
+  unrepresentable     INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (session, seq)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS compat_journal_state (
+  id    INTEGER PRIMARY KEY CHECK (id = 1),
+  phase TEXT NOT NULL
+) STRICT;
+`;
+
+interface JournalRow {
+  session: string;
+  seq: number;
+  event_id: string;
+  digest: string;
+  kind: string;
+  legacy_projection: string | null;
+  unrepresentable: number;
+}
+
+/** Ensure the journal tables exist and seed the singleton phase row. */
+export function initCompatJournal(db: DatabaseSync): void {
+  db.exec(SCHEMA);
+  db.prepare(
+    `INSERT OR IGNORE INTO compat_journal_state (id, phase) VALUES (1, 'prepared')`,
+  ).run();
+}
+
+function phaseOf(db: DatabaseSync): JournalPhase {
+  const row = db
+    .prepare(`SELECT phase FROM compat_journal_state WHERE id = 1`)
+    .get() as { phase: JournalPhase } | undefined;
+  return row?.phase ?? "prepared";
+}
+
+/** Read the durable journal phase (for the M2 migration host seam). */
+export function journalPhase(db: DatabaseSync): JournalPhase {
+  return phaseOf(db);
+}
+
+function setPhase(db: DatabaseSync, phase: JournalPhase): void {
+  db.prepare(`UPDATE compat_journal_state SET phase = @phase WHERE id = 1`).run({
+    "@phase": phase,
+  });
+}
+
+/**
+ * Verify a recorded digest by RECOMPUTING sha256 over the base64 source embedded
+ * in the legacy projection and comparing it to the recorded digest (Q03: real
+ * digest parity, not a `sha256:` prefix check). Returns false when the projection
+ * is absent or malformed, or the digest does not match the recomputed hash.
+ */
+export function verifyLegacyDigest(
+  digest: string,
+  legacyProjection: string | null,
+): boolean {
+  if (legacyProjection === null) return false;
+  let rec: unknown;
+  try {
+    rec = JSON.parse(legacyProjection);
+  } catch {
+    return false;
+  }
+  const source = (rec as { source?: unknown }).source;
+  if (typeof source !== "string") return false;
+  const recomputed = `sha256:${createHash("sha256").update(Buffer.from(source, "base64")).digest("hex")}`;
+  return recomputed === digest;
+}
+
+/**
+ * Build the CompatJournalV1 over the isolated occurrence-v2 DB. Call
+ * `initCompatJournal` once before use. All record writes are append-only and
+ * best-effort/non-fatal so the agent loop is never broken (PREVENT-PI-004).
+ */
+export function createCompatJournal(db: DatabaseSync): CompatJournalV1 {
+  return {
+    active(): boolean {
+      try {
+        const row = db
+          .prepare(`SELECT 1 AS hit FROM compat_journal_v1 LIMIT 1`)
+          .get() as { hit: number } | undefined;
+        return row !== undefined;
+      } catch {
+        return false;
+      }
+    },
+    record(input): void {
+      const { occurrence, legacyProjection } = input;
+      try {
+        const unrep = legacyProjection === null;
+        db.prepare(
+          `INSERT INTO compat_journal_v1
+             (session, seq, event_id, digest, kind, legacy_projection, unrepresentable)
+           VALUES (@session, @seq, @event_id, @digest, @kind, @legacy, @unrep)
+           ON CONFLICT(session, seq) DO NOTHING`,
+        ).run({
+          "@session": occurrence.session,
+          "@seq": Number(occurrence.seq),
+          "@event_id": occurrence.eventId,
+          "@digest": occurrence.digest,
+          "@kind": occurrence.kind,
+          // Q06: an unrepresentable row stores NO projection (legacy_projection
+          // stays NULL); we never write a base64 body we cannot round-trip.
+          "@legacy": legacyProjection,
+          "@unrep": unrep ? 1 : 0,
+        });
+      } catch {
+        /* non-fatal journal write — never break the agent loop */
+      }
+    },
+    isUnrepresentable(eventId, digest): boolean {
+      try {
+        const row = db
+          .prepare(
+            `SELECT unrepresentable AS u FROM compat_journal_v1
+             WHERE event_id = @event_id AND digest = @digest
+             ORDER BY seq DESC LIMIT 1`,
+          )
+          .get({ "@event_id": eventId, "@digest": digest }) as { u: number } | undefined;
+        return row?.u === 1;
+      } catch {
+        return false;
+      }
+    },
+    prepare(): string[] {
+      const rows = db
+        .prepare(
+          `SELECT session, seq, event_id, digest, kind, legacy_projection, unrepresentable
+           FROM compat_journal_v1 ORDER BY session ASC, seq ASC`,
+        )
+        .all() as unknown as JournalRow[];
+      setPhase(db, "prepared");
+      return rows.filter((r) => r.unrepresentable === 1).map((r) => r.event_id);
+    },
+    copied(): void {
+      setPhase(db, "copied");
+    },
+    validate(): { ok: boolean; codes: readonly MigDownCode[] } {
+      const codes: MigDownCode[] = [];
+      const phase = phaseOf(db);
+      if (!isRepresentableState(phase, "copied")) codes.push(MIG_DOWN_FAIL.PHASE_UNREACHED);
+      if (!this.active()) codes.push(MIG_DOWN_FAIL.NOT_ACTIVE);
+      // Seq must be strictly increasing within a session (no regression).
+      const prev = new Map<string, number>();
+      const rows = db
+        .prepare(
+          `SELECT session, seq FROM compat_journal_v1 ORDER BY session ASC, seq ASC`,
+        )
+        .all() as unknown as Array<{ session: string; seq: number }>;
+      for (const r of rows) {
+        const last = prev.get(r.session);
+        if (last !== undefined && r.seq <= last) codes.push(MIG_DOWN_FAIL.SEQ_REGRESSION);
+        prev.set(r.session, r.seq);
+      }
+      // Digests must verify: recompute sha256 over the stored source and compare
+      // to the recorded digest (Q03 — real parity, not just a `sha256:` prefix).
+      for (const r of db
+        .prepare(
+          `SELECT digest, legacy_projection FROM compat_journal_v1 WHERE unrepresentable = 0`,
+        )
+        .all() as unknown as Array<{ digest: string; legacy_projection: string | null }>) {
+        if (r.legacy_projection === null) continue;
+        if (!verifyLegacyDigest(r.digest, r.legacy_projection)) {
+          codes.push(MIG_DOWN_FAIL.DIGEST_MISMATCH);
+        }
+      }
+      const ok = codes.length === 0;
+      if (ok) setPhase(db, "validated");
+      return { ok, codes: dedupe(codes) };
+    },
+    switched(): void {
+      if (this.active()) setPhase(db, "switched");
+    },
+  };
+}
+
+/** A phase has reached at least `required` in the prepare→…→switched order. */
+function isRepresentableState(phase: JournalPhase, required: JournalPhase): boolean {
+  const order: readonly JournalPhase[] = ["prepared", "copied", "validated", "switched"];
+  return order.indexOf(phase) >= order.indexOf(required);
+}
+
+function dedupe(codes: MigDownCode[]): MigDownCode[] {
+  const out: MigDownCode[] = [];
+  for (const c of codes) if (!out.includes(c)) out.push(c);
+  return out;
+}

package/src/vector-cortex/ledger/emit.ts

@@ -0,0 +1,86 @@
+/**
+ * vector-cortex/ledger/emit.ts — VC1A ledger emit seam.
+ *
+ * The single structured-event surface for the EventV2 ledger path. It mirrors
+ * the VC0B replay emit seam (`src/vector-cortex/replay/emit.ts`): the same
+ * non-fatal, structured-JSON `ts`+`event` contract (`src/log.ts` LogEntry),
+ * delivered through an injected emit callback so it stays pi-agnostic,
+ * deterministically testable, and network-free (PREVENT-PI-004).
+ *
+ * Carries only the two EventV2 events:
+ *   - vector_cortex_event_decoded          (a V2 occurrence was byte-decoded)
+ *   - vector_cortex_event_validation_failed (a V2 conformity check failed)
+ *
+ * Flag gating: this is VC1A's single real consumer of `VC1A_ENABLED()`. When the
+ * flag is OFF the reporter emits NOTHING (zero observability writes) — the
+ * VC1A mode-C byte-identical behavior — while the codec/validator still operate.
+ * The flag is read per-call so a live toggle takes effect immediately.
+ */
+
+import { VC1A_ENABLED } from "../../config/vector-cortex.js";
+
+export type LedgerEventName =
+  | "vector_cortex_event_decoded"
+  | "vector_cortex_event_validation_failed";
+
+/** Injected emit callback — same (event, fields) shape as the eval/replay seams. */
+export type LedgerEmitter = (event: string, fields: Record<string, unknown>) => void;
+
+export interface LedgerEventDecodedFields {
+  readonly session: string;
+  readonly seq: string;
+  readonly eventId: string;
+  readonly bytes: number;
+  readonly utf8Valid: boolean;
+}
+
+export interface LedgerValidationFailedFields {
+  readonly session: string;
+  readonly seq: string;
+  readonly eventId: string;
+  readonly code: string;
+}
+
+/** Typed, best-effort reporter bound to the two ledger event names. */
+export interface LedgerReporter {
+  readonly eventDecoded: (fields: LedgerEventDecodedFields) => void;
+  readonly validationFailed: (fields: LedgerValidationFailedFields) => void;
+}
+
+function safe(fn: (event: LedgerEventName, fields: Record<string, unknown>) => void): (
+  event: LedgerEventName,
+  fields: Record<string, unknown>,
+) => void {
+  return (event, fields) => {
+    try {
+      fn(event, fields);
+    } catch {
+      /* non-fatal observability — never break the agent loop */
+    }
+  };
+}
+
+/**
+ * Build a typed reporter over an injected emit callback. Emission is gated on
+ * `VC1A_ENABLED()` — flag OFF means zero ledger observability writes (mode-C
+ * parity). `emit` is optional: absent (or flag off) degrades to a no-op.
+ */
+export function createLedgerReporter(emit?: LedgerEmitter): LedgerReporter {
+  const fire = safe((event, fields) => {
+    if (VC1A_ENABLED()) emit?.(event, fields);
+  });
+  return {
+    eventDecoded(fields) {
+      fire("vector_cortex_event_decoded", fields as unknown as Record<string, unknown>);
+    },
+    validationFailed(fields) {
+      fire("vector_cortex_event_validation_failed", fields as unknown as Record<string, unknown>);
+    },
+  };
+}
+
+/** Export the event names for consumers that match on them. */
+export const LEDGER_EVENTS: readonly LedgerEventName[] = [
+  "vector_cortex_event_decoded",
+  "vector_cortex_event_validation_failed",
+] as const;

package/src/vector-cortex/ledger/event-codec.ts

@@ -0,0 +1,79 @@
+/**
+ * vector-cortex/ledger/event-codec.ts — EventV2 byte-authority codec, Mode A
+ * (VC1A, TRIAD_RESILIENCE).
+ *
+ * A retains `originalBytes` + a SHA-256 `bytesDigest` and classifies strict
+ * UTF-8 (success) vs invalid-byte content WITHOUT replacement decoding:
+ * `TextDecoder(..., {fatal:true})` either yields text or throws — invalid input
+ * is represented only as `{valid:false, base64}` and is NEVER lossy-replaced.
+ * `canonicalNfc` is computed ONLY as a derived field for valid UTF-8 and is
+ * NEVER used for identity, digest, or byte reconstruction — `decode` returns the
+ * authoritative `originalBytes` exactly.
+ *
+ * Mode B (`./event-codecB.ts`) is a genuinely independent implementation of the
+ * same byte rule; A and B share no subroutine and must agree byte-for-byte.
+ *
+ * Pure/deterministic — no console, no network, no side effects (PREVENT-PI-004).
+ */
+
+import nodeCrypto from "node:crypto";
+import type { BytesDigest, EventCodec, EventEncodeInput, EventV2 } from "./types.js";
+
+/** Mode-A internal SHA-256 helper (NOT shared with mode B). */
+function digestSha256A(bytes: Uint8Array): BytesDigest {
+  const hex = nodeCrypto.createHash("sha256").update(bytes).digest("hex");
+  return `sha256:${hex}`;
+}
+
+/** Mode-A internal base64 (NOT shared with mode B). */
+function base64EncodeA(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64");
+}
+
+/**
+ * Strict UTF-8 classification with FATAL decoding (never replaces invalid bytes
+ * with U+FFFD). Returns the decoded text, or `{valid:false, base64}`.
+ */
+export function classifyUtf8(bytes: Uint8Array): { valid: true; text: string } | { valid: false; base64: string } {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return { valid: true, text };
+  } catch {
+    return { valid: false, base64: base64EncodeA(bytes) };
+  }
+}
+
+/** Build the Mode-A byte-authority codec. */
+export function createEventCodec(): EventCodec {
+  return {
+    encode(input: EventEncodeInput): EventV2 {
+      const bytes = input.bytes;
+      const bytesDigest = digestSha256A(bytes);
+      const utf8 = classifyUtf8(bytes);
+      const event: EventV2 = {
+        schema: "event-v2",
+        sessionId: input.sessionId,
+        seq: input.seq,
+        eventId: input.eventId,
+        role: input.role,
+        kind: input.kind,
+        originalBytes: bytes,
+        bytesDigest,
+        utf8,
+        occurredAtMs: input.occurredAtMs,
+      };
+      if (input.toolCallId !== undefined) event.toolCallId = input.toolCallId;
+      // canonicalNfc is a DERIVED search key — valid UTF-8 only, never identity.
+      if (utf8.valid) event.canonicalNfc = utf8.text.normalize("NFC");
+      return event;
+    },
+
+    decode(event: EventV2): Uint8Array {
+      return event.originalBytes;
+    },
+
+    classifyUtf8,
+  };
+}
+
+export type { BytesDigest, EventV2 };