@shivaedev/jobs 0.29.2 → 0.31.0

package/src/server/adapters/jobEngine.ts

@@ -0,0 +1,59 @@
+import { type Context, Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deferralObservers } from "#server/internal/deferral.ts";
+import type { JobEngine } from "#server/internal/engine.ts";
+import { listJobs } from "./listJobs.ts";
+import { queueAdministration } from "./queueAdministration.ts";
+import { settleDeferral } from "./settleDeferral.ts";
+
+export function jobEngine(client: PgBossClient, schema = "pgboss"): Context.Service.Shape<typeof JobEngine> {
+	return {
+		...queueAdministration(client),
+		getJob: (queue, id) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("getJob", error, queue),
+				try: async () => {
+					if (client.findJobs === undefined) {
+						throw new TypeError("This pg-boss client does not support findJobs");
+					}
+					return (await client.findJobs(queue, { id }))[0];
+				},
+			}),
+		listJobs: listJobs(client, schema),
+		retry: (queue, id) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("retry", error, queue),
+				try: async () => {
+					if (client.findJobs === undefined || client.retry === undefined || client.update === undefined) {
+						throw new TypeError("This pg-boss client does not support findJobs, retry and update");
+					}
+					const job = (await client.findJobs(queue, { id }))[0];
+					if (job?.state !== "failed" && job?.state !== "retry") {
+						return;
+					}
+					if (job.state === "failed") {
+						await client.retry(queue, id);
+					}
+					await client.update(queue, undefined, { id, startAfter: 0 });
+				},
+			}),
+		settleDeferral: (job, at, reason, maxDeferrals) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("settle", error, job.name),
+				try: () => settleDeferral(client, schema, job, at, reason, maxDeferrals),
+			}).pipe(
+				Effect.tap((settled) =>
+					Effect.sync(() => {
+						if (!settled.claimed || settled.deferred) {
+							// 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)?.();
+						}
+					}),
+				),
+			),
+	};
+}

package/src/server/adapters/lifecycle.ts

@@ -0,0 +1,67 @@
+import { type Context, Effect, Exit, Scope } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import { PgBossClientOptionsError, toPgBossError } from "#server/error.ts";
+import { observeClientErrors } from "#server/internal/clientErrors.ts";
+import { jobStorePlans } from "#server/internal/jobStorePlans.ts";
+import type { AcquireClientOptions, ClientEngine } from "#server/internal/lifecycle.ts";
+import { acquireCachedClient, releaseCachedClient } from "./clientCache.ts";
+import { defaultClientFactory } from "./defaultClientFactory.ts";
+
+export interface StartingClient {
+	readonly client: PgBossClient;
+	readonly ready: Promise<void>;
+	readonly stop: (options?: StopOptions) => Promise<void>;
+}
+
+function startClient(options: AcquireClientOptions, report: (error: Error) => void): StartingClient {
+	const client = (options.clientFactory ?? defaultClientFactory)(options.constructor);
+	observeClientErrors(client, report);
+	let closing = false;
+	const ready = (async () => {
+		await client.start();
+		if (!closing && options.constructor.migrate !== false && client.getDb !== undefined) {
+			for (const plan of jobStorePlans(options.constructor.schema ?? "pgboss")) {
+				await client.getDb().executeSql(plan);
+			}
+		}
+	})();
+	return {
+		client,
+		ready,
+		stop: (settings) => {
+			closing = true;
+			return client.stop(settings);
+		},
+	};
+}
+
+const acquire = Effect.fnUntraced(function* (options: AcquireClientOptions, report: (error: Error) => void, stop?: StopOptions) {
+	const scope = yield* Scope.fork(yield* Scope.Scope);
+	return yield* Effect.gen(function* () {
+		const lease = yield* Effect.acquireRelease(
+			Effect.try({
+				catch: (error) => (error instanceof PgBossClientOptionsError ? error : toPgBossError("start", error)),
+				try: () =>
+					options.clientCacheKey === undefined
+						? { ...startClient(options, report), reused: false }
+						: acquireCachedClient(options.clientCacheKey, options.constructor, () => startClient(options, report)),
+			}),
+			(acquired) =>
+				Effect.tryPromise({
+					catch: (error) => toPgBossError("stop", error),
+					try: async () => {
+						const client = options.clientCacheKey === undefined ? acquired : releaseCachedClient(options.clientCacheKey);
+						await client?.stop(stop);
+					},
+				}).pipe(Effect.catch(Effect.logError)),
+		);
+		yield* Effect.tryPromise({ catch: (error) => toPgBossError("start", error), try: () => lease.ready });
+		return { ...(options.clientCacheKey === undefined ? {} : { cacheKey: options.clientCacheKey }), client: lease.client, reused: lease.reused };
+	}).pipe(
+		Effect.provideService(Scope.Scope, scope),
+		Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))),
+	);
+});
+
+export const clientEngine: Context.Service.Shape<typeof ClientEngine> = { acquire };

