fyflow-orchestration 0.7.0 → 0.8.0

package/dist/browser/index.js

@@ -1,4 +1,5 @@
 import {
+  ASK_REFUSED_KEYS,
   BUILT_IN_GATE_TYPES,
   BUILT_IN_GROUP_TYPES,
   BUILT_IN_NODE_TYPES,
@@ -21,6 +22,7 @@ import {
   InvalidRunId,
   InvalidTaskId,
   KEY_PATH_RE,
+  MESSAGE_OPTION_KEYS,
   MissingJoinPolicy,
   MultipleRuns,
   NODE_KEYS_DECLARED,
@@ -30,6 +32,7 @@ import {
   NoMatchingEdge,
   NotStarted,
   POLICIES,
+  POOL_INSTANCE_KEYS,
   POOL_SPEC_KEYS,
   PREDICATE_GROUP_KEYS,
   PREDICATE_LEAF_KEYS,
@@ -41,10 +44,12 @@ import {
   RETRY_POLICY_KEYS,
   RegistryError,
   ResumeRefused,
+  RunControlRefused,
   SCHEMA_KEYWORDS,
   SCHEMA_TYPES,
   SchemaRefused,
   TASK_KEYS_DECLARED,
+  TERMINAL_EVENTS,
   TRANSFORM_KEYS,
   TypeDefaultRefused,
   UncloneableResult,
@@ -90,11 +95,14 @@ import {
   gateTypeCollisions,
   gateTypeProblem,
   gateTypesOf,
+  givenVerdict,
   groupsNamedBy,
+  innermostMapOf,
   innermostRegionOf,
   isDerivation,
   isSuspended,
   isTerminal,
+  isTerminalEvent,
   keyPathProblem,
   languagesOf,
   lastRecordFor,
@@ -122,6 +130,7 @@ import {
   resolveRegistry,
   resumeRefusal,
   retryPolicyProblem,
+  routesOf,
   sampleOf,
   schemaProblem,
   selectEdge,
@@ -134,7 +143,7 @@ import {
   violatedRules,
   witness,
   workersOf
-} from "./chunks/chunk-YVOP3DIN.js";
+} from "./chunks/chunk-EUU44PHD.js";
 
 // src/definition/assist.ts
 var TYPES = ["object", "array", "string", "number", "integer", "boolean", "null"];
@@ -174,8 +183,8 @@ async function tryTransform(registry, flow, nodeId, transform, options = {}) {
     else copy.transform = { lang: transform.lang, expr: transform.expr };
     return copy;
   });
-  const report = await checkWiring(registry, { ...flow, nodes }, options);
-  return report.verdicts.filter((v) => v.consumer === nodeId);
+  const { input, ...wiring } = options;
+  return await givenVerdict(registry, { ...flow, nodes }, nodeId, input, wiring);
 }
 function schemaOfValue(v) {
   if (v === void 0) return void 0;
@@ -278,13 +287,8 @@ function signaturesOf(workers) {
 }
 var PATH_TYPES = ["*", ...TYPES];
 var TS_TYPE_NAMES = [...TS_STRUCTURED, ...TS_NAMES.keys()];
-
-// src/driver/events.ts
-var TERMINAL_EVENTS = ["branch.arrived", "branch.exited", "branch.lost"];
-function isTerminalEvent(e) {
-  return TERMINAL_EVENTS.includes(e.type);
-}
 export {
+  ASK_REFUSED_KEYS,
   BUILT_IN_GATE_TYPES,
   BUILT_IN_GROUP_TYPES,
   BUILT_IN_NODE_TYPES,
@@ -307,6 +311,7 @@ export {
   InvalidRunId,
   InvalidTaskId,
   KEY_PATH_RE,
+  MESSAGE_OPTION_KEYS,
   MissingJoinPolicy,
   MultipleRuns,
   NODE_KEYS_DECLARED,
@@ -317,6 +322,7 @@ export {
   NotStarted,
   PATH_TYPES,
   POLICIES,
+  POOL_INSTANCE_KEYS,
   POOL_SPEC_KEYS,
   PREDICATE_GROUP_KEYS,
   PREDICATE_LEAF_KEYS,
@@ -328,6 +334,7 @@ export {
   RETRY_POLICY_KEYS,
   RegistryError,
   ResumeRefused,
+  RunControlRefused,
   SCHEMA_KEYWORDS,
   SCHEMA_TYPES,
   SchemaRefused,
@@ -380,7 +387,9 @@ export {
   gateTypeCollisions,
   gateTypeProblem,
   gateTypesOf,
+  givenVerdict,
   groupsNamedBy,
+  innermostMapOf,
   innermostRegionOf,
   isDerivation,
   isSuspended,
@@ -414,6 +423,7 @@ export {
   resolveRegistry,
   resumeRefusal,
   retryPolicyProblem,
+  routesOf,
   sampleOf,
   sampledOutput,
   schemaOfValue,

package/dist/browser/scheduler/index.js

@@ -2,6 +2,7 @@ import {
   BUILT_IN_NODE_TYPES,
   ConfigRefused,
   Driver,
+  InvalidDefinition,
   InvalidTaskId,
   TypeDefaultRefused,
   checkGateTypes,
@@ -20,38 +21,23 @@ import {
   poolsOf,
   resolveRegistry,
   resumeRefusal,
+  retryPolicyProblem,
   step,
+  validateDefinition,
   workersOf
-} from "../chunks/chunk-YVOP3DIN.js";
+} from "../chunks/chunk-EUU44PHD.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";
 
 // fyflow-envelope-worker:envelope-worker
-var envelope_worker_default = URL.createObjectURL(new Blob(['// src/scheduler/envelope-worker.ts\nvar NotAnEnvelope = class extends Error {\n};\nvar TransformFailed = class extends Error {\n  lang;\n  expr;\n  code;\n  constructor(transform, code, why) {\n    super(`transform failed \\u2014 ${transform.lang} ${JSON.stringify(transform.expr)}${code !== void 0 ? ` [${code}]` : ""}: ${why}`);\n    this.lang = transform.lang;\n    this.expr = transform.expr;\n    this.code = code;\n  }\n};\nfunction unpackEnvelope(payload) {\n  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {\n    throw new NotAnEnvelope(`typed pool: the payload is not an envelope { settings, input } \\u2014 got ${brief(payload)}`);\n  }\n  const p = payload;\n  for (const k of ["settings", "input"]) {\n    if (!(k in p)) throw new NotAnEnvelope(`typed pool: the payload is not an envelope \\u2014 it has no "${k}" key (keys: ${Object.keys(p).map((x) => `"${x}"`).join(", ") || "none"})`);\n  }\n  const settings = p.settings;\n  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {\n    throw new NotAnEnvelope(`typed pool: the envelope\'s settings is not a plain object \\u2014 got ${brief(settings)}`);\n  }\n  const env = { settings, input: p.input };\n  if ("transform" in p) {\n    const t = p.transform;\n    const wellFormed = typeof t === "object" && t !== null && !Array.isArray(t) && typeof t.lang === "string" && typeof t.expr === "string" && Object.keys(t).length === 2;\n    if (!wellFormed) throw new NotAnEnvelope(`typed pool: the envelope\'s transform is not { lang, expr } \\u2014 got ${brief(p.transform)}`);\n    env.transform = { lang: t.lang, expr: t.expr };\n  }\n  return env;\n}\nfunction brief(v) {\n  const s = printable(v);\n  return s.length > 120 ? `${s.slice(0, 117)}...` : s;\n}\nfunction printable(v) {\n  try {\n    const j = JSON.stringify(v);\n    if (j !== void 0) return j;\n  } catch {\n  }\n  try {\n    return String(v);\n  } catch {\n    return `an unprintable ${typeof v}`;\n  }\n}\nfunction codeOf(e) {\n  const c = e?.code;\n  return typeof c === "string" && c.length ? c : void 0;\n}\nfunction messageOf(e) {\n  if (e instanceof Error) return e.message;\n  try {\n    return String(e);\n  } catch {\n    return printable(e);\n  }\n}\nvar EnvelopeWorker = class {\n  cfg;\n  workerContext;\n  inner = null;\n  /**\n   * **Set by `setup()` when the pool config names no worker \u2014 a type that only TRANSFORMS** (ADR 0075).\n   * It is a SEPARATE field from `inner === null` on purpose, and that is the whole of this arm\'s\n   * correctness: `inner` is null before `setup()` and after `teardown()` too, which are LIFECYCLE\n   * states `run()` has refused by name since v0.17, so reading the absence off `inner` would turn\n   * *run() before setup()* into *return the input untouched* \u2014 a run that silently hands a worker\'s\n   * successor the wrong value instead of failing the task. Measured at W109\'s declaration step: before\n   * this item BOTH of those states threw, and neither was an arm.\n   */\n  noInner = false;\n  /**\n   * The worker half of each language the pool config names, loaded in `setup()` \u2014 or the reason\n   * it did not load, REMEMBERED so that `run()` can fail the task with it (the maintainer\'s call,\n   * see `setup()`).\n   */\n  langs = /* @__PURE__ */ new Map();\n  /** Each distinct `(lang, expr)` compiled ONCE per worker instance, never per task \u2014 P17 decision 3. */\n  compiled = /* @__PURE__ */ new Map();\n  /**\n   * **Why this worker could not set up, REMEMBERED \u2014 or `null`** \u2014\n   * [W141](../../doc/work-items/w141-a-worker-that-cannot-set-up-fails-its-tasks-and-the-registry-has-one-shape.md),\n   * [Q266](../../doc/questions/q266.md), P31 decision 3: W61\'s road for a language, taken for the whole\n   * of `setup()`. Set by `setup()` instead of throwing; read FIRST by `run()`, which fails every task\n   * with it; cleared by `teardown()`, so a torn-down worker is in its constructed state again.\n   */\n  setupFailure = null;\n  /**\n   * Both arguments are kept, and the second is forwarded to the inner worker: the scheduler passes\n   * its worker-level context here, and a worker that only accepts `config` silently loses the\n   * ability to self-terminate (the scheduler\'s own reference, \xA74).\n   */\n  constructor(config, workerContext) {\n    this.cfg = config;\n    this.workerContext = workerContext;\n  }\n  /**\n   * Loads the type\'s worker and runs ITS setup \u2014 a module with no default class is refused by\n   * name, as at v0.17 \u2014 then the worker half of every language the pool config names, ONCE per\n   * worker instance (P17 decision 3).\n   *\n   * **A language module that FAILS TO LOAD does not throw here; the failure is remembered and\n   * every task whose transform names that language fails at `run()` with it.** Measured at W61\'s\n   * declaration, both runtimes, inline and threaded: a wrapper whose `setup()` throws leaves every\n   * task of the pool `pending` with `attempts: 0`, the pool restarts its worker, and the scheduler\n   * emits nothing a driver could turn into a record \u2014 the failure is reported on the POOL as\n   * `worker.setup.failed` and `task.requeue_required`, a worker error and not a task\'s, which is\n   * P17 prediction 2\'s stated reversal condition. The maintainer chose this road at W61\'s\n   * stop-and-ask (ADR 0051 rule 5): a URL that does not resolve, a module with no default compile\n   * function, or an empty URL, each becomes a `TransformFailed` naming the language and the load\n   * error, on exactly the tasks that need that language \u2014 a task with no transform, or one in a\n   * language that did load, still runs on this worker.\n   *\n   * **And since W141 the same is true of the TYPE\'s own worker: this method never throws** \u2014 Q266,\n   * P31 decision 3, W61\'s road taken for the whole of `setup()`. F1 is a fact about THIS method\n   * throwing, whatever threw, and W141 measured it again on 0.5.2 through `createRuntime`: three\n   * tasks on a worker whose `setup()` throws stay `pending` for ever in both pool modes, the pool\n   * requeueing them on each worker failure until its restart limit, and the run\'s fold says\n   * `running`. So every way the type\'s worker can fail to set up \u2014 the module does not load, it\n   * exports no default class, its constructor throws, its own `setup()` throws \u2014 and the two\n   * pool-config refusals this method made by name, are REMEMBERED in `setupFailure`, and `run()`\n   * fails every task on this worker with it: an ordinary task failure, which the run routes per\n   * ADR 0004 \u2014 down an `on: ["failed"]` edge on an optional node, parked `user_action` on a\n   * non-optional one. **A constructed inner worker is torn down at once**, because the scheduler\n   * tears down a worker whose `setup()` threw (its own reference, \xA76: *a failing `setup()` still\n   * tears the worker down*) and this class is now the only thing that knows one did. The worker\n   * stays up and fails every task until the pool is rebuilt: a setup that failed for a transient\n   * reason is not retried here (W141\'s Out).\n   */\n  async setup() {\n    this.setupFailure = null;\n    try {\n      await this.setupOrThrow();\n    } catch (e) {\n      this.setupFailure = messageOf(e);\n      const inner = this.inner;\n      this.inner = null;\n      this.noInner = false;\n      this.langs.clear();\n      if (inner !== null) {\n        try {\n          await inner.teardown?.();\n        } catch (t) {\n          this.setupFailure += ` (and its teardown() after the failed setup threw too: ${messageOf(t)})`;\n        }\n      }\n    }\n  }\n  /** What `setup()` did until W141, throws and all; `setup()` turns each throw into `setupFailure`. */\n  async setupOrThrow() {\n    if (this.cfg?.transformOnly === true) {\n      if (this.cfg.worker !== void 0) {\n        throw new Error(`envelope worker: the pool config says transformOnly AND names worker ${brief(this.cfg.worker)} \\u2014 a type either has an inner worker or only transforms`);\n      }\n      this.noInner = true;\n      for (const [name, url] of Object.entries(this.cfg.languages ?? {})) {\n        this.langs.set(name, await this.loadLanguage(name, url));\n      }\n      return;\n    }\n    if (typeof this.cfg?.worker !== "string" || this.cfg.worker.length === 0) {\n      throw new Error(`envelope worker: the pool config names no worker URL \\u2014 got ${brief(this.cfg)}`);\n    }\n    const workerUrl = this.cfg.worker;\n    let mod;\n    try {\n      mod = await import(workerUrl);\n    } catch (e) {\n      throw new Error(`envelope worker: the type\'s worker ${JSON.stringify(workerUrl)} did not load: ${messageOf(e)}`);\n    }\n    if (typeof mod.default !== "function" || !mod.default.prototype) {\n      throw new Error(`envelope worker: the type\'s worker ${JSON.stringify(workerUrl)} must export a default class`);\n    }\n    const Inner = mod.default;\n    try {\n      this.inner = new Inner(this.cfg.config ?? {}, this.workerContext);\n    } catch (e) {\n      throw new Error(`envelope worker: the type\'s worker ${JSON.stringify(workerUrl)} threw from its constructor: ${messageOf(e)}`);\n    }\n    try {\n      await this.inner.setup?.();\n    } catch (e) {\n      throw new Error(`envelope worker: the type\'s worker ${JSON.stringify(workerUrl)} threw from its setup(): ${messageOf(e)}`);\n    }\n    for (const [name, url] of Object.entries(this.cfg.languages ?? {})) {\n      this.langs.set(name, await this.loadLanguage(name, url));\n    }\n  }\n  /** One language\'s worker half, or the Error that stands in for it \u2014 never a throw (see `setup()`). */\n  async loadLanguage(name, url) {\n    if (typeof url !== "string" || url.length === 0) {\n      return new Error(`language "${name}" names no worker module URL in the pool config \\u2014 got ${brief(url)}`);\n    }\n    try {\n      const lm = await import(url);\n      if (typeof lm.default !== "function") {\n        return new Error(`language "${name}"\'s worker module ${url} must export a default compile function (got ${typeof lm.default})`);\n      }\n      return lm.default;\n    } catch (e) {\n      return new Error(`language "${name}"\'s worker module ${url} did not load: ${messageOf(e)}`);\n    }\n  }\n  /**\n   * `FD-C5`: the inner worker receives `{ settings, input }` and nothing else. `FD-C6`: when the\n   * envelope carries a `transform`, `input` is the evaluation of that expression over the value\n   * received, with the node\'s settings bound as `$settings`, and the third key is consumed here.\n   */\n  async run(payload, context) {\n    if (this.setupFailure !== null) {\n      throw new Error(`${this.setupFailure} \\u2014 every task on this worker fails with this until the pool is rebuilt`);\n    }\n    if (this.inner === null && !this.noInner) throw new Error("envelope worker: run() before setup() \\u2014 the inner worker is not loaded");\n    const env = unpackEnvelope(payload);\n    if (this.noInner) {\n      if (env.transform === void 0) {\n        throw new NotAnEnvelope("typed pool: this pool`s type names no worker, so the envelope must carry a transform \\u2014 there is nothing else for the task to do (FD-V46 refuses such a node at construction)");\n      }\n      return await this.transform(env.transform, env.input, env.settings);\n    }\n    const input = env.transform === void 0 ? env.input : await this.transform(env.transform, env.input, env.settings);\n    return await this.inner.run({ settings: env.settings, input }, context);\n  }\n  /** Evaluates one declared transform; every failure is a `TransformFailed` naming what failed and why. */\n  async transform(t, input, settings) {\n    const compile = this.langs.get(t.lang);\n    if (compile === void 0) {\n      const carried = Object.keys(this.cfg.languages ?? {}).map((x) => `"${x}"`).join(", ") || "no languages";\n      throw new TransformFailed(t, void 0, `language "${t.lang}" is not loaded in this pool (the pool config carries ${carried}) \\u2014 the bootstrap helper writes an adapter URL for a type some node of which declares a transform, and needs the flow and the languages to do it`);\n    }\n    if (compile instanceof Error) {\n      throw new TransformFailed(t, void 0, `${compile.message} \\u2014 every task transforming in "${t.lang}" on this worker fails with this until the pool is rebuilt`);\n    }\n    const key = JSON.stringify([t.lang, t.expr]);\n    let compiled = this.compiled.get(key);\n    if (compiled === void 0) {\n      try {\n        compiled = compile(t.expr);\n      } catch (e) {\n        throw new TransformFailed(t, codeOf(e), `the worker half of "${t.lang}" refused the expression the registry half accepted: ${messageOf(e)}`);\n      }\n      if (typeof compiled?.evaluate !== "function") {\n        throw new TransformFailed(t, void 0, `the worker half of "${t.lang}" compiled to ${brief(compiled)}, which has no evaluate(input, settings)`);\n      }\n      this.compiled.set(key, compiled);\n    }\n    try {\n      return await compiled.evaluate(input, settings);\n    } catch (e) {\n      throw new TransformFailed(t, codeOf(e), messageOf(e));\n    }\n  }\n  async teardown() {\n    await this.inner?.teardown?.();\n    this.inner = null;\n    this.noInner = false;\n    this.setupFailure = null;\n    this.langs.clear();\n    this.compiled.clear();\n  }\n};\nexport {\n  NotAnEnvelope,\n  TransformFailed,\n  EnvelopeWorker as default,\n  unpackEnvelope\n};\n'], { type: "text/javascript" }));
+var envelope_worker_default = URL.createObjectURL(new Blob(['// src/scheduler/envelope-worker.ts\nvar NotAnEnvelope = class extends Error {\n};\nvar TransformFailed = class extends Error {\n  lang;\n  expr;\n  code;\n  constructor(transform, code, why) {\n    super(`transform failed \\u2014 ${transform.lang} ${JSON.stringify(transform.expr)}${code !== void 0 ? ` [${code}]` : ""}: ${why}`);\n    this.lang = transform.lang;\n    this.expr = transform.expr;\n    this.code = code;\n  }\n};\nfunction unpackEnvelope(payload) {\n  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {\n    throw new NotAnEnvelope(`typed pool: the payload is not an envelope { settings, input } \\u2014 got ${brief(payload)}`);\n  }\n  const p = payload;\n  for (const k of ["settings", "input"]) {\n    if (!(k in p)) throw new NotAnEnvelope(`typed pool: the payload is not an envelope \\u2014 it has no "${k}" key (keys: ${Object.keys(p).map((x) => `"${x}"`).join(", ") || "none"})`);\n  }\n  const settings = p.settings;\n  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {\n    throw new NotAnEnvelope(`typed pool: the envelope\'s settings is not a plain object \\u2014 got ${brief(settings)}`);\n  }\n  const env = { settings, input: p.input };\n  if ("transform" in p) {\n    const t = p.transform;\n    const wellFormed = typeof t === "object" && t !== null && !Array.isArray(t) && typeof t.lang === "string" && typeof t.expr === "string" && Object.keys(t).length === 2;\n    if (!wellFormed) throw new NotAnEnvelope(`typed pool: the envelope\'s transform is not { lang, expr } \\u2014 got ${brief(p.transform)}`);\n    env.transform = { lang: t.lang, expr: t.expr };\n  }\n  return env;\n}\nfunction brief(v) {\n  const s = printable(v);\n  return s.length > 120 ? `${s.slice(0, 117)}...` : s;\n}\nfunction printable(v) {\n  try {\n    const j = JSON.stringify(v);\n    if (j !== void 0) return j;\n  } catch {\n  }\n  try {\n    return String(v);\n  } catch {\n    return `an unprintable ${typeof v}`;\n  }\n}\nfunction codeOf(e) {\n  const c = e?.code;\n  return typeof c === "string" && c.length ? c : void 0;\n}\nfunction messageOf(e) {\n  if (e instanceof Error) return e.message;\n  try {\n    return String(e);\n  } catch {\n    return printable(e);\n  }\n}\nvar EnvelopeWorker = class {\n  cfg;\n  workerContext;\n  inner = null;\n  /**\n   * **Set by `setup()` when the pool config names no worker \u2014 a type that only TRANSFORMS** (ADR 0075).\n   * It is a SEPARATE field from `inner === null` on purpose, and that is the whole of this arm\'s\n   * correctness: `inner` is null before `setup()` and after `teardown()` too, which are LIFECYCLE\n   * states `run()` has refused by name since v0.17, so reading the absence off `inner` would turn\n   * *run() before setup()* into *return the input untouched* \u2014 a run that silently hands a worker\'s\n   * successor the wrong value instead of failing the task. Measured at W109\'s declaration step: before\n   * this item BOTH of those states threw, and neither was an arm.\n   */\n  noInner = false;\n  /**\n   * The worker half of each language the pool config names, loaded in `setup()` \u2014 or the reason\n   * it did not load, REMEMBERED so that `run()` can fail the task with it (the maintainer\'s call,\n   * see `setup()`).\n   */\n  langs = /* @__PURE__ */ new Map();\n  /** Each distinct `(lang, expr)` compiled ONCE per worker instance, never per task \u2014 P17 decision 3. */\n  compiled = /* @__PURE__ */ new Map();\n  /**\n   * **Why this worker could not set up, REMEMBERED \u2014 or `null`** \u2014\n   * [W141](../../doc/work-items/w141-a-worker-that-cannot-set-up-fails-its-tasks-and-the-registry-has-one-shape.md),\n   * [Q266](../../doc/questions/q266.md), P31 decision 3: W61\'s road for a language, taken for the whole\n   * of `setup()`. Set by `setup()` instead of throwing; read FIRST by `run()`, which fails every task\n   * with it; cleared by `teardown()`, so a torn-down worker is in its constructed state again.\n   */\n  setupFailure = null;\n  /**\n   * Both arguments are kept, and the second is forwarded to the inner worker: the scheduler passes\n   * its worker-level context here, and a worker that only accepts `config` silently loses the\n   * ability to self-terminate (the scheduler\'s own reference, \xA74).\n   */\n  constructor(config, workerContext) {\n    this.cfg = config;\n    this.workerContext = workerContext;\n  }\n  /**\n   * Loads the type\'s worker and runs ITS setup \u2014 a module with no default class is refused by\n   * name, as at v0.17 \u2014 then the worker half of every language the pool config names, ONCE per\n   * worker instance (P17 decision 3).\n   *\n   * **A language module that FAILS TO LOAD does not throw here; the failure is remembered and\n   * every task whose transform names that language fails at `run()` with it.** Measured at W61\'s\n   * declaration, both runtimes, inline and threaded: a wrapper whose `setup()` throws leaves every\n   * task of the pool `pending` with `attempts: 0`, the pool restarts its worker, and the scheduler\n   * emits nothing a driver could turn into a record \u2014 the failure is reported on the POOL as\n   * `worker.setup.failed` and `task.requeue_required`, a worker error and not a task\'s, which is\n   * P17 prediction 2\'s stated reversal condition. The maintainer chose this road at W61\'s\n   * stop-and-ask (ADR 0051 rule 5): a URL that does not resolve, a module with no default compile\n   * function, or an empty URL, each becomes a `TransformFailed` naming the language and the load\n   * error, on exactly the tasks that need that language \u2014 a task with no transform, or one in a\n   * language that did load, still runs on this worker.\n   *\n   * **And since W141 the same is true of the TYPE\'s own worker: this method never throws** \u2014 Q266,\n   * P31 decision 3, W61\'s road taken for the whole of `setup()`. F1 is a fact about THIS method\n   * throwing, whatever threw, and W141 measured it again on 0.5.2 through `createRuntime`: three\n   * tasks on a worker whose `setup()` throws stay `pending` for ever in both pool modes, the pool\n   * requeueing them on each worker failure until its restart limit, and the run\'s fold says\n   * `running`. So every way the type\'s worker can fail to set up \u2014 the module does not load, it\n   * exports no default class, its constructor throws, its own `setup()` throws \u2014 and the two\n   * pool-config refusals this method made by name, are REMEMBERED in `setupFailure`, and `run()`\n   * fails every task on this worker with it: an ordinary task failure, which the run routes per\n   * ADR 0004 \u2014 down an `on: ["failed"]` edge on an optional node, parked `user_action` on a\n   * non-optional one. **A constructed inner worker is torn down at once**, because the scheduler\n   * tears down a worker whose `setup()` threw (its own reference, \xA76: *a failing `setup()` still\n   * tears the worker down*) and this class is now the only thing that knows one did. The worker\n   * stays up and fails every task until the pool is rebuilt: a setup that failed for a transient\n   * reason is not retried here (W141\'s Out).\n   */\n  async setup() {\n    this.setupFailure = null;\n    try {\n      await this.setupOrThrow();\n    } catch (e) {\n      this.setupFailure = messageOf(e);\n      const inner = this.inner;\n      this.inner = null;\n      this.noInner = false;\n      this.langs.clear();\n      if (inner !== null) {\n        try {\n          await inner.teardown?.();\n        } catch (t) {\n          this.setupFailure += ` (and its teardown() after the failed setup threw too: ${messageOf(t)})`;\n        }\n      }\n    }\n  }\n  /** What `setup()` did until W141, throws and all; `setup()` turns each throw into `setupFailure`. */\n  async setupOrThrow() {\n    if (this.cfg?.transformOnly === true) {\n      if (this.cfg.worker !== void 0) {\n        throw new Error(`envelope worker: the pool config says transformOnly AND names worker ${brief(this.cfg.worker)} \\u2014 a type either has an inner worker or only transforms`);\n      }\n      this.noInner = true;\n      for (const [name, url] of Object.entries(this.cfg.languages ?? {})) {\n        this.langs.set(name, await this.loadLanguage(name, url));\n      }\n      return;\n    }\n    if (typeof this.cfg?.worker !== "string" || this.cfg.worker.length === 0) {\n      throw new Error(`envelope worker: the pool config names no worker URL \\u2014 got ${brief(this.cfg)}`);\n    }\n    const workerUrl = this.cfg.worker;\n    let mod;\n    try {\n      mod = await import(workerUrl);\n    } catch (e) {\n      throw new Error(`envelope worker: the type\'s worker ${JSON.stringify(workerUrl)} did not load: ${messageOf(e)}`);\n    }\n    if (typeof mod.default !== "function" || !mod.default.prototype) {\n      throw new Error(`envelope worker: the type\'s worker ${JSON.stringify(workerUrl)} must export a default class`);\n    }\n    const Inner = mod.default;\n    try {\n      this.inner = new Inner(this.cfg.config ?? {}, this.workerContext);\n    } catch (e) {\n      throw new Error(`envelope worker: the type\'s worker ${JSON.stringify(workerUrl)} threw from its constructor: ${messageOf(e)}`);\n    }\n    try {\n      await this.inner.setup?.();\n    } catch (e) {\n      throw new Error(`envelope worker: the type\'s worker ${JSON.stringify(workerUrl)} threw from its setup(): ${messageOf(e)}`);\n    }\n    for (const [name, url] of Object.entries(this.cfg.languages ?? {})) {\n      this.langs.set(name, await this.loadLanguage(name, url));\n    }\n  }\n  /** One language\'s worker half, or the Error that stands in for it \u2014 never a throw (see `setup()`). */\n  async loadLanguage(name, url) {\n    if (typeof url !== "string" || url.length === 0) {\n      return new Error(`language "${name}" names no worker module URL in the pool config \\u2014 got ${brief(url)}`);\n    }\n    try {\n      const lm = await import(url);\n      if (typeof lm.default !== "function") {\n        return new Error(`language "${name}"\'s worker module ${url} must export a default compile function (got ${typeof lm.default})`);\n      }\n      return lm.default;\n    } catch (e) {\n      return new Error(`language "${name}"\'s worker module ${url} did not load: ${messageOf(e)}`);\n    }\n  }\n  /**\n   * `FD-C5`: the inner worker receives `{ settings, input }` as its payload, and the scheduler\'s task context as its\n   * second argument, passed through untouched (W159). `FD-C6`: when the\n   * envelope carries a `transform`, `input` is the evaluation of that expression over the value\n   * received, with the node\'s settings bound as `$settings`, and the third key is consumed here.\n   */\n  async run(payload, context) {\n    if (this.setupFailure !== null) {\n      throw new Error(`${this.setupFailure} \\u2014 every task on this worker fails with this until the pool is rebuilt`);\n    }\n    if (this.inner === null && !this.noInner) throw new Error("envelope worker: run() before setup() \\u2014 the inner worker is not loaded");\n    const env = unpackEnvelope(payload);\n    if (this.noInner) {\n      if (env.transform === void 0) {\n        throw new NotAnEnvelope("typed pool: this pool`s type names no worker, so the envelope must carry a transform \\u2014 there is nothing else for the task to do (FD-V46 refuses such a node at construction)");\n      }\n      return await this.transform(env.transform, env.input, env.settings);\n    }\n    const input = env.transform === void 0 ? env.input : await this.transform(env.transform, env.input, env.settings);\n    return await this.inner.run({ settings: env.settings, input }, context);\n  }\n  /** Evaluates one declared transform; every failure is a `TransformFailed` naming what failed and why. */\n  async transform(t, input, settings) {\n    const compile = this.langs.get(t.lang);\n    if (compile === void 0) {\n      const carried = Object.keys(this.cfg.languages ?? {}).map((x) => `"${x}"`).join(", ") || "no languages";\n      throw new TransformFailed(t, void 0, `language "${t.lang}" is not loaded in this pool (the pool config carries ${carried}) \\u2014 the bootstrap helper writes every language it is given into every pool, so this one was not in the registry the pool was built from`);\n    }\n    if (compile instanceof Error) {\n      throw new TransformFailed(t, void 0, `${compile.message} \\u2014 every task transforming in "${t.lang}" on this worker fails with this until the pool is rebuilt`);\n    }\n    const key = JSON.stringify([t.lang, t.expr]);\n    let compiled = this.compiled.get(key);\n    if (compiled === void 0) {\n      try {\n        compiled = compile(t.expr);\n      } catch (e) {\n        throw new TransformFailed(t, codeOf(e), `the worker half of "${t.lang}" refused the expression the registry half accepted: ${messageOf(e)}`);\n      }\n      if (typeof compiled?.evaluate !== "function") {\n        throw new TransformFailed(t, void 0, `the worker half of "${t.lang}" compiled to ${brief(compiled)}, which has no evaluate(input, settings)`);\n      }\n      this.compiled.set(key, compiled);\n    }\n    try {\n      return await compiled.evaluate(input, settings);\n    } catch (e) {\n      throw new TransformFailed(t, codeOf(e), messageOf(e));\n    }\n  }\n  async teardown() {\n    await this.inner?.teardown?.();\n    this.inner = null;\n    this.noInner = false;\n    this.setupFailure = null;\n    this.langs.clear();\n    this.compiled.clear();\n  }\n};\nexport {\n  NotAnEnvelope,\n  TransformFailed,\n  EnvelopeWorker as default,\n  unpackEnvelope\n};\n'], { type: "text/javascript" }));
 
 // src/scheduler/bootstrap.ts
 var ENVELOPE_WORKER_URL = envelope_worker_default;
 var BootstrapError = class extends Error {
 };
 var defaultCreatePool = (scriptUrl, options) => new WorkerManager(scriptUrl, options);
-function transformLanguagesByType(flows) {
-  const out = /* @__PURE__ */ new Map();
-  for (const flow of flows) {
-    for (const n of flow.nodes) {
-      if (n.kind !== "task") continue;
-      const t = n;
-      if (t.type === void 0 || t.transform === void 0) continue;
-      let set = out.get(t.type);
-      if (set === void 0) {
-        set = /* @__PURE__ */ new Set();
-        out.set(t.type, set);
-      }
-      set.add(t.transform.lang);
-    }
-  }
-  return out;
-}
 function bootstrap(registry, groups = {}, options = {}) {
   checkRegistry(registry);
   const workers = workersOf(registry.workers);
@@ -68,7 +54,7 @@ function bootstrap(registry, groups = {}, options = {}) {
   for (const [key, inst] of named) {
     const entry = types.get(inst.type);
     const def = isDerivation(entry) ? entry : nodeTypeFromDeclaration(entry);
-    derived[key] = derivePool(key, inst.type, def, def.worker === void 0 ? void 0 : workers.get(def.worker), inst.config, groupKeys, ConfigRefused);
+    derived[key] = derivePool(key, inst.type, def, def.worker === void 0 ? void 0 : workers.get(def.worker), inst.config, groupKeys, ConfigRefused, inst.pool);
   }
   for (const [name, entry] of types) if (builtIn(name)) one(name, name, entry, (isDerivation(entry) ? entry : nodeTypeFromDeclaration(entry)).config, TypeDefaultRefused);
   const namedByPools = /* @__PURE__ */ new Set();
@@ -79,28 +65,18 @@ function bootstrap(registry, groups = {}, options = {}) {
     }
   }
   const adapters = languagesOf(options.languages);
-  const byType = transformLanguagesByType(options.flows ?? []);
-  const languagesFor = /* @__PURE__ */ new Map();
-  for (const [name] of types) {
-    const langs = byType.get(name);
-    if (langs === void 0 || langs.size === 0) continue;
-    const urls = {};
-    for (const lang of [...langs].sort()) {
-      const adapter = adapters.get(lang);
-      if (adapter === void 0) {
-        throw new BootstrapError(`node type "${name}" has a node declaring transform.lang "${lang}", and no adapter was given for it (given: ${[...adapters.keys()].sort().map((x) => `"${x}"`).join(", ") || "none"}) \u2014 the wrapper would meet the transform with nothing to evaluate it`);
-      }
-      if (typeof adapter.worker !== "string" || adapter.worker.length === 0) {
-        throw new BootstrapError(`language "${lang}" names no worker module URL \u2014 LanguageAdapter.worker is the URL of the module whose default export compiles and evaluates it; a function cannot cross to a thread`);
-      }
-      urls[lang] = adapter.worker;
+  let languages;
+  for (const lang of [...adapters.keys()].sort()) {
+    const adapter = adapters.get(lang);
+    if (typeof adapter?.worker !== "string" || adapter.worker.length === 0) {
+      throw new BootstrapError(`language "${lang}" names no worker module URL \u2014 LanguageAdapter.worker is the URL of the module whose default export compiles and evaluates it; a function cannot cross to a thread`);
     }
-    languagesFor.set(name, urls);
+    (languages ??= {})[lang] = adapter.worker;
   }
   const createPool = options.createPool ?? defaultCreatePool;
   const workerPools = {};
   for (const [key, p] of Object.entries(derived)) {
-    workerPools[key] = createPool(ENVELOPE_WORKER_URL, poolOptionsOf(p.spec, p.definition.inline, p.worker?.url, languagesFor.get(p.type)));
+    workerPools[key] = createPool(ENVELOPE_WORKER_URL, poolOptionsOf(p.spec, p.definition.inline, p.worker?.url, languages === void 0 ? void 0 : { ...languages }));
   }
   return { workerPools, resourceGroups: { ...groups }, derived };
 }
@@ -122,10 +98,11 @@ var GroupUnusable = class extends RuntimeError {
 };
 var GroupNotBuildable = class extends RuntimeError {
 };
-var LanguageNotBuilt = class extends RuntimeError {
-};
 var RunIdInUse = class extends RuntimeError {
 };
+var LimitKeyMissing = class extends RuntimeError {
+};
+var KEYED_RULE = "FD-R6";
 var BUILT_IN_GROUP_FACTORIES = {
   ConcurrentLimitGroup: (config, key) => new ConcurrentLimitGroup(config.limit, key),
   RateLimitGroup: (config, key) => new RateLimitGroup(config.windows, key),
@@ -161,6 +138,10 @@ function checkGroup(key, typeName, group) {
   return group;
 }
 function createRuntime(document, code = {}, options = {}) {
+  if (options.defaultRetryPolicy !== void 0) {
+    const problem = retryPolicyProblem(options.defaultRetryPolicy);
+    if (problem !== null) throw new InvalidDefinition(["FD-V30"], `defaultRetryPolicy is not a RetryPolicy \u2014 FD-V30: ${problem}`);
+  }
   const resolved = resolveRegistry(document, code);
   const suppliedPredicateNames = code.predicates === void 0 ? [] : code.predicates instanceof Map ? [...code.predicates.keys()] : code.predicates instanceof Set ? [...code.predicates] : Array.isArray(code.predicates) ? [...code.predicates] : Object.keys(code.predicates);
   for (const [what, named, given] of [
@@ -192,7 +173,7 @@ function createRuntime(document, code = {}, options = {}) {
   const nodeTypes = {};
   for (const [name, def] of resolved.nodeTypes) nodeTypes[name] = def;
   const pools = {};
-  for (const [key, p] of resolved.pools) if (key !== p.type) pools[key] = { type: p.type, config: p.config };
+  for (const [key, p] of resolved.pools) if (key !== p.type) pools[key] = { type: p.type, config: p.config, ...p.pool !== void 0 ? { pool: p.pool } : {} };
   const languages = {};
   for (const [name, adapter] of resolved.languages) languages[name] = adapter;
   const namedByPools = {};
@@ -201,8 +182,7 @@ function createRuntime(document, code = {}, options = {}) {
   }
   const built = bootstrap({ workers, nodeTypes, pools }, namedByPools, {
     ...options.createPool !== void 0 ? { createPool: options.createPool } : {},
-    languages,
-    flows: options.flows ?? []
+    languages
   });
   const scheduler = (options.createScheduler ?? ((p, g) => new FyflowScheduler(p, g)))(built.workerPools, groups);
   const predicates = /* @__PURE__ */ new Map();
@@ -220,7 +200,40 @@ function createRuntime(document, code = {}, options = {}) {
     languages,
     ...code.gateTypes !== void 0 ? { gateTypes: code.gateTypes } : {}
   };
-  const builtLanguages = transformLanguagesByType(options.flows ?? []);
+  const validatorRegistry = {
+    predicates: new Set(predicates.keys()),
+    groups: new Set(registry.groups ?? []),
+    nodeTypes: nodeTypesOf(registry.nodeTypes),
+    languages: languagesOf(registry.languages),
+    workers: workersOf(registry.workers),
+    pools: poolsOf(registry.pools),
+    ...registry.gateTypes !== void 0 ? { gateTypes: registry.gateTypes } : {}
+  };
+  const keyedByBuiltIn = /* @__PURE__ */ new Set();
+  for (const [key, g] of resolved.groups) if (g.type === "KeyedRateLimitGroup") keyedByBuiltIn.add(key);
+  const keyedFindings = (flow) => {
+    const nodes = flow?.nodes;
+    if (keyedByBuiltIn.size === 0 || typeof nodes?.[Symbol.iterator] !== "function") return [];
+    const out = [];
+    for (const node of nodes) {
+      if (typeof node !== "object" || node === null) continue;
+      const n = node;
+      if (n.kind !== "task") continue;
+      const poolKey = typeof n.pool === "string" ? n.pool : typeof n.type === "string" ? n.type : void 0;
+      const fromPool = poolKey === void 0 ? [] : resolved.pools.get(poolKey)?.spec.groups ?? [];
+      const fromNode = Array.isArray(n.workerGroups) ? n.workerGroups.filter((g) => typeof g === "string") : [];
+      const reached = [.../* @__PURE__ */ new Set([...fromPool, ...fromNode])].filter((g) => keyedByBuiltIn.has(g)).sort();
+      if (reached.length === 0) continue;
+      const at = typeof n.id === "string" ? n.id : null;
+      out.push({
+        rule: KEYED_RULE,
+        at,
+        detail: `node ${at === null ? "<unnamed>" : q(at)} reaches keyed group${reached.length > 1 ? "s" : ""} ${reached.map(q).join(", ")}, built by the built-in KeyedRateLimitGroup factory with no keyFrom \u2014 so every task of it needs a limitKey, which nothing sets unless start is given a createTask, and without one the scheduler's addTask throws "Missing limit key". Two roads work: pass start a createTask that sets limitKey on the task it builds, or declare the group with a code group type (code.groupTypes) whose create() builds a KeyedRateLimitGroup with a keyFrom that derives the key. A key derived from the flow itself is Q248, deferred`
+      });
+    }
+    return out;
+  };
+  const check = (flow) => [...validateDefinition(flow, validatorRegistry), ...keyedFindings(flow)];
   let minted = 0;
   const inUse = /* @__PURE__ */ new Set();
   const router = settlementRouter(scheduler);
@@ -237,6 +250,7 @@ function createRuntime(document, code = {}, options = {}) {
     scheduler,
     pools: built.derived,
     groups,
+    check,
     start(flow, payload, startOptions = {}) {
       return openRun(flow, payload, startOptions, null);
     },
@@ -252,14 +266,12 @@ function createRuntime(document, code = {}, options = {}) {
   };
   return runtime;
   function openRun(flow, payload, startOptions, from) {
-    for (const [type, langs] of transformLanguagesByType([flow])) {
-      if (!resolved.nodeTypes.has(type)) continue;
-      const carried = builtLanguages.get(type) ?? /* @__PURE__ */ new Set();
-      for (const lang of langs) {
-        if (!carried.has(lang)) {
-          throw new LanguageNotBuilt(type, `flow ${q(flow.flowId)} declares transform.lang ${q(lang)} on a node of type ${q(type)}, and this runtime's pools for that type carry ${carried.size ? [...carried].sort().map(q).join(", ") : "no language"} \u2014 pools are built once, so pass every flow this runtime will run as \`flows\` to createRuntime`);
-        }
-      }
+    const findings = check(flow);
+    const definition = findings.filter((f) => f.rule !== KEYED_RULE);
+    if (definition.length) throw InvalidDefinition.fromFindings(flow.flowId, definition);
+    const keyed = startOptions.createTask === void 0 ? findings.filter((f) => f.rule === KEYED_RULE) : [];
+    if (keyed.length) {
+      throw new LimitKeyMissing(keyed[0].at ?? "<document>", `flow "${flow.flowId}" cannot start with no createTask \u2014 ` + keyed.map((f) => `${f.rule} at ${f.at ?? "<document>"}: ${f.detail}`).join("; ") + " (ADR 0097)");
     }
     const runId = startOptions.runId ?? mint();
     if (inUse.has(runId)) {
@@ -275,10 +287,33 @@ function createRuntime(document, code = {}, options = {}) {
     const settleIfTerminal = () => {
       if (settled || !isTerminal(state)) return;
       settled = true;
+      if (state.outcome === "interrupted" && stopping.size > 0) {
+        const at = state;
+        const fin = () => {
+          settle(at);
+          router.release(runId);
+        };
+        void Promise.allSettled([...stopping]).then(fin);
+        return;
+      }
       settle(state);
       router.release(runId);
     };
-    const scheduler2 = router.forRun(runId);
+    const view = router.forRun(runId);
+    const stopping = /* @__PURE__ */ new Set();
+    const viewCancel = view.cancel;
+    const scheduler2 = typeof viewCancel === "function" ? {
+      ...view,
+      cancel: (id, cancelOptions) => {
+        const p = viewCancel(id, cancelOptions);
+        stopping.add(p);
+        const drop = () => {
+          stopping.delete(p);
+        };
+        p.then(drop, drop);
+        return p;
+      }
+    } : view;
     const driver = new Driver(flow, {
       runId,
       scheduler: scheduler2,
@@ -306,8 +341,13 @@ function createRuntime(document, code = {}, options = {}) {
         queueMicrotask(settleIfTerminal);
         startOptions.onFoldInput?.(input, seq);
       },
+      ...startOptions.onHeader !== void 0 ? { onHeader: startOptions.onHeader } : {},
       ...startOptions.onRegionEvent !== void 0 ? { onRegionEvent: startOptions.onRegionEvent } : {},
       ...startOptions.onRunFailure !== void 0 ? { onRunFailure: startOptions.onRunFailure } : {},
+      // **Spread only when given** (`RN-R42`): the driver subscribes the pass-through events for a callback present, so an
+      // `undefined` forwarded here must stay ABSENT — and on a runtime the scheduler is subscribed once the first run asks.
+      ...startOptions.onTaskMessage !== void 0 ? { onTaskMessage: startOptions.onTaskMessage } : {},
+      ...startOptions.onTaskProgress !== void 0 ? { onTaskProgress: startOptions.onTaskProgress } : {},
       ...startOptions.onUnsatisfiableJoin !== void 0 ? { onUnsatisfiableJoin: startOptions.onUnsatisfiableJoin } : {},
       ...startOptions.onUnmintedTask !== void 0 ? { onUnmintedTask: startOptions.onUnmintedTask } : {},
       ...startOptions.onNonconformingResult !== void 0 ? { onNonconformingResult: startOptions.onNonconformingResult } : {},
@@ -321,7 +361,7 @@ function createRuntime(document, code = {}, options = {}) {
       router.release(runId);
       throw e;
     }
-    return { driver, done, header: driver.checkpoint().header };
+    return { driver, done, header: driver.checkpoint().header, stop: (stopOptions) => driver.stop(stopOptions) };
   }
 }
 function settlementRouter(scheduler) {
@@ -329,7 +369,8 @@ function settlementRouter(scheduler) {
   const every = /* @__PURE__ */ new Map();
   const deliver = (name) => (e) => {
     const detail = "detail" in e ? e.detail : void 0;
-    const id = typeof detail === "object" && detail !== null ? detail.id : void 0;
+    const d = typeof detail === "object" && detail !== null ? detail : void 0;
+    const id = typeof d?.id === "string" ? d.id : d?.taskId;
     let runId = null;
     if (typeof id === "string") {
       try {
@@ -355,7 +396,9 @@ function settlementRouter(scheduler) {
   };
   return {
     forRun(runId) {
+      const cancel = scheduler.cancel;
       return {
+        ...typeof cancel === "function" ? { cancel: (id, options) => cancel.call(scheduler, id, options) } : {},
         addTask: (task, options) => scheduler.addTask(task, options),
         addEventListener(name, listener) {
           let mine = byRun.get(runId);
@@ -589,7 +632,8 @@ var EnvelopeWorker = class {
     }
   }
   /**
-   * `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.
    */
@@ -613,7 +657,7 @@ var EnvelopeWorker = class {
     const compile = this.langs.get(t.lang);
     if (compile === void 0) {
       const carried = Object.keys(this.cfg.languages ?? {}).map((x) => `"${x}"`).join(", ") || "no languages";
-      throw new TransformFailed(t, void 0, `language "${t.lang}" is not loaded in this pool (the pool config carries ${carried}) \u2014 the bootstrap helper writes an adapter URL for a type some node of which declares a transform, and needs the flow and the languages to do it`);
+      throw new TransformFailed(t, void 0, `language "${t.lang}" is not loaded in this pool (the pool config carries ${carried}) \u2014 the bootstrap helper writes every language it is given into every pool, so this one was not in the registry the pool was built from`);
     }
     if (compile instanceof Error) {
       throw new TransformFailed(t, void 0, `${compile.message} \u2014 every task transforming in "${t.lang}" on this worker fails with this until the pool is rebuilt`);
@@ -654,13 +698,12 @@ export {
   GROUP_MEMBERS,
   GroupNotBuildable,
   GroupUnusable,
-  LanguageNotBuilt,
+  LimitKeyMissing,
   NotAnEnvelope,
   RunIdInUse,
   RuntimeError,
   TransformFailed,
   bootstrap,
   createRuntime,
-  transformLanguagesByType,
   unpackEnvelope
 };