footprintjs 4.0.5 → 4.2.0

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

@@ -1,54 +1,35 @@
 /**
- * SubflowExecutor — Isolated recursive execution with I/O mapping.
+ * SubflowExecutor — Isolation boundary for subflow execution.
  *
  * Responsibilities:
- * - Execute subflows with isolated ExecutionRuntime contexts
+ * - Create isolated ExecutionRuntime for each subflow
  * - Apply input/output mapping via SubflowInputMapper
- * - Handle nested subflow detection and delegation
+ * - Delegate traversal to a factory-created FlowchartTraverser
  * - Track subflow results for debugging/visualization
  *
  * Each subflow gets its own GlobalStore for isolation.
- * The subflow's `next` chain after children is NOT executed inside —
- * the parent's executeNode continues with node.next after return.
+ * Traversal uses the SAME 7-phase algorithm as the top-level traverser
+ * (via SubflowTraverserFactory), so deciders, selectors, loops, lazy subflows,
+ * and abort signals all work inside subflows automatically.
  */
 import type { StageContext } from '../../memory/StageContext.js';
 import type { StageNode } from '../graph/StageNode.js';
 import type { TraversalContext } from '../narrative/types.js';
-import type { HandlerDeps, StageFunction, SubflowResult } from '../types.js';
-import type { NodeResolver } from './NodeResolver.js';
-import type { CallExtractorFn, RunStageFn } from './types.js';
-export type { CallExtractorFn, RunStageFn } from './types.js';
-/** Callback for getting a stage function from the stage map. */
-export type GetStageFnFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>) => StageFunction<TOut, TScope> | undefined;
+import type { HandlerDeps, SubflowResult, SubflowTraverserFactory } from '../types.js';
 export declare class SubflowExecutor<TOut = any, TScope = any> {
     private deps;
-    private nodeResolver;
-    private executeStage;
-    private callExtractor;
-    private getStageFn;
-    private currentSubflowDeps?;
-    private currentSubflowRoot?;
-    private subflowResultsMap?;
-    constructor(deps: HandlerDeps<TOut, TScope>, nodeResolver: NodeResolver<TOut, TScope>, executeStage: RunStageFn<TOut, TScope>, callExtractor: CallExtractorFn<TOut, TScope>, getStageFn: GetStageFnFn<TOut, TScope>);
+    private traverserFactory;
+    constructor(deps: HandlerDeps<TOut, TScope>, traverserFactory: SubflowTraverserFactory<TOut, TScope>);
     /**
      * Execute a subflow with isolated context.
      *
      * 1. Creates a fresh ExecutionRuntime for the subflow
      * 2. Applies input mapping to seed the subflow's GlobalStore
-     * 3. Executes the subflow's internal structure
+     * 3. Delegates traversal to a factory-created FlowchartTraverser
      * 4. Applies output mapping to write results back to parent scope
      * 5. Stores execution data for debugging/visualization
      */
     executeSubflow(node: StageNode<TOut, TScope>, parentContext: StageContext, breakFlag: {
         shouldBreak: boolean;
     }, branchPath: string | undefined, subflowResultsMap: Map<string, SubflowResult>, parentTraversalContext?: TraversalContext): Promise<any>;
-    /**
-     * Internal execution within subflow context.
-     * Mirrors the traverser's executeNode but within the subflow's isolated runtime.
-     */
-    private executeSubflowInternal;
-    private computeContextDepth;
-    private getStagePath;
-    private executeNodeChildrenInternal;
-    private executeSelectedChildrenInternal;
 }

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

@@ -13,12 +13,18 @@
  * emit the stage entry + flush the buffered ops in one pass.
  */
 import type { ReadEvent, Recorder, WriteEvent } from '../../scope/types.js';
