agentfootprint 2.14.4 → 3.0.0

package/dist/esm/recorders/observability/BoundaryRecorder.js

@@ -75,8 +75,9 @@
  * }
  * ```
  */
-import { ROOT_RUNTIME_STAGE_ID, ROOT_SUBFLOW_ID, SequenceRecorder } from 'footprintjs/trace';
+import { ROOT_RUNTIME_STAGE_ID, ROOT_SUBFLOW_ID, SequenceStore, CommitRangeIndex, } from 'footprintjs/trace';
 import { SUBFLOW_IDS, STAGE_IDS, slotFromSubflowId } from '../../conventions.js';
+import { createRunIdObserver } from './observeRunId.js';
 /** Closed set of routing/wrapper subflow IDs that are pure plumbing.
  *  Slot subflows (`sf-system-prompt` / `sf-messages` / `sf-tools`) are
  *  NOT in this set — they're real context-engineering moments.
@@ -124,6 +125,53 @@ function isAgentInternalId(localId) {
     }
     return false;
 }
+function toBoundaryLabel(e) {
+    if (e.type === 'subflow.entry') {
+        return {
+            type: 'subflow.entry',
+            runtimeStageId: e.runtimeStageId,
+            subflowPath: e.subflowPath,
+            depth: e.depth,
+            ts: e.ts,
+            subflowId: e.subflowId,
+            localSubflowId: e.localSubflowId,
+            subflowName: e.subflowName,
+            ...(e.description !== undefined ? { description: e.description } : {}),
+            ...(e.primitiveKind !== undefined ? { primitiveKind: e.primitiveKind } : {}),
+            ...(e.slotKind !== undefined ? { slotKind: e.slotKind } : {}),
+            isAgentInternal: e.isAgentInternal,
+        };
+    }
+    return {
+        type: 'run.entry',
+        runtimeStageId: e.runtimeStageId,
+        subflowPath: e.subflowPath,
+        depth: e.depth,
+        ts: e.ts,
+    };
+}
+/** Build a BoundaryRangeLabel for the open side of a composition pair. */
+function toCompositionBoundaryLabel(e) {
+    return {
+        type: 'composition.start',
+        runtimeStageId: e.runtimeStageId,
+        subflowPath: e.subflowPath,
+        depth: e.depth,
+        ts: e.ts,
+        compositionKind: e.kind,
+        compositionName: e.name,
+    };
+}
+/** Clamp `getCommitCount()` returns to a safe non-negative integer.
+ *  Defensive against malformed injections returning NaN/Infinity/negatives
+ *  (security panel review YELLOW #2). */
+function sanitizeCommitCount(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    if (n < 0)
+        return 0;
+    return n;
+}
 let _counter = 0;
 /** Factory — matches the `inOutRecorder()` / `topologyRecorder()` style. */
 export function boundaryRecorder(options = {}) {
@@ -134,12 +182,35 @@ export function boundaryRecorder(options = {}) {
  * attach to the executor's FlowRecorder channel; exposes `subscribe()`
  * to wire to the agentfootprint typed-event dispatcher.
  *
- * Internally stores events in a `SequenceRecorder<DomainEvent>` so the
- * usual time-travel utilities (`getEntryRanges`, `accumulate`) work
- * out of the box.
+ * v5: composes a `SequenceStore<DomainEvent>` (storage) instead of
+ * extending the deprecated `SequenceRecorder<T>` base. Time-travel
+ * utilities (`getEntryRanges`, `accumulate`) are accessed through the
+ * store via the public read API on this class.
  */
-export class BoundaryRecorder extends SequenceRecorder {
+export class BoundaryRecorder {
     id;
+    /** Composition: storage shelf. */
+    store = new SequenceStore();
+    /**
+     * Phase 5 Layer 2 — interval index over commit indices, populated
+     * live as boundary entry/exit pairs fire. Consumers (Lens) read
+     * `enclosing(commitIdx)` for breadcrumbs and `overlapping(slice)`
+     * for time-range queries. Empty when `getCommitCount` is not
+     * injected. See `docs/design/boundary-commit-ranges.md`.
+     */
+    boundaryIndex = new CommitRangeIndex();
+    /** Open-range tokens keyed by `runtimeStageId` so the matching exit
+     *  can close the correct range. Pure side-table; cleared on runId
+     *  reset. Not exposed externally. */
+    openTokens = new Map();
+    /** Live commit-count accessor injected by the runner. Sanitized
+     *  (NaN/Infinity/negative → 0) before use. */
+    getCommitCount;
+    /** True when `getCommitCount` was explicitly injected. In LEGACY
+     *  MODE (false), `boundaryIndex` is intentionally NOT populated —
+     *  zero-width [0,0] ranges would mislead consumers querying the
+     *  index. Multi-panel review flagged this footgun. */
+    hasCommitTracking;
     /**
      * Tracks whether the most recent `llm.end` had toolCalls. Used to
      * classify the NEXT `llm.start` as `'tool→llm'` (vs `'user→llm'` if
@@ -147,50 +218,167 @@ export class BoundaryRecorder extends SequenceRecorder {
      * `llm.start` event after the classification is applied.
      */
     prevLLMEndHadTools = false;
+    /**
+     * Run-boundary observer — fires resetForNewRun() when
+     * traversalContext.runId changes between events AND no boundary is
+     * currently open. The "no open boundary" gate distinguishes:
+     *
+     *   - **Legitimate new run** — consumer reuses one recorder across
+     *     sequential `executor.run()` calls. All prior boundaries closed
+     *     before the second run began; openTokens is empty when the new
+     *     runId arrives → safe to wipe state so the second run doesn't
+     *     alias with the first.
+     *   - **Composition sub-run** — primitives like `LLMCall`, `Sequence`,
+     *     and `Parallel` internally spawn their own `FlowChartExecutor`
+     *     instances. Each sub-executor mints a NEW runId. When that
+     *     sub-executor fires events on the SHARED recorder, the recorder
+     *     is still inside the parent run — `openTokens` is non-empty.
+     *     Resetting here would wipe the parent's boundary index mid-run
+     *     (the bug Layer 4 surfaced in agentfootprint-lens fanout).
+     *
+     * The `openTokens.size === 0` check is the cleanest semantic signal:
+     * if nothing is in-flight, a runId change means "the consumer started
+     * fresh"; if something is open, the new runId is from a sub-executor
+     * nested inside the still-ongoing parent.
+     */
+    runIdGuard = createRunIdObserver(() => {
+        if (this.openTokens.size > 0) {
+            // Inside an active run — new runId is from a composition sub-
+            // executor (LLMCall / Sequence / Parallel). Do NOT reset.
+            return;
+        }
+        this.store.clear();
+        this.boundaryIndex.clear();
+        this.openTokens.clear();
+        this.prevLLMEndHadTools = false;
+    });
     constructor(options = {}) {
-        super();
         this.id = options.id ?? `boundary-${++_counter}`;
+        this.hasCommitTracking = options.getCommitCount !== undefined;
+        const raw = options.getCommitCount;
+        this.getCommitCount = raw === undefined ? () => 0 : () => sanitizeCommitCount(raw());
     }
+    /**
+     * Reset all transient state.
+     *
+     * **Composition-safe gate (Phase 5 Layer 4):** if `openTokens.size > 0`
+     * the call is a no-op. Rationale: `FlowChartExecutor.run()` calls
+     * `r.clear?.()` on every attached recorder during its pre-run loop.
+     * When agentfootprint composition primitives (LLMCall, Sequence,
+     * Parallel, etc.) propagate the parent's recorders to nested
+     * sub-executors, EACH sub-executor's pre-run clear loop calls
+     * `clear()` on the SHARED parent recorder mid-run — wiping live
+     * parent state. The `openTokens.size > 0` check distinguishes:
+     *
+     *   - **Legitimate reset** — consumer or executor calls `clear()`
+     *     when no boundary is in-flight (`openTokens` empty). Safe to
+     *     wipe; the recorder is idle.
+     *   - **Composition wipe** — sub-executor's pre-run clear fires
+     *     while the parent has open boundaries (`openTokens` non-empty).
+     *     Skip the wipe; the parent's state must be preserved.
+     *
+     * If a consumer needs to forcibly wipe state even with open tokens
+     * (e.g., manual recovery after a crashed run), pair `clear()` with
+     * an explicit `forceClear()` (TODO — add when the use case shows up;
+     * today the recorder lifecycle pattern is "one recorder per logical
+     * run" so leaked tokens shouldn't occur).
+     */
     clear() {
-        super.clear();
+        if (this.openTokens.size > 0) {
+            // Mid-run wipe attempt — almost certainly a sub-executor's
+            // pre-run clear via composition propagation. Skip.
+            return;
+        }
+        this.store.clear();
+        this.boundaryIndex.clear();
+        this.openTokens.clear();
         this.prevLLMEndHadTools = false;
+        this.runIdGuard.reset();
+    }
+    observeRunId(runId) {
+        this.runIdGuard.observe(runId);
     }
     // ── FlowRecorder hooks (footprintjs side) ───────────────────────────
     onRunStart(event) {
-        this.emit(buildRunEvent('run.entry', event.payload));
+        this.observeRunId(event.traversalContext?.runId);
+        const commitIdxBefore = this.getCommitCount();
+        const e = buildRunEvent('run.entry', event.payload, commitIdxBefore);
+        // Open range BEFORE the store push so a failed push doesn't leak
+        // an unclosed range (DS+logic panel review). The label is the
+        // stripped projection (no payload) — security-panel YELLOW #1.
+        if (this.hasCommitTracking) {
+            const token = this.boundaryIndex.open(toBoundaryLabel(e), commitIdxBefore);
+            this.openTokens.set(e.runtimeStageId, token);
+        }
+        this.store.push(e);
     }
     onRunEnd(event) {
-        this.emit(buildRunEvent('run.exit', event.payload));
+        this.observeRunId(event.traversalContext?.runId);
+        const commitIdxBefore = this.getCommitCount();
+        const e = buildRunEvent('run.exit', event.payload, commitIdxBefore);
+        // Close the range BEFORE store.push so a failed push doesn't
+        // leak a permanently-open range. The range is the canonical
+        // truth; the store entry is downstream telemetry.
+        if (this.hasCommitTracking) {
+            const token = this.openTokens.get(e.runtimeStageId);
+            if (token) {
+                this.boundaryIndex.close(token, commitIdxBefore);
+                this.openTokens.delete(e.runtimeStageId);
+            }
+        }
+        this.store.push(e);
     }
     onSubflowEntry(event) {
-        const e = buildSubflowEvent(event, 'subflow.entry');
-        if (e)
-            this.emit(e);
+        this.observeRunId(event.traversalContext?.runId);
+        const commitIdxBefore = this.getCommitCount();
+        const e = buildSubflowEvent(event, 'subflow.entry', commitIdxBefore);
+        if (!e)
+            return;
+        if (this.hasCommitTracking) {
+            const token = this.boundaryIndex.open(toBoundaryLabel(e), commitIdxBefore);
+            this.openTokens.set(e.runtimeStageId, token);
+        }
+        this.store.push(e);
     }
     onSubflowExit(event) {
-        const e = buildSubflowEvent(event, 'subflow.exit');
-        if (e)
-            this.emit(e);
+        this.observeRunId(event.traversalContext?.runId);
+        const commitIdxBefore = this.getCommitCount();
+        const e = buildSubflowEvent(event, 'subflow.exit', commitIdxBefore);
+        if (!e)
+            return;
+        if (this.hasCommitTracking) {
+            const token = this.openTokens.get(e.runtimeStageId);
+            if (token) {
+                this.boundaryIndex.close(token, commitIdxBefore);
+                this.openTokens.delete(e.runtimeStageId);
+            }
+        }
+        this.store.push(e);
     }
     onFork(event) {
+        this.observeRunId(event.traversalContext?.runId);
         const ts = Date.now();
         const ctx = event.traversalContext;
         const runtimeStageId = ctx?.runtimeStageId ?? '';
         const segments = ctx?.subflowPath ? ctx.subflowPath.split('/').filter(Boolean) : [];
         const subflowPath = [ROOT_SUBFLOW_ID, ...segments];
+        const commitIdxBefore = this.getCommitCount();
         for (const childName of event.children) {
-            this.emit({
+            this.store.push({
                 type: 'fork.branch',
                 runtimeStageId,
                 subflowPath,
                 depth: subflowPath.length - 1,
                 ts,
+                commitIdxBefore,
+                commitIdxAfter: commitIdxBefore,
                 parentSubflowId: event.parent,
                 childName,
             });
         }
     }
     onDecision(event) {
+        this.observeRunId(event.traversalContext?.runId);
         const ctx = event.traversalContext;
         // Agent-internal decisions (Route picking tool-calls / final) are
         // identified by the deciding stage's stableId matching one of the
@@ -204,12 +392,15 @@ export class BoundaryRecorder extends SequenceRecorder {
             ? stageId.slice(stageId.lastIndexOf('/') + 1)
             : stageId;
         const isAgentInternal = isAgentInternalId(localStageId);
-        this.emit({
+        const commitIdxBefore = this.getCommitCount();
+        this.store.push({
             type: 'decision.branch',
             runtimeStageId: ctx?.runtimeStageId ?? '',
             subflowPath: pathFromCtx(ctx?.subflowPath),
             depth: ctxDepth(ctx?.subflowPath),
             ts: Date.now(),
+            commitIdxBefore,
+            commitIdxAfter: commitIdxBefore,
             decider: event.decider,
             chosen: event.chosen,
             ...(event.rationale ? { rationale: event.rationale } : {}),
@@ -217,13 +408,17 @@ export class BoundaryRecorder extends SequenceRecorder {
         });
     }
     onLoop(event) {
+        this.observeRunId(event.traversalContext?.runId);
         const ctx = event.traversalContext;
-        this.emit({
+        const commitIdxBefore = this.getCommitCount();
+        this.store.push({
             type: 'loop.iteration',
             runtimeStageId: ctx?.runtimeStageId ?? '',
             subflowPath: pathFromCtx(ctx?.subflowPath),
             depth: ctxDepth(ctx?.subflowPath),
             ts: Date.now(),
+            commitIdxBefore,
+            commitIdxAfter: commitIdxBefore,
             target: event.target,
             iteration: event.iteration,
         });
@@ -241,11 +436,22 @@ export class BoundaryRecorder extends SequenceRecorder {
         return dispatcher.on('*', (event) => this.ingestTypedEvent(event));
     }
     ingestTypedEvent(event) {
+        // NOTE: deliberately does NOT call observeRunId(event.meta.runId).
+        // The agentfootprint dispatcher's runId is generated by a DIFFERENT
+        // generator than footprintjs's traversalContext.runId. Mixing them
+        // would toggle lastRunId on every event and trigger a false reset.
+        // Run-boundary detection happens reliably via the FlowRecorder hooks
+        // (onRunStart fires FIRST in any new run, before any typed event).
         const meta = event.meta;
         const runtimeStageId = meta.runtimeStageId ?? '';
         const subflowPath = [ROOT_SUBFLOW_ID, ...(meta.subflowPath ?? [])];
         const depth = subflowPath.length - 1;
         const ts = meta.wallClockMs;
+        // Phase 5 Layer 2: stamp commit index on every typed event for
+        // consumers that want to join domain events with the commit log
+        // (e.g., "which LLM call happened during this commit slice?").
+        // Typed events don't write to scope themselves, so before === after.
+        const commitIdxBefore = this.getCommitCount();
         switch (event.type) {
             case 'agentfootprint.stream.llm_start': {
                 const p = event.payload;
@@ -257,12 +463,14 @@ export class BoundaryRecorder extends SequenceRecorder {
                     ? 'tool→llm'
                     : 'user→llm';
                 this.prevLLMEndHadTools = false;
-                this.emit({
+                this.store.push({
                     type: 'llm.start',
                     runtimeStageId,
                     subflowPath,
                     depth,
                     ts,
+                    commitIdxBefore,
+                    commitIdxAfter: commitIdxBefore,
                     model: p.model,
                     provider: p.provider,
                     ...(p.systemPromptChars !== undefined ? { systemPromptChars: p.systemPromptChars } : {}),
@@ -279,12 +487,14 @@ export class BoundaryRecorder extends SequenceRecorder {
                 // terminal call (toolCallCount === 0) leaves the flag false so
                 // a hypothetical follow-up call would correctly be 'user→llm'.
                 this.prevLLMEndHadTools = p.toolCallCount > 0;
-                this.emit({
+                this.store.push({
                     type: 'llm.end',
                     runtimeStageId,
                     subflowPath,
                     depth,
                     ts,
+                    commitIdxBefore,
+                    commitIdxAfter: commitIdxBefore,
                     content: p.content,
                     toolCallCount: p.toolCallCount,
                     usage: { input: p.usage.input, output: p.usage.output },
@@ -295,12 +505,14 @@ export class BoundaryRecorder extends SequenceRecorder {
             }
             case 'agentfootprint.stream.tool_start': {
                 const p = event.payload;
-                this.emit({
+                this.store.push({
                     type: 'tool.start',
                     runtimeStageId,
                     subflowPath,
                     depth,
                     ts,
+                    commitIdxBefore,
+                    commitIdxAfter: commitIdxBefore,
                     toolName: p.toolName,
                     toolCallId: p.toolCallId,
                     ...(p.args !== undefined ? { args: p.args } : {}),
@@ -309,12 +521,14 @@ export class BoundaryRecorder extends SequenceRecorder {
             }
             case 'agentfootprint.stream.tool_end': {
                 const p = event.payload;
-                this.emit({
+                this.store.push({
                     type: 'tool.end',
                     runtimeStageId,
                     subflowPath,
                     depth,
                     ts,
+                    commitIdxBefore,
+                    commitIdxAfter: commitIdxBefore,
                     toolCallId: p.toolCallId,
                     ...(p.result !== undefined ? { result: p.result } : {}),
                     ...(p.durationMs !== undefined ? { durationMs: p.durationMs } : {}),
@@ -324,12 +538,14 @@ export class BoundaryRecorder extends SequenceRecorder {
             }
             case 'agentfootprint.context.injected': {
                 const p = event.payload;
-                this.emit({
+                this.store.push({
                     type: 'context.injected',
                     runtimeStageId,
                     subflowPath,
                     depth,
                     ts,
+                    commitIdxBefore,
+                    commitIdxAfter: commitIdxBefore,
                     slot: p.slot,
                     source: p.source ?? 'unknown',
                     ...(p.sourceId ? { sourceId: p.sourceId } : {}),
@@ -347,23 +563,82 @@ export class BoundaryRecorder extends SequenceRecorder {
                 });
                 break;
             }
+            case 'agentfootprint.composition.enter': {
+                // Open a boundary range for the composition. The MATCHING KEY
+                // for open/close is `payload.id` (the composition's stable id),
+                // NOT `meta.runtimeStageId`. Reason: the composition's enter
+                // event fires from a different stage (entry hook) than its
+                // exit event (merge / exit hook) — different `meta.runtimeStageId`s.
+                // The composition's `id` is the only field that's the same on
+                // both. The boundary range's runtimeStageId (used as the Lens
+                // group identity) is the ENTER event's `meta.runtimeStageId`
+                // (the entry stage's id) — that's the "fork moment."
+                const p = event.payload;
+                const e = {
+                    type: 'composition.start',
+                    runtimeStageId,
+                    subflowPath,
+                    depth,
+                    ts,
+                    commitIdxBefore,
+                    commitIdxAfter: commitIdxBefore,
+                    kind: p.kind,
+                    compositionId: p.id,
+                    name: p.name,
+                };
+                if (this.hasCommitTracking) {
+                    const token = this.boundaryIndex.open(toCompositionBoundaryLabel(e), commitIdxBefore);
+                    this.openTokens.set(`composition:${p.id}`, token);
+                }
+                this.store.push(e);
+                break;
+            }
+            case 'agentfootprint.composition.exit': {
+                // Close the matching composition range. Keyed by `payload.id`
+                // — see the enter handler for why this differs from
+                // meta.runtimeStageId.
+                const p = event.payload;
+                const e = {
+                    type: 'composition.end',
+                    runtimeStageId,
+                    subflowPath,
+                    depth,
+                    ts,
+                    commitIdxBefore,
+                    commitIdxAfter: commitIdxBefore,
+                    kind: p.kind,
+                    compositionId: p.id,
+                    name: p.name ?? '',
+                    status: p.status,
+                    durationMs: p.durationMs,
+                };
+                if (this.hasCommitTracking) {
+                    const key = `composition:${p.id}`;
+                    const token = this.openTokens.get(key);
+                    if (token) {
+                        this.boundaryIndex.close(token, commitIdxBefore);
+                        this.openTokens.delete(key);
+                    }
+                }
+                this.store.push(e);
+                break;
+            }
             default:
-                // Other typed events (composition.*, agent.*, etc.) are not
-                // mapped to DomainEvent for now — they're either implied by
-                // FlowRecorder events (composition) or higher-level summaries
-                // (agent.turn_*) that downstream selectors derive on demand.
+                // Other typed events (agent.*, eval.*, etc.) are not mapped to
+                // DomainEvent for now — they're higher-level summaries that
+                // downstream selectors derive on demand.
                 break;
         }
     }
     // ── Read API ────────────────────────────────────────────────────────
     /** All events in capture order (the canonical projection). */
     getEvents() {
-        return this.getEntries();
+        return this.store.getAll();
     }
     /** Type-narrowed lookup: all events of one kind. */
     getEventsByType(type) {
         const out = [];
-        for (const e of this.getEntries()) {
+        for (const e of this.store.getAll()) {
             if (e.type === type)
                 out.push(e);
         }
@@ -373,7 +648,7 @@ export class BoundaryRecorder extends SequenceRecorder {
     /** All boundary events (run + subflow, entry + exit interleaved). */
     getBoundaries() {
         const out = [];
-        for (const e of this.getEntries()) {
+        for (const e of this.store.getAll()) {
             if (e.type === 'run.entry' ||
                 e.type === 'run.exit' ||
                 e.type === 'subflow.entry' ||
@@ -393,7 +668,7 @@ export class BoundaryRecorder extends SequenceRecorder {
     }
     /** Entry/exit pair for one chart execution by `runtimeStageId`. */
     getBoundary(runtimeStageId) {
-        const matches = this.getEntriesForStep(runtimeStageId);
+        const matches = this.store.getByKey(runtimeStageId);
         let entry;
         let exit;
         for (const e of matches) {
@@ -420,7 +695,7 @@ export class BoundaryRecorder extends SequenceRecorder {
         const systemPrompt = [];
         const messages = [];
         const tools = [];
-        for (const e of this.getEntries()) {
+        for (const e of this.store.getAll()) {
             if (e.type !== 'subflow.entry' && e.type !== 'subflow.exit')
                 continue;
             if (e.slotKind === 'system-prompt')
@@ -459,7 +734,7 @@ export class BoundaryRecorder extends SequenceRecorder {
      *   matches `runtimeStageId`.
      */
     aggregateForBoundary(runtimeStageId) {
-        const events = this.getEntries();
+        const events = this.store.getAll();
         let entry;
         let exit;
         for (const e of events) {
@@ -484,7 +759,7 @@ export class BoundaryRecorder extends SequenceRecorder {
      * not user-facing rollup units.
      */
     aggregateAllBoundaries() {
-        const events = this.getEntries();
+        const events = this.store.getAll();
         const out = [];
         // Index exits by runtimeStageId for O(1) pair-up.
         const exitByRid = new Map();
@@ -513,18 +788,20 @@ export class BoundaryRecorder extends SequenceRecorder {
     }
 }
 // ── Internal helpers ─────────────────────────────────────────────────
-function buildRunEvent(type, payload) {
+function buildRunEvent(type, payload, commitIdxBefore) {
     return {
         type,
         runtimeStageId: ROOT_RUNTIME_STAGE_ID,
         subflowPath: [ROOT_SUBFLOW_ID],
         depth: 0,
         ts: Date.now(),
+        commitIdxBefore,
+        commitIdxAfter: commitIdxBefore,
         payload,
         isRoot: true,
     };
 }
-function buildSubflowEvent(event, type) {
+function buildSubflowEvent(event, type, commitIdxBefore) {
     const subflowId = event.subflowId;
     if (!subflowId)
         return undefined;
@@ -545,6 +822,8 @@ function buildSubflowEvent(event, type) {
         subflowPath,
         depth,
         ts: Date.now(),
+        commitIdxBefore,
+        commitIdxAfter: commitIdxBefore,
         subflowId,
         localSubflowId,
         subflowName: event.name,