footprintjs 8.2.0 → 9.0.0

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

@@ -8,6 +8,15 @@
  * - String ID → reference to existing node (resolve via NodeResolver)
  * - StageNode with fn → truly dynamic node (execute directly)
  * - StageNode without fn → reference by ID (resolve via NodeResolver)
+ *
+ * Two entry points:
+ * - `resolveTarget` — resolves the continuation to `{ node, context }` and
+ *   fires every side effect (iteration counting, debug logs, `onLoop`
+ *   narrative) WITHOUT executing. The traverser's trampoline driver uses
+ *   this to follow loop edges iteratively — flat stack, so the iteration
+ *   limit (not call-stack depth) is what bounds a loop.
+ * - `resolve` — resolveTarget + immediate execution via the provided
+ *   `executeNode` callback. Kept for direct/advanced callers.
  */
 import type { StageContext } from '../../memory/StageContext.js';
 import type { StageNode } from '../graph/StageNode.js';
@@ -16,6 +25,16 @@ import type { HandlerDeps } from '../types.js';
 import type { NodeResolver } from './NodeResolver.js';
 import type { ExecuteNodeFn } from './types.js';
 export declare const DEFAULT_MAX_ITERATIONS = 1000;
+/**
+ * A resolved continuation target — the node to execute next plus the
+ * StageContext to execute it in. All side effects (iteration counting,
+ * debug logs, `onLoop` narrative) have already fired by the time this
+ * is returned.
+ */
+export interface ResolvedContinuation<TOut = any, TScope = any> {
+    node: StageNode<TOut, TScope>;
+    context: StageContext;
+}
 export declare class ContinuationResolver<TOut = any, TScope = any> {
     private readonly deps;
     private readonly nodeResolver;
@@ -28,19 +47,27 @@ export declare class ContinuationResolver<TOut = any, TScope = any> {
     private readonly maxIterations;
     constructor(deps: HandlerDeps<TOut, TScope>, nodeResolver: NodeResolver<TOut, TScope>, onIterationUpdate?: (nodeId: string, count: number) => void, maxIterations?: number);
     /**
-     * Resolve a dynamic continuation.
-     * Dispatches to handleStringReference, handleDirectNode, or handleNodeReference
-     * based on the dynamicNext type.
+     * Resolve a dynamic continuation and execute it immediately.
+     * Equivalent to `executeNode(...resolveTarget(...))` — the traverser's
+     * driver loop calls `resolveTarget` directly instead so the continuation
+     * becomes a flat trampoline hop rather than a retained recursive frame.
      */
     resolve(dynamicNext: string | StageNode<TOut, TScope>, node: StageNode<TOut, TScope>, context: StageContext, breakFlag: {
         shouldBreak: boolean;
     }, branchPath: string | undefined, executeNode: ExecuteNodeFn<TOut, TScope>, traversalContext?: TraversalContext): Promise<any>;
-    /** dynamicNext is a string ID → resolve from graph, track iteration. */
-    private handleStringReference;
-    /** dynamicNext is a StageNode with fn → execute directly (truly dynamic). */
-    private handleDirectNode;
-    /** dynamicNext is a StageNode without fn → reference by ID, resolve + track iteration. */
-    private handleNodeReference;
+    /**
+     * Resolve a dynamic continuation to its target node + next StageContext
+     * WITHOUT executing it. Fires the same side effects `resolve` always did
+     * (iteration counting + limit, `dynamicNext*` logs, loop debug message,
+     * `onLoop` narrative), in the same order.
+     *
+     * Three dynamicNext patterns:
+     * - StageNode with fn → truly dynamic node, returned as-is (no iteration
+     *   tracking — it is a fresh node, not a back-edge).
+     * - String ID → reference to an existing node, resolved via NodeResolver.
+     * - StageNode without fn → reference by ID, resolved via NodeResolver.
+     */
+    resolveTarget(dynamicNext: string | StageNode<TOut, TScope>, currentNode: StageNode<TOut, TScope>, context: StageContext, branchPath: string | undefined, traversalContext?: TraversalContext): ResolvedContinuation<TOut, TScope>;
     /**
      * Get the next iteration number for a node and increment.
      * Returns 0 for first visit, 1 for second, etc.

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

@@ -3,6 +3,16 @@
  *
  * Handles scope-based deciders (stage IS the decider, returns branch ID).
  * Logs flow control decisions and narrative sentences.
+ *
+ * Two entry points:
+ * - `prepareDispatch` — runs the decider stage, commits, resolves the chosen
+ *   branch, fires narrative, and returns the chosen node + branch context
+ *   WITHOUT executing it. The traverser's trampoline driver uses this so a
+ *   decider with no continuation of its own can hand the branch to the
+ *   driver as a flat hop (loop-heavy decider charts stay flat-stacked).
+ * - `handleScopeBased` — prepareDispatch + immediate branch execution via
+ *   the provided `executeNode` callback. Kept for direct/advanced callers
+ *   and for deciders whose own `.next` must run after the branch completes.
  */
 import type { StageContext } from '../../memory/StageContext.js';
 import type { StageNode } from '../graph/StageNode.js';
@@ -10,6 +20,19 @@ import type { TraversalContext } from '../narrative/types.js';
 import type { HandlerDeps, StageFunction } from '../types.js';
 import type { ExecuteNodeFn, RunStageFn } from './types.js';
 export type { ExecuteNodeFn, RunStageFn };
+/**
+ * Result of `prepareDispatch` — either the decider stage broke (no branch
+ * runs; `branchId` is the decider's return value), or a branch was chosen
+ * and is ready to execute in `branchContext`.
+ */
+export type DeciderDispatch<TOut = any, TScope = any> = {
+    kind: 'break';
+    branchId: string;
+} | {
+    kind: 'dispatch';
+    chosen: StageNode<TOut, TScope>;
+    branchContext: StageContext;
+};
 export declare class DeciderHandler<TOut = any, TScope = any> {
     private readonly deps;
     constructor(deps: HandlerDeps<TOut, TScope>);
@@ -21,4 +44,13 @@ export declare class DeciderHandler<TOut = any, TScope = any> {
     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>, traversalContext?: TraversalContext): Promise<any>;
+    /**
+     * Run the decider stage and resolve the chosen branch WITHOUT executing it.
+     * Everything up to (and including) the `onDecision`/`onStageExecuted`
+     * narrative and the branch context creation happens here — only the
+     * branch execution itself is left to the caller.
+     */
+    prepareDispatch(node: StageNode<TOut, TScope>, stageFunc: StageFunction<TOut, TScope>, context: StageContext, breakFlag: {
+        shouldBreak: boolean;
+    }, branchPath: string | undefined, runStage: RunStageFn<TOut, TScope>, traversalContext?: TraversalContext): Promise<DeciderDispatch<TOut, TScope>>;
 }

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

@@ -11,7 +11,15 @@ import type { HandlerDeps } from '../types.js';
 export declare class NodeResolver<TOut = any, TScope = any> {
     private deps;
     private readonly nodeIdMap;
-    constructor(deps: HandlerDeps<TOut, TScope>, nodeIdMap?: Map<string, StageNode<TOut, TScope>>);
+    private readonly getEffectiveChildren?;
+    constructor(deps: HandlerDeps<TOut, TScope>, nodeIdMap?: Map<string, StageNode<TOut, TScope>>, 
+    /**
+     * Overlay-aware children accessor injected by the traverser. The DFS
+     * fallback resolves loop targets against the LIVE runtime shape — a node
+     * patched by a dynamic StageNode return carries its children in the
+     * traverser-local overlay, not on the shared built-chart node.
+     */
+    getEffectiveChildren?: (node: StageNode<TOut, TScope>) => StageNode<TOut, TScope>[] | undefined);
     /**
      * O(1) node lookup via pre-built ID map.
      * Falls back to DFS from startNode (for dynamic nodes added at runtime

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

@@ -1,12 +1,15 @@
 /**
  * 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);
+ * Unified traversal algorithm for all node shapes. `executeNode` is a
+ * TRAMPOLINE driver: it runs `executeNodeStep` (one node, all 7 phases) in
+ * a flat loop, following tail continuations (linear `next`, loop edges,
+ * dynamic next, flat decider dispatch) iteratively — so chain length and
+ * loop iterations never grow the call stack. Only true tree nesting (fork
+ * children, with-continuation decider/selector branches, subflow mounts)
+ * recurses.
  *
- * For each node, executeNode follows 7 phases:
+ * For each node, executeNodeStep follows 7 phases:
  *   0. CLASSIFY  — subflow detection, early delegation
  *   1. VALIDATE  — node invariants, role markers
  *   2. EXECUTE   — run stage fn, commit, break check
@@ -21,7 +24,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 { IExecutionRuntime, ILogger, ScopeFactory, SerializedPipelineStructure, StageFunction, StageNode, StreamHandlers, SubflowResult, TraversalResult } from '../types.js';
+import type { IExecutionRuntime, ILogger, ScopeFactory, Selector, SerializedPipelineStructure, StageFunction, StageNode, StreamHandlers, SubflowMountOptions, SubflowResult, TraversalResult } from '../types.js';
 export interface TraverserOptions<TOut = any, TScope = any> {
     root: StageNode<TOut, TScope>;
     stageMap: Map<string, StageFunction<TOut, TScope>>;
@@ -49,10 +52,17 @@ export interface TraverserOptions<TOut = any, TScope = any> {
      */
     narrativeGenerator?: IControlFlowNarrative;
     /**
-     * Maximum recursive executeNode depth. Defaults to FlowchartTraverser.MAX_EXECUTE_DEPTH (500).
-     * Override in tests or unusually deep pipelines.
+     * Maximum nested executeNode depth (tree nesting — branch/fork dispatch and
+     * dynamic recursion, NOT linear chains or loop iterations, which run flat).
+     * Defaults to FlowchartTraverser.MAX_EXECUTE_DEPTH (500).
      */
     maxDepth?: number;
+    /**
+     * Maximum loop iterations per node (the ContinuationResolver guard).
+     * Defaults to DEFAULT_MAX_ITERATIONS (1000). Propagated to subflow
+     * traversers. Must be >= 1.
+     */
+    maxIterations?: 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.
@@ -78,6 +88,37 @@ export interface TraverserOptions<TOut = any, TScope = any> {
      */
     runId: string;
 }
+/**
+ * Traverser-local overlay entry for a node whose stage function returned a
+ * StageNode (dynamic continuation). Holds the dynamic values that earlier
+ * versions wrote DIRECTLY onto the shared built-chart node — which leaked the
+ * dynamic shape into every later run of the same built chart and raced
+ * concurrent executors. The overlay keeps the built graph immutable: patches
+ * live in a per-traverser Map keyed by `node.id` and die with the run.
+ *
+ * `next` is intentionally ABSENT: a dynamic `next` only ever applies to the
+ * visit that produced it (the old code wrote `node.next` and restored it
+ * before anything could observe the write), so it stays a local variable in
+ * `executeNode` and is routed through `ContinuationResolver` directly.
+ */
+export interface DynamicNodePatch<TOut = any, TScope = any> {
+    /**
+     * Subflow mount metadata from a dynamic-subflow return. Grouped so the
+     * merged view reproduces the old field-wise overwrite exactly — including
+     * `subflowName`/`subflowMountOptions` becoming undefined when the dynamic
+     * return omitted them.
+     */
+    subflowMeta?: {
+        isSubflowRoot: true;
+        subflowId: string;
+        subflowName: string | undefined;
+        subflowMountOptions: SubflowMountOptions | undefined;
+    };
+    /** Dynamic fork children (replaces the built node's children for this run). */
+    children?: StageNode<TOut, TScope>[];
+    /** Dynamic output-based selector accompanying dynamic children. */
+    nextNodeSelector?: Selector;
+}
 export declare class FlowchartTraverser<TOut = any, TScope = any> {
     private readonly root;
     private stageMap;
@@ -112,11 +153,41 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
      */
     private readonly resolvedLazySubflows;
     /**
-     * Recursion depth counter for executeNode.
-     * Each recursive executeNode call increments this; decrements on exit (try/finally).
-     * Prevents call-stack overflow on infinite loops or excessively deep stage chains.
+     * Per-traverser overlay of dynamic StageNode returns, keyed by `node.id`.
+     * Phase 4 writes patches HERE instead of mutating the shared built-chart
+     * node objects (same isolation convention as `resolvedLazySubflows`).
+     * All engine reads of the patched fields go through the `eff*` accessors
+     * below. The map dies with the traverser — one run, one overlay — so a
+     * fresh executor over the same built chart always sees the original graph.
+     *
+     * Keyed by the node OBJECT (WeakMap), not `node.id`: a dynamic child that
+     * reuses a built node's id must NOT make the built node inherit the patch
+     * (id-keyed lookup caused phantom double-execution). `patchCount` is the
+     * fast-path check — WeakMap has no `size`.
+     */
+    private readonly dynamicPatches;
+    private patchCount;
+    /**
+     * TREE-nesting depth counter for executeNode (the trampoline driver).
+     * Each driver invocation increments this; decrements on exit (try/finally).
+     *
+     * Linear `next` chains, loop edges, and dynamic continuations are followed
+     * ITERATIVELY inside one driver invocation, so they never grow this
+     * counter. Only true tree recursion does: fork children, decider/selector
+     * branch dispatch (when the decider has its own continuation), and
+     * unbounded dynamic recursion. Prevents call-stack overflow on runaway
+     * recursive composition.
      */
     private _executeDepth;
+    /**
+     * Memoized parent-chain depth per StageContext. The context tree deepens
+     * by one per executed stage along a chain, so the naive parent-walk in
+     * `computeContextDepth` is O(chain length) per stage — O(n²) per run once
+     * the trampoline allows chains of tens of thousands of stages. Contexts
+     * are visited parent-before-child, so the memo makes each lookup O(1)
+     * amortized. WeakMap — dies with the traverser.
+     */
+    private readonly contextDepthCache;
     /**
      * Shared mutable execution counter — monotonic, incremented per stage execution.
      * Shared with child traversers (subflows) so indices are globally unique within a run.
@@ -127,18 +198,26 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
      */
     private readonly _maxDepth;
     /**
-     * Default maximum recursive executeNode depth before an error is thrown.
-     * 500 comfortably covers any realistic pipeline depth (including deeply nested
-     * subflows) while preventing call-stack overflow (~10 000 frames in V8).
+     * Per-instance loop-iteration limit forwarded to the ContinuationResolver
+     * and propagated to subflow traversers. Undefined → resolver default (1000).
+     */
+    private readonly _maxIterations?;
+    /**
+     * Default maximum nested executeNode depth before an error is thrown.
      *
-     * **Note on counting:** the counter increments once per `executeNode` call, not once per
-     * logical user stage. Subflow root entry and subflow continuation after return each cost
-     * one tick. For pipelines with many nested subflows, budget roughly 2 × (avg stages per
-     * subflow) of headroom when computing a custom `maxDepth` via `RunOptions.maxDepth`.
+     * **What counts as depth (trampoline model):** `executeNode` is an iterative
+     * driver — linear `next` hops, loop edges (`loopTo`/dynamic next), and
+     * dynamic-subflow re-entry are followed in a flat loop and consume NO depth.
+     * Depth grows only with true tree nesting: one tick per fork child, one per
+     * decider/selector branch dispatch that must return to its invoker (decider
+     * with its own `next`), one per subflow mount frame in the parent (the
+     * subflow body itself runs on a FRESH traverser with its own budget).
      *
-     * **Note on loops:** for `loopTo()` pipelines, this depth guard and `ContinuationResolver`'s
-     * iteration limit are independent — the lower one fires first. The default depth guard (500)
-     * fires before the default iteration limit (1000) for loop-heavy pipelines.
+     * 500 therefore covers any realistic chart — it bounds recursive
+     * COMPOSITION, not chain length or loop count. Loops are bounded by
+     * `ContinuationResolver`'s independent iteration limit (default 1000,
+     * configurable via `RunOptions.maxIterations`), which is now the binding
+     * constraint for loop-heavy pipelines.
      *
      * @remarks Not safe for concurrent `.execute()` calls on the same instance — concurrent
      * executions race on `_executeDepth`. Use a separate `FlowchartTraverser` per concurrent
@@ -197,19 +276,72 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     /**
      * Build an O(1) ID→node map from the root graph.
      * Used by NodeResolver to avoid repeated DFS on every loopTo() call.
-     * Depth-guarded at MAX_EXECUTE_DEPTH to prevent infinite recursion on cyclic graphs.
+     * Iterative worklist (no recursion) so arbitrarily long chains index fully;
+     * the `map.has` guard handles cyclic refs. First-visited node wins per ID —
+     * worklist order matches the old recursive pre-order (children, then next).
      * Dynamic subflows and lazy-resolved nodes are added to stageMap at runtime but not to this map —
      * those use the DFS fallback in NodeResolver.
      */
     private buildNodeIdMap;
     private getStageFn;
+    private getPatch;
+    private getOrCreatePatch;
+    /** Effective children: dynamic patch first, then the built node's children. */
+    private effChildren;
+    /** Effective output-based selector: dynamic patch first, then the built node's. */
+    private effSelector;
+    /** Effective subflow-root marker (true when a dynamic subflow was patched on). */
+    private effIsSubflowRoot;
+    /** Effective subflow id (patched verbatim by a dynamic subflow return). */
+    private effSubflowId;
+    /**
+     * Materialize the effective view of a node — field-identical to what the
+     * pre-overlay code produced by mutating the shared node. Used where a node
+     * is handed to a helper executor (NodeResolver / SubflowExecutor /
+     * ChildrenExecutor) so helpers never read stale built fields. Returns the
+     * node itself (no allocation) when it carries no patch.
+     */
+    private effNode;
     private executeStage;
     /**
-     * Pre-order DFS traversal — the core algorithm.
-     * Each call processes one node through all 7 phases.
+     * Trampoline driver — pre-order DFS traversal entry point.
+     *
+     * Runs `executeNodeStep` (one node, all 7 phases) in a flat loop: every
+     * TAIL continuation (linear `next`, loop edge, dynamic next / dynamic
+     * re-entry, no-continuation decider dispatch) comes back as a
+     * `ContinuationHop` and is followed ITERATIVELY — neither the call stack
+     * nor the retained promise chain grows with chain length or loop count.
+     *
+     * Recursion remains ONLY for true tree nesting (each gets a nested driver
+     * call): fork children (`ChildrenExecutor`), selector branches (parallel
+     * fan-out), decider branch dispatch when the decider has its own `next`
+     * (the branch must complete BEFORE the decider's continuation runs), and
+     * subflow mounts (fresh traverser; the mount frame stays in the parent).
+     * `_executeDepth` therefore counts chart COMPOSITION depth only, guarded
+     * by `_maxDepth` (default `MAX_EXECUTE_DEPTH` = 500).
+     *
+     * PauseSignal: a flat decider dispatch records an `InvokerStamp`; if the
+     * continued chain later pauses, the driver stamps the signal during
+     * unwind — same invoker context the recursive dispatch's catch used to
+     * stamp, innermost (most recent dispatch) first.
      */
     private executeNode;
+    /** Build a flat continuation hop for the driver loop. */
+    private hop;
+    /**
+     * Execute ONE node through all 7 phases — the old recursive `executeNode`
+     * body; only the tail calls became `ContinuationHop` returns. Returns the
+     * node's result, or a hop for the driver loop to follow.
+     */
+    private executeNodeStep;
     private captureDynamicChildrenResult;
+    /**
+     * Parent-chain length of a StageContext — same value the pre-trampoline
+     * walk produced, memoized. The context tree deepens by one per executed
+     * stage along a chain, so the naive walk is O(chain length) per stage —
+     * O(n²) per run once chains reach trampoline scale. Contexts are visited
+     * parent-before-child, so the cached parent makes this O(1) amortized.
+     */
     private computeContextDepth;
     private prefixNodeTree;
     private autoRegisterSubflowDef;

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

@@ -322,12 +322,24 @@ export interface RunOptions {
      */
     env?: ExecutionEnv;
     /**
-     * Override the maximum recursive `executeNode` depth for this run.
+     * Override the maximum nested `executeNode` depth for this run.
      * Defaults to `FlowchartTraverser.MAX_EXECUTE_DEPTH` (500).
-     * Useful when deeply nested subflows or long chains need more headroom.
-     * Must be >= 1.
+     *
+     * Depth counts TREE nesting only — fork children, decider/selector branch
+     * dispatch, recursive composition. Linear chains and loop iterations run
+     * on a flat trampoline and never consume depth, so this rarely needs
+     * raising. Must be >= 1.
      */
     maxDepth?: number;
+    /**
+     * Override the maximum loop iterations per node for this run (the
+     * `ContinuationResolver` infinite-loop guard). Defaults to 1000.
+     * This is the binding constraint for loop-heavy pipelines — raise it for
+     * legitimately long loops (`loopTo` chains run with a flat stack, so high
+     * values are safe; memory for state/narrative still grows per iteration).
+     * Propagates to subflows. Must be >= 1.
+     */
+    maxIterations?: number;
 }
 export type { FlowControlType, FlowMessage };
 export interface RuntimeStructureMetadata {

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

@@ -117,4 +117,7 @@ export declare class StageContext {
     }): void;
     getStageId(): string;
     getSnapshot(): StageSnapshot;
+    /** Snapshot of THIS context's own fields — `next`/`children` are filled
+     *  in by the iterative walk in `getSnapshot`. */
+    private snapshotSelf;
 }

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

@@ -212,7 +212,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * const result = await executor.resume(restored, { approved: true });
      * ```
      */
-    resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth'>): Promise<ExecutorResult>;
+    resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth' | 'maxIterations'>): Promise<ExecutorResult>;
     /**
      * Build a fully DETACHED checkpoint from a caught PauseSignal.
      *

package/package.json

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