package/src/server/adapters/listJobs.ts

@@ -0,0 +1,43 @@
+import { type Context, Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deadLetterQueueName } from "#server/health.ts";
+import type { JobEngine } from "#server/internal/engine.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+
+export function listJobs(client: PgBossClient, schema: string): Context.Service.Shape<typeof JobEngine>["listJobs"] {
+	return (listing, queue, after, limit) =>
+		Effect.tryPromise({
+			catch: (error) => toPgBossError(listing, error, queue),
+			try: async () => {
+				if (client.getDb === undefined) {
+					throw new TypeError("This pg-boss client does not support getDb");
+				}
+				const quoted = quotedSchema(schema);
+				const { rows: storedRows } = await client.getDb().executeSql(
+					`SELECT
+					id,
+					name AS queue,
+					state,
+					retry_count AS "retryCount",
+					retry_limit AS "retryLimit",
+					created_on AS "createdOn",
+					started_on AS "startedOn",
+					completed_on AS "completedOn",
+					output,
+					data,
+					source_id AS "sourceId",
+					source_output AS "sourceOutput",
+					to_json(created_on) #>> '{}' AS "cursorAt"
+				FROM ${quoted}.job
+				WHERE name = $1
+					${listing === "failedJobs" ? "AND state = 'failed'" : ""}
+					AND ($2::timestamptz IS NULL OR (created_on, id) < ($2::timestamptz, $3::uuid))
+				ORDER BY created_on DESC, id DESC
+				LIMIT $4`,
+					[listing === "failedJobs" ? queue : deadLetterQueueName(queue), after?.[0] ?? null, after?.[1] ?? null, limit + 1],
+				);
+				return storedRows;
+			},
+		});
+}

package/src/server/{internal → adapters}/observeTestingSettlements.ts

@@ -1,6 +1,6 @@
-import type { PgBoss } from "pg-boss";
+import type { EngineClient } from "#server/engineClient.ts";
 
