fyflow-orchestration 0.10.0 → 0.11.0

package/AGENTS.md

@@ -347,6 +347,7 @@ that object and nothing else — there is no wrapper and no reserved key.
 | `"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* |
+| **`!error` after the node id, on any of those** — `"someNode!error"`, `["someNode!error?"]`, … | that node's **ERROR** instead of its result: the string its failure was reduced to, `null` where it succeeded (since 0.11.0, below) |
 
 **What a reference hands you is ONE shared, frozen copy — read it, never write it** — from 0.10.0 ([ADR 0126](doc/decisions/0126-a-references-value-is-one-frozen-copy-shared-by-every-reader.md),
 `spec/flow-definition.md` v0.47). The value under a `"someNode"` or `["someNode"]` key (either with `?`) is ONE deep copy
@@ -691,6 +692,83 @@ 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}`);
 ```
 
+### `"someNode!error"` — what FAILED, from the nodes after it
+
+**`"lookup!error"` names node `lookup`'s ERROR** — the outcome's `error`, the string the scheduler reduced the failure to
+(section 6) — where `"lookup"` names its result (`spec/flow-definition.md` v0.49,
+[ADR 0131](doc/decisions/0131-a-reference-may-name-a-nodes-error.md), since 0.11.0). A failed task's result is `null`, so
+until it a node after a failure edge — an ask asking a person *what now?* above all — could not say what failed.
+
+| | |
+|---|---|
+| what it is | the effective outcome's `error`: the record's, or a RESOLUTION's where a person resolved the node (`resolve(id, 'failed', { error })` on a parked task, a declined ask; `'resolved as failed'` where they gave none). **`null` where the output SUCCEEDED** — the key is present, holding `null` |
+| its forms | the plain reference's four: `"lookup!error"`, `"lookup!error?"`, `["lookup!error"]`, `["lookup!error?"]` — the `?` goes LAST. It names the same node's same outputs as `"lookup"`, so `FD-V27`-`FD-V29` and the `?` and array rules are the plain form's, and the fixes `FD-V28` and `FD-V29` name keep the `!error` (`FD-V27` names the node, as for `"lookup"`) |
+| where it is legal | wherever `"lookup"` is: a `task`'s, a `map`'s or an `ask`'s `needs`, and an edge's (`ctx.needs`, section 4) |
+| what it is NOT | a path: the error is a field of the OUTCOME beside `result`, and `error` is the one part a reference may name. `"lookup?!error"`, `"!error"` and `"lookup!err"` are `FD-V26`, each naming its fix |
+| what it costs | nothing to copy — a string or `null`, never the shared frozen copy of the result (above) |
+| in the wiring check | the key composes as `{ type: ['string', 'null'] }` with the sample `''`, whatever the producer declares (section 15) |
+| `referenceTarget` | the error form parses to the plain form's object plus `part: 'error'`, present ONLY there (`AimedReference`), so every other spelling parses as before. A resolver of your own must read `part`; an aiming rule may ignore it |
+
+**The default — a failure edge handing `{ error }` to its successor — was declined** (P43 (c2)): it would change what every
+existing failure edge's successor receives. You name the error where you want it.
+
+The app's case — `lookup` fails, an ask after its failure edge shows the person why, and the node both roads reach reads
+the error beside the result:
+
+```ts run
+import { Driver, fold, liveToken, validateDefinition, type FlowDefinition } from 'fyflow-orchestration';
+
+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 handedInput = (id: string) => added.find((t) => t.id === id)?.payload.input;
+const fire = (type: string, detail: unknown) => { for (const fn of listeners.get(type) ?? []) fn({ detail }); };
+
+const flow: FlowDefinition = {
+  flowId: 'lookup-or-ask', version: 1, entry: 'lookup',
+  nodes: [
+    // `optional`, so a failure SETTLES failed and routes the failure edge (a non-optional task would park, section 7).
+    { id: 'lookup', kind: 'task', type: 'Work', optional: true, edges: [{ on: ['failed'], to: 'resolve' }, { to: 'publish' }] },
+    { id: 'resolve', kind: 'ask', needs: { why: 'lookup!error' },
+      answerSchema: { type: 'object', required: ['value'], properties: { value: { type: 'string' } } },
+      edges: [{ on: ['failed'], to: 'skipped' }, { to: 'publish' }] },
+    { id: 'publish', kind: 'task', type: 'Work', needs: { found: 'lookup', why: 'lookup!error', given: 'resolve?' }, edges: [{ to: 'done' }] },
+    { id: 'skipped', kind: 'end', outcome: 'skipped' },
+    { id: 'done', kind: 'end', outcome: 'completed' },
+  ],
+};
+const types = { workers: { w: { url: 'worker.js' } }, nodeTypes: { Work: { worker: 'w' } } };
+const registry = { predicates: [], ...types };
+if (validateDefinition(flow, registry).length) throw new Error('"lookup!error" is legal on an ask and on a task');
+
+const driver = new Driver(flow, { runId: 'r1', scheduler, createTask: (c) => c, predicates: new Map(), joinPolicy: liveToken, ...types });
+driver.start({ invoice: 'INV-?' });
+fire('task.failed', { id: 'r1:lookup:-:0', state: 'failed', result: null, error: 'lookup timed out after 30 s' });
+
+// The ask parks with the error: what it shows the person.
+const asked = driver.foldInputs().find((e) => e.kind === 'asked');
+console.log(asked?.kind === 'asked' && asked.input);   // { why: 'lookup timed out after 30 s' }
+if (JSON.stringify(asked?.kind === 'asked' && asked.input) !== '{"why":"lookup timed out after 30 s"}') throw new Error('the ask is handed the error');
+
+driver.resolve('r1:resolve:-:0', 'done', { result: { value: 'INV-9' }, actor: 'ana' });
+console.log(handedInput('r1:publish:-:0'));   // { found: null, why: 'lookup timed out after 30 s', given: { value: 'INV-9' } }
+if (JSON.stringify(handedInput('r1:publish:-:0')) !== '{"found":null,"why":"lookup timed out after 30 s","given":{"value":"INV-9"}}') {
+  throw new Error(`publish received ${JSON.stringify(handedInput('r1:publish:-:0'))}`);
+}
+if (fold(driver.foldInputs()).outcome !== 'running') throw new Error('publish is in flight');
+
+// A part other than `error`, or the `?` in the wrong place, is refused naming the fix.
+const refuse = (ref: unknown) => validateDefinition({ ...flow, nodes: flow.nodes.map((n) =>
+  (n.id === 'publish' ? { ...n, needs: { why: ref } } : n)) } as FlowDefinition, registry).map((f) => `${f.rule}: ${f.detail}`);
+for (const [ref, fix] of [['lookup!err', 'write "lookup!error"'], ['lookup?!error', 'write "lookup!error?"']] as const) {
+  const [finding] = refuse(ref);
+  if (!finding?.startsWith('FD-V26') || !finding.includes(fix)) throw new Error(`${ref}: ${finding}`);
+}
+```
+
 ### Validation happens at construction, not at routing time
 
 `new Driver(...)` validates the whole definition before anything is queued. A typo cannot become a
@@ -724,6 +802,82 @@ It would have said *every path from a branch entry reaches the join* — which w
 that routes a branch away from its join invalid input, and that case is the one this library exists
 to get right (`ADR 0003`). Do not add it.
 
+### The definition's SHAPE, as data — `definitionSchema()` and `definitionSchema(registry)`
+
+**`definitionSchema()` returns everything above as a JSON Schema, draft 2020-12** (`spec/flow-definition.md` v0.50,
+[ADR 0132](doc/decisions/0132-a-definitions-shape-is-a-schema-built-from-the-validator.md), since 0.11.0): every node kind
+and its keys, which are required, the edges of each kind, the three `when` shapes, the `needs` grammar (`"lookup!error"`
+included), a `retryPolicy`, a `transform` and an `answerSchema` — each key with a `description`. Hand it to any 2020-12
+validator, or to an agent writing a flow, BEFORE the findings. It is BUILT from the validator's own key sets, so its
+keys cannot drift from them (the reference tokens and the operator partition are written beside them and held to the
+validator by its tests); it is a new plain object on every call, yours to change. A join's `of` and a fanout's branch
+entries are held to the id charset only where they are strings — the validator does no more today
+([Q774](doc/questions/q774.md)).
+
+| | |
+|---|---|
+| it refuses | what a node, an edge or a value gets wrong in its OWN shape: an undeclared or missing key, a wrong type, an id outside `[A-Za-z0-9_-]{1,64}`, an unknown kind, a malformed reference, `when`, `retryPolicy` or `transform`, a task's key on an ask, an `answerSchema` outside the subset |
+| it does not | anything that needs ANOTHER node or the REGISTRY — whether `to` names a node, reachability, regions and joins, where a reference points, every registered name (types, pools, groups, languages, predicates, gate types and their routes) — the last is what `definitionSchema(registry)` adds, below |
+| the authority | **`validateDefinition(flow, registry)`**, or `runtime.check(flow)` on a runtime — for all of that and for the whole. What the schema refuses, `validateDefinition` refuses under every registry; a document it accepts may still be refused there. The root `description` says so |
+| not | a check the library runs (nothing evaluates it), nor in [ADR 0053](doc/decisions/0053-the-schema-validator-is-a-built-in-subset-and-a-keyword-outside-it-is-refused.md)'s subset — it uses `$defs`, `$ref`, `oneOf`, `if`/`then`, `pattern` |
+
+**`definitionSchema(registry)` is the same shape SPECIALISED to the `Registry` you validate against** (`spec/flow-definition.md`
+v0.51, since 0.11.0) — what an agent most often gets wrong, as data: a task's `type` is one of your node types, and per
+type (an `if`/`then`) its `pool`, its `settings` against its worker's `settingsSchema`, and a `transform` where the type only
+transforms; `workerGroups`, `transform.lang` and a predicate name from your sets; a gate's `type`, and per gate type its
+`settings` and — for a static type — its edges' `route` names. A registry `checkRegistry` refuses (what `new Driver` would
+refuse) is never specialised: the call throws that refusal. What it refuses, `validateDefinition(flow, registry)` refuses.
+
+| | |
+|---|---|
+| it cannot cleanly carry | the `settings` check over the EFFECTIVE settings (your type's defaults merged under the node's): a key the defaults supply is not required of the node, and a default's own value — and a top-level keyword of your settingsSchema other than `properties`, `required` and `additionalProperties` — is not checked; a `minLength` above 1 inside one of your schemas, emitted as half of it rounded up (your schemas count UTF-16 units, JSON Schema counts code points); a DERIVED gate type's routes (`switch`'s are its cases); every route wired EXACTLY ONCE; a gate type's `settingsProblem` and a language's `compile` |
+| annotation only | each node type's worker `inputSchema` — at `$defs.inputSchema` in its type's branch, constraining nothing (it is runtime input) |
+| the authority | as above, against that registry. The root `description` names every row of this table |
+| mind | a validator that tests a property with `in` (`@cfworker/json-schema` 4.1.1 does) misreads a schema property of yours NAMED as an `Object.prototype` member — `constructor`, `toString`, `__proto__` — and refuses or throws where 2020-12 accepts; name your settings otherwise |
+
+```ts run
+import { definitionSchema, validateDefinition, type FlowDefinition } from 'fyflow-orchestration';
+
+const schema = definitionSchema();
+console.log(schema.$schema);   // https://json-schema.org/draft/2020-12/schema
+if (schema.$schema !== 'https://json-schema.org/draft/2020-12/schema') throw new Error('a 2020-12 document');
+if (!String(schema.description).includes('validateDefinition')) throw new Error('it names the authority for the rest');
+
+type Def = { properties: Record<string, { description?: string }>; required: string[]; additionalProperties: boolean };
+const defs = schema.$defs as Record<string, Def> & { reference: { anyOf: { pattern?: string }[] } };
+console.log(defs.askNode.required);   // [ 'id', 'kind', 'edges' ]
+if (defs.askNode.additionalProperties !== false || 'type' in defs.askNode.properties) throw new Error('an ask declares no type');
+if (!defs.taskNode.properties.retryPolicy?.description) throw new Error('every key is described');
+
+// The reference grammar, as a pattern any validator can apply — the error form accepted, a misplaced "?" not.
+const reference = new RegExp(defs.reference.anyOf[0]!.pattern!);
+if (!reference.test('lookup!error?') || reference.test('lookup?!error')) throw new Error('the "!error" grammar');
+
+// A shape the schema accepts can still be refused: an edge to a node that does not exist is the VALIDATOR's.
+const dangling = { flowId: 'f', version: 1, entry: 'a', nodes: [{ id: 'a', kind: 'task', type: 'Work', edges: [{ to: 'ghost' }] }] } as FlowDefinition;
+const rules = validateDefinition(dangling, { predicates: [], workers: { w: { url: 'worker.js' } }, nodeTypes: { Work: { worker: 'w' } } }).map((f) => f.rule);
+if (rules.join() !== 'FD-V2') throw new Error(`the graph is validateDefinition's: ${rules.join()}`);
+if (definitionSchema() === schema) throw new Error('a new object per call');
+
+// Specialised to a registry: its node types (the built-in Transform beside yours), each type's pools and settings.
+const registry = {
+  predicates: ['isUrgent'],
+  workers: { w: { url: 'worker.js', settingsSchema: { type: 'object', properties: { depth: { type: 'integer', minimum: 1 } }, additionalProperties: false } } },
+  nodeTypes: { Work: { worker: 'w' } },
+};
+const specialised = definitionSchema(registry);
+type Task = { properties: { type: { enum: string[] } }; allOf: { then: { properties: { pool: { enum: string[] }; settings?: unknown } } }[] };
+const task = (specialised.$defs as { taskNode: Task }).taskNode;
+console.log(task.properties.type.enum);              // [ 'Work', 'Transform' ]
+console.log(task.allOf[0]!.then.properties.pool.enum); // [ 'Work' ]
+if (task.allOf[0]!.then.properties.settings === undefined) throw new Error('Work\'s settings are held to its worker\'s schema');
+if (!String(specialised.description).includes('EXACTLY ONCE')) throw new Error('it names what it cannot carry');
+// A registry new Driver would refuse is never specialised.
+let refused = '';
+try { definitionSchema({ ...registry, nodeTypes: { Lost: { worker: 'missing' } } }); } catch (e) { refused = (e as Error).name; }
+if (refused !== 'WorkerMissing') throw new Error(`a refused registry throws its refusal: ${refused}`);
+```
+
 ---
 
 ## 4. Decisions and predicates
@@ -860,7 +1014,7 @@ 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, and since 0.8.0 `"$payload"` and `"$item"` —
+a node's (section 3) — a node id, or a one-element array holding one, since 0.8.0 `"$payload"` and `"$item"`, and since 0.11.0 a node's error, `"n!error"` —
 **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).
@@ -1468,10 +1622,17 @@ keeps waiting, and the run is not stuck.
 ([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
+  `{ kind: 'asked', taskId, input, observedAt? }`; 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**.
+- **WHEN it was asked** (since 0.11.0, [ADR 0130](doc/decisions/0130-a-regenerated-asked-element-keeps-the-stored-runs-time.md)):
+  the element's `observedAt` is the driver's `now` — the clock an outcome record's `observedAt` reads — and the node's
+  entry carries it as **`askedAt`**, kept after the answer as `input` is. **A resume KEEPS the stored time**: the replay
+  regenerates the element and takes its stored `observedAt`, so a wait measured across a resume does not restart; past
+  the stored tail it is the resumed driver's `now`. An `asked` element written before 0.11.0 has none, and its run
+  resumes with none. **A driver older than 0.11.0 refuses a newer checkpoint `diverged` at its first ask** — resume a
+  run on a driver at least as new as the one that wrote it.
 - **The 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.
@@ -1484,7 +1645,7 @@ keeps waiting, and the run is not stuck.
   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.
+  is `number | null` — `null` only on an ask's effective outcome. `NodeRun.input` is optional and additive — as, since 0.11.0, are the element's `observedAt` and `NodeRun.askedAt`.
 - **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
@@ -1543,6 +1704,9 @@ 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');
+// And WHEN it was asked: the element's `observedAt` (the driver's clock, `Date.now()` by default) is the entry's `askedAt`.
+const askedEl = driver.foldInputs().find((e) => e.kind === 'asked');
+if (askedEl?.kind !== 'asked' || typeof askedEl.observedAt !== 'number' || parked.nodes['r1:approve:-:0'].askedAt !== askedEl.observedAt) throw new Error('the ask keeps when it was asked');
 
 // An answer its schema refuses is thrown at you BY NAME — nothing appended, the ask still parked.
 let refused: unknown = null;
@@ -2035,7 +2199,7 @@ AFTER the target — or one that moves only an envelope, even at the target: the
 answers with the definition you hand it. **It re-runs your predicates and gate types**, as a resume does. The value is
 the reading's own — a value a `needs` reference composed is frozen, as every reader's is (section 3), the rest yours —
 and nothing of a live run is reachable through it. **The input a task's worker sees AFTER its transform is not answered**
-([Q760](doc/questions/q760.md)): hand the envelope's `input` to `tryTransform` (section 15). **BREAKING in 0.10.0**:
+([Q760](doc/questions/q760.md), resolved by P43: the road serves): hand the envelope's `input` to `tryTransform` (section 15). **BREAKING in 0.10.0**:
 `RunHandle` gains `inputOf`, which breaks only code that BUILDS a handle.
 
 ```ts run
