fyflow-orchestration 0.7.0 → 0.9.0

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';

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

@@ -50,19 +50,23 @@
  * `bootstrap`, every declared one goes to the scheduler — and direction ONE (a pool naming a group
  * the document lacks) is untouched, refused by the resolver before anything is built.
  *
- * **Why `flows` is an argument here.** A language adapter's worker half reaches a typed pool through
- * that pool's config, and W61 measured that it is written ONLY where a node of that type declares a
- * transform — so the same type carries the engine on one flow and not on another. Pools are built
- * once, at `createRuntime`, so the flows a runtime will run are named there; `start` REFUSES a flow
- * whose transforming type was not accounted for, naming the type, the language and the fix, rather
- * than letting the wrapper meet a transform with nothing to evaluate it.
+ * **Why there is no `flows` argument here, and what `check` is** —
+ * [ADR 0096](../../doc/decisions/0096-a-runtime-is-its-registry-and-start-refuses-from-runtime-check.md),
+ * [W162](../../doc/work-items/w162-a-runtimes-languages-are-its-registrys-and-runtime-check.md). A runtime IS its
+ * registry: its pools are built once, here, and `fyflow-scheduler` cannot add one later (P37 fact 8). Until W162 a
+ * language reached a pool only where a node of that type transformed in a flow given here as `flows`, and `start`
+ * refused any other flow's transform (`LanguageNotBuilt`) — so a flow published after the runtime started could not
+ * transform on a type no earlier flow had. Now EVERY typed pool carries every language the registry names, and a flow
+ * needs nothing passed in advance. **`check(flow)`** returns every finding `start` would refuse that flow on that
+ * depends on the flow and this runtime alone, and **`start` and `resume` refuse from that same call**, so the two
+ * cannot disagree.
  */
 import { FyflowScheduler } from 'fyflow-scheduler';
 import type { ResourceGroup, WorkerManager } from 'fyflow-scheduler';
 import { Driver } from '../driver/driver.js';
-import type { Checkpoint, CheckpointHeader, DriverOptions } from '../driver/driver.js';
-import type { RunState } from '../fold/run-state.js';
-import type { FlowDefinition, JsonSchema, RegistryCode, RegistryDocument, ResolvedPool, ResolvedRegistry, RetryPolicy, TaskNode } from '../definition/types.js';
+import type { Checkpoint, CheckpointHeader, DriverOptions, RunStopOptions } from '../driver/driver.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';
 /**
  * **A runtime that cannot be built, and why** — thrown at `createRuntime` or at `start`, before
@@ -81,9 +85,6 @@ export declare class GroupUnusable extends RuntimeError {
 /** A group type named by the document has no factory: a built-in this module does not implement, or a `code.groupTypes` entry `resolveRegistry` admitted and this cannot call. */
 export declare class GroupNotBuildable extends RuntimeError {
 }
-/** `start` was given a flow whose transforming type runs on pools this runtime built without that language — the pool would meet the transform with nothing to evaluate it. */
-export declare class LanguageNotBuilt extends RuntimeError {
-}
 /**
  * **A `start` or a `resume` naming a run id a driver of THIS runtime already holds** — `RN-R25`,
  * [ADR 0065](../../doc/decisions/0065-a-resume-replays-the-stored-stimuli-refuses-what-it-cannot-regenerate-and-re-dispatches-what-was-in-flight.md),
@@ -93,6 +94,17 @@ export declare class LanguageNotBuilt extends RuntimeError {
  */
 export declare class RunIdInUse extends RuntimeError {
 }
