fyflow-orchestration 0.10.0 → 0.11.0

package/dist/browser/index.js

@@ -9,23 +9,28 @@ import {
   ConfigRefused,
   DECLARED_POOL_KEYS,
   DOCUMENT_KEYS,
+  DOC_KEYS_DECLARED,
   DerivationRefused,
   Driver,
   DuplicateTaskId,
   EDGE_KEYS_DECLARED,
+  EDGE_KEYS_REQUIRED,
   GATE_TYPE_KEYS,
   GateTypeRefused,
   GroupConfigRefused,
   GroupTypeMissing,
+  ID_RE_COPY,
   INSTANCE_KEYS,
   InvalidDefinition,
   InvalidRunId,
   InvalidTaskId,
   KEY_PATH_RE,
+  KINDS_COPY,
   MESSAGE_OPTION_KEYS,
   MissingJoinPolicy,
   MultipleRuns,
   NODE_KEYS_DECLARED,
+  NODE_KEYS_REQUIRED,
   NODE_TYPE_DECLARATION_KEYS,
   NameCollision,
   NameMissing,
@@ -42,6 +47,7 @@ import {
   PREDICATE_ROOTS,
   PoolTypeMissing,
   RETRY_POLICY_KEYS,
+  ROUTABLE_STATES,
   RegistryError,
   ResumeRefused,
   RunControlRefused,
@@ -145,7 +151,530 @@ import {
   visibilityKey,
   witness,
   workersOf
-} from "./chunks/chunk-NA6QQAZ2.js";
+} from "./chunks/chunk-5CVSWDCB.js";
+
+// src/definition/definition-schema.ts
+var DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+var idOrNonString = () => ({ anyOf: [ref("id"), { not: { type: "string" } }] });
+var ref = (name) => ({ $ref: `#/$defs/${name}` });
+function body(re, name) {
+  const s = re.source;
+  if (!s.startsWith("^") || !s.endsWith("$") || re.flags !== "") {
+    throw new Error(`definitionSchema: ${name} is no longer an anchored, flagless expression (${String(re)}) \u2014 its body cannot be reused as a pattern`);
+  }
+  return s.slice(1, -1);
+}
+function described(table, key, where) {
+  const d = Object.prototype.hasOwnProperty.call(table, key) ? table[key] : void 0;
+  if (d === void 0) throw new Error(`definitionSchema: ${where} declares the key "${key}" and no description is written for it`);
+  return d;
+}
+var DOC_DESCRIPTIONS = {
+  flowId: "The flow's id: 1-64 characters from [A-Za-z0-9_-] (FD-V16), the charset of spec/task-id.md \u2014 it is a segment of every task id this flow mints.",
+  version: "The definition's version, an integer >= 1 (FD-V21), managed by the author. The driver does not interpret it.",
+  entry: "The id of the node a run starts at. It must name a node of this document that is neither a join nor an end (FD-V3 \u2014 validateDefinition's, not this schema's).",
+  nodes: "One object per node, order irrelevant. Node ids are unique across the document (FD-V1 \u2014 validateDefinition's)."
+};
+var NODE_DESCRIPTIONS = {
+  id: "The node's id: 1-64 characters from [A-Za-z0-9_-] (FD-V16), unique in the document (FD-V1). It is a segment of the task id the node mints.",
+  kind: 'Which of the seven node kinds this is (FD-V24). There is no "decision" kind: a decision is an edge\'s `when`, and a decision with memory is a `gate`.',
+  edges: "Where the run goes from here, in order. The first eligible edge whose `when` holds is taken; an edge with no `on` routes `done` only.",
+  needs: "What this node receives instead of the previous node's output: an object whose keys name what the node receives and whose values are references (spec/flow-definition.md section 3, FD-V26). Where each reference points is validateDefinition's (FD-V27-FD-V29, FD-V49).",
+  settings: "Settings, a plain object.",
+  type: "A registered type's name."
+};
+var KIND_DESCRIPTIONS = {
+  task: {
+    kind: "A `task`: the one kind that is dispatched \u2014 one scheduler task, run by the worker of the node type it names.",
+    type: "The registered NODE type that runs this task (required since v0.19). Which names are registered is the registry's: FD-V32, validateDefinition's. The built-in \"Transform\" runs nothing but the node's own `transform` (FD-V46).",
+    pool: "A named pool INSTANCE of this node's type, from the registry's `pools` (FD-V38). Absent: the type's default instance, keyed by the type's name.",
+    settings: "Settings handed to the worker in its envelope, merged OVER the type's defaults. A plain object; what its worker's settingsSchema says of them is FD-V33's, validateDefinition's.",
+    transform: "An expression the node type's worker wrapper evaluates over this node's input before the worker sees it: exactly { lang, expr } (FD-V37). The language must be registered (FD-V35) and accept the expression (FD-V36) \u2014 validateDefinition's.",
+    optional: "true: the FLOW handles this task's failure \u2014 it ends `failed` and may route a `failed` edge. Absent or false: a failure out of retries waits for a person (`user_action`).",
+    retryPolicy: "How the scheduler retries a failed attempt, inside one task id: exactly { maxRetries, backoffMs } (FD-V30).",
+    workerGroups: "The resource groups the scheduler holds this task to: a non-empty list of distinct group ids (FD-V31). That each id is one the registry's `groups` declares is validateDefinition's.",
+    needs: NODE_DESCRIPTIONS.needs
+  },
+  fanout: {
+    kind: "A `fanout`: opens a region of N branches declared HERE, closed by the one `join` naming it. Dispatches nothing.",
+    branches: "The region's branch entries: at least two distinct node ids (FD-V9), each a task or an ask, none of them its own join (FD-V9, FD-V12 \u2014 validateDefinition's)."
+  },
+  map: {
+    kind: "A `map`: opens a region of ONE branch, opened once per item of an array at run time, closed by the one `join` naming it. Dispatches nothing.",
+    over: "The key, in the value that reaches the map, holding the array of items: 1-64 characters from [A-Za-z0-9_-] (FD-V25).",
+    branch: "The id of the one node each item's instance starts at \u2014 a task or an ask (FD-V25, validateDefinition's).",
+    needs: "What the map receives before it reads `over` (spec/flow-definition.md section 3, FD-V26)."
+  },
+  join: {
+    kind: "A `join`: closes the region its `of` opened, by the join policy the driver is given. Dispatches nothing.",
+    of: "The id of the `fanout` or `map` whose region this closes (FD-V6, validateDefinition's).",
+    edges: "Exactly one edge, carrying neither `when` nor `on` (FD-V7): a join has no outcome for either to read."
+  },
+  end: {
+    kind: "An `end`: terminates one path. No edges.",
+    outcome: "A non-empty, author-defined string (FD-V8). The driver does not interpret it."
+  },
+  gate: {
+    kind: "A `gate`: routes the branch that reaches it by a registered GATE type's decision, and hands on exactly what reached it \u2014 a decision with memory. Dispatches nothing.",
+    type: `The registered GATE type that decides: a built-in (${Object.keys(BUILT_IN_GATE_TYPES).sort().map((t) => `"${t}"`).join(", ")}) or one the registry's \`gateTypes\` adds (FD-V39, validateDefinition's).`,
+    settings: "Settings the gate type reads: a plain object (FD-V40). A `key`, where present, is a key path the library resolves over what reached the gate. What the type's settingsSchema says of the rest is validateDefinition's.",
+    edges: "One edge per route of the gate's type, each carrying `to` and `route` \u2014 an edge with no `route` carries the type's DEFAULT route, which may also be named (FD-V41). That every route is wired exactly once is validateDefinition's."
+  },
+  ask: {
+    kind: `An \`ask\`: waits for a PERSON, whose answer is its output and is routed by its edges as a task's settlement is. Never dispatched. A task's ${ASK_REFUSED_KEYS.map((k) => `\`${k}\``).join(", ")} are refused on an ask (FD-V47).`,
+    settings: "Opaque settings a UI reads: a plain object (FD-V21). The library never reads them.",
+    answerSchema: "The schema a `done` answer is held to, in the library's built-in schema subset (FD-V48, ADR 0053). That an `examples` entry conforms is validateDefinition's (ADR 0056).",
+    needs: "What the person is shown as the ask's input (spec/flow-definition.md section 3, FD-V26)."
+  }
+};
+var EDGE_DESCRIPTIONS = {
+  to: "The id of the node this edge leads to (FD-V2, validateDefinition's).",
+  on: 'The terminal states this edge is eligible for: a non-empty list of distinct "done" / "failed" (FD-V18). Absent: ["done"]. "user_action" suspends rather than routes.',
+  when: "The decision: a registered predicate NAME { predicate }, a declared COMPARISON { path, op, value, default?, length? }, or a flat GROUP { all } or { any } of comparisons (FD-V42-FD-V45). Absent: the edge is the default for its state.",
+  needs: "What this edge's predicate sees beyond its node's outcome \u2014 `needs`' grammar minus \".\" (FD-V26).",
+  route: "On a gate's edge, which of the gate type's routes it carries; absent: the type's DEFAULT route (FD-V41). Refused on every other kind's edge."
+};
+var RETRY_DESCRIPTIONS = {
+  maxRetries: "How many times a failed attempt is re-dispatched: an integer >= 0.",
+  backoffMs: "Milliseconds between a failed attempt and its retry: a finite number >= 0."
+};
+var TRANSFORM_DESCRIPTIONS = {
+  lang: "A registered language's name (FD-V35, validateDefinition's).",
+  expr: "Text that language compiles (FD-V36, validateDefinition's): `$` is the value this node receives, `$settings` its effective settings."
+};
+var PREDICATE_DESCRIPTIONS = {
+  predicate: "A registered predicate's name (FD-V4, validateDefinition's).",
+  path: `A key path over the decision's context, starting at ${PREDICATE_ROOTS.map((r) => `"${r}"`).join(" or ")} and naming a key beyond it (FD-V43).`,
+  op: `One of ${PREDICATE_OPS.join(", ")} (FD-V44). The ordering operators compare numbers and "startsWith" a string \u2014 a comparison between kinds is no match, never a coercion.`,
+  value: "The scalar compared against: null, a boolean, a number or a string (FD-V44).",
+  default: "What is compared where the path does not resolve or resolves to null: a scalar, or \u2014 with `length` \u2014 an array or a string (FD-V44).",
+  length: "Exactly true: compare the LENGTH of the array or string, against a number (FD-V44).",
+  all: "A flat group: a non-empty list of comparisons that must all hold (FD-V45).",
+  any: "A flat group: a non-empty list of comparisons of which one must hold (FD-V45)."
+};
+var SUBSET_DESCRIPTIONS = {
+  type: "One of the seven JSON types, or a non-empty list of distinct ones.",
+  required: "Property names an object must carry.",
+  properties: "A schema, in the subset, per property name.",
+  additionalProperties: "true or false only \u2014 never a schema.",
+  enum: "A non-empty list of the values allowed.",
+  const: "The one value allowed.",
+  minimum: "The smallest number allowed.",
+  maximum: "The largest number allowed.",
+  minLength: "The shortest string allowed: an integer >= 0.",
+  maxLength: "The longest string allowed: an integer >= 0.",
+  items: "ONE schema, in the subset, for every item \u2014 never a tuple.",
+  minItems: "The fewest items allowed: an integer >= 0.",
+  examples: "A non-empty list of values the schema accepts (that each conforms is ADR 0056's check, validateDefinition's).",
+  title: "An annotation: a string, constraining nothing (ADR 0098).",
+  description: "An annotation: a string, constraining nothing (ADR 0098).",
+  readOnly: "An annotation: true or false, constraining nothing (ADR 0098).",
+  writeOnly: "An annotation: true or false, constraining nothing (ADR 0098)."
+};
+var NUMERIC_OPS = ["lt", "lte", "gt", "gte"];
+var STRING_OPS = ["startsWith"];
+var ERROR_PART = "!error";
+function nodeKeySchema(kind, key) {
+  switch (key) {
+    case "id":
+      return ref("id");
+    case "kind":
+      return { const: kind };
+    case "type":
+    case "pool":
+      return { type: "string" };
+    case "settings":
+      return kind === "gate" ? { type: "object", properties: { key: { type: "string", pattern: KEY_PATH_RE.source, description: "A key path: dot-separated object keys, each [A-Za-z0-9_-]{1,64} \u2014 no index, no wildcard, no expression (FD-V40)." } } } : { type: "object" };
+    case "transform":
+      return ref("transform");
+    case "optional":
+      return { type: "boolean" };
+    case "needs":
+      return ref("needs");
+    case "retryPolicy":
+      return ref("retryPolicy");
+    case "workerGroups":
+      return { type: "array", minItems: 1, uniqueItems: true, items: { type: "string" } };
+    // **`branches`' entries and `of` admit a NON-string** — W210's conformity reader, B1: the validator holds both only
+    // through the graph (`FD-V2`, `FD-V6` and `FD-V9` read a string and pass anything else over), so `of: null` on a join
+    // of no region and `["b", "c", 5]` are ACCEPTED there, and refusing them here would refuse what the validator accepts
+    // (ADR 0132 rule 2). A string is held to the id charset. That `FD-V21` should refuse the rest is Q774.
+    case "branches":
+      return { type: "array", minItems: 2, uniqueItems: true, items: idOrNonString() };
+    case "of":
+      return idOrNonString();
+    case "over":
+    case "branch":
+      return ref("id");
+    case "outcome":
+      return { type: "string", minLength: 1 };
+    case "answerSchema":
+      return ref("subsetSchema");
+    case "edges": {
+      if (kind === "join") return { type: "array", minItems: 1, maxItems: 1, items: ref("joinEdge") };
+      if (kind === "gate") return { type: "array", minItems: 1, items: ref("gateEdge") };
+      return { type: "array", minItems: 1, items: ref("edge") };
+    }
+  }
+  throw new Error(`definitionSchema: the "${kind}" kind declares the key "${key}" and no schema is written for it`);
+}
+function edgeKeySchema(key) {
+  switch (key) {
+    case "to":
+      return ref("id");
+    case "on":
+      return { type: "array", minItems: 1, uniqueItems: true, items: { enum: [...ROUTABLE_STATES] } };
+    case "when":
+      return ref("when");
+    case "needs":
+      return ref("edgeNeeds");
+    case "route":
+      return { type: "string" };
+  }
+  throw new Error(`definitionSchema: an edge declares the key "${key}" and no schema is written for it`);
+}
+var EDGE_KEYS_BY_SITE = {
+  edge: (k) => k !== "route",
+  joinEdge: (k) => k !== "route" && k !== "on" && k !== "when",
+  gateEdge: (k) => k === "to" || k === "route"
+};
+var SITE_DESCRIPTIONS = {
+  edge: "An edge of a task or an ask: { to, on?, when?, needs? }.",
+  joinEdge: "A join's one edge: { to, needs? } \u2014 neither `on` nor `when` (FD-V7).",
+  gateEdge: "A gate's edge: { to, route? } and nothing else (FD-V41)."
+};
+function edgeSchema(site) {
+  const keys = EDGE_KEYS_DECLARED.filter(EDGE_KEYS_BY_SITE[site]);
+  return {
+    description: SITE_DESCRIPTIONS[site],
+    type: "object",
+    required: EDGE_KEYS_REQUIRED.filter((k) => keys.includes(k)),
+    properties: Object.fromEntries(keys.map((k) => [k, { ...edgeKeySchema(k), description: described(EDGE_DESCRIPTIONS, k, "an edge") }])),
+    additionalProperties: false
+  };
+}
+function kindSchema(kind) {
+  const keys = NODE_KEYS_DECLARED[kind];
+  const required = NODE_KEYS_REQUIRED[kind];
+  if (keys === void 0 || required === void 0) throw new Error(`definitionSchema: the validator declares no keys for the kind "${kind}"`);
+  const own2 = KIND_DESCRIPTIONS[kind] ?? {};
+  return {
+    description: described(own2, "kind", `the "${kind}" kind`),
+    type: "object",
+    required: [...required],
+    properties: Object.fromEntries(keys.map((k) => [k, {
+      ...nodeKeySchema(kind, k),
+      description: Object.prototype.hasOwnProperty.call(own2, k) ? own2[k] : described(NODE_DESCRIPTIONS, k, `the "${kind}" kind`)
+    }])),
+    additionalProperties: false
+  };
+}
+function subsetKeywordSchema(keyword) {
+  const nonNegInt = { type: "integer", minimum: 0 };
+  switch (keyword) {
+    case "type":
+      return { anyOf: [{ enum: [...SCHEMA_TYPES] }, { type: "array", minItems: 1, uniqueItems: true, items: { enum: [...SCHEMA_TYPES] } }] };
+    case "required":
+      return { type: "array", uniqueItems: true, items: { type: "string" } };
+    case "properties":
+      return { type: "object", additionalProperties: ref("subsetSchema") };
+    case "additionalProperties":
+      return { type: "boolean" };
+    case "enum":
+      return { type: "array", minItems: 1 };
+    case "const":
+      return {};
+    case "minimum":
+    case "maximum":
+      return { type: "number" };
+    case "minLength":
+    case "maxLength":
+    case "minItems":
+      return nonNegInt;
+    case "items":
+      return ref("subsetSchema");
+    case "examples":
+      return { type: "array", minItems: 1 };
+    case "title":
+    case "description":
+      return { type: "string" };
+    case "readOnly":
+    case "writeOnly":
+      return { type: "boolean" };
+  }
+  throw new Error(`definitionSchema: the schema subset declares the keyword "${keyword}" and no schema is written for it`);
+}
+function needsSchema(withSelf, description) {
+  return {
+    description,
+    type: "object",
+    minProperties: 1,
+    propertyNames: ref("id"),
+    additionalProperties: ref(withSelf ? "reference" : "edgeReference")
+  };
+}
+function referenceSchema(withSelf, id) {
+  const aimed = `${id}(?:${ERROR_PART})?\\??`;
+  const tokens = [...withSelf ? ["\\."] : [], "\\$payload", "\\$item", aimed];
+  return {
+    description: (withSelf ? '"." (what this node would have received), ' : "") + `"$payload" (what the run entered with), "$item" (the item of the map instance containing this node), a node id (that node's output), or a node id followed by "!error" (that node's error, null where it succeeded) \u2014 each node form with an optional "?" last (the node may not have run: absent, not refused), and as a one-element array (every output of that node visible on this node's path, in branch-path order; where each form is legal is FD-V28's) (FD-V26).`,
+    anyOf: [
+      { type: "string", pattern: `^(?:${tokens.join("|")})$` },
+      { type: "array", minItems: 1, maxItems: 1, items: { type: "string", pattern: `^${aimed}$` } }
+    ]
+  };
+}
+function leafSchema(id) {
+  const path = `^(?:${PREDICATE_ROOTS.join("|")})(?:\\.${id})+$`;
+  const scalar = () => ({ type: ["null", "boolean", "number", "string"] });
+  const keySchemas = {
+    path: { type: "string", pattern: path },
+    op: { enum: [...PREDICATE_OPS] },
+    value: scalar(),
+    default: { anyOf: [scalar(), { type: "array", items: scalar() }] },
+    length: { const: true }
+  };
+  return {
+    description: "A declared comparison over the decision's context.",
+    type: "object",
+    required: [...PREDICATE_LEAF_REQUIRED],
+    properties: Object.fromEntries(PREDICATE_LEAF_KEYS.map((k) => {
+      const s = keySchemas[k];
+      if (s === void 0) throw new Error(`definitionSchema: a comparison declares the key "${k}" and no schema is written for it`);
+      return [k, { ...s, description: described(PREDICATE_DESCRIPTIONS, k, "a comparison") }];
+    })),
+    additionalProperties: false,
+    allOf: [
+      // `length: true` compares a length — a number — and a length has no prefix; its default stands in for the value.
+      {
+        if: { required: ["length"] },
+        then: { properties: { value: { type: "number" }, op: { not: { enum: [...STRING_OPS] } }, default: { type: ["array", "string"] } } }
+      },
+      // with no `length`: an ordering operator compares a number, and a default is a scalar.
+      {
+        if: { not: { required: ["length"] } },
+        then: { properties: { default: scalar() } }
+      },
+      {
+        if: { required: ["op"], properties: { op: { enum: [...NUMERIC_OPS] } } },
+        then: { anyOf: [{ required: ["length"] }, { properties: { value: { type: "number" } } }] }
+      },
+      {
+        if: { required: ["op"], properties: { op: { enum: [...STRING_OPS] } } },
+        then: { properties: { value: { type: "string" } } }
+      }
+    ]
+  };
+}
+function definitionSchema(registry) {
+  if (registry !== void 0) checkRegistry(registry);
+  const s = staticSchema();
+  if (registry !== void 0) specialise(s, registry);
+  return s;
+}
+function staticSchema() {
+  const id = body(ID_RE_COPY, "ID_RE");
+  body(KEY_PATH_RE, "KEY_PATH_RE");
+  const defs = {
+    id: { description: "A node id: 1-64 characters from [A-Za-z0-9_-] (FD-V16).", type: "string", pattern: `^${id}$` },
+    node: {
+      description: `A node: one of ${KINDS_COPY.join(", ")}, told apart by \`kind\`.`,
+      type: "object",
+      required: ["kind"],
+      properties: { kind: { enum: [...KINDS_COPY] } },
+      allOf: KINDS_COPY.map((k) => ({ if: { required: ["kind"], properties: { kind: { const: k } } }, then: ref(`${k}Node`) }))
+    },
+    ...Object.fromEntries(KINDS_COPY.map((k) => [`${k}Node`, kindSchema(k)])),
+    edge: edgeSchema("edge"),
+    joinEdge: edgeSchema("joinEdge"),
+    gateEdge: edgeSchema("gateEdge"),
+    needs: needsSchema(true, "A node's `needs`: a non-empty object, each key 1-64 characters from [A-Za-z0-9_-], each value a reference (FD-V26)."),
+    edgeNeeds: needsSchema(false, "An edge's `needs`: as a node's, minus \".\" \u2014 its predicate already has the outcome (FD-V26)."),
+    reference: referenceSchema(true, id),
+    edgeReference: referenceSchema(false, id),
+    retryPolicy: {
+      description: "Exactly the scheduler's shape (FD-V30).",
+      type: "object",
+      required: [...RETRY_POLICY_KEYS],
+      properties: Object.fromEntries(RETRY_POLICY_KEYS.map((k) => [k, {
+        ...k === "maxRetries" ? { type: "integer", minimum: 0 } : { type: "number", minimum: 0 },
+        description: described(RETRY_DESCRIPTIONS, k, "a retryPolicy")
+      }])),
+      additionalProperties: false
+    },
+    transform: {
+      description: "Exactly { lang, expr }, both strings (FD-V37).",
+      type: "object",
+      required: [...TRANSFORM_KEYS],
+      properties: Object.fromEntries(TRANSFORM_KEYS.map((k) => [k, { type: "string", description: described(TRANSFORM_DESCRIPTIONS, k, "a transform") }])),
+      additionalProperties: false
+    },
+    when: {
+      description: "One of three shapes, told apart by its keys (FD-V42): a registered name, a declared comparison, or a flat group.",
+      oneOf: [ref("predicateName"), ref("comparison"), ref("group")]
+    },
+    predicateName: {
+      description: "A registered predicate, by name (FD-V4's lookup is validateDefinition's).",
+      type: "object",
+      required: [...PREDICATE_NAME_KEYS],
+      properties: Object.fromEntries(PREDICATE_NAME_KEYS.map((k) => [k, { type: "string", description: described(PREDICATE_DESCRIPTIONS, k, "a predicate name") }])),
+      additionalProperties: false
+    },
+    comparison: leafSchema(id),
+    group: {
+      description: "A FLAT group \u2014 `all` or `any`, never both, never nested, its members comparisons (FD-V45).",
+      oneOf: PREDICATE_GROUP_KEYS.map((k) => ({
+        type: "object",
+        required: [k],
+        properties: { [k]: { type: "array", minItems: 1, items: ref("comparison"), description: described(PREDICATE_DESCRIPTIONS, k, "a group") } },
+        additionalProperties: false
+      }))
+    },
+    subsetSchema: {
+      description: "A schema in the library's built-in subset (ADR 0053): a plain object using only these keywords \u2014 any other is refused, never ignored (Q278).",
+      type: "object",
+      properties: Object.fromEntries(SCHEMA_KEYWORDS.map((k) => [k, { ...subsetKeywordSchema(k), description: described(SUBSET_DESCRIPTIONS, k, "the schema subset") }])),
+      additionalProperties: false
+    }
+  };
+  return {
+    $schema: DRAFT_2020_12,
+    title: "FlowDefinition",
+    description: "The STATIC SHAPE of a fyflow-orchestration flow definition (spec/flow-definition.md). It carries every rule a node, an edge or a value decides by its own shape, and none that needs another node or a registry: whether a named node exists and what kind it is, reachability, cycles, regions and joins, where a `needs` reference points, and every registered name \u2014 node types, pools, groups, languages, predicates, gate types and their routes and settings. For all of those, and for the definition as a whole, the AUTHORITY is `validateDefinition(flow, registry)` \u2014 and `runtime.check(flow)` on a runtime. A document this schema refuses, validateDefinition refuses; one it accepts may still be refused there.",
+    type: "object",
+    required: [...DOC_KEYS_DECLARED],
+    properties: Object.fromEntries(DOC_KEYS_DECLARED.map((k) => {
+      const s = k === "flowId" || k === "entry" ? ref("id") : k === "version" ? { type: "integer", minimum: 1 } : k === "nodes" ? { type: "array", minItems: 1, items: ref("node") } : (() => {
+        throw new Error(`definitionSchema: the document declares the key "${k}" and no schema is written for it`);
+      })();
+      return [k, { ...s, description: described(DOC_DESCRIPTIONS, k, "the document") }];
+    })),
+    additionalProperties: false,
+    $defs: defs
+  };
+}
+var REGISTRY_DESCRIPTION = "The SHAPE of a fyflow-orchestration flow definition SPECIALISED TO ONE REGISTRY (spec/flow-definition.md section 1). Beyond the static shape it carries what the registry decides of a node by itself: a task's `type`, one of the registry's node types (FD-V32), and per type its `pool` (the type's own name or one of its named instances, FD-V38), its `settings` held to the type's worker settingsSchema (FD-V33) and, for a type that only transforms, a required `transform` (FD-V46); `workerGroups` from the registry's groups (FD-V31); `transform.lang` from its languages (FD-V35); a predicate NAME from its predicates (FD-V4); a gate's `type`, one of its gate types (FD-V39), and per type its `settings` held to the type's settingsSchema (FD-V40) and, for a STATIC gate type, each edge's `route` one of its routes (FD-V41). It does NOT cleanly carry, and leaves to the authority: FD-V33 over the EFFECTIVE settings \u2014 a node's settings merged over its type's defaults \u2014 so a settingsSchema's `required` is WEAKENED by the keys the defaults supply, and a default's own value and any top-level keyword but properties, required and additionalProperties are unchecked; a `minLength` above 1 inside an embedded registry schema, relaxed to half rounded up, because the registry's schema subset counts a string's UTF-16 units and JSON Schema its code points; a DERIVED gate type's routes, which its routesFor computes from each gate's settings; FD-V41's every route wired EXACTLY ONCE; a gate type's settingsProblem and a language's compile (FD-V36), which are code; a node type's worker inputSchema, which is RUNTIME input and is carried as an ANNOTATION only, at `$defs.inputSchema` in its type's branch; and every rule that needs another node \u2014 existence, kinds, reachability, cycles, regions, joins, where a `needs` reference points. For all of those, and for the definition as a whole, the AUTHORITY is `validateDefinition(flow, registry)` against THIS registry \u2014 and `runtime.check(flow)` on a runtime. A document this schema refuses, validateDefinition refuses against this registry; one it accepts may still be refused there.";
+function relaxed(schema) {
+  const walk = (s) => {
+    if (typeof s.minLength === "number" && s.minLength > 1) s.minLength = Math.ceil(s.minLength / 2);
+    if (isObject(s.properties)) {
+      for (const p of Object.values(s.properties)) if (isObject(p)) walk(p);
+    }
+    if (isObject(s.items)) walk(s.items);
+    return s;
+  };
+  return walk(structuredClone(schema));
+}
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+var quoted = (names) => [...names].map((n) => JSON.stringify(n)).join(", ");
+function nodeTypeBranch(name, t, workers, pools) {
+  const instances = [...pools].filter(([, p]) => p.type === name).map(([k]) => k);
+  const workerName = t.worker;
+  const worker = typeof workerName === "string" ? workers.get(workerName) : void 0;
+  const properties = {
+    pool: {
+      description: `A pool of "${name}": its own name (the default instance)${instances.length ? ` or a named instance of it \u2014 ${quoted(instances)}` : ""} (FD-V38).`,
+      enum: [name, ...instances]
+    }
+  };
+  const required = [];
+  const settingsSchema = worker?.settingsSchema;
+  if (settingsSchema !== void 0) {
+    const defaults = t.settings ?? {};
+    const left = (settingsSchema.required ?? []).filter((k) => !own(defaults, k));
+    const settings = {
+      description: `Settings held to worker "${String(workerName)}"'s settingsSchema, merged OVER the type's defaults` + (Object.keys(defaults).length ? ` (${quoted(Object.keys(defaults))} supplied by them)` : "") + " (FD-V33).",
+      type: "object"
+    };
+    if (isObject(settingsSchema.properties)) {
+      settings.properties = Object.fromEntries(Object.entries(settingsSchema.properties).map(([k, p]) => [k, relaxed(p)]));
+    }
+    if (settingsSchema.additionalProperties === false) settings.additionalProperties = false;
+    if (left.length) {
+      settings.required = left;
+      required.push("settings");
+    }
+    properties.settings = settings;
+  }
+  if (onlyTransforms(t)) required.push("transform");
+  const branch = {
+    description: onlyTransforms(t) ? `A task of the built-in type "${name}": it names no worker and runs only its own \`transform\`, which it must declare (FD-V46).` : `A task of node type "${name}", run by worker "${String(workerName)}".` + (worker?.inputSchema !== void 0 ? " What that worker receives as input is described at $defs.inputSchema here \u2014 an ANNOTATION: it is runtime input, and nothing in a definition is held to it." : ""),
+    properties
+  };
+  if (required.length) branch.required = required;
+  if (worker?.inputSchema !== void 0) branch.$defs = { inputSchema: structuredClone(worker.inputSchema) };
+  return branch;
+}
+function gateTypeBranch(name, t) {
+  const properties = {};
+  const branch = { description: "", properties };
+  if (t.settingsSchema !== void 0) {
+    properties.settings = relaxed(t.settingsSchema);
+    if (findings(t.settingsSchema, {}).length > 0) branch.required = ["settings"];
+  }
+  if (typeof t.routesFor !== "function") {
+    const set = routesOf(t, {});
+    if ("problem" in set) throw new Error(`definitionSchema: gate type "${name}" resolves no route set: ${set.problem}`);
+    properties.edges = {
+      items: {
+        properties: {
+          route: {
+            description: `One of "${name}"'s routes \u2014 ${quoted(set.routes)}; an edge with no \`route\` carries its default, "${set.defaultRoute}" (FD-V41).`,
+            enum: [...set.routes]
+          }
+        }
+      }
+    };
+    branch.description = `A gate of the STATIC gate type "${name}": routes ${quoted(set.routes)}, the default "${set.defaultRoute}". That each is wired exactly once is validateDefinition's (FD-V41).`;
+  } else {
+    branch.description = `A gate of the DERIVED gate type "${name}": its routes are computed from each gate's settings, so which \`route\` names exist is validateDefinition's (FD-V41).`;
+  }
+  return branch;
+}
+var branchOn = (key, name, then) => ({ if: { required: [key], properties: { [key]: { const: name } } }, then });
+function specialise(s, registry) {
+  const defs = s.$defs;
+  const nodeTypes = nodeTypesOf(registry.nodeTypes);
+  const workers = workersOf(registry.workers);
+  const pools = poolsOf(registry.pools);
+  const gateTypes = gateTypesOf(registry.gateTypes);
+  const groups = [...new Set(registry.groups ?? [])];
+  const predicates = [...new Set(registry.predicates)];
+  const languages = [...languagesOf(registry.languages).keys()];
+  const task = defs.taskNode;
+  task.properties.type = {
+    ...task.properties.type,
+    description: `The node type that runs this task: one of the registry's \u2014 ${quoted(nodeTypes.keys())} (FD-V32). What each type adds is its branch in this node's allOf.`,
+    enum: [...nodeTypes.keys()]
+  };
+  task.properties.workerGroups = {
+    ...task.properties.workerGroups,
+    description: `The resource groups the scheduler holds this task to: a non-empty list of distinct ids of the registry's groups \u2014 ${groups.length ? quoted(groups) : "it declares none"} (FD-V31).`,
+    items: { type: "string", enum: groups }
+  };
+  task.allOf = [...nodeTypes].map(([n, t]) => branchOn("type", n, nodeTypeBranch(n, t, workers, pools)));
+  const transform = defs.transform;
+  transform.properties.lang = {
+    ...transform.properties.lang,
+    description: `A language the registry declares \u2014 ${languages.length ? quoted(languages) : "it declares none"} (FD-V35). That it compiles \`expr\` is validateDefinition's (FD-V36).`,
+    enum: languages
+  };
+  const predicateName = defs.predicateName;
+  predicateName.properties.predicate = {
+    ...predicateName.properties.predicate,
+    description: `A predicate the registry declares \u2014 ${predicates.length ? quoted(predicates) : "it declares none"} (FD-V4).`,
+    enum: predicates
+  };
+  const gate = defs.gateNode;
+  gate.properties.type = {
+    ...gate.properties.type,
+    description: `The gate type that decides: one of ${quoted(gateTypes.keys())} \u2014 the built-ins and the registry's \`gateTypes\` (FD-V39). What each adds is its branch in this node's allOf.`,
+    enum: [...gateTypes.keys()]
+  };
+  gate.allOf = [...gateTypes].map(([g, t]) => branchOn("type", g, gateTypeBranch(g, t)));
+  s.description = REGISTRY_DESCRIPTION;
+}
 
 // src/definition/assist.ts
 var TYPES = ["object", "array", "string", "number", "integer", "boolean", "null"];
