fyflow-orchestration 0.11.0 → 0.13.0

package/AGENTS.md

@@ -218,11 +218,12 @@ if (v48.join() !== 'FD-V48') throw new Error(`expected FD-V48, got ${v48.join()}
 >
 > **What each instance receives, and what the join hands on.** Each instance is dispatched with
 > **its own item** — `over`'s array at that instance's index, as its own copy, so no two instances
-> share an object — and the join carries **every item's result keyed by that item's branch path**. A
-> map of three items at the top level dispatches three tasks and its successor receives
-> `{ "0": …, "1": …, "2": … }`; **a map nested in a fan-out branch keys its collection with the whole
-> path**, so a map inside branch 1 gives `{ "1.0": …, "1.1": … }`. *(This said "keyed by its item
-> index", which is the depth-1 case stated as if it were general — W34's conformity reader.)*
+> share an object — and the join carries **every item's result keyed by that item's INDEX**, one
+> segment, wherever the map sits: a map of three items dispatches three tasks and its successor
+> receives `{ "0": …, "1": …, "2": … }`, and so does a map nested in a fan-out branch. **Since 0.12.0**
+> ([ADR 0138](doc/decisions/0138-a-join-hands-on-each-branch-under-its-own-key-and-a-checkpoint-of-the-old-keying-is-refused-by-format.md)): until then a nested map keyed its collection with the whole path — a map
+> inside branch 1 gave `{ "1.0": …, "1.1": … }` — and *What a join carries downstream* in section 5 says
+> what moved with it.
 > [ADR 0037](doc/decisions/0037-what-a-branch-receives-is-a-property-of-the-fan-out-and-what-a-join-carries-is-a-property-of-the-region.md),
 > and see *What a join carries downstream* in section 5 for what happens when an item's branch does
 > not arrive.
@@ -292,7 +293,7 @@ if (!noGroups.some((f) => f.rule === 'FD-V31' && f.at === 'score')) {
 | `join` | `of: '<fanout id>'`. Fires when its policy says so | it does not have **exactly one** edge, or that edge carries `when` or `on` (`FD-V7`) |
 | `end` | terminal. `outcome` is **your label**, never interpreted | — |
 | `ask` | waits for a PERSON — `edges`, and optionally `settings` (opaque), `answerSchema` (what a `done` answer must satisfy) and `needs` (what reaches it). Never dispatched, and has a task id; its answer is its output. A run PARKS at one and takes the person's answer at `resolve()` (section 7) | it has no `edges`, or **no edge of it is eligible for `done`** (`FD-V7`, as a task); `settings` that is not a plain object (`FD-V21`); a key only a task declares — `type`, `pool`, `optional`, `retryPolicy`, `workerGroups`, `transform` — one finding per key (`FD-V47`); an `answerSchema` outside the schema subset (`FD-V48`) |
-| `gate` | `type: '<gate type>'`, optional `settings`, and `edges` of `{ to, route? }` — routes the branch that reaches it and hands on what reached it. `settings.key` is a dotted key path over that value (`series.id`; no index). Built in: `distinct`, `if` and `switch`. Run by the driver where a branch enters it (section 19) | its `type` is not a registered gate type, or its type's `routesFor` throws or returns a malformed route set for this gate, or its `settingsProblem` throws or returns neither a message nor `null` (`FD-V39`); its `settings` are not a plain object its type's schema accepts, its type's `settingsProblem` returns a message, they cannot be copied for the type, or its `key` is not a key path (`FD-V40`); a route is unwired, wired twice, or not its type's, or a gate edge carries `when`, `on` or `needs` (`FD-V41`) — and `route` on any other node's edge is `FD-V41` too |
+| `gate` | `type: '<gate type>'`, optional `settings`, and `edges` of `{ to, route? }` — routes the branch that reaches it and hands on what reached it. `settings.key` is a dotted key path over that value — `series.id`, and since 0.12.0 an array element by a bracket index, `files[0].series` (a plain `xs.1` is still a KEY, never an index). Built in: `distinct`, `if` and `switch`. Run by the driver where a branch enters it (section 19) | its `type` is not a registered gate type, or its type's `routesFor` throws or returns a malformed route set for this gate, or its `settingsProblem` throws or returns neither a message nor `null` (`FD-V39`); its `settings` are not a plain object its type's schema accepts, its type's `settingsProblem` returns a message, they cannot be copied for the type, or its `key` is not a key path (`FD-V40`); a route is unwired, wired twice, or not its type's, or a gate edge carries `when`, `on` or `needs` (`FD-V41`) — and `route` on any other node's edge is `FD-V41` too |
 
 **A `task` node — and an `ask` — must have an edge that can be taken when it succeeds.** A node whose only edge is
 `{ when: { predicate: 'p' }, to: 'x' }` is refused at construction — it is the mistake the format most invites, and
@@ -522,7 +523,7 @@ that passed it through.
 | where it is legal | every node and every edge — at the entry, on a task, it equals `"."`, and both spellings are accepted. **On an edge it is NOT refused** the way `"."` is: a predicate has no `ctx.payload`, so `needs: { run: '$payload' }` is how a decision routes on `needs.run.amount` with no task before it |
 | always there | no `?` and no array form: `["$payload"]` and `"$payload?"` are `FD-V26`, each naming the bare form. The whole `$` prefix is reserved — `$` is outside the node-id charset (`FD-V16`), so the token can never collide with a node — and any other `$` spelling (`"$input"`, a typo) is `FD-V26` naming the two `$` references |
 | `"$item"` | the prefix's second reference, the item of the map instance the reader is in — the next subsection |
-| on a resume | the same value, from the stored header: nothing new is written to the log, the header or the checkpoint (`CHECKPOINT_FORMAT` stays 1) |
+| on a resume | the same value, from the stored header: nothing new is written to the log, the header or the checkpoint (`CHECKPOINT_FORMAT` does not move for it — it is 2 since 0.12.0, for the join's keys, section 5) |
 | at `start()` | `FD-R4` holds a task's composed `"$payload"` key to its worker's `inputSchema` like any other key (section 9) — composed from the value you passed, before the run exists |
 | in the wiring check | an arc composed through a `"$payload"` key is `unchecked`: the run's payload is a value no schema declares (section 15) |
 | what it costs | ONE copy of the whole payload per RUN, from 0.10.0 — however many instances of a `map` read it. *(Until 0.10.0 one copy per key per read: inside a `map`, once per instance — the cliff above at its largest.)* On an ASK the copy is also written into the run's LOG: the `asked` element keeps what reached the ask (section 7) |
@@ -617,7 +618,7 @@ passed it through.
 | always there | no `?` and no array form: `["$item"]` and `"$item?"` are `FD-V26`, each naming the bare form |
 | what it is | its OWN deep copy of the item, per key per read — two `"$item"` keys on one node are two objects, and a worker or a predicate writing into one reaches nothing else |
 | what an instance KEEPS | its item, by reference to the element the map received — and only where some node of that map's region reads `"$item"`: a map nobody reads it from keeps nothing. **Released when nothing of that instance may still be entered** — its branch has ended (arrived at the map's join, exited the region, or been lost) AND no branch of a region nested inside it is still live — told by those branches' terminal region events, never by a join: an ask parked in the instance keeps it until the person answers, and a nested fan-out whose join a policy fired early keeps it until its last branch ends. Released whole when the run halts, is cancelled or is stopped (`spec/run-state.md` `RN-R13`) |
-| on a resume | rebuilt by the replay, which re-enters the map: nothing new is written to the log, the header or the checkpoint (`CHECKPOINT_FORMAT` stays 1) |
+| on a resume | rebuilt by the replay, which re-enters the map: nothing new is written to the log, the header or the checkpoint (`CHECKPOINT_FORMAT` does not move for it — it is 2 since 0.12.0, for the join's keys, section 5) |
 | at `start()` | `FD-R4` composes it on an ENTRY map's branch task from the element the walk reached — which IS that instance's item — and holds it to the worker's `inputSchema` like any key (section 9). *Until 0.8.0's W191 ANY `needs` on such a task — `"."` included — made `start()` throw an `UnresolvedBranchPath` instead of `BoundaryRefused`* |
 | in the wiring check | an arc composed through a `"$item"` key reads the enclosing map's ITEM schema, one sample per element; `unchecked` for an ENTRY map, whose items come from the run's payload, which no schema declares (section 15) |
 | what it costs | one copy of ONE element per key per read — the cheap end of section 3's cliff — and the retention above, at most the `over` array the log already holds |
@@ -811,8 +812,14 @@ included), a `retryPolicy`, a `transform` and an `answerSchema` — each key wit
 validator, or to an agent writing a flow, BEFORE the findings. It is BUILT from the validator's own key sets, so its
 keys cannot drift from them (the reference tokens and the operator partition are written beside them and held to the
 validator by its tests); it is a new plain object on every call, yours to change. A join's `of` and a fanout's branch
-entries are held to the id charset only where they are strings — the validator does no more today
-([Q774](doc/questions/q774.md)).
+entries are held to the id charset, a non-string refused — as `validateDefinition` refuses one under `FD-V21` **since
+0.12.0** (`spec/flow-definition.md` v0.52, [Q774](doc/questions/q774.md)). **That is a change in what is accepted**:
+`of: null`, or `branches: ["b", "c", 5]`, passed 0.11.0's validator with no finding when nothing else in the flow
+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. *(It, the parse and
+the read a host may call are section 4's* Reading a key path the way the library does*.)*
 
 | | |
 |---|---|
@@ -888,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: [
@@ -934,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`. No array index, 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.
@@ -954,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
@@ -1091,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
@@ -1225,10 +1313,12 @@ is not a supported choice. See
 
 ### What a join carries downstream
 
-**The arrived branches' results, keyed by branch path.** A satisfied join dispatches its successor
-with an object whose keys are the `branchPath`s of the branches that **reached** it, and whose values
-are what each of those branches carried in — so a fan-out's results are not thrown away, and the
-value is the same whatever order the branches finished in.
+**The arrived branches' results, each under the branch's OWN key.** A satisfied join dispatches its
+successor with an object holding one entry per branch that **reached** it — keyed by the branch's
+**entry node id** for a `fanout` and by the **item index** for a `map`, one segment at every depth —
+whose values are what each of those branches carried in. So a fan-out's results are not thrown away,
+a key path reaches into any depth (`input.prep.1`), and the value is the same whatever order the
+branches finished in.
 
 ```ts run
 import { createRuntime } from 'fyflow-orchestration/scheduler';
@@ -1250,7 +1340,7 @@ const flow: FlowDefinition = {
   flowId: 'collect', version: 1, entry: 'split',
   nodes: [
     { id: 'split',   kind: 'fanout', branches: ['scoreA', 'scoreB'] },
-    // `scoreA` is branch path "0" and is made SLOW on purpose, so "1" settles first.
+    // `scoreA` is the FIRST entry and is made SLOW on purpose, so `scoreB` settles first.
     { id: 'scoreA',  kind: 'task', type: 'Scorer', settings: { score: 0.9, ms: 40 }, edges: [{ to: 'collect' }] },
     { id: 'scoreB',  kind: 'task', type: 'Scorer', settings: { score: 0.4 },         edges: [{ to: 'collect' }] },
     { id: 'collect', kind: 'join', of: 'split', edges: [{ to: 'publish' }] },
@@ -1269,7 +1359,7 @@ const inputs: FoldInput[] = [];
 const state = await runtime.start(flow, {}, { onFoldInput: (input) => { inputs.push(input); } }).done;
 await runtime.shutdown();
 
-// **The order is READ, not assumed.** The delay above ASKS for branch "1" to settle first; this is
+// **The order is READ, not assumed.** The delay above ASKS for `scoreB` to settle first; this is
 // what the run actually did, and the claim below is about the collection being independent of it.
 const settledOrder = inputs.flatMap((i) =>
   (i.kind === 'outcome' && /:score[AB]:/.test(i.record.taskId) ? [i.record.taskId.split(':')[1]] : []));
@@ -1278,13 +1368,14 @@ console.log(settledOrder.join(' then '));    // 'scoreB then scoreA'
 // `publish` is the join's successor, so what it received IS the collection — and `tag` returns what
 // it was handed with its own label added, so the collection is readable in the result.
 const published = Object.values(state.nodes).find((n) => n.nodeId === 'publish')?.result;
-console.log(JSON.stringify(published));      // {"0":{"score":0.9},"1":{"score":0.4},"publish":true}
+console.log(JSON.stringify(published));      // {"scoreA":{"score":0.9},"scoreB":{"score":0.4},"publish":true}
 
-const want = '{"0":{"score":0.9},"1":{"score":0.4},"publish":true}';
+const want = '{"scoreA":{"score":0.9},"scoreB":{"score":0.4},"publish":true}';
 if (JSON.stringify(published) !== want) throw new Error(`the join carried ${JSON.stringify(published)}`);
-// **B settled FIRST and is still under key "1".** The collection is keyed by BRANCH PATH, not by
-// arrival order, which is the whole point — and the two assertions are a pair: the first says which
-// order the run took, the second says the record did not follow it.
+// **B settled FIRST and is still under its own key, listed SECOND.** The collection is keyed by each
+// branch's ENTRY ID and inserted in `branches` order, not in arrival order, which is the whole point —
+// and the two assertions are a pair: the first says which order the run took, the second says the
+// record did not follow it.
 if (settledOrder.join() !== 'scoreB,scoreA') throw new Error(`settled ${settledOrder.join()} — the arrangement did not hold, so the claim below is untested`);
 ```
 
@@ -1297,20 +1388,32 @@ if (settledOrder.join() !== 'scoreB,scoreA') throw new Error(`settled ${settledO
 2. **`{}` is a real answer, not an error.** Under `liveToken` a join fires once its region has no live
    branches, and every branch reaching an `end` satisfies that with nothing arrived. If that should be
    a failure instead, pass `liveTokenRequiringArrival` — see above.
-3. **The keys are strings, in ascending branch-path order**, compared segment by segment as numbers —
-   so `"0"`, `"1"`, `"2"`, `"10"` at the top level, and `"1.0"`, `"1.1"`, `"1.10"` inside branch 1.
-   A nested region's inner join carries its own object, which becomes the value of the outer branch it
-   sits in. **Every key of one collection has the same number of segments**, because they are the
-   branch paths of one region. *(An earlier version of this bullet illustrated the order as `"1"`,
-   `"1.0"`, `"2"`, `"10"` — a mix of depths that no single collection can hold, and one that
-   `Object.keys` would not even return in that order, because JavaScript re-orders integer-like keys
-   ahead of string ones. W34's conformity reader.)*
+3. **Every key is ONE segment, at every depth — the branch's own key.** A `fanout`'s branch is keyed by
+   its entry node id (`FD-V9` keeps them distinct), a `map`'s instance by its item index — so a
+   fan-out whose first branch holds a map gives `{"prep":{"0":1,"1":2},"side":{"xs":[1,2]}}`, never
+   `"0.1"` under `"0"`. A nested region's inner join carries its own object, which becomes the value of
+   the outer branch it sits in. The full branch path is not lost: it is the region's own path (`regionPath`) + `.` + the
+   position — the position alone at the top level, where `regionPath` is `-` — on every `branch.*` event, task id and
+   `inputOf` path, which are unchanged.
+4. **The order is the object's own.** Entries are inserted in `branches` order for a fan-out and in
+   ascending item index for a map, and **JavaScript lists integer-like keys first, ascending** — so a
+   fan-out whose entries are `"b"` and `"2"` lists `"2"` first. Deterministic whatever order the
+   branches finished in; no node id is refused for it. Each entry is an own property, so even an entry
+   id `__proto__` is a key.
+5. **BREAKING in 0.12.0, and a run in flight across the upgrade cannot be resumed.** Until 0.11.0 the
+   keys were full branch paths (`{"0":{"0.0":1,"0.1":2},"1":{"xs":[1,2]}}` for the flow above) and a
+   fan-out's were POSITIONS; a flow reading `"0.1"` or `"0"` reads nothing now. A collection reaches a
+   checkpoint (an ask's kept input, a gate's decision, a worker's result), so **`CHECKPOINT_FORMAT` is
+   2** and a checkpoint 0.11.0 wrote — join or none — is refused `ResumeRefused('format')` by
+   `resume()`, `runtime.resume` and `inputOf`; a 0.11.0 driver refuses a 0.12.0 checkpoint the same
+   way. There is no migration: drain or abandon those runs first
+   ([ADR 0138](doc/decisions/0138-a-join-hands-on-each-branch-under-its-own-key-and-a-checkpoint-of-the-old-keying-is-refused-by-format.md)).
 
 *(This section read **"`null`, currently … this is [Q36](doc/questions/q36.md) and it is open"**
 until [ADR 0037](doc/decisions/0037-what-a-branch-receives-is-a-property-of-the-fan-out-and-what-a-join-carries-is-a-property-of-the-region.md).
 The argument for the `null` was real and is unchanged — which branch finishes last is genuinely
 non-deterministic — and what answered it is that carrying **all** the arrivals keyed by branch is not
-picking one. `spec/join-policy.md` section 4, `JP-R12`.)*
+picking one. `spec/join-policy.md` section 4, `JP-R12`; its keys are each branch's own since 0.12.0.)*
 
 ### The same on the RUNTIME — a decision, a fan-out and a join on real workers
 
@@ -1345,7 +1448,7 @@ const isLowConfidence: Predicate = (ctx) => {
 
 // THE FLOW — a DECISION, a FAN-OUT, a JOIN. `ingest` goes to `review` when the predicate holds,
 // otherwise to `split`. `split` runs two branches concurrently; `collect` waits for both and hands
-// `publish` every branch's result, keyed by branch path.
+// `publish` every branch's result, each under its own entry id.
 const flow: FlowDefinition = {
   flowId: 'decide', version: 1, entry: 'ingest',
   nodes: [
@@ -1373,13 +1476,13 @@ const ran = (s: RunState) => Object.values(s.nodes).map((n) => n.nodeId).sort();
 const resultOf = (s: RunState, id: string) => Object.values(s.nodes).find((n) => n.nodeId === id)?.result;
 console.log(ran(high));                    // [ 'classify', 'enrich', 'ingest', 'publish' ]
 console.log(ran(low));                     // [ 'ingest', 'review' ]
-console.log(resultOf(high, 'publish'));    // { '0': { confidence: 0.9, ingest: true, enrich: true }, '1': { …, classify: true }, publish: true }
+console.log(resultOf(high, 'publish'));    // { enrich: { confidence: 0.9, ingest: true, enrich: true }, classify: { …, classify: true }, publish: true }
 
 // Verified by the docs gate:
 if (high.outcome !== 'completed' || low.outcome !== 'completed') throw new Error(`outcomes ${high.outcome} / ${low.outcome}`);
 if (ran(high).join() !== 'classify,enrich,ingest,publish') throw new Error(`high ran ${ran(high).join()}`);
 if (ran(low).join() !== 'ingest,review') throw new Error(`low ran ${ran(low).join()}`);
-const want = '{"0":{"confidence":0.9,"ingest":true,"enrich":true},"1":{"confidence":0.9,"ingest":true,"classify":true},"publish":true}';
+const want = '{"enrich":{"confidence":0.9,"ingest":true,"enrich":true},"classify":{"confidence":0.9,"ingest":true,"classify":true},"publish":true}';
 if (JSON.stringify(resultOf(high, 'publish')) !== want) throw new Error(`publish received ${JSON.stringify(resultOf(high, 'publish'))}`);
 ```
 
@@ -1630,9 +1733,10 @@ keeps waiting, and the run is not stuck.
   the element's `observedAt` is the driver's `now` — the clock an outcome record's `observedAt` reads — and the node's
   entry carries it as **`askedAt`**, kept after the answer as `input` is. **A resume KEEPS the stored time**: the replay
   regenerates the element and takes its stored `observedAt`, so a wait measured across a resume does not restart; past
-  the stored tail it is the resumed driver's `now`. An `asked` element written before 0.11.0 has none, and its run
-  resumes with none. **A driver older than 0.11.0 refuses a newer checkpoint `diverged` at its first ask** — resume a
-  run on a driver at least as new as the one that wrote it.
+  the stored tail it is the resumed driver's `now`. *(An `asked` element written before 0.11.0 has none; since 0.12.0
+  such a checkpoint is refused `format` before its events are read — section 5, `CHECKPOINT_FORMAT` 2.)* **A driver
+  older than 0.11.0 refused a 0.11.0 checkpoint `diverged` at its first ask**; any driver before 0.12.0 refuses a 0.12.0
+  checkpoint `format` before replaying anything — resume a run on a driver of the format that wrote it.
 - **The answer is `driver.resolve(taskId, …)`** — the same call as below. `'done'` with `result` the answer, held to the
   ask's `answerSchema` (refused as `BoundaryRefused` with NOTHING appended and the ask still parked — answer again;
   `validateBoundaries: false` turns it off); `'failed'` with an `error` is the person DECLINING, held to nothing.