@@ -2979,7 +3143,7 @@ if (!haltedRun.haltedBy?.startsWith('UncloneableResult')) throw new Error(`halte
 | ~~**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 **live, mutable view** of a run's state, or the state handed to `onFoldInput` beside each input | **no** — [P39](doc/plans/p39-what-a-step-costs-and-where-a-live-run-state-is-read.md) (b), [ADR 0122](doc/decisions/0122-a-runtimes-live-state-is-a-frozen-copy-on-its-handle.md): `handle.state()` is a frozen COPY, cached until the run moves, and `handle.outcome()` / `handle.node()` are the O(1) reads — section 8 |
-| a task's INPUT kept in the run state — `NodeRun.input` for a task, or `pathEnded` carrying the value that reached an end | **no** — [ADR 0046](doc/decisions/0046-a-run-retains-what-its-tasks-returned-and-a-region-releases-its-collection-when-its-join-becomes-terminal.md): a run keeps what its tasks returned. **READ it instead**, since [W205](doc/work-items/w205-what-a-node-was-handed-read-by-replaying-the-run.md): `inputOf(flow, options, { header, events }, target)` or `handle.inputOf(target)` replays the run to that node — section 8. The input a worker sees AFTER its transform: **no** ([Q760](doc/questions/q760.md)) |
+| a task's INPUT kept in the run state — `NodeRun.input` for a task, or `pathEnded` carrying the value that reached an end | **no** — [ADR 0046](doc/decisions/0046-a-run-retains-what-its-tasks-returned-and-a-region-releases-its-collection-when-its-join-becomes-terminal.md): a run keeps what its tasks returned. **READ it instead**, since [W205](doc/work-items/w205-what-a-node-was-handed-read-by-replaying-the-run.md): `inputOf(flow, options, { header, events }, target)` or `handle.inputOf(target)` replays the run to that node — section 8. The input a worker sees AFTER its transform: **no** ([Q760](doc/questions/q760.md), resolved — the envelope's `input` through `tryTransform` serves) |
 | 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 |
@@ -4149,6 +4313,7 @@ whatever arcs reach the node, on the entry node too** (W166, P37 stop-and-ask (d
 | `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'`** |
+| `cause` | **on `transform-fails` only** (since 0.11.0, every road — `checkWiring`'s arcs too): `'threw'` — the worker half did not import, had no default export, or its `compile` or `evaluate` threw — or `'schema'`, a result the node's `inputSchema` refused — the type `TransformFailureCause`, a root export. Absent on every other kind. Read it rather than `why`'s prefix |
 | `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
@@ -4205,6 +4370,7 @@ if (entry!.kind !== 'transform-passes') throw new Error(`expected the given valu
 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}`);
+if (wrong!.cause !== 'schema') throw new Error(`a result the schema refused is cause 'schema', got ${wrong!.cause}`);
 
 // 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, " ") }' };
@@ -4217,6 +4383,8 @@ if (JSON.stringify(mine!.sample!.result) !== JSON.stringify({ text: 'typed by ha
 // 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}`);
