footprintjs 4.1.0 → 4.3.0

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

@@ -12,6 +12,7 @@
  * it belongs in the runner layer (Phase 5).
  */
 import type { ScopeFactory } from '../engine/types.js';
+import type { PausableHandler } from '../pause/types.js';
 import type { TypedScope } from '../reactive/types.js';
 import { type RunnableFlowChart } from '../runner/RunnableChart.js';
 import { type TypedStageFunction } from './typedFlowChart.js';
@@ -107,6 +108,27 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     start(name: string, fn: StageFunction<TOut, TScope>, id: string, description?: string): this;
     addFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, description?: string): this;
     addStreamingFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, streamId?: string, description?: string): this;
+    /**
+     * Add a pausable stage — can pause execution and resume later with input.
+     *
+     * The handler has two phases:
+     * - `execute`: runs first time. Return `{ pause: true }` to pause.
+     * - `resume`: runs when the flowchart is resumed with input.
+     *
+     * @example
+     * ```typescript
+     * .addPausableFunction('ApproveOrder', {
+     *   execute: async (scope) => {
+     *     scope.orderId = '123';
+     *     return { pause: true, data: { question: 'Approve?' } };
+     *   },
+     *   resume: async (scope, input) => {
+     *     scope.approved = input.approved;
+     *   },
+     * }, 'approve-order', 'Manager approval gate')
+     * ```
+     */
+    addPausableFunction(name: string, handler: PausableHandler<TScope>, id: string, description?: string): this;
     addDeciderFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string): DeciderList<TOut, TScope>;
     addSelectorFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string): SelectorFnList<TOut, TScope>;
     addListOfFunction(children: SimplifiedParallelSpec<TOut, TScope>[], options?: {

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

@@ -11,7 +11,7 @@
 import type { StageNode } from '../engine/graph/StageNode.js';
 import type { ILogger, ScopeFactory, StageFunction, TraversalExtractor } from '../engine/types.js';
 import type { ScopeProtectionMode } from '../scope/protection/types.js';
-export type { StageNode } from '../engine/graph/StageNode.js';
+export type { ResumeFn, StageNode } from '../engine/graph/StageNode.js';
 export type { ILogger, StageFunction, StreamCallback, StreamHandlers, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions, } from '../engine/types.js';
 /** Relaxed-generic alias for builder ergonomics. */
 export type StageFn = StageFunction<any, any>;
@@ -49,6 +49,8 @@ export interface SerializedPipelineStructure {
     isLazy?: boolean;
     /** True when this node is a back-edge reference created by loopTo() — not an executable stage. */
     isLoopReference?: boolean;
+    /** When true, this stage can pause execution (PausableHandler pattern). */
+    isPausable?: boolean;
 }
 export interface FlowChartSpec {
     name: string;

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

@@ -9,6 +9,11 @@
  * - Isolated sub-traversals via `isSubflowRoot` (subflow)
  */
 import type { StageFunction, SubflowMountOptions } from '../types.js';
+/**
+ * Resume function for pausable stages.
+ * Unlike StageFunction, the 2nd argument is the resume input (not breakFn).
+ */
+export type ResumeFn<TScope = any, TInput = unknown> = (scope: TScope, input: TInput) => Promise<void> | void;
 /** Picks exactly ONE child by ID. Conditional branch (if/switch). */
 export type Decider = (nodeArgs: any) => string | Promise<string>;
 /**
@@ -59,6 +64,10 @@ export type StageNode<TOut = any, TScope = any> = {
     subflowMountOptions?: SubflowMountOptions;
     /** When true, parallel children use fail-fast semantics (reject on first error) */
     failFast?: boolean;
+    /** When true, this stage can pause execution (PausableHandler pattern). */
+    isPausable?: boolean;
+    /** Resume function — called instead of fn when resuming a paused stage. */
+    resumeFn?: ResumeFn<TScope>;
     /**
      * True if this node is a back-edge reference created by loopTo() — not an executable stage.
      * Serialization equivalent: `SerializedPipelineStructure.isLoopReference` (different name

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

@@ -14,7 +14,7 @@
  */
 import type { ReadEvent, Recorder, WriteEvent } from '../../scope/types.js';
 import type { CombinedNarrativeEntry, NarrativeRenderer } from './narrativeTypes.js';
-import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
+import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowPauseEvent, FlowRecorder, FlowResumeEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
 export interface CombinedNarrativeRecorderOptions {
     includeStepNumbers?: boolean;
     includeValues?: boolean;
@@ -61,6 +61,14 @@ export declare class CombinedNarrativeRecorder implements FlowRecorder, Recorder
     onSubflowExit(event: FlowSubflowEvent): void;
     onLoop(event: FlowLoopEvent): void;
     onBreak(event: FlowBreakEvent): void;
+    onPause(event: FlowPauseEvent | {
+        stageName?: string;
+        stageId?: string;
+    }): void;
+    onResume(event: FlowResumeEvent | {
+        stageName?: string;
+        stageId?: string;
+    }): void;
     /**
      * Handles errors from both channels:
      * - FlowRecorder.onError (FlowErrorEvent with message + structuredError)

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

@@ -32,6 +32,8 @@ export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     onLoop(targetStage: string, iteration: number, description?: string, traversalContext?: TraversalContext): void;
     onBreak(stageName: string, traversalContext?: TraversalContext): void;
     onError(stageName: string, errorMessage: string, error: unknown, traversalContext?: TraversalContext): void;
+    onPause(stageName: string, stageId: string, pauseData: unknown, subflowPath: readonly string[], traversalContext?: TraversalContext): void;
+    onResume(stageName: string, stageId: string, hasInput: boolean, 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/NarrativeFlowRecorder.d.ts

@@ -8,7 +8,7 @@
  * Consumers who want different narrative behavior (windowed loops, adaptive
  * summarization, etc.) can replace this with a different FlowRecorder.
  */
-import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
+import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowPauseEvent, FlowRecorder, FlowResumeEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
 export declare class NarrativeFlowRecorder implements FlowRecorder {
     readonly id: string;
     private sentences;
@@ -25,6 +25,8 @@ export declare class NarrativeFlowRecorder implements FlowRecorder {
     onLoop(event: FlowLoopEvent): void;
     onBreak(event: FlowBreakEvent): void;
     onError(event: FlowErrorEvent): void;
+    onPause(event: FlowPauseEvent): void;
+    onResume(event: FlowResumeEvent): void;
     /** Returns a defensive copy of accumulated sentences. */
     getSentences(): string[];
     /** Clears accumulated sentences. Useful for reuse across runs. */

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

@@ -18,5 +18,7 @@ export declare class NullControlFlowNarrativeGenerator implements IControlFlowNa
     onLoop(): void;
     onBreak(): void;
     onError(): void;
+    onPause(): void;
+    onResume(): void;
     getSentences(): string[];
 }

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

@@ -6,7 +6,7 @@
  * Use CombinedNarrativeRecorder (auto-attached by setEnableNarrative()) instead.
  */
 export interface CombinedNarrativeEntry {
-    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error';
+    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error' | 'pause' | 'resume';
     text: string;
     depth: number;
     stageName?: string;

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

@@ -36,6 +36,10 @@ export interface IControlFlowNarrative {
     onBreak(stageName: string, traversalContext?: TraversalContext): void;
     /** Called when a stage throws an error. Raw error is extracted into structured details. */
     onError(stageName: string, errorMessage: string, error: unknown, traversalContext?: TraversalContext): void;
+    /** Called when a pausable stage pauses execution. */
+    onPause(stageName: string, stageId: string, pauseData: unknown, subflowPath: readonly string[], traversalContext?: TraversalContext): void;
+    /** Called when a paused stage is resumed. */
+    onResume(stageName: string, stageId: string, hasInput: boolean, traversalContext?: TraversalContext): void;
     /** Returns accumulated narrative sentences in execution order. */
     getSentences(): string[];
 }
@@ -145,6 +149,24 @@ export interface FlowErrorEvent {
     structuredError: StructuredErrorInfo;
     traversalContext?: TraversalContext;
 }
+/** Event passed to FlowRecorder.onPause. */
+export interface FlowPauseEvent {
+    stageName: string;
+    stageId: string;
+    /** Data from the pause signal (question, reason, metadata). */
+    pauseData?: unknown;
+    /** Path through subflows to the paused stage. Empty at root level. */
+    subflowPath: readonly string[];
+    traversalContext?: TraversalContext;
+}
+/** Event passed to FlowRecorder.onResume. */
+export interface FlowResumeEvent {
+    stageName: string;
+    stageId: string;
+    /** Whether resume input was provided. */
+    hasInput: boolean;
+    traversalContext?: TraversalContext;
+}
 /**
  * FlowRecorder — Pluggable observer for control flow events.
  *
@@ -177,6 +199,8 @@ export interface FlowRecorder {
     onLoop?(event: FlowLoopEvent): void;
     onBreak?(event: FlowBreakEvent): void;
     onError?(event: FlowErrorEvent): void;
+    onPause?(event: FlowPauseEvent): void;
+    onResume?(event: FlowResumeEvent): void;
     /** Called before each run to reset per-run state. Implement for stateful recorders. */
     clear?(): void;
     /** Optional: expose collected data for inclusion in snapshots. */

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

@@ -11,6 +11,8 @@ import type { ScopeProtectionMode } from '../scope/protection/types.js';
 import type { StageNode } from './graph/StageNode.js';
 import type { IControlFlowNarrative } from './narrative/types.js';
 export type { Decider, Selector, StageNode } from './graph/StageNode.js';
+export type { FlowchartCheckpoint, PausableHandler, PauseResult } from '../pause/index.js';
+export { isPauseResult, isPauseSignal, PauseSignal } from '../pause/index.js';
 /** Minimal logging contract. Mirrors Console API subset. */
 export interface ILogger {
     info(message?: any, ...optionalParams: any[]): void;
@@ -48,6 +50,18 @@ export interface SubflowMountOptions<TParentScope = any, TSubflowInput = any, TS
      * `[...existing, ...value]` for arrays. Return only the **delta** (new items)
      * for array keys, or the parent's existing array items will be duplicated.
      * Scalar values are replaced normally.
+     *
+     * @example
+     * ```typescript
+     * // WRONG — returns full array, parent concats → duplicates
+     * outputMapper: (sf) => ({ messages: sf.allMessages })
+     *
+     * // RIGHT — returns only new items (delta), concat appends correctly
+     * outputMapper: (sf) => ({ messages: sf.newMessages })
+     *
+     * // Scalars are fine — replaced, not concatenated
+     * outputMapper: (sf) => ({ status: sf.result, count: sf.total })
+     * ```
      */
     outputMapper?: (subflowOutput: TSubflowOutput, parentScope: TParentScope) => Record<string, unknown>;
 }
@@ -243,6 +257,13 @@ export type BranchResults = {
     [branchId: string]: BranchResult;
 };
 export type TraversalResult = BranchResults | string | Error;
+/** Returned by run()/resume() when execution pauses. */
+export type PausedResult = {
+    readonly paused: true;
+    readonly checkpoint: import('../pause/types.js').FlowchartCheckpoint;
+};
+/** Full return type of FlowChartExecutor.run() and resume(). */
+export type ExecutorResult = TraversalResult | PausedResult;
 export interface SerializedPipelineNode {
     name: string;
     id: string;
@@ -264,6 +285,8 @@ export interface SerializedPipelineNode {
     isParallelChild?: boolean;
     parallelGroupId?: string;
     isDynamic?: boolean;
+    /** When true, this stage can pause execution (PausableHandler pattern). */
+    isPausable?: boolean;
 }
 export type FlowChart<TOut = any, TScope = any> = {
     root: StageNode<TOut, TScope>;

package/dist/types/lib/pause/index.d.ts

@@ -0,0 +1,2 @@
+export type { FlowchartCheckpoint, PausableHandler, PauseResult } from './types.js';
+export { isPauseResult, isPauseSignal, PauseSignal } from './types.js';

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

@@ -0,0 +1,175 @@
+/**
+ * Pause/Resume — serializable checkpoint for long-running or human-in-the-loop flows.
+ *
+ * A stage signals pause by calling `scope.$pause(data)` which throws a PauseSignal.
+ * The signal bubbles up through SubflowExecutor → FlowchartTraverser → FlowChartExecutor,
+ * each level adding its subflow ID to the path.
+ *
+ * The checkpoint captures:
+ *   - pausedPath: full path to the paused stage (e.g., ['sf-payment', 'approve'])
+ *   - sharedState: scope at the pause point
+ *   - executionTree: completed stages for BTS/narrative
+ *   - pauseData: question, reason, or metadata from $pause()
+ *
+ * Resume rebuilds the flowchart, restores scope, navigates to the paused stage,
+ * injects resumeInput, and continues traversal.
+ *
+ * Supported topologies: linear, subflow, lazy subflow, loop, nested subflow in loop.
+ */
+/**
+ * Thrown by `scope.$pause()` to signal that execution should stop
+ * and create a serializable checkpoint.
+ *
+ * Bubbles up through SubflowExecutor (which prepends subflow ID to path)
+ * and is caught by FlowchartTraverser/FlowChartExecutor.
+ */
+export declare class PauseSignal extends Error {
+    /** Data from $pause() — question, reason, metadata. */
+    readonly pauseData: unknown;
+    /** ID of the stage that called $pause(). */
+    readonly stageId: string;
+    /** Path through subflows to the paused stage. Built during bubble-up. */
+    private _subflowPath;
+    constructor(data: unknown, stageId: string);
+    get subflowPath(): readonly string[];
+    /** Prepend a subflow ID to the path (called during bubble-up). */
+    prependSubflow(subflowId: string): void;
+}
+/**
+ * Returned by a pausable stage's execute/resume function to signal pause.
+ *
+ * @example
+ * ```typescript
+ * execute: async (scope) => {
+ *   scope.orderId = '123';
+ *   return { pause: true, data: { question: 'Approve order 123?' } };
+ * }
+ * ```
+ */
+export interface PauseResult {
+    readonly pause: true;
+    /** Data to include in the checkpoint — question, reason, metadata. */
+    readonly data?: unknown;
+}
+/**
+ * Serializable checkpoint — everything needed to resume a paused flowchart.
+ *
+ * JSON-safe: no functions, no class instances, no SDK clients.
+ * Store anywhere: Redis, Postgres, localStorage, a file.
+ *
+ * @example
+ * ```typescript
+ * // Save
+ * const checkpoint = executor.getCheckpoint(); // after pause
+ * await redis.set(`session:${id}`, JSON.stringify(checkpoint));
+ *
+ * // Resume (hours later, possibly different server)
+ * const checkpoint = JSON.parse(await redis.get(`session:${id}`));
+ * const executor = new FlowChartExecutor(chart);
+ * await executor.resume(checkpoint, { approved: true });
+ * ```
+ */
+/**
+ * Serializable checkpoint — everything needed to resume a paused flowchart.
+ *
+ * The execution tree IS the traversed path. The leaf node with status 'paused'
+ * IS the cursor. No separate path array needed — the tree structure captures
+ * the full nesting (including subflows).
+ *
+ * JSON-safe: no functions, no class instances, no SDK clients.
+ * Store anywhere: Redis, Postgres, localStorage, a file.
+ *
+ * @example
+ * ```typescript
+ * const checkpoint = executor.getCheckpoint(); // after pause
+ * await redis.set(`session:${id}`, JSON.stringify(checkpoint));
+ *
+ * // Resume (hours later, possibly different server)
+ * const checkpoint = JSON.parse(await redis.get(`session:${id}`));
+ * const executor = new FlowChartExecutor(chart);
+ * await executor.resume(checkpoint, { approved: true });
+ * ```
+ */
+export interface FlowchartCheckpoint {
+    /** Scope state at the pause point — all shared memory key/values. */
+    readonly sharedState: Record<string, unknown>;
+    /** Execution tree — the traversed path. The leaf with status 'paused' is the cursor.
+     *  Contains subflow nesting. Used for BTS visualization and to find the resume point. */
+    readonly executionTree: unknown;
+    /** ID of the stage that paused. Used by resume() to find the node in the graph. */
+    readonly pausedStageId: string;
+    /** Path through subflows to the paused stage (e.g., ['sf-payment', 'sf-validation']).
+     *  Empty array when paused at the top level. */
+    readonly subflowPath: readonly string[];
+    /** Data from $pause() — question, reason, metadata. */
+    readonly pauseData?: unknown;
+    /** Subflow results collected before the pause. */
+    readonly subflowResults?: Record<string, unknown>;
+    /** Timestamp of when the pause occurred. */
+    readonly pausedAt: number;
+}
+/**
+ * Handler for a pausable stage — has two phases: execute and resume.
+ *
+ * `execute` runs the first time. It can return `{ pause: true }` to pause.
+ * `resume` runs when the flowchart is resumed. It receives the resume input.
+ *
+ * Both phases receive the same scope. After execute pauses, the scope state
+ * is preserved in the checkpoint. On resume, the scope is restored before
+ * calling resume.
+ *
+ * @example
+ * ```typescript
+ * .addPausableFunction('ApproveOrder', {
+ *   execute: async (scope) => {
+ *     scope.orderId = '123';
+ *     scope.amount = 299;
+ *     return { pause: true, data: { question: `Approve $${scope.amount} refund?` } };
+ *   },
+ *   resume: async (scope, input) => {
+ *     scope.approved = input.approved;
+ *     scope.approver = input.approver;
+ *   },
+ * }, 'approve-order', 'Manager approval gate')
+ *
+ * // Later — resume with human's answer
+ * await executor.resume(checkpoint, { approved: true, approver: 'Jane' });
+ * ```
+ */
+export interface PausableHandler<TScope = any, TInput = unknown> {
+    /**
+     * First-run phase. Return data to pause, or void/undefined to continue normally.
+     *
+     * Any non-void return value becomes the `pauseData` in the checkpoint.
+     * The library detects the return and pauses automatically — no need to
+     * call `pause()` or construct `{ pause: true }`.
+     *
+     * @example
+     * ```typescript
+     * execute: async (scope) => {
+     *   scope.orderId = '123';
+     *   return { question: `Approve order ${scope.orderId}?` }; // ← pauses
+     * }
+     *
+     * // Conditional pause
+     * execute: async (scope) => {
+     *   if (scope.amount > 500) {
+     *     return { reason: 'High-value order needs approval' }; // ← pauses
+     *   }
+     *   // void return → no pause, continues normally
+     * }
+     * ```
+     */
+    execute: (scope: TScope) => Promise<unknown> | unknown;
+    /**
+     * Resume phase. Called with the resume input when execution continues.
+     *
+     * The scope is restored from the checkpoint's `sharedState`. Writes during
+     * `resume` are committed and visible to subsequent stages.
+     */
+    resume: (scope: TScope, input: TInput) => Promise<void> | void;
+}
+/** Check if a value is a PauseResult (stage wants to pause). */
+export declare function isPauseResult(value: unknown): value is PauseResult;
+/** Check if an error is a PauseSignal. Uses instanceof + name brand fallback for cross-realm safety. */
+export declare function isPauseSignal(error: unknown): error is PauseSignal;

package/dist/types/lib/recorder/CompositeRecorder.d.ts

@@ -0,0 +1,95 @@
+/**
+ * CompositeRecorder — fan-out a single recorder attachment to multiple child recorders.
+ *
+ * Implements both Recorder (scope data ops) and FlowRecorder (control flow events)
+ * so it works with both `executor.attachRecorder()` and `executor.attachFlowRecorder()`.
+ *
+ * The composite has a single ID for idempotent attach/detach. Child recorders
+ * keep their own IDs internally but are not individually visible to the executor.
+ *
+ * Domain libraries (e.g., agentfootprint) use this to bundle multiple recorders
+ * into a single preset — the consumer calls one function, gets full observability.
+ *
+ * @example
+ * ```typescript
+ * import { CompositeRecorder, MetricRecorder, DebugRecorder } from 'footprintjs';
+ *
+ * // Bundle metrics + debug into a single recorder
+ * const observability = new CompositeRecorder('observability', [
+ *   new MetricRecorder({ stageFilter: (name) => name === 'CallLLM' }),
+ *   new DebugRecorder({ verbosity: 'minimal' }),
+ * ]);
+ *
+ * executor.attachRecorder(observability);
+ *
+ * // Access child recorders by type
+ * const metrics = observability.get(MetricRecorder);
+ * metrics?.getMetrics(); // timing data
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Domain library preset (e.g., agentfootprint)
+ * export function agentObservability(options?: AgentObservabilityOptions) {
+ *   return new CompositeRecorder('agent-observability', [
+ *     new MetricRecorder(options?.stageFilter ? { stageFilter: options.stageFilter } : undefined),
+ *     new TokenRecorder(),
+ *     new ToolUsageRecorder(),
+ *   ]);
+ * }
+ *
+ * // Consumer
+ * executor.attachRecorder(agentObservability());
+ * ```
+ */
+import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent } from '../engine/narrative/types.js';
+import type { CommitEvent, ErrorEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../scope/types.js';
+/** Snapshot format for composite recorders — wraps child snapshots. */
+export interface CompositeSnapshot {
+    name: string;
+    data: {
+        children: Array<{
+            id: string;
+            name: string;
+            data: unknown;
+        }>;
+    };
+}
+export declare class CompositeRecorder implements Recorder, FlowRecorder {
+    readonly id: string;
+    private readonly children;
+    constructor(id: string, children: Array<Recorder | FlowRecorder>);
+    /**
+     * Get a child recorder by class type.
+     *
+     * @example
+     * ```typescript
+     * const metrics = composite.get(MetricRecorder);
+     * ```
+     */
+    get<T>(type: new (...args: any[]) => T): T | undefined;
+    /** Get all child recorders. */
+    getChildren(): ReadonlyArray<Recorder | FlowRecorder>;
+    onRead(event: ReadEvent): void;
+    onWrite(event: WriteEvent): void;
+    onCommit(event: CommitEvent): void;
+    onError(event: ErrorEvent | FlowErrorEvent): void;
+    onStageStart(event: StageEvent): void;
+    onStageEnd(event: StageEvent): void;
+    onStageExecuted(event: FlowStageEvent): void;
+    onNext(event: FlowNextEvent): void;
+    onDecision(event: FlowDecisionEvent): void;
+    onFork(event: FlowForkEvent): void;
+    onSelected(event: FlowSelectedEvent): void;
+    onSubflowEntry(event: FlowSubflowEvent): void;
+    onSubflowExit(event: FlowSubflowEvent): void;
+    onSubflowRegistered(event: FlowSubflowRegisteredEvent): void;
+    onLoop(event: FlowLoopEvent): void;
+    onBreak(event: FlowBreakEvent): void;
+    clear(): void;
+    /**
+     * Snapshot merges all child snapshots into a single composite entry.
+     * Each child's snapshot is preserved with its own id/name/data.
+     */
+    toSnapshot(): CompositeSnapshot;
+}

package/dist/types/lib/recorder/index.d.ts

@@ -0,0 +1,2 @@
+export type { CompositeSnapshot } from './CompositeRecorder.js';
+export { CompositeRecorder } from './CompositeRecorder.js';

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

@@ -32,7 +32,11 @@ export declare class ExecutionRuntime {
     globalStore: SharedMemory;
     rootStageContext: StageContext;
     executionHistory: EventLog;
+    /** Original root for getSnapshot() — set before resume changes rootStageContext. */
+    private _snapshotRoot?;
     constructor(rootName: string, rootId: string, defaultValues?: unknown, initialState?: unknown);
+    /** Preserve the current rootStageContext for snapshots before changing it for resume. */
+    preserveSnapshotRoot(): void;
     getPipelines(): string[];
     setRootObject(path: string[], key: string, value: unknown): void;
     getSnapshot(): RuntimeSnapshot;

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

@@ -20,7 +20,8 @@ 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 ExtractorError, type FlowChart, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type StreamHandlers, type SubflowResult, type TraversalResult } from '../engine/types.js';
+import { type ExecutorResult, type ExtractorError, type FlowChart, 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 { ScopeProtectionMode } from '../scope/protection/types.js';
 import type { Recorder, RedactionPolicy, RedactionReport } from '../scope/types.js';
 import { type RuntimeSnapshot } from './ExecutionRuntime.js';
@@ -88,6 +89,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     private redactionPolicy;
     private sharedRedactedKeys;
     private sharedRedactedFieldsByKey;
+    private lastCheckpoint;
     private readonly flowChartArgs;
     /**
      * Create a FlowChartExecutor.
@@ -118,10 +120,82 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * most recent run. Never includes actual values.
      */
     getRedactionReport(): RedactionReport;
+    /**
+     * Returns the checkpoint from the most recent paused execution, or `undefined`
+     * if the last run completed without pausing.
+     *
+     * The checkpoint is JSON-serializable — store it in Redis, Postgres, localStorage, etc.
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.run({ input });
+     * if (executor.isPaused()) {
+     *   const checkpoint = executor.getCheckpoint()!;
+     *   await redis.set(`session:${id}`, JSON.stringify(checkpoint));
+     * }
+     * ```
+     */
+    getCheckpoint(): FlowchartCheckpoint | undefined;
+    /** Returns `true` if the most recent run() was paused (checkpoint available). */
+    isPaused(): boolean;
+    /**
+     * Resume a paused flowchart from a checkpoint.
+     *
+     * Restores the scope state, calls the paused stage's `resumeFn` with the
+     * provided input, then continues traversal from the next stage.
+     *
+     * The checkpoint can come from `getCheckpoint()` on a previous run, or from
+     * a serialized checkpoint stored in Redis/Postgres/localStorage.
+     *
+     * **Narrative/recorder state is reset on resume.** To keep a unified narrative
+     * across pause/resume cycles, collect it before calling resume.
+     *
+     * @example
+     * ```typescript
+     * // After a pause...
+     * const checkpoint = executor.getCheckpoint()!;
+     * await redis.set(`session:${id}`, JSON.stringify(checkpoint));
+     *
+     * // Later (possibly different server, same chart)
+     * const checkpoint = JSON.parse(await redis.get(`session:${id}`));
+     * const executor = new FlowChartExecutor(chart);
+     * const result = await executor.resume(checkpoint, { approved: true });
+     * ```
+     */
+    resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth'>): Promise<ExecutorResult>;
+    /**
+     * Find a StageNode in the compiled graph by ID.
+     * Handles subflow paths by drilling into registered subflows.
+     */
+    private findNodeInGraph;
+    /** DFS search for a node by ID in the StageNode graph. Cycle-safe via visited set. */
+    private dfsFind;
     /**
      * Attach a scope Recorder to observe data operations (reads, writes, commits).
      * Automatically attached to every ScopeFacade created during traversal.
      * Must be called before run().
+     *
+     * **Idempotent by ID:** If a recorder with the same `id` is already attached,
+     * it is replaced (not duplicated). This prevents double-counting when both
+     * a framework and the user attach the same recorder type.
+     *
+     * Built-in recorders use auto-increment IDs (`metrics-1`, `debug-1`, ...) by
+     * default, so multiple instances with different configs coexist. To override
+     * a framework-attached recorder, pass the same well-known ID.
+     *
+     * @example
+     * ```typescript
+     * // Multiple recorders with different configs — each gets a unique ID
+     * executor.attachRecorder(new MetricRecorder());
+     * executor.attachRecorder(new DebugRecorder({ verbosity: 'minimal' }));
+     *
+     * // Override a framework-attached recorder by passing its well-known ID
+     * executor.attachRecorder(new MetricRecorder('metrics'));
+     *
+     * // Attaching twice with same ID replaces (no double-counting)
+     * executor.attachRecorder(new MetricRecorder('my-metrics'));
+     * executor.attachRecorder(new MetricRecorder('my-metrics')); // replaces previous
+     * ```
      */
     attachRecorder(recorder: Recorder): void;
     /** Detach all scope Recorders with the given ID. */
@@ -132,6 +206,8 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * Attach a FlowRecorder to observe control flow events.
      * Automatically enables narrative if not already enabled.
      * Must be called before run() — recorders are passed to the traverser at creation time.
+     *
+     * **Idempotent by ID:** replaces existing recorder with same `id`.
      */
     attachFlowRecorder(recorder: FlowRecorder): void;
     /** Detach all FlowRecorders with the given ID. */
@@ -169,7 +245,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * chart with N stages you will typically get more entries here than from `getNarrative()`.
      */
     getFlowNarrative(): string[];
-    run(options?: RunOptions): Promise<TraversalResult>;
+    run(options?: RunOptions): Promise<ExecutorResult>;
     getSnapshot(): RuntimeSnapshot;
     /** @internal */
     getRuntime(): import("../engine/types.js").IExecutionRuntime;