footprintjs 6.1.2 → 7.0.0

package/dist/types/lib/recorder/BoundaryStateTracker.d.ts

@@ -1,212 +0,0 @@
-/**
- * BoundaryStateTracker<TState> — third storage primitive on the recorder
- * shelf, alongside `SequenceRecorder<T>` and `KeyedRecorder<T>`.
- *
- * **Mental model — observers vs. bookkeepers:**
- *
- *   `ScopeRecorder` / `FlowRecorder` / `EmitRecorder` / `CombinedRecorder`
- *     are OBSERVER interfaces — they describe how a recorder hears
- *     events from the executor.
- *
- *   `SequenceRecorder<T>` / `KeyedRecorder<T>` / `BoundaryStateTracker<TState>`
- *     are STORAGE primitives — three different bookkeeping shelves with
- *     different durability and indexing properties. A real recorder
- *     class typically picks ONE observer interface AND ONE storage
- *     shelf, combining them via `extends + implements`.
- *
- * **What this primitive answers:** "At any moment during the run, what
- * is the LIVE transient state of every currently-active boundary?"
- *
- * A "boundary" is a matched event pair `[start, stop]` bracketing an
- * interval — for example, `(llm_start, llm_end)` for an LLM call,
- * `(tool_start, tool_end)` for tool execution, `(turn_start, turn_end)`
- * for an agent turn. Between the brackets, intermediate events evolve
- * the boundary's state (token chunks accumulating into a partial
- * answer, args streaming in, etc.). On `stop`, the state clears.
- *
- * Algorithmically this is the **DFS bracket-sequence pattern** —
- * stack-frame state during a graph-traversal interval. Same shape used
- * by Tarjan's SCC algorithm, tree decomposition, and push-down
- * automata. The `active` map is the open-brackets stack at any moment.
- *
- * **Comparison with the other storage primitives:**
- *
- * | Primitive                       | Stores                               | Time scope          | Memory      |
- * |---------------------------------|--------------------------------------|---------------------|-------------|
- * | `SequenceRecorder<T>`           | append-only ordered + keyed entries  | durable across run  | O(N events) |
- * | `KeyedRecorder<T>`              | 1:1 entry per `runtimeStageId`       | durable across run  | O(N steps)  |
- * | `BoundaryStateTracker<TState>`  | transient bracket-scoped state       | live; clears on stop | O(K active) |
- *
- * **When to pick which:**
- *
- *   - "I need to keep a permanent log of every event for time-travel"
- *      → `SequenceRecorder<T>`
- *   - "I want one durable record per stage execution (e.g., metrics)"
- *      → `KeyedRecorder<T>`
- *   - "I need to know what's happening RIGHT NOW inside an in-flight
- *     boundary (e.g., partial LLM stream, partial tool args)"
- *      → `BoundaryStateTracker<TState>` (this class)
- *
- * **What this is NOT for:**
- *
- *   - Time-travel queries ("what was the state at past slider step N?")
- *     — transient state clears on stop. For time-travel, snapshot the
- *     state at each emit into a separate `SequenceRecorder<TState>`,
- *     or wait for a future `BoundarySnapshotRecorder<TState>` primitive.
- *
- *   - Aggregations across the whole run (totals, counts) — those are
- *     `SequenceRecorder.aggregate()` / `KeyedRecorder.aggregate()`.
- *
- *   - Stage-level concerns — those use `ScopeRecorder.onStageStart` /
- *     `ScopeRecorder.onStageEnd`. This primitive operates at finer
- *     granularity (events emitted DURING a stage execution).
- *
- * **Lifecycle contract — STRICT:**
- *
- *   Every `startBoundary(key, ...)` call MUST be paired with a
- *   `stopBoundary(key)` call. Failure to wire the stop side produces a
- *   memory leak: the active map grows without bound, and `getAllActive()`
- *   returns stale entries that look in-flight but aren't. Common cause:
- *   subclass wires `start` to one event handler and forgets to wire
- *   `stop`. **Always wire both at the same time.**
- *
- *   Dev mode (`enableDevMode()`) detects leaks at `clear()` time —
- *   warning includes the leaked keys so you can find the missing wiring.
- *
- * **Concurrency / nesting:**
- *
- *   - Concurrent boundaries (parallel branches with two LLM calls
- *     active at once) work correctly: each is keyed independently in
- *     the active map.
- *   - Nested boundaries of DIFFERENT KINDS (Agent boundary contains
- *     LLM boundary) require SEPARATE tracker instances — one per kind.
- *     The base class tracks one boundary kind per instance.
- *
- * **Key convention:**
- *
- *   The `key: string` is whatever your subclass picks. Convention:
- *   use `runtimeStageId` when the boundary maps 1:1 to a stage
- *   execution — this gives free interop with `SequenceRecorder
- *   .getEntriesForStep`, `KeyedRecorder.getByKey`, `findCommit` /
- *   `findLastWriter`, and the rest of the trace ecosystem. Use a more
- *   granular key (e.g., `toolCallId`) only when there are multiple
- *   concurrent boundaries WITHIN one stage execution.
- *
- * @example Build a live LLM tracker (combining storage + observer):
- *
- * ```typescript
- * import { BoundaryStateTracker } from 'footprintjs/trace';
- * import { type CombinedRecorder, type EmitEvent } from 'footprintjs';
- *
- * interface LLMLiveState {
- *   readonly partial: string;
- *   readonly tokens: number;
- * }
- *
- * class LiveLLMTracker
- *   extends BoundaryStateTracker<LLMLiveState>   // STORAGE shelf
- *   implements CombinedRecorder                   // OBSERVER interface
- * {
- *   readonly id = 'live-llm';
- *
- *   // Observer half — translate events into bracket mutations.
- *   onEmit(event: EmitEvent): void {
- *     if (event.name === 'agentfootprint.stream.llm_start') {
- *       this.startBoundary(event.runtimeStageId, { partial: '', tokens: 0 });
- *     } else if (event.name === 'agentfootprint.stream.llm_end') {
- *       this.stopBoundary(event.runtimeStageId);
- *     } else if (event.name === 'agentfootprint.stream.token') {
- *       this.updateBoundary(event.runtimeStageId, (s) => ({
- *         partial: s.partial + (event.payload as { content: string }).content,
- *         tokens: s.tokens + 1,
- *       }));
- *     }
- *   }
- *
- *   // Public read API — O(1) at any moment.
- *   isInFlight(): boolean { return this.hasActive; }
- *   getPartial(stageId: string): string {
- *     return this.getActive(stageId)?.partial ?? '';
- *   }
- * }
- *
- * // Attached the same way as any other CombinedRecorder.
- * const tracker = new LiveLLMTracker();
- * executor.attachCombinedRecorder(tracker);
- * await executor.run({ input });
- *
- * // Read live state at any time during or after the run.
- * tracker.isInFlight();
- * tracker.getPartial(rid);
- * ```
- */
-export declare abstract class BoundaryStateTracker<TState> {
-    /** Stable id — same idempotency contract as other recorders. */
-    abstract readonly id: string;
-    /** Open-brackets stack: key → current transient state. */
-    private readonly active;
-    /** Per-key count of `updateBoundary` calls that landed without a
-     *  matching active boundary. Drives rate-limited dev-mode warnings
-     *  so a stuck loop doesn't spam the console. */
-    private readonly missedUpdates;
-    /**
-     * Open a new boundary with initial transient state.
-     *
-     * If a boundary with the same `key` is already active, the prior
-     * state is overwritten (last-writer-wins). In dev mode, a warning
-     * is logged because re-starting an active key usually indicates a
-     * missed `stopBoundary` call upstream.
-     *
-     * @param key Boundary identifier — by convention, `runtimeStageId`
-     *            for 1:1-with-stage boundaries, or a more granular id
-     *            (e.g., `toolCallId`) when multiple concurrent boundaries
-     *            run within one stage execution.
-     * @param initial Initial state — typed by `TState`.
-     */
-    protected startBoundary(key: string, initial: TState): void;
-    /**
-     * Evolve the transient state of an active boundary using an updater
-     * function. Silent no-op if no boundary is active for `key`
-     * (defensive against out-of-order events). In dev mode, a rate-limited
-     * warning is logged on the 1st, 10th, and 100th missed update per key.
-     *
-     * @param key      Boundary identifier (must match a prior `startBoundary`).
-     * @param updater  Pure function: previous state → next state.
-     */
-    protected updateBoundary(key: string, updater: (prev: TState) => TState): void;
-    /**
-     * Close the boundary identified by `key` and return its FINAL
-     * transient state (for any cleanup the subclass wants — e.g., emit a
-     * snapshot to a SequenceRecorder for durable storage).
-     *
-     * @param key Boundary identifier.
-     * @returns The final state, or `undefined` if no boundary was active.
-     */
-    protected stopBoundary(key: string): TState | undefined;
-    /** Current transient state of ONE active boundary. `undefined` if no
-     *  boundary is active for `key`. */
-    getActive(key: string): TState | undefined;
-    /**
-     * All currently-active boundaries.
-     *
-     * **Type-only readonly:** the returned reference IS the internal Map.
-     * TypeScript prevents mutation through the `ReadonlyMap` type, but a
-     * runtime cast or non-TS consumer can mutate it and corrupt internal
-     * state. **Do not mutate.**
-     */
-    getAllActive(): ReadonlyMap<string, TState>;
-    /** True if any boundary is currently active. O(1). */
-    get hasActive(): boolean;
-    /** Number of currently-active boundaries. O(1). */
-    get activeCount(): number;
-    /**
-     * Reset all transient state. Called by executors before each `run()`
-     * so consumers get a clean slate per run — same lifecycle contract
-     * as `SequenceRecorder.clear()`.
-     *
-     * In dev mode, warns if any boundaries are still active when called
-     * — likely indicates a missed `stopBoundary` upstream. The leaked
-     * keys are listed (truncated to 10) so the wiring bug is findable.
-     */
-    clear(): void;
-}