-export function observeTestingSettlements(client: PgBoss, settled: (name: string) => void) {
+export function observeTestingSettlements(client: EngineClient, settled: (name: string) => void) {
 	const observers = new Map<string, () => void>();
 	return {
 		close() {

package/src/server/adapters/queueAdministration.ts

@@ -0,0 +1,47 @@
+import { Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { PgBossNotFoundError, toPgBossError } from "#server/error.ts";
+import type { PgBossService } from "#server/service.ts";
+
+export function queueAdministration(client: PgBossClient): Pick<PgBossService, "deleteQueue" | "refreshQueueStats" | "unschedule"> {
+	return {
+		deleteQueue: (queue) =>
+			Effect.tryPromise({
+				catch: (error) => (error instanceof PgBossNotFoundError ? error : toPgBossError("deleteQueue", error, queue.name)),
+				try: async () => {
+					if (client.deleteQueue === undefined) {
+						throw new TypeError("This pg-boss client does not support deleteQueue");
+					}
+					if ((await client.getQueue(queue.name)) === null) {
+						throw new PgBossNotFoundError({ operation: "deleteQueue", queue: queue.name });
+					}
+					await client.offWork(queue.name);
+					await client.deleteQueue(queue.name);
+				},
+			}),
+		refreshQueueStats: (queue) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("refreshQueueStats", error, queue?.name),
+				try: async () => {
+					if (client.supervise === undefined) {
+						throw new TypeError("This pg-boss client does not support supervise");
+					}
+					await client.supervise(queue?.name);
+				},
+			}),
+		unschedule: (schedule) =>
+			Effect.tryPromise({
+				catch: (error) => (error instanceof PgBossNotFoundError ? error : toPgBossError("unschedule", error, schedule.name)),
+				try: async () => {
+					if (client.getSchedule === undefined || client.unschedule === undefined) {
+						throw new TypeError("This pg-boss client does not support getSchedule and unschedule");
+					}
+					const key = schedule.scheduleOptions.key ?? "";
+					if ((await client.getSchedule(schedule.name, key)) === null) {
+						throw new PgBossNotFoundError({ key, operation: "unschedule", queue: schedule.name });
+					}
+					await client.unschedule(schedule.name, key);
+				},
+			}),
+	};
+}

package/src/server/adapters/registerWorker.ts

@@ -1,17 +1,21 @@
 import { Effect, Fiber, Scope } from "effect";
-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";
-import { deferrableAttempt } from "#internal/deferrableAttempt.ts";
-import { retryWake } from "#internal/retryWake.ts";
-import { traceJob } from "#internal/tracing.ts";
+import { batchHandler } from "#server/adapters/batchHandler.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deferrableAttempt } from "#server/internal/deferrableAttempt.ts";
+import { JobEngine } from "#server/internal/engine.ts";
+import { retryWake } from "#server/internal/retryWake.ts";
+import { traceJob } from "#server/internal/tracing.ts";
+import type { WorkerJob } from "#server/job.ts";
+import type { WorkerOptions } from "#server/workerOptions.ts";
+import { jobEngine } from "./jobEngine.ts";
 
 export const registerWorker = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
 	name: string,
-	options: WorkOptions,
-	run: (job: Job<unknown>, deadline: number) => Effect.Effect<unknown, unknown, R>,
+	options: WorkerOptions,
+	run: (job: WorkerJob<unknown>, deadline: number) => Effect.Effect<unknown, unknown, R>,
 	scope: Scope.Scope,
 	schema: string,
 	maxDeferrals: number,
@@ -20,15 +24,22 @@ export const registerWorker = Effect.fnUntraced(function* <R>(
 	const execute = Effect.runPromiseWith(yield* Effect.context<R>());
 	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);
+	const engine = jobEngine(client, schema);
+	function runJob(job: WorkerJob<unknown>, deadline: number) {
+		return traceJob(deferrableAttempt(run(job, deadline), job, maxDeferrals).pipe(Effect.provideService(JobEngine, engine)), job, name);
 	}
-	function afterRetry(attempt: Job<unknown>) {
+	function afterRetry(attempt: WorkerJob<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, afterRetry),
+		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),

package/src/server/adapters/retireJobs.ts

@@ -1,9 +1,9 @@
 import { Effect } from "effect";
-import type { PgBossClient } from "#client.ts";
-import type { JobRegistration } from "#definition.ts";
-import { toPgBossError } from "#error.ts";
-import { deadLetterQueueName } from "#health.ts";
-import { registrationNames } from "#internal/register.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { JobRegistration } from "#server/definition.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deadLetterQueueName } from "#server/health.ts";
+import { registrationNames } from "#server/internal/register.ts";
 
 export const retireJobs = Effect.fnUntraced(function* (client: PgBossClient, jobs: readonly JobRegistration[], retired: readonly string[]) {
 	yield* Effect.try({

package/src/server/adapters/schemaIndexBuilds.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import type { PgBoss } from "pg-boss";
+import type { EngineClient } from "#server/engineClient.ts";
 
 const IndexBuilds = Schema.Array(Schema.Struct({ command: Schema.String, id: Schema.String }));
 const IndexValidity = Schema.Array(Schema.Struct({ invalid: Schema.Boolean }));
@@ -28,7 +28,7 @@ export function pendingIndexInserts(schema: string, version: number, commands: r
 		.join("\n");
 }
 
-export async function resumeSchemaIndexes(client: PgBoss, schema: string): Promise<void> {
+export async function resumeSchemaIndexes(client: EngineClient, schema: string): Promise<void> {
 	const db = client.getDb();
 	const { rows } = await db.executeSql(
 		`SELECT id, command FROM ${schema}.bam WHERE starts_with(name, $1) AND status <> 'completed' ORDER BY created_on, name`,

package/src/server/{internal → adapters}/settleDeferral.ts

@@ -1,12 +1,12 @@
 import { Schema } from "effect";
-import type { Job } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
-import { STATELY_DEFERRAL_POLICY } from "#internal/deferral.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { STATELY_DEFERRAL_POLICY } from "#server/internal/deferral.ts";
+import type { JobAttempt } from "#server/internal/engine.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 const Settlement = Schema.Struct({ claimed: Schema.Boolean, deferred: Schema.Boolean });
 
-export async function settleDeferral(client: PgBossClient, schema: string, job: Job<unknown>, at: string, reason: string, maxDeferrals: number) {
+export async function settleDeferral(client: PgBossClient, schema: string, job: JobAttempt, at: string, reason: string, maxDeferrals: number) {
 	if (client.getDb === undefined) {
 		throw new TypeError("This pg-boss client does not support getDb for RetryAt");
 	}

package/src/server/{internal → adapters}/testingClient.ts

@@ -1,33 +1,39 @@
-import type { Job, PgBoss, SendOptions, UpdateOptions, UpdateRequest, UpdateResponse } from "pg-boss";
-import { testingExpirations } from "#adapters/testingExpirations.ts";
-import type { PgBossClient } from "#client.ts";
-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 { Effect } from "effect";
+import { testingEngine } from "#server/adapters/testingEngine.ts";
+import { testingExpirations } from "#server/adapters/testingExpirations.ts";
+import type { ClientUpdateOptions, ClientUpdateRequest, ClientUpdateResult, PgBossClient } from "#server/client.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
+import { deferralObservers } from "#server/internal/deferral.ts";
+import type { TestingBatch, TestingWork } from "#server/internal/testingIdle.ts";
+import { testingRegistration } from "#server/internal/testingRegistrations.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 export interface TestingControls {
 	readonly changed: () => void;
 	readonly expirations: Map<string, number>;
 	readonly expirySeconds: Map<string, number>;
 	readonly failures: Set<string>;
-	readonly retryPolicy: Pick<SendOptions, "retryBackoff" | "retryDelay">;
+	readonly retryPolicy: Pick<EnqueueOptions, "retryBackoff" | "retryDelay">;
 	readonly work: TestingWork;
 }
 
-export function testingClient(client: PgBoss, schema: string, controls: TestingControls): PgBossClient {
-	const settlements = observeTestingSettlements(client, (name) => {
-		for (const batch of controls.work.batches) {
-			if (batch.name === name) {
-				batch.settled = true;
+export function testingClient(client: EngineClient, schema: string, controls: TestingControls): PgBossClient {
+	const engine = testingEngine(client, schema);
+	const settlements = Effect.runSync(
+		engine.observeSettlements((name) => {
+			for (const batch of controls.work.batches) {
+				if (batch.name === name) {
+					batch.settled = true;
+				}
 			}
-		}
-		controls.changed();
-	});
+			controls.changed();
+		}),
+	);
 	const expirations = testingExpirations(client);
-	function update(request: UpdateRequest): Promise<UpdateResponse>;
-	function update(name: string, data: object | null | undefined, options?: UpdateOptions): Promise<UpdateResponse>;
-	async function update(request: string | UpdateRequest, data?: object | null, options?: UpdateOptions): Promise<UpdateResponse> {
+	function update(request: ClientUpdateRequest): Promise<ClientUpdateResult>;
+	function update(name: string, data: object | null | undefined, options?: ClientUpdateOptions): Promise<ClientUpdateResult>;
+	async function update(request: string | ClientUpdateRequest, data?: object | null, options?: ClientUpdateOptions): Promise<ClientUpdateResult> {
 		const result = typeof request === "string" ? await client.update(request, data, options) : await client.update(request);
 		controls.changed();
 		return result;
@@ -82,7 +88,7 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 			try {
 				await client.stop(options);
 			} finally {
-				settlements.close();
+				await Effect.runPromise(settlements.close);
 			}
 		},
 		update,
@@ -92,19 +98,18 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 				...controls.retryPolicy,
 				...(controls.retryPolicy.retryBackoff === false ? { retryDelayMax: null } : {}),
 			}),
-		work: (name, options, handler) => {
-			settlements.watch(name);
-			controls.work.queues.add(name);
-			return client.work(name, options, async (jobs: Job<unknown>[]) => {
+		work: async (name, options, handler) => {
+			await Effect.runPromise(settlements.watch(name));
+			return client.work(name, options, async (jobs: readonly WorkerJob<unknown>[]) => {
 				const batch: TestingBatch = { name, settled: false };
 				controls.work.batches.add(batch);
 				controls.changed();
 				try {
-					const ready: Job<unknown>[] = [];
+					const ready: WorkerJob<unknown>[] = [];
 					for (const job of jobs) {
 						const attempts = await expirations.attemptsFor(job);
 						if (attempts !== undefined && job.retryCount + 1 >= attempts) {
-							await expireAttempt(client, schema, job);
+							await Effect.runPromise(engine.expireAttempt(job));
 						} else {
 							ready.push(job);
 						}
@@ -121,6 +126,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/adapters/testingController.ts

@@ -0,0 +1,109 @@
+import { Duration, Effect, Redacted } from "effect";
+import { defaultClientFactory } from "#server/adapters/defaultClientFactory.ts";
+import { testingClient } from "#server/adapters/testingClient.ts";
+import { testingDueNow } from "#server/adapters/testingDueNow.ts";
+import type { PgBossClientFactory } from "#server/client.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import { PgBossTestingError } from "#server/error.ts";
+import { type TestingFetches, testingFetches } from "#server/internal/adapters/testingFetches.ts";
+import { testingDeferrals } from "#server/internal/testingDeferrals.ts";
+import { type TestingWork, testingIdle } from "#server/internal/testingIdle.ts";
+import { testingOperation, testingReadout } from "#server/internal/testingReadout.ts";
+import { testingSchedules } from "#server/internal/testingSchedules.ts";
+import { testingSignal } from "#server/internal/testingSignal.ts";
+import { testingSnapshot } from "#server/internal/testingSnapshot.ts";
+import { testingWaits } from "#server/internal/testingWaits.ts";
+import type { PgBossTestingOptions } from "#server/testing.ts";
+export function testingController(options: PgBossTestingOptions = {}) {
+	let current: EngineClient | 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(): EngineClient {
+		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),
+	};
+}

package/src/server/adapters/testingDueNow.ts

@@ -1,9 +1,9 @@
-import type { PgBoss } from "pg-boss";
-import type { QueueDefinition } from "#definition.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+import { testingOperation } from "#server/internal/testingReadout.ts";
 
-export function testingDueNow(client: () => PgBoss, schema: () => string, changed: () => void) {
+export function testingDueNow(client: () => EngineClient, schema: () => string, changed: () => void) {
 	function makeDue(queue: Pick<QueueDefinition, "name">, deferredOnly: boolean) {
 		return testingOperation(
 			deferredOnly ? "runDeferredNow" : "runDueNow",

package/src/server/adapters/testingEngine.ts

@@ -0,0 +1,28 @@
+import { type Context, Effect, Redacted } from "effect";
+import type { EngineClient } from "#server/engineClient.ts";
+import { PgBossTestingError } from "#server/error.ts";
+import type { TestingEngine } from "#server/internal/engine.ts";
+import { expireAttempt } from "./expireAttempt.ts";
+import { observeTestingSettlements } from "./observeTestingSettlements.ts";
+
+export function testingEngine(client: EngineClient, schema: string): Context.Service.Shape<typeof TestingEngine> {
+	return {
+		expireAttempt: (job, cause) =>
+			Effect.tryPromise({
+				catch: (original) => new PgBossTestingError({ operation: "expireAttempt", original: Redacted.make(original), queue: job.name }),
+				try: () => expireAttempt(client, schema, job, cause),
+			}),
+		observeSettlements: (settled) =>
+			Effect.sync(() => {
+				const observer = observeTestingSettlements(client, settled);
+				return {
+					close: Effect.sync(() => observer.close()),
+					watch: (name: string) =>
+						Effect.try({
+							catch: (original) => new PgBossTestingError({ operation: "observeSettlements", original: Redacted.make(original), queue: name }),
+							try: () => observer.watch(name),
+						}),
+				};
+			}),
+	};
+}

package/src/server/adapters/testingExpirations.ts

@@ -1,10 +1,12 @@
-import type { Job, PgBoss, SendOptions } from "pg-boss";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
+import type { WorkerJob } from "#server/job.ts";
 
-export function testingExpirations(client: PgBoss) {
+export function testingExpirations(client: EngineClient) {
 	const snapshots = new Map<string, Promise<number | undefined>>();
 	return {
-		attemptsFor: (job: Job<unknown>) => snapshots.get(`${job.name}:${job.id}`),
-		send(name: string, data: object | null | undefined, options: SendOptions, attempts: number | undefined) {
+		attemptsFor: (job: WorkerJob<unknown>) => snapshots.get(`${job.name}:${job.id}`),
+		send(name: string, data: object | null | undefined, options: EnqueueOptions, attempts: number | undefined) {
 			if (attempts === undefined && options.id === undefined) {
 				return client.send(name, data, options);
 			}

package/src/server/adapters/transactionDb.ts

@@ -1,8 +1,8 @@
 import { Effect, Option } from "effect";
 import { SqlClient } from "effect/sql";
-import type { SendOptions } from "pg-boss";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
 
-export const transactionDb: Effect.Effect<SendOptions["db"]> = Effect.gen(function* () {
+export const transactionDb: Effect.Effect<EnqueueOptions["db"]> = Effect.gen(function* () {
 	const sql = yield* Effect.serviceOption(SqlClient.SqlClient);
 	if (Option.isNone(sql)) {
 		return undefined;