fyflow-orchestration 0.10.0 → 0.12.0

package/README.md

@@ -17,7 +17,7 @@ worker returned, routing can **fan out** into parallel branches, and a **join**
 The scheduler runs tasks; this library decides **which task runs next**. `fyflow-scheduler` has no
 dependency graph of its own, so sequence, decision, fan-out and join live here.
 
-Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.10.0`.
+Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.12.0`.
 
 ## Install
 
@@ -93,7 +93,7 @@ if (JSON.stringify(shout?.result) !== '{"text":"hello world !"}') throw new Erro
 
 A **decision** is an edge with a `when` naming a predicate: code you supply, under a name the
 registry declares. A **fan-out** opens branches that run concurrently; a **join** waits for them and
-hands the next node every branch's result, keyed by branch path. Below, two runs at high and low
+hands the next node every branch's result, each under its own entry id. Below, two runs at high and low
 confidence take different roads. The worker is
 [examples/getting-started/tag.ts](examples/getting-started/tag.ts).
 
@@ -116,7 +116,7 @@ const isLowConfidence: Predicate = (ctx) => {
 
 // THE FLOW — a DECISION, a FAN-OUT, a JOIN. `ingest` goes to `review` when the predicate holds,
 // otherwise to `split`. `split` runs two branches concurrently; `collect` waits for both and hands
-// `publish` every branch's result, keyed by branch path.
+// `publish` every branch's result, each under its own entry id.
 const flow: FlowDefinition = {
   flowId: 'decide', version: 1, entry: 'ingest',
   nodes: [
@@ -144,13 +144,13 @@ const ran = (s: RunState) => Object.values(s.nodes).map((n) => n.nodeId).sort();
 const resultOf = (s: RunState, id: string) => Object.values(s.nodes).find((n) => n.nodeId === id)?.result;
 console.log(ran(high));                    // [ 'classify', 'enrich', 'ingest', 'publish' ]
 console.log(ran(low));                     // [ 'ingest', 'review' ]
-console.log(resultOf(high, 'publish'));    // { '0': { confidence: 0.9, ingest: true, enrich: true }, '1': { …, classify: true }, publish: true }
+console.log(resultOf(high, 'publish'));    // { enrich: { confidence: 0.9, ingest: true, enrich: true }, classify: { …, classify: true }, publish: true }
 
 // Verified by the docs gate:
 if (high.outcome !== 'completed' || low.outcome !== 'completed') throw new Error(`outcomes ${high.outcome} / ${low.outcome}`);
 if (ran(high).join() !== 'classify,enrich,ingest,publish') throw new Error(`high ran ${ran(high).join()}`);
 if (ran(low).join() !== 'ingest,review') throw new Error(`low ran ${ran(low).join()}`);
-const want = '{"0":{"confidence":0.9,"ingest":true,"enrich":true},"1":{"confidence":0.9,"ingest":true,"classify":true},"publish":true}';
+const want = '{"enrich":{"confidence":0.9,"ingest":true,"enrich":true},"classify":{"confidence":0.9,"ingest":true,"classify":true},"publish":true}';
 if (JSON.stringify(resultOf(high, 'publish')) !== want) throw new Error(`publish received ${JSON.stringify(resultOf(high, 'publish'))}`);
 ```
 

package/dist/browser/chunks/{chunk-NA6QQAZ2.js → chunk-4JFQX7DL.js}

@@ -360,10 +360,32 @@ function describeFindings(fs) {
 }
 
 // src/definition/condition.ts
+var INDEX_SPELLING = "\\[(0|[1-9][0-9]{0,8})\\]";
+var INDEXED_SEGMENT = new RegExp(`^([A-Za-z0-9_-]{1,64})((?:${INDEX_SPELLING})+)$`);
+var INDEX2 = new RegExp(INDEX_SPELLING, "g");
+function keyPathSteps(path) {
+  const out = [];
+  for (const seg of path.split(".")) {
+    const m = INDEXED_SEGMENT.exec(seg);
+    if (m === null) {
+      out.push({ key: seg });
+      continue;
+    }
+    out.push({ key: m[1] });
+    for (const i of m[2].matchAll(INDEX2)) out.push({ index: Number(i[1]) });
+  }
+  return out;
+}
 function readKeyPath(value, path) {
   let v = value;
-  for (const seg of path.split(".")) {
+  for (const step2 of keyPathSteps(path)) {
     if (typeof v !== "object" || v === null) return void 0;
+    if ("index" in step2) {
+      if (!Array.isArray(v) || step2.index >= v.length || !Object.prototype.hasOwnProperty.call(v, step2.index)) return void 0;
+      v = v[step2.index];
+      continue;
+    }
+    const seg = step2.key;
     const proto = Object.getPrototypeOf(v);
     if (proto !== Object.prototype && proto !== null) return void 0;
     if (!Object.prototype.hasOwnProperty.call(v, seg)) return void 0;
@@ -416,7 +438,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 +476,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)) {
@@ -506,11 +536,12 @@ function languagesOf(x) {
   if (x instanceof Map) return x;
   return new Map(Object.entries(x));
 }
-var KEY_PATH_RE = /^[A-Za-z0-9_-]{1,64}(?:\.[A-Za-z0-9_-]{1,64})*$/;
+var KEY_PATH_RE = /^[A-Za-z0-9_-]{1,64}(?:\[(?:0|[1-9][0-9]{0,8})\])*(?:\.[A-Za-z0-9_-]{1,64}(?:\[(?:0|[1-9][0-9]{0,8})\])*)*$/;
+var KEY_PATH_WORDS = "dot-separated object keys, each [A-Za-z0-9_-]{1,64} and optionally followed by array indexes [n] (n is 0 or a number with no leading zero, at most 999999999 \u2014 files[0].series, m[0][2]); no index leading the path, no quoted key, no wildcard, no expression";
 function keyPathProblem(v) {
   if (typeof v !== "string") return `settings.key must be a key path string, got ${JSON.stringify(v)}`;
   if (KEY_PATH_RE.test(v)) return null;
-  return `settings.key ${JSON.stringify(v)} is not a key path \u2014 dot-separated object keys, each [A-Za-z0-9_-]{1,64}; no array index, no wildcard, no expression (a key that must be computed is computed in the task before the gate)`;
+  return `settings.key ${JSON.stringify(v)} is not a key path \u2014 ${KEY_PATH_WORDS} (a key that must be computed is computed in the task before the gate)`;
 }
 var GATE_TYPE_KEYS = ["routes", "defaultRoute", "settingsSchema", "keyResolvedRoutes", "routesFor", "settingsProblem", "fn"];
 var STATIC_ROUTE_KEYS = ["routes", "defaultRoute", "keyResolvedRoutes"];
@@ -762,12 +793,17 @@ function leafProblem(o, where, scope = EDGE_SCOPE) {
   }
   const path = o.path;
   if (typeof path !== "string" || !KEY_PATH_RE.test(path)) {
-    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is not a key path \u2014 dot-separated object keys, each [A-Za-z0-9_-]{1,64}; no array index, no wildcard, no expression` };
+    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is not a key path \u2014 ${KEY_PATH_WORDS}` };
   }
-  const root = path.split(".")[0];
+  const first = path.split(".")[0];
+  const bracket = first.indexOf("[");
+  const root = bracket === -1 ? first : first.slice(0, bracket);
   if (!scope.roots.includes(root)) {
     return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} starts at ${JSON.stringify(root)}, ${scope.foreignRoot(root)}` };
   }
