@owlmeans/agent-common 0.1.18-rc.7 → 0.1.18

package/src/consts.ts

@@ -1,3 +1,5 @@
+import type { ShallowFlow } from '@owlmeans/flow'
+
 /**
  * The agent service alias.
  *
@@ -16,9 +18,54 @@ export const AGENTS_SERVICE = 'agents'
  * the same way `ExecutionService.checkpoint` does with no plugin registered.
  */
 export const AGENT_CONVERSATION_STORE = 'agent-conversation-store'
-export const AGENT_RUN_STATE_STORE = 'agent-run-state-store'
 export const AGENT_MEMORY_GRAPH_STORE = 'agent-memory-graph-store'
 export const AGENT_MEMORY_EVENTS_STORE = 'agent-memory-events-store'
+export const AGENT_PIPELINE_RUN_STORE = 'agent-pipeline-run-store'
+export const AGENT_CHECKPOINT_STORE = 'agent-checkpoint-store'
+export const AGENT_CUMULATIVE_RESULT_STORE = 'agent-cumulative-result-store'
+
+/**
+ * Caps and defaults for cumulative pipeline results.
+ *
+ * Every one of them bounds what a later step is TOLD, never what a step may produce: a fact that
+ * does not fit is left out of one view, and it is still on its entry for the next view and for any
+ * code that queries it. `DEFAULT_RESULTS_WINDOW` is a distance in the step graph — a consumer that
+ * many edges or fewer after a producer gets the producer's full entry; anything further back gets
+ * its names only, unless the producer names the consumer outright.
+ */
+export const DEFAULT_RESULTS_MAX_CHARS = 12_000
+export const DEFAULT_RESULT_ENTRY_CHARS = 4_000
+export const DEFAULT_RESULT_COMPACT_CHARS = 400
+export const DEFAULT_RESULTS_WINDOW = 2
+export const DEFAULT_RESULT_SUMMARY_CHARS = 600
+
+/** The consumer wildcard: every later step of the pipeline — and of anything it is composed into. */
+export const RESULTS_EVERY_STEP = '*'
+
+/**
+ * Caps and defaults for a pipeline run.
+ *
+ * `DEFAULT_MAX_STATE_CHARS` is generous by the standard of what a state may legally hold — scalars
+ * and keys — and deliberately so: it is a TRIPWIRE, not a budget. A state approaching it is a state
+ * carrying an artifact, and the step fails so that fact is discovered on the first run rather than
+ * surviving as a row nobody can read back.
+ *
+ * `DEFAULT_STEP_ATTEMPTS` is 1 because retry budgets in this family multiply: an outer retry around
+ * a model's own inner retry is their product, not their sum.
+ */
+export const DEFAULT_MAX_STATE_CHARS = 256_000
+export const DEFAULT_STEP_ATTEMPTS = 1
+export const DEFAULT_STEP_TIMEOUT = 1_800_000
+
+/**
+ * Where a pipeline's answers live in its state.
+ *
+ * One key, named here rather than per pipeline, because an answer has to survive every hop it can
+ * take: a resume merges answers into it, a composing step forwards it to its child, and a reader
+ * looks a question up by id. Scalars and keys, like everything else a state holds — the answer's
+ * decision travels here and its prose belongs wherever that pipeline keeps its documents.
+ */
+export const INQUIRY_ANSWERS_KEY = 'answers'
 
 /** The lifecycle flow every agent run is driven through. */
 export const AGENT_RUN_FLOW = 'agent-run'
@@ -29,8 +76,12 @@ export const AGENT_RUN_FLOW = 'agent-run'
  * These are recoverable LIFECYCLE stages, not conversational turns. A ReAct loop's turn count is
  * unbounded and its messages are not scalars, while `FlowPayload` holds flat scalars only — so the
  * loop lives inside `Working` and only its counter travels in the payload. What the steps buy is
