@shivaedev/jobs 0.29.2 → 0.31.0

package/src/server/client.ts

@@ -1,39 +1,92 @@
-import type {
-	ConstructorOptions,
-	FindJobsOptions,
-	Job,
-	JobWithMetadata,
-	PgBoss,
-	Queue,
-	QueueResult,
-	ScheduleOptions,
-	SendOptions,
-	StopOptions,
-	WorkOptions,
-} from "pg-boss";
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+import type { ClientOptions, StopOptions } from "#server/clientOptions.ts";
+import type { EnqueueOptions, ScheduleOptions } from "#server/enqueueOptions.ts";
+import type { Job, WorkerJob } from "#server/job.ts";
+import type { QueueOptions } from "#server/queueOptions.ts";
+import type { WorkerOptions } from "#server/workerOptions.ts";
+
+export interface JobReadOptions {
+	readonly after?: string;
+	readonly data?: object;
+	readonly db?: ClientDatabase;
+	readonly id?: string;
+	readonly key?: string;
+	readonly limit?: number;
+	readonly queued?: boolean;
+}
+
+export interface ClientQueueOptions extends Omit<QueueOptions, "maxDeferrals" | "policy"> {
+	readonly deadLetter?: string;
+	readonly policy?: string;
+}
+
+export interface ClientQueue extends ClientQueueOptions {
+	readonly activeCount: number;
+	readonly blockedCount: number;
+	readonly deferredCount: number;
+	readonly failedCount: number;
+	readonly name: string;
+	readonly queuedCount: number;
+	readonly readyCount: number;
+	readonly totalCount: number;
+}
+
+export type JobTarget = string | string[] | { id: string; retryCount: number } | { id: string; retryCount: number }[];
+export interface ClientConnectionOptions {
+	readonly db?: ClientDatabase;
+}
+export interface ClientUpdateOptions extends Omit<EnqueueOptions, "singletonSeconds" | "singletonNextSlot"> {
+	readonly match?: "newest" | "oldest" | "all";
+}
+export interface ClientUpdateRequest {
+	data?: object | null;
+	name: string;
+	options?: ClientUpdateOptions;
+}
+export interface ClientUpdateResult {
+	jobs: string[];
+	updated: number;
+}
 
 export interface PgBossClient {
-	readonly complete?: PgBoss["complete"];
-	readonly createQueue: (name: string, options?: Omit<Queue, "name">) => Promise<void>;
-	readonly deleteQueue?: PgBoss["deleteQueue"];
-	readonly fail?: PgBoss["fail"];
-	readonly findJobs?: (name: string, options?: FindJobsOptions) => Promise<readonly JobWithMetadata<unknown>[]>;
-	readonly getDb?: PgBoss["getDb"];
-	readonly getQueue: (name: string) => Promise<QueueResult | null>;
-	readonly getWipData?: PgBoss["getWipData"];
-	readonly notifyWorker?: PgBoss["notifyWorker"];
+	readonly complete?: (
+		name: string,
+		id: JobTarget,
+		data?: object | null,
+		options?: ClientConnectionOptions & { includeQueued?: boolean },
+	) => Promise<object>;
+	readonly createQueue: (name: string, options?: ClientQueueOptions) => Promise<void>;
+	readonly deleteQueue?: (name: string) => Promise<void>;
+	readonly fail?: (name: string, id: JobTarget, data?: object | null, options?: ClientConnectionOptions) => Promise<object>;
+	readonly findJobs?: (name: string, options?: JobReadOptions) => Promise<readonly Job<unknown>[]>;
+	readonly getDb?: () => ClientDatabase;
+	readonly getQueue: (name: string) => Promise<ClientQueue | null>;
+	readonly getSchedule?: (name: string, key?: string) => Promise<{ readonly name: string; readonly key: string } | null>;
+	readonly getWipData?: (options?: { includeInternal?: boolean }) => { id: string; workId: string; name: string; count: number }[];
+	readonly notifyWorker?: (workerId: string) => void;
 	readonly off: (event: "error", listener: (error: Error) => void) => unknown;
-	readonly offWork: PgBoss["offWork"];
+	readonly offWork: (name: string, options?: { id?: string; wait?: boolean }) => Promise<void>;
 	readonly on: (event: "error", listener: (error: Error) => void) => unknown;
-	readonly retry?: PgBoss["retry"];
+	readonly retry?: (name: string, id: string | string[], options?: ClientConnectionOptions) => Promise<object>;
 	readonly schedule: (name: string, cron: string, data?: object | null, options?: ScheduleOptions) => Promise<void>;
-	readonly send: (name: string, data?: object | null, options?: SendOptions) => Promise<string | null>;
+	readonly send: (name: string, data?: object | null, options?: EnqueueOptions) => Promise<string | null>;
 	readonly start: () => Promise<unknown>;
 	readonly stop: (options?: StopOptions) => Promise<void>;
-	readonly unschedule?: PgBoss["unschedule"];
-	readonly update?: PgBoss["update"];
-	readonly updateQueue?: PgBoss["updateQueue"];
-	readonly work: (name: string, options: WorkOptions, handler: (jobs: readonly Job<unknown>[]) => Promise<unknown>) => Promise<string>;
+	readonly supervise?: (name?: string) => Promise<void>;
+	readonly unschedule?: (name: string, key?: string, options?: ClientConnectionOptions) => Promise<void>;
+	readonly update?: {
+		(request: ClientUpdateRequest): Promise<ClientUpdateResult>;
+		(name: string, data: object | null | undefined, options?: ClientUpdateOptions): Promise<ClientUpdateResult>;
+	};
+	readonly updateQueue?: (
+		name: string,
+		options: Omit<QueueOptions, "policy" | "partition" | "maxDeferrals" | "heartbeatSeconds" | "retryDelayMax"> & {
+			deadLetter?: string | null;
+			heartbeatSeconds?: number | null;
+			retryDelayMax?: number | null;
+		},
+	) => Promise<void>;
+	readonly work: (name: string, options: WorkerOptions, handler: (jobs: readonly WorkerJob<unknown>[]) => Promise<unknown>) => Promise<string>;
 }
 