@@ -260,11 +789,11 @@ function object(s, indent) {
   const req = new Set(s.required ?? []);
   const named = [...props.map(([k]) => k)];
   const all = [...props, ...[...req].filter((k) => !named.includes(k)).map((k) => [k, {}])];
-  const body = all.map(([k, sub]) => `${indent}  ${lit(k)}${req.has(k) ? "" : "?"}: ${tsTypeOf(sub, `${indent}  `)};`).join("\n");
+  const body2 = all.map(([k, sub]) => `${indent}  ${lit(k)}${req.has(k) ? "" : "?"}: ${tsTypeOf(sub, `${indent}  `)};`).join("\n");
   const rest = closed ? "" : `
 ${indent}  [k: string]: unknown;`;
   return `{
-${body}${rest}
+${body2}${rest}
 ${indent}}`;
 }
 function signatureOf(name, worker) {
@@ -300,23 +829,28 @@ export {
   ConfigRefused,
   DECLARED_POOL_KEYS,
   DOCUMENT_KEYS,
+  DOC_KEYS_DECLARED,
   DerivationRefused,
   Driver,
   DuplicateTaskId,
   EDGE_KEYS_DECLARED,
+  EDGE_KEYS_REQUIRED,
   GATE_TYPE_KEYS,
   GateTypeRefused,
   GroupConfigRefused,
   GroupTypeMissing,
+  ID_RE_COPY as ID_RE,
   INSTANCE_KEYS,
   InvalidDefinition,
   InvalidRunId,
   InvalidTaskId,
   KEY_PATH_RE,
+  KINDS_COPY as KINDS,
   MESSAGE_OPTION_KEYS,
   MissingJoinPolicy,
   MultipleRuns,
   NODE_KEYS_DECLARED,
+  NODE_KEYS_REQUIRED,
   NODE_TYPE_DECLARATION_KEYS,
   NameCollision,
   NameMissing,
@@ -334,6 +868,7 @@ export {
   PREDICATE_ROOTS,
   PoolTypeMissing,
   RETRY_POLICY_KEYS,
+  ROUTABLE_STATES,
   RegistryError,
   ResumeRefused,
   RunControlRefused,
@@ -371,6 +906,7 @@ export {
   checkRegistry,
   checkWiring,
   compileProblem,
+  definitionSchema,
   derivePool,
   describeFindings,
   describePaths,

package/dist/browser/scheduler/index.js

@@ -26,7 +26,7 @@ import {
   retryPolicyProblem,
   validateDefinition,
   workersOf
-} from "../chunks/chunk-NA6QQAZ2.js";
+} from "../chunks/chunk-5CVSWDCB.js";
 
 // src/scheduler/bootstrap.ts
 import { WorkerManager } from "fyflow-scheduler";