octaflow 0.14.0 → 0.16.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.
 
@@ -104,7 +105,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 on `toPublicWorkflow()` | yes | yes | yes | via third-party UIs |
+| **Web dashboard** | **none** — [build one](https://octabits-io.github.io/octaflow/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 |
 
@@ -241,7 +242,8 @@ Full docs — concepts, every feature, production wiring and the API reference
 | [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 |
-| [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, 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 |
@@ -267,6 +269,7 @@ 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) |
 
 The in-memory examples (01–11) 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/{dispatcher-BydjyrgU.d.ts → dispatcher-CnMTwfCc.d.ts}

@@ -21,6 +21,17 @@ interface EnqueueOptions {
  */
 interface Dispatcher {
   enqueueStep(payload: DispatchStepPayload, options?: EnqueueOptions): Promise<Result<void, FlowErrorShape>>;
+  /**
+   * **Optional capability.** Enqueue inside the caller's store transaction, so
+   * the job and the state change that produced it commit together.
+   *
+   * `handle` comes from `WorkflowStore.runInTransaction` and is opaque to the
+   * engine — the store and dispatcher agree on its meaning. Implement this only
+   * when the queue lives in the same database as the store (pg-boss on the same
+   * Postgres does; SQS or a separate Redis cannot). Without it the engine writes
+   * state and then enqueues, which is at-least-once with a crash window.
+   */
+  enqueueStepIn?(handle: unknown, payload: DispatchStepPayload, options?: EnqueueOptions): Promise<Result<void, FlowErrorShape>>;
 }
 //#endregion
 export { Dispatcher as n, EnqueueOptions as r, DispatchStepPayload as t };

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

@@ -1,6 +1,6 @@
 import "../index-D_fOYfmf.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { n as Dispatcher } from "../dispatcher-BydjyrgU.js";
+import { n as Dispatcher } from "../dispatcher-CnMTwfCc.js";
 import { z } from "zod";
 import { PgBoss } from "pg-boss";
 //#region src/dispatcher-pgboss/payload.d.ts
@@ -29,8 +29,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 +45,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 +157,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 +184,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 +213,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

@@ -20,16 +20,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) {
@@ -73,7 +88,16 @@ function createPgBossDispatcher(deps) {
 		...deps.config
 	};
 	let ensured = false;
-	return { async enqueueStep(payload, options) {
+	/**
+	* Adapt flow's `SqlExecutor` to the shape pg-boss wants for a caller-supplied
+	* connection. The two are the same idea under different names.
+	*/
+	function asPgBossDb(handle) {
+		const exec = handle;
+		if (!exec || typeof exec.query !== "function") return void 0;
+		return { executeSql: (text, values) => exec.query(text, values) };
+	}
+	async function send(payload, options, handle) {
 		try {
 			const wire = {
 				partitionKey,
@@ -92,11 +116,20 @@ function createPgBossDispatcher(deps) {
 				ensured = true;
 			}
 			const startAfter = options?.startAfterSeconds;
+			const db = handle === void 0 ? void 0 : asPgBossDb(handle);
+			if (handle !== void 0 && !db) return {
+				ok: false,
+				error: {
+					key: "queue_error",
+					message: "Transaction handle is not a SqlExecutor — is the store store-pg?"
+				}
+			};
 			if (!await boss.send(queueName, parsed.data, {
 				retryLimit: cfg.retryLimit,
 				retryDelay: cfg.retryDelay,
 				expireInSeconds: cfg.expireInSeconds,
-				...startAfter != null && startAfter > 0 ? { startAfter } : {}
+				...startAfter != null && startAfter > 0 ? { startAfter } : {},
+				...db ? { db } : {}
 			})) return {
 				ok: false,
 				error: {
@@ -117,7 +150,16 @@ function createPgBossDispatcher(deps) {
 				}
 			};
 		}
-	} };
+	}
+	return {
+		enqueueStep: (payload, options) => send(payload, options),
+		/**
+		* Enqueue on the store's open transaction, so the job and the state change
+		* that produced it commit together. `handle` is the transaction-bound
+		* `SqlExecutor` that `createWorkflowStore.runInTransaction` hands out.
+		*/
+		enqueueStepIn: (handle, payload, options) => send(payload, options, handle)
+	};
 }
 /** A pg-boss worker that drives `executeStep` for step jobs. */
 function createPgBossStepWorker(deps) {
@@ -248,7 +290,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,
@@ -282,7 +325,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)
+				});
 			}
 		});
 	}
