@shivaedev/jobs 0.29.1 → 0.30.0

package/src/server/adapters/registerWorker.ts

@@ -1,5 +1,5 @@
 import { Effect, Fiber, Scope } from "effect";
-import type { Job, WorkOptions } from "pg-boss";
+import type { Job, StopOptions, WorkOptions } from "pg-boss";
 import type { PgBossClient } from "#client.ts";
 import { toPgBossError } from "#error.ts";
 import { batchHandler } from "#internal/batchHandler.ts";
@@ -15,19 +15,26 @@ export const registerWorker = Effect.fnUntraced(function* <R>(
 	scope: Scope.Scope,
 	schema: string,
 	maxDeferrals: number,
-	graceful: boolean,
+	stop?: StopOptions,
 ) {
 	const execute = Effect.runPromiseWith(yield* Effect.context<R>());
-	const fibers = yield* Scope.fork(scope);
+	const workerScope = yield* Scope.fork(scope);
+	const fibers = yield* Scope.fork(workerScope);
 	function runJob(job: Job<unknown>, deadline: number) {
 		return traceJob(deferrableAttempt(run(job, deadline), client, schema, job, maxDeferrals), job, name);
 	}
-	function afterFailure(attempt: Job<unknown>) {
-		return retryWake(client, name, attempt.id, registration).pipe(Effect.forkIn(fibers), Effect.asVoid);
+	function afterRetry(attempt: Job<unknown>) {
+		return retryWake(client, schema, name, attempt.id, registration).pipe(Effect.forkIn(fibers), Effect.asVoid);
 	}
 	const handle = yield* Effect.try({
 		catch: (error) => toPgBossError("register", error, name),
-		try: () => batchHandler(client, name, schema, runJob, afterFailure),
+		try: () => {
+			const unsupported = (["perJobResults", "transactional"] as const).filter((mode) => options[mode] === true);
+			if (unsupported.length > 0) {
+				throw new TypeError(`Unsupported worker callback modes: ${unsupported.join(", ")}. Omit these options or set them to false.`);
+			}
+			return batchHandler(client, name, schema, runJob, afterRetry);
+		},
 	});
 	const registration: Promise<string> = yield* Effect.try({
 		catch: (error) => toPgBossError("register", error, name),
@@ -37,12 +44,24 @@ export const registerWorker = Effect.fnUntraced(function* <R>(
 			),
 	});
 	const id = yield* Effect.tryPromise({ catch: (error) => toPgBossError("register", error, name), try: () => registration });
+	const graceful = stop?.graceful !== false;
+	const timeout = stop?.timeout ?? 30_000;
+	const drain = Effect.tryPromise({
+		catch: (error) => toPgBossError("stop", error, name),
+		try: () => client.offWork(name, { id, wait: graceful }),
+	});
 	yield* Scope.addFinalizer(
-		scope,
-		Effect.tryPromise({
-			catch: (error) => toPgBossError("stop", error, name),
-			try: () => client.offWork(name, { id, wait: graceful }),
-		}).pipe(Effect.catch(Effect.logError)),
+		workerScope,
+		(graceful
+			? drain.pipe(
+					Effect.timeoutOrElse({
+						duration: timeout,
+						orElse: () => Effect.logWarning(`pg-boss worker drain timed out for queue ${name} after ${timeout}ms; interrupting in-flight work`),
+					}),
+					Effect.interruptible,
+				)
+			: drain
+		).pipe(Effect.catch(Effect.logError)),
 	);
 	return id;
 });

package/src/server/definition.ts

@@ -48,9 +48,10 @@ export interface QueueWorker<TPayload extends JobPayloadSchema = JobPayloadSchem
 	readonly queue: QueueDefinition<string, TPayload>;
 }
 
-export interface JobRegistration {
-	readonly _tag: "QueueDefinition" | "QueueWorker" | "ScheduledWorker";
-}
+export type JobRegistration<TRequirements = unknown> =
+	| QueueDefinition
+	| QueueWorker<JobPayloadSchema & { readonly DecodingServices: TRequirements }, TRequirements>
+	| ScheduledWorker<TRequirements>;
 
 export interface ScheduleDefinition<TName extends string = string> {
 	readonly _tag: "ScheduleDefinition";

package/src/server/internal/batchHandler.ts

@@ -52,7 +52,7 @@ export function batchHandler<R>(
 	name: string,
 	schema: string,
 	run: (job: Job<unknown>, deadline: number) => Effect.Effect<unknown, unknown, R>,
-	afterFailure: (job: Job<unknown>) => Effect.Effect<void, unknown> = () => Effect.void,
+	afterRetry: (job: Job<unknown>) => Effect.Effect<void, unknown> = () => Effect.void,
 ) {
 	const complete = client.complete?.bind(client);
 	const fail = client.fail?.bind(client);
@@ -73,8 +73,8 @@ export function batchHandler<R>(
 			return "interrupted";
 		}
 		yield* settleAttempt(complete, fail, name, job, exit);
-		if (Exit.isFailure(exit)) {
-			yield* afterFailure(job);
+		if (Exit.isFailure(exit) || exit.value === deferredAttempt) {
+			yield* afterRetry(job);
 		}
 		return "settled";
 	});

package/src/server/internal/jobControl.ts

@@ -1,10 +1,21 @@
-import { Effect, Option } from "effect";
+import { Effect, Option, Redacted, Schema } from "effect";
 import { redact } from "@shivaedev/errors/redact.ts";
 import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
+import { PgBossPayloadError, toPgBossError } from "#error.ts";
+import { deferralOf } from "#internal/deferral.ts";
 import { decodeStoredData } from "#internal/storedRows.ts";
+import { JobFailure } from "#JobFailure.ts";
 import type { PgBossService } from "#service.ts";
 
+const StoredFailure = Schema.Union([JobFailure, Schema.Struct({ value: JobFailure })]);
+
+function decodeFailure(queue: string, output: unknown) {
+	return Schema.decodeUnknownEffect(StoredFailure)(output).pipe(
+		Effect.map((failure) => ("value" in failure ? failure.value : failure)),
+		Effect.mapError((error) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(error), queue })),
+	);
+}
+
 export function getJobFor(client: PgBossClient): PgBossService["getJob"] {
 	return (queue, id) =>
 		Effect.tryPromise({
@@ -16,10 +27,16 @@ export function getJobFor(client: PgBossClient): PgBossService["getJob"] {
 				return (await client.findJobs(queue.name, { id }))[0];
 			},
 		}).pipe(
-			Effect.flatMap((job) =>
-				job === undefined
-					? Effect.succeed(Option.none())
-					: decodeStoredData(queue, job.data).pipe(Effect.map((data) => Option.some({ ...job, data: redact(data) }))),
+			Effect.flatMap(
+				Effect.fnUntraced(function* (job) {
+					if (job === undefined) {
+						return Option.none();
+					}
+					const data = yield* decodeStoredData(queue, job.data);
+					const output = job.output === null || deferralOf(job) !== undefined ? job.output : yield* decodeFailure(queue.name, job.output);
+					const sourceOutput = job.sourceOutput === null ? null : yield* decodeFailure(queue.name, job.sourceOutput);
+					return Option.some({ ...job, data: redact(data), output, sourceOutput });
+				}),
 			),
 		);
 }

package/src/server/internal/register.ts

@@ -1,34 +1,22 @@
-import { type Context, Effect, type Scope } from "effect";
+import { type Context, Effect, Scope } from "effect";
+import type { StopOptions } from "pg-boss";
 import { registerWorker } from "#adapters/registerWorker.ts";
+import { workerDiagnostics } from "#adapters/workerDiagnostics.ts";
 import type { PgBossClient } from "#client.ts";
-import type { JobRegistration, QueueDefinition, QueueWorker, ScheduleDefinition, ScheduledWorker } from "#definition.ts";
+import type { JobPayloadSchema, JobRegistration, QueueDefinition, QueueWorker, ScheduleDefinition, ScheduledWorker } from "#definition.ts";
 import { PgBossQueueOptionsError, toPgBossError } from "#error.ts";
 import { ensureQueue } from "#internal/ensureQueue.ts";
 import { runQueueWorker } from "#internal/runQueueWorker.ts";
-
-function isQueueWorker(registration: JobRegistration): registration is QueueWorker {
-	return registration._tag === "QueueWorker";
-}
-
-function isScheduledWorker(registration: JobRegistration): registration is ScheduledWorker {
-	return registration._tag === "ScheduledWorker";
-}
-
-function isQueueDefinition(registration: JobRegistration): registration is QueueDefinition {
-	return registration._tag === "QueueDefinition";
-}
+import { registerTestingQueue } from "#internal/testingRegistrations.ts";
 
 function registrationDefinition(registration: JobRegistration): QueueDefinition | ScheduleDefinition {
-	if (isQueueDefinition(registration)) {
+	if (registration._tag === "QueueDefinition") {
 		return registration;
 	}
-	if (isQueueWorker(registration)) {
+	if (registration._tag === "QueueWorker") {
 		return registration.queue;
 	}
-	if (isScheduledWorker(registration)) {
-		return registration.schedule;
-	}
-	throw new TypeError(`Unknown pg-boss registration: ${registration._tag}`);
+	return registration.schedule;
 }
 
 export function registrationName(registration: JobRegistration): string {
@@ -37,7 +25,7 @@ export function registrationName(registration: JobRegistration): string {
 
 const prepareQueues = Effect.fnUntraced(function* (client: PgBossClient, registrations: readonly JobRegistration[], replaceWorkers: boolean) {
 	for (const registration of registrations) {
-		if (replaceWorkers && !isQueueDefinition(registration)) {
+		if (replaceWorkers && registration._tag !== "QueueDefinition") {
 			yield* Effect.tryPromise({ catch: (error) => toPgBossError("register", error), try: () => client.offWork(registrationName(registration)) });
 		}
 	}
@@ -49,19 +37,13 @@ const prepareQueues = Effect.fnUntraced(function* (client: PgBossClient, registr
 	}
 });
 
-// The layer requires RegistrationRequirements of its jobs, so its context provides every registered worker.
-function workerContext<R>(context: Context.Context<R>): Context.Context<unknown>;
-function workerContext(context: unknown): unknown {
-	return context;
-}
-
-const registerQueue = Effect.fnUntraced(function* (
+const registerQueue = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
-	registration: QueueWorker | QueueDefinition,
-	context: Context.Context<unknown>,
+	registration: QueueWorker<JobPayloadSchema & { readonly DecodingServices: R }, R> | QueueDefinition,
+	context: Context.Context<R>,
 	scope: Scope.Scope,
 	schema: string,
-	graceful: boolean,
+	stop: StopOptions | undefined,
 ) {
 	const queue = registration._tag === "QueueWorker" ? registration.queue : registration;
 	const name = queue.name;
@@ -76,22 +58,29 @@ const registerQueue = Effect.fnUntraced(function* (
 		scope,
 		schema,
 		queue.maxDeferrals,
-		graceful,
+		stop,
 	).pipe(Effect.provide(context));
 });
 
-const registerSchedule = Effect.fnUntraced(function* (
+const registerSchedule = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
-	worker: ScheduledWorker,
-	context: Context.Context<unknown>,
+	worker: ScheduledWorker<R>,
+	context: Context.Context<R>,
 	scope: Scope.Scope,
 	schema: string,
-	graceful: boolean,
+	stop: StopOptions | undefined,
 ) {
 	const { schedule } = worker;
-	yield* registerWorker(client, schedule.name, schedule.workerOptions, () => worker.effect, scope, schema, schedule.maxDeferrals, graceful).pipe(
-		Effect.provide(context),
-	);
+	yield* registerWorker(
+		client,
+		schedule.name,
+		schedule.workerOptions,
+		() => workerDiagnostics(worker.effect),
+		scope,
+		schema,
+		schedule.maxDeferrals,
+		stop,
+	).pipe(Effect.provide(context));
 	yield* Effect.tryPromise({
 		catch: (error) => toPgBossError("register", error, schedule.name),
 		try: () => client.schedule(schedule.name, schedule.cron, null, schedule.scheduleOptions),
@@ -108,25 +97,27 @@ export function registrationNames(registrations: readonly JobRegistration[]): re
 
 export const registerJobs = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
-	registrations: readonly JobRegistration[],
+	registrations: readonly JobRegistration<R>[],
 	context: Context.Context<R>,
 	replaceWorkers: boolean,
 	schema = "pgboss",
 	startWorkers = true,
-	graceful = true,
+	stop?: StopOptions,
 ) {
-	const scope = yield* Effect.scope;
+	const scope = yield* Scope.fork(yield* Effect.scope, "parallel");
 	yield* Effect.try({ catch: (error) => toPgBossError("register", error), try: () => registrationNames(registrations) });
 	yield* prepareQueues(client, registrations, replaceWorkers);
+	for (const registration of registrations) {
+		registerTestingQueue(client, registrationName(registration));
+	}
 	if (!startWorkers) {
 		return;
 	}
-	const provided = workerContext(context);
 	for (const registration of registrations) {
-		if (isQueueWorker(registration) || isQueueDefinition(registration)) {
-			yield* registerQueue(client, registration, provided, scope, schema, graceful);
-		} else if (isScheduledWorker(registration)) {
-			yield* registerSchedule(client, registration, provided, scope, schema, graceful);
+		if (registration._tag === "QueueWorker" || registration._tag === "QueueDefinition") {
+			yield* registerQueue(client, registration, context, scope, schema, stop);
+		} else {
+			yield* registerSchedule(client, registration, context, scope, schema, stop);
 		}
 	}
 });

package/src/server/internal/registerReleasedJobs.ts

@@ -1,4 +1,5 @@
 import { type Context, Effect, Option, Scope } from "effect";
+import type { StopOptions } from "pg-boss";
 import { WorkerRelease } from "@shivaedev/sql/WorkerRelease.ts";
 import { retireJobs } from "#adapters/retireJobs.ts";
 import type { PgBossClient } from "#client.ts";
@@ -8,24 +9,24 @@ import { registerJobs, registrationName } from "./register.ts";
 
 export const registerReleasedJobs = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
-	jobs: readonly JobRegistration[],
+	jobs: readonly JobRegistration<R>[],
 	context: Context.Context<R>,
 	replaceWorkers: boolean,
 	schema: string | undefined,
-	graceful: boolean,
+	stop: StopOptions | undefined,
 	retired: readonly string[] = [],
 ) {
 	const signal = yield* Effect.serviceOption(WorkerRelease);
 	const workers = jobs.filter((job) => job._tag !== "QueueDefinition");
 	const scope = yield* Effect.scope;
 	const register = retireJobs(client, jobs, retired).pipe(
-		Effect.andThen(registerJobs(client, jobs, context, replaceWorkers, schema, true, graceful)),
+		Effect.andThen(registerJobs(client, jobs, context, replaceWorkers, schema, true, stop)),
 		Effect.provideService(Scope.Scope, scope),
 	);
 	if (Option.isNone(signal) || (workers.length === 0 && retired.length === 0)) {
 		return yield* register;
 	}
-	yield* registerJobs(client, jobs, context, replaceWorkers, schema, false, graceful);
+	yield* registerJobs(client, jobs, context, replaceWorkers, schema, false, stop);
 	let working = replaceWorkers;
 	let paused = false;
 	yield* signal.value.register((active) =>

package/src/server/internal/retryWake.ts

@@ -1,9 +1,10 @@
 import { Clock, Effect } from "effect";
 import { redactDiagnosticCause } from "@shivaedev/errors/redactCause.ts";
+import { batchClockOffset } from "#adapters/batchClockOffset.ts";
 import type { PgBossClient } from "#client.ts";
 import { toPgBossError } from "#error.ts";
 
-export function retryWake(client: PgBossClient, name: string, id: string, registration: Promise<string>): Effect.Effect<void> {
+export function retryWake(client: PgBossClient, schema: string, name: string, id: string, registration: Promise<string>): Effect.Effect<void> {
 	return Effect.gen(function* () {
 		const findJobs = client.findJobs?.bind(client);
 		if (findJobs === undefined || client.notifyWorker === undefined) {
@@ -15,8 +16,9 @@ export function retryWake(client: PgBossClient, name: string, id: string, regist
 			return;
 		}
 		const workId = yield* Effect.tryPromise({ catch: (error) => toPgBossError("register", error, name), try: () => registration });
+		const offset = yield* batchClockOffset(client, schema, name);
 		// Host timers can fire early; PostgreSQL retains precision that Date drops.
-		const deadline = job.startAfter.getTime() + 1;
+		const deadline = job.startAfter.getTime() + offset + 1;
 		let remaining = deadline - (yield* Clock.currentTimeMillis);
 		while (remaining > 0) {
 			yield* Effect.sleep(remaining);

package/src/server/internal/runQueueWorker.ts

@@ -3,11 +3,17 @@ import type { Job } from "pg-boss";
 import { deferralCount } from "#adapters/deferralCount.ts";
 import { workerDiagnostics } from "#adapters/workerDiagnostics.ts";
 import type { PgBossClient } from "#client.ts";
-import { jobContext, type QueueWorker } from "#definition.ts";
+import { type JobPayloadSchema, jobContext, type QueueWorker } from "#definition.ts";
 import { PgBossPayloadError } from "#error.ts";
 import { payloadOf } from "#internal/tracing.ts";
 
-export function runQueueWorker(worker: QueueWorker, job: Job<unknown>, deadline: number, client: PgBossClient, schema: string) {
+export function runQueueWorker<R>(
+	worker: QueueWorker<JobPayloadSchema & { readonly DecodingServices: R }, R>,
+	job: Job<unknown>,
+	deadline: number,
+	client: PgBossClient,
+	schema: string,
+) {
 	return Schema.decodeUnknownEffect(Schema.toCodecJson(worker.queue.schema))(payloadOf(job.data)).pipe(
 		Effect.mapError(
 			(error) =>

package/src/server/internal/testingClient.ts

@@ -5,6 +5,7 @@ import { deferralObservers } from "#internal/deferral.ts";
 import { expireAttempt } from "#internal/expireAttempt.ts";
 import { observeTestingSettlements } from "#internal/observeTestingSettlements.ts";
 import type { TestingBatch, TestingWork } from "#internal/testingIdle.ts";
+import { testingRegistration } from "#internal/testingRegistrations.ts";
 
 export interface TestingControls {
 	readonly changed: () => void;
@@ -94,7 +95,6 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 			}),
 		work: (name, options, handler) => {
 			settlements.watch(name);
-			controls.work.queues.add(name);
 			return client.work(name, options, async (jobs: Job<unknown>[]) => {
 				const batch: TestingBatch = { name, settled: false };
 				controls.work.batches.add(batch);
@@ -121,6 +121,9 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 	};
 	const wrapped = new Proxy(client, {
 		get(target, property) {
+			if (property === testingRegistration) {
+				return (name: string) => controls.work.queues.add(name);
+			}
 			if (Object.hasOwn(overrides, property)) {
 				const override: unknown = Reflect.get(overrides, property);
 				return override;

package/src/server/internal/testingIdle.ts

@@ -1,4 +1,4 @@
-import { Effect, Schema } from "effect";
+import { Clock, Effect, Schema } from "effect";
 import type { PgBoss } from "pg-boss";
 import type { PgBossTestingError } from "#error.ts";
 import { quotedSchema } from "#internal/storedRows.ts";
@@ -46,7 +46,12 @@ export function testingIdle(
 			if (work.queues.size === 0 || !(unsettled || (yield* busy))) {
 				return;
 			}
-			yield* signal.waitForChange(revision);
+			if (unsettled) {
+				yield* signal.waitForChange(revision);
+			} else {
+				// Other clients have no local callback; PostgreSQL remains the source of idle state.
+				yield* Effect.raceFirst(signal.waitForChange(revision), Effect.sleep("50 millis"));
+			}
 		}
-	});
+	}).pipe(Effect.provideService(Clock.Clock, Clock.Clock.defaultValue()));
 }

package/src/server/internal/testingRegistrations.ts

@@ -0,0 +1,10 @@
+import type { PgBossClient } from "#client.ts";
+
+export const testingRegistration = Symbol("jobs testing registration");
+
+export function registerTestingQueue(client: PgBossClient, name: string) {
+	const observe: unknown = Reflect.get(client, testingRegistration);
+	if (typeof observe === "function") {
+		observe(name);
+	}
+}

package/src/server/internal/testingSnapshot.ts

@@ -11,7 +11,7 @@ const Rows = Schema.Array(
 		id: Schema.String,
 		queue: Schema.String,
 		startAfter: Schema.DateTimeUtcFromDate,
-		state: Schema.Literals(["created", "retry", "active", "failed"]),
+		state: Schema.Literals(["created", "retry", "deferred", "active", "failed"]),
 	}),
 );
 
@@ -29,7 +29,10 @@ export function testingSnapshot(client: () => PgBoss, schema: () => string) {
 			const { rows } = await client()
 				.getDb()
 				.executeSql(
-					`SELECT id, name AS queue, state, data, start_after AS "startAfter"
+					`SELECT id, name AS queue, data, start_after AS "startAfter",
+					CASE WHEN state = 'retry' AND started_on IS NULL AND start_after > ${quoted}.job_now()
+						AND output ? 'jobDeferral'
+					THEN 'deferred' ELSE state::text END AS state
 					FROM ${quoted}.job
 					WHERE name = ANY($1::text[]) AND state IN ('created', 'retry', 'active', 'failed')
 					ORDER BY created_on, id`,

package/src/server/jobModule.ts

@@ -0,0 +1,18 @@
+import type { JobRegistration } from "#definition.ts";
+import type { PgBossDefinition, PgBossLayerOptions } from "#service.ts";
+
+export function jobModule<TIdentifier extends string, const TJobs extends readonly JobRegistration[], R = never>(
+	layer: PgBossDefinition<TIdentifier>["layer"],
+	options: PgBossLayerOptions<TJobs, R>,
+) {
+	const queues = options.jobs.map((job) => {
+		if (job._tag === "QueueDefinition") {
+			return job;
+		}
+		return job._tag === "QueueWorker" ? job.queue : job.schedule;
+	});
+	return {
+		queues,
+		workers: layer(options),
+	};
+}

package/src/server/service.ts

@@ -2,6 +2,7 @@ import { Context, Effect, Exit, Layer, type Option, Redacted, type Schema, Scope
 import type { ConstructorOptions, JobWithMetadata, SendOptions, StopOptions } from "pg-boss";
 import { defineService } from "@shivaedev/service/defineService.ts";
 import { genericMethod } from "@shivaedev/service/genericMethod.ts";
+import { clientErrorLogger } from "#adapters/clientErrorLogger.ts";
 import { clientErrorReporter } from "#adapters/clientErrorReporter.ts";
 import type { PgBossClientFactory } from "#client.ts";
 import type { JobPayloadSchema, JobRegistration, QueueDefinition, RegistrationRequirements } from "#definition.ts";
@@ -58,7 +59,7 @@ export function pgBossLayer(options: PgBossOptions): Layer.Layer<PgBoss, PgBossE
 	return Layer.effect(
 		PgBoss,
 		Effect.gen(function* () {
-			const report = yield* clientErrorReporter(logClientError);
+			const report = yield* clientErrorLogger();
 			const acquired = yield* Effect.acquireRelease(
 				acquireClient(
 					{
@@ -92,7 +93,10 @@ export interface PgBossDefinition<TIdentifier extends string = string> extends C
 }
 
 export function makePgBoss<const TIdentifier extends string>(identifier: TIdentifier, queueNames?: readonly string[]): PgBossDefinition<TIdentifier> {
-	function definition<R>(options: PgBossLayerOptions<readonly JobRegistration[], R>, dependencies: Context.Context<R>) {
+	function definition<R, E>(
+		options: PgBossLayerOptions<readonly JobRegistration<R>[], E>,
+		dependencies: Context.Context<Exclude<R, TIdentifier> | E>,
+	) {
 		return defineService({
 			id: identifier,
 			initialize: Effect.gen(function* () {
@@ -100,20 +104,16 @@ export function makePgBoss<const TIdentifier extends string>(identifier: TIdenti
 				const acquired = yield* PgBoss;
 				const workerScope = yield* Scope.make();
 				const service = makeService(acquired.client, options.jobs.map(registrationName), acquired.schema);
-				const context = Context.add(dependencies, Service, service);
-				const reportError = options.onError ?? logClientError;
-				const report = yield* clientErrorReporter(reportError).pipe(Effect.provide(context));
-				const unsubscribe = subscribeClientErrors(acquired.client, report);
-				yield* Effect.addFinalizer(() => Scope.close(workerScope, Exit.void).pipe(Effect.ensuring(Effect.sync(unsubscribe))));
-				yield* registerReleasedJobs(
-					acquired.client,
-					options.jobs,
-					context,
-					acquired.reused,
-					acquired.schema,
-					acquired.stop?.graceful !== false,
-					options.retired,
-				).pipe(Effect.provideService(Scope.Scope, workerScope), Effect.provide(dependencies));
+				yield* Effect.gen(function* () {
+					const context = yield* Effect.context<R | E>();
+					const reportError = options.onError ?? logClientError;
+					const report = yield* clientErrorReporter(reportError).pipe(Effect.provide(context));
+					const unsubscribe = subscribeClientErrors(acquired.client, report);
+					yield* Effect.addFinalizer(() => Scope.close(workerScope, Exit.void).pipe(Effect.ensuring(Effect.sync(unsubscribe))));
+					yield* registerReleasedJobs(acquired.client, options.jobs, context, acquired.reused, acquired.schema, acquired.stop, options.retired).pipe(
+						Effect.provideService(Scope.Scope, workerScope),
+					);
+				}).pipe(Effect.provideService(Service, service), Effect.provide(dependencies));
 				return service;
 			}),
 			methods: (service) => ({
@@ -128,12 +128,16 @@ export function makePgBoss<const TIdentifier extends string>(identifier: TIdenti
 			requires: [PgBoss],
 		});
 	}
-	const Service: Context.Service<TIdentifier, PgBossService> = definition({ jobs: [] }, Context.empty());
-	function layer<const TRegistrations extends readonly JobRegistration[], TErrorRequirements = never>(
-		options: PgBossLayerOptions<TRegistrations, TErrorRequirements>,
-	) {
-		type Requirements = Exclude<RegistrationRequirements<TRegistrations>, TIdentifier> | TErrorRequirements;
-		return Layer.unwrap(Effect.map(Effect.context<Requirements>(), (dependencies) => definition(options, dependencies).layer));
+	const Service: Context.Service<TIdentifier, PgBossService> = definition<never, never>({ jobs: [] }, Context.empty());
+	function layer<const TRegistrations extends readonly JobRegistration[], E = never>(
+		options: PgBossLayerOptions<TRegistrations, E>,
+	): Layer.Layer<
+		TIdentifier,
+		PgBossError | PgBossQueueNamesError | PgBossQueueOptionsError,
+		PgBoss | Exclude<RegistrationRequirements<TRegistrations>, TIdentifier> | E
+	>;
+	function layer<R = never, E = never>(options: PgBossLayerOptions<readonly JobRegistration<R>[], E>) {
+		return Layer.unwrap(Effect.map(Effect.context<Exclude<R, TIdentifier> | E>(), (dependencies) => definition(options, dependencies).layer));
 	}
 	return Object.assign(Service, { layer });
 }

package/src/server/testing.ts

@@ -1,4 +1,4 @@
-import { type DateTime, Duration, Effect, Redacted } from "effect";
+import { type DateTime, Duration, Effect, Redacted, type Tracer } from "effect";
 import type { PgBoss } from "pg-boss";
 import { testingDueNow } from "#adapters/testingDueNow.ts";
 import type { PgBossClientFactory } from "#client.ts";
@@ -22,7 +22,7 @@ export interface UnfinishedJob<TQueue extends SnapshotQueue> {
 	readonly id: string;
 	readonly queue: TQueue["name"];
 	readonly startAfter: DateTime.Utc;
-	readonly state: "active" | "created" | "failed" | "retry";
+	readonly state: "active" | "created" | "deferred" | "failed" | "retry";
 }
 
 export interface PgBossTestingWaitOptions {
@@ -35,6 +35,17 @@ export interface PgBossTestingOptions {
 	readonly retryPolicy?: typeof testRetryPolicy;
 }
 
+export function linkedWorkerSpans(sender: Pick<Tracer.AnySpan, "spanId" | "traceId">, spans: readonly Tracer.Span[]) {
+	return Effect.sync(() =>
+		spans.filter(
+			(span) =>
+				span.kind === "consumer"
+				&& span.attributes.get("messaging.system") === "pg-boss"
+				&& span.links.some((link) => link.span.spanId === sender.spanId && link.span.traceId === sender.traceId),
+		),
+	);
+}
+
 export function makePgBossTesting(options: PgBossTestingOptions = {}) {
 	let current: PgBoss | undefined;
 	let fetches: TestingFetches | undefined;