footprintjs 4.6.0 → 4.8.0

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/dist/types/trace.d.ts

@@ -0,0 +1,23 @@
+/**
+ * footprintjs/trace — Execution tracing, debugging, and backtracking utilities.
+ *
+ * Runtime stage IDs, commit log queries, and keyed recorder base class.
+ *
+ * @example
+ * ```typescript
+ * import { parseRuntimeStageId, findLastWriter, KeyedRecorder } from 'footprintjs/trace';
+ *
+ * // Parse a runtimeStageId
+ * const { stageId, executionIndex } = parseRuntimeStageId('call-llm#5');
+ *
+ * // Backtrack: who wrote 'systemPrompt' before stage at idx 8?
+ * const writer = findLastWriter(commitLog, 'systemPrompt', 8);
+ *
+ * // Build a keyed recorder
+ * class MyRecorder extends KeyedRecorder<MyEntry> { ... }
+ * ```
+ */
+export type { ExecutionCounter } from './lib/engine/runtimeStageId.js';
+export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId } from './lib/engine/runtimeStageId.js';
+export { findCommit, findCommits, findLastWriter } from './lib/memory/commitLogUtils.js';
+export { KeyedRecorder } from './lib/recorder/KeyedRecorder.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "4.6.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",
@@ -82,6 +82,11 @@
       "types": "./dist/types/recorders.d.ts",
       "import": "./dist/esm/recorders.js",
       "require": "./dist/recorders.js"
+    },
+    "./trace": {
+      "types": "./dist/types/trace.d.ts",
+      "import": "./dist/esm/trace.js",
+      "require": "./dist/trace.js"
     }
   },
   "lint-staged": {