agentfootprint 2.14.4 → 3.0.0

package/dist/types/recorders/observability/RunStepRecorder.d.ts

@@ -0,0 +1,232 @@
+/**
+ * RunStepRecorder — slider-ready ordered list of RunSteps, BUILT
+ * INCREMENTALLY during traversal. Real-time recorder, not a walker.
+ *
+ * Pattern: extends `SequenceRecorder<RunStep>` (shared storage shelf)
+ *          and implements `CombinedRecorder` (FlowRecorder hooks).
+ *          Subscribes to the agentfootprint typed-event dispatcher
+ *          for actor-arrow events. Each event handler decides whether
+ *          to emit a step; state lives on the instance and persists
+ *          across the run.
+ * Role:    The single source of truth for "what slider positions
+ *          exist in this run, and what transitions does each light
+ *          up." Lens consumers attach the recorder once and read
+ *          `getSteps()` — no per-render re-derivation.
+ *
+ * Why this matters: the older `buildRunSteps(events)` walker violated
+ * footprintjs's core principle ("collect during traversal, never
+ * post-process"). Each call walked the full event log multiple times;
+ * the playground triggered a full walk on every flowchart update,
+ * yielding O(N²) total work for a streaming run. The recorder pattern
+ * is O(N) — one handler call per event — and matches BoundaryRecorder /
+ * FlowchartRecorder / KeyedRecorder idioms throughout the library.
+ *
+ * The `buildRunSteps(...)` function is RETAINED as a thin compatibility
+ * shim that constructs a fresh recorder, replays events through it,
+ * and returns the resulting entries. Useful for snapshot-from-saved-
+ * events use cases (replay, testing, post-hoc analysis). Live consumers
+ * should attach the recorder directly via `runner.attach(rec)`.
+ */
+import type { CombinedRecorder, FlowDecisionEvent, FlowForkEvent, FlowLoopEvent, FlowSubflowEvent, TraversalContext } from 'footprintjs';
+interface FlowRunEvent {
+    readonly payload?: unknown;
+    readonly traversalContext?: TraversalContext;
+}
+import type { AgentfootprintEvent } from '../../events/registry.js';
+import type { EventDispatcher, Unsubscribe } from '../../events/dispatcher.js';
+import type { BoundaryRecorder, DomainEvent } from './BoundaryRecorder.js';
+/**
+ * One slider position. The smallest scrubable unit of the run.
+ *
+ * `transitions` is 1+ — fan-out / merge steps light up multiple
+ * transitions at once; sequential / decide / react steps light up
+ * exactly one. Renderers iterate `transitions` to highlight edges;
+ * details panels read `anchor.runtimeStageId`.
+ */
+export interface RunStep {
+    /** 0-based slider index (matches array position in `getSteps()`). */
+    readonly seq: number;
+    readonly kind: RunStepKind;
+    readonly transitions: readonly RunStepTransition[];
+    /**
+     * Per-step key — required by `SequenceRecorder<T>` for time-travel
+     * utilities (`getEntriesForStep`, `getEntryRanges`). Mirrors
+     * `anchor.runtimeStageId`; both fields point at the same value.
+     * Top-level placement satisfies the recorder's storage contract.
+     */
+    readonly runtimeStageId: string;
+    /** Anchor for commentary highlight + details pane lookup. */
+    readonly anchor: {
+        readonly runtimeStageId: string;
+        readonly subflowPath: readonly string[];
+    };
+    /** Human label — short, kind-specific. */
+    readonly label: string;
+    /** Wall-clock ms at which this step occurred. */
+    readonly tsMs: number;
+    /** Kind-specific decoration. Discriminate on `kind`. */
+    readonly meta?: RunStepMeta;
+}
+export type RunStepKind = 'sequential' | 'fork' | 'merge' | 'decide' | 'iteration' | 'iteration-exit' | 'react';
+export interface RunStepTransition {
+    readonly from: string;
+    readonly to: string;
+    readonly via: 'next' | 'fork-branch' | 'decision-branch' | 'loop-iteration' | 'actor-arrow';
+    readonly label?: string;
+}
+export type RunStepMeta = {
+    readonly kind: 'decide';
+    readonly chosen: string;
+    readonly rationale?: string;
+} | {
+    readonly kind: 'iteration';
+    readonly index: number;
+    readonly target: string;
+} | {
+    readonly kind: 'iteration-exit';
+    readonly index: number;
+    readonly reason?: string;
+} | {
+    readonly kind: 'fork';
+    readonly parentSubflowId: string;
+} | {
+    readonly kind: 'merge';
+    readonly mergedCount: number;
+} | {
+    readonly kind: 'react';
+    readonly actorArrow: 'user→llm' | 'tool→llm' | 'llm→tool' | 'llm→user';
+};
+export interface RunStepRecorderOptions {
+    readonly id?: string;
+}
+/** Factory — matches the `boundaryRecorder()` / `topologyRecorder()` style. */
+export declare function runStepRecorder(options?: RunStepRecorderOptions): RunStepRecorder;
+/**
+ * Real-time slider-step recorder. Emits a `RunStep` whenever an event
+ * marks a meaningful slider transition. State persists on the instance
+ * so successive events update bookkeeping in O(1).
+ *
+ * Attach via `runner.attach(rec)` for FlowRecorder events; call
+ * `rec.subscribe(runner.dispatcher)` for actor-arrow events. The
+ * `getSteps(drillPath?)` method returns the already-built list (no
+ * walking) with optional drill-scope filtering.
+ */
+export declare class RunStepRecorder implements CombinedRecorder {
+    readonly id: string;
+    /** Composition: storage shelf for the slider-step sequence. */
+    private readonly store;
+    /** Run-boundary observer — fires this.clear() when traversalContext.runId
+     *  changes between events. THIS IS THE FIX for the Parallel multi-run
+     *  aliasing bug — without it `forkKey = ${parent}@${rid}` collides
+     *  because rid resets to `seed#0` on each run. */
+    private readonly runIdGuard;
+    /** Stack of currently-open boundaries. The recorder owns this
+     *  directly because it's a simple stack and frames are recorder-
+     *  shaped. */
+    private boundaryStack;
+    /** Fork-emission coalescing + branch-exit tally. */
+    private readonly forks;
+    /** Tracks the most-recent leaf exit per depth → "forwards" handoff. */
+    private readonly siblings;
+    /** Buffers a "this MIGHT be the answer" leaf until onRunEnd. */
+    private readonly answerBuffer;
+    /** Run-root inference state machine (leaf vs composition). */
+    private readonly rootInferrer;
+    /** llm.start / llm.end actor-arrow classifier. */
+    private readonly actorArrows;
+    /** Has the first `asks` step fired? */
+    private asksEmitted;
+    constructor(options?: RunStepRecorderOptions);
+    /**
+     * Emit a RunStep, auto-mirroring `anchor.runtimeStageId` to the
+     * top-level `runtimeStageId` field that the keyed index uses. Single
+     * source of truth (the anchor) — never inconsistent with the storage
+     * key.
+     */
+    private push;
+    /** Internal seq-numbering helper — mirrors the store size so each
+     *  RunStep gets a unique 0-based index in emit order. */
+    private get entryCount();
+    clear(): void;
+    /** Internal — wipe all per-run state WITHOUT resetting the runIdGuard
+     *  itself. Called by `clear()` (which then resets the guard) AND by
+     *  the runIdGuard's onNewRun callback (where the guard is mid-update
+     *  and must NOT be reset, only the recorder's data should be).
+     *
+     *  Note: each sub-tracker owns its OWN clear; the orchestrator just
+     *  fans out. Adding new state to a sub-tracker requires no edit here. */
+    private resetForNewRun;
+    private observeRunId;
+    onRunStart(event: FlowRunEvent): void;
+    onRunEnd(event: FlowRunEvent): void;
+    onSubflowEntry(event: FlowSubflowEvent): void;
+    onSubflowExit(event: FlowSubflowEvent): void;
+    onFork(event: FlowForkEvent): void;
+    onDecision(event: FlowDecisionEvent): void;
+    onLoop(event: FlowLoopEvent): void;
+    /**
+     * Subscribe to the runner's typed-event dispatcher and emit a
+     * `react` RunStep on every `llm.start` / `llm.end`. The recorder
+     * classifies `actorArrow` locally (mirrors BoundaryRecorder's
+     * pattern) so consumers don't have to depend on BoundaryRecorder's
+     * own subscription order.
+     */
+    subscribe(dispatcher: EventDispatcher): Unsubscribe;
+    /** Internal — also called by `ingestDomainEvent` for shim replay.
+     *
+     *  NOTE: deliberately does NOT call observeRunId(event.meta.runId).
+     *  The agentfootprint dispatcher's runId is 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 on the FlowRecorder side
+     *  (onRunStart fires FIRST in any new run before any typed event). */
+    protected ingestTypedEvent(event: AgentfootprintEvent): void;
+    /**
+     * Feed a single recorded `DomainEvent` (from BoundaryRecorder) into
+     * this recorder as if it had fired live. Used by `buildRunSteps`
+     * for snapshot replay; tests use it for fixture-driven projection.
+     *
+     * Live consumers should use `runner.attach(rec)` +
+     * `rec.subscribe(dispatcher)` instead — the recorder's hooks fire
+     * naturally during traversal.
+     */
+    ingestDomainEvent(e: DomainEvent): void;
+    /**
+     * Read-only query — returns the already-built step list filtered to
+     * `drillPath` scope. O(1) per call when scope is empty; O(N) filter
+     * otherwise. Composition-vs-leaf root filter is applied so the
+     * slider semantics match the user's mental model:
+     *
+     *   - **Leaf root** (single Agent / LLMCall): show `react` steps only.
+     *   - **Composition root** (Sequence / Parallel / Conditional / Loop):
+     *     show composition steps; hide intra-leaf `react` steps.
+     *
+     * Drill-down filters by `anchor.subflowPath` prefix and re-applies
+     * the leaf-vs-composition rule for the drilled scope.
+     */
+    getSteps(drillPath?: readonly string[]): readonly RunStep[];
+    /** Flush any deferred answer-candidate from the buffer. Called by
+     *  `onRunEnd` so a single `answers` step appears for runs that end
+     *  on a leaf exit (no further leaf entries followed). */
+    private flushCandidateAnswer;
+}
+export interface RunStepGraph {
+    readonly steps: readonly RunStep[];
+}
+export interface BuildRunStepsOptions {
+    readonly drillPath?: readonly string[];
+}
+/**
+ * Compatibility shim for snapshot-from-events use cases (replay,
+ * post-hoc analysis, tests). For LIVE use, prefer attaching a
+ * `RunStepRecorder` directly via `runner.attach(rec)` —
+ * `buildRunSteps(events)` constructs a fresh recorder, replays the
+ * events through its handlers, and returns the resulting entries.
+ *
+ * @deprecated Prefer `runStepRecorder()` + `runner.attach(rec)` for
+ *             live consumers. This shim remains for offline / testing
+ *             scenarios where only a recorded event list is available.
+ */
+export declare function buildRunSteps(source: BoundaryRecorder | readonly DomainEvent[], options?: BuildRunStepsOptions): RunStep[];
+export {};
+//# sourceMappingURL=RunStepRecorder.d.ts.map

