pi-mega-compact 0.16.2 → 0.17.0

package/src/vector-cortex/migrations/effective-cut-v2.ts

@@ -0,0 +1,149 @@
+/**
+ * vector-cortex/migrations/effective-cut-v2.ts — M3 copy/validate/switch
+ * migration (VC0B).
+ *
+ * Freezes the v2 effective replay cut: `min(boundarySafeSeq, committedSeq,
+ * capturedHighWater)` with pair retreat and anchor floor. The migration copies
+ * the candidate into the staged slot, validates the STAGED pointer against the
+ * minima and pair/anchor invariants (plus copy-match), and ONLY THEN atomically
+ * switches the active pointer. The three phases are exposed separately so a
+ * crash between validate and switch retains the OLD pointer and a restart
+ * resumes idempotently (the unique failure-injection contract).
+ *
+ * This is an internal developer seam: no dashboard/API change is necessary. It
+ * operates against the EXISTING host state via an injected M3Host interface —
+ * the future v2 compat-journal is owned by VC1B and is not introduced here.
+ */
+
+import { computeEffectiveCutV2 } from "../replay/cut.js";
+import type { ReplayToolPair, ReplayRetreatCode } from "../replay/types.js";
+
+/** Migration failure codes (registered in M3-001..010 as conformance rows). */
+export const M3_FAIL = {
+  MISSING_HOST: "M3_HOST_MISSING",
+  INVALID_MINIMA: "M3_MINIMA_VIOLATED",
+  PAIR_SPLIT: "M3_PAIR_SPLIT",
+  ANCHOR_CROSSED: "M3_ANCHOR_CROSSED",
+  COPY_MISMATCH: "M3_COPY_MISMATCH",
+} as const;
+export type M3FailureCode = (typeof M3_FAIL)[keyof typeof M3_FAIL];
+
+/** Live seq inputs that parameterize the effective cut. */
+export interface M3CutInput {
+  readonly requestedSeq: bigint;
+  readonly boundarySafeSeq: bigint;
+  readonly committedSeq: bigint;
+  readonly capturedHighWater: bigint;
+  readonly anchorFloor: bigint;
+  readonly pairs: readonly ReplayToolPair[];
+}
+
+/**
+ * Host state the migration reads/writes. copy/validate are read-only over host;
+ * switch is the only mutating step (atomically activates the staged pointer).
+ */
+export interface M3Host {
+  /** Actively used cut pointer (legacy prior). Never changes before switch. */
+  readonly oldPointer: bigint | null;
+  /** Persist the staged (new) cut pointer WITHOUT activating it. */
+  writeStaged(pointer: bigint): void;
+  /** The currently staged (new) pointer, persisted across restarts. */
+  stagedPointer(): bigint | null;
+  /** Contiguous durable authority high-water (min source). */
+  committedSeq(): bigint;
+  /** Atomic switch: activate the staged pointer and freeze the prior one. */
+  switchPointer(pointer: bigint): void;
+}
+
+export interface M3ValidateResult {
+  readonly ok: boolean;
+  readonly codes: readonly M3FailureCode[];
+  readonly retreats: readonly { code: ReplayRetreatCode; fromSeq: bigint; toSeq: bigint }[];
+  readonly effectiveSeq: bigint;
+}
+
+/** Pure effective-cut computation (min-of-three + retreat + floor). */
+export function m3Compute(input: M3CutInput): bigint {
+  return computeEffectiveCutV2(input).cut.effectiveSeq;
+}
+
+/**
+ * Phase 1 — copy: compute the candidate effective cut and stage it via the host
+ * (without activating). Returns the staged seq.
+ */
+export function m3Copy(host: M3Host, input: M3CutInput): bigint {
+  const effective = m3Compute(input);
+  host.writeStaged(effective);
+  return effective;
+}
+
+/**
+ * Phase 2 — validate: the host's STAGED pointer must equal the freshly computed
+ * effective cut (copy-match), respect the minima, not split a pair, and never
+ * fall below the anchor floor. Failure codes:
+ *   M3_HOST_MISSING     — no staged pointer at all
+ *   M3_COPY_MISMATCH    — staged != freshly computed effective
+ *   M3_MINIMA_VIOLATED  — effective exceeds a source minimum (or requested)
+ *   M3_PAIR_SPLIT       — effective splits a tool call/result pair
+ *   M3_ANCHOR_CROSSED   — effective is below the anchor floor
+ */
+export function m3Validate(host: M3Host, input: M3CutInput): M3ValidateResult {
+  const codes: M3FailureCode[] = [];
+  const { cut, retreats } = computeEffectiveCutV2(input);
+  const expected = cut.effectiveSeq;
+
+  const staged = host.stagedPointer();
+  if (staged === null) {
+    codes.push(M3_FAIL.MISSING_HOST);
+  } else {
+    if (staged !== expected) codes.push(M3_FAIL.COPY_MISMATCH);
+    if (
+      staged > input.boundarySafeSeq ||
+      staged > host.committedSeq() ||
+      staged > input.capturedHighWater ||
+      staged > input.requestedSeq
+    ) {
+      codes.push(M3_FAIL.INVALID_MINIMA);
+    }
+    for (const p of input.pairs) {
+      if (p.callSeq <= staged && staged < p.resultSeq) {
+        codes.push(M3_FAIL.PAIR_SPLIT);
+        break;
+      }
+    }
+    if (staged < input.anchorFloor) codes.push(M3_FAIL.ANCHOR_CROSSED);
+  }
+
+  return {
+    ok: codes.length === 0,
+    codes,
+    retreats,
+    effectiveSeq: expected,
+  };
+}
+
+/**
+ * Phase 3 — switch: atomic activation of the staged pointer. Only call after
+ * m3Validate reports ok; the host performs the durable pointer flip.
+ */
+export function m3Switch(host: M3Host, input: M3CutInput): bigint {
+  const effective = m3Compute(input);
+  host.switchPointer(effective);
+  return effective;
+}
+
+/**
+ * Run the full copy-validate-switch migration against a host. On validation
+ * failure the switch is NOT performed and the host retains its previous pointer
+ * (crash-safety / copy-validate-switch).
+ */
+export function migrateEffectiveCutV2(
+  host: M3Host,
+  input: M3CutInput,
+): { ok: boolean; codes: readonly M3FailureCode[]; effectiveSeq: bigint } {
+  m3Copy(host, input);
+  const v = m3Validate(host, input);
+  if (!v.ok) return { ok: false, codes: v.codes, effectiveSeq: v.effectiveSeq };
+  m3Switch(host, input);
+  return { ok: true, codes: [], effectiveSeq: v.effectiveSeq };
+}