-import type { CombinedNarrativeEntry } from './narrativeTypes.js';
+import type { CombinedNarrativeEntry, NarrativeRenderer } from './narrativeTypes.js';
 import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
 export interface CombinedNarrativeRecorderOptions {
     includeStepNumbers?: boolean;
     includeValues?: boolean;
     maxValueLength?: number;
+    /** Custom value formatter. Called at render time (flushOps), not capture time.
+     *  Receives the raw value and maxValueLength. Defaults to summarizeValue(). */
+    formatValue?: (value: unknown, maxLen: number) => string;
+    /** Pluggable renderer for customizing narrative output. Unimplemented methods
+     *  fall back to the default English renderer. See NarrativeRenderer docs. */
+    renderer?: NarrativeRenderer;
 }
 export declare class CombinedNarrativeRecorder implements FlowRecorder, Recorder {
     readonly id: string;
@@ -39,6 +45,8 @@ export declare class CombinedNarrativeRecorder implements FlowRecorder, Recorder
     private includeStepNumbers;
     private includeValues;
     private maxValueLength;
+    private formatValue;
+    private renderer?;
     constructor(options?: CombinedNarrativeRecorderOptions & {
         id?: string;
     });
@@ -79,4 +87,13 @@ export declare class CombinedNarrativeRecorder implements FlowRecorder, Recorder
     private consumeFirstStageFlag;
     private bufferOp;
     private flushOps;
+    private defaultRenderStage;
+    private defaultRenderOp;
+    private defaultRenderDecision;
+    private defaultRenderFork;
+    private defaultRenderSelected;
+    private defaultRenderSubflow;
+    private defaultRenderLoop;
+    private defaultRenderBreak;
+    private defaultRenderError;
 }

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

@@ -1,6 +1,6 @@
 export type { CombinedNarrativeRecorderOptions } from './CombinedNarrativeRecorder.js';
 export { CombinedNarrativeRecorder } from './CombinedNarrativeRecorder.js';
-export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './narrativeTypes.js';
+export type { BreakRenderContext, CombinedNarrativeEntry, CombinedNarrativeOptions, DecisionRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, } from './narrativeTypes.js';
 export { NullControlFlowNarrativeGenerator } from './NullControlFlowNarrativeGenerator.js';
 export type { IControlFlowNarrative } from './types.js';
 export { FlowRecorderDispatcher } from './FlowRecorderDispatcher.js';

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

@@ -15,9 +15,101 @@ export interface CombinedNarrativeEntry {
     stepNumber?: number;
     /** Subflow ID when this entry was generated inside a subflow. Undefined for root-level. */
     subflowId?: string;
+    /** Raw value from the scope event — available for programmatic access and custom formatting.
+     *  Only present on 'step' entries (read/write ops). This is a live reference, not a clone.
+     *  When using ScopeFacade, redacted keys will have value '[REDACTED]' (sanitized upstream
+     *  by ScopeFacade before dispatching events — the recorder does not enforce redaction). */
+    rawValue?: unknown;
 }
 export interface CombinedNarrativeOptions {
     includeStepNumbers?: boolean;
     includeValues?: boolean;
     indent?: string;
 }
