footprintjs 4.17.2 → 6.0.0

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

@@ -0,0 +1,147 @@
+/**
+ * CommitRangeIndex<TLabel> — interval index over commit indices.
+ *
+ * Built incrementally during traversal: `open(label, startIdx)` when a
+ * boundary begins, `close(token, endIdx)` when it ends. Query at any
+ * commit position with `enclosing(idx)` (returns ranges containing
+ * that index, ordered outer→inner) or `overlapping(start, end)`
+ * (returns ranges intersecting a slice).
+ *
+ * See `docs/design/commit-range-index.md` for the full contract. In
+ * one paragraph: this is a generic interval data structure for
+ * commit-range queries. footprintjs owns ZERO knowledge of what
+ * labels mean — consumers (agentfootprint, lens, OTel exporters)
+ * pick their own `TLabel` type. Open ranges (mid-run, no end yet)
+ * are first-class — query results carry `endIdx: undefined` for them.
+ *
+ * Pattern: incremental builder + interval query. Same "collect during
+ *          traversal, never post-process" rule footprintjs's CLAUDE.md
+ *          requires of every observer.
+ * Role:    structural primitive for time-travel UIs and per-boundary
+ *          aggregation.
+ * Channel: consumer-driven (no engine subscription).
+ *
+ * @example
+ * ```typescript
+ * import { CommitRangeIndex } from 'footprintjs/trace';
+ *
+ * const idx = new CommitRangeIndex<string>();
+ * const t = idx.open('LLMCall', executor.getCommitCount());
+ * // ... LLM call runs, scope writes happen ...
+ * idx.close(t, executor.getCommitCount());
+ *
+ * idx.enclosing(50);  // → ranges containing commit 50, outer→inner
+ * idx.overlapping(40, 60);  // → ranges sharing the slice [40,60]
+ * idx.clear();        // wipe (e.g., on new run)
+ * ```
+ *
+ * REDACTION NOTE: labels are stored verbatim and returned verbatim in
+ * query results — the index does NOT redact `TLabel` content. If a
+ * consumer attaches a label containing PII (user email, scope reads
+ * with sensitive keys, etc.) and then serializes the index for
+ * logging or telemetry, that data leaves the trust boundary. Use
+ * `RedactionPolicy` (or your own scrubbing) on the consumer side
+ * BEFORE attaching labels. The index follows the same contract as
+ * other footprintjs storage primitives (SequenceStore, KeyedStore):
+ * storage is verbatim; redaction is the caller's responsibility.
+ */
+/** Opaque token identifying an open range. Hold onto it; pass to `close()`.
+ *  Index-scoped — using a token from one CommitRangeIndex on another is
+ *  a silent no-op (verified by the per-index `_owner` symbol).
+ *
+ *  SECURITY NOTE: the `_owner` symbol is enumerable on the token object
+ *  via `Object.getOwnPropertySymbols(token)`. This means tokens are NOT
+ *  adversary-safe — a malicious caller with access to ANY token from
+ *  this index can recover the owner symbol and forge new tokens. The
+ *  index is designed for in-process trust boundaries (cooperative
+ *  recorders sharing one runner), not for hostile-input scenarios.
+ *  If adversary-safety becomes a requirement, switch to a WeakMap-
+ *  scoped token model (see security panel review Y2). */
+export interface RangeToken {
+    /** Per-index sequential id. Opaque to consumers — they shouldn't read it. */
+    readonly _id: number;
+    /** Per-index identity — prevents accidental cross-index token misuse. */
+    readonly _owner: symbol;
+}
+/** A single range as returned by query methods. Frozen-shape — readonly fields. */
+export interface RangeEntry<TLabel> {
+    readonly label: TLabel;
+    readonly startIdx: number;
+    /** Undefined while the range is still open (mid-run boundary). */
+    readonly endIdx?: number;
+}
+export declare class CommitRangeIndex<TLabel> {
+    private entries;
+    private byId;
+    private nextId;
+    /** Identity for token scoping — each index gets a fresh symbol so
+     *  tokens from one index can't accidentally close ranges in another.
+     *  ROTATED on `clear()` to invalidate stale tokens that survived a
+     *  run reset (would otherwise hit a recycled id and silently mutate
+     *  a different range — see DS+logic panel review RED #1). */
+    private owner;
+    /**
+     * Open a new range. Returns a token the caller MUST hold and pass
+     * to `close()` later. Each `open()` gets a fresh token; tokens
+     * cannot be reused or shared across indices (silent no-op if
+     * misused — see Law 2 in the design doc). Tokens from BEFORE
+     * the most recent `clear()` are also invalid (owner symbol
+     * rotates on clear).
+     */
+    open(label: TLabel, startIdx: number): RangeToken;
+    /**
+     * Close an open range at `endIdx` (inclusive). After close, the
+     * range is queryable with both bounds. Closing an already-closed
+     * token is a no-op. Closing an unknown token (from another index,
+     * or fabricated) is a no-op.
+     */
+    close(token: RangeToken, endIdx: number): void;
+    /**
+     * Returns ALL ranges enclosing `commitIdx`, ordered outer→inner.
+     * Includes both closed and open ranges. For a closed range to
+     * enclose: `startIdx <= commitIdx <= endIdx`. For an open range:
+     * `startIdx <= commitIdx` (no upper bound check).
+     *
+     * Ordering rule: ascending by `startIdx`, with TIES BROKEN BY
+     * descending `endIdx` (wider range = outer). Open ranges (endIdx
+     * undefined) are treated as `+Infinity` for tie-break — they
+     * always sort outer of any closed range starting at the same idx.
+     * This is the only deterministic outer→inner ordering when two
+     * boundaries open at the same commit (e.g., Parallel root +
+     * its first branch).
+     *
+     * Returns a SHALLOW IMMUTABLE COPY — caller mutations don't affect
+     * internal state.
+     */
+    enclosing(commitIdx: number): readonly RangeEntry<TLabel>[];
+    /**
+     * Returns all ranges OVERLAPPING the slice `[startIdx, endIdx]`. A
+     * range overlaps if it shares at least one commit position with the
+     * slice. Use for parallel-branch detection, time-window queries,
+     * or "what boundaries fired during this slice."
+     *
+     * Sorted by the SAME outer→inner comparator as `enclosing()`:
+     * ascending by `startIdx`, ties broken by descending `endIdx`
+     * (wider = outer; open ranges treated as +Infinity).
+     *
+     * Returns a SHALLOW IMMUTABLE COPY.
+     */
+    overlapping(startIdx: number, endIdx: number): readonly RangeEntry<TLabel>[];
+    /** Total range count (open + closed). */
+    get size(): number;
+    /**
+     * Wipe all ranges + reset the token counter AND rotate the owner
+     * symbol so any token from before this clear becomes invalid.
+     * Critical: without rotating the owner, a stale token whose `_id`
+     * happens to match a recycled id after clear would silently mutate
+     * the wrong entry. Owner rotation makes stale-token close a no-op
+     * via the `_owner !== this.owner` guard.
+     *
+     * Call from a consumer's runId guard when a new run starts (e.g.,
+     * agentfootprint's `observeRunId(onNewRun)` from Phase 2).
+     */
+    clear(): void;
+    /** O(1) lookup by token id. Always returns the entry that the token
+     *  references (or undefined if the id was never opened in this index). */
+    private findById;
+}

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

