@shivaedev/jobs 0.31.0 → 0.32.0

package/dist/server/testing.d.ts

@@ -1,41 +1,76 @@
-import { type DateTime, type Duration, Effect, type Tracer } from "effect";
-import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
+import { type Duration, Effect, type Tracer } from "effect";
 export declare function makePgBossTesting(options?: PgBossTestingOptions): {
-    runDeferredNow: (queue: Pick<QueueDefinition, "name">) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
-    runDueNow: (queue: Pick<QueueDefinition, "name">) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
-    deferred: (queue: Pick<QueueDefinition, "name">) => Effect.Effect<{
-        at: DateTime.Utc;
-        reason: string;
-    }[], import("./error.ts").PgBossTestingError, never>;
+    runDeferredNow: (queue: Pick<import("./definition.ts").QueueDefinition, "name">) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
+    runDueNow: (queue: Pick<import("./definition.ts").QueueDefinition, "name">) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
     schedules: () => Effect.Effect<{
         cron: string;
         name: string;
         timezone: string;
     }[], import("./error.ts").PgBossTestingError, never>;
-    trigger: (schedule: Pick<import("#server/definition.ts").ScheduleDefinition, "name" | "scheduleOptions">) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
-    fetchesPass: (queue: Pick<QueueDefinition, "name">, count: number, options?: PgBossTestingWaitOptions) => Effect.Effect<unknown, import("./error.ts").PgBossTestingError | import("./error.ts").PgBossWaitError, never>;
-    untilJob: <TName extends string, TPayload extends JobPayloadSchema>(queue: Pick<QueueDefinition<TName, TPayload>, "name" | "schema">, id: string, state: import("./job.ts").JobState, options?: PgBossTestingWaitOptions) => Effect.Effect<import("./job.ts").Job<TPayload["Type"]>, import("./error.ts").PgBossPayloadError | import("./error.ts").PgBossTestingError | import("./error.ts").PgBossWaitError, Exclude<TPayload["DecodingServices"], never>>;
-    checkBatchWindow: (queue: Pick<QueueDefinition, "name" | "workerOptions">, millisecondsPerJob: number) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
+    trigger: (schedule: Pick<import("./definition.ts").ScheduleDefinition, "name" | "scheduleOptions">) => Effect.Effect<string | null, import("./error.ts").PgBossTestingError, never>;
+    fetchesPass: (queue: Pick<import("./definition.ts").QueueDefinition, "name">, count: number, options?: PgBossTestingWaitOptions) => Effect.Effect<unknown, import("./error.ts").PgBossTestingError | import("./error.ts").PgBossWaitError, never>;
+    untilJob: <TName extends string, TPayload extends import("./definition.ts").JobPayloadSchema | typeof import("effect/Schema").Null>(queue: {
+        readonly name: TName;
+        readonly schema: TPayload;
+    }, id: string, state: import("./job.ts").JobState, options?: PgBossTestingWaitOptions) => Effect.Effect<import("./job.ts").Job<TPayload["Type"]>, import("./error.ts").PgBossPayloadError | import("./error.ts").PgBossTestingError | import("./error.ts").PgBossWaitError, Exclude<TPayload["DecodingServices"], never>>;
+    deferred: (queue: Pick<import("./definition.ts").QueueDefinition, "name">) => Effect.Effect<{
+        at: import("effect/DateTime").Utc;
+        reason: string;
+    }[], import("./error.ts").PgBossTestingError, never>;
+    checkBatchWindow: (queue: Pick<import("./definition.ts").QueueDefinition, "name" | "workerOptions">, millisecondsPerJob: number) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
     checkSchemaVersion: (expected: number) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
     clientFactory: import("./client.ts").PgBossClientFactory;
-    expireAfter: (queue: Pick<QueueDefinition, "name">, attempts: number) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
-    expireIn: (queue: Pick<QueueDefinition, "name">, duration: Duration.Input) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
-    failNextSend: (queue: Pick<QueueDefinition, "name">) => Effect.Effect<void, never, never>;
-    jobs: <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: import("./client.ts").JobReadOptions) => Effect.Effect<import("./job.ts").Job<TPayload["Type"]>[], import("./error.ts").PgBossTestingError | import("./error.ts").PgBossPayloadError, TPayload["DecodingServices"]>;
+    expireAfter: (queue: Pick<import("./definition.ts").QueueDefinition, "name">, attempts: number) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
+    expireIn: (queue: Pick<import("./definition.ts").QueueDefinition, "name">, duration: Duration.Input) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
+    failNextSend: (queue: Pick<import("./definition.ts").QueueDefinition, "name">) => Effect.Effect<void, never, never>;
+    jobs: <TName extends string, TPayload extends import("./definition.ts").JobPayloadSchema | typeof import("effect/Schema").Null>(queue: {
+        readonly name: TName;
+        readonly schema: TPayload;
+    }, readOptions?: import("./client.ts").JobReadOptions) => Effect.Effect<{
+        expireInSeconds: number;
+        groupId?: string | null;
+        groupTier?: string | null;
+        heartbeatSeconds: number | null;
+        id: string;
+        name: string;
+        retryCount: number;
+        signal: AbortSignal;
+        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: import("./job.ts").JobState;
+        data: TPayload["Type"];
+    }[], import("./error.ts").PgBossPayloadError | import("./error.ts").PgBossTestingError, TPayload["DecodingServices"]>;
+    refreshQueueStats: (queue?: Pick<import("./definition.ts").QueueDefinition, "name">) => Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
     revision: Effect.Effect<number, never, never>;
     schemaVersion: Effect.Effect<number | null, import("./error.ts").PgBossTestingError, never>;