-export type PgBossClientFactory = (options: ConstructorOptions) => PgBossClient;
+export type PgBossClientFactory = (options: ClientOptions) => PgBossClient;

package/src/server/clientOptions.ts

@@ -0,0 +1,81 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+
+export interface ClientOptions {
+	"__test__enableSpies"?: boolean;
+	allowSchemaCaseVariant?: boolean;
+	"application_name"?: string;
+
+	backend?: "postgres" | "cockroachdb" | "yugabytedb" | "citus" | "pglite";
+	bamIntervalSeconds?: number;
+
+	clock?: Clock;
+	clockMonitorIntervalSeconds?: number;
+	connectionString?: string;
+	connectionTimeoutMillis?: number;
+	createSchema?: boolean;
+	cronMonitorIntervalSeconds?: number;
+	cronWorkerIntervalSeconds?: number;
+	database?: string;
+	db?: ClientDatabase;
+	flowIntervalSeconds?: number;
+	host?: string;
+	instanceHeartbeatSeconds?: number;
+	instanceName?: string;
+	maintenanceIntervalSeconds?: number;
+	max?: number;
+	migrate?: boolean;
+	monitorIntervalSeconds?: number;
+	monitorVacuum?: boolean;
+	notifyHeartbeatIntervalMs?: number;
+	notifyHeartbeatTimeoutMs?: number;
+	notifyKeepAliveInitialDelayMs?: number;
+	openTelemetry?: { enabled?: boolean; propagateContext?: boolean };
+	options?: string;
+	password?: string | (() => string | Promise<string>);
+	persistQueueStats?: boolean;
+	persistWarnings?: boolean;
+	port?: number;
+	queueCacheIntervalSeconds?: number;
+	queueStatRetentionDays?: number;
+
+	registerInstance?: boolean;
+	reindex?: boolean | ReindexOptions;
+	reindexIntervalSeconds?: number;
+
+	schedule?: boolean;
+	schema?: string;
+	ssl?: boolean | import("node:tls").ConnectionOptions;
+
+	supervise?: boolean;
+	superviseIntervalSeconds?: number;
+	useListenNotify?: boolean;
+	user?: string;
+	warningQueueSize?: number;
+	warningRetentionDays?: number;
+	warningSlowQuerySeconds?: number;
+}
+
+export interface ReindexOptions extends IndexBloatOptions {
+	force?: boolean;
+	maxIndexBytes?: number;
+}
+
+export interface IndexBloatOptions {
+	maxEntriesPerPage?: number;
+	minPages?: number;
+	minSizeRatio?: number;
+}
+
+export interface Clock {
+	clearInterval: (handle: unknown) => void;
+	clearTimeout: (handle: unknown) => void;
+	now: () => number;
+	setInterval: (fn: () => void, ms: number) => unknown;
+	setTimeout: (fn: () => void, ms: number) => unknown;
+}
+
+export interface StopOptions {
+	close?: boolean;
+	graceful?: boolean;
+	timeout?: number;
+}

