octaflow 0.17.1 → 0.17.2

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.1",
+  "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",