package/dist/types/lib/recorder/KeyedRecorder.d.ts

@@ -1,56 +0,0 @@
-/**
- * KeyedRecorder<T> — base class for Map-based recorders keyed by runtimeStageId.
- *
- * Provides typed key-value storage with O(1) lookup, insertion-ordered iteration,
- * and three standard operations on auto-collected traversal data:
- *
- *   - **Translate** (raw): `getByKey(id)` — per-step value
- *   - **Accumulate** (progressive): `accumulate(fn, initial, keys?)` — running total up to a point
- *   - **Aggregate** (summary): `aggregate(fn, initial)` — reduce all entries
- *
- * Data is automatically collected during the single DFS traversal.
- * The consumer chooses the operation at read time.
- *
- * @example
- * ```typescript
- * class TokenRecorder extends KeyedRecorder<LLMCallEntry> {
- *   readonly id = 'tokens';
- *   onLLMCall(event) { this.store(event.runtimeStageId, { tokens: event.usage }); }
- *
- *   // Translate: per-step
- *   getForStep(id: string) { return this.getByKey(id); }
- *
- *   // Aggregate: total
- *   getTotalTokens() { return this.aggregate((sum, e) => sum + e.tokens, 0); }
- *
- *   // Accumulate: progressive up to slider position
- *   getTokensUpTo(keys: Set<string>) { return this.accumulate((sum, e) => sum + e.tokens, 0, keys); }
- * }
- * ```
- */
-export declare abstract class KeyedRecorder<T> {
-    abstract readonly id: string;
-    private readonly data;
-    /** Store an entry keyed by runtimeStageId. */
-    protected store(runtimeStageId: string, entry: T): void;
-    /** O(1) lookup by runtimeStageId. */
-    getByKey(runtimeStageId: string): T | undefined;
-    /** All entries as a read-only Map (insertion-ordered). */
-    getMap(): ReadonlyMap<string, T>;
-    /** All entries as an array (insertion-ordered). */
-    values(): T[];
-    /** Number of entries stored. */
-    get size(): number;
-    /** Reduce ALL entries to a single value. For dashboards, totals, summaries. */
-    aggregate<R>(fn: (acc: R, entry: T, key: string) => R, initial: R): R;
-    /**
-     * Reduce entries, optionally filtered by a set of keys.
-     * For time-travel progressive view: pass the runtimeStageIds visible at the current slider position.
-     * Without keys, reduces all entries (same as aggregate).
-     */
-    accumulate<R>(fn: (acc: R, entry: T, key: string) => R, initial: R, keys?: ReadonlySet<string>): R;
-    /** Return entries whose keys are in the set, preserving insertion order. */
-    filterByKeys(keys: ReadonlySet<string>): T[];
-    /** Clear all stored data. Called by executor before each run(). */
-    clear(): void;
-}

