pi-mega-compact 0.16.2 → 0.17.0

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

@@ -0,0 +1,308 @@
+/**
+ * vector-cortex/replay/replay.ts — ReplayCutV2 replay scan (VC0B).
+ *
+ * Scans EventV2 occurrences in ascending `(seq, eventId bytewise UTF-8)`,
+ * computes the v2 effective cut (M3 min-of-three + pair retreat + anchor floor),
+ * and returns the replayed prefix bytes joined in strict source order. Before
+ * returning bytes it reports any CUT_TOOL_PAIR_SPLIT / CUT_ANCHOR_FLOOR retreat
+ * via the injected emit callback. Hard invariants are enforced zero-tolerance:
+ * the output is a source-order prefix with no orphan tool event and no split
+ * pair (reordered === 0, orphanToolEvents === 0, splitPairs-after-cut === 0).
+ *
+ * Mode A uses the v2 effective-cut calculator; mode B is a plain sequential
+ * boundary scan with no precomputed index; mode C leaves the host transcript
+ * unchanged and returns a zero-byte report with the derived high-water frozen.
+ *
+ * Pure wrt inputs, emits structured events via the replay emit seam
+ * (`src/vector-cortex/replay/emit.ts`) — no console, no network (PREVENT-PI-004).
+ */
+
+import { computeEffectiveCutV2 } from "./cut.js";
+import { computeEffectiveCutV2B } from "./replayB.js";
+import { createReplayReporter, type ReplayReporter } from "./emit.js";
+import type {
+  ReplayCutV2,
+  ReplayOccurrenceV2,
+  ReplayReportV2,
+  ReplayRetreatRecord,
+  ReplayToolPair,
+} from "./types.js";
+
+export interface ReplayV2Options {
+  readonly sessionId: string;
+  /** Occurrences in ascending (seq, eventId bytewise UTF-8). */
+  readonly occurrences: readonly ReplayOccurrenceV2[];
+  readonly requestedSeq: bigint;
+  readonly committedSeq: bigint;
+  readonly capturedHighWater: bigint;
+  readonly anchorFloor: bigint;
+  readonly mode?: "A" | "B" | "C";
+  /** Structured event reporter (ts+event); optional, best-effort. */
+  readonly reporter?: ReplayReporter;
+}
+
+/** The pair map is per-session; a tool result references one earlier call by id. */
+export function extractToolPairs(
+  occurrences: readonly ReplayOccurrenceV2[],
+): ReplayToolPair[] {
+  const calls = new Map<string, bigint>();
+  const pairs: ReplayToolPair[] = [];
+  let maxSeq = -1n;
+  for (const o of occurrences) {
+    if (o.seq > maxSeq) maxSeq = o.seq;
+    if (o.role === "tool" && o.toolCallId !== undefined) {
+      const callSeq = calls.get(o.toolCallId);
+      if (callSeq !== undefined && callSeq < o.seq) {
+        pairs.push({ callSeq, resultSeq: o.seq });
+        // Matched: remove so only genuinely-unclosed calls remain for the
+        // synthetic dangling-call pairs below (otherwise a matched call would
+        // also get a synthetic pair and force an over-retreat).
+        calls.delete(o.toolCallId);
+      }
+      continue;
+    }
+    // A call is an assistant event carrying a tool call id in EventV2; here we
+    // treat an assistant occurrence with a toolCallId as the CALL side.
+    if (o.toolCallId !== undefined) {
+      calls.set(o.toolCallId, o.seq);
+    }
+  }
+  // VC0B-I11: a call with NO observed result (dangling / unclosed) must still
+  // bound the cut. Mode B's open-call tracker retreats below such a call; to
+  // keep A and B in lockstep we surface each dangling call as a synthetic pair
+  // whose "result" lies one past the last observed seq. Any cut at/after the
+  // call then splits it, so A retreats to the call boundary exactly like B —
+  // and the synthetic unmatched marker also makes finalizeReplay count the
+  // dangling call as an orphan instead of reporting a false 0.
+  const pastEnd = maxSeq + 1n;
+  for (const callSeq of calls.values()) {
+    pairs.push({ callSeq, resultSeq: pastEnd });
+  }
+  return pairs;
+}
+
+/**
+ * Largest pair-safe seq <= `ceiling` (a cut at e keeps seq <= e and must not
+ * split any pair where callSeq <= e < resultSeq). Sequential boundary scan
+ * (mode B); no aggregate index required.
+ */
+export function largestPairSafeSeq(
+  pairs: readonly ReplayToolPair[],
+  ceiling: bigint,
+): bigint {
+  let e = ceiling;
+  for (;;) {
+    let blocked = false;
+    for (const p of pairs) {
+      if (p.callSeq <= e && e < p.resultSeq) {
+        e = p.callSeq - 1n;
+        blocked = true;
+        break;
+      }
+    }
+    if (!blocked) return e;
+  }
+}
+
+/** Ascending (seq, eventId) comparator over two occurrences. */
+export function compareOccurrences(a: ReplayOccurrenceV2, b: ReplayOccurrenceV2): number {
+  if (a.seq !== b.seq) return a.seq < b.seq ? -1 : 1;
+  const ea = a.eventId;
+  const eb = b.eventId;
+  if (ea < eb) return -1;
+  if (ea > eb) return 1;
+  return 0;
+}
+
+/**
+ * Run the v2 replay scan and produce a ReplayReportV2 plus the replayed bytes.
+ */
+export function runReplayV2(
+  options: ReplayV2Options,
+): { report: ReplayReportV2; bytes: Uint8Array } {
+  const { sessionId, occurrences, requestedSeq, committedSeq, capturedHighWater, anchorFloor } = options;
+  const mode = options.mode ?? "A";
+  const reporter = options.reporter ?? createReplayReporter();
+
+  // Mode C: unchanged host transcript — derived high-water frozen, zero bytes.
+  if (mode === "C") {
+    const cut = {
+      requestedSeq,
+      boundarySafeSeq: requestedSeq,
+      committedSeq,
+      capturedHighWater,
+      effectiveSeq: anchorFloor,
+    };
+    reporter.highWaterFrozen({
+      session: sessionId,
+      committedSeq: committedSeq.toString(),
+      frozenHighWater: capturedHighWater.toString(),
+    });
+    return {
+      report: zeroReport(cut, "C", []),
+      bytes: new Uint8Array(0),
+    };
+  }
+
+  const pairs = extractToolPairs(occurrences);
+
+  // Mode B: genuinely independent deterministic local cut (streams the bytes,
+  // shares no subroutine with A). Mode A: optimized pair-list + min-of-three.
+  if (mode === "B") {
+    const b = computeEffectiveCutV2B({
+      occurrences,
+      requestedSeq,
+      committedSeq,
+      capturedHighWater,
+      anchorFloor,
+    });
+    const bCut: ReplayCutV2 = {
+      requestedSeq,
+      boundarySafeSeq: b.boundarySafeSeq,
+      committedSeq,
+      capturedHighWater,
+      effectiveSeq: b.effectiveSeq,
+    };
+    return finalizeReplay({
+      occurrences,
+      cut: bCut,
+      mode: "B",
+      retreats: [],
+      pairs,
+    });
+  }
+
+  // Boundary-safe cap: largest pair-safe seq (sequential scan; mode A).
+  const boundarySafeSeq = largestPairSafeSeq(pairs, requestedSeq);
+
+  // effective cut: min-of-three + pair retreat + anchor floor.
+  const effectiveResult = computeEffectiveCutV2({
+    requestedSeq,
+    boundarySafeSeq,
+    committedSeq,
+    capturedHighWater,
+    anchorFloor,
+    pairs,
+  });
+  const { cut, retreats } = effectiveResult;
+
+  for (const r of retreats) {
+    reporter.cutRetreat({
+      session: sessionId,
+      code: r.code,
+      fromSeq: r.fromSeq.toString(),
+      toSeq: r.toSeq.toString(),
+    });
+  }
+
+  return finalizeReplay({
+    occurrences,
+    cut,
+    mode: "A",
+    retreats,
+    pairs,
+  });
+}
+
+/** Shared post-cut scan: strict (seq,eventId) prefix + invariant counting. */
+function finalizeReplay(opts: {
+  occurrences: readonly ReplayOccurrenceV2[];
+  cut: ReplayCutV2;
+  mode: "A" | "B";
+  retreats: readonly ReplayRetreatRecord[];
+  pairs: readonly ReplayToolPair[];
+}): { report: ReplayReportV2; bytes: Uint8Array } {
+  const { occurrences, cut, mode, retreats, pairs } = opts;
+  const effective = cut.effectiveSeq;
+
+  // Strict ascending source order scan up to the effective cut.
+  const kept: ReplayOccurrenceV2[] = [];
+  let reordered = 0;
+  let scanned = 0;
+  let bytesTotal = 0;
+  const keptBytes: Uint8Array[] = [];
+
+  let prev: ReplayOccurrenceV2 | null = null;
+  const effectiveBig = effective;
+  for (const o of occurrences) {
+    scanned += 1;
+    if (compareOccurrences(prev ?? o, o) > 0) reordered += 1;
+    prev = o;
+    if (o.seq > effectiveBig) break;
+    kept.push(o);
+    if (o.originalBytes) {
+      keptBytes.push(o.originalBytes);
+      bytesTotal += o.originalBytes.length;
+    }
+  }
+
+  // No orphan tool event: every kept tool RESULT must have its CALL kept too.
+  const keptCallIds = new Set<string>();
+  for (const o of kept) {
+    if (o.toolCallId !== undefined && o.role !== "tool") {
+      keptCallIds.add(o.toolCallId);
+    }
+  }
+  let orphanToolEvents = 0;
+  for (const o of kept) {
+    if (o.role === "tool" && o.toolCallId !== undefined && !keptCallIds.has(o.toolCallId)) {
+      orphanToolEvents += 1;
+    }
+  }
+  // Pair-splits that survived retreat (must be 0 for a correct boundary-safe cut).
+  let splitPairs = 0;
+  for (const p of pairs) {
+    if (p.callSeq <= effectiveBig && effectiveBig < p.resultSeq) splitPairs += 1;
+  }
+
+  const bytes = concatBytes(keptBytes);
+  const report: ReplayReportV2 = {
+    cut,
+    mode,
+    counts: {
+      scanned,
+      bytes: bytesTotal,
+      replayed: kept.length,
+      splitPairs,
+      anchorFloorCuts: retreats.filter((r) => r.code === "CUT_ANCHOR_FLOOR").length,
+      lowestSourceCuts: retreats.filter((r) => r.code === "CUT_LOWEST_SOURCE_ORDER").length,
+      reordered,
+      orphanToolEvents,
+    },
+    retreats,
+  };
+  return { report, bytes };
+}
+
+function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((a, c) => a + c.length, 0);
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.length;
+  }
+  return out;
+}
+
+function zeroReport(
+  cut: ReplayReportV2["cut"],
+  mode: "A" | "B" | "C",
+  retreats: ReplayReportV2["retreats"],
+): ReplayReportV2 {
+  return {
+    cut,
+    mode,
+    counts: {
+      scanned: 0,
+      bytes: 0,
+      replayed: 0,
+      splitPairs: 0,
+      anchorFloorCuts: 0,
+      lowestSourceCuts: 0,
+      reordered: 0,
+      orphanToolEvents: 0,
+    },
+    retreats,
+  };
+}

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

