footprintjs 4.17.2 → 5.0.0

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

@@ -0,0 +1,120 @@
+/**
+ * SequenceStore<T> — concrete, composable storage for ordered sequence data.
+ *
+ * Pattern: COMPOSITION primitive. Concrete class — instantiate with
+ *          `new SequenceStore<T>()` and own it as a field on your
+ *          recorder. Replaces the abstract `SequenceRecorder<T>` base
+ *          class for the v5 "one purpose per recorder" rule:
+ *          stores ARE storage; recorders ARE event handlers; consumers
+ *          COMPOSE.
+ * Role:    Dual-indexed append-only sequence: a flat array preserving
+ *          insertion order plus a `Map<runtimeStageId, T[]>` for O(1)
+ *          per-step lookup. Plus a precomputed range index for time-
+ *          travel scrubbing.
+ *
+ * @example
+ * ```typescript
+ * import { SequenceStore } from 'footprintjs/trace';
+ * import type { ScopeRecorder } from 'footprintjs';
+ *
+ * interface AuditEntry {
+ *   runtimeStageId?: string;
+ *   type: 'read' | 'write' | 'decision';
+ *   detail: string;
+ * }
+ *
+ * // ONE PURPOSE: scope-event handler. Storage is composed in.
+ * class AuditRecorder implements ScopeRecorder {
+ *   readonly id = 'audit';
+ *   private readonly store = new SequenceStore<AuditEntry>();
+ *
+ *   onRead(event: ReadEvent) {
+ *     this.store.push({
+ *       runtimeStageId: event.runtimeStageId,
+ *       type: 'read',
+ *       detail: event.key,
+ *     });
+ *   }
+ *   onWrite(event: WriteEvent) {
+ *     this.store.push({
+ *       runtimeStageId: event.runtimeStageId,
+ *       type: 'write',
+ *       detail: event.key,
+ *     });
+ *   }
+ *
+ *   getAudit() { return this.store.getAll(); }
+ *   getAuditUpTo(ids: ReadonlySet<string>) {
+ *     return this.store.getEntriesUpTo(ids);
+ *   }
+ *
+ *   clear() { this.store.clear(); }
+ * }
+ * ```
+ *
+ * **Contrast with `KeyedStore<T>`:** SequenceStore stores 1:N entries
+ * per runtimeStageId in insertion order. Use KeyedStore for 1:1
+ * (one record per step — token counts, metric snapshots).
+ */
+export declare class SequenceStore<T extends {
+    runtimeStageId?: 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 push(). */
+    private readonly entryRanges;
+    /** The runtimeStageId of the most recently emitted keyed entry. Used to extend
+     *  ranges for trailing markers (entries without runtimeStageId attached after a step). */
+    private lastEmittedId;
+    /**
+     * Append an entry to both the ordered sequence, keyed index, and range index.
+     * All three reference the SAME entry object — no duplication.
+     */
+    push(entry: T): void;
+    /** All entries in insertion order. Returns a shallow copy — entry objects are shared. */
+    getAll(): T[];
+    /** Number of entries in the sequence. */
+    get size(): number;
+    /** Zero-copy iteration. Avoids the `getAll()` spread when the caller just needs
+     *  to walk the entries (e.g., aggregating, rendering). */
+    forEach(fn: (entry: T) => void): void;
+    /** O(1) lookup: all entries for a specific execution step. Returns a copy. */
+    getByKey(runtimeStageId: string): T[];
+    /** Number of distinct execution steps that have at least one entry. */
+    get keyCount(): number;
+    /**
+     * Pre-built range index: runtimeStageId → half-open `[firstIdx, endIdx)`
+     * range in the entries array. Maintained during `push()` — no rebuild
+     * needed. Use for O(1) per-step lookups during time-travel scrubbing.
+     * `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. Recorders typically call this from their own
+     *  `clear()` method, which the executor invokes before each run. */
+    clear(): void;
+}

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