-    snapshot: <const TQueues extends readonly SnapshotQueue[]>(queues: TQueues) => Effect.Effect<readonly UnfinishedJob<TQueues[number]>[], import("./error.ts").PgBossPayloadError | import("./error.ts").PgBossTestingError, TQueues[number]["schema"]["DecodingServices"]>;
+    snapshot: <const TQueues extends readonly import("./inspection.ts").SnapshotQueue[]>(queues: TQueues) => Effect.Effect<readonly import("./inspection.ts").UnfinishedJob<TQueues[number]>[], import("./error.ts").PgBossPayloadError | import("./error.ts").PgBossTestingError, TQueues[number]["schema"]["DecodingServices"]>;
     waitForChange: (after: number) => Effect.Effect<number>;
     waitForIdle: Effect.Effect<void, import("./error.ts").PgBossTestingError, never>;
 };
-export type SnapshotQueue = Pick<QueueDefinition<string, JobPayloadSchema>, "name" | "schema">;
-export interface UnfinishedJob<TQueue extends SnapshotQueue> {
-    readonly data: TQueue["schema"]["Type"];
-    readonly id: string;
-    readonly queue: TQueue["name"];
-    readonly startAfter: DateTime.Utc;
-    readonly state: "active" | "created" | "deferred" | "failed" | "retry";
-}
 export interface PgBossTestingWaitOptions {
     readonly within?: Duration.Input;
 }