package/src/vector-cortex/migrations/occurrence-v2.ts

@@ -0,0 +1,192 @@
+/**
+ * vector-cortex/migrations/occurrence-v2.ts — M2 copy/validate/switch migration
+ * for the occurrence-v2 ledger + compat journal (VC1B).
+ *
+ * M2 converts the neutral v2 ledger into a lossless legacy export so an OLD
+ * binary may keep reading after a downgrade. It follows the compat-journal
+ * copy/validate/switch contract: COPY the v2 rows + journal records into the
+ * staged legacy export, VALIDATE the staged export (seq monotonicity + digest
+ * parity + unrepresentable rows listed), and ONLY THEN atomically SWITCH
+ * authority to the export. Each phase is exposed separately so a crash between
+ * validate and switch retains the OLD authority and a restart resumes
+ * idempotently (the unique failure-injection contract — terminate after
+ * `validated` and before `switched`, restart switches once without duplicate
+ * rows).
+ *
+ * Runs against an injected M2Host so the migration is deterministic and
+ * testable. Never mutates v2; the export is a NEW copy (silent direct downgrade
+ * is rejected). Registered conformance rows: M2-001..015 + MIG-DOWN-001.
+ * PREVENT-002/011/PI-004 honored; no console.log.
+ */
+
+import type { DatabaseSync } from "node:sqlite";
+import { MIG_DOWN_FAIL, verifyLegacyDigest } from "../ledger/compat-journal.js";
+
+/** M2 failure codes (downgrade export). */
+export const M2_FAIL = {
+  ...MIG_DOWN_FAIL,
+  COPY_MISSING: "M2_COPY_MISSING",
+  UNREPRESENTABLE_UNLISTED: "M2_UNREPRESENTABLE_UNLISTED",
+} as const;
+export type M2MigrationCode = (typeof M2_FAIL)[keyof typeof M2_FAIL];
+
+/** A legacy export row derived from a v2 occurrence (or an unrepresentable marker). */
+export interface LegacyExportRow {
+  readonly session: string;
+  readonly seq: bigint;
+  readonly eventId: string;
+  readonly digest: string;
+  readonly kind: string;
+  readonly legacyProjection: string | null;
+  readonly unrepresentable: boolean;
+}
+
+/**
+ * The host the migration reads from and writes to. copy/validate are read-only
+ * over v2; switch is the only mutating step (atomically activating the legacy
+ * export as the openable authority). All phase transitions delegate to the
+ * compat journal's lifecycle so validate/switch advance the same singleton
+ * state machine (prepared→copied→validated→switched).
+ */
+export interface M2Host {
+  readonly db: DatabaseSync;
+  /** Durable journal phase (prepared/copied/validated/switched). */
+  readonly phase: () => string;
+  /** Whether the journal is active (any v2 append journaled). */
+  readonly journalActive: () => boolean;
+  /** All journaled occurrences (v2 source of truth for the export). */
+  readonly journalRows: () => readonly LegacyExportRow[];
+  /** Stage the legacy export rows (idempotent; never activates). */
+  readonly writeStagedLegacy: (rows: readonly LegacyExportRow[]) => void;
+  /** The staged legacy export (null when not yet staged). */
+  readonly stagedLegacy: () => readonly LegacyExportRow[] | null;
+  /** Validate the staged export against the journal (advances to `validated`). */
+  readonly validateStaged: () => { ok: boolean; codes: readonly string[] };
+  /** Atomically switch authority to the legacy export (advances to `switched`). */
+  readonly switchLegacy: () => void;
+}
+
+/** The freshly computed legacy export from the v2 journal (expected bytes). */
+export function computeLegacyExport(host: M2Host): readonly LegacyExportRow[] {
+  return host.journalRows();
+}
+
+/** Phase 1 — copy: stage the legacy export without activating. Returns rows. */
+export function m2Copy(host: M2Host): readonly LegacyExportRow[] {
+  const rows = computeLegacyExport(host);
+  host.writeStagedLegacy(rows);
+  return rows;
+}
+
+/**
+ * Phase 2 — validate: the staged export must equal the freshly computed one
+ * (copy-match), the journal must be active and have reached the `copied`
+ * phase, seq must be monotonic per session, digests must be well-formed, and
+ * every unrepresentable row must be listed. Advances to `validated` only when
+ * every check passes (so a crash here leaves authority unchanged).
+ */
+export function m2Validate(host: M2Host): M2ValidateResult {
+  const codes: M2MigrationCode[] = [];
+  const staged = host.stagedLegacy();
+  const expected = computeLegacyExport(host);
+
+  if (staged === null) {
+    codes.push(M2_FAIL.COPY_MISSING);
+  } else {
+    const sameRows =
+      staged.length === expected.length &&
+      staged.every(
+        (r, i) =>
+          r.session === expected[i]!.session &&
+          r.seq === expected[i]!.seq &&
+          r.eventId === expected[i]!.eventId &&
+          r.unrepresentable === expected[i]!.unrepresentable,
+      );
+    if (!sameRows) codes.push(M2_FAIL.COPY_MISSING);
+    // Seq monotonic per session (no regression).
+    const prev = new Map<string, bigint>();
+    for (const r of staged) {
+      const last = prev.get(r.session);
+      if (last !== undefined && r.seq <= last) codes.push(M2_FAIL.SEQ_REGRESSION);
+      prev.set(r.session, r.seq);
+    }
+    // Digests on representable rows must verify: recompute sha256 over the stored
+    // source and compare to the recorded digest (Q03 — real parity).
+    for (const r of staged) {
+      if (!r.unrepresentable && !verifyLegacyDigest(r.digest, r.legacyProjection)) {
+        codes.push(M2_FAIL.DIGEST_MISMATCH);
+      }
+    }
+    // Every unrepresentable row is explicitly flagged (MIG-DOWN-003).
+    for (const r of expected) {
+      if (r.unrepresentable) {
+        const flag = staged.find(
+          (s) => s.session === r.session && s.seq === r.seq && s.unrepresentable,
+        );
+        if (!flag) codes.push(M2_FAIL.UNREPRESENTABLE_UNLISTED);
+      }
+    }
+  }
+
+  if (!host.journalActive()) codes.push(M2_FAIL.NOT_ACTIVE);
+  if (host.phase() !== "copied") codes.push(M2_FAIL.PHASE_UNREACHED);
+
+  if (codes.length === 0) {
+    const v = host.validateStaged();
+    if (!v.ok) {
+      // Q05: narrow the host's string codes through a runtime type guard instead
+      // of an unchecked cast — unknown codes are dropped, never mis-typed.
+      for (const c of v.codes) if (isM2MigrationCode(c)) codes.push(c);
+    }
+  }
+  const ok = codes.length === 0;
+  return { ok, codes: dedupe(codes) };
+}
+
+/** M2 downgrade-export validation result. */
+export interface M2ValidateResult {
+  readonly ok: boolean;
+  readonly codes: readonly M2MigrationCode[];
+}
+
+/**
+ * Phase 3 — switch: atomic activation of the legacy export as the openable
+ * authority. Only call after m2Validate reports ok; the journal advances to
+ * `switched` and v2 becomes read-only-archival. Idempotent on resume.
+ */
+export function m2Switch(host: M2Host): void {
+  host.switchLegacy();
+}
+
+/** Registered M2 conformance ID range (M2-001..015). */
+export const M2_IDS = [
+  "M2-001",
+  "M2-002",
+  "M2-003",
+  "M2-004",
+  "M2-005",
+  "M2-006",
+  "M2-007",
+  "M2-008",
+  "M2-009",
+  "M2-010",
+  "M2-011",
+  "M2-012",
+  "M2-013",
+  "M2-014",
+  "M2-015",
+] as const;
+
+/** Registered MIG-DOWN conformance ID (MIG-DOWN-001). */
+export const MIG_DOWN_IDS = ["MIG-DOWN-001"] as const;
+
+/** Runtime narrowing: is `code` a known M2 migration failure code? */
+function isM2MigrationCode(code: string): code is M2MigrationCode {
+  return (Object.values(M2_FAIL) as string[]).includes(code);
+}
+
+function dedupe(codes: M2MigrationCode[]): M2MigrationCode[] {
+  const out: M2MigrationCode[] = [];
+  for (const c of codes) if (!out.includes(c)) out.push(c);
+  return out;
+}