package/dist/types/recorders/observability/RunStepRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunStepRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/RunStepRecorder.ts"],"names":[],"mappings":"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"}

package/dist/types/recorders/observability/commentary/commentaryTemplates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commentaryTemplates.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;2EAG2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBA+ExC,CAAC;AAEF;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;2EAGuE;IACvE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CA6FzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,iBAAiB,EACtB,SAAS,GAAE,mBAAgD,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoDxB;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAS3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEvF"}
+{"version":3,"file":"commentaryTemplates.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;2EAG2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBA+ExC,CAAC;AAEF;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;2EAGuE;IACvE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CA6FzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,iBAAiB,EACtB,SAAS,GAAE,mBAAgD,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmDxB;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAS3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEvF"}

package/dist/types/recorders/observability/internal/ActorArrowClassifier.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * ActorArrowClassifier — classifies the next `llm.start` as
+ * `'user→llm'` (no pending tool result) vs `'tool→llm'` (after a
+ * tool result), and the next `llm.end` as `'llm→tool'` vs `'llm→user'`
+ * based on the call's `toolCallCount`.
+ *
+ * Extracted from RunStepRecorder per Convention 1. Keeps a single
+ * boolean of state — `prevLLMEndHadTools` — and consumes-then-resets
+ * it on each `llm.start`.
+ */
+export type StartArrow = 'user→llm' | 'tool→llm';
+export type EndArrow = 'llm→tool' | 'llm→user';
+export declare class ActorArrowClassifier {
+    private prevLLMEndHadTools;
+    /** Classify the next `llm.start`. Consumes + resets the pending
+     *  flag after returning. */
+    classifyStart(): StartArrow;
+    /** Classify an `llm.end` based on its tool-call count, and update
+     *  the pending flag for the NEXT llm.start. */
+    classifyEnd(toolCallCount: number): EndArrow;
+    clear(): void;
+}
+//# sourceMappingURL=ActorArrowClassifier.d.ts.map

