@shivaedev/jobs 0.29.2 → 0.31.0

package/src/server/internal/testingRegistrations.ts

@@ -0,0 +1,10 @@
+import type { PgBossClient } from "#server/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/testingSchedules.ts

@@ -1,8 +1,8 @@
-import type { PgBoss } from "pg-boss";
-import type { ScheduleDefinition } from "#definition.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
+import type { ScheduleDefinition } from "#server/definition.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import { testingOperation } from "#server/internal/testingReadout.ts";
 
-export function testingSchedules(client: () => PgBoss, changed: () => void) {
+export function testingSchedules(client: () => EngineClient, changed: () => void) {
 	return {
 		schedules: () =>
 			testingOperation("schedules", async () => (await client().getSchedules()).map(({ name, cron, timezone }) => ({ cron, name, timezone }))),

package/src/server/internal/testingSnapshot.ts

@@ -1,9 +1,9 @@
 import { Effect, Schema } from "effect";
-import type { PgBoss } from "pg-boss";
-import type { PgBossPayloadError, PgBossTestingError } from "#error.ts";
-import { decodeStoredData, quotedSchema } from "#internal/storedRows.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
-import type { SnapshotQueue, UnfinishedJob } from "#testing.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { PgBossPayloadError, PgBossTestingError } from "#server/error.ts";
+import { decodeStoredData, quotedSchema } from "#server/internal/storedRows.ts";
+import { testingOperation } from "#server/internal/testingReadout.ts";
+import type { SnapshotQueue, UnfinishedJob } from "#server/testing.ts";
 
 const Rows = Schema.Array(
 	Schema.Struct({
@@ -11,11 +11,11 @@ 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"]),
 	}),
 );
 
-export function testingSnapshot(client: () => PgBoss, schema: () => string) {
+export function testingSnapshot(client: () => EngineClient, schema: () => string) {
 	return <const TQueues extends readonly SnapshotQueue[]>(
 		queues: TQueues,
 	): Effect.Effect<
@@ -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/internal/testingWaits.ts

@@ -1,11 +1,12 @@
 import { Clock, Duration, Effect, Option, Redacted } from "effect";
-import type { JobWithMetadata, PgBoss } from "pg-boss";
-import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
-import { type PgBossPayloadError, PgBossTestingError, PgBossWaitError } from "#error.ts";
-import type { TestingFetches } from "#internal/adapters/testingFetches.ts";
-import { decodeStoredData } from "#internal/storedRows.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
-import type { PgBossTestingWaitOptions } from "#testing.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import { type PgBossPayloadError, PgBossTestingError, PgBossWaitError } from "#server/error.ts";
+import type { TestingFetches } from "#server/internal/adapters/testingFetches.ts";
+import { decodeStoredData } from "#server/internal/storedRows.ts";
+import { testingOperation } from "#server/internal/testingReadout.ts";
+import type { Job, JobState } from "#server/job.ts";
+import type { PgBossTestingWaitOptions } from "#server/testing.ts";
 
 interface Reading<A> {
 	readonly arrived: Option.Option<A>;
@@ -49,7 +50,7 @@ function fetchesRefused(queue: Pick<QueueDefinition, "name">, original: Error) {
 	return new PgBossTestingError({ operation: "fetchesPass", original: Redacted.make(original), queue: queue.name });
 }
 
-export function testingWaits(client: () => PgBoss, fetches: () => TestingFetches | undefined, signal: Signal) {
+export function testingWaits(client: () => EngineClient, fetches: () => TestingFetches | undefined, signal: Signal) {
 	return {
 		fetchesPass: (queue: Pick<QueueDefinition, "name">, count: number, options?: PgBossTestingWaitOptions) =>
 			Effect.gen(function* () {
@@ -75,14 +76,14 @@ export function testingWaits(client: () => PgBoss, fetches: () => TestingFetches
 		untilJob: <TName extends string, TPayload extends JobPayloadSchema>(
 			queue: Pick<QueueDefinition<TName, TPayload>, "name" | "schema">,
 			id: string,
-			state: JobWithMetadata["state"],
+			state: JobState,
 			options?: PgBossTestingWaitOptions,
 		) =>
 			waitUntil(
 				signal,
 				`job ${id} in ${queue.name} is ${state}`,
 				testingOperation("untilJob", () => client().getJobById<unknown>(queue.name, id), queue.name).pipe(
-					Effect.flatMap((job): Effect.Effect<Reading<JobWithMetadata<TPayload["Type"]>>, PgBossPayloadError, TPayload["DecodingServices"]> => {
+					Effect.flatMap((job): Effect.Effect<Reading<Job<TPayload["Type"]>>, PgBossPayloadError, TPayload["DecodingServices"]> => {
 						if (job === null) {
 							return Effect.succeed({ arrived: Option.none(), seen: "no such job" });
 						}

package/src/server/internal/tracing.ts

@@ -1,5 +1,5 @@
 import { Effect, Option, Schema, Tracer } from "effect";
-import type { Job } from "pg-boss";
+import type { WorkerJob } from "#server/job.ts";
 
 const TracedPayload = Schema.Struct({
 	_tag: Schema.Literal("@shivaedev/jobs/TracedPayload"),
@@ -25,7 +25,7 @@ export function payloadOf(data: unknown): unknown {
 	return isTracedPayload(data) ? data.payload : data;
 }
 
-export function traceJob<A, E, R>(effect: Effect.Effect<A, E, R>, job: Job<unknown>, queue: string) {
+export function traceJob<A, E, R>(effect: Effect.Effect<A, E, R>, job: WorkerJob<unknown>, queue: string) {
 	return Effect.withSpan(effect, queue, {
 		attributes: {
 			"job.attempt": job.retryCount + 1,

package/src/server/internal/validateQueueNames.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
-import type { JobRegistration } from "#definition.ts";
-import { PgBossQueueNamesError } from "#error.ts";
+import type { JobRegistration } from "#server/definition.ts";
+import { PgBossQueueNamesError } from "#server/error.ts";
 import { registrationName } from "./register.ts";
 
 export const validateQueueNames = Effect.fnUntraced(function* (jobs: readonly JobRegistration[], declared: readonly string[] | undefined) {

package/src/server/internal/waitForBatchExpiry.ts

@@ -1,12 +1,12 @@
 import { Clock, Effect } from "effect";
-import type { Job } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
-import { type PgBossError, toPgBossError } from "#error.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { type PgBossError, toPgBossError } from "#server/error.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 export function waitForBatchExpiry(
 	client: PgBossClient,
 	name: string,
-	jobs: readonly Job<unknown>[],
+	jobs: readonly WorkerJob<unknown>[],
 	deadline: number,
 ): Effect.Effect<void, PgBossError> {
 	return Effect.gen(function* () {

package/src/server/job.ts

@@ -0,0 +1,42 @@
+export type JobState = "created" | "retry" | "active" | "completed" | "cancelled" | "failed";
+
+export interface WorkerJob<T = unknown> {
+	data: T;
+	expireInSeconds: number;
+	groupId?: string | null;
+	groupTier?: string | null;
+	heartbeatSeconds: number | null;
+	id: string;
+	name: string;
+	retryCount: number;
+	signal: AbortSignal;
+}
+export interface Job<T = unknown> extends WorkerJob<T> {
+	blocked: boolean;
+	blocking: boolean;
+	completedOn: Date | null;
+	createdOn: Date;
+	deadLetter: string;
+	deleteAfterSeconds: number;
+	heartbeatOn: Date | null;
+	keepUntil: Date;
+	output: object | null;
+	pendingDependencies: number;
+	policy: string;
+	priority: number;
+	retryBackoff: boolean;
+	retryDelay: number;
+	retryDelayMax?: number;
+	retryLimit: number;
+	singletonKey: string | null;
+	singletonOn: Date | null;
+	sourceCreatedOn: Date | null;
+	sourceId: string | null;
+	sourceName: string | null;
+	sourceOutput: object | null;
+	sourceRetryCount: number | null;
+	sourceRootId: string | null;
+	startAfter: Date;
+	startedOn: Date | null;
+	state: JobState;
+}

package/src/server/jobModule.ts

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

package/src/server/queueOptions.ts

@@ -0,0 +1,20 @@
+export type QueuePolicy = "standard" | "short" | "singleton" | "stately" | "exclusive" | "key_strict_fifo";
+
+export interface RetryOptions {
+	deleteAfterSeconds?: number;
+	expireInSeconds?: number;
+	heartbeatSeconds?: number;
+	retentionSeconds?: number;
+	retryBackoff?: boolean;
+	retryDelay?: number;
+	retryDelayMax?: number;
+	retryLimit?: number;
+}
+
+export interface QueueOptions extends RetryOptions {
+	readonly maxDeferrals?: number;
+	readonly notify?: boolean;
+	readonly partition?: boolean;
+	readonly policy?: QueuePolicy;
+	readonly warningQueueSize?: number;
+}

package/src/server/readJobFailure.ts

@@ -0,0 +1,12 @@
+import { Effect, Redacted, Schema } from "effect";
+import { JobFailure } from "#JobFailure.ts";
+import { PgBossPayloadError } from "#server/error.ts";
+
+const StoredFailure = Schema.NullOr(Schema.Union([JobFailure, Schema.Struct({ value: JobFailure })]));
+
+export function readJobFailure(queue: string, output: unknown): Effect.Effect<JobFailure | null, PgBossPayloadError> {
+	return Schema.decodeUnknownEffect(StoredFailure)(output).pipe(
+		Effect.map((failure) => (failure !== null && "value" in failure ? failure.value : failure)),
+		Effect.mapError((error) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(error), queue })),
+	);
+}

package/src/server/schema.ts

@@ -2,12 +2,12 @@ import { Effect, Schema } from "effect";
 import { SqlClient } from "effect/sql";
 import pgBossPackage from "pg-boss/package.json" with { type: "json" };
 import type { SchemaComponent } from "@shivaedev/sql/SchemaComponent.ts";
-import { installSchema } from "#adapters/installSchema.ts";
-import { type PgBossError, toPgBossError } from "#error.ts";
+import { installSchema } from "#server/adapters/installSchema.ts";
+import { type PgBossError, toPgBossError } from "#server/error.ts";
 
 const InstalledSchema = Schema.Array(Schema.Struct({ name: Schema.NullOr(Schema.String) }));
 const InstalledVersion = Schema.Array(Schema.Struct({ version: Schema.Number }));
-const InstalledResolution = Schema.Array(Schema.Struct({ installed: Schema.Boolean }));
+const MissingArtifacts = Schema.Array(Schema.Struct({ name: Schema.String }));
 
 export interface PgBossSchemaOptions {
 	readonly schema?: string;
@@ -40,10 +40,21 @@ export function pgBossSchema(options: PgBossSchemaOptions = {}): SchemaComponent
 				return `schema ${schema}, installed version ${row?.version ?? "missing"}, required version ${required}`;
 			}
 			const job = sql`${sql(schema)}.${sql("job")}`;
-			const [resolution] = yield* sql`SELECT EXISTS (
-				SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass(${job.compile()[0]}) AND tgname = 'effect_dead_letter_resolution'
-			) AS installed`.withoutTransform.pipe(Effect.flatMap(Schema.decodeUnknownEffect(InstalledResolution)));
-			return resolution?.installed ? undefined : `schema ${schema}, missing dead-letter resolution trigger`;
+			const deferrals = sql`${sql(schema)}.${sql("effect_job_deferral")}`;
+			const cleanup = sql`${sql(schema)}.${sql("effect_job_deferral_keep_until")}`;
+			const stately = sql`${sql(schema)}.${sql("effect_stately_deferral")}()`;
+			const missing = yield* sql`SELECT name FROM (VALUES
+				('dead-letter resolution trigger', EXISTS (
+					SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass(${job.compile()[0]}) AND tgname = 'effect_dead_letter_resolution'
+				)),
+				('effect_job_deferral', to_regclass(${deferrals.compile()[0]}) IS NOT NULL),
+				('effect_job_deferral_keep_until', to_regclass(${cleanup.compile()[0]}) IS NOT NULL),
+				('effect_stately_deferral()', to_regprocedure(${stately.compile()[0]}) IS NOT NULL),
+				('effect_stately_deferral trigger', EXISTS (
+					SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass(${job.compile()[0]}) AND tgname = 'effect_stately_deferral'
+				))
+			) AS artifacts(name, installed) WHERE NOT installed`.withoutTransform.pipe(Effect.flatMap(Schema.decodeUnknownEffect(MissingArtifacts)));
+			return missing.length === 0 ? undefined : `schema ${schema}, missing ${missing.map(({ name }) => name).join(", ")}`;
 		}),
 	};
 }

package/src/server/service.ts

@@ -1,20 +1,32 @@
-import { Context, Effect, Exit, Layer, type Option, Redacted, type Schema, Scope } from "effect";
-import type { ConstructorOptions, JobWithMetadata, SendOptions, StopOptions } from "pg-boss";
+import { Context, Effect, Exit, Layer, type Option, type Redacted, type Schema, Scope } from "effect";
 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";
-import type { PgBossClientOptionsError, PgBossError, PgBossPayloadError, PgBossQueueNamesError, PgBossQueueOptionsError } from "#error.ts";
-import type { DeadLetteredJob, JobPage, JobPageOptions, JobsHealth, ListedJob, QueueCounts } from "#health.ts";
-import { logClientError, subscribeClientErrors } from "#internal/clientErrors.ts";
-import { acquireClient, releaseClient } from "#internal/lifecycle.ts";
-import { makeService } from "#internal/makeService.ts";
-import { registrationName } from "#internal/register.ts";
-import { registerReleasedJobs } from "#internal/registerReleasedJobs.ts";
-import { validateQueueNames } from "#internal/validateQueueNames.ts";
-import { PgBoss } from "#PgBoss.ts";
+import { clientErrorReporter } from "#server/adapters/clientErrorReporter.ts";
+import { jobEngine } from "#server/adapters/jobEngine.ts";
+import { clientEngine } from "#server/adapters/lifecycle.ts";
+import type { PgBossClientFactory } from "#server/client.ts";
+import type { ClientOptions, StopOptions } from "#server/clientOptions.ts";
+import type { JobPayloadSchema, JobRegistration, QueueDefinition, RegistrationRequirements, ScheduleDefinition } from "#server/definition.ts";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
+import type {
+	PgBossClientOptionsError,
+	PgBossError,
+	PgBossNotFoundError,
+	PgBossPayloadError,
+	PgBossQueueNamesError,
+	PgBossQueueOptionsError,
+} from "#server/error.ts";
+import type { DeadLetteredJob, JobPage, JobPageOptions, JobsHealth, ListedJob, QueueCounts } from "#server/health.ts";
+import { acquireClient } from "#server/internal/acquireClient.ts";
+import { logClientError, subscribeClientErrors } from "#server/internal/clientErrors.ts";
+import { JobEngine } from "#server/internal/engine.ts";
+import { ClientEngine } from "#server/internal/lifecycle.ts";
+import { makeService } from "#server/internal/makeService.ts";
+import { registrationName } from "#server/internal/register.ts";
+import { registerReleasedJobs } from "#server/internal/registerReleasedJobs.ts";
+import { validateQueueNames } from "#server/internal/validateQueueNames.ts";
+import type { Job } from "#server/job.ts";
+import { PgBoss } from "#server/PgBoss.ts";
 
 export interface PgBossService {
 	readonly counts: (queue: Pick<QueueDefinition, "name">) => Effect.Effect<QueueCounts, PgBossError>;
@@ -22,10 +34,11 @@ export interface PgBossService {
 		queue: { readonly name: TName; readonly schema: TPayload },
 		options: JobPageOptions,
 	) => Effect.Effect<JobPage<DeadLetteredJob<unknown>>, PgBossError | PgBossPayloadError | Schema.SchemaError, TPayload["DecodingServices"]>;
+	readonly deleteQueue: (queue: Pick<QueueDefinition, "name">) => Effect.Effect<void, PgBossError | PgBossNotFoundError>;
 	readonly enqueue: <const TName extends string, const TPayload extends JobPayloadSchema, const TQueue extends QueueDefinition<TName, TPayload>>(
 		queue: QueueDefinition<TName, TPayload> & TQueue,
 		payload: NoInfer<Schema.Schema.Type<TPayload>>,
-		options?: NoInfer<TQueue["key"] extends undefined ? SendOptions : Omit<SendOptions, "singletonKey"> & { readonly singletonKey?: never }>,
+		options?: NoInfer<TQueue["key"] extends undefined ? EnqueueOptions : Omit<EnqueueOptions, "singletonKey"> & { readonly singletonKey?: never }>,
 	) => Effect.Effect<Option.Option<string>, PgBossError | PgBossPayloadError, TPayload["EncodingServices"]>;
 	readonly failedJobs: <const TName extends string, const TPayload extends JobPayloadSchema | typeof Schema.Null>(
 		queue: { readonly name: TName; readonly schema: TPayload },
@@ -34,12 +47,14 @@ export interface PgBossService {
 	readonly getJob: <const TName extends string, const TPayload extends JobPayloadSchema | typeof Schema.Null>(
 		queue: { readonly name: TName; readonly schema: TPayload },
 		id: string,
-	) => Effect.Effect<Option.Option<JobWithMetadata<unknown>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]>;
+	) => Effect.Effect<Option.Option<Job<unknown>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]>;
 	readonly health: (queues?: readonly Pick<QueueDefinition, "name">[]) => Effect.Effect<JobsHealth, PgBossError>;
+	readonly refreshQueueStats: (queue?: Pick<QueueDefinition, "name">) => Effect.Effect<void, PgBossError>;
 	readonly retry: (queue: Pick<QueueDefinition, "name">, id: string) => Effect.Effect<void, PgBossError>;
+	readonly unschedule: (schedule: Pick<ScheduleDefinition, "name" | "scheduleOptions">) => Effect.Effect<void, PgBossError | PgBossNotFoundError>;
 }
 
-export type PgBossOptions = Omit<ConstructorOptions, "connectionString"> & {
+export type PgBossOptions = Omit<ClientOptions, "connectionString"> & {
 	readonly connectionString?: Redacted.Redacted<string>;
 	readonly idleTimeoutMillis?: number;
 	readonly maxLifetimeSeconds?: number;
@@ -49,31 +64,7 @@ export type PgBossOptions = Omit<ConstructorOptions, "connectionString"> & {
 };
 
 export function pgBossLayer(options: PgBossOptions): Layer.Layer<PgBoss, PgBossError | PgBossClientOptionsError> {
-	const { connectionString, clientFactory, clientCacheKey, stop, ...settings } = options;
-	const constructorOptions = {
-		...settings,
-		idleTimeoutMillis: settings.idleTimeoutMillis ?? 60_000,
-		maxLifetimeSeconds: settings.maxLifetimeSeconds ?? 600,
-		...(connectionString === undefined ? {} : { connectionString: Redacted.value(connectionString) }),
-	};
-	return Layer.effect(
-		PgBoss,
-		Effect.gen(function* () {
-			const report = yield* clientErrorLogger();
-			const acquired = yield* Effect.acquireRelease(
-				acquireClient(
-					{
-						clientCacheKey,
-						clientFactory,
-						constructor: constructorOptions,
-					},
-					report,
-				),
-				(client) => releaseClient(client, stop),
-			);
-			return { ...acquired, schema: settings.schema, stop };
-		}),
-	);
+	return Layer.effect(PgBoss, acquireClient(options)).pipe(Layer.provide(Layer.succeed(ClientEngine, clientEngine)));
 }
 
 export interface PgBossLayerOptions<TRegistrations extends readonly JobRegistration[], TErrorRequirements> {
@@ -93,43 +84,56 @@ 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* () {
 				yield* validateQueueNames(options.jobs, queueNames);
 				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, options.retired).pipe(
-					Effect.provideService(Scope.Scope, workerScope),
-					Effect.provide(dependencies),
+				const service = yield* makeService(acquired.client, options.jobs.map(registrationName), acquired.schema).pipe(
+					Effect.provideService(JobEngine, jobEngine(acquired.client, acquired.schema)),
 				);
+				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) => ({
 				counts: service.counts,
 				deadLetteredJobs: genericMethod(service.deadLetteredJobs),
+				deleteQueue: service.deleteQueue,
 				enqueue: genericMethod(service.enqueue),
 				failedJobs: genericMethod(service.failedJobs),
 				getJob: genericMethod(service.getJob),
 				health: service.health,
+				refreshQueueStats: service.refreshQueueStats,
 				retry: service.retry,
+				unschedule: service.unschedule,
 			}),
 			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,19 +1,10 @@
-import { type DateTime, Duration, Effect, Redacted } from "effect";
-import type { PgBoss } from "pg-boss";
-import { testingDueNow } from "#adapters/testingDueNow.ts";
-import type { PgBossClientFactory } from "#client.ts";
-import { defaultClientFactory } from "#defaultClientFactory.ts";
-import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
-import { PgBossTestingError } from "#error.ts";
-import { type TestingFetches, testingFetches } from "#internal/adapters/testingFetches.ts";
-import { testingClient } from "#internal/testingClient.ts";
-import { testingDeferrals } from "#internal/testingDeferrals.ts";
-import { type TestingWork, testingIdle } from "#internal/testingIdle.ts";
-import { testingOperation, testingReadout } from "#internal/testingReadout.ts";
-import { testingSchedules } from "#internal/testingSchedules.ts";
-import { testingSignal } from "#internal/testingSignal.ts";
-import { testingSnapshot } from "#internal/testingSnapshot.ts";
-import { testingWaits } from "#internal/testingWaits.ts";
+import { type DateTime, type Duration, Effect, type Tracer } from "effect";
+import { testingController } from "#server/adapters/testingController.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
+
+export function makePgBossTesting(options: PgBossTestingOptions = {}) {
+	return testingController(options);
+}
 
 export type SnapshotQueue = Pick<QueueDefinition<string, JobPayloadSchema>, "name" | "schema">;
 
@@ -22,7 +13,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,97 +26,15 @@ export interface PgBossTestingOptions {
 	readonly retryPolicy?: typeof testRetryPolicy;
 }
 
-export function makePgBossTesting(options: PgBossTestingOptions = {}) {
-	let current: PgBoss | undefined;
-	let fetches: TestingFetches | undefined;
-	let schema = "pgboss";
-	const signal = testingSignal();
-	const work: TestingWork = { batches: new Set(), queues: new Set() };
-	const controls = {
-		changed: signal.changed,
-		expirations: new Map<string, number>(),
-		expirySeconds: new Map<string, number>(),
-		failures: new Set<string>(),
-		retryPolicy: options.retryPolicy ?? {},
-		work,
-	};
-	function client(): PgBoss {
-		if (current === undefined) {
-			throw new Error("Provide the testing clientFactory to a jobs Layer first");
-		}
-		return current;
-	}
-	const clientFactory: PgBossClientFactory = (clientOptions) => {
-		if (current !== undefined) {
-			throw new Error("A testing controller owns one jobs client; create a controller per runtime");
-		}
-		schema = clientOptions.schema ?? "pgboss";
-		current = defaultClientFactory({ ...clientOptions, "__test__enableSpies": true });
-		fetches = testingFetches(current.getDb(), signal.changed);
-		return testingClient(current, clientOptions.schema ?? "pgboss", controls);
-	};
-	return {
-		...testingDeferrals(client),
-		...testingDueNow(client, () => schema, signal.changed),
-		...testingSchedules(client, signal.changed),
-		...testingWaits(client, () => fetches, signal),
-		checkBatchWindow: (queue: Pick<QueueDefinition, "name" | "workerOptions">, millisecondsPerJob: number) =>
-			testingOperation(
-				"checkBatchWindow",
-				async () => {
-					const stored = await client().getQueue(queue.name);
-					if (stored === null) {
-						throw new Error("Queue is not registered");
-					}
-					if (stored.expireInSeconds === undefined) {
-						throw new Error("Queue has no expiry window");
-					}
-					if (!Number.isFinite(millisecondsPerJob) || millisecondsPerJob < 0) {
-						throw new RangeError("Job duration must be nonnegative and finite");
-					}
-					const required = (queue.workerOptions.batchSize ?? 10) * millisecondsPerJob;
-					if (required >= stored.expireInSeconds * 1000) {
-						throw new Error("Sequential batch work must fit within the queue expiry window");
-					}
-				},
-				queue.name,
-			),
-		checkSchemaVersion: (expected: number) =>
-			testingOperation("checkSchemaVersion", async () => {
-				if ((await client().schemaVersion()) !== expected) {
-					throw new Error(`Expected pg-boss schema version ${expected}`);
-				}
-			}),
-		clientFactory,
-		expireAfter: (queue: Pick<QueueDefinition, "name">, attempts: number) =>
-			Effect.try({
-				catch: (original) => new PgBossTestingError({ operation: "expireAfter", original: Redacted.make(original), queue: queue.name }),
-				try: () => {
-					if (!Number.isSafeInteger(attempts) || attempts < 1) {
-						throw new RangeError("Attempts must be a positive integer");
-					}
-					controls.expirations.set(queue.name, attempts);
-				},
-			}),
-		expireIn: (queue: Pick<QueueDefinition, "name">, duration: Duration.Input) =>
-			Effect.try({
-				catch: (original) => new PgBossTestingError({ operation: "expireIn", original: Redacted.make(original), queue: queue.name }),
-				try: () => {
-					const milliseconds = Duration.toMillis(Duration.fromInputUnsafe(duration));
-					if (!Number.isFinite(milliseconds) || milliseconds < 1000) {
-						throw new RangeError("Expiry must be finite and at least one second");
-					}
-					controls.expirySeconds.set(queue.name, Math.ceil(milliseconds / 1000));
-				},
-			}),
-		failNextSend: (queue: Pick<QueueDefinition, "name">) => Effect.sync(() => controls.failures.add(queue.name)).pipe(Effect.asVoid),
-		jobs: testingReadout(client),
-		revision: signal.revision,
-		schemaVersion: testingOperation("schemaVersion", () => client().schemaVersion()),
-		snapshot: testingSnapshot(client, () => schema),
-		waitForChange: signal.waitForChange,
-		waitForIdle: testingIdle(client, () => schema, work, signal),
-	};
+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 type PgBossTesting = ReturnType<typeof makePgBossTesting>;