@shivaedev/effect-pg-boss 0.10.1 → 0.12.0

package/dist/server/testing.js

@@ -2,11 +2,13 @@ import { Effect, Redacted } from "effect";
 import { PgBoss } from "pg-boss";
 import { PgBossTestingError } from "#error.ts";
 import { testingClient } from "#internal/testingClient.ts";
+import { testingDeferrals } from "#internal/testingDeferrals.ts";
 import { testingOperation, testingReadout } from "#internal/testingReadout.ts";
 import { testingSignal } from "#internal/testingSignal.ts";
 export const testRetryPolicy = Object.freeze({ retryBackoff: false, retryDelay: 0 });
 export function makePgBossTesting(options = {}) {
     let current;
+    let schema = "pgboss";
     const signal = testingSignal();
     const controls = {
         changed: signal.changed,
@@ -24,10 +26,12 @@ export function makePgBossTesting(options = {}) {
         if (current !== undefined) {
             throw new Error("A testing controller owns one jobs client; create a controller per runtime");
         }
+        schema = clientOptions.schema ?? "pgboss";
         current = new PgBoss({ ...clientOptions, "__test__enableSpies": true });
         return testingClient(current, clientOptions.schema ?? "pgboss", controls);
     };
     return {
+        ...testingDeferrals(client, () => schema, signal.changed),
         checkBatchWindow: (queue, millisecondsPerJob) => testingOperation("checkBatchWindow", async () => {
             const stored = await client().getQueue(queue.name);
             if (stored === null) {

package/dist/server/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;AAMrF,MAAM,UAAU,iBAAiB,CAAC,OAAO,GAAyB,EAAE;IACnE,IAAI,OAA2B,CAAC;IAChC,IAAI,MAAM,GAAG,QAAQ,CAAC;IACtB,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG;QAChB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,IAAI,GAAG,EAAkB;QACtC,QAAQ,EAAE,IAAI,GAAG,EAAU;QAC3B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;KACtC,CAAC;IACF,SAAS,MAAM;QACd,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IACD,MAAM,aAAa,GAAwB,CAAC,aAAa,EAAE,EAAE;QAC5D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,GAAG,aAAa,CAAC,MAAM,IAAI,QAAQ,CAAC;QAC1C,OAAO,GAAG,IAAI,MAAM,CAAC,EAAE,GAAG,aAAa,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC,CAAC;QACxE,OAAO,aAAa,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,IAAI,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3E,CAAC,CAAC;IACF,OAAO;QACN,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC;QACzD,gBAAgB,EAAE,CAAC,KAAsD,EAAE,kBAA0B,EAAE,EAAE,CACxG,gBAAgB,CACf,kBAAkB,EAClB,KAAK,IAAI,EAAE;YACV,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACnD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAC5C,CAAC;YACD,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;gBAC1C,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;YAC/C,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;gBACpE,MAAM,IAAI,UAAU,CAAC,6CAA6C,CAAC,CAAC;YACrE,CAAC;YACD,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,SAAS,IAAI,EAAE,CAAC,GAAG,kBAAkB,CAAC;YAC5E,IAAI,QAAQ,IAAI,MAAM,CAAC,eAAe,GAAG,IAAI,EAAE,CAAC;gBAC/C,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;YAClF,CAAC;QACF,CAAC,EACD,KAAK,CAAC,IAAI,CACV;QACF,kBAAkB,EAAE,CAAC,QAAgB,EAAE,EAAE,CACxC,gBAAgB,CAAC,oBAAoB,EAAE,KAAK,IAAI,EAAE;YACjD,IAAI,CAAC,MAAM,MAAM,EAAE,CAAC,aAAa,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACnD,MAAM,IAAI,KAAK,CAAC,mCAAmC,QAAQ,EAAE,CAAC,CAAC;YAChE,CAAC;QACF,CAAC,CAAC;QACH,aAAa;QACb,WAAW,EAAE,CAAC,KAAoC,EAAE,QAAgB,EAAE,EAAE,CACvE,MAAM,CAAC,GAAG,CAAC;YACV,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YAC/H,GAAG,EAAE,GAAG,EAAE;gBACT,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;oBACrD,MAAM,IAAI,UAAU,CAAC,qCAAqC,CAAC,CAAC;gBAC7D,CAAC;gBACD,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAChD,CAAC;SACD,CAAC;QACH,YAAY,EAAE,CAAC,KAAoC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAChI,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,aAAa,EAAE,gBAAgB,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,aAAa,EAAE,CAAC;QAChF,aAAa,EAAE,MAAM,CAAC,aAAa;KACnC,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/effect-pg-boss",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Effect-native jobs and lifecycle management for pg-boss",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/effect-pg-boss#readme",
   "bugs": {
@@ -41,10 +41,10 @@
     "README.md"
   ],
   "devDependencies": {
-    "@shivaedev/effect-test": "0.6.0",
-    "@shivaedev/effect-test-sql": "0.6.0",
-    "@shivaedev/quality": "0.27.1",
-    "@shivaedev/test-story": "0.10.0",
+    "@shivaedev/effect-test": "0.7.1",
+    "@shivaedev/effect-test-sql": "0.6.1",
+    "@shivaedev/quality": "0.28.0",
+    "@shivaedev/test-story": "0.12.0",
     "@types/node": "24.19.2",
     "effect": "4.0.4",
     "pg-boss": "12.37.1",

package/src/server/definition.ts

@@ -1,6 +1,19 @@
-import { Clock, Duration, Effect, type Schema } from "effect";
-import type { Job, Queue, ScheduleOptions, WorkOptions } from "pg-boss";
+import { Clock, Duration, Effect, Schema } from "effect";
+import type { Job, policies, Queue, ScheduleOptions, WorkOptions } from "pg-boss";
 import { deadlineOf } from "#internal/deadlineOf.ts";
+import { maxDeferrals, nativeQueueOptions } from "#internal/definitionOptions.ts";
+import { scheduleDefinition } from "#internal/scheduleDefinition.ts";
+
+export class RetryAt extends Schema.TaggedError<RetryAt>()("RetryAt", {
+	at: Schema.DateTimeUtc,
+	reason: Schema.String,
+}) {}
+
+export type QueuePolicy = (typeof policies)[keyof typeof policies];
+export type QueueOptions = Omit<Queue, "name" | "deadLetter" | "policy"> & {
+	readonly maxDeferrals?: number;
+	readonly policy?: QueuePolicy;
+};
 
 export interface JobPayloadSchema extends Schema.Top {
 	readonly Encoded: object;
@@ -16,108 +29,112 @@ export interface JobContext {
 	readonly signal: AbortSignal;
 }
 
-export interface QueueDefinition<Name extends string = string, Payload extends JobPayloadSchema = JobPayloadSchema> {
+export interface QueueDefinition<TName extends string = string, TPayload extends JobPayloadSchema = JobPayloadSchema> {
 	readonly _tag: "QueueDefinition";
 	readonly handle: <E, R>(
-		handler: (payload: Schema.Schema.Type<Payload>, job: JobContext) => Effect.Effect<unknown, E, R>,
-	) => QueueWorker<Payload, R>;
-	readonly name: Name;
+		handler: (payload: Schema.Schema.Type<TPayload>, job: JobContext) => Effect.Effect<unknown, E, R>,
+	) => QueueWorker<TPayload, R>;
+	readonly key?: ((payload: Schema.Schema.Type<TPayload>) => string) | undefined;
+	readonly maxDeferrals: number;
+	readonly name: TName;
 	readonly queueOptions: Omit<Queue, "name" | "deadLetter">;
-	readonly schema: Payload;
+	readonly schema: TPayload;
 	readonly workerOptions: WorkOptions;
 }
 
-export interface QueueWorker<Payload extends JobPayloadSchema = JobPayloadSchema, Requirements = unknown> {
+export interface QueueWorker<TPayload extends JobPayloadSchema = JobPayloadSchema, TRequirements = unknown> {
 	readonly _tag: "QueueWorker";
-	readonly handler: (payload: Schema.Schema.Type<Payload>, job: JobContext) => Effect.Effect<unknown, unknown, Requirements>;
-	readonly queue: QueueDefinition<string, Payload>;
+	readonly handler: (payload: Schema.Schema.Type<TPayload>, job: JobContext) => Effect.Effect<unknown, unknown, TRequirements>;
+	readonly queue: QueueDefinition<string, TPayload>;
 }
 
 export interface JobRegistration {
 	readonly _tag: "QueueDefinition" | "QueueWorker" | "ScheduledWorker";
 }
 
-export interface ScheduleDefinition<Name extends string = string> {
+export interface ScheduleDefinition<TName extends string = string> {
 	readonly _tag: "ScheduleDefinition";
 	readonly cron: string;
-	readonly name: Name;
+	readonly maxDeferrals: number;
+	readonly name: TName;
 	readonly queueOptions: Omit<Queue, "name" | "deadLetter">;
 	readonly run: <E, R>(effect: Effect.Effect<unknown, E, R>) => ScheduledWorker<R>;
 	readonly scheduleOptions: ScheduleOptions;
 	readonly workerOptions: WorkOptions;
 }
 
-export interface ScheduledWorker<Requirements = unknown> {
+export interface ScheduledWorker<TRequirements = unknown> {
 	readonly _tag: "ScheduledWorker";
-	readonly effect: Effect.Effect<unknown, unknown, Requirements>;
+	readonly effect: Effect.Effect<unknown, unknown, TRequirements>;
 	readonly schedule: ScheduleDefinition;
 }
 
-export type RegistrationRequirements<Registrations extends readonly JobRegistration[]> = Registrations[number] extends infer Registration
-	? Registration extends QueueWorker<infer Payload, infer Requirements>
-		? Requirements | Payload["DecodingServices"]
-		: Registration extends ScheduledWorker<infer Requirements>
-			? Requirements
+export type RegistrationRequirements<TRegistrations extends readonly JobRegistration[]> = TRegistrations[number] extends infer TRegistration
+	? TRegistration extends QueueWorker<infer TPayload, infer TRequirements>
+		? TRequirements | TPayload["DecodingServices"]
+		: TRegistration extends ScheduledWorker<infer TRequirements>
+			? TRequirements
 			: never
 	: never;
 
-export interface DefineQueueOptions<Name extends string, Payload extends JobPayloadSchema> {
-	readonly name: Name;
-	readonly queue?: Omit<Queue, "name" | "deadLetter">;
-	readonly schema: Payload;
+export type DefineQueueOptions<TName extends string, TPayload extends JobPayloadSchema> = {
+	readonly name: TName;
+	readonly schema: TPayload;
 	readonly worker?: WorkOptions;
-}
+} & (
+	| { readonly key: (payload: Schema.Schema.Type<TPayload>) => string; readonly queue: QueueOptions & { readonly policy: "singleton" } }
+	| { readonly key?: never; readonly queue?: QueueOptions & { readonly policy?: Exclude<QueuePolicy, "singleton"> } }
+);
 
-export const defineQueue = <const Name extends string, const Payload extends JobPayloadSchema>(
-	options: DefineQueueOptions<Name, Payload>,
-): QueueDefinition<Name, Payload> => {
-	const definition: QueueDefinition<Name, Payload> = {
+export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
+	options: DefineQueueOptions<TName, TPayload> & { readonly key: (payload: Schema.Schema.Type<TPayload>) => string },
+): QueueDefinition<TName, TPayload> & { readonly key: (payload: Schema.Schema.Type<TPayload>) => string };
+export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
+	options: DefineQueueOptions<TName, TPayload> & { readonly key?: never },
+): QueueDefinition<TName, TPayload> & { readonly key?: never };
+export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
+	options: DefineQueueOptions<TName, TPayload>,
+): QueueDefinition<TName, TPayload>;
+export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
+	options: DefineQueueOptions<TName, TPayload>,
+): QueueDefinition<TName, TPayload> {
+	const definition: QueueDefinition<TName, TPayload> = {
 		_tag: "QueueDefinition",
+		...(options.key === undefined ? {} : { key: options.key }),
 		handle: (handler) =>
 			Object.freeze({
 				_tag: "QueueWorker" as const,
 				handler,
 				queue: definition,
 			}),
+		maxDeferrals: maxDeferrals(options.queue),
 		name: options.name,
-		queueOptions: Object.freeze({ ...options.queue }),
+		queueOptions: nativeQueueOptions(options.queue),
 		schema: options.schema,
 		workerOptions: Object.freeze({ batchSize: 10, burstWhenBatchFull: true, ...options.worker }),
 	};
 	return Object.freeze(definition);
-};
+}
 
-export interface DefineScheduleOptions<Name extends string> {
+export interface DefineScheduleOptions<TName extends string> {
 	readonly cron: string;
-	readonly name: Name;
-	readonly queue?: Omit<Queue, "name" | "deadLetter">;
+	readonly name: TName;
+	readonly queue?: QueueOptions;
 	readonly schedule?: ScheduleOptions;
 	readonly worker?: WorkOptions;
 }
 
-export const defineSchedule = <const Name extends string>(options: DefineScheduleOptions<Name>): ScheduleDefinition<Name> => {
-	const definition: ScheduleDefinition<Name> = {
-		_tag: "ScheduleDefinition",
-		cron: options.cron,
-		name: options.name,
-		queueOptions: Object.freeze({ ...options.queue }),
-		run: (effect) =>
-			Object.freeze({
-				_tag: "ScheduledWorker" as const,
-				effect,
-				schedule: definition,
-			}),
-		scheduleOptions: Object.freeze({ tz: "UTC", ...options.schedule }),
-		workerOptions: Object.freeze({ batchSize: 10, burstWhenBatchFull: true, ...options.worker }),
-	};
-	return Object.freeze(definition);
-};
+export function defineSchedule<const TName extends string>(options: DefineScheduleOptions<TName>): ScheduleDefinition<TName> {
+	return scheduleDefinition(options);
+}
 
-export const jobContext = (job: Job<unknown>): JobContext => ({
-	expireInSeconds: job.expireInSeconds,
-	heartbeatSeconds: job.heartbeatSeconds,
-	id: job.id,
-	name: job.name,
-	remainingBudget: Effect.map(Clock.currentTimeMillis, (now) => Duration.millis(Math.max(0, deadlineOf(job) - now))),
-	signal: job.signal,
-});
+export function jobContext(job: Job<unknown>): JobContext {
+	return {
+		expireInSeconds: job.expireInSeconds,
+		heartbeatSeconds: job.heartbeatSeconds,
+		id: job.id,
+		name: job.name,
+		remainingBudget: Effect.map(Clock.currentTimeMillis, (now) => Duration.millis(Math.max(0, deadlineOf(job) - now))),
+		signal: job.signal,
+	};
+}

package/src/server/internal/batchHandler.ts

@@ -2,12 +2,31 @@ import { Cause, Clock, Effect, Exit } from "effect";
 import type { Job } from "pg-boss";
 import type { PgBossClient } from "#client.ts";
 import { deadlineOf } from "#internal/deadlineOf.ts";
+import { deferredAttempt } from "#internal/deferral.ts";
 
 function failureOutput(cause: Cause.Cause<unknown>): object {
 	const error = Cause.squash(cause);
 	return typeof error === "object" && error !== null ? error : { message: String(error) };
 }
 
+async function settleAttempt(
+	complete: NonNullable<PgBossClient["complete"]>,
+	fail: NonNullable<PgBossClient["fail"]>,
+	name: string,
+	job: Job<unknown>,
+	exit: Exit.Exit<unknown, unknown>,
+	afterFailure?: (job: Job<unknown>) => Promise<void>,
+) {
+	if (Exit.isSuccess(exit)) {
+		if (exit.value !== deferredAttempt) {
+			await complete(name, job);
+		}
+	} else {
+		await fail(name, job, failureOutput(exit.cause));
+		await afterFailure?.(job);
+	}
+}
+
 export function batchHandler(
 	client: PgBossClient,
 	name: string,
@@ -19,6 +38,7 @@ export function batchHandler(
 	if (complete === undefined || fail === undefined) {
 		throw new TypeError("This pg-boss client does not support complete and fail");
 	}
+
 	return async (jobs: readonly Job<unknown>[]): Promise<void> => {
 		let expired = false;
 		for (const job of jobs) {
@@ -38,12 +58,7 @@ export function batchHandler(
 				// Returning would let pg-boss complete the unprocessed jobs; its expiry owns them instead.
 				return new Promise<never>(() => undefined);
 			}
-			if (Exit.isSuccess(exit)) {
-				await complete(name, job);
-			} else {
-				await fail(name, job, failureOutput(exit.cause));
-				await afterFailure?.(job);
-			}
+			await settleAttempt(complete, fail, name, job, exit, afterFailure);
 		}
 		if (expired) {
 			return new Promise<never>(() => undefined);

package/src/server/internal/deferrableAttempt.ts

@@ -0,0 +1,41 @@
+import { Clock, DateTime, Effect, Schema } from "effect";
+import type { Job } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { RetryAt } from "#definition.ts";
+import { deferralObservers, deferredAttempt } from "#internal/deferral.ts";
+import { settleDeferral } from "#internal/settleDeferral.ts";
+
+const recordDeferral = Effect.fnUntraced(function* (at: string, reason: string) {
+	const span = yield* Effect.currentSpan.pipe(Effect.orDie);
+	span.event("job.deferred", yield* Clock.currentTimeNanos, { at, reason });
+});
+
+export function deferrableAttempt<A, E, R>(
+	effect: Effect.Effect<A, E, R>,
+	client: PgBossClient,
+	schema: string,
+	job: Job<unknown>,
+	maxDeferrals: number,
+) {
+	return effect.pipe(
+		Effect.catchIf(Schema.is(RetryAt), (error) => {
+			if (maxDeferrals === 0) {
+				return Effect.fail(error);
+			}
+			const at = DateTime.formatIso(error.at);
+			return Effect.promise(() => settleDeferral(client, schema, job, at, error.reason, maxDeferrals)).pipe(
+				Effect.flatMap((settled) => {
+					if (settled.claimed && !settled.deferred) {
+						return Effect.fail(error);
+					}
+					// Native batch settlement must not match a sibling's new claim at the unchanged retry count.
+					job.retryCount = Number.MAX_SAFE_INTEGER;
+					if (settled.deferred) {
+						deferralObservers.get(client)?.();
+					}
+					return (settled.deferred ? recordDeferral(at, error.reason) : Effect.void).pipe(Effect.as(deferredAttempt));
+				}),
+			);
+		}),
+	);
+}

package/src/server/internal/deferral.ts

@@ -0,0 +1,19 @@
+import { Schema } from "effect";
+import type { Job } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+
+export const deferredAttempt = Symbol("deferredAttempt");
+export const deferralObservers = new WeakMap<PgBossClient, () => void>();
+export const STATELY_DEFERRAL_POLICY = "effect-stately-deferred";
+
+export const Deferral = Schema.Struct({
+	at: Schema.String,
+	reason: Schema.String,
+});
+
+const Output = Schema.Struct({ jobDeferral: Deferral });
+
+export function deferralOf(job: Job<unknown>) {
+	const output: unknown = Reflect.get(job, "output");
+	return Schema.is(Output)(output) ? output.jobDeferral : undefined;
+}

package/src/server/internal/deferralStorePlan.ts

@@ -0,0 +1,34 @@
+import { STATELY_DEFERRAL_POLICY } from "./deferral.ts";
+
+export function deferralStorePlan(schema: string): string {
+	const quoted = `"${schema.replaceAll('"', '""')}"`;
+	const jobTable = `${quoted}.job`.replaceAll("'", "''");
+	const key = `${schema}.effect_job_deferral`.replaceAll("'", "''");
+	const body = `BEGIN
+		PERFORM pg_advisory_xact_lock(hashtextextended('${key}', 0));
+		CREATE TABLE IF NOT EXISTS ${quoted}.effect_job_deferral (
+			name text NOT NULL,
+			id uuid NOT NULL,
+			created_on timestamptz NOT NULL,
+			count bigint NOT NULL,
+			keep_until timestamptz NOT NULL,
+			PRIMARY KEY (name, id)
+		);
+		CREATE INDEX IF NOT EXISTS effect_job_deferral_keep_until ON ${quoted}.effect_job_deferral (keep_until);
+		CREATE OR REPLACE FUNCTION ${quoted}.effect_stately_deferral() RETURNS trigger LANGUAGE plpgsql AS $claim$
+		BEGIN
+			IF NEW.policy = '${STATELY_DEFERRAL_POLICY}' AND NEW.state = 'active' THEN
+				NEW.policy := 'stately';
+			END IF;
+			RETURN NEW;
+		END
+		$claim$;
+		IF NOT EXISTS (
+			SELECT 1 FROM pg_trigger WHERE tgrelid = '${jobTable}'::regclass AND tgname = 'effect_stately_deferral'
+		) THEN
+			CREATE TRIGGER effect_stately_deferral BEFORE UPDATE OF state, policy ON ${quoted}.job
+			FOR EACH ROW EXECUTE FUNCTION ${quoted}.effect_stately_deferral();
+		END IF;
+	END`;
+	return `DO '${body.replaceAll("'", "''")}'`;
+}

package/src/server/internal/definitionOptions.ts

@@ -0,0 +1,14 @@
+import type { QueueOptions } from "#definition.ts";
+
+export function maxDeferrals(options: QueueOptions | undefined): number {
+	const limit = options?.maxDeferrals ?? 10;
+	if (!Number.isSafeInteger(limit) || limit < 0) {
+		throw new RangeError("maxDeferrals must be a nonnegative safe integer");
+	}
+	return limit;
+}
+
+export function nativeQueueOptions(options: QueueOptions | undefined) {
+	const { maxDeferrals: _limit, ...native } = options ?? {};
+	return Object.freeze(native);
+}

package/src/server/internal/expireAttempt.ts

@@ -1,12 +1,14 @@
 import type { Job, PgBoss } from "pg-boss";
 
-export async function expireAttempt(client: PgBoss, schema: string, job: Job<unknown>): Promise<void> {
+export async function expireAttempt(client: PgBoss, schema: string, job: Job<unknown>, cause: "expiry" | "heartbeat" = "expiry"): Promise<void> {
 	if ((await client.schemaVersion()) !== 45) {
 		throw new Error("Testing expiry requires pg-boss schema version 45");
 	}
 	const quoted = `"${schema.replaceAll('"', '""')}"`;
+	const timestamp = cause === "expiry" ? "started_on" : "heartbeat_on";
+	const seconds = cause === "expiry" ? "expire_seconds" : "heartbeat_seconds";
 	await client.getDb().executeSql(
-		`UPDATE ${quoted}.job SET started_on = ${quoted}.job_now() - (expire_seconds + 1) * interval '1 second'
+		`UPDATE ${quoted}.job SET ${timestamp} = ${quoted}.job_now() - (${seconds} + 1) * interval '1 second'
 		WHERE name = $1 AND id = $2 AND retry_count = $3 AND state = 'active'`,
 		[job.name, job.id, job.retryCount],
 	);

package/src/server/internal/lifecycle.ts

@@ -2,6 +2,7 @@ import { Effect } from "effect";
 import type { ConstructorOptions, StopOptions } from "pg-boss";
 import { defaultClientFactory, type PgBossClient, type PgBossClientFactory } from "#client.ts";
 import { toPgBossError } from "#error.ts";
+import { deferralStorePlan } from "#internal/deferralStorePlan.ts";
 import { acquireCachedClient, releaseCachedClient } from "./clientCache.ts";
 import { logClientError, observeClientErrors } from "./clientErrors.ts";
 
@@ -22,6 +23,9 @@ async function startClient(options: AcquireClientOptions, report: (error: Error)
 	observeClientErrors(client, report);
 	try {
 		await client.start();
+		if (options.constructor.migrate !== false && client.getDb !== undefined) {
+			await client.getDb().executeSql(deferralStorePlan(options.constructor.schema ?? "pgboss"));
+		}
 		return client;
 	} catch (error) {
 		try {

package/src/server/internal/register.ts

@@ -12,7 +12,7 @@ import {
 import { PgBossError, PgBossPayloadError, PgBossQueueOptionsError, toPgBossError } from "#error.ts";
 import { ensureQueue } from "#internal/ensureQueue.ts";
 import { registerWorker } from "#internal/registerWorker.ts";
-import { payloadOf, traceJob } from "#internal/tracing.ts";
+import { payloadOf } from "#internal/tracing.ts";
 
 function isQueueWorker(registration: JobRegistration): registration is QueueWorker {
 	return registration._tag === "QueueWorker";
@@ -65,7 +65,7 @@ function workerContext(context: unknown): unknown {
 	return context;
 }
 
-function runQueueWorker(worker: QueueWorker, job: Job<unknown>, context: Context.Context<unknown>) {
+function runQueueWorker(worker: QueueWorker, job: Job<unknown>) {
 	return Schema.decodeUnknownEffect(worker.queue.schema)(payloadOf(job.data)).pipe(
 		Effect.mapError(
 			(error) =>
@@ -76,8 +76,6 @@ function runQueueWorker(worker: QueueWorker, job: Job<unknown>, context: Context
 				}),
 		),
 		Effect.flatMap((payload) => worker.handler(payload, jobContext(job))),
-		(effect) => traceJob(effect, job, worker.queue.name),
-		Effect.provide(context),
 	);
 }
 
@@ -86,24 +84,25 @@ async function registerQueue(
 	registration: QueueWorker | QueueDefinition,
 	context: Context.Context<unknown>,
 	scope: Scope.Scope,
+	schema: string,
 ): Promise<void> {
 	const queue = registration._tag === "QueueWorker" ? registration.queue : registration;
 	const name = queue.name;
 	if (registration._tag === "QueueDefinition") {
 		return;
 	}
-	await registerWorker(client, name, queue.workerOptions, (job) => runQueueWorker(registration, job, context), scope);
+	await registerWorker(client, name, queue.workerOptions, (job) => runQueueWorker(registration, job), scope, schema, queue.maxDeferrals, context);
 }
 
-async function registerSchedule(client: PgBossClient, worker: ScheduledWorker, context: Context.Context<unknown>, scope: Scope.Scope): Promise<void> {
+async function registerSchedule(
+	client: PgBossClient,
+	worker: ScheduledWorker,
+	context: Context.Context<unknown>,
+	scope: Scope.Scope,
+	schema: string,
+): Promise<void> {
 	const { schedule } = worker;
-	await registerWorker(
-		client,
-		schedule.name,
-		schedule.workerOptions,
-		(job) => Effect.provide(traceJob(worker.effect, job, schedule.name), context),
-		scope,
-	);
+	await registerWorker(client, schedule.name, schedule.workerOptions, () => worker.effect, scope, schema, schedule.maxDeferrals, context);
 	await client.schedule(schedule.name, schedule.cron, null, schedule.scheduleOptions);
 }
 
@@ -120,6 +119,7 @@ export const registerJobs = <R>(
 	registrations: readonly JobRegistration[],
 	context: Context.Context<R>,
 	replaceWorkers: boolean,
+	schema = "pgboss",
 ): Effect.Effect<void, PgBossError | PgBossQueueOptionsError, Scope.Scope> =>
 	Effect.flatMap(Effect.scope, (scope) =>
 		Effect.tryPromise({
@@ -130,9 +130,9 @@ export const registerJobs = <R>(
 				const provided = workerContext(context);
 				for (const registration of registrations) {
 					if (isQueueWorker(registration) || isQueueDefinition(registration)) {
-						await registerQueue(client, registration, provided, scope);
+						await registerQueue(client, registration, provided, scope, schema);
 					} else if (isScheduledWorker(registration)) {
-						await registerSchedule(client, registration, provided, scope);
+						await registerSchedule(client, registration, provided, scope, schema);
 					}
 				}
 			},

package/src/server/internal/registerWorker.ts

@@ -1,42 +1,55 @@
-import { Clock, Effect, type Scope } from "effect";
+import { Clock, type Context, Effect, type Scope } from "effect";
 import type { Job, WorkOptions } from "pg-boss";
 import type { PgBossClient } from "#client.ts";
 import { batchHandler } from "#internal/batchHandler.ts";
+import { deferrableAttempt } from "#internal/deferrableAttempt.ts";
+import { traceJob } from "#internal/tracing.ts";
 
 export function registerWorker(
 	client: PgBossClient,
 	name: string,
 	options: WorkOptions,
-	run: (job: Job<unknown>) => Effect.Effect<unknown, unknown>,
+	run: (job: Job<unknown>) => Effect.Effect<unknown, unknown, unknown>,
 	scope: Scope.Scope,
+	schema: string,
+	maxDeferrals: number,
+	context: Context.Context<unknown>,
 ): Promise<string> {
 	const registration = client.work(
 		name,
 		{ ...options, includeMetadata: true },
-		batchHandler(client, name, run, async (attempt) => {
-			if (client.findJobs === undefined || client.notifyWorker === undefined) {
-				return;
-			}
-			const job = (await client.findJobs(name, { id: attempt.id }))[0];
-			if (job?.state !== "retry") {
-				return;
-			}
-			const workId = await registration;
-			await Effect.runPromise(
-				Effect.gen(function* () {
-					const now = yield* Clock.currentTimeMillis;
-					// PostgreSQL timestamps retain sub-millisecond precision that Date drops.
-					yield* Effect.sleep(Math.max(0, job.startAfter.getTime() + 1 - now));
-					const workerIds = client
-						.getWipData?.()
-						.filter((worker) => worker.workId === workId)
-						.map((worker) => worker.id) ?? [workId];
-					for (const workerId of workerIds) {
-						client.notifyWorker?.(workerId);
-					}
-				}).pipe(Effect.forkIn(scope)),
-			);
-		}),
+		batchHandler(
+			client,
+			name,
+			(job) => {
+				const attempt = traceJob(deferrableAttempt(run(job), client, schema, job, maxDeferrals), job, name);
+				return Effect.provide(attempt, context);
+			},
+			async (attempt) => {
+				if (client.findJobs === undefined || client.notifyWorker === undefined) {
+					return;
+				}
+				const job = (await client.findJobs(name, { id: attempt.id }))[0];
+				if (job?.state !== "retry") {
+					return;
+				}
+				const workId = await registration;
+				await Effect.runPromise(
+					Effect.gen(function* () {
+						const now = yield* Clock.currentTimeMillis;
+						// PostgreSQL timestamps retain sub-millisecond precision that Date drops.
+						yield* Effect.sleep(Math.max(0, job.startAfter.getTime() + 1 - now));
+						const workerIds = client
+							.getWipData?.()
+							.filter((worker) => worker.workId === workId)
+							.map((worker) => worker.id) ?? [workId];
+						for (const workerId of workerIds) {
+							client.notifyWorker?.(workerId);
+						}
+					}).pipe(Effect.forkIn(scope)),
+				);
+			},
+		),
 	);
 	return registration;
 }

package/src/server/internal/scheduleDefinition.ts

@@ -0,0 +1,21 @@
+import type { DefineScheduleOptions, ScheduleDefinition } from "#definition.ts";
+import { maxDeferrals, nativeQueueOptions } from "#internal/definitionOptions.ts";
+
+export function scheduleDefinition<const TName extends string>(options: DefineScheduleOptions<TName>): ScheduleDefinition<TName> {
+	const definition: ScheduleDefinition<TName> = {
+		_tag: "ScheduleDefinition",
+		cron: options.cron,
+		maxDeferrals: maxDeferrals(options.queue),
+		name: options.name,
+		queueOptions: nativeQueueOptions(options.queue),
+		run: (effect) =>
+			Object.freeze({
+				_tag: "ScheduledWorker" as const,
+				effect,
+				schedule: definition,
+			}),
+		scheduleOptions: Object.freeze({ tz: "UTC", ...options.schedule }),
+		workerOptions: Object.freeze({ batchSize: 10, burstWhenBatchFull: true, ...options.worker }),
+	};
+	return Object.freeze(definition);
+}