+  if (bracket !== -1) {
+    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} indexes its root ${JSON.stringify(root)} \u2014 a path names a KEY inside its root first, as a gate's key path names a key inside the value that reached it; an index follows a key (${root}.items[0])` };
+  }
   if (path.split(".").length < 2) {
     return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is a root alone ${scope.rootAlone(root)}` };
   }
@@ -958,10 +994,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";
@@ -1230,8 +1291,15 @@ function validateDefinition(doc, registry) {
       if (nd.edges !== void 0) add("FD-V9", where, "fanout has edges");
       if (nd.branches !== void 0 && !Array.isArray(nd.branches)) {
         add("FD-V21", where, "fanout branches must be an array");
+      } else if (Array.isArray(nd.branches)) {
+        nd.branches.forEach((b, i) => {
+          if (typeof b !== "string") add("FD-V21", where, `fanout branches[${i}] must be a string, got ${describeValue(b)}`);
+        });
       }
     }
+    if (nd.kind === "join" && nd.of !== void 0 && typeof nd.of !== "string") {
+      add("FD-V21", where, `join of must be a string, got ${describeValue(nd.of)}`);
+    }
     if (nd.kind === "map") {
       if (nd.edges !== void 0) add("FD-V25", where, "map has edges");
       if (nd.branch !== void 0 && typeof nd.branch !== "string") {
@@ -1252,10 +1320,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 +1389,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 +1576,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)}"`);
         }
       }
     }
