fyflow-orchestration 0.7.0 → 0.8.0

package/dist/types/src/driver/listener.d.ts

@@ -6,6 +6,11 @@ export interface TaskDetailLike {
     result?: unknown;
     error?: string;
     attempts?: number;
+    /**
+     * The scheduler's 1-based number of the attempt, read on `task.running` ONLY — `RN-R40`, W186, by the driver while its
+     * listener runs. Never on a record: the record's `attempts` is the scheduler's count (`OR-R4`, P36 (i)).
+     */
+    attemptNumber?: number;
     timestamp?: number;
     startTime?: number;
     endTime?: number;
@@ -15,7 +20,7 @@ export interface TaskDetailLike {
  * `OR-R6`'s refusal. **It sets its own `name`**, as `BoundaryRefused` and `ResumeRefused` do, so the
  * error's own render — `String(e)`, a stack's first line — reads `UncloneableResult: <message>`. Since
  * W133 the MESSAGE no longer carries the class name (Q63), and without this the error itself would
- * say `Error:` everywhere but `RunFailure.kind` and `stoppedBy`.
+ * say `Error:` everywhere but `RunFailure.kind` and `haltedBy`.
  */
 export declare class UncloneableResult extends Error {
     constructor(message?: string, options?: ErrorOptions);
@@ -29,6 +34,7 @@ export declare class UncloneableResult extends Error {
  *   done                      task.completed              -> 1 record
  *   failed (optional task)    task.failed                 -> 1 record
  *   user_action               task.failed, task.user_action -> 1 record, on the SECOND
+ *   cancelled                 task.cancelled              -> 1 record (ADR 0094)
  *
  * The third row is why this exists. `task.failed` fires for a task that did not
  * fail, its detail already reads `state: 'user_action'`, and a driver keying on

package/dist/types/src/driver/log.d.ts

@@ -15,7 +15,12 @@ export interface OutcomeRecord {
     result: CloneableValue | null;
     error: string | null;
     attempts: number;
-    schedulerTimestamp: number;
+    /**
+     * The scheduler's stamp — and **`null` for an ASK's effective outcome** (`spec/outcome-record.md` v0.18, P35 (e),
+     * [ADR 0109](../../doc/decisions/0109-an-ask-parks-with-nothing-dispatched-and-its-answer-is-its-result.md)): no
+     * scheduler was involved. A SETTLEMENT always carries a number. **BREAKING in 0.8.0** for a consumer typed on `number`.
+     */
+    schedulerTimestamp: number | null;
     observedAt: number;
     startTime: number | null;
     endTime: number | null;
@@ -39,8 +44,14 @@ export type LogRecord = OutcomeRecord | ResolutionRecord;
  * second resolution refusable.
  */
 export declare function lastRecordFor(log: readonly LogRecord[], taskId: string): LogRecord | undefined;
-/** `RS-R1` — a task is suspended when its last record is an outcome in `user_action`. */
-export declare function isSuspended(log: readonly LogRecord[], taskId: string): boolean;
+/**
+ * `RS-R1` — a task is suspended when its last record is an outcome in `user_action`; **or, since v0.18, when it was
+ * ASKED and has no record at all** (P35 (b), ADR 0109): an ask parks with an `asked` fold input — not a log record,
+ * since section 1 fixes the log at two kinds — and the person's answer is the first record its id ever gets, so a
+ * second answer is refused as a second resolution is. `asked` is the caller's: whether the fold-input sequence holds an
+ * `asked` element for the id, which this function cannot see.
+ */
+export declare function isSuspended(log: readonly LogRecord[], taskId: string, asked?: boolean): boolean;
 /**
  * `spec/outcome-record.md` section 6 — the record ROUTING reads, which is never
  * the log directly.
@@ -52,8 +63,12 @@ export declare function isSuspended(log: readonly LogRecord[], taskId: string):
  * `OR-R8`: derived, never appended. Appending it would make the log contain its
  * own conclusions, and a second fold would derive a third record from the second.
  *
+ * **An ASK's** — a resolution with NO settlement before it, which `RS-R1` admits only for an asked task — is DERIVED
+ * from the resolution alone (`spec/outcome-record.md` section 7, v0.18, P35 (e), ADR 0109): the answer is the node's
+ * result, `attempts` `0` and every scheduler field `null`, because no dispatch happened for those fields to describe.
+ *
  * @returns `null` when the task has not settled, or has settled `user_action` and
- *   has no resolution — a suspended node has no effective outcome, which is
- *   exactly right: it has not finished and nothing routes.
+ *   has no resolution, or was asked and has no answer — a suspended node has no
+ *   effective outcome, which is exactly right: it has not finished and nothing routes.
  */
 export declare function effectiveOutcome(log: readonly LogRecord[], taskId: string): OutcomeRecord | null;

package/dist/types/src/driver/routing.d.ts

@@ -21,12 +21,16 @@ import type { OutcomeRecord } from './log.js';
 export interface DecisionContext {
     /**
      * `OR-R9` — ALWAYS the node's effective outcome, so a predicate sees one shape
-     * whether the node settled or was resolved, and `terminalState` is never undefined.
+     * whether the node settled or was resolved, and `terminalState` is never undefined. **For an ASK it is derived from
+     * the person's answer** (`spec/outcome-record.md` section 7, v0.18): `result` the answer, `attempts` `0`, and
+     * `schedulerTimestamp` and the timing fields `null` — no scheduler was involved.
      */
     outcome: OutcomeRecord;
     /**
      * **What this EDGE declared it needs** — the object its `needs` describes, resolved
-     * against the run's own outputs exactly as a node's is (`FD-C1`, `FD-C2`).
+     * against the run's own outputs exactly as a node's is (`FD-C1`, `FD-C2`) — and, since
+     * v0.44, against the value the RUN entered with, for a `"$payload"` key (`FD-C3`,
+     * ADR 0117): so a predicate routes on `needs.run.amount` with no task before it.
      *
      * **`{}` when the edge declares none, never `undefined`**, for rule 4's own reason
      * one level out: *a predicate written `ctx.needs.flag` must mean one thing*, and a
@@ -58,9 +62,10 @@ export declare function eligibleEdges(node: FlowNode, terminalState: TerminalSta
  * **The ONE edge a gate takes for a route** — `spec/flow-definition.md` section 2's gate,
  * [ADR 0066](../../doc/decisions/0066-a-gate-is-a-decision-with-memory-that-names-a-registered-type-and-wires-every-route-exactly-once.md)
  * rule 4, [W93](../../doc/work-items/w93-what-a-gate-does-in-a-run.md). An edge carries the route it names,
- * and **an edge with no `route` carries the type's DEFAULT route** — never every route, and not the first.
- * Pure, as `selectEdge` is: the caller has already held `route` to the type's declared routes (`FD-R5`), and
- * `FD-V41` wires every declared route by exactly one edge, so this is total over what reaches it — `null` is
+ * and **an edge with no `route` carries the gate's DEFAULT route** — never every route, and not the first.
+ * `defaultRoute` is the GATE's resolved set's (`routesOf`, ADR 0092 rule 3), never read off the type here.
+ * Pure, as `selectEdge` is: the caller has already held `route` to the gate's resolved routes (`FD-R5`), and
+ * `FD-V41` wires every route of that set by exactly one edge, so this is total over what reaches it — `null` is
  * the assertion that `FD-V41` held, and the driver stops the run on it rather than routing nowhere.
  */
 export declare function gateEdge(node: GateNode, defaultRoute: string, route: string): Edge | null;

package/dist/types/src/fold/policies.d.ts

@@ -91,11 +91,10 @@ export interface ArrivalCountState {
  * That rule's own section says *"`arrival-count` is immune, because its `N` comes
  * from `region.branches.length` at `open`"* — true until this change and false
  * after it. Every `branch.opened` for a region precedes any other event for it, so
- * `need` is final before any arrival can be counted against it. The clause remains
- * unfalsifiable through a conformant driver — `FD-V25` makes a map's branch a
- * `task` and entering a task dispatches without emitting, which is `FD-V9`'s role
- * for a fanout played by a second rule — but what RESTS on it is now both counting
- * policies rather than one.
+ * `need` is final before any arrival can be counted against it. *(This read "the clause remains unfalsifiable through
+ * a conformant driver" until W180: since `spec/flow-definition.md` v0.42 a branch entry or a map's branch may be an
+ * `ask`, which EMITS on entry, so the clause's guarantor is the driver's two-pass emission — `spec/join-policy.md`
+ * v0.23.)* What RESTS on it is now both counting policies rather than one.
  */
 export declare const arrivalCount: JoinPolicy<ArrivalCountState>;
 export interface LiveTokenState {

package/dist/types/src/fold/run-state.d.ts

@@ -10,14 +10,19 @@
 import type { LogRecord, OutcomeRecord } from '../driver/log.js';
 import type { RegionEvent } from '../driver/events.js';
 /**
- * `spec/run-state.md` section 4. Four, not five.
+ * `spec/run-state.md` section 4. Five, not the scheduler's six.
  *
  * `user_action` is `suspended` here — it is not terminal at flow level. And there
  * is **no `pending`**: `OR-R4` says `task.running` writes no record, so the only
  * signal the fold has is the dispatch itself, and a task is `running` from that
- * moment. A state nothing can produce is not a state.
+ * moment. A state nothing can produce is not a state. *(Since v0.26 `task.running` produces a FOLD INPUT, `attempted`
+ * (`RN-R40`, W186) — still no record, and it moves no state: a task is `running` from its dispatch either way.)*
+ *
+ * **`cancelled` is W158's** ([ADR 0094](../../doc/decisions/0094-a-cancelled-task-is-a-terminal-state-that-routes-no-edge-and-ends-its-run-cancelled.md)),
+ * copied verbatim from the settlement as `done` and `failed` are. **Widening this union is BREAKING for a
+ * consumer switching on it exhaustively** — `resumed`'s and `gated`'s precedent.
  */
-export type NodeState = 'running' | 'done' | 'failed' | 'suspended';
+export type NodeState = 'running' | 'done' | 'failed' | 'suspended' | 'cancelled';
 /**
  * `spec/run-state.md` section 3. Closed, and ours — an author labels why a path
  * ended, not what the run is.
@@ -26,17 +31,93 @@ export type NodeState = 'running' | 'done' | 'failed' | 'suspended';
  * [ADR 0015](../../doc/decisions/0015-a-run-whose-join-can-no-longer-fire-is-stuck.md):
  * nothing is live, nothing waits on a person, and a region's join has not fired,
  * so nothing will ever move again. v0.2 called that run **`completed`**.
+ *
+ * **`cancelled` is v0.15's seventh**, added by W158 under
+ * [ADR 0094](../../doc/decisions/0094-a-cancelled-task-is-a-terminal-state-that-routes-no-edge-and-ends-its-run-cancelled.md):
+ * a task of the run settled `cancelled`, so the driver halted it (`RN-R28`). **Widening this union is BREAKING
+ * for a consumer switching on it exhaustively** — `resumed`'s and `gated`'s precedent; a consumer comparing
+ * strings sees a value it never named, and `isTerminal` already calls it terminal.
+ *
+ * **`halted` is v0.16's NAME for the outcome 0.7.0 called `stopped`** — W171,
+ * [ADR 0102](../../doc/decisions/0102-a-run-the-driver-halts-is-halted-and-a-stored-stopped-reads-as-one.md), P34
+ * decision 2 and stop-and-ask (f): a refusal terminated the run (`OR-R10`, `RN-R8`). *Stop* is P34's resumable stop
+ * of a run (W174), so the old name leaves this union ENTIRELY: **BREAKING**, and loudly — a consumer's
+ * `outcome === 'stopped'` no longer compiles, rather than silently changing what it means. The count does not move.
+ *
+ * **`cancelling` is v0.18's EIGHTH**, added by W173 under
+ * [ADR 0104](../../doc/decisions/0104-a-run-its-owner-cancels-is-cancelling-until-its-last-task-has-stopped.md): the
+ * run's OWNER cancelled it (`driver.cancel`, a `cancelRequested` element) and a task is still stopping (`RN-R30`).
+ * **NOT terminal** — the third outcome {@link isTerminal} calls unfinished — so a runtime's `done` waits for the last
+ * task to stop. **BREAKING in 0.8.0** (P34 decision 10): a consumer switching on it exhaustively, or keying a
+ * `Record<RunOutcome, …>`, fails to compile; one comparing strings sees a value it never named.
+ *
+ * **`interrupted` is v0.19's NINTH**, added by W174 under
+ * [ADR 0105](../../doc/decisions/0105-a-run-its-owner-stops-goes-deaf-before-it-cancels-and-resumes-elsewhere.md): the
+ * run's OWNER stopped it to resume it elsewhere (`driver.stop`, an `interrupted` element), and no `resumed` element has
+ * followed (`RN-R32`). **Terminal** — {@link isTerminal} needs no change, and a runtime's `done` settles on it once the
+ * stop's cancels have resolved — **and the one terminal outcome a resume ACCEPTS**. **BREAKING in 0.8.0** (P34 decision
+ * 10), as `cancelling` is.
  */
-export type RunOutcome = 'running' | 'completed' | 'failed' | 'awaiting_action' | 'stopped' | 'stuck';
+export type RunOutcome = 'running' | 'completed' | 'failed' | 'awaiting_action' | 'halted' | 'stuck' | 'cancelled' | 'cancelling' | 'interrupted';
+/**
+ * **Who cancelled the run, and why** — `RunState.cancelRequest`, `RN-R30`, v0.18. What the `cancelRequested` element
+ * carried: `actor` as the caller gave it, `reason` the caller's or `null` when it gave none.
+ */
+export interface CancelRequest {
+    actor: string;
+    reason: string | null;
+}
+/**
+ * **Who stopped the run, and why** — `RunState.interruption`, `RN-R32`, v0.19. What the `interrupted` element carried:
+ * `actor` as the caller gave it, `reason` the caller's or `null` when it gave none.
+ */
+export interface Interruption {
+    actor: string;
+    reason: string | null;
+}
 /** How a branch left its region. `null` while it is still live. */
 export type BranchSettlement = 'arrived' | 'exited' | 'lost';
+/**
+ * **One task's entry in `RunState.nodes`** — `RN-R5`, and since v0.27 its ATTRIBUTION as fields (`RN-R41`,
+ * [ADR 0114](../../doc/decisions/0114-a-tasks-attribution-is-fields-and-its-messages-and-progress-are-passed-through.md), P36
+ * stop-and-ask (j)): the run, the flow-level attempt and the scheduler's attempt number, so a reader holding an entry on
+ * its own needs no parse of its key. **`runId`, `flowAttempt` and `attemptNumber` are REQUIRED, and that is BREAKING in
+ * 0.8.0 for code that builds a `NodeRun` literal** (P36 (p)); a reader is unaffected. Fold OUTPUT only: no fold input
+ * carries a field derived from the task id (`spec/outcome-record.md` section 2), and none moves.
+ */
 export interface NodeRun {
+    /**
+     * **The run the task belongs to** — v0.27, `RN-R41`: the task id's first segment (`spec/task-id.md` section 1), equal to
+     * `RunState.runId` on every entry of a run's fold. On the entry so it travels with it.
+     */
+    runId: string;
     nodeId: string;
     /** `'-'` when the node is in no fan-out region. */
     branchPath: string;
+    /**
+     * **The FLOW-LEVEL attempt** — v0.27, `RN-R41`: the task id's fourth segment, `0` on every id this library mints today
+     * ([Q16](../../doc/questions/q16.md)'s flow half mints nothing above it). NOT the scheduler's attempt number: that is
+     * {@link NodeRun.attemptNumber}, named apart so the two cannot be confused (P36 (j)).
+     */
+    flowAttempt: number;
+    /**
+     * **The SCHEDULER's attempt number** — v0.27, `RN-R41`: the 1-based `attemptNumber` the LATEST `attempted` element for this
+     * task carried (`RN-R40`), so a retried task reads the attempt it is on, or settled on. **`null`** before its first
+     * attempt starts, on an ASK (never handed to a scheduler), and on every entry of a log written before 0.8.0, which holds
+     * no `attempted` element — never derived from a settlement's `attempts`.
+     */
+    attemptNumber: number | null;
     state: NodeState;
     result: unknown;
     error: string | null;
+    /**
+     * **What REACHED an ask** — `RN-R36`, v0.22, P35 (f),
+     * [ADR 0109](../../doc/decisions/0109-an-ask-parks-with-nothing-dispatched-and-its-answer-is-its-result.md): the value
+     * its `needs` composed (or the edge's value without one), as its `asked` element carried it, and KEPT after the answer.
+     * **Present only on an ask's node**, so every other node's entry has the five fields it always had — OPTIONAL, and
+     * additive: a consumer building a `NodeRun` literal is unaffected.
+     */
+    input?: unknown;
 }
 export interface RegionRun {
     /** Branch paths opened, in the order the driver emitted them (`JP-R5`). */
@@ -95,8 +176,37 @@ export interface RunState {
         reason: 'end' | 'no-eligible-edge';
         at: string;
     }[];
-    /** Set when a refusal terminated the run (`OR-R10`, `RN-R8`). */
-    stoppedBy: string | null;
+    /**
+     * Set when a refusal HALTED the run (`OR-R10`, `RN-R8`): the refusal's class, `: `, and its message. *(0.7.0's
+     * `stoppedBy` — renamed with the outcome by ADR 0102; BREAKING, and a consumer reading the old name fails to compile.)*
+     */
+    haltedBy: string | null;
+    /**
+     * **Set when the run's OWNER cancelled it** — `RN-R30`, v0.18, W173,
+     * [ADR 0104](../../doc/decisions/0104-a-run-its-owner-cancels-is-cancelling-until-its-last-task-has-stopped.md): the
+     * FIRST `cancelRequested` element's `{ actor, reason }`, and `null` for a run nobody cancelled — including one a cancel
+     * the scheduler made on its own ended (`RN-R28`), which carries no actor. **A new cell, BREAKING in 0.8.0 for a
+     * consumer that builds a `RunState` literal** (P34 decision 10).
+     */
+    cancelRequest: CancelRequest | null;
+    /**
+     * **Set while the run's OWNER has STOPPED it** — `RN-R32`, v0.19, W174,
+     * [ADR 0105](../../doc/decisions/0105-a-run-its-owner-stops-goes-deaf-before-it-cancels-and-resumes-elsewhere.md): the
+     * `interrupted` element's `{ actor, reason }`, and `null` again once a `resumed` element follows it. **CURRENT, not
+     * cumulative** — `regions[*].suspended`'s precedent (`RN-R6`): that a resumed run was ever stopped is in the input
+     * sequence, not here. **A new cell, BREAKING in 0.8.0 for a consumer that builds a `RunState` literal** (P34 decision 10).
+     */
+    interruption: Interruption | null;
+    /**
+     * **Whether the run's OWNER has paused it NOW** — `RN-R34`, v0.20, W175,
+     * [ADR 0106](../../doc/decisions/0106-a-run-its-owner-pauses-routes-on-and-holds-every-dispatch-until-unpaused.md): `true`
+     * from a `paused` element until an `unpaused` one. **A flag, NOT an outcome** (P34 (e)): a paused run still routes, and
+     * each dispatch it holds is `dispatched` and so `running` in `nodes` — so `outcome` is exactly what it would be without
+     * the pause, and no precedence moves. **CURRENT, not cumulative**: that a run was ever paused is in the input sequence.
+     * Neither a stop, a cancel nor a resume lifts it — only an `unpaused` element does, so a run stopped while paused
+     * resumes paused. **A new cell, BREAKING in 0.8.0 for a consumer that builds a `RunState` literal** (P34 decision 10).
+     */
+    paused: boolean;
     /**
      * **Every resume this run has had, in order, each the task ids it handed a scheduler AGAIN** —
      * `RN-R22`, [ADR 0065](../../doc/decisions/0065-a-resume-replays-the-stored-stimuli-refuses-what-it-cannot-regenerate-and-re-dispatches-what-was-in-flight.md),
@@ -167,7 +277,7 @@ export interface GateDecision {
  *
  * Neither is a log record, and neither belongs in one: `spec/outcome-record.md`
  * section 1 fixes the log at two kinds. This is the fold's input sequence, which
- * already carried region events and a stop for the same reason.
+ * already carried region events and a halt for the same reason.
  *
  * **`joinSettled` is W5's, and it is the third fact of this shape**
  * ([ADR 0015](../../doc/decisions/0015-a-run-whose-join-can-no-longer-fire-is-stuck.md)):
@@ -221,6 +331,25 @@ export type FoldInput = {
 } | {
     kind: 'dispatched';
     taskId: string;
+}
+/**
+ * **A branch reached an ASK, which parked** — `RN-R36`, `RN-R37`, v0.22,
+ * [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), P35
+ * stop-and-ask (b): appended by the driver where a branch ENTERS an ask, with NOTHING handed to the scheduler — `taskId`
+ * the ask's own (`spec/task-id.md`'s scheme, attempt `0`) and `input` what reached it, composed through its `needs`
+ * (P35 (f)). The fold reads the node `suspended` from here, its `input` kept, until the person's `resolution`.
+ *
+ * **A structural fact, not a terminal state** (P35 decision 5, fact 13): `dispatched`'s precedent — no outcome record is
+ * ever written for an ask, and its only terminal fact is the person's answer. **REGENERATED on resume, never FED**
+ * (`RN-R19`): the replay re-enters the ask and compares the input it composes with the stored one (`RN-R20`). **The
+ * first kind whose payload is a value of ANY shape**, so it is deep-copied on the way out (`freezeInput`, `RN-R17`).
+ * **A new kind, BREAKING in 0.8.0 for a consumer switching on `kind` exhaustively** (P35 decision 8).
+ */
+ | {
+    kind: 'asked';
+    taskId: string;
+    input: unknown;
 } | {
     kind: 'pathEnded';
     reason: 'end' | 'no-eligible-edge';
@@ -231,10 +360,77 @@ export type FoldInput = {
     regionPath: string;
     joinId: string;
     fired: boolean;
-} | {
-    kind: 'stopped';
+}
+/**
+ * **A refusal HALTED the run** — `OR-R10`, `RN-R8`; appended by the driver's `failRun`, `reason` the refusal's class,
+ * `: ` and its message. **0.7.0 wrote this element as `{ kind: 'stopped', reason }`** and ADR 0102 renamed it
+ * (W171, P34 stop-and-ask (f)). **The old kind is READ, never written, and is not a member of this union**: a stored
+ * sequence is data from before the rename, so {@link step} folds an element whose `kind` is `'stopped'` exactly as
+ * this one and `resumeRefusal` refuses it `halted` at its position — `CHECKPOINT_FORMAT` stays `1`, and a 0.7.0
+ * checkpoint of a halted run is refused for the right reason while one of a live run still resumes. Nothing in this
+ * library writes `'stopped'` again, and the type says so: a consumer's `kind === 'stopped'` no longer compiles.
+ * **BREAKING in 0.8.0** (P34 decision 10): a consumer that switched on, compared or CONSTRUCTED the old kind fails
+ * to compile.
+ */
+ | {
+    kind: 'halted';
     reason: string;
 }
+/**
+ * **The run's OWNER cancelled it** — `RN-R30`, `RN-R31`, v0.18,
+ * [W173](../../doc/work-items/w173-cancelling-a-run.md),
+ * [ADR 0104](../../doc/decisions/0104-a-run-its-owner-cancels-is-cancelling-until-its-last-task-has-stopped.md), P34
+ * decision 4: appended ONCE by `Driver.cancel`, after the hold and BEFORE the scheduler is asked to cancel anything,
+ * so every `task.cancelled` it causes folds under it. `reason` is `null` when the caller gave none. The fold reads the
+ * run `cancelling` from here while a dispatched task is unsettled, and `cancelled` once none is.
+ *
+ * **Never fed to a replay**: a resume refuses a stored one `cancelled` before replaying anything (`RN-R23`). **A new
+ * kind, BREAKING in 0.8.0 for a consumer switching on `kind` exhaustively** (P34 decision 10).
+ */
+ | {
+    kind: 'cancelRequested';
+    actor: string;
+    reason: string | null;
+}
+/**
+ * **The run's OWNER stopped it, to resume it elsewhere** — `RN-R32`, `RN-R33`, v0.19,
+ * [W174](../../doc/work-items/w174-stopping-a-run-to-resume-it-elsewhere.md),
+ * [ADR 0105](../../doc/decisions/0105-a-run-its-owner-stops-goes-deaf-before-it-cancels-and-resumes-elsewhere.md), P34
+ * decision 3 and stop-and-ask (d): appended ONCE by `Driver.stop`, after the hold and the driver going DEAF and BEFORE
+ * it asks the scheduler to cancel anything, so no `task.cancelled` the stop causes — nor any settlement at all — follows it. `reason` is `null` when the
+ * caller gave none. The fold reads the run `interrupted` from here until a `resumed` element.
+ *
+ * **FED to a replay** (`RN-R19`), at its own position — the one terminal element a resume does not refuse. **A new
+ * kind, BREAKING in 0.8.0 for a consumer switching on `kind` exhaustively** (P34 decision 10).
+ */
+ | {
+    kind: 'interrupted';
+    actor: string;
+    reason: string | null;
+}
+/**
+ * **The run's OWNER paused it** — `RN-R34`, `RN-R35`, v0.20,
+ * [W175](../../doc/work-items/w175-pausing-a-run.md),
+ * [ADR 0106](../../doc/decisions/0106-a-run-its-owner-pauses-routes-on-and-holds-every-dispatch-until-unpaused.md), P34
+ * stop-and-ask (e): appended ONCE by `Driver.pause`, at rest — between two of the driver's steps — and from it on every
+ * dispatch is appended and HELD. The fold sets `RunState.paused`; no outcome moves.
+ *
+ * **FED to a replay** (`RN-R19`), at its own position, so a run stopped while paused resumes paused. **A new kind,
+ * BREAKING in 0.8.0 for a consumer switching on `kind` exhaustively** (P34 decision 10).
+ */
+ | {
+    kind: 'paused';
+    actor: string;
+}
+/**
+ * **The run's OWNER unpaused it** — `RN-R34`, `RN-R35`, v0.20, W175, ADR 0106: appended ONCE by `Driver.unpause`, at
+ * rest, BEFORE the held tasks are handed on, in dispatch order. The fold clears `RunState.paused`. **FED to a replay**;
+ * **a new kind, BREAKING in 0.8.0** (P34 decision 10).
+ */
+ | {
+    kind: 'unpaused';
+    actor: string;
+}
 /**
  * **The run was RESUMED, and these are the tasks handed to a scheduler again** — `RN-R22`,
  * [W89](../../doc/work-items/w89-what-resuming-is.md), P23 stop-and-ask (a), answered: *a resume
@@ -269,7 +465,30 @@ export type FoldInput = {
  */
  | ({
     kind: 'gated';
-} & GateDecision);
+} & GateDecision)
+/**
+ * **An ATTEMPT of a task started** — `RN-R40`, v0.26,
+ * [W186](../../doc/work-items/w186-attempts-recorded-and-carried-across-a-resume.md),
+ * [ADR 0113](../../doc/decisions/0113-a-tasks-attempts-are-recorded-and-carried-across-a-resume.md), P36 stop-and-ask (f):
+ * appended by the driver for the scheduler's `task.running` of a task THIS run dispatched, carrying the scheduler's
+ * 1-based `attemptNumber` — and ONLY when that number EXCEEDS the last one recorded for the task, so a requeue (which
+ * repeats its number) appends nothing. For every task, with or without a `retryPolicy`. **Appended at REST**: a
+ * `task.running` heard on the driver's own step — an inline pool fires it INSIDE `addTask` — is appended when that step
+ * ends, so the element always lies BETWEEN two steps, where a resume's replay feeds it (`RN-R19`).
+ *
+ * **FED to a replay** (`RN-R19`'s seventh kind): only the scheduler can produce it, so the replay cannot regenerate it;
+ * the highest number the replay was fed for a task is what a resume re-hands it with as `attemptsSpent` (`RN-R21`), so a
+ * task's retry budget is NOT reset by a crash (Q365). **Moved nothing in `RunState` at v0.26; since v0.27 it sets ONE
+ * cell, its task's `NodeRun.attemptNumber`** (`RN-R41`, W187) — the run's outcome, every state and every other cell are
+ * what they would be without it. **Never a log record**
+ * (`OR-R4`: `task.running` writes none) — `cancelRequested`'s precedent. **A new kind, BREAKING in 0.8.0 for a consumer
+ * switching on `kind` exhaustively** (P36 decision 8, (p)).
+ */
+ | {
+    kind: 'attempted';
+    taskId: string;
+    attemptNumber: number;
+};
 export declare function emptyState(): RunState;
 /**
  * One step. **Returns a new state; never mutates the one it was given** — which is
@@ -292,14 +511,26 @@ export declare function foldLog(log: readonly LogRecord[]): RunState;
  * Whether a run can still change — the predicate an L6 harness resolves on, and
  * the reason it needs no clock.
  *
- * `running` and `awaiting_action` are the two outcomes that say more input is
- * coming: a dispatched node has not settled, or a person has not answered. Every
- * other outcome is reached only when nothing is live, so the sequence is
- * finished. **This is `stuck`'s point:** before
+ * `running` and `awaiting_action` are two of the three outcomes that say more input is
+ * coming that can MOVE the run (`cancelling`, the third, below): a dispatched node has not settled, or a person has
+ * not answered. `completed`, `failed` and `stuck` are reached only when nothing is
+ * live. `halted` and — since W158 — `cancelled` are reached with dispatched nodes
+ * possibly still unsettled: the driver has HALTED the run, so what is in flight
+ * settles into `nodes` routed nowhere and moves no outcome. Either way the run is
+ * over. **This is `stuck`'s point:** before
  * [ADR 0015](../../doc/decisions/0015-a-run-whose-join-can-no-longer-fire-is-stuck.md)
  * a permanently stuck run was `completed`, so a harness waiting on this predicate
  * would have reported the hang as a success rather than waiting forever — which
  * is the worse of the two failures.
+ *
+ * **`cancelling` is the THIRD unfinished outcome since v0.18** (`RN-R12`, `RN-R30`, ADR 0104): the run's owner
+ * cancelled it and a task is still stopping, so its `task.cancelled` is still coming and moves the outcome to
+ * `cancelled`. Calling it terminal would settle a runtime's `done` at the request — before the tasks have stopped,
+ * the app's #1 complaint (P34 fact 6).
+ *
+ * **`interrupted` is TERMINAL, unchanged by v0.19** (`RN-R12`, `RN-R32`, ADR 0105): the run's owner stopped it and the
+ * driver went deaf, so nothing more can move it on THIS runtime — its in-flight set is moved by a resume on another,
+ * which is not this driver's input. A runtime's `done` settles on it once the stop's cancels have resolved (`RN-R33`).
  */
 export declare function isTerminal(s: RunState): boolean;
 /** A node's entry, or `null`. Not an outcome record: it has no `attempts` and no timing fields. */

package/dist/types/src/scheduler/bootstrap.d.ts

@@ -8,7 +8,7 @@
  * decision 5, [W59](../../doc/work-items/w59-what-a-node-type-is.md), [W65](../../doc/work-items/w65-the-registry-document-and-a-node-type-is-a-derivation.md);
  * **and since v0.18 the place a language adapter's WORKER half reaches a typed pool** —
  * [ADR 0051](../../doc/decisions/0051-a-transform-is-a-declared-expression-in-a-registered-language-applied-in-the-types-worker-wrapper.md)
- * rule 4, [W61](../../doc/work-items/w61-what-a-transform-is.md).
+ * rule 4, [W61](../../doc/work-items/w61-what-a-transform-is.md) — into EVERY typed pool since ADR 0096 (W162).
  *
  * **This sub-path is the one place the published package CONSTRUCTS a scheduler object** (`RT-R13`;
  * `createRuntime` in `./runtime.ts` is the other module in it, and it constructs the groups and the
@@ -21,7 +21,8 @@
  * **Since W65 the helper takes the REGISTRY's three sections — `workers`, `nodeTypes`, `pools` —
  * and builds one pool per INSTANCE**: the default instance of every type, keyed by the type's name,
  * and every named instance in `pools`, keyed as declared. Each is the type's derivation run over the
- * instance's config (`derivePool`, the same checks `resolveRegistry` makes), turned into
+ * instance's config — and, since v0.37, a document type's instance's own `pool` options merged over the type's
+ * (ADR 0099) — (`derivePool`, the same checks `resolveRegistry` makes), turned into
  * `WorkerManagerOptions` by `poolOptionsOf` — the type's `inline`, the derived pool fields and
  * groups, and the envelope pool config `{ worker: <the worker entry's url>, config: <the derived
  * config> }` — and handed to the pool factory with the package's envelope worker as its script.
@@ -35,21 +36,23 @@
  * nothing. Since W65 a POOL's groups are what its derivation returned (`groups` and `residentGroups`),
  * which for a document type is what the type declared.
  *
- * **The languages are written into a pool's config ONLY for a type some node of which declares a
- * transform, and only the languages those nodes name** (W61, P17 decision 3): the helper reads the
- * `flows` it is given, collects each type's transforming languages, and writes their WORKER-side
- * module URLs (`LanguageAdapter.worker`) into every instance of that type — a FUNCTION could not cross
- * to a thread and a URL can (P17 fact 7). A type whose nodes never transform gets the two-key pool
- * config it had at v0.17, so no pool loads an engine it does not use. Direction one is a refusal;
- * direction two is NOT — an adapter given that no node names is inert (ADR 0051 rule 4's asymmetry).
+ * **Every pool carries every language it is given** — [ADR 0096](../../doc/decisions/0096-a-runtime-is-its-registry-and-start-refuses-from-runtime-check.md)
+ * rule 2, [W162](../../doc/work-items/w162-a-runtimes-languages-are-its-registrys-and-runtime-check.md),
+ * superseding ADR 0051 rule 4. The helper writes each adapter's WORKER-side module URL
+ * (`LanguageAdapter.worker`) into EVERY pool it builds, under the language's name — a FUNCTION could
+ * not cross to a thread and a URL can (P17 fact 7). It reads no flow: a runtime's pools are built once
+ * and a flow published later may transform on any type, so which types transform is not knowable here.
+ * Given no language, every pool config is the two-key one it had at v0.17 (P18 fact 5).
  */
 import { WorkerManager } from 'fyflow-scheduler';
 import type { ResourceGroup, WorkerManagerOptions } from 'fyflow-scheduler';
-import type { FlowDefinition, Languages, NodeTypes, Pools, ResolvedPool, Workers } from '../definition/types.js';
+import type { Languages, NodeTypes, Pools, ResolvedPool, Workers } from '../definition/types.js';
 /**
- * The script every typed pool loads. Resolved against THIS module, so it is the published
- * package's own file wherever the package is installed; the type's real worker is loaded from
- * inside it (`EnvelopeWorker.setup`).
+ * The script every typed pool loads; the type's real worker is loaded from inside it
+ * (`EnvelopeWorker.setup`). In the source it resolves against THIS module, the package's own file
+ * wherever it is installed — so a bundle built from the JSR source must serve it beside itself. The
+ * npm dist replaces it at build time with the worker itself: a `data:` URL on Node, a `Blob` URL in
+ * the browser (`scripts/build.mjs`, Q580).
  */
 export declare const ENVELOPE_WORKER_URL: string;
 /** A registry that cannot be bootstrapped, and why — thrown before any pool is built. A registry SHAPE defect is a `RegistryError` instead, from `checkRegistry`. */
@@ -70,15 +73,10 @@ export interface BootstrapOptions {
     createPool?: PoolFactory;
     /**
      * **The registry's languages — the same object the driver is handed** (W61). Read for ONE field,
-     * `worker`, and only for the languages some node in `flows` declares on a node of each type.
+     * `worker`, and written into EVERY pool (ADR 0096 rule 2). Omitted or empty, no pool config carries
+     * a `languages` key. *(A `flows` option sat beside this until W162 and is removed — ADR 0096 rule 3.)*
      */
     languages?: Languages;
-    /**
-     * **The flows these pools will run**, read for WHICH types transform in WHICH languages. Omitted,
-     * or naming no transform, every pool config is exactly what it was at v0.17. A node naming a
-     * type this registry lacks is skipped here — it is the driver's `FD-V32`, not this helper's.
-     */
-    flows?: readonly FlowDefinition[];
 }
 export interface BootstrapResult {
     /** One per pool INSTANCE — every type's default instance under the type's name, every named instance under its key — spread into `new FyflowScheduler(...)`'s first argument. */
@@ -88,10 +86,4 @@ export interface BootstrapResult {
     /** What each pool was DERIVED as — the checked spec every pool above was built from, for a caller that reads pools back (ladder L6's observers). */
     derived: Record<string, ResolvedPool>;
 }
-/**
- * **Which languages each type's nodes transform in, over the flows given** — the one reading of a
- * definition this helper makes. Exported so a test can compare what the helper WROTE into pool
- * configs against what the flows DECLARE, both ways (rule 8 obligation (e) on `Registry.languages`).
- */
-export declare function transformLanguagesByType(flows: readonly FlowDefinition[]): ReadonlyMap<string, ReadonlySet<string>>;
 export declare function bootstrap(registry: BootstrapRegistry, groups?: Readonly<Record<string, ResourceGroup>>, options?: BootstrapOptions): BootstrapResult;

package/dist/types/src/scheduler/envelope-worker.d.ts

@@ -10,8 +10,8 @@
  * A `WorkerManager` loads its worker from a script URL and instantiates the module's default
  * export, so a wrapper cannot be a function around a class — it has to BE the script the pool
  * loads. This module is that script: its pool config names the type's real worker (`worker`, a
- * module URL), that worker's own config (`config`), and — for a type some node of which declares
- * a transform — the worker-side module URL of each language those nodes name (`languages`); this
+ * module URL), that worker's own config (`config`), and the worker-side module URL of every language
+ * the registry names (`languages` — every typed pool's since ADR 0096, W162); this
  * class loads the inner worker and the language modules in `setup()`, evaluates the envelope's
  * `transform` in `run()` when one is present, hands the inner worker **exactly `{ settings, input }`**
  * with `input` REPLACED by the evaluation's result, and tears the inner worker down with itself.
@@ -74,8 +74,8 @@ export interface EnvelopePoolConfig {
     config?: unknown;
     /**
      * **Language name → worker-side module URL** (`LanguageAdapter.worker`), written by the bootstrap
-     * helper ONLY for a type some node of which declares a `transform`, and only for the languages
-     * those nodes name — so a pool whose nodes never transform loads no engine. Loaded in `setup()`,
+     * helper into EVERY pool, for every language it is given — ADR 0096 rule 2 (W162), superseding
+     * ADR 0051 rule 4's *only for a type some node of which declares a transform*. Loaded in `setup()`,
      * once per worker instance; each module's default export is `compile(expr) => { evaluate(input,
      * settings) }`.
      */
@@ -188,7 +188,8 @@ export default class EnvelopeWorker {
     /** One language's worker half, or the Error that stands in for it — never a throw (see `setup()`). */
     private loadLanguage;
     /**
-     * `FD-C5`: the inner worker receives `{ settings, input }` and nothing else. `FD-C6`: when the
+     * `FD-C5`: the inner worker receives `{ settings, input }` as its payload, and the scheduler's task context as its
+     * second argument, passed through untouched (W159). `FD-C6`: when the
      * envelope carries a `transform`, `input` is the evaluation of that expression over the value
      * received, with the node's settings bound as `$settings`, and the third key is consumed here.
      */

package/dist/types/src/scheduler/index.d.ts

@@ -5,9 +5,9 @@
  * for everything else. Since v0.18 (W61, ADR 0051) the envelope worker here also evaluates a
  * node's declared `transform`, and `TransformFailed` is what a task fails with when it cannot.
  */
-export { bootstrap, BootstrapError, ENVELOPE_WORKER_URL, transformLanguagesByType } from './bootstrap.js';
+export { bootstrap, BootstrapError, ENVELOPE_WORKER_URL } from './bootstrap.js';
 export type { BootstrapOptions, BootstrapRegistry, BootstrapResult, PoolFactory } from './bootstrap.js';
-export { BUILT_IN_GROUP_FACTORIES, createRuntime, GROUP_MEMBERS, GroupNotBuildable, GroupUnusable, LanguageNotBuilt, RunIdInUse, RuntimeError } from './runtime.js';
+export { BUILT_IN_GROUP_FACTORIES, createRuntime, GROUP_MEMBERS, GroupNotBuildable, GroupUnusable, LimitKeyMissing, RunIdInUse, RuntimeError } from './runtime.js';
 export type { ResumeOptions, RunHandle, Runtime, RuntimeOptions, RuntimeRegistry, StartOptions } from './runtime.js';
 export { default as EnvelopeWorker, NotAnEnvelope, TransformFailed, unpackEnvelope } from './envelope-worker.js';
 export type { Envelope, EnvelopePoolConfig } from './envelope-worker.js';