Defining steps

Helper	Use it for
`defineStep({ type, workflowInputSchema, outputSchema, dependencies?, handler, retry?, isRetryable?, timeoutMs?, delayMs?, waitForEvent?, compensate? })`	a normal step
`defineSleepStep({ type, sleepMs, dependencies? })`	a durable no-op delay
`defineWaitStep({ type, outputSchema, dependencies? })`	suspend until `engine.resumeStep`
`defineMapStep({ type, workflowInputSchema, itemOutputSchema, items, each, dependencies?, itemRetry?, itemIsRetryable?, itemTimeoutMs? })`	runtime-sized fan-out
`defineSubWorkflowStep({ type, workflowInputSchema, childWorkflow, input, outputSchema?, dependencies? })`	start + await a child workflow
`defineAiStep({ ... })`	a step whose `ctx.context` is an instrumented `AiContext` (AI add-on)

Keys and types are different things

const wf = buildWorkflow({ type: 'publish', inputSchema, steps: { draft, approval } });
//                                                                ^^^^^  ^^^^^^^^
//                                                                these are the step KEYS

type (on the step) names the handler. It is what the registry looks up, what gate rules and metrics are keyed on, and it may repeat across workflows.
The key is the property name under steps: in buildWorkflow. It identifies the step within this workflow: it’s what ctx.deps is keyed by, what engine.resumeStep takes, and what the workflow’s output object is keyed by.

The same rule applies to dependencies. The property name — not the variable — is the dependency key, and it must match the step’s key in buildWorkflow:

const shout = defineStep({ …, dependencies: { greet } });     // key 'greet'
buildWorkflow({ …, steps: { greet, shout } });                // ✅ matches

buildWorkflow({ …, steps: { greeting: greet, shout } });      // ❌ throws:
// [buildWorkflow] Step 'shout' depends on 'greet', which is not a valid step key.

Note that buildWorkflow throws here rather than returning a Result — a malformed DAG is a programming error, caught at module load. The deeper checks (cycles, duplicate keys, missing handlers) run at start and are returned as a Result; see validateDefinition.

The handler context

A handler receives a typed context:

handler: async (ctx) => {
  ctx.workflowInput;   // validated against workflowInputSchema
  ctx.deps.greet;      // each dependency's output, validated against ITS outputSchema
  ctx.stepInput;       // static per-step input from the definition
  ctx.context;         // host value from the `buildStepContext` hook
  ctx.signal;          // AbortSignal — fires on timeout
  ctx.workflowId; ctx.stepId; ctx.stepKey; ctx.partitionKey;
  return { … };        // validated against outputSchema
}

To fail a step, throw. The typed handler returns the step’s output; there is no error-return form (the Result-returning StepHandler is the untyped internal shape that defineStep wraps for you). Whether a throw is retried is decided by retryability — throw retryableError(…) or nonRetryableError(…) to say so outright.

Validation is a permanent failure

defineStep runs a five-phase pipeline: parse workflowInput → parse each dependency output → build the typed context → call the handler → parse the output. A mismatch at any of those phases fails the step with retryable: false — it is never retried, whatever the step’s retry policy says, because a schema mismatch is a bug rather than a blip.

The error message names the phase, which is usually enough to locate it:

[shout] Invalid dependency output 'greet': …
[shout] Invalid step output: …

ctx.signal is worth wiring through to anything that accepts one (fetch, database drivers) — timeoutMs aborts it on expiry, but only a handler that observes it actually stops early.