footprintjs 8.2.0 → 8.3.0

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

@@ -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 { 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>>;
@@ -78,6 +78,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;
@@ -111,6 +142,21 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
      * resolver before another traverser has finished using it.
      */
     private readonly resolvedLazySubflows;
+    /**
+     * 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;
     /**
      * Recursion depth counter for executeNode.
      * Each recursive executeNode call increments this; decrements on exit (try/finally).
@@ -203,6 +249,24 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
      */
     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.

package/package.json

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