@particle-academy/fancy-flow 0.72.1 → 0.74.0

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