pi-mega-compact 0.16.2 → 0.17.0

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

@@ -0,0 +1,380 @@
+/**
+ * vector-cortex/ledger/store.ts — VC1B capability-separated ledger contracts.
+ *
+ * Owns `LedgerReader` / `LedgerWriter` / `LedgerAdmin` and `CompatJournalV1`.
+ * The ledger is append-only, seq is monotonic per session, a tool RESULT names
+ * exactly one earlier call in the same session, and duplicates are identified by
+ * `(eventId, digest)` only (two occurrences may share bytes at distinct seq).
+ *
+ * Capability gating mirrors the host `asReader/asWriter/asAdmin` pattern: a
+ * consumer receives ONLY what it needs. Dashboard GET receives `LedgerReader`;
+ * only ingestion receives `LedgerWriter`; only the migration coordinator
+ * receives `LedgerAdmin`. This keeps the neutral byte-authority ledger closed to
+ * anything but the sanctioned channels (CONTRACTS §Store and migration
+ * contracts).
+ *
+ * Pure type/schema definitions + small pure predicates. No storage, no console,
+ * no network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/**
+ * An accepted occurrence in the canonical v2 ledger. This is the durable row
+ * shape: the neutral byte authority plus the reference envelope. `digest` is the
+ * authoritative `sha256:${string}` of `sourceBytes`; `sourceBytes` round-trips
+ * exactly (never reconstructed from normalized text).
+ */
+export interface LedgerOccurrence {
+  /** The source session the occurrence belongs to (ledger scopes by session). */
+  readonly session: string;
+  /** Monotonic per-session sequence (never regresses for an accepted row). */
+  readonly seq: bigint;
+  /** Stable occurrence identity within the session (the EventV2 eventId). */
+  readonly eventId: string;
+  /** SHA-256 over sourceBytes (authoritative, `sha256:<hex>`). */
+  readonly digest: string;
+  /** Neutral occurrence kind (policy/user/assistant/tool/message...). */
+  readonly kind: string;
+  /** On a tool RESULT, references exactly one earlier call in this session. */
+  readonly toolCallId?: string;
+  /** Authoritative original bytes (byte authority). */
+  readonly sourceBytes: Uint8Array;
+}
+
+/**
+ * Identifier of a tool pair for a RESULT row: names exactly one earlier CALL's
+ * (session-local) eventId. Absent on non-result rows.
+ */
+export interface LedgerToolRef {
+  /** The session-local eventId of the CALL this RESULT closes. */
+  readonly callEventId: string;
+}
+
+/** Failure codes the writer surfaces on a rejected append (write path). */
+export type LedgerAppendCode = "EVT_TOOL_CALL_MISSING" | "EVT_SEQ_REGRESSION";
+
+/** Result of a single append attempt. */
+export type LedgerAppendResult =
+  | { ok: true; occurrence: LedgerOccurrence }
+  | { ok: false; code: LedgerAppendCode; rejected: LedgerOccurrence };
+
+/**
+ * Reader capability: read-access only. The dashboard's `GET
+ * /api/vector-cortex/ledger` is built on exactly this surface and nothing more —
+ * it can read counts/order/digests but never mutate.
+ */
+export interface LedgerReader {
+  readonly kind: "LedgerReader";
+  /** Accept the latest contiguous high-water (durable authority), or 0. */
+  highWater(session: string): bigint;
+  /** Contiguous accepted occurrences for a session in ascending `(seq,eventId)`. */
+  readSession(session: string): readonly LedgerOccurrence[];
+  /** Occurrences at or above `fromSeq` (inclusive) for a session. */
+  readFrom(session: string, fromSeq: bigint): readonly LedgerOccurrence[];
+  /** Count of accepted occurrences for a session. */
+  count(session: string): number;
+  /** Whether a `(eventId, digest)` pair is already accepted (unique key). */
+  hasOccurrence(session: string, eventId: string, digest: string): boolean;
+}
+
+/**
+ * Writer capability: append-only ingestion. Can create occurrences and advance
+ * the per-session seq — but cannot read arbitrary history, run migrations, or
+ * touch the compat journal. Enforces monotonic seq and tool-call reference
+ * completeness on every append.
+ */
+export interface LedgerWriter {
+  readonly kind: "LedgerWriter";
+  /** Append one occurrence; rejects on seq regression or a dangling tool ref. */
+  append(input: {
+    readonly session: string;
+    readonly seq: bigint;
+    readonly eventId: string;
+    readonly kind: string;
+    readonly toolCallId?: string;
+    readonly sourceBytes: Uint8Array;
+    readonly digest?: string;
+  }): LedgerAppendResult;
+  /** Append a batch, all-or-nothing per occurrence (each returns its outcome). */
+  appendBatch(inputs: ReadonlyArray<Parameters<LedgerWriter["append"]>[0]>): LedgerAppendResult[];
+}
+
+/**
+ * Admin capability: maintenance + migration coordination only. The sole surface
+ * with access to the compatibility journal switch and to run the M2
+ * copy/validate/switch. Never exposed to ingestion or to the dashboard reader.
+ */
+export interface LedgerAdmin {
+  readonly kind: "LedgerAdmin";
+  /** The compatibility journal (downgrade safety). */
+  readonly compat: CompatJournalV1;
+  /** Prepare + validate + switch the v2 ledger (M2), idempotently. */
+  migrateOccurrenceV2(): { ok: boolean; codes: readonly string[] };
+}
+
+/**
+ * CompatJournalV1 — the downgrade-safety journal. Every accepted v2 append
+ * atomically appends a journal record holding the original bytes, IDs, and a
+ * legacy projection or an explicit `unrepresentable` marker. The journal records
+ * its own lifecycle state (prepared/copied/validated/switched) so M2 is
+ * resumable and a stop mid-journal never corrupts v2.
+ */
+export interface CompatJournalV1 {
+  /** Whether any v2 append has activated the journal (journal present). */
+  active(): boolean;
+  /**
+   * Record a new v2 occurrence into the journal. `legacyProjection` holds the
+   * lossless legacy copy, or null when the row has no lossless legacy form — in
+   * which case the row is marked `unrepresentable` (e.g. invalid UTF-8 bytes).
+   */
+  record(input: {
+    readonly occurrence: LedgerOccurrence;
+    readonly legacyProjection: string | null;
+  }): void;
+  /** True when a row could not be projected to legacy and is marked. */
+  isUnrepresentable(eventId: string, digest: string): boolean;
+  /**
+   * Prepare a downgrade export: snapshot the journal for the copy/validate/switch
+   * lifecycle. Returns the list of unrepresentable rows (EVT/MIG reference).
+   */
+  prepare(): string[];
+  /** Mark the copy phase complete. */
+  copied(): void;
+  /** Validate the copied legacy export (sequence/digest parity). */
+  validate(): { ok: boolean; codes: readonly string[] };
+  /** Atomically switch authority to the legacy export (downgrade). */
+  switched(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory + capability gating (VC1B)
+// ---------------------------------------------------------------------------
+
+import type { DatabaseSync } from "node:sqlite";
+import { VC1B_ENABLED } from "../../config/vector-cortex.js";
+import {
+  openOccurrenceStore,
+  appendOccurrence,
+  ledgerHighWater,
+  readSessionOccurrences,
+  readFromSeq,
+  countOccurrences,
+  hasOccurrence,
+} from "./sqlite.js";
+import {
+  initCompatJournal,
+  createCompatJournal,
+  journalPhase,
+} from "./compat-journal.js";
+import {
+  m2Copy,
+  m2Validate,
+  m2Switch,
+  type M2Host,
+  type LegacyExportRow,
+} from "../migrations/occurrence-v2.js";
+
+/** The token that gates closures to a single capability (PREVENT-011-free). */
+const _capability: unique symbol = Symbol("mc-ledger-capability");
+
+interface ReaderToken {
+  readonly [_capability]: "reader";
+}
+interface WriterToken {
+  readonly [_capability]: "writer";
+}
+interface AdminToken {
+  readonly [_capability]: "admin";
+}
+
+/** A capability-gated ledger handle: access only what you were handed. */
+export interface LedgerHandle {
+  readonly reader: () => LedgerReader & ReaderToken;
+  readonly writer: () => LedgerWriter & WriterToken;
+  readonly admin: () => LedgerAdmin & AdminToken;
+  /** Close the underlying DB handle (test/sandbox teardown). */
+  readonly close: () => void;
+}
+
+/** Optional structured-event emitter (same shape as the other VC seams). */
+export type LedgerEmit = (event: string, fields: Record<string, unknown>) => void;
+
+/**
+ * Create the capability-separated occurrence-v2 ledger over its OWN isolated
+ * SQLite DB. `emit` is optional; occurrence-appended and compat-switch-committed
+ * events are only emitted when VC1B_ENABLED() and an emitter is supplied (mode-C
+ * parity: flag OFF / no emitter => zero observability writes).
+ *
+ * Normalization: `stateDir` gives the standard daemon location
+ * `<stateDir>/vector-cortex/occurrence-v2.db`; a bare `dbPath` overrides it
+ * (tests/rehearsal isolate the ledger). The compat journal shares the same DB
+ * so a v2 append + its journal record commit atomically.
+ */
+export function createLedgerStore(
+  opts: { readonly stateDir: string } | { readonly dbPath: string },
+  emit?: LedgerEmit,
+): LedgerHandle {
+  const dbPath =
+    "dbPath" in opts
+      ? opts.dbPath
+      : `${opts.stateDir}/vector-cortex/occurrence-v2.db`;
+  const db = openOccurrenceStore(dbPath);
+  initCompatJournal(db);
+  const compat = createCompatJournal(db);
+
+  const fire = (event: string, fields: Record<string, unknown>): void => {
+    if (!VC1B_ENABLED()) return;
+    try {
+      emit?.(event, fields);
+    } catch {
+      /* non-fatal observability — never break the agent loop */
+    }
+  };
+
+  const asReader = (): LedgerReader & ReaderToken => ({
+    kind: "LedgerReader",
+    [_capability]: "reader" as const,
+    highWater: (session) => ledgerHighWater(db, session),
+    readSession: (session) => readSessionOccurrences(db, session),
+    readFrom: (session, fromSeq) => readFromSeq(db, session, fromSeq),
+    count: (session) => countOccurrences(db, session),
+    hasOccurrence: (session, eventId, digest) =>
+      hasOccurrence(db, session, eventId, digest),
+  });
+
+  const asWriter = (): LedgerWriter & WriterToken => ({
+    kind: "LedgerWriter",
+    [_capability]: "writer" as const,
+    append(input) {
+      // The occurrence insert and its compat-journal record commit atomically
+      // inside one nested savepoint (CONTRACTS §Store: atomically appends).
+      db.exec("SAVEPOINT mc_ledger_app");
+      try {
+        const result = appendOccurrence(db, input);
+        if (result.ok) {
+          compat.record({
+            occurrence: result.occurrence,
+            legacyProjection: legacyProjectionOf(result.occurrence),
+          });
+        }
+        if (result.ok) {
+          db.exec("RELEASE mc_ledger_app");
+          fire("vector_cortex_occurrence_appended", {
+            session: result.occurrence.session,
+            seq: result.occurrence.seq.toString(),
+            eventId: result.occurrence.eventId,
+            digest: result.occurrence.digest,
+            kind: result.occurrence.kind,
+          });
+        } else {
+          db.exec("ROLLBACK TO mc_ledger_app");
+          db.exec("RELEASE mc_ledger_app");
+        }
+        return result;
+      } catch (e) {
+        db.exec("ROLLBACK TO mc_ledger_app");
+        db.exec("RELEASE mc_ledger_app");
+        throw e;
+      }
+    },
+    appendBatch(inputs) {
+      const out = [];
+      for (const input of inputs) out.push(this.append(input));
+      return out;
+    },
+  });
+
+  const asAdmin = (): LedgerAdmin & AdminToken => ({
+    kind: "LedgerAdmin",
+    [_capability]: "admin" as const,
+    compat,
+    migrateOccurrenceV2() {
+      // copy => validate => switch; resumable & idempotent. The M2 host wraps
+      // the live DB + journal so every phase transition advances the SAME
+      // singleton journal state machine (prepared→copied→validated→switched).
+      const unrepresentable = compat.prepare().length;
+      const mig = migrateHost(db, compat);
+      m2Copy(mig);
+      const v = m2Validate(mig);
+      if (v.ok) {
+        m2Switch(mig);
+        fire("vector_cortex_compat_switch_committed", {
+          session: "all",
+          unrepresentable,
+        });
+      }
+      return { ok: v.ok, codes: v.codes };
+    },
+  });
+
+  return { reader: asReader, writer: asWriter, admin: asAdmin, close: () => db.close() };
+}
+
+/**
+ * Lossless legacy projection for a v2 occurrence: its identity envelope plus
+ * base64 source bytes. Returns null (→ journal `unrepresentable` marker) when the
+ * source bytes do not form valid UTF-8, which the legacy pipeline cannot round-trip
+ * losslessly — those rows are listed rather than silently coerced (MIG-DOWN-003).
+ */
+function legacyProjectionOf(occ: LedgerOccurrence): string | null {
+  const source = Buffer.from(occ.sourceBytes);
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(source);
+  } catch {
+    return null;
+  }
+  return JSON.stringify({
+    session: occ.session,
+    eventId: occ.eventId,
+    kind: occ.kind,
+    digest: occ.digest,
+    source: source.toString("base64"),
+  });
+}
+
+/** Build an M2Host over the live ledger DB + journal (for migrateOccurrenceV2). */
+function migrateHost(
+  db: DatabaseSync,
+  journal: CompatJournalV1,
+): M2Host {
+  let staged: readonly LegacyExportRow[] | null = null;
+  return {
+    db,
+    phase: () => journalPhase(db),
+    journalActive: () => journal.active(),
+    journalRows: () => journalRowsOf(db),
+    writeStagedLegacy: (rows) => {
+      staged = rows;
+      journal.copied();
+    },
+    stagedLegacy: () => staged,
+    validateStaged: () => journal.validate(),
+    switchLegacy: () => journal.switched(),
+  };
+}
+
+/** Read the journaled occurrences as legacy-export rows. */
+function journalRowsOf(db: DatabaseSync): readonly LegacyExportRow[] {
+  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 Array<{
+    session: string;
+    seq: number;
+    event_id: string;
+    digest: string;
+    kind: string;
+    legacy_projection: string | null;
+    unrepresentable: number;
+  }>;
+  return rows.map((r) => ({
+    session: r.session,
+    seq: BigInt(r.seq),
+    eventId: r.event_id,
+    digest: r.digest,
+    kind: r.kind,
+    legacyProjection: r.legacy_projection,
+    unrepresentable: r.unrepresentable === 1,
+  }));
+}

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

@@ -0,0 +1,141 @@
+/**
+ * vector-cortex/ledger/types.ts — EventV2 / EventCodec byte-authority contract
+ * types, validation result codes, and the registered EVT conformance ID range.
+ *
+ * Owned by VC1A (canonical byte events). Consumes only reviewer-accepted
+ * predecessor contracts and [common contracts](../../CONTRACTS.md §EventV2),
+ * which are NORMATIVE here. `originalBytes` and its SHA-256 digest are the byte
+ * authority; strict UTF-8 classification is never lossy; `canonicalNfc` is a
+ * DERIVED comparison/search key only (never identity, digest, or reconstruction).
+ *
+ * Pure type/schema definitions + a short pure digest/classify predicate runtime
+ * (validator codes). No network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/** SHA-256 digest over the authoritative `originalBytes`, `sha256:<hex>`. */
+export type BytesDigest = `sha256:${string}`;
+
+/**
+ * EventV2 — the neutral byte-authority ledger occurrence. `schema:"event-v2"`
+ * is the discriminant tag of the union. Two events whose bytes differ by NFC
+ * normalization are DISTINCT identities (different `originalBytes`, different
+ * `bytesDigest`); their `canonicalNfc` (derived) may coincide but never drives
+ * equality, hashing, or byte reconstruction.
+ */
+export interface EventV2 {
+  schema: "event-v2";
+  sessionId: string;
+  seq: bigint;
+  eventId: string;
+  role: "policy" | "user" | "assistant" | "tool";
+  kind: string;
+  /** Authoritative original event bytes (byte authority). */
+  originalBytes: Uint8Array;
+  /** DigitalObjectIdentifier over originalBytes (authoritative digest). */
+  bytesDigest: BytesDigest;
+  /**
+   * Strict UTF-8 classification (NO lossy replacement). Invalid input is
+   * represented only as `{valid:false, base64}`.
+   */
+  utf8: { valid: true; text: string } | { valid: false; base64: string };
+  /** DERIVED NFC comparison/search key, valid UTF-8 only. Never identity. */
+  canonicalNfc?: string;
+  /** On a tool RESULT, references exactly one earlier CALL in this session. */
+  toolCallId?: string;
+  /** Wall-clock occurrence timestamp (monotonic for ordering; not the sort key). */
+  occurredAtMs: bigint;
+}
+
+/** Inputs to the byte-authority encoder. `bytes` is the sole byte source. */
+export interface EventEncodeInput {
+  sessionId: string;
+  seq: bigint;
+  eventId: string;
+  role: "policy" | "user" | "assistant" | "tool";
+  kind: string;
+  bytes: Uint8Array;
+  toolCallId?: string;
+  occurredAtMs: bigint;
+}
+
+/**
+ * EventCodec — byte-authority contract (normative, [CONTRACTS §EventV2]).
+ * `encode` computes the SHA-256 digest + strict UTF-8 classification + derived
+ * NFC; `decode` returns the authoritative `originalBytes` unchanged. Decoding
+ * never reconstructs bytes from normalized text — only from originalBytes.
+ */
+export interface EventCodec {
+  encode(input: EventEncodeInput): EventV2;
+  decode(event: EventV2): Uint8Array;
+  /**
+   * Strict UTF-8 classification: `fatal` decode succeeds, or the raw bytes are
+   * reported as `{valid:false, base64}` — never replacement-decode to U+FFFD.
+   */
+  classifyUtf8(bytes: Uint8Array): { valid: true; text: string } | { valid: false; base64: string };
+}
+
+/** Canonical validator failure codes (VC1A). */
+export type ValidationCode =
+  /** sha256(originalBytes) !== bytesDigest (authority corruption). */
+  | "EVT_DIGEST_MISMATCH"
+  /** The stored `utf8` discriminant contradicts a strict re-classification. */
+  | "EVT_UTF8_TAG_INVALID"
+  /** Duplicate (sessionId, seq, eventId) occurrence. */
+  | "EVT_DUPLICATE_ID";
+
+/**
+ * Deterministic validation result. `ok:false` carries the deduplicated failure
+ * codes (fixed priority order) AND the per-occurrence `issues` with real
+ * locators (sessionId/seq/eventId) so consumers can identify WHICH event failed.
+ */
+export type ValidationResult =
+  | { ok: true; ordered: readonly EventV2[] }
+  | { ok: false; codes: readonly ValidationCode[]; issues: readonly ValidationIssue[] };
+
+/** A single flagged validation issue (code + the offending occurrence locator). */
+export interface ValidationIssue {
+  readonly code: ValidationCode;
+  readonly sessionId: string;
+  readonly seq: bigint;
+  readonly eventId: string;
+}
+
+/**
+ * Registered EVT conformance ID range (EVT-001..030). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest bytes or
+ * exactly its listed failure code. Mirrors CUT_IDS / M3_IDS in replay/types.ts.
+ * EVT-001..015 are owned by VC1A (codec/validator); EVT-016..030 are owned by
+ * VC1B (occurrence ledger, see ledger/store.ts).
+ */
+export const EVT_IDS = [
+  "EVT-001",
+  "EVT-002",
+  "EVT-003",
+  "EVT-004",
+  "EVT-005",
+  "EVT-006",
+  "EVT-007",
+  "EVT-008",
+  "EVT-009",
+  "EVT-010",
+  "EVT-011",
+  "EVT-012",
+  "EVT-013",
+  "EVT-014",
+  "EVT-015",
+  "EVT-016",
+  "EVT-017",
+  "EVT-018",
+  "EVT-019",
+  "EVT-020",
+  "EVT-021",
+  "EVT-022",
+  "EVT-023",
+  "EVT-024",
+  "EVT-025",
+  "EVT-026",
+  "EVT-027",
+  "EVT-028",
+  "EVT-029",
+  "EVT-030",
+] as const;

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

@@ -0,0 +1,124 @@
+/**
+ * vector-cortex/ledger/validator.ts — EventV2 canonical validation (VC1A).
+ *
+ * Canonical ordering is `(sessionId, seq, eventId bytewise UTF-8)`: the sort is
+ * by the eventId's UTF-8 BYTES (unsigned) — NOT by JS string code-unit order —
+ * so multi-byte eventIds sort bytewise. Deterministic failure detection with a
+ * fixed priority order:
+ *   1. EVT_DIGEST_MISMATCH   — sha256(originalBytes) !== bytesDigest
+ *   2. EVT_UTF8_TAG_INVALID  — stored `utf8` discriminant contradicting a strict
+ *                              fatal re-classification of originalBytes
+ *   3. EVT_DUPLICATE_ID      — duplicate (sessionId, seq, eventId) occurrence
+ *
+ * The unique failure injection requirement: flip ONE stored byte while retaining
+ * the SHA-256 signature — the digest recomputation diverges and the validator
+ * returns EVT_DIGEST_MISMATCH (never a lossy replacement text, which is not
+ * produced anywhere in this module).
+ *
+ * Pure/deterministic — no console, no network, no side effects (PREVENT-PI-004).
+ */
+
+import nodeCrypto from "node:crypto";
+import { classifyUtf8 } from "./event-codec.js";
+import type { BytesDigest, EventV2, ValidationCode, ValidationIssue, ValidationResult } from "./types.js";
+
+/** Mode-A digest recompute (validator uses the codec's canonical digest rule). */
+function digestOf(bytes: Uint8Array): BytesDigest {
+  const hex = nodeCrypto.createHash("sha256").update(bytes).digest("hex");
+  return `sha256:${hex}`;
+}
+
+/** Bytewise UTF-8 comparator for eventId tiebreak (unsigned bytes, not code units). */
+function compareEventIdBytes(a: string, b: string): number {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  const n = Math.min(ab.length, bb.length);
+  for (let i = 0; i < n; i++) {
+    if (ab[i] !== bb[i]) return ab[i] < bb[i] ? -1 : 1;
+  }
+  if (ab.length !== bb.length) return ab.length < bb.length ? -1 : 1;
+  return 0;
+}
+
+/** Comparator: `(sessionId, seq, eventId bytewise UTF-8)`. */
+export function compareEvents(a: EventV2, b: EventV2): number {
+  if (a.sessionId !== b.sessionId) return a.sessionId < b.sessionId ? -1 : 1;
+  if (a.seq !== b.seq) return a.seq < b.seq ? -1 : 1;
+  return compareEventIdBytes(a.eventId, b.eventId);
+}
+
+/** Ascending (sessionId, seq, eventId-bytes) sort. Returns a new array. */
+export function sortEvents(events: readonly EventV2[]): EventV2[] {
+  return [...events].sort(compareEvents);
+}
+
+/** Recompute the digest and compare to the stored one (authority corruption). */
+function digestMismatch(event: EventV2): boolean {
+  return digestOf(event.originalBytes) !== event.bytesDigest;
+}
+
+/** The stored utf8 discriminant must match a strict fatal re-classification. */
+function utf8TagMismatch(event: EventV2): boolean {
+  const cls = classifyUtf8(event.originalBytes);
+  const stored = event.utf8;
+  if (stored.valid !== cls.valid) return true;
+  if (!stored.valid) {
+    // Both invalid: never compare decoded text; only the (valid, base64) shape.
+    return false;
+  }
+  if (!cls.valid) return true; // unreachable given `stored.valid === cls.valid`
+  // Both valid: compare the strict-decoded TEXT (no NFC — the tag stores raw text).
+  return stored.text !== cls.text;
+}
+
+/**
+ * Validate a batch of events. Returns `{ok:true, ordered}` when every event
+ * passes digest + UTF-8-tag consistency and no duplicate occurrence exists;
+ * otherwise `{ok:false, codes}` with the failure codes in fixed priority order,
+ * deduplicated, and an explicit issue list for diagnostics.
+ */
+export function validateEvents(events: readonly EventV2[]): ValidationResult {
+  const issues: ValidationIssue[] = [];
+
+  // Fixed priority order: DIGEST_MISMATCH, UTF8_TAG_INVALID, DUPLICATE_ID.
+  for (const e of events) {
+    if (digestMismatch(e)) {
+      issues.push({ code: "EVT_DIGEST_MISMATCH", sessionId: e.sessionId, seq: e.seq, eventId: e.eventId });
+    }
+  }
+  for (const e of events) {
+    if (utf8TagMismatch(e)) {
+      issues.push({ code: "EVT_UTF8_TAG_INVALID", sessionId: e.sessionId, seq: e.seq, eventId: e.eventId });
+    }
+  }
+
+  // Unambiguous (sessionId, seq, eventId) occurrence key (seq stringified — a
+  // bigint cannot be JSON-serialized directly).
+  const key = (e: EventV2): string => JSON.stringify([e.sessionId, e.seq.toString(), e.eventId]);
+  const seen = new Set<string>();
+  for (const e of sortEvents(events)) {
+    const k = key(e);
+    if (seen.has(k)) {
+      issues.push({ code: "EVT_DUPLICATE_ID", sessionId: e.sessionId, seq: e.seq, eventId: e.eventId });
+    }
+    seen.add(k);
+  }
+
+  if (issues.length === 0) {
+    return { ok: true, ordered: sortEvents(events) };
+  }
+  // Surface the per-occurrence issues (real locators) alongside the deduped
+  // codes so the adapter/observability feed can name WHICH event failed.
+  return { ok: false, codes: dedupe(issues.map((i) => i.code)), issues };
+}
+
+function dedupe(codes: ValidationCode[]): ValidationCode[] {
+  const out: ValidationCode[] = [];
+  for (const c of codes) {
+    if (!out.includes(c)) out.push(c);
+  }
+  return out;
+}
+
+/** Export the canonical ordering comparator for consumers (replay etc.). */
+export { compareEventIdBytes };