@humwick/server 0.130.1 → 0.130.3

package/node_modules/@humwick/kernel/workflow-definition.ts

@@ -1,507 +0,0 @@
-import { z } from "zod";
-import { emptyBoundary, validateWorkflowSchema, validateWorkflowExpressions, workflowObject, workflowCondition } from "./workflow-values";
-
-// #3045 — the declarative workflow format (`.agent-relay/workflows/<name>.yaml`) and its routing.
-// Pure data: the src side reads the file at a landed commit; this module owns what it may say.
-
-/** Built-in terminal steps: `land` clears the input Task's review hold and waits for the land;
- *  `escalate` hands the run, with its whole history, back to the coordinator. */
-const WORKFLOW_TERMINALS = ["land", "close", "escalate"] as const;
-/** The optional built-in step after `land`: the repo's CI on the landed commit, read from the CI monitor (#3045 H5). */
-export const CI_MAIN_STEP = "ci-main";
-const BUILT_IN_STEPS = [...WORKFLOW_TERMINALS, CI_MAIN_STEP, "done", "fail", "wait", "next"] as const;
-const DISPOSITIONS = ["complete", "failed", "blocked", "needs-review"] as const;
-const GATE_VERDICTS = ["pass", "fail"] as const;
-/** #3166 — the outcome of a step whose agent exited without a delivery; unrouted, it escalates like any outcome. */
-export const WORKFLOW_EXITED_OUTCOME = "exited";
-const TOP_FIELDS = ["description", "steps", "routes", "land", CI_MAIN_STEP, "version", "inputs", "outputs", "return", "limits"] as const;
-/** #3121 — what a step's agent may be pinned to, in its YAML step and per run at relay_workflow_start / resume.
- *  #3091 `profile` replaces the base profile the step's role extends. */
-export const WORKFLOW_PIN_FIELDS = ["provider", "model", "effort", "orchestratorId", "profile"] as const;
-const STEP_FIELDS = ["role", "task", "gate", "reap", "timeout", "crossProvider", ...WORKFLOW_PIN_FIELDS, "script", "on", "verify", "workflow", "inputs", "output-schema", "taskId", "for-each", "parallel", "if", "decision"] as const;
-const LAND_FIELDS = ["timeout", "then"] as const;
-const CI_MAIN_FIELDS = ["workflow", "timeout"] as const;
-/** When the run shuts a step's agents down; `on-run-done` keeps the builder warm across fix rounds. */
-export const WORKFLOW_REAP_POLICIES = ["on-step-done", "on-run-done", "never"] as const;
-export type WorkflowReapPolicy = (typeof WORKFLOW_REAP_POLICIES)[number];
-const BOUND_FIELDS = ["to", "max", "else"] as const;
-const NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
-const DURATION = /^(\d+)\s*(s|m|h|d)$/;
-const DURATION_UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
-const MIN_TIMEOUT_MS = 60_000;
-const MAX_TIMEOUT_MS = 30 * 86_400_000;
-/** How long a wait may make no progress before the run escalates once and keeps waiting (#3045 H1). */
-export const WORKFLOW_DEFAULT_TIMEOUT_MS = { input: 4 * 3_600_000, new: 2 * 3_600_000, land: 2 * 3_600_000, ci: 3_600_000 } as const;
-
-const timeoutSchema = z.number().int().min(MIN_TIMEOUT_MS).max(MAX_TIMEOUT_MS);
-const pinValue = z.string().min(1).optional();
-export const workflowScriptSchema = z.object({
-  run: z.string().min(1).max(6000), host: z.string().min(1), everyMs: z.number().int().min(1000).optional(),
-  timeoutMs: z.number().int().min(1000).max(86_400_000), on: z.record(z.string(), z.string()),
-});
-export const workflowPinSchema = z.object({ provider: pinValue, model: pinValue, effort: pinValue, orchestratorId: pinValue, profile: pinValue });
-/** A pin the coordinator set for one step at the start call or a later resume. */
-export const workflowCallPinSchema = workflowPinSchema.extend({ by: z.enum(["start", "resume"]) });
-const pinSource = z.enum(["start", "resume", "team", "global", "workflow"]).optional();
-/** The pin a step's dispatch applies, and where each field came from (`workflow`: its YAML step). */
-export const workflowAppliedPinSchema = workflowPinSchema.extend({ from: z.object({ provider: pinSource, model: pinSource, effort: pinSource, orchestratorId: pinSource, profile: pinSource }) });
-export const workflowRoutingDefaultsSchema = z.object({
-  global: z.record(z.string(), workflowPinSchema).optional(),
-  team: z.record(z.string(), workflowPinSchema).optional(),
-  teamId: z.string().optional(),
-});
-export type WorkflowRoutingDefaults = z.output<typeof workflowRoutingDefaultsSchema>;
-export const workflowDecisionSchema = z.object({
-  title: z.string().min(1), context: z.string().optional(), options: z.unknown().optional(),
-  "multi-select": z.unknown().optional(), answeredBy: z.enum(["coordinator", "operator"]).optional(), deadlineMs: timeoutSchema.optional(),
-});
-const actionSchema = workflowPinSchema.extend({
-  role: z.string().min(1), task: z.enum(["input", "new"]), gate: z.string().min(1).optional(), reap: z.enum(WORKFLOW_REAP_POLICIES).optional(),
-  timeoutMs: timeoutSchema.optional(),
-  /** #3105 — the step's agent prefers a provider other than this named step's agent's; with none live and with quota it runs on the same one. */
-  crossProvider: z.string().min(1).optional(),
-  script: workflowScriptSchema.optional(), decision: workflowDecisionSchema.optional(),
-  verify: z.boolean().optional(),
-  condition: z.union([z.boolean(), z.string()]).optional(),
-  workflow: z.string().optional(), inputs: workflowObject.optional(), outputSchema: workflowObject.optional(), taskId: z.unknown().optional(),
-});
-export type WorkflowStep = z.output<typeof actionSchema> & { forEach?: { items: unknown; concurrency: number; onFailure: "fail-fast" | "continue" | "escalate"; action: WorkflowStep; key?: unknown; needs?: unknown; branches?: Record<string, WorkflowStep>; join?: "all" | "any" } };
-const stepSchema: z.ZodType<WorkflowStep> = actionSchema.extend({ forEach: z.lazy(() => z.object({ items: z.unknown(), concurrency: z.number().int().min(1).max(32), onFailure: z.enum(["fail-fast", "continue", "escalate"]), action: stepSchema, key: z.unknown().optional(), needs: z.unknown().optional(), branches: z.record(z.string(), stepSchema).optional(), join: z.enum(["all", "any"]).optional() })).optional() });
-const boundedSchema = z.object({ to: z.string().min(1), max: z.number().int().min(1), else: z.string().min(1) });
-
-const targetSchema = z.union([z.string().min(1), boundedSchema]);
-const guardedSchema = z.array(z.object({ condition: z.union([z.string(), z.boolean()]).optional(), target: targetSchema }));
-
-export const workflowDefinitionSchema = z.object({
-  version: z.literal(2).optional(),
-  inputs: workflowObject.optional(), outputs: workflowObject.optional(), returns: workflowObject.optional(),
-  limits: z.record(z.string(), z.number().int().positive()).optional(),
-  description: z.string().optional(),
-  /** The first declared step; it runs on the run's input Task. */
-  start: z.string().min(1),
-  steps: z.record(z.string(), stepSchema),
-  routes: z.record(z.string(), z.record(z.string(), z.union([z.string().min(1), boundedSchema, guardedSchema]))),
-  /** The built-in land step's wait. */
-  land: z.object({ timeoutMs: timeoutSchema.optional(), then: z.string().optional() }).optional(),
-  /** Wait for CI on the landed commit; `workflow` names one CI workflow, else every watched one counts.
-   *  `timeoutMs` bounds the wait: past it without a verdict the result says "no CI". */
-  ciMain: z.object({ workflow: z.string().min(1).optional(), timeoutMs: timeoutSchema.optional() }).optional(),
-});
-
-export type WorkflowDefinition = z.output<typeof workflowDefinitionSchema>;
-export type WorkflowPin = z.output<typeof workflowPinSchema>;
-export type WorkflowCallPin = z.output<typeof workflowCallPinSchema>;
-export type WorkflowAppliedPin = z.output<typeof workflowAppliedPinSchema>;
-
-export function workflowItemAction(loop: NonNullable<WorkflowStep["forEach"]>, slot: { key?: string; item?: unknown }): WorkflowStep {
-  return loop.branches ? loop.branches[String(slot.key ?? slot.item)]! : loop.action;
-}
-
-export function workflowActions(definition: Pick<WorkflowDefinition, "steps">): WorkflowStep[] {
-  return workflowActionEntries(definition).map(([, step]) => step);
-}
-
-export function workflowActionEntries(definition: Pick<WorkflowDefinition, "steps">): Array<[string, WorkflowStep]> {
-  return Object.entries(definition.steps).flatMap(([name, step]): Array<[string, WorkflowStep]> => [[name, step], ...(step.forEach ? workflowActionEntries({ steps: step.forEach.branches ? Object.fromEntries(Object.entries(step.forEach.branches).map(([key, action]) => [`${name}.${key}`, action])) : { [`${name}.item`]: step.forEach.action } }) : [])]);
-}
-
-export class WorkflowDefinitionError extends Error {}
-
-function fail(message: string): never {
-  throw new WorkflowDefinitionError(message);
-}
-
-function isMapping(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function onlyFields(value: Record<string, unknown>, allowed: readonly string[], where: string): void {
-  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
-  if (unknown.length) fail(`${where}: unknown field${unknown.length > 1 ? "s" : ""} ${unknown.map((key) => `"${key}"`).join(", ")}; allowed: ${allowed.join(", ")}`);
-}
-
-function text(value: unknown, where: string): string {
-  if (typeof value !== "string" || !value.trim()) fail(`${where} must be a non-empty string`);
-  return value.trim();
-}
-
-/** A YAML duration (`90s`, `30m`, `4h`, `2d`), between one minute and 30 days. */
-function duration(value: unknown, where: string, min = MIN_TIMEOUT_MS, max = MAX_TIMEOUT_MS): number {
-  const match = typeof value === "string" ? DURATION.exec(value.trim()) : null;
-  if (!match) fail(`${where} must be a duration like 30m, 4h or 2d`);
-  const ms = Number(match[1]) * DURATION_UNIT_MS[match[2] as keyof typeof DURATION_UNIT_MS];
-  if (ms < min || ms > max) fail(`${where} must be between ${formatWorkflowDuration(min)} and ${formatWorkflowDuration(max)}`);
-  return ms;
-}
-
-/** A duration in the file's own notation, in its largest whole unit. */
-export function formatWorkflowDuration(ms: number): string {
-  const unit = (["d", "h", "m"] as const).find((u) => ms % DURATION_UNIT_MS[u] === 0) ?? "s";
-  return `${Math.round(ms / DURATION_UNIT_MS[unit])}${unit}`;
-}
-
-function routeTargets(route: WorkflowDefinition["routes"][string][string]): string[] {
-  return Array.isArray(route) ? route.flatMap(branch => routeTargets(branch.target)) : typeof route === "string" ? [route] : [route.to, route.else];
-}
-
-/** The outcomes a step can route on: its delivery disposition, or for a gated step the gate's verdict, and its agent's exit. */
-function stepOutcomes(step: WorkflowStep): readonly string[] {
-  return [...(step.condition !== undefined ? ["skipped"] : []), ...(step.workflow ? ["cancelled"] : []), ...(step.gate ? [...GATE_VERDICTS, ...DISPOSITIONS.filter((d) => d !== "complete")] : DISPOSITIONS), WORKFLOW_EXITED_OUTCOME];
-}
-
-function parseStep(name: string, value: unknown, version?: number, depth = 0): WorkflowStep {
-  const where = `steps.${name}`;
-  if (!NAME.test(name)) fail(`${where}: step names are letters, digits, - and _ (starting with a letter)`);
-  if ((BUILT_IN_STEPS as readonly string[]).includes(name)) fail(`${where}: "${name}" is a built-in step and cannot be declared`);
-  if (!isMapping(value)) fail(`${where} must be a mapping with role and task`);
-  onlyFields(value, STEP_FIELDS, where);
-  if (depth > 8) fail(`${where}: container depth exceeds 8`);
-  const data: Pick<WorkflowStep, "inputs" | "outputSchema" | "condition"> = {};
-  if (value.if !== undefined) {
-    if (version !== 2 || typeof value.if !== "boolean" && !(typeof value.if === "string" && value.if.startsWith("${{"))) fail(`${where}.if requires v2 and a boolean or expression`);
-    data.condition = value.if as string | boolean;
-  }
-  if (["role", "script", "workflow", "for-each", "parallel", "decision"].filter(key => value[key] !== undefined).length !== 1) fail(`${where}: declare exactly one action`);
-  if (value.inputs !== undefined) {
-    if (version !== 2 || !isMapping(value.inputs)) fail(`${where}.inputs requires v2 and an object`);
-    data.inputs = value.inputs;
-  }
-  if (value["output-schema"] !== undefined) {
-    if (version !== 2 || !isMapping(value["output-schema"])) fail(`${where}.output-schema requires v2 and an object`);
-    validateWorkflowSchema(value["output-schema"]);
-    data.outputSchema = value["output-schema"];
-  }
-  if (value.decision !== undefined) {
-    if (version !== 2) fail(`${where}.decision requires version: 2`);
-    onlyFields(value, ["decision", "inputs", "output-schema", "if"], where);
-    if (!isMapping(value.decision)) fail(`${where}.decision must be a mapping`);
-    const decision = value.decision;
-    onlyFields(decision, ["title", "context", "options", "multi-select", "deadline", "answeredBy"], `${where}.decision`);
-    if ((decision.options !== undefined) === (decision["multi-select"] !== undefined)) fail(`${where}.decision: declare options or multi-select`);
-    if (decision.answeredBy !== undefined && decision.answeredBy !== "operator" && decision.answeredBy !== "coordinator") fail(`${where}.decision.answeredBy must be coordinator or operator`);
-    const items = decision.options ?? decision["multi-select"];
-    if (!Array.isArray(items) && !(typeof items === "string" && items.startsWith("${{"))) fail(`${where}.decision choices must be an array or whole expression`);
-    return { role: "decision", task: "new", ...data, decision: { title: text(decision.title, `${where}.decision.title`),
-      ...(decision.answeredBy !== undefined ? { answeredBy: decision.answeredBy as "coordinator" | "operator" } : {}),
-      ...(decision.context !== undefined ? { context: text(decision.context, `${where}.decision.context`) } : {}),
-      ...(decision.options !== undefined ? { options: decision.options } : { "multi-select": decision["multi-select"] }),
-      ...(decision.deadline !== undefined ? { deadlineMs: duration(decision.deadline, `${where}.decision.deadline`) } : {}),
-    } };
-  }
-  if (value.parallel !== undefined) {
-    if (version !== 2) fail(`${where}.parallel requires version: 2`);
-    onlyFields(value, ["parallel", "timeout", "output-schema", "if"], where);
-    const group = value.parallel;
-    if (!isMapping(group)) fail(`${where}.parallel must be a mapping`);
-    onlyFields(group, ["join", "concurrency", "on-failure", "branches"], `${where}.parallel`);
-    const join = group.join ?? "all";
-    if (join !== "all" && join !== "any") fail(`${where}.parallel.join must be all or any`);
-    if (join === "any" && group["on-failure"] !== undefined) fail(`${where}.parallel: any cannot declare on-failure`);
-    if (!isMapping(group.branches) || !Object.keys(group.branches).length) fail(`${where}.parallel.branches must be nonempty`);
-    const branches = Object.fromEntries(Object.entries(group.branches).map(([key, action]) => [key, parseStep(key, action, version, depth + 1)]));
-    const lowered = parseStep(name, { "for-each": { items: Object.keys(branches), concurrency: group.concurrency ?? 32, "on-failure": join === "any" ? "continue" : group["on-failure"], do: Object.values(group.branches)[0] }, ...(value.timeout ? { timeout: value.timeout } : {}) }, version, depth);
-    return { ...lowered, ...data, role: "parallel", forEach: { ...lowered.forEach!, branches, join } };
-  }
-  if (value["for-each"] !== undefined) {
-    if (version !== 2) fail(`${where}.for-each requires version: 2`);
-    onlyFields(value, ["for-each", "timeout", "output-schema", "if"], where);
-    const loop = value["for-each"];
-    if (!isMapping(loop)) fail(`${where}.for-each must be a mapping`);
-    onlyFields(loop, ["items", "concurrency", "on-failure", "do", "key", "needs"], `${where}.for-each`);
-    if (!Array.isArray(loop.items) && !(typeof loop.items === "string" && loop.items.startsWith("${{"))) fail(`${where}.for-each.items must be an array or whole expression`);
-    const concurrency = loop.concurrency ?? 1;
-    if (typeof concurrency !== "number" || !Number.isInteger(concurrency) || concurrency < 1 || concurrency > 32) fail(`${where}.for-each.concurrency must be 1..32`);
-    const onFailure = loop["on-failure"] ?? "fail-fast";
-    if (onFailure !== "fail-fast" && onFailure !== "continue" && onFailure !== "escalate") fail(`${where}.for-each.on-failure must be fail-fast, continue or escalate`);
-    return { role: "for-each", task: "new", ...data, forEach: { items: loop.items, concurrency, onFailure, action: parseStep("item", loop.do, version, depth + 1), ...(loop.key !== undefined ? { key: loop.key } : {}), ...(loop.needs !== undefined ? { needs: loop.needs } : {}) }, timeoutMs: value.timeout === undefined ? 86400000 : duration(value.timeout, `${where}.timeout`) };
-  }
-  if (value.workflow !== undefined) {
-    if (version !== 2) fail(`${where}.workflow requires version: 2`);
-    onlyFields(value, ["workflow", "taskId", "inputs", "output-schema", "timeout", "if"], where);
-    const workflow = text(value.workflow, `${where}.workflow`);
-    if (!NAME.test(workflow)) fail(`${where}.workflow must name a workflow`);
-    return { role: "workflow", task: "new", workflow, ...data, ...(value.taskId !== undefined ? { taskId: value.taskId } : {}), timeoutMs: value.timeout === undefined ? 86400000 : duration(value.timeout, `${where}.timeout`) };
-  }
-  if (value.script !== undefined) {
-    onlyFields(value, ["script", "on", ...(version === 2 ? ["inputs", "output-schema", "if"] : [])], where);
-    if (!isMapping(value.script)) fail(`${where}.script must be a mapping`);
-    onlyFields(value.script, ["run", "host", "every", "timeout"], `${where}.script`);
-    const script = value.script;
-    const everyMs = script.every === undefined ? undefined : duration(script.every, `${where}.script.every`, 1000, 86_400_000);
-    if (!isMapping(value.on)) fail(`${where}.on must map exit codes to transitions`);
-    const on: Record<string, string> = {};
-    for (const [code, transition] of Object.entries(value.on)) {
-      if (code !== "default" && (!/^\d+$/.test(code) || Number(code) > 255)) fail(`${where}.on.${code}: expected exit code 0..255 or default`);
-      const action = text(transition, `${where}.on.${code}`);
-      if (!["next", "wait", "fail", "escalate"].includes(action) && !/^goto [A-Za-z][A-Za-z0-9_-]*$/.test(action)) fail(`${where}.on.${code}: use next, wait, fail, escalate or goto <step>`);
-      if (action === "wait" && !everyMs) fail(`${where}.on.${code}: wait requires script.every`);
-      on[code] = action;
-    }
-    return { role: "script", task: "new", ...data, script: {
-      run: text(script.run, `${where}.script.run`), host: script.host === undefined ? "owner" : text(script.host, `${where}.script.host`),
-      timeoutMs: duration(script.timeout, `${where}.script.timeout`, 1000, 86_400_000), ...(everyMs ? { everyMs } : {}), on,
-    } };
-  }
-  if (value.taskId !== undefined) fail(`${where}.taskId is only supported on a child workflow step`);
-  if (value.on !== undefined) fail(`${where}.on is only supported on a script step`);
-  const task = value.task;
-  if (task !== "input" && task !== "new") fail(`${where}.task must be input (the run's Task) or new (a fresh Task per entry)`);
-  const gate = value.gate === undefined ? undefined : text(value.gate, `${where}.gate`);
-  if (value.verify !== undefined && typeof value.verify !== "boolean") fail(`${where}.verify must be a boolean`);
-  if (value.verify && (task !== "new" || !gate)) fail(`${where}.verify requires task: new and a gate`);
-  const reap = value.reap;
-  if (reap !== undefined && !(WORKFLOW_REAP_POLICIES as readonly unknown[]).includes(reap)) fail(`${where}.reap must be ${WORKFLOW_REAP_POLICIES.join(", ")} (default on-run-done)`);
-  const timeoutMs = value.timeout === undefined ? undefined : duration(value.timeout, `${where}.timeout`);
-  const crossProvider = value.crossProvider === undefined ? undefined : text(value.crossProvider, `${where}.crossProvider`);
-  const pin: WorkflowPin = {};
-  for (const field of WORKFLOW_PIN_FIELDS) if (value[field] !== undefined) pin[field] = text(value[field], `${where}.${field}`);
-  return {
-    role: text(value.role, `${where}.role`), task, ...data, ...(gate ? { gate } : {}), ...(reap ? { reap: reap as WorkflowReapPolicy } : {}), ...(timeoutMs ? { timeoutMs } : {}),
-    ...(crossProvider ? { crossProvider } : {}), ...(value.verify !== undefined ? { verify: value.verify as boolean } : {}), ...pin,
-  };
-}
-
-/** #3121 — a start or resume call's pins, stamped with who set them; a step the workflow does not declare is refused. */
-export function stampWorkflowPins(definition: WorkflowDefinition, pins: Record<string, WorkflowPin>, by: WorkflowCallPin["by"]): Record<string, WorkflowCallPin> {
-  const stamped: Record<string, WorkflowCallPin> = {};
-  for (const [step, pin] of Object.entries(pins)) {
-    if (!definition.steps[step]) fail(`pins.${step}: the workflow has no step "${step}"; pin one of ${Object.keys(definition.steps).join(", ")}`);
-    if (definition.steps[step]?.decision || definition.steps[step]?.script || definition.steps[step]?.workflow || definition.steps[step]?.forEach) fail(`pins.${step}: pin an agent step in the workflow`);
-    stamped[step] = { ...pin, by };
-  }
-  return stamped;
-}
-
-/** Fields merge in precedence order. Switching provider drops the lower layer's model and effort. */
-export function workflowStepPin(definition: WorkflowDefinition, pins: Record<string, WorkflowCallPin> | undefined, step: string, defaults?: WorkflowRoutingDefaults): WorkflowAppliedPin | undefined {
-  const call = pins?.[step];
-  const declared = definition.steps[step];
-  const pin: WorkflowAppliedPin = { from: {} };
-  const layers = [[declared, "workflow"], [defaults?.global?.[declared?.role ?? ""], "global"], [defaults?.team?.[declared?.role ?? ""], "team"], [call, call?.by]] as const;
-  for (const [layer, source] of layers) {
-    if (!layer || !source) continue;
-    if (layer.provider && pin.provider && layer.provider !== pin.provider) {
-      for (const field of ["model", "effort"] as const) { delete pin[field]; delete pin.from[field]; }
-    }
-    for (const field of WORKFLOW_PIN_FIELDS) {
-      if (layer[field] === undefined) continue;
-      pin[field] = layer[field];
-      pin.from[field] = source;
-    }
-  }
-  return Object.keys(pin.from).length ? pin : undefined;
-}
-
-/** How long the wait of `step` (a declared step or `land`) may go without its delivery or land. */
-export function waitTimeoutMs(definition: WorkflowDefinition, step: string): number {
-  if (step === "land") return definition.land?.timeoutMs ?? WORKFLOW_DEFAULT_TIMEOUT_MS.land;
-  if (step === CI_MAIN_STEP) return definition.ciMain?.timeoutMs ?? WORKFLOW_DEFAULT_TIMEOUT_MS.ci;
-  const declared = definition.steps[step];
-  if (declared?.script) return declared.script.timeoutMs;
-  return declared?.timeoutMs ?? WORKFLOW_DEFAULT_TIMEOUT_MS[declared?.task ?? "input"];
-}
-
-/** A step's reap policy; an absent `reap` keeps its agents until the run ends. */
-export function stepReap(step: WorkflowStep | undefined): WorkflowReapPolicy {
-  return step?.reap ?? "on-run-done";
-}
-
-/** Presentation follows the actual land continuation, including built-in stations. */
-export function workflowStations(definition: WorkflowDefinition): string[] {
-  const declared = Object.keys(definition.steps);
-  if (definition.version === 2) return declared;
-  const boundary = definition.land?.then ? declared.indexOf(definition.land.then) : declared.length;
-  const targets = Object.values(definition.routes).flatMap(routes => Object.values(routes).flatMap(route => routeTargets(route)));
-  targets.push(...Object.values(definition.steps).flatMap(step => Object.values(step.script?.on ?? {}).filter(action => action.startsWith("goto ")).map(action => action.slice(5))));
-  const closes = targets.includes("close");
-  if (!targets.includes("land")) return [...declared, ...(closes ? ["close"] : [])];
-  return [...declared.slice(0, boundary), "land", ...(definition.ciMain ? [CI_MAIN_STEP] : []), ...declared.slice(boundary), ...(closes ? ["close"] : [])];
-}
-
-/**
- * Validate a parsed YAML document. Every loop must be bounded: a route back to the same or an
- * earlier step must be `{ to, max, else }`, and `else` must leave the loop.
- */
-export function parseWorkflowDefinition(raw: unknown): WorkflowDefinition {
-  if (!isMapping(raw)) fail("the file must be a YAML mapping with steps and routes");
-  onlyFields(raw, TOP_FIELDS, "workflow");
-  if (raw.version !== undefined && raw.version !== 2) fail("version must be 2 or omitted");
-  const version = raw.version as 2 | undefined;
-  const top = raw;
-  if (!version && ["inputs", "outputs", "return", "limits"].some(field => top[field] !== undefined)) fail("typed boundaries require version: 2");
-  const boundary: Pick<WorkflowDefinition, "inputs" | "outputs" | "returns" | "limits"> = {};
-  if (version) {
-    for (const field of ["inputs", "outputs"] as const) {
-      const schema = raw[field] ?? emptyBoundary;
-      if (!isMapping(schema)) fail(`${field} must be a JSON Schema object`);
-      validateWorkflowSchema(schema, true);
-      boundary[field] = schema;
-    }
-    if (raw.return !== undefined && !isMapping(raw.return)) fail("return must be an object");
-    boundary.returns = raw.return as Record<string, unknown> | undefined ?? {};
-    if (raw.limits !== undefined) {
-      if (!isMapping(raw.limits)) fail("limits must be a mapping");
-      const defaults = { depth: 8, children: 256, treeChildren: 1024, activations: 4096, agents: 8, scripts: 8 };
-      boundary.limits = {};
-      for (const [key, value] of Object.entries(raw.limits)) {
-        if (!(key in defaults) || typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > defaults[key as keyof typeof defaults]) fail(`limits.${key} must lower a central default`);
-        boundary.limits[key] = value;
-      }
-    }
-  }
-  const description = raw.description === undefined ? undefined : text(raw.description, "description");
-  if (Array.isArray(raw.steps)) {
-    const entries = raw.steps.map((step: unknown) => {
-      if (!isMapping(step)) fail("steps must contain named step mappings");
-      const { name, ...fields } = step;
-      return [text(name, "steps.name"), fields] as const;
-    });
-    if (new Set(entries.map(([name]) => name)).size !== entries.length) fail("steps have duplicate names");
-    raw = { ...raw, steps: Object.fromEntries(entries) };
-  }
-  if (!isMapping(raw) || !isMapping(raw.steps) || !Object.keys(raw.steps).length) fail("steps must map at least one step name to { role, task } or { script, on }");
-  const steps: Record<string, WorkflowStep> = {};
-  for (const [name, value] of Object.entries(raw.steps)) steps[name] = parseStep(name, value, version);
-  const order = Object.keys(steps);
-  if (version) {
-    validateWorkflowExpressions(boundary.returns, order);
-    for (const step of workflowActions({ steps })) { validateWorkflowExpressions(step.decision, order); validateWorkflowExpressions(step.condition, order); validateWorkflowExpressions(step.forEach?.key, order); validateWorkflowExpressions(step.forEach?.needs, order); validateWorkflowExpressions(step.inputs, order); validateWorkflowExpressions(step.taskId, order); if (typeof step.forEach?.items === "string") validateWorkflowExpressions(step.forEach.items, order); }
-  }
-  for (const [path, action] of workflowActionEntries({ steps })) {
-    if (path.includes(".") && action.script && Object.values(action.script.on).some(transition => transition.startsWith("goto "))) fail(`steps.${path}: a container body cannot goto another step; use a child workflow`);
-  }
-  const inputs = order.filter((name) => steps[name]!.task === "input");
-  const agents = order.filter((name) => !steps[name]!.decision && !steps[name]!.script && !steps[name]!.workflow && !steps[name]!.forEach);
-  if (!version && agents.length && (inputs.length !== 1 || inputs[0] !== agents[0])) fail(`exactly one step runs on the input Task (task: input), and it must be the first step; found ${inputs.length ? inputs.join(", ") : "none"}`);
-  for (const [name, step] of Object.entries(steps)) {
-    if (step.script) for (const action of Object.values(step.script.on)) {
-      if (!action.startsWith("goto ")) continue;
-      const to = action.slice(5);
-      if (to !== "land" && (!steps[to] || order.indexOf(to) <= order.indexOf(name))) fail(`steps.${name}.on: goto must name a later declared step or land`);
-    }
-    if (step.crossProvider !== undefined && (step.crossProvider === name || !steps[step.crossProvider])) fail(`steps.${name}.crossProvider must name another declared step, whose agent's provider this step avoids when it can`);
-  }
-
-  if (raw.routes !== undefined && !isMapping(raw.routes)) fail("routes must map step names to { outcome: target }");
-  const routes: WorkflowDefinition["routes"] = {};
-  const target = (value: unknown, from: string, where: string): string => {
-    const to = text(value, where);
-    // #3660 — `done` ends a v1 run that lands nothing (a single-agent audit); `fail` stays v2.
-    if (!steps[to] && ![...WORKFLOW_TERMINALS, "done", ...(version ? ["fail"] : [])].includes(to)) fail(`${where}: unknown step "${to}"; use a declared step, land, done or escalate`);
-    if (steps[to] && order.indexOf(to) <= order.indexOf(from)) fail(`${where}: a loop back to ${to} must be bounded: { to: ${to}, max: N, else: escalate }`);
-    return to;
-  };
-  for (const [from, table] of Object.entries(raw.routes ?? {})) {
-    const step = steps[from];
-    if (!step) fail(`routes.${from}: no step named "${from}"`);
-    if (!isMapping(table)) fail(`routes.${from} must map outcomes to targets`);
-    const allowed = stepOutcomes(step);
-    routes[from] = {};
-    for (const [outcome, value] of Object.entries(table)) {
-      const where = `routes.${from}.${outcome}`;
-      if (!allowed.includes(outcome)) {
-        const gateNote = step.gate ? `step ${from} routes on its gate "${step.gate}"` : `step ${from} declares no gate`;
-        fail(`${where}: unknown outcome; ${gateNote}, so it routes on ${allowed.join(", ")}`);
-      }
-      const parseTarget = (value: unknown, where: string): z.output<typeof targetSchema> => {
-        if (!isMapping(value)) return target(value, from, where);
-        onlyFields(value, BOUND_FIELDS, where);
-        const to = text(value.to, `${where}.to`);
-        if (!steps[to]) fail(`${where}.to: unknown step "${to}"`);
-        if (typeof value.max !== "number" || !Number.isInteger(value.max) || value.max < 1) fail(`${where}.max must be a whole number of at least 1`);
-        return { to, max: value.max, else: target(value.else, from, `${where}.else`) };
-      };
-      if (Array.isArray(value)) {
-        if (!version || !value.length) fail(`${where}: guarded routes require v2 and a last else`);
-        routes[from][outcome] = value.map((entry, index) => {
-          if (!isMapping(entry)) fail(`${where}: expected guarded route`);
-          const last = index === value.length - 1;
-          onlyFields(entry, last ? ["else"] : ["if", "to"], where);
-          if (last) return { target: parseTarget(entry.else, where) };
-          if (typeof entry.if !== "boolean" && !(typeof entry.if === "string" && entry.if.startsWith("${{"))) fail(`${where}: if must be a boolean or expression`);
-          validateWorkflowExpressions(entry.if, order);
-          return { condition: entry.if as string | boolean, target: parseTarget(entry.to, where) };
-        });
-      } else routes[from][outcome] = parseTarget(value, where);
-    }
-  }
-  const land = raw.land ?? {};
-  if (!isMapping(land)) fail("land must be a mapping: { timeout: 2h }");
-  onlyFields(land, LAND_FIELDS, "land");
-  const landTimeoutMs = land.timeout === undefined ? undefined : duration(land.timeout, "land.timeout");
-  const then = land.then === undefined ? undefined : text(land.then, "land.then");
-  if (then && (!steps[then] || then === order[0] || steps[then]!.task === "input")) fail("land.then must name a later declared step");
-  if (then) {
-    const seen = new Set<string>();
-    const pending = [then];
-    while (pending.length) {
-      const name = pending.pop()!;
-      if (seen.has(name)) continue;
-      seen.add(name);
-      if (name === "land" || (steps[name] && order.indexOf(name) < order.indexOf(then))) fail("land.then routes must stay after the land continuation");
-      const script = steps[name]?.script;
-      if (script) for (const action of Object.values(script.on)) {
-        if (action === "next") pending.push(order[order.indexOf(name) + 1] ?? "done");
-        if (action.startsWith("goto ")) pending.push(action.slice(5));
-      }
-      for (const route of Object.values(routes[name] ?? {})) pending.push(...(routeTargets(route)));
-    }
-  }
-  return {
-    ...(version ? { version, ...boundary } : {}), ...(description ? { description } : {}), start: order[0]!, steps, routes, ...(landTimeoutMs || then ? { land: { ...(landTimeoutMs ? { timeoutMs: landTimeoutMs } : {}), ...(then ? { then } : {}) } } : {}),
-    ...(raw[CI_MAIN_STEP] !== undefined ? { ciMain: parseCiMain(raw[CI_MAIN_STEP]) } : {}),
-  };
-}
-
-/** `ci-main: {}` (or `ci-main: { workflow: CI, timeout: 1h }`) adds the CI check after the land. */
-function parseCiMain(value: unknown): NonNullable<WorkflowDefinition["ciMain"]> {
-  const ciMain = value ?? {};
-  if (!isMapping(ciMain)) fail(`${CI_MAIN_STEP} must be a mapping: { workflow: CI, timeout: 1h } (both optional)`);
-  onlyFields(ciMain, CI_MAIN_FIELDS, CI_MAIN_STEP);
-  const workflow = ciMain.workflow === undefined ? undefined : text(ciMain.workflow, `${CI_MAIN_STEP}.workflow`);
-  const timeoutMs = ciMain.timeout === undefined ? undefined : duration(ciMain.timeout, `${CI_MAIN_STEP}.timeout`);
-  return { ...(workflow ? { workflow } : {}), ...(timeoutMs ? { timeoutMs } : {}) };
-}
-
-/** What a delivery means for a step: a gated step's `complete` is its gate verdict. */
-export function stepOutcome(step: WorkflowStep, delivery: { disposition: string; gateStatus?: string }): string {
-  if (step.gate && delivery.disposition === "complete" && (delivery.gateStatus === "pass" || delivery.gateStatus === "fail")) return delivery.gateStatus;
-  return delivery.disposition;
-}
-
-export interface RouteDecision {
-  target: string;
-  /** Times each bounded route was taken, keyed `<step>.<outcome>`. */
-  counters: Record<string, number>;
-  reason?: string;
-  outcome?: string;
-}
-
-/** Route one outcome. A bounded route's `max`-th use goes to `else`; an unrouted outcome escalates. */
-export function routeOutcome(definition: WorkflowDefinition, from: string, outcome: string, counters: Record<string, number>, context: Record<string, unknown> = {}): RouteDecision {
-  const script = outcome === "skipped" ? undefined : definition.steps[from]?.script;
-  if (script) {
-    const action = outcome === "timeout" ? "escalate" : script.on[outcome] ?? script.on.default ?? "escalate";
-    const target = action === "next" ? Object.keys(definition.steps)[Object.keys(definition.steps).indexOf(from) + 1] ?? "done"
-      : action.startsWith("goto ") ? action.slice(5) : action;
-    if (definition.version !== 2 || action.startsWith("goto ") || action === "wait" || action === "escalate") return { target, counters, outcome: action === "fail" ? "failed" : "complete", reason: `script step ${from} returned ${outcome}` };
-    const normalized = action === "next" ? "complete" : "failed";
-    return { ...routeOutcome({ ...definition, steps: { ...definition.steps, [from]: { ...definition.steps[from]!, script: undefined } } }, from, normalized, counters, context), outcome: normalized };
-  }
-  const declared = definition.routes[from]?.[outcome];
-  const route = Array.isArray(declared) ? declared.find(branch => branch.condition === undefined || workflowCondition(branch.condition, context))?.target : declared;
-  if (route === undefined && definition.version === 2) return { target: outcome === "complete" || outcome === "pass" || outcome === "skipped" ? Object.keys(definition.steps)[Object.keys(definition.steps).indexOf(from) + 1] ?? "done" : outcome === "failed" || outcome === "cancelled" || outcome === "fail" ? "fail" : "escalate", counters };
-  if (route === undefined) return { target: "escalate", counters, reason: `step ${from} returned ${outcome}, which has no route` };
-  if (typeof route === "string") return { target: route, counters };
-  const key = `${from}.${outcome}`;
-  const taken = (counters[key] ?? 0) + 1;
-  const next = { ...counters, [key]: taken };
-  if (taken < route.max) return { target: route.to, counters: next };
-  return { target: route.else, counters: next, reason: `step ${from} returned ${outcome} ${taken} time(s); the bound is ${route.max}` };
-}
-
-/** A route to the same or an earlier step starts a new round. */
-export function isLoopBack(definition: WorkflowDefinition, from: string, to: string): boolean {
-  const order = Object.keys(definition.steps);
-  return order.includes(to) && order.indexOf(to) <= order.indexOf(from);
-}

package/node_modules/@humwick/kernel/workflow-dispatch.ts

@@ -1,60 +0,0 @@
-import { z } from "zod";
-import { OpError, type ModuleCtx } from "./contract";
-import { stepReap, workflowAppliedPinSchema } from "./workflow-definition";
-import { ADMIN_GRANT, agentSchema, crossProviderSchema, stores, requireRun, type WorkflowEffect } from "./workflow-state";
-import { releaseReservation } from "./workflow-composition";
-
-export async function recordDispatchAgent(ctx: ModuleCtx, effect: WorkflowEffect, result: Record<string, unknown>): Promise<void> {
-  if (effect.kind !== "dispatch" || typeof result.taskId !== "number" || typeof result.spawnRequestId !== "string") return;
-  const run = await requireRun(ctx, effect.runId);
-  const step = String(effect.payload.step);
-  const pin = workflowAppliedPinSchema.safeParse(effect.payload.pin);
-  const crossProvider = crossProviderSchema.safeParse(result.crossProvider);
-  const routingSources = agentSchema.shape.routingSources.safeParse(result.routingSources);
-  const warnings = agentSchema.shape.warnings.safeParse(result.warnings);
-  const agent = await stores(ctx).agent.get(result.spawnRequestId);
-  const facts = {
-    ...(typeof result.agentId === "string" && !agent?.agentId ? { agentId: result.agentId } : {}),
-    ...(typeof result.provider === "string" ? { provider: result.provider } : {}),
-    ...(routingSources.success && routingSources.data ? { routingSources: routingSources.data } : {}),
-    ...(warnings.success && warnings.data ? { warnings: warnings.data } : {}),
-    ...(crossProvider.success ? { crossProvider: crossProvider.data } : {}), ...(pin.success ? { pin: pin.data } : {}),
-  };
-  if (agent) await stores(ctx).agent.update(agent.id, facts);
-  else await stores(ctx).agent.create({ id: result.spawnRequestId, spawnRequestId: result.spawnRequestId, reservationId: effect.id,
-    runId: run.id, step, round: typeof effect.payload.round === "number" ? effect.payload.round : run.round, taskId: result.taskId,
-    reap: stepReap(run.definition.steps[step]), ...facts, createdAt: ctx.clock.now() });
-}
-
-export const workflowDispatchOps = {
-  refuseDispatch: {
-    kind: "mutation", idempotent: true, grant: ADMIN_GRANT, summary: "Discard a provisional invocation proven never admitted by the effect driver.", expose: { http: false, mcp: false, cli: false },
-    input: z.object({ id: z.string() }), output: z.object({ refused: z.boolean() }),
-    handler: async (ctx: ModuleCtx, input: { id: string }) => {
-      const effect = await stores(ctx).effect.get(input.id);
-      if (!effect || effect.kind !== "dispatch" || typeof effect.payload.spawnRequestId !== "string") return { refused: false };
-      const run = await requireRun(ctx, effect.runId);
-      if (effect.status !== "failed" && !run.cancel) throw new OpError("conflict", 409, "dispatch can still be admitted");
-      const agent = await stores(ctx).agent.get(effect.payload.spawnRequestId);
-      if (agent?.agentId || agent?.readyAt) throw new OpError("conflict", 409, "invocation already registered");
-      if (agent) await stores(ctx).agent.delete(agent.id);
-      await releaseReservation(ctx, effect.id);
-      await stores(ctx).effect.update(effect.id, { payload: { ...effect.payload, refused: true } });
-      return { refused: true };
-    },
-  },
-  prepareDispatch: {
-    kind: "mutation", idempotent: true, grant: ADMIN_GRANT, summary: "Own a stable invocation before its external spawn is admitted.", expose: { http: false, mcp: false, cli: false },
-    input: z.object({ id: z.string(), taskId: z.number().int(), spawnRequestId: z.string() }), output: agentSchema,
-    handler: async (ctx: ModuleCtx, input: { id: string; taskId: number; spawnRequestId: string }) => {
-      const effect = await stores(ctx).effect.get(input.id);
-      if (!effect || effect.kind !== "dispatch") throw new OpError("not_found", 404, "dispatch intent not found");
-      const run = await requireRun(ctx, effect.runId);
-      if (run.cancel || run.status !== "running") throw new OpError("conflict", 409, "ROOT_STOPPED: dispatch is stale");
-      if (effect.payload.spawnRequestId && effect.payload.spawnRequestId !== input.spawnRequestId) throw new OpError("conflict", 409, "dispatch identity changed");
-      await recordDispatchAgent(ctx, effect, input);
-      await stores(ctx).effect.update(effect.id, { payload: { ...effect.payload, spawnTaskId: input.taskId, spawnRequestId: input.spawnRequestId } });
-      return (await stores(ctx).agent.get(input.spawnRequestId))!;
-    },
-  },
-} as const;