@@ -1,8 +1,8 @@
 /**
  * CompositeRecorder — fan-out a single recorder attachment to multiple child recorders.
  *
- * Implements both Recorder (scope data ops) and FlowRecorder (control flow events)
- * so it works with both `executor.attachRecorder()` and `executor.attachFlowRecorder()`.
+ * Implements both ScopeRecorder (scope data ops) and FlowRecorder (control flow events)
+ * so it works with both `executor.attachScopeRecorder()` and `executor.attachFlowRecorder()`.
  *
  * The composite has a single ID for idempotent attach/detach. Child recorders
  * keep their own IDs internally but are not individually visible to the executor.
@@ -20,7 +20,7 @@
  *   new DebugRecorder({ verbosity: 'minimal' }),
  * ]);
  *
- * executor.attachRecorder(observability);
+ * executor.attachScopeRecorder(observability);
  *
  * // Access child recorders by type
  * const metrics = observability.get(MetricRecorder);
@@ -39,11 +39,11 @@
  * }
  *
  * // Consumer
- * executor.attachRecorder(agentObservability());
+ * executor.attachScopeRecorder(agentObservability());
  * ```
  */
 import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent } from '../engine/narrative/types.js';
-import type { CommitEvent, ErrorEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../scope/types.js';
+import type { CommitEvent, ErrorEvent, ReadEvent, ScopeRecorder, StageEvent, WriteEvent } from '../scope/types.js';
 /** Snapshot format for composite recorders — wraps child snapshots. */
 export interface CompositeSnapshot {
     name: string;
@@ -55,10 +55,10 @@ export interface CompositeSnapshot {
         }>;
     };
 }
