footprintjs 9.26.0 → 9.28.0

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

@@ -14,7 +14,16 @@
  * 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.
+ * Supported topologies: linear, subflow (at any depth — mounted linearly, as a
+ * decider or selector branch, or as a fork child), loop, nested subflow in
+ * loop, and several parallel siblings pausing in one fan-out (each asks in
+ * turn — `FlowchartCheckpoint.pendingPauses`).
+ *
+ * NOT resumable yet: a pause inside a LAZY subflow (`addLazySubFlowChart*`) or
+ * inside an `addParallelForEach` branch. Their graphs are resolved at run time
+ * and are not in the chart a resume walks, so `resume()` refuses the
+ * checkpoint ("not found") instead of guessing. Pinned in
+ * test/lib/pause/resume-known-limitations.test.ts.
  */
 /**
  * Thrown by `scope.$pause()` to signal that execution should stop
@@ -65,10 +74,35 @@ export declare class PauseSignal extends Error {
      * crash with "X is not iterable" / undefined.
      */
     private _subflowStates;
+    /**
+     * Pauses that PARALLEL SIBLINGS raised in the same fan-out as this one,
+     * waiting their turn (9.28.0). Recorded by `ChildrenExecutor` when more
+     * than one child of a fork (or more than one selected branch) pauses: the
+     * first pause is the one that is asked, the others ride here instead of
+     * being dropped. Each path is relative to where the signal currently is
+     * and grows with it — `prependSubflow` prepends to every entry too.
+     */
+    private _pendingPauses;
     constructor(data: unknown, stageId: string, pausedBy?: 'interrupt');
     get subflowPath(): readonly string[];
-    /** Prepend a subflow ID to the path (called during bubble-up). */
+    /**
+     * Prepend a subflow ID to the path (called during bubble-up). The pending
+     * sibling pauses ride the same boundary, so their paths grow with it.
+     */
     prependSubflow(subflowId: string): void;
+    /**
+     * Queue a parallel sibling's pause behind this one (its path relative to
+     * this signal's current level). Copied in: the entry is owned by the
+     * signal from here on.
+     */
+    addPendingPause(pause: PendingPause): void;
+    /** Parallel siblings' pauses waiting behind this one, in the order they will be asked. */
+    get pendingPauses(): readonly PendingPause[];
+    /**
+     * This pause as a {@link PendingPause} — what `ChildrenExecutor` queues
+     * behind a sibling's pause when both paused in one fan-out.
+     */
+    toPendingPause(): PendingPause;
     /** The stage that invoked the paused child (decider, selector, fork). */
     get invokerStageId(): string | undefined;
     /** Where execution should continue after resume (invoker's next node). */
@@ -93,6 +127,42 @@ export declare class PauseSignal extends Error {
     /** Captured subflow scopes (read-only view). */
     get subflowStates(): Readonly<Record<string, Record<string, unknown>>>;
 }
