fyflow-orchestration 0.11.0 → 0.13.0

package/dist/browser/chunks/{chunk-5CVSWDCB.js → chunk-53EDI674.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;
@@ -380,7 +402,13 @@ function evalLeaf(scope, p, unknownOp) {
     else if (typeof v === "string") v = v.length;
     else return false;
   }
-  const w = p.value;
+  let w;
+  if (p.valueFrom !== void 0) {
+    w = readKeyPath(scope, p.valueFrom);
+    if (w === void 0 || typeof w === "object" && w !== null) return false;
+  } else {
+    w = p.value;
+  }
   switch (p.op) {
     // **Type-STRICT, and it is a departure measured rather than assumed.** Under JS comparison
     // `{confidence: "0.4"} < 0.5` is true and every `typeof`-guarded predicate in this tree is false;
@@ -514,11 +542,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"];
@@ -732,8 +761,9 @@ function gateTypeCollisions(x) {
   return names.filter((n) => Object.prototype.hasOwnProperty.call(BUILT_IN_GATE_TYPES, n)).sort();
 }
 var PREDICATE_NAME_KEYS = ["predicate"];
-var PREDICATE_LEAF_KEYS = ["path", "op", "value", "default", "length"];
-var PREDICATE_LEAF_REQUIRED = ["path", "op", "value"];
+var PREDICATE_LEAF_KEYS = ["path", "op", "value", "valueFrom", "default", "length"];
+var PREDICATE_LEAF_REQUIRED = ["path", "op"];
+var RIGHT_SIDE_KEYS = ["value", "valueFrom"];
 var PREDICATE_GROUP_KEYS = ["all", "any"];
 function predicateShapeOf(o) {
   const marks = [];
@@ -760,24 +790,53 @@ var GATE_SCOPE = {
   foreignRoot: () => 'which an if gate cannot see \u2014 its one root is "input", the value that reached the gate; a gate has no outcome and no edge needs, and any other first segment would resolve to nothing in silence',
   rootAlone: () => "and names no key \u2014 a gate's path names a key INSIDE the value that reached it, as every gate's key path does; a value that must be compared whole is wrapped by the task before the gate"
 };
+function comparisonPathProblem(o, key, where, scope) {
+  const path = o[key];
+  if (typeof path !== "string" || !KEY_PATH_RE.test(path)) {
+    return { rule: "FD-V43", message: `${where} ${key} ${JSON.stringify(path)} is not a key path \u2014 ${KEY_PATH_WORDS}` };
+  }
+  const segments = path.split(".");
+  const first = segments[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} ${key} ${JSON.stringify(path)} starts at ${JSON.stringify(root)}, ${scope.foreignRoot(root)}` };
+  }
+  if (bracket !== -1) {
+    return { rule: "FD-V43", message: `${where} ${key} ${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 (segments.length < 2) {
+    return { rule: "FD-V43", message: `${where} ${key} ${JSON.stringify(path)} is a root alone ${scope.rootAlone(root)}` };
+  }
+  if (root === "needs" && scope.needsDeclared !== void 0) {
+    const seg = segments[1];
+    const at = seg.indexOf("[");
+    const name = at === -1 ? seg : seg.slice(0, at);
+    if (!scope.needsDeclared.includes(name)) {
+      const declared = scope.needsDeclared.length === 0 ? "declares no `needs`, so its `ctx.needs` is {}" : `declares needs ${scope.needsDeclared.map((k2) => JSON.stringify(k2)).join(", ")}`;
+      return { rule: "FD-V43", message: `${where} ${key} ${JSON.stringify(path)} reads needs key ${JSON.stringify(name)}, and this edge ${declared} \u2014 the key would be absent for ever and the comparison no match for ever; declare it in the edge's needs` };
+    }
+  }
+  return null;
+}
 function leafProblem(o, where, scope = EDGE_SCOPE) {
   const extra = Object.keys(o).filter((k) => !PREDICATE_LEAF_KEYS.includes(k));
   if (extra.length) {
     return { rule: "FD-V42", message: `${where} carries ${extra.map((k) => JSON.stringify(k)).join(", ")}, which a comparison does not declare; it is { ${PREDICATE_LEAF_KEYS.join(", ")} }` };
   }
   for (const k of PREDICATE_LEAF_REQUIRED) {
-    if (!(k in o)) return { rule: "FD-V42", message: `${where} is missing required key "${k}"; a comparison is { ${PREDICATE_LEAF_KEYS.join(", ")} } with ${PREDICATE_LEAF_REQUIRED.join(", ")} required` };
+    if (!(k in o)) return { rule: "FD-V42", message: `${where} is missing required key "${k}"; a comparison is { ${PREDICATE_LEAF_KEYS.join(", ")} } with ${PREDICATE_LEAF_REQUIRED.join(", ")} required and exactly one of ${RIGHT_SIDE_KEYS.map((k2) => JSON.stringify(k2)).join(" or ")}` };
   }
-  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` };
+  const sides = RIGHT_SIDE_KEYS.filter((k) => k in o);
+  if (sides.length !== 1) {
+    return { rule: "FD-V42", message: `${where} carries ${sides.length === 0 ? "neither" : "both"} "value" and "valueFrom"; a comparison compares against exactly one \u2014 a literal "value", or "valueFrom", a key path over the same context` };
   }
-  const root = path.split(".")[0];
-  if (!scope.roots.includes(root)) {
-    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} starts at ${JSON.stringify(root)}, ${scope.foreignRoot(root)}` };
-  }
-  if (path.split(".").length < 2) {
-    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is a root alone ${scope.rootAlone(root)}` };
+  const pathProblem = comparisonPathProblem(o, "path", where, scope);
+  if (pathProblem !== null) return pathProblem;
+  const fromValue = "valueFrom" in o;
+  if (fromValue) {
+    const fromProblem = comparisonPathProblem(o, "valueFrom", where, scope);
+    if (fromProblem !== null) return fromProblem;
   }
   const op = o.op;
   if (typeof op !== "string" || !PREDICATE_OPS.includes(op)) {
@@ -787,6 +846,12 @@ function leafProblem(o, where, scope = EDGE_SCOPE) {
     return { rule: "FD-V44", message: `${where} length is ${JSON.stringify(o.length)}; it is exactly true or absent \u2014 there is no "compare the value, not its length" to ask for` };
   }
   const takesLength = o.length === true;
+  if (fromValue) {
+    if (takesLength && STRING_OPS.has(op)) {
+      return { rule: "FD-V44", message: `${where} takes a length and uses "${op}"; a length is a number and has no prefix` };
+    }
+    return defaultProblem(o, where, takesLength);
+  }
   if (!isScalar(o.value)) {
     return { rule: "FD-V44", message: `${where} value is ${scalarName(o.value)}; a comparison compares against a SCALAR \u2014 null, a boolean, a finite number or a string` };
   }
@@ -802,6 +867,9 @@ function leafProblem(o, where, scope = EDGE_SCOPE) {
   if (takesLength && STRING_OPS.has(op)) {
     return { rule: "FD-V44", message: `${where} takes a length and uses "${op}"; a length is a number and has no prefix` };
   }
+  return defaultProblem(o, where, takesLength);
+}
+function defaultProblem(o, where, takesLength) {
   if ("default" in o) {
     const d = o.default;
     const okDefault = Array.isArray(d) ? d.every(isScalar) : isScalar(d);
@@ -817,7 +885,8 @@ function leafProblem(o, where, scope = EDGE_SCOPE) {
   }
   return null;
 }
-function predicateProblem(v) {
+function predicateProblem(v, edgeNeeds) {
+  const scope = edgeNeeds === void 0 ? EDGE_SCOPE : { ...EDGE_SCOPE, needsDeclared: edgeNeeds };
   if (typeof v !== "object" || v === null || Array.isArray(v)) {
     return {
       rule: "FD-V42",
@@ -838,8 +907,8 @@ function predicateProblem(v) {
     if (typeof o.predicate !== "string") return { rule: "FD-V42", message: `when predicate is ${scalarName(o.predicate)}; it is the name of a registered predicate` };
     return null;
   }
-  if (shape === "leaf") return leafProblem(o, "when");
-  return groupProblem(o, "when", EDGE_SCOPE);
+  if (shape === "leaf") return leafProblem(o, "when", scope);
+  return groupProblem(o, "when", scope);
 }
 function groupProblem(o, label, scope) {
   const extra = Object.keys(o).filter((k) => !PREDICATE_GROUP_KEYS.includes(k));
@@ -1263,8 +1332,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") {
@@ -1325,7 +1401,9 @@ function validateDefinition(doc, registry) {
         }
       }
       if (ed?.when !== void 0) {
-        const problem = predicateProblem(ed.when);
+        const nv = ed.needs;
+        const edgeNeeds = nv === void 0 ? [] : typeof nv === "object" && nv !== null && !Array.isArray(nv) && Object.keys(nv).length > 0 ? Object.keys(nv) : void 0;
+        const problem = predicateProblem(ed.when, edgeNeeds);
         if (problem) add(problem.rule, at, problem.message);
         else for (const name of predicateNamesIn(ed.when)) {
           if (!preds.has(name)) add("FD-V4", at, `when names "${name}", which is not a registered predicate`);
@@ -2063,7 +2141,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 BRANCH_KEY = /^(?:0|[1-9][0-9]*)$/;
 var ERROR_SCHEMA = Object.freeze({ type: ["string", "null"] });
 function fits(P, C, path = "$") {
   const p = P;
@@ -2095,7 +2173,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;
@@ -2199,14 +2277,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);
@@ -2226,9 +2311,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.
@@ -2250,13 +2336,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)) {
@@ -2269,6 +2363,7 @@ var Wiring = class {
       const next = props[here];
       if (!isPlainObject3(next)) return null;
       s = next;
+      at = at === "$" ? `$.${here}` : `${at}.${here}`;
     }
     return null;
   }
@@ -2361,7 +2456,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 };
@@ -2385,22 +2480,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 },
@@ -2633,7 +2722,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 {
@@ -2657,7 +2746,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`);
     }
   }
@@ -2981,7 +3070,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. */
@@ -3180,11 +3269,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({});
@@ -3367,7 +3457,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.
    *
@@ -6262,7 +6353,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) {
@@ -6980,6 +7071,7 @@ export {
   canonical,
   findings,
   describeFindings,
+  keyPathSteps,
   readKeyPath,
   ID_RE_COPY,
   KINDS_COPY,

package/dist/browser/index.js

@@ -111,6 +111,7 @@ import {
   isTerminal,
   isTerminalEvent,
   keyPathProblem,
+  keyPathSteps,
   languagesOf,
   lastRecordFor,
   liveToken,
@@ -151,11 +152,10 @@ import {
   visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-5CVSWDCB.js";
+} from "./chunks/chunk-53EDI674.js";
 
 // src/definition/definition-schema.ts
 var DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
-var idOrNonString = () => ({ anyOf: [ref("id"), { not: { type: "string" } }] });
 var ref = (name) => ({ $ref: `#/$defs/${name}` });
 function body(re, name) {
   const s = re.source;
@@ -164,6 +164,14 @@ function body(re, name) {
   }
   return s.slice(1, -1);
 }
+function keyPathSegment(id) {
+  const seg = `${id}(?:\\[(?:0|[1-9][0-9]{0,8})\\])*`;
+  const whole = body(KEY_PATH_RE, "KEY_PATH_RE");
+  if (whole !== `${seg}(?:\\.${seg})*`) {
+    throw new Error(`definitionSchema: KEY_PATH_RE (${String(KEY_PATH_RE)}) is no longer one segment pattern repeated \u2014 a comparison's path pattern cannot be derived from it`);
+  }
+  return seg;
+}
 function described(table, key, where) {
   const d = Object.prototype.hasOwnProperty.call(table, key) ? table[key] : void 0;
   if (d === void 0) throw new Error(`definitionSchema: ${where} declares the key "${key}" and no description is written for it`);
@@ -197,7 +205,7 @@ var KIND_DESCRIPTIONS = {
   },
   fanout: {
     kind: "A `fanout`: opens a region of N branches declared HERE, closed by the one `join` naming it. Dispatches nothing.",
-    branches: "The region's branch entries: at least two distinct node ids (FD-V9), each a task or an ask, none of them its own join (FD-V9, FD-V12 \u2014 validateDefinition's)."
+    branches: "The region's branch entries: at least two distinct node ids (FD-V9), each a string (FD-V21), each a task or an ask, none of them its own join (FD-V9, FD-V12 \u2014 validateDefinition's)."
   },
   map: {
     kind: "A `map`: opens a region of ONE branch, opened once per item of an array at run time, closed by the one `join` naming it. Dispatches nothing.",
@@ -207,7 +215,7 @@ var KIND_DESCRIPTIONS = {
   },
   join: {
     kind: "A `join`: closes the region its `of` opened, by the join policy the driver is given. Dispatches nothing.",
-    of: "The id of the `fanout` or `map` whose region this closes (FD-V6, validateDefinition's).",
+    of: "The id of the `fanout` or `map` whose region this closes: a string (FD-V21); that it names an existing node (FD-V2) and that the node is one (FD-V6) are validateDefinition's.",
     edges: "Exactly one edge, carrying neither `when` nor `on` (FD-V7): a join has no outcome for either to read."
   },
   end: {
@@ -230,7 +238,7 @@ var KIND_DESCRIPTIONS = {
 var EDGE_DESCRIPTIONS = {
   to: "The id of the node this edge leads to (FD-V2, validateDefinition's).",
   on: 'The terminal states this edge is eligible for: a non-empty list of distinct "done" / "failed" (FD-V18). Absent: ["done"]. "user_action" suspends rather than routes.',
-  when: "The decision: a registered predicate NAME { predicate }, a declared COMPARISON { path, op, value, default?, length? }, or a flat GROUP { all } or { any } of comparisons (FD-V42-FD-V45). Absent: the edge is the default for its state.",
+  when: "The decision: a registered predicate NAME { predicate }, a declared COMPARISON { path, op, value or valueFrom, default?, length? }, or a flat GROUP { all } or { any } of comparisons (FD-V42-FD-V45). Absent: the edge is the default for its state.",
   needs: "What this edge's predicate sees beyond its node's outcome \u2014 `needs`' grammar minus \".\" (FD-V26).",
   route: "On a gate's edge, which of the gate type's routes it carries; absent: the type's DEFAULT route (FD-V41). Refused on every other kind's edge."
 };
@@ -244,9 +252,10 @@ var TRANSFORM_DESCRIPTIONS = {
 };
 var PREDICATE_DESCRIPTIONS = {
   predicate: "A registered predicate's name (FD-V4, validateDefinition's).",
-  path: `A key path over the decision's context, starting at ${PREDICATE_ROOTS.map((r) => `"${r}"`).join(" or ")} and naming a key beyond it (FD-V43).`,
+  path: `A key path over the decision's context, starting at ${PREDICATE_ROOTS.map((r) => `"${r}"`).join(" or ")} and naming a key beyond it; a key past the root may be followed by array indexes [n], the root never; a "needs" key the edge declares (FD-V43).`,
   op: `One of ${PREDICATE_OPS.join(", ")} (FD-V44). The ordering operators compare numbers and "startsWith" a string \u2014 a comparison between kinds is no match, never a coercion.`,
-  value: "The scalar compared against: null, a boolean, a number or a string (FD-V44).",
+  value: "The scalar compared against: null, a boolean, a number or a string (FD-V44). Exactly one of value and valueFrom (FD-V42).",
+  valueFrom: `A key path over the same context, compared against as a literal would be \u2014 the same roots as path, ${PREDICATE_ROOTS.map((r) => `"${r}"`).join(" or ")}, and a "needs" key the edge declares (FD-V43). Exactly one of value and valueFrom (FD-V42). Where it does not resolve, or resolves to an object or an array, the comparison is no match for every operator.`,
   default: "What is compared where the path does not resolve or resolves to null: a scalar, or \u2014 with `length` \u2014 an array or a string (FD-V44).",
   length: "Exactly true: compare the LENGTH of the array or string, against a number (FD-V44).",
   all: "A flat group: a non-empty list of comparisons that must all hold (FD-V45).",
@@ -284,7 +293,7 @@ function nodeKeySchema(kind, key) {
     case "pool":
       return { type: "string" };
     case "settings":
-      return kind === "gate" ? { type: "object", properties: { key: { type: "string", pattern: KEY_PATH_RE.source, description: "A key path: dot-separated object keys, each [A-Za-z0-9_-]{1,64} \u2014 no index, no wildcard, no expression (FD-V40)." } } } : { type: "object" };
+      return kind === "gate" ? { type: "object", properties: { key: { type: "string", pattern: KEY_PATH_RE.source, description: "A key path: dot-separated object keys, each [A-Za-z0-9_-]{1,64} and optionally followed by array indexes [n] (n is 0 or has no leading zero, at most 999999999; never leading the path) \u2014 files[0].series; no quoted key, no wildcard, no expression (FD-V40)." } } } : { type: "object" };
     case "transform":
       return ref("transform");
     case "optional":
@@ -295,14 +304,14 @@ function nodeKeySchema(kind, key) {
       return ref("retryPolicy");
     case "workerGroups":
       return { type: "array", minItems: 1, uniqueItems: true, items: { type: "string" } };
-    // **`branches`' entries and `of` admit a NON-string** — W210's conformity reader, B1: the validator holds both only
-    // through the graph (`FD-V2`, `FD-V6` and `FD-V9` read a string and pass anything else over), so `of: null` on a join
-    // of no region and `["b", "c", 5]` are ACCEPTED there, and refusing them here would refuse what the validator accepts
-    // (ADR 0132 rule 2). A string is held to the id charset. That `FD-V21` should refuse the rest is Q774.
+    // **`branches`' entries and `of` are ids, unconditionally** — v0.52, W215, Q774 resolved (P44 (d1)): `FD-V21` refuses
+    // a non-string `of` and a non-string branch entry, so the schema may too (ADR 0132 rule 2). Until then both admitted
+    // a non-string here, because the validator accepted one (W210's conformity reader, B1). A string outside the charset
+    // names no node — every node id is `FD-V16`'s — so `FD-V2` refuses it.
     case "branches":
-      return { type: "array", minItems: 2, uniqueItems: true, items: idOrNonString() };
+      return { type: "array", minItems: 2, uniqueItems: true, items: ref("id") };
     case "of":
-      return idOrNonString();
+      return ref("id");
     case "over":
     case "branch":
       return ref("id");
@@ -425,12 +434,15 @@ function referenceSchema(withSelf, id) {
   };
 }
 function leafSchema(id) {
-  const path = `^(?:${PREDICATE_ROOTS.join("|")})(?:\\.${id})+$`;
+  const path = `^(?:${PREDICATE_ROOTS.join("|")})(?:\\.${keyPathSegment(id)})+$`;
   const scalar = () => ({ type: ["null", "boolean", "number", "string"] });
   const keySchemas = {
     path: { type: "string", pattern: path },
     op: { enum: [...PREDICATE_OPS] },
     value: scalar(),
+    // v0.55 (ADR 0140): the RIGHT side as a key path — `path`'s own pattern, so the two keys cannot be held to different
+    // grammars; (g1)'s *a `needs` key the edge declares* needs the edge's own `needs` and is the validator's alone.
+    valueFrom: { type: "string", pattern: path },
     default: { anyOf: [scalar(), { type: "array", items: scalar() }] },
     length: { const: true }
   };
@@ -438,6 +450,8 @@ function leafSchema(id) {
     description: "A declared comparison over the decision's context.",
     type: "object",
     required: [...PREDICATE_LEAF_REQUIRED],
+    // **Exactly one of `value` / `valueFrom`** (`FD-V42`, v0.55): both satisfy both branches and neither satisfies none.
+    oneOf: [{ required: ["value"] }, { required: ["valueFrom"] }],
     properties: Object.fromEntries(PREDICATE_LEAF_KEYS.map((k) => {
       const s = keySchemas[k];
       if (s === void 0) throw new Error(`definitionSchema: a comparison declares the key "${k}" and no schema is written for it`);
@@ -935,6 +949,7 @@ export {
   isTerminal,
   isTerminalEvent,
   keyPathProblem,
+  keyPathSteps,
   languagesOf,
   lastRecordFor,
   liveToken,

package/dist/browser/scheduler/index.js

@@ -26,7 +26,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-5CVSWDCB.js";
+} from "../chunks/chunk-53EDI674.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";