fyflow-orchestration 0.7.0 → 0.8.0

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 { Checkpoint, CheckpointHeader, DriverOptions, RunStopOptions } 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 { 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,8 +282,14 @@ 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 ONE
      * `RunState` and `step`s it per fold input, which is what `fold` is
@@ -261,18 +299,34 @@ export interface RunHandle {
      * is a second route rather than a second definition.
      */
     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;
 }
@@ -287,6 +341,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 +364,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 +372,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.8.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"