@particle-academy/fancy-flow 0.44.0 → 0.46.0

package/dist/fields/react-fancy.d.cts

@@ -1,8 +1,9 @@
-import { C as ConfigFieldRenderFn } from '../ConfigFieldRenderer-LotNHeG8.cjs';
+import { C as ConfigFieldRenderFn } from '../ConfigFieldRenderer-Cyir8-B8.cjs';
 import 'react';
-import '../types-sOmpCitB.cjs';
+import '../types-Jx1TwehV.cjs';
 import '@xyflow/react';
-import '../types-B78Rm69S.cjs';
+import '../types--S2Kzx7w.cjs';
+import '../pause-9iT4tCEV.cjs';
 
 /**
  * Render a `json` config field as a react-fancy `JsonEditor`.

package/dist/fields/react-fancy.d.ts

@@ -1,8 +1,9 @@
-import { C as ConfigFieldRenderFn } from '../ConfigFieldRenderer-BHQDZer6.js';
+import { C as ConfigFieldRenderFn } from '../ConfigFieldRenderer-iMkZj0VK.js';
 import 'react';
-import '../types-sOmpCitB.js';
+import '../types-Jx1TwehV.js';
 import '@xyflow/react';
-import '../types-JViq8reb.js';
+import '../types-ChkCRonF.js';
+import '../pause-9iT4tCEV.js';
 
 /**
  * Render a `json` config field as a react-fancy `JsonEditor`.

package/dist/index.cjs

@@ -11172,10 +11172,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();
@@ -11193,6 +11304,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"}`));
@@ -11232,7 +11355,8 @@ async function runFlow(graph, executors, onEvent = () => {
               throw new Error(reason ?? "aborted");
             },
             emit: onEvent,
-            depth
+            depth,
+            run
           })
         );
         outputs[node.id] = result;
@@ -11385,7 +11509,13 @@ var subflowExecutor = async (ctx) => {
         // require no configuration at all.
         __parent: ctx.inputs
       },
-      depth: depth + 1
+      depth: depth + 1,
+      // Push THIS node onto the identity path, so a node inside the child graph
+      // cannot share an idempotency key with a same-named node in the parent —
+      // or with the same child graph invoked from a different parent node.
+      // Attempt and the first-attempt clock ride down unchanged: the child's
+      // work happens inside this node's attempt.
+      run: ctx.run?.descend(ctx.node.id)
     }
   );
   if (!result.ok) {