octaflow 0.17.0 → 0.17.2

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/octabits-io/octaflow/actions/workflows/ci.yml/badge.svg)](https://github.com/octabits-io/octaflow/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/octaflow.svg)](https://www.npmjs.com/package/octaflow)
-[![docs](https://img.shields.io/badge/docs-octabits--io.github.io%2Fflow-16794a.svg)](https://octabits-io.github.io/octaflow/)
+[![docs](https://img.shields.io/badge/docs-octaflow.octabits.io-16794a.svg)](https://octaflow.octabits.io/)
 [![license](https://img.shields.io/npm/l/octaflow.svg)](./LICENSE)
 [![types](https://img.shields.io/badge/types-included-blue.svg)](https://www.npmjs.com/package/octaflow)
 
@@ -14,12 +14,12 @@ restart. There is
 no workflow server to operate, no control plane, and no vendor — it's a library you import,
 not a platform you adopt.
 
-### 📖 [Read the docs →](https://octabits-io.github.io/octaflow/)
+### 📖 [Read the docs →](https://octaflow.octabits.io/)
 
-[Quick start](https://octabits-io.github.io/octaflow/start/quick-start/) ·
-[Concepts](https://octabits-io.github.io/octaflow/core/concepts/) ·
-[Postgres & pg-boss](https://octabits-io.github.io/octaflow/running/postgres-and-pg-boss/) ·
-[API reference](https://octabits-io.github.io/octaflow/reference/api/)
+[Quick start](https://octaflow.octabits.io/start/quick-start/) ·
+[Concepts](https://octaflow.octabits.io/core/concepts/) ·
+[Postgres & pg-boss](https://octaflow.octabits.io/running/postgres-and-pg-boss/) ·
+[API reference](https://octaflow.octabits.io/reference/api/)
 
 ```ts
 const wf = buildWorkflow({
@@ -73,7 +73,7 @@ fails and its completed steps roll back in reverse.
   <img src="./docs/demo.svg" alt="Terminal trace of a publishing pipeline: parallel fan-out over locales and images with a concurrency cap, a retried step, a sub-workflow, a suspend-and-resume on an external event with a deadline armed, a durable sleep, a skipped branch converging on a join, then a saga rollback in reverse order" width="760">
 </p>
 
-Every line is an engine transition emitted through the [`FlowObserver`](https://octabits-io.github.io/octaflow/running/observability/) seam —
+Every line is an engine transition emitted through the [`FlowObserver`](https://octaflow.octabits.io/running/observability/) seam —
 the same one you'd point at OpenTelemetry or an events table — not a `console.log` in a handler.
 
 ```bash
@@ -106,7 +106,7 @@ workflow is expressed**.
 | **Model** | declarative — a static DAG value | imperative workflow code | imperative step functions | imperative tasks | job queue; flows are **trees** |
 | **Fan-in / diamond deps** | yes | yes | yes | yes | no — a job can't be shared by two branches |
 | **Inspect before running** | yes — the DAG is a value | no — the graph is the execution trace | no | no | yes — the flow tree is data |
-| **Web dashboard** | **none** — [build one](https://octabits-io.github.io/octaflow/running/live-progress/) | yes | yes | yes | via third-party UIs |
+| **Web dashboard** | **none** — [build one](https://octaflow.octabits.io/running/live-progress/) | yes | yes | yes | via third-party UIs |
 | **Languages** | TypeScript | polyglot SDKs | TS, Python, Go, Kotlin | TS | Node (+ ports) |
 | **Maturity** | **pre-1.0** | mature | mature | mature | mature, widely deployed |
 
@@ -120,14 +120,14 @@ that the others have earned.
 Reach for something else if:
 
 - **Your control flow is genuinely dynamic.** A declarative DAG is fixed at definition time.
-  Flow softens this 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
+  Flow softens this a lot — [`when` guards and joins](https://octaflow.octabits.io/core/branching/) (if/else over a static graph),
+  [`defineMapStep`](https://octaflow.octabits.io/core/fan-out-and-map/) (runtime-sized fan-out),
+  [sub-workflows](https://octaflow.octabits.io/core/sub-workflows/), and [`waitForEvent`](https://octaflow.octabits.io/core/signals/) — but the
   set of steps is still fixed up front. If your process is "**loop** until a human approves,
   branching on whatever they typed," an imperative durable function will express it more
   naturally: Flow can pick a branch, not invent a step.
 - **You want a UI out of the box.** Flow ships a wire-safe projection
-  ([`toPublicWorkflow`](https://octabits-io.github.io/octaflow/extending/http/)) and lifecycle events, not a
+  ([`toPublicWorkflow`](https://octaflow.octabits.io/extending/http/)) and lifecycle events, not a
   dashboard. You build it.
 - **You need non-TypeScript workers.** The DAG and its schemas are TypeScript values.
 - **You can't run Postgres**, or you need throughput past what a Postgres-backed queue gives you.
@@ -239,25 +239,25 @@ pnpm add ai @ai-sdk/provider
 ## Documentation
 
 Full docs — concepts, every feature, production wiring and the API reference — live at
-**[octabits-io.github.io/octaflow](https://octabits-io.github.io/octaflow/)**.
+**[octaflow.octabits.io](https://octaflow.octabits.io/)**.
 
 | | |
 |---|---|
-| [Quick start](https://octabits-io.github.io/octaflow/start/quick-start/) | a runnable workflow in one file, no database |
-| [Concepts](https://octabits-io.github.io/octaflow/core/concepts/) | step, workflow, registry, store, dispatcher, engine, partition |
-| [Defining steps](https://octabits-io.github.io/octaflow/core/defining-steps/) | `defineStep` and its variants |
-| [Retry & timeout](https://octabits-io.github.io/octaflow/core/retry-and-timeout/) | attempt budgets, backoff, and how a failure is classified |
-| [Fan-out & map](https://octabits-io.github.io/octaflow/core/fan-out-and-map/) | one child step per item of a runtime list |
-| [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 |
-| [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 |
+| [Quick start](https://octaflow.octabits.io/start/quick-start/) | a runnable workflow in one file, no database |
+| [Concepts](https://octaflow.octabits.io/core/concepts/) | step, workflow, registry, store, dispatcher, engine, partition |
+| [Defining steps](https://octaflow.octabits.io/core/defining-steps/) | `defineStep` and its variants |
+| [Retry & timeout](https://octaflow.octabits.io/core/retry-and-timeout/) | attempt budgets, backoff, and how a failure is classified |
+| [Fan-out & map](https://octaflow.octabits.io/core/fan-out-and-map/) | one child step per item of a runtime list |
+| [Branching](https://octaflow.octabits.io/core/branching/) | `when` guards and join rules — if/else over a static DAG |
+| [Signals](https://octaflow.octabits.io/core/signals/) · [Sub-workflows](https://octaflow.octabits.io/core/sub-workflows/) · [Saga](https://octaflow.octabits.io/core/saga-compensation/) | suspend, nest, and roll back |
+| [Deadlines](https://octaflow.octabits.io/core/deadlines/) | budgets for a suspended step and for a whole run |
+| [Heartbeats](https://octaflow.octabits.io/core/heartbeats/) | liveness for long steps, and interrupting one that was cancelled |
+| [Postgres & pg-boss](https://octaflow.octabits.io/running/postgres-and-pg-boss/) | production wiring, workers, DLQ, cron |
+| [Cancellation & recovery](https://octaflow.octabits.io/running/cancellation-and-recovery/) | cancelling a run, sweeping steps a crash left behind, and retrying a failed run |
+| [Observability](https://octaflow.octabits.io/running/observability/) · [Live progress](https://octaflow.octabits.io/running/live-progress/) | lifecycle events, spans, and streaming them to a browser |
+| [The AI add-on](https://octaflow.octabits.io/extending/ai/) | token/cost capture, quota, usage rollups |
+| [Extending](https://octaflow.octabits.io/extending/interfaces/) | custom stores, dispatchers and gates |
+| [API reference](https://octaflow.octabits.io/reference/api/) | every export, by entry point |
 
 ---
 

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

@@ -34,6 +34,20 @@ interface EnqueueOptions {
  */
 interface Dispatcher {
   enqueueStep(payload: DispatchStepPayload, options?: EnqueueOptions): Promise<Result<void, FlowErrorShape>>;
+  /**
+   * **Optional capability.** Whatever the dispatcher must do *outside* a store
+   * transaction before it can enqueue inside one — queue DDL, warming a queue
+   * cache. The engine calls it once, before its first transactional dispatch,
+   * and never while a transaction is open.
+   *
+   * Why it exists: a dispatcher that lazily creates its queue on first enqueue
+   * does so on its own connection. On a multi-connection database that merely
+   * costs a second connection; on a single-connection database (an embedded
+   * PGlite) it deadlocks — the transaction holds the only connection and waits
+   * for a query that waits for the transaction. `prepare` moves that work to
+   * where no transaction is open.
+   */
+  prepare?(): 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.

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

@@ -1,6 +1,6 @@
 import "../index-BURAYZui.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { r as Dispatcher } from "../dispatcher-Cbb-KjY_.js";
+import { r as Dispatcher } from "../dispatcher-g7Ct0J6w.js";
 import { z } from "zod";
 import { PgBoss } from "pg-boss";
 //#region src/dispatcher-pgboss/payload.d.ts
@@ -68,8 +68,15 @@ declare function resolveStartIdempotencyKey(payload: WireStartPayload, jobId: st
 //#endregion
 //#region src/dispatcher-pgboss/queue.d.ts
 /**
- * Create the step queue and its dead-letter queue (idempotent). Call once at
- * startup; the dispatcher also calls it lazily on first enqueue.
+ * Create the step queue and its dead-letter queue if they do not exist. Call
+ * once at startup; the dispatcher also runs it from `prepare` and lazily on a
+ * plain first enqueue.
+ *
+ * Only what is missing is created: pg-boss's `createQueue` evicts the queue's
+ * entry from its per-instance cache, and a `send` that misses that cache reads
+ * the queue on pg-boss's *own* connection — inside a store transaction on a
+ * single-connection database that is a deadlock. An existing queue is left
+ * alone, cache entry and all.
  */
 declare function ensureStepQueue(boss: PgBoss, queueName: string, config?: StepQueueConfig): Promise<void>;
 interface PgBossDispatcherDeps {

package/dist/dispatcher-pgboss/index.js

@@ -57,8 +57,15 @@ function dlqName(queueName) {
 	return `${queueName}-dlq`;
 }
 /**
-* Create the step queue and its dead-letter queue (idempotent). Call once at
-* startup; the dispatcher also calls it lazily on first enqueue.
+* Create the step queue and its dead-letter queue if they do not exist. Call
+* once at startup; the dispatcher also runs it from `prepare` and lazily on a
+* plain first enqueue.
+*
+* Only what is missing is created: pg-boss's `createQueue` evicts the queue's
+* entry from its per-instance cache, and a `send` that misses that cache reads
+* the queue on pg-boss's *own* connection — inside a store transaction on a
+* single-connection database that is a deadlock. An existing queue is left
+* alone, cache entry and all.
 */
 async function ensureStepQueue(boss, queueName, config = {}) {
 	const cfg = {
@@ -70,12 +77,12 @@ async function ensureStepQueue(boss, queueName, config = {}) {
 		if (error instanceof Error && error.message.includes("already exists")) return;
 		throw error;
 	};
-	try {
+	if (!await boss.getQueue(dlq)) try {
 		await boss.createQueue(dlq, { retryLimit: 0 });
 	} catch (e) {
 		swallowExists(e);
 	}
-	try {
+	if (!await boss.getQueue(queueName)) try {
 		await boss.createQueue(queueName, {
 			retryLimit: cfg.retryLimit,
 			retryDelay: cfg.retryDelay,
@@ -86,6 +93,24 @@ async function ensureStepQueue(boss, queueName, config = {}) {
 		swallowExists(e);
 	}
 }
+/** A job id that cannot exist — see {@link fillQueueCache}. */
+const NIL_JOB_ID = "00000000-0000-0000-0000-000000000000";
+/**
+* pg-boss keeps a per-instance cache of queue rows and consults it on every
+* `send` — on a miss it reads the queue on its *own* connection, whatever `db`
+* the send was handed. `createQueue` evicts the entry rather than filling it,
+* and the `PgBoss` facade keeps the cache private. So after creating our queue
+* we fill the entry here, outside any transaction, through the one public call
+* that reads the queue via the cache and then changes nothing: cancelling a job
+* id that cannot exist. (A boss that does expose `getQueueCache` — a bare
+* manager — is asked directly.) Without this the first transactional send would
+* read on a second connection — a deadlock on a single-connection database.
+*/
+async function fillQueueCache(boss, queueName) {
+	const cache = boss.getQueueCache;
+	if (typeof cache === "function") await cache.call(boss, queueName);
+	else await boss.cancel(queueName, NIL_JOB_ID);
+}
 /** A flow-core `Dispatcher` backed by pg-boss. */
 function createPgBossDispatcher(deps) {
 	const { boss, queueName, partitionKey } = deps;
@@ -93,7 +118,23 @@ function createPgBossDispatcher(deps) {
 		...DEFAULT_STEP_QUEUE_CONFIG,
 		...deps.config
 	};
-	let ensured = false;
+	/**
+	* Queue DDL and cache warm, once. Memoised as a promise so concurrent first
+	* sends share it; cleared on failure so the next attempt retries. The engine
+	* calls this through `prepare` before its first transaction; a direct
+	* `enqueueStep` outside any transaction is free to trigger it lazily.
+	*/
+	let prepared = null;
+	function ensurePrepared() {
+		prepared ??= (async () => {
+			await ensureStepQueue(boss, queueName, cfg);
+			await fillQueueCache(boss, queueName);
+		})().catch((error) => {
+			prepared = null;
+			throw error;
+		});
+		return prepared;
+	}
 	/**
 	* Adapt flow's `SqlExecutor` to the shape pg-boss wants for a caller-supplied
 	* connection. The two are the same idea under different names.
@@ -118,10 +159,7 @@ function createPgBossDispatcher(deps) {
 					message: `Invalid step payload: ${parsed.error.message}`
 				}
 			};
-			if (!ensured) {
-				await ensureStepQueue(boss, queueName, cfg);
-				ensured = true;
-			}
+			await ensurePrepared();
 			const startAfter = options?.startAfterSeconds;
 			const db = handle === void 0 ? void 0 : asPgBossDb(handle);
 			if (handle !== void 0 && !db) return {
@@ -159,6 +197,24 @@ function createPgBossDispatcher(deps) {
 		}
 	}
 	return {
+		/** Queue DDL + cache fill, outside any transaction. See `Dispatcher.prepare`. */
+		async prepare() {
+			try {
+				await ensurePrepared();
+				return {
+					ok: true,
+					value: void 0
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: {
+						key: "queue_error",
+						message: error instanceof Error ? error.message : "Failed to prepare step queue"
+					}
+				};
+			}
+		},
 		enqueueStep: (payload, options) => send(payload, options),
 		/**
 		* Enqueue on the store's open transaction, so the job and the state change

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { $ as computeReadiness, A as StepConditionHandler, B as StepStatus, C as defineWaitStep, D as StartOptions, E as RetryPolicy, F as StepHandlerNotFoundError, G as WorkflowNotFoundError, H as WorkflowCreatedResult, I as StepHandlerRegistry, J as WorkflowStatus, K as WorkflowNotRetryableError, L as StepId, M as StepError, N as StepExecutionContext, O as StepCompensateHandler, P as StepHandler, Q as ReadinessPlan, R as StepRecord, S as defineSubWorkflowStep, T as InvalidWorkflowDefinitionError, U as WorkflowDefinition, V as WaitTimeoutPolicy, W as WorkflowId, X as JoinRule, Y as WorkflowWithSteps, Z as PlannedSkip, _ as WorkflowOutput, a as STEP_DISPLAY_STATUS, b as defineSleepStep, c as WORKFLOW_STATUS_SCHEMA, d as toPublicWorkflow, et as isTerminalStepStatus, f as StepDeps, g as TypedWorkflow, h as TypedStepContext, i as PublicWorkflowStep, it as ok, j as StepDefinition, k as StepCompensationContext, l as toDisplayStepStatus, m as TypedStep, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as Result, o as STEP_DISPLAY_STATUS_SCHEMA, p as StepOutput, q as WorkflowRecord, r as PublicWorkflow, rt as err, s as StepDisplayStatus, t as PUBLIC_WORKFLOW_SCHEMA, tt as FlowErrorShape, u as toPublicStep, v as buildWorkflow, w as FlowError, x as defineStep, y as defineMapStep, z as StepRegistration } from "./index-BURAYZui.js";
 import { n as Logger, r as noopLogger, t as LogAttributes } from "./logger-BCus3AOa.js";
 import { A as WorkflowStore, C as CreateWorkflowStep, D as ListWorkflowsFilters, E as FinishWorkflowParams, O as ReopenWorkflowParams, 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 TransactionalScope, 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-B5KgSJfF.js";
-import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-Cbb-KjY_.js";
+import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-g7Ct0J6w.js";
 import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-BdxIcc92.js";
 //#region src/core/registry.d.ts
 /**

package/dist/index.js

@@ -318,15 +318,34 @@ function createWorkflowEngine(deps) {
 	*/
 	const atomicDispatch = typeof store.runInTransaction === "function" && typeof dispatcher.enqueueStepIn === "function";
 	/**
+	* The dispatcher's one-time setup (`Dispatcher.prepare`), run before the first
+	* transaction opens and never inside one. Memoised as a promise so concurrent
+	* first dispatches share it; cleared on failure so the next attempt retries.
+	*/
+	let prepared = null;
+	function ensurePrepared() {
+		if (!dispatcher.prepare) return Promise.resolve();
+		prepared ??= dispatcher.prepare().then((result) => {
+			if (!result.ok) throw new Error(`Dispatcher failed to prepare: ${result.error.message}`);
+		}).catch((error) => {
+			prepared = null;
+			throw error;
+		});
+		return prepared;
+	}
+	/**
 	* 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.
+	* network call would hold a database transaction open while it does. The
+	* dispatcher's own setup is the same kind of thing — it runs before the
+	* transaction, not in it (see `Dispatcher.prepare`).
 	*/
 	async function withDispatchScope(fn) {
 		if (!atomicDispatch) return fn(void 0);
+		await ensurePrepared();
 		return store.runInTransaction((scope) => fn(scope));
 	}
 	const nowIso = () => now().toISOString();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "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",
@@ -44,7 +44,7 @@
     "type": "git",
     "url": "https://github.com/octabits-io/octaflow.git"
   },
-  "homepage": "https://octabits-io.github.io/octaflow/",
+  "homepage": "https://octaflow.octabits.io/",
   "bugs": {
     "url": "https://github.com/octabits-io/octaflow/issues"
   },
@@ -82,23 +82,23 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/provider": "^4.0.7",
+    "@ai-sdk/provider": "^4.0.9",
     "@changesets/changelog-github": "^1.0.0",
-    "@changesets/cli": "^3.0.0",
+    "@changesets/cli": "^3.0.1",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
     "@testcontainers/postgresql": "^12.1.0",
-    "@types/node": "^26.2.0",
-    "@types/pg": "^8.21.0",
-    "ai": "^7.0.66",
+    "@types/node": "^26.4.0",
+    "@types/pg": "^8.23.1",
+    "ai": "^7.0.87",
     "pg": "^8.23.0",
-    "pg-boss": "^12.27.0",
-    "simple-git-hooks": "^2.13.1",
+    "pg-boss": "^12.29.0",
+    "simple-git-hooks": "^2.14.0",
     "testcontainers": "^12.1.0",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10",
-    "zod": "^4.4.3"
+    "vitest": "^4.1.11",
+    "zod": "^4.5.4"
   },
   "scripts": {
     "build": "tsdown",