footprintjs 4.17.2 → 6.0.0

package/dist/types/lib/engine/narrative/types.d.ts

@@ -13,9 +13,25 @@ import type { StructuredErrorInfo } from '../errors/errorInfo.js';
  * Uses Null Object pattern: NullControlFlowNarrativeGenerator satisfies this
  * interface with empty methods for zero-cost disabled path.
  */
+/**
+ * The kind of stage that completed. Lets consumers route uniform
+ * "did this stage execute" handling without a side-table lookup into
+ * the chart spec. Required on every `onStageExecuted` event since
+ * proposal #003 unified the event to fire for ALL stage kinds.
+ */
+export type StageType = 'linear' | 'decider' | 'fork' | 'selector' | 'subflow-mount';
 export interface IControlFlowNarrative {
-    /** Called when a stage executes. First stage uses distinct opening pattern. */
-    onStageExecuted(stageName: string, description?: string, traversalContext?: TraversalContext): void;
+    /**
+     * Called when a stage completes its main work. Fires for ALL stage
+     * kinds (`'linear'`, `'decider'`, `'fork'`, `'selector'`, `'subflow-mount'`)
+     * AFTER the corresponding specialized event (`onDecision`, `onFork`,
+     * `onSelected`, `onSubflowEntry`). For linear stages, fires after
+     * the stage function returns.
+     *
+     * Consumers tracking "did this stage run?" use this event uniformly
+     * and switch on `stageType` for kind-specific work.
+     */
+    onStageExecuted(stageName: string, description: string | undefined, traversalContext: TraversalContext | undefined, stageType: StageType): void;
     /** Called on linear continuation from one stage to the next. */
     onNext(fromStage: string, toStage: string, description?: string, traversalContext?: TraversalContext): void;
     /** Called when a decider selects a branch. Most valuable for LLM context. */
@@ -73,9 +89,26 @@ export interface IControlFlowNarrative {
  * Like OpenTelemetry's span context: stageId + parentStageId form a tree.
  */
 export interface TraversalContext {
+    /**
+     * Per-`executor.run()` identifier. Generated once at the start of every
+     * `run()` (and again on `resume()`); shared by every event of that run;
+     * differs across consecutive runs of the same executor.
+     *
+     * Format: `${Date.now()}-${counter}` — sortable lexicographically (==
+     * chronologically for runs > 1ms apart). Process-local — for cross-
+     * process correlation use `getEnv().traceId` (consumer-supplied).
+     *
+     * Recorders that accumulate state across runs (fork bookkeeping,
+     * sibling-handoff state, etc.) detect "new run" via
+     * `event.traversalContext.runId !== this.lastRunId` and reset
+     * transient bookkeeping. Recorders that don't care about scoping
+     * ignore the field.
+     */
+    readonly runId: string;
     /** Stable stage identifier from the builder (matches spec node id). */
     readonly stageId: string;
-    /** Unique per-execution-step identifier. Format: [subflowPath/]stageId#executionIndex */
+    /** Unique per-execution-step identifier. Format: [subflowPath/]stageId#executionIndex.
+     *  Counter resets per executor — combine with `runId` for globally unique step keys. */
     readonly runtimeStageId: string;
     /** Human-readable stage name. */
     readonly stageName: string;
@@ -98,6 +131,12 @@ export interface FlowStageEvent {
     description?: string;
     /** Traversal context from the engine — read-only, set by traverser. */
     traversalContext?: TraversalContext;
+    /**
+     * Which kind of stage completed. The engine fires `onStageExecuted`
+     * uniformly for every stage kind (proposal #003); consumers route by
+     * `stageType` without a chart-spec lookup.
+     */
+    stageType: StageType;
 }
 /** Event passed to FlowRecorder.onNext. */
 export interface FlowNextEvent {
@@ -228,7 +267,7 @@ export interface FlowRunEvent {
 /**
  * FlowRecorder — Pluggable observer for control flow events.
  *
- * Mirrors the scope-level Recorder pattern for the engine layer.
+ * Mirrors the scope-level ScopeRecorder pattern for the engine layer.
  * All methods are optional — implement only the hooks you need.
  * Recorders are invoked synchronously in attachment order.
  * If a recorder throws, the error is caught and swallowed; execution continues.

package/dist/types/lib/engine/runtimeStageId.d.ts

@@ -14,6 +14,15 @@
  *   - Human-readable ('sf-tools/execute-tool-calls#8')
  *   - Parseable (split on '#' for stageId and index, split stageId on '/' for subflow path)
  *
+ * Naming-collision warning
+ * ────────────────────────
+ *   The parsed-output `.stageId` field below is the LOCAL form (segment
+ *   after the last '/'). This is NOT the same as `spec.id` / `node.id`
+ *   for subflow-nested stages, which carry the FULL prefixed form
+ *   (`'sf-tools/execute-tool-calls'`). To compare safely, use
+ *   `splitStageId(spec.id)` to decompose the prefixed form the same
+ *   way `parseRuntimeStageId` decomposes a runtimeStageId.
+ *
  * @example
  * ```
  * buildRuntimeStageId('call-llm', 5)                    // 'call-llm#5'
@@ -29,12 +38,59 @@
  * consumers constructing IDs from parsed components (round-trip via parseRuntimeStageId).
  */
 export declare function buildRuntimeStageId(stageId: string, executionIndex: number, subflowPath?: string): string;
-/** Parse a runtimeStageId into its components. */
+/**
+ * Parse a runtimeStageId into its components.
+ *
+ * IMPORTANT — naming collision: the returned `stageId` is the LOCAL
+ * form (the segment between the last '/' and the '#'). This is NOT
+ * the same as `spec.id` or `node.id` for subflow-nested stages,
+ * which contain the FULL prefixed form.
+ *
+ *   parseRuntimeStageId('sf-tools/execute-tool-calls#8').stageId
+ *   // → 'execute-tool-calls'   (LOCAL)
+ *
+ *   node.id  // (post-mount, in a spec that contains subflows)
+ *   // → 'sf-tools/execute-tool-calls'   (FULL prefixed)
+ *
+ * To compare these two safely, use `splitStageId(node.id)` to get
+ * the local form, OR reconstruct the full form via
+ * `(subflowPath ? subflowPath + '/' : '') + stageId`.
+ */
 export declare function parseRuntimeStageId(runtimeStageId: string): {
     stageId: string;
     executionIndex: number;
     subflowPath: string | undefined;
 };
+/**
+ * Decompose a (possibly prefixed) stage id into its components.
+ *
+ * Use this when you have an id WITHOUT the `#N` execution suffix and
+ * need the local stage name and/or the subflow path. Common sources
+ * of such ids:
+ *   - `spec.id` (post-mount the id includes any subflow prefix)
+ *   - `CommitBundle.stageId` (post-mount id)
+ *   - `node.id` from xyflow nodes built off the spec
+ *   - the segment of `runtimeStageId` BEFORE the `#` (use
+ *     `parseRuntimeStageId` directly for full runtimeStageId strings)
+ *
+ * Mirrors the decomposition `parseRuntimeStageId` performs on the
+ * stageId portion of a runtimeStageId, so the two helpers stay in
+ * lockstep on naming and behavior.
+ *
+ * @example
+ * splitStageId('sf-tools/execute-tool-calls')
+ * // → { localStageId: 'execute-tool-calls', subflowPath: 'sf-tools' }
+ *
+ * splitStageId('execute-tool-calls')
+ * // → { localStageId: 'execute-tool-calls', subflowPath: undefined }
+ *
+ * splitStageId('sf-outer/sf-inner/validate')
+ * // → { localStageId: 'validate', subflowPath: 'sf-outer/sf-inner' }
+ */
+export declare function splitStageId(prefixedStageId: string): {
+    localStageId: string;
+    subflowPath: string | undefined;
+};
 /**
  * Shared mutable counter for execution index.
  * Passed by reference to child traversers (subflows) so they

package/dist/types/lib/engine/traversal/FlowchartTraverser.d.ts

@@ -21,7 +21,7 @@
 import type { ScopeProtectionMode } from '../../scope/protection/types.js';
 import { FlowRecorderDispatcher } from '../narrative/FlowRecorderDispatcher.js';
 import type { FlowRecorder, IControlFlowNarrative } from '../narrative/types.js';
-import type { ExtractorError, IExecutionRuntime, ILogger, ScopeFactory, SerializedPipelineStructure, StageFunction, StageNode, StreamHandlers, SubflowResult, TraversalExtractor, TraversalResult } from '../types.js';
+import type { IExecutionRuntime, ILogger, ScopeFactory, SerializedPipelineStructure, StageFunction, StageNode, StreamHandlers, SubflowResult, TraversalResult } from '../types.js';
 export interface TraverserOptions<TOut = any, TScope = any> {
     root: StageNode<TOut, TScope>;
     stageMap: Map<string, StageFunction<TOut, TScope>>;
@@ -32,12 +32,10 @@ export interface TraverserOptions<TOut = any, TScope = any> {
     executionEnv?: import('../../engine/types').ExecutionEnv;
     throttlingErrorChecker?: (error: unknown) => boolean;
     streamHandlers?: StreamHandlers;
-    extractor?: TraversalExtractor;
     scopeProtectionMode?: ScopeProtectionMode;
     subflows?: Record<string, {
         root: StageNode<TOut, TScope>;
     }>;
-    enrichSnapshots?: boolean;
     narrativeEnabled?: boolean;
     buildTimeStructure?: SerializedPipelineStructure;
     logger: ILogger;
@@ -71,6 +69,14 @@ export interface TraverserOptions<TOut = any, TScope = any> {
      * the inputMapper. Undefined on normal `run()` paths.
      */
     subflowStatesForResume?: Record<string, Record<string, unknown>>;
+    /**
+     * Per-`executor.run()` identifier. Threaded into every TraversalContext
+     * this traverser produces so recorders can scope state to a single run.
+     * Subflow traversers inherit the parent's runId (the subflow is part of
+     * the same run from the consumer's POV). Required field — every event
+     * needs it. See `runner/runId.ts`.
+     */
+    runId: string;
 }
 export declare class FlowchartTraverser<TOut = any, TScope = any> {
     private readonly root;
@@ -84,6 +90,9 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
      *  top-level traversal so consumers (e.g. `InOutRecorder`) can bracket
      *  the run with the same payload shape that subflows already have. */
     private readonly readOnlyContext?;
+    /** Per-`executor.run()` identifier. Stamped onto every TraversalContext.
+     *  Inherited by subflow traversers so all events of one run share one runId. */
+    private readonly runId;
     private readonly nodeResolver;
     private readonly childrenExecutor;
     private readonly subflowExecutor;
@@ -92,7 +101,6 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     private readonly deciderHandler;
     private readonly selectorHandler;
     private readonly structureManager;
-    private readonly extractorRunner;
     private readonly narrativeGenerator;
     private readonly flowRecorderDispatcher;
     private subflowResults;
@@ -183,8 +191,6 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     getBranchIds(): string[];
     getRuntimeRoot(): StageNode;
     getSubflowResults(): Map<string, SubflowResult>;
-    getExtractedResults<TResult = unknown>(): Map<string, TResult>;
-    getExtractorErrors(): ExtractorError[];
     getNarrative(): string[];
     /** Returns the FlowRecorderDispatcher, or undefined if narrative is disabled. */
     getFlowRecorderDispatcher(): FlowRecorderDispatcher | undefined;

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

@@ -323,32 +323,6 @@ export interface RuntimeStructureMetadata {
     isLoopReference?: boolean;
     streamId?: string;
 }
-export interface StageSnapshot<TOut = any, TScope = any> {
-    node: StageNode<TOut, TScope>;
-    context: StageContext;
-    stepNumber: number;
-    structureMetadata: RuntimeStructureMetadata;
-    scopeState?: Record<string, unknown>;
-    debugInfo?: {
-        logs: Record<string, unknown>;
-        errors: Record<string, unknown>;
-        metrics: Record<string, unknown>;
-        evals: Record<string, unknown>;
-        flowMessages?: FlowMessage[];
-    };
-    stageOutput?: unknown;
-    errorInfo?: {
-        type: string;
-        message: string;
-    };
-    historyIndex?: number;
-}
-export type TraversalExtractor<TResult = unknown> = (snapshot: StageSnapshot) => TResult | undefined | null;
-export interface ExtractorError {
-    stagePath: string;
-    message: string;
-    error: unknown;
-}
 export type NodeResultType = {
     id: string;
     result: unknown;

package/dist/types/lib/engine/walkSubflowSpec.d.ts

@@ -0,0 +1,95 @@
+/**
+ * walkSubflowSpec — yield the structural shape of a subflow spec as a
+ * flat ordered stream of items, with `subflowPath` already composed
+ * for nested subflows.
+ *
+ * This is the public contract for traversing the structure delivered
+ * via `StructureSubflowMountedEvent.subflowSpec`. Item shapes mirror
+ * the corresponding Structure event payloads so consumers can route
+ * walker items through the same handlers they use for live events.
+ *
+ * Walker contract (LOCKED):
+ *   1. AUTO-RECURSE by default into nested subflows, with composed
+ *      paths (`parent/child/...`). Pass `{ recurse: false }` to walk
+ *      only one level.
+ *   2. ENTRY-STAGE MARKER FIRST: for each subflow (top-level and
+ *      nested), yields a `{ kind: 'subflow-start', ... }` item BEFORE
+ *      any stage/edge items from that subflow. Lets consumers draw the
+ *      boundary edge from the mount node to the entry stage.
+ *   3. COMPOSED PATHS: nested subflows get `parentPath + '/' + localId`.
+ *      Top-level mount paths are local-only (`'auth'`, NOT `'__root__/auth'`).
+ *   4. SHAPE MIRRORING: stage/edge/loop items have the same payload
+ *      shape as Structure events, with `subflowPath` added.
+ *   5. SOURCE DISCRIMINATOR: every walker item carries `source: 'walker'`
+ *      (Structure events do NOT). Lets consumers distinguish event vs
+ *      walker in logs/debuggers while still sharing handler code paths.
+ *   6. STAGE-ID PREFIXING: stage IDs in nested subflows are already
+ *      prefixed by the spec (e.g. `'auth/verify/check'`). Walker
+ *      preserves this; `subflowPath` field is redundant-but-explicit.
+ */
+import type { SerializedPipelineStructure } from '../builder/types.js';
+export interface WalkerOptions {
+    /** Auto-recurse into nested subflows (default: true). When false,
+     *  nested subflow items are yielded but their internals are not
+     *  traversed. */
+    recurse?: boolean;
+}
+export type WalkerItem = {
+    kind: 'subflow-start';
+    stageId: string;
+    subflowPath: string;
+    source: 'walker';
+} | {
+    kind: 'stage';
+    stageId: string;
+    name: string;
+    type: NonNullable<SerializedPipelineStructure['type']>;
+    isPausable?: boolean;
+    spec: SerializedPipelineStructure;
+    subflowPath: string;
+    source: 'walker';
+} | {
+    kind: 'edge';
+    from: string;
+    to: string;
+    edgeKind: 'next' | 'fork-branch' | 'decision-branch';
+    label?: string;
+    subflowPath: string;
+    source: 'walker';
+} | {
+    kind: 'loop';
+    from: string;
+    to: string;
+    subflowPath: string;
+    source: 'walker';
+} | {
+    kind: 'subflow';
+    mountStageId: string;
+    subflowId: string;
+    subflowName: string;
+    subflowSpec: SerializedPipelineStructure;
+    subflowPath: string;
+    source: 'walker';
+};
+/**
+ * Walk a subflow spec, yielding its structure as flat ordered items.
+ *
+ * @example
+ * ```ts
+ * import { walkSubflowSpec } from 'footprintjs/trace';
+ *
+ * onSubflowMounted(event) {
+ *   if (!event.subflowSpec) return; // lazy mount — no spec yet
+ *   for (const item of walkSubflowSpec(event.subflowSpec, event.subflowPath)) {
+ *     switch (item.kind) {
+ *       case 'subflow-start': break;        // entry boundary
+ *       case 'stage':         break;        // inner stage
+ *       case 'edge':          break;        // inner edge
+ *       case 'loop':          break;        // inner loop back-edge
+ *       case 'subflow':       break;        // nested mount marker
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function walkSubflowSpec(spec: SerializedPipelineStructure, subflowPath: string, options?: WalkerOptions): Generator<WalkerItem, void, void>;

package/dist/types/lib/memory/StageContext.d.ts

@@ -50,7 +50,7 @@ export declare class StageContext {
     private _stageWrites;
     /** Tracks user-level reads (pre-namespace) for the memory view. */
     private _stageReads;
-    /** Observer called after commit() — used by ScopeFacade to fire Recorder.onCommit. */
+    /** Observer called after commit() — used by ScopeFacade to fire ScopeRecorder.onCommit. */
     private _commitObserver?;
     constructor(runId: string, name: string, stageId: string, sharedMemory: SharedMemory, branchId?: string, eventLog?: EventLog, isDecider?: boolean);
     /** Returns the SharedMemory instance (needed by scope layer). */
@@ -89,7 +89,7 @@ export declare class StageContext {
     getScope(): Record<string, unknown>;
     getRunId(): string;
     /** Register an observer that fires after commit() applies patches.
-     *  Used by ScopeFacade to dispatch Recorder.onCommit events. */
+     *  Used by ScopeFacade to dispatch ScopeRecorder.onCommit events. */
     setCommitObserver(observer: (mutations: Record<string, {
         value: unknown;
         operation: 'set' | 'update' | 'delete';

package/dist/types/lib/memory/backtrack.d.ts

@@ -84,7 +84,7 @@ export interface CausalChainOptions {
  * which read→write edges to follow.
  *
  * Implementors: QualityRecorder tracks keysRead per step,
- * or build a Map<runtimeStageId, string[]> from Recorder.onRead events.
+ * or build a Map<runtimeStageId, string[]> from ScopeRecorder.onRead events.
  */
 export type KeysReadLookup = (runtimeStageId: string) => string[];
 /**

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

@@ -8,7 +8,7 @@
  * Dependency: type-only imports from engine/ and scope/ (zero runtime cost).
  */
 import type { ExecutionEnv } from '../engine/types.js';
-import type { Recorder } from '../scope/types.js';
+import type { ScopeRecorder } from '../scope/types.js';
 export interface ReactiveTarget {
     getValue(key?: string): unknown;
     setValue(key: string, value: unknown, shouldRedact?: boolean, description?: string): void;
@@ -22,9 +22,9 @@ export interface ReactiveTarget {
     getValueSilent?(key?: string): unknown;
     getArgs<T = Record<string, unknown>>(): T;
     getEnv(): Readonly<ExecutionEnv>;
-    attachRecorder(recorder: Recorder): void;
-    detachRecorder(recorderId: string): void;
-    getRecorders(): Recorder[];
+    attachScopeRecorder(recorder: ScopeRecorder): void;
+    detachScopeRecorder(recorderId: string): void;
+    getScopeRecorders(): ScopeRecorder[];
     addDebugInfo(key: string, value: unknown): void;
     addDebugMessage(value: unknown): void;
     addErrorInfo(key: string, value: unknown): void;
@@ -48,9 +48,9 @@ export interface ScopeMethods {
     $error(key: string, value: unknown): void;
     $metric(name: string, value: unknown): void;
     $eval(name: string, value: unknown): void;
-    $attachRecorder(recorder: Recorder): void;
-    $detachRecorder(recorderId: string): void;
-    $getRecorders(): Recorder[];
+    $attachScopeRecorder(recorder: ScopeRecorder): void;
+    $detachScopeRecorder(recorderId: string): void;
+    $getScopeRecorders(): ScopeRecorder[];
     /**
      * Batch-mutate an array key in a single clone+write cycle.
      *

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

@@ -0,0 +1,115 @@
+/**
+ * BoundaryStateStore<TState> — concrete, composable per-boundary
+ * transient state storage.
+ *
+ * Pattern: COMPOSITION primitive. Concrete class — instantiate with
+ *          `new BoundaryStateStore<TState>()` and own it as a field
+ *          on your recorder. Replaces the abstract
+ *          `BoundaryStateTracker<TState>` base class for the v5
+ *          "one purpose per recorder" rule.
+ * Role:    "What's the LIVE transient state of every currently-active
+ *          boundary?" A boundary is a matched event pair `[start, stop]`
+ *          bracketing an interval (e.g., `(llm_start, llm_end)`).
+ *          Between the brackets, intermediate events evolve the
+ *          boundary's state. On `stop`, the state clears.
+ *
+ * Algorithmically this is the **DFS bracket-sequence pattern** — the
+ * `active` map is the open-brackets stack at any moment.
+ *
+ * **Lifecycle contract — STRICT:** every `start(key, ...)` call MUST
+ * be paired with a `stop(key)` call. Failure to wire stop produces a
+ * memory leak: the active map grows without bound.
+ *
+ * **Concurrency / nesting:** concurrent boundaries (parallel branches
+ * with two LLM calls active at once) work correctly — each is keyed
+ * independently. Nested boundaries of DIFFERENT KINDS require
+ * SEPARATE store instances — one per kind.
+ *
+ * @example
+ * ```typescript
+ * import { BoundaryStateStore } from 'footprintjs/trace';
+ * import type { CombinedRecorder, EmitEvent } from 'footprintjs';
+ *
+ * interface LLMLiveState { partial: string; tokens: number; }
+ *
+ * class LiveLLMTracker implements CombinedRecorder {
+ *   readonly id = 'live-llm';
+ *   private readonly store = new BoundaryStateStore<LLMLiveState>();
+ *
+ *   onEmit(event: EmitEvent): void {
+ *     if (event.name === 'agentfootprint.stream.llm_start') {
+ *       this.store.start(event.runtimeStageId, { partial: '', tokens: 0 });
+ *     } else if (event.name === 'agentfootprint.stream.llm_end') {
+ *       this.store.stop(event.runtimeStageId);
+ *     } else if (event.name === 'agentfootprint.stream.token') {
+ *       this.store.update(event.runtimeStageId, (s) => ({
+ *         partial: s.partial + (event.payload as { content: string }).content,
+ *         tokens: s.tokens + 1,
+ *       }));
+ *     }
+ *   }
+ *
+ *   isInFlight(): boolean { return this.store.hasActive; }
+ *   getPartial(rid: string): string {
+ *     return this.store.get(rid)?.partial ?? '';
+ *   }
+ *
+ *   clear() { this.store.clear(); }
+ * }
+ * ```
+ */
+export declare class BoundaryStateStore<TState> {
+    /** Open-brackets stack: key → current transient state. */
+    private readonly active;
+    /** Per-key count of `update` 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;
+    /** Optional id for diagnostics — passed to dev-mode warnings so the
+     *  source of the leak is easy to find when multiple stores coexist. */
+    private readonly diagnosticId;
+    constructor(diagnosticId?: string);
+    /**
+     * 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). Dev mode warns — usually
+     * indicates a missed `stop` upstream.
+     */
+    start(key: string, initial: TState): void;
+    /**
+     * Evolve the transient state of an active boundary using a pure
+     * updater function. Silent no-op if no boundary is active for `key`
+     * (defensive against out-of-order events). Dev mode logs a rate-
+     * limited warning.
+     */
+    update(key: string, updater: (prev: TState) => TState): void;
+    /**
+     * Close the boundary identified by `key` and return its FINAL
+     * transient state (so the consumer can do any cleanup — e.g., emit
+     * a snapshot to a SequenceStore for durable storage).
+     */
+    stop(key: string): TState | undefined;
+    /** Current transient state of ONE active boundary. `undefined` if no
+     *  boundary is active for `key`. */
+    get(key: string): TState | undefined;
+    /** All currently-active boundaries.
+     *
+     *  **Type-only readonly:** TypeScript prevents mutation through
+     *  `ReadonlyMap`, but a runtime cast or non-TS consumer can mutate
+     *  the underlying Map and corrupt state. Don't. */
+    getAll(): 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 recorder composers from
+     * their own `clear()` method, which the executor invokes before
+     * each run.
+     *
+     * Dev mode warns if any boundaries are still active when called —
+     * likely indicates a missed `stop` upstream. Leaked keys are listed
+     * (truncated to 10) so the wiring bug is findable.
+     */
+    clear(): void;
+}

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

@@ -4,7 +4,7 @@
  *
  * **Mental model — observers vs. bookkeepers:**
  *
- *   `Recorder` / `FlowRecorder` / `EmitRecorder` / `CombinedRecorder`
+ *   `ScopeRecorder` / `FlowRecorder` / `EmitRecorder` / `CombinedRecorder`
  *     are OBSERVER interfaces — they describe how a recorder hears
  *     events from the executor.
  *
@@ -57,8 +57,8 @@
  *   - Aggregations across the whole run (totals, counts) — those are
  *     `SequenceRecorder.aggregate()` / `KeyedRecorder.aggregate()`.
  *
- *   - Stage-level concerns — those use `Recorder.onStageStart` /
- *     `Recorder.onStageEnd`. This primitive operates at finer
+ *   - Stage-level concerns — those use `ScopeRecorder.onStageStart` /
+ *     `ScopeRecorder.onStageEnd`. This primitive operates at finer
  *     granularity (events emitted DURING a stage execution).
  *
  * **Lifecycle contract — STRICT:**

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

@@ -7,9 +7,9 @@
  *
  * Before `CombinedRecorder`, a consumer who wanted to observe both streams
  * had to:
- *   1. Implement both `Recorder` (8 methods) and `FlowRecorder` (12 methods)
+ *   1. Implement both `ScopeRecorder` (8 methods) and `FlowRecorder` (12 methods)
  *      fully — stubbing every event they didn't care about.
- *   2. Remember to call BOTH `attachRecorder(r)` AND `attachFlowRecorder(r)`.
+ *   2. Remember to call BOTH `attachScopeRecorder(r)` AND `attachFlowRecorder(r)`.
  *      Forgetting the second call silently dropped half their events — no
  *      warning, no runtime error.
  *   3. Re-implement coordination logic (buffering, ordering) themselves.
@@ -36,7 +36,7 @@
  *
  * const audit: CombinedRecorder = {
  *   id: 'audit',
- *   onWrite: (e) => logWrite(e.key, e.value),        // Recorder method
+ *   onWrite: (e) => logWrite(e.key, e.value),        // ScopeRecorder method
  *   onDecision: (e) => logDecision(e.chosen),        // FlowRecorder method
  * };
  *
@@ -46,7 +46,7 @@
  *
  * ## Contract with existing APIs
  *
- * - `attachRecorder(r)` and `attachFlowRecorder(r)` remain unchanged.
+ * - `attachScopeRecorder(r)` and `attachFlowRecorder(r)` remain unchanged.
  *   Consumers who want only ONE channel keep using them — explicit is good.
  * - `attachCombinedRecorder(r)` is the ONLY way to guarantee an object is
  *   hooked into every stream it has methods for, without maintaining two
@@ -55,10 +55,10 @@
  *   same `id` replaces the previous instance on BOTH channels, not just one.
  */
 import type { FlowErrorEvent, FlowPauseEvent, FlowRecorder, FlowResumeEvent } from '../engine/narrative/types.js';
-import type { ErrorEvent, PauseEvent, Recorder, ResumeEvent } from '../scope/types.js';
+import type { ErrorEvent, PauseEvent, ResumeEvent, ScopeRecorder } from '../scope/types.js';
 import type { EmitRecorder } from './EmitRecorder.js';
 /**
- * Method names that appear on BOTH `Recorder` and `FlowRecorder` but with
+ * Method names that appear on BOTH `ScopeRecorder` and `FlowRecorder` but with
  * different event payload types. For these, a `CombinedRecorder` declares
  * ONE handler that receives the union of both payloads — consumers
  * discriminate on `traversalContext`, which only control-flow events carry.
@@ -70,7 +70,7 @@ type SharedLifecycle = 'id' | 'clear' | 'toSnapshot';
  * A recorder that MAY observe any combination of supported event streams.
  *
  * Today's streams:
- *   - Scope data-flow (`Recorder`: onRead/onWrite/onCommit/onStageStart/…)
+ *   - Scope data-flow (`ScopeRecorder`: onRead/onWrite/onCommit/onStageStart/…)
  *   - Control-flow (`FlowRecorder`: onDecision/onSubflowEntry/onLoop/…)
  *
  * All event handlers are optional — implement only what you care about.
@@ -78,7 +78,7 @@ type SharedLifecycle = 'id' | 'clear' | 'toSnapshot';
  *
  * ## Shared method names (onError / onPause / onResume)
  *
- * Both `Recorder` and `FlowRecorder` declare these with DIFFERENT payload
+ * Both `ScopeRecorder` and `FlowRecorder` declare these with DIFFERENT payload
  * shapes. In a combined recorder, each such handler is called by BOTH
  * channels with its own variant. The parameter type is a union — consumers
  * can either handle both variants uniformly, or discriminate (control-flow
@@ -90,7 +90,7 @@ type SharedLifecycle = 'id' | 'clear' | 'toSnapshot';
  * gains another `& Partial<…>` clause. Because every clause is `Partial`,
  * existing `CombinedRecorder` implementations remain type-valid.
  */
-export type CombinedRecorder = Partial<Omit<Recorder, SharedLifecycleOverlap | SharedLifecycle>> & Partial<Omit<FlowRecorder, SharedLifecycleOverlap | SharedLifecycle>> & Partial<Omit<EmitRecorder, SharedLifecycle>> & {
+export type CombinedRecorder = Partial<Omit<ScopeRecorder, SharedLifecycleOverlap | SharedLifecycle>> & Partial<Omit<FlowRecorder, SharedLifecycleOverlap | SharedLifecycle>> & Partial<Omit<EmitRecorder, SharedLifecycle>> & {
     readonly id: string;
     clear?(): void;
     toSnapshot?(): {
@@ -151,10 +151,10 @@ export declare function isFlowEvent<T>(event: T): event is Exclude<T, {
  *
  * ## Return type
  *
- * Returns plain `boolean` (not a type predicate). The full `Recorder`
+ * Returns plain `boolean` (not a type predicate). The full `ScopeRecorder`
  * interface has payload types that diverge from `CombinedRecorder`'s union
  * variants for shared methods, so a narrowing predicate would be unsound.
- * Callers that need to treat the recorder as a `Recorder` do so explicitly
+ * Callers that need to treat the recorder as a `ScopeRecorder` do so explicitly
  * at the attach site — the cast is the contract that each channel passes
  * its own payload variant.
  */