footprintjs 4.7.0 → 4.8.0

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

@@ -2,16 +2,29 @@
  * KeyedRecorder<T> — base class for Map-based recorders keyed by runtimeStageId.
  *
  * Provides typed key-value storage with O(1) lookup, insertion-ordered iteration,
- * and common accessors. Recorder implementations extend this and call store()
- * from their event hooks.
+ * 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> {
- *   onLLMCall(event: LLMCallEvent) {
- *     this.store(event.runtimeStageId, { model: event.model, ... });
- *   }
- *   getStats() { return aggregate(this.values()); }
+ *   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); }
  * }
  * ```
  */
@@ -28,6 +41,16 @@ export declare abstract class KeyedRecorder<T> {
     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/scope/recorders/MetricRecorder.d.ts

@@ -1,89 +1,96 @@
 /**
- * MetricRecorder — Production-focused recorder for timing and execution counts.
+ * MetricRecorder — per-step timing and execution counts, keyed by runtimeStageId.
  *
- * Tracks read/write/commit counts per stage and measures stage execution duration.
- *
- * Each instance gets a unique auto-increment ID (`metrics-1`, `metrics-2`, ...),
- * so multiple recorders with different configs coexist. Pass an explicit ID to
- * override a specific instance (e.g., a framework-attached recorder).
+ * Stores per-invocation data during traversal. Aggregated views computed on read.
+ * Extends KeyedRecorder<StepMetrics> for O(1) lookup and standard operations.
  *
  * @example
  * ```typescript
- * // Track all stages (default)
- * executor.attachRecorder(new MetricRecorder());
+ * const metric = new MetricRecorder();
+ * executor.attachRecorder(metric);
+ * await executor.run();
  *
- * // Track only LLM-related stages
- * executor.attachRecorder(new MetricRecorder({
- *   stageFilter: (name) => ['CallLLM', 'ParseResponse'].includes(name),
- * }));
+ * // Per-step (time-travel):
+ * metric.getByKey('call-llm#5');  // { stageName, readCount, writeCount, duration }
  *
- * // Two recorders: one for LLM timing, one for everything else
- * executor.attachRecorder(new MetricRecorder({
- *   stageFilter: (name) => name === 'CallLLM',
- * }));
- * executor.attachRecorder(new MetricRecorder({
- *   stageFilter: (name) => name !== 'CallLLM',
- * }));
+ * // Aggregated (backward compat):
+ * metric.getMetrics();  // { totalDuration, totalReads, stageMetrics: Map<stageName, aggregated> }
  *
- * // Override a framework-attached recorder by passing its well-known ID
- * executor.attachRecorder(new MetricRecorder({ id: 'metrics' }));
+ * // Progressive (slider):
+ * metric.accumulate((sum, m) => sum + m.duration, 0, visibleKeys);
  * ```
  */
+import { KeyedRecorder } from '../../recorder/KeyedRecorder.js';
 import type { CommitEvent, PauseEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types.js';
-export interface StageMetrics {
+/** Per-invocation metrics for a single execution step. */
+export interface StepMetrics {
+    /** Human-readable stage name. */
     stageName: string;
+    /** Number of scope reads during this invocation. */
     readCount: number;
+    /** Number of scope writes during this invocation. */
     writeCount: number;
+    /** Number of commits during this invocation. */
     commitCount: number;
+    /** Number of pauses during this invocation. */
     pauseCount: number;
-    totalDuration: number;
-    invocationCount: number;
+    /** Duration in ms for this invocation. */
+    duration: number;
 }
+/** Aggregated metrics across all invocations (backward compatible). */
 export interface AggregatedMetrics {
     totalDuration: number;
     totalReads: number;
     totalWrites: number;
     totalCommits: number;
     totalPauses: number;
+    /** Aggregated by stageName — sums across loop invocations. */
     stageMetrics: Map<string, StageMetrics>;
 }
-/** Options for MetricRecorder. All fields are optional. */
+/** Aggregated per-stageName (backward compatible with pre-runtimeStageId API). */
+export interface StageMetrics {
+    stageName: string;
+    readCount: number;
+    writeCount: number;
+    commitCount: number;
+    pauseCount: number;
+    totalDuration: number;
+    invocationCount: number;
+}
+/** Options for MetricRecorder. */
 export interface MetricRecorderOptions {
     /** Recorder ID. Defaults to auto-increment (`metrics-1`, `metrics-2`, ...). */
     id?: string;
-    /**
-     * Filter which stages are recorded. Return `true` to record, `false` to skip.
-     * When omitted, all stages are recorded.
-     *
-     * @example
-     * ```typescript
-     * // Only track stages that start with "Call"
-     * stageFilter: (name) => name.startsWith('Call')
-     * ```
-     */
+    /** Filter which stages are recorded. Return `true` to record, `false` to skip. */
     stageFilter?: (stageName: string) => boolean;
 }
-export declare class MetricRecorder implements Recorder {
+export declare class MetricRecorder extends KeyedRecorder<StepMetrics> implements Recorder {
     private static _counter;
     readonly id: string;
-    private metrics;
     private stageStartTimes;
+    private currentRuntimeStageId;
     private stageFilter?;
     constructor(idOrOptions?: string | MetricRecorderOptions);
     private shouldRecord;
+    /** Get or create the StepMetrics for the current stage. */
+    private current;
+    onStageStart(event: StageEvent): void;
     onRead(event: ReadEvent): void;
     onWrite(event: WriteEvent): void;
     onCommit(event: CommitEvent): void;
     onPause(event: PauseEvent): void;
-    onStageStart(event: StageEvent): void;
     onStageEnd(event: StageEvent): void;
+    /** Aggregated metrics — computes totals on the fly from per-step data (backward compatible). */
     getMetrics(): AggregatedMetrics;
+    /** Get aggregated metrics for a specific stage name (backward compatible). */
     getStageMetrics(stageName: string): StageMetrics | undefined;
+    /** Snapshot for serialization (backward compatible format). */
     toSnapshot(): {
         name: string;
         data: unknown;
     };
-    reset(): void;
+    /** Clear all state — called by executor before each run(). */
     clear(): void;
-    private getOrCreateStageMetrics;
+    /** Alias for clear() (backward compat). */
+    reset(): void;
 }

package/dist/types/lib/scope/recorders/index.d.ts

@@ -1,5 +1,5 @@
 export type { CommitEvent, ErrorEvent, ReadEvent, Recorder, RecorderContext, StageEvent, WriteEvent, } from '../types.js';
 export type { DebugEntry, DebugRecorderOptions, DebugVerbosity } from './DebugRecorder.js';
 export { DebugRecorder } from './DebugRecorder.js';
-export type { AggregatedMetrics, StageMetrics } from './MetricRecorder.js';
+export type { AggregatedMetrics, StageMetrics, StepMetrics } from './MetricRecorder.js';
 export { MetricRecorder } from './MetricRecorder.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",