+/** Context passed to renderStage. */
+export interface StageRenderContext {
+    stageName: string;
+    stageNumber: number;
+    isFirst: boolean;
+    description?: string;
+}
+/** Context passed to renderOp. Return null to exclude the entry. */
+export interface OpRenderContext {
+    type: 'read' | 'write';
+    key: string;
+    rawValue: unknown;
+    valueSummary: string;
+    operation?: 'set' | 'update' | 'delete';
+    stepNumber: number;
+}
+/** Context passed to renderDecision. */
+export interface DecisionRenderContext {
+    decider: string;
+    chosen: string;
+    description?: string;
+    rationale?: string;
+    /** Raw evidence from decide()/select() — available for custom rendering. */
+    evidence?: unknown;
+}
+/** Context passed to renderFork. */
+export interface ForkRenderContext {
+    children: string[];
+}
+/** Context passed to renderSubflow. */
+export interface SubflowRenderContext {
+    name: string;
+    direction: 'entry' | 'exit';
+    description?: string;
+}
+/** Context passed to renderLoop. */
+export interface LoopRenderContext {
+    target: string;
+    iteration: number;
+    description?: string;
+}
+/** Context passed to renderBreak. */
+export interface BreakRenderContext {
+    stageName: string;
+}
+/** Context passed to renderSelected. */
+export interface SelectedRenderContext {
+    selected: string[];
+    total: number;
+    /** Raw evidence from select() — available for custom rendering. */
+    evidence?: unknown;
+}
+/** Context passed to renderError. */
+export interface ErrorRenderContext {
+    stageName: string;
+    message: string;
+    validationIssues?: string;
+}
+/**
+ * Pluggable renderer for customizing narrative output.
+ *
+ * Each method is optional — unimplemented methods fall back to the default
+ * English renderer. Return null from renderOp to exclude an entry entirely.
+ *
+ * ```typescript
+ * const rec = narrative({
+ *   renderer: {
+ *     renderOp(ctx) {
+ *       if (ctx.key.startsWith('_internal')) return null; // filter out internal keys
+ *       return `${ctx.type === 'read' ? 'Read' : 'Wrote'} ${ctx.key}: ${ctx.valueSummary}`;
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface NarrativeRenderer {
+    renderStage?(ctx: StageRenderContext): string;
+    /** Return null to exclude the op from the narrative. */
+    renderOp?(ctx: OpRenderContext): string | null;
+    renderDecision?(ctx: DecisionRenderContext): string;
+    renderFork?(ctx: ForkRenderContext): string;
+    renderSelected?(ctx: SelectedRenderContext): string;
+    renderSubflow?(ctx: SubflowRenderContext): string;
+    renderLoop?(ctx: LoopRenderContext): string;
+    renderBreak?(ctx: BreakRenderContext): string;
+    renderError?(ctx: ErrorRenderContext): string;
+}

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

@@ -21,7 +21,7 @@
 /// <reference types="node" />
 import type { ScopeProtectionMode } from '../../scope/protection/types.js';
 import { FlowRecorderDispatcher } from '../narrative/FlowRecorderDispatcher.js';