package/dist/server/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE/E,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,oBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEnE;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;AAE/F,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS,aAAa;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,GAAG,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;CACvE;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;CACjC;AAED,eAAO,MAAM,eAAe;;;EAAwD,CAAC;AAErF,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,eAAe,CAAC;CAC9C;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,CAAC,IAAI,EAAE,8CASlH;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG5D,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,oBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEnE;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;CACjC;AAED,eAAO,MAAM,eAAe;;;EAAwD,CAAC;AAErF,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,eAAe,CAAC;CAC9C;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,CAAC,IAAI,EAAE,8CASlH;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/server/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,MAAM,EAAe,MAAM,QAAQ,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG1E,MAAM,UAAU,iBAAiB,CAAC,OAAO,GAAyB,EAAE;IACnE,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAgBD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;AAMrF,MAAM,UAAU,iBAAiB,CAAC,MAAkD,EAAE,KAA6B;IAClH,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CACvB,KAAK,CAAC,MAAM,CACX,CAAC,IAAI,EAAE,EAAE,CACR,IAAI,CAAC,IAAI,KAAK,UAAU;WACrB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,SAAS;WACrD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CACzG,CACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,EAAe,MAAM,QAAQ,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,UAAU,iBAAiB,CAAC,OAAO,GAAyB,EAAE;IACnE,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAMD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;AAMrF,MAAM,UAAU,iBAAiB,CAAC,MAAkD,EAAE,KAA6B;IAClH,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CACvB,KAAK,CAAC,MAAM,CACX,CAAC,IAAI,EAAE,EAAE,CACR,IAAI,CAAC,IAAI,KAAK,UAAU;WACrB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,SAAS;WACrD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CACzG,CACD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/jobs",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Effect-native jobs and lifecycle management for pg-boss",
   "keywords": [
     "effect"
@@ -43,16 +43,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@shivaedev/errors": "0.6.0",
+    "@shivaedev/errors": "0.7.0",
     "@shivaedev/service": "0.6.1",
-    "@shivaedev/sql": "0.34.0"
+    "@shivaedev/sql": "0.35.0"
   },
   "devDependencies": {
     "@shivaedev/http": "0.5.0",
-    "@shivaedev/quality": "0.57.0",
+    "@shivaedev/quality": "0.57.1",
     "@shivaedev/test": "0.14.0",
-    "@shivaedev/test-sql": "0.17.0",
-    "@shivaedev/test-story": "0.35.0",
+    "@shivaedev/test-sql": "0.18.0",
+    "@shivaedev/test-story": "0.36.0",
     "@types/node": "24.19.2",
     "effect": "4.0.6",
     "pg-boss": "12.38.0",

package/src/server/adapters/inspection.ts

@@ -0,0 +1,31 @@
+import { Effect } from "effect";
+import { jobEngine } from "#server/adapters/jobEngine.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { PgBossInspectionService } from "#server/inspection.ts";
+import { countsFor } from "#server/internal/countsFor.ts";
+import { JobEngine } from "#server/internal/engine.ts";
+import { healthFor } from "#server/internal/healthFor.ts";
+import { jobControl } from "#server/internal/jobControl.ts";
+import { jobListings } from "#server/internal/jobListings.ts";
+import { inspectionChanges } from "./inspectionChanges.ts";
+import { inspectionReads } from "./inspectionReads.ts";
+
+export function inspection(client: PgBossClient, schema = "pgboss"): Effect.Effect<PgBossInspectionService> {
+	const engine = jobEngine(client, schema);
+	return Effect.gen(function* () {
+		const listings = yield* jobListings;
+		const { getJob } = yield* jobControl;
+		return {
+			...inspectionReads(client, schema),
+			...listings,
+			changes: (queue?: { readonly name: string }) => inspectionChanges(client, schema, queue?.name),
+			counts: (queue: { readonly name: string }) => countsFor(client, schema, queue.name),
+			getJob,
+			health: (queues: readonly { readonly name: string }[]) =>
+				healthFor(
+					client,
+					queues.map((queue) => queue.name),
+				),
+		};
+	}).pipe(Effect.provideService(JobEngine, engine));
+}

package/src/server/adapters/inspectionChanges.ts

@@ -0,0 +1,31 @@
+import { Effect } from "effect";
+import { inspectionChannel } from "#server/adapters/inspectionPlan.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { queueSignal } from "./queueSignal.ts";
+
+export const inspectionChanges = Effect.fnUntraced(function* (client: PgBossClient, schema: string, queue?: string) {
+	const signal = queueSignal();
+	yield* Effect.acquireRelease(
+		Effect.tryPromise({
+			catch: (error) => toPgBossError("inspect", error, queue),
+			try: () => {
+				const db = client.getDb?.();
+				if (db?.listen === undefined) {
+					throw new TypeError("This pg-boss client does not support listen");
+				}
+				return db.listen(
+					inspectionChannel(schema),
+					(name) => {
+						if (queue === undefined || name === queue) {
+							signal.changed();
+						}
+					},
+					signal.changed,
+				);
+			},
+		}),
+		(listener) => Effect.promise(() => listener.close()),
+	);
+	return { revision: signal.revision, waitForChange: signal.waitForChange };
+});

package/src/server/{internal/testingDeferrals.ts → adapters/inspectionDeferrals.ts}

@@ -1,22 +1,20 @@
-import { DateTime } from "effect";
+import { DateTime, Effect } from "effect";
+import type { PgBossClient } from "#server/client.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";
+import { inspectionJobs } from "./inspectionJobs.ts";
 
-export function testingDeferrals(client: () => EngineClient) {
+export function inspectionDeferrals(client: PgBossClient) {
+	const { storedJobs } = inspectionJobs(client);
 	return {
 		deferred: (queue: Pick<QueueDefinition, "name">) =>
-			testingOperation(
-				"deferred",
-				async () => {
-					const jobs = await client().findJobs(queue.name);
-					return jobs.flatMap((job) => {
+			storedJobs(queue).pipe(
+				Effect.map((jobs) =>
+					jobs.flatMap((job) => {
 						const deferral = job.state === "retry" && job.startedOn === null ? deferralOf(job) : undefined;
 						return deferral === undefined ? [] : [{ at: DateTime.makeUnsafe(job.startAfter), reason: deferral.reason }];
-					});
-				},
-				queue.name,
+					}),
+				),
 			),
 	};
 }

package/src/server/adapters/inspectionJobs.ts

@@ -0,0 +1,28 @@
+import { Effect, type Schema } from "effect";
+import type { JobReadOptions, PgBossClient } from "#server/client.ts";
+import type { JobPayloadSchema } from "#server/definition.ts";
+import { toPgBossError } from "#server/error.ts";
+import { decodeStoredData } from "#server/internal/storedRows.ts";
+
+export function inspectionJobs(client: PgBossClient) {
+	function storedJobs(queue: { readonly name: string }, options?: JobReadOptions) {
+		return Effect.tryPromise({
+			catch: (error) => toPgBossError("inspect", error, queue.name),
+			try: () => {
+				if (client.findJobs === undefined) {
+					throw new TypeError("This pg-boss client does not support findJobs");
+				}
+				return client.findJobs(queue.name, options);
+			},
+		});
+	}
+	function jobs<TName extends string, TPayload extends JobPayloadSchema | typeof Schema.Null>(
+		queue: { readonly name: TName; readonly schema: TPayload },
+		options?: JobReadOptions,
+	) {
+		return storedJobs(queue, options).pipe(
+			Effect.flatMap((rows) => Effect.forEach(rows, (job) => decodeStoredData(queue, job.data).pipe(Effect.map((data) => ({ ...job, data }))))),
+		);
+	}
+	return { jobs, storedJobs };
+}

package/src/server/adapters/inspectionOperation.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import { toPgBossError } from "#server/error.ts";
+
+export function inspectionOperation<A>(run: () => Promise<A>, queue?: string) {
+	return Effect.tryPromise({ catch: (error) => toPgBossError("inspect", error, queue), try: run });
+}

package/src/server/adapters/inspectionPlan.ts

@@ -0,0 +1,21 @@
+import { quotedSchema } from "#server/internal/storedRows.ts";
+
+export function inspectionChannel(schema: string): string {
+	return `jobs:${schema}`;
+}
+
+export function inspectionPlan(schema: string): string {
+	const quoted = quotedSchema(schema);
+	const channel = inspectionChannel(schema).replaceAll("'", "''");
+	const body = `BEGIN
+	CREATE OR REPLACE FUNCTION ${quoted}.effect_job_changed() RETURNS trigger LANGUAGE plpgsql AS $body$
+	BEGIN
+		PERFORM pg_notify('${channel}', COALESCE(NEW.name, OLD.name));
+		RETURN NULL;
+	END
+	$body$;
+	CREATE OR REPLACE TRIGGER effect_job_changed AFTER INSERT OR UPDATE OR DELETE ON ${quoted}.job
+	FOR EACH ROW EXECUTE FUNCTION ${quoted}.effect_job_changed();
+	END`;
+	return `DO '${body.replaceAll("'", "''")}'`;
+}

package/src/server/adapters/inspectionReads.ts

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import { inspectionDeferrals } from "#server/adapters/inspectionDeferrals.ts";
+import { inspectionJobs } from "#server/adapters/inspectionJobs.ts";
+import { inspectionOperation } from "#server/adapters/inspectionOperation.ts";
+import { inspectionSnapshot } from "#server/adapters/inspectionSnapshot.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+
+const Busy = Schema.Struct({ busy: Schema.Boolean });
+export function inspectionReads(client: PgBossClient, schema: string) {
+	const quoted = quotedSchema(schema);
+	function query(text: string, values?: unknown[]) {
+		const db = client.getDb?.();
+		if (db === undefined) {
+			throw new TypeError("This pg-boss client does not support getDb");
+		}
+		return db.executeSql(text, values);
+	}
+	return {
+		...inspectionDeferrals(client),
+		busy: (queues: readonly Pick<QueueDefinition, "name">[]) =>
+			inspectionOperation(async () => {
+				const { rows } = await query(
+					`/* jobs inspection busy */ SELECT EXISTS (
+				SELECT 1 FROM ${quoted}.job WHERE name = ANY($1::text[]) AND (
+					(state < 'active' AND NOT blocked AND start_after <= ${quoted}.job_now()) OR state = 'active'
+				)
+			) AS busy`,
+					[queues.map(({ name }) => name)],
+				);
+				return Schema.decodeUnknownSync(Busy)(rows[0]).busy;
+			}),
+		...inspectionJobs(client),
+		queue: (queue: Pick<QueueDefinition, "name">) => inspectionOperation(() => client.getQueue(queue.name), queue.name),
+		schedules: (name?: string, key?: string) =>
+			inspectionOperation(() => {
+				if (client.getSchedules === undefined) {
+					throw new TypeError("This pg-boss client does not support getSchedules");
+				}
+				return client.getSchedules(name, key);
+			}),
+		schemaVersion: () =>
+			inspectionOperation(() => {
+				if (client.schemaVersion === undefined) {
+					throw new TypeError("This pg-boss client does not support schemaVersion");
+				}
+				return client.schemaVersion();
+			}),
+		snapshot: inspectionSnapshot(
+			() => client,
+			() => schema,
+		),
+	};
+}

package/src/server/{internal/testingSnapshot.ts → adapters/inspectionSnapshot.ts}

@@ -1,9 +1,9 @@
 import { Effect, Schema } from "effect";
-import type { EngineClient } from "#server/engineClient.ts";
-import type { PgBossPayloadError, PgBossTestingError } from "#server/error.ts";
+import { inspectionOperation } from "#server/adapters/inspectionOperation.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { PgBossError, PgBossPayloadError } from "#server/error.ts";
+import type { SnapshotQueue, UnfinishedJob } from "#server/inspection.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,29 +15,27 @@ const Rows = Schema.Array(
 	}),
 );
 
