@toist/spec 0.2.0

package/src/kinds.ts

@@ -0,0 +1,166 @@
+// 2121
+// Kind contract — the runtime interface every NodeKind sees.
+//
+// Used by the runner (which executes kinds), domain projects (which declare
+// custom kinds via source-mod or workspace packages), and authoring tools
+// (which read manifest entries). Holds no implementation: only types.
+//
+// Domain authors importing only `NodeKind` pay nothing for the rest of
+// platform-spec at runtime — TypeScript erases types and Bun tree-shakes
+// the dependency graph. The split between this file and `validate.ts` is
+// for human clarity, not for bundle isolation.
+
+import type { Database } from "bun:sqlite"
+
+export interface ParamDef {
+  type: "string" | "number" | "boolean" | "expression" | "json" | "select"
+  label?: string
+  description?: string
+  default?: unknown
+  required?: boolean
+  options?: { value: string; label?: string }[]   // for type: "select"
+  placeholder?: string
+}
+
+export interface PortDef {
+  type: "any" | "object" | "array" | "string" | "number" | "boolean"
+  label?: string
+  description?: string
+  required?: boolean
+}
+
+/** Sqlite-backed cache exposed to kinds via ctx.cache. The runner provides
+ *  the implementation; this is the contract kinds code against. */
+export interface Cache {
+  key(...parts: unknown[]): string
+  get<T = unknown>(key: string): T | undefined
+  set(key: string, value: unknown, opts?: { ttl?: string | number }): void
+  delete(key: string): void
+  prune(): number
+}
+
+/** HITL suspension spec. The runner persists this on first ctx.suspend(spec)
+ *  call and replays the response on resume. v1: schema is descriptive, not
+ *  validated; timeout is stored, not enforced. */
+export interface HitlSpec {
+  prompt: string
+  assignee?: string
+  schema?: unknown
+  timeout?: string
+}
+
+/** Per-node failure handling policy per pipeline-spec.md §11 / §16.1 and
+ *  decision_pipeline_recovery_model_v1. Default `"abort"`.
+ *
+ *  - `"abort"`        — strict abort, run marked failed (v1 default)
+ *  - `"suspend"`      — create an `error_review` task; sibling branches
+ *                        continue if independent. Resume picks retry/skip/abort.
+ *  - `{ "skip-with": <value> }` — substitute the failed node's output with
+ *                        the value (itself a discriminator: bare | { value } | { expr }).
+ *                        Run continues.
+ *  - `{ retry: { times, backoff? } }` — retry up to N times with the chosen
+ *                        backoff before applying the next-tier policy (default abort).
+ */
+export type OnErrorPolicy =
+  | "abort"
+  | "suspend"
+  | { "skip-with": unknown }
+  | { retry: { times: number; backoff?: "linear" | "exponential" } }
+
+/** Spec for an error_review task — created when a node with onError:"suspend"
+ *  throws. Mirrors HitlSpec's role: persisted at suspend, surfaced to the UI,
+ *  cleared at resume. The resume payload is `{ action: "retry" | "skip" |
+ *  "abort", value? }` (vs HITL's free-form user input). */
+export interface ErrorReviewSpec {
+  prompt: string
+  assignee?: string
+  /** The original error message that triggered the suspend. */
+  error: string
+  /** Optional structured details — stack trace, kind id, etc. */
+  details?: Record<string, unknown>
+}
+
+/** Resource Type declaration — JSON Schema 2020-12 describing a typed
+ *  external-system handle. Types are registered in the runner's resource
+ *  type registry (parallel to the kind registry). */
+export interface ResourceTypeDef {
+  name: string
+  description?: string
+  schema: Record<string, unknown>  // JSON Schema 2020-12; use x-sensitive:true on secret fields
+}
+
+/** Read-only capability over the runtime ledger (runs + node_outputs).
+ *  Exposed to kinds via ctx.runs so cross-pipeline reads (M3/M4 in
+ *  pipeline-spec.md §12) don't need a raw runtime-db handle. */
+export interface RunStore {
+  /** Final output of the most recent run of `pipeline` matching `status`
+   *  (default `"done"`). Returns null when no matching run exists. */
+  lastOutput(pipeline: string, opts?: { status?: string }): unknown | null
+  /** Output of `node` from the most recent run of `pipeline` matching
+   *  `status` (default `"done"`). Returns null when no matching run/node
+   *  pair exists. Backed by the same node_outputs table that powers HITL
+   *  resume per decision_hitl_checkpoint_durability. */
+  nodeOutput(pipeline: string, node: string, opts?: { status?: string }): unknown | null
+}
+
+/** Outcome of a sub-pipeline invocation. Mirrors the runner's RunOutcome
+ *  but trimmed to what the pipeline.run kind exposes to its caller. */
+export type SubRunOutcome =
+  | { status: "done"; runId: number; output: unknown }
+  | { status: "failed"; runId: number; error: string }
+  | { status: "suspended"; runId: number; suspendedAt: string }
+
+/** Sub-run invocation capability. Pipeline.run uses this; nothing else
+ *  should. Per pipeline-spec.md §12 / decision_pipeline_recovery_model_v1
+ *  sub-runs are the natural unit for recovery — each gets its own run-id,
+ *  own node_outputs, own life-cycle. */
+export type SubRun = (pipelineId: string, payload: Record<string, unknown>) => Promise<SubRunOutcome>
+
+/** What the runner passes into runPipeline. The full per-step ExecContext
+ *  exposed to kinds is built from this by adding `step` and `suspend`. */
+export interface PlatformCtx {
+  runId: number
+  log: (level: "info" | "warn" | "error", msg: string) => void
+  db: Database
+  cache: Cache
+  /** Resolved resource instances. ctx.resource.<name>.<field> in { expr } nodes. */
+  resource: Record<string, Record<string, unknown>>
+  /** Read-only ledger capability — used by runs.lastOutput and runs.nodeOutput. */
+  runs: RunStore
+  /** Sub-pipeline invocation — used by the pipeline.run kind. Pass-through to
+   *  the runner's dispatcher; each sub-run gets its own run-id and lifecycle. */
+  subRun: SubRun
+}
+
+export interface ExecContext extends PlatformCtx {
+  /** Identifier of the node currently executing. ctx.suspend uses this to
+   *  address its own task; other kinds may also use it for logging context. */
+  step: { nodeId: string }
+  /** Pause the run until a human (or agent) responds with input matching the
+   *  given spec. On the first call, throws (caught by the executor). On
+   *  resume, returns the recorded response. */
+  suspend: (spec: HitlSpec) => Promise<unknown>
+}
+
+export interface NodeKind<
+  P extends Record<string, unknown> = Record<string, unknown>,
+  I extends Record<string, unknown> = Record<string, unknown>,
+> {
+  id: string                              // "transform.filter"
+  category: string                        // "data" | "transform" | "db" | "io" | "control"
+  label: string
+  description?: string
+  icon?: string                           // lucide icon name, optional
+  /** Mutates external state (DB writes, network writes, ...). Ad-hoc invokes
+   *  via /kinds/:id/invoke or kinds.invoke MCP tool require `confirm: true`
+   *  for side-effecting kinds. Pipeline runs are always allowed. */
+  sideEffect?: boolean
+  params:  Record<string, ParamDef>
+  inputs:  Record<string, PortDef>        // named, like Windmill OpenFlow modules
+  outputs: Record<string, PortDef>
+  run: (ctx: ExecContext, params: P, input: I) => Promise<unknown> | unknown
+}
+
+/** Manifest entry returned by GET /manifest — same as NodeKind but without
+ *  `run` (functions aren't serialisable). */
+export type NodeKindManifest = Omit<NodeKind, "run">

