footprintjs 0.1.0

package/dist/esm/types/lib/engine/handlers/SelectorHandler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SelectorHandler — Multi-choice filtered fan-out.
+ *
+ * Responsibilities:
+ * - Execute scope-based selector nodes (stage → commit → resolve children → parallel execution)
+ * - The selector function IS a stage: reads scope, returns string[] of branch IDs
+ * - Delegates parallel execution of selected children to ChildrenExecutor
+ */
+import type { StageContext } from '../../memory/StageContext';
+import type { StageNode } from '../graph/StageNode';
+import type { HandlerDeps, NodeResultType, StageFunction } from '../types';
+import type { ChildrenExecutor } from './ChildrenExecutor';
+import type { CallExtractorFn, ExecuteNodeFn, GetStagePathFn, RunStageFn } from './DeciderHandler';
+export declare class SelectorHandler<TOut = any, TScope = any> {
+    private readonly deps;
+    private readonly childrenExecutor;
+    constructor(deps: HandlerDeps<TOut, TScope>, childrenExecutor: ChildrenExecutor<TOut, TScope>);
+    /**
+     * Handle a scope-based selector node (created via addSelectorFunction).
+     * The stage function IS the selector — its return value contains branch IDs.
+     * Execution order: runStage(fn) → commit → resolve children → parallel execute.
+     */
+    handleScopeBased(node: StageNode<TOut, TScope>, stageFunc: StageFunction<TOut, TScope>, context: StageContext, breakFlag: {
+        shouldBreak: boolean;
+    }, branchPath: string | undefined, runStage: RunStageFn<TOut, TScope>, executeNode: ExecuteNodeFn<TOut, TScope>, callExtractor: CallExtractorFn<TOut, TScope>, getStagePath: GetStagePathFn<TOut, TScope>): Promise<Record<string, NodeResultType>>;
+}

package/dist/esm/types/lib/engine/handlers/StageRunner.d.ts

@@ -0,0 +1,17 @@
+/**
+ * StageRunner — Executes individual stage functions.
+ *
+ * Responsibilities:
+ * - Create scope via ScopeFactory for each stage
+ * - Apply scope protection (createProtectedScope) to intercept direct assignments
+ * - Handle streaming stages (onStart, onToken, onEnd lifecycle)
+ * - Sync+async safety: only await real Promises (instanceof check)
+ */
+import type { StageContext } from '../../memory/StageContext';
+import type { StageNode } from '../graph/StageNode';
+import type { HandlerDeps, StageFunction } from '../types';
+export declare class StageRunner<TOut = any, TScope = any> {
+    private readonly deps;
+    constructor(deps: HandlerDeps<TOut, TScope>);
+    run(node: StageNode<TOut, TScope>, stageFunc: StageFunction<TOut, TScope>, context: StageContext, breakFn: () => void): Promise<TOut>;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * SubflowExecutor — Isolated recursive execution with I/O mapping.
+ *
+ * Responsibilities:
+ * - Execute subflows with isolated ExecutionRuntime contexts
+ * - Apply input/output mapping via SubflowInputMapper
+ * - Handle nested subflow detection and delegation
+ * - 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.
+ */
+import type { StageContext } from '../../memory/StageContext';
+import type { StageNode } from '../graph/StageNode';
+import type { HandlerDeps, StageFunction, SubflowResult } from '../types';
+import type { NodeResolver } from './NodeResolver';
+/** Callback for running a stage function. Avoids circular dep with traverser. */
+export type ExecuteStageFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, stageFunc: StageFunction<TOut, TScope>, context: StageContext, breakFn: () => void) => Promise<TOut>;
+/** Callback for calling the traversal extractor. */
+export type CallExtractorFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, context: StageContext, stagePath: string, stageOutput?: unknown, errorInfo?: {
+    type: string;
+    message: string;
+}) => void;
+/** 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;
+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: ExecuteStageFn<TOut, TScope>, callExtractor: CallExtractorFn<TOut, TScope>, getStageFn: GetStageFnFn<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
+     * 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>): Promise<any>;
+    /**
+     * Internal execution within subflow context.
+     * Mirrors the traverser's executeNode but within the subflow's isolated runtime.
+     */
+    private executeSubflowInternal;
+    private getStagePath;
+    private executeNodeChildrenInternal;
+    private executeSelectedChildrenInternal;
+}