package/dist/types/recorders/observability/internal/ActorArrowClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorArrowClassifier.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/internal/ActorArrowClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAE/C,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,kBAAkB,CAAS;IAEnC;gCAC4B;IAC5B,aAAa,IAAI,UAAU;IAM3B;mDAC+C;IAC/C,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ;IAM5C,KAAK,IAAI,IAAI;CAGd"}

package/dist/types/recorders/observability/internal/CandidateAnswerBuffer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * CandidateAnswerBuffer — buffers a "this leaf MIGHT be the run's
+ * answer" candidate that's only confirmed on `onRunEnd`. Replaced
+ * by every later leaf exit at run scope; the last one wins.
+ *
+ * Extracted from RunStepRecorder per Convention 1.
+ *
+ * Use:
+ *   - On leaf EXIT at run scope: `set(frame, ts, runtimeStageId)`.
+ *   - On `onRunEnd`: `flush()` returns the buffered candidate (or
+ *     undefined if none), and clears the buffer.
+ */
+export interface CandidateAnswer<TFrame> {
+    readonly frame: TFrame;
+    readonly tsMs: number;
+    readonly runtimeStageId: string;
+}
+export declare class CandidateAnswerBuffer<TFrame> {
+    private candidate;
+    /** Buffer a new candidate, replacing any prior one. */
+    set(frame: TFrame, tsMs: number, runtimeStageId: string): void;
+    /** Return + clear the buffered candidate (or undefined if empty). */
+    flush(): CandidateAnswer<TFrame> | undefined;
+    clear(): void;
+}
+//# sourceMappingURL=CandidateAnswerBuffer.d.ts.map

