fyflow-orchestration 0.7.0 → 0.9.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/accumulator.d.ts

@@ -0,0 +1,94 @@
+import type { FoldInput, NodeRun, RunOutcome, RunState } from './run-state.js';
+/**
+ * **A count of the work an accumulator did** — P39 decision 6 and stop-and-ask (e): one per input applied, and one per
+ * entry, element or cell it reads or writes while loading, copying or materialising. Clock-free, so a ratio of two
+ * counts is a property of the code and not of a machine (Q179). Owned by the caller; absent, nothing is counted.
+ */
+export interface FoldCounter {
+    visits: number;
+}
+export declare class Accumulator {
+    private runId;
+    private outcome;
+    private haltedBy;
+    private cancelRequest;
+    private interruption;
+    private paused;
+    /** Entries written since the load, by task id, in first-write order. A task id not here reads through to the base. */
+    private readonly nodes;
+    /** Instances touched since the load, by opener and then by the opener's branch path, in first-touch order. */
+    private readonly regions;
+    private readonly pathEnds;
+    private readonly resumes;
+    private readonly gated;
+    private counts;
+    private readonly base;
+    private readonly counter;
+    private constructor();
+    /** An accumulator over `state`, which it reads and never mutates. `counter`, when given, is charged for its work. */
+    static load(state: RunState, counter?: FoldCounter): Accumulator;
+    private tick;
+    /**
+     * **The outcome as the last applied input left it** — what {@link materialise} would write into `outcome`, read in
+     * O(1). The runtime's `RunHandle.outcome()` and `done`'s predicate read this, never a materialisation (P39 prediction 4).
+     */
+    outcomeNow(): RunOutcome;
+    /**
+     * **One task's entry, or `undefined`** — the object {@link materialise} would place at `nodes[taskId]`, read in O(1).
+     * An OWN entry only: a task id naming an `Object.prototype` member (`toString`, `__proto__`) is a task the run never
+     * dispatched, where `prev.nodes[taskId]` on a plain record would read the inherited member.
+     */
+    entry(taskId: string): NodeRun | undefined;
+    /** `prev.nodes[taskId]` — the entry written since the load, else the base's own read, prototype and all. */
+    private node;
+    /** `prev.regions[regionId]?.[regionPath]` — the touched instance, else the base's. */
+    private instance;
+    /** The counts, taken from everything the state holds on first need — O(the state), once per accumulator. */
+    private tally;
+    private countNode;
+    private stateCount;
+    /** `nodes[taskId] = entry`, the counts kept. An entry is REPLACED, never mutated: a materialised state may hold the old one. */
+    private setNode;
+    /**
+     * The instance at (`regionId`, `regionPath`) to write to — the touched one, else a COPY of the base's (O(its branch
+     * paths), once), else an empty one; with its share of the region counts taken out, for {@link settleRegion} to put back.
+     */
+    private touchRegion;
+    private unweigh;
+    /** The instance's share of the region counts put back after a write. */
+    private settleRegion;
+    private addPathEnd;
+    /**
+     * **Apply one input.** `true` when the arm moved the state — where `step` before W194 returned a NEW object — and
+     * `false` where it returned the state it was handed, so `step` can return that same object. Throws where
+     * that `step` threw: a malformed task id (`parseTaskId`), a kind it does not name (`input.record` undefined) — within
+     * the module header's stated limit on region paths.
+     */
+    apply(input: FoldInput): boolean;
+    private applyRegion;
+    /**
+     * **Section 3's precedence, read off the counts** — `RN-R7`, `RN-R8`, `RN-R10`, `RN-R28`, `RN-R30` and `RN-R32` in the
+     * one order they have always had. Called by exactly the arms that recomputed before W194. Always `true`: an arm that
+     * recomputes has moved the state.
+     */
+    private withOutcome;
+    private precedence;
+    /**
+     * **One plain `RunState`**, built from the base and what was written since the load: a record or list nothing wrote is
+     * the base's own object, and one that was written is a new one with the base's entries in their places and the new
+     * entries after them, in first-write order — the key order a spread-per-step produced. O(what it builds).
+     */
+    materialise(): RunState;
+    private list;
+    private materialiseRegion;
+}
+/**
+ * **The fold, with its work counted** — the INTERNAL entry point P39 decision 6 names: `fold` is this with no counter.
+ * One accumulator, every input applied in append order (`RN-R3`), materialised once: linear in `inputs`.
+ */
+export declare function foldWith(inputs: readonly FoldInput[], counter?: FoldCounter): RunState;
+/**
+ * **One step, with its work counted** — `step` is this with no counter: load, apply, materialise, and the state it was
+ * handed itself back wherever the arm moves nothing. O(the state it is handed).
+ */
+export declare function stepWith(prev: RunState, input: FoldInput, counter?: FoldCounter): RunState;

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