@@ -97,7 +97,7 @@ export interface Topology {
     readonly rootId: string | null;
 }
 export interface TopologyRecorderOptions {
-    /** Recorder id. Defaults to `topology-N` (auto-incremented). */
+    /** ScopeRecorder id. Defaults to `topology-N` (auto-incremented). */
     id?: string;
 }
 /**

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

@@ -1,9 +1,12 @@
+export { BoundaryStateStore } from './BoundaryStateStore.js';
+export { KeyedStore } from './KeyedStore.js';
+export { SequenceStore } from './SequenceStore.js';
 export { BoundaryStateTracker } from './BoundaryStateTracker.js';
+export { KeyedRecorder } from './KeyedRecorder.js';
+export { SequenceRecorder } from './SequenceRecorder.js';
 export type { CombinedRecorder } from './CombinedRecorder.js';
 export { hasEmitRecorderMethods, hasFlowRecorderMethods, hasRecorderMethods, isFlowEvent } from './CombinedRecorder.js';
 export type { CompositeSnapshot } from './CompositeRecorder.js';
 export { CompositeRecorder } from './CompositeRecorder.js';
 export type { EmitEvent, EmitRecorder } from './EmitRecorder.js';
-export { KeyedRecorder } from './KeyedRecorder.js';
 export { RecorderOperation } from './RecorderOperation.js';
-export { SequenceRecorder } from './SequenceRecorder.js';

package/dist/types/lib/runner/ExecutionRuntime.d.ts

@@ -17,7 +17,7 @@ import type { CommitBundle, StageSnapshot } from '../memory/types.js';
 export interface RecorderSnapshot {
     id: string;
     name: string;
-    /** Recorder type and pattern description (e.g., "Translator (KeyedRecorder) — per-step token usage"). */
+    /** ScopeRecorder type and pattern description (e.g., "Translator (KeyedRecorder) — per-step token usage"). */
     description?: string;
     /** Preferred read-time operation — hints the UI about which view to show prominently. */
     preferredOperation?: 'translate' | 'accumulate' | 'aggregate';

package/dist/types/lib/runner/FlowChartExecutor.d.ts

@@ -26,7 +26,7 @@ import type { FlowchartCheckpoint } from '../pause/types.js';
 import type { CombinedRecorder } from '../recorder/CombinedRecorder.js';
 import type { EmitRecorder } from '../recorder/EmitRecorder.js';
 import type { ScopeProtectionMode } from '../scope/protection/types.js';
-import type { Recorder, RedactionPolicy, RedactionReport } from '../scope/types.js';
+import type { RedactionPolicy, RedactionReport, ScopeRecorder } from '../scope/types.js';
 import { type RuntimeSnapshot } from './ExecutionRuntime.js';
 /**
  * Options object for `FlowChartExecutor` — preferred over positional params.
@@ -86,6 +86,10 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     private traverser;
     /** Shared execution counter — survives pause/resume. Reset on fresh run(). */
     private _executionCounter;
+    /** Per-`run()` identifier — generated fresh per run + per resume. Threaded
+     *  through every TraversalContext so recorders can scope state to a single
+     *  run. See `runId.ts`. */
+    private _currentRunId;
     private narrativeEnabled;
     private narrativeOptions?;
     private combinedRecorder;
@@ -159,6 +163,24 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     getCheckpoint(): FlowchartCheckpoint | undefined;
     /** Returns `true` if the most recent run() was paused (checkpoint available). */
     isPaused(): boolean;
