@particle-academy/fancy-flow 0.45.0 → 0.46.0

package/dist/registry.js

@@ -1,10 +1,10 @@
-export { ANY_PORT_TYPE, BUILTIN_KINDS, DEFAULT_MAX_DEPTH, RegistryNode, buildNodeTypes, createConnectionValidator, declaredRoutes, defaultPortCompatibility, llmRouterExecutor as llmBranchExecutor, llmRouterExecutor, registerBuiltinKinds, resolveFallbackPort, subflowExecutor, subflowMode, subflowPorts } from './chunk-WBXGZVLB.js';
+export { ANY_PORT_TYPE, BUILTIN_KINDS, DEFAULT_MAX_DEPTH, RegistryNode, buildNodeTypes, createConnectionValidator, declaredRoutes, defaultPortCompatibility, llmRouterExecutor as llmBranchExecutor, llmRouterExecutor, registerBuiltinKinds, resolveFallbackPort, subflowExecutor, subflowMode, subflowPorts } from './chunk-RMU6YCIQ.js';
+export { RichInputPreview, getRichInputAdapter, isRichInputEnabled, onRichInputAdapterChanged, registerRichInputAdapter } from './chunk-F5RPRB7A.js';
 import './chunk-OWENS2H5.js';
-export { LEGACY_PAUSE_PREFIXES, PAUSE_PREFIX, decodePause, encodePause, isPause, pauseForHuman } from './chunk-UEOE6B52.js';
 export { capabilityStatus, getLlmClient, getWorkflowResolver, isResolutionFailure, registerLlmClient, registerWorkflowResolver } from './chunk-USL4FMFU.js';
-import './chunk-VLATLVGH.js';
+export { LEGACY_PAUSE_PREFIXES, PAUSE_PREFIX, decodePause, encodePause, isPause, pauseForHuman } from './chunk-UEOE6B52.js';
+import './chunk-L43CWD63.js';
 export { nodeConfig, resolveNodePorts, resolvePortSpec } from './chunk-TITD5W4Y.js';
 export { categoryAccent, clearNodeKindOverrides, defaultConfigFor, getNodeKind, kindIds, listNodeKinds, onNodeKindsChanged, overrideNodeKind, registerNodeKind, resolveKindId, validateConfig } from './chunk-PVROYW7C.js';
-export { RichInputPreview, getRichInputAdapter, isRichInputEnabled, onRichInputAdapterChanged, registerRichInputAdapter } from './chunk-F5RPRB7A.js';
 //# sourceMappingURL=registry.js.map
 //# sourceMappingURL=registry.js.map

package/dist/{run-cohort-CV7EcwGG.d.ts → run-cohort-Cyeny2Uu.d.ts}

@@ -1,36 +1,5 @@
-import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-CMSrWVYM.js';
-
-type RunOptions = {
-    /** Stop the run after this many ms. Default: no timeout. */
-    timeoutMs?: number;
-    /** Abort signal — host can cancel the run. */
-    signal?: AbortSignal;
-    /** Initial inputs supplied to entry-point nodes (no incoming edges). */
-    initialInputs?: Record<string, Record<string, unknown>>;
-    /** Nesting depth — set by `subflow` when it runs a child graph. */
-    depth?: number;
-};
-type RunResult = {
-    ok: boolean;
-    /** Outputs collected per node, keyed by node id. */
-    outputs: Record<string, unknown>;
-    /** Error captured if any node threw. */
-    error?: string;
-};
-/**
- * runFlow — topological execution of a FlowGraph against an ExecutorRegistry.
- *
- * Each node runs once, when all upstream nodes have produced outputs on the
- * connected ports. Decision nodes (or any executor that returns `{ branch:
- * 'true' }`) can short-circuit specific output ports — only edges leaving
- * an "active" port propagate to downstream nodes.
- *
- * Cycles are detected and abort the run with an error.
- *
- * The `onEvent` callback receives a stream of `RunEvent`s — wire it to a
- * status feed, log panel, or store.
- */
-declare function runFlow(graph: FlowGraph, executors: ExecutorRegistry, onEvent?: (event: RunEvent) => void, options?: RunOptions): Promise<RunResult>;
+import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-Jx1TwehV.js';
+import { R as RunOptions, a as RunResult } from './run-flow-CQvTDBYk.js';
 
 /**
  * How the flows one trigger fired should treat each other.
@@ -108,4 +77,4 @@ type CohortResult = RunResult & {
  */
 declare function runCohort(flows: FlowGraph[], executors: ExecutorRegistry, onEvent?: (event: RunEvent, index: number) => void, options?: CohortOptions): Promise<CohortResult[]>;
 