- * the ability to say where a crashed run has to resume: at `Working` from the last checkpoint, or
- * at `Finalizing` when the loop finished but the compaction never committed.
+ * the ability to say how far a run got when it ended, which is what a plugin reads on `onFinish`.
+ *
+ * Nothing RESUMES one of these. A ReAct run is not a resumable unit: its state is an unbounded
+ * message list whose tool results are side effects already applied to the world, so re-entering it
+ * would re-apply them. Resumable work is a PIPELINE — see `pipeline.ts` — whose steps are named,
+ * whose state is scalars, and whose side effects are guarded per step.
  */
 export enum AgentRunStep {
   Received = 'received',
@@ -48,7 +99,6 @@ export enum AgentRunTransition {
   Finalize = 'finalize',
   Finish = 'finish',
   Fail = 'fail',
-  Resume = 'resume',
 }
 
 /** How a run ended. Written on the conversation event so a reader can weigh the advice. */
@@ -71,3 +121,167 @@ export const DEFAULT_MEMORY_EVENTS_LIMIT = 50
 
 /** Separator between a dedication's kind and its target — `project:<id>`. */
 export const SCOPE_SEP = ':'
+
+/** How a run ended, or that it has not. */
+export enum PipelineRunStatus {
+  Running = 'running',
+  Done = 'done',
+  Failed = 'failed',
+  /** Stopped on purpose with work left — a budget expired, or the caller asked. Resumable. */
+  Aborted = 'aborted',
+  /**
+   * Stopped on purpose, waiting for an answer to {@link PipelineRun.inquiry}.
+   *
+   * Resumable, and NOT stale: a waiting run has no process behind it and its `heartbeatAt` will not
+   * move again until somebody answers. A reconciler that reads staleness alone would take this for
+   * a crashed run and repair what is merely waiting.
+   */
+  Waiting = 'waiting',
+}
+
+/** Where the facts of an entry came from. */
+export enum CumulativeResultSource {
+  /** Read by code from what the step left behind, when the step finished. */
+  Extracted = 'extracted',
+  /**
+   * Read by code from the step's DURABLE inputs, after the fact — on a resume that found no stored
+   * entry, or for a step whose guard skipped it. The same facts an extraction would have found.
+   */
+  Rebuilt = 'rebuilt',
+  /** Supplied before any step of the run ran — the caller already knew them. */
+  Seeded = 'seeded',
+  /** No facts at all; only a model's summary, which nothing has checked. */
+  Summarized = 'summarized',
+}
+
+/** How one entry appears in a view cut for a given step. */
+export enum ResultViewMode {
+  Full = 'full',
+  /** Names only, grouped by kind. */
+  Compact = 'compact',
+  /** Not in the prompt. Still answered by a programmatic facts query. */
+  Omitted = 'omitted',
+}
+
+/**
+ * Kinds an extractor is encouraged to use. `CumulativeResultFact.kind` is an open string — declare
+ * your own — but two extractors naming the same thing differently split one fact into two.
+ */
+export enum CumulativeFactKind {
+  Type = 'type',
+  Symbol = 'symbol',
+  Endpoint = 'endpoint',
+  Resource = 'resource',
+  File = 'file',
+}
+
+/**
+ * The lifecycle of one agent run.
+ *
+ * Read it as "how far did this run get", not "what did it say". Everything conversational happens
+ * inside `Working`; the steps exist so a plugin reading `onFinish` can say where a run ended.
+ * `Fail` is reachable from every working step and is TERMINAL — see the note on that step.
+ *
+ * `service` is left as the flow name on every step. A flow step normally binds to a service or an
+ * entrypoint, but an agent run is driven by whoever holds the model — there is no second party to
+ * hand control to, and inventing one would put a name in the serialized state that nothing
+ * resolves.
+ *
+ * Each working step keeps exactly ONE non-explicit outgoing transition, so `FlowModel.next()`
+ * always has an unambiguous answer: that is what lets a driver advance the run without knowing the
+ * vocabulary. `Fail` is marked explicit precisely so it never becomes that automatic answer.
+ */
+export const agentRunFlow: ShallowFlow = {
+  flow: AGENT_RUN_FLOW,
+  initialStep: AgentRunStep.Received,
+
+  steps: {
+    [AgentRunStep.Received]: {
+      index: 0,
+      step: AgentRunStep.Received,
+      service: AGENT_RUN_FLOW,
+      initial: true,
+      transitions: {
+        [AgentRunTransition.Prepare]: {
+          transition: AgentRunTransition.Prepare,
+          step: AgentRunStep.Prepared,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Prepared]: {
+      index: 1,
+      step: AgentRunStep.Prepared,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Work]: {
+          transition: AgentRunTransition.Work,
+          step: AgentRunStep.Working,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Working]: {
+      index: 2,
+      step: AgentRunStep.Working,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Finalize]: {
+          transition: AgentRunTransition.Finalize,
+          step: AgentRunStep.Finalizing,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Finalizing]: {
+      index: 3,
+      step: AgentRunStep.Finalizing,
+      service: AGENT_RUN_FLOW,
+      transitions: {
+        [AgentRunTransition.Finish]: {
+          transition: AgentRunTransition.Finish,
+          step: AgentRunStep.Finished,
+        },
+        [AgentRunTransition.Fail]: {
+          transition: AgentRunTransition.Fail,
+          step: AgentRunStep.Failed,
+          explicit: true,
+        },
+      },
+    },
+
+    [AgentRunStep.Finished]: {
+      index: 4,
+      step: AgentRunStep.Finished,
+      service: AGENT_RUN_FLOW,
+      transitions: {},
+    },
+
+    [AgentRunStep.Failed]: {
+      index: 5,
+      step: AgentRunStep.Failed,
+      service: AGENT_RUN_FLOW,
+      // Terminal. Nothing resumes a ReAct run — its tool results are side effects already applied
+      // to the world, so re-entering it re-applies them. Resumable work is a pipeline.
+      transitions: {},
+    },
+  },
+}
+
+/** Every flow this package declares, for a provider to serve. */
+export const agentFlows: ShallowFlow[] = [agentRunFlow]

package/src/errors.ts

@@ -18,5 +18,101 @@ export class AgentRunStateError extends AgentCommonError {
   }
 }
 
+/**
+ * A pipeline declaration is not runnable.
+ *
+ * Thrown by {@link import('./models/pipeline-spec/types.js').PipelineSpecModel.validate} and by the runner's own build
+ * step, and it always names EVERY fault it found rather than the first: a spec is authored once and
+ * fixed once, and reporting faults one per build turns a five-minute edit into five builds.
+ */
+export class PipelineSpecError extends AgentCommonError {
+  public static override typeName: string = `PipelineSpec${AgentCommonError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`pipeline-spec:${message}`)
+    this.type = PipelineSpecError.typeName
+  }
+}
+
+/**
+ * A resume was asked of a run started under a different version of its pipeline.
+ *
+ * Refused rather than adapted. `completed` names steps by string, so a spec that has since renamed,
+ * removed or reordered a step would have a resumed run skip work it never did — silently, because
+ * an unknown name in `completed` simply matches nothing.
+ */
+export class PipelineVersionError extends AgentCommonError {
+  public static override typeName: string = `PipelineVersion${AgentCommonError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`pipeline-version:${message}`)
+    this.type = PipelineVersionError.typeName
+  }
+}
+
+/** A resume, a progress report or a skip named a step the spec does not declare. */
+export class PipelineUnknownStepError extends AgentCommonError {
+  public static override typeName: string = `PipelineUnknownStep${AgentCommonError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`pipeline-step:${message}`)
+    this.type = PipelineUnknownStepError.typeName
+  }
+}
+
+/**
+ * A resume was asked to re-enter a completed step whose side effect cannot be repeated.
+ *
+ * The caller may override with `force`, which is why this is an error and not a silent skip: an
+ * operator re-running a wipe, a purge or a hostname claim has to say so.
+ */
+export class PipelineNotIdempotentError extends AgentCommonError {
+  public static override typeName: string = `PipelineNotIdempotent${AgentCommonError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`pipeline-idempotency:${message}`)
+    this.type = PipelineNotIdempotentError.typeName
+  }
+}
+
+/**
+ * A step produced a state larger than the run row may carry.
+ *
+ * The step FAILS — the state is never truncated and the write is never skipped. A pipeline state is
+ * scalars and keys by contract; anything that overflows it is a large artifact that belongs in a
+ * store of its own, and silently dropping it would make a resume replay from a state that never
+ * existed.
+ */
+export class PipelineStateTooLargeError extends AgentCommonError {
+  public static override typeName: string = `PipelineStateTooLarge${AgentCommonError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`pipeline-state:${message}`)
+    this.type = PipelineStateTooLargeError.typeName
+  }
+}
+
+/**
+ * A run was asked to wait for an answer it has no way of being given.
+ *
+ * Thrown when a step asks a question, nobody is there to answer it, and the pipeline has no run
+ * store: parking would leave nothing behind to resume, so the step fails at once rather than
+ * stopping a run that could never be started again.
+ */
+export class PipelineNotResumableError extends AgentCommonError {
+  public static override typeName: string = `PipelineNotResumable${AgentCommonError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`pipeline-not-resumable:${message}`)
+    this.type = PipelineNotResumableError.typeName
+  }
+}
+
 ResilientError.registerErrorClass(AgentCommonError)
 ResilientError.registerErrorClass(AgentRunStateError)
