fyflow-orchestration 0.12.0 → 0.13.0

package/AGENTS.md

@@ -818,7 +818,8 @@ entries are held to the id charset, a non-string refused — as `validateDefinit
 tripped over it, and is refused now. **And the other way, since 0.12.0** (`spec/flow-definition.md` v0.53,
 [ADR 0137](doc/decisions/0137-a-key-path-indexes-an-array-by-a-bracket-suffix-and-a-plain-segment-keeps-its-meaning.md)):
 a gate's key and a comparison's `path` may carry a bracket index — `files[0].series`, `outcome.result.files[0].series` — so both patterns accept it — and
-`KEY_PATH_RE`, the gate key's, is the exported constant whose `source` moved. Only more is accepted.
+`KEY_PATH_RE`, the gate key's, is the exported constant whose `source` moved. Only more is accepted. *(It, the parse and
+the read a host may call are section 4's* Reading a key path the way the library does*.)*
 
 | | |
 |---|---|
@@ -894,14 +895,14 @@ a flow document can say what a branch depends on without any code at all, which
 an agent emit a complete flow. A name still works and is what a predicate that COMPUTES uses.
 
 ```ts run
-import { validateDefinition, type FlowDefinition } from 'fyflow-orchestration';
+import { evaluateWhen, validateDefinition, type FlowDefinition, type When } from 'fyflow-orchestration';
 
 // A `when` is EXACTLY ONE of three shapes, told apart by which keys it carries.
 const flow: FlowDefinition = {
   flowId: 'declared', version: 1, entry: 'score',
   nodes: [
     { id: 'score', kind: 'task', type: 'ScoreWorker', edges: [
-      // 1. a COMPARISON — a key path over the context, an operator, a literal.
+      // 1. a COMPARISON — a key path over the context, an operator, a literal (or `valueFrom`, below).
       { when: { path: 'outcome.result.confidence', op: 'lt', value: 0.5 }, to: 'review' },
       // 2. a flat GROUP — `all` or `any`, whose members are comparisons.
       { when: { any: [
@@ -940,16 +941,41 @@ if (refuse({ path: 'result.confidence', op: 'lt', value: 0.5 })[0] !== 'FD-V43')
 if (refuse({ path: 'outcome.result.name', op: 'matches', value: '^a' })[0] !== 'FD-V44') throw new Error('an unknown operator is FD-V44');
 // FD-V45 — a group is FLAT, and a member naming a registered predicate could be IMPURE.
 if (refuse({ all: [{ any: [{ path: 'outcome.result.a', op: 'eq', value: 1 }] }] })[0] !== 'FD-V45') throw new Error('nesting is FD-V45');
+
+// `valueFrom` (since 0.13.0) — compare against ANOTHER key path over the same context, in place of `value`.
+// Exactly one of the two: both, or neither, is FD-V42. It takes the same roots as `path` (FD-V43).
+if (refuse({ path: 'outcome.result.score', op: 'gte', valueFrom: 'outcome.result.threshold' }).length !== 0) throw new Error('valueFrom alone is valid');
+if (refuse({ path: 'outcome.result.score', op: 'gte', value: 50, valueFrom: 'outcome.result.threshold' })[0] !== 'FD-V42') throw new Error('both is FD-V42');
+if (refuse({ path: 'outcome.result.score', op: 'gte', valueFrom: 'result.threshold' })[0] !== 'FD-V43') throw new Error('a rootless valueFrom is FD-V43');
+// A `needs` path — on either side — reads a key THIS EDGE's `needs` declares; `refuse`'s edge declares none, so FD-V43.
+if (refuse({ path: 'outcome.result.size', op: 'lte', valueFrom: 'needs.limit.max' })[0] !== 'FD-V43') throw new Error('an undeclared needs key is FD-V43');
+
+// What it resolves to is compared as a literal would be — and an ABSENT one is NO MATCH for every operator,
+// so `x gt y` and `x lte y` are BOTH false where `y` is absent. No `default` stands in for it: that is the left's.
+const ask = (when: When, result: unknown) => evaluateWhen(when, { outcome: { result } as never, needs: {} }, new Map());
+const gt: When = { path: 'outcome.result.x', op: 'gt', valueFrom: 'outcome.result.y' };
+const lte: When = { path: 'outcome.result.x', op: 'lte', valueFrom: 'outcome.result.y' };
+if (!ask(gt, { x: 5, y: 3 }) || ask(lte, { x: 5, y: 3 })) throw new Error('5 gt 3, and not 5 lte 3');
+if (ask(gt, { x: 5 }) || ask(lte, { x: 5 })) throw new Error('y absent: both are false');
+// A resolved object or array is no match too, `ne` included — `!==` would have said true.
+if (ask({ path: 'outcome.result.x', op: 'ne', valueFrom: 'outcome.result.y' }, { x: 5, y: { v: 5 } })) throw new Error('ne against an object is no match');
 ```
 
 | | |
 |---|---|
-| `path` | a key path over the context, **rooted at `outcome` or `needs`** — `outcome.result.x`, `outcome.taskId`, `needs.earlier.flag`, and an array element by a bracket index after a key, `outcome.result.items[0].score` (never on the root). No wildcard, no expression |
+| `path` | a key path over the context, **rooted at `outcome` or `needs`** — `outcome.result.x`, `outcome.taskId`, `needs.earlier.flag`, and an array element by a bracket index after a key, `outcome.result.items[0].score` (never on the root). No wildcard, no expression. **A `needs` path names a key THIS EDGE's `needs` declares** (since 0.13.0, `FD-V43`): any other would be absent for ever |
 | `op` | one of `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `startsWith`, and **nothing else** |
-| `value` | a scalar: `null`, a boolean, a finite number or a string |
+| `value` | a scalar: `null`, a boolean, a finite number or a string. **Exactly one of `value` and `valueFrom`** (`FD-V42`) |
+| `valueFrom` | since 0.13.0, in place of `value` — **another key path over the same context**, held to everything `path` is; what it resolves to is compared as a literal would be. **No match where it does not resolve, or resolves to an object or an array** |
 | `default` | optional — what is compared when the path does not resolve **or resolves to `null`**, which is exactly `??`. Without it an absent path is **no match**, and a resolved `null` is compared as the scalar it is |
 | `length` | optional `true` — compare the LENGTH of an array or a string, after `default` |
 
+**The type moved with it, in 0.13.0.** `PredicateLeaf` is a two-member union — `{ value, valueFrom?: never }` or
+`{ valueFrom, value?: never }` over the shared `PredicateLeafBase` — so a comparison with both, or neither, fails to
+compile, and code READING `leaf.value` now sees `PredicateScalar | undefined`: tell the two apart by `'valueFrom' in leaf`.
+`PREDICATE_LEAF_KEYS` gained `valueFrom` and `PREDICATE_LEAF_REQUIRED` lost `value`; `predicateProblem(when, edgeNeeds?)`
+takes the keys an edge's `needs` declares, and asks the `needs` rule only when given them.
+
 **Three things to know before you write one.**
 **A comparison between kinds is no match, never a coercion** — `{ op: 'lt', value: 50 }` is false
 against the string `"9"` where JavaScript's `<` would say true.
@@ -960,6 +986,10 @@ holding `null` as well as a missing one.
 that holds over NUMBERS, and over an absent path where you declared a `default`. Over a value an
 ordering operator cannot compare, a string or a boolean, **both it and its complement are false**.
 `startsWith` has no complement here at all.
+**An absent `valueFrom` is no match for every operator, and nothing makes it otherwise** — `default` and `length`
+are the LEFT side's, and there is no `valueDefault`. So `x gt y` and `x lte y` are BOTH false where `y` is
+absent: route the absent case by its own edge if it matters. And a `valueFrom` resolving to an object or an
+array is no match even for `ne`, where an object on the LEFT with `ne` is still true — the left side is 0.12.0's.
 **A declared predicate CANNOT be impure.** There is no clock, no random source and no way to name
 anything but the context, so re-evaluating it over the same log gives the same answer. A registered
 name has no such guarantee — which is the trade, and why a regular expression, a date window or a
@@ -1097,6 +1127,58 @@ the run did not produce stops the run with an `UnresolvedReference` (`FD-R3`, se
 node's does. **An edge with no `when` may carry a `needs` and nothing will ever read it** — accepted
 and inert, which `spec/flow-definition.md` section 3 records rather than refuses.
 
+### Reading a key path the way the library does — `readKeyPath`, `keyPathSteps`, `KEY_PATH_RE`, `PREDICATE_ROOTS`
+
+**A host that suggests, checks or previews a key path need not keep its own copy of the spelling.** Five names, all
+from the root entry in node, the browser and Deno — `readKeyPath`, `KEY_PATH_RE` and `PREDICATE_ROOTS` since before
+0.12.0, **`keyPathSteps` and its `KeyPathStep` type since 0.13.0** (P45, fyflow-app's pass 6 #2). They are the ones a
+gate's `settings.key`, a comparison's `path` and the wiring check read, so a host using them cannot read a path
+differently from a run.
+
+| name | what it is |
+|---|---|
+| `KEY_PATH_RE` | the GRAMMAR (`spec/flow-definition.md` section 2's KEY PATH): dot-separated object keys, each `[A-Za-z0-9_-]{1,64}` optionally followed by array indexes `[n]` — `n` is `0` or a number with no leading zero, at most 999,999,999 — never an index leading the path; no quoted key, no wildcard, no expression. A gate's `key` is refused `FD-V40` outside it |
+| `keyPathSteps(path)` | the PARSE: a path's steps in order, each `{ key }` or `{ index }` — that union is `KeyPathStep`. **Total**: any string has steps, and a segment the grammar does not spell is ONE literal key (`files[*]` is a key named `files[*]`), so test the path with `KEY_PATH_RE` first |
+| `readKeyPath(value, path)` | the READ: a KEY step is an OWN key of a PLAIN object, an INDEX step an own element of a REAL array; anything else — a missing key, `null`, an array under a key step, a class instance, a hole — is `undefined`. **A plain numeric segment is a KEY**: `xs.1` is nothing over an array, `xs[1]` is its element. The value at the end is returned whatever it is |
+| `PREDICATE_ROOTS` | a task's or a join's edge comparison's two ROOTS, `outcome` and `needs` (`FD-V43`): the first key of its `path` (and of a `valueFrom`), read up to the first `.` or `[`; never indexed, never alone. **An `if` gate's one root, `input`, is not a public name** — section 19 |
+
+```ts run
+import { KEY_PATH_RE, keyPathSteps, PREDICATE_ROOTS, readKeyPath, type KeyPathStep } from 'fyflow-orchestration';
+
+const value = { files: [{ name: 'a.csv' }, { name: 'b.csv' }], xs: ['p', 'q'] };
+
+// The grammar, the parse and the read of one path.
+if (!KEY_PATH_RE.test('files[0].name')) throw new Error('files[0].name is a key path');
+const steps: KeyPathStep[] = keyPathSteps('files[0].name');
+if (JSON.stringify(steps) !== '[{"key":"files"},{"index":0},{"key":"name"}]') throw new Error(`steps: ${JSON.stringify(steps)}`);
+if (readKeyPath(value, 'files[0].name') !== 'a.csv') throw new Error('files[0].name reads a.csv');
+if (readKeyPath(value, 'files[2].name') !== undefined) throw new Error('past the end is nothing');
+
+// A plain numeric segment is a KEY, and an array has none: xs.1 is nothing where xs[1] is 'q'.
+if (readKeyPath(value, 'xs[1]') !== 'q' || readKeyPath(value, 'xs.1') !== undefined) throw new Error('xs.1 is a key');
+
+// A malformed path is refused by the grammar — and the parse, being total, still answers.
+for (const bad of ['files[*].name', 'xs[01]', '[0].x', 'a..b']) {
+  if (KEY_PATH_RE.test(bad)) throw new Error(`${bad} is not a key path`);
+}
+const first = keyPathSteps('files[*].name')[0]!;
+if (!('key' in first) || first.key !== 'files[*]') throw new Error('an unspelled segment is one literal key');
+
+// A comparison's path on an edge: a key path whose first key is a root, with a key after it. NECESSARY, not
+// sufficient: FD-V43 also holds a `needs.X` path to an X the edge's own `needs` declares (since 0.13.0), which
+// these names cannot see — `validateDefinition` is the authority on a whole flow.
+const edgePath = (p: string) => KEY_PATH_RE.test(p) && (PREDICATE_ROOTS as readonly string[]).includes(p.split(/[.[]/)[0]!) && /^[A-Za-z0-9_-]+\./.test(p);
+if (!edgePath('outcome.result.files[0].size') || edgePath('result.size') || edgePath('outcome[0].x') || edgePath('needs')) {
+  throw new Error('the grammar and the roots, as FD-V43 reads them on a path alone');
+}
+```
+
+**What is not exported, and why.** No *is this a valid comparison path* function: the grammar and the roots are
+these two values, and a second spelling of `FD-V43` would be a second thing to hold in step — `validateDefinition`
+is the authority on a whole flow. Nor the declared-comparison internals `evalLeaf` and `evaluateDeclared`: a
+`when` is evaluated over a `DecisionContext` by **`evaluateWhen(when, ctx, predicates)`**, which IS public from the root entry
+(`predicates` a `Map` of the registered names it may call), and the built-in `if` evaluates its `when` over `{ input }` inside a run.
+
 ---
 
 ## 5. Fan-out, join, and which policy to pass
@@ -5387,7 +5469,7 @@ registered:
 |---|---|---|
 | **settings** | `{ when }` — a comparison or a flat `all`/`any` group, section 4's grammar, whose paths start at **`input`**: the value that reached the gate | `{ key, cases }` — `key` a key path as `distinct`'s, `cases` a map from a CASE NAME to a scalar or a non-empty array of scalars |
 | **routes** | `then`, and `else` — the DEFAULT, so an edge with no `route` is the fallback | every case name, then `default` — the DEFAULT. So a case left unwired is refused at load, NAMING the case (`FD-V41`) |
-| **matches** | `when` holds over `{ input }`, by the evaluator a task edge's `when` uses — the same operators, absent rule, `default` and `length` | the case one of whose values is `===` the resolved key: `"1"` and `1` are two values, and a value in two cases is refused at load |
+| **matches** | `when` holds over `{ input }`, by the evaluator a task edge's `when` uses — the same operators, absent rule, `default` and `length`, and since 0.13.0 a `valueFrom` over `input` too (`input.a` `lt` `valueFrom: "input.b"`; `input.b` absent is no match, so `else`) | the case one of whose values is `===` the resolved key: `"1"` and `1` are two values, and a value in two cases is refused at load |
 | **refused at load (`FD-V40`)** | a registered predicate NAME (a gate has no outcome to hand it), a root other than `input` — or `input` alone — and every `when` defect section 4 refuses, named | a case named `default` or outside the route charset, a value that is not a scalar, an empty array, a value in two cases or twice in one, an empty `cases` |
 
 - **Neither reads the gate's memory**: two branches with one key take the same route at a `switch`, where
@@ -5640,8 +5722,9 @@ is underneath it.**
    library's own sub-path — `import { jsonata } from 'fyflow-orchestration/jsonata'` — so it is one
    import and one object entry with no logic in it, but it is not nothing and it is not a domain
    worker. **A flow that only SELECTS needs no adapter; a flow that COMPUTES does.**
-2. **A comparison reads ONE path and compares it to ONE literal.** It cannot name a second path and
-   it cannot do arithmetic, so *is the mean below the threshold this run carries* is not a comparison.
+2. **A comparison reads ONE path and compares it to ONE literal — or, since 0.13.0, to ONE other path
+   (`valueFrom`).** It cannot do arithmetic, so *is the threshold this run carries* is a comparison now
+   (`valueFrom: "needs.cfg.threshold"`, the edge declaring `cfg`) and *is the MEAN below it* is not.
    **The route around it is data**: a tier-three `Transform` node computes the answer and the `when`
    reads `outcome.result.<field>`. That is what the flow below does, and it is the one place the
    three-tier rule's *reshape for … a decision* is load-bearing rather than advisory — a `transform`
@@ -5651,7 +5734,8 @@ is underneath it.**
 > **A comparison whose `value` is meant to be a path is NOT refused** — `{ "op": "eq", "value":
 > "needs.cfg.threshold" }` is a perfectly good string comparison against the literal text, and it is
 > false for ever. The grammar catches a wrong ROOT (`FD-V43`) and nothing catches this
-> ([Q456](doc/questions/q456.md)). Write the literal, or compute the comparison in a `Transform` node.
+> ([Q456](doc/questions/q456.md)). Write the literal — or, since 0.13.0, write the path as `valueFrom`, which is
+> what reads it.
 
 > **This flow is `examples/flows/ui-emitted.flow.json` and this registry is
 > `examples/ui-registry.json`, with the SCHEMAS reduced to what these three verdicts turn on.** The

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.12.0`.
+Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.13.0`.
 
 ## Install
 

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

@@ -402,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;
@@ -755,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 = [];
@@ -783,29 +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 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` };
-  }
-  const path = o.path;
+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} path ${JSON.stringify(path)} is not a key path \u2014 ${KEY_PATH_WORDS}` };
+    return { rule: "FD-V43", message: `${where} ${key} ${JSON.stringify(path)} is not a key path \u2014 ${KEY_PATH_WORDS}` };
   }
-  const first = path.split(".")[0];
+  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} path ${JSON.stringify(path)} starts at ${JSON.stringify(root)}, ${scope.foreignRoot(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} 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])` };
+    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(", ")} }` };
   }
-  if (path.split(".").length < 2) {
-    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is a root alone ${scope.rootAlone(root)}` };
+  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 and exactly one of ${RIGHT_SIDE_KEYS.map((k2) => JSON.stringify(k2)).join(" or ")}` };
+  }
+  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 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)) {
@@ -815,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` };
   }
@@ -830,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);
@@ -845,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",
@@ -866,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));
@@ -1360,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`);
@@ -7028,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,7 +152,7 @@ import {
   visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-4JFQX7DL.js";
+} from "./chunks/chunk-53EDI674.js";
 
 // src/definition/definition-schema.ts
 var DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
@@ -237,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."
 };