@@ -0,0 +1,97 @@
+/**
+ * vector-cortex/replay/replayB.ts — Mode B: independent deterministic replay cut
+ * (VC0B, TRIAD_RESILIENCE).
+ *
+ * Mode B is the deliberately SLOW-but-simple local algorithm. It is a genuine
+ * counterpart to mode A (`./cut.ts`): it shares NO subroutine with A — no
+ * `computeEffectiveCutV2`, no `largestPairSafeSeq`, no `cutIsPairSafe`, no
+ * min-of-three shortcut. Instead it walks the authoritative observed occurrence
+ * bytes in ascending `(seq, eventId)` order from seq 0 and, at EVERY step,
+ * checks tool-pair completeness (via its own open-call tracker built from the
+ * bytes) plus the authority high-water caps and the anchor floor.
+ *
+ * Contract parity: the v2 effective cut is a well-defined pure function of the
+ * stream and the authority inputs, so two independent implementations of the
+ * same rule MUST agree. A optimizes via a precomputed pair list + min-of-three +
+ * retreat; B brute-forces the LARGEST seq that satisfies every constraint by
+ * scanning — slower (O(n·open)), which is exactly its purpose: when the breaker
+ * flips to B it catches bugs in A because the two share no code.
+ *
+ * Pure/deterministic, no network, no side effects (PREVENT-PI-004).
+ */
+
+import type { ReplayOccurrenceV2 } from "./types.js";
+
+export interface ReplayBCut {
+  /** Largest pair-complete seq <= requestedSeq (comparable to A's boundary). */
+  readonly boundarySafeSeq: bigint;
+  /** The cut actually applied: largest pair-complete seq <= the authority cap,
+   *  never below the anchor floor. */
+  readonly effectiveSeq: bigint;
+}
+
+export interface ReplayBInput {
+  /** Occurrences in ascending (seq, eventId bytewise UTF-8) source order. */
+  readonly occurrences: readonly ReplayOccurrenceV2[];
+  readonly requestedSeq: 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;
+}
+
+/**
+ * Independent mode-B effective cut. Walks the occurrence bytes once, tracking
+ * open tool calls from the bytes themselves (no extracted pair list). The
+ * boundary-safe seq is the largest pair-complete seq <= requestedSeq; the
+ * effective seq is the largest pair-complete seq that also lies within the
+ * authority ceiling (requested/committed/captured, applied as independent
+ * sequential caps — no shared min-of-three) and at/above the anchor floor.
+ */
+export function computeEffectiveCutV2B(input: ReplayBInput): ReplayBCut {
+  const { occurrences, requestedSeq, committedSeq, capturedHighWater, anchorFloor } = input;
+
+  // Independent sequential authority ceiling (NOT A's minOfCapped).
+  let ceiling = requestedSeq;
+  if (ceiling > committedSeq) ceiling = committedSeq;
+  if (ceiling > capturedHighWater) ceiling = capturedHighWater;
+
+  // Open tool calls awaiting a result (toolCallId -> callSeq), built from bytes.
+  const open = new Map<string, bigint>();
+  let boundarySafeSeq = 0n; // largest pair-complete seq <= requestedSeq
+  let effectiveSeq = 0n; // largest pair-complete seq <= ceiling (>= floor)
+
+  for (const o of occurrences) {
+    if (o.seq > requestedSeq) break;
+    const s = o.seq;
+
+    if (o.toolCallId !== undefined && o.role !== "tool") {
+      // A CALL: it stays open until its result is observed.
+      open.set(o.toolCallId, s);
+    } else if (o.toolCallId !== undefined && o.role === "tool") {
+      // Its RESULT: the pair closes.
+      open.delete(o.toolCallId);
+    }
+
+    // A cut at `s` is pair-complete iff no still-open call lies at or below `s`
+    // (such a call's result is beyond the cut, so keeping the call orphans it).
+    let complete = true;
+    for (const cseq of open.values()) {
+      if (cseq <= s) {
+        complete = false;
+        break;
+      }
+    }
+    if (!complete) continue;
+
+    boundarySafeSeq = s;
+    if (s <= ceiling && s >= anchorFloor) effectiveSeq = s;
+  }
+
+  // Anchor floor is an absolute lower bound (parity with A's final clamp).
+  if (effectiveSeq < anchorFloor) effectiveSeq = anchorFloor;
+
+  return { boundarySafeSeq, effectiveSeq };
+}

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