package/dist/types/recorders/observability/internal/CandidateAnswerBuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CandidateAnswerBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/internal/CandidateAnswerBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,eAAe,CAAC,MAAM;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,qBAAa,qBAAqB,CAAC,MAAM;IACvC,OAAO,CAAC,SAAS,CAAsC;IAEvD,uDAAuD;IACvD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IAI9D,qEAAqE;IACrE,KAAK,IAAI,eAAe,CAAC,MAAM,CAAC,GAAG,SAAS;IAM5C,KAAK,IAAI,IAAI;CAGd"}

package/dist/types/recorders/observability/internal/ForkTracker.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice; do not import
+ * via deep paths.
+ *
+ * ForkTracker — owns the bookkeeping for parallel-fork emission and
+ * merge-step detection. Extracted from RunStepRecorder per Convention 1
+ * (one purpose per recorder/state machine).
+ *
+ * Responsibilities (and ONLY these):
+ *   1. Coalesce repeated `onFork` events for the same parent (race-safe
+ *      via parent+runtimeStageId key).
+ *   2. Track which child branches belong to which parent fork.
+ *   3. Track which branches have exited; signal "merge ready" when ALL
+ *      branches of a fork have exited.
+ *
+ * What it does NOT own:
+ *   - Storage (the recorder writes RunSteps to its SequenceStore).
+ *   - Run-boundary detection (the recorder's runIdGuard wipes this
+ *     tracker via `clear()`).
+ *   - Any other state machine.
+ */
+export interface ForkRegistration {
+    /** True if this is a NEW fork; false if the same fork was already seen
+     *  (caller should suppress duplicate emission). */
+    readonly fresh: boolean;
+}
+export interface MergeReady {
+    /** All branch IDs of the now-fully-exited fork, in the order they
+     *  were originally registered. */
+    readonly branches: readonly string[];
+}
+export declare class ForkTracker {
+    /** Per-parent: the ordered list of child branch IDs registered. */
+    private readonly branches;
+    /** Per-parent: the set of child branch IDs that have exited so far. */
+    private readonly exited;
+    /** Reverse index: child branch ID → its parent fork. */
+    private readonly childToParent;
+    /** Set of `${parent}@${runtimeStageId}` keys already registered, to
+     *  coalesce repeated onFork events. */
+    private readonly emittedKeys;
+    /**
+     * Register a new fork. If the same fork (by parent+runtimeStageId)
+     * was already registered, returns `{ fresh: false }` and the caller
+     * should suppress emission. Otherwise registers all child branches
+     * and returns `{ fresh: true }`.
+     */
+    registerFork(parent: string, runtimeStageId: string, children: readonly string[]): ForkRegistration;
+    /** True if this child belongs to a tracked fork (used to suppress
+     *  sequential-emission for fork-branch entry events). */
+    isForkChild(childSubflowId: string): boolean;
+    /**
+     * Record a fork-branch exit. If this completes the fork (all branches
+     * have exited), returns `{ branches }` so the caller can emit a merge
+     * step. Returns `undefined` if not yet complete or not a fork branch.
+     */
+    recordChildExit(childSubflowId: string): MergeReady | undefined;
+    clear(): void;
+}
+//# sourceMappingURL=ForkTracker.d.ts.map