@@ -6,18 +6,29 @@
  * ladder L3 checks by folding the same log twice and deep-comparing, and it is
  * what makes [Q14](../../doc/questions/q14.md)'s answer an answer rather than a
  * restated leaning.
+ *
+ * **Since v0.29 the arms live in ONE place, `src/fold/accumulator.ts`** (`RN-R43`,
+ * [ADR 0120](../../doc/decisions/0120-the-fold-is-one-accumulator-and-step-stays-pure.md)): an accumulator mutated in
+ * place WITHIN one call and materialised into a plain state, so nothing survives a call and `RN-R1` holds as before.
+ * This module keeps the types, `emptyState`, `isTerminal`, `nodeOf` and `foldLog`, and `fold` and `step` call into it.
+ * That module is internal: `index.ts` re-exports this one and never it.
  */
 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 +37,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' | '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 type RunOutcome = 'running' | 'completed' | 'failed' | 'awaiting_action' | 'stopped' | 'stuck';
+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 +182,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 +283,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 +337,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 +366,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,17 +471,61 @@ 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
- * what lets `RN-R2` hold (folding a prefix then one more record equals folding the
+ * One step. **Never mutates the state it was given, and returns a NEW one wherever the input moves something** — and
+ * that state ITSELF where it moves nothing (below) — which is what lets `RN-R2` hold (folding a prefix then one more record equals folding the
  * whole) and what makes a fold usable while a run is still going.
+ *
+ * **Its work is O(the state it is handed), not O(the input)** — `RN-R43`, v0.29,
+ * [ADR 0120](../../doc/decisions/0120-the-fold-is-one-accumulator-and-step-stays-pure.md): it loads `prev` into the
+ * fold's one accumulator, applies the input and materialises a new plain state, and a pure function from one plain
+ * `RunState` to another cannot do less than copy the record it changes. So stepping every input of a long run costs
+ * O(run) per input; {@link fold} over the whole sequence is linear. A consumer that needs a run's state after every input
+ * reads it where a runtime keeps it, rather than stepping a copy of its own.
+ *
+ * **Each arm behaves on ANY state it is handed exactly as it did before v0.29** — not only on one a fold can reach. The
+ * outcome is recomputed only by the arms that recomputed it, so a hand-built state whose `outcome` disagrees with its
+ * cells keeps that outcome across `paused`, `unpaused`, `gated`, `attempted` and a `resumed` that ends no stop; and an
+ * input that moves nothing — a second cancel request, or one after the run is already `cancelled`, a second stop or
+ * pause, an unpause of a run not paused, a dispatch or an ask of a
+ * task already in `nodes`, a region instance already entered, an attempt of a task not in `nodes` — hands back `prev`
+ * ITSELF. A cell no input touched is `prev`'s own object in the result. (Its one stated limit, a region path naming an
+ * `Object.prototype` member, which no driver appends, is `src/fold/accumulator.ts`'s header's.)
  */
 export declare function step(prev: RunState, input: FoldInput): RunState;
 /**
  * The fold. `RN-R2`: total over any prefix, so `fold(log.slice(0, n))` is defined
- * for every `n` and `step(fold(prefix), next) === fold(prefix + next)`.
+ * for every `n` and `step(fold(prefix), next)` deep-equals `fold(prefix + next)`.
+ *
+ * **Linear in its inputs** — `RN-R43`, v0.29, [W194](../../doc/work-items/w194-the-fold-is-one-accumulator.md): ONE
+ * accumulator (`src/fold/accumulator.ts`, internal) has every input applied to it in place and is materialised into a
+ * plain state once, at the end. Before v0.29 this was a `step` per input, each copying the run, so a fold was quadratic
+ * in its run — 30 s for a 4,000-item map (P39 fact 1). What it returns is unchanged on every sequence whose region paths are branch paths (P39 decision 5; `RN-R43`'s one stated limit).
  *
  * `RN-R3`: read in **append order**, never sorted. Two settlements can share a
  * millisecond; `schedulerTimestamp` is the scheduler's clock and `observedAt` is
@@ -292,14 +538,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. */