octaflow 0.14.0 → 0.15.0

package/README.md

@@ -104,7 +104,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 |
 

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

package/dist/dispatcher-pgboss/index.js

@@ -73,7 +73,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 +101,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 +135,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) {

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.15.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",