octaflow 0.21.0 → 0.22.0

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

@@ -1,2 +1,226 @@
-import { C as WireStartPayload, S as WIRE_STEP_PAYLOAD_SCHEMA, T as resolveStartIdempotencyKey, _ as ensureStepQueue, a as createPgBossScheduler, b as StepQueueConfig, c as DlqProcessor, d as PgBossStepWorkerDeps, f as PgBossStepWorkerOptions, g as createPgBossStepWorker, h as createPgBossDlqWorker, i as StartJobProcessor, l as PgBossDispatcherDeps, m as createPgBossDispatcher, n as PgBossStartWorkerDeps, o as createPgBossStartWorker, p as StepJobProcessor, r as ScheduleStartInput, s as ensureStartQueue, t as PgBossSchedulerDeps, u as PgBossDlqWorkerDeps, v as DEFAULT_STEP_QUEUE_CONFIG, w as WireStepPayload, x as WIRE_START_PAYLOAD_SCHEMA, y as StartJobContext } from "../scheduler-YCFUqjXf.js";
-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 };
+import "../index-BURAYZui.js";
+import { n as Logger } from "../logger-BCus3AOa.js";
+import { r as Dispatcher } from "../dispatcher-g7Ct0J6w.js";
+import { z } from "zod";
+import { PgBoss } from "pg-boss";
+//#region src/pg-boss/payload.d.ts
+/**
+ * The wire payload for a step job. It is the flow-core `DispatchStepPayload`
+ * plus the `partitionKey` — the worker needs the partition to reconstruct a
+ * partition-scoped engine before handing the job to `engine.handleStepJob`.
+ */
+export declare const WIRE_STEP_PAYLOAD_SCHEMA: z.ZodObject<{
+  partitionKey: z.ZodString;
+  workflowId: z.ZodNumber;
+  stepId: z.ZodNumber;
+  stepKey: z.ZodString;
+  stepType: z.ZodString;
+  kind: z.ZodDefault<z.ZodEnum<{
+    execute: "execute";
+    timeout: "timeout";
+  }>>;
+}, z.core.$strip>;
+export type WireStepPayload = z.infer<typeof WIRE_STEP_PAYLOAD_SCHEMA>;
+export interface StepQueueConfig {
+  /** Retries before a job is dead-lettered. Default 2. */
+  retryLimit?: number;
+  /** Seconds between retries. Default 30. */
+  retryDelay?: number;
+  /** Seconds before an in-flight job is considered expired. Default 600. */
+  expireInSeconds?: number;
+}
+export 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.
+ *
+ * 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.
+ */
+export declare const WIRE_START_PAYLOAD_SCHEMA: z.ZodObject<{
+  partitionKey: z.ZodString;
+  workflowType: z.ZodString;
+  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>;
+export 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.
+ */
+export 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. */
+export declare function resolveStartIdempotencyKey(payload: WireStartPayload, jobId: string): string | undefined;
+//#endregion
+//#region src/pg-boss/queue.d.ts
+/**
+ * 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.
+ */
+export declare function ensureStepQueue(boss: PgBoss, queueName: string, config?: StepQueueConfig): Promise<void>;
+export interface PgBossDispatcherDeps {
+  boss: PgBoss;
+  queueName: string;
+  /** Partition this dispatcher is bound to — stamped into every enqueued job. */
+  partitionKey: string;
+  config?: StepQueueConfig;
+}
+/** A flow-core `Dispatcher` backed by pg-boss. */
+export declare function createPgBossDispatcher(deps: PgBossDispatcherDeps): Dispatcher;
+export interface PgBossStepWorkerOptions {
+  /** Steps fetched per poll. Default 1. */
+  batchSize?: number;
+  /** Base poll interval in seconds (pg-boss minimum 0.5). Default: pg-boss's own. */
+  pollingIntervalSeconds?: number;
+  /**
+   * Poll interval used while pg-boss's LISTEN/NOTIFY is active for the queue, where
+   * polling is only a backstop. Ignored when notify is off or unavailable.
+   */
+  notifyPollingIntervalSeconds?: number;
+  /**
+   * Keep fetching with no delay while every fetch returns a full `batchSize` batch;
+   * the first short fetch ends the burst. Ignored when `batchSize` is 1.
+   *
+   * **Worth enabling for throughput.** Without it a worker spends most of its time
+   * waiting out the poll interval: it drains a batch in milliseconds, then sleeps.
+   * See the performance table in the README.
+   */
+  burstWhenBatchFull?: boolean;
+  /** Burst while the queue's cached ready count exceeds this. Reacts on pg-boss's stats cadence. */
+  burstWhenReadyExceeds?: number;
+  /**
+   * How many steps from one fetched batch run at a time. Default 1 (serial).
+   *
+   * Raising this only helps once the worker is not poll-bound — pair it with
+   * `burstWhenBatchFull`. Each in-flight step needs a store connection, so keep
+   * `concurrency × workers` within your Postgres pool and `max_connections`.
+   */
+  concurrency?: number;
+}
+export interface PgBossStepWorkerDeps {
+  boss: PgBoss;
+  queueName: string;
+  config?: StepQueueConfig;
+  logger?: Logger;
+  workerOptions?: PgBossStepWorkerOptions;
+}
+/** Handles a single step job. Reconstruct the partition-scoped engine and call
+ * `engine.executeStep(workflowId, stepId)`. Throw to trigger a pg-boss retry. */
+export type StepJobProcessor = (payload: WireStepPayload) => Promise<void>;
+/** A pg-boss worker that drives `executeStep` for step jobs. */
+export declare function createPgBossStepWorker(deps: PgBossStepWorkerDeps): {
+  start: (process: StepJobProcessor) => Promise<void>;
+  stop: () => Promise<void>;
+};
+export interface PgBossDlqWorkerDeps {
+  boss: PgBoss;
+  queueName: string;
+  logger?: Logger;
+  pollingIntervalSeconds?: number;
+}
+/** Invoked for a step job that exhausted all retries. Typically calls
+ * `engine.handleStepExhausted(workflowId, stepId, reason)`. */
+export type DlqProcessor = (payload: WireStepPayload) => Promise<void>;
+/** A pg-boss worker on the step queue's dead-letter queue. */
+export declare function createPgBossDlqWorker(deps: PgBossDlqWorkerDeps): {
+  start: (onDlq: DlqProcessor) => Promise<void>;
+  stop: () => Promise<void>;
+};
+//#endregion
+//#region src/pg-boss/scheduler.d.ts
+/** Create the start queue (idempotent). */
+export declare function ensureStartQueue(boss: PgBoss, queueName: string): Promise<void>;
+export interface PgBossSchedulerDeps {
+  boss: PgBoss;
+  /** Queue scheduled start jobs are sent to (and the start worker reads). */
+  queueName: string;
+  /** Partition stamped into every scheduled start payload. */
+  partitionKey: string;
+  logger?: Logger;
+}
+export interface ScheduleStartInput {
+  /** Unique key for this schedule within the queue (allows many crons per queue). */
+  key: string;
+  /** Cron expression (5- or 6-field). */
+  cron: string;
+  /** Workflow type to start (the host resolves it to a definition). */
+  workflowType: string;
+  input?: Record<string, unknown>;
+  entityRef?: string;
+  /**
+   * 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;
+}
+/** Registers cron schedules that enqueue workflow-start jobs. */
+export declare function createPgBossScheduler(deps: PgBossSchedulerDeps): {
+  /** Create or replace a cron schedule that starts a workflow. */
+  schedule(input: ScheduleStartInput): Promise<void>;
+  /** Remove a schedule by key. */
+  unschedule(key: string): Promise<void>;
+  /** 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`.
+ *
+ * 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 });
+ * });
+ * ```
+ */
+export type StartJobProcessor = (payload: StartJobContext) => Promise<void>;
+export interface PgBossStartWorkerDeps {
+  boss: PgBoss;
+  queueName: string;
+  logger?: Logger;
+  workerOptions?: {
+    batchSize?: number;
+    pollingIntervalSeconds?: number;
+  };
+}
+/** A pg-boss worker on the start queue that drives a host start callback. */
+export declare function createPgBossStartWorker(deps: PgBossStartWorkerDeps): {
+  start: (process: StartJobProcessor) => Promise<void>;
+  stop: () => Promise<void>;
+};
+//#endregion

package/dist/pg-boss/index.js

@@ -1,2 +1,411 @@
-import { a as createPgBossDlqWorker, c as DEFAULT_STEP_QUEUE_CONFIG, d as resolveStartIdempotencyKey, i as createPgBossDispatcher, l as WIRE_START_PAYLOAD_SCHEMA, n as createPgBossStartWorker, o as createPgBossStepWorker, r as ensureStartQueue, s as ensureStepQueue, t as createPgBossScheduler, u as WIRE_STEP_PAYLOAD_SCHEMA } from "../scheduler-CzQ1bY0V.js";
+import { z } from "zod";
+//#region src/pg-boss/payload.ts
+/**
+* The wire payload for a step job. It is the flow-core `DispatchStepPayload`
+* plus the `partitionKey` — the worker needs the partition to reconstruct a
+* partition-scoped engine before handing the job to `engine.handleStepJob`.
+*/
+const WIRE_STEP_PAYLOAD_SCHEMA = z.object({
+	partitionKey: z.string().min(1),
+	workflowId: z.number().int().positive(),
+	stepId: z.number().int().positive(),
+	stepKey: z.string().min(1),
+	stepType: z.string().min(1),
+	/**
+	* What the job asks for: run the step, or settle it because its wait deadline
+	* elapsed. Defaulted rather than required, so a job enqueued before wait
+	* deadlines existed still parses — and still means "run the step".
+	*/
+	kind: z.enum(["execute", "timeout"]).default("execute")
+});
+const DEFAULT_STEP_QUEUE_CONFIG = {
+	retryLimit: 2,
+	retryDelay: 30,
+	expireInSeconds: 600
+};
+/**
+* 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.
+*
+* 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(),
+	/** 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/pg-boss/queue.ts
+function dlqName(queueName) {
+	return `${queueName}-dlq`;
+}
+/**
+* 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 = {
+		...DEFAULT_STEP_QUEUE_CONFIG,
+		...config
+	};
+	const dlq = dlqName(queueName);
+	const swallowExists = (error) => {
+		if (error instanceof Error && error.message.includes("already exists")) return;
+		throw error;
+	};
+	if (!await boss.getQueue(dlq)) try {
+		await boss.createQueue(dlq, { retryLimit: 0 });
+	} catch (e) {
+		swallowExists(e);
+	}
+	if (!await boss.getQueue(queueName)) try {
+		await boss.createQueue(queueName, {
+			retryLimit: cfg.retryLimit,
+			retryDelay: cfg.retryDelay,
+			expireInSeconds: cfg.expireInSeconds,
+			deadLetter: dlq
+		});
+	} catch (e) {
+		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;
+	const cfg = {
+		...DEFAULT_STEP_QUEUE_CONFIG,
+		...deps.config
+	};
+	/**
+	* 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.
+	*/
+	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 = {
+				kind: "execute",
+				...payload,
+				partitionKey
+			};
+			const parsed = WIRE_STEP_PAYLOAD_SCHEMA.safeParse(wire);
+			if (!parsed.success) return {
+				ok: false,
+				error: {
+					key: "queue_error",
+					message: `Invalid step payload: ${parsed.error.message}`
+				}
+			};
+			await ensurePrepared();
+			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 octaflow/postgres?"
+				}
+			};
+			if (!await boss.send(queueName, parsed.data, {
+				retryLimit: cfg.retryLimit,
+				retryDelay: cfg.retryDelay,
+				expireInSeconds: cfg.expireInSeconds,
+				...startAfter != null && startAfter > 0 ? { startAfter } : {},
+				...db ? { db } : {}
+			})) return {
+				ok: false,
+				error: {
+					key: "queue_error",
+					message: `Failed to enqueue job to ${queueName}`
+				}
+			};
+			return {
+				ok: true,
+				value: void 0
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: {
+					key: "queue_error",
+					message: error instanceof Error ? error.message : "Unknown enqueue error"
+				}
+			};
+		}
+	}
+	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
+		* 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) {
+	const { boss, queueName } = deps;
+	let workerId = null;
+	async function start(process) {
+		await ensureStepQueue(boss, queueName, deps.config);
+		const opts = deps.workerOptions ?? {};
+		const lanes = Math.max(1, opts.concurrency ?? 1);
+		const workOpts = {
+			batchSize: opts.batchSize ?? 1,
+			perJobResults: true,
+			...opts.pollingIntervalSeconds != null && { pollingIntervalSeconds: opts.pollingIntervalSeconds },
+			...opts.notifyPollingIntervalSeconds != null && { notifyPollingIntervalSeconds: opts.notifyPollingIntervalSeconds },
+			...opts.burstWhenBatchFull != null && { burstWhenBatchFull: opts.burstWhenBatchFull },
+			...opts.burstWhenReadyExceeds != null && { burstWhenReadyExceeds: opts.burstWhenReadyExceeds }
+		};
+		workerId = await boss.work(queueName, workOpts, async (jobs) => {
+			const results = [];
+			const pending = [...jobs];
+			await Promise.all(Array.from({ length: Math.min(lanes, pending.length) }, async () => {
+				for (;;) {
+					const job = pending.shift();
+					if (!job) break;
+					const parsed = WIRE_STEP_PAYLOAD_SCHEMA.safeParse(job.data);
+					if (!parsed.success) {
+						results.push({
+							id: job.id,
+							status: "deadletter",
+							output: { message: `Invalid step payload for job ${job.id}: ${parsed.error.message}` }
+						});
+						continue;
+					}
+					try {
+						await process(parsed.data);
+						results.push({
+							id: job.id,
+							status: "completed"
+						});
+					} catch (error) {
+						results.push({
+							id: job.id,
+							status: "failed",
+							output: { message: error instanceof Error ? error.message : String(error) }
+						});
+					}
+				}
+			}));
+			return results;
+		});
+	}
+	async function stop() {
+		if (workerId) {
+			await boss.offWork(workerId);
+			workerId = null;
+		}
+	}
+	return {
+		start,
+		stop
+	};
+}
+/** A pg-boss worker on the step queue's dead-letter queue. */
+function createPgBossDlqWorker(deps) {
+	const { boss, queueName, logger } = deps;
+	const dlq = dlqName(queueName);
+	let workerId = null;
+	async function start(onDlq) {
+		workerId = await boss.work(dlq, { pollingIntervalSeconds: deps.pollingIntervalSeconds ?? 30 }, async (jobs) => {
+			for (const job of jobs) {
+				const parsed = WIRE_STEP_PAYLOAD_SCHEMA.safeParse(job.data);
+				if (!parsed.success) {
+					logger?.error("Invalid payload in DLQ", void 0, { jobId: job.id });
+					continue;
+				}
+				logger?.error("Step job dead-lettered", void 0, {
+					jobId: job.id,
+					workflowId: parsed.data.workflowId,
+					stepId: parsed.data.stepId,
+					stepKey: parsed.data.stepKey
+				});
+				try {
+					await onDlq(parsed.data);
+				} catch (error) {
+					logger?.error("DLQ handler failed", error instanceof Error ? error : void 0, { jobId: job.id });
+				}
+			}
+		});
+	}
+	async function stop() {
+		if (workerId) {
+			await boss.offWork(workerId);
+			workerId = null;
+		}
+	}
+	return {
+		start,
+		stop
+	};
+}
+//#endregion
+//#region src/pg-boss/scheduler.ts
+/** Create the start queue (idempotent). */
+async function ensureStartQueue(boss, queueName) {
+	try {
+		await boss.createQueue(queueName);
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("already exists")) return;
+		throw e;
+	}
+}
+/** Registers cron schedules that enqueue workflow-start jobs. */
+function createPgBossScheduler(deps) {
+	const { boss, queueName, partitionKey } = deps;
+	let ensured = false;
+	async function ensure() {
+		if (!ensured) {
+			await ensureStartQueue(boss, queueName);
+			ensured = true;
+		}
+	}
+	return {
+		/** Create or replace a cron schedule that starts a workflow. */
+		async schedule(input) {
+			await ensure();
+			const payload = {
+				partitionKey,
+				workflowType: input.workflowType,
+				input: input.input ?? {},
+				entityRef: input.entityRef,
+				idempotencyKey: input.idempotencyKey,
+				idempotencyKeyPrefix: input.idempotencyKeyPrefix
+			};
+			await boss.schedule(queueName, input.cron, payload, {
+				key: input.key,
+				...input.tz ? { tz: input.tz } : {}
+			});
+		},
+		/** Remove a schedule by key. */
+		async unschedule(key) {
+			await boss.unschedule(queueName, key);
+		},
+		/** List the schedules registered on this queue. */
+		async list() {
+			return (await boss.getSchedules()).filter((s) => s.name === queueName);
+		}
+	};
+}
+/** A pg-boss worker on the start queue that drives a host start callback. */
+function createPgBossStartWorker(deps) {
+	const { boss, queueName, logger } = deps;
+	let workerId = null;
+	async function start(process) {
+		await ensureStartQueue(boss, queueName);
+		const workOpts = {
+			batchSize: deps.workerOptions?.batchSize ?? 1,
+			...deps.workerOptions?.pollingIntervalSeconds != null && { pollingIntervalSeconds: deps.workerOptions.pollingIntervalSeconds }
+		};
+		workerId = await boss.work(queueName, workOpts, async (jobs) => {
+			for (const job of jobs) {
+				const parsed = WIRE_START_PAYLOAD_SCHEMA.safeParse(job.data);
+				if (!parsed.success) {
+					logger?.error("Invalid start payload", void 0, { jobId: job.id });
+					continue;
+				}
+				await process({
+					...parsed.data,
+					jobId: job.id,
+					idempotencyKey: resolveStartIdempotencyKey(parsed.data, job.id)
+				});
+			}
+		});
+	}
+	async function stop() {
+		if (workerId) {
+			await boss.offWork(workerId);
+			workerId = null;
+		}
+	}
+	return {
+		start,
+		stop
+	};
+}
+//#endregion
 export { DEFAULT_STEP_QUEUE_CONFIG, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue, resolveStartIdempotencyKey };