fyflow-orchestration 0.7.0 → 0.8.0

package/AGENTS.md

@@ -26,7 +26,7 @@ have: **sequence**, **decision routing**, **fan-out** and **join**.
 a worker declares what it expects and what it returns — it need not, and `unchecked` is the verdict
 when it does not — `checkWiring` gives every arc of a flow one of five verdicts from those
 declarations, `tryTransform` runs a candidate expression on a producer's own
-declared example and holds the result to the consumer's schema, and `signatureOf` turns the same
+declared example — or on a value you give it — and holds the result to the consumer's schema, and `signatureOf` turns the same
 schemas into the TypeScript a worker's author writes against. **Section 15 is a session that does all
 three on a real miswire and then runs the flow it repaired** — it is executed by `npm run gate` like
 everything else here.
@@ -42,7 +42,7 @@ everything else here.
 and later install it for you — and the JSR package maps it to `@fyflow/scheduler` at the same
 version. The driver is written against that version's event shapes, and the range is exact because
 there is no upstream changelog to read a wider one from. **You still pass your own scheduler in**:
-`SchedulerLike` is a two-method structural interface, a real `FyflowScheduler` satisfies it as it is,
+`SchedulerLike` is a structural interface — two methods and an optional `cancel` (section 12) — a real `FyflowScheduler` satisfies it as it is,
 and the one thing the library builds itself is a `FyflowTask` when you omit `createTask`. *(This
 paragraph read "does not depend on the scheduler … install whichever version you like" from W9 to
 W57, while section 12 said to pin it — two sentences a consumer reads first, contradicting each
@@ -79,8 +79,7 @@ import { createRuntime } from 'fyflow-orchestration/scheduler';
 import { type FlowDefinition, type RegistryDocument } from 'fyflow-orchestration';
 
 // THE REGISTRY — what exists. One worker module, and one node type that runs on it. This is data:
-// in your program it is a JSON file you import. The worker url is relative, and `base` below says
-// to what; the file itself is `examples/getting-started/worker.ts` — a class with a `run` method.
+// in your program it is a JSON file you import. The worker url is relative to `base` below.
 const registry: RegistryDocument = {
   workers: {
     greeter: {
@@ -92,9 +91,7 @@ const registry: RegistryDocument = {
 };
 
 // THE FLOW — what happens. Two nodes of that type, each with its own `settings`, then an end. A flow
-// names registry KEYS and nothing else — no file, no url, no class — so it is portable across
-// runtimes that agree on the keys. The end node's `outcome` is a LABEL of yours that the driver does
-// not interpret; the run's own outcome is the fold's — `state.outcome` below.
+// names registry keys only (no files, urls or classes), so it is portable between runtimes.
 const flow: FlowDefinition = {
   flowId: 'hello', version: 1, entry: 'greet',
   nodes: [
@@ -104,29 +101,22 @@ const flow: FlowDefinition = {
   ],
 };
 
-// ONE call builds the pool, the scheduler and everything between, and refuses every defect in the
-// REGISTRY at construction, by name. It never sees the flow: a defect THERE is refused where the
-// flow arrives, at `start`, which is what builds the `Driver` — so a `settings` value the worker's
-// schema rejects names its node from the call three lines below, not from this one. `base` is what
-// relative worker urls resolve against — `import.meta.url` when the registry sits beside this file.
+// ONE call builds the pools and the scheduler, and refuses a defective registry here, by name. A
+// defect in the FLOW is refused by `start`, below.
 const runtime = createRuntime(registry, {}, { base: import.meta.url });
 
-// `start` hands back `{ driver, done }` — the driver already running, and `done` a promise that
-// resolves with the run's terminal `RunState` (ADR 0058). **It never rejects**: `failed`, `stuck`
-// and `stopped` are terminal OUTCOMES, so a run that goes wrong arrives as `state.outcome` and not
-// as a `catch`. This snippet wants only the end, so it names only `done`. *A run with a person in
-// it does not end by itself — section 7 is where that is taught, and section 8 is what `done` waits
-// for.*
+// `start` runs the flow. `done` resolves with the run's final state and never rejects: a run that
+// goes wrong arrives as `state.outcome` ('failed', 'stuck', 'halted'), not as a `catch`.
 const { done } = runtime.start(flow, { text: 'hello' });
 const state = await done;
 await runtime.shutdown();
 
-// What the run did, read off its state: `greet` turned `hello` into `hello world`, and `shout` was
-// handed THAT as its input — the previous node's result is the next node's `input`.
+// The previous node's result is the next node's input: `greet` made `hello world`, `shout` added `!`.
 const shout = Object.values(state.nodes).find((n) => n.nodeId === 'shout');
 console.log(state.outcome);          // 'completed'
 console.log(shout?.result);          // { text: 'hello world !' }
 
+// Verified by the docs gate:
 if (state.outcome !== 'completed') throw new Error(`expected completed, got ${state.outcome}`);
 if (JSON.stringify(shout?.result) !== '{"text":"hello world !"}') throw new Error(`shout returned ${JSON.stringify(shout?.result)}`);
 ```
@@ -143,17 +133,74 @@ their schemas buy you before a run**.
 
 ## 3. The flow definition
 
-**Six** node kinds. A definition is JSON: no functions, so it can be stored, versioned and sent over
+**Seven** node kinds. A definition is JSON: no functions, so it can be stored, versioned and sent over
 a wire.
 
+> **`ask` is the seventh, and it is a node that WAITS FOR A PERSON, by design** — `spec/flow-definition.md` v0.42,
+> [ADR 0108](doc/decisions/0108-an-ask-is-a-seventh-node-kind-with-a-task-id-and-no-dispatch.md),
+> [W179](doc/work-items/w179-the-ask-node-in-the-definition.md). It runs NO worker and nothing is ever handed to the
+> scheduler for it, yet it has a TASK ID (`r1:approve:-:0`, one per map item) — the address the person's answer will
+> be given to — and the answer is its OUTPUT: a later node references it by `needs`, and its edges route as a task's
+> settlement does, `on: ['failed']` being the person DECLINING and a `when` reading `outcome.result`, the answer.
+> `settings` is opaque (the question, a form hint — the library never reads it), `answerSchema` is what a `done`
+> answer must satisfy, held to the schema subset at construction (`FD-V48`), and `needs` composes what reaches it.
+> It stands wherever a task may — the entry, a fan-out's branch entry, a map's branch. **What a task's WORKER reads it
+> may not carry**: `type`, `pool`, `optional`, `retryPolicy`, `workerGroups` and `transform` are each refused by
+> `FD-V47`, one finding per key. **A run PARKS at one** ([W180](doc/work-items/w180-asking-and-answering-in-a-run.md), [ADR 0109](doc/decisions/0109-an-ask-parks-with-nothing-dispatched-and-its-answer-is-its-result.md), section 7): nothing is handed to the
+> scheduler, the node reads `suspended` with what reached it KEPT as `input`, the run `awaiting_action`, and the
+> person's answer is `driver.resolve(taskId, 'done' | 'failed', …)` — a `done` answer held to `answerSchema`, a
+> `failed` one the person declining. *(Until W180 every `Driver` refused a run where a branch entered an ask, by name.)*
+> **BREAKING in 0.8.0** (P35 decision 8): `FlowNode` gains `AskNode`, so a `switch` exhaustive over `node.kind` no
+> longer compiles until it names `'ask'`.
+
+```ts run
+import { validateDefinition, type FlowDefinition } from 'fyflow-orchestration';
+
+const review: FlowDefinition = {
+  flowId: 'review', version: 1, entry: 'draft',
+  nodes: [
+    { id: 'draft', kind: 'task', type: 'Draft', edges: [{ to: 'approve' }] },
+    // An ASK: no worker, no dispatch — and a task id, which is where the answer goes.
+    { id: 'approve', kind: 'ask',
+      settings: { question: 'Publish this draft?' },          // opaque: the library never reads it
+      answerSchema: { type: 'object', required: ['approved'], properties: { approved: { type: 'boolean' } } },
+      needs: { draft: 'draft' },                              // what reaches it — what the person is shown
+      edges: [
+        { on: ['failed'], to: 'declined' },                   // the person DECLINED
+        { when: { path: 'outcome.result.approved', op: 'eq', value: true }, to: 'publish' },
+        { to: 'rework' },                                     // the default, as on a task
+      ] },
+    // The answer is the ask's OUTPUT: `needs` reaches it as it reaches a task's result.
+    { id: 'publish', kind: 'task', type: 'Publish', needs: { text: 'draft', answer: 'approve' }, edges: [{ to: 'done' }] },
+    { id: 'rework', kind: 'end', outcome: 'rework' },
+    { id: 'declined', kind: 'end', outcome: 'declined' },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+const registry = { predicates: [], workers: { w: { url: 'worker.js' } }, nodeTypes: { Draft: { worker: 'w' }, Publish: { worker: 'w' } } };
+const clean = validateDefinition(review, registry);
+if (clean.length) throw new Error(`the ask flow should be valid: ${clean.map((f) => f.rule).join()}`);
+
+// A task turned into an ask with its worker keys left on: FD-V47, ONE finding per key — never FD-V17.
+const leftOn = { ...review, nodes: review.nodes.map((n) => (n.id === 'approve' ? { ...n, type: 'Draft', optional: true } : n)) } as unknown as FlowDefinition;
+const v47 = validateDefinition(leftOn, registry).map((f) => `${f.rule}@${f.at}`);
+if (v47.join() !== 'FD-V47@approve,FD-V47@approve') throw new Error(`expected two FD-V47 at approve, got ${v47.join()}`);
+
+// An answerSchema outside the schema subset is FD-V48 — refused, never ignored.
+const pattern = { ...review, nodes: review.nodes.map((n) => (n.id === 'approve' ? { ...n, answerSchema: { type: 'string', pattern: '^y' } } : n)) } as unknown as FlowDefinition;
+const v48 = validateDefinition(pattern, registry).map((f) => f.rule);
+if (v48.join() !== 'FD-V48') throw new Error(`expected FD-V48, got ${v48.join()}`);
+```
+
 > **`gate` is the sixth, and since [W93](doc/work-items/w93-what-a-gate-does-in-a-run.md) a `Driver` RUNS
 > one** — `spec/flow-definition.md` v0.23-v0.24,
 > [ADR 0066](doc/decisions/0066-a-gate-is-a-decision-with-memory-that-names-a-registered-type-and-wires-every-route-exactly-once.md)
 > and [ADR 0067](doc/decisions/0067-a-gate-runs-in-the-driver-its-memory-is-the-drivers-and-its-decision-is-recorded.md),
-> [W92](doc/work-items/w92-what-a-gate-is.md). A gate is a decision WITH MEMORY: it routes the branch that
-> reaches it by what the run's other branches have already shown it — `distinct`, the one built-in type,
-> sends the FIRST branch per key down its default route `first` and every later one down `duplicate` — and it
-> hands on exactly what reached it. The driver evaluates it where a branch reaches it — the gate's memory is
+> [W92](doc/work-items/w92-what-a-gate-is.md). A gate routes the branch that reaches it by a registered TYPE
+> and hands on exactly what reached it. Three types are built in: `distinct` decides WITH MEMORY — by what the
+> run's other branches have already shown it, the FIRST branch per key down its default route `first` and every
+> later one down `duplicate` — and since v0.31 `if` and `switch` decide WITHOUT any, by a declared condition and a
+> declared table of values (section 19). The driver evaluates it where a branch reaches it — the gate's memory is
 > ONE per gate per RUN, the driver's, rebuilt by replay on a resume — records each decision as a `gated` fold
 > input (`RunState.gated`), and stops the run with an `UndeclaredRoute` if a type returns a route it does not
 > declare (`FD-R5`). *(Until W93 `new Driver` refused a flow holding one, at construction.)* Every route its
@@ -240,13 +287,14 @@ if (!noGroups.some((f) => f.rule === 'FD-V31' && f.at === 'score')) {
 | kind | | refused if |
 |---|---|---|
 | `task` | runs a worker — of its node **`type`**, REQUIRED since v0.19, on the type's default pool or a named **`pool`** instance of it, with per-node **`settings`** and optionally a **`transform`** applied to its input before the worker sees it (section 13). Has `edges`, and optionally **`needs`**, **`retryPolicy`** and **`workerGroups`** — what it says about its own task, below | it has no `edges`, or **no edge of it is eligible for `done`** (`FD-V7`); it has no `type` (`FD-V23`) — `workerType` is retired and is an undeclared key like any other (`FD-V17`); its `retryPolicy` is not exactly `{ maxRetries, backoffMs }` — an integer >= 0 and a finite number >= 0, no other key (`FD-V30`); its `workerGroups` is not a non-empty array of distinct ids the registry's `groups` declares (`FD-V31`); its `type` is not a registered node type whose worker the registry declares (`FD-V32`); its `settings` is not a plain object the type's worker `settingsSchema` accepts (`FD-V33`); its `transform` names a language the registry does not (`FD-V35`), an expression that language's compiler refuses (`FD-V36`), or is not `{ lang, expr }` (`FD-V37`); its `pool` is not a registered instance of its type (`FD-V38`) |
-| `fanout` | `branches: string[]` — the node each branch starts at. Dispatches nothing itself | fewer than two branches, a repeated entry, any `edges` at all, or a branch entry that is not a `task` (`FD-V9`) |
-| `map` | `over: '<key>'` and `branch: '<node id>'` — **one** branch, opened once per item at run time. Dispatches nothing itself; the RUN opens N instances of its one branch. Optionally **`needs`**, which is what `over` is then a key on | any `edges` at all, a `branch` that is not a `task`, or an `over` outside `^[A-Za-z0-9_-]{1,64}$` (`FD-V25`); a missing `over` or `branch` (`FD-V23`) |
+| `fanout` | `branches: string[]` — the node each branch starts at. Dispatches nothing itself | fewer than two branches, a repeated entry, any `edges` at all, or a branch entry that is not a `task` or an `ask` (`FD-V9`) |
+| `map` | `over: '<key>'` and `branch: '<node id>'` — **one** branch, opened once per item at run time. Dispatches nothing itself; the RUN opens N instances of its one branch. Optionally **`needs`**, which is what `over` is then a key on | any `edges` at all, a `branch` that is not a `task` or an `ask`, or an `over` outside `^[A-Za-z0-9_-]{1,64}$` (`FD-V25`); a missing `over` or `branch` (`FD-V23`) |
 | `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 | — |
-| `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). **Not run by any driver yet** | its `type` is not a registered gate type (`FD-V39`); its `settings` are not a plain object its type's schema accepts, 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 |
+| `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 |
 
-**A `task` node must have an edge that can be taken when it succeeds.** A node whose only edge is
+**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
 `FD-V7` is what catches it.
 
@@ -263,11 +311,12 @@ reaching the scheduler, which would drop it in silence.
 
 | key | | |
 |---|---|---|
-| `retryPolicy` | `{ maxRetries, backoffMs }` — **exactly** the scheduler's shape, an integer >= 0 and a finite number >= 0, no other key (`FD-V30`) | the scheduler retries a failed attempt **inside the same task id**, and the outcome record's `attempts` says how many retries were used. `{}` and a string count are refused because the scheduler would accept them and mean something else |
+| `retryPolicy` | `{ maxRetries, backoffMs }` — **exactly** the scheduler's shape, an integer >= 0 and a finite number >= 0, no other key (`FD-V30`) | the scheduler retries a failed attempt **inside the same task id**, and the outcome record's `attempts` says how many retries were used — since 0.8.0 across a crash or a stop too: a resume hands the attempts already made on, and the budget is not reset (section 18). `{}` and a string count are refused because the scheduler would accept them and mean something else |
 | `workerGroups` | a non-empty array of distinct group ids, every one in the registry's **`groups`** set (`FD-V31`) | the task acquires these **in addition to** its pool's `groups`. Pass `groups: Object.keys(scheduler.groups)` to the `Driver`, as you pass `nodeTypes` — **omitting it means the registry declares NO groups**, and any node naming one is refused, because a group id the scheduler does not know is silently ignored at run time |
 
 **A driver may carry a `defaultRetryPolicy`**, applied to every task node that declares none — held
-to `FD-V30` at construction like a node's own — and
+to `FD-V30` at construction like a node's own, and `createRuntime`'s option of the same name at ITS construction
+([ADR 0097](doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md) rule 5) — and
 **the node wins, whole** — a node with its own policy is dispatched with exactly that object, and the
 default is consulted only when the node declares none. There is no `defaultWorkerGroups`: a pool's own `groups` already applies to
 every task it runs, and the scheduler unions the two. A node that declares neither key is dispatched
@@ -275,7 +324,8 @@ with the exact object it was before, so nothing you have already written changes
 
 **Flow-level retry — re-dispatching a NODE under a new attempt, possibly routing elsewhere — is
 still not built** (section 11). This is the scheduler's retry of one task, and it is the whole of
-what `attempts` counts.
+what `attempts` counts — and, since 0.8.0, what the run RECORDS: each attempt's start is a fold input,
+`{ kind: 'attempted', taskId, attemptNumber }`, with the scheduler's 1-based number (section 18).
 
 ### `needs` — reaching an output the previous node did not produce
 
@@ -284,7 +334,7 @@ node that says nothing, and it is what the whole of this section above describes
 
 **`needs` is how a node asks for something else** —
 [ADR 0040](doc/decisions/0040-what-a-node-can-reach-is-the-runs-own-outputs-and-a-node-id-names-them-relative-to-a-branch-path.md),
-answering [Q11](doc/questions/q11.md). It is an optional object on a `task` or a `map`, mapping the
+answering [Q11](doc/questions/q11.md). It is an optional object on a `task`, a `map` or — since 0.8.0 — an `ask`, mapping the
 keys of the payload you want to **declared references**. *(Since v0.12 an **edge** may carry one too,
 and it says what that edge's PREDICATE sees rather than what a worker receives — section 4.)* A node that declares one receives **exactly**
 that object and nothing else — there is no wrapper and no reserved key.
@@ -292,6 +342,8 @@ that object and nothing else — there is no wrapper and no reserved key.
 | a reference is | and you get |
 |---|---|
 | `"."` | what the node would have received anyway — the previous node's result, and for a `map` instance **its own item** |
+| `"$payload"` | **what the RUN was handed** — the payload `start()` took, from any node and any edge, however many hops in (since 0.8.0, below). Always there: no `?`, no array form |
+| `"$item"` | **what opened your MAP INSTANCE** — its own item, from any node and any edge inside the instance, however many hops in (since 0.8.0, below). Always there inside one; outside every map instance it is `FD-V49` |
 | `"someNode"` | that node's result, **on your own branch** |
 | `["someNode"]` | that node's results as an **array**, in ascending branch-path order. Legal only when you are OUTSIDE a region that node is in — which is what makes it more than one |
 | **a `?` on either of those** — `"someNode?"`, `["someNode?"]` | the same thing, except that **nothing to give leaves the key out** (or gives `[]` for the array form) instead of stopping the run. This is how you say *if it ran* |
@@ -425,6 +477,191 @@ once per item* is a fact about your document rather than about your run. **Measu
 obstacle** — a size measurement is about 0.03% of what it would warn about at arity 1000.
 `spec/flow-definition.md` section 3 carries the whole verdict and the measurements.
 
+### `"$payload"` — what reached the RUN, from any node
+
+**`"$payload"` names the value the run was STARTED with** — `start(flow, payload)`'s `payload` — on any node that may
+declare `needs` (a `task`, a `map`, an `ask`) and on any edge, the entry included (`spec/flow-definition.md` v0.44,
+[ADR 0117](doc/decisions/0117-a-reference-may-name-what-reached-the-run.md), since 0.8.0). Until it, a node reached the
+run's payload only through `"."` on the node that received it — and an ASK breaks that: its result is the person's
+answer (section 7), so the node after an ENTRY ask had no road to what the run started with except a task before the ask
+that passed it through.
+
+| | |
+|---|---|
+| what it is | the copy the run's checkpoint HEADER keeps (`header.entryPayload`, section 18) — so a caller changing its payload object after `start()` changes nothing. Each key is its own deep copy, per read: no node receives an object another holds, and a worker writing into it reaches nothing |
+| 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) |
+| 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 key per read** — inside a `map`, once per instance (the cliff above, at its largest: name the small part's producer instead, or give the `map` a `needs` that projects what each instance needs). Nothing warns, as above. On an ASK the copy is also written into the run's LOG: the `asked` element keeps what reached the ask (section 7) |
+
+**`givenVerdict` and `tryTransform(…, { input })` compose nothing** (section 15): the value you give them IS what the node
+receives, so a node declaring `needs: { run: "$payload" }` is given `{ run: <the payload> }` — composing it is yours, as
+for every `needs` key, `"$item"` included.
+
+The app's case — an ENTRY ask whose successor needs the invoice the run started with beside the person's answer, and an
+edge that routes on the invoice's amount:
+
+```ts run
+import { Driver, fold, liveToken, validateDefinition, type FlowDefinition } from 'fyflow-orchestration';
+
+// A scheduler double, section 12's shape: it records what it is handed and fires only what we tell it to.
+const added: { id: string; payload: { input: unknown } }[] = [];
+const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+const scheduler = {
+  addTask(task: unknown) { added.push(task as { id: string; payload: { input: unknown } }); },
+  addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+};
+const inputOf = (id: string) => added.find((t) => t.id === id)?.payload.input;
+
+const flow: FlowDefinition = {
+  flowId: 'pay-invoice', version: 1, entry: 'approve',
+  nodes: [
+    // The ENTRY is an ask: what it shows the person is the run's payload, and its result is the ANSWER alone.
+    { id: 'approve', kind: 'ask', needs: { invoice: '$payload' },
+      answerSchema: { type: 'object', required: ['approved'], properties: { approved: { type: 'boolean' } } },
+      edges: [{ on: ['failed'], to: 'declined' }, { to: 'pay' }] },
+    // `pay` reaches BOTH: the invoice the run started with, and the person's answer.
+    { id: 'pay', kind: 'task', type: 'Pay', needs: { invoice: '$payload', answer: 'approve' },
+      edges: [
+        // An EDGE may name it too, so its predicate routes on the run's payload with no task in between.
+        { when: { path: 'needs.run.amount', op: 'gt', value: 100 }, to: 'audit', needs: { run: '$payload' } },
+        { to: 'done' },
+      ] },
+    { id: 'audit', kind: 'task', type: 'Pay', edges: [{ to: 'done' }] },
+    { id: 'declined', kind: 'end', outcome: 'declined' },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+const types = { workers: { w: { url: 'worker.js' } }, nodeTypes: { Pay: { worker: 'w' } } };
+const registry = { predicates: [], ...types };
+if (validateDefinition(flow, registry).length) throw new Error('"$payload" is legal on an entry ask, on a task and on an edge');
+
+const driver = new Driver(flow, { runId: 'r1', scheduler, createTask: (c) => c, predicates: new Map(), joinPolicy: liveToken, ...types });
+const invoice = { id: 'INV-1', amount: 120 };
+driver.start(invoice);
+invoice.amount = 1;   // yours to change: the run holds its own copy
+
+driver.resolve('r1:approve:-:0', 'done', { result: { approved: true }, actor: 'ana' });
+console.log(inputOf('r1:pay:-:0'));   // { invoice: { id: 'INV-1', amount: 120 }, answer: { approved: true } }
+if (JSON.stringify(inputOf('r1:pay:-:0')) !== '{"invoice":{"id":"INV-1","amount":120},"answer":{"approved":true}}') {
+  throw new Error(`pay received ${JSON.stringify(inputOf('r1:pay:-:0'))}`);
+}
+
+// `pay` settles; its edge reads `needs.run.amount` — 120, the run's — and routes to the audit.
+for (const fn of listeners.get('task.completed') ?? []) fn({ detail: { id: 'r1:pay:-:0', state: 'done', result: { paid: true } } });
+console.log(added.map((t) => t.id));   // [ 'r1:pay:-:0', 'r1:audit:-:0' ]
+if (added.map((t) => t.id).join() !== 'r1:pay:-:0,r1:audit:-:0') throw new Error('120 > 100 routes to the audit');
+if (fold(driver.foldInputs()).outcome !== 'running') throw new Error('the audit is in flight');
+
+// The refusals name their fix: one payload, always there, and the `$` prefix is reserved.
+const refuse = (ref: unknown) => validateDefinition({ ...flow, nodes: flow.nodes.map((n) =>
+  (n.id === 'pay' ? { ...n, needs: { invoice: ref } } : n)) } as FlowDefinition, registry).map((f) => `${f.rule}: ${f.detail}`);
+for (const [ref, fix] of [[['$payload'], 'write "$payload"'], ['$payload?', 'without "?"'], ['$input', '"$payload" (the run\'s payload)']] as const) {
+  const [finding] = refuse(ref);
+  if (!finding?.startsWith('FD-V26') || !finding.includes(fix)) throw new Error(`${JSON.stringify(ref)}: ${finding}`);
+}
+```
+
+**BREAKING in 0.8.0** (P38 (h)): `referenceTarget`'s return type gains two variants, `{ form: 'payload' }` and
+`{ form: 'item' }`, each with `node: null` — so code switching exhaustively on `form` stops compiling, and code reading
+`node === null` as *the `"."` form* reads `"$payload"` as `"."` in silence: switch on `form`. The `Reference` TYPE does
+not move (every token is a string), and a flow that names neither token is unchanged — every tree before 0.8.0's W190
+refuses both.
+
+### `"$item"` — what opened the MAP INSTANCE, from any node in it
+
+**`"$item"` names the item the reader's map instance was opened with** — the element of `over`'s array — on any node that
+may declare `needs` (a `task`, a `map`, an `ask`) and on any edge INSIDE a map instance, however many hops into it
+(`spec/flow-definition.md` v0.45, [ADR 0118](doc/decisions/0118-a-map-instance-keeps-its-item-while-a-node-of-it-may-still-be-entered.md),
+since 0.8.0). Until it, an instance's item reached only its branch ENTRY, as `"."` — and an ASK as a map's branch breaks
+that: its result is the person's answer, so the node after it had no road to the item except a task before the ask that
+passed it through.
+
+| | |
+|---|---|
+| which instance | the INNERMOST map region that CONTAINS the reader. A node in a `fanout` inside a map instance names the MAP's item; a `map` node's own `"$item"` is its ENCLOSING instance's (a map never names the region it opens); an OUTER map's item from inside an inner one is not named — a node of the outer instance that declares it passes it down |
+| where it is legal | every node and every edge inside a map instance — on the branch entry it equals `"."`, and both are accepted; on an edge it is NOT refused the way `"."` is. **Outside every map instance it is `FD-V49`** — before every map, after a map's join, or on a top-level `map` node — naming both fixes: *name the item where a map's branch receives it (`"."`), or move this node inside the map* |
+| 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) |
+| 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 |
+
+The app's case — a map whose branch is an ASK, and the node after it reaching its instance's invoice beside the person's
+answer, and an edge that routes on that invoice's amount:
+
+```ts run
+import { Driver, fold, liveToken, validateDefinition, type FlowDefinition } from 'fyflow-orchestration';
+
+// A scheduler double, section 12's shape: it records what it is handed and fires only what we tell it to.
+const added: { id: string; payload: { input: unknown } }[] = [];
+const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+const scheduler = {
+  addTask(task: unknown) { added.push(task as { id: string; payload: { input: unknown } }); },
+  addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+};
+const inputOf = (id: string) => added.find((t) => t.id === id)?.payload.input;
+
+const flow: FlowDefinition = {
+  flowId: 'review-each', version: 1, entry: 'each',
+  nodes: [
+    // One instance per invoice, and each instance's branch is an ASK: its result is the answer alone.
+    { id: 'each', kind: 'map', over: 'invoices', branch: 'review' },
+    { id: 'review', kind: 'ask',
+      answerSchema: { type: 'object', required: ['approved'], properties: { approved: { type: 'boolean' } } },
+      edges: [{ on: ['failed'], to: 'skipped' }, { to: 'pay' }] },
+    // `pay` reaches BOTH: its own instance's invoice, and the person's answer.
+    { id: 'pay', kind: 'task', type: 'Pay', needs: { invoice: '$item', answer: 'review' },
+      edges: [
+        // An EDGE may name it too, so a predicate routes on the instance's invoice.
+        { when: { path: 'needs.it.amount', op: 'gt', value: 100 }, to: 'audit', needs: { it: '$item' } },
+        { to: 'collect' },
+      ] },
+    { id: 'audit', kind: 'task', type: 'Pay', edges: [{ to: 'collect' }] },
+    { id: 'skipped', kind: 'end', outcome: 'skipped' },
+    { id: 'collect', kind: 'join', of: 'each', edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+const types = { workers: { w: { url: 'worker.js' } }, nodeTypes: { Pay: { worker: 'w' } } };
+const registry = { predicates: [], ...types };
+if (validateDefinition(flow, registry).length) throw new Error('"$item" is legal on a node and on an edge inside a map instance');
+
+const driver = new Driver(flow, { runId: 'r1', scheduler, createTask: (c) => c, predicates: new Map(), joinPolicy: liveToken, ...types });
+const payload = { invoices: [{ id: 'INV-1', amount: 120 }, { id: 'INV-2', amount: 40 }] };
+driver.start(payload);
+payload.invoices[0]!.amount = 1;   // yours to change: the instance keeps its own item
+
+// Two asks parked, one per invoice. Answered out of order, each `pay` gets ITS instance's invoice.
+driver.resolve('r1:review:1:0', 'done', { result: { approved: true }, actor: 'bo' });
+driver.resolve('r1:review:0:0', 'done', { result: { approved: true }, actor: 'ana' });
+console.log(inputOf('r1:pay:0:0'));   // { invoice: { id: 'INV-1', amount: 120 }, answer: { approved: true } }
+if (JSON.stringify(inputOf('r1:pay:0:0')) !== '{"invoice":{"id":"INV-1","amount":120},"answer":{"approved":true}}') {
+  throw new Error(`pay@0 received ${JSON.stringify(inputOf('r1:pay:0:0'))}`);
+}
+if (JSON.stringify(inputOf('r1:pay:1:0')) !== '{"invoice":{"id":"INV-2","amount":40},"answer":{"approved":true}}') {
+  throw new Error(`pay@1 received ${JSON.stringify(inputOf('r1:pay:1:0'))}`);
+}
+
+// Each `pay` settles; its edge reads `needs.it.amount` — 120 audits, 40 does not.
+for (const id of ['r1:pay:0:0', 'r1:pay:1:0']) {
+  for (const fn of listeners.get('task.completed') ?? []) fn({ detail: { id, state: 'done', result: { paid: true } } });
+}
+console.log(added.map((t) => t.id));   // [ 'r1:pay:1:0', 'r1:pay:0:0', 'r1:audit:0:0' ]
+if (added.map((t) => t.id).join() !== 'r1:pay:1:0,r1:pay:0:0,r1:audit:0:0') throw new Error('120 > 100 audits instance 0 alone');
+if (fold(driver.foldInputs()).outcome !== 'running') throw new Error('the audit is in flight');
+
+// Outside every map instance there is no item: a top-level MAP's own "$item" would be an ENCLOSING one — FD-V49.
+const outside = { ...flow, nodes: flow.nodes.map((n) => (n.id === 'each' ? { ...n, needs: { invoices: '$item' } } : n)) } as FlowDefinition;
+const [finding] = validateDefinition(outside, registry);
+if (finding?.rule !== 'FD-V49' || !finding.detail.includes('move this node inside the map')) throw new Error(`expected FD-V49, got ${finding?.rule}`);
+```
+
 ### Validation happens at construction, not at routing time
 
 `new Driver(...)` validates the whole definition before anything is queued. A typo cannot become a
@@ -447,7 +684,7 @@ if (!rules.includes('FD-V2') || !rules.includes('FD-V32')) {
 }
 ```
 
-There are **42 refusals** over the id range `FD-V1` … `FD-V46` *(41 over `FD-V1` … `FD-V45` until W109 shipped the first BUILT-IN node type and added `FD-V46`, which refuses a node of a type that only transforms and declares no `transform`; 37 over `FD-V1` … `FD-V41` until W108 made a predicate DATA and added the four a `when` needs; 34 over `FD-V1` … `FD-V38` until W92 added the gate's three; 35 over `FD-V1` … `FD-V37` until W65 retired `workerType` and with it `FD-V5` and `FD-V34`, adding `FD-V38`; 32 over `FD-V1` … `FD-V34` until W61 added the three transform rules; 29 over `FD-V1` … `FD-V31` until W59 added the three node-type rules — and this sentence stood at 29 twelve lines below the table W59 rewrote, until its conformity reader read the two together)*, each with a failing example in
+There are **45 refusals** over the id range `FD-V1` … `FD-V49` *(44 over `FD-V1` … `FD-V48` until W191 added `FD-V49` — `"$item"` where no map instance contains the reader; 42 over `FD-V1` … `FD-V46` until W179 added the ASK's two, `FD-V47` — a key only a task declares, on an ask — and `FD-V48` — an `answerSchema` outside the schema subset; 41 over `FD-V1` … `FD-V45` until W109 shipped the first BUILT-IN node type and added `FD-V46`, which refuses a node of a type that only transforms and declares no `transform`; 37 over `FD-V1` … `FD-V41` until W108 made a predicate DATA and added the four a `when` needs; 34 over `FD-V1` … `FD-V38` until W92 added the gate's three; 35 over `FD-V1` … `FD-V37` until W65 retired `workerType` and with it `FD-V5` and `FD-V34`, adding `FD-V38`; 32 over `FD-V1` … `FD-V34` until W61 added the three transform rules; 29 over `FD-V1` … `FD-V31` until W59 added the three node-type rules — and this sentence stood at 29 twelve lines below the table W59 rewrote, until its conformity reader read the two together)*, each with a failing example in
 `spec/examples/invalid/`. Four ids in that range are **deliberately absent** and have no rule behind
 them: `FD-V14`, which never existed; **`FD-V15`, retired when nested fan-out became
 expressible**; and **`FD-V5` and `FD-V34`, retired with `workerType`** at v0.19 (section 13). The ids are never renumbered, so it is safe to assert on them. The full
@@ -594,8 +831,10 @@ flagged low confidence* was not expressible until v0.12 —
 answering [Q8](doc/questions/q8.md).
 
 **An edge may carry `needs`, and its predicate sees the result under `ctx.needs`.** Same grammar as
-a node's (section 3) — a node id, or a one-element array holding one — **minus `"."`**, which an edge
-has no use for: *what a predicate would have received anyway* is `ctx.outcome`.
+a node's (section 3) — a node id, or a one-element array holding one, and since 0.8.0 `"$payload"` and `"$item"` —
+**minus `"."`**, which an edge has no use for: *what a predicate would have received anyway* is `ctx.outcome`. `"$payload"`
+and `"$item"` are not refused there: a predicate has no other road to the run's payload or to its map instance's item
+(section 3's two subsections route on them).
 
 ```ts run
 import { validateDefinition, type FlowDefinition, type Predicate } from 'fyflow-orchestration';
@@ -656,7 +895,10 @@ changes what its **worker** receives, so you could not give a predicate reach wi
 worker; and *what the node received* is not something the driver can reconstruct when the decision is
 made — the **entry** node's payload is never written to the log at all, and reconstructing any other
 node's would mean re-deriving the whole payload contract a second time. **A reference resolves from
-what the run produced**, which is available either way.
+what the run produced**, which is available either way — **and from what the run was HANDED**, since 0.8.0: the
+checkpoint header keeps the run's payload for the life of the run, and `"$payload"` names it — **and, inside a map
+instance, from what the instance KEEPS**: its item, while a node of it may still be entered, which `"$item"` names
+(section 3).
 
 **`ctx.needs` is `{}` when the edge declares nothing**, never `undefined`; it is **frozen**, so a
 predicate that writes to it throws rather than editing what the next predicate reads; and a reference
@@ -903,26 +1145,22 @@ It is also `README.md`'s second snippet, held byte-equal to this one by `check-d
 import { createRuntime } from 'fyflow-orchestration/scheduler';
 import { type FlowDefinition, type Predicate, type RegistryDocument, type RunState } from 'fyflow-orchestration';
 
-// THE REGISTRY — one worker, one type, and the NAME of a predicate the flow may use. A predicate is
-// code (ADR 0002), supplied beside the document under that name; a flow using a name nobody supplied
-// is refused at construction, not at the decision. The worker tags its input with the node's label.
+// THE REGISTRY — one worker, one type, and the NAME of a predicate the flow may use. The predicate
+// itself is code, passed to `createRuntime` under that name. The worker tags its input with a label.
 const registry: RegistryDocument = {
   workers: { tag: { url: '../../examples/getting-started/tag.ts' } },   // in your program: './tag.ts'
   nodeTypes: { Tag: { worker: 'tag', inline: true } },
   predicates: ['isLowConfidence'],
 };
-// A predicate reads the EFFECTIVE outcome, and `result` is `null` for an optional task that
-// failed (`OR-R9`) — so it is guarded, as section 4's is. Unreachable here, because `ingest` is
-// not optional; guarded anyway, because this is the form a consumer copies.
+// `result` is `null` when an optional task failed, so a predicate guards it.
 const isLowConfidence: Predicate = (ctx) => {
   const r = ctx.outcome.result as { confidence?: number } | null;
   return typeof r?.confidence === 'number' && r.confidence < 0.5;
 };
 
-// THE FLOW — a DECISION, a FAN-OUT, a JOIN. `ingest`'s first edge is taken when its predicate says so,
-// otherwise the last, unconditional one. `split` opens two branches that run concurrently; `collect`
-// waits for both and hands `publish` every branch's result keyed by branch path (JP-R12). `review` is
-// the road the run takes when confidence is low — it never reaches the join, and the run completes.
+// 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.
 const flow: FlowDefinition = {
   flowId: 'decide', version: 1, entry: 'ingest',
   nodes: [
@@ -938,30 +1176,24 @@ const flow: FlowDefinition = {
   ],
 };
 
-// ONE runtime, TWO runs. Pools belong to the runtime and are shared across runs; each run is its own
-// `Driver` with its own fold, and the join policy defaults to `live-token` (ADR 0003).
+// ONE runtime, TWO runs. Pools belong to the runtime and are shared; each run has its own state.
 const runtime = createRuntime(registry, { predicates: { isLowConfidence } }, { base: import.meta.url });
-// Each run has its OWN `done`, so two runs are two promises — `start` is called twice and the whole
-// of the wait is `await`. Nothing here folds anything: the runtime keeps the fold (ADR 0058).
 const run = (payload: unknown) => runtime.start(flow, payload).done;
 const high = await run({ confidence: 0.9 });
 const low = await run({ confidence: 0.2 });
 await runtime.shutdown();
 
-// WHICH nodes ran, read off each run's own state — the decision took a different edge each time.
+// Which nodes ran: the decision took a different edge each time.
 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 }
 
+// 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()}`);
-// `publish` received BOTH branches' results, keyed by branch path (JP-R12), and each branch's value
-// carries the whole road it came by. What this string pins is the branch-to-KEY MAPPING: the ASCENDING
-// order that rule also fixes is not observable at depth 1, because "0" and "1" are integer-like keys
-// and the language orders those ascending whatever the driver did. A nested region would show it.
 const want = '{"0":{"confidence":0.9,"ingest":true,"enrich":true},"1":{"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'))}`);
 ```
@@ -1006,6 +1238,193 @@ the table above and is wrong. `resolve(taskId, 'failed', …)` routes exactly as
 failure would, and `RS-R3` notes it is **the only road by which a non-`optional` node reaches an
 `on: ['failed']` edge**. That is the half of the human-in-the-loop story section 7 completes.
 
+### A task that ends `cancelled` ends its RUN
+
+The scheduler can end a task a third way: **`scheduler.cancel(id)`** stops it — waiting or running,
+`optional` or not, whatever its attempt produced — and it ends in state `cancelled` with one event,
+`task.cancelled`. The driver hears it, records it (`OR-R3`), and **halts the run**: nothing is dispatched
+or routed for it again, and the run folds to **`cancelled`** (`RN-R28`,
+[ADR 0094](doc/decisions/0094-a-cancelled-task-is-a-terminal-state-that-routes-no-edge-and-ends-its-run-cancelled.md)).
+
+| | what happens |
+|---|---|
+| the cancelled task | one record, `terminalState: 'cancelled'`, `result: null`. `task.cancelling` — the request, while a running task stops — writes nothing (`OR-R4`) |
+| an edge | **none can opt in**: `on: ['cancelled']` is refused at construction (`FD-V18`). A cancel is the owner's act, not an outcome a flow branches on |
+| the rest of the run | a task still in flight is **routed nowhere** when it settles — a bare `Driver` still records it; on a runtime, once `done` has settled the run is RELEASED and later settlements reach no driver (section 12, [ADR 0091](doc/decisions/0091-a-runtime-releases-a-run-when-its-done-settles-and-keeps-only-its-run-id.md)); a parked task stays parked and `resolve()` returns `false`; a join it left waiting never fires, and the run is NOT `stuck`. **Also on your own stack**: a cancel raised SYNCHRONOUSLY from your own `onFoldInput` — while a fan-out is dispatching its branches, a resolution is routing, or a resume is handing its tasks back — holds every further dispatch, as a halt does (`RN-R29`, [ADR 0103](doc/decisions/0103-every-halt-shares-one-dispatch-hold.md)); the one task whose own `dispatched` element you were handed is still handed to the scheduler |
+| what is reported | nothing: a cancel is not a refusal, so `onRunFailure` is not called and `hasFailed()` stays `false` — read `state.outcome` |
+| `done` | settles on the FIRST cancel, with `outcome: 'cancelled'` — the run's other tasks may still be running; cancel those by id, or cancel the RUN with `driver.cancel` instead (below), whose `done` waits for every task to stop |
+| a resume | refused, `reason: 'cancelled'` (section 18) |
+
+```ts run
+import { Driver, fold, liveToken, resumeRefusal, type FlowDefinition } from 'fyflow-orchestration';
+
+const flow: FlowDefinition = {
+  flowId: 'cancel-one', version: 1, entry: 'split',
+  nodes: [
+    { id: 'split',   kind: 'fanout', branches: ['a', 'b'] },
+    { id: 'a',       kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'b',       kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'collect', kind: 'join', of: 'split', edges: [{ to: 'publish' }] },
+    { id: 'publish', kind: 'task', type: 'T', edges: [{ to: 'done' }] },
+    { id: 'done',    kind: 'end', outcome: 'completed' },
+  ],
+};
+
+// The fake scheduler of section 12's no-scheduler snippet: listeners keyed by event type.
+const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+const added: string[] = [];
+const failures: string[] = [];
+const scheduler = {
+  addTask(task: unknown) { added.push((task as { id: string }).id); },
+  addEventListener(type: string, fn: (e: { detail: unknown }) => void) {
+    listeners.set(type, [...(listeners.get(type) ?? []), fn]);
+  },
+};
+const fire = (type: string, detail: unknown) => { for (const fn of listeners.get(type) ?? []) fn({ detail }); };
+
+const driver = new Driver(flow, {
+  runId: 'run-1', scheduler, createTask: (c) => c, predicates: new Map(),
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { T: { worker: 'w' } },
+  joinPolicy: liveToken, onRunFailure: (f) => { failures.push(f.kind); },
+});
+driver.start({});
+console.log(added);                        // [ 'run-1:a:0:0', 'run-1:b:1:0' ]
+
+// Somebody cancels branch `a` — the scheduler fires `task.cancelled`, and nothing else, for it.
+fire('task.cancelled', { id: 'run-1:a:0:0', state: 'cancelled' });
+// Branch `b` was already running; it finishes. It is recorded, and routed nowhere.
+fire('task.completed', { id: 'run-1:b:1:0', state: 'done', result: { b: 1 } });
+
+const state = fold(driver.foldInputs());
+console.log(state.outcome, added.length, failures);   // cancelled 2 []
+if (state.outcome !== 'cancelled') throw new Error(`expected cancelled, got ${state.outcome}`);
+if (added.includes('run-1:publish:-:0')) throw new Error('a cancelled run must not route on to the join`s successor');
+if (failures.length !== 0) throw new Error('a cancel is not a run failure');
+if (state.nodes['run-1:b:1:0']?.state !== 'done') throw new Error('the in-flight task is still recorded');
+
+// And the run cannot be resumed.
+console.log(resumeRefusal(flow, driver.checkpoint())?.reason);   // 'cancelled'
+if (resumeRefusal(flow, driver.checkpoint())?.reason !== 'cancelled') throw new Error('a cancelled run is not resumable');
+```
+
+**That is a cancel the run NOTICES** — one you made through the scheduler, by task id, and the run ends the
+moment the first is heard. To cancel the RUN, ask the driver.
+
+**`'cancelled'` is a NEW value of four published unions** — `TerminalState`, `NodeState`, `RunOutcome` and
+`ResumeRefusalReason`. **A `switch` that is exhaustive over any of them no longer compiles, which is the
+loud half; code that compares strings sees a value it never named and does not notice, which is the
+silent half.** A `Record<RunOutcome, …>` needs a seventh key — and since 0.8.0 an eighth, `cancelling`, below, and a ninth, `interrupted` (section 18).
+
+### Cancelling a RUN — `driver.cancel`
+
+**`driver.cancel({ actor, reason?, graceMs? })` cancels the whole run and resolves once every task it
+cancelled has stopped** (`RN-R31`,
+[ADR 0104](doc/decisions/0104-a-run-its-owner-cancels-is-cancelling-until-its-last-task-has-stopped.md)). In
+order: the run is HELD — nothing is dispatched or routed for it again (`RN-R29`); ONE fold input,
+`{ kind: 'cancelRequested', actor, reason }`, is appended; then the scheduler's `cancel(id, { reason, graceMs })`
+is called for each task IN FLIGHT. Each task still ends with the scheduler's own `task.cancelled` (or whatever it
+reached first), appended and routed nowhere. **The run reads `cancelling` until its LAST task has stopped, and
+`cancelled` after** (`RN-R30`) — so a runtime's `done` settles after the last `task.cancelled`, not at the first.
+
+| | what happens |
+|---|---|
+| a task RUNNING, WAITING behind a group, in a retry BACKOFF, or not yet picked up by a thread | each is cancelled; a waiting or backing-off one settles INSIDE the call, a running one when its worker stops |
+| a task PARKED at `user_action` | nothing is sent — it is not in flight, and the scheduler cannot end it. It stays `suspended`, the run does not wait on it, and `resolve()` is refused (P34 (i)) |
+| an ASK waiting for a person (section 7) | the same as a parked task: nothing is sent — it was never dispatched, so it is never in flight. It stays `suspended` and its answer is refused; a run waiting ONLY on asks and parked tasks reads `cancelled` at once, and a runtime's `done` settles at once ([W181](doc/work-items/w181-an-ask-under-run-control.md), `RN-R38`) |
+| a task HELD by a pause (section 8) | handed on to the scheduler, then cancelled at once — so it too ends with the scheduler's own `task.cancelled` |
+| a task a WORKER spawned (`context.spawnTask()`) | **not cancelled** — the driver knows only what it dispatched. Track those ids from `task.spawn_request` and cancel each yourself (the scheduler's own recipe) |
+| a SECOND call | appends nothing, and forwards its `graceMs` to each task still stopping — a shorter one shortens the wait, as pressing Cancel twice does on the scheduler |
+| `graceMs: 0` | **a request, not a guarantee**: the scheduler arms a 0 ms timer, and a worker that honours its signal promptly can still beat it ([S12](doc/scheduler-upstream.md)). A test needing a FORCED stop uses a worker that ignores its signal |
+| refused | **`RunControlRefused`, by `reason`, with nothing recorded or sent**: `unsupported` (the scheduler has no `cancel` — section 12), `not-started`, `halted`, `cancelled` (a task the scheduler cancelled on its own already ended the run), `ended` (nothing in flight, nothing parked, the driver at rest — a cancel from your own callback mid-step is accepted, and stops what the step would have dispatched) and `interrupted` (the run was STOPPED — cancel it where it resumes, section 18) — and a bad `graceMs` throws `TypeError` or `RangeError`, as the scheduler would |
+| a resume | refused, `reason: 'cancelled'`, at the `cancelRequested` element (section 18) |
+| your `onFoldInput` THROWS on the `cancelRequested` element | every task in flight is still sent its cancel and every task a pause held handed on and cancelled — in a `finally` (`RN-R31`) — and THEN the run is HALTED and reported once, and the throw reaches `cancel()`'s caller (section 9, [W184](doc/work-items/w184-a-consumer-callback-that-throws-on-every-road.md)). `halted` outranks `cancelling`, so a runtime's `done` settles `halted` at once; the tasks still stop, routed nowhere. *Until 0.8.0's W178 it sent none, and a paused run read `cancelling` for ever; until W184 the run read `cancelling`, unhalted* |
+
+```ts run
+import { Driver, RunControlRefused, fold, liveToken, resumeRefusal, type FlowDefinition } from 'fyflow-orchestration';
+
+const flow: FlowDefinition = {
+  flowId: 'cancel-run', version: 1, entry: 'split',
+  nodes: [
+    { id: 'split',   kind: 'fanout', branches: ['a', 'b'] },
+    { id: 'a',       kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'b',       kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'collect', kind: 'join', of: 'split', edges: [{ to: 'publish' }] },
+    { id: 'publish', kind: 'task', type: 'T', edges: [{ to: 'done' }] },
+    { id: 'done',    kind: 'end', outcome: 'completed' },
+  ],
+};
+
+// A fake scheduler WITH the scheduler's own `cancel(taskId, options)`: a running task stops when its worker does.
+const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+const added: string[] = [];
+const sent: { id: string; graceMs?: number }[] = [];
+const stopping = new Map<string, { promise: Promise<boolean>; resolve: (stopped: boolean) => void }>();
+const fire = (type: string, detail: unknown) => { for (const fn of listeners.get(type) ?? []) fn({ detail }); };
+const scheduler = {
+  addTask(task: unknown) { added.push((task as { id: string }).id); },
+  addEventListener(type: string, fn: (e: { detail: unknown }) => void) {
+    listeners.set(type, [...(listeners.get(type) ?? []), fn]);
+  },
+  cancel(id: string, options?: { reason?: unknown; graceMs?: number }) {
+    sent.push({ id, graceMs: options?.graceMs });
+    // A repeat call while the task is still stopping returns the SAME promise, as the scheduler's does.
+    let s = stopping.get(id);
+    if (!s) {
+      let resolve!: (stopped: boolean) => void;
+      s = { promise: new Promise<boolean>((r) => { resolve = r; }), resolve };
+      stopping.set(id, s);
+    }
+    return s.promise;
+  },
+};
+// The worker of `id` has stopped: the scheduler fires `task.cancelled`, and its `cancel()` resolves.
+const stops = (id: string) => { fire('task.cancelled', { id, state: 'cancelled' }); stopping.get(id)?.resolve(true); };
+
+const options = {
+  runId: 'run-1', createTask: (c: unknown) => c, predicates: new Map(),
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { T: { worker: 'w' } }, joinPolicy: liveToken,
+};
+const driver = new Driver(flow, { ...options, scheduler });
+driver.start({});
+
+const cancelled = driver.cancel({ actor: 'ana', reason: 'no longer needed', graceMs: 2000 });
+console.log(sent.map((s) => s.id), fold(driver.foldInputs()).outcome);   // [ 'run-1:a:0:0', 'run-1:b:1:0' ] cancelling
+if (fold(driver.foldInputs()).outcome !== 'cancelling') throw new Error('a run whose tasks are stopping is `cancelling`');
+
+stops('run-1:a:0:0');
+console.log(fold(driver.foldInputs()).outcome);   // cancelling — b has not stopped yet
+if (fold(driver.foldInputs()).outcome !== 'cancelling') throw new Error('`cancelled` waits for the LAST task');
+
+// Press Cancel again: nothing is recorded, and the task still stopping is sent the shorter graceMs.
+void driver.cancel({ actor: 'ana', graceMs: 0 });
+console.log(sent.at(-1));   // { id: 'run-1:b:1:0', graceMs: 0 }
+if (sent.length !== 3 || sent[2]!.id !== 'run-1:b:1:0' || sent[2]!.graceMs !== 0) throw new Error('the second call escalates what is still stopping');
+
+stops('run-1:b:1:0');
+await cancelled;
+const state = fold(driver.foldInputs());
+console.log(state.outcome, state.cancelRequest);   // cancelled { actor: 'ana', reason: 'no longer needed' }
+if (state.outcome !== 'cancelled' || state.cancelRequest?.actor !== 'ana') throw new Error('cancelled, by ana');
+if (driver.foldInputs().filter((e) => e.kind === 'cancelRequested').length !== 1) throw new Error('ONE element for two calls');
+if (added.includes('run-1:publish:-:0')) throw new Error('a cancelled run routes nowhere');
+if (resumeRefusal(flow, driver.checkpoint())?.reason !== 'cancelled') throw new Error('a cancelled run is not resumable');
+
+// A scheduler with no `cancel` drives a run, and refuses to cancel it — by name, before recording anything.
+const plain = new Driver(flow, { ...options, runId: 'run-2', scheduler: { addTask() {}, addEventListener() {} } });
+plain.start({});
+let refused: unknown = null;
+try { void plain.cancel({ actor: 'ana' }); } catch (e) { refused = e; }
+console.log(refused instanceof RunControlRefused && refused.reason);   // 'unsupported'
+if (!(refused instanceof RunControlRefused) || refused.reason !== 'unsupported') throw new Error('no cancel, no run cancel');
+if (plain.foldInputs().some((e) => e.kind === 'cancelRequested')) throw new Error('and nothing was recorded');
+```
+
+**BREAKING in 0.8.0, in four places** (P34 decision 10): `RunOutcome` gains `'cancelling'` — the first NON-terminal
+outcome since `awaiting_action`, so `isTerminal` is false for it and an exhaustive `switch` no longer compiles;
+`FoldInput` gains the kind `'cancelRequested'`; `RunState` gains the cell `cancelRequest` (`null` until the owner
+cancels), which a `RunState` literal must now carry; and `SchedulerLike` gains an OPTIONAL `cancel`, which breaks only
+a double that declares a `cancel` of another shape (section 12).
+
 ---
 
 ## 7. The human in the loop
@@ -1013,6 +1432,167 @@ failure would, and `RS-R3` notes it is **the only road by which a non-`optional`
 A non-optional task that runs out of retries ends in `user_action`. The branch **suspends**: the join
 keeps waiting, and the run is not stuck.
 
+**A node that waits for a person BY DESIGN is a different thing, and it is the `ask` kind** (section 3, since 0.8.0's
+`spec/flow-definition.md` v0.42): no task fails to get there, and a question is not an error. **A run PARKS at it**
+([W180](doc/work-items/w180-asking-and-answering-in-a-run.md), [ADR 0109](doc/decisions/0109-an-ask-parks-with-nothing-dispatched-and-its-answer-is-its-result.md), `spec/run-state.md` `RN-R36`/`RN-R37`):
+
+- **Nothing is handed to the scheduler** — the scheduler never sees the ask's id. The driver appends ONE fold input,
+  `{ kind: 'asked', taskId, input }`; the fold reads the node `suspended` and the run `awaiting_action`, exactly the
+  words a parked task gives (so `done` waits, below), and the node's entry in `nodes` carries **`input`** — what reached
+  the ask, its `needs` composed — kept after the answer. Tell an ask from a parked failure by the node's KIND, or by the
+  `asked` element, never by an error string. In a fan-out the ask's branch is LIVE, so **its join waits for the person**.
+- **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.
+- **The answer IS the node's result.** It routes as a task's settlement does — `on: ['failed']` for a decline, a `when`
+  over `outcome.result` — the successor RECEIVES it, and a later `needs` naming the ask reads it; the value that reached
+  the ask stays reachable by naming whatever produced it — and where NOTHING produced it, an ask at the ENTRY, by
+  `"$payload"`, the run's payload (since 0.8.0, section 3: `needs: { invoice: '$payload', answer: 'approve' }`); and where
+  the ask is a MAP's branch, by `"$item"`, the instance's own item (`needs: { invoice: '$item', answer: 'review' }`). A
+  `"$payload"` key in an ask's OWN `needs` puts a copy of the whole payload into the `asked` element, and so into the
+  run's log, once per ask — that element keeps what reached the ask, whatever its size. A predicate's `ctx.outcome` for an ask has `attempts: 0` and
+  **`schedulerTimestamp`, `startTime`, `endTime` and `executionTime` all `null`** — no scheduler was involved.
+- **BREAKING in 0.8.0** (P35 decision 8): `FoldInput` gains the kind `'asked'`, and `OutcomeRecord.schedulerTimestamp`
+  is `number | null` — `null` only on an ask's effective outcome. `NodeRun.input` is optional and additive.
+- **An answer given from a callback on the driver's own step** — `onFoldInput` on the `asked` element included — is
+  checked at once (a refusal is thrown or `false` returned right there) and, accepted, `resolve()` returns `true` and the
+  resolution is appended when the step ends: so the run's checkpoint resumes. A second answer while it is pending is
+  refused. **The same holds for ANY `resolve()` made from such a callback**, a parked task's included (since 0.8.0).
+- **On a resume** the replay re-enters the ask and REGENERATES its `asked` element — the same id, the same kept input,
+  compared with what you stored as structured-clone data (a different one — a `Map` entry, a `Date` — is refused
+  `diverged`) — and hands nothing to the new scheduler for it.
+- **Under run control an ask is a parked task** ([W181](doc/work-items/w181-an-ask-under-run-control.md), `RN-R38`, P35 (g)): it was never dispatched, so it
+  is never in flight. A **cancel** sends the scheduler nothing for it and the run reads `cancelled` once the tasks it did
+  cancel have stopped — at once if nothing runs; a **stop** sends nothing for it and refuses its answer on that runtime,
+  and the resume elsewhere re-parks it and takes the answer there; a **pause** holds nothing for it, and its answer is
+  accepted while paused, whatever it routes to recorded and HELD until you unpause (section 8). A run waiting only on
+  asks is not refused `ended` by any of them.
+
+```ts run
+import { BoundaryRefused, Driver, fold, liveToken, type FlowDefinition } from 'fyflow-orchestration';
+
+// A scheduler double, section 12's shape: it RECORDS what it is handed and fires only what we tell it to.
+const added: string[] = [];
+const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+const scheduler = {
+  addTask(task: unknown) { added.push((task as { id: string }).id); },
+  addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+};
+const done = (id: string, result: unknown) => {
+  const detail = { id, state: 'done', result, attempts: 0, timestamp: 1, startTime: 1, endTime: 2, executionTime: 1 };
+  for (const fn of listeners.get('task.completed') ?? []) fn({ detail });
+};
+
+const flow: FlowDefinition = {
+  flowId: 'publish-review', version: 1, entry: 'draft',
+  nodes: [
+    { id: 'draft', kind: 'task', type: 'Draft', edges: [{ to: 'approve' }] },
+    { id: 'approve', kind: 'ask', settings: { question: 'Publish this draft?' },
+      answerSchema: { type: 'object', required: ['approved'], properties: { approved: { type: 'boolean' } } },
+      edges: [
+        { on: ['failed'], to: 'declined' },
+        { when: { path: 'outcome.result.approved', op: 'eq', value: true }, to: 'publish' },
+        { to: 'declined' },
+      ] },
+    { id: 'publish', kind: 'task', type: 'Publish', edges: [{ to: 'end' }] },
+    { id: 'declined', kind: 'end', outcome: 'declined' },
+    { id: 'end', kind: 'end', outcome: 'completed' },
+  ],
+};
+const driver = new Driver(flow, {
+  runId: 'r1', scheduler, createTask: (c) => c, predicates: new Map(), joinPolicy: liveToken,
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { Draft: { worker: 'w' }, Publish: { worker: 'w' } },
+});
+driver.start({ topic: 'release notes' });
+done('r1:draft:-:0', { text: 'a draft' });
+
+// The run PARKED at the ask: nothing handed to the scheduler for it, the draft it was shown KEPT.
+const parked = fold(driver.foldInputs());
+console.log(added, parked.outcome, parked.nodes['r1:approve:-:0'].input);
+// [ 'r1:draft:-:0' ] awaiting_action { text: 'a draft' }
+if (added.join() !== 'r1:draft:-:0' || parked.outcome !== 'awaiting_action') throw new Error('the ask should park with nothing dispatched');
+if (JSON.stringify(parked.nodes['r1:approve:-:0'].input) !== '{"text":"a draft"}') throw new Error('the ask keeps what reached it');
+
+// An answer its schema refuses is thrown at you BY NAME — nothing appended, the ask still parked.
+let refused: unknown = null;
+try { driver.resolve('r1:approve:-:0', 'done', { result: { approved: 'yes' }, actor: 'ana' }); } catch (e) { refused = e; }
+if (!(refused instanceof BoundaryRefused)) throw new Error(`a nonconforming answer is BoundaryRefused, got ${String(refused)}`);
+if (fold(driver.foldInputs()).nodes['r1:approve:-:0'].state !== 'suspended') throw new Error('and the ask is still parked');
+
+// The corrected answer IS the node's result: the `when` reads it, and `publish` is dispatched.
+if (!driver.resolve('r1:approve:-:0', 'done', { result: { approved: true }, actor: 'ana' })) throw new Error('the answer was refused');
+const outcome = driver.effectiveOutcomeOf('r1:approve:-:0');
+console.log(added, outcome?.attempts, outcome?.schedulerTimestamp);   // [ 'r1:draft:-:0', 'r1:publish:-:0' ] 0 null
+if (added.join() !== 'r1:draft:-:0,r1:publish:-:0') throw new Error('approved routes to publish');
+if (outcome?.attempts !== 0 || outcome.schedulerTimestamp !== null) throw new Error('an ask`s outcome has no scheduler fields');
+```
+
+**Stopped, resumed elsewhere, and answered while paused** — the same flow, its run stopped while it waits on the person:
+
+```ts run
+import { Driver, fold, liveToken, type FlowDefinition } from 'fyflow-orchestration';
+
+// A scheduler double per "runtime": it records what it is handed and cancelled, and fires only what we tell it to.
+function schedulerDouble() {
+  const added: string[] = [];
+  const cancelled: string[] = [];
+  const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+  return {
+    added, cancelled,
+    addTask(task: unknown) { added.push((task as { id: string }).id); },
+    addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+    cancel(id: string) { cancelled.push(id); return Promise.resolve(true); },
+    done(id: string, result: unknown) {
+      const detail = { id, state: 'done', result, attempts: 0, timestamp: 1, startTime: 1, endTime: 2, executionTime: 1 };
+      for (const fn of listeners.get('task.completed') ?? []) fn({ detail });
+    },
+  };
+}
+const flow: FlowDefinition = {
+  flowId: 'publish-review', version: 1, entry: 'draft',
+  nodes: [
+    { id: 'draft', kind: 'task', type: 'Draft', edges: [{ to: 'approve' }] },
+    { id: 'approve', kind: 'ask', edges: [{ to: 'publish' }] },
+    { id: 'publish', kind: 'task', type: 'Publish', edges: [{ to: 'end' }] },
+    { id: 'end', kind: 'end', outcome: 'completed' },
+  ],
+};
+const driverOn = (scheduler: ReturnType<typeof schedulerDouble>) => new Driver(flow, {
+  runId: 'r1', scheduler, createTask: (c) => c, predicates: new Map(), joinPolicy: liveToken,
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { Draft: { worker: 'w' }, Publish: { worker: 'w' } },
+});
+
+// RUNTIME A: the draft settles, the run parks at the ask — and is STOPPED. Nothing is sent for the ask.
+const a = schedulerDouble();
+const first = driverOn(a);
+first.start({ topic: 'release notes' });
+a.done('r1:draft:-:0', { text: 'a draft' });
+await first.stop({ actor: 'ops', reason: 'upgrade' });
+console.log(a.cancelled, fold(first.foldInputs()).outcome);   // [] interrupted
+if (a.cancelled.length !== 0) throw new Error('a stop sends nothing for an ask: it is not in flight');
+if (first.resolve('r1:approve:-:0', 'done', { result: { ok: true }, actor: 'ana' })) throw new Error('the answer is refused on the stopped runtime');
+
+// RUNTIME B: the checkpoint resumed — the ask RE-PARKED with what it was shown, nothing handed on for it.
+const b = schedulerDouble();
+const second = driverOn(b);
+second.resume(first.checkpoint());
+console.log(b.added, fold(second.foldInputs()).nodes['r1:approve:-:0'].input);   // [] { text: 'a draft' }
+if (b.added.length !== 0 || fold(second.foldInputs()).outcome !== 'awaiting_action') throw new Error('re-parked, nothing handed on');
+
+// PAUSED, the answer is accepted — and what it routes to is recorded and HELD until the unpause.
+second.pause({ actor: 'ops' });
+if (!second.resolve('r1:approve:-:0', 'done', { result: { ok: true }, actor: 'ana' })) throw new Error('answered while paused');
+if (b.added.length !== 0) throw new Error('publish is held while paused');
+second.unpause({ actor: 'ops' });
+console.log(b.added);   // [ 'r1:publish:-:0' ]
+if (b.added.join() !== 'r1:publish:-:0') throw new Error('the unpause hands publish on');
+b.done('r1:publish:-:0', 'published');
+if (fold(second.foldInputs()).outcome !== 'completed') throw new Error('the run completes on runtime B');
+```
+
+**A flow that waits for a person because a task FAILED** is the parked task below — the road an ask replaces for a
+question asked by design, and still the road for a task out of retries.
+
 > **A `user_action` task fires TWO events, and the first one is called `task.failed`.** The scheduler
 > sets `state = 'user_action'` and then dispatches `task.failed` *and* `task.user_action` carrying
 > the same object. **Never key on the event name alone**: that first `task.failed` is for a task
@@ -1020,7 +1600,9 @@ keeps waiting, and the run is not stuck.
 > human-intervention case down an error edge. The driver drops it and records on the second — it
 > matters if you subscribe to the scheduler yourself.
 > [ADR 0007](doc/decisions/0007-the-driver-normalizes-events-into-an-immutable-outcome-record.md)
-> rule 2; the scheduler's own reference does not document it for the ordinary path.
+> rule 2. The scheduler's own reference records the pair in its per-task event order —
+> *"`task.failed` (plus `task.user_action`)"* — while its task-states paragraph still says *"`task.failed`
+> fires once per failed task"*; trust the pair (re-read at the pin by W157 and W158).
 
 ```ts run
 import { createRuntime } from 'fyflow-orchestration/scheduler';
@@ -1056,7 +1638,7 @@ const { driver, done } = runtime.start(flow, {}, { onFoldInput: (input) => { inp
 
 // **`done` IS STILL PENDING HERE, and that is the trap this section exists to teach.** Its
 // settlement rule is terminality and nothing else (ADR 0058 rule 3), and `isTerminal` is
-// `outcome !== 'running' && outcome !== 'awaiting_action'` — so a run parked on a person is not
+// `outcome !== 'running' && outcome !== 'awaiting_action' && outcome !== 'cancelling'` — so a run parked on a person is not
 // terminal and `done` waits for the resolution. **A promise cannot tell you a run has PARKED**,
 // because parking is not the end; the poll below is for the state `done` is waiting THROUGH, and it
 // is the one thing here a completion handle does not give you.
@@ -1133,9 +1715,10 @@ if (state.pathEnds.map((p) => p.at).join() !== 'quarantine') {
 ```
 
 `resolve()` returns `false` if the task is not suspended — a rejected command, not a run failure, so
-you may retry. It does **one** thing: supply an outcome for a dispatch that already happened. It
-cannot re-run the node and it cannot send it somewhere else. It also returns `false` once the run has
-been **stopped** by a refusal (section 9), and there retrying can never succeed: check
+you may retry. It does **one** thing: supply an outcome for a dispatch that already happened — or, for
+an ask, the answer to a node that dispatched nothing (above). It cannot re-run the node and it cannot send it
+somewhere else. It also returns `false` once the run has
+been **halted** by a refusal (section 9), and there retrying can never succeed: check
 `driver.hasFailed()` to tell the two `false`s apart.
 
 A resolved node is **indistinguishable** from one that settled that way: same node state, same
@@ -1154,7 +1737,7 @@ into state and touches nothing else.
 ```ts run
 import { fold, isTerminal, type FoldInput } from 'fyflow-orchestration';
 
-const settled = (taskId: string, state: 'done' | 'failed' | 'user_action'): FoldInput => ({
+const settled = (taskId: string, state: 'done' | 'failed' | 'user_action' | 'cancelled'): FoldInput => ({
   kind: 'outcome',
   record: { kind: 'outcome', taskId, terminalState: state, result: null, error: null,
     attempts: 0, schedulerTimestamp: 1, observedAt: 1, startTime: 1, endTime: 2, executionTime: 1 },
@@ -1179,10 +1762,30 @@ const rows: [string, FoldInput[]][] = [
   ['awaiting_action', [dispatched('r1:a:-:0'), settled('r1:a:-:0', 'done'), ended('end'),
                        ended('no-eligible-edge'), openJoin, dispatched('r1:b:-:0'),
                        dispatched('r1:c:-:0'), settled('r1:c:-:0', 'user_action')]],
-  ['stopped',         [dispatched('r1:a:-:0'), settled('r1:a:-:0', 'done'), ended('end'),
+  // The run's OWNER stops it to resume it elsewhere (section 18) while `b` is still in flight: `interrupted`.
+  ['interrupted',     [dispatched('r1:a:-:0'), settled('r1:a:-:0', 'done'), ended('end'),
+                       ended('no-eligible-edge'), openJoin, dispatched('r1:b:-:0'),
+                       dispatched('r1:c:-:0'), settled('r1:c:-:0', 'user_action'),
+                       { kind: 'interrupted', actor: 'ops', reason: null }]],
+  // The OWNER cancels it (section 6) while `b` is still running: `cancelling`. (The driver refuses a cancel after a
+  // stop, but a fold must answer every sequence.)
+  ['cancelling',      [dispatched('r1:a:-:0'), settled('r1:a:-:0', 'done'), ended('end'),
+                       ended('no-eligible-edge'), openJoin, dispatched('r1:b:-:0'),
+                       dispatched('r1:c:-:0'), settled('r1:c:-:0', 'user_action'),
+                       { kind: 'interrupted', actor: 'ops', reason: null },
+                       { kind: 'cancelRequested', actor: 'ops', reason: null }]],
+  // ... and `b`, the last task in flight, has stopped: `cancelled`.
+  ['cancelled',       [dispatched('r1:a:-:0'), settled('r1:a:-:0', 'done'), ended('end'),
+                       ended('no-eligible-edge'), openJoin, dispatched('r1:b:-:0'),
+                       dispatched('r1:c:-:0'), settled('r1:c:-:0', 'user_action'),
+                       { kind: 'interrupted', actor: 'ops', reason: null },
+                       { kind: 'cancelRequested', actor: 'ops', reason: null }, settled('r1:b:-:0', 'cancelled')]],
+  ['halted',          [dispatched('r1:a:-:0'), settled('r1:a:-:0', 'done'), ended('end'),
                        ended('no-eligible-edge'), openJoin, dispatched('r1:b:-:0'),
                        dispatched('r1:c:-:0'), settled('r1:c:-:0', 'user_action'),
-                       { kind: 'stopped', reason: 'DuplicateTaskId: x' }]],
+                       { kind: 'interrupted', actor: 'ops', reason: null },
+                       { kind: 'cancelRequested', actor: 'ops', reason: null }, settled('r1:b:-:0', 'cancelled'),
+                       { kind: 'halted', reason: 'DuplicateTaskId: x' }]],
 ];
 for (const [expected, inputs] of rows) {
   const got = fold(inputs).outcome;
@@ -1190,14 +1793,16 @@ for (const [expected, inputs] of rows) {
   if (got !== expected) throw new Error(`precedence: expected ${expected}, got ${got}`);
 }
 
-// `isTerminal` is false for exactly `running` and `awaiting_action`.
+// `isTerminal` is false for exactly `running`, `awaiting_action` and `cancelling`.
 const terminal = Object.fromEntries(rows.map(([o, i]) => [o, isTerminal(fold(i))]));
-console.log(terminal);   // completed/failed/stuck/stopped true, running/awaiting_action false
+console.log(terminal);   // completed/failed/stuck/interrupted/cancelled/halted true, running/awaiting_action/cancelling false
 if (!terminal.stuck) throw new Error('`stuck` is terminal — that is the point of it existing');
 if (terminal.running || terminal.awaiting_action) throw new Error('a live run is not terminal');
-if (!terminal.completed || !terminal.failed || !terminal.stopped) {
-  throw new Error('completed, failed and stopped are all terminal');
+if (terminal.cancelling) throw new Error('a run whose tasks are still stopping is not terminal');
+if (!terminal.completed || !terminal.failed || !terminal.cancelled || !terminal.halted) {
+  throw new Error('completed, failed, cancelled and halted are all terminal');
 }
+if (!terminal.interrupted) throw new Error('a stopped run is terminal HERE — a resume elsewhere continues it');
 
 // `completed` means every live path reached an `end` — NOT "no node settled failed".
 // A failed node that routed on through an `on: ["failed"]` edge completes the run.
@@ -1216,11 +1821,14 @@ const state = fold(driver.foldInputs());
 if (isTerminal(state)) console.log('finished as', state.outcome);
 ```
 
-### The six outcomes, highest first
+### The nine outcomes, highest first
 
 | | means |
 |---|---|
-| `stopped` | a refusal terminated the run — section 9 |
+| `halted` | a refusal terminated the run — section 9. *`stopped` until 0.8.0 (ADR 0102); a stored `stopped` element folds as this* |
+| **`cancelled`** | **a task of the run was cancelled by the scheduler on its own, and the driver halted it — or the run's owner cancelled it with `driver.cancel` and every task has stopped** — section 6. It outranks everything below it, a parked task and a waiting join included |
+| **`cancelling`** | **the run's owner cancelled it and a task is still stopping** — section 6, since 0.8.0. **NOT terminal**: `done` waits for the last task. It outranks everything below it |
+| **`interrupted`** | **the run's owner STOPPED it to resume it elsewhere** — section 18, since 0.8.0. Terminal on this runtime and the ONE terminal outcome a resume accepts; a `resumed` event ends it. It outranks everything below it, a parked task included |
 | `awaiting_action` | a node is suspended and nobody has resolved it |
 | `running` | a dispatched node has not settled |
 | **`stuck`** | nothing is live and **nothing ever will be**: a join has not fired and cannot |
@@ -1238,15 +1846,15 @@ rule 6). *(That phrase lived in §2's copied block until [W78](doc/work-items/w7
 reduced it to `await done`; ADR 0058's Context cites it, so it moved here rather than going out with
 the block — W78's conformity reader, finding 3.)*
 
-**`isTerminal(state)` is how you wait for a run without a clock.** It is false for `running` and
-`awaiting_action` and true for everything else — including `stuck`, which is the point: before
+**`isTerminal(state)` is how you wait for a run without a clock.** It is false for `running`,
+`awaiting_action` and `cancelling` and true for everything else — `interrupted` included, though a resume ELSEWHERE continues that run — and `stuck`, which is the point: before
 `stuck` existed, a permanently hung run folded to `completed` and a waiter reported success.
 
 **And `done` is that rule applied for you.** `runtime.start` returns `{ driver, done, header }` —
 `header` is the run's CHECKPOINT header since
 [ADR 0064](doc/decisions/0064-a-checkpoint-is-the-whole-event-sequence-and-a-header-and-it-is-a-copy.md),
 and `driver.checkpoint()` hands out the header with every event so far (`spec/run-state.md`
-section 8); `runtime.resume(flow, checkpoint)` resumes a run from one, returning the same handle
+section 8) — and, since 0.8.0, `start`'s `onHeader` option hands you the same header BEFORE the first event (section 18); `runtime.resume(flow, checkpoint)` resumes a run from one, returning the same handle
 ([ADR 0065](doc/decisions/0065-a-resume-replays-the-stored-stimuli-refuses-what-it-cannot-regenerate-and-re-dispatches-what-was-in-flight.md), `spec/run-state.md` section 9 — section 18 teaches it, as an executed snippet) — and `done`
 resolves with the first `RunState` this predicate calls terminal
 ([ADR 0058](doc/decisions/0058-runtime-start-returns-a-completion-handle-the-runtime-keeps.md)). It
@@ -1255,9 +1863,14 @@ is the same two functions — the runtime keeps one `RunState`, steps it per inp
 nothing above about reading at rest stops being true. **Three things follow, and two of them catch
 people:**
 
-- **`done` never rejects.** `failed`, `stuck` and `stopped` are terminal OUTCOMES, not errors, so a
-  run that goes wrong arrives as `state.outcome`. A driver refusal resolves it with `stopped` and
-  `stoppedBy` naming the refusal — section 9.
+- **`done` never rejects.** `failed`, `stuck`, `cancelled` and `halted` are terminal OUTCOMES, not
+  errors, so a run that goes wrong arrives as `state.outcome`. A driver refusal resolves it with
+  `halted` and `haltedBy` naming the refusal — section 9; a task the scheduler cancelled on its own
+  resolves it with `cancelled` on the FIRST cancel, while the run's other tasks may still be running —
+  section 6 — and `driver.cancel` resolves it with `cancelled` only once its LAST task has stopped,
+  the run reading `cancelling` until then. A run its owner STOPPED (`handle.stop()`, section 18)
+  resolves it with `interrupted` once the stop's cancels have resolved — not at the stop. **Either resolves it with
+  `halted` AT ONCE if your callback threw on the `cancelRequested` or `interrupted` element** (section 9).
 - **`awaiting_action` is NOT terminal, so `done` waits through it.** A run parked on a person stays
   pending until somebody calls `resolve()`, which is correct and is the trap: if you are waiting for
   a run and a human is in it, you are waiting for the human. Section 7 is the worked case.
@@ -1265,6 +1878,219 @@ people:**
   `Promise.race([done, timeout])` is your one line — and a library default would be wrong for the
   bullet above.
 
+### Pausing a run — `driver.pause` / `driver.unpause`, and a FLAG that is not an outcome
+
+**`driver.pause({ actor })` holds a run without ending it, and `driver.unpause({ actor })` lets it go on** (`RN-R35`,
+[ADR 0106](doc/decisions/0106-a-run-its-owner-pauses-routes-on-and-holds-every-dispatch-until-unpaused.md)). While it
+is paused the run still ROUTES — a settlement's successor is chosen, a join settles, `resolve()` is accepted — and every
+task it dispatches is RECORDED and HELD: its `dispatched` event is in the log, and nothing new reaches the scheduler.
+The tasks the scheduler already has run on and finish. The unpause hands the held tasks on **in the order they were
+dispatched**. Each call is ONE fold input, `{ kind: 'paused', actor }` or `{ kind: 'unpaused', actor }`.
+
+**The fold reads `state.paused` — a FLAG, NOT one of the nine outcomes above**: a held task is dispatched, so it reads
+`running`, and so does the run. Nothing about `outcome`, `isTerminal` or `done` changes; a paused run whose tasks all
+finish and whose paths all end still `completed`s. **And `paused` can read `true` on a run that has ENDED**: only an
+unpause clears it, and a cancelled or halted run refuses one — read `outcome` first, and `paused` only on a live run.
+
+| | what happens |
+|---|---|
+| a task the scheduler already has | runs on and settles, and its settlement routes as ever — what it routes to is held |
+| `resolve()` on a parked task | accepted; its successor is held |
+| an ASK's answer (section 7) | the same: accepted, and whatever it routes to is recorded and HELD until the unpause. Nothing is held FOR the ask — it was never going to be handed on ([W181](doc/work-items/w181-an-ask-under-run-control.md), `RN-R38`) |
+| a call from your own callback, mid-step | accepted, and taken when the driver's step ends — so that step's dispatches are handed on. **Pause before the settlement whose successor you want held** |
+| `handle.stop()` / `driver.stop()` of a paused run | cancels only what the scheduler has; a held task is sent nothing and stays in flight — and the checkpoint resumes **PAUSED** elsewhere, EVERY task in flight held until you unpause there, the ones that were running at the stop included (section 18) |
+| `driver.cancel()` of a paused run | hands each held task on and cancels it, so the scheduler settles every one — `cancelling`, then `cancelled` (section 6) |
+| refused | `RunControlRefused`, `control: 'pause'` or `'unpause'`, by `reason`: `not-started`, `halted`, `cancelled`, `interrupted` (a stopped run — pause it where it resumes), `paused` (a second pause), `not-paused` (an unpause of a run not paused), and for a pause only `ended` — nothing recorded |
+| your `onFoldInput` THROWS on the `paused` or `unpaused` element | the element is in the log — an unpause's held tasks still handed on, in a `finally` — and then the run is HALTED and reported once, and the throw reaches the caller of `pause()` or `unpause()`, or of the call whose step took it; on a scheduler event's step nothing is thrown (section 9, `RN-R35`). *Until [W184](doc/work-items/w184-a-consumer-callback-that-throws-on-every-road.md) a throw on your own call's step reached you with the run going on, paused or running* |
+
+```ts run
+import { Driver, fold, liveToken, type FlowDefinition } from 'fyflow-orchestration';
+
+const flow: FlowDefinition = {
+  flowId: 'pause-run', version: 1, entry: 'split',
+  nodes: [
+    { id: 'split',   kind: 'fanout', branches: ['a', 'b'] },
+    { id: 'a',       kind: 'task', type: 'T', edges: [{ to: 'a2' }] },
+    { id: 'b',       kind: 'task', type: 'T', edges: [{ to: 'b2' }] },
+    { id: 'a2',      kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'b2',      kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'collect', kind: 'join', of: 'split', edges: [{ to: 'done' }] },
+    { id: 'done',    kind: 'end', outcome: 'completed' },
+  ],
+};
+
+// A fake scheduler: it records what it is handed, and a test says when a task completes.
+const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+const added: string[] = [];
+const scheduler = {
+  addTask(task: unknown) { added.push((task as { id: string }).id); },
+  addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+};
+const completes = (id: string) => {
+  for (const fn of listeners.get('task.completed') ?? []) fn({ detail: { id, state: 'done', result: { ok: true } } });
+};
+
+const driver = new Driver(flow, {
+  runId: 'run-1', scheduler, createTask: (c: unknown) => c, predicates: new Map(),
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { T: { worker: 'w' } }, joinPolicy: liveToken,
+});
+driver.start({});
+driver.pause({ actor: 'ops' });     // a and b are already with the scheduler: they run on
+completes('run-1:b:1:0');           // b2 is routed, RECORDED and HELD
+completes('run-1:a:0:0');           // and a2
+console.log(added);                 // [ 'run-1:a:0:0', 'run-1:b:1:0' ] — nothing new handed on
+const paused = fold(driver.foldInputs());
+console.log(paused.outcome, paused.paused);   // running true — a held task is in flight, not finished
+if (added.length !== 2 || paused.outcome !== 'running' || !paused.paused) throw new Error('held, recorded, not handed on');
+
+driver.unpause({ actor: 'ops' });
+console.log(added.slice(2));        // [ 'run-1:b2:1:0', 'run-1:a2:0:0' ] — in the order they were dispatched
+if (added.slice(2).join() !== 'run-1:b2:1:0,run-1:a2:0:0') throw new Error('handed on in dispatch order');
+completes('run-1:b2:1:0');
+completes('run-1:a2:0:0');
+const state = fold(driver.foldInputs());
+if (state.outcome !== 'completed' || state.paused) throw new Error('unpaused, and the run completed');
+```
+
+**BREAKING in 0.8.0** (P34 decision 10): `FoldInput` gains the kinds `'paused'` and `'unpaused'`, so an exhaustive
+`switch` over `kind` no longer compiles; `RunState` gains the cell `paused`, which a `RunState` literal must carry;
+`RunControlRefused.control` gains `'pause'` and `'unpause'` and its `reason` `'paused'` and `'not-paused'`.
+`RunOutcome` does not move.
+
+### Whose task it is — the attribution on a `nodes` entry, and a task's messages and progress
+
+**Every `nodes` entry says which run and which attempt it is, as FIELDS** (`RN-R41`,
+[ADR 0114](doc/decisions/0114-a-tasks-attribution-is-fields-and-its-messages-and-progress-are-passed-through.md)): `runId`
+and `flowAttempt` are the task id's first and fourth segments — `flowAttempt` is `0` on every id minted today — and
+`attemptNumber` is the SCHEDULER's 1-based number of the attempt the task is on or settled on, from the latest `attempted`
+event (section 18). **`attemptNumber` is `null`** before the task's first attempt starts, on an ASK (never handed to a
+scheduler), and on every entry of a log written before 0.8.0 — it is never read off a settlement's `attempts`. Two names,
+so the two attempts cannot be confused.
+
+**And a task's `context.emit()` and progress reach you through the run, with the same attribution** (`RN-R42`):
+`onTaskMessage(m)` and `onTaskProgress(p)` on the `Driver`'s options or `runtime.start`'s (and `runtime.resume`'s). `m`
+carries `runId`, `nodeId`, `branchPath`, `taskId`, `flowAttempt`, `attemptNumber` and the scheduler's `name`, `data`,
+`seq`, `timestamp` — `dropped` and `error` only when the scheduler set them; `p` the same attribution with `progress`,
+`message`, `details` and `timestamp`, and NONE of the task's own fields. Each is a FROZEN copy that is yours.
+
+| | what happens |
+|---|---|
+| you pass neither | the driver does not subscribe `task.message` or `task.progress` — and the scheduler sends nothing while nobody listens, so your workers' emits cost nothing |
+| an event for another run's task, an id no driver minted, or a task this run has not dispatched | dropped in silence — nothing reported, nothing halted. On a runtime ANOTHER run's task never even reaches this run's driver: the router reads `taskId` where the detail has no string `id`. An id that does not parse reaches every driver that asked (each drops it), and an undispatched task of THIS run reaches this run's driver, which drops it |
+| after `stop()`, or once a runtime has released the run (its `done` settled) | nothing more is delivered. A HALTED run's tasks still run, and their events still arrive |
+| a value that cannot be cloned (a function in an inline worker's `details`) | handed to you as `undefined` — the scheduler does the same with an `emit` it cannot clone. **You cannot tell it from a worker that gave nothing**: no marker says the clone failed (a message's `error` is set only when the SCHEDULER refused the clone) |
+| your callback THROWS | reported once through `onRunFailure` and the run HALTED — the treatment `onUnmintedTask` gets (section 9) |
+| the fold, the checkpoint, the routing | untouched: neither callback is ever a fold input |
+
+```ts run
+import { Driver, fold, type FlowDefinition, type TaskMessage, type TaskProgress } from 'fyflow-orchestration';
+
+const flow: FlowDefinition = {
+  flowId: 'attributed', version: 1, entry: 'a',
+  nodes: [
+    { id: 'a',    kind: 'task', type: 'T', retryPolicy: { maxRetries: 1, backoffMs: 0 }, edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+
+// A fake scheduler: it records what the driver SUBSCRIBED to, and a test fires the scheduler's events by hand.
+const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+const subscribed: string[] = [];
+const scheduler = {
+  addTask() {},
+  addEventListener(type: string, fn: (e: { detail: unknown }) => void) {
+    subscribed.push(type);
+    listeners.set(type, [...(listeners.get(type) ?? []), fn]);
+  },
+};
+const fire = (type: string, detail: unknown) => { for (const fn of listeners.get(type) ?? []) fn({ detail }); };
+
+const messages: TaskMessage[] = [];
+const progress: TaskProgress[] = [];
+const driver = new Driver(flow, {
+  runId: 'run-1', scheduler, createTask: (c: unknown) => c, predicates: new Map(),
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { T: { worker: 'w' } },
+  onTaskMessage: (m) => { messages.push(m); },
+  onTaskProgress: (p) => { progress.push(p); },
+});
+if (!subscribed.includes('task.message') || !subscribed.includes('task.progress')) throw new Error('subscribed, because you asked');
+driver.start({});
+
+fire('task.running', { id: 'run-1:a:-:0', state: 'running', attemptNumber: 1 });
+fire('task.running', { id: 'run-1:a:-:0', state: 'running', attemptNumber: 2 });   // the retry starts
+// `task.message` names its task `taskId`; `task.progress` is the task spread flat, so its id is `id`.
+fire('task.message', { taskId: 'run-1:a:-:0', workerId: 'w1', attemptNumber: 2, name: 'log', data: { line: 'fetched 3 rows' }, seq: 0, timestamp: 1 });
+fire('task.message', { taskId: 'run-2:a:-:0', workerId: 'w1', attemptNumber: 1, name: 'log', data: {}, seq: 0, timestamp: 1 });   // another run's
+fire('task.progress', { id: 'run-1:a:-:0', state: 'running', attemptNumber: 2, workerType: 'inline', progress: 0.5, message: 'half', details: null, timestamp: 2 });
+// Messages are BATCHED, so attempt 1's last line can arrive after attempt 2 started: it is attributed to attempt 1.
+fire('task.message', { taskId: 'run-1:a:-:0', workerId: 'w1', attemptNumber: 1, name: 'log', data: { line: 'retrying' }, seq: 1, timestamp: 1 });
+
+const m = messages[0]!;
+console.log(messages.length, m.runId, m.nodeId, m.flowAttempt, m.attemptNumber, m.name, m.data);   // 2 run-1 a 0 2 log { line: 'fetched 3 rows' }
+if (messages.length !== 2 || m.attemptNumber !== 2 || !Object.isFrozen(m)) throw new Error('this run`s messages alone, attributed, frozen');
+if (messages[1]!.attemptNumber !== 1) throw new Error('a late message carries the attempt that EMITTED it, not the latest');
+if (progress.length !== 1 || progress[0]!.progress !== 0.5 || 'workerType' in progress[0]!) throw new Error('the report, not the task');
+
+const entry = fold(driver.foldInputs()).nodes['run-1:a:-:0']!;
+console.log(entry.runId, entry.flowAttempt, entry.attemptNumber);   // run-1 0 2
+if (entry.runId !== 'run-1' || entry.flowAttempt !== 0 || entry.attemptNumber !== 2) throw new Error('the entry carries its attribution — 2, beside the late message`s 1');
+if (driver.foldInputs().length !== 3) throw new Error('dispatched and two attempts — nothing for the message or the progress');
+```
+
+**A worker's OWN messages — `worker.message`, outside any run.** A worker's constructor gets the scheduler's worker
+context as its second argument, and `workerContext.emit(name, data)` sends a `worker.message` on the worker's POOL —
+for what belongs to no task, such as model-loading progress from `setup()`. The library passes these through to
+nothing: they have no run, node or attempt to attribute. Listen on the pool yourself. **The pools are reachable
+through `createRuntime`'s `createScheduler` option**, which is handed the `WorkerManager`s keyed by pool name before
+any task is added — so a listener added there misses nothing. (`runtime.pools` is the DERIVED description of each
+pool, not the `WorkerManager`, and has no events.)
+
+```ts run
+import { createRuntime } from 'fyflow-orchestration/scheduler';
+import { type FlowDefinition, type RegistryDocument } from 'fyflow-orchestration';
+import { FyflowScheduler } from 'fyflow-scheduler';
+
+// A worker that keeps its constructor's second argument and emits from `setup()`, where there is no task.
+const loader = `data:text/javascript,${encodeURIComponent(`export default class Loader {
+  constructor(config, workerContext) { this.ctx = workerContext; }
+  async setup() { this.ctx.emit('loading', { pct: 50 }); this.ctx.emit('loading', { pct: 100 }); }
+  run(envelope) { return envelope.input; } }`)}`;
+
+const registry: RegistryDocument = { workers: { loader: { url: loader } }, nodeTypes: { Model: { worker: 'loader', inline: true } } };
+const flow: FlowDefinition = {
+  flowId: 'loads', version: 1, entry: 'm',
+  nodes: [{ id: 'm', kind: 'task', type: 'Model', edges: [{ to: 'done' }] }, { id: 'done', kind: 'end', outcome: 'completed' }],
+};
+
+// `createScheduler` is handed every pool by name, and returns the scheduler the runtime will use.
+const seen: { pool: string; name: string; data: unknown; seq: number }[] = [];
+const runtime = createRuntime(registry, {}, {
+  base: import.meta.url,
+  createScheduler: (pools, groups) => {
+    for (const [pool, manager] of Object.entries(pools)) {
+      manager.addEventListener('worker.message', (e) => {
+        const d = (e as CustomEvent<{ name: string; data: unknown; seq: number }>).detail;
+        seen.push({ pool, name: d.name, data: d.data, seq: d.seq });
+      });
+    }
+    return new FyflowScheduler(pools, groups);
+  },
+});
+const state = await runtime.start(flow, { ok: true }).done;
+await runtime.shutdown();
+console.log(seen);   // [ { pool: 'Model', name: 'loading', data: { pct: 50 }, seq: 0 }, { …, data: { pct: 100 }, seq: 1 } ]
+
+// Verified by the docs gate:
+const want = JSON.stringify([{ pool: 'Model', name: 'loading', data: { pct: 50 }, seq: 0 }, { pool: 'Model', name: 'loading', data: { pct: 100 }, seq: 1 }]);
+if (state.outcome !== 'completed') throw new Error(`expected completed, got ${state.outcome}`);
+if (JSON.stringify(seen) !== want) throw new Error(`the pool delivered ${JSON.stringify(seen)}`);
+```
+
+**BREAKING in 0.8.0** (P36 (j), (p)): `NodeRun` gains three REQUIRED fields — `runId`, `flowAttempt` and `attemptNumber` —
+so code that builds a `NodeRun` literal (a test's expected entry, a hand-made `RunState`) no longer compiles until it
+carries them. Reading an entry is unaffected. `onTaskMessage`, `onTaskProgress` and the types `TaskMessage`,
+`TaskProgress` and `TaskAttribution` are additive.
+
 ---
 
 ## 9. Refusals
@@ -1272,7 +2098,8 @@ people:**
 Two kinds, and **the distinction is the stack, not the refusal class** (`OR-R10`). The same class can
 do either: whether you are on the stack when it is raised is what decides. A refusal raised while
 *your* call is running is thrown; one raised inside a scheduler event listener is reported, because
-`EventTarget.dispatchEvent` **discards a listener throw** and there is nobody to catch it.
+`EventTarget.dispatchEvent` **never hands a listener throw back** — it resurfaces out of band, and in node
+and deno that is an UNCAUGHT exception that ends your process — and there is nobody to catch it.
 
 **Thrown**, because you are on the stack and can act:
 
@@ -1295,8 +2122,8 @@ console.log(thrown);                                   // 'WorkerMissing'
 if (thrown !== 'WorkerMissing') throw new Error(`construction refused with ${thrown}`);
 
 // **REPORTED — raised inside a scheduler event listener.** Nobody is on the stack to catch it:
-// `EventTarget.dispatchEvent` DISCARDS a listener throw, so the driver reports it instead and the
-// run stops. This is the half a `try` around your own call can never see.
+// `EventTarget.dispatchEvent` never hands a listener throw back (node and deno raise it as an uncaught
+// exception), so the driver reports it instead and the run stops. This is the half a `try` around your own call can never see.
 const registry: RegistryDocument = {
   workers: { scorer: { url: '../../examples/getting-started/scorer.ts' } },
   nodeTypes: { Scorer: { worker: 'scorer', inline: true } },
@@ -1339,7 +2166,11 @@ if (reported.kind !== 'UnresolvedMapArity') throw new Error(`the run reported ${
 ```
 
 `InvalidDefinition` carries the violated rule ids on `.rules`, so you can act on them rather than
-parse a string. `InvalidRunId` is thrown by the **constructor** for a `runId` outside `[A-Za-z0-9_-]{1,64}`
+parse a string. Its message is `definition "<flowId>" is invalid: ` then each finding as `<rule> at <at>: <detail>` — `at` a node id,
+an edge site (`id#edgeN`), or `<document>` for a finding with none — joined by `; `. It is built by ONE function,
+`InvalidDefinition.fromFindings(flowId, findings)`, which `new Driver` and a runtime's `start` and `resume` all call
+(W169), so the two roads cannot word one defect two ways; its precondition is at least one finding, and an empty list
+is refused with a `RangeError` rather than built into an error that names nothing. `InvalidRunId` is thrown by the **constructor** for a `runId` outside `[A-Za-z0-9_-]{1,64}`
 (`ID-R2`) — `:` is excluded because it is the task-id delimiter, and excluding it is what makes the
 task-id parse total.
 
@@ -1348,24 +2179,30 @@ task-id parse total.
 key, and a message naming the entry. `new Driver` runs the shape half only, six classes:
 `WorkerMissing` (a type naming no worker entry, an entry with no `url`), `PoolTypeMissing`,
 `NameCollision` (a pool named as a type), `SchemaRefused` (a keyword outside the subset), and
-`UndeclaredKey` and `DerivationRefused` for a type's or a pool's field of the wrong shape. The other
+`UndeclaredKey` and `DerivationRefused` for a type's or a pool's field of the wrong shape (`DerivationRefused`'s
+other clauses — a derivation that throws, a resident group beside `idleTimeout: 0`, a built-in keyed group held
+resident — need a derivation run, and are `resolveRegistry`'s alone). The other
 five — `ConfigRefused`, `TypeDefaultRefused`, `GroupTypeMissing`, `GroupConfigRefused`,
 `NameMissing` — need a derivation run or a group built, and are thrown by
 `resolveRegistry(document, code)` when a registry DOCUMENT is resolved against the code that
 supplies its predicates, languages, group types and node-type classes, by `createRuntime` (which
 calls that resolver first — section 12), and by the bootstrap helper before it builds a pool. The
 twelfth, **`GateTypeRefused`** (v0.23), is thrown by `checkRegistry` when a gate type it holds is not
-a `GateType` — the built-in `distinct` on every call, and any the registry adds in `gateTypes` — and a gate
+a `GateType` — the built-ins `distinct`, `if` and `switch` on every call, and any the registry adds in `gateTypes` — and a gate
 type named as a built-in is `NameCollision` — at `new Driver`, which since W93 takes yours as `gateTypes`, and
 at `createRuntime`, which takes them as `code.gateTypes` and hands them to every run (section 3). None is `InvalidDefinition`, on purpose: a registry defect is fixed in the registry and a flow defect in the
 flow, and the class says which document to open.
 
 **And four the RUNTIME adds, all `RuntimeError` subclasses from `fyflow-orchestration/scheduler`**
 (W66): `GroupUnusable` — a group factory returned something the scheduler cannot use, naming the
-member and the group's key; `GroupNotBuildable` — a group type with no `create`; `LanguageNotBuilt` —
-`start` was given a flow that transforms on a type no pool was built for; and, 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). A bare
-`RuntimeError` is the fifth road: a relative worker url with no `base`, and a predicate or adapter supplied that the
+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.
+*(`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
+`RuntimeError` is one more road: a relative worker url with no `base`, and a predicate or adapter supplied that the
 document names nowhere. **They are not exported from the package ROOT**, so the enumeration below —
 which walks the root's own exports — does not see them, and `BootstrapError` has never been there
 either.
@@ -1376,12 +2213,16 @@ reported, which is why the rule is about the stack:
 | | |
 |---|---|
 | `driver.start()` a **second time** | throws `MultipleRuns` — a driver serves one run and its id was fixed at construction (`ID-R3`) |
-| `driver.resolve()` with a `result` that is not structured-cloneable | throws the platform's own `DataCloneError`, **not** `UncloneableResult`, and the run is not stopped |
+| `driver.resolve()` with a `result` that is not structured-cloneable | throws the platform's own `DataCloneError`, **not** `UncloneableResult`, and the run is not halted |
 | `driver.start()` with a payload that is not structured-cloneable | throws the platform's own `DataCloneError` with the driver UNSTARTED — a run whose entry payload cannot be copied into its checkpoint header cannot be checkpointed, so it is refused before it exists (`RN-R15`, [ADR 0064](doc/decisions/0064-a-checkpoint-is-the-whole-event-sequence-and-a-header-and-it-is-a-copy.md)). **New in W88, and BREAKING**: such a payload used to start a run on an inline pool |
+| `driver.start()` or `runtime.start()` whose `onHeader` THROWS | throws YOUR error with the driver UNSTARTED — nothing recorded, nothing handed to the scheduler, `onRunFailure` not called: the run never existed, so it is not halted (`RN-R39`, [ADR 0112](doc/decisions/0112-a-run-delivers-its-header-before-its-first-event.md), section 18). A `Driver` may be started again; on a runtime the run id is SPENT (`RunIdInUse` after), as for any `start` that throws once its driver exists |
 | `driver.checkpoint()` before `start()` | throws `NotStarted` — there is no run, and no entry payload to put in a header (`RN-R14`) |
 | `driver.resume(checkpoint)` or `runtime.resume(flow, checkpoint)` with an entry payload that is not structured-cloneable | throws the platform's `DataCloneError` before anything is replayed — the driver unstarted, and on a runtime no run id spent (`RN-R15`) |
-| `driver.checkpoint()` on a driver whose resume was refused | throws `NotStarted` — a refused resume leaves the driver SPENT and deaf to its scheduler, with no run to checkpoint (`RN-R23`) — **except** a resume refused `stopped` because its replay regenerated a stop in the lost tail: that driver keeps the STOPPED run, and its checkpoint is one a store may take. *(This row said `NotStarted` without the exception until W90 read it against `RN-R23`.)* |
-| `driver.resume(checkpoint)` or `runtime.resume(flow, checkpoint)` on a checkpoint it will not resume | throws `ResumeRefused`, whose `reason` is `format`, `run`, `flow`, `stopped` or `diverged` and whose `index` names the position for the last two — nothing is handed to a scheduler ([ADR 0065](doc/decisions/0065-a-resume-replays-the-stored-stimuli-refuses-what-it-cannot-regenerate-and-re-dispatches-what-was-in-flight.md)). `resume()` on a driver that already started or resumed throws `MultipleRuns` (`ID-R3`). **On a runtime, a refusal DURING the replay spends the run id there** — a driver was built for it, so that runtime answers the id with `RunIdInUse` from then on (ADR 0091 keeps the id after it releases the driver); one refused by its header spends nothing ([Q371](doc/questions/q371.md), section 18) |
+| `driver.checkpoint()` on a driver whose resume was refused | throws `NotStarted` — a refused resume leaves the driver SPENT and deaf to its scheduler, with no run to checkpoint (`RN-R23`) — **except** a resume refused `halted` because its replay regenerated a stop in the lost tail: that driver keeps the HALTED run, and its checkpoint is one a store may take. *(This row said `NotStarted` without the exception until W90 read it against `RN-R23`.)* |
+| `driver.resume(checkpoint)` or `runtime.resume(flow, checkpoint)` on a checkpoint it will not resume | throws `ResumeRefused`, whose `reason` is `format`, `run`, `flow`, `halted`, `cancelled` or `diverged` and whose `index` names the position for the last three — nothing is handed to a scheduler ([ADR 0065](doc/decisions/0065-a-resume-replays-the-stored-stimuli-refuses-what-it-cannot-regenerate-and-re-dispatches-what-was-in-flight.md)). `resume()` on a driver that already started or resumed throws `MultipleRuns` (`ID-R3`). **On a runtime, a refusal DURING the replay spends the run id there** — a driver was built for it, so that runtime answers the id with `RunIdInUse` from then on (ADR 0091 keeps the id after it releases the driver); one refused by its header spends nothing ([Q371](doc/questions/q371.md), section 18) |
+| `driver.cancel(options)` the driver will not make | throws `RunControlRefused`, whose `reason` is `unsupported` (the scheduler has no `cancel`), `not-started`, `halted`, `cancelled`, `ended` or `interrupted` (the run was stopped) — nothing recorded and nothing sent to the scheduler (`RN-R31`, [ADR 0104](doc/decisions/0104-a-run-its-owner-cancels-is-cancelling-until-its-last-task-has-stopped.md), section 6); a `graceMs` that is not a number, or is negative or `NaN`, throws `TypeError` or `RangeError` the same way |
+| `driver.stop(options)` or `handle.stop(options)` the driver will not make | throws `RunControlRefused` with `control: 'stop'`, whose `reason` is `unsupported`, `not-started`, `halted`, `cancelled` (a cancelled run is not resumable) or `ended` — nothing recorded and nothing sent to the scheduler (`RN-R33`, [ADR 0105](doc/decisions/0105-a-run-its-owner-stops-goes-deaf-before-it-cancels-and-resumes-elsewhere.md), section 18); a bad `graceMs` throws `TypeError` or `RangeError` the same way |
+| `driver.pause(options)` or `driver.unpause(options)` the driver will not make | throws `RunControlRefused` with `control: 'pause'` or `'unpause'`, whose `reason` is `not-started`, `halted`, `cancelled`, `interrupted` (a stopped run — pause or unpause it where it resumes), `paused` (a second pause), `not-paused` (an unpause of a run not paused), or — a pause only — `ended`; nothing recorded (`RN-R35`, [ADR 0106](doc/decisions/0106-a-run-its-owner-pauses-routes-on-and-holds-every-dispatch-until-unpaused.md), section 8) |
 
 `MultipleRuns` is thrown by a second `start()`: a driver's sequence and join state carry no run id,
 so a second run would silently merge into the first. **One driver, one run** — and the run id is a
@@ -1426,7 +2267,85 @@ settlement it did not mint means its bookkeeping is wrong.
 
 **Reported, not thrown**, when there is nobody on the stack: `DuplicateTaskId`, `UncloneableResult`,
 `NoMatchingEdge` and `UndispatchedTask` raised *inside a scheduler event listener*. Give the driver
-`onRunFailure` or you will not hear about them — the run stops and folds to `stopped`, silently.
+`onRunFailure` or you will not hear about them — the run stops and folds to `halted`, silently. **So is
+a throw from your own `onFoldInput` on any element a scheduler event's step appends** — including the
+`paused`, `unpaused` or `interrupted` element of a pause, unpause or stop you called from a callback on
+that step, which is taken when the step ends (sections 8 and 18): reported under your error's class and
+the run HALTED, the element already in the log (`OR-R10`). A stopped run halted so is not resumable.
+*Until 0.8.0's W178 that throw left the listener and ended the process.* **On YOUR call's step it is the
+SAME — and then it is thrown to you as well** (`OR-R10` v0.19, [W184](doc/work-items/w184-a-consumer-callback-that-throws-on-every-road.md)): `start`, `resume`, `resolve`,
+`cancel`, `stop`, `pause` and `unpause`, called at rest, or with a pause, an unpause, a stop or an answer you
+called from a callback and that is taken when the step ends. Your error is reported ONCE under its class, the run
+is HALTED right after the element — the element's own side effects made first: a stop's and a cancel's cancels sent, an
+unpause's and a cancel's held tasks handed on — and THEN your error is thrown at you. **The FIRST throw halts**: a
+pause, an unpause or an answer you called on the same step and still pending behind it is DROPPED — nothing more is
+dispatched or routed — and a stop pending behind it is still taken, silently, its own throw discarded; so the error
+thrown at you is the one reported. So is a throw from the SCHEDULER once your call is accepted — its `cancel` failing
+inside `driver.cancel` or a stop: reported under its class, the run halted, the error thrown at you. A `cancel()` you call from a
+callback appends its element where you call it, so a throw on it halts the run there even if your callback catches
+it. A `resume()` whose `resumed` element you throw on hands NOTHING on (section 18); one whose lost tail you throw on
+is still refused `ResumeRefused('halted')`. **A call REFUSED before it is accepted halts nothing** —
+`RunControlRefused`, `BoundaryRefused`, `ResumeRefused`, `MultipleRuns`, a `DataCloneError`: nothing was appended. **Nor
+does a throw from your `onHeader`** (section 18): it runs inside `start` before anything is appended, so it is that
+call's refusal — thrown at you, nothing reported, the driver unstarted. **And a throw from your `onTaskMessage` or
+`onTaskProgress`** (section 8) is always a scheduler event's: reported once, the run halted, never thrown at you. That is
+the driver's guarantee, not only the timing: both reach your callback only through the driver's scheduler-event listener,
+which catches whatever it throws — and the scheduler delivers both on its own step anyway, never inside your call.
+**Two callbacks must not throw at all: `onFoldInput` on the `halted` element, and `onRunFailure`.** Each runs
+after the run is halted and the failure reported, so inside a scheduler event listener their throw is DISCARDED —
+lost, with nobody told (`OR-R10`); on your own call's step it reaches you.
+
+**BREAKING in 0.8.0** (P36 (b), (c) and (p), [W184](doc/work-items/w184-a-consumer-callback-that-throws-on-every-road.md)): until W184 a throw from your `onFoldInput` on your OWN
+call's step reached you and the run went ON. A `resolve()` whose `resolution` element you threw on left the answered
+node routed nowhere and the run folding **`completed`** — a run that never reached its end; a stop at rest so thrown
+stayed `interrupted` and resumable, a cancel `cancelling`, a pause or an unpause running; a `resume()` threw with its
+in-flight set never handed on, `running` for ever. Each is now **`halted`** — so a store that failed on a stop's
+`interrupted` element holds a run that is NOT resumable, and a runtime's `done` settles `halted` at once.
+
+```ts run
+import { Driver, fold, liveToken, type FlowDefinition, type FoldInput } from 'fyflow-orchestration';
+
+const flow: FlowDefinition = {
+  flowId: 'store-fails', version: 1, entry: 'x',
+  nodes: [
+    { id: 'x', kind: 'task', type: 'T', edges: [{ to: 'y' }] },
+    { id: 'y', kind: 'task', type: 'T', edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+// A scheduler double, section 12's shape: it records what it is handed and fires only what we tell it to.
+const added: string[] = [];
+const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+const scheduler = {
+  addTask(task: unknown) { added.push((task as { id: string }).id); },
+  addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+};
+const fire = (type: string, detail: unknown) => { for (const fn of listeners.get(type) ?? []) fn({ detail }); };
+
+// YOUR store, which fails on ONE element: the resolution a person's answer appends.
+class StoreDown extends Error {}
+const reported: string[] = [];
+const driver = new Driver(flow, {
+  runId: 'r1', scheduler, createTask: (c) => c, predicates: new Map(), joinPolicy: liveToken,
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { T: { worker: 'w' } },
+  onFoldInput: (e: FoldInput) => { if (e.kind === 'resolution') throw new StoreDown('the store is down'); },
+  onRunFailure: (f) => { reported.push(f.kind); },
+});
+driver.start({});
+// x runs out of retries and parks for a person: the scheduler's PAIR, `task.failed` then `task.user_action`.
+fire('task.failed', { id: 'r1:x:-:0', state: 'user_action', error: 'a person must look' });
+fire('task.user_action', { id: 'r1:x:-:0', state: 'user_action' });
+
+// YOUR call: your error is thrown at you — AND the run is HALTED, and reported once.
+let thrown: unknown = null;
+try { driver.resolve('r1:x:-:0', 'done', { result: { ok: true }, actor: 'ana' }); } catch (e) { thrown = e; }
+const state = fold(driver.foldInputs());
+console.log(thrown instanceof StoreDown, reported, state.outcome, added);   // true [ 'StoreDown' ] halted [ 'r1:x:-:0' ]
+if (!(thrown instanceof StoreDown)) throw new Error('your own error is thrown at you');
+if (reported.join() !== 'StoreDown') throw new Error(`reported ONCE, under its class: ${reported.join()}`);
+if (state.outcome !== 'halted') throw new Error(`the run is HALTED, got ${state.outcome} — before W184 it folded completed`);
+if (added.includes('r1:y:-:0')) throw new Error('nothing is routed from the resolution you threw on');
+```
 
 **`InvalidTaskId` is the ninth class and it is the one that does NOT stop a run.** It is thrown by
 `buildTaskId` and `parseTaskId`, both exported, and it is how you check an id yourself — *did some
@@ -1460,7 +2379,7 @@ import { Driver, type RunFailure } from 'fyflow-orchestration';
 declare const opts: ConstructorParameters<typeof Driver>[1];
 const withReporting = {
   ...opts,
-  onRunFailure: (f: RunFailure) => console.error(`run ${f.runId} stopped: ${f.kind} — ${f.message}`),
+  onRunFailure: (f: RunFailure) => console.error(`run ${f.runId} halted: ${f.kind} — ${f.message}`),
 };
 void withReporting;
 ```
@@ -1501,12 +2420,19 @@ named did not run on your path*, which is the **flow's** shape.
 `BoundaryRefused` is **W73's, and it is the one class here that STOPS NOTHING** — [P19](doc/plans/p19-what-a-schema-buys-an-author.md) decision 5's `FD-R4`. The two values no static check can reach are held to the workers' declared
 schemas ONCE each: the run's payload at `start()`, against the `inputSchema` of every task it reaches with no
 worker in between (the entry, or every branch task of an entry fan-out, or a map's branch once per item),
-and a person's `done` resolution at `resolve()`, against the parked node's worker `outputSchema`. Refused, it is
+and a person's `done` resolution at `resolve()`, against the parked node's worker `outputSchema` — or, for an ASK,
+against the ask's own `answerSchema` (since [W180](doc/work-items/w180-asking-and-answering-in-a-run.md)). Refused, it is
 **thrown at you as a REJECTED COMMAND**: nothing appended, nothing reported, the run unaffected — at `start`
 the driver is still UNSTARTED and a corrected payload starts it, at `resolve` the task is still suspended and
 a corrected value (the worker's declared example is one) resolves it. It carries `boundary`, `nodeId`,
 `taskId` and the schema's `findings`, and its message names the worker and every finding, so you read
-the VALUE and not the flow. A worker declaring no schema on that side is unchecked; `validateBoundaries: false`
+the VALUE and not the flow. A worker declaring no schema on that side is unchecked — **and so, at `start()`, is a
+task that declares a `transform`** ([ADR 0101](doc/decisions/0101-a-transforming-task-is-not-held-at-start.md), W170):
+its worker's `inputSchema` holds the transform's RESULT, which only the worker wrapper makes, so a payload that is
+wrong for the transform starts: it MAY fail in the run (`TransformFailed`, or the worker), or reach the worker
+unchecked and complete — Q633's `{ label: "y" }` ran to `completed` with the worker receiving `{}`. The check before
+a run is yours — `givenVerdict(registry, flow, task, received)` on each transforming target, with the value that task
+RECEIVES (section 15); `validateBoundaries: false`
 on `DriverOptions` or `RuntimeOptions` turns both off. **`FD-R4` is never per settlement**: it holds the run's PAYLOAD once and a person's RESOLUTION
 once, as rejected commands. What a WORKER returns is checked at authoring time by
 `npm run check:workers` and by the wiring check (section 13) — **and, since
@@ -1535,7 +2461,7 @@ import {
   BoundaryRefused,
   ConfigRefused, DerivationRefused, DuplicateTaskId, GateTypeRefused, GroupConfigRefused, GroupTypeMissing, InvalidDefinition,
   InvalidRunId, InvalidTaskId, MissingJoinPolicy, MultipleRuns, NameCollision, NameMissing, NoMatchingEdge, NotStarted,
-  PoolTypeMissing, RegistryError, ResumeRefused, SchemaRefused, TypeDefaultRefused, UncloneableResult, UndeclaredKey,
+  PoolTypeMissing, RegistryError, ResumeRefused, RunControlRefused, SchemaRefused, TypeDefaultRefused, UncloneableResult, UndeclaredKey,
   UndeclaredRoute, UndispatchedTask, UnresolvedBranchPath, UnresolvedMapArity, UnresolvedReference, WorkerMissing,
 } from 'fyflow-orchestration';
 
@@ -1544,6 +2470,7 @@ const documented = [
   MultipleRuns, InvalidRunId, InvalidDefinition, MissingJoinPolicy,      // thrown at you
   NotStarted,                                // thrown at you from checkpoint() before start() — there is no run yet (RN-R14)
   ResumeRefused,                             // thrown at you from resume() — a checkpoint it will not resume, `reason` says why (RN-R23)
+  RunControlRefused,                         // thrown at you from driver.cancel(), stop(), pause() and unpause() — nothing recorded or sent, `reason` says why (RN-R31, RN-R33, RN-R35)
   RegistryError, WorkerMissing, PoolTypeMissing, ConfigRefused, TypeDefaultRefused, GroupTypeMissing,   // thrown at you — a REGISTRY defect,
   GroupConfigRefused, NameCollision, SchemaRefused, UndeclaredKey, NameMissing, DerivationRefused,       // the base class and its twelve (section 13)
   GateTypeRefused,                           // a registered GATE type that is not a GateType — checkRegistry (v0.23)
@@ -1565,8 +2492,12 @@ if (missing.length) throw new Error(`section 9 does not mention: ${missing.join(
 if (stale.length) throw new Error(`section 9 names classes the package no longer exports: ${stale.join(' ')}`);
 ```
 
-After a refusal the run is **stopped**: nothing routes for it again, and its state folds to
-`stopped` whatever its nodes say.
+After a refusal the run is **halted**: nothing routes for it again, and its state folds to
+`halted` whatever its nodes say. **BREAKING in 0.8.0** (P34 decision 10, ADR 0102): 0.7.0 called this `stopped`,
+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.
 
 ---
 
@@ -1581,12 +2512,18 @@ After a refusal the run is **stopped**: nothing routes for it again, and its sta
   flow is between every step. It is not "the run finished". `await done` — the second half of what
   `runtime.start` returns (section 8).
 - **Expecting `await done` to reject when a run goes wrong.** It resolves, always: `failed`, `stuck`
-  and `stopped` are outcomes you read off the state, and `stoppedBy` names a refusal. A `.catch` on
+  and `halted` are outcomes you read off the state, and `haltedBy` names a refusal. A `.catch` on
   `done` is a `.catch` that never fires.
 - **Waiting on `done` for a run with a person in it.** `awaiting_action` is not terminal, so `done`
   is still pending — by design. Poll the fold for the park, resolve the task, then await; section 7
   is that snippet, and `Promise.race([done, timeout])` is the deadline nothing ships for you.
 - **Reading run state mid-turn.** Section 8.
+- **Counting on `start()` to check the payload of an entry that TRANSFORMS.** It does not — `FD-R4` holds a
+  payload to a worker's `inputSchema` only where nothing stands between them, and a `transform` does
+  ([ADR 0101](doc/decisions/0101-a-transforming-task-is-not-held-at-start.md)). *Check, then start*:
+  `givenVerdict(registry, flow, task, received)` runs a task's declared transform and holds the result to the
+  schema — on each transforming TARGET (never a fan-out, map or gate entry, where it returns `[]`) and on the value
+  that task RECEIVES, the payload composed through its `needs` and, for a map's branch, each element — section 15.
 - **Retaining a scheduler event's `detail`.** It is the live task object and it mutates — including
   its `timestamp`, so a retained detail reports the *most recent* event's time. `{...e.detail}` is
   **not** compliance: it still aliases `result` and `error`. The driver copies at the listener
@@ -1644,8 +2581,9 @@ const frozen: Record<string, boolean> = {};
 const HANDLES = ['onFoldInput', 'onRegionEvent', 'snapshot', 'foldInputs'];
 
 // **`onRegionEvent` is FORWARDED, so this road can watch a fan-out open and close** — W76. It was
-// not, until W76: `StartOptions` is a `Pick` of the driver's options, and of the driver's twenty
-// (eighteen when W76 wrote this; `onNonconformingResult` is ADR 0060's, W80's; `gateTypes` ADR 0067's, W93's)
+// not, until W76: `StartOptions` is a `Pick` of the driver's options, and of the driver's twenty-three
+// (eighteen when W76 wrote this; `onNonconformingResult` is ADR 0060's, W80's; `gateTypes` ADR 0067's, W93's; `onHeader` ADR 0112's, W185's;
+// `onTaskMessage` and `onTaskProgress` ADR 0114's, W187's)
 // this was the one no `createRuntime` consumer could reach at all, which is
 // [Q297](doc/questions/q297.md). **The previous version of this snippet asserted the opposite and
 // passed a CAST**, because that was the only way to try; there is no cast now, and the two counts
@@ -1791,15 +2729,15 @@ if (failures.length !== 0) throw new Error(`the quiet half reported ${failures.j
 // `failures.length === 0` above is a measurement rather than a sentence about an empty array.
 //
 // **And `done` RESOLVES here rather than rejecting** (ADR 0058 rules 3 and 4): a refusal is a
-// terminal OUTCOME, not an error, so there is no `.catch` — the run arrives as `stopped` with
-// `stoppedBy` naming the refusal. One settlement rule for every way a run can end.
-const stoppedRun = await run(loud);
+// terminal OUTCOME, not an error, so there is no `.catch` — the run arrives as `halted` with
+// `haltedBy` naming the refusal. One settlement rule for every way a run can end.
+const haltedRun = await run(loud);
 await runtime.shutdown();
-console.log(failures.join(), stoppedRun.outcome, stoppedRun.stoppedBy?.split(':')[0]);
-// 'UncloneableResult' 'stopped' 'UncloneableResult'
+console.log(failures.join(), haltedRun.outcome, haltedRun.haltedBy?.split(':')[0]);
+// 'UncloneableResult' 'halted' 'UncloneableResult'
 if (failures.join() !== 'UncloneableResult') throw new Error(`the loud half reported ${failures.join() || 'nothing'}`);
-if (stoppedRun.outcome !== 'stopped') throw new Error(`a refused run resolved \`done\` with ${stoppedRun.outcome}, not stopped`);
-if (!stoppedRun.stoppedBy?.startsWith('UncloneableResult')) throw new Error(`stoppedBy: ${stoppedRun.stoppedBy}`);
+if (haltedRun.outcome !== 'halted') throw new Error(`a refused run resolved \`done\` with ${haltedRun.outcome}, not halted`);
+if (!haltedRun.haltedBy?.startsWith('UncloneableResult')) throw new Error(`haltedBy: ${haltedRun.haltedBy}`);
 ```
 
 ## 11. What does NOT exist — do not write code using it
@@ -1807,10 +2745,18 @@ if (!stoppedRun.stoppedBy?.startsWith('UncloneableResult')) throw new Error(`sto
 | not available | instead |
 |---|---|
 | 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 |
-| **cancellation** | nothing. The scheduler cannot cancel a queued task either |
-| **durability** — resuming a run after a restart | nothing. The fold is designed to make it additive; it is not built |
+| **`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 `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 |
+| ~~**cancelling a RUN**~~ | **BUILT** since [W173](doc/work-items/w173-cancelling-a-run.md): `driver.cancel({ actor, reason?, graceMs? })` — section 6; the run reads `cancelling` and `done` settles `cancelled` after its last task has stopped. **Not cancelled with it: tasks a WORKER spawned** (`context.spawnTask()`) — the driver knows only what it dispatched, so track their ids from `task.spawn_request` and cancel each (P34 (j)). **And `graceMs: 0` is a request, not a guarantee** — a 0 ms timer a prompt worker can beat ([S12](doc/scheduler-upstream.md)) |
+| ~~**stopping a run**~~ to resume it elsewhere | **BUILT** since [W174](doc/work-items/w174-stopping-a-run-to-resume-it-elsewhere.md): `handle.stop({ actor, reason?, graceMs? })` or `driver.stop(…)` — section 18; the run reads `interrupted`, its `done` settles once the stop's cancels have resolved, and its checkpoint resumes on a FRESH runtime (this one keeps the run id). **Not stopped with it: tasks a WORKER spawned**, as for a cancel |
+| ~~**pausing** a run~~ | **BUILT** since [W175](doc/work-items/w175-pausing-a-run.md): `driver.pause({ actor })` / `driver.unpause({ actor })` — section 8; the run routes on, every dispatch is recorded and HELD, and the unpause hands them on in dispatch order. `state.paused` is a flag, not an outcome. **Nothing is cancelled**: a task the scheduler already has — queued behind a group included — runs on. There is no `handle.pause()`: call `handle.driver.pause()` |
+| ~~**durability**~~ — resuming a run after a restart | **BUILT** since [W89](doc/work-items/w89-what-resuming-is.md): append the events, resume from them — section 18. A cancelled or halted run is refused |
 | **nested fan-out** — a branch that fans out again | **built, and the join over it is settled.** `FD-V15` is retired; a task inside a nested region is dispatched at its whole dotted `branchPath` (`r1:scoreC:1.0:0`); and every policy in section 5 is **transitive** — each region answers exactly as it would if it were not nested ([ADR 0030](doc/decisions/0030-a-join-is-transitive-and-a-dead-join-ends-the-branch-it-sits-in.md)). One thing to know: if an inner join is reported through `onUnsatisfiableJoin`, the outer branch containing it **ends** rather than waiting, so the outer join may still fire and its successor may run — and once that work settles the run folds to `stuck`, because a region that never fired is what `stuck` reads. **Fold too early and you will see `running`.** The four matrix rows and the join seam are tested at **depth 2**; the dead-join cascade is asserted at depth 3, and nothing else about depth 3 is a tested claim |
 | ~~**map-style fan-out**~~ — **BUILT** since [W33](doc/work-items/w33-a-map-at-run-time-arity.md); see section 3 |
+| ~~**RUNNING an `ask`**~~ — a node that waits for a person, its answer at `resolve()` | **BUILT** since [W180](doc/work-items/w180-asking-and-answering-in-a-run.md): a run parks at an ask with nothing handed to the scheduler, and its answer is its result — section 7. Under a cancel, a stop, a pause and a resume an ask is a parked task — never in flight, so nothing is ever sent or handed on for it — since [W181](doc/work-items/w181-an-ask-under-run-control.md) (section 7) |
 | a **join timeout** | nothing. A stuck join is detected by the `stuck` outcome, with no clock |
 | **per-join policy choice** | one policy per driver |
 | a **declared event family** for `fyflow-react-components` | `onRegionEvent`, `onFoldInput` and `joinStatusOf()` — see below |
@@ -1823,6 +2769,14 @@ so you can fold incrementally and see a run finish without polling; `onRegionEve
 opening, arriving, exiting, suspending and resuming; `joinStatusOf()` answers what a join is waiting
 on. What is missing is an agreed envelope shape between the two repositories, not the data.
 
+**Runtime compatibility, as this package intends it: Deno, Node, and the browser for the library but
+not for a flow** — the browser rung is [Q52](doc/questions/q52.md), and a worker there must be a
+bundled `.js` asset. **It is a jsr.io package SETTING, not a manifest field**: measured at W157, Deno's
+`deno.json` schema has no `runtimeCompat` key, `deno publish --dry-run` accepts one and nothing reads
+it, and JSR's API carries it per package. Every lane of the gate runs Node 24; **one L6 run on Node
+26.11.1** — the version fyflow-app's host targets — exited 0 with every assertion passing at W157, and
+is recorded rather than added to the gate.
+
 ---
 
 ## 12. Wiring it to a real scheduler
@@ -1832,7 +2786,8 @@ on. What is missing is an agreed envelope shape between the two repositories, no
 name the document uses against the code you supply, refuses every defect at construction by a named
 error, builds one pool per type instance and one object per group, holds a `FyflowScheduler` over
 them, and hands you **`{ driver, done, header }` per run** — the driver already running, `done` a
-promise that resolves with the run's terminal `RunState`, and `header` the run's checkpoint header
+promise that resolves with the run's terminal `RunState`, and `header` the run's checkpoint header — handed to
+`start`'s `onHeader` option too, before the run's first event, for a store that writes it first (section 18)
 ([ADR 0058](doc/decisions/0058-runtime-start-returns-a-completion-handle-the-runtime-keeps.md);
 section 8 is what it waits for). **What stays yours is exactly what is code**: predicates,
 language adapters, custom group types and custom node-type classes, in one `code` argument.
@@ -1983,11 +2938,38 @@ with no `onStart` throws on its first task and one with no `onFinish` leaves eve
 running for ever, while one with no `getMetrics` runs fine —
 [ADR 0055](doc/decisions/0055-a-group-factorys-output-is-held-to-what-the-scheduler-calls.md).)*
 
-**If a flow transforms, tell the runtime about it.** A language adapter's worker half is written
-into a pool's config at construction, and only for the types whose nodes transform (section 13), so
-pass every flow the runtime will run: `createRuntime(registry, code, { base, flows: [flow] })`. A
-flow handed to `start` that transforms on a type no pool was built for is refused there, naming the
-type and the language, rather than failing every task of that node one run in.
+**A runtime is its registry, and a flow needs nothing passed in advance** —
+[ADR 0096](doc/decisions/0096-a-runtime-is-its-registry-and-start-refuses-from-runtime-check.md). Node
+types, pools, groups and languages are fixed at `createRuntime`, and **every typed pool carries every
+language the registry document names** — the built-in `Transform` and every named instance included —
+so a flow published after the runtime started runs on it, transforming on any type, with nothing extra.
+**`runtime.check(flow)` returns every finding `start` would refuse that flow on** — an array of
+`{ rule, at, detail }`, empty when there is none, and it never throws for a flow's defect — and
+**`start` and `resume` refuse from that same call**, throwing `InvalidDefinition` with exactly those
+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
+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
+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`** —
+`InvalidDefinition`, `FD-V30`, at construction, where until W163 every `start` threw it. **BREAKING in 0.8.0**: `createRuntime`'s and `bootstrap`'s `flows` option,
+`LanguageNotBuilt` and `transformLanguagesByType` are gone. A caller passing `flows` in an object
+LITERAL fails to compile; one passing an options object held in a variable still compiles, and `flows`
+is then an unread key at run time — so delete it either way, and any warm-up flows written to feed it. **The cost** is a thread's, not a
+bundle's: each worker of a typed pool loads every registered engine in its `setup()` — measured at
+W162, about 22 ms and 6.4 MiB of heap per node thread for JSONata, and nothing measurable inline,
+where registering the language already loaded it. A registry naming no language pays nothing. **A
+changed registry is a NEW runtime** (`runtime.register` is declined, section 11): while two overlap,
+their pools and resource groups are SEPARATE, so a rate limit may briefly be exceeded and a model a
+worker loads in `setup()` is loaded twice.
 
 **Thousands of runs at once: start them all on ONE runtime.** Every run `start` (or `resume`) opens
 shares the runtime's pools and its one scheduler, and the runtime ROUTES each settlement to the driver
@@ -2003,7 +2985,8 @@ not routed, and both are yours to size:
   that are not its run's (`ID-R4`). That is correct, and N of them on one scheduler is N² deliveries.
   For a handful of runs it does not matter; for thousands, go through `start`.
 - **A listener of your own** on `runtime.scheduler` — a dashboard, a logger — hears every event of
-  every run. Key it on `detail.id` and do O(1) work per event, or N such listeners are N² again.
+  every run. Key it on `detail.id` — or `detail.taskId` for `task.message`, which has no `id` — and do O(1) work per
+  event, or N such listeners are N² again.
 
 A task id that does not parse — work this library did not mint — still reaches EVERY live run's
 driver, which each report it through `onUnmintedTask` (section 9): nobody owns it, so everybody says so.
@@ -2016,7 +2999,7 @@ parked `awaiting_action` is kept — `resolve()` works as before. **The runtime
 past run, so a postmortem is what YOU keep**: the `RunHandle` (`driver.foldInputs()`, `snapshot()`,
 `checkpoint()`, the `RunState` `done` resolved with), or what your `onFoldInput` stored. Drop the
 handle and the run is gone. After `done`, a released run is handed nothing — not its own run id, not
-an unminted one — so a `stopped` run's tasks still in flight settle into no driver; listen on
+an unminted one — so a `halted` run's tasks still in flight settle into no driver; listen on
 `runtime.scheduler` yourself if you want their results. **The id stays in use**: `start` or `resume`
 naming it on the same runtime throws `RunIdInUse`, because those late settlements carry it. And the
 SCHEDULER keeps every completed task in `scheduler.tasks` unless `maxCompletedTasks` caps it (its own
@@ -2104,7 +3087,11 @@ pools from, as above, rather than a second list; every task the driver dispatche
 envelope `{ settings, input }` (section 13), which is what this repository's worker reads `input`
 from. Pass `createTask` only to run against a
 double — ladder L2-L5 here hand the driver `(c) => c` and read the plain object back — or to build
-something other than a plain `FyflowTask`.
+something other than a plain `FyflowTask`. **A `createTask` that builds the task FIELD BY FIELD must copy
+`attemptsSpent`** (since 0.8.0): a resume hands a task it runs again the attempts it already made, as that key, only
+when there were some — and a factory that drops it starts the task at a fresh retry budget again, silently (section
+18). `(c) => new FyflowTask({ ...c, limitKey })` copies it; `new FyflowTask({ id: c.id, workerType: c.workerType, … })`
+does not.
 
 **The `scheduler` option takes a `FyflowScheduler` as it is.** Until W57 it did not, under the one
 configuration most consumers have: `FyflowScheduler extends EventTarget`, so with the DOM lib in
@@ -2114,6 +3101,13 @@ was [Q71](doc/questions/q71.md), a defect in our type and not in yours, and it i
 `SchedulerLike`'s listener parameter is `object`, which is what makes the real class satisfy it,
 and every snippet in this document is typechecked under the DOM lib by `npm run check:docs`.
 
+**`SchedulerLike` has a THIRD member since 0.8.0, and it is OPTIONAL: `cancel(taskId, options?)`** — the
+scheduler's own signature, which a `FyflowScheduler` has and a runtime's per-run view forwards
+([ADR 0104](doc/decisions/0104-a-run-its-owner-cancels-is-cancelling-until-its-last-task-has-stopped.md)). It is
+read by `driver.cancel` and `driver.stop` alone (sections 6 and 18), so a double with only `addTask` and
+`addEventListener` still drives every run — and either over it is refused `unsupported`, by name, before anything is
+recorded. Give your double a `cancel` that returns a promise if it must cancel or stop a run.
+
 **A worker file can be TypeScript.** Node 24 runs it by stripping types, and Deno natively, so **one
 `.ts` worker serves Node and Deno**. *(The scheduler's own reference **used to say** a Node worker
 must be JavaScript, which was stale at Node 24 — [S9](doc/scheduler-upstream.md), raised 2026-09-07
@@ -2124,20 +3118,30 @@ called the reference stale for nine days and then for one more, in the document
 a browser build needs the worker emitted as a bundled `.js` asset. `RT-R10` — ladder L6 runs in Node
 and Deno and not in the browser, and the browser rung is [Q52](doc/questions/q52.md).
 
-**Pin the scheduler at 0.5.2.** This library's listener boundary is written against **0.3.0
-semantics, which neither 0.5.1 nor 0.5.2 changes**: `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` is byte-identical between 0.3.0, 0.5.1 and 0.5.2**, so
-every one of those still holds; what 0.5.1 added is a `worker.setup.*` / `worker.teardown.*` event
-family this library subscribes to not at all. Install it from a registry — npm and JSR both carry it —
-and **never from a working tree**, which is
+**Pin the scheduler at exactly the version this package's `peerDependencies` names** — read it in
+this package's `package.json`, or run `npm ls fyflow-scheduler` once it is installed. *(Until W157 this sentence carried the
+number, and so did four other documents; each bump was five edits that agreed only by care. The
+number now lives in the manifests and the lock files, and `npm run check:scheduler`'s `D7` refuses it
+anywhere else.)* This library's listener boundary is written against **0.3.0 semantics**:
+`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
+`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
+`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
+every task of a run in flight (section 6). Install the
+scheduler from a registry — npm and JSR both carry it — and **never from a working tree**, which is
 [ADR 0029](doc/decisions/0029-the-scheduler-is-a-registry-dependency-and-nothing-reaches-the-working-tree.md)
 superseding [ADR 0013](doc/decisions/0013-the-scheduler-is-a-development-dependency-reached-from-the-working-tree.md)
 rules 3 and 5. **The manifests say the same thing**, since
 [ADR 0048](doc/decisions/0048-the-scheduler-is-a-declared-dependency-reached-by-one-bare-specifier.md):
 `package.json` names it in `peerDependencies` at exactly that version and `deno.json` maps it to
 `jsr:@fyflow/scheduler` at exactly that version, and `npm run check:scheduler`'s `D8` holds both to
-the pin the same way `D7` holds this sentence. *(This read **"pin at 0.3.0 … npm and JSR both stop at 0.2.1, so 0.3.0 is reached from
+the pin. *(This read **"pin at 0.3.0 … npm and JSR both stop at 0.2.1, so 0.3.0 is reached from
 a working tree"** — a live instruction to a consumer, wrong in the version AND in the mechanism, the
 second having been superseded on 2026-08-31. W36's conformity reader.)*
 
@@ -2175,9 +3179,11 @@ const definition: FlowDefinition = {
 // A fake scheduler, so this snippet runs with no workers. In your program this is
 // `new FyflowScheduler({ ... })` — see section 12.
 //
-// **Key the listeners by event type.** The driver subscribes to three of them and
-// normalizes on the task's terminal STATE rather than the event name (`OR-R3`), so a
-// double that fans one settlement to every listener writes THREE records for it and
+// **Key the listeners by event type.** The driver subscribes to five of them — the four
+// settlements and, since 0.8.0, `task.running` (and `task.message` and `task.progress` when you pass
+// `onTaskMessage` or `onTaskProgress`, section 8) — and normalizes a settlement on the task's
+// terminal STATE rather than the event name (`OR-R3`), so a
+// double that fans one settlement to every listener writes FOUR records for it and
 // the run stops on a `DuplicateTaskId`. A real `EventTarget` does not do this; a
 // hand-written double is where it happens.
 const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
@@ -2315,7 +3321,7 @@ import { validateDefinition, type FlowDefinition, type NodeTypeDeclaration, type
 // key refuses absence by name, and a type whose nodes carry no settings is written over an entry
 // that declares none (two entries here, one module each — since W67 a worker is a module). `configSchema` is held against every pool's
 // derived config at construction; `inputSchema` and `outputSchema` are declared and carried, enforced on ONE
-// value per run each (the entry payload at start(), a person's resolution at resolve() — FD-R4, W73)
+// value per run each (the entry payload at start() unless the task transforms, a person's resolution at resolve() — FD-R4, W73)
 // and never per settlement — since v0.20 (ADR 0056) any schema may carry `examples`, held to it at
 // construction, `npm run check:workers` runs a worker on its input example (P19, W72), and since v0.21
 // `checkWiring(registry, flow)` gives every arc of a flow a verdict from the two (W73).
@@ -2403,10 +3409,10 @@ declare const typed: FlowDefinition;
 declare const languages: Languages;
 
 // The types' groups are given as OBJECTS here and only here; the helper returns them keyed as given.
-// The languages and the flows are what tells the helper WHICH typed pools need which adapter's
-// worker module — written into a pool's config only where a node of that type transforms (W61).
+// The languages' worker modules are written into EVERY pool's config, whatever a flow transforms on
+// (ADR 0096) — the helper reads no flow.
 const registry = { workers: { ingest, scorer }, nodeTypes: { IngestWorker, Scorer } };
-const built = bootstrap(registry, { scorer: new ConcurrentLimitGroup(4, 'scorer') }, { languages, flows: [typed] });
+const built = bootstrap(registry, { scorer: new ConcurrentLimitGroup(4, 'scorer') }, { languages });
 const scheduler = new FyflowScheduler(built.workerPools, built.resourceGroups);
 const driver = new Driver(typed, {
   runId: 'run-1', scheduler, predicates: new Map(), joinPolicy: liveToken,
@@ -2426,6 +3432,49 @@ spent per admission and not per task. Both are held at
 construction: a type's policy to `FD-V30` and a type's groups to the registry's `groups` under
 `FD-V31`, naming the type.
 
+**What a type's `pool` may declare, and what its worker is handed beside the envelope** —
+`spec/flow-definition.md` v0.33, [W159](doc/work-items/w159-what-the-pin-adds-that-a-type-reaches.md).
+`pool` takes the scheduler's `maxThreads`, `maxConcurrentTasks`, `idleTimeout` and `residentGroups`, and
+since v0.33 **`cancelGraceMs`** — on a THREADED pool, the ms a cancelled task's worker gets to stop by
+itself before the scheduler forces it (`Infinity` never forces; an inline pool ignores it) — and
+**`messages: { flushIntervalMs?, maxBuffered? }`**, the bounds on a worker's `emit()`. Each is held to the
+scheduler's own rule at construction, `DerivationRefused` naming the type and the key, so a value the
+scheduler would throw on at `new WorkerManager` is refused where the registry is built. Three more are
+refused here where the scheduler says nothing: a `messages` that is not a PLAIN object (a Map, a Date, an
+array or a class instance — the scheduler spreads it into its defaults and reads nothing), a
+`cancelGraceMs` of `null` (the scheduler takes it for absent and uses 2000), and a stray key inside
+`messages` — which the scheduler does not merely ignore: it carries the object to every worker, so on a
+threaded pool a stray value that cannot be cloned fails the task at run time with *could not be cloned*.
+**`flushIntervalMs` is capped at 2^31-1 ms** (v0.37), the longest delay a timer holds: the scheduler arms `setTimeout`
+with it, and a longer one fires at once — so a value meaning *batch for a month* would flush every `emit()` after 1 ms.
+**And a NAMED instance of a document type may declare its own** — `pools: { "scorer-1": { "type": "Scorer", "pool":
+{ "maxThreads": 1 } } }`, `spec/flow-definition.md` v0.37, [ADR 0099](doc/decisions/0099-a-named-instance-of-a-document-type-may-declare-its-own-pool-options.md),
+[W165](doc/work-items/w165-pool-options-on-a-named-pool-instance.md): the same keys, each held to the same rule and
+refused naming the pool, **merged SHALLOWLY over the type's** — the instance's key wins, a key it leaves out (or sets
+to `undefined`) is the type's, and a `messages` it declares replaces the type's WHOLE — with every object copied, so
+no two pools share one. Two instances of one type need no second type. **An instance of a CLASS type carrying `pool` is
+refused** (`UndeclaredKey`): your class gets the instance key in `pool(config, key)`, so the knob belongs in its
+`configSchema`. The scheduler's `idleCheckIntervalMs`, `requeueFailedTasks` and `maxWorkerRestarts` are refused on a
+type and on an instance alike. **A RESOLVED document type is still a document type here** — what
+`runtime.registry.nodeTypes` holds — so a `Driver` or `bootstrap` handed the runtime's registry accepts the instance;
+a hand-written `NodeTypeDefinition`, or a copy of a resolved one, is a class to this rule.
+**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
+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
+built-in factory's keyed group from your own — as a `Driver` built by hand is not covered by `FD-R6`.
+**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`
+on the scheduler) work in a typed worker exactly as in one the scheduler loads itself, and its
+constructor gets the worker context. The library reads the signal never, and a `task.message` only when you ask:
+pass `onTaskMessage` to `start` (since 0.8.0, section 8) and each message of the run's own tasks reaches you with
+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.
+
 **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
@@ -2451,7 +3500,7 @@ produced. The language this package ships is JSONata, as the sub-path `fyflow-or
 — section 14; the snippet below uses a toy one so it loads no engine, and it is the same interface.
 
 ```ts run
-import { validateDefinition, type FlowDefinition, type LanguageAdapter, type NodeTypeDeclaration, type Registry, type WorkerEntry } from 'fyflow-orchestration';
+import { DerivationRefused, findings, resolveRegistry, SchemaRefused, UndeclaredKey, validateDefinition, type FlowDefinition, type LanguageAdapter, type NodeTypeDeclaration, type Registry, type WorkerEntry } from 'fyflow-orchestration';
 import { EnvelopeWorker, TransformFailed } from 'fyflow-orchestration/scheduler';
 
 // A toy language: an expression is a dotted key path into the input, or `$settings.<path>`.
@@ -2499,8 +3548,8 @@ if (!rules(score({ lang: 'path' })).includes('FD-V37')) throw new Error('FD-V37:
 if (!rules(score({ lang: 'path', expr: 'confidence' }, {})).includes('FD-V23')) throw new Error('FD-V23: a transform on a node with no type is a node with no type');
 
 // And what the wrapper does with it — the class the bootstrap helper puts around your worker,
-// driven here directly. The helper writes `languages` into a typed pool's config for you when you
-// pass it the flows and the languages: `bootstrap(registry, groups, { languages: { path }, flows: [flow] })`.
+// driven here directly. The helper writes `languages` into EVERY pool's config for you when you
+// pass it the languages: `bootstrap(registry, groups, { languages: { path } })`.
 const w = new EnvelopeWorker({ worker: echo.url, languages: { path: path.worker } });
 await w.setup();
 const seen = await w.run({ settings: { factor: 10 }, input: { confidence: 0.9, text: 'a bb ccc' }, transform: { lang: 'path', expr: 'confidence' } });
@@ -2513,15 +3562,77 @@ let failed: unknown;
 try { await w.run({ settings: {}, input: { a: 5 }, transform: { lang: 'path', expr: 'a.b' } }); } catch (e) { failed = e; }
 if (!(failed instanceof TransformFailed) || failed.code !== 'P0002') throw new Error('a loud evaluation failure is a TransformFailed carrying the language`s own code — the TASK fails');
 await w.teardown();
+
+// The CONTEXT, passed through (v0.33): a worker that reads its signal and emits. On a real pool the
+// scheduler builds the context; here it is built by hand, which the wrapper cannot tell apart.
+const reads = `data:text/javascript,${encodeURIComponent(`export default class W {
+  run(p, context) { context.emit('seen', { aborted: context.signal.aborted }); return context.signal.reason; } }`)}`;
+const cw = new EnvelopeWorker({ worker: reads });
+await cw.setup();
+const ctl = new AbortController();
+ctl.abort('stopped by its owner');
+const emitted: unknown[] = [];
+const why = await cw.run({ settings: {}, input: null }, { signal: ctl.signal, emit: (name: string, data: unknown) => emitted.push([name, data]) });
+if (why !== 'stopped by its owner' || JSON.stringify(emitted) !== JSON.stringify([['seen', { aborted: true }]])) throw new Error('a typed worker reaches the signal and the emit its task was handed');
+await cw.teardown();
+
+// And the two v0.33 pool options are held to the scheduler's rules where the registry is built.
+let refused: unknown;
+try { resolveRegistry({ workers: { echo }, nodeTypes: { Scorer: { worker: 'echo', pool: { cancelGraceMs: -1 } } } }); } catch (e) { refused = e; }
+if (!(refused instanceof DerivationRefused) || !refused.message.includes('cancelGraceMs')) throw new Error('a negative cancelGraceMs is refused, naming the key');
+if (resolveRegistry({ workers: { echo }, nodeTypes: { Scorer: { worker: 'echo', pool: { cancelGraceMs: 500, messages: { maxBuffered: 500 } } } } }).pools.get('Scorer')?.spec.cancelGraceMs !== 500) throw new Error('a well-formed one is carried to the pool');
+let tooLong: unknown;
+try { resolveRegistry({ workers: { echo }, nodeTypes: { Scorer: { worker: 'echo', pool: { messages: { flushIntervalMs: 2 ** 31 } } } } }); } catch (e) { tooLong = e; }
+if (!(tooLong instanceof DerivationRefused) || !tooLong.message.includes('flushIntervalMs')) throw new Error('a flush interval no timer can hold (above 2^31-1) is refused');
+
+// And a NAMED instance of a document type may set its own (v0.37, ADR 0099): merged over its type's, key by key.
+const perInstance = resolveRegistry({
+  workers: { echo },
+  nodeTypes: { Scorer: { worker: 'echo', pool: { maxThreads: 4, idleTimeout: 30000 } } },
+  pools: { 'scorer-1': { type: 'Scorer', pool: { maxThreads: 1 } } },
+});
+const single = perInstance.pools.get('scorer-1')?.spec;
+if (single?.maxThreads !== 1 || single.idleTimeout !== 30000) throw new Error('the instance`s maxThreads over the type`s, its idleTimeout the type`s');
+if (perInstance.pools.get('Scorer')?.spec.maxThreads !== 4) throw new Error('and the type`s default pool unmoved');
+let classInstance: unknown;
+try { resolveRegistry({ workers: { echo }, pools: { big: { type: 'Gpu', pool: { maxThreads: 1 } } } }, { nodeTypes: { Gpu: { worker: 'echo', pool: () => ({}) } } }); } catch (e) { classInstance = e; }
+if (!(classInstance instanceof UndeclaredKey)) throw new Error('pool options on a CLASS type`s instance are refused — the class owns its pool');
+
+// And a schema may ANNOTATE (v0.36, ADR 0098): `title` and `description` a string, `readOnly` and
+// `writeOnly` a boolean, each held to that shape, at any depth, and read by NO value check.
+const inputSchema = {
+  type: 'object', title: 'Login', description: 'what the worker reads',
+  properties: { user: { type: 'string', readOnly: true }, password: { type: 'string', writeOnly: true } },
+};
+resolveRegistry({ workers: { echo: { ...echo, inputSchema } }, nodeTypes: { Scorer } });   // accepted
+// writeOnly HIDES NOTHING: the value under it is validated, carried and retained like any other — no redaction.
+if (findings(inputSchema, { user: 'ada', password: 'hunter2' }).length !== 0) throw new Error('the annotations constrain nothing');
+const schemaRefusal = (schema: Record<string, unknown>): unknown => {
+  try { resolveRegistry({ workers: { echo: { ...echo, inputSchema: schema } }, nodeTypes: { Scorer } }); } catch (e) { return e; }
+  return undefined;
+};
+const shape = schemaRefusal({ type: 'string', writeOnly: 'yes' });
+if (!(shape instanceof SchemaRefused) || !shape.message.includes('writeOnly')) throw new Error('an annotation of the wrong shape is refused, naming it');
+const format = schemaRefusal({ type: 'string', format: 'email' });
+if (!(format instanceof SchemaRefused) || !format.message.includes('"format"')) throw new Error('format reads as a constraint and checks nothing here, so it is refused by name');
 ```
 
+**A schema may carry four ANNOTATIONS — `title`, `description`, `readOnly`, `writeOnly` — and they
+constrain nothing** (v0.36, [ADR 0098](doc/decisions/0098-four-annotations-join-the-schema-subset-and-constrain-nothing.md)).
+Each one's value is held to its shape — a string, a boolean — where the schema is declared, and no
+check reads it afterwards: **`writeOnly: true` promises NO REDACTION**. A value under it is cloned,
+kept in the run's event log, checkpointed, kept in run state and handed on exactly as any other, so a secret you do not
+want retained is redacted by your own code before it reaches a run. `readOnly: true` refuses nothing a
+caller supplies. `deprecated`, `$comment`, `default`, `format`, `$schema` and `$id` are still refused
+by name — `default` because nothing applies it, `format` because it would check nothing.
+
 **What this is not.** What a type says about what its worker EXPECTS and RETURNS — input and
 output schemas, and a sample-based check across a transformed edge — was
 [P16](doc/plans/p16-what-a-node-type-is-and-what-the-library-owes-the-scheduler.md)'s plan after
 this one (P18) and is now [P19](doc/plans/p19-what-a-schema-buys-an-author.md)'s, answered in
 **section 15**: since v0.19 a worker DECLARES `inputSchema` and `outputSchema`, no RUN enforces
 them per settlement (that is OUT of P19 as a default) — since v0.21 the two values no static check
-can reach are held to them ONCE each, `FD-R4` (section 9's `BoundaryRefused`), and `checkWiring(registry, flow)`
+can reach are held to them ONCE each (a transforming task's payload excepted, ADR 0101), `FD-R4` (section 9's `BoundaryRefused`), and `checkWiring(registry, flow)`
 gives every arc of a flow one of five verdicts from them before any run (W73), with `pathsOf`,
 `tryTransform` and `signatureOf` beside it as the authoring assists (W74) — and since v0.20 any schema may carry
 `examples` — an annotation held to its schema at construction ([ADR 0056](doc/decisions/0056-an-example-is-an-annotation-validated-against-the-schema-it-sits-on.md),
@@ -2547,7 +3658,8 @@ The language this package ships for a `transform` is **JSONata**, at the one exa
 [W62](doc/work-items/w62-the-jsonata-adapter.md). **The engine is a dependency of this package and
 is loaded by that sub-path alone**: the root and `fyflow-orchestration/scheduler` import none of it,
 so a consumer who never transforms pays the install and never the load, and a browser bundle carries
-the engine only where the sub-path is imported (237 KiB). Import it, put it in the registry's
+the engine only where the sub-path is imported (237 KiB). **A runtime whose registry names it loads it
+in every worker of every typed pool** (ADR 0096 — section 12 has the measured cost). Import it, put it in the registry's
 `languages` under the name a flow's `transform.lang` uses, and hand the same object to the
 bootstrap helper:
 
@@ -2563,7 +3675,7 @@ declare const flow: FlowDefinition;
 // The adapter is `{ compile, worker }`: `compile` runs on the main thread at `new Driver` and
 // `worker` is the URL of the SAME module, which the envelope worker imports inside the pool.
 const languages = { jsonata };
-const built = bootstrap(registry, { scorer: new ConcurrentLimitGroup(4, 'scorer') }, { languages, flows: [flow] });
+const built = bootstrap(registry, { scorer: new ConcurrentLimitGroup(4, 'scorer') }, { languages });
 const scheduler = new FyflowScheduler(built.workerPools, built.resourceGroups);
 const driver = new Driver(flow, {
   runId: 'run-1', scheduler, predicates: new Map(), joinPolicy: liveToken,
@@ -2651,16 +3763,18 @@ specifier there but the bare `jsonata`. An npm consumer installs one 834 KiB pac
 dependencies of its own, whether or not they ever import the sub-path; a Deno consumer's
 `deno.json` resolves the mapping; a bundler includes the engine only in a bundle that imports the
 sub-path. **A bundled worker is your asset**: inside a bundle `import.meta.url` is the bundle's own
-URL ([Q261](doc/questions/q261.md)), so `jsonata.worker` — like the envelope worker itself — has to be
-served beside your bundle as a module of its own for a pool's thread to load it.
+URL ([Q261](doc/questions/q261.md)), so `jsonata.worker` has to be served beside your bundle as a module of its own
+for a pool's thread to load it. **The envelope worker does not**, from npm: the npm dist carries it inside itself, a
+`data:` URL on Node and a `Blob` URL in the browser. A bundle you build from the JSR SOURCE has to serve it
+too, compiled, at the `./envelope-worker.ts` URL the source names beside the bundle.
 
 ---
 
 ## 15. What a schema buys an AUTHOR — an authoring session
 
 **The schemas in section 13 were never for the run.** A worker's `inputSchema` and `outputSchema`
-are held to the run's PAYLOAD once and to a person's RESOLUTION once each (`FD-R4`, section 9) and
-never per settlement — and neither of those is *two values per run*, because a fan-out or map entry
+are held to the run's PAYLOAD once (not where the task declares a `transform`, ADR 0101) and to a person's
+RESOLUTION once each (`FD-R4`, section 9) and never per settlement — and neither of those is *two values per run*, because a fan-out or map entry
 validates one value per branch task it reaches and a run nobody parks validates no resolution at
 all. So what are they for? **They are for whoever is wiring the flow**, a person or an agent, and this section is
 the session that shows it: a flow written, a MISWIRE caught before anything runs, a transform
@@ -2673,7 +3787,7 @@ adapter's worker half, so it loads a module by URL and returns a promise:
 | | answers |
 |---|---|
 | `pathsOf(schema)` | *what is there to reach for* — every path a value may carry, and which are guaranteed |
-| `tryTransform(registry, flow, node, transform)` | *does THIS expression fit* — one candidate, one verdict, on a real sample |
+| `tryTransform(registry, flow, node, transform, { input }?)` | *does THIS expression fit* — one candidate, one verdict, on a real sample — or on a value you GIVE, the entry node included (*A sample you GIVE*, below) |
 | `signatureOf(name, worker)` | *what do I write my worker against* — TypeScript, as text |
 
 The registry below is
@@ -2692,8 +3806,7 @@ import { SESSION_BASE, SESSION_REGISTRY, SESSION_WORKERS } from '../../examples/
 // and the languages a transform may be written in. `createRuntime` takes the whole document below.
 const registry = { workers: SESSION_WORKERS, nodeTypes: SESSION_REGISTRY.nodeTypes, languages: { jsonata } };
 
-// THE FLOW, as an author first writes it: read a batch, summarise it. It is a VALID document —
-// `validateDefinition` has nothing to say about it, because nothing here is about the grammar.
+// THE FLOW, as an author first writes it: read a batch, summarise it. Its grammar is valid.
 const flow: FlowDefinition = {
   flowId: 'session', version: 1, entry: 'read',
   nodes: [
@@ -2718,40 +3831,39 @@ console.log(describePaths(pathsOf(SESSION_WORKERS.reader.outputSchema)));
 // ? $.lines[]                    string
 //   $.source                     string
 
-// STEP 3 — a first candidate. It is run on the producer's declared EXAMPLE, and the result is held
-// to the consumer's input schema, so the answer is about a value rather than about two declarations.
+// STEP 3 — a first candidate, run on the producer's declared example and checked against the
+// consumer's input schema.
 const attempt = await tryTransform(registry, flow, 'sum', { lang: 'jsonata', expr: '{ "text": lines }' });
 console.log(`${attempt[0]!.kind}: ${attempt[0]!.why}`);
 // transform-fails: the transform's result on the example fails the consumer's inputSchema — $.text expected string, got array
 if (attempt[0]!.kind !== 'transform-fails') throw new Error('an array is not a string, and the loop says which');
 
-// STEP 4 — ONE expression edit, and the same loop. `transform-passes` is never `fits`: it is a fact
-// about the sample the verdict names, which is why `sample.source` is on it (a declared example
-// here; where a schema declares none, a generated WITNESS, and the verdict says so).
+// STEP 4 — one edit, and the same loop. `transform-passes` is about the sample it names, which is
+// the declared example here, or a generated one where a schema declares none.
 const good = { lang: 'jsonata', expr: '{ "text": $join(lines, " ") }' };
 const passed = await tryTransform(registry, flow, 'sum', good);
 console.log(`${passed[0]!.kind} on the ${passed[0]!.sample!.source}: ${JSON.stringify(passed[0]!.sample!.result)}`);
 if (passed[0]!.kind !== 'transform-passes') throw new Error(`expected the sample to pass, got ${passed[0]!.kind}`);
 
-// STEP 5 — the signature the worker is written against, generated from the same three schemas.
-// `examples/getting-started/session-types.ts` is this text, checked in, and `summarise.ts` imports
-// it. A type holds the SHAPE: `words` is `number` here and its schema says `minimum: 0`.
+// STEP 5 — the signature the worker is written against, generated from the same schemas.
+// `examples/getting-started/session-types.ts` is this text, and `summarise.ts` imports it.
 const signature = signatureOf('Summarise', SESSION_WORKERS.summarise);
 console.log(signature.split('\n').filter((l) => l.startsWith('export')).join('\n'));
 if (!signature.includes('"text": string;')) throw new Error('the required key is required in the type too');
 
-// STEP 6 — and only now the runtime. Pools are built ONCE, so a flow whose transform was decided
-// during the session has to reach `createRuntime` as `flows`, or `start` throws `LanguageNotBuilt`
-// naming the type. Check, then build.
+// STEP 6 — only now the runtime. Check the wired flow against it, then start it; `start` refuses
+// from that same check.
 const wired: FlowDefinition = { ...flow, nodes: flow.nodes.map((n) => (n.id === 'sum' ? { ...n, transform: good } : n)) };
-const runtime = createRuntime(SESSION_REGISTRY, { languages: { jsonata } }, { base: SESSION_BASE, flows: [wired] });
+const runtime = createRuntime(SESSION_REGISTRY, { languages: { jsonata } }, { base: SESSION_BASE });
+const refused = runtime.check(wired);
+if (refused.length !== 0) throw new Error(`the runtime refuses the wired flow: ${JSON.stringify(refused)}`);
+const unknownLang: FlowDefinition = { ...flow, nodes: flow.nodes.map((n) => (n.id === 'sum' ? { ...n, transform: { lang: 'nope', expr: '$' } } : n)) };
+if (!runtime.check(unknownLang).some((f) => f.rule === 'FD-V35' && f.at === 'sum')) throw new Error('a language the registry does not name is FD-V35, at check');
 const state = await runtime.start(wired, { source: 'inbox' }).done;
 await runtime.shutdown();
 console.log(state.outcome, Object.values(state.nodes).find((n) => n.nodeId === 'sum')?.result);  // completed { words: 3 }
 
-// The expected values are the DOCUMENT's, not literals beside the run: the consumer's own declared
-// output example, and the producer's declared line count. A registry whose examples stop describing
-// its workers is red here and in `test/definition/assist.test.ts`, which runs the same chain.
+// Verified by the docs gate:
 if (state.outcome !== 'completed') throw new Error(`expected completed, got ${state.outcome}`);
 const got = Object.values(state.nodes).find((n) => n.nodeId === 'sum')?.result;
 if (JSON.stringify(got) !== JSON.stringify(SESSION_WORKERS.summarise.outputSchema.examples[0])) {
@@ -2798,6 +3910,97 @@ W74's conformity reader, from the author's own scratchpad output.)* Neither hold
 which RUNS each worker on its declared example and validates what came back — is what catches the
 rest.** Even that sees one value: a bound the code does not keep past the example is invisible to it
 and visible at every consumer the wiring check reads ([Q302](doc/questions/q302.md)).
+
+### A sample you GIVE — `tryTransform(…, { input })`, the entry node included
+
+**Every verdict above runs on a SCHEMA's value** — the producer's declared example, or its witness — and
+the entry node gets none, because no arc reaches it: `tryTransform` on `read` above returns `[]`. An
+editor has a value in hand instead: typed, pasted, or taken from a run. **Pass it as `input`** and the
+candidate runs ONCE on it as what the node RECEIVES — `$` — and `tryTransform` returns **ONE verdict
+whatever arcs reach the node, on the entry node too** (W166, P37 stop-and-ask (d)):
+
+| | a given verdict |
+|---|---|
+| `shape` | `'given'` — not an arc; `checkWiring` never produces it |
+| `producer` | **absent** — the value came from no node (and `through` too) |
+| `sample` | `{ source: 'given', value, result }` — the value you gave, and what the transform made of it; no `arity`. **Never `'example'` or `'witness'`** |
+| `kind` | `transform-passes`, or `transform-fails` with the finding against the node's worker `inputSchema` — or naming the error, where the expression does not compile or throws on this value; `unchecked` for a language, type, worker or worker schema the registry lacks, as on an arc, naming which — and for a `null` candidate, which takes away any transform the node declares too: there is nothing to run the value through, and holding that value to the `inputSchema` is `findings(schema, value)` |
+
+**The value is `$` as you give it: no `needs` is composed over it**, because a `needs` composes what
+arrives and this is what arrived — and on a `map`'s branch task it is ONE instance's value, evaluated
+once. **That includes a `"$payload"` or a `"$item"` key** (since 0.8.0): give the node what it RECEIVES, the payload
+or the instance's item already under that key — neither function composes one, so a given input and a run agree only when you compose as the run does. `input: undefined` is no input (the arcs answer, as before); `null` is a value. *What it is not*:
+a statement about the producer or the flow — it says what this expression does to this value, and a
+value that passes is *the sample passed — the given input*, never *fits*. **`givenVerdict(registry, flow,
+node, input)`**, exported beside `checkWiring`, is the same road on the node as the flow DECLARES it —
+`tryTransform` calls it on the copy that carries your candidate, so the two have ONE contract: `input`
+`undefined` is no input there too, and the node's arcs answer. **`givenVerdict` and `TryTransformOptions` are
+NEW public surface in 0.8.0.**
+
+**On an entry that TRANSFORMS, this is the only check of a run's payload before the run.** `start()` does not hold
+a task that declares a `transform` to its worker's `inputSchema` ([ADR 0101](doc/decisions/0101-a-transforming-task-is-not-held-at-start.md),
+`FD-R4`, section 9): the schema is about the transform's RESULT, and that exists only in the worker. So *check, then
+start* — but on the value each transforming TASK receives, because a given value is `$` with no `needs` composed:
+`boundaryTargets(flow, payload)` lists the tasks the payload reaches and the value reaching each (for a map's branch,
+each element under `over`; through an entry gate, every route's target), and where the task declares `needs` (at an
+entry `"."` and, since 0.8.0, `"$payload"`) compose it first — `needs: { own: "." }` receives `{ own: value }`, and
+`needs: { run: "$payload" }` receives `{ run: payload }`, the PAYLOAD even on a map's branch, where the value is an
+element — and there `needs: { it: "$item" }` receives `{ it: element }`. Call
+`givenVerdict(registry, flow, task, received)` on each that transforms; a fan-out, map or gate ENTRY is no task and
+gives `[]`. Start on `transform-passes`; `unchecked` (no `inputSchema`, or a language, type or worker the registry
+lacks) checked nothing. Until W170 `start()`
+held the payload BEFORE the transform, and one value drew opposite verdicts from the two
+([Q633](doc/questions/q633.md)).
+
+```ts run
+import { tryTransform, type FlowDefinition } from 'fyflow-orchestration';
+import { jsonata } from 'fyflow-orchestration/jsonata';
+import { SESSION_REGISTRY, SESSION_WORKERS } from '../../examples/getting-started/session-registry.ts';  // in your program: './registry.ts', a module or a JSON file of your own
+
+const registry = { workers: SESSION_WORKERS, nodeTypes: SESSION_REGISTRY.nodeTypes, languages: { jsonata } };
+const flow: FlowDefinition = {
+  flowId: 'session', version: 1, entry: 'read',
+  nodes: [
+    { id: 'read', kind: 'task', type: 'Reader', edges: [{ to: 'sum' }] },
+    { id: 'sum', kind: 'task', type: 'Summarise', edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+
+// THE ENTRY NODE. No arc reaches it, so the schemas have nothing to say about what it receives...
+const rename = { lang: 'jsonata', expr: '{ "source": folder }' };
+if ((await tryTransform(registry, flow, 'read', rename)).length !== 0) throw new Error('no arc reaches the entry');
+// ...and given what it receives, ONE verdict. `reader`'s inputSchema wants `source` a string.
+const [entry] = await tryTransform(registry, flow, 'read', rename, { input: { folder: 'inbox' } });
+console.log(`${entry!.kind} on the ${entry!.sample!.source}: ${JSON.stringify(entry!.sample!.result)}`);  // transform-passes on the given: {"source":"inbox"}
+if (entry!.shape !== 'given' || entry!.producer !== undefined || entry!.sample!.source !== 'given') throw new Error('a given verdict: shape given, no producer');
+if (entry!.kind !== 'transform-passes') throw new Error(`expected the given value to pass, got ${entry!.kind}: ${entry!.why}`);
+
+// The same expression on a value it does not fit: the finding, against the node's own inputSchema.
+const [wrong] = await tryTransform(registry, flow, 'read', rename, { input: { folder: 3 } });
+console.log(`${wrong!.kind}: ${wrong!.why}`);  // transform-fails: the transform's result on the given input fails the consumer's inputSchema — $.source expected string, ...
+if (wrong!.kind !== 'transform-fails' || !wrong!.why.includes('$.source expected string')) throw new Error(`expected the finding, got ${wrong!.why}`);
+
+// THE INNER NODE. Without an input its one arc runs on `reader`'s declared EXAMPLE; given a value, it runs on that.
+const join = { lang: 'jsonata', expr: '{ "text": $join(lines, " ") }' };
+const [arc] = await tryTransform(registry, flow, 'sum', join);
+const [mine] = await tryTransform(registry, flow, 'sum', join, { input: { lines: ['typed', 'by', 'hand'] } });
+console.log(arc!.sample!.source, mine!.sample!.source, mine!.sample!.result);  // example given { text: 'typed by hand' }
+if (arc!.sample!.source !== 'example' || mine!.sample!.source !== 'given') throw new Error('the arc runs on the example, a given value on itself');
+if (JSON.stringify(mine!.sample!.result) !== JSON.stringify({ text: 'typed by hand' })) throw new Error('joined, the three given lines');
+
+// An expression the engine refuses: `transform-fails`, naming the throw — the compile error, on the given input.
+const [broken] = await tryTransform(registry, flow, 'sum', { lang: 'jsonata', expr: '{{{' }, { input: { lines: [] } });
+if (broken!.kind !== 'transform-fails' || !broken!.why.startsWith('the transform threw on the given input')) throw new Error(`expected the compile error, got ${broken!.why}`);
+```
+
+**BREAKING in 0.8.0** (P37 decision 10): **`SampleSource` gains `'given'`**, **`WiringShape` gains
+`'given'`** (and `WIRING_SHAPES` with it), and **`WiringVerdict.producer` is optional** — absent on a
+given verdict and only there. A `switch` exhaustive over the two sources or the five shapes no longer is,
+and code reading `producer` as a `string` fails to compile under `strictNullChecks` — narrow it on
+`shape !== 'given'`, or read it as `string | undefined`. `checkWiring`'s own verdicts are unchanged: every
+one still carries a producer and an `'example'` or `'witness'` sample.
+
 ---
 
 ## 16. What a schema buys a RUN — holding a result to the schema its worker declares
@@ -2905,7 +4108,7 @@ if (wiring.counts.no !== 0) throw new Error('the static check has nothing to say
 // authored, no dispatch moves, and the value reaches the next node exactly as it would with the
 // check off.
 const found: NonconformingResult[] = [];
-const runtime = createRuntime(registry, {}, { base: import.meta.url, flows: [flow] });
+const runtime = createRuntime(registry, {}, { base: import.meta.url });
 const state = await runtime.start(flow, { text: 'one two three four five six seven eight nine ten eleven' }, {
   onNonconformingResult: (f) => { found.push(f); },
 }).done;
@@ -2941,7 +4144,7 @@ if (after.keys.join() !== 'load,words') throw new Error(`the successor received
 // OMIT THE CALLBACK AND NOTHING IS CHECKED — and the run is the same run. This is the property to
 // rely on: you can turn the reading on in one environment and off in another without changing what
 // the flow DOES, because an instrument that altered what it measures would be useless for auditing.
-const quiet = createRuntime(registry, {}, { base: import.meta.url, flows: [flow] });
+const quiet = createRuntime(registry, {}, { base: import.meta.url });
 const same = await quiet.start(flow, { text: 'one two three four five six seven eight nine ten eleven' }).done;
 await quiet.shutdown();
 const shape = (s: typeof state) => JSON.stringify(Object.values(s.nodes).map((n) => [n.nodeId, n.result]));
@@ -2983,8 +4186,8 @@ a fan-out's width is an authoring-time fact. Here the outer width is *how many o
 returned* and each inner width is *how many lines THAT order has* — different per instance.
 
 **Writing it needs exactly one node between the two maps.** A `map`'s `over` names a key of what the
-previous node returned, and a `map`'s branch is a TASK (`FD-V25` refuses a map whose branch is a
-map) — so the outer branch entry is the node whose output carries the item's own list. No `needs`, no
+previous node returned, and a `map`'s branch is a TASK — or, since 0.8.0, an `ask`, which runs no worker (`FD-V25`
+refuses a map whose branch is a map) — so the outer branch entry is the node whose output carries the item's own list. No `needs`, no
 `transform`, no reshaping node and no second flow.
 
 ```ts run
@@ -3026,7 +4229,7 @@ const flow: FlowDefinition = {
 // A region event now says WHICH INSTANCE it is about. Before 0.4.0 it carried `regionId` alone,
 // which is the same string for every instance of one opener.
 const arrivals: string[] = [];
-const runtime = createRuntime(registry, {}, { base: import.meta.url, flows: [flow] });
+const runtime = createRuntime(registry, {}, { base: import.meta.url });
 const state = await runtime.start(flow, { region: 'ab c' }, {
   onRegionEvent: (e: RegionEvent) => {
     if (e.type === 'branch.arrived') arrivals.push(`${e.regionId}@${e.regionPath} <- ${e.branchPath}`);
@@ -3099,14 +4302,20 @@ checkpoint is an append to it**. You never have to call `driver.checkpoint()` to
 
 | | where you get it | what you do with it |
 |---|---|---|
-| the header | `runtime.start(…)` returns it as `header`, beside `driver` and `done` | write it once |
+| the header | **`onHeader(header)`** on `start`'s options — handed to you inside `start`, BEFORE the first event and before anything reaches the scheduler; and `runtime.start(…)` returns the same one as `header`, beside `driver` and `done` | write it once, FIRST |
 | every event | `onFoldInput(event, position)` | write it AT `position` — the driver's index, never a count you start again in each process |
-| a resumed run | `runtime.resume(flow, { header, events }, options)` returns the same `{ driver, done, header }` | keep writing: it hands you positions from the STORED LENGTH on |
-
-**Key the store by POSITION, and the reason is measured.** The first events are delivered WHILE
-`start` runs, so the header arrives after them — a store that must write its header first cannot —
-and a resumed run's first position is the length you stored, not 0, so an arrival counter per process
-overwrites the run it is resuming. ([W90](doc/work-items/w90-a-run-killed-and-resumed-on-real-workers.md)
+| a resumed run | `runtime.resume(flow, { header, events }, options)` returns the same `{ driver, done, header }` — and calls no `onHeader`: you hold the header already | keep writing: it hands you positions from the STORED LENGTH on |
+
+**Write the header FIRST, through `onHeader`** (`RN-R39`, [ADR 0112](doc/decisions/0112-a-run-delivers-its-header-before-its-first-event.md),
+since 0.8.0). The first events are delivered WHILE `start` runs, so the handle's `header` arrives after them, and a process
+that died between your first event write and that header write left events no resume can read. `onHeader` is called ONCE,
+before the first `onFoldInput`, with a frozen copy equal to `handle.header` — and **if it throws** (your store could not
+write it), `start` throws your error with NOTHING started: nothing recorded, nothing handed to the scheduler, nothing
+reported. A `Driver` you built may be started again; on a runtime that run id is spent, so retry under another (or let it
+mint one). It is never called on a refused `start` (`BoundaryRefused`, `DataCloneError`, `MultipleRuns`), nor by `resume`.
+
+**And still key the store by POSITION, and the reason is measured.** A resumed run's first position is the length you
+stored, not 0, so an arrival counter per process overwrites the run it is resuming. ([W90](doc/work-items/w90-a-run-killed-and-resumed-on-real-workers.md)
 runs exactly that wrong store at L6 and it is refused `diverged` at position 0.) **The contract is
 `structuredClone`, not JSON**: a result is whatever survived `OR-R2`'s clone, which includes `Map`,
 `Set`, `Date`, `BigInt` and `-0` — pick a serializer that keeps them, or revive them.
@@ -3153,9 +4362,12 @@ const store: { header?: CheckpointHeader; events: FoldInput[] } = { events: [] }
 let alive = true;
 let die!: () => void;
 const died = new Promise<void>((resolve) => { die = resolve; });
-const first = createRuntime(registry, {}, { base: import.meta.url, flows: [flow] });
+const first = createRuntime(registry, {}, { base: import.meta.url });
 const run = first.start(flow, { region: 'ab c' }, {
+  // The header FIRST — called once, inside `start`, before the first event below and before any task is handed on.
+  onHeader: (header) => { store.header = header; },
   onFoldInput: (event, position) => {
+    if (store.header === undefined) throw new Error('an event before the header: the store would hold events no resume can read');
     if (!alive) return;                                   // a dead process writes nothing
     store.events[position] = structuredClone(event);     // your durable append, BY POSITION
     // THE CRASH, simulated: the process dies the instant the first `expand` settles — inside the
@@ -3163,9 +4375,9 @@ const run = first.start(flow, { region: 'ab c' }, {
     if (event.kind === 'outcome' && event.record.taskId.includes(':expand:')) { alive = false; die(); }
   },
 });
-// The header arrives on the handle, AFTER the first events: they were delivered while `start` ran.
-// A store that had to write its header first could not; one keyed by position does not care.
-store.header = run.header;
+// The handle carries the SAME header — it arrives AFTER the first events, which were delivered while `start` ran, and
+// that is why the store took it from `onHeader` instead.
+if (JSON.stringify(store.header) !== JSON.stringify(run.header)) throw new Error('onHeader and the handle carry one header');
 await died;
 // `shutdown()` is cleanup, NOT the kill: it lets running work finish, and here that finishes the
 // whole run. What makes this a crash is the store — nothing after `alive = false` reached it.
@@ -3179,7 +4391,7 @@ console.log(`stored ${store.events.length} events, the last one the settlement t
 // keep appending BY POSITION: a resumed run hands you positions from the stored length on, so the
 // same store holds the whole run again.
 const header = store.header!;                            // written once, by process one
-const second = createRuntime(registry, {}, { base: import.meta.url, flows: [flow] });
+const second = createRuntime(registry, {}, { base: import.meta.url });
 const resumed = second.resume(flow, { header, events: store.events.slice() }, {
   onFoldInput: (event, position) => { store.events[position] = structuredClone(event); },
 });
@@ -3221,7 +4433,7 @@ try {
   if (!(err instanceof RunIdInUse)) throw err;
 }
 // And a checkpoint is resumed against the definition it was stored under, or not at all.
-const third = createRuntime(registry, {}, { base: import.meta.url, flows: [flow] });
+const third = createRuntime(registry, {}, { base: import.meta.url });
 try {
   third.resume({ ...flow, version: 2 }, { header, events: store.events.slice() });
   throw new Error('expected ResumeRefused');
@@ -3232,20 +4444,90 @@ await second.shutdown();
 await third.shutdown();
 ```
 
+**A store that cannot write the header stops the run BEFORE it exists** — `onHeader`'s throw, on a `Driver` you build
+(section 12's double, so you can see what reaches the scheduler):
+
+```ts run
+import { Driver, NotStarted, liveToken, type CheckpointHeader, type FlowDefinition, type FoldInput } from 'fyflow-orchestration';
+
+const flow: FlowDefinition = {
+  flowId: 'header-first', version: 1, entry: 'split',
+  nodes: [
+    { id: 'split', kind: 'fanout', branches: ['a', 'b'] },
+    { id: 'a', kind: 'task', type: 'T', edges: [{ to: 'join' }] },
+    { id: 'b', kind: 'task', type: 'T', edges: [{ to: 'join' }] },
+    { id: 'join', kind: 'join', of: 'split', edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+// ONE log: what your store wrote, and what reached the scheduler, in the order it happened.
+const log: string[] = [];
+const scheduler = { addTask(task: unknown) { log.push(`handed on ${(task as { id: string }).id}`); }, addEventListener() {} };
+
+// YOUR store, down for the first attempt.
+class StoreDown extends Error {}
+let storeUp = false;
+const store: { header?: CheckpointHeader; events: FoldInput[] } = { events: [] };
+const driver = new Driver(flow, {
+  runId: 'r1', scheduler, createTask: (c) => c, predicates: new Map(), joinPolicy: liveToken,
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { T: { worker: 'w' } },
+  onHeader: (header) => {
+    if (!storeUp) throw new StoreDown('the store could not write the header');
+    store.header = header;
+    log.push('header written');
+  },
+  onFoldInput: (event, position) => { store.events[position] = event; log.push(`event ${position} written`); },
+});
+
+// The store is down: `start` throws YOUR error, and NOTHING started — no event, nothing handed on.
+let thrown: unknown = null;
+try { driver.start({ batch: 7 }); } catch (e) { thrown = e; }
+console.log(thrown instanceof StoreDown, log);   // true []
+if (!(thrown instanceof StoreDown) || log.length !== 0) throw new Error(`nothing starts when the header cannot be written: ${log.join()}`);
+let unstarted = false;
+try { driver.checkpoint(); } catch (e) { unstarted = e instanceof NotStarted; }
+if (!unstarted) throw new Error('the driver is UNSTARTED — there is no run to checkpoint');
+
+// The store is back: the SAME driver starts, and the header is written before the first event and the first hand-off.
+storeUp = true;
+driver.start({ batch: 7 });
+console.log(log[0], log.length);   // 'header written' 8 — then the five events of an entry fan-out of two and its two hand-offs
+if (log[0] !== 'header written') throw new Error(`the header is written FIRST: ${log.join(' | ')}`);
+if (log.filter((l) => l.startsWith('event ')).length !== 5 || log.filter((l) => l.startsWith('handed on ')).length !== 2) {
+  throw new Error(`an entry fan-out of two appends five events and hands on two tasks, all after the header: ${log.join(' | ')}`);
+}
+if (JSON.stringify(store.header) !== JSON.stringify(driver.checkpoint().header)) throw new Error('the header written is the run`s');
+```
+
 **What a resume PROMISES, and what it does not** — [ADR 0065](doc/decisions/0065-a-resume-replays-the-stored-stimuli-refuses-what-it-cannot-regenerate-and-re-dispatches-what-was-in-flight.md), `spec/run-state.md` section 9:
 
 - **It is AT-LEAST-ONCE, and your workers must tolerate running twice.** The resume REPLAYS the
-  stored settlements and resolutions through the routing that produced them, with every dispatch
-  held, and then hands every task still in flight to the new scheduler at the SAME task id. That set
+  stored settlements and resolutions through the routing that produced them — and the stored stops, pauses,
+  unpauses, earlier resumes and, since 0.8.0, attempts at their positions — with every dispatch
+  held, and then hands every task still in flight to the new scheduler at the SAME task id — or, for a checkpoint of a
+  PAUSED run, holds each until you unpause the resumed run (`RN-R21` v0.20, section 8). That set
   is what was in flight at the END of the replay — including a task that finished in the dead process
   whose settlement you had not stored yet, and a task the dying settlement dispatched after your last
   write, which the snippet shows the store never saw. The run records it: a `resumed` event naming
   those ids, and `state.resumes`.
-- **A re-run task gets a FRESH retry budget.** The log records a task's `attempts` only when it
-  SETTLES, so the attempts a task spent before the crash are recorded nowhere — measured: a task with
-  a budget of two attempts ran THREE times across one kill ([Q365](doc/questions/q365.md)).
+- **A re-run task KEEPS its retry budget** (since 0.8.0 — `RN-R40`,
+  [ADR 0113](doc/decisions/0113-a-tasks-attempts-are-recorded-and-carried-across-a-resume.md)). The run RECORDS each
+  attempt as it starts — one event, `{ kind: 'attempted', taskId, attemptNumber }`, each time the scheduler's
+  `task.running` number for a task of the run RISES (a requeue repeats its number and records nothing) — and the resume
+  hands each task it runs again to the new scheduler with **`attemptsSpent`, the highest number your store holds for it**:
+  the attempt in flight at the crash COUNTS as spent, and so does one a STOP interrupted. A task whose budget is already
+  spent is handed on all the same and runs ONCE more — the scheduler settles it; the library writes no settlement — and a
+  task with no attempt stored gets no key. So the record's `attempts` after a resume counts the attempts of EVERY
+  process, as the scheduler reports it. Two limits: a task whose attempts only the LOST TAIL saw starts fresh, and a
+  `createTask` that builds the task field by field must copy `attemptsSpent` (section 12). *Until 0.8.0 a re-run task got
+  a FRESH budget — a budget of two attempts ran THREE times across one kill ([Q365](doc/questions/q365.md)).*
 - **A task PARKED for a person is not in flight.** It stays parked, the resumed run is
-  `awaiting_action`, and `resolve()` on the RESUMED driver completes it (section 7).
+  `awaiting_action`, and `resolve()` on the RESUMED driver completes it (section 7). **So is an ASK**: the replay
+  re-enters it and REGENERATES its `asked` element — the same id and the same kept input, compared with what you stored
+  — handing nothing to the new scheduler; answer it on the resumed driver. **An ask parked in a MAP instance whose
+  successor reads `"$item"`** (section 3) has its instance's item REBUILT by the same replay — the map is re-entered from
+  the stored header and log, and nothing of the item is in your checkpoint — so the answer on the resumed driver reaches a
+  `pay` holding the same invoice the uninterrupted run's would have.
 - **The check sees only what you STORED.** The stored events must be a prefix of what the replay
   regenerates, and the first position where they are not is refused `diverged` — so a predicate or a
   flow you changed is caught where the stored run's road crosses it, and NOT where that road lies
@@ -3253,23 +4535,217 @@ await third.shutdown();
   ([Q372](doc/questions/q372.md)). Change a flow, change its `version`.
 - **The store is TRUSTED for what the resume feeds.** A stored settlement's result and a stored
   person's resolution are replayed as stored — nothing can check they are what the process saw
-  ([Q374](doc/questions/q374.md)). A store you do not trust is a store you should not resume from.
+  ([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
   header's run is not the driver's), `flow` (another flow id or `version` — there is no migration),
-  `stopped` and `diverged` — the last two with the `index` of the position. **A STOPPED run is not
-  resumable**: the refusal that stopped it would stop it again. A completed or `stuck` run resumes to
-  itself and dispatches nothing.
+  `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**
+  (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.
 - **A refused resume may SPEND its run id.** Refused by its header, nothing exists and the id is still
   free; refused during its replay, the runtime built a driver for it — so that runtime refuses the id
   with `RunIdInUse` from then on, as it refuses any id it ever built a driver for, a finished run's
   included, long after it released the driver (section 12). Resume on a fresh runtime
   ([Q371](doc/questions/q371.md)).
+- **A throw from your `onFoldInput` on the `resumed` element HALTS the resumed run** ([W184](doc/work-items/w184-a-consumer-callback-that-throws-on-every-road.md), `RN-R22`): it is
+  reported once, NOTHING of the in-flight set is handed to the new scheduler, and your own error is thrown at
+  `resume()`'s caller — so the stored run, `resumed` and `halted` are a checkpoint refused `halted`, and on a runtime the
+  run id is spent there. A throw on an element the replay regenerated in the LOST TAIL is refused
+  `ResumeRefused('halted')`, as above. *Until W184 it reached you with nothing handed on: `running` for ever.*
 - **`shutdown()` is not a kill.** It DRAINS: measured in node and deno, a run one settlement in
-  completes inside it, while a retry waiting on its backoff never runs. It waits while tasks are RUNNING
+  completes inside it, while a retry waiting on its backoff runs only if the backoff ends inside the
+  drain — the drain dispatches like any other moment, and a backoff still pending when it ends is
+  discarded (the current pin's `shutdown()` says so in its source; measured on the scheduler alone by
+  W157 and its conformity reader, in node: a 100 ms backoff beside a 500 ms running task ran its retry
+  in the drain, a 300 ms one with nothing else running did not; at 0.5.2 a retry could also start
+  before its backoff ended). It waits while tasks are RUNNING
   and for at most five seconds, so a run with longer work in flight, or only queued or blocked tasks, is
   left where the wait ended. A crash is what the snippet's
   `alive` flag stands for — the store stops, whatever the process was doing.
 
+### Stopping a run to resume it ELSEWHERE — `handle.stop`
+
+**`handle.stop({ actor, reason?, graceMs? })` — or `driver.stop(…)` on a driver you built — stops ONE run so that a
+resume on another runtime continues it** (`RN-R33`,
+[ADR 0105](doc/decisions/0105-a-run-its-owner-stops-goes-deaf-before-it-cancels-and-resumes-elsewhere.md)): an
+upgrade, a move, *stop them and continue*. In order: the run is HELD and the driver goes **DEAF**; ONE fold input, `{ kind: 'interrupted', actor,
+reason }`, is appended; and only then is each task IN FLIGHT cancelled. Because it hears nothing from the stop on, no `task.cancelled` of the stop is ever written — **the log ends with those tasks dispatched
+and unsettled, which is exactly what a resume runs again, at the same ids.** The run reads **`interrupted`** (section 8):
+terminal here, and the one terminal outcome a resume accepts.
+
+| | what happens |
+|---|---|
+| a task RUNNING, WAITING, in a BACKOFF or not yet picked up | each is cancelled, and its `task.cancelled` is NOT recorded — it stays in flight in the log |
+| a task PARKED at `user_action` | nothing is sent. **`resolve()` is refused on this runtime from the call on** — the person answers on the runtime that resumes the run |
+| an ASK waiting for a person (section 7) | the same: nothing is sent, and its answer is refused here. The runtime that resumes the run REGENERATES the ask — the same id, the same kept input — hands its scheduler nothing for it, and takes the answer. An answer given on the SAME step before the stop was called is taken first — its successor is handed to this runtime and cancelled at once, and the resume runs it again, so the answer is not lost (a same-step CANCEL instead drops a pending answer). Stopped while paused, it resumes paused ([W181](doc/work-items/w181-an-ask-under-run-control.md), `RN-R38`) |
+| a task HELD by a pause (section 8) | sent nothing — the scheduler never had it. It stays in flight in the log, and the checkpoint resumes **PAUSED**: every task in flight held until you unpause there |
+| `done` | settles with `interrupted` once the stop's CANCELS have resolved — not at the stop, so the old runtime's workers have stopped before you resume elsewhere. The run is released then; a sibling run on the same runtime is untouched |
+| the run id | still in use on THIS runtime (`RunIdInUse`) — resume on a FRESH one, which is what an upgrade is |
+| a call from your own callback, mid-step | accepted, and taken when the driver's step ends — so everything that step dispatched is in the log and runs again on resume |
+| a SECOND call | appends nothing, and forwards its `graceMs` to each task still stopping |
+| refused | `RunControlRefused` with `control: 'stop'`, by `reason`: `unsupported` (the scheduler has no `cancel`), `not-started`, `halted`, `cancelled` (a cancelled run is not resumable) and `ended` — nothing recorded or sent. And a `driver.cancel` AFTER a stop is refused `interrupted`: cancel it where it resumes |
+| a task that finished before its cancel arrived | runs AGAIN on the resume — its settlement was never heard. At-least-once, as across a crash |
+| a task's ATTEMPT that had started | COUNTED as spent, as a crash's is — its `attempted` event is in the log before `interrupted`, so the resume hands the task on with that number as `attemptsSpent`. A stop costs a task one RETRY, never its last run: a task out of retries still runs once (since 0.8.0, `RN-R40`) |
+| your `onFoldInput` THROWS on the `interrupted` element | every task in flight is still cancelled and every promise settles, in a `finally` — then the run is HALTED and reported once, and the throw reaches `stop()`'s caller (section 9, `RN-R33`). `halted` outranks `interrupted`: the run is NOT resumable, and `done` settles `halted` at once. *Until [W184](doc/work-items/w184-a-consumer-callback-that-throws-on-every-road.md) a stop at rest so thrown stayed `interrupted`, resumable* |
+
+```ts run
+import { Driver, fold, liveToken, resumeRefusal, type FlowDefinition } from 'fyflow-orchestration';
+
+const flow: FlowDefinition = {
+  flowId: 'stop-run', version: 1, entry: 'split',
+  nodes: [
+    { id: 'split',   kind: 'fanout', branches: ['a', 'b', 'review'] },
+    { id: 'a',       kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'b',       kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'review',  kind: 'task', type: 'T', edges: [{ to: 'collect' }] },
+    { id: 'collect', kind: 'join', of: 'split', edges: [{ to: 'done' }] },
+    { id: 'done',    kind: 'end', outcome: 'completed' },
+  ],
+};
+
+// A fake scheduler with the scheduler's own `cancel`: the stopped worker fires `task.cancelled`, then cancel() resolves.
+function fakeScheduler() {
+  const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+  const added: string[] = [];
+  const stopping = new Map<string, (stopped: boolean) => void>();
+  const fire = (type: string, detail: unknown) => { for (const fn of listeners.get(type) ?? []) fn({ detail }); };
+  const settle = (id: string, state: 'done' | 'user_action') => {
+    if (state === 'done') fire('task.completed', { id, state, result: { ok: true } });
+    else { fire('task.failed', { id, state, error: 'a person must look' }); fire('task.user_action', { id, state }); }
+  };
+  return {
+    added, settle,
+    stops: (id: string) => { fire('task.cancelled', { id, state: 'cancelled' }); stopping.get(id)?.(true); },
+    addTask(task: unknown) { added.push((task as { id: string }).id); },
+    addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+    cancel(id: string) { return new Promise<boolean>((resolve) => { stopping.set(id, resolve); }); },
+  };
+}
+const options = {
+  runId: 'run-1', createTask: (c: unknown) => c, predicates: new Map(),
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { T: { worker: 'w' } }, joinPolicy: liveToken,
+};
+
+// RUNTIME A: a and b running, review parked on a person.
+const oldScheduler = fakeScheduler();
+const driver = new Driver(flow, { ...options, scheduler: oldScheduler });
+driver.start({});
+oldScheduler.settle('run-1:review:2:0', 'user_action');
+
+const stopped = driver.stop({ actor: 'ops', reason: 'upgrade' });
+console.log(fold(driver.foldInputs()).outcome);   // interrupted
+if (fold(driver.foldInputs()).outcome !== 'interrupted') throw new Error('a stopped run reads `interrupted`');
+if (driver.resolve('run-1:review:2:0', 'done', { actor: 'ana', result: null })) throw new Error('resolve() is refused here');
+
+// The workers stop. Their `task.cancelled` reaches a DEAF driver: the element is still the last thing in the log.
+oldScheduler.stops('run-1:a:0:0');
+oldScheduler.stops('run-1:b:1:0');
+await stopped;
+if (driver.foldInputs().at(-1)?.kind !== 'interrupted') throw new Error('no task.cancelled of a stop is recorded');
+
+// RUNTIME B: a fresh driver, resumed from the stored checkpoint.
+const checkpoint = structuredClone(driver.checkpoint());
+if (resumeRefusal(flow, checkpoint) !== null) throw new Error('a stopped run is resumable');
+const newScheduler = fakeScheduler();
+const resumed = new Driver(flow, { ...options, scheduler: newScheduler });
+resumed.resume(checkpoint);
+console.log(newScheduler.added);   // [ 'run-1:a:0:0', 'run-1:b:1:0' ] — exactly what was in flight, at the same ids
+if (newScheduler.added.join() !== 'run-1:a:0:0,run-1:b:1:0') throw new Error('the in-flight set runs again');
+// The person answers HERE, and the run completes.
+if (!resumed.resolve('run-1:review:2:0', 'done', { actor: 'ana', result: { ok: true } })) throw new Error('resolved on B');
+newScheduler.settle('run-1:a:0:0', 'done');
+newScheduler.settle('run-1:b:1:0', 'done');
+const state = fold(resumed.foldInputs());
+console.log(state.outcome, state.interruption);   // completed null
+if (state.outcome !== 'completed' || state.interruption !== null) throw new Error('the resume ended the stop, and the run completed');
+```
+
+On a runtime you call `handle.stop(…)` and wait for `handle.done`, which settles `interrupted` once the workers have
+stopped; then you resume the checkpoint on a fresh runtime, as the snippet above does after a crash.
+
+**BREAKING in 0.8.0** (P34 decision 10): `RunOutcome` gains `'interrupted'` and `FoldInput` the kind `'interrupted'`,
+so an exhaustive `switch` over either no longer compiles; `RunState` gains the cell `interruption` (`null` unless the
+run is stopped NOW — a `resumed` event ends it), which a `RunState` literal must carry; `RunControlRefused.control` gains
+`'stop'` and its `reason` `'interrupted'`; and `RunHandle` gains `stop`, which breaks only code that builds a handle.
+
+### What a run records of each ATTEMPT — and what a resume hands on
+
+**Each attempt a task STARTS is one event in the run, and a resume hands the count on** (`RN-R40`,
+[ADR 0113](doc/decisions/0113-a-tasks-attempts-are-recorded-and-carried-across-a-resume.md), since 0.8.0). The driver
+hears the scheduler's `task.running` and appends `{ kind: 'attempted', taskId, attemptNumber }` — the scheduler's
+1-based number — for a task of its run, each time that number RISES: a requeue (a worker died under the task, and the
+pool ran it again) repeats its number and records nothing. Every task, with a `retryPolicy` or without. It is a FOLD
+INPUT, never a log record, and it moves no outcome and no state — only its task's `attemptNumber` on the `nodes` entry
+(section 8, since W187). What it changes besides is what a resume does: each task it runs again is handed on with
+`attemptsSpent`, the highest number your store holds for it.
+
+| | what happens |
+|---|---|
+| an inline pool starts the task INSIDE the driver's `addTask` | the event is appended when the driver's step ENDS — after everything that step recorded, before a pause or a stop called on it — so it always sits between two steps, where a resume can feed it |
+| an id of another run, an id no driver minted, a task the run never dispatched, a detail with no attempt number | nothing recorded and nothing reported — an attempt never stops a run |
+| a stopped driver (section 18's stop) | records nothing more: the attempt running at the stop is in the log, one after it is not |
+| your `onFoldInput` THROWS on the event | section 9's rule: the run halted, reported once, and on your own call's step thrown to you |
+
+```ts run
+import { Driver, fold, liveToken, type FlowDefinition } from 'fyflow-orchestration';
+
+const flow: FlowDefinition = {
+  flowId: 'attempts', version: 1, entry: 'fetch',
+  nodes: [
+    { id: 'fetch', kind: 'task', type: 'T', retryPolicy: { maxRetries: 2, backoffMs: 1000 }, edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+// A fake scheduler: it records what it is handed, and a test says when an attempt STARTS — the scheduler's
+// `task.running`, with its 1-based `attemptNumber`.
+function fakeScheduler() {
+  const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+  const added: Record<string, unknown>[] = [];
+  return {
+    added,
+    starts: (id: string, attemptNumber: number) => {
+      for (const fn of listeners.get('task.running') ?? []) fn({ detail: { id, state: 'running', attemptNumber } });
+    },
+    addTask(task: unknown) { added.push(task as Record<string, unknown>); },
+    addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+  };
+}
+const options = {
+  runId: 'run-1', createTask: (c: unknown) => c, predicates: new Map(),
+  workers: { w: { url: 'worker.js' } }, nodeTypes: { T: { worker: 'w' } }, joinPolicy: liveToken,
+};
+
+// PROCESS ONE: `fetch` fails its first attempt and starts its second — and then the process dies.
+const first = fakeScheduler();
+const driver = new Driver(flow, { ...options, scheduler: first });
+driver.start({});
+first.starts('run-1:fetch:-:0', 1);
+first.starts('run-1:fetch:-:0', 2);
+first.starts('run-1:fetch:-:0', 2);   // a worker died under it and the pool REQUEUED it: the same number, nothing recorded
+const attempts = driver.foldInputs().filter((e) => e.kind === 'attempted');
+console.log(attempts.length);   // 2 — one per attempt STARTED
+if (attempts.length !== 2) throw new Error('one event per attempt started, and none for the requeue');
+if (driver.snapshot().length !== 0) throw new Error('an attempt is a fold input, never a log record');
+if (fold(driver.foldInputs()).outcome !== 'running') throw new Error('and it moves no outcome');
+if (fold(driver.foldInputs()).nodes['run-1:fetch:-:0']!.attemptNumber !== 2) throw new Error('only the entry`s attemptNumber (section 8)');
+
+// PROCESS TWO: resumed from the stored events — `fetch` is handed on with the two attempts it SPENT.
+const second = fakeScheduler();
+new Driver(flow, { ...options, scheduler: second }).resume(structuredClone(driver.checkpoint()));
+console.log(second.added[0]?.attemptsSpent);   // 2 — the scheduler runs it as attempt 3, its LAST, not as attempt 1
+if (second.added[0]?.attemptsSpent !== 2) throw new Error('the retry budget survives the crash');
+```
+
+**BREAKING in 0.8.0** (P36 (p)): `FoldInput` gains the kind `'attempted'`, so an exhaustive `switch` over `kind` no
+longer compiles; a run on a real scheduler appends one more event per attempt started, so your store grows by about one
+event per task; and a resumed task is handed on with `attemptsSpent`, so its retries are not reset and the record's
+`attempts` counts every process's. Additive: `TaskFactory`'s config gains the optional `attemptsSpent` — which a
+`createTask` building the task field by field must copy (section 12).
+
 **`0.5.0` is BREAKING for a consumer of the fold, in two ways.** `FoldInput` has a new kind,
 `resumed`, so a `switch` that is exhaustive over `kind` no longer compiles, and `RunState` has a new
 cell, `resumes`, so a `RunState` you construct needs it. A run nobody resumes carries no `resumed`
@@ -3292,7 +4768,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 |
+| **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) |
 | **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 |
@@ -3303,6 +4779,7 @@ rest, while every file gets a thumbnail* — had nowhere to keep that memory.
 ```ts run
 import { createRuntime } from 'fyflow-orchestration/scheduler';
 import type { FlowDefinition, GateType, RegistryDocument } from 'fyflow-orchestration';
+import { validateDefinition } from 'fyflow-orchestration';
 
 const registry: RegistryDocument = {
   workers: {
@@ -3351,7 +4828,7 @@ const flow: FlowDefinition = {
 
 const files = ['Dark.S01E01.mkv', 'Lost.S01E01.mkv', 'Dark.S01E02.mkv', 'trailer.mkv', 'Lost.S01E02.mkv']
   .map((name) => ({ name, sizeMB: 1 }));
-const runtime = createRuntime(registry, {}, { base: import.meta.url, flows: [flow] });
+const runtime = createRuntime(registry, {}, { base: import.meta.url });
 const state = await runtime.start(flow, { files }).done;
 await runtime.shutdown();
 
@@ -3404,14 +4881,41 @@ const filter: FlowDefinition = {
     { id: 'done', kind: 'end', outcome: 'completed' },
   ],
 };
-const second = createRuntime(registry, { gateTypes: { sloppy } }, { base: import.meta.url, flows: [filter] });
+const second = createRuntime(registry, { gateTypes: { sloppy } }, { base: import.meta.url });
 const kinds: string[] = [];
-const stopped = await second.start(filter, { name: 'Dark.S01E01.mkv', sizeMB: 1 }, { onRunFailure: (f) => kinds.push(f.kind) }).done;
+const halted = await second.start(filter, { name: 'Dark.S01E01.mkv', sizeMB: 1 }, { onRunFailure: (f) => kinds.push(f.kind) }).done;
 await second.shutdown();
-console.log(stopped.outcome, kinds);                            // stopped [ 'UndeclaredRoute' ]
-if (stopped.outcome !== 'stopped' || kinds.join() !== 'UndeclaredRoute' || stopped.gated.length !== 0) {
-  throw new Error(`an undeclared route stops the run by name, recording nothing: ${stopped.outcome} ${kinds.join()}`);
+console.log(halted.outcome, kinds);                             // halted [ 'UndeclaredRoute' ]
+if (halted.outcome !== 'halted' || kinds.join() !== 'UndeclaredRoute' || halted.gated.length !== 0) {
+  throw new Error(`an undeclared route halts the run by name, recording nothing: ${halted.outcome} ${kinds.join()}`);
 }
+
+// A type whose routes are its GATE's — v0.30, ADR 0092. `routesFor` IN PLACE of `routes` and `defaultRoute`: each
+// gate's routes come from its OWN settings, so FD-V41 counts each gate against its own — a case left unwired is
+// refused at load naming the case. `settingsProblem` says what a settingsSchema cannot (FD-V40).
+const byCase: GateType = {
+  settingsProblem: (s) => (Array.isArray(s.cases) && s.cases.every((c) => typeof c === 'string') ? null : 'cases is a list of route names'),
+  routesFor: (s) => ({ routes: [...(s.cases as string[]), 'other'], defaultRoute: 'other' }),
+  fn: (ctx) => (typeof ctx.key === 'string' && (ctx.settings.cases as string[]).includes(ctx.key) ? ctx.key : 'other'),
+};
+const sorter = (edges: { to: string; route?: string }[]): FlowDefinition => ({
+  flowId: 'sorter', version: 1, entry: 'sort',
+  nodes: [
+    { id: 'sort', kind: 'gate', type: 'byCase', settings: { key: 'kind', cases: ['video', 'audio'] }, edges },
+    { id: 'kept', kind: 'end', outcome: 'kept' },
+    { id: 'rest', kind: 'end', outcome: 'rest' },
+  ],
+});
+const withByCase = { predicates: [], gateTypes: { byCase } };
+const wired = validateDefinition(sorter([{ route: 'video', to: 'kept' }, { route: 'audio', to: 'kept' }, { to: 'rest' }]), withByCase);
+if (wired.length !== 0) throw new Error(`every case wired, and the default by an edge with no route: ${JSON.stringify(wired)}`);
+const forgot = validateDefinition(sorter([{ route: 'video', to: 'kept' }, { to: 'rest' }]), withByCase);
+console.log(forgot.map((f) => `${f.rule} ${f.at}`));        // [ 'FD-V41 sort' ]
+if (forgot.length !== 1 || forgot[0]!.rule !== 'FD-V41' || !forgot[0]!.detail.includes('"audio"')) {
+  throw new Error(`the unwired case is refused at load, by name: ${JSON.stringify(forgot)}`);
+}
+const malformed = validateDefinition({ ...sorter([{ to: 'rest' }]), nodes: [{ id: 'sort', kind: 'gate', type: 'byCase', settings: { cases: [1] }, edges: [{ to: 'rest' }] }, { id: 'rest', kind: 'end', outcome: 'rest' }] }, withByCase);
+if (malformed.map((f) => f.rule).join() !== 'FD-V40') throw new Error(`settingsProblem's message is FD-V40: ${JSON.stringify(malformed)}`);
 ```
 
 **What the snippet cannot show, and you need:**
@@ -3436,11 +4940,106 @@ if (stopped.outcome !== 'stopped' || kinds.join() !== 'UndeclaredRoute' || stopp
   route is what arrived with `required` added along the gate's key path, at every step. So a worker after `first`
   that REQUIRES the key `fits`. *It read `no` there until v0.25, which is [Q391](doc/questions/q391.md) and is
   [ADR 0068](doc/decisions/0068-a-route-guarantees-what-its-type-declares-and-the-library-derives-it-from-the-key-path.md).*
+- **A type's routes may come from its GATE — v0.30.** A gate type declares `routes` and `defaultRoute`
+  (`keyResolvedRoutes` beside them) as `distinct` does, OR `routesFor(settings)` returning
+  `{ routes, defaultRoute, keyResolvedRoutes? }` for one gate — exactly one of the two; both or neither is
+  `GateTypeRefused`. `GateType` is `StaticGateType | DerivedGateType`, so code that READS `type.routes` off a
+  `GateType` gets `readonly string[] | undefined`: ask `routesOf(type, settings)`, which returns the gate's set or
+  a `{ problem }` and never throws. `routesFor` is asked once per gate at load, after its settings passed, and
+  once per gate by each driver — keep it the pure function of its settings `fn` is of its context. A throw or a
+  malformed set is `FD-V39` at that gate; a message from `settingsProblem` is `FD-V40`
+  ([ADR 0092](doc/decisions/0092-a-gate-types-routes-are-declared-statically-or-derived-from-its-node.md)).
 - **A route that guarantees something else guarantees nothing a check can use.** A type declaring no
   `keyResolvedRoutes`, a gate naming no `key`, and a route the type does not name each pass the value through
   exactly as before — and the guarantee is PRESENCE along the path, never the leaf's TYPE, which is the type's own
   judgement (`distinct` wants a string or a finite number, and no static tool derives that).
 
+### Routing with NO code — the built-in `if` and `switch`
+
+**A gate need not remember anything.** Since `spec/flow-definition.md` v0.31
+([P32](doc/plans/p32-what-a-gate-may-decide-without-memory.md), [W154](doc/work-items/w154-the-built-in-if-and-switch.md))
+two more types are built in, and they route the value that reached the gate by its SETTINGS alone — so a flow can
+route its ENTRY payload, or the value straight after a gate, with no worker before the decision and nothing
+registered:
+
+| | `if` | `switch` |
+|---|---|---|
+| **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 |
+| **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
+  `distinct` sends the second to `duplicate`.
+- **`input` is an `if`'s root and nobody else's.** A task's edge still roots at `outcome` and `needs`; `input.x`
+  there is `FD-V43`.
+- **`switch`'s cases are key-resolved routes** (ADR 0068), so `checkWiring` refines what leaves on a case along
+  the key, as it does for `distinct`'s `first`. **An `if` guarantees nothing**: a task after `then` that requires
+  the key the condition compared reads `no` against a producer that does not REQUIRE it.
+- **Neither has a named export** — `if` and `switch` are words a `const` cannot carry. Reach them as a flow does,
+  by name: `BUILT_IN_GATE_TYPES.if`, `BUILT_IN_GATE_TYPES.switch`. A type of your own may not take either name
+  (`NameCollision`).
+
+```ts run
+import { Driver, fold, liveToken, validateDefinition, type FlowDefinition } from 'fyflow-orchestration';
+
+// The ENTRY is an `if` over the payload; `classify` runs only on the escalated road, and a `switch` routes its
+// result. No predicate and no gate type is registered anywhere below.
+const flow: FlowDefinition = {
+  flowId: 'triage', version: 1, entry: 'triage',
+  nodes: [
+    { id: 'triage', kind: 'gate', type: 'if', settings: { when: { path: 'input.priority', op: 'gte', value: 5 } },
+      edges: [{ route: 'then', to: 'classify' }, { to: 'queue' }] },                       // no route: else, the default
+    { id: 'classify', kind: 'task', type: 'Work', edges: [{ to: 'byStatus' }] },
+    { id: 'byStatus', kind: 'gate', type: 'switch',
+      settings: { key: 'status', cases: { approved: 'approved', rework: ['rejected', 'needs-changes'] } },
+      edges: [{ route: 'approved', to: 'publish' }, { route: 'rework', to: 'revise' }, { to: 'review' }] },
+    { id: 'queue', kind: 'task', type: 'Work', edges: [{ to: 'done' }] },
+    { id: 'publish', kind: 'task', type: 'Work', edges: [{ to: 'done' }] },
+    { id: 'revise', kind: 'task', type: 'Work', edges: [{ to: 'done' }] },
+    { id: 'review', kind: 'task', type: 'Work', edges: [{ to: 'done' }] },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+
+// One run per payload, on the twelve-line fake scheduler section 12 explains.
+function run(payload: unknown, classified?: unknown): string[] {
+  const listeners = new Map<string, ((e: { detail: unknown }) => void)[]>();
+  const added: string[] = [];
+  const failures: string[] = [];
+  const scheduler = {
+    addTask(task: unknown) { added.push((task as { id: string }).id); },
+    addEventListener(type: string, fn: (e: { detail: unknown }) => void) { listeners.set(type, [...(listeners.get(type) ?? []), fn]); },
+  };
+  const driver = new Driver(flow, {
+    runId: 'r', scheduler, createTask: (c) => c, predicates: new Map(), joinPolicy: liveToken,
+    workers: { w: { url: 'worker.js' } }, nodeTypes: { Work: { worker: 'w' } },
+    onRunFailure: (f) => { failures.push(f.kind); },
+  });
+  driver.start(payload);
+  if (classified !== undefined) for (const fn of listeners.get('task.completed') ?? []) fn({ detail: { id: 'r:classify:-:0', state: 'done', result: classified } });
+  if (failures.length) throw new Error(`the run reported ${failures.join(', ')}`);
+  const gated = fold(driver.foldInputs()).gated.map((d) => `${d.gateId}:${d.route}`);
+  return [...gated, ...added.map((id) => id.split(':')[1]!)];
+}
+
+console.log(run({ priority: 2 }));                                       // [ 'triage:else', 'queue' ]
+console.log(run({ priority: 7 }, { status: 'needs-changes' }));          // [ 'triage:then', 'byStatus:rework', 'classify', 'revise' ]
+if (run({ priority: 2 }).join() !== 'triage:else,queue') throw new Error('priority 2 is below 5: else');
+if (run({ priority: '9' }).join() !== 'triage:else,queue') throw new Error('"9" is not a number: no coercion, so else');
+if (run({ priority: 7 }, { status: 'approved' }).join() !== 'triage:then,byStatus:approved,classify,publish') throw new Error('approved');
+if (run({ priority: 7 }, { status: 'needs-changes' }).join() !== 'triage:then,byStatus:rework,classify,revise') throw new Error('a value in an array case');
+if (run({ priority: 7 }, { status: 'pending' }).join() !== 'triage:then,byStatus:default,classify,review') throw new Error('no case: default');
+
+// A case left unwired is refused at LOAD, naming it — the forgotten case an edge chain of comparisons cannot catch.
+// (`revise` goes too, or it is unreachable and FD-V11 says so beside it.)
+const forgot = { ...flow, nodes: flow.nodes.filter((n) => n.id !== 'revise')
+  .map((n) => (n.id === 'byStatus' ? { ...n, edges: [{ route: 'approved', to: 'publish' }, { to: 'review' }] } : n)) } as FlowDefinition;
+const found = validateDefinition(forgot, { predicates: [], workers: { w: { url: 'worker.js' } }, nodeTypes: { Work: { worker: 'w' } } });
+console.log(found.map((f) => `${f.rule} ${f.at}`));                     // [ 'FD-V41 byStatus' ]
+if (found.length !== 1 || found[0]!.rule !== 'FD-V41' || !found[0]!.detail.includes('"rework"')) throw new Error(`the unwired case, by name: ${JSON.stringify(found)}`);
+```
+
 **`0.6.0` is BREAKING in four ways, all of them for code that enumerates or matches.** `FlowNode` has a SIXTH kind,
 `GateNode` ([Q381](doc/questions/q381.md)), so a `switch` exhaustive over `node.kind` no longer compiles;
 `FoldInput` has a new kind, `gated`, so one exhaustive over `input.kind` no longer compiles either; `RunState` has a
@@ -3751,7 +5350,8 @@ reported rather than hidden. And a declared predicate's PATH is checked against
 a path naming a key the producer cannot emit answers *no match* for ever (ADR 0074 consequence 6).
 
 > **A `Transform` node's realm and its groups are the scheduler's default and nothing else.** The
-> built-in declares no `inline`, no `groups` and no `pool`, and a named pool instance carries only
-> `type` and `config` — so of the four things ADR 0075 rule 3 lists, a named instance reaches
-> `config`, a `retryPolicy` goes on the NODE, and `inline` and `groups` are reachable by no road a
-> consumer can write ([Q457](doc/questions/q457.md)). Measured at W110.
+> built-in declares no `inline`, no `groups` and no `pool`, and a named pool instance carries `type`,
+> `config` and — since v0.37 ([ADR 0099](doc/decisions/0099-a-named-instance-of-a-document-type-may-declare-its-own-pool-options.md)) — `pool`; so of the four things ADR 0075 rule 3
+> lists, a named instance reaches `config` and `pool` (its options, `residentGroups` included: a transform-only pool
+> CAN now hold a resident group, [Q626](doc/questions/q626.md)), a `retryPolicy` goes on the NODE, and `inline` and
+> `groups` are reachable by no road a consumer can write ([Q457](doc/questions/q457.md)). Measured at W110 and W165.