fyflow-orchestration 0.10.0 → 0.11.0

package/dist/node/chunks/{chunk-NA6QQAZ2.js → chunk-5CVSWDCB.js}

@@ -416,7 +416,10 @@ function evaluateDeclared(when, scope, unknownOp) {
 // src/definition/validate.ts
 var ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 var KINDS = ["task", "fanout", "map", "join", "end", "gate", "ask"];
+var ID_RE_COPY = new RegExp(ID_RE.source, ID_RE.flags);
+var KINDS_COPY = Object.freeze([...KINDS]);
 var ROUTABLE = ["done", "failed"];
+var ROUTABLE_STATES = [...ROUTABLE];
 var DOC_KEYS = ["flowId", "version", "entry", "nodes"];
 var NODE_KEYS = {
   // `retryPolicy` and `workerGroups` since v0.16 (W58): what a node says about its OWN task,
@@ -451,6 +454,11 @@ var TASK_KEYS_DECLARED = [...NODE_KEYS.task.req, ...NODE_KEYS.task.opt];
 var NODE_KEYS_DECLARED = Object.fromEntries(
   Object.entries(NODE_KEYS).map(([kind, k]) => [kind, [...k.req, ...k.opt]])
 );
+var NODE_KEYS_REQUIRED = Object.fromEntries(
+  Object.entries(NODE_KEYS).map(([kind, k]) => [kind, [...k.req]])
+);
+var EDGE_KEYS_REQUIRED = [...EDGE_KEYS.req];
+var DOC_KEYS_DECLARED = [...DOC_KEYS];
 var RETRY_POLICY_KEYS = ["maxRetries", "backoffMs"];
 function retryPolicyProblem(v) {
   if (typeof v !== "object" || v === null || Array.isArray(v)) {
@@ -958,10 +966,35 @@ function referenceTarget(ref) {
   }
   return null;
 }
+var ERROR_PART = "!error";
 function aimed(s, form) {
   const conditional = s.endsWith("?");
-  const node = conditional ? s.slice(0, -1) : s;
-  return ID_RE.test(node) ? { form, node, conditional } : null;
+  const body = conditional ? s.slice(0, -1) : s;
+  const error = body.endsWith(ERROR_PART);
+  const node = error ? body.slice(0, -ERROR_PART.length) : body;
+  if (!ID_RE.test(node)) return null;
+  return error ? { form, node, conditional, part: "error" } : { form, node, conditional };
+}
+var spelled = (t, conditional) => `${t.node}${t.part === "error" ? ERROR_PART : ""}${conditional ? "?" : ""}`;
+function bangProblem(ref) {
+  const array = Array.isArray(ref) && ref.length === 1;
+  const one = array ? ref[0] : ref;
+  if (typeof one !== "string" || one.startsWith("$") || !one.includes("!")) return null;
+  const wrap = (s) => JSON.stringify(array ? [s] : s);
+  const at = one.indexOf("!");
+  const before = one.slice(0, at);
+  const after = one.slice(at + 1);
+  const afterBare = after.endsWith("?") ? after.slice(0, -1) : after;
+  if (afterBare === "error" && before.endsWith("?") && ID_RE.test(before.slice(0, -1))) {
+    return `${JSON.stringify(ref)} carries "?" before "!error", and the suffix goes last: write ${wrap(`${before.slice(0, -1)}!error?`)}`;
+  }
+  if (before === "") {
+    return `${JSON.stringify(ref)} names no node before "!": write the node whose error you mean first, as ${wrap(`<node>!error${one.endsWith("?") ? "?" : ""}`)}`;
+  }
+  if (afterBare !== "error" && ID_RE.test(before)) {
+    return `${JSON.stringify(ref)} names "${after}" after "!", and the one part of a node's outcome a reference may name is its error: write ${wrap(`${before}!error${after.endsWith("?") ? "?" : ""}`)}, or ${wrap(`${before}${after.endsWith("?") ? "?" : ""}`)} for its result`;
+  }
+  return null;
 }
 var PAYLOAD_TOKEN = "$payload";
 var ITEM_TOKEN = "$item";
@@ -1252,10 +1285,13 @@ function validateDefinition(doc, registry) {
           if (!ID_RE.test(k)) add("FD-V26", where, `needs key ${JSON.stringify(k)} is not [A-Za-z0-9_-]{1,64}`);
           const target = referenceTarget(ref);
           const dollar = target === null ? dollarProblem(ref) : null;
+          const bang = target === null && dollar === null ? bangProblem(ref) : null;
           if (dollar !== null) {
             add("FD-V26", where, `needs[${JSON.stringify(k)}]: ${dollar}`);
+          } else if (bang !== null) {
+            add("FD-V26", where, `needs[${JSON.stringify(k)}]: ${bang}`);
           } else if (target === null) {
-            add("FD-V26", where, `needs[${JSON.stringify(k)}] is ${JSON.stringify(ref)}, which is not "." , "$payload", "$item", a node id with an optional "?" suffix, or a one-element array holding one`);
+            add("FD-V26", where, `needs[${JSON.stringify(k)}] is ${JSON.stringify(ref)}, which is not "." , "$payload", "$item", a node id with an optional "!error" and an optional "?" suffix, or a one-element array holding one`);
           }
         }
       }
@@ -1318,10 +1354,13 @@ function validateDefinition(doc, registry) {
             if (!ID_RE.test(k)) add("FD-V26", at, `edge needs key ${JSON.stringify(k)} is not [A-Za-z0-9_-]{1,64}`);
             const target = referenceTarget(ref);
             const dollar = target === null ? dollarProblem(ref) : null;
+            const bang = target === null && dollar === null ? bangProblem(ref) : null;
             if (dollar !== null) {
               add("FD-V26", at, `edge needs[${JSON.stringify(k)}]: ${dollar}`);
+            } else if (bang !== null) {
+              add("FD-V26", at, `edge needs[${JSON.stringify(k)}]: ${bang}`);
             } else if (target === null) {
-              add("FD-V26", at, `edge needs[${JSON.stringify(k)}] is ${JSON.stringify(ref)}, which is not "$payload", "$item", a node id with an optional "?" suffix or a one-element array holding one`);
+              add("FD-V26", at, `edge needs[${JSON.stringify(k)}] is ${JSON.stringify(ref)}, which is not "$payload", "$item", a node id with an optional "!error" and an optional "?" suffix or a one-element array holding one`);
             } else if (target.form === "self") {
               add("FD-V26", at, `edge needs[${JSON.stringify(k)}] is ".", which an EDGE may not use: what a predicate would have received anyway is its node's own outcome, and \`ctx.outcome\` already carries it`);
             }
@@ -1502,14 +1541,14 @@ function validateDefinition(doc, registry) {
           add(
             "FD-V29",
             at,
-            `${site}[${JSON.stringify(k)}] names "${target}" unconditionally, and a run can reach this node without "${target}" having run \u2014 a decision routes around it, or it is inside a region whose branch may be lost before it is entered. \`FD-V27\` checked that this node is reachable FROM it, which is weaker. Write "${target}?"${t.form === "all" ? " inside the array" : ""} if you mean *if it ran*, and read the key as ${t.form === "all" ? "a possibly-empty array" : "possibly absent"}; otherwise move the reference to a node every path reaches`
+            `${site}[${JSON.stringify(k)}] names "${spelled(t, false)}" unconditionally, and a run can reach this node without "${target}" having run \u2014 a decision routes around it, or it is inside a region whose branch may be lost before it is entered. \`FD-V27\` checked that this node is reachable FROM it, which is weaker. Write "${spelled(t, true)}"${t.form === "all" ? " inside the array" : ""} if you mean *if it ran*, and read the key as ${t.form === "all" ? "a possibly-empty array" : "possibly absent"}; otherwise move the reference to a node every path reaches`
           );
         }
         const many = regions.some((r) => r.opensWith === "map" && r.members.has(target) && !r.members.has(n.id));
         if (many && t.form === "one") {
-          add("FD-V28", at, `${site}[${JSON.stringify(k)}] names "${target}" as one value, but it is inside a map region this node is outside of, so it produces one output per ITEM; write ["${target}"]`);
+          add("FD-V28", at, `${site}[${JSON.stringify(k)}] names "${spelled(t, false)}" as one value, but it is inside a map region this node is outside of, so it produces one output per ITEM; write ["${spelled(t, false)}"]`);
         } else if (!many && t.form === "all") {
-          add("FD-V28", at, `${site}[${JSON.stringify(k)}] names ["${target}"] as a list, but it produces exactly one output on this node's branch path; write "${target}"`);
+          add("FD-V28", at, `${site}[${JSON.stringify(k)}] names ["${spelled(t, false)}"] as a list, but it produces exactly one output on this node's branch path; write "${spelled(t, false)}"`);
         }
       }
     }
@@ -2025,6 +2064,7 @@ var typesOf = (s) => {
 var widen = (ts) => ts.flatMap((t) => t === "integer" ? ["integer"] : t === "number" ? ["number", "integer"] : [t]);
 var canon = (v) => JSON.stringify(v);
 var BRANCH_KEY = /^\d+(\.\d+)*$/;
+var ERROR_SCHEMA = Object.freeze({ type: ["string", "null"] });
 function fits(P, C, path = "$") {
   const p = P;
   const c = C;
@@ -2419,6 +2459,11 @@ var Wiring = class {
         value = a.sample?.value;
         src = a.sample?.source ?? "witness";
         dot.push(key);
+      } else if (t.part === "error") {
+        schema2 = ERROR_SCHEMA;
+        const w = sampleOf(ERROR_SCHEMA);
+        value = w.value;
+        src = w.source;
       } else {
         const p = this.produced(t.node);
         if (p.schema === void 0) return { ...base, unchecked: `needs.${key} names "${t.node}", which ${p.unchecked}` };
@@ -2538,6 +2583,7 @@ async function judgeTransform(v, node, transform, type, consumer, consumerWhy, l
     for (const input of inputs) results.push(await c.evaluate(input, settings));
   } catch (e) {
     v.kind = "transform-fails";
+    v.cause = "threw";
     v.why = `the transform threw on the ${sourceWord(sample.source)}: ${e instanceof Error ? e.message : String(e)}`;
     v.sample = { ...sample, result: e instanceof Error ? e.message : String(e) };
     return;
@@ -2551,6 +2597,7 @@ async function judgeTransform(v, node, transform, type, consumer, consumerWhy, l
   const bad = results.map((r, i) => [i, findings(consumer, r)]).find(([, f]) => f.length > 0);
   if (bad) {
     v.kind = "transform-fails";
+    v.cause = "schema";
     v.why = `the transform's result on the ${sourceWord(sample.source)}${perItem ? ` (item ${bad[0]})` : ""} fails the consumer's inputSchema \u2014 ${describeFindings(bad[1])}`;
   } else {
     v.kind = "transform-passes";
@@ -3046,6 +3093,11 @@ function sameData(a, b) {
   const kb = Object.keys(rb).filter((k) => rb[k] !== void 0);
   return ka.length === kb.length && ka.every((k) => Object.hasOwn(rb, k) && sameData(ra[k], rb[k]));
 }
+function storedAskedAt(e) {
+  if (e === void 0 || e === null || typeof e !== "object" || e.kind !== "asked") return void 0;
+  const t = e.observedAt;
+  return typeof t === "number" ? t : void 0;
+}
 function isFed(e) {
   return e.kind === "outcome" || e.kind === "resolution" || e.kind === "resumed" || e.kind === "interrupted" || e.kind === "paused" || e.kind === "unpaused" || e.kind === "attempted";
 }
@@ -5408,7 +5460,7 @@ var Driver = class _Driver {
   }
   /**
    * **One task's entry, made what its effective outcome now says** — `outputs()`'s catch-up, for a task one of whose records
-   * was just read. An entry is `{ path, result }` with `result` the record's own object (`RN-R13`); a node's list is kept
+   * was just read. An entry is `{ path, result, error }` with `result` the record's own object (`RN-R13`) and `error` its string or `null` (v0.49, ADR 0131); a node's list is kept
    * in its tasks' FIRST-RECORD order, the order the rebuild grouped them in.
    *
    * **`!eff` — a suspended node contributes no entry.** The first record of a `user_action` task has none, and its
@@ -5441,7 +5493,7 @@ var Driver = class _Driver {
       }
       return;
     }
-    const entry = { path: t.path, result: eff.result };
+    const entry = { path: t.path, result: eff.result, error: eff.error };
     if (t.entry !== null && list !== void 0) {
       list[list.indexOf(t.entry)] = entry;
       this.reindex(c, t.nodeId, t.entry, entry);
@@ -5616,6 +5668,9 @@ var Driver = class _Driver {
     }
     const c = this.outputsCache;
     c.examined += t.form === "all" ? visible.length : 1;
+    if (t.part === "error") {
+      return t.form === "all" ? visible.map((e) => e.error) : visible[0].error;
+    }
     return t.form === "all" ? visible.map((e) => this.sharedOf(c, e)) : this.sharedOf(c, visible[0]);
   }
   /** **An output entry's shared copy**, made at its first read and kept on the entry (`OutputEntry.shared`) — counted. */
@@ -5782,7 +5837,10 @@ var Driver = class _Driver {
       throw new DuplicateTaskId(`"${taskId}" was already asked in run "${runId}" \u2014 an ask's id is minted once per path (ID-R1)`);
     }
     this.asked.add(taskId);
-    this.append({ kind: "asked", taskId, input: cloneValue(received) });
+    const replay = this.replay;
+    const at = this.inputs.length;
+    const observedAt = replay !== null && at < replay.stored.length ? storedAskedAt(replay.stored[at]) : this.now();
+    this.append(observedAt === void 0 ? { kind: "asked", taskId, input: cloneValue(received) } : { kind: "asked", taskId, input: cloneValue(received), observedAt });
     if (this.shut()) return;
     const region = this.regionOf(node.id);
     if (region) {
@@ -6676,7 +6734,9 @@ var Accumulator = class _Accumulator {
         state: "suspended",
         result: null,
         error: null,
-        input: structuredClone(input.input)
+        input: structuredClone(input.input),
+        // `RN-R36` v0.35 (W208, ADR 0130): WHEN it was asked, where the element says — and only there.
+        ...input.observedAt !== void 0 ? { askedAt: input.observedAt } : {}
       });
       return this.withOutcome();
     }
@@ -6744,7 +6804,8 @@ var Accumulator = class _Accumulator {
         state: r.resolvedAs,
         result: r.result,
         error: r.error,
-        ...existing !== void 0 && "input" in existing ? { input: existing.input } : {}
+        ...existing !== void 0 && "input" in existing ? { input: existing.input } : {},
+        ...existing?.askedAt !== void 0 ? { askedAt: existing.askedAt } : {}
       });
     }
     this.runId = this.runId ?? runId;
@@ -6920,10 +6981,16 @@ export {
   findings,
   describeFindings,
   readKeyPath,
+  ID_RE_COPY,
+  KINDS_COPY,
+  ROUTABLE_STATES,
   ASK_REFUSED_KEYS,
   EDGE_KEYS_DECLARED,
   TASK_KEYS_DECLARED,
   NODE_KEYS_DECLARED,
+  NODE_KEYS_REQUIRED,
+  EDGE_KEYS_REQUIRED,
+  DOC_KEYS_DECLARED,
   RETRY_POLICY_KEYS,
   retryPolicyProblem,
   BUILT_IN_NODE_TYPES,