footprintjs 5.0.0 → 6.0.0

package/dist/types/lib/builder/structure/StructureRecorderDispatcher.d.ts

@@ -0,0 +1,77 @@
+/**
+ * StructureRecorderDispatcher — Fans build-time structure events out to N
+ * attached `StructureRecorder` instances.
+ *
+ * Mirrors `FlowRecorderDispatcher` (engine/narrative/) exactly:
+ *
+ *   - `recorders: StructureRecorder[]` — attach order preserved
+ *   - per-event fire methods early-return when no recorders attached
+ *     (zero-allocation fast path)
+ *   - per-recorder try/catch isolates errors; one bad recorder cannot
+ *     cascade into the chain build or sibling recorders
+ *   - errors route to BOTH the dev-mode console warning (matches
+ *     FlowRecorderDispatcher) AND a structured `buildErrors`
+ *     accumulator so consumers can inspect failures post-build
+ *   - spec payloads are NOT frozen at dispatch time — handlers must
+ *     respect the `readonly` markers on event payload types (the
+ *     builder still needs to mutate `spec.next` after the immediate
+ *     `onStageAdded` fires; see `fireStageAdded` for the full note,
+ *     and `StructureRecorder.ts` header "Spec mutation" for the
+ *     trust-model implications)
+ *
+ * The dispatcher itself owns NO chart state. The builder owns the
+ * dispatcher; events fire from the natural mutation points in
+ * FlowChartBuilder (L7.3).
+ */
+import type { FlowChartSpec } from '../types.js';
+import type { StructureDeciderCompleteEvent, StructureEdgeAddedEvent, StructureLoopEdgeAddedEvent, StructureRecorder, StructureStageAddedEvent, StructureSubflowMountedEvent } from './StructureRecorder.js';
+/** Structured error captured when a recorder throws. Read post-build
+ *  via `builder.getStructureBuildErrors()` — call on the BUILDER
+ *  reference (NOT the chart returned by `.build()`). Capture the
+ *  builder reference before `.build()` if you need post-build access. */
+export interface StructureBuildError {
+    /** Which recorder's handler threw. */
+    readonly recorderId: string;
+    /** Which event method (`'onStageAdded'`, `'onEdgeAdded'`, ...). */
+    readonly method: string;
+    /** Error message extracted from the thrown value. */
+    readonly message: string;
+    /** The original thrown value — `Error` instance or whatever the
+     *  recorder threw. Useful when diagnosis needs a stack trace. */
+    readonly error: unknown;
+}
+export declare class StructureRecorderDispatcher {
+    private recorders;
+    private readonly errors;
+    private _truncated;
+    /** Attach a `StructureRecorder`. Multiple recorders with the same
+     *  id are allowed; the convention is one id per logical concern. */
+    attach(recorder: StructureRecorder): void;
+    /** Detach every recorder with the given id. */
+    detach(id: string): void;
+    /** Defensive copy of the attached recorders — used in tests + by
+     *  tooling that wants to inspect what's registered. */
+    getRecorders(): StructureRecorder[];
+    /** Find one recorder by id. */
+    getRecorderById<T extends StructureRecorder = StructureRecorder>(id: string): T | undefined;
+    /** Read accumulated errors from this build. Returns a defensive copy. */
+    getErrors(): StructureBuildError[];
+    fireStageAdded(event: StructureStageAddedEvent): void;
+    fireEdgeAdded(event: StructureEdgeAddedEvent): void;
+    fireLoopEdgeAdded(event: StructureLoopEdgeAddedEvent): void;
+    fireDeciderComplete(event: StructureDeciderCompleteEvent): void;
+    fireSubflowMounted(event: StructureSubflowMountedEvent): void;
+    /**
+     * Externally-callable error capture for events the builder fires
+     * OUTSIDE the normal fire* fan-out path — specifically the seed
+     * replay in `FlowChartBuilder.attachStructureRecorder()`, which
+     * targets one specific recorder rather than every attached recorder.
+     *
+     * Same observability contract as the internal `recordError`:
+     * accumulates on `getErrors()` AND logs in dev mode.
+     */
+    recordErrorForReplay(recorderId: string, method: string, err: unknown): void;
+    private recordError;
+}
+/** Re-export the FlowChartSpec type for downstream type completeness. */
+export type { FlowChartSpec };

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

@@ -9,8 +9,9 @@
  * The builder remains standalone at runtime.
  */
 import type { StageNode } from '../engine/graph/StageNode.js';