package/src/validate.ts

@@ -0,0 +1,522 @@
+// 2121
+// Pipeline-spec v1 validator. Implements pipeline-spec.md §13.
+//
+// Pure spec validation with no runtime dependencies. Kind-existence checks
+// are delegated to a caller-supplied resolver — the runner injects its
+// in-memory registry, while the CLI gen scripts and offline tooling can
+// pass an accept-all stub or hit /manifest themselves.
+
+import Ajv2020, { type ValidateFunction } from "ajv/dist/2020.js"
+import { parseDiscContainer, parseDisc, type DiscNode } from "./discriminator.ts"
+import type { NodeKindManifest, OnErrorPolicy } from "./kinds.ts"
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface PipelineNode {
+  id: string
+  kind: string
+  label?: string
+  params?: Record<string, unknown>
+  input?: Record<string, unknown>
+  dependsOn?: string[]
+  /** §11 / §16.1 failure-handling policy. Defaults to "abort". */
+  onError?: OnErrorPolicy
+}
+
+/** Discriminator-parsed form of a node, attached after validation. */
+export interface ParsedNode {
+  id: string
+  kind: string
+  label?: string
+  paramsTree: DiscNode
+  inputTree: DiscNode
+  dependsOn: string[]
+  /** Union of ctx.results.<id> ids referenced anywhere in params/input. */
+  refs: Set<string>
+  /** Resolved failure-handling policy. Always present after validation
+   *  (defaults to "abort" when the node omits onError). For skip-with, the
+   *  value is a parsed DiscNode so the dispatcher can resolve it against
+   *  the live ctx at substitution time — mirroring how params/input leaves work. */
+  onError: ResolvedOnError
+}
+
+export type ResolvedOnError =
+  | { kind: "abort" }
+  | { kind: "suspend" }
+  | { kind: "skip-with"; valueTree: DiscNode }
+  | { kind: "retry"; times: number; backoff: "linear" | "exponential" }
+
+export interface PipelineSpec {
+  apiVersion: string
+  id: string
+  label?: string
+  description?: string
+  schedule?: string
+  payloadSchema?: object
+  /** Compiled payload validator (ajv). Run-time validation per pipeline-spec §10. */
+  payloadValidator?: ValidateFunction
+  /** Raw nodes as authored in YAML. Preserved for serialization round-trip. */
+  nodes: PipelineNode[]
+  /** Parsed nodes ready for execution. Populated post-validation. */
+  parsedNodes: ParsedNode[]
+  /** Derived execution graph. `source` distinguishes expr-derived vs explicit dependsOn. */
+  edges: { from: string; to: string; source: "expr" | "dependsOn" }[]
+  /** Validation warnings (non-blocking, e.g. apiVersion absent). */
+  warnings: string[]
+  /** Optional caller-supplied source path; preserved across loads for diagnostics. */
+  _source?: string
+}
+
+export interface ValidateOptions {
+  /** Lookup whether a kind id resolves in the runner's registry. If absent,
+   *  kind references are accepted (useful for offline validation, schema
+   *  generation, or tools that have not loaded a runner). */
+  hasKind?: (id: string) => boolean
+  /** Per-kind manifest for shape enforcement (§13 item 9). When supplied,
+   *  validateSpec checks that every node's params/input keys match the
+   *  kind's declared ParamDef/PortDef contract: required keys are present,
+   *  no unknown keys, no use of params on a kind with no params declared.
+   *  Type-of-value checks on literals are deferred to v1.1. */
+  getKindManifest?: (id: string) => NodeKindManifest | undefined
+}
+
+export interface ValidateResult {
+  ok: boolean
+  errors: string[]
+  warnings?: string[]
+  parsed?: PipelineSpec
+  /** Backwards-compat: edge list when ok=true. */
+  edges?: { from: string; to: string }[]
+}
+
+// ─── Closed sets and constants ───────────────────────────────────────────────
+
+const SLUG_RE = /^[A-Za-z][\w-]*$/
+const API_VERSION = "2121.fi/v1"
+
+const ALLOWED_PIPELINE_KEYS = new Set([
+  "apiVersion", "id", "label", "description", "schedule", "payloadSchema", "nodes",
+])
+
+const ALLOWED_NODE_KEYS = new Set([
+  "id", "kind", "label", "params", "input", "dependsOn", "onError",
+])
+
+// Per pipeline-spec.md §16.4. Listed explicitly so users get a precise
+// "reserved for future use" error rather than a generic unknown-key one.
+//
+// Note: pipeline-level `onError` stays reserved in v1 — the task body of
+// open_task_pipeline_v1_recovery_model and decision_pipeline_recovery_model_v1
+// fix the pipeline default at "abort" with no override; only per-node
+// onError is functional. Forward-compat: lift this from RESERVED to ALLOWED
+// when v1.1 enables pipeline-level overrides.
+const RESERVED_PIPELINE_KEYS = new Set([
+  "version", "kind", "tags", "forEach", "loop", "retry", "timeout", "concurrency",
+  "notifications", "secrets", "imports", "inputs", "outputs", "outputSchema",
+  "dependsOnPipelines", "produces", "consumes", "onError",
+])
+
+const RESERVED_NODE_KEYS = new Set([
+  "if", "when", "forEach", "retry", "timeout", "cache",
+  "onSuccess", "outputs", "meta",
+])
+
+const ajv = new Ajv2020({ allErrors: true, strict: false })
+
+// ─── Validator ───────────────────────────────────────────────────────────────
+
+export function validateSpec(input: unknown, options: ValidateOptions = {}): ValidateResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+  const hasKind = options.hasKind ?? (() => true)
+  const getKindManifest = options.getKindManifest
+
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, errors: ["spec must be a JSON object"] }
+  }
+
+  const spec = input as Record<string, unknown>
+
+  // §13.2 — top-level closed set + reserved-key check.
+  for (const key of Object.keys(spec)) {
+    if (ALLOWED_PIPELINE_KEYS.has(key)) continue
+    if (RESERVED_PIPELINE_KEYS.has(key)) {
+      errors.push(`pipeline-level key "${key}" is reserved for future use; remove it`)
+    } else {
+      errors.push(`unknown pipeline-level key "${key}" (allowed: ${[...ALLOWED_PIPELINE_KEYS].join(", ")})`)
+    }
+  }
+
+  // §13.4 — apiVersion. Implicit-v1 with warning per §7.
+  let apiVersion: string
+  if (spec.apiVersion === undefined) {
+    warnings.push(`apiVersion absent; treating as "${API_VERSION}". Add apiVersion: "${API_VERSION}" explicitly.`)
+    apiVersion = API_VERSION
+  } else if (spec.apiVersion === API_VERSION) {
+    apiVersion = API_VERSION
+  } else {
+    errors.push(`unsupported apiVersion: ${JSON.stringify(spec.apiVersion)} (this runner accepts "${API_VERSION}")`)
+    apiVersion = API_VERSION
+  }
+
+  // §13.3 — id (slug). Optional in spec input (default applied at file load); required for storage.
+  if (spec.id !== undefined) {
+    if (typeof spec.id !== "string" || !SLUG_RE.test(spec.id)) {
+      errors.push(`id must match ${SLUG_RE} (got ${JSON.stringify(spec.id)})`)
+    }
+    if (typeof spec.id === "string" && spec.id.includes(".")) {
+      errors.push(`id must not contain dots (dots are reserved for kind ids like transform.map)`)
+    }
+  }
+
+  // Optional scalar fields.
+  if (spec.label !== undefined && typeof spec.label !== "string") {
+    errors.push(`label must be a string`)
+  }
+  if (spec.description !== undefined && typeof spec.description !== "string") {
+    errors.push(`description must be a string`)
+  }
+
+  // §13.14 — schedule (cron syntax check).
+  if (spec.schedule !== undefined) {
+    if (typeof spec.schedule !== "string") {
+      errors.push(`schedule must be a 5-field cron string (structured form is reserved, see §9)`)
+    } else if (!isValidCron(spec.schedule)) {
+      errors.push(`schedule "${spec.schedule}" is not a valid 5-field cron expression`)
+    } else {
+      warnings.push(`schedule is parsed but the scheduler is not yet active (pipeline-spec.md §16.1)`)
+    }
+  }
+
+  // §13.13 — payloadSchema, ajv-compiled at validation time.
+  let payloadValidator: ValidateFunction | undefined
+  if (spec.payloadSchema !== undefined) {
+    if (!spec.payloadSchema || typeof spec.payloadSchema !== "object" || Array.isArray(spec.payloadSchema)) {
+      errors.push(`payloadSchema must be a JSON Schema object`)
+    } else {
+      try {
+        payloadValidator = ajv.compile(spec.payloadSchema)
+      } catch (err) {
+        errors.push(`payloadSchema is not a valid JSON Schema 2020-12 document: ${(err as Error).message}`)
+      }
+    }
+  }
+
+  // §13.5 — nodes is a non-empty array.
+  if (!Array.isArray(spec.nodes)) {
+    return { ok: false, errors: [...errors, "nodes must be an array"], warnings }
+  }
+  if (spec.nodes.length === 0) {
+    errors.push("nodes must be a non-empty array")
+  }
+
+  const rawNodes: PipelineNode[] = []
+  const parsedNodes: ParsedNode[] = []
+  const seenIds = new Set<string>()
+
+  for (let i = 0; i < spec.nodes.length; i++) {
+    const n = spec.nodes[i]
+    const ctx = `nodes[${i}]`
+    if (!n || typeof n !== "object" || Array.isArray(n)) {
+      errors.push(`${ctx}: must be a JSON object`)
+      continue
+    }
+    const node = n as Record<string, unknown>
+
+    // §13.6 — node closed-set + reserved-key check.
+    for (const key of Object.keys(node)) {
+      if (ALLOWED_NODE_KEYS.has(key)) continue
+      if (RESERVED_NODE_KEYS.has(key)) {
+        errors.push(`${ctx}: node key "${key}" is reserved for future use; remove it`)
+      } else {
+        errors.push(`${ctx}: unknown node key "${key}" (allowed: ${[...ALLOWED_NODE_KEYS].join(", ")})`)
+      }
+    }
+
+    // §13.7 — id slug, unique.
+    if (typeof node.id !== "string" || !SLUG_RE.test(node.id)) {
+      errors.push(`${ctx}: id must match ${SLUG_RE} (got ${JSON.stringify(node.id)})`)
+      continue
+    }
+    if (seenIds.has(node.id)) {
+      errors.push(`${ctx}: duplicate node id "${node.id}"`)
+    }
+    seenIds.add(node.id)
+
+    // §13.8 — kind resolves in registry (when a resolver is supplied).
+    if (typeof node.kind !== "string") {
+      errors.push(`${ctx} ("${node.id}"): kind must be a string`)
+      continue
+    }
+    if (!hasKind(node.kind)) {
+      errors.push(`${ctx} ("${node.id}"): unknown kind "${node.kind}"`)
+    }
+
+    // params / input objects (raw shape).
+    if (node.params !== undefined && (typeof node.params !== "object" || Array.isArray(node.params) || node.params === null)) {
+      errors.push(`${ctx} ("${node.id}"): params must be an object`)
+    }
+    if (node.input !== undefined && (typeof node.input !== "object" || Array.isArray(node.input) || node.input === null)) {
+      errors.push(`${ctx} ("${node.id}"): input must be an object`)
+    }
+
+    // dependsOn shape.
+    let dependsOn: string[] = []
+    if (node.dependsOn !== undefined) {
+      if (!Array.isArray(node.dependsOn) || !node.dependsOn.every((d) => typeof d === "string")) {
+        errors.push(`${ctx} ("${node.id}"): dependsOn must be a string[]`)
+      } else {
+        dependsOn = node.dependsOn as string[]
+      }
+    }
+
+    // §13.9 — discriminator parse for params + input. `params` and `input`
+    // are kind-namespaced containers per §1: keys are kind-defined, values
+    // follow the discriminator. parseDiscContainer ensures the container
+    // itself is not mistaken for an explicit-static `{ value: ... }` form
+    // when a kind happens to have a single port named `value` (e.g. sink).
+    const paramsRaw = (node.params as Record<string, unknown> | undefined) ?? {}
+    const inputRaw  = (node.input  as Record<string, unknown> | undefined) ?? {}
+    const paramsParse = parseDiscContainer(paramsRaw, `${ctx}.params`)
+    const inputParse  = parseDiscContainer(inputRaw,  `${ctx}.input`)
+    for (const e of paramsParse.errors) errors.push(e)
+    for (const e of inputParse.errors)  errors.push(e)
+
+    const refs = new Set<string>([...paramsParse.refs, ...inputParse.refs])
+
+    // §11 / §16.1 — per-node failure-handling policy.
+    const onError = parseOnError(node.onError, `${ctx} ("${node.id}")`, errors) ?? { kind: "abort" }
+
+    // §13 item 9 — per-kind manifest enforcement (params + input shape).
+    // Skipped for unknown kinds (already errored above) and when no manifest
+    // resolver was supplied (offline mode).
+    if (getKindManifest && hasKind(node.kind as string)) {
+      const manifest = getKindManifest(node.kind as string)
+      if (manifest) {
+        const declParams = manifest.params ?? {}
+        const declInputs = manifest.inputs ?? {}
+
+        for (const [key, def] of Object.entries(declParams)) {
+          if (def.required && !(key in paramsRaw)) {
+            errors.push(`${ctx} ("${node.id}"): kind "${node.kind}" requires param "${key}"`)
+          }
+        }
+        for (const key of Object.keys(paramsRaw)) {
+          if (!(key in declParams)) {
+            const allowed = Object.keys(declParams).join(", ") || "(none)"
+            errors.push(`${ctx} ("${node.id}"): kind "${node.kind}" has no param "${key}" (allowed: ${allowed})`)
+          }
+        }
+
+        for (const [key, def] of Object.entries(declInputs)) {
+          if (def.required && !(key in inputRaw)) {
+            errors.push(`${ctx} ("${node.id}"): kind "${node.kind}" requires input "${key}"`)
+          }
+        }
+        for (const key of Object.keys(inputRaw)) {
+          if (!(key in declInputs)) {
+            const allowed = Object.keys(declInputs).join(", ") || "(none)"
+            errors.push(`${ctx} ("${node.id}"): kind "${node.kind}" has no input "${key}" (allowed: ${allowed})`)
+          }
+        }
+      }
+    }
+
+    rawNodes.push({
+      id: node.id,
+      kind: node.kind as string,
+      label: typeof node.label === "string" ? node.label : undefined,
+      params: paramsRaw,
+      input:  inputRaw,
+      dependsOn: dependsOn.length > 0 ? dependsOn : undefined,
+      onError: node.onError as PipelineNode["onError"],
+    })
+
+    parsedNodes.push({
+      id: node.id,
+      kind: node.kind as string,
+      label: typeof node.label === "string" ? node.label : undefined,
+      paramsTree: paramsParse.tree,
+      inputTree:  inputParse.tree,
+      dependsOn,
+      refs,
+      onError,
+    })
+  }
+
+  // §13.11 — every ref resolves to an existing node.
+  // §13.12 — DAG is acyclic.
+  const edges: { from: string; to: string; source: "expr" | "dependsOn" }[] = []
+  if (errors.length === 0) {
+    for (const node of parsedNodes) {
+      for (const ref of node.refs) {
+        if (!seenIds.has(ref)) {
+          errors.push(`node "${node.id}" references unknown result "${ref}" via ctx.results.${ref}`)
+        } else {
+          edges.push({ from: ref, to: node.id, source: "expr" })
+        }
+      }
+      for (const dep of node.dependsOn) {
+        if (!seenIds.has(dep)) {
+          errors.push(`node "${node.id}" dependsOn unknown id "${dep}"`)
+        } else {
+          edges.push({ from: dep, to: node.id, source: "dependsOn" })
+        }
+      }
+    }
+
+    if (errors.length === 0) {
+      const cycle = detectCycle(parsedNodes, edges)
+      if (cycle) errors.push(`pipeline has a cycle: ${cycle.join(" → ")}`)
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors, warnings }
+  }
+
+  const parsed: PipelineSpec = {
+    apiVersion,
+    id: typeof spec.id === "string" ? spec.id : "draft",
+    label: typeof spec.label === "string" ? spec.label : undefined,
+    description: typeof spec.description === "string" ? spec.description : undefined,
+    schedule: typeof spec.schedule === "string" ? spec.schedule : undefined,
+    payloadSchema: spec.payloadSchema as object | undefined,
+    payloadValidator,
+    nodes: rawNodes,
+    parsedNodes,
+    edges,
+    warnings,
+  }
+
+  return {
+    ok: true,
+    errors: [],
+    warnings,
+    parsed,
+    edges: edges.map(({ from, to }) => ({ from, to })),
+  }
+}
+
+/** Cron 5-field syntactic check. Lenient — accepts standard `* / , -` syntax. */
+function isValidCron(expr: string): boolean {
+  const fields = expr.trim().split(/\s+/)
+  if (fields.length !== 5) return false
+  return fields.every((f) => /^[\d*/,\-]+$/.test(f) || /^[A-Za-z]{3}([,\-][A-Za-z]{3})*$/.test(f))
+}
+
+/** DFS cycle detection. Returns the offending path on cycle, null otherwise. */
+function detectCycle(
+  nodes: ParsedNode[],
+  edges: { from: string; to: string }[],
+): string[] | null {
+  const adj = new Map<string, string[]>()
+  for (const n of nodes) adj.set(n.id, [])
+  for (const e of edges) adj.get(e.from)!.push(e.to)
+
+  const WHITE = 0, GREY = 1, BLACK = 2
+  const color = new Map<string, number>()
+  for (const n of nodes) color.set(n.id, WHITE)
+  const stack: string[] = []
+
+  const visit = (id: string): string[] | null => {
+    color.set(id, GREY)
+    stack.push(id)
+    for (const next of adj.get(id) ?? []) {
+      const c = color.get(next)
+      if (c === GREY) {
+        const start = stack.indexOf(next)
+        return [...stack.slice(start), next]
+      }
+      if (c === WHITE) {
+        const cyc = visit(next)
+        if (cyc) return cyc
+      }
+    }
+    color.set(id, BLACK)
+    stack.pop()
+    return null
+  }
+
+  for (const n of nodes) {
+    if (color.get(n.id) === WHITE) {
+      const cyc = visit(n.id)
+      if (cyc) return cyc
+    }
+  }
+  return null
+}
+
+// ─── onError policy parser ───────────────────────────────────────────────────
+// Per pipeline-spec.md §11 / §16.1 and decision_pipeline_recovery_model_v1.
+// Returns a ResolvedOnError on success (or `null` plus errors[] additions).
+// The skip-with value is parsed as a discriminator so the dispatcher can
+// resolve it against the live ctx at substitution time.
+
+function parseOnError(
+  raw: unknown,
+  ctxLabel: string,
+  errors: string[],
+): ResolvedOnError | null {
+  if (raw === undefined) return { kind: "abort" }
+
+  if (raw === "abort")   return { kind: "abort" }
+  if (raw === "suspend") return { kind: "suspend" }
+
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push(
+      `${ctxLabel}: onError must be "abort" | "suspend" | { skip-with } | { retry } ` +
+      `(got ${JSON.stringify(raw)})`,
+    )
+    return null
+  }
+
+  const obj = raw as Record<string, unknown>
+  const keys = Object.keys(obj)
+  if (keys.length !== 1) {
+    errors.push(
+      `${ctxLabel}: onError object form must have exactly one key (skip-with or retry); got [${keys.join(", ")}]`,
+    )
+    return null
+  }
+
+  const key = keys[0]
+  if (key === "skip-with") {
+    // The value is itself a discriminator leaf — bare | { value } | { expr }.
+    const parsed = parseDisc(obj[key], `${ctxLabel}.skip-with`)
+    for (const e of parsed.errors) errors.push(e)
+    return { kind: "skip-with", valueTree: parsed.tree }
+  }
+
+  if (key === "retry") {
+    const r = obj[key]
+    if (!r || typeof r !== "object" || Array.isArray(r)) {
+      errors.push(`${ctxLabel}: onError.retry must be an object { times, backoff? }`)
+      return null
+    }
+    const ro = r as Record<string, unknown>
+    const times = ro.times
+    if (typeof times !== "number" || !Number.isFinite(times) || times < 1 || !Number.isInteger(times)) {
+      errors.push(`${ctxLabel}: onError.retry.times must be a positive integer (got ${JSON.stringify(times)})`)
+      return null
+    }
+    let backoff: "linear" | "exponential" = "linear"
+    if (ro.backoff !== undefined) {
+      if (ro.backoff !== "linear" && ro.backoff !== "exponential") {
+        errors.push(`${ctxLabel}: onError.retry.backoff must be "linear" or "exponential" (got ${JSON.stringify(ro.backoff)})`)
+        return null
+      }
+      backoff = ro.backoff
+    }
+    // Reject extra keys
+    const extras = Object.keys(ro).filter((k) => k !== "times" && k !== "backoff")
+    if (extras.length > 0) {
+      errors.push(`${ctxLabel}: onError.retry has unknown keys: ${extras.join(", ")}`)
+      return null
+    }
+    return { kind: "retry", times, backoff }
+  }
+
+  errors.push(`${ctxLabel}: onError object key "${key}" not recognised (allowed: skip-with, retry)`)
+  return null
+}