package/dist/types/recorders/observability/internal/ForkTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForkTracker.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/internal/ForkTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B;uDACmD;IACnD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB;sCACkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,qBAAa,WAAW;IACtB,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IACjE,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D;2CACuC;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IAEjD;;;;;OAKG;IACH,YAAY,CACV,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,gBAAgB;IAYnB;6DACyD;IACzD,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI5C;;;;OAIG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAgB/D,KAAK,IAAI,IAAI;CAMd"}

package/dist/types/recorders/observability/internal/RootInferrer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * RootInferrer — small state machine deciding whether a run's root is
+ * a single leaf primitive (Agent / LLMCall) or a composition (Sequence
+ * / Parallel / Conditional / Loop).
+ *
+ * Extracted from RunStepRecorder per Convention 1.
+ *
+ * Inputs: subflow entries (with their depth + parsed primitiveKind),
+ * fork events (depth 0 → Parallel root), decision events (depth 0 →
+ * Conditional root), loop events (depth 0 → Loop root).
+ *
+ * Output: query `kind()` for the inferred root. Returns `undefined`
+ * until a signal arrives.
+ *
+ * Inference rules:
+ *   - Decisive composition signals (fork / decide / loop AT DEPTH 0)
+ *     lock the root and are never overridden.
+ *   - Shallowest primitive boundary IS a composition kind → root is
+ *     that composition.
+ *   - Two+ leaf siblings at the shallowest depth → implicit Sequence
+ *     root (Sequence-as-runner case where the Sequence itself doesn't
+ *     fire its own subflow.entry).
+ *   - Single leaf at the shallowest depth → root is "leaf".
+ */
+export type InferredRoot = 'leaf' | 'sequence' | 'parallel' | 'conditional' | 'loop' | undefined;
+export declare class RootInferrer {
+    private inferred;
+    private shallowestDepth;
+    private shallowestSiblings;
+    /** Currently-inferred root kind, or undefined if no signal yet. */
+    kind(): InferredRoot;
+    /** True when the root is a single leaf primitive (or unknown,
+     *  which should be treated as leaf for kind-filter purposes). */
+    isLeafRoot(): boolean;
+    /** Observe a subflow entry. */
+    observeSubflowEntry(depth: number, primitiveKind: string | undefined): void;
+    /** Observe a fork event. Locks root to Parallel if at depth 0 and
+     *  no decisive root has been inferred yet. */
+    observeFork(depth: number): void;
+    /** Observe a decision event. Locks root to Conditional if at depth 0
+     *  and no decisive root has been inferred yet. */
+    observeDecision(depth: number): void;
+    /** Observe a loop event. Locks root to Loop if at depth 0 and no
+     *  decisive root has been inferred yet. */
+    observeLoop(depth: number): void;
+    clear(): void;
+    private tryInfer;
+}
+//# sourceMappingURL=RootInferrer.d.ts.map

package/dist/types/recorders/observability/internal/RootInferrer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RootInferrer.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/internal/RootInferrer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAaH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;AAEjG,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,kBAAkB,CAAK;IAE/B,mEAAmE;IACnE,IAAI,IAAI,YAAY;IAIpB;qEACiE;IACjE,UAAU,IAAI,OAAO;IAIrB,+BAA+B;IAC/B,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAY3E;kDAC8C;IAC9C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMhC;sDACkD;IAClD,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMpC;+CAC2C;IAC3C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMhC,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,QAAQ;CA0BjB"}