-import type { ILogger, ScopeFactory, StageFunction, TraversalExtractor } from '../engine/types.js';
+import type { ILogger, ScopeFactory, StageFunction } from '../engine/types.js';
 import type { ScopeProtectionMode } from '../scope/protection/types.js';
+import type { StructureRecorder } from './structure/StructureRecorder.js';
 export type { ResumeFn, StageNode } from '../engine/graph/StageNode.js';
 export type { ILogger, StageFunction, StreamCallback, StreamHandlers, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions, } from '../engine/types.js';
 export { ArrayMergeMode } from '../engine/types.js';
@@ -77,14 +78,27 @@ export interface FlowChartSpec {
     /** True when this node is a back-edge reference created by loopTo() — not an executable stage. */
     isLoopReference?: boolean;
 }
-/** Metadata provided to the build-time extractor for each node. */
-export type BuildTimeNodeMetadata = FlowChartSpec;
-export type BuildTimeExtractor<TResult = FlowChartSpec> = (metadata: BuildTimeNodeMetadata) => TResult;
-export type { TraversalExtractor } from '../engine/types.js';
+/**
+ * Options-bag argument shape for the `flowChart()` factory.
+ */
+export interface FlowChartOptions {
+    /**
+     * Build-time recorders to attach BEFORE `start()` fires. Equivalent
+     * to chaining `.attachStructureRecorder(rec)` immediately after the
+     * factory returns — but registered EARLIER, so even the seed event
+     * fires through the dispatcher without needing the seed-replay path.
+     *
+     * Multiple recorders attach in array order (same as
+     * `.attachStructureRecorder` repeated). See `StructureRecorder` JSDoc
+     * for event semantics, ordering invariants, and the trust model.
+     */
+    structureRecorders?: StructureRecorder[];
+    /** Free-form description shown on the root spec node. */
+    description?: string;
+}
 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>;
     }>;

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

@@ -6,8 +6,9 @@
  * a single extraction point that preserves structured details while still
  * producing a human-readable message.
  *
- * Consumers (narrative recorders, extractors, diagnostic collectors) receive
- * StructuredErrorInfo instead of a flat string, and can decide how to render it.
+ * Consumers (narrative recorders, FlowRecorder.onError handlers, diagnostic
+ * collectors) receive StructuredErrorInfo instead of a flat string, and can
+ * decide how to render it.
  * String-ification happens only at the final rendering boundary.
  */
 import type { ValidationIssue } from '../../schema/errors.js';

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

@@ -8,8 +8,8 @@ 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 } from '../types.js';
-import type { CallExtractorFn, ExecuteNodeFn, GetStagePathFn, RunStageFn } from './types.js';
-export type { CallExtractorFn, ExecuteNodeFn, GetStagePathFn, RunStageFn };
+import type { ExecuteNodeFn, RunStageFn } from './types.js';
+export type { ExecuteNodeFn, RunStageFn };
 export declare class DeciderHandler<TOut = any, TScope = any> {
     private readonly deps;
     constructor(deps: HandlerDeps<TOut, TScope>);
@@ -20,5 +20,5 @@ 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>, callExtractor: CallExtractorFn<TOut, TScope>, getStagePath: GetStagePathFn<TOut, TScope>, traversalContext?: TraversalContext): Promise<any>;
+    }, branchPath: string | undefined, runStage: RunStageFn<TOut, TScope>, executeNode: ExecuteNodeFn<TOut, TScope>, traversalContext?: TraversalContext): Promise<any>;
 }

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

@@ -11,7 +11,7 @@ import type { StageNode } from '../graph/StageNode.js';
 import type { SerializedPipelineStructure } from '../types.js';
 /**
  * Compute the node type from node properties.
- * Shared by RuntimeStructureManager (serialization) and ExtractorRunner (metadata).
+ * Used by RuntimeStructureManager for serialization.
  */
 export declare function computeNodeType(node: StageNode): 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow' | 'loop';
 export declare class RuntimeStructureManager {

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

@@ -11,7 +11,7 @@ import type { StageNode } from '../graph/StageNode.js';
 import type { TraversalContext } from '../narrative/types.js';
 import type { HandlerDeps, NodeResultType, StageFunction } from '../types.js';
 import type { ChildrenExecutor } from './ChildrenExecutor.js';
-import type { CallExtractorFn, ExecuteNodeFn, GetStagePathFn, RunStageFn } from './types.js';
+import type { ExecuteNodeFn, RunStageFn } from './types.js';
 export declare class SelectorHandler<TOut = any, TScope = any> {
     private readonly deps;
     private readonly childrenExecutor;
@@ -23,5 +23,5 @@ export declare class SelectorHandler<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>, callExtractor: CallExtractorFn<TOut, TScope>, getStagePath: GetStagePathFn<TOut, TScope>, traversalContext?: TraversalContext): Promise<Record<string, NodeResultType>>;
+    }, branchPath: string | undefined, runStage: RunStageFn<TOut, TScope>, executeNode: ExecuteNodeFn<TOut, TScope>, traversalContext?: TraversalContext): Promise<Record<string, NodeResultType>>;
 }

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