-export declare class CompositeRecorder implements Recorder, FlowRecorder {
+export declare class CompositeRecorder implements ScopeRecorder, FlowRecorder {
     readonly id: string;
     private readonly children;
-    constructor(id: string, children: Array<Recorder | FlowRecorder>);
+    constructor(id: string, children: Array<ScopeRecorder | FlowRecorder>);
     /**
      * Get a child recorder by class type.
      *
@@ -69,7 +69,7 @@ export declare class CompositeRecorder implements Recorder, FlowRecorder {
      */
     get<T>(type: new (...args: any[]) => T): T | undefined;
     /** Get all child recorders. */
-    getChildren(): ReadonlyArray<Recorder | FlowRecorder>;
+    getChildren(): ReadonlyArray<ScopeRecorder | FlowRecorder>;
     onRead(event: ReadEvent): void;
     onWrite(event: WriteEvent): void;
     onCommit(event: CommitEvent): void;

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

@@ -1,5 +1,5 @@
 /**
- * EmitRecorder — the third observer channel, alongside `Recorder`
+ * EmitRecorder — the third observer channel, alongside `ScopeRecorder`
  * (scope data-flow) and `FlowRecorder` (control-flow).
  *
  * ## Why this exists
@@ -34,7 +34,7 @@
  *
  * | Channel         | Fires when                         | Built-in consumers     |
  * |-----------------|------------------------------------|------------------------|
- * | `Recorder`      | scope read/write/commit            | DebugRecorder, MetricRecorder |
+ * | `ScopeRecorder`      | scope read/write/commit            | DebugRecorder, MetricRecorder |
  * | `FlowRecorder`  | traversal transitions              | NarrativeFlowRecorder, etc. |
  * | `EmitRecorder`  | consumer calls `scope.$emit(...)`  | (none ships today; Phase 3.X adds MemoryEmitRecorder) |
  *

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

@@ -111,7 +111,7 @@ export interface InOutEntry {
     readonly isRoot: boolean;
 }
 export interface InOutRecorderOptions {
-    /** Recorder id. Defaults to `inout-N` (auto-incremented). */
+    /** ScopeRecorder id. Defaults to `inout-N` (auto-incremented). */
     id?: string;
 }
 /**

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

@@ -0,0 +1,70 @@
+/**
+ * KeyedStore<T> — concrete, composable 1:1 storage keyed by string id.
+ *
+ * Pattern: COMPOSITION primitive. Concrete class — instantiate with
+ *          `new KeyedStore<T>()` and own it as a field on your
+ *          recorder. Replaces the abstract `KeyedRecorder<T>` base
+ *          class for the v5 "one purpose per recorder" rule.
+ * Role:    1:1 Map keyed by `runtimeStageId` (or any string).
+ *          Insertion-ordered iteration.
+ *
+ * **Contrast with `SequenceStore<T>`:** KeyedStore is 1:1 — one entry
+ * per key. Use SequenceStore for 1:N (multiple entries per
+ * runtimeStageId, ordering matters).
+ *
+ * @example
+ * ```typescript
+ * import { KeyedStore } from 'footprintjs/trace';
+ *
+ * interface TokenEntry { input: number; output: number; }
+ *
+ * // ONE PURPOSE: typed-event handler. Storage is composed in.
+ * class TokenRecorder {
+ *   readonly id = 'tokens';
+ *   private readonly store = new KeyedStore<TokenEntry>();
+ *
+ *   onLLMCall(event: LLMCallEvent) {
+ *     this.store.set(event.runtimeStageId, event.usage);
+ *   }
+ *
+ *   getForStep(id: string)    { return this.store.get(id); }
+ *   getTotalTokens()           { return this.store.aggregate((s, e) => s + e.input + e.output, 0); }
+ *   getTokensUpTo(keys: Set<string>) {
+ *     return this.store.accumulate((s, e) => s + e.input + e.output, 0, keys);
+ *   }
+ *
+ *   clear() { this.store.clear(); }
+ * }
+ * ```
+ */
+export declare class KeyedStore<T> {
+    private readonly data;
+    /** Store a single entry. Replaces any existing entry for the same key. */
+    set(key: string, entry: T): void;
+    /** Remove an entry. Returns true if the key existed, false otherwise. */
+    delete(key: string): boolean;
+    /** O(1) lookup. */
+    get(key: string): T | undefined;
+    /** True if a value exists for the key. */
+    has(key: string): boolean;
+    /** All entries as a read-only Map (insertion-ordered). */
+    getMap(): ReadonlyMap<string, T>;
+    /** All values 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 keys 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. Recorders typically call this from their own
+     *  `clear()` method, which the executor invokes before each run. */
+    clear(): void;
+}

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

@@ -16,7 +16,7 @@
  *   if (event.stageName.includes('llm')) return 0.7;
  *   return 1.0;
  * });