-export { type CohortGuard as C, type RunOptions as R, type CohortOptions as a, type CohortPolicy as b, type CohortResult as c, type RunResult as d, runFlow as e, runCohort as r };
+export { type CohortGuard as C, type CohortOptions as a, type CohortPolicy as b, type CohortResult as c, runCohort as r };

package/dist/{run-cohort-DitsaYgS.d.cts → run-cohort-DdPPowJ3.d.cts}

@@ -1,36 +1,5 @@
-import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-CMSrWVYM.cjs';
-
-type RunOptions = {
-    /** Stop the run after this many ms. Default: no timeout. */
-    timeoutMs?: number;
-    /** Abort signal — host can cancel the run. */
-    signal?: AbortSignal;
-    /** Initial inputs supplied to entry-point nodes (no incoming edges). */
-    initialInputs?: Record<string, Record<string, unknown>>;
-    /** Nesting depth — set by `subflow` when it runs a child graph. */
-    depth?: number;
-};
-type RunResult = {
-    ok: boolean;
-    /** Outputs collected per node, keyed by node id. */
-    outputs: Record<string, unknown>;
-    /** Error captured if any node threw. */
-    error?: string;
-};
-/**
- * runFlow — topological execution of a FlowGraph against an ExecutorRegistry.
- *
- * Each node runs once, when all upstream nodes have produced outputs on the
- * connected ports. Decision nodes (or any executor that returns `{ branch:
- * 'true' }`) can short-circuit specific output ports — only edges leaving
- * an "active" port propagate to downstream nodes.
- *
- * Cycles are detected and abort the run with an error.
- *
- * The `onEvent` callback receives a stream of `RunEvent`s — wire it to a
- * status feed, log panel, or store.
- */
-declare function runFlow(graph: FlowGraph, executors: ExecutorRegistry, onEvent?: (event: RunEvent) => void, options?: RunOptions): Promise<RunResult>;
+import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-Jx1TwehV.cjs';
+import { R as RunOptions, a as RunResult } from './run-flow-1KiXhy59.cjs';
 
 /**
  * How the flows one trigger fired should treat each other.
@@ -108,4 +77,4 @@ type CohortResult = RunResult & {
  */
 declare function runCohort(flows: FlowGraph[], executors: ExecutorRegistry, onEvent?: (event: RunEvent, index: number) => void, options?: CohortOptions): Promise<CohortResult[]>;
 
-export { type CohortGuard as C, type RunOptions as R, type CohortOptions as a, type CohortPolicy as b, type CohortResult as c, type RunResult as d, runFlow as e, runCohort as r };
+export { type CohortGuard as C, type CohortOptions as a, type CohortPolicy as b, type CohortResult as c, runCohort as r };

package/dist/run-flow-1KiXhy59.d.cts