@@ -3,12 +3,11 @@
  */
 export { StageRunner } from './StageRunner.js';
 export { NodeResolver } from './NodeResolver.js';
-export type { CallExtractorFn, ExecuteNodeFn, GetStagePathFn, RunStageFn } from './types.js';
+export type { ExecuteNodeFn, RunStageFn } from './types.js';
 export { ChildrenExecutor } from './ChildrenExecutor.js';
 export { DeciderHandler } from './DeciderHandler.js';
 export { SelectorHandler } from './SelectorHandler.js';
 export { ContinuationResolver, DEFAULT_MAX_ITERATIONS } from './ContinuationResolver.js';
 export { SubflowExecutor } from './SubflowExecutor.js';
 export { applyOutputMapping, createSubflowHandlerDeps, extractParentScopeValues, getInitialScopeValues, seedSubflowGlobalStore, } from './SubflowInputMapper.js';
-export { ExtractorRunner } from './ExtractorRunner.js';
 export { computeNodeType, RuntimeStructureManager } from './RuntimeStructureManager.js';

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

@@ -1,7 +1,7 @@
 /**
  * handlers/types.ts — Shared callback types for all handler modules.
  *
- * Avoids duplicate definitions of ExecuteNodeFn / CallExtractorFn / etc.
+ * Avoids duplicate definitions of ExecuteNodeFn / RunStageFn / etc.
  * across ChildrenExecutor, DeciderHandler, ContinuationResolver, SubflowExecutor.
  * All types are callbacks that break circular dependencies with FlowchartTraverser.
  */
@@ -28,12 +28,5 @@ export interface BreakFlag {
 }
 /** Recursive node execution — avoids circular dep with FlowchartTraverser. */
 export type ExecuteNodeFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, context: StageContext, breakFlag: BreakFlag, branchPath?: string) => Promise<any>;
-/** Run a stage function with commit + extractor. */
+/** Run a stage function with commit. */
 export type RunStageFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, stageFunc: StageFunction<TOut, TScope>, context: StageContext, breakFn: () => void) => Promise<TOut>;
-/** Call the traversal extractor after stage execution. */
-export type CallExtractorFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, context: StageContext, stagePath: string, stageOutput?: unknown, errorInfo?: {
-    type: string;
-    message: string;
-}) => void;
-/** Compute the stage path string for extractor and narrative. */
-export type GetStagePathFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, branchPath?: string, contextStageName?: string) => string;

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

@@ -10,7 +10,7 @@
  * When no recorders are attached, every method is a fast no-op (empty array check).
  */
 import type { DecisionEvidence, SelectionEvidence } from '../../decide/types.js';
-import type { FlowRecorder, IControlFlowNarrative, TraversalContext } from './types.js';
+import type { FlowRecorder, IControlFlowNarrative, StageType, TraversalContext } from './types.js';
 export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     private recorders;
     /** Attach a FlowRecorder. Duplicate IDs are allowed (same as scope ScopeRecorder). */
@@ -21,7 +21,7 @@ export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     getScopeRecorders(): FlowRecorder[];
     /** Find a recorder by ID. Useful for retrieving built-in recorders like NarrativeFlowRecorder. */
     getRecorderById<T extends FlowRecorder = FlowRecorder>(id: string): T | undefined;