+// The same, as DATA (since 0.11.0): `cause` is 'threw' — no result was produced — where the finding above is 'schema'.
+if (broken!.cause !== 'threw' || entry!.cause !== undefined) throw new Error(`a throw is cause 'threw', and a passing verdict has none — got ${broken!.cause}, ${entry!.cause}`);
 ```
 
 **BREAKING in 0.8.0** (P37 decision 10): **`SampleSource` gains `'given'`**, **`WiringShape` gains

package/README.md

@@ -17,7 +17,7 @@ worker returned, routing can **fan out** into parallel branches, and a **join**
 The scheduler runs tasks; this library decides **which task runs next**. `fyflow-scheduler` has no
 dependency graph of its own, so sequence, decision, fan-out and join live here.
 
-Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.10.0`.
+Published on npm as `fyflow-orchestration` and on JSR as `@fyflow/orchestration`. The manifests read `0.11.0`.
 
 ## Install
 

package/dist/browser/chunks/{chunk-NA6QQAZ2.js → chunk-5CVSWDCB.js}

@@ -416,7 +416,10 @@ function evaluateDeclared(when, scope, unknownOp) {
 // src/definition/validate.ts
 var ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 var KINDS = ["task", "fanout", "map", "join", "end", "gate", "ask"];
+var ID_RE_COPY = new RegExp(ID_RE.source, ID_RE.flags);
+var KINDS_COPY = Object.freeze([...KINDS]);
 var ROUTABLE = ["done", "failed"];
+var ROUTABLE_STATES = [...ROUTABLE];
 var DOC_KEYS = ["flowId", "version", "entry", "nodes"];
 var NODE_KEYS = {
   // `retryPolicy` and `workerGroups` since v0.16 (W58): what a node says about its OWN task,
@@ -451,6 +454,11 @@ var TASK_KEYS_DECLARED = [...NODE_KEYS.task.req, ...NODE_KEYS.task.opt];
 var NODE_KEYS_DECLARED = Object.fromEntries(
   Object.entries(NODE_KEYS).map(([kind, k]) => [kind, [...k.req, ...k.opt]])
 );
+var NODE_KEYS_REQUIRED = Object.fromEntries(
+  Object.entries(NODE_KEYS).map(([kind, k]) => [kind, [...k.req]])
+);
+var EDGE_KEYS_REQUIRED = [...EDGE_KEYS.req];
+var DOC_KEYS_DECLARED = [...DOC_KEYS];
 var RETRY_POLICY_KEYS = ["maxRetries", "backoffMs"];
 function retryPolicyProblem(v) {
   if (typeof v !== "object" || v === null || Array.isArray(v)) {
@@ -958,10 +966,35 @@ function referenceTarget(ref) {
   }
   return null;
 }
+var ERROR_PART = "!error";
 function aimed(s, form) {
   const conditional = s.endsWith("?");
-  const node = conditional ? s.slice(0, -1) : s;
-  return ID_RE.test(node) ? { form, node, conditional } : null;
+  const body = conditional ? s.slice(0, -1) : s;
+  const error = body.endsWith(ERROR_PART);
+  const node = error ? body.slice(0, -ERROR_PART.length) : body;
+  if (!ID_RE.test(node)) return null;
+  return error ? { form, node, conditional, part: "error" } : { form, node, conditional };
+}
+var spelled = (t, conditional) => `${t.node}${t.part === "error" ? ERROR_PART : ""}${conditional ? "?" : ""}`;
+function bangProblem(ref) {
+  const array = Array.isArray(ref) && ref.length === 1;
+  const one = array ? ref[0] : ref;
+  if (typeof one !== "string" || one.startsWith("$") || !one.includes("!")) return null;
+  const wrap = (s) => JSON.stringify(array ? [s] : s);
+  const at = one.indexOf("!");
+  const before = one.slice(0, at);
+  const after = one.slice(at + 1);
+  const afterBare = after.endsWith("?") ? after.slice(0, -1) : after;
+  if (afterBare === "error" && before.endsWith("?") && ID_RE.test(before.slice(0, -1))) {
+    return `${JSON.stringify(ref)} carries "?" before "!error", and the suffix goes last: write ${wrap(`${before.slice(0, -1)}!error?`)}`;
+  }
+  if (before === "") {
+    return `${JSON.stringify(ref)} names no node before "!": write the node whose error you mean first, as ${wrap(`<node>!error${one.endsWith("?") ? "?" : ""}`)}`;
+  }
+  if (afterBare !== "error" && ID_RE.test(before)) {
+    return `${JSON.stringify(ref)} names "${after}" after "!", and the one part of a node's outcome a reference may name is its error: write ${wrap(`${before}!error${after.endsWith("?") ? "?" : ""}`)}, or ${wrap(`${before}${after.endsWith("?") ? "?" : ""}`)} for its result`;
+  }
+  return null;
 }
 var PAYLOAD_TOKEN = "$payload";
 var ITEM_TOKEN = "$item";
@@ -1252,10 +1285,13 @@ function validateDefinition(doc, registry) {
           if (!ID_RE.test(k)) add("FD-V26", where, `needs key ${JSON.stringify(k)} is not [A-Za-z0-9_-]{1,64}`);
           const target = referenceTarget(ref);
           const dollar = target === null ? dollarProblem(ref) : null;
+          const bang = target === null && dollar === null ? bangProblem(ref) : null;
           if (dollar !== null) {
             add("FD-V26", where, `needs[${JSON.stringify(k)}]: ${dollar}`);
+          } else if (bang !== null) {
+            add("FD-V26", where, `needs[${JSON.stringify(k)}]: ${bang}`);
           } else if (target === null) {
-            add("FD-V26", where, `needs[${JSON.stringify(k)}] is ${JSON.stringify(ref)}, which is not "." , "$payload", "$item", a node id with an optional "?" suffix, or a one-element array holding one`);
+            add("FD-V26", where, `needs[${JSON.stringify(k)}] is ${JSON.stringify(ref)}, which is not "." , "$payload", "$item", a node id with an optional "!error" and an optional "?" suffix, or a one-element array holding one`);
           }
         }
       }
@@ -1318,10 +1354,13 @@ function validateDefinition(doc, registry) {
             if (!ID_RE.test(k)) add("FD-V26", at, `edge needs key ${JSON.stringify(k)} is not [A-Za-z0-9_-]{1,64}`);
             const target = referenceTarget(ref);
             const dollar = target === null ? dollarProblem(ref) : null;
+            const bang = target === null && dollar === null ? bangProblem(ref) : null;
             if (dollar !== null) {
               add("FD-V26", at, `edge needs[${JSON.stringify(k)}]: ${dollar}`);
+            } else if (bang !== null) {
+              add("FD-V26", at, `edge needs[${JSON.stringify(k)}]: ${bang}`);
             } else if (target === null) {
-              add("FD-V26", at, `edge needs[${JSON.stringify(k)}] is ${JSON.stringify(ref)}, which is not "$payload", "$item", a node id with an optional "?" suffix or a one-element array holding one`);
+              add("FD-V26", at, `edge needs[${JSON.stringify(k)}] is ${JSON.stringify(ref)}, which is not "$payload", "$item", a node id with an optional "!error" and an optional "?" suffix or a one-element array holding one`);
             } else if (target.form === "self") {
               add("FD-V26", at, `edge needs[${JSON.stringify(k)}] is ".", which an EDGE may not use: what a predicate would have received anyway is its node's own outcome, and \`ctx.outcome\` already carries it`);
             }
@@ -1502,14 +1541,14 @@ function validateDefinition(doc, registry) {
           add(
             "FD-V29",
             at,
-            `${site}[${JSON.stringify(k)}] names "${target}" unconditionally, and a run can reach this node without "${target}" having run \u2014 a decision routes around it, or it is inside a region whose branch may be lost before it is entered. \`FD-V27\` checked that this node is reachable FROM it, which is weaker. Write "${target}?"${t.form === "all" ? " inside the array" : ""} if you mean *if it ran*, and read the key as ${t.form === "all" ? "a possibly-empty array" : "possibly absent"}; otherwise move the reference to a node every path reaches`
+            `${site}[${JSON.stringify(k)}] names "${spelled(t, false)}" unconditionally, and a run can reach this node without "${target}" having run \u2014 a decision routes around it, or it is inside a region whose branch may be lost before it is entered. \`FD-V27\` checked that this node is reachable FROM it, which is weaker. Write "${spelled(t, true)}"${t.form === "all" ? " inside the array" : ""} if you mean *if it ran*, and read the key as ${t.form === "all" ? "a possibly-empty array" : "possibly absent"}; otherwise move the reference to a node every path reaches`
           );
         }
         const many = regions.some((r) => r.opensWith === "map" && r.members.has(target) && !r.members.has(n.id));
         if (many && t.form === "one") {
-          add("FD-V28", at, `${site}[${JSON.stringify(k)}] names "${target}" as one value, but it is inside a map region this node is outside of, so it produces one output per ITEM; write ["${target}"]`);
+          add("FD-V28", at, `${site}[${JSON.stringify(k)}] names "${spelled(t, false)}" as one value, but it is inside a map region this node is outside of, so it produces one output per ITEM; write ["${spelled(t, false)}"]`);
         } else if (!many && t.form === "all") {
-          add("FD-V28", at, `${site}[${JSON.stringify(k)}] names ["${target}"] as a list, but it produces exactly one output on this node's branch path; write "${target}"`);
+          add("FD-V28", at, `${site}[${JSON.stringify(k)}] names ["${spelled(t, false)}"] as a list, but it produces exactly one output on this node's branch path; write "${spelled(t, false)}"`);
         }
       }
     }
@@ -2025,6 +2064,7 @@ var typesOf = (s) => {
 var widen = (ts) => ts.flatMap((t) => t === "integer" ? ["integer"] : t === "number" ? ["number", "integer"] : [t]);
 var canon = (v) => JSON.stringify(v);
 var BRANCH_KEY = /^\d+(\.\d+)*$/;
+var ERROR_SCHEMA = Object.freeze({ type: ["string", "null"] });
 function fits(P, C, path = "$") {
   const p = P;
   const c = C;
@@ -2419,6 +2459,11 @@ var Wiring = class {
         value = a.sample?.value;
         src = a.sample?.source ?? "witness";
         dot.push(key);
+      } else if (t.part === "error") {
+        schema2 = ERROR_SCHEMA;
+        const w = sampleOf(ERROR_SCHEMA);
+        value = w.value;
+        src = w.source;
       } else {
         const p = this.produced(t.node);
         if (p.schema === void 0) return { ...base, unchecked: `needs.${key} names "${t.node}", which ${p.unchecked}` };
@@ -2538,6 +2583,7 @@ async function judgeTransform(v, node, transform, type, consumer, consumerWhy, l
     for (const input of inputs) results.push(await c.evaluate(input, settings));
   } catch (e) {
     v.kind = "transform-fails";
+    v.cause = "threw";
     v.why = `the transform threw on the ${sourceWord(sample.source)}: ${e instanceof Error ? e.message : String(e)}`;
     v.sample = { ...sample, result: e instanceof Error ? e.message : String(e) };
     return;
@@ -2551,6 +2597,7 @@ async function judgeTransform(v, node, transform, type, consumer, consumerWhy, l
   const bad = results.map((r, i) => [i, findings(consumer, r)]).find(([, f]) => f.length > 0);
   if (bad) {
     v.kind = "transform-fails";
+    v.cause = "schema";
     v.why = `the transform's result on the ${sourceWord(sample.source)}${perItem ? ` (item ${bad[0]})` : ""} fails the consumer's inputSchema \u2014 ${describeFindings(bad[1])}`;
   } else {
     v.kind = "transform-passes";
@@ -3046,6 +3093,11 @@ function sameData(a, b) {
   const kb = Object.keys(rb).filter((k) => rb[k] !== void 0);
   return ka.length === kb.length && ka.every((k) => Object.hasOwn(rb, k) && sameData(ra[k], rb[k]));
 }
+function storedAskedAt(e) {
+  if (e === void 0 || e === null || typeof e !== "object" || e.kind !== "asked") return void 0;
+  const t = e.observedAt;
+  return typeof t === "number" ? t : void 0;
+}
 function isFed(e) {
   return e.kind === "outcome" || e.kind === "resolution" || e.kind === "resumed" || e.kind === "interrupted" || e.kind === "paused" || e.kind === "unpaused" || e.kind === "attempted";
 }
@@ -5408,7 +5460,7 @@ var Driver = class _Driver {
   }
   /**
    * **One task's entry, made what its effective outcome now says** — `outputs()`'s catch-up, for a task one of whose records
-   * was just read. An entry is `{ path, result }` with `result` the record's own object (`RN-R13`); a node's list is kept
+   * was just read. An entry is `{ path, result, error }` with `result` the record's own object (`RN-R13`) and `error` its string or `null` (v0.49, ADR 0131); a node's list is kept
    * in its tasks' FIRST-RECORD order, the order the rebuild grouped them in.
    *
    * **`!eff` — a suspended node contributes no entry.** The first record of a `user_action` task has none, and its
@@ -5441,7 +5493,7 @@ var Driver = class _Driver {
       }
       return;
     }
-    const entry = { path: t.path, result: eff.result };
+    const entry = { path: t.path, result: eff.result, error: eff.error };
     if (t.entry !== null && list !== void 0) {
       list[list.indexOf(t.entry)] = entry;
       this.reindex(c, t.nodeId, t.entry, entry);
@@ -5616,6 +5668,9 @@ var Driver = class _Driver {
     }
     const c = this.outputsCache;
     c.examined += t.form === "all" ? visible.length : 1;
+    if (t.part === "error") {
+      return t.form === "all" ? visible.map((e) => e.error) : visible[0].error;
+    }
     return t.form === "all" ? visible.map((e) => this.sharedOf(c, e)) : this.sharedOf(c, visible[0]);
   }
   /** **An output entry's shared copy**, made at its first read and kept on the entry (`OutputEntry.shared`) — counted. */
@@ -5782,7 +5837,10 @@ var Driver = class _Driver {
       throw new DuplicateTaskId(`"${taskId}" was already asked in run "${runId}" \u2014 an ask's id is minted once per path (ID-R1)`);
     }
     this.asked.add(taskId);
-    this.append({ kind: "asked", taskId, input: cloneValue(received) });
+    const replay = this.replay;
+    const at = this.inputs.length;
+    const observedAt = replay !== null && at < replay.stored.length ? storedAskedAt(replay.stored[at]) : this.now();
+    this.append(observedAt === void 0 ? { kind: "asked", taskId, input: cloneValue(received) } : { kind: "asked", taskId, input: cloneValue(received), observedAt });
     if (this.shut()) return;
     const region = this.regionOf(node.id);
     if (region) {
@@ -6676,7 +6734,9 @@ var Accumulator = class _Accumulator {
         state: "suspended",
         result: null,
         error: null,
-        input: structuredClone(input.input)
+        input: structuredClone(input.input),
+        // `RN-R36` v0.35 (W208, ADR 0130): WHEN it was asked, where the element says — and only there.
+        ...input.observedAt !== void 0 ? { askedAt: input.observedAt } : {}
       });
       return this.withOutcome();
     }
@@ -6744,7 +6804,8 @@ var Accumulator = class _Accumulator {
         state: r.resolvedAs,
         result: r.result,
         error: r.error,
-        ...existing !== void 0 && "input" in existing ? { input: existing.input } : {}
+        ...existing !== void 0 && "input" in existing ? { input: existing.input } : {},
+        ...existing?.askedAt !== void 0 ? { askedAt: existing.askedAt } : {}
       });
     }
     this.runId = this.runId ?? runId;
@@ -6920,10 +6981,16 @@ export {
   findings,
   describeFindings,
   readKeyPath,
+  ID_RE_COPY,
+  KINDS_COPY,
+  ROUTABLE_STATES,
   ASK_REFUSED_KEYS,
   EDGE_KEYS_DECLARED,
   TASK_KEYS_DECLARED,
   NODE_KEYS_DECLARED,
+  NODE_KEYS_REQUIRED,
+  EDGE_KEYS_REQUIRED,
+  DOC_KEYS_DECLARED,
   RETRY_POLICY_KEYS,
   retryPolicyProblem,
   BUILT_IN_NODE_TYPES,