@@ -251,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; a key past the root may be followed by array indexes [n], the root never (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).",
@@ -438,6 +440,9 @@ function leafSchema(id) {
     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 }
   };
@@ -445,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`);
@@ -942,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-4JFQX7DL.js";
+} from "../chunks/chunk-53EDI674.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";

package/dist/node/chunks/{chunk-4JFQX7DL.js → chunk-53EDI674.js}

@@ -402,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;
@@ -755,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 = [];
@@ -783,29 +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 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` };
-  }
-  const path = o.path;
+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} path ${JSON.stringify(path)} is not a key path \u2014 ${KEY_PATH_WORDS}` };
+    return { rule: "FD-V43", message: `${where} ${key} ${JSON.stringify(path)} is not a key path \u2014 ${KEY_PATH_WORDS}` };
   }
-  const first = path.split(".")[0];
+  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} path ${JSON.stringify(path)} starts at ${JSON.stringify(root)}, ${scope.foreignRoot(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} 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])` };
+    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(", ")} }` };
   }
-  if (path.split(".").length < 2) {
-    return { rule: "FD-V43", message: `${where} path ${JSON.stringify(path)} is a root alone ${scope.rootAlone(root)}` };
+  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 and exactly one of ${RIGHT_SIDE_KEYS.map((k2) => JSON.stringify(k2)).join(" or ")}` };
+  }
+  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 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)) {
@@ -815,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` };
   }
@@ -830,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);
@@ -845,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",
@@ -866,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));
@@ -1360,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`);
@@ -7028,6 +7071,7 @@ export {
   canonical,
   findings,
   describeFindings,
+  keyPathSteps,
   readKeyPath,
   ID_RE_COPY,
   KINDS_COPY,

package/dist/node/index.js

@@ -111,6 +111,7 @@ import {
   isTerminal,
   isTerminalEvent,
   keyPathProblem,
+  keyPathSteps,
   languagesOf,
   lastRecordFor,
   liveToken,
@@ -151,7 +152,7 @@ import {
   visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-4JFQX7DL.js";
+} from "./chunks/chunk-53EDI674.js";
 
 // src/definition/definition-schema.ts
 var DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
@@ -237,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."
 };
@@ -251,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; a key past the root may be followed by array indexes [n], the root never (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).",
@@ -438,6 +440,9 @@ function leafSchema(id) {
     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 }
   };