package/src/vector-cortex/replay/cut.ts

@@ -0,0 +1,169 @@
+/**
+ * vector-cortex/replay/cut.ts — ReplayCutV2 effective-cut calculator (VC0B).
+ *
+ * M3 effective-cut rule: effective = min(boundarySafeSeq, committedSeq,
+ * capturedHighWater), capped by requestedSeq, then retreated to the call
+ * boundary whenever the candidate intersects a tool call/result pair, then
+ * clamped to the recent-anchor floor. On a tie among the min sources we choose
+ * the LOWER source order and record CUT_LOWEST_SOURCE_ORDER. This is the
+ * successor to the legacy capped-replay effective cut — the defect at
+ * docs/vector-cortex/SPRINT_PLAN.md M3 ("capped replay effective cut must
+ * respect boundary/commit/capture minima") is fixed here.
+ *
+ * Pure/deterministic — no network, no side effects (PREVENT-PI-004).
+ */
+
+import type {
+  ReplayCutV2,
+  ReplayRetreatCode,
+  ReplayRetreatRecord,
+  ReplayToolPair,
+} from "./types.js";
+
+export interface EffectiveCutInput {
+  /** Caller's desired cap; effective never exceeds this. */
+  readonly requestedSeq: bigint;
+  /** Largest pair-safe cap (already boundary-safe). */
+  readonly boundarySafeSeq: bigint;
+  /** Contiguous durable authority high-water. */
+  readonly committedSeq: bigint;
+  /** Derived high-water captured/frozen at replay start. */
+  readonly capturedHighWater: bigint;
+  /** Recent-anchor floor (inclusive lower bound the cut never crosses). */
+  readonly anchorFloor: bigint;
+  /** Tool call/result pairs (callSeq < resultSeq) to reason over. */
+  readonly pairs: readonly ReplayToolPair[];
+}
+
+export interface EffectiveCutOutput {
+  readonly cut: ReplayCutV2;
+  readonly retreats: readonly ReplayRetreatRecord[];
+}
+
+const MIN_SOURCES = ["boundary", "committed", "captured"] as const;
+type MinSource = (typeof MIN_SOURCES)[number];
+
+/**
+ * min-of-three, capped by requestedSeq, with deterministic lower-source
+ * tie-breaking. Returns the min value and every source that tied for it.
+ * On a tie the LOWER source order wins; `sources[0]` is the winning source.
+ */
+function minOfCapped(
+  requestedSeq: bigint,
+  boundarySafeSeq: bigint,
+  committedSeq: bigint,
+  capturedHighWater: bigint,
+): { value: bigint; sources: MinSource[] } {
+  const values: [MinSource, bigint][] = [
+    ["boundary", boundarySafeSeq],
+    ["committed", committedSeq],
+    ["captured", capturedHighWater],
+  ];
+  const minVal = values.reduce<bigint>((a, [, v]) => (v < a ? v : a), requestedSeq);
+  const floors = values.filter(([, v]) => v === minVal).map(([s]) => s);
+  // If a source value exceeds requestedSeq it is capped away; the min is
+  // positioned at requestedSeq only when every source is above the request.
+  const value = floors.length > 0 ? minVal : requestedSeq;
+  return { value, sources: floors.length > 0 ? floors : ["boundary"] };
+}
+
+/** True when a cut at seq `e` does NOT split any tool call/result pair. */
+export function cutIsPairSafe(e: bigint, pairs: readonly ReplayToolPair[]): boolean {
+  for (const p of pairs) {
+    // Cutting at e keeps events with seq <= e. A pair is split when the call
+    // (callSeq) is kept but the result (resultSeq) is dropped.
+    if (p.callSeq <= e && e < p.resultSeq) return false;
+  }
+  return true;
+}
+
+/**
+ * Retreat `e` upward-locked toward the call boundary of any pair it splits.
+ * Returns the largest pair-safe e <= start, never below `floor`.
+ *
+ * `splitResolved` is true when a CUT_TOOL_PAIR_SPLIT retreat occurred; when a
+ * retreat would cross the floor the cut clamps AT the floor and the reason
+ * becomes CUT_ANCHOR_FLOOR (the floor is assumed pair-safe for legal inputs).
+ */
+function retreatAgainstPairs(
+  start: bigint,
+  pairs: readonly ReplayToolPair[],
+  floor: bigint,
+): { effective: bigint; split: boolean; floorClamped: boolean } {
+  let e = start;
+  let split = false;
+  let floorClamped = false;
+  for (;;) {
+    let hit = false;
+    for (const p of pairs) {
+      if (p.callSeq <= e && e < p.resultSeq) {
+        hit = true;
+        const target = p.callSeq - 1n;
+        if (target < floor) {
+          // No-progress guard (VC0B-I12): the retreat target lies below the
+          // floor. If the floor itself still splits a pair we must not loop
+          // back onto it (that hangs the synchronous agent loop) — clamp AT
+          // the floor once and stop. The floor is taken as the legal cut.
+          e = floor;
+          floorClamped = true;
+        } else {
+          e = target;
+        }
+        split = true;
+        break;
+      }
+    }
+    // Terminate when no pair splits e, OR when we have already clamped to the
+    // floor (the floor is an absolute lower bound; we never retreat past it
+    // even if it is not itself pair-safe).
+    if (!hit || floorClamped) return { effective: e, split, floorClamped };
+  }
+}
+
+/**
+ * Compute the v2 effective cut. Pure with respect to the provided inputs.
+ */
+export function computeEffectiveCutV2(input: EffectiveCutInput): EffectiveCutOutput {
+  const { requestedSeq, boundarySafeSeq, committedSeq, capturedHighWater, anchorFloor, pairs } = input;
+
+  const retreats: ReplayRetreatRecord[] = [];
+
+  // Step 1 — min-of-three (capped by requestedSeq) with lower-source tie-break.
+  const min = minOfCapped(requestedSeq, boundarySafeSeq, committedSeq, capturedHighWater);
+  let effective: bigint = min.value;
+  // Tie among the min sources: resolved to the LOWER source order — record it.
+  if (min.sources.length > 1) {
+    retreats.push({
+      code: "CUT_LOWEST_SOURCE_ORDER",
+      fromSeq: effective,
+      toSeq: effective,
+    });
+  }
+
+  // Step 2 — pair retreat (never below the anchor floor).
+  const retreat = retreatAgainstPairs(effective, pairs, anchorFloor);
+  if (retreat.split && retreat.floorClamped) {
+    retreats.push({ code: "CUT_ANCHOR_FLOOR", fromSeq: effective, toSeq: retreat.effective });
+  } else if (retreat.split) {
+    retreats.push({ code: "CUT_TOOL_PAIR_SPLIT", fromSeq: effective, toSeq: retreat.effective });
+  }
+  effective = retreat.effective;
+
+  // Step 3 — final anchor-floor clamp (safety; legal floors are already >=).
+  if (effective < anchorFloor) {
+    retreats.push({ code: "CUT_ANCHOR_FLOOR", fromSeq: effective, toSeq: anchorFloor });
+    effective = anchorFloor;
+  }
+
+  const cut: ReplayCutV2 = {
+    requestedSeq,
+    boundarySafeSeq,
+    committedSeq,
+    capturedHighWater,
+    effectiveSeq: effective,
+  };
+  return { cut, retreats };
+}
+
+/** Re-export for callers that want just the code type. */
+export type { ReplayRetreatCode };

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