package/dist/esm/types/lib/engine/handlers/SubflowInputMapper.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SubflowInputMapper — Pure functions for subflow data contracts.
+ *
+ * Mental model: Subflow = Pure Function
+ * - Isolated scope (own GlobalStore)
+ * - Explicit inputs via inputMapper
+ * - Explicit outputs via outputMapper
+ *
+ * | Scenario        | Behavior                                  |
+ * |-----------------|-------------------------------------------|
+ * | No inputMapper  | Subflow starts with empty scope           |
+ * | No outputMapper | Subflow scope changes discarded           |
+ * | Both present    | Full data contract (args in, results out) |
+ * | Neither present | Complete isolation (side effects only)    |
+ */
+import type { StageContext } from '../../memory/StageContext';
+import type { HandlerDeps, IExecutionRuntime, SubflowMountOptions } from '../types';
+/** Extract values from parent scope using inputMapper. */
+export declare function extractParentScopeValues<TParentScope, TSubflowInput>(parentScope: TParentScope, options?: SubflowMountOptions<TParentScope, TSubflowInput>): TSubflowInput | Record<string, unknown>;
+/**
+ * Get the initial scope values for a subflow.
+ * Always isolated — only inputMapper values are included.
+ */
+export declare function getInitialScopeValues<TParentScope, TSubflowInput>(parentScope: TParentScope, options?: SubflowMountOptions<TParentScope, TSubflowInput>): Record<string, unknown>;
+/**
+ * Create a new HandlerDeps for subflow execution.
+ * Key: sets readOnlyContext to mapped input so StageRunner passes it to ScopeFactory.
+ */
+export declare function createSubflowHandlerDeps<TOut = any, TScope = any>(parentDeps: HandlerDeps<TOut, TScope>, subflowRuntime: IExecutionRuntime, mappedInput: Record<string, unknown>): HandlerDeps<TOut, TScope>;
+/**
+ * Seed the subflow's GlobalStore with initial values.
+ * Called before subflow execution to make inputMapper values available.
+ */
+export declare function seedSubflowGlobalStore(subflowRuntime: IExecutionRuntime, initialValues: Record<string, unknown>): void;
+/**
+ * Apply output mapping after subflow completion.
+ * Writes mapped values back to parent scope using merge semantics:
+ * arrays are appended, objects are shallow-merged, scalars are replaced.
+ */
+export declare function applyOutputMapping<TParentScope, TSubflowOutput>(subflowOutput: TSubflowOutput, parentScope: TParentScope, parentContext: StageContext, options?: SubflowMountOptions<TParentScope, any, TSubflowOutput>): Record<string, unknown> | undefined;

package/dist/esm/types/lib/engine/handlers/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Barrel export for all engine handler modules.
+ */
+export { StageRunner } from './StageRunner';
+export { NodeResolver } from './NodeResolver';
+export type { ExecuteNodeFn } from './ChildrenExecutor';
+export { ChildrenExecutor } from './ChildrenExecutor';
+export type { CallExtractorFn, GetStagePathFn, RunStageFn } from './DeciderHandler';
+export { DeciderHandler } from './DeciderHandler';
+export { SelectorHandler } from './SelectorHandler';
+export { ContinuationResolver, DEFAULT_MAX_ITERATIONS } from './ContinuationResolver';
+export { SubflowExecutor } from './SubflowExecutor';
+export { applyOutputMapping, createSubflowHandlerDeps, extractParentScopeValues, getInitialScopeValues, seedSubflowGlobalStore, } from './SubflowInputMapper';
+export { ExtractorRunner } from './ExtractorRunner';
+export { computeNodeType, RuntimeStructureManager } from './RuntimeStructureManager';

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