+ResilientError.registerErrorClass(PipelineSpecError)
+ResilientError.registerErrorClass(PipelineVersionError)
+ResilientError.registerErrorClass(PipelineUnknownStepError)
+ResilientError.registerErrorClass(PipelineNotIdempotentError)
+ResilientError.registerErrorClass(PipelineStateTooLargeError)
+ResilientError.registerErrorClass(PipelineNotResumableError)

package/src/helpers/conversation.ts

@@ -28,35 +28,3 @@ export const conversationFor = (
     scope: override?.scope ?? (target !== '' ? target : 'anonymous'),
   }
 }
-
-/**
- * Cut `text` to `max` characters on a boundary a reader will not trip over.
- *
- * Every cap in this package lands here, because a model asked for "at most N characters" answers
- * with N plus whatever it felt was needed. Truncating mid-word reads as corruption and truncating
- * mid-sentence reads as a bug report, so the cut prefers the last paragraph, then line, then
- * sentence, then word break inside the last quarter of the budget, and always marks itself.
- */
-export const truncateAt = (text: string, max: number): string => {
-  const trimmed = text.trim()
-  if (trimmed.length <= max) {
-    return trimmed
-  }
-  if (max <= 1) {
-    return trimmed.slice(0, Math.max(0, max))
-  }
-
-  const ellipsis = '…'
-  const budget = max - ellipsis.length
-  const head = trimmed.slice(0, budget)
-  const floor = Math.floor(budget * 0.75)
-
-  for (const boundary of ['\n\n', '\n', '. ', ' ']) {
-    const at = head.lastIndexOf(boundary)
-    if (at >= floor) {
-      return head.slice(0, boundary === '. ' ? at + 1 : at).trimEnd() + ellipsis
-    }
-  }
-
-  return head.trimEnd() + ellipsis
-}