+/**
+ * **A `start` or a `resume` given no `createTask`, of a flow a node of which reaches a group the BUILT-IN
+ * `KeyedRateLimitGroup` factory built** — `FD-R6`,
+ * [ADR 0097](../../doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md), P37 fact 1 and
+ * stop-and-ask (c). That factory gives the group no `keyFrom`, so its key is the task's `limitKey`, which nothing here
+ * sets — and the scheduler THROWS in `addTask` for a keyed group with no key. `at` is the first such node in the flow's
+ * order; the message carries every `FD-R6` finding `check` returned. Thrown before a run id is minted or a driver built,
+ * so the refused call costs nothing.
+ */
+export declare class LimitKeyMissing extends RuntimeError {
+}
 /**
  * **The three built-in group types' FACTORIES, and they are three different constructors** (P18
  * fact 2, re-run at W66): `(limit, id)`, `(windows, id)` and `(windows, { id })`, the third keyed.
@@ -109,6 +121,10 @@ export declare const BUILT_IN_GROUP_FACTORIES: Readonly<Record<string, (config:
  * **What a created group must carry.** The first three are what the scheduler CALLS on the acquire
  * path, the last three what the interface requires and a viewer reads — the union, by the
  * maintainer's decision at W66's declaration step. `EventTarget` is deliberately not required.
+ * **The `why` strings say "measured on 0.5.2" and stay dated**: W157 re-read the current pin's source
+ * rather than re-running the table above — `onStart`/`onFinish` are still optional in
+ * `ResourceGroup` (`groups/resourceGroup.ts:114`, `:117`) and still called unguarded
+ * (`core/FyflowScheduler.ts:894`, `:976`), so S10 stands unchanged.
  */
 export declare const GROUP_MEMBERS: readonly {
     readonly name: string;
@@ -124,16 +140,17 @@ export interface RuntimeOptions {
      * ([Q261](../../doc/questions/q261.md)), which is why the runtime cannot guess it.
      */
     base?: string;
-    /**
-     * **The flows this runtime will run**, read for WHICH types transform in WHICH languages (W61).
-     * A flow given to `start` that names a transform on a type no pool was built for is refused.
-     */
-    flows?: readonly FlowDefinition[];
     /** The pool seam, as `bootstrap`'s — omitted, a real `WorkerManager`. */
     createPool?: PoolFactory;
     /** The scheduler seam. Omitted, a real `FyflowScheduler` over the pools and groups this runtime built. */
     createScheduler?: (pools: Record<string, WorkerManager>, groups: Record<string, ResourceGroup>) => FyflowScheduler;
-    /** Applied to every node of every flow this runtime starts that declares no `retryPolicy` and whose type declares none — the driver's option, held to `FD-V30` there. */
+    /**
+     * Applied to every node of every flow this runtime starts that declares no `retryPolicy` and whose type declares none —
+     * the driver's option. **Held to `FD-V30` HERE, at `createRuntime`**, before anything is built — `InvalidDefinition`,
+     * the class and message `new Driver` throws for it ([ADR 0097](../../doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md)
+     * rule 5, P37 stop-and-ask (b)): until W163 it was read only by each driver, so a malformed one was accepted here and
+     * every `start` threw.
+     */
     defaultRetryPolicy?: RetryPolicy;
     /** `FD-R4`'s switch, forwarded to every driver this runtime starts (W73): the payload at `start` and a person's resolution at `resolve`, each held to the worker's schema once. Default ON; `false` turns both off runtime-wide, since the schemas are the document's. */
     validateBoundaries?: boolean;
@@ -168,7 +185,7 @@ export interface RuntimeOptions {
  * `createRuntime` could reach** ([Q297](../../doc/questions/q297.md), [W71](../../doc/work-items/w71-the-reference-stops-teaching-a-fake-scheduler.md)).
  * Of the eighteen members AS THEY STOOD a consumer reaches **two** because the runtime supplies them (`runId`,
  * `scheduler`), **six** through `RuntimeRegistry`, **two** through `RuntimeOptions` — and only two,
- * because `base`, `flows`, `createPool` and `createScheduler` are the runtime's own and are not
+ * because `base`, `flows` (as it stood: W162 removed it), `createPool` and `createScheduler` are the runtime's own and are not
  * `DriverOptions` members at all — and **seven** through this `Pick` as it stood. 2 + 6 + 2 + 7 is
  * seventeen; the eighteenth was `onRegionEvent`. *P20 fact 1 states the third road as SIX, which
  * makes its table 21 slots over 18 members and therefore not a partition at all; what survives is
@@ -187,8 +204,21 @@ export interface RuntimeOptions {
  * `Pick` and not in `RuntimeOptions` beside `validateBoundaries`: that one is a POLICY every driver
  * a runtime starts inherits, and this one names a `runId`. The orphan count stays **0** and its pin
  * moved 18 to 19 in the same diff, which is what the test's own comment asks for.
+ *
+ * **`onHeader` is the TWENTY-FIRST `DriverOptions` member and the twelfth here** — `RN-R39`,
+ * [ADR 0112](../../doc/decisions/0112-a-run-delivers-its-header-before-its-first-event.md), P36 (d),
+ * [W185](../../doc/work-items/w185-the-header-before-the-first-event.md). A DRIVER member, because only the driver stands
+ * between the header and the run's first dispatch: `start` dispatches synchronously inside `driver.start`, so a runtime
+ * could call it no earlier than the handle it returns. Conditionally spread, the binding's first road, and OMITTED from
+ * {@link ResumeOptions} below: `resume()` never calls it.
+ *
+ * **`onTaskMessage` and `onTaskProgress` are the TWENTY-SECOND and TWENTY-THIRD members, and the thirteenth and fourteenth
+ * here** — `RN-R42`, [ADR 0114](../../doc/decisions/0114-a-tasks-attribution-is-fields-and-its-messages-and-progress-are-passed-through.md),
+ * P36 (k), [W187](../../doc/work-items/w187-attribution-on-the-fold-and-messages-passed-through.md). Per-RUN callbacks, as
+ * every `on*` member here is; conditionally spread, the binding's first road — and KEPT by {@link ResumeOptions}: a
+ * resumed run's re-dispatched tasks emit as a started run's do, and nothing about the pass-through is the stored run's.
  */
-export interface StartOptions extends Pick<DriverOptions, 'createTask' | 'joinPolicy' | 'onFoldInput' | 'onNonconformingResult' | 'onRegionEvent' | 'onRunFailure' | 'onUnsatisfiableJoin' | 'onUnmintedTask' | 'now'> {
+export interface StartOptions extends Pick<DriverOptions, 'createTask' | 'joinPolicy' | 'onFoldInput' | 'onHeader' | 'onNonconformingResult' | 'onRegionEvent' | 'onRunFailure' | 'onTaskMessage' | 'onTaskProgress' | 'onUnsatisfiableJoin' | 'onUnmintedTask' | 'now'> {
     /**
      * Omitted, the runtime mints `r<n>` from its own counter — inside `ID-R2`'s charset, unique per RUNTIME and not globally
      * (decision 10). **Since W89 the counter SKIPS an id in use on this runtime, and a caller naming one is refused** (`RunIdInUse`,
@@ -199,8 +229,10 @@ export interface StartOptions extends Pick<DriverOptions, 'createTask' | 'joinPo
 /**
  * **What `resume` may say about the run it resumes: everything `start` may, but its id** — `RN-R25`. The run id is the
  * checkpoint's (`header.runId`), because every task id the stored run dispatched embeds it; there is nothing to choose.
+ * **Nor its `onHeader`** (`RN-R39`, P36 (d)): the caller of `resume` already holds the header — it is the checkpoint's —
+ * and `Driver.resume` never calls it, so a member here would be a typed option that does nothing.
  */
-export type ResumeOptions = Omit<StartOptions, 'runId'>;
+export type ResumeOptions = Omit<StartOptions, 'runId' | 'onHeader'>;
 /**
  * **What a driver is handed, and therefore what `runtime.registry` IS** — decision 14. Note
  * `predicates`: the driver wants the FUNCTIONS, keyed by name, where the validator's `Registry`
@@ -232,8 +264,8 @@ export type RuntimeRegistry = Pick<DriverOptions, 'predicates' | 'workers' | 'no
  *
  * **`done` RESOLVES and never rejects, and that reversed the plan's own lean on a measurement.**
  * Its settlement rule is terminality and nothing else, so a run the driver REFUSES resolves with
- * `outcome: 'stopped'` and `stoppedBy` carrying the reason rather than throwing it away — `failRun`
- * appends the `stopped` element BEFORE it calls `onRunFailure`, so a refusal is already terminal
+ * `outcome: 'halted'` and `haltedBy` carrying the reason rather than throwing it away — `failRun`
+ * appends the `halted` element BEFORE it calls `onRunFailure`, so a refusal is already terminal
  * when a consumer hears of it. The road not taken rejects there, and on the one class of refusal
  * that is reported AND rethrown (`start()` has the caller on the stack) it rejects a promise the
  * caller is never handed: measured in a child process with no listener, **exit 1, the process
@@ -250,31 +282,85 @@ export interface RunHandle {
     /** The run's `Driver`, already started — exactly what `start` returned before ADR 0058. */
     readonly driver: Driver;
     /**
-     * **The run's end.** Resolves with the terminal `RunState` — `completed`, `failed`, `stuck` or
-     * `stopped` — and never rejects. Pending while the outcome is `running` or `awaiting_action`.
+     * **The run's end.** Resolves with the terminal `RunState` — `completed`, `failed`, `stuck`, `cancelled` or
+     * `halted` (0.7.0's `stopped`, ADR 0102) — and never rejects. Pending while the outcome is `running`, `awaiting_action`
+     * or — since W173 — `cancelling`: a run its owner cancelled through `driver.cancel` settles `cancelled` after its LAST
+     * task has stopped, and is released then (ADR 0104, `RN-R30`); one a task the scheduler cancelled on its own ended
+     * settles at that first `task.cancelled` (`RN-R28`). **A run its owner STOPPED** (`stop` below, or `driver.stop`) settles
+     * `interrupted` — terminal on this runtime, resumable on another — once the stop's cancels have RESOLVED, not at the
+     * 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 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 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 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>;
+    /**
+     * **Stop this run so that a resume on ANOTHER runtime can continue it** — `driver.stop(options)`, forwarded, and
+     * nothing else (`RN-R33`, [ADR 0105](../../doc/decisions/0105-a-run-its-owner-stops-goes-deaf-before-it-cancels-and-resumes-elsewhere.md),
+     * P34 stop-and-ask (d)): the run is held and the driver goes deaf, ONE `interrupted` element is appended, and each task in
+     * flight is cancelled; `done` then settles `interrupted` once those cancels have resolved, and the run is released.
+     * **One run, touching no sibling** on this runtime. Resume its checkpoint on a FRESH runtime: this one keeps the run
+     * id in use (`RN-R25`). **BREAKING in 0.8.0 for code that BUILDS a `RunHandle`** (P34 decision 10) — a new member.
+     *
+     * @throws RunControlRefused — `control: 'stop'`, as `driver.stop` throws it; nothing recorded or sent.
+     * @throws the consumer's own error — an `onFoldInput` that threw on the `interrupted` element (`OR-R10` v0.19, `RN-R33`
+     *   v0.24, P36 (b), W184): the cancels are still sent, and the run is HALTED and reported once — `halted` outranks
+     *   `interrupted`, so it is NOT resumable and `done` settles `halted` at once, without waiting on the cancels.
+     */
+    stop(options: RunStopOptions): Promise<void>;
     /**
      * **What a consumer writes FIRST when it stores this run by appending its events** — P23
      * decision 4, [ADR 0064](../../doc/decisions/0064-a-checkpoint-is-the-whole-event-sequence-and-a-header-and-it-is-a-copy.md)
      * rule 5. Equal to `driver.checkpoint().header` and a separate copy of it.
      *
-     * **It arrives AFTER the run's first events, and that is measured rather than avoidable.** `start`
-     * dispatches the entry node synchronously, so a consumer's `onFoldInput` has been handed **1 to 5**
-     * elements before this handle exists — 1 on 59 of L6's 62 starts, 5 on a nested map at the entry
-     * (W88's declaration step) — and it is not bounded by 5: an entry FAN-OUT of N branches delivers
-     * `regionEntered`, N `branch.opened` and N `dispatched`, 2N + 1, before `start` returns (W88's
-     * conformity reader, finding 11). That is what `onFoldInput`'s `seq` is for: a store keyed by position
-     * does not care which was written first (`RN-R18`).
+     * **ON THE HANDLE it arrives AFTER the run's first events.** `start` dispatches the entry node synchronously, so a
+     * consumer's `onFoldInput` has been handed **1 to 5** elements before this handle exists — 1 on 59 of L6's 62 starts, 5
+     * on a nested map at the entry (W88's declaration step) — and it is not bounded by 5: an entry FAN-OUT of N branches
+     * delivers `regionEntered`, N `branch.opened` and N `dispatched`, 2N + 1, before `start` returns (W88's conformity
+     * reader, finding 11). **A store that must write its header FIRST passes `onHeader`** (`StartOptions`, `RN-R39`,
+     * [ADR 0112](../../doc/decisions/0112-a-run-delivers-its-header-before-its-first-event.md)): the same header, handed over
+     * inside `start` before the first element and before anything reaches the scheduler. *(This read *measured rather than
+     * avoidable* until W185: true of the handle, and the avoidance is the driver's.)* `onFoldInput`'s `seq` still names what a
+     * 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. */
@@ -287,6 +373,20 @@ export interface Runtime {
     readonly pools: Readonly<Record<string, ResolvedPool>>;
     /** The group objects this runtime CREATED, keyed as the document declared them. */
     readonly groups: Readonly<Record<string, ResourceGroup>>;
+    /**
+     * **Every finding `start(flow, payload, {})` would refuse `flow` on that depends on the FLOW and this runtime
+     * alone** — [ADR 0096](../../doc/decisions/0096-a-runtime-is-its-registry-and-start-refuses-from-runtime-check.md)
+     * rule 4, P37 stop-and-ask (b). `[]` means `start` will not refuse the flow; a non-empty result is what `start`
+     * throws, built from this same call (rule 5): the `FD-V` findings as `InvalidDefinition`, and — since
+     * [ADR 0097](../../doc/decisions/0097-what-start-refuses-that-the-flow-does-not-decide.md) — the `FD-R6` findings, a
+     * node reaching a group the built-in `KeyedRateLimitGroup` factory built, as `LimitKeyMissing` when `start` is given
+     * no `createTask`. **`check` reads as `start` given none** (P37 stop-and-ask (c)), so a caller who will pass a
+     * `createTask` setting `limitKey` filters `FD-R6` out by its rule id. **It never throws for a flow's defect**: every
+     * finding is returned, as `validateDefinition` returns them, against this runtime's own registry. **Not included,
+     * by name**: the PAYLOAD's refusals (`FD-R4`, the entry payload's clone) and the RUN ID's (`ID-R2`, `RunIdInUse`),
+     * which depend on what a run is started with. *Register* a flow on a running runtime by calling this, then `start`.
+     */
+    check(flow: FlowDefinition): Finding[];
     /**
      * Start one run of `flow` with `payload`, and return its {@link RunHandle} — the `Driver`,
      * already started, and a `done` promise that resolves when the run reaches a terminal
@@ -296,7 +396,7 @@ export interface Runtime {
     /**
      * **Resume the run a checkpoint stored**, on THIS runtime's scheduler, and return the same {@link RunHandle} `start` does —
      * `RN-R19` to `RN-R25`, [ADR 0065](../../doc/decisions/0065-a-resume-replays-the-stored-stimuli-refuses-what-it-cannot-regenerate-and-re-dispatches-what-was-in-flight.md).
-     * The header is refused first and before any driver exists (`resumeRefusal` — format, flow id, version, a stopped run),
+     * The header is refused first and before any driver exists (`resumeRefusal` — format, flow id, version, a halted run, a cancelled run),
      * then a run id in use (`RunIdInUse`); then a driver is built for `header.runId` exactly as `start` builds one and
      * `Driver.resume` replays the stored events, re-dispatches what was in flight AT-LEAST-ONCE, and appends `resumed`.
      *
@@ -304,6 +404,11 @@ export interface Runtime {
      * regenerated past the stored events (the lost tail), then `resumed`, then whatever the run does next — so a store that
      * appends what it is handed holds the whole run again (`RN-R24`). `done` resolves with the terminal `RunState` of the
      * WHOLE run, stored elements included.
+     *
+     * **A consumer `onFoldInput` that THROWS on the `resumed` element** (`RN-R22` v0.24, P36 (c), W184): the run is HALTED and
+     * reported once, NOTHING of the in-flight set is handed to this runtime's scheduler, and the consumer's own error is
+     * thrown here — after the driver was built, so the run id is spent on this runtime (ADR 0091 rule 4, as for a resume
+     * refused during its replay).
      */
     resume(flow: FlowDefinition, checkpoint: Checkpoint, options?: ResumeOptions): RunHandle;
     /** The scheduler's, forwarded — a runtime owns its pools, so it owns their shutdown. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fyflow-orchestration",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Flow orchestration over fyflow-scheduler: sequence, decision, fan-out and join",
   "keywords": [
     "workflow",
@@ -126,12 +126,12 @@
   "devDependencies": {
     "@types/node": "^24.13.3",
     "esbuild": "^0.25.12",
-    "fyflow-scheduler": "0.5.2",
+    "fyflow-scheduler": "0.6.0",
     "playwright": "^1.62.1",
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "fyflow-scheduler": "0.5.2"
+    "fyflow-scheduler": "0.6.0"
   },
   "dependencies": {
     "jsonata": "2.2.2"