@shivaedev/jobs 0.30.0 → 0.31.0

package/src/server/internal/jobStorePlans.ts

@@ -1,5 +1,5 @@
-import { deadLetterResolutionPlan } from "#internal/deadLetterResolutionPlan.ts";
-import { deferralStorePlan } from "#internal/deferralStorePlan.ts";
+import { deadLetterResolutionPlan } from "#server/internal/deadLetterResolutionPlan.ts";
+import { deferralStorePlan } from "#server/internal/deferralStorePlan.ts";
 
 export function jobStorePlans(schema: string): readonly string[] {
 	return [deferralStorePlan(schema), deadLetterResolutionPlan(schema)];

package/src/server/internal/lifecycle.ts

@@ -1,16 +1,12 @@
-import { Effect } from "effect";
-import type { ConstructorOptions, StopOptions } from "pg-boss";
-import type { PgBossClient, PgBossClientFactory } from "#client.ts";
-import { defaultClientFactory } from "#defaultClientFactory.ts";
-import { PgBossClientOptionsError, type PgBossError, toPgBossError } from "#error.ts";
-import { jobStorePlans } from "#internal/jobStorePlans.ts";
-import { acquireCachedClient, releaseCachedClient } from "./clientCache.ts";
-import { observeClientErrors } from "./clientErrors.ts";
+import { Context, type Effect, type Scope } from "effect";
+import type { PgBossClient, PgBossClientFactory } from "#server/client.ts";
+import type { ClientOptions, StopOptions } from "#server/clientOptions.ts";
+import type { PgBossClientOptionsError, PgBossError } from "#server/error.ts";
 
 export interface AcquireClientOptions {
 	readonly clientCacheKey?: string | symbol | undefined;
 	readonly clientFactory?: PgBossClientFactory | undefined;
-	readonly constructor: ConstructorOptions;
+	readonly constructor: ClientOptions;
 }
 
 export interface AcquiredClient {
@@ -19,50 +15,13 @@ export interface AcquiredClient {
 	readonly reused: boolean;
 }
 
-async function startClient(options: AcquireClientOptions, report: (error: Error) => void): Promise<PgBossClient> {
-	const client = (options.clientFactory ?? defaultClientFactory)(options.constructor);
-	observeClientErrors(client, report);
-	try {
-		await client.start();
-		if (options.constructor.migrate !== false && client.getDb !== undefined) {
-			for (const plan of jobStorePlans(options.constructor.schema ?? "pgboss")) {
-				await client.getDb().executeSql(plan);
-			}
-		}
-		return client;
-	} catch (error) {
-		try {
-			await client.stop();
-		} catch {
-			// Preserve the startup failure; stop is best effort on failed acquisition.
-		}
-		throw error;
+export class ClientEngine extends Context.Service<
+	ClientEngine,
+	{
+		readonly acquire: (
+			options: AcquireClientOptions,
+			report: (error: Error) => void,
+			stop?: StopOptions,
+		) => Effect.Effect<AcquiredClient, PgBossError | PgBossClientOptionsError, Scope.Scope>;
 	}
-}
-
-export function acquireClient(
-	options: AcquireClientOptions,
-	report: (error: Error) => void,
-): Effect.Effect<AcquiredClient, PgBossError | PgBossClientOptionsError> {
-	return Effect.tryPromise({
-		catch: (error) => (error instanceof PgBossClientOptionsError ? error : toPgBossError("start", error)),
-		try: async () => {
-			const cacheKey = options.clientCacheKey;
-			return cacheKey === undefined
-				? { client: await startClient(options, report), reused: false }
-				: { cacheKey, ...(await acquireCachedClient(cacheKey, options.constructor, () => startClient(options, report))) };
-		},
-	});
-}
-
-export function releaseClient(acquired: AcquiredClient, stopOptions?: StopOptions): Effect.Effect<void> {
-	return Effect.tryPromise({
-		catch: (error) => toPgBossError("stop", error),
-		try: async () => {
-			const client = acquired.cacheKey === undefined ? acquired.client : await releaseCachedClient(acquired.cacheKey);
-			if (client !== undefined) {
-				await client.stop(stopOptions);
-			}
-		},
-	}).pipe(Effect.catch((error) => Effect.logError(error)));
-}
+>()("@shivaedev/jobs/ClientEngine") {}

package/src/server/internal/makeService.ts

@@ -1,19 +1,27 @@
-import type { PgBossClient } from "#client.ts";
-import { countsFor } from "#internal/countsFor.ts";
-import { enqueueFor } from "#internal/enqueueFor.ts";
-import { healthFor } from "#internal/healthFor.ts";
-import { getJobFor, retryFor } from "#internal/jobControl.ts";
-import { deadLetteredJobsFor, failedJobsFor } from "#internal/listJobs.ts";
-import type { PgBossService } from "#service.ts";
+import { Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { countsFor } from "#server/internal/countsFor.ts";
+import { JobEngine } from "#server/internal/engine.ts";
+import { enqueueFor } from "#server/internal/enqueueFor.ts";
+import { healthFor } from "#server/internal/healthFor.ts";
+import { jobControl } from "#server/internal/jobControl.ts";
+import { jobListings } from "#server/internal/jobListings.ts";
+import type { PgBossService } from "#server/service.ts";
 
-export function makeService(client: PgBossClient, names: readonly string[], schema = "pgboss"): PgBossService {
+export const makeService = Effect.fnUntraced(function* (
+	client: PgBossClient,
+	names: readonly string[],
+	schema = "pgboss",
+): Effect.fn.Return<PgBossService, never, JobEngine> {
+	const engine = yield* JobEngine;
 	return {
 		counts: (queue) => countsFor(client, schema, queue.name),
-		deadLetteredJobs: deadLetteredJobsFor(client, schema),
+		deleteQueue: engine.deleteQueue,
+		...(yield* jobListings),
 		enqueue: enqueueFor(client),
-		failedJobs: failedJobsFor(client, schema),
-		getJob: getJobFor(client),
+		...(yield* jobControl),
 		health: (queues) => healthFor(client, queues === undefined ? names : queues.map((queue) => queue.name)),
-		retry: retryFor(client),
+		refreshQueueStats: engine.refreshQueueStats,
+		unschedule: engine.unschedule,
 	};
-}
+});

package/src/server/internal/register.ts

@@ -1,13 +1,13 @@
 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 { 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";
-import { registerTestingQueue } from "#internal/testingRegistrations.ts";
+import { registerWorker } from "#server/adapters/registerWorker.ts";
+import { workerDiagnostics } from "#server/adapters/workerDiagnostics.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import type { JobPayloadSchema, JobRegistration, QueueDefinition, QueueWorker, ScheduleDefinition, ScheduledWorker } from "#server/definition.ts";
+import { PgBossQueueOptionsError, toPgBossError } from "#server/error.ts";
+import { ensureQueue } from "#server/internal/ensureQueue.ts";
+import { runQueueWorker } from "#server/internal/runQueueWorker.ts";
+import { registerTestingQueue } from "#server/internal/testingRegistrations.ts";
 
 function registrationDefinition(registration: JobRegistration): QueueDefinition | ScheduleDefinition {
 	if (registration._tag === "QueueDefinition") {

package/src/server/internal/registerReleasedJobs.ts

@@ -1,10 +1,10 @@
 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";
-import type { JobRegistration } from "#definition.ts";
-import { toPgBossError } from "#error.ts";
+import { retireJobs } from "#server/adapters/retireJobs.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import type { JobRegistration } from "#server/definition.ts";
+import { toPgBossError } from "#server/error.ts";
 import { registerJobs, registrationName } from "./register.ts";
 
 export const registerReleasedJobs = Effect.fnUntraced(function* <R>(

package/src/server/internal/retryWake.ts

@@ -1,8 +1,8 @@
 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";
+import { batchClockOffset } from "#server/adapters/batchClockOffset.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
 
 export function retryWake(client: PgBossClient, schema: string, name: string, id: string, registration: Promise<string>): Effect.Effect<void> {
 	return Effect.gen(function* () {

package/src/server/internal/runQueueWorker.ts

@@ -1,15 +1,15 @@
 import { Effect, Redacted, Schema } from "effect";
-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 { type JobPayloadSchema, jobContext, type QueueWorker } from "#definition.ts";
-import { PgBossPayloadError } from "#error.ts";
-import { payloadOf } from "#internal/tracing.ts";
+import { deferralCount } from "#server/adapters/deferralCount.ts";
+import { workerDiagnostics } from "#server/adapters/workerDiagnostics.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { type JobPayloadSchema, jobContext, type QueueWorker } from "#server/definition.ts";
+import { PgBossPayloadError } from "#server/error.ts";
+import { payloadOf } from "#server/internal/tracing.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 export function runQueueWorker<R>(
 	worker: QueueWorker<JobPayloadSchema & { readonly DecodingServices: R }, R>,
-	job: Job<unknown>,
+	job: WorkerJob<unknown>,
 	deadline: number,
 	client: PgBossClient,
 	schema: string,

package/src/server/internal/storedRows.ts

@@ -1,7 +1,7 @@
 import { Effect, Redacted, Schema } from "effect";
-import type { JobPayloadSchema } from "#definition.ts";
-import { PgBossPayloadError } from "#error.ts";
-import { payloadOf } from "#internal/tracing.ts";
+import type { JobPayloadSchema } from "#server/definition.ts";
+import { PgBossPayloadError } from "#server/error.ts";
+import { payloadOf } from "#server/internal/tracing.ts";
 
 export function quotedSchema(schema: string): string {
 	return `"${schema.replaceAll('"', '""')}"`;

package/src/server/internal/testingDeferrals.ts

@@ -1,10 +1,10 @@
 import { DateTime } from "effect";
-import type { PgBoss } from "pg-boss";
-import type { QueueDefinition } from "#definition.ts";
-import { deferralOf } from "#internal/deferral.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import { deferralOf } from "#server/internal/deferral.ts";
+import { testingOperation } from "#server/internal/testingReadout.ts";
 
-export function testingDeferrals(client: () => PgBoss) {
+export function testingDeferrals(client: () => EngineClient) {
 	return {
 		deferred: (queue: Pick<QueueDefinition, "name">) =>
 			testingOperation(

package/src/server/internal/testingIdle.ts

@@ -1,8 +1,8 @@
 import { Clock, Effect, Schema } from "effect";
-import type { PgBoss } from "pg-boss";
-import type { PgBossTestingError } from "#error.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { PgBossTestingError } from "#server/error.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+import { testingOperation } from "#server/internal/testingReadout.ts";
 
 export interface TestingBatch {
 	readonly name: string;
@@ -17,7 +17,7 @@ export interface TestingWork {
 const Busy = Schema.Struct({ busy: Schema.Boolean });
 
 export function testingIdle(
-	client: () => PgBoss,
+	client: () => EngineClient,
 	schema: () => string,
 	work: TestingWork,
 	signal: { readonly revision: Effect.Effect<number>; readonly waitForChange: (after: number) => Effect.Effect<number> },

package/src/server/internal/testingReadout.ts

@@ -1,8 +1,11 @@
 import { Effect, Redacted } from "effect";
-import type { FindJobsOptions, PgBoss } from "pg-boss";
-import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
-import { PgBossTestingError } from "#error.ts";
-import { decodeStoredData } from "#internal/storedRows.ts";
+import type { JobReadOptions } from "#server/client.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { PgBossPayloadError } from "#server/error.ts";
+import { PgBossTestingError } from "#server/error.ts";
+import { decodeStoredData } from "#server/internal/storedRows.ts";
+import type { Job } from "#server/job.ts";
 
 export function testingOperation<A>(operation: string, run: () => Promise<A>, queue?: string) {
 	return Effect.tryPromise({
@@ -11,8 +14,11 @@ export function testingOperation<A>(operation: string, run: () => Promise<A>, qu
 	});
 }
 
-export function testingReadout(client: () => PgBoss) {
-	return <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: FindJobsOptions) =>
+export function testingReadout(client: () => EngineClient) {
+	return <TName extends string, TPayload extends JobPayloadSchema>(
+		queue: QueueDefinition<TName, TPayload>,
+		options?: JobReadOptions,
+	): Effect.Effect<Job<TPayload["Type"]>[], PgBossTestingError | PgBossPayloadError, TPayload["DecodingServices"]> =>
 		testingOperation("jobs", () => client().findJobs<unknown>(queue.name, options), queue.name).pipe(
 			Effect.flatMap((jobs) => Effect.forEach(jobs, (job) => decodeStoredData(queue, job.data).pipe(Effect.map((data) => ({ ...job, data }))))),
 		);

package/src/server/internal/testingRegistrations.ts

@@ -1,4 +1,4 @@
-import type { PgBossClient } from "#client.ts";
+import type { PgBossClient } from "#server/client.ts";
 
 export const testingRegistration = Symbol("jobs testing registration");
 

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({
@@ -15,7 +15,7 @@ const Rows = Schema.Array(
 	}),
 );
 
-export function testingSnapshot(client: () => PgBoss, schema: () => string) {
+export function testingSnapshot(client: () => EngineClient, schema: () => string) {
 	return <const TQueues extends readonly SnapshotQueue[]>(
 		queues: TQueues,
 	): Effect.Effect<

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

@@ -1,18 +1,30 @@
-import type { JobRegistration } from "#definition.ts";
-import type { PgBossDefinition, PgBossLayerOptions } from "#service.ts";
+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>,
 ) {
-	const queues = options.jobs.map((job) => {
+	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;
 	});
-	return {
-		queues,
-		workers: layer(options),
-	};
 }

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(", ")}`;
 		}),
 	};
 }