@@ -0,0 +1,145 @@
+/**
+ * vector-cortex/replay/types.ts — ReplayCutV2 / ReplayReportV2 contract types
+ * and the registered CUT / M3 conformance ID ranges.
+ *
+ * Owned by VC0B (replay correctness). Consumes reviewer-accepted predecessor
+ * contracts and common contracts only (EventV2 minimal shape). Pure type/schema
+ * definitions — no runtime network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/**
+ * Minimal EventV2 occurrence shape sufficient for the replay scan, consumed
+ * contractually from EventV2 (VC1A owns the full codec). Ordering is
+ * `(sessionId, seq, eventId bytewise UTF-8)`. A tool result references exactly
+ * one earlier CALL in the same session via `toolCallId`.
+ */
+export interface ReplayOccurrenceV2 {
+  readonly sessionId: string;
+  /** Monotonic per-session sequence (bigint). */
+  readonly seq: bigint;
+  /** Occurrence id; bytewise UTF-8 tiebreak within equal seq. */
+  readonly eventId: string;
+  readonly role: "policy" | "user" | "assistant" | "tool";
+  readonly kind: string;
+  /** Present on a tool RESULT; names exactly one earlier CALL in this session. */
+  readonly toolCallId?: string;
+  /** Original event bytes (authoritative per EventV2); used for the byte count. */
+  readonly originalBytes?: Uint8Array;
+}
+
+/** A tool call/result pair in a session (call seq < result seq). */
+export interface ReplayToolPair {
+  readonly callSeq: bigint;
+  readonly resultSeq: bigint;
+}
+
+/**
+ * ReplayCutV2 — the five authoritative values of the effective cut.
+ *
+ * `effectiveSeq` is `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 anchor
+ * floor. Flags: `MEGACOMPACT_VC0B=0` routes to the legacy capped replay.
+ */
+export interface ReplayCutV2 {
+  /** Caller's desired cap (the largest seq the caller asked to replay to). */
+  readonly requestedSeq: bigint;
+  /** Largest pair-safe cap that never splits a tool call/result pair. */
+  readonly boundarySafeSeq: bigint;
+  /** Contiguous durable authority high-water (min source). */
+  readonly committedSeq: bigint;
+  /** Derived high-water captured/frozen at the start of replay (min source). */
+  readonly capturedHighWater: bigint;
+  /** The resulting cut actually applied to the replay scan. */
+  readonly effectiveSeq: bigint;
+}
+
+/** Retreat/retraction reasons recorded on a ReplayReportV2. */
+export type ReplayRetreatCode =
+  | "CUT_TOOL_PAIR_SPLIT"
+  | "CUT_ANCHOR_FLOOR"
+  | "CUT_LOWEST_SOURCE_ORDER";
+
+/** A single recorded retreat (fromSeq -> toSeq with its reason). */
+export interface ReplayRetreatRecord {
+  readonly code: ReplayRetreatCode;
+  readonly fromSeq: bigint;
+  readonly toSeq: bigint;
+}
+
+/**
+ * ReplayReportV2 — outcome of a replay scan. Counts are exact; the hard
+ * invariants (zero reordered pairs, zero orphan tool events, zero split pairs
+ * after the effective cut) are enforced as zero-tolerance.
+ */
+export interface ReplayReportV2 {
+  readonly cut: ReplayCutV2;
+  /** Triad mode that produced this report: "A" | "B" | "C". */
+  readonly mode: "A" | "B" | "C";
+  readonly counts: {
+    /** Total occurrences scanned (ascending (seq,eventId)). */
+    readonly scanned: number;
+    /** Bytes returned (sum of replayed originalBytes lengths). */
+    readonly bytes: number;
+    /** Occurrences replayed (seq <= effectiveSeq). */
+    readonly replayed: number;
+    /** Retreats of kind CUT_TOOL_PAIR_SPLIT. */
+    readonly splitPairs: number;
+    /** Retreats of kind CUT_ANCHOR_FLOOR. */
+    readonly anchorFloorCuts: number;
+    /** Tie-break retreats of kind CUT_LOWEST_SOURCE_ORDER. */
+    readonly lowestSourceCuts: number;
+    /** Reordered (out-of-source-order) pairs — MUST be 0. */
+    readonly reordered: number;
+    /** Orphan tool events after the cut — MUST be 0. */
+    readonly orphanToolEvents: number;
+  };
+  /** Every retreat applied, in apply order. */
+  readonly retreats: readonly ReplayRetreatRecord[];
+}
+
+/**
+ * Registered CUT conformance ID range (CUT-001..020). The acceptance test
+ * reads these rows from the v2 manifest and asserts their expected bytes/results.
+ */
+export const CUT_IDS = [
+  "CUT-001",
+  "CUT-002",
+  "CUT-003",
+  "CUT-004",
+  "CUT-005",
+  "CUT-006",
+  "CUT-007",
+  "CUT-008",
+  "CUT-009",
+  "CUT-010",
+  "CUT-011",
+  "CUT-012",
+  "CUT-013",
+  "CUT-014",
+  "CUT-015",
+  "CUT-016",
+  "CUT-017",
+  "CUT-018",
+  "CUT-019",
+  "CUT-020",
+] as const;
+
+/**
+ * Registered M3 conformance ID range (M3-001..010) for the effective-cut-v2
+ * migration (copy/validate/switch). The migration fixtures assert that crash
+ * after M3 copy validation but before pointer switch retains the old cut pointer
+ * and resumes idempotently.
+ */
+export const M3_IDS = [
+  "M3-001",
+  "M3-002",
+  "M3-003",
+  "M3-004",
+  "M3-005",
+  "M3-006",
+  "M3-007",
+  "M3-008",
+  "M3-009",
+  "M3-010",
+] as const;