- * executor.attachRecorder(quality);
+ * executor.attachScopeRecorder(quality);
  * await executor.run();
  *
  * // Per-step score
@@ -29,7 +29,7 @@
  * quality.getLowest();  // { runtimeStageId: 'call-llm#5', entry: { score: 0.7, ... } }
  * ```
  */
-import type { ReadEvent, Recorder, StageEvent, WriteEvent } from '../scope/types.js';
+import type { ReadEvent, ScopeRecorder, StageEvent, WriteEvent } from '../scope/types.js';
 import { KeyedRecorder } from './KeyedRecorder.js';
 import type { RecorderOperation } from './RecorderOperation.js';
 /** Per-step quality data stored by QualityRecorder. */
@@ -64,12 +64,12 @@ export type QualityScoringFn = (runtimeStageId: string, context: {
 };
 /** Options for QualityRecorder. */
 export interface QualityRecorderOptions {
-    /** Recorder ID. Defaults to auto-increment. */
+    /** ScopeRecorder ID. Defaults to auto-increment. */
     id?: string;
     /** Preferred UI operation. Defaults to 'accumulate' (progressive quality). */
     preferredOperation?: RecorderOperation;
 }
-export declare class QualityRecorder extends KeyedRecorder<QualityEntry> implements Recorder {
+export declare class QualityRecorder extends KeyedRecorder<QualityEntry> implements ScopeRecorder {
     private static _counter;
     readonly id: string;
     readonly preferredOperation: RecorderOperation;

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

@@ -3,7 +3,7 @@
  *
  * 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 Recorder and FlowRecorder
+ * 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>:**

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';