fyflow-orchestration 0.12.0 → 0.14.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
@@ -2605,7 +2687,7 @@ flow, and the class says which document to open.
 member and the group's key; `GroupNotBuildable` — a group type with no `create`; since W89, `RunIdInUse`
 — a `start` or `resume` naming a run id that runtime has already built a driver for, a finished run's included (`RN-R25`, ADR 0091);
 and, since W163, **`LimitKeyMissing`** — a `start` or `resume` given no `createTask`, of a flow a node of which reaches a
-group the built-in `KeyedRateLimitGroup` factory built (`FD-R6`, [ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md), section 12), its `at` the node.
+group a built-in keyed factory built — `KeyedRateLimitGroup`, or since spec v0.56 `KeyedConcurrentLimitGroup` (`FD-R6`, [ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md), section 12), its `at` the node.
 *(`LanguageNotBuilt` — a flow transforming on a type no pool was built for — was another until W162 removed it
 with `createRuntime`'s `flows`: every typed pool carries every registered language since
 [ADR 0096](doc/decisions/0096-a-runtime-is-its-registry-and-start-refuses-from-runtime-check.md), section 12.)* A bare
@@ -3155,7 +3237,7 @@ if (!haltedRun.haltedBy?.startsWith('UncloneableResult')) throw new Error(`halte
 |---|---|
 | flow-level **retry** — re-dispatching a NODE under a new attempt, possibly routing elsewhere | **task-level retry IS built** since [W58](doc/work-items/w58-what-a-node-says-about-its-own-task.md): declare `retryPolicy` on the node (section 3) and the scheduler retries inside the same task id, reported on the record's `attempts`. Re-dispatching the node is [Q16](doc/questions/q16.md)'s other half and the task id's fourth segment, and nothing mints one |
 | **`runtime.register()`** — adding node types, pools, groups or languages to a RUNNING runtime | **declined** — [P37](doc/plans/p37-a-runtime-is-its-registry.md) decision 1, [ADR 0096](doc/decisions/0096-a-runtime-is-its-registry-and-start-refuses-from-runtime-check.md): `fyflow-scheduler` cannot add a pool after construction. A changed registry is a NEW runtime; a run on the old one finishes there or moves by stop-and-resume ([P34](doc/plans/p34-what-cancelling-stopping-and-pausing-a-run-do.md)). **A FLOW is not a registry entry**: `runtime.check(flow)`, then `runtime.start(flow, …)`, takes any flow the registry can run, at any time (section 12) |
-| **a `limitKey` from the FLOW** — a node or a document saying which key a task of a keyed group is counted under | **deferred** — [Q248](doc/questions/q248.md). Pass `start` a `createTask` that sets `limitKey` on the task it builds, or register a group type whose `create` builds a `KeyedRateLimitGroup` with a `keyFrom` (section 12). A node reaching a document's built-in keyed group with neither is refused before its run starts — `FD-R6`, `LimitKeyMissing` |
+| **a `limitKey` from the FLOW** — a node or a document saying which key a task of a keyed group is counted under | **deferred** — [Q248](doc/questions/q248.md). Pass `start` a `createTask` that sets `limitKey` on the task it builds, or register a group type whose `create` builds a `KeyedRateLimitGroup` or a `KeyedConcurrentLimitGroup` with a `keyFrom` (section 12). A node reaching a document's built-in keyed group with neither is refused before its run starts — `FD-R6`, `LimitKeyMissing` |
 | **a `start()` that checks a TRANSFORMING task's payload** — the transform run first and its result held to the `inputSchema` | **no** — [ADR 0101](doc/decisions/0101-a-transforming-task-is-not-held-at-start.md): `start()` is synchronous and the transform runs only in the worker, so a task declaring one is UNCHECKED at `start` (`FD-R4`), as a worker declaring no `inputSchema` is. Call `givenVerdict(registry, flow, task, received)` — `tryTransform(…, { input: received })` on the declared transform — first, on each transforming target with the value it RECEIVES (section 15), then start |
 | **redaction by `writeOnly`** — a schema annotation keeping a value out of what a run retains or reports | **no** — [ADR 0098](doc/decisions/0098-four-annotations-join-the-schema-subset-and-constrain-nothing.md) rule 4: `writeOnly`, like `readOnly`, `title` and `description`, is admitted as an annotation since v0.36, held to its shape and read by nothing after. Redact in your own code, before the value reaches a run (section 13) |
 | **pool options on a CLASS type's instance**, and the scheduler's `idleCheckIntervalMs`, `requeueFailedTasks` and `maxWorkerRestarts` anywhere | **no** — [ADR 0099](doc/decisions/0099-a-named-instance-of-a-document-type-may-declare-its-own-pool-options.md) rules 4 and 7: a named instance of a DOCUMENT type may declare `pool` (section 13); a class computes its pool from the instance's `config` and key, so give it a `configSchema` knob. The three are refused as undeclared keys |
@@ -3262,7 +3344,7 @@ if (Object.keys(runtime.groups).join() !== 'gate') throw new Error(`groups: ${Ob
 
 **A custom group type is a FACTORY, and the runtime holds its output to what the scheduler CALLS.**
 The document names a group by KEY with a `type`; the code supplies `{ configSchema?, create(config,
-key) }` under that type name; the three built-ins are pre-registered in the same shape. What comes
+key) }` under that type name; the five built-ins are pre-registered in the same shape (section 13). What comes
 back is checked for ADR 0055's six members and refused by name otherwise. Read the counts off the
 object the runtime built — [W70](doc/work-items/w70-a-flow-that-decides-and-a-custom-group-on-the-runtime.md):
 
@@ -3294,8 +3376,9 @@ class CountingGroup extends EventTarget implements ResourceGroup {
 }
 
 // THE REGISTRY declares the group by KEY, with its TYPE by name and its config; the CODE supplies the
-// factory for that type name — `{ configSchema?, create(config, key) }`. The three built-ins,
-// `ConcurrentLimitGroup`, `RateLimitGroup` and `KeyedRateLimitGroup`, are pre-registered in the same
+// factory for that type name — `{ configSchema?, create(config, key) }`. The five built-ins,
+// `ConcurrentLimitGroup`, `RateLimitGroup`, `KeyedRateLimitGroup`, `UnitGroup` and
+// `KeyedConcurrentLimitGroup` (section 13), are pre-registered in the same
 // shape, so `"type": "ConcurrentLimitGroup"` needs no code at all. A node type names the groups its
 // pool's tasks acquire.
 const registry: RegistryDocument = {
@@ -3362,14 +3445,14 @@ so a flow published after the runtime started runs on it, transforming on any ty
 rules — every one but `FD-R6`, below — before any run id is spent, so the two cannot disagree: *register* a flow by checking it, then
 start it. `check` leaves out what depends on a RUN rather than the flow — a payload `FD-R4` refuses,
 and a run id in use. **One finding it returns is not a definition defect: `FD-R6`**
-([ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md)) — a node reaching a group of the BUILT-IN `KeyedRateLimitGroup` type, through the
+([ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md)) — a node reaching a group of a BUILT-IN keyed type — `KeyedRateLimitGroup`, or (spec v0.56) `KeyedConcurrentLimitGroup` (section 13) — through the
 pool it runs on — the named instance its `pool` says, else its type's default — or its `workerGroups`. The runtime builds that group with no `keyFrom`, so the scheduler counts each task
 under its `limitKey` — and nothing sets one unless you pass `start` a `createTask` that does, `(c) => new FyflowTask({
 ...c, limitKey: tenant })`; without one the scheduler's `addTask` throws. So `start` with no `createTask` throws
 **`LimitKeyMissing`** for it — after any `InvalidDefinition`, before any run id is spent — and with one, `FD-R6` refuses
 nothing (a factory that sets no key meets the scheduler's own throw). `check` cannot know what you will pass, so it
 reports `FD-R6` as if you pass none: filter it out by `f.rule` if you start with a keying `createTask`. A group a CODE
-group type builds — a `KeyedRateLimitGroup` with a `keyFrom` — is never `FD-R6`. A pool's `residentGroups` is not read
+group type builds — a keyed group with a `keyFrom` — is never `FD-R6`. A pool's `residentGroups` is not read
 here: a built-in keyed group held RESIDENT is refused earlier, at `createRuntime` (`DerivationRefused`, section 13,
 [Q619](doc/questions/q619.md)). A key derived from the flow is
 [Q248](doc/questions/q248.md), deferred. **And `createRuntime` refuses a malformed `defaultRetryPolicy`** —
@@ -3539,10 +3622,10 @@ anywhere else.)* This library's listener boundary is written against **0.3.0 sem
 `task.progress`'s detail changed shape at 0.3.0 (the id is `id`, not `taskId`), the second
 `task.user_action` dispatch site arrived there, and `task.timestamp` did not exist before it.
 **`core/FyflowScheduler.ts` was byte-identical between 0.3.0, 0.5.1 and 0.5.2**; it is not at the
-current pin, and W157 re-read what this library rests on there rather than inferring it: the
+current pin, and W157 and W224 re-read what this library rests on there rather than inferring it: the
 `user_action` pair is unchanged on both of its paths, and `task.progress` is built from the same
 fields. What 0.5.1 added is a `worker.setup.*` / `worker.teardown.*` event family this library
-subscribes to not at all. **The current pin adds a sixth task state, `cancelled`, reached only through
+subscribes to not at all. **A sixth task state, `cancelled`, arrived at 0.6.0 and is still the pin's (re-read by W224), reached only through
 `scheduler.cancel(id)`**, and a run hears it: a cancelled task ends its run `cancelled` and settles
 its `done` (section 6, [P33](doc/plans/p33-what-a-run-does-when-a-task-ends-cancelled.md)) — on real
 workers in ladder L6, a task cancelled while running and while queued — and `driver.cancel` asks for one on
@@ -3874,11 +3957,88 @@ a hand-written `NodeTypeDefinition`, or a copy of a resolved one, is a class to
 **A `residentGroups` naming a group of the built-in `KeyedRateLimitGroup` type is refused at `createRuntime`** (v0.39,
 [Q619](doc/questions/q619.md), W169) — `DerivationRefused`, naming the pool and the group, whether a type, a named
 instance or your class's `pool()` put it there. The scheduler resolves no key for a RESIDENT group, so every worker
-holding it would be counted in ONE `""` bucket, in silence. Name a keyed group in `groups` instead — each task is then
-counted under its `limitKey` (`FD-R6`, section 12) — or hold a `ConcurrentLimitGroup` or `RateLimitGroup` resident. A
+holding it would be counted in ONE `""` bucket, in silence. **A built-in `KeyedConcurrentLimitGroup` is refused the same
+way** (spec v0.56, W225) — the scheduler rejects one held resident at construction. Name a keyed group in `groups` instead — each task is then
+counted under its `limitKey` (`FD-R6`, section 12) — or hold a `ConcurrentLimitGroup` or `RateLimitGroup` resident (or a `UnitGroup`). A
 group your own `code.groupTypes` factory builds is never refused. **BREAKING in 0.8.0**: such a document built a
-runtime at 0.7.0. **`bootstrap` called by hand is not covered** — it is handed group OBJECTS and cannot tell the
+runtime at orchestration 0.7.0. **`bootstrap` called by hand is not covered** — it is handed group OBJECTS and cannot tell the
 built-in factory's keyed group from your own — as a `Driver` built by hand is not covered by `FD-R6`.
+
+**Units with names, a limit per key, and a resident REQUEST — as data** — `spec/flow-definition.md` v0.56,
+[ADR 0143](doc/decisions/0143-unit-and-keyed-concurrent-groups-are-built-ins-and-a-resident-request-is-checked-against-the-group.md),
+[W225](doc/work-items/w225-unit-and-keyed-concurrent-groups-and-a-resident-request.md). Two more built-in group types, beside
+`ConcurrentLimitGroup`, `RateLimitGroup` and `KeyedRateLimitGroup`, each the scheduler's own class:
+
+| `type` | `config` | built as |
+|---|---|---|
+| `UnitGroup` | `{ "units": 2 }` (units `0` and `1`) or `{ "units": ["gpu0", "gpu1"] }` — at least one, the names DISTINCT | `new UnitGroup(units, { id: key })` — a hold is granted named units; no `requestFrom` |
+| `KeyedConcurrentLimitGroup` | `{ "limit": 4, "limits": { "E:": 1 } }` — every per-key limit a positive integer | `new KeyedConcurrentLimitGroup(limit, { id: key, limitFor })`, `limitFor(k)` reading a COPY of `limits`, else `limit`; no `keyFrom` |
+
+A repeated unit, or a per-key limit that is not a positive integer, is `GroupConfigRefused` naming the group. **A
+`KeyedConcurrentLimitGroup` is held to `KeyedRateLimitGroup`'s rules**: a node reaching one is `FD-R6` (section 12), and one
+held resident is refused, as above. **A `residentGroups` value may be a REQUEST** — `{ "gpu": { "cost": 1, "from":
+["gpu1"] } }`, `{ cost?, from?, prefer? }`: `from` the units a worker of the pool may hold, `prefer` a hint that never
+blocks, each a non-empty list of distinct ids (an integer for a `UnitGroup` declared by count). **A resident cost is a
+positive INTEGER** — a fraction, which the scheduler throws on, was accepted until spec v0.56. Every cost and request is
+held against the group it names when the runtime is built, `DerivationRefused` naming the pool and the group, each a pool
+the scheduler would throw on at construction: an id a `UnitGroup` lacks, a cost above `from`'s size or above a group's
+limit (a `RateLimitGroup`'s smallest window), and `from` / `prefer` on a `ConcurrentLimitGroup` or `RateLimitGroup`, which
+take no request — `{ cost }` alone is a cost for any group. A request to a group your `code.groupTypes` factory builds is
+handed on untouched WITHIN the request shape `{ cost?, from?, prefer? }`, for its own `checkRequest` — a request
+language beyond that shape is not declarable in a document. A TASK's request is its `units`, set by your `createTask`; nothing in a
+flow declares one.
+
+```ts run
+import { createRuntime } from 'fyflow-orchestration/scheduler';
+import { DerivationRefused, GroupConfigRefused, type FlowDefinition, type RegistryDocument } from 'fyflow-orchestration';
+import { KeyedConcurrentLimitGroup, UnitGroup } from 'fyflow-scheduler';
+
+// Two cards, a worker per card, and this pool pinned to the second; a per-disk limit with a slow USB disk.
+const registry = (resident: unknown, units: unknown = ['gpu0', 'gpu1']): RegistryDocument => ({
+  workers: { ingest: { url: '../../examples/workers/ingest.ts' } },
+  groups: {
+    gpu: { type: 'UnitGroup', config: { units } },
+    disk: { type: 'KeyedConcurrentLimitGroup', config: { limit: 4, limits: { 'E:': 1 } } },
+  },
+  nodeTypes: {
+    Model: { worker: 'ingest', inline: true, pool: { idleTimeout: 1000, residentGroups: resident as never } },
+    Copy: { worker: 'ingest', inline: true, groups: ['disk'] },
+  },
+});
+
+const runtime = createRuntime(registry({ gpu: { cost: 1, from: ['gpu1'] } }), {}, { base: import.meta.url });
+const gpu = runtime.groups['gpu'] as unknown as UnitGroup;
+const disk = runtime.groups['disk'] as unknown as KeyedConcurrentLimitGroup;
+if (!(gpu instanceof UnitGroup) || gpu.getFreeUnits().join() !== 'gpu0,gpu1') throw new Error('the scheduler`s own UnitGroup, both cards free');
+if (!(disk instanceof KeyedConcurrentLimitGroup) || disk.getKeyMetrics('E:').limit !== 1 || disk.getKeyMetrics('C:').limit !== 4) {
+  throw new Error('the per-key limits: E: 1, any other disk 4');
+}
+// The pool is handed the request as declared — the scheduler grants this pool's workers gpu1 and nothing else.
+if (JSON.stringify(runtime.pools['Model']!.spec.residentGroups) !== '{"gpu":{"cost":1,"from":["gpu1"]}}') throw new Error('the request');
+
+// A node reaching the keyed group needs a `limitKey`, which only your createTask sets: FD-R6, as for KeyedRateLimitGroup.
+const copy: FlowDefinition = {
+  flowId: 'copy', version: 1, entry: 'c',
+  nodes: [{ id: 'c', kind: 'task', type: 'Copy', edges: [{ to: 'done' }] }, { id: 'done', kind: 'end', outcome: 'completed' }],
+};
+if (runtime.check(copy).map((f) => f.rule).join() !== 'FD-R6') throw new Error('FD-R6 at the node reaching `disk`');
+await runtime.shutdown();
+
+// What the scheduler would throw on at construction is refused here, naming the pool and the group.
+const refusal = (doc: RegistryDocument): Error => {
+  try { createRuntime(doc, {}, { base: import.meta.url }); } catch (e) { return e as Error; }
+  return new Error('expected a refusal');   // not a refusal class, so every check below throws
+};
+const missing = refusal(registry({ gpu: { from: ['gpu7'] } }));
+if (!(missing instanceof DerivationRefused) || !missing.message.includes('node type "Model"') || !missing.message.includes('unit "gpu7"')) throw new Error(missing.message);
+const tooMany = refusal(registry({ gpu: { cost: 2, from: ['gpu1'] } }));
+if (!(tooMany instanceof DerivationRefused) || !tooMany.message.includes('a cost of 2 from 1')) throw new Error(tooMany.message);
+const keyedResident = refusal(registry(['disk']));
+if (!(keyedResident instanceof DerivationRefused) || !keyedResident.message.includes('KeyedConcurrentLimitGroup')) throw new Error(keyedResident.message);
+const twice = refusal(registry(['gpu'], ['gpu0', 'gpu0']));
+if (!(twice instanceof GroupConfigRefused) || twice.at !== 'gpu') throw new Error(twice.message);
+```
+
 **Your worker's `run(payload, context)` gets the scheduler's own task context as its second argument** —
 the same object the scheduler handed the envelope worker, so `context.signal` (an `AbortSignal`, aborted
 when `scheduler.cancel(taskId)` is called for the task) and `context.emit(name, data)` (a `task.message`
@@ -3888,6 +4048,62 @@ pass `onTaskMessage` to `start` (since 0.8.0, section 8) and each message of the
 its run, node, branch and attempts as fields — or listen for it on `runtime.scheduler` yourself, as before; what
 cancelling a task does to its RUN is section 6's.
 
+**Which UNITS your worker holds reaches it in both places the scheduler puts it** — P46,
+[W226](doc/work-items/w226-grants-reach-a-types-worker-the-reply-and-p46s-close.md), held on real workers by ladder L6's
+*W226 exit* block, threaded and inline, in Node 24 and Deno. The constructor's second argument is the scheduler's own
+**worker context**, so **`workerContext.grants`** is what the worker's `residentGroups` granted it — a `UnitGroup`'s
+units as an array, `{ gpu: ['gpu1'] }` — set BEFORE the constructor runs, so `setup()` can load onto that card; keep the
+argument (a class extending the scheduler's `BaseWorker` passes it to `super` and reads `this.workerContext`). `run`'s
+second argument is the task's **`context`**, and **`context.grants`** is that attempt's: the task's own units plus its
+worker's resident ones — in the scheduler's words, *"its own winning on a clash"*, so a task holding the group its worker
+holds resident reads its own unit there — per attempt (a retry may get another unit, so read it every time), *"frozen one
+level down - a copy, on inline pools too"*, and `{}` when nothing was granted — a `ConcurrentLimitGroup` grants nothing. **A task's request is `units` on the task, and `units` set by your
+`createTask` reaches the scheduler as `limitKey` does**: `(c) => new FyflowTask({ ...c, units: { gpu: { from: ['gpu1']
+} } })`. A named instance's request reaches the scheduler the same way (section 13's `residentGroups` above); what `from`
+and `prefer` each mean is the scheduler's own.
+
+```ts run
+import { createRuntime, type StartOptions } from 'fyflow-orchestration/scheduler';
+import type { FlowDefinition, RegistryDocument } from 'fyflow-orchestration';
+import { FyflowTask } from 'fyflow-scheduler';
+
+// A type's worker reading both: the card its worker holds (read in the constructor) and what its task was granted.
+const worker = `data:text/javascript,${encodeURIComponent(`export default class {
+  constructor(config, workerContext) { this.card = workerContext.grants.gpu?.[0] ?? null; }
+  async setup() {}
+  run(p, context) { return { card: this.card, task: context.grants }; } }`)}`;
+const registry: RegistryDocument = {
+  workers: { model: { url: worker } },
+  groups: { gpu: { type: 'UnitGroup', config: { units: ['gpu0', 'gpu1'] } } },
+  nodeTypes: {
+    Model: { worker: 'model', inline: true, pool: { residentGroups: { gpu: 1 } } },   // a card per WORKER
+    Batch: { worker: 'model', inline: true, groups: ['gpu'] },                        // a card per TASK
+  },
+  pools: { 'model-1': { type: 'Model', pool: { residentGroups: { gpu: { cost: 1, from: ['gpu1'] } } } } },
+};
+const seen = async (type: string, pool?: string, options: StartOptions = {}): Promise<string> => {
+  const flow: FlowDefinition = { flowId: type, version: 1, entry: 't', nodes: [
+    { id: 't', kind: 'task', type, ...(pool === undefined ? {} : { pool }), edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' }] };
+  const runtime = createRuntime(registry, {}, { base: import.meta.url });   // its own gpu, both cards free
+  try {
+    const run = runtime.start(flow, {}, options);
+    if ((await run.done).outcome !== 'completed') return `${type} did not complete`;   // a sentinel no check below accepts
+    const results = run.driver.foldInputs().flatMap((i) => (i.kind === 'outcome' && i.record.kind === 'outcome' ? [i.record.result] : []));
+    return JSON.stringify(results);
+  } finally {
+    await runtime.shutdown();
+  }
+};
+// Resident: the worker holds a card from its constructor on, and its task sees it; the named instance's request reaches it.
+if (await seen('Model') !== '[{"card":"gpu0","task":{"gpu":["gpu0"]}}]') throw new Error('the lowest free card');
+if (await seen('Model', 'model-1') !== '[{"card":"gpu1","task":{"gpu":["gpu1"]}}]') throw new Error('the named instance`s request');
+// Per task: the worker holds nothing, and `units` set by createTask picks the card.
+const pinned: StartOptions = { createTask: (c) => new FyflowTask({ ...c, units: { gpu: { from: ['gpu1'] } } }) };
+if (await seen('Batch', undefined, pinned) !== '[{"card":null,"task":{"gpu":["gpu1"]}}]') throw new Error('units through createTask');
+if (await seen('Batch') !== '[{"card":null,"task":{"gpu":["gpu0"]}}]') throw new Error('no request, the lowest free card');
+```
+
 **A transform — what a node may DO to its input before its worker sees it** — `spec/flow-definition.md`
 v0.18, [ADR 0051](doc/decisions/0051-a-transform-is-a-declared-expression-in-a-registered-language-applied-in-the-types-worker-wrapper.md),
 [W61](doc/work-items/w61-what-a-transform-is.md). When the value a typed node receives is not the
@@ -5387,7 +5603,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 +5856,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 +5868,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.14.0`.
 
 ## Install