@@ -2882,7 +2986,9 @@ After a refusal the run is **halted**: nothing routes for it again, and its stat
 and FOUR surfaces are renamed — the `RunOutcome` `stopped` is `halted`, `RunState.stoppedBy` is `haltedBy`, the fold
 input `{ kind: 'stopped', reason }` is `{ kind: 'halted', reason }`, and `ResumeRefusalReason`'s `stopped` is
 `halted` — so a comparison against an old name, or a `{ kind: 'stopped' }` you construct, no longer compiles. A 0.7.0 checkpoint or log holding a `{ kind: 'stopped' }` element still reads as `halted`:
-`fold` folds it so, and a resume refuses it `halted` at its position.
+`fold` folds it so, and a resume refuses it `halted` at its position — but a 0.7.0 checkpoint is format 1, so since
+0.12.0 a resume refuses it `format` first (section 5); the `halted` read is reached only by such an element under a
+format-2 header, which no driver writes.
 
 ---
 
@@ -4075,7 +4181,7 @@ driver.start({ items: [1, 2, 3] });
 
 **What an expression sees, and what it may not.** `$` is the node's input — the previous node's
 result, the object `needs` described, a map instance's own item, or a join's collection keyed by
-branch path — and the node's effective `settings` are bound as `$settings`, so one expression is
+each branch's own key — and the node's effective `settings` are bound as `$settings`, so one expression is
 parameterised per node. **Five names are unbound, by name, on every compiled expression**: `$now`,
 `$millis`, `$random` — the three every adapter must refuse, because a transform is a function of what
 the run produced and run state is a fold of the log — **`$shuffle`**, JSONata's own fourth, which