@@ -0,0 +1,55 @@
+import { b as RunIdentity, c as RunIdentityJson, F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-Jx1TwehV.cjs';
+
+type RunOptions = {
+    /** Stop the run after this many ms. Default: no timeout. */
+    timeoutMs?: number;
+    /** Abort signal — host can cancel the run. */
+    signal?: AbortSignal;
+    /** Initial inputs supplied to entry-point nodes (no incoming edges). */
+    initialInputs?: Record<string, Record<string, unknown>>;
+    /** Nesting depth — set by `subflow` when it runs a child graph. */
+    depth?: number;
+    /**
+     * Who is running, so a writing node can derive a stable idempotency key.
+     *
+     * A bare string is taken as the run key. **Deliberately not defaulted:** a
+     * minted-per-call key would change on every whole-run retry, which is exactly
+     * the failure an idempotency key exists to prevent — so a host that has not
+     * supplied one gets `ctx.run === undefined` and a connector that declines to
+     * write blind, rather than a plausible-looking key that double-charges.
+     */
+    run?: RunIdentity | RunIdentityJson | string;
+    /**
+     * Outputs already checkpointed for this run, keyed by node id.
+     *
+     * A node present here is **republished, not re-executed** — its stored value
+     * goes back onto the same ports, so downstream routing reproduces exactly
+     * what it did the first time. This is what makes a per-node durable driver
+     * possible without a second copy of the routing rules, and it is how the PHP
+     * and Python runtimes have always resumed.
+     */
+    resumeOutputs?: Record<string, unknown>;
+};
+type RunResult = {
+    ok: boolean;
+    /** Outputs collected per node, keyed by node id. */
+    outputs: Record<string, unknown>;
+    /** Error captured if any node threw. */
+    error?: string;
+};
+/**
+ * runFlow — topological execution of a FlowGraph against an ExecutorRegistry.
+ *
+ * Each node runs once, when all upstream nodes have produced outputs on the
+ * connected ports. Decision nodes (or any executor that returns `{ branch:
+ * 'true' }`) can short-circuit specific output ports — only edges leaving
+ * an "active" port propagate to downstream nodes.
+ *
+ * Cycles are detected and abort the run with an error.
+ *
+ * The `onEvent` callback receives a stream of `RunEvent`s — wire it to a
+ * status feed, log panel, or store.
+ */
+declare function runFlow(graph: FlowGraph, executors: ExecutorRegistry, onEvent?: (event: RunEvent) => void, options?: RunOptions): Promise<RunResult>;
+
+export { type RunOptions as R, type RunResult as a, runFlow as r };

package/dist/run-flow-CQvTDBYk.d.ts

@@ -0,0 +1,55 @@
+import { b as RunIdentity, c as RunIdentityJson, F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-Jx1TwehV.js';
+
+type RunOptions = {
+    /** Stop the run after this many ms. Default: no timeout. */
+    timeoutMs?: number;
+    /** Abort signal — host can cancel the run. */
+    signal?: AbortSignal;
+    /** Initial inputs supplied to entry-point nodes (no incoming edges). */
+    initialInputs?: Record<string, Record<string, unknown>>;
+    /** Nesting depth — set by `subflow` when it runs a child graph. */
+    depth?: number;
+    /**
+     * Who is running, so a writing node can derive a stable idempotency key.
+     *
+     * A bare string is taken as the run key. **Deliberately not defaulted:** a
+     * minted-per-call key would change on every whole-run retry, which is exactly
+     * the failure an idempotency key exists to prevent — so a host that has not
+     * supplied one gets `ctx.run === undefined` and a connector that declines to
+     * write blind, rather than a plausible-looking key that double-charges.
+     */
+    run?: RunIdentity | RunIdentityJson | string;
+    /**
+     * Outputs already checkpointed for this run, keyed by node id.
+     *
+     * A node present here is **republished, not re-executed** — its stored value
+     * goes back onto the same ports, so downstream routing reproduces exactly
+     * what it did the first time. This is what makes a per-node durable driver
+     * possible without a second copy of the routing rules, and it is how the PHP
+     * and Python runtimes have always resumed.
+     */
+    resumeOutputs?: Record<string, unknown>;
+};
+type RunResult = {
+    ok: boolean;
+    /** Outputs collected per node, keyed by node id. */
+    outputs: Record<string, unknown>;
+    /** Error captured if any node threw. */
+    error?: string;
+};
+/**
+ * runFlow — topological execution of a FlowGraph against an ExecutorRegistry.
+ *
+ * Each node runs once, when all upstream nodes have produced outputs on the
+ * connected ports. Decision nodes (or any executor that returns `{ branch:
+ * 'true' }`) can short-circuit specific output ports — only edges leaving
+ * an "active" port propagate to downstream nodes.
+ *
+ * Cycles are detected and abort the run with an error.
+ *
+ * The `onEvent` callback receives a stream of `RunEvent`s — wire it to a
+ * status feed, log panel, or store.
+ */
+declare function runFlow(graph: FlowGraph, executors: ExecutorRegistry, onEvent?: (event: RunEvent) => void, options?: RunOptions): Promise<RunResult>;
+
+export { type RunOptions as R, type RunResult as a, runFlow as r };

package/dist/runtime/index.d.cts

@@ -1,6 +1,8 @@
-import { d as RunResult, R as RunOptions } from '../run-cohort-DitsaYgS.cjs';
-export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort, e as runFlow } from '../run-cohort-DitsaYgS.cjs';
-import { e as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, a as FlowNode, b as FlowEdge } from '../types-CMSrWVYM.cjs';
+import { a as RunResult, R as RunOptions } from '../run-flow-1KiXhy59.cjs';
+export { r as runFlow } from '../run-flow-1KiXhy59.cjs';
+import { g as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, a as FlowNode, d as FlowEdge } from '../types-Jx1TwehV.cjs';
+export { b as RunIdentity, c as RunIdentityJson, i as escapeSegment } from '../types-Jx1TwehV.cjs';
+export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort } from '../run-cohort-DdPPowJ3.cjs';
 import { NodeChange, EdgeChange, Connection } from '@xyflow/react';
 
 type FlowRunFeedEntry = {

package/dist/runtime/index.d.ts

@@ -1,6 +1,8 @@
-import { d as RunResult, R as RunOptions } from '../run-cohort-CV7EcwGG.js';
-export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort, e as runFlow } from '../run-cohort-CV7EcwGG.js';
-import { e as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, a as FlowNode, b as FlowEdge } from '../types-CMSrWVYM.js';
+import { a as RunResult, R as RunOptions } from '../run-flow-CQvTDBYk.js';
+export { r as runFlow } from '../run-flow-CQvTDBYk.js';
+import { g as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, a as FlowNode, d as FlowEdge } from '../types-Jx1TwehV.js';
+export { b as RunIdentity, c as RunIdentityJson, i as escapeSegment } from '../types-Jx1TwehV.js';
+export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort } from '../run-cohort-Cyeny2Uu.js';
 import { NodeChange, EdgeChange, Connection } from '@xyflow/react';
 
 type FlowRunFeedEntry = {

package/dist/runtime.cjs

@@ -53,10 +53,121 @@ function resolveNodePorts(node, kind) {
   };
 }
 
