pi-mega-compact 0.16.3 → 0.17.0

package/dist/src/vector-cortex/replay/cut.js

@@ -0,0 +1,123 @@
+/**
+ * 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).
+ */
+const MIN_SOURCES = ["boundary", "committed", "captured"];
+/**
+ * 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, boundarySafeSeq, committedSeq, capturedHighWater) {
+    const values = [
+        ["boundary", boundarySafeSeq],
+        ["committed", committedSeq],
+        ["captured", capturedHighWater],
+    ];
+    const minVal = values.reduce((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, pairs) {
+    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, pairs, floor) {
+    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) {
+    const { requestedSeq, boundarySafeSeq, committedSeq, capturedHighWater, anchorFloor, pairs } = input;
+    const retreats = [];
+    // Step 1 — min-of-three (capped by requestedSeq) with lower-source tie-break.
+    const min = minOfCapped(requestedSeq, boundarySafeSeq, committedSeq, capturedHighWater);
+    let effective = 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 = {
+        requestedSeq,
+        boundarySafeSeq,
+        committedSeq,
+        capturedHighWater,
+        effectiveSeq: effective,
+    };
+    return { cut, retreats };
+}

package/dist/src/vector-cortex/replay/emit.js

@@ -0,0 +1,58 @@
+/**
+ * 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";
+function safe(fn) {
+    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) {
+    const fire = safe((event, fields) => {
+        if (VC0B_ENABLED())
+            emit?.(event, fields);
+    });
+    return {
+        cutRetreat(fields) {
+            fire("vector_cortex_replay_cut_retreat", fields);
+        },
+        highWaterFrozen(fields) {
+            fire("vector_cortex_replay_highwater_frozen", fields);
+        },
+    };
+}
+/** Export the event names for consumers that match on them. */
+export const REPLAY_EVENTS = [
+    "vector_cortex_replay_cut_retreat",
+    "vector_cortex_replay_highwater_frozen",
+];

package/dist/src/vector-cortex/replay/replay.js

@@ -0,0 +1,260 @@
+/**
+ * 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 } from "./emit.js";
+/** The pair map is per-session; a tool result references one earlier call by id. */
+export function extractToolPairs(occurrences) {
+    const calls = new Map();
+    const pairs = [];
+    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, ceiling) {
+    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, b) {
+    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) {
+    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 = {
+            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) {
+    const { occurrences, cut, mode, retreats, pairs } = opts;
+    const effective = cut.effectiveSeq;
+    // Strict ascending source order scan up to the effective cut.
+    const kept = [];
+    let reordered = 0;
+    let scanned = 0;
+    let bytesTotal = 0;
+    const keptBytes = [];
+    let prev = 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();
+    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 = {
+        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) {
+    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, mode, retreats) {
+    return {
+        cut,
+        mode,
+        counts: {
+            scanned: 0,
+            bytes: 0,
+            replayed: 0,
+            splitPairs: 0,
+            anchorFloorCuts: 0,
+            lowestSourceCuts: 0,
+            reordered: 0,
+            orphanToolEvents: 0,
+        },
+        retreats,
+    };
+}

package/dist/src/vector-cortex/replay/replayB.js

@@ -0,0 +1,73 @@
+/**
+ * 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).
+ */
+/**
+ * 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) {
+    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();
+    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/dist/src/vector-cortex/replay/types.js

@@ -0,0 +1,52 @@
+/**
+ * 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).
+ */
+/**
+ * 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",
+];
+/**
+ * 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",
+];