@particle-academy/fancy-flow 0.72.0 → 0.73.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.
@@ -720,7 +724,7 @@ function resolveWorkflowProps(declared, passed) {
 // src/runtime/run-flow.ts
 async function runFlow(graph, executors, onEvent = () => {
 }, options = {}) {
-  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {}, entryNodes } = options;
+  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {}, entryNodes, nodeExecutors } = options;
   const run = options.run === void 0 ? void 0 : RunIdentity.from(options.run);
   const outputs = {};
   const portValues = /* @__PURE__ */ new Map();
@@ -808,7 +812,7 @@ async function runFlow(graph, executors, onEvent = () => {
       onEvent({ type: "node-status", nodeId: node.id, status: "running" });
       announce(onEvent, node, "start");
       const inputs = collectInputs(node, incoming, portValues, initialInputs, props, declaresProps);
-      const exec = pickExecutor(executors, node);
+      const exec = pickExecutor(executors, node, nodeExecutors);
       if (!exec) {
         const tried = executorLookupIds(node);
         const msg = `No executor registered for kind=${node.type} \u2014 tried ${tried.map((id) => `"${id}"`).join(", ")}. Key your registry by one of those.`;
@@ -928,7 +932,9 @@ function executorLookupIds(node) {
   ids.push("*");
   return [...new Set(ids)];
 }
-function pickExecutor(executors, node) {
+function pickExecutor(executors, node, nodeExecutors) {
+  const pinned = nodeExecutors && Object.prototype.hasOwnProperty.call(nodeExecutors, node.id) ? nodeExecutors[node.id] : void 0;
+  if (pinned) return pinned;
   for (const id of executorLookupIds(node)) {
     if (executors[id]) return executors[id];
   }
@@ -2732,14 +2738,43 @@ 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";
 async function replayUpTo(graph, nodeId, executors, options = {}) {
-  const fenced = { ...executors };
+  const fencedOff = /* @__PURE__ */ new Set();
+  const fence = (ctx) => {
+    fencedOff.add(ctx.node.id);
+    return { __port: FENCE_PORT, value: null };
+  };
+  const fences = {};
   for (const node of graph.nodes) {
-    if (node.id !== nodeId) {
-      fenced[node.id] = (ctx) => ctx.abort(BOUNDARY);
-    }
+    if (node.id !== nodeId) fences[node.id] = fence;
   }
   const ports = {};
   const collect = (event) => {
@@ -2749,12 +2784,17 @@ async function replayUpTo(graph, nodeId, executors, options = {}) {
     }
     options.onEvent?.(event);
   };
-  const result = await runFlow(graph, fenced, collect, {
+  const result = await runFlow(graph, executors, collect, {
     initialInputs: options.initialInputs ?? {},
     resumeOutputs: options.resumeOutputs ?? {},
     depth: options.depth ?? 0,
-    run: options.run
+    run: options.run,
+    nodeExecutors: fences
   });
+  for (const id of fencedOff) {
+    delete result.outputs[id];
+    delete ports[id];
+  }
   return {
     result,
     ports,
@@ -2922,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() {
@@ -2931,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.
    *
@@ -2946,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.
@@ -2985,12 +3038,12 @@ var Coordinator = class {
       await this.store.pause(this.runKey, nodeId, result.error ?? "");
       return { nodeId, status: "paused", pause, claimed: true, attempt };
     }
-    if (isBoundary(result.error)) {
+    if (isBoundary(result.error) || result.ok) {
       await this.store.skip(this.runKey, nodeId);
       return {
         nodeId,
         status: "skipped",
-        error: "replay stopped before reaching this node",
+        error: "the engine found no live inbound edge for this node",
         claimed: true,
         attempt
       };
@@ -3008,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.
    *
@@ -3016,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;
@@ -3166,6 +3225,7 @@ function cryptoRandom() {
 
 exports.BOUNDARY = BOUNDARY;
 exports.Coordinator = Coordinator;
+exports.FENCE_PORT = FENCE_PORT;
 exports.Frontier = Frontier;
 exports.InMemoryClaimStore = InMemoryClaimStore;
 exports.NodeRunStatus = NodeRunStatus;
@@ -3173,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