@@ -445,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`);
@@ -942,6 +949,7 @@ export {
   isTerminal,
   isTerminalEvent,
   keyPathProblem,
+  keyPathSteps,
   languagesOf,
   lastRecordFor,
   liveToken,

package/dist/node/scheduler/index.js

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

package/dist/types/src/definition/condition.d.ts

@@ -6,9 +6,11 @@
  * is*). [W154](../../doc/work-items/w154-the-built-in-if-and-switch.md) exception (p): until it, the `if` reached
  * the evaluator through `routing.ts`, which imports `src/definition` — a module cycle in a published library.
  *
- * **Not re-exported by `index.ts`.** `readKeyPath` stays public through `validate.ts`' re-export, and
- * `evaluateWhen` through `routing.ts`, so the package's exported names do not move. Nothing here imports anything
- * but types.
+ * **Not re-exported WHOLE by `index.ts`.** Three names here are public, each through `validate.ts`' re-export:
+ * `readKeyPath` (public since W92, defined in `validate.ts` then; through this re-export since W154), and `keyPathSteps`
+ * with its `KeyPathStep` (since W220, P45 (c1) — fyflow-app's pass 6 #2: a host reads a key path with the library's own
+ * parse and read rather than a copy of the spelling). `evalLeaf` and `evaluateDeclared` are NOT (P45 decision 1): a
+ * host evaluates a `when` by `evaluateWhen`, public through `routing.ts`. Nothing here imports anything but types.
  */
 import type { PredicateLeaf, When } from './types.js';
 /**
@@ -52,7 +54,8 @@ export declare function readKeyPath(value: unknown, path: string): unknown;
  * closure over anything — so a declared predicate **CANNOT** be impure, which is strictly stronger
  * than [Q9](../../doc/questions/q9.md)'s measured result for a function (evaluating twice caught
  * 1 impurity shape of 4) and is asserted rather than argued. `scope` is a task edge's `DecisionContext`
- * or an `if` gate's `{ input }` (W154) — the path is read off it by `readKeyPath`, and that is the only read.
+ * or an `if` gate's `{ input }` (W154) — the path, and since v0.55 a `valueFrom`, is read off it by `readKeyPath`,
+ * and that is the only read.
  *
  * **Total by construction**, because `FD-V42`-`FD-V45` refuse everything this does not handle at
  * `new Driver`. The `default:` arm below is the assertion that they held; `unknownOp` is the error it throws,

package/dist/types/src/definition/types.d.ts

@@ -86,10 +86,12 @@ export type PredicateOp = typeof PREDICATE_OPS[number];
 /** The two roots a predicate's key path may start at — the two members of `DecisionContext`, and no other. */
 export declare const PREDICATE_ROOTS: readonly ["outcome", "needs"];
 /**
- * **What a declared comparison may compare AGAINST** — a scalar, and nothing else (`FD-V44`).
+ * **What a declared comparison's LITERAL may be** — a scalar, and nothing else (`FD-V44`).
  * Every one of the ten predicate bodies in this tree compares to one (`0.5`, `50`, `true`,
  * `'r1:publish:'`, `0`), and admitting an object would need a deep-equality semantics with no
- * instance and no obvious right answer for `NaN`, key order or a prototype.
+ * instance and no obvious right answer for `NaN`, key order or a prototype. *Since v0.55 a comparison
+ * may compare against ANOTHER key path instead — `valueFrom` (ADR 0140) — and a resolved object or
+ * array there is no match, for the same reason.*
  */
 export type PredicateScalar = null | boolean | number | string;
 /** A registered predicate NAME, resolved against the registry at instantiation (`FD-V4`). */
@@ -97,21 +99,20 @@ export interface PredicateName {
     predicate: string;
 }
 /**
- * **One comparison over the decision's own context** — `FD-V43` owns the path and `FD-V44` the
- * operator and the value.
+ * **What every comparison carries, whichever right side it names** — `FD-V43` owns the path and `FD-V44` the
+ * operator and the modifiers.
  */
-export interface PredicateLeaf {
+export interface PredicateLeafBase {
     /**
      * A KEY PATH over the `DecisionContext` itself, read by `readKeyPath` — the same resolution a
      * gate's `settings.key` gets, measured unchanged at this scope. **Its first segment is `outcome`
      * or `needs` and nothing else** (`FD-V43`), because a first segment that is neither resolves to
      * `undefined` in silence and a typo would be a wrong key rather than a refusal. A key past the root may
      * carry array indexes — `outcome.result.items[0].score` — and the root never does (v0.53, ADR 0137).
+     * **A `needs` path names a key that edge's `needs` DECLARES** (v0.55, P45 (g1)): any other is absent for ever.
      */
     path: string;
     op: PredicateOp;
-    /** The literal compared against. Required — there is no operator here that takes one operand. */
-    value: PredicateScalar;
     /**
      * **What is compared when the path does not resolve, or resolves to `null`.** Absent is NO MATCH
      * by default; where this is declared it is substituted instead — which is `?? 0` and `?? []`
@@ -136,6 +137,29 @@ export interface PredicateLeaf {
      */
     length?: true;
 }
+/**
+ * **One comparison over the decision's own context — against a LITERAL, or against ANOTHER KEY PATH** (v0.55,
+ * [ADR 0140](../../doc/decisions/0140-a-comparison-may-compare-against-another-key-path-and-an-absent-one-is-no-match.md),
+ * P45 (a1)). Exactly one of `value` / `valueFrom` (`FD-V42`), so a TWO-member union rather than one interface with
+ * both optional — `PredicateGroup`'s precedent: `{ path, op }` with neither, and both at once, fail at L0. **The type
+ * change, stated** (P45 decision 8): until 0.13.0 `value` was required, so code READING `leaf.value` now sees
+ * `PredicateScalar | undefined` and tells the two apart by `'valueFrom' in leaf`.
+ */
+export type PredicateLeaf = (PredicateLeafBase & {
+    /** The literal compared against. */
+    value: PredicateScalar;
+    valueFrom?: never;
+}) | (PredicateLeafBase & {
+    /**
+     * **A key path over the SAME context, compared against as a literal would be** — the same roots as `path` (and
+     * the same `needs` rule), held to `FD-V43`; resolved by `readKeyPath` when the comparison is asked. Type-strict, a
+     * resolved `null` compared as `null`; **a resolved object or array is NO MATCH for every operator, `ne` included**;
+     * and **an ABSENT one is NO MATCH** — the left side's `default` does not stand in for it, so `x gt y` and `x lte y`
+     * are both false where `y` is absent. `default` and `length` are the LEFT side's only.
+     */
+    valueFrom: string;
+    value?: never;
+});
 /**
  * **A FLAT group — `all` or `any`, and its members are LEAVES.** Nesting is refused by name
  * (`FD-V45`), and so is a `{ predicate }` member: a group holding a registered name could be

package/dist/types/src/definition/validate.d.ts

@@ -18,7 +18,8 @@
  * ADR 0002 rule 3: this runs in full, at instantiation, before any task is queued.
  */
 import type { Finding, FlowDefinition, GateType, GateTypes, JsonSchema, StaticGateType, LanguageAdapter, Languages, NodeTypeEntry, NodeTypes, Pools, Registry, WorkerEntry, Workers } from './types.js';
-export { readKeyPath } from './condition.js';
+export { keyPathSteps, readKeyPath } from './condition.js';
+export type { KeyPathStep } from './condition.js';
 declare const KINDS: readonly ["task", "fanout", "map", "join", "end", "gate", "ask"];
 /**
  * **`FD-V16`'s charset — a flow's and a node's id** ([spec/task-id.md](../../spec/task-id.md)'s) — v0.50 (W210,
@@ -269,7 +270,7 @@ export declare const PREDICATE_GROUP_KEYS: readonly string[];
  * has owned *an edge's `when` names a predicate absent from the registry* since P1 and whose only
  * change at v0.27 is where the name is written.
  */
-export declare function predicateProblem(v: unknown): {
+export declare function predicateProblem(v: unknown, edgeNeeds?: readonly string[]): {
     rule: string;
     message: string;
 } | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fyflow-orchestration",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Flow orchestration over fyflow-scheduler: sequence, decision, fan-out and join",
   "keywords": [
     "workflow",