@@ -2024,7 +2098,8 @@ 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 BRANCH_KEY = /^(?:0|[1-9][0-9]*)$/;
+var ERROR_SCHEMA = Object.freeze({ type: ["string", "null"] });
 function fits(P, C, path = "$") {
   const p = P;
   const c = C;
@@ -2055,7 +2130,7 @@ function fits(P, C, path = "$") {
       if (!own2(pp, k)) {
         if (record !== void 0 && BRANCH_KEY.test(k)) {
           const r2 = fits(record, cp[k], `${path}.${k}`);
-          if (r2.verdict !== "fits") return { verdict: "no", why: `${r2.why} (a branch path the map's record may mint)` };
+          if (r2.verdict !== "fits") return { verdict: "no", why: `${r2.why} (an item index the map's record may mint)` };
           continue;
         }
         if (p.additionalProperties === false) continue;
@@ -2159,14 +2234,21 @@ var Wiring = class {
    * key-resolved route licenses. A step the producer's schema does not describe is left alone rather than
    * invented: `required` on a key no `properties` entry mentions is still a promise the value carries it,
    * which is what the consumer asked about, and describing its SHAPE is not this function's to guess.
+   * **An index step `[n]` raises the array's `minItems` to `n + 1` and ends the walk** (v0.53, ADR 0137) — below.
    */
   requireAlong(schema, key) {
     if (schema === void 0 || key === "") return schema;
-    const steps = key.split(".");
+    const steps = keyPathSteps(key);
     const go = (s, i) => {
       if (i >= steps.length || typeof s !== "object" || s === null || Array.isArray(s)) return s;
       const o = s;
-      const here = steps[i];
+      const step2 = steps[i];
+      if ("index" in step2) {
+        const floor = step2.index + 1;
+        const had = typeof o.minItems === "number" ? o.minItems : 0;
+        return had >= floor ? o : { ...o, minItems: floor };
+      }
+      const here = step2.key;
       const req = Array.isArray(o.required) ? o.required : [];
       const props = o.properties ?? {};
       const described = own2(props, here);
@@ -2186,9 +2268,10 @@ var Wiring = class {
    * the producer can emit.
    *
    * **The question is per STEP and about the CONTAINER, because that is what `readKeyPath` is** —
-   * the DRIVER's own resolution (`src/definition/validate.ts`, W93), where each segment is an OWN key
-   * of a PLAIN object and a missing key, a `null`, an array mid-path or a primitive is `undefined`.
-   * So two shapes forbid a step and the third is a silence:
+   * the DRIVER's own resolution (`src/definition/condition.ts`, W93), where each KEY step is an OWN key
+   * of a PLAIN object and a missing key, a `null`, an array under a key step or a primitive is `undefined`
+   * — and, since v0.53, each INDEX step `[n]` an element of a REAL array (ADR 0137), asked below in the loop.
+   * So, for a key step, two shapes forbid it and the third is a silence:
    *
    * - **its declared types cannot include `object`** — `name.id` where the producer calls `name` a
    *   string. No value the schema admits carries the path.
@@ -2210,13 +2293,21 @@ var Wiring = class {
    * Every rung this repository has is green on a flow that did none of the work it exists for.
    */
   keyPathRefusal(schema, key, gateId, route) {
-    const steps = key.split(".");
+    const steps = keyPathSteps(key);
     let s = schema;
-    const because = (at, detail) => `gate "${gateId}" is keyed on "${key}", which the producer's schema FORBIDS at ${at}: ${detail} \u2014 so route "${route}" can never be taken, and a run may route every branch by another route, doing none of the work this gate guards`;
-    for (let i = 0; i < steps.length; i++) {
-      const here = steps[i];
-      const at = i === 0 ? "$" : `$.${steps.slice(0, i).join(".")}`;
+    let at = "$";
+    const because = (at2, detail) => `gate "${gateId}" is keyed on "${key}", which the producer's schema FORBIDS at ${at2}: ${detail} \u2014 so route "${route}" can never be taken, and a run may route every branch by another route, doing none of the work this gate guards`;
+    for (const step2 of steps) {
       const ts = typesOf(s);
+      if ("index" in step2) {
+        if (!ts.includes("array")) return because(at, `the schema calls it ${ts.join("|")}, and an index [${step2.index}] reads an element of an array`);
+        if (s.items === void 0) return null;
+        if (!isPlainObject3(s.items)) return null;
+        s = s.items;
+        at = `${at}[${step2.index}]`;
+        continue;
+      }
+      const here = step2.key;
       if (!ts.includes("object")) return because(at, `the schema calls it ${ts.join("|")}, and a key path reads an own key of a plain object`);
       const props = s.properties ?? {};
       if (!own2(props, here)) {
@@ -2229,6 +2320,7 @@ var Wiring = class {
       const next = props[here];
       if (!isPlainObject3(next)) return null;
       s = next;
+      at = at === "$" ? `$.${here}` : `${at}.${here}`;
     }
     return null;
   }
@@ -2321,7 +2413,7 @@ var Wiring = class {
     const members = region.branchOf.get(branch) ?? /* @__PURE__ */ new Set();
     return [...members].map((id) => this.byId.get(id)).filter((n) => (n.kind === "task" || n.kind === "ask" || n.kind === "join" || n.kind === "gate") && (n.edges ?? []).some((e) => e.to === region.joinId));
   }
-  /** `JP-R12`'s record for the region a join closes — exact for a fan-out, keyed by minted paths for a map. */
+  /** `JP-R12`'s record for the region a join closes — exact for a fan-out, keyed by entry id; keyed by item index for a map. */
   record(j) {
     const region = this.regions.find((r) => r.joinId === j.id);
     const base = { shape: "record", producer: j.id };
@@ -2345,22 +2437,16 @@ var Wiring = class {
       values.push({ branch: b, schema: firstSchema, sample: first.sample ?? { value: null, source: "witness" } });
     }
     const source = values.every((v2) => v2.sample.source === "example") ? "example" : "witness";
-    const enclosing = new Map(this.regions.filter((r) => r.opensWith === "map" && r.members.has(region.fanoutId)).map((r) => [r.fanoutId, 0]));
     if (opener.kind === "fanout") {
-      const props = {};
-      const sample2 = {};
-      for (const v2 of values) {
-        const path = branchPathOf(this.regions, v2.branch, enclosing);
-        props[path] = v2.schema;
-        sample2[path] = v2.sample.value;
-      }
+      const props = Object.fromEntries(values.map((v2) => [v2.branch, v2.schema]));
+      const sample2 = Object.fromEntries(values.map((v2) => [v2.branch, v2.sample.value]));
       return { ...base, schema: { type: "object", required: [], properties: props, additionalProperties: false }, sample: { value: sample2, source, arity: values.length } };
     }
     const v = values[0];
     if (!v) return { ...base, unchecked: `map "${opener.id}"'s branch never arrives at "${j.id}"` };
     const arity = this.arrivals(opener.branch)[0]?.sample?.arity ?? 1;
     const sample = {};
-    for (let i = 0; i < arity; i++) sample[branchPathOf(this.regions, opener.branch, new Map([...enclosing, [opener.id, i]]))] = v.sample.value;
+    for (let i = 0; i < arity; i++) sample[String(i)] = v.sample.value;
     return {
       ...base,
       schema: { type: "object", additionalProperties: v.schema, branchKeys: true },
@@ -2419,6 +2505,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 +2629,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 +2643,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";
@@ -2586,7 +2679,7 @@ var WIRING_SHAPES = ["edge", "branch", "item", "record", "needs", "given"];
 var SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
 var BRANCH_PATH = /^(?:-|(?:0|[1-9][0-9]*)(?:\.(?:0|[1-9][0-9]*))*)$/;
 var ATTEMPT = /^(?:0|[1-9][0-9]*)$/;
-var INDEX2 = /^(?:0|[1-9][0-9]*)$/;
+var INDEX3 = /^(?:0|[1-9][0-9]*)$/;
 var InvalidRunId = class extends Error {
 };
 var InvalidTaskId = class extends Error {
@@ -2610,7 +2703,7 @@ function branchPathSegment(branchIndex) {
     throw new InvalidTaskId("branchPath must be null for a node in no region, never an empty path");
   }
   for (const n of parts) {
-    if (!INDEX2.test(String(n))) {
+    if (!INDEX3.test(String(n))) {
       throw new InvalidTaskId(`branchPath segment ${JSON.stringify(n)} is not a non-negative integer`);
     }
   }
@@ -2934,7 +3027,7 @@ var RunControlRefused = class extends Error {
     this.reason = reason;
   }
 };
-var CHECKPOINT_FORMAT = 1;
+var CHECKPOINT_FORMAT = 2;
 var ResumeRefused = class extends Error {
   reason;
   /** The position `halted`, `cancelled` and `diverged` name; `null` for the three a header decides. */
@@ -3046,6 +3139,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";
 }
@@ -3128,11 +3226,12 @@ function compareBranchPaths(a, b) {
   }
   return 0;
 }
-function collectArrivals(arrived) {
-  const out = {};
-  if (!arrived) return out;
-  for (const path of [...arrived.keys()].sort(compareBranchPaths)) out[path] = arrived.get(path);
-  return out;
+function collectArrivals(arrived, region) {
+  if (!arrived) return {};
+  return Object.fromEntries([...arrived.keys()].sort(compareBranchPaths).map((path) => {
+    const segment = path.slice(path.lastIndexOf(".") + 1);
+    return [region.opensWith === "fanout" ? region.branches[Number(segment)] : segment, arrived.get(path)];
+  }));
 }
 var EMPTY_INDICES = /* @__PURE__ */ new Map();
 var EMPTY_NEEDS = Object.freeze({});
@@ -3315,7 +3414,8 @@ var Driver = class _Driver {
   firedJoins = /* @__PURE__ */ new Map();
   /**
    * **What each branch carried into its join, keyed by region and then by
-   * `branchPath`** — [ADR 0037](../../doc/decisions/0037-what-a-branch-receives-is-a-property-of-the-fan-out-and-what-a-join-carries-is-a-property-of-the-region.md)
+   * `branchPath`** — the FULL path, here where it is recorded; the collection a join hands on is keyed by each
+   * branch's OWN key, derived from these paths by `collectArrivals` at the exit (ADR 0138) —[ADR 0037](../../doc/decisions/0037-what-a-branch-receives-is-a-property-of-the-fan-out-and-what-a-join-carries-is-a-property-of-the-region.md)
    * rule 4, and `JP-R11` in [spec/join-policy.md](../../spec/join-policy.md)
    * section 4.
    *
@@ -5408,7 +5508,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 +5541,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 +5716,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 +5885,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) {
@@ -6204,7 +6310,7 @@ var Driver = class _Driver {
       fired: true
     });
     if (this.shut()) return;
-    const collected = collectArrivals(this.arrivals.get(region.fanoutId)?.get(rp));
+    const collected = collectArrivals(this.arrivals.get(region.fanoutId)?.get(rp), region);
     this.releaseArrivals(region.fanoutId, rp);
     const reading = this.replay?.reading ?? null;
     if (reading !== null && region.joinId === reading.nodeId) {
@@ -6676,7 +6782,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 +6852,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 +7029,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,