footprintjs 4.2.0 → 4.3.1

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;
@@ -255,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;
@@ -276,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/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,6 +120,56 @@ 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.
@@ -193,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;

package/dist/types/lib/scope/ScopeFacade.d.ts

@@ -62,6 +62,10 @@ export declare class ScopeFacade {
     /** @internal */
     notifyStageEnd(duration?: number): void;
     /** @internal */
+    notifyPause(stageId: string, pauseData?: unknown): void;
+    /** @internal */
+    notifyResume(stageId: string, hasInput: boolean): void;
+    /** @internal */
     notifyCommit(mutations: CommitEvent['mutations']): void;
     /** Called by StageContext.commit() observer. Converts tracked writes to CommitEvent format.
      *  Errors are caught to prevent recorder issues from aborting the traversal. */

package/dist/types/lib/scope/recorders/DebugRecorder.d.ts

@@ -4,10 +4,10 @@
  * Captures errors (always), mutations and reads (in verbose mode),
  * and stage lifecycle events for troubleshooting.
  */
-import type { ErrorEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types.js';
+import type { ErrorEvent, PauseEvent, ReadEvent, Recorder, ResumeEvent, StageEvent, WriteEvent } from '../types.js';
 export type DebugVerbosity = 'minimal' | 'verbose';
 export interface DebugEntry {
-    type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd';
+    type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd' | 'pause' | 'resume';
     stageName: string;
     timestamp: number;
     data: unknown;
@@ -42,6 +42,8 @@ export declare class DebugRecorder implements Recorder {
     onError(event: ErrorEvent): void;
     onStageStart(event: StageEvent): void;
     onStageEnd(event: StageEvent): void;
+    onPause(event: PauseEvent): void;
+    onResume(event: ResumeEvent): void;
     getEntries(): DebugEntry[];
     getErrors(): DebugEntry[];
     getEntriesForStage(stageName: string): DebugEntry[];

package/dist/types/lib/scope/recorders/MetricRecorder.d.ts

@@ -29,12 +29,13 @@
  * executor.attachRecorder(new MetricRecorder({ id: 'metrics' }));
  * ```
  */
-import type { CommitEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types.js';
+import type { CommitEvent, PauseEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types.js';
 export interface StageMetrics {
     stageName: string;
     readCount: number;
     writeCount: number;
     commitCount: number;
+    pauseCount: number;
     totalDuration: number;
     invocationCount: number;
 }
@@ -43,6 +44,7 @@ export interface AggregatedMetrics {
     totalReads: number;
     totalWrites: number;
     totalCommits: number;
+    totalPauses: number;
     stageMetrics: Map<string, StageMetrics>;
 }
 /** Options for MetricRecorder. All fields are optional. */
@@ -72,6 +74,7 @@ export declare class MetricRecorder implements Recorder {
     onRead(event: ReadEvent): void;
     onWrite(event: WriteEvent): void;
     onCommit(event: CommitEvent): void;
+    onPause(event: PauseEvent): void;
     onStageStart(event: StageEvent): void;
     onStageEnd(event: StageEvent): void;
     getMetrics(): AggregatedMetrics;

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

@@ -38,6 +38,14 @@ export interface ErrorEvent extends RecorderContext {
 export interface StageEvent extends RecorderContext {
     duration?: number;
 }
+export interface PauseEvent extends RecorderContext {
+    stageId: string;
+    pauseData?: unknown;
+}
+export interface ResumeEvent extends RecorderContext {
+    stageId: string;
+    hasInput: boolean;
+}
 /**
  * Declarative redaction configuration — define once, applied everywhere.
  *
@@ -86,6 +94,8 @@ export interface Recorder {
     onError?(event: ErrorEvent): void;
     onStageStart?(event: StageEvent): void;
     onStageEnd?(event: StageEvent): void;
+    onPause?(event: PauseEvent): void;
+    onResume?(event: ResumeEvent): void;
     /** Reset state before each executor.run() — prevents cross-run accumulation. */
     clear?(): void;
     /** Expose collected data for inclusion in executor.getSnapshot().recorders. */

package/package.json

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