package/src/server/defineSchedule.ts

@@ -1,9 +1,10 @@
-import type { DefineScheduleOptions, ScheduleDefinition } from "#definition.ts";
-import { maxDeferrals, nativeQueueOptions } from "#internal/definitionOptions.ts";
+import type { DefineScheduleOptions, ScheduleDefinition } from "#server/definition.ts";
+import { maxDeferrals, nativeQueueOptions } from "#server/internal/definitionOptions.ts";
 
 export function defineSchedule<const TName extends string>(options: DefineScheduleOptions<TName>): ScheduleDefinition<TName> {
 	const definition: ScheduleDefinition<TName> = {
 		_tag: "ScheduleDefinition",
+		...(options.label === undefined ? {} : { label: options.label }),
 		cron: options.cron,
 		maxDeferrals: maxDeferrals(options.queue),
 		name: options.name,

package/src/server/definition.ts

@@ -1,18 +1,16 @@
 import { Clock, Duration, Effect, Schema } from "effect";
-import type { Job, policies, Queue, ScheduleOptions, WorkOptions } from "pg-boss";
-import { maxDeferrals, nativeQueueOptions } from "#internal/definitionOptions.ts";
+import type { QueueDisplay, SubjectColumn } from "#display.ts";
+import type { ScheduleOptions } from "#server/enqueueOptions.ts";
+import { maxDeferrals, nativeQueueOptions } from "#server/internal/definitionOptions.ts";
+import type { WorkerJob } from "#server/job.ts";
+import type { QueueOptions, QueuePolicy } from "#server/queueOptions.ts";
+import type { WorkerOptions } from "#server/workerOptions.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;
 	readonly Type: object;
@@ -29,7 +27,7 @@ export interface JobContext {
 	readonly signal: AbortSignal;
 }
 
-export interface QueueDefinition<TName extends string = string, TPayload extends JobPayloadSchema = JobPayloadSchema> {
+export interface QueueDefinition<TName extends string = string, TPayload extends JobPayloadSchema = JobPayloadSchema> extends QueueDisplay {
 	readonly _tag: "QueueDefinition";
 	readonly handle: <E, R>(
 		handler: (payload: Schema.Schema.Type<TPayload>, job: JobContext) => Effect.Effect<unknown, E, R>,
@@ -37,9 +35,9 @@ export interface QueueDefinition<TName extends string = string, TPayload extends
 	readonly key?: ((payload: Schema.Schema.Type<TPayload>) => string) | undefined;
 	readonly maxDeferrals: number;
 	readonly name: TName;
-	readonly queueOptions: Omit<Queue, "name" | "deadLetter">;
+	readonly queueOptions: Omit<QueueOptions, "maxDeferrals">;
 	readonly schema: TPayload;
-	readonly workerOptions: WorkOptions;
+	readonly workerOptions: WorkerOptions;
 }
 
 export interface QueueWorker<TPayload extends JobPayloadSchema = JobPayloadSchema, TRequirements = unknown> {
@@ -48,19 +46,20 @@ 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> {
+export interface ScheduleDefinition<TName extends string = string> extends QueueDisplay {
 	readonly _tag: "ScheduleDefinition";
 	readonly cron: string;
 	readonly maxDeferrals: number;
 	readonly name: TName;
-	readonly queueOptions: Omit<Queue, "name" | "deadLetter">;
+	readonly queueOptions: Omit<QueueOptions, "maxDeferrals">;
 	readonly run: <E, R>(effect: Effect.Effect<unknown, E, R>) => ScheduledWorker<R>;
 	readonly scheduleOptions: ScheduleOptions;
-	readonly workerOptions: WorkOptions;
+	readonly workerOptions: WorkerOptions;
 }
 
 export interface ScheduledWorker<TRequirements = unknown> {
@@ -78,9 +77,11 @@ export type RegistrationRequirements<TRegistrations extends readonly JobRegistra
 	: never;
 
 export type DefineQueueOptions<TName extends string, TPayload extends JobPayloadSchema> = {
+	readonly label?: string;
 	readonly name: TName;
 	readonly schema: TPayload;
-	readonly worker?: WorkOptions;
+	readonly subject?: readonly SubjectColumn<NoInfer<TPayload>>[];
+	readonly worker?: WorkerOptions;
 } & (
 	| { 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"> } }
@@ -101,6 +102,8 @@ export function defineQueue<const TName extends string, const TPayload extends J
 	const definition: QueueDefinition<TName, TPayload> = {
 		_tag: "QueueDefinition",
 		...(options.key === undefined ? {} : { key: options.key }),
+		...(options.label === undefined ? {} : { label: options.label }),
+		...(options.subject === undefined ? {} : { subject: Object.freeze(options.subject.map((column) => Object.freeze({ ...column }))) }),
 		handle: (handler) =>
 			Object.freeze({
 				_tag: "QueueWorker" as const,
@@ -118,13 +121,14 @@ export function defineQueue<const TName extends string, const TPayload extends J
 
 export interface DefineScheduleOptions<TName extends string> {
 	readonly cron: string;
+	readonly label?: string;
 	readonly name: TName;
 	readonly queue?: QueueOptions;
 	readonly schedule?: ScheduleOptions;
-	readonly worker?: WorkOptions;
+	readonly worker?: WorkerOptions;
 }
 
-export function jobContext(job: Job<unknown>, deadline: number, deferralCount = 0): JobContext {
+export function jobContext(job: WorkerJob<unknown>, deadline: number, deferralCount = 0): JobContext {
 	return {
 		deferralCount,
 		expireInSeconds: job.expireInSeconds,

package/src/server/engineClient.ts

@@ -0,0 +1,24 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+import type { JobReadOptions, PgBossClient } from "#server/client.ts";
+import type { ScheduleOptions } from "#server/enqueueOptions.ts";
+import type { Job } from "#server/job.ts";
+
+export interface EngineSchedule {
+	cron: string;
+	data?: object;
+	key: string;
+	name: string;
+	options?: ScheduleOptions;
+	timezone: string;
+}
+
+export interface EngineClient extends Required<PgBossClient> {
+	readonly emit: (event: "error", error: Error) => boolean;
+	readonly findJobs: <T = unknown>(name: string, options?: JobReadOptions) => Promise<Job<T>[]>;
+	readonly getDb: () => ClientDatabase;
+	readonly getJobById: <T = unknown>(name: string, id: string) => Promise<Job<T> | null>;
+	readonly getSchedules: (name?: string, key?: string) => Promise<EngineSchedule[]>;
+	readonly getSpy: (name: string) => { clear: () => void; waitForJob: (selector: () => boolean, state: "completed" | "failed") => Promise<unknown> };
+	readonly schemaVersion: () => Promise<number | null>;
+	readonly supervise: (name?: string) => Promise<void>;
+}

package/src/server/enqueueOptions.ts

@@ -0,0 +1,20 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+import type { RetryOptions } from "#server/queueOptions.ts";
+
+export interface EnqueueOptions extends RetryOptions {
+	readonly db?: ClientDatabase;
+	readonly deadLetter?: string;
+	readonly group?: { readonly id: string; readonly tier?: string };
+	readonly id?: string;
+	readonly priority?: number;
+	readonly singletonKey?: string;
+	readonly singletonNextSlot?: boolean;
+	readonly singletonSeconds?: number;
+	readonly startAfter?: number | string | Date;
+}
+
+export interface ScheduleOptions extends EnqueueOptions {
+	readonly key?: string;
+	readonly missed?: "skip" | "once";
+	readonly tz?: string;
+}

package/src/server/error.ts

@@ -1,19 +1,34 @@
 import { Cause, Data, Duration, Redacted } from "effect";
-import { failureOutput } from "#internal/failureOutput.ts";
+import { failureOutput } from "#server/internal/failureOutput.ts";
 
 export type PgBossOperation =
 	| "counts"
 	| "deadLetteredJobs"
+	| "deleteQueue"
 	| "enqueue"
 	| "failedJobs"
 	| "getJob"
 	| "health"
 	| "install"
 	| "register"
+	| "refreshQueueStats"
 	| "retry"
 	| "settle"
 	| "start"
-	| "stop";
+	| "stop"
+	| "unschedule";
+
+export class PgBossNotFoundError extends Data.TaggedError("PgBossNotFoundError")<{
+	readonly operation: "deleteQueue" | "unschedule";
+	readonly queue: string;
+	readonly key?: string;
+}> {
+	override get message(): string {
+		return this.operation === "deleteQueue"
+			? `Queue ${this.queue} does not exist`
+			: `Schedule ${this.queue} with key ${JSON.stringify(this.key ?? "")} does not exist`;
+	}
+}
 
 export class PgBossError extends Data.TaggedError("PgBossError")<{
 	readonly operation: PgBossOperation;

package/src/server/health.ts

@@ -1,6 +1,6 @@
 import type { DateTime, Option } from "effect";
-import type { JobWithMetadata } from "pg-boss";
 import type { JobFailure } from "#JobFailure.ts";
+import type { JobState } from "#server/job.ts";
 
 export interface QueueCounts {
 	readonly activeCount: number;
@@ -42,7 +42,7 @@ export interface ListedJob<TData> {
 	readonly retryCount: number;
 	readonly retryLimit: number;
 	readonly startedOn: Option.Option<DateTime.Utc>;
-	readonly state: JobWithMetadata["state"];
+	readonly state: JobState;
 }
 
 export interface DeadLetteredJob<TData> extends ListedJob<TData> {

package/src/server/internal/acquireClient.ts

@@ -0,0 +1,26 @@
+import { Effect, Redacted } from "effect";
+import { clientErrorLogger } from "#server/adapters/clientErrorLogger.ts";
+import type { PgBossOptions } from "#server/service.ts";
+import { ClientEngine } from "./lifecycle.ts";
+
+export const acquireClient = Effect.fnUntraced(function* (options: PgBossOptions) {
+	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) }),
+	};
+	const report = yield* clientErrorLogger();
+	const engine = yield* ClientEngine;
+	const acquired = yield* engine.acquire(
+		{
+			clientCacheKey,
+			clientFactory,
+			constructor: constructorOptions,
+		},
+		report,
+		stop,
+	);
+	return { ...acquired, schema: settings.schema, stop };
+});

package/src/server/internal/adapters/testingFetches.ts

@@ -1,4 +1,4 @@
-import type { PgBoss } from "pg-boss";
+import type { EngineClient } from "#server/engineClient.ts";
 
 // pg-boss offers no hook for a worker fetch that finds nothing, so the controller recognizes its claim statement on the client's database.
 const claim = /UPDATE\s+\S+\s+j\s+SET\s+state\s*=\s*'active'/u;
@@ -9,7 +9,7 @@ export interface TestingFetches {
 	readonly passedSince: (queue: string, begun: number) => number;
 }
 
-export function testingFetches(db: ReturnType<PgBoss["getDb"]>, changed: () => void): TestingFetches {
+export function testingFetches(db: ReturnType<EngineClient["getDb"]>, changed: () => void): TestingFetches {
 	const begun = new Map<string, number>();
 	const passed = new Map<string, number[]>();
 	const executeSql = db.executeSql.bind(db);

package/src/server/internal/clientErrors.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
 import { isSensitiveKey, redactText } from "@shivaedev/errors/sensitive.ts";
-import type { PgBossClient } from "#client.ts";
+import type { PgBossClient } from "#server/client.ts";
 
 type Listener = (error: Error) => void;
 

package/src/server/internal/countsFor.ts

@@ -1,8 +1,8 @@
 import { Effect, Schema } from "effect";
-import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
-import type { QueueCounts } from "#health.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import type { QueueCounts } from "#server/health.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 const Counts = Schema.Struct({
 	activeCount: Schema.Number,
@@ -11,7 +11,7 @@ const Counts = Schema.Struct({
 	totalCount: Schema.Number,
 });
 
-export function countsFor(client: PgBossClient, schema: string, name: string): Effect.Effect<QueueCounts, import("#error.ts").PgBossError> {
+export function countsFor(client: PgBossClient, schema: string, name: string): Effect.Effect<QueueCounts, import("#server/error.ts").PgBossError> {
 	return Effect.tryPromise({
 		catch: (error) => toPgBossError("counts", error, name),
 		try: async () => {

package/src/server/internal/deadLetterResolutionPlan.ts

@@ -1,4 +1,4 @@
-import { quotedSchema } from "#internal/storedRows.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 export function deadLetterResolutionPlan(schema: string): string {
 	const quoted = quotedSchema(schema);

package/src/server/internal/deadlineOf.ts

@@ -1,6 +1,6 @@
-import type { Job } from "pg-boss";
+import type { WorkerJob } from "#server/job.ts";
 
-export function deadlineOf(job: Job<unknown>): number {
+export function deadlineOf(job: WorkerJob<unknown>): number {
 	if (!("startedOn" in job && job.startedOn instanceof Date && Number.isFinite(job.startedOn.getTime()))) {
 		throw new TypeError("Worker jobs must include pg-boss startedOn metadata");
 	}

package/src/server/internal/deferrableAttempt.ts

@@ -1,42 +1,25 @@
 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 { toPgBossError } from "#error.ts";
-import { deferralObservers, deferredAttempt } from "#internal/deferral.ts";
-import { settleDeferral } from "#internal/settleDeferral.ts";
+import { RetryAt } from "#server/definition.ts";
+import { deferredAttempt } from "#server/internal/deferral.ts";
+import { type JobAttempt, JobEngine } from "#server/internal/engine.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,
-) {
+export function deferrableAttempt<A, E, R>(effect: Effect.Effect<A, E, R>, job: JobAttempt, 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.tryPromise({
-				catch: (failure) => toPgBossError("settle", failure, job.name),
-				try: () => settleDeferral(client, schema, job, at, error.reason, maxDeferrals),
-			}).pipe(
+			return Effect.flatMap(JobEngine, (engine) => engine.settleDeferral(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

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
-import type { Job } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 export const deferredAttempt = Symbol("deferredAttempt");
 export const deferralObservers = new WeakMap<PgBossClient, () => void>();
@@ -13,7 +13,7 @@ export const Deferral = Schema.Struct({
 
 const Output = Schema.Struct({ jobDeferral: Deferral });
 
-export function deferralOf(job: Job<unknown>) {
+export function deferralOf(job: WorkerJob<unknown>) {
 	const output: unknown = Reflect.get(job, "output");
 	return Schema.is(Output)(output) ? output.jobDeferral : undefined;
 }

package/src/server/internal/deferralStorePlan.ts

@@ -1,5 +1,5 @@
-import { STATELY_DEFERRAL_POLICY } from "#internal/deferral.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
+import { STATELY_DEFERRAL_POLICY } from "#server/internal/deferral.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 export function deferralStorePlan(schema: string): string {
 	const quoted = quotedSchema(schema);

package/src/server/internal/definitionOptions.ts

@@ -1,4 +1,4 @@
-import type { QueueOptions } from "#definition.ts";
+import type { QueueOptions } from "#server/queueOptions.ts";
 
 export function maxDeferrals(options: QueueOptions | undefined): number {
 	const limit = options?.maxDeferrals ?? 10;

package/src/server/internal/engine.ts

@@ -0,0 +1,41 @@
+import { Context, type Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import type { PgBossError, PgBossTestingError } from "#server/error.ts";
+import type { PgBossService } from "#server/service.ts";
+
+export type StoredJob = Awaited<ReturnType<NonNullable<PgBossClient["findJobs"]>>>[number];
+export type JobAttempt = Pick<StoredJob, "name" | "id" | "retryCount">;
+export type Listing = "deadLetteredJobs" | "failedJobs";
+
+export class JobEngine extends Context.Service<
+	JobEngine,
+	Pick<PgBossService, "deleteQueue" | "refreshQueueStats" | "unschedule"> & {
+		readonly getJob: (queue: string, id: string) => Effect.Effect<StoredJob | undefined, PgBossError>;
+		readonly retry: (queue: string, id: string) => Effect.Effect<void, PgBossError>;
+		readonly listJobs: (
+			listing: Listing,
+			queue: string,
+			after: readonly [string, string] | undefined,
+			limit: number,
+		) => Effect.Effect<readonly unknown[], PgBossError>;
+		readonly settleDeferral: (
+			job: JobAttempt,
+			at: string,
+			reason: string,
+			maxDeferrals: number,
+		) => Effect.Effect<{ readonly claimed: boolean; readonly deferred: boolean }, PgBossError>;
+	}
+>()("@shivaedev/jobs/JobEngine") {}
+
+export interface TestingSettlements {
+	readonly close: Effect.Effect<void>;
+	readonly watch: (name: string) => Effect.Effect<void, PgBossTestingError>;
+}
+
+export class TestingEngine extends Context.Service<
+	TestingEngine,
+	{
+		readonly expireAttempt: (job: JobAttempt, cause?: "expiry" | "heartbeat") => Effect.Effect<void, PgBossTestingError>;
+		readonly observeSettlements: (settled: (name: string) => void) => Effect.Effect<TestingSettlements>;
+	}
+>()("@shivaedev/jobs/TestingEngine") {}