fyflow-orchestration 0.7.0 → 0.8.0

package/dist/types/src/definition/regions.d.ts

@@ -231,6 +231,17 @@ export declare function branchPathOf(regions: RegionSets[], nodeId: string, item
  * does.
  */
 export declare function regionChainOf(regions: RegionSets[], nodeId: string): string[];
+/**
+ * **The map instance a node is IN — the innermost `map` region containing it as a MEMBER** —
+ * `spec/flow-definition.md` v0.45, P38 (c), [ADR 0118](../../doc/decisions/0118-a-map-instance-keeps-its-item-while-a-node-of-it-may-still-be-entered.md).
+ * What `"$item"` names: the item of the instance this node is entered in. **The region chain's own walk**
+ * (`regionChainOf`), read innermost-first for the first region a `map` opened — so a node in a `fanout`
+ * nested inside a map instance names the MAP's item, and a `map` NODE names its ENCLOSING instance's item,
+ * because an opener is never a member of the region it opens (its branch cannot reach it, `FD-V10`).
+ * `undefined` for a node no map region contains — `FD-V49`'s refusal, and the one answer the validator,
+ * the driver and the wiring check all read from here, so the three cannot disagree about which item it is.
+ */
+export declare function innermostMapOf(regions: RegionSets[], nodeId: string): RegionSets | undefined;
 /**
  * **How many leading `branchPath` segments the two nodes have anything to compare
  * on** — the length of the COMMON PREFIX of their two region chains, and the whole
@@ -327,7 +338,7 @@ export declare function branchIndexOf(regions: RegionSets[], nodeId: string): nu
  *
  * | out-arcs of | are | because |
  * |---|---|---|
- * | a `task`'s `edges` | **disjunctive** — exactly one is taken | section 3's routing rule 2 |
+ * | a `task`'s `edges`, and — v0.42 — an `ask`'s | **disjunctive** — exactly one is taken | section 3's routing rule 2; an ask routes as a task's settlement does (P35 (h)) |
  * | a `fanout`'s `branches`, a `map`'s `branch` | **conjunctive** — all are entered | `JP-R5`, which emits every `branch.opened` before any dispatch |
  *
  * So a branch entry never *dominates* its own join — every path to the join goes

package/dist/types/src/definition/registry.d.ts

@@ -79,14 +79,20 @@ export declare class UndeclaredKey extends RegistryError {
 /** A predicate or language the document NAMES that `code` did not supply, or a group a type names that the document lacks. */
 export declare class NameMissing extends RegistryError {
 }
-/** A derivation returned something that is not a `PoolSpec`, threw, or produced a pool the runtime refuses (a resident group beside `idleTimeout: 0`). */
+/**
+ * A derivation returned something that is not a `PoolSpec`, threw, or produced a pool the runtime refuses: a resident group
+ * beside `idleTimeout: 0`, or — since v0.39 ([Q619](../../doc/questions/q619.md) option B) — a group of the built-in
+ * `KeyedRateLimitGroup` type held in `residentGroups`, which the scheduler would count in one `""` bucket.
+ */
 export declare class DerivationRefused extends RegistryError {
 }
 /**
  * **A registered GATE type is not a `GateType`** — v0.23 (W92, ADR 0066): not an object; a key beside the
- * interface's five; `routes` empty, repeated or outside `FD-V16`'s charset; a `defaultRoute` that is not one
- * of them; a `settingsSchema` outside the subset; a `keyResolvedRoutes` that is not an array of its own
- * routes, or repeats one (v0.25); or no `fn`. `gateTypeProblem` is the predicate, shared with
+ * interface's seven; **static routes AND `routesFor`, or neither** (v0.30, ADR 0092); a `routesFor` or a
+ * `settingsProblem` that is not a function (v0.30); `routes` empty, repeated or outside `FD-V16`'s charset; a
+ * `defaultRoute` that is not one of them; a `settingsSchema` outside the subset; a `keyResolvedRoutes` that is not
+ * an array of its own routes, or repeats one (v0.25); or no `fn`. What a derived type's `routesFor` RETURNS is
+ * held at the gate, `FD-V39`, since only a gate has settings. `gateTypeProblem` is the predicate, shared with
  * `FD-V39`'s second clause, so the registry and the validator cannot disagree about what a gate type IS.
  */
 export declare class GateTypeRefused extends RegistryError {
@@ -110,12 +116,21 @@ export declare const WORKER_KEYS: readonly string[];
 export declare const CHECKED_WORKER_SCHEMAS: readonly string[];
 /** A document node type's keys. */
 export declare const NODE_TYPE_DECLARATION_KEYS: readonly string[];
-/** A `PoolSpec`'s keys — what a derivation may return. */
+/** A `PoolSpec`'s keys — what a derivation may return. `cancelGraceMs` and `messages` since v0.33 (P33 decision 6, W159). */
 export declare const POOL_SPEC_KEYS: readonly string[];
-/** A document type's `pool` field: the `PoolSpec` minus what the type states beside it. */
+/** A `PoolSpec.messages` object's keys — the scheduler's `MessageOptions`, v0.33. */
+export declare const MESSAGE_OPTION_KEYS: readonly string[];
+/** A document type's `pool` field: the `PoolSpec` minus what the type states beside it — and, since v0.37, a named instance's `pool` (ADR 0099). */
 export declare const DECLARED_POOL_KEYS: readonly string[];
-/** A pool instance's and a group instance's keys. */
+/** A GROUP instance's keys — and the two every instance shares. */
 export declare const INSTANCE_KEYS: readonly string[];
+/**
+ * **A POOL instance's keys: the two, and `pool`** — v0.37,
+ * [ADR 0099](../../doc/decisions/0099-a-named-instance-of-a-document-type-may-declare-its-own-pool-options.md),
+ * [W165](../../doc/work-items/w165-pool-options-on-a-named-pool-instance.md): the instance's OWN pool options, the
+ * `DECLARED_POOL_KEYS`, on an instance of a DOCUMENT type only. A group instance still declares the two alone.
+ */
+export declare const POOL_INSTANCE_KEYS: readonly string[];
 /** A class-form entry is the one whose `pool` is a FUNCTION; a document form's `pool` is an options object or absent. */
 export declare function isDerivation(t: NodeTypeEntry): t is NodeTypeDefinition;
 /**
@@ -125,19 +140,38 @@ export declare function isDerivation(t: NodeTypeEntry): t is NodeTypeDefinition;
  * deliberately not offered — a class is where any other rule lives.
  */
 export declare function mergeConfig(base: unknown, over: unknown): unknown;
+/** The pool options a document type declares, and since v0.37 a named instance of one (ADR 0099). */
+type DeclaredPool = NonNullable<NodeTypeDeclaration['pool']>;
 /**
  * **The document form of a node type IS the identity derivation** — decision 2: `pool(config)`
  * merges the instance's config over the declared one, and copies the declared pool fields and the
  * declared groups. Keys are copied only when declared, so an absent `groups` stays absent (fact 5).
  * The declaration's shape is checked by `resolveRegistry` before this is called; here it is trusted.
+ *
+ * **`over` is a NAMED INSTANCE's own pool options** (v0.37, ADR 0099 rules 1-3): merged over the declared `pool` by
+ * `mergePool`, and the result is what this derivation hands on. Absent — every type's default instance, and every
+ * instance that declares none — the derivation is the one it has always been, option for option (P18 fact 5).
  */
-export declare function nodeTypeFromDeclaration(decl: NodeTypeDeclaration): NodeTypeDefinition;
+export declare function nodeTypeFromDeclaration(decl: NodeTypeDeclaration, over?: DeclaredPool): NodeTypeDefinition;
 /**
  * **Why a derivation's output is not a `PoolSpec`, or `null`** — the check BOTH forms pass through
  * (decision 2's *a class cannot compute around a check*). The scheduler coerces or ignores a wrong
  * option in silence exactly as it does a retry policy (`FD-V30`'s measurements), so the shape is
  * pinned here: numbers where numbers, a string list for `groups`, a string list or a `{ key: cost }`
- * record for `residentGroups`, and no key beside the six.
+ * record for `residentGroups`, and no key beside the eight.
+ *
+ * **`cancelGraceMs` and `messages` (v0.33, P33 decision 6, W159) are held to the SCHEDULER's own rules**, read
+ * at the pin in its `validateGraceMs` and `resolveMessageOptions`, where it throws at `new WorkerManager`:
+ * `cancelGraceMs` a number `>= 0` — which `NaN` is not, so no clause of its own refuses it — and `Infinity` admitted, the scheduler's *never force*; `messages` a
+ * plain object of `flushIntervalMs` (finite, `> 0`) and `maxBuffered` (an integer `>= 1`), each optional. **A
+ * `messages` key that is PRESENT is held whatever its value**, `undefined` included, unlike the top-level keys
+ * here: the scheduler reads `cancelGraceMs ?? 2000` but spreads `messages` over its defaults, so a present
+ * `undefined` replaces a default and it throws. A key beside the two is refused, as everywhere in this module —
+ * and it is not merely ignored by the scheduler: the resolved object is carried to every worker, so on a
+ * THREADED pool a stray key holding a value that cannot be cloned fails the task at run time with *could not be
+ * cloned* (W159's conformity reader, F1). Refusing it here moves that failure to construction. **Stricter than
+ * the scheduler, where it is silent**: a `messages` that is not a plain object (it spreads one into its
+ * defaults and reads nothing), and a `cancelGraceMs` of `null` (it reads `?? 2000`), are refused here.
  */
 export declare function poolSpecProblem(v: unknown): string | null;
 /** The group keys a `PoolSpec` names, from both fields — what must exist in `groups`. */
@@ -160,8 +194,15 @@ export declare function poolOptionsOf(spec: PoolSpec, inline: boolean | undefine
  * its output held to `PoolSpec`'s shape, the derived config against the WORKER's `configSchema`,
  * every group it names present, and decision 9's refusal — a resident group beside `idleTimeout: 0`
  * deadlocks a contended group (P18 fact 6, the scheduler reference's own sentence).
+ *
+ * **`pool` is a named instance's OWN pool options** (v0.37, ADR 0099): the instance is derived by its type's identity
+ * derivation with them merged over the type's declared ones (`nodeTypeFromDeclaration(declaration, pool)`), and the
+ * OUTPUT takes every check below exactly as any derivation's does — P37 decision 9's *through `derivePool`'s one check*.
+ * Its own shape, and its type being a DOCUMENT type, were held by the registry's shape check before this is called, on
+ * both roads. The returned `definition` is the TYPE's, as for every instance; `pool` is carried, copied, so a caller that
+ * hands the instance on (`createRuntime`, to the bootstrap helper) hands on what was resolved.
  */
-export declare function derivePool(key: string, typeName: string, def: NodeTypeDefinition, worker: WorkerEntry | undefined, config: unknown, groupKeys: ReadonlySet<string>, refuse: new (at: string, m: string) => RegistryError): ResolvedPool;
+export declare function derivePool(key: string, typeName: string, def: NodeTypeDefinition, worker: WorkerEntry | undefined, config: unknown, groupKeys: ReadonlySet<string>, refuse: new (at: string, m: string) => RegistryError, pool?: unknown): ResolvedPool;
 export declare function checkRegistry(reg: {
     workers?: Workers;
     nodeTypes?: NodeTypes;
@@ -183,3 +224,4 @@ export declare function checkGateTypes(x: GateTypes | undefined): void;
  * schemas, derived `PoolSpec`s and the adapters and factories as given.
  */
 export declare function resolveRegistry(doc: RegistryDocument, code?: RegistryCode): ResolvedRegistry;
+export {};

package/dist/types/src/definition/schema.d.ts

@@ -7,7 +7,8 @@
  *
  * A worker entry in the registry document declares up to four schemas (`configSchema`,
  * `settingsSchema`, `inputSchema`, `outputSchema`); a group type declares one; a node-type class may
- * declare one. A worker's first two, a group type's and a class's are CHECKED — at `createRuntime`
+ * declare one; and since v0.42 an `ask` NODE in a flow may declare one, `answerSchema`, held to this subset
+ * by `schemaProblem` when the flow is validated (`FD-V48`, W179) rather than when a registry is built. A worker's first two, a group type's and a class's are CHECKED — at `createRuntime`
  * and at `new Driver` — and a worker's last two are declared, carried, enforced on ONE value per run
  * each since v0.21 (the entry payload at `start()`, a person's resolution at `resolve()` — `FD-R4`, W73),
  * never per settlement, and since v0.20 confirmed on a run by `scripts/check-workers.mjs` (P19, whose name is *what a schema
@@ -22,8 +23,11 @@
  * shape one layer up: a document that says one thing and a validator that checks another, at exit 0.
  * The refusal names the keyword and the path, so a consumer meets a refusal rather than a pass, and
  * prediction 4's reversal (a real worker needing a keyword outside the subset) is legible the day it
- * happens. Annotation keywords (`title`, `description`, `$schema`, `$comment`) are outside the subset
- * too and are refused the same way — a consequence ADR 0053 states rather than a whitelist it invents.
+ * happens. **ANNOTATION keywords are inside it too** — `examples` (v0.20, ADR 0056) and, since v0.36,
+ * `title`, `description`, `readOnly` and `writeOnly`
+ * ([ADR 0098](../../doc/decisions/0098-four-annotations-join-the-schema-subset-and-constrain-nothing.md)) —
+ * each with its VALUE SHAPE checked and none read by a value check; every other annotation
+ * (`deprecated`, `$comment`, `default`, `format`, `$schema`, `$id`) is outside it and refused the same way.
  *
  * **What `type` means over JSON data.** `number` and `integer` admit FINITE numbers only: JSON text
  * cannot carry `NaN` or an infinity, so a schema over JSON data has no reading of them but *not a
@@ -41,15 +45,15 @@
 /** A JSON Schema in the subset — data, as everything in a registry document is. Checked by `schemaProblem`. */
 export type JsonSchema = Readonly<Record<string, unknown>>;
 /**
- * **The subset, enumerated** — the twelve keywords P18 fact 1 measured as covering the sample's and
- * the corpus's schemas (14 of 14 cases), **and `examples`, the thirteenth, an ANNOTATION** —
+ * **The subset, enumerated** — the CONSTRAINING keywords P18 fact 1 measured as covering the sample's
+ * and the corpus's schemas, **and the ANNOTATIONS**, first `examples` —
  * [ADR 0056](../../doc/decisions/0056-an-example-is-an-annotation-validated-against-the-schema-it-sits-on.md),
  * [W72](../../doc/work-items/w72-the-contract-an-example-beside-every-schema-and-a-worker-run-on-it.md),
  * the plan's first deliberate extension of the subset. `spec/flow-definition.md` section 3's table
- * names the same thirteen, and `test/definition/schema.test.ts` compares the two lists both ways
- * (rule 8 obligation (e)'s third shape — a list is a claim about another list).
+ * names the same keywords and marks which annotate, and `test/definition/schema.test.ts` compares the
+ * two both ways (rule 8 obligation (e)'s third shape — a list is a claim about another list).
  *
- * `examples` differs from the other twelve in ONE way, and the difference is the decision: it
+ * `examples` differs from the constraining keywords in ONE way, and the difference is the decision: it
  * constrains NOTHING when a value is checked (`findings` never reads it) and is itself HELD to the
  * schema it sits on at construction (`schemaProblem` runs `findings` over each declared example) —
  * so a worker's declared example is a value the check-time tools may RUN the worker on, and an
@@ -59,6 +63,14 @@ export type JsonSchema = Readonly<Record<string, unknown>>;
  * self-consistent. The rule is optional — an absent `examples` refuses nothing (the maintainer's
  * choice, W72's stop-and-ask 1) — and an EMPTY one is refused, because a declared-and-empty list
  * is the silent kind (`enum`'s own reason).
+ *
+ * **And the annotations of v0.36** — `title` and `description` (a string), `readOnly` and
+ * `writeOnly` (a boolean) —
+ * [ADR 0098](../../doc/decisions/0098-four-annotations-join-the-schema-subset-and-constrain-nothing.md),
+ * P37 decision 4. Their bar: *an annotation is admitted if it constrains nothing in JSON Schema itself
+ * and its value shape is checked*. `schemaProblem` checks the shape; `findings` reads none of them, so
+ * **`writeOnly` hides nothing and promises no redaction**, and `readOnly` refuses nothing. They are in
+ * THIS list rather than a second one, so the spec's table binds them as it binds every other keyword.
  */
 export declare const SCHEMA_KEYWORDS: readonly string[];
 /** The type names `type` may use — JSON Schema's seven, `integer` included. */

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

@@ -8,26 +8,42 @@
 import type { ResourceGroup } from 'fyflow-scheduler';
 import type { JsonSchema } from './schema.js';
 export type { JsonSchema } from './schema.js';
-/** The terminal states an edge may opt into. `user_action` is refused: it suspends (FD-V18). */
+/**
+ * The terminal states an edge may opt into. `user_action` is refused: it suspends (FD-V18). **And
+ * `cancelled` is refused too** — a cancel is the consumer's own act and halts the run rather than
+ * routing it ([ADR 0094](../../doc/decisions/0094-a-cancelled-task-is-a-terminal-state-that-routes-no-edge-and-ends-its-run-cancelled.md)
+ * rule 1), so `FD-V18` still admits exactly these two.
+ */
 export type RoutableState = 'done' | 'failed';
-/** Every terminal state a scheduler task can reach. Five library states, three terminal. */
-export type TerminalState = 'done' | 'failed' | 'user_action';
+/**
+ * Every terminal state a scheduler task can reach. **Six library states, four terminal** — `cancelled`
+ * since the scheduler pin W157 moved to, which ends a task through `scheduler.cancel()` alone
+ * ([ADR 0094](../../doc/decisions/0094-a-cancelled-task-is-a-terminal-state-that-routes-no-edge-and-ends-its-run-cancelled.md),
+ * W158). **Widening this union is BREAKING for a consumer switching on it exhaustively**, on
+ * `resumed`'s and `gated`'s precedent: such a switch stops compiling, and one comparing strings does
+ * not notice.
+ */
+export type TerminalState = 'done' | 'failed' | 'user_action' | 'cancelled';
 /**
  * **A declared reference to something the run has produced** —
  * `spec/flow-definition.md` section 3's `needs`, and
  * [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).
  *
- * Three forms, all of them data (ADR 0002 rule 1 — nothing here is a function and
+ * Four forms, all of them data (ADR 0002 rule 1 — nothing here is a function and
  * everything survives `JSON.parse(JSON.stringify(x))`):
  *
  * | | |
  * |---|---|
- * | `"."` | what this node would have received anyway — the ordinary edge's value, and for a `map` instance its own item (`JP-R11`). The one token outside `FD-V16`'s charset, so it can never collide with a node id |
+ * | `"."` | what this node would have received anyway — the ordinary edge's value, and for a `map` instance its own item (`JP-R11`). Outside `FD-V16`'s charset, so it can never collide with a node id |
+ * | `"$payload"` | **the value the RUN entered with** — what `start()` was handed, from any node and any edge (v0.44, [ADR 0117](../../doc/decisions/0117-a-reference-may-name-what-reached-the-run.md)). Always there, so no `?` and no array form. `$` is outside `FD-V16`'s charset, and the whole `$` prefix is reserved: `"$item"` — a map instance's item — is W191's, and any other `$` spelling is `FD-V26` |
  * | `"score"` | that node's output **on this node's own branch path**. Exactly one, or the run stops (`FD-R3`) |
  * | `["score"]` | that node's outputs as an **array**, in ascending segment-wise-numeric `branchPath` order. Legal only where the reader is outside a region containing the named node (`FD-V28`) |
  *
  * **The array form uses JSON's own array syntax rather than a sigil**, so the
- * grammar needs exactly one invented token (`"."`) rather than two.
+ * grammar invents tokens only for what has no node id: `"."`, the `?` modifier
+ * (v0.13), and — v0.44 — the `$` prefix. *(This read *"exactly one invented token"*
+ * until v0.13 and stayed so until W190.)* A `string` covers every token, so the
+ * TYPE does not move; `referenceTarget`'s parse does.
  */
 export type Reference = string | readonly [string];
 /**
@@ -37,8 +53,9 @@ export type Reference = string | readonly [string];
  * object this describes; a node that does not receives what section 3 says an
  * ordinary edge carries, unchanged.
  *
- * Only a `task` and a `map` may carry it: `FD-V17` already refuses an undeclared
- * key on the other three kinds, so that clause needs no rule of its own.
+ * Only a `task`, a `map` and — since v0.42 — an `ask` may carry it: `FD-V17` already refuses an
+ * undeclared key on the other four kinds, so that clause needs no rule of its own. *(This read "the
+ * other three", stale since v0.23's `gate`.)*
  */
 export type Needs = Readonly<Record<string, Reference>>;
 /**
@@ -223,13 +240,7 @@ export type Workers = ReadonlyMap<string, WorkerEntry> | Readonly<Record<string,
  * validator reads of one is its `type` (`FD-V38`); a `PoolInstance` and a resolved pool both fit.
  * **Absent means EMPTY**; a type's DEFAULT instance is implicit and never listed here.
  */
-export type Pools = ReadonlyMap<string, {
-    readonly type: string;
-    readonly config?: unknown;
-}> | Readonly<Record<string, {
-    readonly type: string;
-    readonly config?: unknown;
-}>>;
+export type Pools = ReadonlyMap<string, Readonly<PoolInstance>> | Readonly<Record<string, Readonly<PoolInstance>>>;
 /**
  * **A declared transform: a language NAME and an expression in it** — `spec/flow-definition.md`
  * section 2's `transform` subsection (v0.18). Data, as everything in a definition is (ADR 0002
@@ -306,6 +317,25 @@ export interface PoolSpec {
     groups?: readonly string[];
     /** Group keys held for the WORKER's lifetime rather than per task, at a cost each — never beside `idleTimeout: 0` (decision 9). */
     residentGroups?: readonly string[] | Readonly<Record<string, number>>;
+    /**
+     * **Threaded pools: the ms a cancelled task's worker gets to stop by itself before it is forced** — the
+     * scheduler's own option, declarable since `spec/flow-definition.md` v0.33 (P33 decision 6, W159). Zero or
+     * more, `Infinity` included (the scheduler's *never force*); accepted, and ignored by the scheduler, on an
+     * inline pool.
+     */
+    cancelGraceMs?: number;
+    /**
+     * **The bounds on a worker's `context.emit()`** — the scheduler's `messages` option, declarable since v0.33
+     * (P33 decision 6, W159): events batched for up to `flushIntervalMs` (a finite number > 0), at most
+     * `maxBuffered` (an integer >= 1) per buffer between flushes. Each key optional; a key PRESENT is held to its
+     * rule whatever its value, `undefined` included, because the scheduler spreads this object over its defaults
+     * and a present `undefined` is what it throws on. Written out rather than imported from the scheduler, as
+     * `POOL_SPEC_KEYS` is a literal: a key the scheduler adds is admitted by a version of the spec, not by a bump.
+     */
+    messages?: Readonly<{
+        flushIntervalMs?: number;
+        maxBuffered?: number;
+    }>;
 }
 /**
  * **A node type as a DERIVATION from an instance's config to pool options** — decision 2, the CLASS
@@ -343,7 +373,8 @@ export interface NodeTypeDefinition {
  * a worker entry; `inline` is the type's; `config` is the default instance's constructor argument;
  * `pool` carries the declared pool options (a `PoolSpec` minus `config` and `groups`); `groups` are
  * the pool's group keys; `retryPolicy` and `settings` are what the type declares FOR its nodes. An
- * instance's `config` merges shallowly over `config`; every other field is copied as declared.
+ * instance's `config` merges shallowly over `config`, and since v0.37 a named instance's own `pool` merges shallowly
+ * over `pool` (ADR 0099); every other field is copied as declared, every object in it copied.
  */
 export interface NodeTypeDeclaration {
     /** As `NodeTypeDefinition.worker`: absent only on a built-in that only transforms (ADR 0075). */
@@ -363,6 +394,13 @@ export interface PoolInstance {
     type: string;
     /** The instance's config — the derivation's input, merged over the type's for a document type. */
     config?: unknown;
+    /**
+     * **The instance's OWN pool options** — v0.37, [ADR 0099](../../doc/decisions/0099-a-named-instance-of-a-document-type-may-declare-its-own-pool-options.md):
+     * the keys a type's `pool` may declare, merged SHALLOWLY over its type's (the instance's key winning, a key present
+     * with `undefined` absent), every object in them copied. **On an instance of a DOCUMENT type only** — one of a CLASS
+     * type is refused (`UndeclaredKey`): the class receives the instance key and owns how its pool is built.
+     */
+    pool?: NodeTypeDeclaration['pool'];
 }
 /** A resource group the runtime constructs — an instance of a group TYPE, by name, with the config its factory's schema admits. */
 export interface GroupInstance {
@@ -434,6 +472,8 @@ export interface ResolvedPool {
     config: unknown;
     /** What the derivation returned, held to `PoolSpec`'s shape and the worker's `configSchema`. */
     spec: PoolSpec;
+    /** A named instance's OWN pool options, COPIED, a key present with `undefined` dropped (it overrides nothing) — v0.37, ADR 0099; absent where it declares none, and on every default instance. */
+    pool?: NodeTypeDeclaration['pool'];
 }
 /** One resource group, resolved: its factory and its checked config. `create` has NOT been called. */
 export interface ResolvedGroup {
@@ -552,7 +592,7 @@ export interface MapNode {
      * against whatever that resolves to.
      */
     over: string;
-    /** **One** branch entry id, whose kind is a `task` (`FD-V25`). Not a list. */
+    /** **One** branch entry id, whose kind is a `task` or — since v0.42 — an `ask` (`FD-V25`). Not a list. */
     branch: string;
     /**
      * **What this node receives, and therefore what `over` is a key on** —
@@ -601,7 +641,7 @@ export interface EndNode {
 export interface GateNode {
     id: string;
     kind: 'gate';
-    /** A registered GATE type's name — a built-in (`distinct`) or `Registry.gateTypes`' (`FD-V39`). */
+    /** A registered GATE type's name — a built-in (`distinct`, `if`, `switch`) or `Registry.gateTypes`' (`FD-V39`). */
     type: string;
     /**
      * **What the gate's type is configured with** — a plain object its type's `settingsSchema` accepts
@@ -641,14 +681,54 @@ export interface GateContext {
  * (P24 decision 2, ADR 0066). Code, not a document entry: `fn` is a function, which a JSON registry
  * cannot carry (ADR 0002 rule 1), so a consumer's types are registered in `Registry.gateTypes` the way
  * a language adapter's `compile` is supplied in code.
+ *
+ * **Its routes are declared STATICALLY or DERIVED from the gate's own settings — exactly one of the two**
+ * ([ADR 0092](../../doc/decisions/0092-a-gate-types-routes-are-declared-statically-or-derived-from-its-node.md),
+ * v0.30): a `StaticGateType` carries `routes`, `defaultRoute` and `keyResolvedRoutes?`, the same for every
+ * gate naming it; a `DerivedGateType` carries `routesFor(settings)` IN PLACE of the three, so two gates of
+ * one type may have two route sets. Every reader of a gate's routes reads the gate's RESOLVED set
+ * (`routesOf`), never the type's members. A value carrying both, or neither, is refused (`FD-V39`,
+ * `GateTypeRefused`).
  */
-export interface GateType {
+export type GateType = StaticGateType | DerivedGateType;
+/** **A gate type whose routes are its NODE's** — `routesFor` in place of `routes`, `defaultRoute` and `keyResolvedRoutes` (ADR 0092). */
+export interface DerivedGateType {
+    /**
+     * **The routes of ONE gate, from that gate's settings** — `{ routes, defaultRoute, keyResolvedRoutes? }`,
+     * held to the clauses a static type's three members are. Called once per gate at instantiation, after
+     * `FD-V40` passed, with a COPY of the settings (`{}` when the gate declares none); every reader — `FD-V41`'s
+     * count, the default edge, `FD-R5`, the wiring check's guarantee — reads what it returned. **A pure function
+     * of the settings**, as `fn` is of its context (Q9): the validator and each driver ask it separately, and a
+     * resume asks it again. A throw or a malformed set is refused at the GATE, `FD-V39`.
+     */
+    routesFor(settings: Readonly<Record<string, unknown>>): Pick<StaticGateType, 'routes' | 'defaultRoute' | 'keyResolvedRoutes'>;
+    readonly routes?: never;
+    readonly defaultRoute?: never;
+    readonly keyResolvedRoutes?: never;
+    /** What a gate's `settings` must satisfy, in the built-in subset (ADR 0053). Absent means UNCHECKED (P18 decision 3). */
+    readonly settingsSchema?: JsonSchema;
+    /**
+     * **What the settings must satisfy beyond the schema** — a message naming what is wrong, or `null`. Run by
+     * `FD-V40` once the settings are a plain object the `settingsSchema` accepts, with a COPY of them; a message
+     * is reported under `FD-V40`, and a throw or a return that is neither a string nor `null` under `FD-V39`
+     * (ADR 0092). The subset cannot state a grammar (ADR 0053), so a type that needs one states it here.
+     */
+    settingsProblem?(settings: Readonly<Record<string, unknown>>): string | null;
+    /** The decision: one of THIS GATE's routes, synchronously — a route outside the set `routesFor` returned for the gate HALTS the run (`FD-R5`). */
+    fn(ctx: GateContext): string;
+}
+/** **A gate type whose routes are the same for every gate naming it** — the interface as ADR 0066 wrote it; `distinct` is one. */
+export interface StaticGateType {
     /** Every route `fn` may return, each in `FD-V16`'s charset, distinct, at least one. Every one must be wired by exactly one edge (`FD-V41`). */
     readonly routes: readonly string[];
     /** What an edge with no `route` carries. One of `routes` — and NOT necessarily the first. */
     readonly defaultRoute: string;
+    /** Absent on a static type: its routes are declared, not derived (ADR 0092). */
+    readonly routesFor?: never;
     /** What a gate's `settings` must satisfy, in the built-in subset (ADR 0053). Absent means UNCHECKED (P18 decision 3). */
     readonly settingsSchema?: JsonSchema;
+    /** As `DerivedGateType.settingsProblem`: run by `FD-V40` after the schema, its message reported under it. */
+    settingsProblem?(settings: Readonly<Record<string, unknown>>): string | null;
     /**
      * **The routes on which the gate's KEY PATH resolved** — a subset of `routes` (`FD-V39`'s second clause, as every
      * other malformed member of this interface is), OPTIONAL, and
@@ -666,12 +746,60 @@ export interface GateType {
      * and a type must not read this member as a promise about the leaf's TYPE.
      */
     readonly keyResolvedRoutes?: readonly string[];
-    /** The decision: one of `routes`, synchronously. A route not declared STOPS the run by name (P24 decision 8 — `FD-R5`, `UndeclaredRoute`); a throw stops it with the thrown error, as a predicate's does. */
+    /** The decision: one of `routes`, synchronously. A route not declared HALTS the run by name (P24 decision 8 — `FD-R5`, `UndeclaredRoute`); a throw halts it with the thrown error, as a predicate's does. */
     fn(ctx: GateContext): string;
 }
 /** A consumer's gate types, keyed by the name a gate's `type` gives. A `Map` or a plain object, as `nodeTypes` is. */
 export type GateTypes = ReadonlyMap<string, GateType> | Readonly<Record<string, GateType>>;
-export type FlowNode = TaskNode | FanoutNode | MapNode | JoinNode | EndNode | GateNode;
+/**
+ * **An ASK: a node that waits for a PERSON, by design** — `spec/flow-definition.md` section 2 (v0.42),
+ * [P35](../../doc/plans/p35-may-a-node-wait-for-a-person-by-design.md) stop-and-asks (a) and (h),
+ * [ADR 0108](../../doc/decisions/0108-an-ask-is-a-seventh-node-kind-with-a-task-id-and-no-dispatch.md).
+ *
+ * It runs NO worker and is NEVER dispatched, yet it has a TASK ID (`spec/task-id.md` v0.13) — the address a
+ * person's answer is given to, `resolve(taskId, …)`, one per map item where it sits in a `map` region. The answer
+ * is its OUTPUT: a later node may reference it by `needs` (`FD-V27`), and its edges ROUTE like a task's — `on:
+ * ['done' | 'failed']`, a `failed` answer being the person DECLINING, and a `when` over `outcome.result`, the
+ * answer. Allowed wherever a `task` is, the entry included. **What a task's WORKER reads it does not carry** —
+ * `type`, `pool`, `optional`, `retryPolicy`, `workerGroups` and `transform` are each refused by `FD-V47`, because
+ * nothing would read them: there is no worker, no scheduler task and no wrapper to evaluate a transform in
+ * (`FD-C6`, P35 decision 6).
+ *
+ * **BREAKING** (0.8.0, P35 decision 8): `FlowNode` gains a seventh member, so a consumer's `switch` over
+ * `node.kind` with a `never` check stops compiling until it names `'ask'`.
+ *
+ * **Valid since v0.42 and run since W180** — until then every `Driver` refuses the run by name where a branch
+ * ENTERS one (`enter()`), as W92's gate was refused until W93.
+ */
+export interface AskNode {
+    id: string;
+    kind: 'ask';
+    /**
+     * **What a UI shows the person — opaque.** A plain JSON object the library NEVER reads (`FD-V21` refuses one that
+     * is not a plain object): the question, a form hint. Read from the definition, as a gate's settings are read by
+     * its type.
+     */
+    settings?: Readonly<Record<string, unknown>>;
+    /**
+     * **What a `done` answer must satisfy** — a JSON Schema in the built-in subset, held to it at load exactly as a
+     * worker's schemas are (`FD-V48`, ADR 0053), its `examples` held to it too (ADR 0056). Absent, an answer is held
+     * to nothing. A `failed` answer — a decline — is held to nothing either way. What it holds at run time is W180's
+     * (`FD-R4`'s resolve boundary).
+     */
+    answerSchema?: JsonSchema;
+    /**
+     * **What reaches the ask** — `FD-C1`, `FD-V26`-`FD-V29`, composed in the driver as a task's is. Optional: without
+     * one, the ordinary edge's value. What reached it is what the person is shown, and what W180 keeps.
+     */
+    needs?: Needs;
+    /** Routed like a task's: `on` and `when`, a default edge for every terminal state an edge opts into (`FD-V7`). */
+    edges: Edge[];
+}
+/**
+ * **Seven kinds since v0.42** (`ask`, W179). **BREAKING for an exhaustive consumer `switch`** each time a member
+ * is added — `gate` at 0.6.0, `ask` at 0.8.0.
+ */
+export type FlowNode = TaskNode | FanoutNode | MapNode | JoinNode | EndNode | GateNode | AskNode;
 export interface FlowDefinition {
     flowId: string;
     version: number;
@@ -726,7 +854,8 @@ export interface Registry {
      * **A consumer's GATE types, beside the built-ins** — the sixth set, v0.23 (W92, ADR 0066). **Absent
      * means the BUILT-INS ALONE** — `distinct` is always there, so this set only ever ADDS; a name that
      * is a built-in's is refused (`NameCollision` at construction, `FD-V39` reached here directly). The
-     * validator reads `routes`, `defaultRoute` and `settingsSchema`; the driver reads `fn` too. **A driver
+     * validator reads each gate's route set (`routesOf` — the static members, or `routesFor` over the gate's
+     * settings, v0.30), `settingsSchema` and `settingsProblem`; the driver reads `fn` too. **A driver
      * is handed the set as `DriverOptions.gateTypes`** since W93 — the runtime's road is
      * `runtime.registry.gateTypes`, from `RegistryCode.gateTypes`. *(Until W93 no driver carried it and
      * every gate flow was refused at construction.)*
@@ -740,7 +869,7 @@ export interface Registry {
  * legitimately violate more than one rule.
  */
 export interface Finding {
-    /** `FD-V1` … `FD-V46`. Never renumbered, so it is safe to assert on. */
+    /** `FD-V1` … `FD-V46` from the validator; `runtime.check` adds `FD-R6` (ADR 0097). Never renumbered, so it is safe to assert on. */
     rule: string;
     /** Node id, edge index, or document-level `null`. */
     at: string | null;