@@ -298,4 +345,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/index.d.ts

@@ -1,7 +1,7 @@
 import { A as StepError, B as WorkflowDefinition, C as FlowError, D as StepCompensateHandler, E as StartOptions, F as StepId, G as WorkflowWithSteps, H as WorkflowNotFoundError, I as StepRecord, J as err, K as FlowErrorShape, L as StepRegistration, M as StepHandler, N as StepHandlerNotFoundError, O as StepCompensationContext, P as StepHandlerRegistry, R as StepStatus, S as defineWaitStep, T as RetryPolicy, U as WorkflowRecord, V as WorkflowId, W as WorkflowStatus, Y as ok, _ as buildWorkflow, a as STEP_DISPLAY_STATUS, b as defineStep, c as WORKFLOW_STATUS_SCHEMA, d as toPublicWorkflow, f as StepOutput, g as WorkflowOutput, h as TypedWorkflow, i as PublicWorkflowStep, j as StepExecutionContext, k as StepDefinition, l as toDisplayStepStatus, m as TypedStepContext, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as STEP_DISPLAY_STATUS_SCHEMA, p as TypedStep, q as Result, r as PublicWorkflow, s as StepDisplayStatus, t as PUBLIC_WORKFLOW_SCHEMA, u as toPublicStep, v as defineMapStep, w as InvalidWorkflowDefinitionError, x as defineSubWorkflowStep, y as defineSleepStep, z as WorkflowCreatedResult } from "./index-D_fOYfmf.js";
 import { n as Logger, r as noopLogger, t as LogAttributes } from "./logger-BCus3AOa.js";