-import type { FlowRecorder } from '../narrative/types.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';
 export interface TraverserOptions<TOut = any, TScope = any> {
     root: StageNode<TOut, TScope>;
@@ -45,11 +45,22 @@ export interface TraverserOptions<TOut = any, TScope = any> {
     signal?: AbortSignal;
     /** Pre-configured FlowRecorders to attach when narrative is enabled. */
     flowRecorders?: FlowRecorder[];
+    /**
+     * Pre-configured narrative generator. If provided, takes precedence over
+     * flowRecorders and narrativeEnabled. Used by the subflow traverser factory
+     * to share the parent's narrative generator with subflow traversers.
+     */
+    narrativeGenerator?: IControlFlowNarrative;
     /**
      * Maximum recursive executeNode depth. Defaults to FlowchartTraverser.MAX_EXECUTE_DEPTH (500).
      * Override in tests or unusually deep pipelines.
      */
     maxDepth?: number;
+    /**
+     * When this traverser runs inside a subflow, set this to the subflow's ID.
+     * Propagated to TraversalContext so narrative entries carry the correct subflowId.
+     */
+    parentSubflowId?: string;
 }
 export declare class FlowchartTraverser<TOut = any, TScope = any> {
     private readonly root;
@@ -58,6 +69,7 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     private subflows;
     private readonly logger;
     private readonly signal?;
+    private readonly parentSubflowId?;
     private readonly nodeResolver;
     private readonly childrenExecutor;
     private readonly subflowExecutor;
@@ -107,8 +119,14 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
      */
     static readonly MAX_EXECUTE_DEPTH = 500;
     constructor(opts: TraverserOptions<TOut, TScope>);
+    /**
+     * Create a factory that produces FlowchartTraverser instances for subflow execution.
+     * Captures parent config in closure — SubflowExecutor provides subflow-specific overrides.
+     * Each subflow gets a full traverser with all 7 phases (deciders, selectors, loops, etc.).
+     */
+    private createSubflowTraverserFactory;
     private createDeps;
-    execute(): Promise<TraversalResult>;
+    execute(branchPath?: string): Promise<TraversalResult>;
     getRuntimeStructure(): SerializedPipelineStructure | undefined;
     getSnapshot(): {
         sharedState: Record<string, unknown>;
@@ -117,12 +135,6 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
         subflowResults?: Record<string, unknown> | undefined;
         recorders?: {
             id: string;
-            /**
-             * Per-traverser set of lazy subflow IDs that have been resolved by THIS run.
-             * Used instead of writing `node.subflowResolver = undefined` back to the shared
-             * StageNode graph — avoids a race where a concurrent traverser clears the shared
-             * resolver before another traverser has finished using it.
-             */
             name: string;
             data: unknown;
         }[] | undefined;

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

@@ -41,6 +41,26 @@ export interface StreamHandlers {
 }
 export interface SubflowMountOptions<TParentScope = any, TSubflowInput = any, TSubflowOutput = any> {
     inputMapper?: (parentScope: TParentScope) => TSubflowInput;
+    /**
+     * Maps subflow output back into parent scope.
+     *
+     * **Array values are concatenated, not replaced.** `applyOutputMapping` uses
+     * `[...existing, ...value]` for arrays. Return only the **delta** (new items)
+     * for array keys, or the parent's existing array items will be duplicated.
+     * Scalar values are replaced normally.
+     *
+     * @example
+     * ```typescript
+     * // WRONG — returns full array, parent concats → duplicates
+     * outputMapper: (sf) => ({ messages: sf.allMessages })
+     *
+     * // RIGHT — returns only new items (delta), concat appends correctly
+     * outputMapper: (sf) => ({ messages: sf.newMessages })
+     *
+     * // Scalars are fine — replaced, not concatenated
+     * outputMapper: (sf) => ({ status: sf.result, count: sf.total })
+     * ```
+     */
     outputMapper?: (subflowOutput: TSubflowOutput, parentScope: TParentScope) => Record<string, unknown>;
 }
 export interface SubflowResult {
@@ -54,6 +74,37 @@ export interface SubflowResult {
     parentStageId: string;
     pipelineStructure?: unknown;
 }
+/**
+ * SubflowTraverserFactory — Creates a FlowchartTraverser for subflow execution.
+ *
+ * Injected into SubflowExecutor to break the circular dependency:
+ * FlowchartTraverser → SubflowExecutor → FlowchartTraverser.
+ *
+ * The factory captures parent traverser config (stageMap, scopeFactory, narrative, etc.)
+ * in a closure. SubflowExecutor calls it with subflow-specific overrides (root, runtime, input).
+ * The returned traverser uses the SAME 7-phase algorithm as the top-level traverser,
+ * so deciders, selectors, loops, lazy subflows, and abort signals all work inside subflows.
+ */
+export type SubflowTraverserFactory<TOut = any, TScope = any> = (options: {
+    /** Root node of the subflow (with isSubflowRoot stripped). */
+    root: StageNode<TOut, TScope>;
+    /** Isolated execution runtime for the subflow. */
+    executionRuntime: IExecutionRuntime;
+    /** Mapped input from parent scope (becomes readOnlyContext for stages). */
+    readOnlyContext?: unknown;
+    /** Subflow identifier — used as branchPath for narrative context. */
+    subflowId?: string;
+}) => SubflowTraverserHandle<TOut, TScope>;
+/**
+ * Handle returned by SubflowTraverserFactory.
+ * Provides execute() + access to nested subflow results.
+ */
+export interface SubflowTraverserHandle<TOut = any, TScope = any> {
+    /** Execute the subflow's graph using the full 7-phase traversal algorithm. */
+    execute(): Promise<TraversalResult>;
+    /** Collect nested subflow results (from subflows mounted inside this subflow). */
+    getSubflowResults(): Map<string, SubflowResult>;
+}
 /**
  * IExecutionRuntime — Interface for the runtime environment.
  *

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

@@ -31,10 +31,12 @@ export declare class StageContext {
     next?: StageContext;
     children?: StageContext[];
     debug: DiagnosticCollector;
-    /** Tracks user-level writes (pre-namespace) for the memory view. */
+    /** Tracks user-level writes (pre-namespace) for the memory view and onCommit. */
     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. */
+    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). */
     getSharedMemory(): SharedMemory;
@@ -45,18 +47,27 @@ export declare class StageContext {
     patch(path: string[], key: string, value: unknown, shouldRedact?: boolean): void;
     set(path: string[], key: string, value: unknown): void;
     merge(path: string[], key: string, value: unknown): void;
-    setObject(path: string[], key: string, value: unknown, shouldRedact?: boolean, description?: string): void;
-    updateObject(path: string[], key: string, value: unknown, description?: string): void;
+    setObject(path: string[], key: string, value: unknown, shouldRedact?: boolean, description?: string, operationOverride?: 'set' | 'delete'): void;
+    updateObject(path: string[], key: string, value: unknown, description?: string, shouldRedact?: boolean): void;
     setRoot(key: string, value: unknown): void;
     setGlobal(key: string, value: unknown, description?: string): void;
     updateGlobalContext(key: string, value: unknown): void;
     appendToArray(path: string[], key: string, items: unknown[], description?: string): void;
     mergeObject(path: string[], key: string, obj: Record<string, unknown>, description?: string): void;
     getValue(path: string[], key?: string, description?: string): any;
+    /** Read state without tracking in _stageReads or paying structuredClone cost.
+     *  Used by ScopeFacade.getValueSilent() for array proxy internal operations. */
+    getValueDirect(path: string[], key?: string): unknown;
     getRoot(key: string): any;
     getGlobal(key: string): any;
     getScope(): Record<string, unknown>;
     getRunId(): string;
+    /** Register an observer that fires after commit() applies patches.
+     *  Used by ScopeFacade to dispatch Recorder.onCommit events. */
+    setCommitObserver(observer: (mutations: Record<string, {
+        value: unknown;
+        operation: 'set' | 'update' | 'delete';
+    }>) => void): void;
     commit(): void;
     createNext(path: string, stageName: string, stageId: string, isDecider?: boolean): StageContext;
     createChild(runId: string, branchId: string, stageName: string, stageId: string, isDecider?: boolean): StageContext;

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

@@ -18,6 +18,8 @@ export interface ReactiveTarget {
     getStateKeys?(): string[];
     /** Check key existence without firing onRead. Used by has trap. */
     hasKey?(key: string): boolean;
+    /** Read state without firing onRead. Used by array proxy getCurrent(). */
+    getValueSilent?(key?: string): unknown;
     getArgs<T = Record<string, unknown>>(): T;
     getEnv(): Readonly<ExecutionEnv>;
     attachRecorder(recorder: Recorder): void;

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

@@ -0,0 +1,95 @@
+/**
+ * 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()`.
+ *
+ * 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.
+ *
+ * Domain libraries (e.g., agentfootprint) use this to bundle multiple recorders
+ * into a single preset — the consumer calls one function, gets full observability.
+ *
+ * @example
+ * ```typescript
+ * import { CompositeRecorder, MetricRecorder, DebugRecorder } from 'footprintjs';
+ *
+ * // Bundle metrics + debug into a single recorder
+ * const observability = new CompositeRecorder('observability', [
+ *   new MetricRecorder({ stageFilter: (name) => name === 'CallLLM' }),
+ *   new DebugRecorder({ verbosity: 'minimal' }),
+ * ]);
+ *
+ * executor.attachRecorder(observability);
+ *
+ * // Access child recorders by type
+ * const metrics = observability.get(MetricRecorder);
+ * metrics?.getMetrics(); // timing data
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Domain library preset (e.g., agentfootprint)
+ * export function agentObservability(options?: AgentObservabilityOptions) {
+ *   return new CompositeRecorder('agent-observability', [
+ *     new MetricRecorder(options?.stageFilter ? { stageFilter: options.stageFilter } : undefined),
+ *     new TokenRecorder(),
+ *     new ToolUsageRecorder(),
+ *   ]);
+ * }
+ *
+ * // Consumer
+ * executor.attachRecorder(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';
+/** Snapshot format for composite recorders — wraps child snapshots. */
+export interface CompositeSnapshot {
+    name: string;
+    data: {
+        children: Array<{
+            id: string;
+            name: string;
+            data: unknown;
+        }>;
+    };
+}
+export declare class CompositeRecorder implements Recorder, FlowRecorder {
+    readonly id: string;
+    private readonly children;
+    constructor(id: string, children: Array<Recorder | FlowRecorder>);
+    /**
+     * Get a child recorder by class type.
+     *
+     * @example
+     * ```typescript
+     * const metrics = composite.get(MetricRecorder);
+     * ```
+     */
+    get<T>(type: new (...args: any[]) => T): T | undefined;
+    /** Get all child recorders. */
+    getChildren(): ReadonlyArray<Recorder | FlowRecorder>;
+    onRead(event: ReadEvent): void;
+    onWrite(event: WriteEvent): void;
+    onCommit(event: CommitEvent): void;
+    onError(event: ErrorEvent | FlowErrorEvent): void;
+    onStageStart(event: StageEvent): void;
+    onStageEnd(event: StageEvent): void;
+    onStageExecuted(event: FlowStageEvent): void;
+    onNext(event: FlowNextEvent): void;
+    onDecision(event: FlowDecisionEvent): void;
+    onFork(event: FlowForkEvent): void;
+    onSelected(event: FlowSelectedEvent): void;
+    onSubflowEntry(event: FlowSubflowEvent): void;
+    onSubflowExit(event: FlowSubflowEvent): void;
+    onSubflowRegistered(event: FlowSubflowRegisteredEvent): void;
+    onLoop(event: FlowLoopEvent): void;
+    onBreak(event: FlowBreakEvent): void;
+    clear(): void;
+    /**
+     * Snapshot merges all child snapshots into a single composite entry.
+     * Each child's snapshot is preserved with its own id/name/data.
+     */
+    toSnapshot(): CompositeSnapshot;
+}

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

@@ -0,0 +1,2 @@
+export type { CompositeSnapshot } from './CompositeRecorder.js';
+export { CompositeRecorder } from './CompositeRecorder.js';

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

@@ -16,6 +16,7 @@
  *
  *   const result = await executor.run({ input: data, env: { traceId: 'req-123' } });
  */
+import type { CombinedNarrativeRecorderOptions } from '../engine/narrative/CombinedNarrativeRecorder.js';
 import type { CombinedNarrativeEntry } from '../engine/narrative/narrativeTypes.js';
 import type { ManifestEntry } from '../engine/narrative/recorders/ManifestFlowRecorder.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
@@ -80,6 +81,7 @@ export interface FlowChartExecutorOptions<TScope = any> {
 export declare class FlowChartExecutor<TOut = any, TScope = any> {
     private traverser;
     private narrativeEnabled;
+    private narrativeOptions?;
     private combinedRecorder;
     private flowRecorders;
     private scopeRecorders;
@@ -105,7 +107,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      */
     constructor(flowChart: FlowChart<TOut, TScope>, factoryOrOptions?: ScopeFactory<TScope> | FlowChartExecutorOptions<TScope>);
     private createTraverser;
-    enableNarrative(): void;
+    enableNarrative(options?: CombinedNarrativeRecorderOptions): void;
     /**
      * Set a declarative redaction policy that applies to all stages.
      * Must be called before run().
@@ -120,6 +122,28 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * Attach a scope Recorder to observe data operations (reads, writes, commits).
      * Automatically attached to every ScopeFacade created during traversal.
      * Must be called before run().
+     *
+     * **Idempotent by ID:** If a recorder with the same `id` is already attached,
+     * it is replaced (not duplicated). This prevents double-counting when both
+     * a framework and the user attach the same recorder type.
+     *
+     * Built-in recorders use auto-increment IDs (`metrics-1`, `debug-1`, ...) by
+     * default, so multiple instances with different configs coexist. To override
+     * a framework-attached recorder, pass the same well-known ID.
+     *
+     * @example
+     * ```typescript
+     * // Multiple recorders with different configs — each gets a unique ID
+     * executor.attachRecorder(new MetricRecorder());
+     * executor.attachRecorder(new DebugRecorder({ verbosity: 'minimal' }));
+     *
+     * // Override a framework-attached recorder by passing its well-known ID
+     * executor.attachRecorder(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
+     * ```
      */
     attachRecorder(recorder: Recorder): void;
     /** Detach all scope Recorders with the given ID. */
@@ -130,6 +154,8 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * Attach a FlowRecorder to observe control flow events.
      * Automatically enables narrative if not already enabled.
      * Must be called before run() — recorders are passed to the traverser at creation time.
+     *
+     * **Idempotent by ID:** replaces existing recorder with same `id`.
      */
     attachFlowRecorder(recorder: FlowRecorder): void;
     /** Detach all FlowRecorders with the given ID. */

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

@@ -63,6 +63,9 @@ export declare class ScopeFacade {
     notifyStageEnd(duration?: number): void;
     /** @internal */
     notifyCommit(mutations: CommitEvent['mutations']): void;
+    /** Called by StageContext.commit() observer. Converts tracked writes to CommitEvent format.
+     *  Errors are caught to prevent recorder issues from aborting the traversal. */
+    private _onCommitFired;
     addDebugInfo(key: string, value: unknown): void;
     addDebugMessage(value: unknown): void;
     addErrorInfo(key: string, value: unknown): void;
@@ -74,6 +77,14 @@ export declare class ScopeFacade {
      *  Contract: returns false for keys never set OR keys set to undefined.
      *  This matches deleteValue() semantics (sets to undefined = deleted). */
     hasKey(key: string): boolean;
+    /** Read state without firing onRead. Used by array proxy getCurrent() to avoid
+     *  phantom reads on internal array operations (.length, .has, iteration, etc.).
+     *  The initial property access fires one tracked onRead via getValue(); subsequent
+     *  internal array operations use this method to stay silent.
+     *  NOTE: Like getValue(), returns the raw value to the caller. Redaction applies
+     *  only to recorder dispatch — it does not filter the returned value. This matches
+     *  the existing getValue() contract where user code always receives raw data. */
+    getValueSilent(key?: string): unknown;
     getInitialValueFor(key: string): any;
     getValue(key?: string): any;
     setValue(key: string, value: unknown, shouldRedact?: boolean, description?: string): void;

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

@@ -16,7 +16,23 @@ export interface DebugRecorderOptions {
     id?: string;
     verbosity?: DebugVerbosity;
 }
+/**
+ * Each instance gets a unique auto-increment ID (`debug-1`, `debug-2`, ...),
+ * so multiple recorders with different verbosity coexist.
+ *
+ * @example
+ * ```typescript
+ * // Verbose debug for development
+ * executor.attachRecorder(new DebugRecorder({ verbosity: 'verbose' }));
+ *
+ * // Minimal debug for production (errors only)
+ * executor.attachRecorder(new DebugRecorder({ verbosity: 'minimal' }));
+ *
+ * // Both coexist — different auto IDs
+ * ```
+ */
 export declare class DebugRecorder implements Recorder {
+    private static _counter;
     readonly id: string;
     private entries;
     private verbosity;