+    /**
+     * Number of commits in the run's commit log. O(1) — direct length
+     * read, no snapshot materialization. Use this to stamp commit
+     * indices on observer events (e.g., `BoundaryRecorder` storing
+     * `commitIdxBefore` / `commitIdxAfter` per domain event for
+     * `CommitRangeIndex` queries — see `footprintjs/trace`).
+     *
+     * Returns 0 before any run; after, returns the cumulative commit
+     * count across the executor's lifetime (including resumes).
+     *
+     * IMPLEMENTATION NOTE: this returns `runtime.executionHistory.length`,
+     * which is the same value as `getSnapshot().commitLog.length`. The
+     * naming asymmetry is historical — the underlying `EventLog` field
+     * is named `executionHistory` but stores the `CommitBundle[]` that
+     * `commitLog` exposes. They are the SAME array (verified by the
+     * "matches commitLog.length" integration test).
+     */
+    getCommitCount(): number;
     /**
      * Resume a paused flowchart from a checkpoint.
      *
@@ -201,7 +223,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     /** DFS search for a node by ID in the StageNode graph. Cycle-safe via visited set. */
     private dfsFind;
     /**
-     * Attach a scope Recorder to observe data operations (reads, writes, commits).
+     * Attach a scope ScopeRecorder to observe data operations (reads, writes, commits).
      * Automatically attached to every ScopeFacade created during traversal.
      * Must be called before run().
      *
@@ -216,18 +238,18 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * @example
      * ```typescript
      * // Multiple recorders with different configs — each gets a unique ID
-     * executor.attachRecorder(new MetricRecorder());
-     * executor.attachRecorder(new DebugRecorder({ verbosity: 'minimal' }));
+     * executor.attachScopeRecorder(new MetricRecorder());
+     * executor.attachScopeRecorder(new DebugRecorder({ verbosity: 'minimal' }));
      *
      * // Override a framework-attached recorder by passing its well-known ID
-     * executor.attachRecorder(new MetricRecorder('metrics'));
+     * executor.attachScopeRecorder(new MetricRecorder('metrics'));
      *
      * // Attaching twice with same ID replaces (no double-counting)
-     * executor.attachRecorder(new MetricRecorder('my-metrics'));
-     * executor.attachRecorder(new MetricRecorder('my-metrics')); // replaces previous
+     * executor.attachScopeRecorder(new MetricRecorder('my-metrics'));
+     * executor.attachScopeRecorder(new MetricRecorder('my-metrics')); // replaces previous
      * ```
      */
-    attachRecorder(recorder: Recorder): void;
+    attachScopeRecorder(recorder: ScopeRecorder): void;
     /**
      * Detach a child flowchart on the given driver and return a `DetachHandle`
      * the caller can `wait()` on (Promise) or read `.status` from (sync).
@@ -257,9 +279,9 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      */
     detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
     /** Detach all scope Recorders with the given ID. */
-    detachRecorder(id: string): void;
+    detachScopeRecorder(id: string): void;
     /** Returns a defensive copy of attached scope Recorders. */