package/dist/types/recorders/observability/internal/SequenceSiblingTracker.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * SequenceSiblingTracker — tracks the most-recent leaf exit at each
+ * depth so the recorder knows when a new leaf entry at the same depth
+ * should emit a "sequential handoff" step ("forwards" semantics).
+ *
+ * Extracted from RunStepRecorder per Convention 1.
+ *
+ * Use:
+ *   - On leaf EXIT: `recordExit(depth, subflowId)`.
+ *   - On leaf ENTRY: `peekPrevSibling(depth)` returns the previous
+ *     leaf's subflowId at this depth, or undefined for the first leaf.
+ */
+export declare class SequenceSiblingTracker {
+    private readonly prevExitedAtDepth;
+    /** Returns the subflow id of the most-recently-exited leaf at this
+     *  depth, or undefined if this is the first leaf entry at the depth. */
+    peekPrevSibling(depth: number): string | undefined;
+    /** Record that a leaf at this depth just exited. */
+    recordExit(depth: number, subflowId: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=SequenceSiblingTracker.d.ts.map

package/dist/types/recorders/observability/internal/SequenceSiblingTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SequenceSiblingTracker.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/internal/SequenceSiblingTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAE/D;4EACwE;IACxE,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIlD,oDAAoD;IACpD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIlD,KAAK,IAAI,IAAI;CAGd"}

package/dist/types/recorders/observability/observeRunId.d.ts

@@ -0,0 +1,37 @@
+/**
+ * observeRunId — shared run-boundary detection helper for recorders.
+ *
+ * Why this exists: 5 places in observability/* duplicated the same
+ * 10-line pattern (lastRunId field + 3-line check + reset). Extract
+ * once so the contract stays consistent under maintenance.
+ *
+ * The pattern: hold a `lastRunId | undefined`. On every observed event:
+ *   - If runId is missing/undefined → no-op (defensive, allows callers
+ *     to pass `event.meta?.runId` without checking).
+ *   - First observation (lastRunId === undefined) → record, no reset.
+ *   - Same runId → no-op (steady state).
+ *   - Different runId → call onNewRun() then record the new id.
+ *
+ * Returned helper is mutable closure state — callers store it as a
+ * private field and call `.observe(runId)` from event hooks.
+ *
+ * @example
+ * ```typescript
+ * class MyRecorder implements ScopeRecorder {
+ *   private readonly runIdGuard = createRunIdObserver(() => this.reset());
+ *   onWrite(e) {
+ *     this.runIdGuard.observe(e.runId);
+ *     // ... handle event
+ *   }
+ *   private reset() { this.store.clear(); }
+ * }
+ * ```
+ */
+export interface RunIdObserver {
+    /** Process an event's runId; fires onNewRun callback when it changes. */
+    observe(runId: string | undefined): void;
+    /** Clear state so the next observation initializes fresh. */
+    reset(): void;
+}
+export declare function createRunIdObserver(onNewRun: () => void): RunIdObserver;
+//# sourceMappingURL=observeRunId.d.ts.map

package/dist/types/recorders/observability/observeRunId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observeRunId.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/observeRunId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACzC,6DAA6D;IAC7D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,aAAa,CAkBvE"}

package/dist/types/reliability/buildReliabilityGateChart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildReliabilityGateChart.d.ts","sourceRoot":"","sources":["../../../src/reliability/buildReliabilityGateChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAWzD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,YAAY,CAAC;AAkFvF;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAkT9E"}
+{"version":3,"file":"buildReliabilityGateChart.d.ts","sourceRoot":"","sources":["../../../src/reliability/buildReliabilityGateChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAWzD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,YAAY,CAAC;AAkFvF;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAiT9E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.14.4",
+  "version": "3.0.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -184,7 +184,7 @@
     "@aws-sdk/client-xray": "*",
     "@modelcontextprotocol/sdk": "*",
     "@opentelemetry/api": "*",
-    "footprintjs": ">=4.17.2",
+    "footprintjs": "^6.0.0",
     "ioredis": "*",
     "openai": "*",
     "zod": "*"
@@ -228,7 +228,7 @@
     "@vitest/coverage-v8": "^4.1.5",
     "eslint": "^8.44.0",
     "eslint-config-prettier": "^6.15.0",
-    "footprintjs": "^4.17.2",
+    "footprintjs": "^6.0.0",
     "prettier": "^2.8.1",
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",