-    onStageExecuted(stageName: string, description?: string, traversalContext?: TraversalContext): void;
+    onStageExecuted(stageName: string, description: string | undefined, traversalContext: TraversalContext | undefined, stageType: StageType): void;
     onNext(fromStage: string, toStage: string, description?: string, traversalContext?: TraversalContext): void;
     onDecision(deciderName: string, chosenBranch: string, rationale?: string, deciderDescription?: string, traversalContext?: TraversalContext, evidence?: DecisionEvidence): void;
     onFork(parentStage: string, childNames: string[], traversalContext?: TraversalContext): void;

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. */
@@ -115,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 {

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;
@@ -103,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;
@@ -194,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/runner/FlowChartExecutor.d.ts

@@ -9,7 +9,7 @@
  *   const executor = new FlowChartExecutor(chart);
  *
  *   // Options-object form (preferred when you need to customize behavior):
- *   const executor = new FlowChartExecutor(chart, { scopeFactory: myFactory, enrichSnapshots: true });
+ *   const executor = new FlowChartExecutor(chart, { scopeFactory: myFactory });
  *
  *   // 2-param form (accepts a ScopeFactory directly, for backward compatibility):
  *   const executor = new FlowChartExecutor(chart, myFactory);
@@ -21,7 +21,7 @@ import type { CombinedNarrativeRecorderOptions } from '../engine/narrative/Combi
 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';
-import { type ExecutorResult, type ExtractorError, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type StreamHandlers, type SubflowResult } from '../engine/types.js';
+import { type ExecutorResult, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type StreamHandlers, type SubflowResult } from '../engine/types.js';
 import type { FlowchartCheckpoint } from '../pause/types.js';
 import type { CombinedRecorder } from '../recorder/CombinedRecorder.js';
 import type { EmitRecorder } from '../recorder/EmitRecorder.js';
@@ -34,7 +34,7 @@ import { type RuntimeSnapshot } from './ExecutionRuntime.js';
  * ```typescript
  * const ex = new FlowChartExecutor(chart, {
  *   scopeFactory: myFactory,
- *   enrichSnapshots: true,
+ *   defaultValuesForContext: { ... },
  * });
  * ```
  *
@@ -50,14 +50,6 @@ import { type RuntimeSnapshot } from './ExecutionRuntime.js';
 export interface FlowChartExecutorOptions<TScope = any> {
     /** Custom scope factory. Defaults to TypedScope or ScopeFacade auto-detection. */
     scopeFactory?: ScopeFactory<TScope>;
-    /**
-     * Attach a per-stage scope snapshot to each extractor result. When `true`, the
-     * extraction callback receives the full shared state at the point that stage
-     * committed — useful for debugging multi-stage state transitions. Defaults to
-     * `false` (no scope snapshot attached). Can also be set on the chart via
-     * `flowChart(...).enrichSnapshots(true)`.
-     */
-    enrichSnapshots?: boolean;
     /**
      * Default values pre-populated into the shared context before **each** stage
      * (re-applied every stage, acting as baseline defaults).
@@ -121,7 +113,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      *
      * **Options object form** (preferred):
      * ```typescript
-     * new FlowChartExecutor(chart, { scopeFactory, enrichSnapshots: true })
+     * new FlowChartExecutor(chart, { scopeFactory, defaultValuesForContext })
      * ```
      *
      * **2-param form** (also supported):
@@ -419,10 +411,6 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     getRuntimeStructure(): SerializedPipelineStructure | undefined;
     /** @internal */
     getSubflowResults(): Map<string, SubflowResult>;
-    /** @internal */
-    getExtractedResults<TResult = unknown>(): Map<string, TResult>;
-    /** @internal */
-    getExtractorErrors(): ExtractorError[];
     /**
      * Returns the subflow manifest from an attached ManifestFlowRecorder.
      * Returns empty array if no ManifestFlowRecorder is attached.

package/dist/types/trace.d.ts

@@ -21,7 +21,9 @@
  * ```
  */
 export type { ExecutionCounter } from './lib/engine/runtimeStageId.js';
-export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId } from './lib/engine/runtimeStageId.js';
+export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId, splitStageId, } from './lib/engine/runtimeStageId.js';
+export type { WalkerItem, WalkerOptions } from './lib/engine/walkSubflowSpec.js';
+export { walkSubflowSpec } from './lib/engine/walkSubflowSpec.js';
 export { findCommit, findCommits, findLastWriter } from './lib/memory/commitLogUtils.js';
 export type { CausalChainOptions, CausalNode, KeysReadLookup } from './lib/memory/backtrack.js';
 export { causalChain, flattenCausalDAG, formatCausalChain } from './lib/memory/backtrack.js';

package/package.json

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