@shivaedev/effect-pg-boss 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.9.0 - 2026-10-18
+
+### Added
+
+- Export `testing.ts` with `makePgBossTesting`, `testRetryPolicy`, `PgBossTesting` and `PgBossTestingOptions`, plus `PgBossTestingError` from `error.ts`. Story kits can read Schema-decoded jobs, fail the next send, expire a selected attempt, set immediate retries, check batch budgets and schema versions, and wait for local queue changes or worker idleness without application SQL or timer polling.
+- Expiry rules stay with each successfully sent job, and native terminal worker timeouts wake queue-change waiters even when a handler promise stays pending.
+
 ## 0.8.1 - 2026-10-18
 
 ### Changed

package/README.md

@@ -324,6 +324,53 @@ const live = Jobs.layer({
 
 Include every target queue in `jobs`, as either a worker or a producer-only definition. Startup creates all queues before starting consumers. The example registers `Receipt` for another process to consume. A follow-up target can also have a worker in the same Layer. Scheduled effects can yield `Jobs` too. Keep one jobs Layer in the process's native Layer graph; that Layer owns one client for enqueueing and handling. The PostgreSQL follow-up test completes a chain across two workers, enqueues to a producer-only queue and asserts one client acquisition and shutdown.
 
+### Test through the queue contract
+
+`testing.ts` gives story kits a controller for one real pg-boss client. Create a fresh controller per runtime, pass its `clientFactory` to the jobs Layer, and keep that Layer scoped as usual. `jobs(queue, options?)` returns native job metadata with `data` decoded through the queue's Schema, including traced payloads. Invalid durable data fails with `PgBossPayloadError`; decoding services remain in the Effect's requirements.
+
+This producer story uses the `SendEmail` definition and `Jobs` service from above. `databaseUrl` points to the story's PostgreSQL database:
+
+```ts
+import { Context, Layer, Option } from "effect";
+import { expect } from "vitest";
+import { storyKit } from "@shivaedev/test-story/storyKit.ts";
+import { makePgBossTesting, testRetryPolicy } from "@shivaedev/effect-pg-boss/testing.ts";
+
+const emailStories = storyKit({
+  clock: "live",
+  *create() {
+    const testing = makePgBossTesting({ retryPolicy: testRetryPolicy });
+    const context = yield* Layer.build(Jobs.layer({
+      connectionString: databaseUrl,
+      clientFactory: testing.clientFactory,
+      jobs: [SendEmail],
+    }));
+    return { jobs: Context.get(context, Jobs), testing };
+  },
+  name: "queued email",
+  stages: ["ready"],
+  verbs: ({ jobs, testing }) => ({
+    enqueue: (userId: number) => jobs.enqueue(SendEmail, { userId }),
+    testing,
+  }),
+});
+
+emailStories.it("decodes the queued email", [], function* ({ enqueue, testing }) {
+  const id = Option.getOrThrow(yield* enqueue(42));
+  expect(yield* testing.jobs(SendEmail)).toMatchObject([
+    { id, data: { userId: 42 }, state: "created" },
+  ]);
+});
+```
+
+Set `retryPolicy: testRetryPolicy` through the controller to override queue and send settings with `retryDelay: 0` and `retryBackoff: false`. A failing worker can then exhaust its native retries without production backoff. The policy applies to subsequently sent jobs; it does not rewrite jobs already stored.
+
+`failNextSend(queue)` arms one send failure for that queue. The next valid `enqueue` fails with the usual typed `PgBossError` (`operation: "enqueue"`); the following send proceeds normally. `expireAfter(queue, n)` takes a positive attempt count: configure it before enqueueing to limit subsequent jobs to `n` attempts. Each successful send keeps its own expiry rule; later changes and duplicate-ID sends do not alter pending jobs. Earlier attempts run the handler normally; on attempt `n`, the controller expires the claimed job instead of invoking its handler. PostgreSQL supervision performs the terminal failure and dead lettering. A job that succeeds earlier completes normally. This expiry hook supports pg-boss schema version 45 and keeps its SQL inside the testing module.
+
+`checkBatchWindow(queue, millisecondsPerJob)` checks that the declared sequential batch fits strictly inside the stored queue expiry window. `schemaVersion` reads the installed version, and `checkSchemaVersion(expected)` fails when it differs. Test control, read and check failures use `PgBossTestingError` with `operation`, optional `queue` and a redacted `original`.
+
+A kit can capture `revision` before reading jobs and yield `waitForChange(revision)` when its condition is unmet. The wait resumes after a local send, settlement, worker fetch or return to idle, including terminal native worker timeouts whose handler promises remain pending. It also resumes immediately if a change occurred between the read and the wait. This signal observes the controller's client; external clients, future scheduled work and external database writes need their own wake source. Stories should retain a bounded test timeout. The package's PostgreSQL story kit uses this signal to settle failed-job stories without timer polling or application SQL.
+
 ### API
 
 Import the module that defines the name; the package has no root entry.
@@ -333,8 +380,9 @@ Import the module that defines the name; the package has no root entry.
 | `@shivaedev/effect-pg-boss/definition.ts` | `defineQueue`, `defineSchedule`, `jobContext`; `DefineQueueOptions`, `DefineScheduleOptions`, `JobContext`, `JobPayloadSchema`, `JobRegistration`, `QueueDefinition`, `QueueWorker`, `RegistrationRequirements`, `ScheduleDefinition`, `ScheduledWorker` |
 | `@shivaedev/effect-pg-boss/service.ts` | `makePgBoss`; `PgBossDefinition`, `PgBossLayerOptions`, `PgBossService` |
 | `@shivaedev/effect-pg-boss/health.ts` | `deadLetterQueueName`; `JobsHealth`, `QueueCounts`, `QueueHealth` |
-| `@shivaedev/effect-pg-boss/error.ts` | `PgBossError`, `PgBossPayloadError`, `PgBossQueueOptionsError`, `toPgBossError`; `PgBossOperation` |
+| `@shivaedev/effect-pg-boss/error.ts` | `PgBossError`, `PgBossPayloadError`, `PgBossQueueOptionsError`, `PgBossTestingError`, `toPgBossError`; `PgBossOperation` |
 | `@shivaedev/effect-pg-boss/client.ts` | `defaultClientFactory`; `PgBossClient`, `PgBossClientFactory` |
+| `@shivaedev/effect-pg-boss/testing.ts` | `makePgBossTesting`, `testRetryPolicy`; `PgBossTesting`, `PgBossTestingOptions` |
 
 The definition options keep the pg-boss names: `queue` uses `Queue` except `name` and `deadLetter`, `worker` uses `WorkOptions`, and a schedule's `schedule` uses `ScheduleOptions`. A queue also requires `name` and `schema`; a schedule requires `name` and `cron`.
 

package/dist/server/error.d.ts

@@ -28,6 +28,15 @@ export declare class PgBossPayloadError extends PgBossPayloadError_base<{
     readonly original: Redacted.Redacted<unknown>;
 }> {
 }
+declare const PgBossTestingError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PgBossTestingError";
+} & Readonly<A>;
+export declare class PgBossTestingError extends PgBossTestingError_base<{
+    readonly operation: string;
+    readonly original: Redacted.Redacted<unknown>;
+    readonly queue?: string | undefined;
+}> {
+}
 export declare const toPgBossError: (operation: PgBossOperation, error: unknown, queue?: string) => PgBossError;
 export {};
 //# sourceMappingURL=error.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/server/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAExC,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;;;;AAEnH,qBAAa,WAAY,SAAQ,iBAAgC;IAChE,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CAC9C,CAAC;IAED,IAAa,OAAO,IAAI,MAAM,CAG7B;CACD;;;;AAUD,qBAAa,uBAAwB,SAAQ,6BAA4C;IACxF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,QAAQ,CAAC,EAAE,CAAC;CACtD,CAAC;IACD,IAAa,OAAO,IAAI,MAAM,CAE7B;CACD;;;;AAED,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC9E,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CAC9C,CAAC;CAAG;AAEL,eAAO,MAAM,aAAa,cAAe,eAAe,SAAS,OAAO,UAAU,MAAM,KAAG,WAKxF,CAAC"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/server/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAExC,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;;;;AAEnH,qBAAa,WAAY,SAAQ,iBAAgC;IAChE,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CAC9C,CAAC;IAED,IAAa,OAAO,IAAI,MAAM,CAG7B;CACD;;;;AAUD,qBAAa,uBAAwB,SAAQ,6BAA4C;IACxF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,QAAQ,CAAC,EAAE,CAAC;CACtD,CAAC;IACD,IAAa,OAAO,IAAI,MAAM,CAE7B;CACD;;;;AAED,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC9E,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CAC9C,CAAC;CAAG;;;;AAEL,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,CAAC;CAAG;AAEL,eAAO,MAAM,aAAa,cAAe,eAAe,SAAS,OAAO,UAAU,MAAM,KAAG,WAKxF,CAAC"}

package/dist/server/error.js

@@ -20,6 +20,8 @@ export class PgBossQueueOptionsError extends Data.TaggedError("PgBossQueueOption
 }
 export class PgBossPayloadError extends Data.TaggedError("PgBossPayloadError") {
 }
+export class PgBossTestingError extends Data.TaggedError("PgBossTestingError") {
+}
 export const toPgBossError = (operation, error, queue) => new PgBossError({
     operation,
     original: Redacted.make(error),

package/dist/server/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/server/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAIxC,MAAM,OAAO,WAAY,SAAQ,IAAI,CAAC,WAAW,CAAC,aAAa,CAI7D;IACD,yGAAyG;IACzG,IAAa,OAAO;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1E,OAAO,WAAW,IAAI,CAAC,SAAS,GAAG,MAAM,YAAY,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;IACpG,CAAC;CACD;AAED,SAAS,YAAY,CAAC,QAAiB;IACtC,IAAI,CAAC,CAAC,QAAQ,YAAY,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,OAAO,QAAQ,CAAC;IACxB,CAAC;IACD,MAAM,IAAI,GAAY,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC;AACtG,CAAC;AAED,MAAM,OAAO,uBAAwB,SAAQ,IAAI,CAAC,WAAW,CAAC,yBAAyB,CAGrF;IACD,IAAa,OAAO;QACnB,OAAO,SAAS,IAAI,CAAC,KAAK,0CAA0C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC/F,CAAC;CACD;AAED,MAAM,OAAO,kBAAmB,SAAQ,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAI3E;CAAG;AAEL,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAA0B,EAAE,KAAc,EAAE,KAAc,EAAe,EAAE,CACxG,IAAI,WAAW,CAAC;IACf,SAAS;IACT,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;IAC9B,KAAK;CACL,CAAC,CAAC"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/server/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAIxC,MAAM,OAAO,WAAY,SAAQ,IAAI,CAAC,WAAW,CAAC,aAAa,CAI7D;IACD,yGAAyG;IACzG,IAAa,OAAO;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1E,OAAO,WAAW,IAAI,CAAC,SAAS,GAAG,MAAM,YAAY,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;IACpG,CAAC;CACD;AAED,SAAS,YAAY,CAAC,QAAiB;IACtC,IAAI,CAAC,CAAC,QAAQ,YAAY,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,OAAO,QAAQ,CAAC;IACxB,CAAC;IACD,MAAM,IAAI,GAAY,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC;AACtG,CAAC;AAED,MAAM,OAAO,uBAAwB,SAAQ,IAAI,CAAC,WAAW,CAAC,yBAAyB,CAGrF;IACD,IAAa,OAAO;QACnB,OAAO,SAAS,IAAI,CAAC,KAAK,0CAA0C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC/F,CAAC;CACD;AAED,MAAM,OAAO,kBAAmB,SAAQ,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAI3E;CAAG;AAEL,MAAM,OAAO,kBAAmB,SAAQ,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAI3E;CAAG;AAEL,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAA0B,EAAE,KAAc,EAAE,KAAc,EAAe,EAAE,CACxG,IAAI,WAAW,CAAC;IACf,SAAS;IACT,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;IAC9B,KAAK;CACL,CAAC,CAAC"}

package/dist/server/internal/expireAttempt.d.ts

@@ -0,0 +1,3 @@
+import type { Job, PgBoss } from "pg-boss";
+export declare function expireAttempt(client: PgBoss, schema: string, job: Job<unknown>): Promise<void>;
+//# sourceMappingURL=expireAttempt.d.ts.map

package/dist/server/internal/expireAttempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expireAttempt.d.ts","sourceRoot":"","sources":["../../../src/server/internal/expireAttempt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAE3C,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAepG"}

package/dist/server/internal/expireAttempt.js

@@ -0,0 +1,14 @@
+export async function expireAttempt(client, schema, job) {
+    if ((await client.schemaVersion()) !== 45) {
+        throw new Error("Testing expiry requires pg-boss schema version 45");
+    }
+    const quoted = `"${schema.replaceAll('"', '""')}"`;
+    await client.getDb().executeSql(`UPDATE ${quoted}.job SET started_on = ${quoted}.job_now() - (expire_seconds + 1) * interval '1 second'
+		WHERE name = $1 AND id = $2 AND retry_count = $3 AND state = 'active'`, [job.name, job.id, job.retryCount]);
+    // Supervision owns expiry and dead lettering; make its claim due with the job's deadline.
+    await client
+        .getDb()
+        .executeSql(`UPDATE ${quoted}.queue SET monitor_claim_on = ${quoted}.job_now() - interval '1 week' WHERE name = $1`, [job.name]);
+    await client.supervise(job.name);
+}
+//# sourceMappingURL=expireAttempt.js.map

package/dist/server/internal/expireAttempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expireAttempt.js","sourceRoot":"","sources":["../../../src/server/internal/expireAttempt.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,MAAc,EAAE,GAAiB;IACpF,IAAI,CAAC,MAAM,MAAM,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;IACnD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,UAAU,CAC9B,UAAU,MAAM,yBAAyB,MAAM;wEACuB,EACtE,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,UAAU,CAAC,CAClC,CAAC;IACF,0FAA0F;IAC1F,MAAM,MAAM;SACV,KAAK,EAAE;SACP,UAAU,CAAC,UAAU,MAAM,iCAAiC,MAAM,gDAAgD,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAClI,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/server/internal/observeTestingSettlements.d.ts

@@ -0,0 +1,6 @@
+import type { PgBoss } from "pg-boss";
+export declare function observeTestingSettlements(client: PgBoss, changed: () => void): {
+    close(): void;
+    watch(name: string): void;
+};
+//# sourceMappingURL=observeTestingSettlements.d.ts.map

package/dist/server/internal/observeTestingSettlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observeTestingSettlements.d.ts","sourceRoot":"","sources":["../../../src/server/internal/observeTestingSettlements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI;IAG3E,KAAK;IAML,KAAK,OAAO,MAAM;EAwBnB"}

package/dist/server/internal/observeTestingSettlements.js

@@ -0,0 +1,35 @@
+export function observeTestingSettlements(client, changed) {
+    const observers = new Map();
+    return {
+        close() {
+            for (const close of observers.values()) {
+                close();
+            }
+            observers.clear();
+        },
+        watch(name) {
+            if (observers.has(name)) {
+                return;
+            }
+            const spy = client.getSpy(name);
+            let open = true;
+            async function observe() {
+                while (true) {
+                    await Promise.race([spy.waitForJob(() => true, "completed"), spy.waitForJob(() => true, "failed")]);
+                    if (!open) {
+                        return;
+                    }
+                    // This controller owns the spy; clear history and the losing wait before rearming both outcomes.
+                    spy.clear();
+                    changed();
+                }
+            }
+            observers.set(name, () => {
+                open = false;
+                spy.clear();
+            });
+            void observe().catch((error) => client.emit("error", error instanceof Error ? error : new Error(String(error))));
+        },
+    };
+}
+//# sourceMappingURL=observeTestingSettlements.js.map

package/dist/server/internal/observeTestingSettlements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observeTestingSettlements.js","sourceRoot":"","sources":["../../../src/server/internal/observeTestingSettlements.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,yBAAyB,CAAC,MAAc,EAAE,OAAmB;IAC5E,MAAM,SAAS,GAAG,IAAI,GAAG,EAAsB,CAAC;IAChD,OAAO;QACN,KAAK;YACJ,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;gBACxC,KAAK,EAAE,CAAC;YACT,CAAC;YACD,SAAS,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;QACD,KAAK,CAAC,IAAY;YACjB,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,OAAO;YACR,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,IAAI,GAAG,IAAI,CAAC;YAChB,KAAK,UAAU,OAAO;gBACrB,OAAO,IAAI,EAAE,CAAC;oBACb,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;oBACpG,IAAI,CAAC,IAAI,EAAE,CAAC;wBACX,OAAO;oBACR,CAAC;oBACD,iGAAiG;oBACjG,GAAG,CAAC,KAAK,EAAE,CAAC;oBACZ,OAAO,EAAE,CAAC;gBACX,CAAC;YACF,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE;gBACxB,IAAI,GAAG,KAAK,CAAC;gBACb,GAAG,CAAC,KAAK,EAAE,CAAC;YACb,CAAC,CAAC,CAAC;YACH,KAAK,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3H,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/server/internal/testingClient.d.ts

@@ -0,0 +1,10 @@
+import type { PgBoss, SendOptions } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+export interface TestingControls {
+    readonly changed: () => void;
+    readonly expirations: Map<string, number>;
+    readonly failures: Set<string>;
+    readonly retryPolicy: Pick<SendOptions, "retryBackoff" | "retryDelay">;
+}
+export declare function testingClient(client: PgBoss, schema: string, controls: TestingControls): PgBossClient;
+//# sourceMappingURL=testingClient.d.ts.map

package/dist/server/internal/testingClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingClient.d.ts","sourceRoot":"","sources":["../../../src/server/internal/testingClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAO,MAAM,EAAE,WAAW,EAAgD,MAAM,SAAS,CAAC;AACtG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;CACvE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,YAAY,CAqGrG"}

package/dist/server/internal/testingClient.js

@@ -0,0 +1,101 @@
+import { expireAttempt } from "#internal/expireAttempt.ts";
+import { observeTestingSettlements } from "#internal/observeTestingSettlements.ts";
+import { testingExpirations } from "#internal/testingExpirations.ts";
+export function testingClient(client, schema, controls) {
+    const settlements = observeTestingSettlements(client, controls.changed);
+    const expirations = testingExpirations(client);
+    async function update(request, data, options) {
+        const result = typeof request === "string" ? await client.update(request, data, options) : await client.update(request);
+        controls.changed();
+        return result;
+    }
+    const overrides = {
+        complete: async (...args) => {
+            const result = await client.complete(...args);
+            controls.changed();
+            return result;
+        },
+        createQueue: (name, options) => {
+            const { retryDelayMax, ...rest } = options ?? {};
+            return client.createQueue(name, {
+                ...rest,
+                ...(controls.retryPolicy.retryBackoff === false || retryDelayMax === undefined ? {} : { retryDelayMax }),
+                ...controls.retryPolicy,
+            });
+        },
+        fail: async (...args) => {
+            const result = await client.fail(...args);
+            controls.changed();
+            return result;
+        },
+        retry: async (...args) => {
+            const result = await client.retry(...args);
+            controls.changed();
+            return result;
+        },
+        send: async (name, data, options) => {
+            if (controls.failures.delete(name)) {
+                throw new Error("Injected pg-boss send failure");
+            }
+            const attempts = controls.expirations.get(name);
+            const { retryDelayMax, ...rest } = options ?? {};
+            const id = await expirations.send(name, data, {
+                ...rest,
+                ...(controls.retryPolicy.retryBackoff === false || retryDelayMax === undefined ? {} : { retryDelayMax }),
+                ...controls.retryPolicy,
+                ...(attempts === undefined ? {} : { retryLimit: attempts - 1 }),
+            }, attempts);
+            controls.changed();
+            return id;
+        },
+        stop: async (options) => {
+            try {
+                await client.stop(options);
+            }
+            finally {
+                settlements.close();
+            }
+        },
+        update,
+        updateQueue: (name, options) => client.updateQueue(name, {
+            ...options,
+            ...controls.retryPolicy,
+            ...(controls.retryPolicy.retryBackoff === false ? { retryDelayMax: null } : {}),
+        }),
+        work: (name, options, handler) => {
+            settlements.watch(name);
+            return client.work(name, options, async (jobs) => {
+                controls.changed();
+                try {
+                    const ready = [];
+                    for (const job of jobs) {
+                        const attempts = await expirations.attemptsFor(job);
+                        if (attempts !== undefined && job.retryCount + 1 >= attempts) {
+                            await expireAttempt(client, schema, job);
+                        }
+                        else {
+                            ready.push(job);
+                        }
+                    }
+                    if (ready.length > 0) {
+                        await handler(ready);
+                    }
+                }
+                finally {
+                    controls.changed();
+                }
+            });
+        },
+    };
+    return new Proxy(client, {
+        get(target, property) {
+            if (Object.hasOwn(overrides, property)) {
+                const override = Reflect.get(overrides, property);
+                return override;
+            }
+            const value = Reflect.get(target, property);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+//# sourceMappingURL=testingClient.js.map

package/dist/server/internal/testingClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingClient.js","sourceRoot":"","sources":["../../../src/server/internal/testingClient.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AASrE,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,MAAc,EAAE,QAAyB;IACtF,MAAM,WAAW,GAAG,yBAAyB,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACxE,MAAM,WAAW,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAG/C,KAAK,UAAU,MAAM,CAAC,OAA+B,EAAE,IAAoB,EAAE,OAAuB;QACnG,MAAM,MAAM,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACxH,QAAQ,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC;IACf,CAAC;IACD,MAAM,SAAS,GAA0B;QACxC,QAAQ,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;YAC3B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;YAC9C,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC;QACf,CAAC;QACD,WAAW,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE;YAC9B,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;YACjD,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE;gBAC/B,GAAG,IAAI;gBACP,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,YAAY,KAAK,KAAK,IAAI,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC;gBACxG,GAAG,QAAQ,CAAC,WAAW;aACvB,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;YACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;YAC1C,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC;QACf,CAAC;QACD,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;YACxB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;YAC3C,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC;QACf,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;YACnC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAClD,CAAC;YACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChD,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;YACjD,MAAM,EAAE,GAAG,MAAM,WAAW,CAAC,IAAI,CAChC,IAAI,EACJ,IAAI,EACJ;gBACC,GAAG,IAAI;gBACP,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,YAAY,KAAK,KAAK,IAAI,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC;gBACxG,GAAG,QAAQ,CAAC,WAAW;gBACvB,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,GAAG,CAAC,EAAE,CAAC;aAC/D,EACD,QAAQ,CACR,CAAC;YACF,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC;QACX,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACvB,IAAI,CAAC;gBACJ,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC5B,CAAC;oBAAS,CAAC;gBACV,WAAW,CAAC,KAAK,EAAE,CAAC;YACrB,CAAC;QACF,CAAC;QACD,MAAM;QACN,WAAW,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAC9B,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE;YACxB,GAAG,OAAO;YACV,GAAG,QAAQ,CAAC,WAAW;YACvB,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,YAAY,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/E,CAAC;QACH,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;YAChC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACxB,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAoB,EAAE,EAAE;gBAChE,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACnB,IAAI,CAAC;oBACJ,MAAM,KAAK,GAAmB,EAAE,CAAC;oBACjC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;wBACxB,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;wBACpD,IAAI,QAAQ,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,GAAG,CAAC,IAAI,QAAQ,EAAE,CAAC;4BAC9D,MAAM,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;wBAC1C,CAAC;6BAAM,CAAC;4BACP,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;wBACjB,CAAC;oBACF,CAAC;oBACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACtB,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;oBACtB,CAAC;gBACF,CAAC;wBAAS,CAAC;oBACV,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACpB,CAAC;YACF,CAAC,CAAC,CAAC;QACJ,CAAC;KACD,CAAC;IACF,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;QACxB,GAAG,CAAC,MAAM,EAAE,QAAQ;YACnB,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;gBACxC,MAAM,QAAQ,GAAY,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;gBAC3D,OAAO,QAAQ,CAAC;YACjB,CAAC;YACD,MAAM,KAAK,GAAY,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACrD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACjE,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}

package/dist/server/internal/testingExpirations.d.ts

@@ -0,0 +1,6 @@
+import type { Job, PgBoss, SendOptions } from "pg-boss";
+export declare function testingExpirations(client: PgBoss): {
+    attemptsFor: (job: Job<unknown>) => Promise<number | undefined> | undefined;
+    send(name: string, data: object | null | undefined, options: SendOptions, attempts: number | undefined): Promise<string | null>;
+};
+//# sourceMappingURL=testingExpirations.d.ts.map

package/dist/server/internal/testingExpirations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingExpirations.d.ts","sourceRoot":"","sources":["../../../src/server/internal/testingExpirations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAExD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM;IAG/C,WAAW,QAAQ,GAAG,CAAC,OAAO,CAAC;IAC/B,IAAI,OAAO,MAAM,QAAQ,MAAM,GAAG,IAAI,GAAG,SAAS,WAAW,WAAW,YAAY,MAAM,GAAG,SAAS;EAwBvG"}

package/dist/server/internal/testingExpirations.js

@@ -0,0 +1,27 @@
+export function testingExpirations(client) {
+    const snapshots = new Map();
+    return {
+        attemptsFor: (job) => snapshots.get(`${job.name}:${job.id}`),
+        send(name, data, options, attempts) {
+            if (attempts === undefined && options.id === undefined) {
+                return client.send(name, data, options);
+            }
+            const id = options.id ?? crypto.randomUUID();
+            const key = `${name}:${id}`;
+            const previous = snapshots.get(key);
+            const sending = client.send(name, data, { ...options, id });
+            // A worker may claim the row before send returns. Wait for its result before applying the snapshot.
+            const snapshot = sending
+                .then((sent) => (sent === id ? attempts : previous), () => previous)
+                .then((value) => {
+                if (value === undefined && snapshots.get(key) === snapshot) {
+                    snapshots.delete(key);
+                }
+                return value;
+            });
+            snapshots.set(key, snapshot);
+            return sending;
+        },
+    };
+}
+//# sourceMappingURL=testingExpirations.js.map

package/dist/server/internal/testingExpirations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingExpirations.js","sourceRoot":"","sources":["../../../src/server/internal/testingExpirations.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAChD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuC,CAAC;IACjE,OAAO;QACN,WAAW,EAAE,CAAC,GAAiB,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;QAC1E,IAAI,CAAC,IAAY,EAAE,IAA+B,EAAE,OAAoB,EAAE,QAA4B;YACrG,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;gBACxD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;YACzC,CAAC;YACD,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YAC7C,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;YAC5D,oGAAoG;YACpG,MAAM,QAAQ,GAAG,OAAO;iBACtB,IAAI,CACJ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAC7C,GAAG,EAAE,CAAC,QAAQ,CACd;iBACA,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;gBACf,IAAI,KAAK,KAAK,SAAS,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;oBAC5D,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACvB,CAAC;gBACD,OAAO,KAAK,CAAC;YACd,CAAC,CAAC,CAAC;YACJ,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC7B,OAAO,OAAO,CAAC;QAChB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/server/internal/testingReadout.d.ts

@@ -0,0 +1,44 @@
+import { Effect } from "effect";
+import type { FindJobsOptions, PgBoss } from "pg-boss";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
+import { PgBossPayloadError, PgBossTestingError } from "#error.ts";
+export declare function testingOperation<A>(operation: string, run: () => Promise<A>, queue?: string): Effect.Effect<A, PgBossTestingError, never>;
+export declare function testingReadout(client: () => PgBoss): <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: FindJobsOptions) => Effect.Effect<{
+    id: string;
+    name: string;
+    retryCount: number;
+    signal: AbortSignal;
+    groupId?: string | null;
+    groupTier?: string | null;
+    priority: number;
+    state: 'created' | 'retry' | 'active' | 'completed' | 'cancelled' | 'failed';
+    retryLimit: number;
+    retryDelay: number;
+    retryBackoff: boolean;
+    retryDelayMax?: number;
+    startAfter: Date;
+    startedOn: Date;
+    singletonKey: string | null;
+    singletonOn: Date | null;
+    expireInSeconds: number;
+    deleteAfterSeconds: number;
+    createdOn: Date;
+    completedOn: Date | null;
+    keepUntil: Date;
+    policy: import("pg-boss").QueuePolicy;
+    heartbeatOn: Date | null;
+    heartbeatSeconds: number | null;
+    blocked: boolean;
+    blocking: boolean;
+    pendingDependencies: number;
+    deadLetter: string;
+    output: object;
+    sourceName: string | null;
+    sourceId: string | null;
+    sourceCreatedOn: Date | null;
+    sourceRetryCount: number | null;
+    sourceOutput: object | null;
+    sourceRootId: string | null;
+    data: TPayload["Type"];
+}[], PgBossPayloadError | PgBossTestingError, TPayload["DecodingServices"]>;
+//# sourceMappingURL=testingReadout.d.ts.map

package/dist/server/internal/testingReadout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingReadout.d.ts","sourceRoot":"","sources":["../../../src/server/internal/testingReadout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,QAAQ,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAGnE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,+CAK3F;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,MAAM,IAC1C,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,gBAAgB,SAAS,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4EAWnI"}

package/dist/server/internal/testingReadout.js

@@ -0,0 +1,13 @@
+import { Effect, Redacted, Schema } from "effect";
+import { PgBossPayloadError, PgBossTestingError } from "#error.ts";
+import { payloadOf } from "#internal/tracing.ts";
+export function testingOperation(operation, run, queue) {
+    return Effect.tryPromise({
+        catch: (original) => new PgBossTestingError({ operation, original: Redacted.make(original), queue }),
+        try: run,
+    });
+}
+export function testingReadout(client) {
+    return (queue, options) => testingOperation("jobs", () => client().findJobs(queue.name, options), queue.name).pipe(Effect.flatMap((jobs) => Effect.forEach(jobs, (job) => Schema.decodeUnknownEffect(queue.schema)(payloadOf(job.data)).pipe(Effect.mapError((original) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(original), queue: queue.name })), Effect.map((data) => ({ ...job, data }))))));
+}
+//# sourceMappingURL=testingReadout.js.map

package/dist/server/internal/testingReadout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingReadout.js","sourceRoot":"","sources":["../../../src/server/internal/testingReadout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,MAAM,UAAU,gBAAgB,CAAI,SAAiB,EAAE,GAAqB,EAAE,KAAc;IAC3F,OAAO,MAAM,CAAC,UAAU,CAAC;QACxB,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC;QACpG,GAAG,EAAE,GAAG;KACR,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAoB;IAClD,OAAO,CAA0D,KAAuC,EAAE,OAAyB,EAAE,EAAE,CACtI,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAU,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAC/F,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACvB,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAC5B,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CACjE,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,EACpI,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CACxC,CACD,CACD,CACD,CAAC;AACJ,CAAC"}

package/dist/server/internal/testingSignal.d.ts

@@ -0,0 +1,7 @@
+import { Effect } from "effect";
+export declare function testingSignal(): {
+    changed(): void;
+    revision: Effect.Effect<number, never, never>;
+    waitForChange: (after: number) => Effect.Effect<number>;
+};
+//# sourceMappingURL=testingSignal.d.ts.map

package/dist/server/internal/testingSignal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingSignal.d.ts","sourceRoot":"","sources":["../../../src/server/internal/testingSignal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,wBAAgB,aAAa;IAI3B,OAAO;IAOP,QAAQ;IACR,aAAa,UAAU,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;EAatD"}

package/dist/server/internal/testingSignal.js

@@ -0,0 +1,27 @@
+import { Effect } from "effect";
+export function testingSignal() {
+    let revision = 0;
+    const listeners = new Set();
+    return {
+        changed() {
+            revision += 1;
+            for (const listener of listeners) {
+                listener(revision);
+            }
+            listeners.clear();
+        },
+        revision: Effect.sync(() => revision),
+        waitForChange: (after) => Effect.callback((resume) => {
+            if (revision !== after) {
+                resume(Effect.succeed(revision));
+                return;
+            }
+            function listener(current) {
+                resume(Effect.succeed(current));
+            }
+            listeners.add(listener);
+            return Effect.sync(() => listeners.delete(listener));
+        }),
+    };
+}
+//# sourceMappingURL=testingSignal.js.map

package/dist/server/internal/testingSignal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingSignal.js","sourceRoot":"","sources":["../../../src/server/internal/testingSignal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,UAAU,aAAa;IAC5B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,SAAS,GAAG,IAAI,GAAG,EAA8B,CAAC;IACxD,OAAO;QACN,OAAO;YACN,QAAQ,IAAI,CAAC,CAAC;YACd,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBAClC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACpB,CAAC;YACD,SAAS,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;QACD,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC;QACrC,aAAa,EAAE,CAAC,KAAa,EAAyB,EAAE,CACvD,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE;YAC1B,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;gBACxB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACjC,OAAO;YACR,CAAC;YACD,SAAS,QAAQ,CAAC,OAAe;gBAChC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YACjC,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtD,CAAC,CAAC;KACH,CAAC;AACH,CAAC"}

package/dist/server/testing.d.ts

@@ -0,0 +1,61 @@
+import { Effect } from "effect";
+import type { PgBossClientFactory } from "#client.ts";
+import type { QueueDefinition } from "#definition.ts";
+import { PgBossTestingError } from "#error.ts";
+export declare const testRetryPolicy: Readonly<{
+    retryBackoff: false;
+    retryDelay: 0;
+}>;
+export interface PgBossTestingOptions {
+    readonly retryPolicy?: typeof testRetryPolicy;
+}
+export declare function makePgBossTesting(options?: PgBossTestingOptions): {
+    checkBatchWindow: (queue: QueueDefinition, millisecondsPerJob: number) => Effect.Effect<void, PgBossTestingError, never>;
+    checkSchemaVersion: (expected: number) => Effect.Effect<void, PgBossTestingError, never>;
+    clientFactory: PgBossClientFactory;
+    expireAfter: (queue: QueueDefinition, attempts: number) => Effect.Effect<void, PgBossTestingError, never>;
+    failNextSend: (queue: QueueDefinition) => Effect.Effect<void, never, never>;
+    jobs: <TName extends string, TPayload extends import("#definition.ts").JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: import("pg-boss").FindJobsOptions) => Effect.Effect<{
+        id: string;
+        name: string;
+        retryCount: number;
+        signal: AbortSignal;
+        groupId?: string | null;
+        groupTier?: string | null;
+        priority: number;
+        state: 'created' | 'retry' | 'active' | 'completed' | 'cancelled' | 'failed';
+        retryLimit: number;
+        retryDelay: number;
+        retryBackoff: boolean;
+        retryDelayMax?: number;
+        startAfter: Date;
+        startedOn: Date;
+        singletonKey: string | null;
+        singletonOn: Date | null;
+        expireInSeconds: number;
+        deleteAfterSeconds: number;
+        createdOn: Date;
+        completedOn: Date | null;
+        keepUntil: Date;
+        policy: import("pg-boss").QueuePolicy;
+        heartbeatOn: Date | null;
+        heartbeatSeconds: number | null;
+        blocked: boolean;
+        blocking: boolean;
+        pendingDependencies: number;
+        deadLetter: string;
+        output: object;
+        sourceName: string | null;
+        sourceId: string | null;
+        sourceCreatedOn: Date | null;
+        sourceRetryCount: number | null;
+        sourceOutput: object | null;
+        sourceRootId: string | null;
+        data: TPayload["Type"];
+    }[], import("#error.ts").PgBossPayloadError | PgBossTestingError, TPayload["DecodingServices"]>;
+    revision: Effect.Effect<number, never, never>;
+    schemaVersion: Effect.Effect<number | null, PgBossTestingError, never>;
+    waitForChange: (after: number) => Effect.Effect<number>;
+};
+export type PgBossTesting = ReturnType<typeof makePgBossTesting>;
+//# sourceMappingURL=testing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAY,MAAM,QAAQ,CAAC;AAE1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAK/C,eAAO,MAAM,eAAe;;;EAAwD,CAAC;AAErF,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,eAAe,CAAC;CAC9C;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,oBAAyB;8BAuBxC,eAAe,sBAAsB,MAAM;mCAqBtC,MAAM;;yBAOhB,eAAe,YAAY,MAAM;0BAUhC,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMtC;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/server/testing.js

@@ -0,0 +1,69 @@
+import { Effect, Redacted } from "effect";
+import { PgBoss } from "pg-boss";
+import { PgBossTestingError } from "#error.ts";
+import { testingClient } from "#internal/testingClient.ts";
+import { testingOperation, testingReadout } from "#internal/testingReadout.ts";
+import { testingSignal } from "#internal/testingSignal.ts";
+export const testRetryPolicy = Object.freeze({ retryBackoff: false, retryDelay: 0 });
+export function makePgBossTesting(options = {}) {
+    let current;
+    const signal = testingSignal();
+    const controls = {
+        changed: signal.changed,
+        expirations: new Map(),
+        failures: new Set(),
+        retryPolicy: options.retryPolicy ?? {},
+    };
+    function client() {
+        if (current === undefined) {
+            throw new Error("Provide the testing clientFactory to a jobs Layer first");
+        }
+        return current;
+    }
+    const clientFactory = (clientOptions) => {
+        if (current !== undefined) {
+            throw new Error("A testing controller owns one jobs client; create a controller per runtime");
+        }
+        current = new PgBoss({ ...clientOptions, "__test__enableSpies": true });
+        return testingClient(current, clientOptions.schema ?? "pgboss", controls);
+    };
+    return {
+        checkBatchWindow: (queue, millisecondsPerJob) => 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) => testingOperation("checkSchemaVersion", async () => {
+            if ((await client().schemaVersion()) !== expected) {
+                throw new Error(`Expected pg-boss schema version ${expected}`);
+            }
+        }),
+        clientFactory,
+        expireAfter: (queue, attempts) => 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);
+            },
+        }),
+        failNextSend: (queue) => Effect.sync(() => controls.failures.add(queue.name)).pipe(Effect.asVoid),
+        jobs: testingReadout(client),
+        revision: signal.revision,
+        schemaVersion: testingOperation("schemaVersion", () => client().schemaVersion()),
+        waitForChange: signal.waitForChange,
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/server/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/effect-pg-boss",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Effect-native jobs and lifecycle management for pg-boss",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/effect-pg-boss#readme",
   "bugs": {
@@ -43,8 +43,9 @@
     "README.md"
   ],
   "devDependencies": {
-    "@shivaedev/effect-test-sql": "0.5.3",
+    "@shivaedev/effect-test-sql": "0.5.4",
     "@shivaedev/quality": "0.23.0",
+    "@shivaedev/test-story": "0.6.0",
     "@types/node": "24.19.2",
     "@typescript/native": "npm:typescript@7.0.2",
     "effect": "4.0.4",

package/src/server/error.ts

@@ -37,6 +37,12 @@ export class PgBossPayloadError extends Data.TaggedError("PgBossPayloadError")<{
 	readonly original: Redacted.Redacted<unknown>;
 }> {}
 
+export class PgBossTestingError extends Data.TaggedError("PgBossTestingError")<{
+	readonly operation: string;
+	readonly original: Redacted.Redacted<unknown>;
+	readonly queue?: string | undefined;
+}> {}
+
 export const toPgBossError = (operation: PgBossOperation, error: unknown, queue?: string): PgBossError =>
 	new PgBossError({
 		operation,

package/src/server/internal/expireAttempt.ts

@@ -0,0 +1,18 @@
+import type { Job, PgBoss } from "pg-boss";
+
+export async function expireAttempt(client: PgBoss, schema: string, job: Job<unknown>): Promise<void> {
+	if ((await client.schemaVersion()) !== 45) {
+		throw new Error("Testing expiry requires pg-boss schema version 45");
+	}
+	const quoted = `"${schema.replaceAll('"', '""')}"`;
+	await client.getDb().executeSql(
+		`UPDATE ${quoted}.job SET started_on = ${quoted}.job_now() - (expire_seconds + 1) * interval '1 second'
+		WHERE name = $1 AND id = $2 AND retry_count = $3 AND state = 'active'`,
+		[job.name, job.id, job.retryCount],
+	);
+	// Supervision owns expiry and dead lettering; make its claim due with the job's deadline.
+	await client
+		.getDb()
+		.executeSql(`UPDATE ${quoted}.queue SET monitor_claim_on = ${quoted}.job_now() - interval '1 week' WHERE name = $1`, [job.name]);
+	await client.supervise(job.name);
+}

package/src/server/internal/observeTestingSettlements.ts

@@ -0,0 +1,36 @@
+import type { PgBoss } from "pg-boss";
+
+export function observeTestingSettlements(client: PgBoss, changed: () => void) {
+	const observers = new Map<string, () => void>();
+	return {
+		close() {
+			for (const close of observers.values()) {
+				close();
+			}
+			observers.clear();
+		},
+		watch(name: string) {
+			if (observers.has(name)) {
+				return;
+			}
+			const spy = client.getSpy(name);
+			let open = true;
+			async function observe() {
+				while (true) {
+					await Promise.race([spy.waitForJob(() => true, "completed"), spy.waitForJob(() => true, "failed")]);
+					if (!open) {
+						return;
+					}
+					// This controller owns the spy; clear history and the losing wait before rearming both outcomes.
+					spy.clear();
+					changed();
+				}
+			}
+			observers.set(name, () => {
+				open = false;
+				spy.clear();
+			});
+			void observe().catch((error: unknown) => client.emit("error", error instanceof Error ? error : new Error(String(error))));
+		},
+	};
+}

package/src/server/internal/testingClient.ts

@@ -0,0 +1,115 @@
+import type { Job, PgBoss, SendOptions, UpdateOptions, UpdateRequest, UpdateResponse } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { expireAttempt } from "#internal/expireAttempt.ts";
+import { observeTestingSettlements } from "#internal/observeTestingSettlements.ts";
+import { testingExpirations } from "#internal/testingExpirations.ts";
+
+export interface TestingControls {
+	readonly changed: () => void;
+	readonly expirations: Map<string, number>;
+	readonly failures: Set<string>;
+	readonly retryPolicy: Pick<SendOptions, "retryBackoff" | "retryDelay">;
+}
+
+export function testingClient(client: PgBoss, schema: string, controls: TestingControls): PgBossClient {
+	const settlements = observeTestingSettlements(client, 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> {
+		const result = typeof request === "string" ? await client.update(request, data, options) : await client.update(request);
+		controls.changed();
+		return result;
+	}
+	const overrides: Partial<PgBossClient> = {
+		complete: async (...args) => {
+			const result = await client.complete(...args);
+			controls.changed();
+			return result;
+		},
+		createQueue: (name, options) => {
+			const { retryDelayMax, ...rest } = options ?? {};
+			return client.createQueue(name, {
+				...rest,
+				...(controls.retryPolicy.retryBackoff === false || retryDelayMax === undefined ? {} : { retryDelayMax }),
+				...controls.retryPolicy,
+			});
+		},
+		fail: async (...args) => {
+			const result = await client.fail(...args);
+			controls.changed();
+			return result;
+		},
+		retry: async (...args) => {
+			const result = await client.retry(...args);
+			controls.changed();
+			return result;
+		},
+		send: async (name, data, options) => {
+			if (controls.failures.delete(name)) {
+				throw new Error("Injected pg-boss send failure");
+			}
+			const attempts = controls.expirations.get(name);
+			const { retryDelayMax, ...rest } = options ?? {};
+			const id = await expirations.send(
+				name,
+				data,
+				{
+					...rest,
+					...(controls.retryPolicy.retryBackoff === false || retryDelayMax === undefined ? {} : { retryDelayMax }),
+					...controls.retryPolicy,
+					...(attempts === undefined ? {} : { retryLimit: attempts - 1 }),
+				},
+				attempts,
+			);
+			controls.changed();
+			return id;
+		},
+		stop: async (options) => {
+			try {
+				await client.stop(options);
+			} finally {
+				settlements.close();
+			}
+		},
+		update,
+		updateQueue: (name, options) =>
+			client.updateQueue(name, {
+				...options,
+				...controls.retryPolicy,
+				...(controls.retryPolicy.retryBackoff === false ? { retryDelayMax: null } : {}),
+			}),
+		work: (name, options, handler) => {
+			settlements.watch(name);
+			return client.work(name, options, async (jobs: Job<unknown>[]) => {
+				controls.changed();
+				try {
+					const ready: Job<unknown>[] = [];
+					for (const job of jobs) {
+						const attempts = await expirations.attemptsFor(job);
+						if (attempts !== undefined && job.retryCount + 1 >= attempts) {
+							await expireAttempt(client, schema, job);
+						} else {
+							ready.push(job);
+						}
+					}
+					if (ready.length > 0) {
+						await handler(ready);
+					}
+				} finally {
+					controls.changed();
+				}
+			});
+		},
+	};
+	return new Proxy(client, {
+		get(target, property) {
+			if (Object.hasOwn(overrides, property)) {
+				const override: unknown = Reflect.get(overrides, property);
+				return override;
+			}
+			const value: unknown = Reflect.get(target, property);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}

package/src/server/internal/testingExpirations.ts

@@ -0,0 +1,31 @@
+import type { Job, PgBoss, SendOptions } from "pg-boss";
+
+export function testingExpirations(client: PgBoss) {
+	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) {
+			if (attempts === undefined && options.id === undefined) {
+				return client.send(name, data, options);
+			}
+			const id = options.id ?? crypto.randomUUID();
+			const key = `${name}:${id}`;
+			const previous = snapshots.get(key);
+			const sending = client.send(name, data, { ...options, id });
+			// A worker may claim the row before send returns. Wait for its result before applying the snapshot.
+			const snapshot = sending
+				.then(
+					(sent) => (sent === id ? attempts : previous),
+					() => previous,
+				)
+				.then((value) => {
+					if (value === undefined && snapshots.get(key) === snapshot) {
+						snapshots.delete(key);
+					}
+					return value;
+				});
+			snapshots.set(key, snapshot);
+			return sending;
+		},
+	};
+}

package/src/server/internal/testingReadout.ts

@@ -0,0 +1,26 @@
+import { Effect, Redacted, Schema } from "effect";
+import type { FindJobsOptions, PgBoss } from "pg-boss";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
+import { PgBossPayloadError, PgBossTestingError } from "#error.ts";
+import { payloadOf } from "#internal/tracing.ts";
+
+export function testingOperation<A>(operation: string, run: () => Promise<A>, queue?: string) {
+	return Effect.tryPromise({
+		catch: (original) => new PgBossTestingError({ operation, original: Redacted.make(original), queue }),
+		try: run,
+	});
+}
+
+export function testingReadout(client: () => PgBoss) {
+	return <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: FindJobsOptions) =>
+		testingOperation("jobs", () => client().findJobs<unknown>(queue.name, options), queue.name).pipe(
+			Effect.flatMap((jobs) =>
+				Effect.forEach(jobs, (job) =>
+					Schema.decodeUnknownEffect(queue.schema)(payloadOf(job.data)).pipe(
+						Effect.mapError((original) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(original), queue: queue.name })),
+						Effect.map((data) => ({ ...job, data })),
+					),
+				),
+			),
+		);
+}

package/src/server/internal/testingSignal.ts

@@ -0,0 +1,28 @@
+import { Effect } from "effect";
+
+export function testingSignal() {
+	let revision = 0;
+	const listeners = new Set<(revision: number) => void>();
+	return {
+		changed() {
+			revision += 1;
+			for (const listener of listeners) {
+				listener(revision);
+			}
+			listeners.clear();
+		},
+		revision: Effect.sync(() => revision),
+		waitForChange: (after: number): Effect.Effect<number> =>
+			Effect.callback((resume) => {
+				if (revision !== after) {
+					resume(Effect.succeed(revision));
+					return;
+				}
+				function listener(current: number) {
+					resume(Effect.succeed(current));
+				}
+				listeners.add(listener);
+				return Effect.sync(() => listeners.delete(listener));
+			}),
+	};
+}

package/src/server/testing.ts

@@ -0,0 +1,85 @@
+import { Effect, Redacted } from "effect";
+import { PgBoss } from "pg-boss";
+import type { PgBossClientFactory } from "#client.ts";
+import type { QueueDefinition } from "#definition.ts";
+import { PgBossTestingError } from "#error.ts";
+import { testingClient } from "#internal/testingClient.ts";
+import { testingOperation, testingReadout } from "#internal/testingReadout.ts";
+import { testingSignal } from "#internal/testingSignal.ts";
+
+export const testRetryPolicy = Object.freeze({ retryBackoff: false, retryDelay: 0 });
+
+export interface PgBossTestingOptions {
+	readonly retryPolicy?: typeof testRetryPolicy;
+}
+
+export function makePgBossTesting(options: PgBossTestingOptions = {}) {
+	let current: PgBoss | undefined;
+	const signal = testingSignal();
+	const controls = {
+		changed: signal.changed,
+		expirations: new Map<string, number>(),
+		failures: new Set<string>(),
+		retryPolicy: options.retryPolicy ?? {},
+	};
+	function client(): PgBoss {
+		if (current === undefined) {
+			throw new Error("Provide the testing clientFactory to a jobs Layer first");
+		}
+		return current;
+	}
+	const clientFactory: PgBossClientFactory = (clientOptions) => {
+		if (current !== undefined) {
+			throw new Error("A testing controller owns one jobs client; create a controller per runtime");
+		}
+		current = new PgBoss({ ...clientOptions, "__test__enableSpies": true });
+		return testingClient(current, clientOptions.schema ?? "pgboss", controls);
+	};
+	return {
+		checkBatchWindow: (queue: QueueDefinition, 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: QueueDefinition, 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);
+				},
+			}),
+		failNextSend: (queue: QueueDefinition) => Effect.sync(() => controls.failures.add(queue.name)).pipe(Effect.asVoid),
+		jobs: testingReadout(client),
+		revision: signal.revision,
+		schemaVersion: testingOperation("schemaVersion", () => client().schemaVersion()),
+		waitForChange: signal.waitForChange,
+	};
+}
+
+export type PgBossTesting = ReturnType<typeof makePgBossTesting>;