+// src/runtime/run-identity.ts
+function escapeSegment(value) {
+  return value.replace(/%/g, "%25").replace(/\//g, "%2F").replace(/#/g, "%23");
+}
+function renderSegment(value, occurrence) {
+  const escaped = escapeSegment(value);
+  return occurrence === void 0 || occurrence === null ? escaped : `${escaped}#${occurrence}`;
+}
+function instant(value) {
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new Error(
+      `RunIdentity: firstAttemptAt is not a parseable timestamp: ${JSON.stringify(value)}`
+    );
+  }
+  return ms;
+}
+var RunIdentity = class _RunIdentity {
+  constructor(runKey, path = [], attempt = 1, firstAttemptAt = (/* @__PURE__ */ new Date()).toISOString()) {
+    if (!runKey || runKey.trim() === "") {
+      throw new Error("RunIdentity: runKey must be a non-empty string.");
+    }
+    this.runKey = runKey;
+    this.path = Object.freeze([...path]);
+    this.attempt = Math.max(1, Math.trunc(attempt));
+    this.firstAttemptAt = firstAttemptAt;
+    Object.freeze(this);
+  }
+  /**
+   * The identity of one execution of one node — stable across retries of that
+   * execution, distinct from every other execution of the same node.
+   *
+   * Pass `occurrence` when an executor runs the same node more than once at the
+   * same level (a loop body, one item of a fan-out it drives itself).
+   */
+  stepKey(nodeId, occurrence) {
+    return `${this.runKey}:${[...this.path, renderSegment(nodeId, occurrence)].join("/")}`;
+  }
+  /**
+   * A child identity for work nested inside this step.
+   *
+   * `subflow` pushes the invoking node's id, so a node inside the child graph
+   * cannot collide with a same-named node in the parent. Attempt and
+   * `firstAttemptAt` are carried down unchanged: the nested work happens inside
+   * this step's attempt, and shares its clock.
+   */
+  descend(segment, occurrence) {
+    return new _RunIdentity(
+      this.runKey,
+      [...this.path, renderSegment(segment, occurrence)],
+      this.attempt,
+      this.firstAttemptAt
+    );
+  }
+  /** A copy on a different attempt, first-attempt clock preserved. */
+  withAttempt(attempt, firstAttemptAt) {
+    return new _RunIdentity(
+      this.runKey,
+      this.path,
+      attempt,
+      firstAttemptAt ?? this.firstAttemptAt
+    );
+  }
+  /**
+   * May this attempt reuse the step key and still be deduplicated?
+   *
+   * Providers forget idempotency keys — Stripe after 24 hours. Past that
+   * window, resending the key creates a second charge and sending a fresh one
+   * creates a second charge, so **the caller must refuse rather than pick
+   * between them**: a loud stuck run beats a silent double write.
+   *
+   * `true` on attempt 1 whatever the elapsed time — nothing was sent on an
+   * earlier attempt, so there is nothing for the provider to have forgotten.
+   * That is what lets a run park on a human gate for a week and then write.
+   *
+   * `windowSeconds: null` means the provider does not expire keys. `0` means
+   * it does not dedupe at all, so no retry may reuse a key — it is a real
+   * window, not an absent one, and the two must not be conflated: reading `0`
+   * as `null` turns "this provider does not dedupe" into "this provider
+   * dedupes forever", which is the more dangerous of the two by a distance.
+   */
+  isReplaySafe(windowSeconds, now2 = /* @__PURE__ */ new Date()) {
+    if (this.attempt <= 1) return true;
+    if (windowSeconds === null || windowSeconds === void 0) return true;
+    if (windowSeconds <= 0) return false;
+    const nowMs = typeof now2 === "string" ? instant(now2) : now2.getTime();
+    const elapsedSeconds = Math.max(0, (nowMs - instant(this.firstAttemptAt)) / 1e3);
+    return elapsedSeconds <= windowSeconds;
+  }
+  toJSON() {
+    return {
+      runKey: this.runKey,
+      path: [...this.path],
+      attempt: this.attempt,
+      firstAttemptAt: this.firstAttemptAt
+    };
+  }
+  /** Rebuild from a queue payload. */
+  static from(value) {
+    if (value instanceof _RunIdentity) return value;
+    if (typeof value === "string") return new _RunIdentity(value);
+    return new _RunIdentity(
+      value.runKey,
+      value.path ?? [],
+      value.attempt ?? 1,
+      value.firstAttemptAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    );
+  }
+};
+
 // src/runtime/run-flow.ts
 async function runFlow(graph, executors, onEvent = () => {
 }, options = {}) {
-  const { signal, initialInputs = {}, timeoutMs, depth = 0 } = options;
+  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {} } = options;
+  const run = options.run === void 0 ? void 0 : RunIdentity.from(options.run);
   const outputs = {};
   const portValues = /* @__PURE__ */ new Map();
   const completed = /* @__PURE__ */ new Set();