package/src/helpers/truncate.ts

@@ -0,0 +1,31 @@
+/**
+ * Cut `text` to `max` characters on a boundary a reader will not trip over.
+ *
+ * Every cap in this package lands here, because a model asked for "at most N characters" answers
+ * with N plus whatever it felt was needed. Truncating mid-word reads as corruption and truncating
+ * mid-sentence reads as a bug report, so the cut prefers the last paragraph, then line, then
+ * sentence, then word break inside the last quarter of the budget, and always marks itself.
+ */
+export const truncateAt = (text: string, max: number): string => {
+  const trimmed = text.trim()
+  if (trimmed.length <= max) {
+    return trimmed
+  }
+  if (max <= 1) {
+    return trimmed.slice(0, Math.max(0, max))
+  }
+
+  const ellipsis = '…'
+  const budget = max - ellipsis.length
+  const head = trimmed.slice(0, budget)
+  const floor = Math.floor(budget * 0.75)
+
+  for (const boundary of ['\n\n', '\n', '. ', ' ']) {
+    const at = head.lastIndexOf(boundary)
+    if (at >= floor) {
+      return head.slice(0, boundary === '. ' ? at + 1 : at).trimEnd() + ellipsis
+    }
+  }
+
+  return head.trimEnd() + ellipsis
+}

package/src/index.ts

@@ -1,5 +1,10 @@
 export * from './consts.js'
 export * from './errors.js'
 export type * from './types.js'
-export * from './flows.js'
+export type * from './results/types.js'
+export type * from './models/pipeline-spec/types.js'
+export * from './models/pipeline-spec.js'
+export * from './pipeline.js'
+export * from './results.js'
 export * from './helpers/conversation.js'
+export * from './helpers/truncate.js'

package/src/models/pipeline-spec/types.ts