+/**
+ * A pause a PARALLEL SIBLING of the paused stage raised in the same fan-out —
+ * two children of one fork (or two selected branches of one selector) that
+ * both paused (9.28.0). Only one pause is asked at a time: the checkpoint's
+ * own (`pausedStageId`), then each of these in turn, with the fan-out's join
+ * running only once every child is done.
+ *
+ * Everything needed to raise the sibling's pause again later WITHOUT re-running
+ * the sibling: its stage, its path, its captured subflow state, its question.
+ *
+ * @example
+ * ```typescript
+ * // A fork whose two children both ask: the first checkpoint asks c1 and
+ * // carries c2's pause; resuming it finishes c1, then pauses with c2's
+ * // question; resuming THAT finishes c2 and runs the join.
+ * const cp = executor.getCheckpoint()!;
+ * cp.pausedStageId;                  // 'c1/ask'
+ * cp.pendingPauses?.[0].pausedStageId; // 'c2/ask'
+ * ```
+ */
+export interface PendingPause {
+    /** The sibling's paused stage (path-prefixed id, as `pausedStageId`). */
+    readonly pausedStageId: string;
+    /** Path through subflows to the sibling's paused stage (as `subflowPath`). */
+    readonly subflowPath: readonly string[];
+    /**
+     * The sibling's own subflow captures — the subflows on ITS path below the
+     * fan-out. The subflows above the fan-out are shared with the checkpoint's
+     * own pause and are captured again when this pause is raised.
+     */
+    readonly subflowStates: Record<string, Record<string, unknown>>;
+    /** The sibling's question (as `pauseData`). */
+    readonly pauseData?: unknown;
+    /** How the sibling paused (as `pausedBy`). */
+    readonly pausedBy?: 'interrupt';
+}
 /**
  * Returned by a pausable stage's execute/resume function to signal pause.
  *
@@ -183,8 +253,10 @@ export interface FlowchartCheckpoint {
      *
      * Always present (empty `{}` for root-level pauses where no subflows
      * were entered). On resume, `SubflowExecutor` seeds each nested runtime
-     * from this map (and skips the inputMapper) so resume handlers see
-     * pre-pause scope across same-executor AND cross-executor restarts.
+     * on the path from this map — ONCE, on its first entry, in place of the
+     * inputMapper's values (the mapper still runs, for the stages' read-only
+     * args) — so resume handlers see pre-pause scope across same-executor AND
+     * cross-executor restarts. Only the subflows ON `subflowPath` read it.
      */
     readonly subflowStates: Record<string, Record<string, unknown>>;
     /**
@@ -209,8 +281,24 @@ export interface FlowchartCheckpoint {
     readonly visitCounts?: Readonly<Record<string, number>>;
     /** Stage that invoked the paused child (decider, selector, fork). Absent for linear pauses. */
     readonly invokerStageId?: string;
-    /** Where to continue after resume — the invoker's next node ID. Absent for linear pauses. */
+    /**
+     * The invoker's next node ID. Absent for linear pauses.
+     *
+     * A RECORD, not an instruction: since 9.28.0 `resume()` derives what runs
+     * after the paused stage from the chart itself (the stage's own `next`, else
+     * the continuation of the dispatcher that ran it — at every level of the
+     * pause path), so an edited value cannot redirect a resumed run.
+     */
     readonly continuationStageId?: string;
+    /**
+     * Pauses raised by PARALLEL SIBLINGS of the paused stage in the same
+     * fan-out, waiting their turn (9.28.0) — see {@link PendingPause}. Absent
+     * when only one child paused (every checkpoint before 9.28.0 omits it, and
+     * resumes exactly as before). Resuming this checkpoint finishes the paused
+     * stage's child, then pauses again with the first of these; the fan-out's
+     * join runs once every child is done.
+     */
+    readonly pendingPauses?: readonly PendingPause[];
     /** Timestamp of when the pause occurred. */
     readonly pausedAt: number;
 }

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

@@ -320,7 +320,14 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * 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.
+     * provided input (or, for an `interrupt()` pause, re-runs the stage with the
+     * answer), then continues with whatever ran after that stage on the run —
+     * its own `next`, or the continuation of the decider, selector or fork that
+     * dispatched it, at every level of the pause path — and from there walks the
+     * chart as built. When parallel siblings paused in the same fan-out
+     * (`checkpoint.pendingPauses`), the run pauses again with the next sibling's
+     * question once this one's branch is done; the fan-out's join runs after the
+     * last answer. See `ResumeEntry` (`footprintjs/advanced`).
      *
      * The checkpoint can come from `getCheckpoint()` on a previous run, or from
      * a serialized checkpoint stored in Redis/Postgres/localStorage.
@@ -392,15 +399,6 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * Handles subflow paths by drilling into registered subflows.
      */
     private findNodeInGraph;
-    /**
-     * Find the mount node (the node that mounts a subflow boundary)
-     * for a given subflowId, by DFS from `start`. Used by `resume()` to
-     * locate the OUTER node we have to enter through so the subflow's
-     * outputMapper and parent continuation execute.
-     *
-     * Cycle-safe via visited set. Returns the first match (DFS order).
-     */
-    private findMountInGraph;
     /** DFS search for a node by ID in the StageNode graph. Cycle-safe via visited set. */
     private dfsFind;
     /**

package/package.json

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