@@ -0,0 +1,89 @@
+/**
+ * vector-cortex/replay/emit.ts — VC0B replay emit seam (VC0B).
+ *
+ * The single structured-event surface for the replay/effective-cut path. It is
+ * the replay analogue of the VC0A eval observer (`src/vector-cortex/eval/
+ * observer.ts`): the same non-fatal, structured-JSON `ts`+`event` contract
+ * (see `src/log.ts` LogEntry), delivered through an injected emit callback so it
+ * stays pi-agnostic, deterministically testable, and network-free
+ * (PREVENT-PI-004). A future VC0C breaker/dashboard consumes these lines.
+ *
+ * This is deliberately MINIMAL — it is NOT a second metrics pipeline. It carries
+ * only the two events the replay/effective-cut path emits:
+ *   - vector_cortex_replay_cut_retreat     (a pair/anchor/lowest-source retreat)
+ *   - vector_cortex_replay_highwater_frozen (mode C: host transcript unchanged)
+ *
+ * Flag gating: this is VC0B's single real consumer of `VC0B_ENABLED`. When the
+ * flag is OFF, the reporter emits NOTHING (zero observability writes) — mirroring
+ * the VC0A mode-C pattern where flag-off produces zero evaluation writes. The
+ * ReplayReportV2 data (cut/effectiveSeq/capturedHighWater/mode) is returned by
+ * `runReplayV2` regardless; only the emitted observability is gated. The flag is
+ * read per-call so a live toggle takes effect immediately.
+ */
+
+import { VC0B_ENABLED } from "../../config/vector-cortex.js";
+
+export type ReplayEventName =
+  | "vector_cortex_replay_cut_retreat"
+  | "vector_cortex_replay_highwater_frozen";
+
+/** Injected emit callback — same (event, fields) shape as the eval observer. */
+export type ReplayEmitter = (event: string, fields: Record<string, unknown>) => void;
+
+export interface ReplayCutRetreatFields {
+  readonly session: string;
+  readonly code: string;
+  readonly fromSeq: string;
+  readonly toSeq: string;
+}
+
+export interface ReplayHighWaterFrozenFields {
+  readonly session: string;
+  readonly committedSeq: string;
+  readonly frozenHighWater: string;
+}
+
+/** Typed, best-effort reporter bound to the two replay event names. */
+export interface ReplayReporter {
+  readonly cutRetreat: (fields: ReplayCutRetreatFields) => void;
+  readonly highWaterFrozen: (fields: ReplayHighWaterFrozenFields) => void;
+}
+
+function safe(fn: (event: ReplayEventName, fields: Record<string, unknown>) => void): (
+  event: ReplayEventName,
+  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. Observability emission
+ * is gated on `VC0B_ENABLED()` — flag OFF means zero replay observability writes
+ * (VC0A mode-C parity). `emit` is optional: absent (or flag off) degrades to a
+ * no-op. The flag is read per-call so a live toggle takes effect immediately.
+ */
+export function createReplayReporter(emit?: ReplayEmitter): ReplayReporter {
+  const fire = safe((event, fields) => {
+    if (VC0B_ENABLED()) emit?.(event, fields);
+  });
+  return {
+    cutRetreat(fields) {
+      fire("vector_cortex_replay_cut_retreat", fields as unknown as Record<string, unknown>);
+    },
+    highWaterFrozen(fields) {
+      fire("vector_cortex_replay_highwater_frozen", fields as unknown as Record<string, unknown>);
+    },
+  };
+}
+
+/** Export the event names for consumers that match on them. */
+export const REPLAY_EVENTS: readonly ReplayEventName[] = [
+  "vector_cortex_replay_cut_retreat",
+  "vector_cortex_replay_highwater_frozen",
+] as const;