fyflow-orchestration 0.8.0 → 0.9.0

package/dist/node/index.js

@@ -143,7 +143,7 @@ import {
   violatedRules,
   witness,
   workersOf
-} from "./chunks/chunk-EUU44PHD.js";
+} from "./chunks/chunk-3U4UZC34.js";
 
 // src/definition/assist.ts
 var TYPES = ["object", "array", "string", "number", "integer", "boolean", "null"];

package/dist/node/scheduler/index.js

@@ -1,4 +1,5 @@
 import {
+  Accumulator,
   BUILT_IN_NODE_TYPES,
   ConfigRefused,
   Driver,
@@ -22,10 +23,9 @@ import {
   resolveRegistry,
   resumeRefusal,
   retryPolicyProblem,
-  step,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-EUU44PHD.js";
+} from "../chunks/chunk-3U4UZC34.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";
@@ -281,14 +281,50 @@ function createRuntime(document, code = {}, options = {}) {
     const done = new Promise((resolve) => {
       settle = resolve;
     });
-    let state = emptyState();
+    const acc = Accumulator.load(emptyState());
+    let cached = null;
+    const frozen = /* @__PURE__ */ new WeakSet();
     let settled = false;
     let seed = from === null ? null : from.events;
+    const own = (input) => {
+      if (input.kind !== "outcome" && input.kind !== "resolution") return input;
+      const r = input.record;
+      return typeof r.result === "object" && r.result !== null ? { kind: input.kind, record: structuredClone(r) } : input;
+    };
+    const take = (input) => {
+      if (acc.apply(own(input))) cached = null;
+    };
+    const catchUp = () => {
+      if (seed === null) return;
+      for (const stored of seed) take(stored);
+      seed = null;
+    };
+    const freezeDeep = (root) => {
+      const stack = [root];
+      while (stack.length > 0) {
+        const v = stack.pop();
+        if (typeof v !== "object" || v === null || frozen.has(v)) continue;
+        frozen.add(v);
+        if (ArrayBuffer.isView(v)) continue;
+        if (v instanceof Map) for (const [k, x] of v) stack.push(k, x);
+        else if (v instanceof Set) for (const x of v) stack.push(x);
+        for (const k of Reflect.ownKeys(v)) {
+          const d = Object.getOwnPropertyDescriptor(v, k);
+          if (d !== void 0 && "value" in d) stack.push(d.value);
+        }
+        Object.freeze(v);
+      }
+      return root;
+    };
+    const current = () => {
+      catchUp();
+      return cached ??= freezeDeep(acc.materialise());
+    };
     const settleIfTerminal = () => {
-      if (settled || !isTerminal(state)) return;
+      if (settled || !isTerminal({ outcome: acc.outcomeNow() })) return;
       settled = true;
-      if (state.outcome === "interrupted" && stopping.size > 0) {
-        const at = state;
+      const at = current();
+      if (at.outcome === "interrupted" && stopping.size > 0) {
         const fin = () => {
           settle(at);
           router.release(runId);
@@ -296,7 +332,7 @@ function createRuntime(document, code = {}, options = {}) {
         void Promise.allSettled([...stopping]).then(fin);
         return;
       }
-      settle(state);
+      settle(at);
       router.release(runId);
     };
     const view = router.forRun(runId);
@@ -333,11 +369,8 @@ function createRuntime(document, code = {}, options = {}) {
       // of a run from its first, and it is the well-formed wrong answer the first time a driver's
       // sequence does not start at this callback's first call.
       onFoldInput: (input, seq) => {
-        if (seed !== null) {
-          for (const stored of seed) state = step(state, stored);
-          seed = null;
-        }
-        state = step(state, input);
+        catchUp();
+        take(input);
         queueMicrotask(settleIfTerminal);
         startOptions.onFoldInput?.(input, seq);
       },
@@ -361,7 +394,22 @@ function createRuntime(document, code = {}, options = {}) {
       router.release(runId);
       throw e;
     }
-    return { driver, done, header: driver.checkpoint().header, stop: (stopOptions) => driver.stop(stopOptions) };
+    return {
+      driver,
+      done,
+      header: driver.checkpoint().header,
+      stop: (stopOptions) => driver.stop(stopOptions),
+      state: current,
+      outcome: () => {
+        catchUp();
+        return acc.outcomeNow();
+      },
+      node: (taskId) => {
+        catchUp();
+        const entry = acc.entry(taskId);
+        return entry === void 0 ? null : freezeDeep(entry);
+      }
+    };
   }
 }
 function settlementRouter(scheduler) {

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

@@ -939,13 +939,21 @@ export declare class Driver {
      * channels with no shared order, so `RN-R3`'s *"read in append order"* was about
      * a value no one could hold.
      *
-     * `log` above is the **record-kind subsequence of this array**, kept as its own
-     * array only because `effectiveOutcome` and `isSuspended` scan it on every
-     * settlement and rebuilding it by filter each time is quadratic. It holds the
-     * same record objects, never copies. `test/driver/` asserts the two agree, so
-     * the redundancy is checked rather than trusted.
+     * `log` above is the **record-kind subsequence of this array**, by reference — the
+     * same record objects, never copies; `test/driver/` asserts the two agree, so the
+     * redundancy is checked rather than trusted. *(It was kept "only because
+     * `effectiveOutcome` and `isSuspended` scan it on every settlement" until W195,
+     * whose {@link TaskLog} hands each of them one task's records instead — P39 fact 5.
+     * It stays for what still reads it WHOLE and in order: `snapshot()`, `outputs()`'s
+     * catch-up, and the retention walk's alias check.)*
      */
     private readonly inputs;
+    /**
+     * **Each task's records, by reference and in append order** — {@link TaskLog}, `RN-R13` v0.30, ADR 0121 (W195). Written in
+     * `append` beside `log`; read by every per-task question the driver asks of its log — `advance`, `parked`, `hasParked`,
+     * `inFlight`, `outputs()`, `effectiveOutcomeOf` — so each costs the task, never the run.
+     */
+    private readonly taskLog;
     private readonly graph;
     private readonly regions;
     private readonly dispatched;
@@ -1687,7 +1695,7 @@ export declare class Driver {
      * [ADR 0040](../../doc/decisions/0040-what-a-node-can-reach-is-the-runs-own-outputs-and-a-node-id-names-them-relative-to-a-branch-path.md)
      * rules 2 and 3, and `FD-C2`.
      *
-     * **It is a PROJECTION of the log and adds no retention** — measured at
+     * **It is a PROJECTION of the log and adds no retention of a result** — measured at
      * [P12](../../doc/plans/p12-what-a-node-receives-and-what-a-decision-sees.md)'s
      * declaration and again before this was written: this driver holds
      * `private readonly log: LogRecord[]` with exactly one `push` and no `splice`,
@@ -1697,14 +1705,11 @@ export declare class Driver {
      * described **today** before this method existed, and this adds **no retention**.
      * *(Q19 is RESOLVED since W53 —
      * [ADR 0046](../../doc/decisions/0046-a-run-retains-what-its-tasks-returned-and-a-region-releases-its-collection-when-its-join-becomes-terminal.md)
-     * — and `RN-R13` names this memo by id: it holds results **by reference only**,
+     * — and `RN-R13` names `outputsCache` by id: it holds results **by reference only**,
      * asserted by IDENTITY at ladder L2 rather than by a byte count, because a
      * reachability SET cannot tell an alias from a copy. W53's readers found that
      * from both ends — the rule's stated test returned a third name on a `needs`
      * flow, and cloning here cost ZERO.)*
-     * *(It adds ONE field — `outputsCache` below — which is a memo the log invalidates
-     * and which holds nothing the log does not. This read *"zero fields"* until W41's
-     * conformity reader read it beside the memo the cost measurement had just added.)*
      *
      * **`effectiveOutcome` and not the raw record**, for `spec/flow-definition.md`
      * section 3 rule 4's own reason: a resumed node has two records in the log and
@@ -1712,19 +1717,46 @@ export declare class Driver {
      * suspended has no effective outcome and therefore no entry — which is what makes
      * `FD-R3` fire rather than a reference quietly resolving to `undefined`.
      *
-     * **Computed on demand rather than maintained**, and the cost is why: it is
-     * `O(log)` per call, so maintaining it would be a second source that could
-     * disagree with the log — the defect [Q43](../../doc/questions/q43.md) and
-     * `arrival-count`'s re-sourcing are each an instance of. **A node that declares no
-     * `needs` never reaches this method**, which is what keeps ADR 0040 rule 1's *the
-     * default is unchanged* true of the cost as well as of the value.
+     * **CAUGHT UP rather than rebuilt** — `RN-R13` v0.30, P39 decision 4 and fact 7,
+     * [ADR 0121](../../doc/decisions/0121-the-driver-keeps-a-per-task-view-of-its-log.md) (W195), amending ADR 0040
+     * rule 2's *computed rather than maintained*. Until W195 this was memoised on the log's LENGTH and rebuilt from the
+     * WHOLE log whenever the log had grown — so a node with a `needs` entered once per settlement, which is every instance
+     * of a `map` whose branch declares one, paid O(log) per entry and the run O(log²): the case its own memo missed by
+     * construction. Now each call reads only the records appended since the last (`at`, an index into the append-only
+     * `log`), and for each one asks `effectiveOutcome` of THAT TASK's records ({@link TaskLog}) — so the merge stays in
+     * ONE place, which is ADR 0040 rule 2's own reason, and an entry is always the merge of its task's whole sub-log at
+     * the moment of the call: nothing here can say what the log does not. **Equal to a rebuild at every read**
+     * (`test/driver/log-view.test.ts`, at every fold input of every valid corpus flow): the same entries, a node's list
+     * in its tasks' first-record order, each `result` the log record's own object.
+     *
+     * **Still LAZY, so ADR 0040 rule 1's *the default is unchanged* holds of the cost**: nothing is caught up until a
+     * node or an edge that declares a `needs` asks, and a run that declares none never builds it.
      */
     private outputs;
     /**
-     * The memo above. **Not run state and not a second copy of it** — it is discarded
-     * and rebuilt the moment the log grows, and nothing ever reads it without checking
-     * the length first, so there is no state here that could be stale in a way anything
-     * could observe. `ADR 0014`'s *the driver computes no run state* is untouched.
+     * **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
+     * 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
+     * RESOLUTION, later, gives it one: that is the one entry that is not appended at the END of its node's list but placed
+     * at its first record's position — reachable, and the corpus's *parked, attempted, resolved* drain reaches it. *(Whether
+     * a suspended node's ABSENCE is ever read: no — W41's adequacy reader measured making it contribute
+     * `{result: undefined}` cost **0**, because every shipped policy leaves a parked branch holding a token, so no join
+     * fires while one is parked and no reader downstream of it is entered. [Q97](../../doc/questions/q97.md).)* An entry
+     * that LOSES its effective outcome is removed — **reachable**: `ID-R4` asks only whether a settlement's id was dispatched,
+     * so a settlement event repeated for a settled task is appended, and a `done` then a `user_action` leaves the task with
+     * none (W195's conformity reader, C4; `test/driver/log-view.test.ts` drives it and the resolution that places it again).
+     */
+    private place;
+    /**
+     * The projection above, CAUGHT UP to `at` — `RN-R13` v0.30, ADR 0121 (W195). **Not run state and not a second copy of
+     * it**: `byNode`'s entries hold each result BY REFERENCE (the log record's own object) — so it is a holder of results and
+     * never a copy — `tasks` is one slot per task id
+     * read — its node, its path, its first-record position and its current entry — and `orders` the same positions, per
+     * node, parallel to its list. Everything here is the merge `effectiveOutcome` computed from the task's own records at the moment they were
+     * read, and `at` says which records have been; so there is nothing here that could disagree with the log. `ADR 0014`'s
+     * *the driver computes no run state* is untouched. `null` until a `needs` first asks.
      */
     private outputsCache;
     /**
@@ -1980,7 +2012,9 @@ export declare class Driver {
      *
      * A record is pushed to `log` as well, by reference: `effectiveOutcome` reads
      * the stored object and `OR-R8` derives rather than appends, so a second copy
-     * here would be a second truth. What leaves through `onFoldInput` **is** a
+     * here would be a second truth. **And to its task's sub-log in {@link TaskLog}**,
+     * by reference too (`RN-R13` v0.30, ADR 0121, W195) — here, the one place every
+     * element passes, so the view can never lag the log. What leaves through `onFoldInput` **is** a
      * copy, frozen, for the same reason `snapshot()` is: a listener holding the
      * driver's own array could forge a settlement and bypass `RS-R1`.
      */

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/run-state.d.ts

@@ -6,6 +6,12 @@
  * 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';
@@ -491,14 +497,35 @@ export type FoldInput = {
 };
 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

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

@@ -65,7 +65,7 @@ import { FyflowScheduler } from 'fyflow-scheduler';
 import type { ResourceGroup, WorkerManager } from 'fyflow-scheduler';
 import { Driver } from '../driver/driver.js';
 import type { Checkpoint, CheckpointHeader, DriverOptions, RunStopOptions } from '../driver/driver.js';
-import type { RunState } from '../fold/run-state.js';
+import type { NodeRun, RunOutcome, RunState } from '../fold/run-state.js';
 import type { Finding, FlowDefinition, JsonSchema, RegistryCode, RegistryDocument, ResolvedPool, ResolvedRegistry, RetryPolicy, TaskNode } from '../definition/types.js';
 import type { PoolFactory } from './bootstrap.js';
 /**
@@ -291,12 +291,17 @@ export interface RunHandle {
      * element: the stopped driver is deaf, so no settlement could move the fold again, and the runtime waits on the cancels
      * the driver sent through this run's view of the scheduler instead (`RN-R33`, ADR 0105, amending ADR 0058 rule 3).
      *
-     * It is the SAME expression a consumer would have written, moved: the runtime keeps ONE
-     * `RunState` and `step`s it per fold input, which is what `fold` is
-     * (`for (const i of inputs) s = step(s, i)`), and `RN-R2` is the rule that says a stepped prefix
-     * equals a fold of that prefix. `test/scheduler/runtime.test.ts` holds `await done` equal to
-     * `fold(driver.foldInputs())` — the caller's own expression over the driver's own sequence, which
-     * is a second route rather than a second definition.
+     * It is the SAME expression a consumer would have written, moved: the runtime keeps the fold's ONE accumulator OPEN —
+     * W194's, `fold`'s own definition (`RN-R43`) — and applies each fold input to it, which is what `fold` does over a
+     * whole sequence; `RN-R2` is the rule that says a prefix applied equals a fold of that prefix. *(Until W196 it kept ONE
+     * `RunState` and `step`ped it per input — O(run) a step since W194, so O(run²) a run; ADR 0122 amends ADR 0058 rule 5.)*
+     * `test/scheduler/runtime.test.ts` holds `await done` equal to `fold(driver.foldInputs())` — the caller's own
+     * expression over the driver's own sequence, which is a second route rather than a second definition.
+     *
+     * **It resolves with the SAME frozen object {@link RunHandle.state} returns at that moment** — P39 (f), `RN-R44`: one
+     * copy and one definition, so `await done === handle.state()` once it has settled (but for an `unpause` after it — see
+     * `state`). **BREAKING in 0.9.0 for code that
+     * MUTATES `await done`**: it is frozen at every depth, and a write throws in strict code.
      */
     readonly done: Promise<RunState>;
     /**
@@ -329,6 +334,33 @@ export interface RunHandle {
      * store holds whichever is written first (`RN-R18`).
      */
     readonly header: CheckpointHeader;
+    /**
+     * **The run's state NOW — a frozen copy, cached until the next fold input that moves it** — `RN-R44`,
+     * [ADR 0122](../../doc/decisions/0122-a-runtimes-live-state-is-a-frozen-copy-on-its-handle.md), P39 (b). Equal to
+     * `fold(driver.foldInputs())` at a quiescent point (`RN-R12`: read it on a `queueMicrotask` after an `onFoldInput`, or
+     * outside the driver's turn — mid-turn it is a prefix, which the fold is total over and which may read terminal while
+     * the run is not). **Frozen at every depth** — a write to it throws in strict code and reaches nothing the runtime keeps
+     * — and **the SAME object on every read until an input moves the state**, so reading it twice costs one copy. It is NOT
+     * a live view (ADR 0007's hazard): a read is the state at that moment, and the next input makes a new one beside it.
+     *
+     * **Its cost is O(run) for the first read after each input that moved the state** — a materialisation of every
+     * `nodes` entry — so reading it after EVERY input costs O(run²) over a run (P39 prediction 4). Read
+     * {@link RunHandle.outcome} and {@link RunHandle.node} per input; read this when you draw the run. On a RESUMED run it
+     * holds the stored events too: they are applied before the first delivered input, which `resume()` always delivers
+     * before it returns (`RN-R22`). After `done` settles it is the object `done` resolved with — until an `unpause` of a run
+     * that finished while paused, the one run control a finished run takes (`RN-R35`): `state()` follows that element and
+     * `done` keeps the state at settlement. What `Object.freeze` does not stop — a typed array's elements, an
+     * `ArrayBuffer`'s bytes, a `Date`'s time, a `Map`'s or a `Set`'s membership — stays writable through a read and reaches
+     * later reads: the stated limit (`RN-R44`). **BREAKING in 0.9.0 for code that BUILDS a `RunHandle`** (P39 (d)) — with `outcome` and `node`.
+     */
+    state(): RunState;
+    /** **The run's outcome now, in O(1)** — `state().outcome` without the copy (`RN-R44`); the read to make after every input. */
+    outcome(): RunOutcome;
+    /**
+     * **One task's entry now, in O(1) in the run, or `null`** — `state().nodes[taskId]`, the same frozen object, without
+     * materialising the rest (`RN-R44`); the first read of an entry freezes it once, O(the entry). `null` for a task the run never dispatched or asked, whatever the id names (`toString` included).
+     */
+    node(taskId: string): NodeRun | null;
 }
 export interface Runtime {
     /** **Exactly the object this runtime hands its own drivers** (decision 14) — spread it into `new Driver(…)` beside a `runId`, a `scheduler` and a `joinPolicy` and you have built what `start` builds. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fyflow-orchestration",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Flow orchestration over fyflow-scheduler: sequence, decision, fan-out and join",
   "keywords": [
     "workflow",