octaflow 0.16.0 → 0.17.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/octabits-io/octaflow/actions/workflows/ci.yml/badge.svg)](https://github.com/octabits-io/octaflow/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/octaflow.svg)](https://www.npmjs.com/package/octaflow)
-[![docs](https://img.shields.io/badge/docs-octabits--io.github.io%2Fflow-16794a.svg)](https://octabits-io.github.io/octaflow/)
+[![docs](https://img.shields.io/badge/docs-octaflow.octabits.io-16794a.svg)](https://octaflow.octabits.io/)
 [![license](https://img.shields.io/npm/l/octaflow.svg)](./LICENSE)
 [![types](https://img.shields.io/badge/types-included-blue.svg)](https://www.npmjs.com/package/octaflow)
 
@@ -14,12 +14,12 @@ restart. There is
 no workflow server to operate, no control plane, and no vendor — it's a library you import,
 not a platform you adopt.
 
-### 📖 [Read the docs →](https://octabits-io.github.io/octaflow/)
+### 📖 [Read the docs →](https://octaflow.octabits.io/)
 
-[Quick start](https://octabits-io.github.io/octaflow/start/quick-start/) ·
-[Concepts](https://octabits-io.github.io/octaflow/core/concepts/) ·
-[Postgres & pg-boss](https://octabits-io.github.io/octaflow/running/postgres-and-pg-boss/) ·
-[API reference](https://octabits-io.github.io/octaflow/reference/api/)
+[Quick start](https://octaflow.octabits.io/start/quick-start/) ·
+[Concepts](https://octaflow.octabits.io/core/concepts/) ·
+[Postgres & pg-boss](https://octaflow.octabits.io/running/postgres-and-pg-boss/) ·
+[API reference](https://octaflow.octabits.io/reference/api/)
 
 ```ts
 const wf = buildWorkflow({
@@ -65,14 +65,15 @@ of what it did. Both models are durable — they trade off differently, and
 
 A fuller pipeline than the snippet above — dynamic fan-out over two `map` steps at once, a
 concurrency cap so only 2 of 6 images encode at a time, a flaky step retried, a sub-workflow,
-a step suspended on an external event, and a durable sleep. Then a second workflow fails and
-its completed steps roll back in reverse.
+a step suspended on an external event under a deadline, a durable sleep, and a branch where
+the arm the review didn't choose is skipped but the join still fires. Then a second workflow
+fails and its completed steps roll back in reverse.
 
 <p align="center">
-  <img src="./docs/demo.svg" alt="Terminal trace of a publishing pipeline: parallel fan-out over locales and images with a concurrency cap, a retried step, a sub-workflow, a suspend-and-resume on an external event, a durable sleep, then a saga rollback in reverse order" width="760">
+  <img src="./docs/demo.svg" alt="Terminal trace of a publishing pipeline: parallel fan-out over locales and images with a concurrency cap, a retried step, a sub-workflow, a suspend-and-resume on an external event with a deadline armed, a durable sleep, a skipped branch converging on a join, then a saga rollback in reverse order" width="760">
 </p>
 
-Every line is an engine transition emitted through the [`FlowObserver`](https://octabits-io.github.io/octaflow/running/observability/) seam —
+Every line is an engine transition emitted through the [`FlowObserver`](https://octaflow.octabits.io/running/observability/) seam —
 the same one you'd point at OpenTelemetry or an events table — not a `console.log` in a handler.
 
 ```bash
@@ -105,7 +106,7 @@ workflow is expressed**.
 | **Model** | declarative — a static DAG value | imperative workflow code | imperative step functions | imperative tasks | job queue; flows are **trees** |
 | **Fan-in / diamond deps** | yes | yes | yes | yes | no — a job can't be shared by two branches |
 | **Inspect before running** | yes — the DAG is a value | no — the graph is the execution trace | no | no | yes — the flow tree is data |
-| **Web dashboard** | **none** — [build one](https://octabits-io.github.io/octaflow/running/live-progress/) | yes | yes | yes | via third-party UIs |
+| **Web dashboard** | **none** — [build one](https://octaflow.octabits.io/running/live-progress/) | yes | yes | yes | via third-party UIs |
 | **Languages** | TypeScript | polyglot SDKs | TS, Python, Go, Kotlin | TS | Node (+ ports) |
 | **Maturity** | **pre-1.0** | mature | mature | mature | mature, widely deployed |
 
@@ -119,12 +120,14 @@ that the others have earned.
 Reach for something else if:
 
 - **Your control flow is genuinely dynamic.** A declarative DAG is fixed at definition time.
-  Flow softens this with [`defineMapStep`](https://octabits-io.github.io/octaflow/core/fan-out-and-map/) (runtime-sized fan-out),
-  [sub-workflows](https://octabits-io.github.io/octaflow/core/sub-workflows/), and [`waitForEvent`](https://octabits-io.github.io/octaflow/core/signals/) — but if your
-  process is "loop until a human approves, branching on whatever they typed," an imperative
-  durable function will express it more naturally.
+  Flow softens this a lot — [`when` guards and joins](https://octaflow.octabits.io/core/branching/) (if/else over a static graph),
+  [`defineMapStep`](https://octaflow.octabits.io/core/fan-out-and-map/) (runtime-sized fan-out),
+  [sub-workflows](https://octaflow.octabits.io/core/sub-workflows/), and [`waitForEvent`](https://octaflow.octabits.io/core/signals/) — but the
+  set of steps is still fixed up front. If your process is "**loop** until a human approves,
+  branching on whatever they typed," an imperative durable function will express it more
+  naturally: Flow can pick a branch, not invent a step.
 - **You want a UI out of the box.** Flow ships a wire-safe projection
-  ([`toPublicWorkflow`](https://octabits-io.github.io/octaflow/extending/http/)) and lifecycle events, not a
+  ([`toPublicWorkflow`](https://octaflow.octabits.io/extending/http/)) and lifecycle events, not a
   dashboard. You build it.
 - **You need non-TypeScript workers.** The DAG and its schemas are TypeScript values.
 - **You can't run Postgres**, or you need throughput past what a Postgres-backed queue gives you.
@@ -188,13 +191,18 @@ next to what your steps actually do.
 | ⚡ | **Auto-parallelism** — dependency-free steps run concurrently; a step starts when all its deps complete |
 | 🔁 | **Retry & timeout** — per-step `maxAttempts`, fixed/exponential backoff, wall-clock timeout |
 | 💤 | **Durable sleep** — hold a step in the queue for N ms (survives restarts) |
+| 🔀 | **Conditional branching** — `when` guards skip a step and its branch; `join: 'any'` converges |
+| ⏳ | **Deadlines** — a budget on a suspended step (fail, or continue with a stand-in answer) and on a whole run |
+| ♻️ | **Retry a failed run** — `retryWorkflow` resumes from the failure point; completed steps keep their output |
 | 🚦 | **Concurrency & rate limiting** — per-step-type caps and token buckets via a pluggable gate |
 | ⏰ | **Cron / scheduled starts** — fire workflows on a schedule (pg-boss) |
 | 🔑 | **Start idempotency** — a dedup key collapses double-clicks / overlapping ticks |
 | 🗺️ | **Dynamic fan-out / map** — spawn one child step per item of a runtime-sized list |
-| ⏸️ | **Signals / waitForEvent** — suspend a step until an external event (`resumeStep`) |
+| ⏸️ | **Signals / waitForEvent** — suspend a step until an external event (`resumeStep`), with an optional deadline |
 | 🪆 | **Sub-workflows** — a step starts a child workflow and awaits its result |
 | ↩️ | **Saga compensation** — run rollback handlers in reverse order on failure |
+| 🚑 | **Crash recovery** — a step whose worker died is re-queued while its attempt budget lasts |
+| 💓 | **Heartbeats** — a long step proves it is alive, so a dead one is caught in seconds, not minutes |
 | 🔭 | **Observability** — lifecycle events (run history) + per-step spans, both pluggable |
 | 🤖 | **AI add-on** — instrumented models, token/cost capture, quota, daily rollups |
 | 🧱 | **Pluggable everything** — `WorkflowStore`, `Dispatcher`, `StepGate`, `FlowObserver`, hooks |
@@ -231,22 +239,25 @@ pnpm add ai @ai-sdk/provider
 ## Documentation
 
 Full docs — concepts, every feature, production wiring and the API reference — live at
-**[octabits-io.github.io/octaflow](https://octabits-io.github.io/octaflow/)**.
+**[octaflow.octabits.io](https://octaflow.octabits.io/)**.
 
 | | |
 |---|---|
-| [Quick start](https://octabits-io.github.io/octaflow/start/quick-start/) | a runnable workflow in one file, no database |
-| [Concepts](https://octabits-io.github.io/octaflow/core/concepts/) | step, workflow, registry, store, dispatcher, engine, partition |
-| [Defining steps](https://octabits-io.github.io/octaflow/core/defining-steps/) | `defineStep` and its variants |
-| [Retry & timeout](https://octabits-io.github.io/octaflow/core/retry-and-timeout/) | attempt budgets, backoff, and how a failure is classified |
-| [Fan-out & map](https://octabits-io.github.io/octaflow/core/fan-out-and-map/) | one child step per item of a runtime list |
-| [Signals](https://octabits-io.github.io/octaflow/core/signals/) · [Sub-workflows](https://octabits-io.github.io/octaflow/core/sub-workflows/) · [Saga](https://octabits-io.github.io/octaflow/core/saga-compensation/) | suspend, nest, and roll back |
-| [Postgres & pg-boss](https://octabits-io.github.io/octaflow/running/postgres-and-pg-boss/) | production wiring, workers, DLQ, cron |
-| [Cancellation & recovery](https://octabits-io.github.io/octaflow/running/cancellation-and-recovery/) | cancelling a run, and sweeping steps a crash left behind |
-| [Observability](https://octabits-io.github.io/octaflow/running/observability/) · [Live progress](https://octabits-io.github.io/octaflow/running/live-progress/) | lifecycle events, spans, and streaming them to a browser |
-| [The AI add-on](https://octabits-io.github.io/octaflow/extending/ai/) | token/cost capture, quota, usage rollups |
-| [Extending](https://octabits-io.github.io/octaflow/extending/interfaces/) | custom stores, dispatchers and gates |
-| [API reference](https://octabits-io.github.io/octaflow/reference/api/) | every export, by entry point |
+| [Quick start](https://octaflow.octabits.io/start/quick-start/) | a runnable workflow in one file, no database |
+| [Concepts](https://octaflow.octabits.io/core/concepts/) | step, workflow, registry, store, dispatcher, engine, partition |
+| [Defining steps](https://octaflow.octabits.io/core/defining-steps/) | `defineStep` and its variants |
+| [Retry & timeout](https://octaflow.octabits.io/core/retry-and-timeout/) | attempt budgets, backoff, and how a failure is classified |
+| [Fan-out & map](https://octaflow.octabits.io/core/fan-out-and-map/) | one child step per item of a runtime list |
+| [Branching](https://octaflow.octabits.io/core/branching/) | `when` guards and join rules — if/else over a static DAG |
+| [Signals](https://octaflow.octabits.io/core/signals/) · [Sub-workflows](https://octaflow.octabits.io/core/sub-workflows/) · [Saga](https://octaflow.octabits.io/core/saga-compensation/) | suspend, nest, and roll back |
+| [Deadlines](https://octaflow.octabits.io/core/deadlines/) | budgets for a suspended step and for a whole run |
+| [Heartbeats](https://octaflow.octabits.io/core/heartbeats/) | liveness for long steps, and interrupting one that was cancelled |
+| [Postgres & pg-boss](https://octaflow.octabits.io/running/postgres-and-pg-boss/) | production wiring, workers, DLQ, cron |
+| [Cancellation & recovery](https://octaflow.octabits.io/running/cancellation-and-recovery/) | cancelling a run, sweeping steps a crash left behind, and retrying a failed run |
+| [Observability](https://octaflow.octabits.io/running/observability/) · [Live progress](https://octaflow.octabits.io/running/live-progress/) | lifecycle events, spans, and streaming them to a browser |
+| [The AI add-on](https://octaflow.octabits.io/extending/ai/) | token/cost capture, quota, usage rollups |
+| [Extending](https://octaflow.octabits.io/extending/interfaces/) | custom stores, dispatchers and gates |
+| [API reference](https://octaflow.octabits.io/reference/api/) | every export, by entry point |
 
 ---
 
@@ -270,8 +281,10 @@ Runnable, focused examples live in [`examples/`](./examples) — see [`examples/
 | 12 | `12-postgres-pgboss-production.ts` | full pg store + gate + event sink + pg-boss + cron |
 | 13 | `13-ai-workflow.ts` | AI add-on (instrumented model + cost) |
 | 14 | `14-live-progress.ts` | `FlowObserver` → SSE fan-out (build your own dashboard) |
+| 15 | `15-conditional-branching.ts` | `when` guards + a `join: 'any'` convergence |
+| 16 | `16-deadlines-and-retry.ts` | wait deadlines, run deadlines, `retryWorkflow`, heartbeats |
 
-The in-memory examples (01–11) share a small driver, [`examples/runtime.ts`](./examples/runtime.ts),
+The in-memory examples (01–11, 14–16) share a small driver, [`examples/runtime.ts`](./examples/runtime.ts),
 that builds an engine over the in-memory store and an in-process queue you drain.
 
 ---

package/dist/ai/index.d.ts

@@ -1,6 +1,6 @@
-import { K as FlowErrorShape, T as RetryPolicy, h as TypedWorkflow, m as TypedStepContext, p as TypedStep, q as Result } from "../index-D_fOYfmf.js";
+import { E as RetryPolicy, g as TypedWorkflow, h as TypedStepContext, m as TypedStep, nt as Result, tt as FlowErrorShape } from "../index-BURAYZui.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-CDRFQZbT.js";
+import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-BdxIcc92.js";
 import { z } from "zod";
 import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
 //#region src/ai/instrumented-model.d.ts

package/dist/ai/index.js

@@ -1,4 +1,4 @@
-import { S as ok, b as noopLogger, f as defineStep, l as buildWorkflow, x as err } from "../core-ERYGlYsS.js";
+import { S as ok, b as noopLogger, f as defineStep, l as buildWorkflow, x as err } from "../core-DNWPwFaE.js";
 import { wrapEmbeddingModel, wrapLanguageModel } from "ai";
 //#region src/ai/instrumented-model.ts
 function createUsageAccumulator() {

package/dist/{core-ERYGlYsS.js → core-DNWPwFaE.js}

@@ -171,33 +171,61 @@ const emptyObjectSchema = z.object({});
 * Validation errors are non-retryable (a schema mismatch is a programming error).
 */
 function defineStep(config) {
-	const { type, workflowInputSchema, outputSchema, dependencies, handler, retry, isRetryable, timeoutMs, delayMs, waitForEvent } = config;
+	const { type, workflowInputSchema, outputSchema, dependencies, handler, retry, isRetryable, timeoutMs, delayMs, waitForEvent, join } = config;
 	const deps = dependencies ?? {};
-	const wrappedHandler = async (ctx) => {
-		try {
-			const inputResult = workflowInputSchema.safeParse(ctx.workflowInput);
-			if (!inputResult.success) return {
+	/**
+	* Classify a thrown error. Precedence: an explicit marker on the error
+	* (following `cause`), then this step's predicate, then the default
+	* classifier. `retryableFrom` records which one answered, so the engine's
+	* `defaultRetryable` can override a guess without overriding a decision
+	* someone actually made.
+	*/
+	const toStepError = (error) => {
+		const message = error instanceof Error ? error.message : "Unknown step error";
+		const marked = explicitRetryability(error);
+		return {
+			key: "step_error",
+			message,
+			retryable: marked ?? (isRetryable ? isRetryable(error) : isRetryableError(error)),
+			retryableFrom: marked !== void 0 ? "explicit" : isRetryable ? "predicate" : "heuristic"
+		};
+	};
+	/**
+	* Phases 1–3 of the pipeline: validate the workflow input, validate each
+	* dependency's output, and assemble the typed context. Shared so the `when`
+	* guard decides on exactly the same values the handler would receive.
+	*/
+	const buildTypedContext = (ctx) => {
+		const inputResult = workflowInputSchema.safeParse(ctx.workflowInput);
+		if (!inputResult.success) return {
+			ok: false,
+			error: {
+				key: "step_error",
+				message: `[${type}] Invalid workflow input: ${inputResult.error.message}`,
+				retryable: false
+			}
+		};
+		const parsedDeps = {};
+		for (const [depKey, depStep] of Object.entries(deps)) {
+			const raw = ctx.dependencyOutputs[depKey];
+			if (join === "any" && raw === void 0) {
+				parsedDeps[depKey] = void 0;
+				continue;
+			}
+			const depResult = depStep.outputSchema.safeParse(raw);
+			if (!depResult.success) return {
 				ok: false,
 				error: {
 					key: "step_error",
-					message: `[${type}] Invalid workflow input: ${inputResult.error.message}`,
+					message: `[${type}] Invalid dependency output '${depKey}': ${depResult.error.message}`,
 					retryable: false
 				}
 			};
-			const parsedDeps = {};
-			for (const [depKey, depStep] of Object.entries(deps)) {
-				const depResult = depStep.outputSchema.safeParse(ctx.dependencyOutputs[depKey]);
-				if (!depResult.success) return {
-					ok: false,
-					error: {
-						key: "step_error",
-						message: `[${type}] Invalid dependency output '${depKey}': ${depResult.error.message}`,
-						retryable: false
-					}
-				};
-				parsedDeps[depKey] = depResult.data;
-			}
-			const typedCtx = {
+			parsedDeps[depKey] = depResult.data;
+		}
+		return {
+			ok: true,
+			value: {
 				workflowId: ctx.workflowId,
 				stepId: ctx.stepId,
 				stepKey: ctx.stepKey,
@@ -206,9 +234,16 @@ function defineStep(config) {
 				stepInput: ctx.stepInput,
 				deps: parsedDeps,
 				signal: ctx.signal,
+				heartbeat: ctx.heartbeat,
 				context: ctx.context
-			};
-			const output = await handler(typedCtx);
+			}
+		};
+	};
+	const wrappedHandler = async (ctx) => {
+		try {
+			const built = buildTypedContext(ctx);
+			if (!built.ok) return built;
+			const output = await handler(built.value);
 			const outputResult = outputSchema.safeParse(output);
 			if (!outputResult.success) return {
 				ok: false,
@@ -223,19 +258,31 @@ function defineStep(config) {
 				value: outputResult.data
 			};
 		} catch (error) {
-			const message = error instanceof Error ? error.message : "Unknown step error";
-			const marked = explicitRetryability(error);
 			return {
 				ok: false,
-				error: {
-					key: "step_error",
-					message,
-					retryable: marked ?? (isRetryable ? isRetryable(error) : isRetryableError(error)),
-					retryableFrom: marked !== void 0 ? "explicit" : isRetryable ? "predicate" : "heuristic"
-				}
+				error: toStepError(error)
 			};
 		}
 	};
+	let wrappedCondition;
+	if (config.when) {
+		const when = config.when;
+		wrappedCondition = async (ctx) => {
+			try {
+				const built = buildTypedContext(ctx);
+				if (!built.ok) return built;
+				return {
+					ok: true,
+					value: await when(built.value) === true
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: toStepError(error)
+				};
+			}
+		};
+	}
 	let wrappedCompensate;
 	if (config.compensate) {
 		const compensate = config.compensate;
@@ -256,6 +303,7 @@ function defineStep(config) {
 				stepInput: ctx.stepInput,
 				deps: parsedDeps,
 				signal: ctx.signal,
+				heartbeat: ctx.heartbeat,
 				context: ctx.context,
 				output: out.success ? out.data : ctx.output
 			});
@@ -269,9 +317,14 @@ function defineStep(config) {
 		handler: wrappedHandler,
 		retry,
 		timeoutMs,
+		onTimeout: config.onTimeout,
+		heartbeatTimeoutMs: config.heartbeatTimeoutMs,
+		heartbeat: config.heartbeat,
 		delayMs,
 		waitForEvent,
-		compensate: wrappedCompensate
+		compensate: wrappedCompensate,
+		condition: wrappedCondition,
+		join
 	};
 }
 /**
@@ -281,6 +334,21 @@ function defineStep(config) {
 * (validated by dependents against `outputSchema`), then the DAG advances.
 *
 * Use for human-in-the-loop approvals, webhooks, or any async external dependency.
+*
+* Give it a `timeoutMs` so the wait cannot last forever. What the expiry does is
+* `onTimeout`'s call: `'fail'` (the default) ends the run, while `{ output }`
+* completes the step with a stand-in answer and lets the DAG carry on — which,
+* paired with a `when` guard downstream, is how "approve within 48 hours,
+* otherwise escalate" is expressed:
+*
+* ```ts
+* const approval = defineWaitStep({
+*   type: 'await-approval',
+*   outputSchema: z.object({ approved: z.boolean() }),
+*   timeoutMs: 48 * 60 * 60 * 1000,
+*   onTimeout: { output: { approved: false } },
+* });
+* ```
 */
 function defineWaitStep(config) {
 	return defineStep({
@@ -289,6 +357,10 @@ function defineWaitStep(config) {
 		outputSchema: config.outputSchema,
 		dependencies: config.dependencies,
 		waitForEvent: true,
+		timeoutMs: config.timeoutMs,
+		onTimeout: config.onTimeout,
+		when: config.when,
+		join: config.join,
 		handler: async () => ({})
 	});
 }
@@ -308,6 +380,7 @@ function defineMapStep(config) {
 		workflowInputSchema: config.workflowInputSchema,
 		outputSchema: z.object({ items: z.array(z.unknown()) }),
 		dependencies: config.dependencies,
+		when: config.when,
 		handler: async (ctx) => ({ items: await config.items(ctx) })
 	});
 	const child = defineStep({
@@ -317,6 +390,7 @@ function defineMapStep(config) {
 		retry: config.itemRetry,
 		isRetryable: config.itemIsRetryable,
 		timeoutMs: config.itemTimeoutMs,
+		heartbeatTimeoutMs: config.itemHeartbeatTimeoutMs,
 		handler: async (ctx) => config.each(ctx.stepInput.item, {
 			index: Number(ctx.stepInput.index ?? 0),
 			context: ctx.context,
@@ -333,7 +407,8 @@ function defineMapStep(config) {
 			type: childType,
 			handler: child.handler,
 			retry: child.retry,
-			timeoutMs: child.timeoutMs
+			timeoutMs: child.timeoutMs,
+			heartbeatTimeoutMs: child.heartbeatTimeoutMs
 		}
 	};
 }
@@ -355,6 +430,7 @@ function defineSubWorkflowStep(config) {
 			workflowInputSchema: config.workflowInputSchema,
 			outputSchema: recordSchema,
 			dependencies: config.dependencies,
+			when: config.when,
 			handler: async (ctx) => config.input(ctx)
 		}),
 		outputSchema: config.outputSchema ?? recordSchema,
@@ -409,18 +485,24 @@ function buildWorkflow(config) {
 				registry.register(step.type, step.handler, {
 					retry: step.retry,
 					timeoutMs: step.timeoutMs,
+					onTimeout: step.onTimeout,
+					heartbeatTimeoutMs: step.heartbeatTimeoutMs,
+					heartbeat: step.heartbeat,
 					delayMs: step.delayMs,
 					waitForEvent: step.waitForEvent,
 					map: step.map,
 					childType: step.childType,
 					subWorkflowDefinition: step.subWorkflowDefinition,
-					compensate: step.compensate
+					compensate: step.compensate,
+					condition: step.condition,
+					join: step.join
 				});
 				if (step.childRegistration) {
 					const c = step.childRegistration;
 					registry.register(c.type, c.handler, {
 						retry: c.retry,
-						timeoutMs: c.timeoutMs
+						timeoutMs: c.timeoutMs,
+						heartbeatTimeoutMs: c.heartbeatTimeoutMs
 					});
 				}
 				if (step.subWorkflowRegister) step.subWorkflowRegister(registry);
@@ -441,7 +523,7 @@ function buildWorkflow(config) {
 * The engine's records ({@link WorkflowRecord}, {@link StepRecord}) are the
 * store's data model: they carry fields that must not leak onto a public API
 * (`partitionKey`, `idempotencyKey`, sub-workflow linkage, `metadata`, retry
-* `attempts`) and step statuses that are engine mechanics rather than display
+* `attempts`, heartbeats) and step statuses that are engine mechanics rather than display
 * states. Serving them verbatim also couples the consumer's API contract to
 * flow's record shape. This module owns the boundary instead:
 *
@@ -531,8 +613,8 @@ const PUBLIC_WORKFLOW_SCHEMA = z.object({
 });
 /**
 * Project a step record to its public view. Drops `workflowId` (redundant
-* under the parent), `metadata`, `attempts`, and `parentStepId`; folds the
-* status.
+* under the parent), `metadata`, `attempts`, `heartbeatAt`, and `parentStepId`;
+* folds the status.
 */
 function toPublicStep(step) {
 	return {

package/dist/{dispatcher-CnMTwfCc.d.ts → dispatcher-Cbb-KjY_.d.ts}

@@ -1,11 +1,24 @@
-import { F as StepId, K as FlowErrorShape, V as WorkflowId, q as Result } from "./index-D_fOYfmf.js";
+import { L as StepId, W as WorkflowId, nt as Result, tt as FlowErrorShape } from "./index-BURAYZui.js";
 //#region src/core/dispatcher.d.ts
+/**
+ * What a step job is for. A queue carries two kinds of work for a step, and
+ * they differ only in this field:
+ *
+ * - `'execute'` (default) — run the step. Every job before wait deadlines
+ *   existed was this, which is why it is also what a payload without a `kind`
+ *   means: an in-flight job enqueued by an older version still routes correctly.
+ * - `'timeout'` — the step's wait budget has elapsed; settle it if it is still
+ *   suspended. Delivered by the same durable delay that powers a sleep step.
+ */
+type DispatchKind = 'execute' | 'timeout';
 /** Payload handed to the dispatcher to schedule a single step for execution. */
 interface DispatchStepPayload {
   workflowId: WorkflowId;
   stepId: StepId;
   stepKey: string;
   stepType: string;
+  /** Defaults to `'execute'` when absent. */
+  kind?: DispatchKind;
 }
 interface EnqueueOptions {
   /**
@@ -34,4 +47,4 @@ interface Dispatcher {
   enqueueStepIn?(handle: unknown, payload: DispatchStepPayload, options?: EnqueueOptions): Promise<Result<void, FlowErrorShape>>;
 }
 //#endregion
-export { Dispatcher as n, EnqueueOptions as r, DispatchStepPayload as t };
+export { EnqueueOptions as i, DispatchStepPayload as n, Dispatcher as r, DispatchKind as t };

package/dist/dispatcher-pgboss/index.d.ts

@@ -1,13 +1,13 @@
-import "../index-D_fOYfmf.js";
+import "../index-BURAYZui.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { n as Dispatcher } from "../dispatcher-CnMTwfCc.js";
+import { r as Dispatcher } from "../dispatcher-Cbb-KjY_.js";
 import { z } from "zod";
 import { PgBoss } from "pg-boss";
 //#region src/dispatcher-pgboss/payload.d.ts
 /**
  * The wire payload for a step job. It is the flow-core `DispatchStepPayload`
  * plus the `partitionKey` — the worker needs the partition to reconstruct a
- * partition-scoped engine before calling `executeStep`.
+ * partition-scoped engine before handing the job to `engine.handleStepJob`.
  */
 declare const WIRE_STEP_PAYLOAD_SCHEMA: z.ZodObject<{
   partitionKey: z.ZodString;
@@ -15,6 +15,10 @@ declare const WIRE_STEP_PAYLOAD_SCHEMA: z.ZodObject<{
   stepId: z.ZodNumber;
   stepKey: z.ZodString;
   stepType: z.ZodString;
+  kind: z.ZodDefault<z.ZodEnum<{
+    execute: "execute";
+    timeout: "timeout";
+  }>>;
 }, z.core.$strip>;
 type WireStepPayload = z.infer<typeof WIRE_STEP_PAYLOAD_SCHEMA>;
 interface StepQueueConfig {

package/dist/dispatcher-pgboss/index.js

@@ -3,14 +3,20 @@ import { z } from "zod";
 /**
 * The wire payload for a step job. It is the flow-core `DispatchStepPayload`
 * plus the `partitionKey` — the worker needs the partition to reconstruct a
-* partition-scoped engine before calling `executeStep`.
+* partition-scoped engine before handing the job to `engine.handleStepJob`.
 */
 const WIRE_STEP_PAYLOAD_SCHEMA = z.object({
 	partitionKey: z.string().min(1),
 	workflowId: z.number().int().positive(),
 	stepId: z.number().int().positive(),
 	stepKey: z.string().min(1),
-	stepType: z.string().min(1)
+	stepType: z.string().min(1),
+	/**
+	* What the job asks for: run the step, or settle it because its wait deadline
+	* elapsed. Defaulted rather than required, so a job enqueued before wait
+	* deadlines existed still parses — and still means "run the step".
+	*/
+	kind: z.enum(["execute", "timeout"]).default("execute")
 });
 const DEFAULT_STEP_QUEUE_CONFIG = {
 	retryLimit: 2,
@@ -100,8 +106,9 @@ function createPgBossDispatcher(deps) {
 	async function send(payload, options, handle) {
 		try {
 			const wire = {
-				partitionKey,
-				...payload
+				kind: "execute",
+				...payload,
+				partitionKey
 			};
 			const parsed = WIRE_STEP_PAYLOAD_SCHEMA.safeParse(wire);
 			if (!parsed.success) return {

package/dist/{hooks-CDRFQZbT.d.ts → hooks-BdxIcc92.d.ts}

@@ -1,4 +1,4 @@
-import { B as WorkflowDefinition, E as StartOptions, F as StepId, I as StepRecord, K as FlowErrorShape, U as WorkflowRecord, V as WorkflowId, q as Result } from "./index-D_fOYfmf.js";
+import { D as StartOptions, L as StepId, R as StepRecord, U as WorkflowDefinition, W as WorkflowId, nt as Result, q as WorkflowRecord, tt as FlowErrorShape } from "./index-BURAYZui.js";
 //#region src/core/hooks.d.ts
 interface BeforeStartArgs {
   definition: WorkflowDefinition;