-    getRecorders(): Recorder[];
+    getScopeRecorders(): ScopeRecorder[];
     /**
      * Attach a FlowRecorder to observe control flow events.
      * Automatically enables narrative if not already enabled.
@@ -277,7 +299,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * data-flow, control-flow, or both). Detects at runtime which streams the
      * recorder has methods for and routes it to the correct internal channels.
      *
-     * Preferred over calling `attachRecorder` and `attachFlowRecorder`
+     * Preferred over calling `attachScopeRecorder` and `attachFlowRecorder`
      * separately, because forgetting one of the two is a silent foot-gun —
      * half your events never fire and there is no runtime warning. With
      * `attachCombinedRecorder` the library guarantees the recorder's declared
@@ -287,7 +309,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      *
      * Idempotent by `id` across ALL channels — re-attaching with the same `id`
      * replaces the previous instance everywhere it was registered. Mixing
-     * `attachCombinedRecorder(x)` with a prior `attachRecorder(y)` or
+     * `attachCombinedRecorder(x)` with a prior `attachScopeRecorder(y)` or
      * `attachFlowRecorder(y)` that share `x.id === y.id` is also safe: the
      * combined attach replaces the single-channel registration on whichever
      * channel(s) `x` has methods for. No duplicate firings occur.
@@ -330,8 +352,8 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * Internally, emit recorders share the scope-recorder channel because
      * emit events fire from inside `ScopeFacade` during stage execution,
      * same timing as `onRead`/`onWrite`. This method is a convenience that
-     * delegates to `attachRecorder` — consumers can also use
-     * `attachRecorder` directly for a recorder that implements BOTH
+     * delegates to `attachScopeRecorder` — consumers can also use
+     * `attachScopeRecorder` directly for a recorder that implements BOTH
      * `onWrite` and `onEmit`. Either approach places the recorder on the
      * same underlying list, so `onEmit` fires exactly once per event.
      *

package/dist/types/lib/runner/RunContext.d.ts

@@ -10,7 +10,7 @@
 import type { FlowChart } from '../builder/types.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
 import type { RunOptions } from '../engine/types.js';
-import type { Recorder, RedactionPolicy } from '../scope/types.js';
+import type { RedactionPolicy, ScopeRecorder } from '../scope/types.js';
 /** Result from RunContext.run() — owns state and output. */
 export interface RunResult {
     /** Raw scope state after execution. */
@@ -29,7 +29,7 @@ export declare class RunContext<TOut = any, TScope = any> {
     private redactionPolicy?;
     constructor(chart: FlowChart<TOut, TScope>);
     /** Attach a recorder. Auto-detects scope vs flow recorder. Chainable. */
-    recorder(r: Recorder | FlowRecorder): RunContext<TOut, TScope>;
+    recorder(r: ScopeRecorder | FlowRecorder): RunContext<TOut, TScope>;
     /** Set redaction policy for this run. Chainable. */
     redact(policy: RedactionPolicy): RunContext<TOut, TScope>;
     /** Execute the chart with accumulated config. Returns RunResult. */

package/dist/types/lib/runner/RunnableChart.d.ts

@@ -9,7 +9,7 @@ import type { FlowChart } from '../builder/types.js';
 import type { JsonSchema } from '../contract/types.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
 import type { RunOptions } from '../engine/types.js';
-import type { Recorder, RedactionPolicy } from '../scope/types.js';
+import type { RedactionPolicy, ScopeRecorder } from '../scope/types.js';
 import { type RunResult, RunContext } from './RunContext.js';
 /** OpenAPI generation options. */
 export interface ChartOpenAPIOptions {
@@ -38,7 +38,7 @@ export interface MCPToolDescription {
  */
 export interface RunnableFlowChart<TOut = any, TScope = any> extends FlowChart<TOut, TScope> {
     /** Attach a recorder for the next run. Returns a chainable RunContext. */
-    recorder(r: Recorder | FlowRecorder): RunContext<TOut, TScope>;
+    recorder(r: ScopeRecorder | FlowRecorder): RunContext<TOut, TScope>;
     /** Set redaction policy for the next run. Returns a chainable RunContext. */
     redact(policy: RedactionPolicy): RunContext<TOut, TScope>;
     /** Execute the chart directly (bare run, no recorders). */

package/dist/types/lib/runner/runId.d.ts

@@ -0,0 +1,45 @@
+/**
+ * runId — per-`executor.run()` identifier generator.
+ *
+ * Pattern: monotonic counter + clock-guarded timestamp. One id per
+ *          call to `executor.run()` (or `executor.resume()`). Stable
+ *          for the duration of that run; unique across consecutive
+ *          runs.
+ * Role:    primitive that solves the "two consecutive runs of the
+ *          same executor produce identical runtimeStageIds" class of
+ *          bugs. Recorders that accumulate state across runs detect
+ *          "new run" via `runId` change and reset transient
+ *          bookkeeping.
+ *
+ * Format: `${timestamp}-${counter}`.
+ *   - `timestamp` is `Date.now()` clamped to a monotonic-clock guard
+ *     (never decreases — protects against NTP / system-clock
+ *     adjustments).
+ *   - `counter` is a process-local incrementing integer, ZERO-PADDED
+ *     to 10 digits so lexicographic sort matches numeric order
+ *     (`"...001"` < `"...010"` < `"...100"`). 10 digits = 10 billion
+ *     runs in a single process — sufficient for any real workload.
+ *
+ * Lexicographic ordering of `runId` strings matches chronological
+ * ordering for runs that are at least 1ms apart, AND for runs that
+ * happen within the same millisecond (because the padded counter
+ * tie-breaks). The counter NEVER resets — it is process-global.
+ *
+ * Process-local only. Cross-process correlation uses
+ * `getEnv().traceId` (consumer-supplied), not `runId`. Documented
+ * in `docs/design/v5-recorder-redesign.md` Section 8.1.
+ */
+/**
+ * Generate a fresh runId. Called once per `executor.run()` and once
+ * per `executor.resume()`. Pure (deterministic for a given clock +
+ * counter state); no side effects beyond advancing the counter and
+ * monotonic-clock guard.
+ */
+export declare function generateRunId(): string;
+/**
+ * Reset the runId state. Test-only. NEVER call from production code —
+ * runIds must be process-globally monotonic.
+ *
+ * @internal
+ */
+export declare function _resetRunIdStateForTesting(): void;

package/dist/types/lib/scope/ScopeFacade.d.ts

@@ -15,7 +15,7 @@
  */
 import type { ExecutionEnv } from '../engine/types.js';
 import { StageContext } from '../memory/StageContext.js';
-import type { CommitEvent, Recorder, RedactionPolicy, RedactionReport } from './types.js';
+import type { CommitEvent, RedactionPolicy, RedactionReport, ScopeRecorder } from './types.js';
 export declare class ScopeFacade {
     static readonly BRAND: unique symbol;
     /**
@@ -60,9 +60,9 @@ export declare class ScopeFacade {
      * Never includes actual values — only key names, field names, and patterns.
      */
     getRedactionReport(): RedactionReport;
-    attachRecorder(recorder: Recorder): void;
-    detachRecorder(recorderId: string): void;
-    getRecorders(): Recorder[];
+    attachScopeRecorder(recorder: ScopeRecorder): void;
+    detachScopeRecorder(recorderId: string): void;
+    getScopeRecorders(): ScopeRecorder[];
     /** @internal */
     notifyStageStart(): void;
     /** @internal */

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

@@ -5,7 +5,7 @@
  * providers, protection, and Zod-based scope definitions.
  */
 export { ScopeFacade } from './ScopeFacade.js';
-export type { CommitEvent, ErrorEvent, ReadEvent, Recorder, RecorderContext, RedactionPolicy, RedactionReport, StageEvent, WriteEvent, } from './types.js';
+export type { CommitEvent, ErrorEvent, ReadEvent, RecorderContext, RedactionPolicy, RedactionReport, ScopeRecorder, StageEvent, WriteEvent, } from './types.js';
 export type { DebugEntry, DebugRecorderOptions, DebugVerbosity } from './recorders/DebugRecorder.js';
 export { DebugRecorder } from './recorders/DebugRecorder.js';
 export type { AggregatedMetrics, StageMetrics } from './recorders/MetricRecorder.js';

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

@@ -5,7 +5,7 @@
  * and stage lifecycle events for troubleshooting.
  */
 import type { RecorderOperation } from '../../recorder/RecorderOperation.js';
-import type { ErrorEvent, PauseEvent, ReadEvent, Recorder, ResumeEvent, StageEvent, WriteEvent } from '../types.js';
+import type { ErrorEvent, PauseEvent, ReadEvent, ResumeEvent, ScopeRecorder, StageEvent, WriteEvent } from '../types.js';
 export type DebugVerbosity = 'minimal' | 'verbose';
 export interface DebugEntry {
     type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd' | 'pause' | 'resume';
@@ -26,15 +26,15 @@ export interface DebugRecorderOptions {
  * @example
  * ```typescript
  * // Verbose debug for development
- * executor.attachRecorder(new DebugRecorder({ verbosity: 'verbose' }));
+ * executor.attachScopeRecorder(new DebugRecorder({ verbosity: 'verbose' }));
  *
  * // Minimal debug for production (errors only)
- * executor.attachRecorder(new DebugRecorder({ verbosity: 'minimal' }));
+ * executor.attachScopeRecorder(new DebugRecorder({ verbosity: 'minimal' }));
  *
  * // Both coexist — different auto IDs
  * ```
  */
-export declare class DebugRecorder implements Recorder {
+export declare class DebugRecorder implements ScopeRecorder {
     private static _counter;
     readonly id: string;
     readonly preferredOperation: RecorderOperation;

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

@@ -7,7 +7,7 @@
  * @example
  * ```typescript
  * const metric = new MetricRecorder();
- * executor.attachRecorder(metric);
+ * executor.attachScopeRecorder(metric);
  * await executor.run();
  *
  * // Per-step (time-travel):
@@ -22,7 +22,7 @@
  */
 import { KeyedRecorder } from '../../recorder/KeyedRecorder.js';
 import type { RecorderOperation } from '../../recorder/RecorderOperation.js';
-import type { CommitEvent, PauseEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types.js';
+import type { CommitEvent, PauseEvent, ReadEvent, ScopeRecorder, StageEvent, WriteEvent } from '../types.js';
 /** Per-invocation metrics for a single execution step. */
 export interface StepMetrics {
     /** Human-readable stage name. */
@@ -60,14 +60,14 @@ export interface StageMetrics {
 }
 /** Options for MetricRecorder. */
 export interface MetricRecorderOptions {
-    /** Recorder ID. Defaults to auto-increment (`metrics-1`, `metrics-2`, ...). */
+    /** ScopeRecorder ID. Defaults to auto-increment (`metrics-1`, `metrics-2`, ...). */
     id?: string;
     /** Filter which stages are recorded. Return `true` to record, `false` to skip. */
     stageFilter?: (stageName: string) => boolean;
     /** Preferred UI operation. Defaults to 'aggregate' (dashboard totals). */
     preferredOperation?: RecorderOperation;
 }
-export declare class MetricRecorder extends KeyedRecorder<StepMetrics> implements Recorder {
+export declare class MetricRecorder extends KeyedRecorder<StepMetrics> implements ScopeRecorder {
     private static _counter;
     readonly id: string;
     readonly preferredOperation: RecorderOperation;

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

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

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

@@ -100,7 +100,7 @@ export interface RedactionReport {
  * If a recorder throws, the error is caught and passed to onError
  * hooks of other recorders; the scope operation continues normally.
  */
-export interface Recorder {
+export interface ScopeRecorder {
     readonly id: string;
     onRead?(event: ReadEvent): void;
     onWrite?(event: WriteEvent): void;

package/dist/types/recorders.d.ts

@@ -37,7 +37,7 @@ import { DebugRecorder } from './lib/scope/recorders/DebugRecorder.js';
 import type { AggregatedMetrics, MetricRecorderOptions, StageMetrics } from './lib/scope/recorders/MetricRecorder.js';
 import { MetricRecorder } from './lib/scope/recorders/MetricRecorder.js';
 /**
- * Recorder factory for combined flow+data narrative.
+ * ScopeRecorder factory for combined flow+data narrative.
  *
  * The returned recorder is a `CombinedNarrativeRecorder` — attach it to a
  * chart/executor, then read structured entries via `.getEntries()` after

package/dist/types/trace.d.ts

@@ -25,6 +25,11 @@ export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId } from
 export { findCommit, findCommits, findLastWriter } from './lib/memory/commitLogUtils.js';
 export type { CausalChainOptions, CausalNode, KeysReadLookup } from './lib/memory/backtrack.js';
 export { causalChain, flattenCausalDAG, formatCausalChain } from './lib/memory/backtrack.js';
+export { BoundaryStateStore } from './lib/recorder/BoundaryStateStore.js';
+export { KeyedStore } from './lib/recorder/KeyedStore.js';
+export { SequenceStore } from './lib/recorder/SequenceStore.js';
+export type { RangeEntry, RangeToken } from './lib/recorder/CommitRangeIndex.js';
+export { CommitRangeIndex } from './lib/recorder/CommitRangeIndex.js';
 export { KeyedRecorder } from './lib/recorder/KeyedRecorder.js';
 export { SequenceRecorder } from './lib/recorder/SequenceRecorder.js';
 export { BoundaryStateTracker } from './lib/recorder/BoundaryStateTracker.js';

package/package.json

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