-export function testingSnapshot(client: () => EngineClient, schema: () => string) {
+export function inspectionSnapshot(client: () => PgBossClient, schema: () => string) {
 	return <const TQueues extends readonly SnapshotQueue[]>(
 		queues: TQueues,
-	): Effect.Effect<
-		readonly UnfinishedJob<TQueues[number]>[],
-		PgBossPayloadError | PgBossTestingError,
-		TQueues[number]["schema"]["DecodingServices"]
-	> => {
+	): Effect.Effect<readonly UnfinishedJob<TQueues[number]>[], PgBossPayloadError | PgBossError, TQueues[number]["schema"]["DecodingServices"]> => {
 		const byName = new Map<string, TQueues[number]>(queues.map((queue) => [queue.name, queue]));
-		return testingOperation("snapshot", async () => {
+		return inspectionOperation(async () => {
 			const quoted = quotedSchema(schema());
-			const { rows } = await client()
-				.getDb()
-				.executeSql(
-					`SELECT id, name AS queue, data, start_after AS "startAfter",
+			const db = client().getDb?.();
+			if (db === undefined) {
+				throw new TypeError("This pg-boss client does not support getDb");
+			}
+			const { rows } = await db.executeSql(
+				`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`,
-					[[...byName.keys()]],
-				);
+				[[...byName.keys()]],
+			);
 			return Schema.decodeUnknownPromise(Rows)(rows);
 		}).pipe(
 			Effect.flatMap((rows) =>

package/src/server/adapters/jobEngine.ts

@@ -1,7 +1,6 @@
 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";
@@ -49,9 +48,6 @@ export function jobEngine(client: PgBossClient, schema = "pgboss"): Context.Serv
 							// 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/payloadIdentity.ts

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+
+export function payloadKey(parts: readonly string[], payload: object): string {
+	return JSON.stringify(parts.map((part) => [part, typeof Reflect.get(payload, part), String(Reflect.get(payload, part))]));
+}
+
+export function payloadJobId(queue: string, parts: readonly string[], payload: object): string {
+	const bytes = createHash("sha256")
+		.update(JSON.stringify([queue, payloadKey(parts, payload)]))
+		.digest();
+	bytes.writeUInt8((bytes.readUInt8(6) & 0x0f) | 0x80, 6);
+	bytes.writeUInt8((bytes.readUInt8(8) & 0x3f) | 0x80, 8);
+	const hex = bytes.subarray(0, 16).toString("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/server/{internal/testingSignal.ts → adapters/queueSignal.ts}

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
 
-export function testingSignal() {
+export function queueSignal() {
 	let revision = 0;
 	const listeners = new Set<(revision: number) => void>();
 	return {

package/src/server/adapters/testingClient.ts

@@ -4,9 +4,7 @@ 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 {
@@ -18,18 +16,9 @@ export interface TestingControls {
 	readonly work: TestingWork;
 }
 
-export function testingClient(client: EngineClient, schema: string, controls: TestingControls): PgBossClient {
+export function testingClient(client: EngineClient, schema: string, controls: TestingControls): EngineClient {
 	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();
-		}),
-	);
+
 	const expirations = testingExpirations(client);
 	function update(request: ClientUpdateRequest): Promise<ClientUpdateResult>;
 	function update(name: string, data: object | null | undefined, options?: ClientUpdateOptions): Promise<ClientUpdateResult>;
@@ -45,6 +34,9 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 			return result;
 		},
 		createQueue: (name, options) => {
+			if (options?.deadLetter !== undefined) {
+				controls.work.queues.add(name);
+			}
 			const { retryDelayMax, ...rest } = options ?? {};
 			return client.createQueue(name, {
 				...rest,
@@ -84,13 +76,6 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 			controls.changed();
 			return id;
 		},
-		stop: async (options) => {
-			try {
-				await client.stop(options);
-			} finally {
-				await Effect.runPromise(settlements.close);
-			}
-		},
 		update,
 		updateQueue: (name, options) =>
 			client.updateQueue(name, {
@@ -98,10 +83,9 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 				...controls.retryPolicy,
 				...(controls.retryPolicy.retryBackoff === false ? { retryDelayMax: null } : {}),
 			}),
-		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 };
+		work: async (name, options, handler) =>
+			client.work(name, options, async (jobs: readonly WorkerJob<unknown>[]) => {
+				const batch: TestingBatch = { jobs: new Map(jobs.map((job) => [job.id, job.retryCount])), name, settled: false };
 				controls.work.batches.add(batch);
 				controls.changed();
 				try {
@@ -121,14 +105,10 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 					controls.work.batches.delete(batch);
 					controls.changed();
 				}
-			});
-		},
+			}),
 	};
 	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;
@@ -137,6 +117,5 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 			return typeof value === "function" ? value.bind(target) : value;
 		},
 	});
-	deferralObservers.set(wrapped, controls.changed);
 	return wrapped;
 }