@particle-academy/fancy-flow 0.72.1 → 0.73.0

package/README.md

@@ -633,6 +633,28 @@ registerNodeKind({
 `awaiting-input:` prefixes, so runs that parked under an older version still
 resume.
 
+### Queued runs: one node at a time
+
+`@particle-academy/fancy-flow/durable` splits a run into one queue job per node.
+`Coordinator.advance()` says what to dispatch, and `runNode()` claims, executes
+and checkpoints one node.
+
+**Serial is the default.** `advance()` hands out one node, and the next only
+once that node has settled, in the graph's declaration order. A node paused for
+a person keeps its slot, so nothing else goes out while they decide. To dispatch
+more at once, pass `maxConcurrent`:
+
+```ts
+import { Coordinator, UNLIMITED_CONCURRENCY } from "@particle-academy/fancy-flow/durable";
+
+new Coordinator({ graph, executors, run, store });                                        // serial
+new Coordinator({ graph, executors, run, store, maxConcurrent: 4 });                      // up to 4 held
+new Coordinator({ graph, executors, run, store, maxConcurrent: UNLIMITED_CONCURRENCY });  // whole frontier
+```
+
+The selection is pinned by the shared `flow/durable-dispatch` conformance suite,
+which specifies the same behaviour for the PHP and Python runtimes.
+
 ## Status
 
 Shipping. Since this list was last written, all of the following landed:

package/dist/durable/index.d.cts

@@ -108,6 +108,10 @@ declare class InMemoryClaimStore implements NodeClaimStore {
     /**
      * Drop a paused node's claim so a recorded answer can re-run it.
      *
+     * A PAUSED row holds one of the run's dispatch slots (see `selectDispatch`),
+     * so this is also what frees the slot: until the row is released, a serial
+     * run's `advance()` hands out nothing, the gate included.
+     *
      * Not part of the interface: resuming a human gate is the host's decision and
      * its storage's business. Provided here because the in-memory store is also
      * what the tests resume through.
@@ -180,6 +184,57 @@ declare const Frontier: {
     settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<string[]>;
 };
 
+/**
+ * How many of ONE run's nodes may be held at once, and which ready nodes go next.
+ *
+ * ## Serial is the default
+ *
+ * A queued run hands a node to the queue only once the node before it has
+ * settled: one node of a run held at a time, in the graph's own declaration
+ * order. Parallel dispatch of a ready frontier is something a host ASKS for,
+ * with `maxConcurrent` on the {@link Coordinator}.
+ *
+ * | `maxConcurrent` | meaning |
+ * |---|---|
+ * | unset | **1**: serial |
+ * | `N >= 1` | up to N of the run's nodes held at once |
+ * | {@link UNLIMITED_CONCURRENCY} (`0`) | the whole ready frontier |
+ * | anything else | refused, by name |
+ *
+ * A negative number is refused rather than read as "unlimited". Under a serial
+ * default, a typo that silently turned a run parallel is the failure to avoid.
+ *
+ * ## Held means claimed OR paused
+ *
+ * A node parked on a person keeps its slot. A pause does not park the whole run
+ * in this runtime: `advance()` is called whenever any job settles, and without
+ * this rule it would hand out the gate's siblings while the person is still
+ * deciding.
+ *
+ * ## Measured against held work, not the batch
+ *
+ * Two nodes settling at once each trigger an `advance()` on a real queue. A cap
+ * applied to one batch would let each of them dispatch its own quota, so the
+ * budget is `maxConcurrent - held`, counted off the claim rows.
+ *
+ * This is the TypeScript member of a three-runtime contract. The
+ * `flow/durable-dispatch` conformance suite pins it, and names
+ * `fancy-flow-php`'s `DispatchLimit` and the Python runtime's
+ * `fancy_flow.durable.select_dispatch` as the other two implementations.
+ */
+
+/** Dispatch the whole ready frontier. Named so a host never writes a bare `0`. */
+declare const UNLIMITED_CONCURRENCY = 0;
+/**
+ * The ready nodes that may be dispatched now, in the order given.
+ *
+ * `ready` comes from `Frontier.compute`, in declaration order, and that order is
+ * kept: this slices, it never sorts. `state` must already include any skips the
+ * frontier just settled. Skips are never held, so that changes no count, but the
+ * state must describe the run as it is after the decision.
+ */
+declare function selectDispatch(ready: readonly string[], state: Record<string, NodeState>, maxConcurrent: number): string[];
+
 /**
  * Run ONE node of a graph — through the real engine, not around it.
  *
@@ -396,7 +451,10 @@ declare function durableApproval(submissions: Submissions): NodeExecutor;
  *
  * `advance()`
  *   Ask the frontier what is unblocked, settle the skip cascade, and report the
- *   ready node ids. A queue adapter dispatches one job per id.
+ *   node ids that may be dispatched NOW. A queue adapter dispatches one job per
+ *   id. By default that is at most one id: a run holds one node at a time, and
+ *   the next node is handed out only when the one before it settles. See
+ *   {@link CoordinatorOptions.maxConcurrent}.
  *
  * `runNode()`
  *   Claim one node, replay the graph through the real engine fenced to that
@@ -420,6 +478,12 @@ declare function durableApproval(submissions: Submissions): NodeExecutor;
  * A human gate returns `paused`. `runToCompletion` returns immediately when it
  * sees one — it does not spin, sleep or poll. The run is parked in the store,
  * the process is free, and a recorded answer is what starts the next job.
+ *
+ * A paused node keeps its dispatch slot, so under any finite `maxConcurrent`
+ * (serial, by default) a queue adapter's `advance()` hands out nothing
+ * alongside a gate while the person decides. Resuming releases the row — see
+ * `InMemoryClaimStore.release` — which frees the slot for the gate to run
+ * again.
  */
 
 /** What happened to one node. */
@@ -467,6 +531,19 @@ type CoordinatorOptions = {
     initialInputs?: Record<string, Record<string, unknown>>;
     retry?: RetryPolicy;
     onEvent?: (event: RunEvent) => void;
+    /**
+     * How many of this run's nodes may be HELD at once. Held means CLAIMED by a
+     * worker or PAUSED on a person: a paused gate keeps its slot.
+     *
+     * **Defaults to `1`: serial.** `advance()` hands out one node, and the next
+     * only once that one has settled, in the graph's declaration order.
+     *
+     * A positive integer raises the cap. `UNLIMITED_CONCURRENCY` (`0`) hands out
+     * the whole ready frontier at once, which is what every queued run did before
+     * this option existed. A negative, fractional or non-numeric value throws
+     * here, at construction.
+     */
+    maxConcurrent?: number;
 };
 declare class Coordinator {
     readonly graph: FlowGraph;
@@ -475,12 +552,21 @@ declare class Coordinator {
     readonly store: NodeClaimStore;
     readonly initialInputs: Record<string, Record<string, unknown>>;
     readonly retry: RetryPolicy;
+    /** The dispatch cap `advance()` applies. `0` is unlimited. */
+    readonly maxConcurrent: number;
     private readonly onEvent?;
     constructor(options: CoordinatorOptions);
     get runKey(): string;
     /**
      * Which nodes may be dispatched right now.
      *
+     * The ready frontier, cut to the run's {@link maxConcurrent} budget: the
+     * first `maxConcurrent - held` ready ids in declaration order, where `held`
+     * counts CLAIMED and PAUSED rows. Under the serial default that is at most one
+     * id, and none while a node is still running or a gate is waiting on a person.
+     * An empty result with work held is a throttled run, not a stalled one: the
+     * held node's settle is what calls this again.
+     *
      * Also settles the skip cascade, because a skip is a decision the frontier
      * just made and a second caller must not make it again.
      *
@@ -507,6 +593,12 @@ declare class Coordinator {
     /**
      * Drive the graph here, in this process, one node at a time.
      *
+     * It asks `advance()` exactly as a queue adapter does, so it runs nodes in the
+     * order a queued run under the same `maxConcurrent` would dispatch them. A run
+     * that finishes produces the same outputs under every limit. A run that stops
+     * on a pause or a failure can have run a different set of nodes before it
+     * stopped, because the order among nodes that are ready together differs.
+     *
      * Every checkpoint is written exactly as a queued run writes it, so a crash
      * mid-loop resumes from the same place a crashed worker would.
      *
@@ -561,4 +653,4 @@ declare class Coordinator {
     private forward;
 }
 
-export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, FENCE_PORT, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo };
+export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, FENCE_PORT, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNLIMITED_CONCURRENCY, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo, selectDispatch };

package/dist/durable/index.d.ts

@@ -108,6 +108,10 @@ declare class InMemoryClaimStore implements NodeClaimStore {
     /**
      * Drop a paused node's claim so a recorded answer can re-run it.
      *
+     * A PAUSED row holds one of the run's dispatch slots (see `selectDispatch`),
+     * so this is also what frees the slot: until the row is released, a serial
+     * run's `advance()` hands out nothing, the gate included.
+     *
      * Not part of the interface: resuming a human gate is the host's decision and
      * its storage's business. Provided here because the in-memory store is also
      * what the tests resume through.
@@ -180,6 +184,57 @@ declare const Frontier: {
     settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<string[]>;
 };
 
+/**
+ * How many of ONE run's nodes may be held at once, and which ready nodes go next.
+ *
+ * ## Serial is the default
+ *
+ * A queued run hands a node to the queue only once the node before it has
+ * settled: one node of a run held at a time, in the graph's own declaration
+ * order. Parallel dispatch of a ready frontier is something a host ASKS for,
+ * with `maxConcurrent` on the {@link Coordinator}.
+ *
+ * | `maxConcurrent` | meaning |
+ * |---|---|
+ * | unset | **1**: serial |
+ * | `N >= 1` | up to N of the run's nodes held at once |
+ * | {@link UNLIMITED_CONCURRENCY} (`0`) | the whole ready frontier |
+ * | anything else | refused, by name |
+ *
+ * A negative number is refused rather than read as "unlimited". Under a serial
+ * default, a typo that silently turned a run parallel is the failure to avoid.
+ *
+ * ## Held means claimed OR paused
+ *
+ * A node parked on a person keeps its slot. A pause does not park the whole run
+ * in this runtime: `advance()` is called whenever any job settles, and without
+ * this rule it would hand out the gate's siblings while the person is still
+ * deciding.
+ *
+ * ## Measured against held work, not the batch
+ *
+ * Two nodes settling at once each trigger an `advance()` on a real queue. A cap
+ * applied to one batch would let each of them dispatch its own quota, so the
+ * budget is `maxConcurrent - held`, counted off the claim rows.
+ *
+ * This is the TypeScript member of a three-runtime contract. The
+ * `flow/durable-dispatch` conformance suite pins it, and names
+ * `fancy-flow-php`'s `DispatchLimit` and the Python runtime's
+ * `fancy_flow.durable.select_dispatch` as the other two implementations.
+ */
+
+/** Dispatch the whole ready frontier. Named so a host never writes a bare `0`. */
+declare const UNLIMITED_CONCURRENCY = 0;
+/**
+ * The ready nodes that may be dispatched now, in the order given.
+ *
+ * `ready` comes from `Frontier.compute`, in declaration order, and that order is
+ * kept: this slices, it never sorts. `state` must already include any skips the
+ * frontier just settled. Skips are never held, so that changes no count, but the
+ * state must describe the run as it is after the decision.
+ */
+declare function selectDispatch(ready: readonly string[], state: Record<string, NodeState>, maxConcurrent: number): string[];
+
 /**
  * Run ONE node of a graph — through the real engine, not around it.
  *
@@ -396,7 +451,10 @@ declare function durableApproval(submissions: Submissions): NodeExecutor;
  *
  * `advance()`
  *   Ask the frontier what is unblocked, settle the skip cascade, and report the
- *   ready node ids. A queue adapter dispatches one job per id.
+ *   node ids that may be dispatched NOW. A queue adapter dispatches one job per
+ *   id. By default that is at most one id: a run holds one node at a time, and
+ *   the next node is handed out only when the one before it settles. See
+ *   {@link CoordinatorOptions.maxConcurrent}.
  *
  * `runNode()`
  *   Claim one node, replay the graph through the real engine fenced to that
@@ -420,6 +478,12 @@ declare function durableApproval(submissions: Submissions): NodeExecutor;
  * A human gate returns `paused`. `runToCompletion` returns immediately when it
  * sees one — it does not spin, sleep or poll. The run is parked in the store,
  * the process is free, and a recorded answer is what starts the next job.
+ *
+ * A paused node keeps its dispatch slot, so under any finite `maxConcurrent`
+ * (serial, by default) a queue adapter's `advance()` hands out nothing
+ * alongside a gate while the person decides. Resuming releases the row — see
+ * `InMemoryClaimStore.release` — which frees the slot for the gate to run
+ * again.
  */
 
 /** What happened to one node. */
@@ -467,6 +531,19 @@ type CoordinatorOptions = {
     initialInputs?: Record<string, Record<string, unknown>>;
     retry?: RetryPolicy;
     onEvent?: (event: RunEvent) => void;
+    /**
+     * How many of this run's nodes may be HELD at once. Held means CLAIMED by a
+     * worker or PAUSED on a person: a paused gate keeps its slot.
+     *
+     * **Defaults to `1`: serial.** `advance()` hands out one node, and the next
+     * only once that one has settled, in the graph's declaration order.
+     *
+     * A positive integer raises the cap. `UNLIMITED_CONCURRENCY` (`0`) hands out
+     * the whole ready frontier at once, which is what every queued run did before
+     * this option existed. A negative, fractional or non-numeric value throws
+     * here, at construction.
+     */
+    maxConcurrent?: number;
 };
 declare class Coordinator {
     readonly graph: FlowGraph;
@@ -475,12 +552,21 @@ declare class Coordinator {
     readonly store: NodeClaimStore;
     readonly initialInputs: Record<string, Record<string, unknown>>;
     readonly retry: RetryPolicy;
+    /** The dispatch cap `advance()` applies. `0` is unlimited. */
+    readonly maxConcurrent: number;
     private readonly onEvent?;
     constructor(options: CoordinatorOptions);
     get runKey(): string;
     /**
      * Which nodes may be dispatched right now.
      *
+     * The ready frontier, cut to the run's {@link maxConcurrent} budget: the
+     * first `maxConcurrent - held` ready ids in declaration order, where `held`
+     * counts CLAIMED and PAUSED rows. Under the serial default that is at most one
+     * id, and none while a node is still running or a gate is waiting on a person.
+     * An empty result with work held is a throttled run, not a stalled one: the
+     * held node's settle is what calls this again.
+     *
      * Also settles the skip cascade, because a skip is a decision the frontier
      * just made and a second caller must not make it again.
      *
@@ -507,6 +593,12 @@ declare class Coordinator {
     /**
      * Drive the graph here, in this process, one node at a time.
      *
+     * It asks `advance()` exactly as a queue adapter does, so it runs nodes in the
+     * order a queued run under the same `maxConcurrent` would dispatch them. A run
+     * that finishes produces the same outputs under every limit. A run that stops
+     * on a pause or a failure can have run a different set of nodes before it
+     * stopped, because the order among nodes that are ready together differs.
+     *
      * Every checkpoint is written exactly as a queued run writes it, so a crash
      * mid-loop resumes from the same place a crashed worker would.
      *
@@ -561,4 +653,4 @@ declare class Coordinator {
     private forward;
 }
 
-export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, FENCE_PORT, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo };
+export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, FENCE_PORT, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNLIMITED_CONCURRENCY, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo, selectDispatch };

package/dist/durable.cjs

@@ -72,6 +72,10 @@ var InMemoryClaimStore = class {
   /**
    * Drop a paused node's claim so a recorded answer can re-run it.
    *
+   * A PAUSED row holds one of the run's dispatch slots (see `selectDispatch`),
+   * so this is also what frees the slot: until the row is released, a serial
+   * run's `advance()` hands out nothing, the gate included.
+   *
    * Not part of the interface: resuming a human gate is the host's decision and
    * its storage's business. Provided here because the in-memory store is also
    * what the tests resume through.
@@ -2734,6 +2738,31 @@ var Frontier = {
   }
 };
 
+// src/durable/dispatch.ts
+var UNLIMITED_CONCURRENCY = 0;
+var DEFAULT_MAX_CONCURRENT = 1;
+function assertMaxConcurrent(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0) return value;
+  throw new RangeError(
+    `maxConcurrent must be a positive integer, or UNLIMITED_CONCURRENCY (0) for the whole ready frontier, or unset for serial; got ${describe(value)}.`
+  );
+}
+function selectDispatch(ready, state, maxConcurrent) {
+  const limit = assertMaxConcurrent(maxConcurrent);
+  if (limit === UNLIMITED_CONCURRENCY) return [...ready];
+  let held = 0;
+  for (const entry of Object.values(state)) {
+    if (entry.status === NodeRunStatus.CLAIMED || entry.status === NodeRunStatus.PAUSED) held++;
+  }
+  return ready.slice(0, Math.max(0, limit - held));
+}
+function describe(value) {
+  if (typeof value === "number") return String(value);
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === null) return "null";
+  return typeof value;
+}
+
 // src/durable/replay.ts
 var BOUNDARY = "fancy-flow:node-boundary";
 var FENCE_PORT = "fancy-flow:fenced";
@@ -2933,6 +2962,7 @@ var Coordinator = class {
     this.store = options.store ?? new InMemoryClaimStore();
     this.initialInputs = options.initialInputs ?? {};
     this.retry = options.retry ?? new RetryPolicy();
+    this.maxConcurrent = assertMaxConcurrent(options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT);
     this.onEvent = options.onEvent;
   }
   get runKey() {
@@ -2942,6 +2972,13 @@ var Coordinator = class {
   /**
    * Which nodes may be dispatched right now.
    *
+   * The ready frontier, cut to the run's {@link maxConcurrent} budget: the
+   * first `maxConcurrent - held` ready ids in declaration order, where `held`
+   * counts CLAIMED and PAUSED rows. Under the serial default that is at most one
+   * id, and none while a node is still running or a gate is waiting on a person.
+   * An empty result with work held is a throttled run, not a stalled one: the
+   * held node's settle is what calls this again.
+   *
    * Also settles the skip cascade, because a skip is a decision the frontier
    * just made and a second caller must not make it again.
    *
@@ -2957,7 +2994,12 @@ var Coordinator = class {
     const frontier = Frontier.compute(this.graph, state);
     const settled = await Frontier.settleSkips(this.store, this.runKey, frontier.skipped);
     this.warnForSkipped(settled, state);
-    return frontier.ready;
+    const after = { ...state };
+    for (const nodeId of frontier.skipped) {
+      const row = state[nodeId];
+      after[nodeId] = row ? { ...row, status: NodeRunStatus.SKIPPED, ports: [] } : { status: NodeRunStatus.SKIPPED, ports: [], attempts: 0, firstAttemptAt: "" };
+    }
+    return selectDispatch(frontier.ready, after, this.maxConcurrent);
   }
   /**
    * Claim, execute and checkpoint one node.
@@ -3019,6 +3061,12 @@ var Coordinator = class {
   /**
    * Drive the graph here, in this process, one node at a time.
    *
+   * It asks `advance()` exactly as a queue adapter does, so it runs nodes in the
+   * order a queued run under the same `maxConcurrent` would dispatch them. A run
+   * that finishes produces the same outputs under every limit. A run that stops
+   * on a pause or a failure can have run a different set of nodes before it
+   * stopped, because the order among nodes that are ready together differs.
+   *
    * Every checkpoint is written exactly as a queued run writes it, so a crash
    * mid-loop resumes from the same place a crashed worker would.
    *
@@ -3027,7 +3075,7 @@ var Coordinator = class {
    * claim with the same owner token — so the step key it derives is unchanged,
    * which is what makes the retry idempotent rather than duplicative.
    */
-  async runToCompletion(maxPasses = 1e4) {
+  async runToCompletion(maxPasses = Math.max(1e4, this.graph.nodes.length + 1)) {
     for (let pass = 0; pass < maxPasses; pass++) {
       const ready = await this.advance();
       if (ready.length === 0) break;
@@ -3185,11 +3233,13 @@ exports.NotAwaitingHuman = NotAwaitingHuman;
 exports.RetryPolicy = RetryPolicy;
 exports.SETTLED = SETTLED;
 exports.Submissions = Submissions;
+exports.UNLIMITED_CONCURRENCY = UNLIMITED_CONCURRENCY;
 exports.UNSAFE_TO_REPLAY = UNSAFE_TO_REPLAY;
 exports.durableApproval = durableApproval;
 exports.durableUserInput = durableUserInput;
 exports.isBoundary = isBoundary;
 exports.isSettled = isSettled;
 exports.replayUpTo = replayUpTo;
+exports.selectDispatch = selectDispatch;
 //# sourceMappingURL=durable.cjs.map
 //# sourceMappingURL=durable.cjs.map