octaflow 0.15.0 → 0.17.0

package/README.md

@@ -9,7 +9,8 @@
 **Durable workflows for TypeScript that run on the Postgres you already have.**
 
 Declare a DAG of Zod-typed steps. The engine runs each step as soon as its dependencies
-complete, persists every transition, retries failures, and resumes after a crash. There is
+complete, persists every transition, retries failures, and picks up where it left off after a
+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.
 
@@ -64,11 +65,12 @@ 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 —
@@ -118,10 +120,12 @@ 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://octabits-io.github.io/octaflow/core/branching/) (if/else over a static graph),
+  [`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 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
   dashboard. You build it.
@@ -187,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 |
@@ -239,9 +248,13 @@ Full docs — concepts, every feature, production wiring and the API reference
 | [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 |
+| [Branching](https://octabits-io.github.io/octaflow/core/branching/) | `when` guards and join rules — if/else over a static DAG |
 | [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 |
+| [Deadlines](https://octabits-io.github.io/octaflow/core/deadlines/) | budgets for a suspended step and for a whole run |
+| [Heartbeats](https://octabits-io.github.io/octaflow/core/heartbeats/) | liveness for long steps, and interrupting one that was cancelled |
 | [Postgres & pg-boss](https://octabits-io.github.io/octaflow/running/postgres-and-pg-boss/) | production wiring, workers, DLQ, cron |
-| [Observability](https://octabits-io.github.io/octaflow/running/observability/) | lifecycle events and spans |
+| [Cancellation & recovery](https://octabits-io.github.io/octaflow/running/cancellation-and-recovery/) | cancelling a run, sweeping steps a crash left behind, and retrying a failed run |
+| [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 |
@@ -267,8 +280,11 @@ Runnable, focused examples live in [`examples/`](./examples) — see [`examples/
 | 11 | `11-observability.ts` | observer events + tracer spans |
 | 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 {
@@ -29,8 +33,15 @@ declare const DEFAULT_STEP_QUEUE_CONFIG: Required<StepQueueConfig>;
 /**
  * The wire payload for a scheduled (or ad-hoc) workflow **start**. Carries the
  * partition plus what `engine.startWorkflow` needs; the host resolves `workflowType`
- * to a definition. `idempotencyKey` is forwarded to the start so overlapping
- * cron ticks don't double-start.
+ * to a definition.
+ *
+ * Two mutually exclusive ways to ask for start idempotency, because a cron schedule
+ * stores its payload **once** and pg-boss redelivers that same payload on every tick:
+ *
+ * - `idempotencyKeyPrefix` — the usual choice. The start worker appends the job id,
+ *   so each tick gets a distinct key while a redelivery of the *same* tick reuses it.
+ * - `idempotencyKey` — used verbatim. On a schedule this means "start exactly one
+ *   workflow, ever"; every later tick returns the first one.
  */
 declare const WIRE_START_PAYLOAD_SCHEMA: z.ZodObject<{
   partitionKey: z.ZodString;
@@ -38,8 +49,22 @@ declare const WIRE_START_PAYLOAD_SCHEMA: z.ZodObject<{
   input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   entityRef: z.ZodOptional<z.ZodString>;
   idempotencyKey: z.ZodOptional<z.ZodString>;
+  idempotencyKeyPrefix: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type WireStartPayload = z.infer<typeof WIRE_START_PAYLOAD_SCHEMA>;
+/**
+ * What a {@link WireStartPayload} becomes at delivery time: the same fields, plus the
+ * pg-boss job id and the **resolved** `idempotencyKey` to hand `engine.startWorkflow`.
+ *
+ * `idempotencyKey` is verbatim when the payload set one, `${idempotencyKeyPrefix}:${jobId}`
+ * when it set a prefix, and `undefined` when it set neither.
+ */
+interface StartJobContext extends WireStartPayload {
+  /** pg-boss job id — unique per cron tick, stable across that job's retries. */
+  jobId: string;
+}
+/** Resolve the per-delivery idempotency key. Explicit key wins over a prefix. */
+declare function resolveStartIdempotencyKey(payload: WireStartPayload, jobId: string): string | undefined;
 //#endregion
 //#region src/dispatcher-pgboss/queue.d.ts
 /**
@@ -136,7 +161,20 @@ interface ScheduleStartInput {
   workflowType: string;
   input?: Record<string, unknown>;
   entityRef?: string;
-  /** Forwarded to the start so overlapping ticks don't double-start. */
+  /**
+   * Per-tick start idempotency. The start worker resolves this to
+   * `${idempotencyKeyPrefix}:${jobId}`, so each cron tick gets a distinct key while a
+   * redelivery of the same tick reuses it — the usual thing you want on a schedule.
+   */
+  idempotencyKeyPrefix?: string;
+  /**
+   * Verbatim start idempotency key.
+   *
+   * A schedule stores its payload **once**, so this same key rides every tick — and
+   * start keys never expire. On a cron schedule that means **exactly one workflow,
+   * ever**; every later tick returns the first one. That is occasionally what you
+   * want ("run this once and never again"); if it isn't, use `idempotencyKeyPrefix`.
+   */
   idempotencyKey?: string;
   /** Optional IANA time zone (default UTC). */
   tz?: string;
@@ -150,8 +188,20 @@ declare function createPgBossScheduler(deps: PgBossSchedulerDeps): {
   /** List the schedules registered on this queue. */
   list(): Promise<import("pg-boss").Schedule[]>;
 };
-/** Invoked for each start job — typically resolves the type and calls `engine.startWorkflow`. */
-type StartJobProcessor = (payload: WireStartPayload) => Promise<void>;
+/**
+ * Invoked for each start job — typically resolves the type and calls `engine.startWorkflow`.
+ *
+ * The context's `idempotencyKey` is already resolved for **this delivery** (see
+ * {@link resolveStartIdempotencyKey}), so forwarding it is the right default:
+ *
+ * ```ts
+ * await starter.start(async (job) => {
+ *   const wf = workflowsByType[job.workflowType];
+ *   await engine.startWorkflow(wf.definition, job.input, { idempotencyKey: job.idempotencyKey });
+ * });
+ * ```
+ */
+type StartJobProcessor = (payload: StartJobContext) => Promise<void>;
 interface PgBossStartWorkerDeps {
   boss: PgBoss;
   queueName: string;
@@ -167,4 +217,4 @@ declare function createPgBossStartWorker(deps: PgBossStartWorkerDeps): {
   stop: () => Promise<void>;
 };
 //#endregion
-export { DEFAULT_STEP_QUEUE_CONFIG, DlqProcessor, PgBossDispatcherDeps, PgBossDlqWorkerDeps, PgBossSchedulerDeps, PgBossStartWorkerDeps, PgBossStepWorkerDeps, PgBossStepWorkerOptions, ScheduleStartInput, StartJobProcessor, StepJobProcessor, StepQueueConfig, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, WireStartPayload, WireStepPayload, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue };
+export { DEFAULT_STEP_QUEUE_CONFIG, DlqProcessor, PgBossDispatcherDeps, PgBossDlqWorkerDeps, PgBossSchedulerDeps, PgBossStartWorkerDeps, PgBossStepWorkerDeps, PgBossStepWorkerOptions, ScheduleStartInput, StartJobContext, StartJobProcessor, StepJobProcessor, StepQueueConfig, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, WireStartPayload, WireStepPayload, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue, resolveStartIdempotencyKey };

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,
@@ -20,16 +26,31 @@ const DEFAULT_STEP_QUEUE_CONFIG = {
 /**
 * The wire payload for a scheduled (or ad-hoc) workflow **start**. Carries the
 * partition plus what `engine.startWorkflow` needs; the host resolves `workflowType`
-* to a definition. `idempotencyKey` is forwarded to the start so overlapping
-* cron ticks don't double-start.
+* to a definition.
+*
+* Two mutually exclusive ways to ask for start idempotency, because a cron schedule
+* stores its payload **once** and pg-boss redelivers that same payload on every tick:
+*
+* - `idempotencyKeyPrefix` — the usual choice. The start worker appends the job id,
+*   so each tick gets a distinct key while a redelivery of the *same* tick reuses it.
+* - `idempotencyKey` — used verbatim. On a schedule this means "start exactly one
+*   workflow, ever"; every later tick returns the first one.
 */
 const WIRE_START_PAYLOAD_SCHEMA = z.object({
 	partitionKey: z.string().min(1),
 	workflowType: z.string().min(1),
 	input: z.record(z.string(), z.unknown()).default({}),
 	entityRef: z.string().optional(),
-	idempotencyKey: z.string().optional()
+	/** Verbatim dedup key — collapses *every* delivery, including future cron ticks. */
+	idempotencyKey: z.string().optional(),
+	/** Per-tick dedup: the start worker resolves this to `${prefix}:${jobId}`. */
+	idempotencyKeyPrefix: z.string().optional()
 });
+/** Resolve the per-delivery idempotency key. Explicit key wins over a prefix. */
+function resolveStartIdempotencyKey(payload, jobId) {
+	if (payload.idempotencyKey !== void 0) return payload.idempotencyKey;
+	if (payload.idempotencyKeyPrefix !== void 0) return `${payload.idempotencyKeyPrefix}:${jobId}`;
+}
 //#endregion
 //#region src/dispatcher-pgboss/queue.ts
 function dlqName(queueName) {
@@ -85,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 {
@@ -275,7 +297,8 @@ function createPgBossScheduler(deps) {
 				workflowType: input.workflowType,
 				input: input.input ?? {},
 				entityRef: input.entityRef,
-				idempotencyKey: input.idempotencyKey
+				idempotencyKey: input.idempotencyKey,
+				idempotencyKeyPrefix: input.idempotencyKeyPrefix
 			};
 			await boss.schedule(queueName, input.cron, payload, {
 				key: input.key,
@@ -309,7 +332,11 @@ function createPgBossStartWorker(deps) {
 					logger?.error("Invalid start payload", void 0, { jobId: job.id });
 					continue;
 				}
-				await process(parsed.data);
+				await process({
+					...parsed.data,
+					jobId: job.id,
+					idempotencyKey: resolveStartIdempotencyKey(parsed.data, job.id)
+				});
 			}
 		});
 	}
@@ -325,4 +352,4 @@ function createPgBossStartWorker(deps) {
 	};
 }
 //#endregion
-export { DEFAULT_STEP_QUEUE_CONFIG, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue };
+export { DEFAULT_STEP_QUEUE_CONFIG, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue, resolveStartIdempotencyKey };

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;