pi-mega-compact 0.16.3 → 0.17.1

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;