package/dist/types/lib/recorder/SequenceRecorder.d.ts

@@ -1,112 +0,0 @@
-/**
- * SequenceRecorder<T> — base class for ordered sequence recorders with keyed index.
- *
- * Provides dual-indexed storage: a flat array preserving insertion order plus a
- * Map<runtimeStageId, T[]> for O(1) per-step lookup. One entry type, multiple entries
- * per step. Designed for recorders that implement BOTH ScopeRecorder and FlowRecorder
- * (merging data ops and control flow into a single interleaved sequence).
- *
- * **Contrast with KeyedRecorder<T>:**
- * - `KeyedRecorder<T>` — 1:1 Map. One entry per runtimeStageId. For single-value recorders
- *   like MetricRecorder (one StepMetrics per stage execution).
- * - `SequenceRecorder<T>` — 1:N sequence + Map. Multiple entries per runtimeStageId,
- *   plus ordering matters. For recorders that produce a prose narrative or event log
- *   where a single step generates stage + data + decision entries.
- *
- * **How to choose:**
- * - If each step produces exactly one record → extend `KeyedRecorder<T>`
- * - If each step produces multiple records or ordering matters → extend `SequenceRecorder<T>`
- *
- * @example
- * ```typescript
- * import { SequenceRecorder } from 'footprintjs/trace';
- *
- * interface AuditEntry {
- *   runtimeStageId?: string;
- *   type: 'read' | 'write' | 'decision';
- *   detail: string;
- * }
- *
- * class AuditRecorder extends SequenceRecorder<AuditEntry> {
- *   readonly id = 'audit';
- *
- *   // Scope hooks (fires during stage execution)
- *   onRead(event: ReadEvent) {
- *     this.emit({ runtimeStageId: event.runtimeStageId, type: 'read', detail: event.key });
- *   }
- *   onWrite(event: WriteEvent) {
- *     this.emit({ runtimeStageId: event.runtimeStageId, type: 'write', detail: event.key });
- *   }
- *
- *   // Flow hooks (fires after stage execution)
- *   onDecision(event: FlowDecisionEvent) {
- *     this.emit({
- *       runtimeStageId: event.traversalContext?.runtimeStageId,
- *       type: 'decision',
- *       detail: `${event.decider} chose ${event.chosen}`,
- *     });
- *   }
- *
- *   // Time-travel: entries up to slider position
- *   getAuditUpTo(visibleIds: ReadonlySet<string>) {
- *     return this.getEntriesUpTo(visibleIds);
- *   }
- * }
- * ```
- */
-export declare abstract class SequenceRecorder<T extends {
-    runtimeStageId?: string;
-}> {
-    abstract readonly id: string;
-    /** Ordered sequence of all entries (insertion order). */
-    private readonly entries;
-    /** Per-step index: runtimeStageId → entries for that step. Same objects as entries[]. */
-    private readonly byRuntimeStageId;
-    /** Per-step range index: runtimeStageId → [firstIdx, endIdx) in entries array.
-     *  endIdx includes trailing keyless entries (structural markers). Maintained during emit(). */
-    private readonly entryRanges;
-    /** The runtimeStageId of the most recently emitted keyed entry. Used to extend ranges for trailing markers. */
-    private lastEmittedId;
-    /**
-     * Append an entry to both the ordered sequence, keyed index, and range index.
-     * All reference the same entry object — no duplication.
-     */
-    protected emit(entry: T): void;
-    /** All entries in insertion order (returns a shallow copy — entry objects are shared). */
-    getEntries(): T[];
-    /** Number of entries in the sequence. */
-    get entryCount(): number;
-    /** Zero-copy iteration for subclass rendering methods (avoids getEntries() spread). */
-    protected forEachEntry(fn: (entry: T) => void): void;
-    /** O(1) lookup: all entries for a specific execution step (returns a copy). */
-    getEntriesForStep(runtimeStageId: string): T[];
-    /** Number of unique execution steps that have entries. */
-    get stepCount(): number;
-    /**
-     * Pre-built range index: runtimeStageId → half-open range [firstIdx, endIdx) in entries array.
-     * Maintained during emit() — no rebuild needed. Use for O(1) per-step lookups during time-travel.
-     * endIdx includes trailing keyless entries (structural markers following a step).
-     */
-    getEntryRanges(): ReadonlyMap<string, {
-        readonly firstIdx: number;
-        readonly endIdx: number;
-    }>;
-    /** Reduce ALL entries to a single value. For dashboards, totals, summaries. */
-    aggregate<R>(fn: (acc: R, entry: T) => R, initial: R): R;
-    /**
-     * Reduce entries, optionally filtered by a set of runtimeStageIds.
-     * For time-travel progressive view: pass the runtimeStageIds visible at the current slider position.
-     * Entries without runtimeStageId (structural markers) are excluded when keys are provided.
-     * Without keys, reduces all entries (same as aggregate).
-     */
-    accumulate<R>(fn: (acc: R, entry: T) => R, initial: R, keys?: ReadonlySet<string>): R;
-    /**
-     * Progressive reveal: entries whose runtimeStageId is in the visible set.
-     * Preserves insertion order. Entries without runtimeStageId (structural markers)
-     * are buffered and included only when surrounded by visible steps on both sides —
-     * trailing markers after the last visible step are discarded.
-     */
-    getEntriesUpTo(visibleIds: ReadonlySet<string>): T[];
-    /** Clear all stored data. Called by executor before each run(). */
-    clear(): void;
-}