footprintjs 5.0.0 → 6.1.0

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

@@ -0,0 +1,349 @@
+/**
+ * StructureRecorder — passive observer of BUILD-TIME chart construction events.
+ *
+ * The build-time twin of `FlowRecorder`. Where `FlowRecorder` observes
+ * RUNTIME control-flow transitions (per-execution `runtimeStageId`,
+ * iteration counts, errors, pauses), `StructureRecorder` observes
+ * STATIC chart shape as it's assembled by the builder — every spec
+ * node added, every outgoing edge wired, every decider closed.
+ *
+ * Why two interfaces, not one
+ * ───────────────────────────
+ *   Build and runtime events have different INVARIANTS, not just
+ *   different timing:
+ *
+ *     - Runtime events carry `runtimeStageId` (`[subflowPath/]stageId#N`),
+ *       `iteration`, `traversalContext` — load-bearing for time-travel
+ *       UIs, commit-log indices, and `SequenceRecorder<T>` consumers.
+ *       NONE of these exist at build time.
+ *
+ *     - Build events carry only `stageId` + structural fields. No
+ *       execution index, no iteration, no snapshot.
+ *
+ *     - Some events have no analog across phases: `onPause` /
+ *       `onResume` / `onError` / `onRunStart` are runtime-only;
+ *       `onDeciderComplete` / `onStageAdded` are build-only.
+ *
+ *   A single `FlowRecorder` with `phase: 'static' | 'dynamic'`
+ *   discriminator would force every consumer to write
+ *   `if (e.phase === 'static') ...` branches and would erase the
+ *   least-privilege boundary (a static-only consumer should NOT
+ *   accidentally observe runtime data — e.g., a public docs site
+ *   rendering chart topology must not see scope values).
+ *
+ *   Two interfaces, same mental model, clean separation. Two
+ *   registration sites ship today (pick whichever fits your call
+ *   site):
+ *
+ *     1. **Options-bag** (preferred when the recorder set is known
+ *        at construction time — registers BEFORE `start()` so even
+ *        the seed event fires through the normal dispatcher fan-out):
+ *        ```ts
+ *        flowChart('seed', fn, 'seed', { structureRecorders: [rec] })
+ *          .addFunction('a', fnA, 'a').build();
+ *        ```
+ *
+ *     2. **Fluent** (preferred when attach is conditional, late, or
+ *        in a chain builder — the just-attached recorder gets a
+ *        one-time seed replay so it observes the root stage):
+ *        ```ts
+ *        flowChart('seed', fn, 'seed')
+ *          .attachStructureRecorder(rec)
+ *          .addFunction('a', fnA, 'a').build();
+ *        ```
+ *
+ *   Both deliver the same event stream to the same recorder. See the
+ *   `@example` block below for a fully-fleshed-out implementation.
+ *
+ * Lifecycle + ordering invariants
+ * ───────────────────────────────
+ *   - Fires SYNCHRONOUSLY during builder chain calls (and during
+ *     `.build()` for the terminal node) at the natural moment each
+ *     spec mutation completes.
+ *   - `onStageAdded(A)` and `onStageAdded(B)` fire BEFORE any
+ *     `onEdgeAdded({from: A, to: B})` — endpoint registration
+ *     happens before edge wiring.
+ *   - `onDeciderComplete(D)` fires at sub-builder `.end()` time, AFTER
+ *     every child's `onStageAdded` and every `onEdgeAdded({from: D,
+ *     to: child})`. Marks the decider as no-further-mutation.
+ *   - `onSubflowMounted({subflowId})` fires once per mount.
+ *     **MOUNT-ONLY**: parent recorders do NOT receive a replay of
+ *     the subflow's own internal structure events (those fired
+ *     during the subflow's own `.build()`). Matches the runtime
+ *     `onSubflowEntry` semantics — composition over replay.
+ *
+ * Error isolation (matches FlowRecorder contract)
+ * ───────────────────────────────────────────────
+ *   - A throwing handler is caught, logged via `isDevMode()` warning,
+ *     and accumulated on `builder.getStructureBuildErrors()` for
+ *     post-hoc inspection.
+ *   - Subsequent recorders + subsequent events fire normally; one
+ *     misbehaving recorder cannot THROW its way into blocking
+ *     construction.
+ *   - The errors[] accumulator is soft-capped (~100 entries) with a
+ *     `__truncated__` sentinel record once the cap is hit, to prevent
+ *     unbounded growth on chatty broken recorders.
+ *   - Note: throw isolation does NOT defend against a handler that
+ *     succeeds at runtime but mutates `event.spec` to corrupt the
+ *     chart. See "Spec mutation" below.
+ *
+ * Spec mutation — readonly-by-contract (NOT runtime-enforced)
+ * ────────────────────────────────────────────────────────────
+ *   - Event payloads pass spec references where useful (e.g., `spec`
+ *     on `onStageAdded`). Every field on every event payload is
+ *     marked `readonly` in TypeScript — the type system signals
+ *     consumer intent at author time.
+ *   - There is NO runtime freeze. The builder fires `onStageAdded`
+ *     IMMEDIATELY when a spec node is added, BEFORE the builder
+ *     wires that node's `.next`/`.children`/`.loopTarget` in the
+ *     subsequent `addX` call. Freezing here would break the
+ *     builder's own subsequent mutation.
+ *   - Handler mutation of `event.spec` is DOCUMENTED UNDEFINED
+ *     BEHAVIOR — it will succeed at runtime, but is not supported
+ *     and downstream consumers may break. Specifically, mutating
+ *     `event.spec.fn`, `event.spec.id`, or `event.spec.children`
+ *     can corrupt subsequent runtime behavior of the chart.
+ *   - **Trust model**: attach ONLY recorders from trusted code paths.
+ *     A hostile or buggy recorder can effectively substitute stage
+ *     functions or rewire the chart structure. The `readonly`
+ *     markers cannot defend against intentional mutation.
+ *
+ * @example
+ * ```ts
+ * class TraceStructureRecorder implements StructureRecorder {
+ *   readonly id = 'trace-static';
+ *   nodes: XyflowNode[] = [];
+ *   edges: XyflowEdge[] = [];
+ *
+ *   onStageAdded(e) {
+ *     // Node role: 'stage' is the initial type. If outgoing edges
+ *     // arrive with kind 'fork-branch' / 'decision-branch' the node
+ *     // is functioning as a fork/decider — derive the visual style
+ *     // from those edges, not from `e.type` alone.
+ *     this.nodes.push({ id: e.stageId, type: 'lensStage', data: { label: e.name } });
+ *   }
+ *   onEdgeAdded(e) {
+ *     this.edges.push({ id: `${e.from}->${e.to}`, source: e.from, target: e.to });
+ *   }
+ *   onSubflowMounted(e) {
+ *     this.nodes.push({ id: e.subflowId, type: 'subflow', data: { label: e.subflowName } });
+ *   }
+ *   onDeciderComplete(e) {
+ *     // Optional: finalize node styling now that branch list is sealed.
+ *   }
+ * }
+ *
+ * // Registration option A — options-bag (preferred when recorders
+ * // are known up front; attaches BEFORE the seed event fires):
+ * const rec = new TraceStructureRecorder();
+ * const builder = flowChart('seed', fn, 'seed', {
+ *   structureRecorders: [rec],
+ * }).addFunction('a', fnA, 'a');
+ * const chart = builder.build();
+ *
+ * // Registration option B — fluent chain (preferred for conditional
+ * // or late attach; the just-attached recorder gets a seed replay):
+ * const rec2 = new TraceStructureRecorder();
+ * const builder2 = flowChart('seed', fn, 'seed')
+ *   .attachStructureRecorder(rec2)
+ *   .addFunction('a', fnA, 'a');
+ *
+ * // Inspect any recorder errors (call on the BUILDER, not the chart):
+ * const errors = builder.getStructureBuildErrors();
+ *
+ * <ReactFlow nodes={rec.nodes} edges={rec.edges} />
+ * ```
+ */
+import type { FlowChartSpec, SerializedPipelineStructure } from '../types.js';
+/**
+ * Event payload for `StructureRecorder.onStageAdded`. Fires for every
+ * spec node added to the chart, including the seed (added via
+ * `flowChart()` factory) and subflow mount nodes. Excludes synthetic
+ * loop-reference nodes (those carry `isLoopReference: true` on the
+ * spec; consumers see them via the separate `onLoopEdgeAdded` event
+ * instead of as fresh stages).
+ */
+export interface StructureStageAddedEvent {
+    /**
+     * Stable identifier for this node. AT EVENT FIRE TIME this is the
+     * builder's LOCAL form (no subflow prefix — the prefix is applied
+     * later by `_prefixNodeTree` when this builder is mounted as a
+     * subflow into a parent).
+     *
+     * Note: `spec.id` is a LIVE reference. If you read it AFTER this
+     * chart has been mounted as a subflow, it may have been rewritten
+     * to the FULL prefixed form. Use `splitStageId(spec.id)` from
+     * `footprintjs/trace` to decompose it back into local + subflowPath.
+     *
+     * Correlating with runtime events:
+     *   - Same builder (no mount) →
+     *     `event.stageId === parseRuntimeStageId(runtime).stageId`
+     *   - This builder mounted as subflow → use `splitStageId` on the
+     *     prefixed form (or `parseRuntimeStageId` on the full
+     *     runtimeStageId) before comparing.
+     */
+    readonly stageId: string;
+    /** Human-readable label for the node. */
+    readonly name: string;
+    /** Spec node `type`. Lets recorders branch on stage vs decider vs
+     *  fork vs subflow without re-deriving from other fields. */
+    readonly type: NonNullable<FlowChartSpec['type']>;
+    /** True for nodes added via `addPausableFunction()` — useful for
+     *  visualisers that want to mark stages that can pause execution. */
+    readonly isPausable?: boolean;
+    /** Live reference to the full spec node, for handlers that want
+     *  details beyond the discriminator fields above. MUST NOT be
+     *  mutated by the handler — readonly is type-level intent; no
+     *  runtime freeze. See "Spec mutation" in the file header for the
+     *  trust-model caveats. */
+    readonly spec: FlowChartSpec;
+}
+/** Edge kinds the builder produces at structural time. Matches the
+ *  footprintjs control-flow vocabulary used at runtime.
+ *
+ *  Why no `subflow-entry` here: subflow mounts use the lifecycle
+ *  event `onSubflowMounted` (not an edge event). If a future use case
+ *  needs the parent→subflow-root edge as a distinct kind, it'll be
+ *  added then — YAGNI now (Panel 3, L7.2 review). */
+export type StructureEdgeKind = 'next' | 'fork-branch' | 'decision-branch';
+/**
+ * Event payload for `StructureRecorder.onEdgeAdded`. Fires whenever
+ * the builder wires an outgoing edge from one node to another. Both
+ * endpoints have already been announced via `onStageAdded` by the
+ * time this fires.
+ *
+ * Loop back-edges have their OWN event (`onLoopEdgeAdded`) so
+ * consumers can theme them distinctly and so build-time events stay
+ * free of the runtime-only `iteration` field.
+ */
+export interface StructureEdgeAddedEvent {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: StructureEdgeKind;
+    /** Optional human-readable label — used today for decider branch
+     *  keys (e.g., `'low'`, `'high'`, `'high (default)'`) and parallel
+     *  branch ids. */
+    readonly label?: string;
+}
+/**
+ * Event payload for `StructureRecorder.onLoopEdgeAdded`. Fires when
+ * `.loopTo(target)` installs a back-edge. Distinct from
+ * `onEdgeAdded` so consumers can theme back-edges differently and
+ * because runtime `onLoop` carries `iteration: number` which has no
+ * build-time meaning — keeping the events separated avoids forcing
+ * an `iteration?: number` lie into the structural shape.
+ */
+export interface StructureLoopEdgeAddedEvent {
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * Event payload for `StructureRecorder.onDeciderComplete`. Fires
+ * when a decider / selector sub-builder closes via `.end()`. By the
+ * time this fires every branch has been announced and the
+ * `defaultBranch` (if set via `.setDefault()`) is final. Lets
+ * recorders treat the decider as no-further-mutation and snapshot
+ * its branch list as final.
+ */
+export interface StructureDeciderCompleteEvent {
+    /** Decider / selector stage id. */
+    readonly decider: string;
+    /** Spec type (`'decider'` vs `'selector'`) — exposed so consumers
+     *  don't need to look up the original `onStageAdded` event. */
+    readonly type: 'decider' | 'selector';
+    /** Branch member ids in declaration order. */
+    readonly branchIds: readonly string[];
+    /** Default branch id when set via `.setDefault()`; undefined when
+     *  no default is configured (e.g., selectors). */
+    readonly defaultBranch?: string;
+}
+/**
+ * Event payload for `StructureRecorder.onSubflowMounted`. Fires once
+ * per subflow mount (`addSubFlowChart` / `addSubFlowChartNext` and
+ * their lazy variants).
+ *
+ * **MOUNT-ONLY semantics** — the subflow's OWN structure events
+ * (every `onStageAdded` / `onEdgeAdded` inside the subflow) fired
+ * during the subflow's own `.build()`, before the mount. Parent
+ * recorders do NOT receive a replay. Instead, this event delivers
+ * the subflow's full structure via `subflowSpec`, and consumers can
+ * walk it via `walkSubflowSpec` from `footprintjs/trace`.
+ *
+ * This matches `FlowRecorder.onSubflowEntry` semantics at runtime
+ * (parents see the boundary, not a replay of internals) and
+ * preserves the "one purpose per recorder" convention.
+ */
+export interface StructureSubflowMountedEvent {
+    /** Subflow identifier the parent assigned at mount. */
+    readonly subflowId: string;
+    /** Human-readable subflow name. */
+    readonly subflowName: string;
+    /** Mount node id in the parent's chart. */
+    readonly rootStageId: string;
+    /** True when the mount uses lazy resolution (deferred subflow
+     *  resolution until execution). */
+    readonly isLazy?: boolean;
+    /**
+     * The mounted subflow's complete spec — the SAME OBJECT
+     * (=== reference equality) reachable via `subflow.buildTimeStructure`
+     * for the FlowChart the consumer passed to `addSubFlowChartBranch` /
+     * `addSubFlowChart` / `addSubFlowChartNext`.
+     *
+     * UNDEFINED for lazy mounts at build time (`isLazy: true`) — the
+     * subflow's structure hasn't been resolved yet. Consumers waiting on
+     * lazy subflows handle the runtime `onSubflowEntry` event instead.
+     *
+     * Immutable post-build; consumers MUST NOT mutate.
+     *
+     * @internal `SerializedPipelineStructure` is library-internal.
+     *           Use `walkSubflowSpec` from `footprintjs/trace` for the
+     *           stable public contract.
+     */
+    readonly subflowSpec?: SerializedPipelineStructure;
+    /**
+     * Local mount id of this subflow within its parent — equal to
+     * `subflowId` for top-level mounts (e.g. `'auth'`), composed
+     * (`'auth/verify'`) for nested mounts whose recorder is attached
+     * to the grandparent. Matches runtime `traversalContext.subflowPath`
+     * semantics — NEVER prefixed with `__root__/`.
+     */
+    readonly subflowPath: string;
+}
+/**
+ * Pluggable observer for BUILD-TIME chart construction events.
+ *
+ * All methods are optional — implement only the hooks you need.
+ * Handlers fire SYNCHRONOUSLY during builder operations and `.build()`.
+ * A throwing handler is caught (see "Error isolation" in the file
+ * header); subsequent dispatch continues.
+ *
+ * Lifecycle: each `StructureRecorder` instance is registered via
+ * EITHER the `flowChart()` options bag (`{ structureRecorders: [rec] }`)
+ * OR the fluent `.attachStructureRecorder(rec)` chain — see the file
+ * header for the trade-offs. Registration after `.build()` is
+ * rejected (chart is sealed).
+ */
+export interface StructureRecorder {
+    /**
+     * Stable identifier — used by the dispatcher to scope error
+     * messages and to support `detach(id)` lookup.
+     *
+     * Convention (matches `FlowRecorder.id` from CLAUDE.md):
+     *   - domain-prefixed kebab-case (`'lens-structure'`,
+     *     `'agentfootprint-composition'`, `'trace-explainable'`)
+     *   - same id → multiple recorders coexist (NOT deduplicated by
+     *     id; the dispatcher fires every attached recorder regardless)
+     *   - `detach(id)` removes EVERY recorder with that id — be
+     *     intentional about reuse if you rely on selective detach
+     *
+     * Choose a stable id at module load and don't randomise it across
+     * runs — it lands in `StructureBuildError.recorderId` so debug
+     * output is greppable.
+     */
+    readonly id: string;
+    onStageAdded?(event: StructureStageAddedEvent): void;
+    onEdgeAdded?(event: StructureEdgeAddedEvent): void;
+    onLoopEdgeAdded?(event: StructureLoopEdgeAddedEvent): void;
+    onDeciderComplete?(event: StructureDeciderCompleteEvent): void;
+    onSubflowMounted?(event: StructureSubflowMountedEvent): void;
+}

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';
@@ -52,6 +53,15 @@ export interface SerializedPipelineStructure {
     isLoopReference?: boolean;
     /** When true, this stage can pause execution (PausableHandler pattern). */
     isPausable?: boolean;
+    /**
+     * STRUCTURE-ONLY: for a fork/selector/decider branch, the downstream stage
+     * id its convergence `next` edge points to, instead of the shared next-stage
+     * its siblings converge at. Set from `SubflowMountOptions.convergeAt`; read by
+     * `_fireNextEdgeFromParent` to express an unequal-depth merge (e.g. tools →
+     * call-llm, bypassing message-api). Visualization-only — runtime convergence
+     * is unchanged.
+     */
+    convergeAt?: string;
 }
 export interface FlowChartSpec {
     name: string;
@@ -77,14 +87,37 @@ 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;
+    /**
+     * Only meaningful for `flowChartSelector` (a root selector). When the
+     * selector picks ≥2 branches they fan out in parallel: `failFast: true`
+     * uses `Promise.all` (first branch error rejects + aborts), the default
+     * uses `Promise.allSettled` (best-effort — all branches run even if some
+     * fail). Use fail-fast when all selected branches are REQUIRED. Ignored for
+     * non-selector charts. Same flag `addSelectorFunction` / `addListOfFunction`
+     * expose.
+     */
+    failFast?: 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>;
     }>;

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/ChildrenExecutor.d.ts

@@ -28,5 +28,5 @@ export declare class ChildrenExecutor<TOut = any, TScope = any> {
      * Execute selected children based on selector result.
      * Validates IDs, records selection info, then delegates to executeNodeChildren.
      */
-    executeSelectedChildren(selector: Selector, children: StageNode<TOut, TScope>[], input: any, context: StageContext, branchPath: string, traversalContext?: TraversalContext): Promise<Record<string, NodeResultType>>;
+    executeSelectedChildren(selector: Selector, children: StageNode<TOut, TScope>[], input: any, context: StageContext, branchPath: string, traversalContext?: TraversalContext, failFast?: boolean): Promise<Record<string, NodeResultType>>;
 }

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/index.d.ts

@@ -14,7 +14,7 @@ export { NullControlFlowNarrativeGenerator } from './narrative/NullControlFlowNa
 export type { IControlFlowNarrative } from './narrative/types.js';
 export { FlowRecorderDispatcher } from './narrative/FlowRecorderDispatcher.js';
 export { NarrativeFlowRecorder } from './narrative/NarrativeFlowRecorder.js';
-export type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, TraversalContext, } from './narrative/types.js';
+export type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, TraversalContext, } from './narrative/types.js';
 export type { StructuredErrorInfo } from './errors/errorInfo.js';
 export { extractErrorInfo, formatErrorInfo } from './errors/errorInfo.js';
 export { AdaptiveNarrativeFlowRecorder } from './narrative/recorders/AdaptiveNarrativeFlowRecorder.js';

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

@@ -10,7 +10,8 @@
  * 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 { StructuredErrorInfo } from '../errors/errorInfo.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 +22,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;
@@ -36,6 +37,7 @@ export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     onResume(stageName: string, stageId: string, hasInput: boolean, traversalContext?: TraversalContext): void;
     onRunStart(input: unknown, traversalContext?: TraversalContext): void;
     onRunEnd(output: unknown, traversalContext?: TraversalContext): void;
+    onRunFailed(error: StructuredErrorInfo, traversalContext?: TraversalContext): void;
     /**
      * Returns sentences from an attached NarrativeFlowRecorder (looked up by ID).
      * Callers that need sentences should attach a NarrativeFlowRecorder with id 'narrative'

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

@@ -22,5 +22,6 @@ export declare class NullControlFlowNarrativeGenerator implements IControlFlowNa
     onResume(): void;
     onRunStart(): void;
     onRunEnd(): void;
+    onRunFailed(): void;
     getSentences(): string[];
 }