@@ -4130,10 +4236,10 @@ if (!publish('$sum([*.score])', { ...registry, languages: {} }).some((f) => f.ru
 // The envelope worker — the class the bootstrap helper puts around your worker — with the adapter's worker half by URL.
 const w = new EnvelopeWorker({ worker: echo.url, languages: { jsonata: jsonata.worker } });
 await w.setup();
-const record = { '0': { score: 40 }, '1': { score: 20 } };                                    // JP-R12's collection, two branches
+const record = { scoreA: { score: 40 }, scoreB: { score: 20 } };                              // JP-R12's collection: `split`'s two entry ids
 const total = await w.run({ settings: { factor: 2 }, input: record, transform: { lang: 'jsonata', expr: '$sum([*.score]) * $settings.factor' } });
 if (total !== 120) throw new Error(`the worker received ${JSON.stringify(total)} — expected the reduction, 120`);
-const one = await w.run({ settings: {}, input: { '0': { score: 7 } }, transform: { lang: 'jsonata', expr: '$sum([*.score])' } });
+const one = await w.run({ settings: {}, input: { scoreA: { score: 7 } }, transform: { lang: 'jsonata', expr: '$sum([*.score])' } });
 if (one !== 7) throw new Error('arity one, the same expression: 7');
 const none = await w.run({ settings: {}, input: {}, transform: { lang: 'jsonata', expr: '$sum([*.score])' } });
 if (none !== 0) throw new Error('a join nothing reached: 0, because the reduction is over the ARRAY form');
@@ -4571,7 +4677,7 @@ Three things follow, and they are the whole of what you need:
 |---|---|
 | **`RunState.regions` is TWO-LEVEL** | `regions[openerId][openerPath]`. The opener's id is unchanged in meaning and in value; the second key is `-` for a region in no region, and inside a `map` region it is that map's item index |
 | **every `RegionEvent` carries `regionPath` beside `regionId`** | so an event says WHICH instance it is about. The same for `UnsatisfiableJoin` |
-| **a join's collection is per INSTANCE** | `JP-R12` keys it by branch path, and a branch inside an instance carries that instance's path as its own prefix — so two instances of one opener hold DISJOINT key sets and cannot collide |
+| **a join's collection is per INSTANCE** | each instance of one opener holds its OWN collection, so two instances cannot collide — even though, since 0.12.0, their keys are each branch's own key (`JP-R12`) and two instances may hold the SAME key set ([ADR 0138](doc/decisions/0138-a-join-hands-on-each-branch-under-its-own-key-and-a-checkpoint-of-the-old-keying-is-refused-by-format.md): until 0.11.0 the keys were branch paths, carrying the instance's path as a prefix) |
 
 **Both arities come from data, at both levels, and neither is in the document.** That is what
 separates a `map` from a `fanout`: `FD-V9` requires a fan-out's branch entries to be written down, so
@@ -4657,11 +4763,12 @@ if (!arrivals.includes('perLine@0 <- 0.0') || !arrivals.includes('perLine@1 <- 1
 }
 
 // WHAT THE OUTER JOIN CARRIES IS TWO LEVELS DEEP. `JP-R12`: one entry per branch that arrived, keyed
-// by branch path — and each of the outer entries IS that instance's own collection.
+// by its OWN key — an item index at both levels — and each of the outer entries IS that instance's own
+// collection. So `report.0.1` is order 0's second line: the key path a gate or an `if` reads.
 const report = Object.values(state.nodes).find((n) => n.nodeId === 'report')?.result as Record<string, Record<string, { sku: string }>>;
 console.log(Object.keys(report).filter((k) => k !== 'reported').sort());   // [ '0', '1' ]
-console.log(report['0']!['0.1']!.sku);                       // ab-1
-if (report['0']!['0.1']!.sku !== 'ab-1' || report['1']!['1.0']!.sku !== 'c-0') {
+console.log(report['0']!['1']!.sku);                         // ab-1
+if (report['0']!['1']!.sku !== 'ab-1' || report['1']!['0']!.sku !== 'c-0') {
   throw new Error(`the outer collection's values are the inner collections: ${JSON.stringify(report)}`);
 }
 ```
@@ -4794,7 +4901,7 @@ console.log(state.outcome);                                  // completed
 if (state.outcome !== 'completed') throw new Error(`expected completed, got ${state.outcome}`);
 // The same answer a run nobody killed gives (section 17's):
 const report = Object.values(state.nodes).find((n) => n.nodeId === 'report')?.result as Record<string, Record<string, { sku: string }>>;
-if (report['0']!['0.1']!.sku !== 'ab-1' || report['1']!['1.0']!.sku !== 'c-0') {
+if (report['0']!['1']!.sku !== 'ab-1' || report['1']!['0']!.sku !== 'c-0') {
   throw new Error(`the resumed run reaches the same report: ${JSON.stringify(report)}`);
 }
 
@@ -4931,11 +5038,13 @@ if (JSON.stringify(store.header) !== JSON.stringify(driver.checkpoint().header))
   ([Q374](doc/questions/q374.md)) — and so is a stored `attempted` event's number, which a re-run task is handed as
   the attempts it SPENT (one naming a task the replay never dispatched, carrying no positive integer, or not RISING over
   the last stored for its task, is refused `diverged` at its position). A store you do not trust is a store you should not resume from.
-- **`ResumeRefused` names its `reason`**: `format` (not a checkpoint this version writes), `run` (the
+- **`ResumeRefused` names its `reason`**: `format` (not a checkpoint this version writes — **every checkpoint 0.11.0
+  or earlier wrote is format 1 and refused here**: `CHECKPOINT_FORMAT` is 2 since 0.12.0, section 5), `run` (the
   header's run is not the driver's), `flow` (another flow id or `version` — there is no migration),
   `halted`, `cancelled` and `diverged` — the last three with the `index` of the position. **A HALTED
-  run is not resumable**: the refusal that halted it would halt it again — and a 0.7.0 checkpoint whose
-  halt is stored under the old kind, `stopped`, is refused `halted` at that element's position (ADR 0102). **Nor is a CANCELLED one**
+  run is not resumable**: the refusal that halted it would halt it again — and a halt stored under 0.7.0's kind,
+  `stopped`, is refused `halted` at that element's position (ADR 0102; a 0.7.0 checkpoint itself is format 1, refused
+  `format` first). **Nor is a CANCELLED one**
   (section 6): a cancel is its owner's act, and a resume would hand the scheduler again what the owner
   stopped — `index` is the first cancelled settlement or the cancel request, whichever is first. A completed or `stuck` run resumes to itself and
   dispatches nothing. **A STOPPED run is the one terminal run a resume TAKES** (below): its `interrupted` event is replayed, and `resumed` ends it.
@@ -5161,7 +5270,7 @@ rest, while every file gets a thumbnail* — had nowhere to keep that memory.
 
 | | |
 |---|---|
-| **it names a gate TYPE** | `distinct` is built in: routes `first` (its DEFAULT), `duplicate` and `nokey`, keyed by `settings.key` — a DOTTED path of object keys over the value that reached the gate, no index, no wildcard, no expression. A key a flow needs COMPUTED is computed by the task before the gate. `if` and `switch` are built in too, and remember nothing (the end of this section) |
+| **it names a gate TYPE** | `distinct` is built in: routes `first` (its DEFAULT), `duplicate` and `nokey`, keyed by `settings.key` — a DOTTED path of object keys over the value that reached the gate, each key optionally followed by bracket indexes into an ARRAY (`files[0].series`, `m[0][2]`; `[n]` with no leading zero, at most 999,999,999, never leading the path — [ADR 0137](doc/decisions/0137-a-key-path-indexes-an-array-by-a-bracket-suffix-and-a-plain-segment-keeps-its-meaning.md)); no quoted key, no wildcard, no expression. **`[1]` and `.1` are two paths**: `xs[1]` is element 1 of a real array and nothing over an object, `xs.1` an object's own key `"1"` and nothing over an array. A key a flow needs COMPUTED is computed by the task before the gate. `if` and `switch` are built in too, and remember nothing (the end of this section) |
 | **every route is wired, exactly once** | an edge with no `route` carries the type's DEFAULT route, never every route; a DROP is an edge to an `end`, and each is refused at load if it is missing (`FD-V41`) |
 | **it computes nothing** | the branch leaves on the chosen route with EXACTLY the value that reached the gate |
 | **its memory is ONE per gate per RUN** | shared by every branch that reaches it, whatever map item or region instance it comes from — and it starts empty with the run and ends with it |
@@ -5252,12 +5361,13 @@ for (const d of firsts) {
 }
 
 // A DROP IS AN `end`, so it is a path end like any other — and the thumbnail ran for EVERY file: each file's
-// `perFile` record holds its thumbnail, and nothing from the gate road, which ended at an `end` in every branch.
+// `perFile` record holds its thumbnail under `beside`'s entry id `thumbnail`, and nothing from the gate road,
+// which ended at an `end` in every branch.
 console.log(state.pathEnds.map((p) => p.at).sort());
 //   [ 'done', 'dropDuplicate', 'dropDuplicate', 'dropUnidentified', 'seriesReady', 'seriesReady' ]
 const published = Object.values(state.nodes).find((n) => n.nodeId === 'publish')!.result as
   { joinPayload: Record<string, Record<string, { thumbnail?: string }>> };
-const thumbs = Object.entries(published.joinPayload).map(([i, perFile]) => perFile[`${i}.0`]?.thumbnail);
+const thumbs = Object.values(published.joinPayload).map((perFile) => perFile['thumbnail']?.thumbnail);
 if (thumbs.length !== files.length || thumbs.some((t) => t === undefined)) throw new Error(`a thumbnail per file: ${thumbs.join()}`);
 
 // A GATE TYPE OF YOUR OWN is CODE, registered by name the way `distinct` is written. A route its `fn` returns that
@@ -5359,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
@@ -5466,7 +5576,7 @@ its three routes, so the third is the control sitting in the same report.
 | the author writes | the check says |
 |---|---|
 | a key path the producer FORBIDS at any step | **`no`** on every arc leaving by a key-resolved route, naming the gate, the key, the STEP it stopped on, the word the schema itself uses, and the route |
-| a key path the producer describes | those arcs carry `required` along the path, so a consumer requiring it **`fits`** |
+| a key path the producer describes | those arcs carry `required` along the path, so a consumer requiring it **`fits`** — and through a bracket index `[n]`, `minItems: n + 1` on that array and nothing about any element past it, since `items` speaks for every element ([ADR 0137](doc/decisions/0137-a-key-path-indexes-an-array-by-a-bracket-suffix-and-a-plain-segment-keeps-its-meaning.md)) |
 | the same arc, with the type declaring no guarantee | **`no`** again — *consumer requires "owner", producer does not guarantee it* |
 | an arc leaving by a route the type does NOT call key-resolved | its own verdict, unchanged — the refusal is the ROUTE's and not the gate's |
 
@@ -5612,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`
@@ -5623,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.11.0`.
+Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.13.0`.
 
 ## Install
 
@@ -93,7 +93,7 @@ if (JSON.stringify(shout?.result) !== '{"text":"hello world !"}') throw new Erro
 
 A **decision** is an edge with a `when` naming a predicate: code you supply, under a name the
 registry declares. A **fan-out** opens branches that run concurrently; a **join** waits for them and
-hands the next node every branch's result, keyed by branch path. Below, two runs at high and low
+hands the next node every branch's result, each under its own entry id. Below, two runs at high and low
 confidence take different roads. The worker is
 [examples/getting-started/tag.ts](examples/getting-started/tag.ts).
 
@@ -116,7 +116,7 @@ const isLowConfidence: Predicate = (ctx) => {
 
 // THE FLOW — a DECISION, a FAN-OUT, a JOIN. `ingest` goes to `review` when the predicate holds,
 // otherwise to `split`. `split` runs two branches concurrently; `collect` waits for both and hands
-// `publish` every branch's result, keyed by branch path.
+// `publish` every branch's result, each under its own entry id.
 const flow: FlowDefinition = {
   flowId: 'decide', version: 1, entry: 'ingest',
   nodes: [
@@ -144,13 +144,13 @@ const ran = (s: RunState) => Object.values(s.nodes).map((n) => n.nodeId).sort();
 const resultOf = (s: RunState, id: string) => Object.values(s.nodes).find((n) => n.nodeId === id)?.result;
 console.log(ran(high));                    // [ 'classify', 'enrich', 'ingest', 'publish' ]
 console.log(ran(low));                     // [ 'ingest', 'review' ]
-console.log(resultOf(high, 'publish'));    // { '0': { confidence: 0.9, ingest: true, enrich: true }, '1': { …, classify: true }, publish: true }
+console.log(resultOf(high, 'publish'));    // { enrich: { confidence: 0.9, ingest: true, enrich: true }, classify: { …, classify: true }, publish: true }
 
 // Verified by the docs gate:
 if (high.outcome !== 'completed' || low.outcome !== 'completed') throw new Error(`outcomes ${high.outcome} / ${low.outcome}`);
 if (ran(high).join() !== 'classify,enrich,ingest,publish') throw new Error(`high ran ${ran(high).join()}`);
 if (ran(low).join() !== 'ingest,review') throw new Error(`low ran ${ran(low).join()}`);
-const want = '{"0":{"confidence":0.9,"ingest":true,"enrich":true},"1":{"confidence":0.9,"ingest":true,"classify":true},"publish":true}';
+const want = '{"enrich":{"confidence":0.9,"ingest":true,"enrich":true},"classify":{"confidence":0.9,"ingest":true,"classify":true},"publish":true}';
 if (JSON.stringify(resultOf(high, 'publish')) !== want) throw new Error(`publish received ${JSON.stringify(resultOf(high, 'publish'))}`);
 ```