-import { C as CreateWorkflowStep, D as ListWorkflowsFilters, E as FinishWorkflowParams, O as WorkflowStore, S as CreateWorkflowParams, T as FailStepParams, _ as StepGateDecision, a as FlowTracer, b as AddChildStep, c as RecordingTracer, d as noopObserver, f as noopTracer, g as StepGate, h as RateRule, i as FlowSpan, l as createRecordingObserver, m as InMemoryStepGateConfig, n as FlowEventType, o as RecordedSpan, p as ConcurrencyRule, r as FlowObserver, s as RecordingObserver, t as FlowEvent, u as createRecordingTracer, v as StepGateRequest, w as CreatedWorkflow, x as CompleteStepParams, y as createInMemoryStepGate } from "./observability-BsrvbhDr.js";
-import { n as Dispatcher, r as EnqueueOptions, t as DispatchStepPayload } from "./dispatcher-BydjyrgU.js";
+import { C as CreateWorkflowStep, D as ListWorkflowsFilters, E as FinishWorkflowParams, O as TransactionalScope, S as CreateWorkflowParams, T as FailStepParams, _ as StepGateDecision, a as FlowTracer, b as AddChildStep, c as RecordingTracer, d as noopObserver, f as noopTracer, g as StepGate, h as RateRule, i as FlowSpan, k as WorkflowStore, l as createRecordingObserver, m as InMemoryStepGateConfig, n as FlowEventType, o as RecordedSpan, p as ConcurrencyRule, r as FlowObserver, s as RecordingObserver, t as FlowEvent, u as createRecordingTracer, v as StepGateRequest, w as CreatedWorkflow, x as CompleteStepParams, y as createInMemoryStepGate } from "./observability-3tcmRwIw.js";
+import { n as Dispatcher, r as EnqueueOptions, t as DispatchStepPayload } from "./dispatcher-CnMTwfCc.js";
 import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-CDRFQZbT.js";
 //#region src/core/registry.d.ts
 /**
@@ -134,4 +134,4 @@ declare function createInMemoryWorkflowStore(partitionKey?: string): WorkflowSto
   };
 };
 //#endregion
-export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PublicWorkflow, PublicWorkflowStep, RateRule, RecordedSpan, RecordingObserver, RecordingTracer, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepDefinition, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowEngine, WorkflowEngineConfig, WorkflowEngineDeps, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStore, WorkflowWithSteps, buildWorkflow, createInMemoryStepGate, createInMemoryWorkflowStore, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, isRetryableError, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PublicWorkflow, PublicWorkflowStep, RateRule, RecordedSpan, RecordingObserver, RecordingTracer, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepDefinition, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowEngine, WorkflowEngineConfig, WorkflowEngineDeps, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStore, WorkflowWithSteps, buildWorkflow, createInMemoryStepGate, createInMemoryWorkflowStore, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, isRetryableError, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

package/dist/index.js

@@ -221,6 +221,26 @@ function createWorkflowEngine(deps) {
 	const stepExpirySeconds = deps.config?.stepExpirySeconds ?? 600;
 	const stuckStepBufferSeconds = deps.config?.stuckStepBufferSeconds ?? 300;
 	const defaultRetryable = deps.config?.defaultRetryable;
+	/**
+	* Both halves must opt in: the store has to offer a transaction and the
+	* dispatcher has to be able to enqueue inside it. When they do, a state change
+	* and the dispatches it unlocks commit atomically — there is no window in
+	* which a step is `pending` with no job behind it. When either cannot, the
+	* engine writes and then enqueues, exactly as before.
+	*/
+	const atomicDispatch = typeof store.runInTransaction === "function" && typeof dispatcher.enqueueStepIn === "function";
+	/**
+	* Run `fn` atomically when both halves support it, otherwise run it directly.
+	* `fn` receives the scope to write through — pass it to `dispatchReadyStep`.
+	*
+	* Only writes and enqueues belong in here. Anything that can run user code
+	* (saga compensation, hooks) must stay outside, or a rollback handler making a
+	* network call would hold a database transaction open while it does.
+	*/
+	async function withDispatchScope(fn) {
+		if (!atomicDispatch) return fn(void 0);
+		return store.runInTransaction((scope) => fn(scope));
+	}
 	const nowIso = () => now().toISOString();
 	/** Emit a run-history / metrics event. Guarded — a faulty observer never breaks a run. */
 	function emit(event) {
@@ -249,9 +269,10 @@ function createWorkflowEngine(deps) {
 	* and awaits `resumeStep`; everything else is enqueued (with any durable delay).
 	* Returns whether the step was enqueued.
 	*/
-	async function dispatchReadyStep(workflowId, stepId, stepKey, stepType) {
+	async function dispatchReadyStep(workflowId, stepId, stepKey, stepType, scope) {
+		const st = scope?.store ?? store;
 		if (isWaitStep(stepType)) {
-			await store.markStepWaiting(stepId);
+			await st.markStepWaiting(stepId);
 			logger.info("Step is waiting for an event", {
 				workflowId,
 				stepId,
@@ -266,12 +287,14 @@ function createWorkflowEngine(deps) {
 			});
 			return false;
 		}
-		const result = await dispatcher.enqueueStep({
+		const payload = {
 			workflowId,
 			stepId,
 			stepKey,
 			stepType
-		}, readyStepDelay(stepType));
+		};
+		const delay = readyStepDelay(stepType);
+		const result = scope ? await dispatcher.enqueueStepIn(scope.handle, payload, delay) : await dispatcher.enqueueStep(payload, delay);
 		if (!result.ok) {
 			logger.error("Failed to enqueue step", new Error(result.error.message), {
 				workflowId,
@@ -377,21 +400,38 @@ function createWorkflowEngine(deps) {
 			};
 		}
 		const { steps } = definition;
-		const created = await store.createWorkflow({
-			type: definition.type,
-			input,
-			entityRef: options?.entityRef,
-			metadata,
-			idempotencyKey: options?.idempotencyKey,
-			parentWorkflowId: options?.parentWorkflowId,
-			parentStepId: options?.parentStepId,
-			startedAt: nowIso(),
-			steps: steps.map((s) => ({
-				key: s.key,
-				type: s.type,
-				dependencies: s.dependencies ?? [],
-				input: s.input ?? null
-			}))
+		const { created, enqueuedStepKeys } = await withDispatchScope(async (scope) => {
+			const created = await (scope?.store ?? store).createWorkflow({
+				type: definition.type,
+				input,
+				entityRef: options?.entityRef,
+				metadata,
+				idempotencyKey: options?.idempotencyKey,
+				parentWorkflowId: options?.parentWorkflowId,
+				parentStepId: options?.parentStepId,
+				startedAt: nowIso(),
+				steps: steps.map((s) => ({
+					key: s.key,
+					type: s.type,
+					dependencies: s.dependencies ?? [],
+					input: s.input ?? null
+				}))
+			});
+			if (created.alreadyExisted) return {
+				created,
+				enqueuedStepKeys: []
+			};
+			const readySteps = steps.filter((s) => !s.dependencies || s.dependencies.length === 0);
+			const keys = [];
+			for (const readyStep of readySteps) {
+				const dbStep = created.steps.find((s) => s.key === readyStep.key);
+				if (!dbStep) continue;
+				if (await dispatchReadyStep(created.workflowId, dbStep.id, readyStep.key, readyStep.type, scope)) keys.push(readyStep.key);
+			}
+			return {
+				created,
+				enqueuedStepKeys: keys
+			};
 		});
 		const workflowId = created.workflowId;
 		if (created.alreadyExisted) {
@@ -413,13 +453,6 @@ function createWorkflowEngine(deps) {
 			workflowId,
 			workflowType: definition.type
 		});
-		const readySteps = steps.filter((s) => !s.dependencies || s.dependencies.length === 0);
-		const enqueuedStepKeys = [];
-		for (const readyStep of readySteps) {
-			const dbStep = created.steps.find((s) => s.key === readyStep.key);
-			if (!dbStep) continue;
-			if (await dispatchReadyStep(workflowId, dbStep.id, readyStep.key, readyStep.type)) enqueuedStepKeys.push(readyStep.key);
-		}
 		logger.info("Workflow started", {
 			workflowId,
 			type: definition.type,
@@ -468,6 +501,20 @@ function createWorkflowEngine(deps) {
 			}
 		};
 		if (step.status !== "pending") {
+			const workflowLive = workflow.status === "running" || workflow.status === "pending";
+			if (step.status === "completed" && workflowLive) {
+				logger.info("Re-driving advance for a redelivered completed step", {
+					workflowId,
+					stepId,
+					stepKey: step.key
+				});
+				if (step.parentStepId != null) await advanceAfterChildCompleted(workflowId, step);
+				else await advanceAfterStepCompleted(workflowId, stepId, step.output ?? {});
+				return {
+					ok: true,
+					value: void 0
+				};
+			}
 			logger.info("Skipping already-processed step", {
 				workflowId,
 				stepId,
@@ -791,32 +838,60 @@ function createWorkflowEngine(deps) {
 		};
 	}
 	async function onStepCompleted(workflowId, stepId, output) {
-		const completedAt = nowIso();
-		await store.completeStep({
-			workflowId,
-			stepId,
-			output,
-			completedAt
-		});
-		const keyedSteps = (await store.listSteps(workflowId)).filter((s) => s.parentStepId == null);
+		await finalizeAfterStepCompleted(workflowId, stepId, output, await withDispatchScope(async (scope) => {
+			await (scope?.store ?? store).completeStep({
+				workflowId,
+				stepId,
+				output,
+				completedAt: nowIso()
+			});
+			return dispatchNewlyReady(workflowId, stepId, scope);
+		}));
+	}
+	/**
+	* The readiness half of a completion, without the write. Split out so a
+	* redelivered job for an already-completed step can re-drive it — see the
+	* recovery branch in {@link executeStep}. Idempotent: dispatching a step that
+	* is already queued is harmless, because claiming it is atomic.
+	*/
+	async function advanceAfterStepCompleted(workflowId, stepId, output) {
+		await finalizeAfterStepCompleted(workflowId, stepId, output, await withDispatchScope((scope) => dispatchNewlyReady(workflowId, stepId, scope)));
+	}
+	/**
+	* Transactional half: read readiness and dispatch whatever just became ready.
+	* Contains only store writes and enqueues — never user code.
+	*/
+	async function dispatchNewlyReady(workflowId, stepId, scope) {
+		const keyedSteps = (await (scope?.store ?? store).listSteps(workflowId)).filter((s) => s.parentStepId == null);
 		const completedKeys = new Set(keyedSteps.filter((s) => s.status === "completed").map((s) => s.key));
 		const newlyReady = keyedSteps.filter((s) => {
 			if (s.status !== "pending") return false;
 			return (s.dependencies ?? []).every((dep) => completedKeys.has(dep));
 		});
-		for (const readyStep of newlyReady) await dispatchReadyStep(workflowId, readyStep.id, readyStep.key, readyStep.type);
+		for (const readyStep of newlyReady) await dispatchReadyStep(workflowId, readyStep.id, readyStep.key, readyStep.type, scope);
+		return {
+			keyedSteps,
+			newlyReadyCount: newlyReady.length
+		};
+	}
+	/**
+	* Non-transactional half: decide whether the workflow is now failed or done.
+	* Deliberately outside any transaction — the failure path runs saga
+	* compensation, i.e. user handlers that may do network I/O.
+	*/
+	async function finalizeAfterStepCompleted(workflowId, stepId, output, { keyedSteps, newlyReadyCount }) {
 		if (keyedSteps.some((s) => s.id !== stepId && s.status === "failed")) {
 			await checkWorkflowFailure(workflowId);
 			return;
 		}
-		if (keyedSteps.every((s) => s.id === stepId || s.status === "completed" || s.status === "skipped") && newlyReady.length === 0) {
+		if (keyedSteps.every((s) => s.id === stepId || s.status === "completed" || s.status === "skipped") && newlyReadyCount === 0) {
 			const aggregatedOutput = {};
 			for (const s of keyedSteps) if (s.status === "completed" || s.id === stepId) aggregatedOutput[s.key] = s.id === stepId ? output : s.output ?? null;
 			await store.finishWorkflow({
 				workflowId,
 				status: "completed",
 				output: aggregatedOutput,
-				completedAt
+				completedAt: nowIso()
 			});
 			logger.info("Workflow completed", { workflowId });
 			emit({
@@ -877,6 +952,10 @@ function createWorkflowEngine(deps) {
 			output,
 			completedAt: nowIso()
 		});
+		await advanceAfterChildCompleted(workflowId, childStep);
+	}
+	/** The aggregation half of a map child's completion, without the write. */
+	async function advanceAfterChildCompleted(workflowId, childStep) {
 		const parentId = childStep.parentStepId;
 		const children = await store.listChildSteps(parentId);
 		if (children.some((c) => c.status === "failed")) {

package/dist/{observability-BsrvbhDr.d.ts → observability-3tcmRwIw.d.ts}

@@ -61,6 +61,18 @@ interface ListWorkflowsFilters {
   entityRef?: string;
   limit?: number;
 }
+/**
+ * A store bound to an open transaction, plus an opaque handle a capable
+ * {@link Dispatcher} can join so a job and the state change that produced it
+ * commit together. Core never inspects `handle` — it belongs to the adapter
+ * pair (e.g. store-pg hands dispatcher-pgboss its transaction-bound executor).
+ */
+interface TransactionalScope {
+  /** A store whose writes go through the open transaction. */
+  store: WorkflowStore;
+  /** Opaque; pass to `Dispatcher.enqueueStepIn`. */
+  handle: unknown;
+}
 /**
  * Persistence boundary for the engine. Implementations are **partition-scoped at
  * construction** (e.g. bound to one tenant) — exactly like the engine — so methods
@@ -72,6 +84,19 @@ interface ListWorkflowsFilters {
  * are computed from `listSteps`.
  */
 interface WorkflowStore {
+  /**
+   * **Optional capability.** Run `fn` inside one store transaction.
+   *
+   * When the dispatcher also implements `enqueueStepIn`, the engine uses both so
+   * that a state change and the dispatches it unlocks commit atomically —
+   * closing the window where a crash leaves a step `pending` with no job behind
+   * it. A store that cannot offer this simply omits it, and the engine falls
+   * back to writing then enqueueing.
+   *
+   * Implementations MUST run every operation on `scope.store` inside the same
+   * transaction, and MUST roll back if `fn` throws.
+   */
+  runInTransaction?<T>(fn: (scope: TransactionalScope) => Promise<T>): Promise<T>;
   /** Create the workflow + all step rows atomically (transactional). */
   createWorkflow(params: CreateWorkflowParams): Promise<CreatedWorkflow>;
   getWorkflow(workflowId: WorkflowId): Promise<WorkflowRecord | null>;
@@ -246,4 +271,4 @@ interface RecordingTracer extends FlowTracer {
 }
 declare function createRecordingTracer(): RecordingTracer;
 //#endregion
-export { CreateWorkflowStep as C, ListWorkflowsFilters as D, FinishWorkflowParams as E, WorkflowStore as O, CreateWorkflowParams as S, FailStepParams as T, StepGateDecision as _, FlowTracer as a, AddChildStep as b, RecordingTracer as c, noopObserver as d, noopTracer as f, StepGate as g, RateRule as h, FlowSpan as i, createRecordingObserver as l, InMemoryStepGateConfig as m, FlowEventType as n, RecordedSpan as o, ConcurrencyRule as p, FlowObserver as r, RecordingObserver as s, FlowEvent as t, createRecordingTracer as u, StepGateRequest as v, CreatedWorkflow as w, CompleteStepParams as x, createInMemoryStepGate as y };
+export { CreateWorkflowStep as C, ListWorkflowsFilters as D, FinishWorkflowParams as E, TransactionalScope as O, CreateWorkflowParams as S, FailStepParams as T, StepGateDecision as _, FlowTracer as a, AddChildStep as b, RecordingTracer as c, noopObserver as d, noopTracer as f, StepGate as g, RateRule as h, FlowSpan as i, WorkflowStore as k, createRecordingObserver as l, InMemoryStepGateConfig as m, FlowEventType as n, RecordedSpan as o, ConcurrencyRule as p, FlowObserver as r, RecordingObserver as s, FlowEvent as t, createRecordingTracer as u, StepGateRequest as v, CreatedWorkflow as w, CompleteStepParams as x, createInMemoryStepGate as y };

package/dist/store-pg/index.d.ts

@@ -1,5 +1,5 @@
 import { V as WorkflowId } from "../index-D_fOYfmf.js";
-import { O as WorkflowStore, g as StepGate, h as RateRule, p as ConcurrencyRule, r as FlowObserver, t as FlowEvent } from "../observability-BsrvbhDr.js";
+import { g as StepGate, h as RateRule, k as WorkflowStore, p as ConcurrencyRule, r as FlowObserver, t as FlowEvent } from "../observability-3tcmRwIw.js";
 import { Pool } from "pg";
 //#region src/store-pg/ddl.d.ts
 /**

package/dist/store-pg/index.js

@@ -386,7 +386,27 @@ function createWorkflowStore(deps) {
 			cutoff
 		])).rows.map(mapStep);
 	}
+	/**
+	* Optional transaction capability (see `WorkflowStore.runInTransaction`). Hands
+	* back a store bound to the open transaction plus the transaction-bound
+	* executor as the opaque handle — `createPgBossDispatcher` knows how to enqueue
+	* through it, so a job and the state change that produced it commit together.
+	*
+	* Recursing is not supported (adapters never nest transactions); a nested call
+	* would reuse the same connection via `poolExecutor`, so it is simply the same
+	* transaction rather than a new one.
+	*/
+	async function runInTransaction(fn) {
+		return exec.transaction((tx) => fn({
+			store: createWorkflowStore({
+				...deps,
+				exec: tx
+			}),
+			handle: tx
+		}));
+	}
 	return {
+		runInTransaction,
 		createWorkflow,
 		getWorkflow,
 		getStep,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss, with an optional AI add-on (token/cost/quota). Layered single package.",
   "license": "MIT",
   "type": "module",