@@ -0,0 +1,58 @@
+import type { PipelineSpec, PipelineStepSpec } from '../../types.js'
+
+/** One step a step transitively waits on, with the fewest `after` edges between the two. */
+export interface PipelineStepDepth {
+  step: string
+  depth: number
+}
+
+/** The rules of one pipeline declaration: its validity, its order and the graph of its steps. */
+export interface PipelineSpecModel {
+  readonly record: PipelineSpec
+  /**
+   * Every fault in one message, or nothing.
+   *
+   * Total and IO-free, so a spec can be checked by a test in microseconds and by the runner at build
+   * time. It reports EVERY fault it finds rather than the first, because a spec is authored once and
+   * a build that names one fault per run turns a five-minute edit into five builds.
+   *
+   * @throws {PipelineSpecError}
+   */
+  validate: () => void
+  /**
+   * The steps in an order that respects every `after`, with declaration order as the tie-break.
+   *
+   * Deterministic on purpose: the order decides what a progress report calls "step 3 of 16" and what
+   * a resume considers already behind it, and an order that depends on a `Set`'s iteration would make
+   * both drift between processes.
+   *
+   * @throws {PipelineSpecError} on a cycle or an unknown `after`.
+   */
+  orderSteps: () => string[]
+  /**
+   * `step` and everything that transitively waits on it.
+   *
+   * What a resume has to re-run when an operator names a step: re-entering a step without re-entering
+   * what read its output leaves the run describing a state that no longer follows from itself.
+   *
+   * @throws {PipelineUnknownStepError} when the spec does not declare `step`.
+   */
+  descendants: (step: string) => string[]
+  /**
+   * Every step `step` transitively waits on, with its DEPTH — the fewest `after` edges between the
+   * two — in topological order.
+   *
+   * The mirror of {@link PipelineSpecModel.descendants}, with one deliberate asymmetry: the named step
+   * itself is NOT included. A re-run re-enters the step it names, so the descendants include it;
+   * nothing is its own predecessor, so the ancestors do not. The depth is what a consumer uses to
+   * decide how much of a predecessor's output it needs to be told — a direct predecessor is depth 1
+   * however far apart the two sit in the topological order.
+   *
+   * @throws {PipelineUnknownStepError} when the spec does not declare `step`.
+   */
+  ancestry: (step: string) => PipelineStepDepth[]
+  /** The names from {@link PipelineSpecModel.ancestry}: what must finish before `step` may start, in order. */
+  ancestors: (step: string) => string[]
+  /** The declaration of one step, by name. `null` when the spec does not declare it. */
+  stepOf: (step: string) => PipelineStepSpec | null
+}

package/src/models/pipeline-spec.ts