@@ -0,0 +1,16 @@
+/**
+ * engine/ — Graph traversal engine library.
+ *
+ * Executes flowcharts built by FlowChartBuilder via pre-order DFS traversal.
+ * Handles linear, fork, decider, selector, loop, and subflow node shapes.
+ */
+export type { TraverserOptions } from './traversal/FlowchartTraverser';
+export { FlowchartTraverser } from './traversal/FlowchartTraverser';
+export { isStageNodeReturn } from './graph/StageNode';
+export * from './types';
+export * from './handlers';
+export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './narrative/CombinedNarrativeBuilder';
+export { CombinedNarrativeBuilder } from './narrative/CombinedNarrativeBuilder';
+export { ControlFlowNarrativeGenerator } from './narrative/ControlFlowNarrativeGenerator';
+export { NullControlFlowNarrativeGenerator } from './narrative/NullControlFlowNarrativeGenerator';
+export type { IControlFlowNarrative } from './narrative/types';

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

@@ -0,0 +1,33 @@
+/**
+ * CombinedNarrativeBuilder — Merges flow-level narrative with data-level operations.
+ *
+ * ControlFlowNarrativeGenerator captures FLOW — what stages ran, which branches were taken.
+ * NarrativeRecorder (scope/) captures DATA — what values were read, written, updated.
+ *
+ * This builder weaves both into a single unified narrative:
+ *   Stage 1: "Receive Application"
+ *     Step 1: Write applicantName = 'Bob'
+ *   [Condition]: risk tier is high → chose "Reject Application"
+ */
+import type { NarrativeRecorder } from '../../scope/recorders/NarrativeRecorder';
+export interface CombinedNarrativeEntry {
+    type: 'stage' | 'step' | 'condition' | 'fork' | 'subflow' | 'loop' | 'break' | 'error';
+    text: string;
+    depth: number;
+    stageName?: string;
+    stepNumber?: number;
+}
+export interface CombinedNarrativeOptions {
+    includeStepNumbers?: boolean;
+    includeValues?: boolean;
+    indent?: string;
+}
+export declare class CombinedNarrativeBuilder {
+    private options;
+    constructor(options?: CombinedNarrativeOptions);
+    buildEntries(flowSentences: string[], recorder: NarrativeRecorder): CombinedNarrativeEntry[];
+    build(flowSentences: string[], recorder: NarrativeRecorder): string[];
+    private addStepEntries;
+    private findStageData;
+    private parseSentence;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * ControlFlowNarrativeGenerator — Active implementation of IControlFlowNarrative.
+ *
+ * Converts traversal events into plain-English sentences at traversal time.
+ * Produces a human-readable story as a first-class output, enabling any consumer
+ * (cheaper LLM, follow-up agent, logging system) to understand what happened
+ * without parsing technical structures.
+ *
+ * This is the FLOW narrative — it captures control flow decisions.
+ * The DATA narrative comes from scope/recorders/NarrativeRecorder.
+ * CombinedNarrativeBuilder merges both into one story.
+ */
+import type { IControlFlowNarrative } from './types';
+export declare class ControlFlowNarrativeGenerator implements IControlFlowNarrative {
+    private sentences;
+    private isFirstStage;
+    onStageExecuted(stageName: string, displayName?: string, description?: string): void;
+    onNext(fromStage: string, toStage: string, toDisplayName?: string, description?: string): void;
+    onDecision(deciderName: string, chosenBranch: string, chosenDisplayName?: string, rationale?: string, deciderDescription?: string): void;
+    onFork(parentStage: string, childNames: string[]): void;
+    onSelected(parentStage: string, selectedNames: string[], totalCount: number): void;
+    onSubflowEntry(subflowName: string): void;
+    onSubflowExit(subflowName: string): void;
+    onLoop(targetStage: string, targetDisplayName: string | undefined, iteration: number, description?: string): void;
+    onBreak(stageName: string, displayName?: string): void;
+    onError(stageName: string, errorMessage: string, displayName?: string): void;
+    /** Returns a defensive copy of accumulated sentences. */
+    getSentences(): string[];
+}

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

@@ -0,0 +1,21 @@
+/**
+ * NullControlFlowNarrativeGenerator — Zero-cost no-op (Null Object pattern).
+ *
+ * When narrative is disabled, handlers call this unconditionally.
+ * All methods are empty bodies — zero allocation, zero string formatting.
+ * getSentences() returns a bare [] literal to avoid even a single array allocation.
+ */
+import type { IControlFlowNarrative } from './types';
+export declare class NullControlFlowNarrativeGenerator implements IControlFlowNarrative {
+    onStageExecuted(): void;
+    onNext(): void;
+    onDecision(): void;
+    onFork(): void;
+    onSelected(): void;
+    onSubflowEntry(): void;
+    onSubflowExit(): void;
+    onLoop(): void;
+    onBreak(): void;
+    onError(): void;
+    getSentences(): string[];
+}

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

@@ -0,0 +1,5 @@
+export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './CombinedNarrativeBuilder';
+export { CombinedNarrativeBuilder } from './CombinedNarrativeBuilder';
+export { ControlFlowNarrativeGenerator } from './ControlFlowNarrativeGenerator';
+export { NullControlFlowNarrativeGenerator } from './NullControlFlowNarrativeGenerator';
+export type { IControlFlowNarrative } from './types';

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

@@ -0,0 +1,33 @@
+/**
+ * IControlFlowNarrative — Interface for control flow narrative generation.
+ *
+ * Captures FLOW events during traversal: decisions, forks, loops, subflows.
+ * Complementary to scope/recorders/NarrativeRecorder which captures DATA events.
+ *
+ * Uses Null Object pattern: NullControlFlowNarrativeGenerator satisfies this
+ * interface with empty methods for zero-cost disabled path.
+ */
+export interface IControlFlowNarrative {
+    /** Called when a stage executes. First stage uses distinct opening pattern. */
+    onStageExecuted(stageName: string, displayName?: string, description?: string): void;
+    /** Called on linear continuation from one stage to the next. */
+    onNext(fromStage: string, toStage: string, toDisplayName?: string, description?: string): void;
+    /** Called when a decider selects a branch. Most valuable for LLM context. */
+    onDecision(deciderName: string, chosenBranch: string, chosenDisplayName?: string, rationale?: string, deciderDescription?: string): void;
+    /** Called when a fork executes all children in parallel. */
+    onFork(parentStage: string, childNames: string[]): void;
+    /** Called when a selector picks a subset of children. */
+    onSelected(parentStage: string, selectedNames: string[], totalCount: number): void;
+    /** Called when entering a subflow (nested context boundary). */
+    onSubflowEntry(subflowName: string): void;
+    /** Called when exiting a subflow. */
+    onSubflowExit(subflowName: string): void;
+    /** Called on loop iteration (back-edge traversal). */
+    onLoop(targetStage: string, targetDisplayName: string | undefined, iteration: number, description?: string): void;
+    /** Called when a stage triggers break (early termination). */
+    onBreak(stageName: string, displayName?: string): void;
+    /** Called when a stage throws an error. */
+    onError(stageName: string, errorMessage: string, displayName?: string): void;
+    /** Returns accumulated narrative sentences in execution order. */
+    getSentences(): string[];
+}

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

@@ -0,0 +1,87 @@
+/**
+ * FlowchartTraverser — Pre-order DFS traversal of StageNode graph.
+ *
+ * Unified traversal algorithm for all node shapes:
+ *   const pre = await prep();
+ *   const [x, y] = await Promise.all([fx(pre), fy(pre)]);
+ *   return await next(x, y);
+ *
+ * For each node, executeNode follows 7 phases:
+ *   0. CLASSIFY  — subflow detection, early delegation
+ *   1. VALIDATE  — node invariants, role markers
+ *   2. EXECUTE   — run stage fn, commit, break check
+ *   3. DYNAMIC   — StageNode return detection, subflow auto-registration, structure updates
+ *   4. CHILDREN  — fork/selector/decider dispatch
+ *   5. CONTINUE  — dynamic next / linear next resolution
+ *   6. LEAF      — no continuation, return output
+ *
+ * Break semantics: If a stage calls breakFn(), commit and STOP.
+ * Patch model: Stage writes into local patch; commitPatch() after return or throw.
+ */
+/// <reference types="node" />
+import type { ScopeProtectionMode } from '../../scope/protection/types';
+import type { ExtractorError, IExecutionRuntime, ILogger, ScopeFactory, SerializedPipelineStructure, StageFunction, StageNode, StreamHandlers, SubflowResult, TraversalExtractor, TraversalResult } from '../types';
+export interface TraverserOptions<TOut = any, TScope = any> {
+    root: StageNode<TOut, TScope>;
+    stageMap: Map<string, StageFunction<TOut, TScope>>;
+    scopeFactory: ScopeFactory<TScope>;
+    executionRuntime: IExecutionRuntime;
+    readOnlyContext?: unknown;
+    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;
+    signal?: AbortSignal;
+}
+export declare class FlowchartTraverser<TOut = any, TScope = any> {
+    private readonly root;
+    private stageMap;
+    private readonly executionRuntime;
+    private subflows?;
+    private readonly logger;
+    private readonly signal?;
+    private readonly nodeResolver;
+    private readonly childrenExecutor;
+    private readonly subflowExecutor;
+    private readonly stageRunner;
+    private readonly continuationResolver;
+    private readonly deciderHandler;
+    private readonly selectorHandler;
+    private readonly structureManager;
+    private readonly extractorRunner;
+    private readonly narrativeGenerator;
+    private subflowResults;
+    constructor(opts: TraverserOptions<TOut, TScope>);
+    private createDeps;
+    execute(): Promise<TraversalResult>;
+    getRuntimeStructure(): SerializedPipelineStructure | undefined;
+    getSnapshot(): {
+        sharedState: Record<string, unknown>;
+        executionTree: unknown;
+        commitLog: unknown[];
+    };
+    getRuntime(): IExecutionRuntime;
+    setRootObject(path: string[], key: string, value: unknown): void;
+    getBranchIds(): string[];
+    getRuntimeRoot(): StageNode;
+    getSubflowResults(): Map<string, SubflowResult>;
+    getExtractedResults<TResult = unknown>(): Map<string, TResult>;
+    getExtractorErrors(): ExtractorError[];
+    getNarrative(): string[];
+    private getStageFn;
+    private executeStage;
+    /**
+     * Pre-order DFS traversal — the core algorithm.
+     * Each call processes one node through all 7 phases.
+     */
+    private executeNode;
+    private captureDynamicChildrenResult;
+    private autoRegisterSubflowDef;
+}

package/dist/esm/types/lib/engine/traversal/index.d.ts

@@ -0,0 +1,2 @@
+export type { TraverserOptions } from './FlowchartTraverser';
+export { FlowchartTraverser } from './FlowchartTraverser';

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

@@ -0,0 +1,208 @@
+/**
+ * types.ts — All type definitions for the engine library.
+ *
+ * Centralizes type definitions to avoid circular dependencies.
+ * Every handler receives HandlerDeps (the DI bag) instead of importing the traverser.
+ */
+/// <reference types="node" />
+import type { StageContext } from '../memory/StageContext';
+import type { ScopeProtectionMode } from '../scope/protection/types';
+import type { StageNode } from './graph/StageNode';
+import type { IControlFlowNarrative } from './narrative/types';
+export type { Decider, Selector, StageNode } from './graph/StageNode';
+/** Minimal logging contract. Mirrors Console API subset. */
+export interface ILogger {
+    info(message?: any, ...optionalParams: any[]): void;
+    log(message?: any, ...optionalParams: any[]): void;
+    debug(message?: any, ...optionalParams: any[]): void;
+    error(message?: any, ...optionalParams: any[]): void;
+    warn(message?: any, ...optionalParams: any[]): void;
+}
+/** Default console-based logger. */
+export declare const defaultLogger: ILogger;
+/** Callback that receives tokens during streaming. */
+export type StreamCallback = (token: string) => void;
+/**
+ * The function signature for stage handlers.
+ * - TOut: return type produced by the stage
+ * - TScope: the scope object passed to the stage
+ * - Optional 3rd parameter `streamCallback` injected for streaming stages.
+ */
+export type StageFunction<TOut = any, TScope = any> = (scope: TScope, breakPipeline: () => void, streamCallback?: StreamCallback) => Promise<TOut> | TOut;
+/** Factory that creates a scope instance for each stage. */
+export type ScopeFactory<TScope = any> = (context: StageContext, stageName: string, readOnlyContext?: unknown) => TScope;
+export type StreamTokenHandler = (streamId: string, token: string) => void;
+export type StreamLifecycleHandler = (streamId: string, fullText?: string) => void;
+export interface StreamHandlers {
+    onToken?: StreamTokenHandler;
+    onStart?: StreamLifecycleHandler;
+    onEnd?: StreamLifecycleHandler;
+}
+export interface SubflowMountOptions<TParentScope = any, TSubflowInput = any, TSubflowOutput = any> {
+    inputMapper?: (parentScope: TParentScope) => TSubflowInput;
+    outputMapper?: (subflowOutput: TSubflowOutput, parentScope: TParentScope) => Record<string, unknown>;
+}
+export interface SubflowResult {
+    subflowId: string;
+    subflowName: string;
+    treeContext: {
+        globalContext: Record<string, unknown>;
+        stageContexts: Record<string, unknown>;
+        history: unknown[];
+    };
+    parentStageId: string;
+    pipelineStructure?: unknown;
+}
+/**
+ * IExecutionRuntime — Interface for the runtime environment.
+ *
+ * Defines the contract that engine handlers need from the runner layer,
+ * avoiding circular imports between engine/ and runner/.
+ */
+export interface IExecutionRuntime {
+    globalStore: {
+        getState(): Record<string, unknown>;
+    };
+    rootStageContext: StageContext;
+    executionHistory: {
+        list(): unknown[];
+    };
+    getSnapshot(): {
+        sharedState: Record<string, unknown>;
+        executionTree: unknown;
+        commitLog: unknown[];
+    };
+    setRootObject(path: string[], key: string, value: unknown): void;
+    getPipelines(): string[];
+}
+/**
+ * HandlerDeps — Dependency injection bag passed to all handler modules.
+ *
+ * Provides shared state (stageMap, runtime, scopeFactory, etc.) without
+ * handlers needing to import the traverser directly. Avoids circular deps.
+ */
+export interface HandlerDeps<TOut = any, TScope = any> {
+    stageMap: Map<string, StageFunction<TOut, TScope>>;
+    root: StageNode<TOut, TScope>;
+    executionRuntime: IExecutionRuntime;
+    ScopeFactory: ScopeFactory<TScope>;
+    subflows?: Record<string, {
+        root: StageNode<TOut, TScope>;
+    }>;
+    throttlingErrorChecker?: (error: unknown) => boolean;
+    streamHandlers?: StreamHandlers;
+    scopeProtectionMode: ScopeProtectionMode;
+    readOnlyContext?: unknown;
+    narrativeGenerator: IControlFlowNarrative;
+    logger: ILogger;
+    signal?: AbortSignal;
+}
+/** Options for FlowChartExecutor.run(). */
+export interface RunOptions {
+    /** AbortSignal for cooperative cancellation. */
+    signal?: AbortSignal;
+    /** Timeout in milliseconds. Creates an internal AbortController. */
+    timeoutMs?: number;
+}
+export type FlowControlType = 'next' | 'branch' | 'children' | 'selected' | 'subflow' | 'loop';
+export interface FlowMessage {
+    type: FlowControlType;
+    description: string;
+    targetStage?: string | string[];
+    rationale?: string;
+    count?: number;
+    iteration?: number;
+    timestamp?: number;
+}
+export interface RuntimeStructureMetadata {
+    type: 'stage' | 'decider' | 'fork' | 'streaming';
+    subflowId?: string;
+    isSubflowRoot?: boolean;
+    subflowName?: string;
+    isParallelChild?: boolean;
+    parallelGroupId?: string;
+    loopTarget?: string;
+    isDynamic?: boolean;
+    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;
+    isError?: boolean;
+};
+export type BranchResult = {
+    result: string | Error;
+    isError: boolean;
+};
+export type BranchResults = {
+    [branchId: string]: BranchResult;
+};
+export type TraversalResult = BranchResults | string | Error;
+export interface SerializedPipelineNode {
+    name: string;
+    id?: string;
+    type?: 'stage' | 'decider' | 'fork' | 'streaming' | 'loop' | 'user' | 'tool' | 'function' | 'sequence';
+    displayName?: string;
+    description?: string;
+    children?: SerializedPipelineNode[];
+    next?: SerializedPipelineNode;
+    branches?: Record<string, SerializedPipelineNode>;
+    hasDecider?: boolean;
+    hasSelector?: boolean;
+    hasSubtree?: boolean;
+    isStreaming?: boolean;
+    streamId?: string;
+    isSubflowRoot?: boolean;
+    subflowId?: string;
+    subflowName?: string;
+    loopTarget?: string;
+    isLoopReference?: boolean;
+    isParallelChild?: boolean;
+    parallelGroupId?: string;
+    isDynamic?: boolean;
+}
+export type FlowChart<TOut = any, TScope = any> = {
+    root: StageNode<TOut, TScope>;
+    stageMap: Map<string, StageFunction<TOut, TScope>>;
+    extractor?: TraversalExtractor;
+    subflows?: Record<string, {
+        root: StageNode<TOut, TScope>;
+    }>;
+    enrichSnapshots?: boolean;
+    enableNarrative?: boolean;
+    logger?: ILogger;
+    buildTimeStructure?: SerializedPipelineStructure;
+};
+/** Alias for SerializedPipelineNode used as full structure */
+export type SerializedPipelineStructure = SerializedPipelineNode & {
+    branchIds?: string[];
+    subflowStructure?: SerializedPipelineStructure;
+    iterationCount?: number;
+};

package/dist/esm/types/lib/memory/DiagnosticCollector.d.ts

@@ -0,0 +1,33 @@
+/**
+ * DiagnosticCollector — Per-stage metadata collector
+ *
+ * Collects non-execution metadata during a stage's run:
+ * - logs, errors, metrics, evals, flowMessages
+ *
+ * Like a compiler's diagnostic collector — gathers warnings, errors,
+ * and timing info without affecting the compilation output.
+ */
+import type { FlowMessage } from './types';
+export declare class DiagnosticCollector {
+    logContext: {
+        [key: string]: any;
+    };
+    errorContext: {
+        [key: string]: any;
+    };
+    metricContext: {
+        [key: string]: any;
+    };
+    evalContext: {
+        [key: string]: any;
+    };
+    flowMessages: FlowMessage[];
+    addLog(key: string, value: any, path?: string[]): void;
+    setLog(key: string, value: any, path?: string[]): void;
+    addError(key: string, value: any, path?: string[]): void;
+    addMetric(key: string, value: any, path?: string[]): void;
+    setMetric(key: string, value: any, path?: string[]): void;
+    addEval(key: string, value: any, path?: string[]): void;
+    setEval(key: string, value: any, path?: string[]): void;
+    addFlowMessage(flowMessage: FlowMessage): void;
+}

package/dist/esm/types/lib/memory/EventLog.d.ts

@@ -0,0 +1,27 @@
+/**
+ * EventLog — Time-travel snapshot storage for flowchart execution
+ *
+ * Like git history: stores commit bundles (diffs), not full snapshots.
+ * materialise(stepIdx) reconstructs state at any point by replaying commits.
+ */
+import type { CommitBundle } from './types';
+export declare class EventLog {
+    /** Base snapshot BEFORE the first stage mutates anything. */
+    private base;
+    /** Ordered list of commit bundles. */
+    private steps;
+    constructor(initialMemory: any);
+    /**
+     * Reconstructs the full state at any given step.
+     * Replays commits from the beginning — O(n) but low memory footprint.
+     */
+    materialise(stepIdx?: number): any;
+    /** Persists a commit bundle for a finished stage. */
+    record(bundle: CommitBundle): void;
+    /** Gets all recorded commit bundles. */
+    list(): CommitBundle[];
+    /** Number of recorded commits. */
+    get length(): number;
+    /** Wipes history (useful for test resets). */
+    clear(): void;
+}