@@ -74,6 +185,18 @@ async function runFlow(graph, executors, onEvent = () => {
     for (const node of order) {
       if (signal?.aborted) throw new Error("aborted");
       if (errors.length) break;
+      if (Object.prototype.hasOwnProperty.call(resumeOutputs, node.id)) {
+        const stored = resumeOutputs[node.id];
+        outputs[node.id] = stored;
+        const activated = activatedPorts(node, stored);
+        for (const portId of activated.ports) {
+          portValues.set(`${node.id}:${portId}`, activated.value);
+          onEvent({ type: "node-output", nodeId: node.id, portId, value: activated.value });
+        }
+        completed.add(node.id);
+        onEvent({ type: "node-status", nodeId: node.id, status: "done", text: "resumed" });
+        continue;
+      }
       const incoming = incomingByNode.get(node.id) ?? [];
       if (incoming.length > 0) {
         const anyActive = incoming.some((e) => portValues.has(`${e.source}:${e.sourceHandle ?? "out"}`));
@@ -113,7 +236,8 @@ async function runFlow(graph, executors, onEvent = () => {
               throw new Error(reason ?? "aborted");
             },
             emit: onEvent,
-            depth
+            depth,
+            run
           })
         );
         outputs[node.id] = result;
@@ -9378,9 +9502,11 @@ function useFlowHistory(flow) {
   };
 }
 
+exports.RunIdentity = RunIdentity;
 exports.applyOutputsToNodes = applyOutputsToNodes;
 exports.applyStatusesToNodes = applyStatusesToNodes;
 exports.createHistory = createHistory;
+exports.escapeSegment = escapeSegment;
 exports.runCohort = runCohort;
 exports.runFlow = runFlow;
 exports.useFlowHistory = useFlowHistory;