@@ -0,0 +1,202 @@
+import { DEFAULT_STEP_ATTEMPTS } from '../consts.js'
+import { PipelineSpecError, PipelineUnknownStepError } from '../errors.js'
+import type { PipelineSpec, PipelineStepSpec } from '../types.js'
+import type { PipelineSpecModel, PipelineStepDepth } from './pipeline-spec/types.js'
+
+export const makePipelineSpecModel = (spec: PipelineSpec): PipelineSpecModel => {
+  const fault = (faults: string[], message: string): void => {
+    faults.push(message)
+  }
+
+  const validate = (): void => {
+    const faults: string[] = []
+
+    if (spec.alias == null || spec.alias.trim() === '') {
+      fault(faults, 'alias is empty')
+    }
+    if (!Number.isInteger(spec.version) || spec.version < 1) {
+      fault(faults, `version must be a positive integer, got ${String(spec.version)}`)
+    }
+    if (!Array.isArray(spec.steps) || spec.steps.length === 0) {
+      fault(faults, 'no steps declared')
+      throw new PipelineSpecError(`${spec.alias ?? '?'}: ${faults.join('; ')}`)
+    }
+
+    const seen = new Set<string>()
+    for (const step of spec.steps) {
+      if (step.step == null || step.step.trim() === '') {
+        fault(faults, 'a step has an empty name')
+        continue
+      }
+      if (seen.has(step.step)) {
+        fault(faults, `duplicate step "${step.step}"`)
+      }
+      seen.add(step.step)
+    }
+
+    for (const step of spec.steps) {
+      for (const dependency of step.after ?? []) {
+        if (dependency === step.step) {
+          fault(faults, `step "${step.step}" declares itself in \`after\``)
+        } else if (!seen.has(dependency)) {
+          fault(faults, `step "${step.step}" waits on unknown step "${dependency}"`)
+        }
+      }
+      const attempts = step.attempts ?? DEFAULT_STEP_ATTEMPTS
+      if (!Number.isInteger(attempts) || attempts < 1) {
+        fault(faults, `step "${step.step}" declares attempts ${String(step.attempts)}`)
+      }
+      if (step.nonIdempotent === true && attempts > 1) {
+        fault(
+          faults,
+          `step "${step.step}" is nonIdempotent and declares attempts ${attempts} — an automatic `
+          + 'retry is exactly what that flag says must not happen',
+        )
+      }
+      if (step.timeout != null && (!Number.isFinite(step.timeout) || step.timeout <= 0)) {
+        fault(faults, `step "${step.step}" declares timeout ${String(step.timeout)}`)
+      }
+    }
+
+    // A cycle is reported here rather than left to the sort, so one message carries every fault.
+    if (faults.every(entry => !entry.includes('unknown step'))) {
+      const cycle = detectCycle()
+      if (cycle != null) {
+        fault(faults, `cycle: ${cycle.join(' → ')}`)
+      }
+    }
+
+    if (faults.length > 0) {
+      throw new PipelineSpecError(`${spec.alias}: ${faults.join('; ')}`)
+    }
+  }
+
+  const detectCycle = (): string[] | null => {
+    const after = new Map(spec.steps.map(step => [step.step, step.after ?? []]))
+    const state = new Map<string, 0 | 1 | 2>()
+    const path: string[] = []
+
+    const walk = (name: string): string[] | null => {
+      const mark = state.get(name)
+      if (mark === 2) return null
+      if (mark === 1) return [...path.slice(path.indexOf(name)), name]
+
+      state.set(name, 1)
+      path.push(name)
+      for (const dependency of after.get(name) ?? []) {
+        const found = walk(dependency)
+        if (found != null) return found
+      }
+      path.pop()
+      state.set(name, 2)
+
+      return null
+    }
+
+    for (const step of spec.steps) {
+      const found = walk(step.step)
+      if (found != null) return found.reverse()
+    }
+
+    return null
+  }
+
+  const orderSteps = (): string[] => {
+    const names = spec.steps.map(step => step.step)
+    const known = new Set(names)
+    const pending = new Map<string, Set<string>>()
+    const dependents = new Map<string, string[]>()
+
+    for (const step of spec.steps) {
+      const dependencies = new Set<string>()
+      for (const dependency of step.after ?? []) {
+        if (!known.has(dependency)) {
+          throw new PipelineSpecError(
+            `${spec.alias}: step "${step.step}" waits on unknown step "${dependency}"`,
+          )
+        }
+        dependencies.add(dependency)
+        dependents.set(dependency, [...(dependents.get(dependency) ?? []), step.step])
+      }
+      pending.set(step.step, dependencies)
+    }
+
+    const ordered: string[] = []
+    const emitted = new Set<string>()
+
+    while (ordered.length < names.length) {
+      // Declaration order among everything currently ready — never a set's own order.
+      const ready = names.filter(name => !emitted.has(name) && (pending.get(name)?.size ?? 0) === 0)
+      if (ready.length === 0) {
+        const cycle = detectCycle()
+        throw new PipelineSpecError(
+          `${spec.alias}: cycle: ${(cycle ?? names.filter(name => !emitted.has(name))).join(' → ')}`,
+        )
+      }
+      for (const name of ready) {
+        ordered.push(name)
+        emitted.add(name)
+        for (const dependent of dependents.get(name) ?? []) {
+          pending.get(dependent)?.delete(name)
+        }
+      }
+    }
+
+    return ordered
+  }
+
+  const descendants = (step: string): string[] => {
+    if (!spec.steps.some(entry => entry.step === step)) {
+      throw new PipelineUnknownStepError(`${spec.alias}:${step}`)
+    }
+
+    const reached = new Set<string>([step])
+    let grew = true
+    while (grew) {
+      grew = false
+      for (const entry of spec.steps) {
+        if (reached.has(entry.step)) continue
+        if ((entry.after ?? []).some(dependency => reached.has(dependency))) {
+          reached.add(entry.step)
+          grew = true
+        }
+      }
+    }
+
+    return orderSteps().filter(name => reached.has(name))
+  }
+
+  const ancestry = (step: string): PipelineStepDepth[] => {
+    if (!spec.steps.some(entry => entry.step === step)) {
+      throw new PipelineUnknownStepError(`${spec.alias}:${step}`)
+    }
+
+    const after = new Map(spec.steps.map(entry => [entry.step, entry.after ?? []]))
+    const depths = new Map<string, number>()
+    let frontier = [step]
+    for (let depth = 1; frontier.length > 0; ++depth) {
+      const next: string[] = []
+      for (const name of frontier) {
+        for (const dependency of after.get(name) ?? []) {
+          if (dependency !== step && !depths.has(dependency)) {
+            depths.set(dependency, depth)
+            next.push(dependency)
+          }
+        }
+      }
+      frontier = next
+    }
+
+    return orderSteps()
+      .filter(name => depths.has(name))
+      .map(name => ({ step: name, depth: depths.get(name)! }))
+  }
+
+  const ancestors = (step: string): string[] =>
+    ancestry(step).map(entry => entry.step)
+
+  const stepOf = (step: string): PipelineStepSpec | null =>
+    spec.steps.find(entry => entry.step === step) ?? null
+
+  return { record: spec, validate, orderSteps, descendants, ancestry, ancestors, stepOf }
+}