@shivaedev/jobs 0.22.0 → 0.23.0

package/README.md

@@ -12,13 +12,11 @@ import { Effect, Schema } from "effect";
 import { Mail } from "./services.ts";
 
 const SendEmail = defineQueue({
-  name: "send-email",
-  schema: Schema.Struct({ userId: Schema.NumberFromString }),
+	name: "send-email",
+	schema: Schema.Struct({ userId: Schema.NumberFromString }),
 });
 
-const emailWorker = SendEmail.handle(({ userId }) =>
-  Effect.flatMap(Mail, (mail) => mail.send(userId)),
-);
+const emailWorker = SendEmail.handle(({ userId }) => Effect.flatMap(Mail, (mail) => mail.send(userId)));
 ```
 
 `Mail` is the application's Effect service, defined in the guide below. The worker receives a number even though the durable payload stores a string. The same Schema encodes the producer's payload and decodes the worker's input; malformed stored data fails before the handler runs. Provide the worker's services when the jobs Layer starts, and the handler uses that captured context when pg-boss calls it later.
@@ -31,7 +29,7 @@ A **queue definition** names a pg-boss queue and the Schema of its payload. Appl
 
 A **schedule definition** describes a queue with a cron trigger. `schedule.run(effect)` pairs it with an Effect that needs no payload. Queue workers and scheduled workers are **registrations**: the values you put in the jobs Layer's `jobs` list.
 
-The application creates one jobs service with `makePgBoss(identifier)`. Its Layer starts a client, registers the job list and captures the services those workers need. The Layer's scope owns its client reference and releases it when the scope ends; the final reference closes the client. Callers use the jobs service to enqueue a decoded payload, look up or retry a job, read queue health and live counts, or list failed and dead-lettered jobs.
+The application creates one jobs service with `makePgBoss(identifier)`. Its Layer reads the shared `PgBoss` service, registers the job list and captures the services those workers need. One `pgBossLayer` owns the client and pool for the application; feature registrations drain before that Layer closes its client. Callers use the jobs service to enqueue a decoded payload, look up or retry a job, read queue health and live counts, or list failed and dead-lettered jobs.
 
 Use a distinct literal identifier for each jobs service. The service and its Layer keep that identifier in their types, so providing a Layer for a different identifier leaves the required jobs service unprovided at compile time.
 
@@ -46,19 +44,19 @@ import { pgBossSchema } from "@shivaedev/jobs/server/schema.ts";
 import { appDatabase } from "@shivaedev/server/appHost.ts";
 
 const database = appDatabase({
-  migrations: {
-    loader,
-    components: [pgBossSchema({ schema: "app_jobs" })],
-    mode: "migrate",
-  },
+	migrations: {
+		loader,
+		components: [pgBossSchema({ schema: "app_jobs" })],
+		mode: "migrate",
+	},
 });
 ```
 
 The component uses `installPgBossSchema` as its only install and upgrade path. It is pending when the schema is missing or its stored version is below the installed pg-boss package's required schema version; the readiness error names the schema and both versions (`missing` for an absent version). Start every producer and worker with the same schema and `migrate: false`. Use host mode `"wait"` for services that must wait for a deployment's migration process; no additional jobs-layer wait is needed.
 
-With server's `appDatabase({ migrations: { mode: "wait", release, ... } })`, each jobs Layer automatically reads sql's optional `WorkerRelease` Context service. When the database belongs to another release, it calls pg-boss `offWork` for every registered worker queue, lets active jobs finish, logs `Workers paused for another database release` once, and idles. Producers and enqueueing continue. When its release owns the marker again and old workers have drained, it registers workers through the normal path and logs `Workers resumed for database release`. Equality permits rollbacks; no version ordering or payload compatibility policy is added. With no service, registration behaves as before.
+With server's `appDatabase({ migrations: { mode: "wait", release, ... } })`, each jobs Layer automatically reads sql's optional `WorkerRelease` Context service. When the database belongs to another release, it calls pg-boss `offWork` for every registered worker queue, lets active jobs finish, logs `Workers paused for another database release` once, and idles. Producers and enqueueing continue. When its release owns the marker again and old workers have drained, it registers workers through the normal path and logs `Workers resumed for database release`. Equality permits rollbacks; no version ordering or payload compatibility policy is added. Without that service, the Layer registers its workers at startup and never pauses them.
 
-A worker keeps its sql heartbeat row live while draining; the owning release waits for all other live releases to step aside. A crashed worker stops blocking once its heartbeat is older than five polling intervals. Set an explicit queue `expireInSeconds` and a `stop: { graceful: true, timeout }` long enough to cover it. Scope shutdown on SIGTERM waits for the native pg-boss stop before releasing application dependencies. Give the host's termination grace a margin beyond that timeout; the starter uses 60-second expiry, 65-second stop and 75-second Railway draining.
+A paused worker keeps its process registered with sql's worker release while active jobs drain, so the owning release waits for it; [sql's worker release](https://github.com/ShivaeDev/platform/blob/main/packages/sql/README.md) owns the heartbeat and how long a crashed worker can block. Closing the jobs Layer's scope waits for the native pg-boss `stop` before releasing the services the Layer captured. Choose the three bounds together: each queue's `expireInSeconds`, a `stop: { graceful: true, timeout }` in milliseconds that covers it, and a host termination grace beyond that timeout. For example, a queue with `expireInSeconds: 60` pairs with `stop: { graceful: true, timeout: 65_000 }` under a 75-second termination grace.
 
 `installPgBossSchema` installs or upgrades pg-boss through the provided Effect SQL client without starting workers or schedules. Run it outside an application transaction, in a release step or the `fixtures` Effect of `makePostgresTestLayer`, so stories inherit the schema from the migrated template:
 
@@ -70,7 +68,7 @@ const jobsFixture = installPgBossSchema({ schema: "app_jobs" });
 
 The Effect requires `SqlClient` and fails with `PgBossError` whose `operation` is `"install"`. The schema defaults to `"pgboss"`. Repeating installation preserves existing jobs. Upgrades apply pg-boss's migration SQL and concurrent index builds, including partition indexes, before returning. Pending index commands are recorded in pg-boss's BAM table in the same transaction as the schema version. A retry resumes unfinished commands and repairs invalid indexes left by failed builds, even when the schema version has already committed.
 
-After installation, pass the same schema and `migrate: false` to `Jobs.layer` to start producers and workers without schema installation or migration. Startup fails if the schema is missing. Ordinary Layer startup retains pg-boss's default migration behavior when `migrate` is omitted.
+After installation, pass the same schema and `migrate: false` to `pgBossLayer` to start producers and workers without schema installation or migration. Startup fails if the schema is missing. Ordinary Layer startup retains pg-boss's default migration behavior when `migrate` is omitted.
 
 ### Once per application: the jobs service
 
@@ -78,19 +76,22 @@ Define the application's jobs service and worker dependencies in `services.ts`:
 
 ```ts
 import { makePgBoss } from "@shivaedev/jobs/server/service.ts";
-import { Context, Effect, Layer } from "effect";
+import { Effect } from "effect";
+import { defineService } from "@shivaedev/service/defineService.ts";
 
 export const Jobs = makePgBoss("@app/Jobs");
 
-export class Mail extends Context.Service<Mail, {
-  readonly send: (userId: number) => Effect.Effect<void>;
-  readonly removeExpired: Effect.Effect<void>;
-}>()("@app/Mail") {}
-
-export const MailLive = Layer.succeed(Mail, {
-  send: (userId) => Effect.log({ event: "send_email", userId }),
-  removeExpired: Effect.log({ event: "remove_expired_mail" }),
+export const Mail = defineService({
+	id: "@app/Mail",
+	requires: [],
+	initialize: Effect.void,
+	methods: () => ({
+		send: (userId: number) => Effect.log({ event: "send_email", userId }),
+		removeExpired: () => Effect.log({ event: "remove_expired_mail" }),
+	}),
 });
+
+export const MailLive = Mail.layer;
 ```
 
 `Jobs` is the service that callers yield. `Mail` is a separate domain service that workers use. The example implementation logs calls so the wiring is complete; an application supplies its own implementation of those methods. The jobs package does not need a provider-specific interface.
@@ -105,27 +106,25 @@ import { Effect, Schema } from "effect";
 import { Mail } from "./services.ts";
 
 export const SendEmail = defineQueue({
-  name: "send-email",
-  schema: Schema.Struct({ userId: Schema.NumberFromString }),
-  queue: { retryLimit: 5 },
+	name: "send-email",
+	schema: Schema.Struct({ userId: Schema.NumberFromString }),
+	queue: { retryLimit: 5 },
 });
 
 export const emailWorker = SendEmail.handle(({ userId }, job) =>
-  Effect.gen(function* () {
-    const mail = yield* Mail;
-    yield* mail.send(userId);
-    yield* Effect.log({ jobId: job.id });
-  }),
+	Effect.gen(function* () {
+		const mail = yield* Mail;
+		yield* mail.send(userId);
+		yield* Effect.log({ jobId: job.id });
+	}),
 );
 
 export const Cleanup = defineSchedule({
-  name: "cleanup-mail",
-  cron: "17 3 * * *",
+	name: "cleanup-mail",
+	cron: "17 3 * * *",
 });
 
-export const cleanupWorker = Cleanup.run(
-  Effect.flatMap(Mail, (mail) => mail.removeExpired),
-);
+export const cleanupWorker = Cleanup.run(Effect.flatMap(Mail, (mail) => mail.removeExpired()));
 ```
 
 The queue takes `{ userId: number }` in application code and stores `{ userId: string }`. Its handler receives the decoded number and a job context, including the job's `id`. Keep the queue definition available to producers; the runtime registers the worker created by `handle`.
@@ -142,16 +141,16 @@ Queue and schedule workers default to `batchSize: 10` and `burstWhenBatchFull: t
 
 ```ts
 const Compare = defineQueue({
-  name: "compare",
-  schema: Schema.Struct({ id: Schema.Number }),
-  queue: { notify: true },
-  worker: { batchSize: 2, localConcurrency: 5 },
+	name: "compare",
+	schema: Schema.Struct({ id: Schema.Number }),
+	queue: { notify: true },
+	worker: { batchSize: 2, localConcurrency: 5 },
 });
 ```
 
 This worker runs up to five handlers at once. `worker` accepts pg-boss 12's `WorkOptions`, including `batchSize`, `localConcurrency`, `pollingIntervalSeconds`, `notifyPollingIntervalSeconds` and the burst options. Explicit options override the adapter defaults. pg-boss ignores `burstWhenBatchFull` at `batchSize: 1`; keep a batch size of at least two for immediate backlog draining. Each job is settled separately through pg-boss: success completes that job, and a typed failure, payload decoding failure or defect fails only that job with its own error. A failed job does not spend the retries of other jobs in its batch or rerun their successful handlers. Interruption stops the batch and leaves the interrupted and remaining jobs to pg-boss expiry; handlers must still tolerate repeated side effects across retries and interrupted attempts.
 
-Apps do not need to shorten the polling backstop to drain a backlog. With `notify: true` and an active LISTEN/NOTIFY listener, pg-boss wakes workers on notifications and defaults to a 30-second backstop (`notifyPollingIntervalSeconds`). Without active notifications its base poll defaults to two seconds (`pollingIntervalSeconds`). Bursting takes precedence over both intervals. After an adapter worker fails a job, it reads pg-boss's stored retry time and schedules a wake for every native worker in its registration at that time, so an idle sibling can retry while another worker is busy. The wake belongs to the worker Layer's scope and is canceled when that scope closes. Override the backstop when the application needs a different bound for other work that becomes runnable without a notification, such as delayed jobs or retries initiated outside the adapter worker.
+Apps do not need to shorten the polling backstop to drain a backlog. With `notify: true` and an active LISTEN/NOTIFY listener, pg-boss wakes workers on notifications and defaults to a 30-second backstop (`notifyPollingIntervalSeconds`). Without active notifications its base poll defaults to two seconds (`pollingIntervalSeconds`). Bursting takes precedence over both intervals. After an adapter worker fails a job, it reads pg-boss's stored retry time and schedules a wake for every native worker in its registration at that time, so an idle sibling can retry while another worker is busy. The wake, including its retry-time read, belongs to the worker Layer's scope and is canceled when that scope closes. Wake failures are logged with redacted diagnostics and do not fail the batch. Override the backstop when the application needs a different bound for other work that becomes runnable without a notification, such as delayed jobs or retries initiated outside the adapter worker.
 
 ### Defer until a provider is ready
 
@@ -161,10 +160,12 @@ Fail a queue handler or scheduled Effect with `RetryAt` when a provider gives a
 import { DateTime, Effect } from "effect";
 import { RetryAt } from "@shivaedev/jobs/server/definition.ts";
 
-const waitForQuota = Effect.fail(new RetryAt({
-  at: DateTime.makeUnsafe("2030-01-01T00:01:00Z"),
-  reason: "Provider quota resets",
-}));
+const waitForQuota = Effect.fail(
+	new RetryAt({
+		at: DateTime.makeUnsafe("2030-01-01T00:01:00Z"),
+		reason: "Provider quota resets",
+	}),
+);
 ```
 
 The same job returns to waiting with `startAfter` set to `at`; its ID, singleton key, payload and retry count stay unchanged. A past or current `at` is eligible on the next fetch. Deferral does not dead-letter the job or call `onError`. Its job span ends OK with a `job.deferred` event whose `at` is an ISO UTC string and whose `reason` is the supplied string. Deferred jobs rely on polling, including queues using `notify: true`. Stately jobs sharing a singleton key can defer together and still run one at a time. While waiting, their native job metadata reports the adapter's `effect-stately-deferred` policy; a database trigger restores `stately` when pg-boss claims them, preserving its active-job exclusion.
@@ -177,19 +178,17 @@ Put related job kinds in one tagged-union queue and choose the entity key in the
 
 ```ts
 const PullRequestJobs = defineQueue({
-  name: "pull-request",
-  schema: Schema.Union([
-    Schema.TaggedStruct("Refresh", { pullRequestId: Schema.NumberFromString }),
-    Schema.TaggedStruct("Reconcile", { pullRequestId: Schema.NumberFromString }),
-  ]),
-  queue: { policy: "singleton" },
-  key: ({ pullRequestId }) => `pr:${pullRequestId.toFixed(0)}`,
-  worker: { batchSize: 1, localConcurrency: 3 },
+	name: "pull-request",
+	schema: Schema.Union([
+		Schema.TaggedStruct("Refresh", { pullRequestId: Schema.NumberFromString }),
+		Schema.TaggedStruct("Reconcile", { pullRequestId: Schema.NumberFromString }),
+	]),
+	queue: { policy: "singleton" },
+	key: ({ pullRequestId }) => `pr:${pullRequestId.toFixed(0)}`,
+	worker: { batchSize: 1, localConcurrency: 3 },
 });
 
-const refresh = Effect.flatMap(Jobs, (jobs) =>
-  jobs.enqueue(PullRequestJobs, { _tag: "Refresh", pullRequestId: 42 }),
-);
+const refresh = Effect.flatMap(Jobs, (jobs) => jobs.enqueue(PullRequestJobs, { _tag: "Refresh", pullRequestId: 42 }));
 ```
 
 `queue.policy` accepts pg-boss's policy literals and rejects typos. The `singleton` policy requires `key: (payload) => string`. The callback sees the decoded payload, so `pullRequestId` is a number. `enqueue` supplies pg-boss's `singletonKey` automatically; callers cannot supply a conflicting key in send options.
@@ -204,15 +203,15 @@ pg-boss marks every job in a fetched batch active together. Each job's expiry wi
 
 ```ts
 const Ingest = defineQueue({
-  name: "ingest",
-  schema: Schema.Struct({ sourceId: Schema.String }),
-  queue: { expireInSeconds: 300 },
-  worker: { batchSize: 1 },
+	name: "ingest",
+	schema: Schema.Struct({ sourceId: Schema.String }),
+	queue: { expireInSeconds: 300 },
+	worker: { batchSize: 1 },
 });
 
 const IndexTitle = defineQueue({
-  name: "index-title",
-  schema: Schema.Struct({ titleId: Schema.String }),
+	name: "index-title",
+	schema: Schema.Struct({ titleId: Schema.String }),
 });
 ```
 
@@ -228,10 +227,10 @@ Queue handlers can yield `job.remainingBudget`, an `Effect.Effect<Duration.Durat
 import { Duration, Effect } from "effect";
 
 const ingestWorker = Ingest.handle(({ sourceId }, job) =>
-  Effect.gen(function* () {
-    const budget = yield* job.remainingBudget;
-    yield* Effect.log({ sourceId, remainingMilliseconds: Duration.toMillis(budget) });
-  }),
+	Effect.gen(function* () {
+		const budget = yield* job.remainingBudget;
+		yield* Effect.log({ sourceId, remainingMilliseconds: Duration.toMillis(budget) });
+	}),
 );
 ```
 
@@ -242,36 +241,36 @@ Keep handler work interruptible and use cancellation-aware Effect integrations f
 Build the jobs Layer in `runtime.ts`:
 
 ```ts
-import { Layer } from "effect";
+import { Layer, type Redacted } from "effect";
+import { pgBossLayer } from "@shivaedev/jobs/server/service.ts";
 import { cleanupWorker, emailWorker } from "./jobs.ts";
 import { Jobs, MailLive } from "./services.ts";
 
-export const jobsLayer = (databaseUrl: string) =>
-  Jobs.layer({
-    connectionString: databaseUrl,
-    schema: "app_jobs",
-    jobs: [emailWorker, cleanupWorker],
-  }).pipe(Layer.provide(MailLive));
+export const jobsLayer = (databaseUrl: Redacted.Redacted<string>) =>
+	Jobs.layer({ jobs: [emailWorker, cleanupWorker] }).pipe(
+		Layer.provide(MailLive),
+		Layer.provide(pgBossLayer({ connectionString: databaseUrl, schema: "app_jobs" })),
+	);
 ```
 
-The constructor options belong to pg-boss. `jobs` is the complete list of registrations for this Layer. The Layer captures `MailLive` for both the queue handler and the scheduled Effect. A startup or registration failure fails Layer acquisition with `PgBossError` or `PgBossQueueOptionsError` and releases its acquired client reference. Registration creates a queue again, up to six times with a short backoff, when PostgreSQL rolls the creation back as a deadlock victim (SQLSTATE `40P01`), which a partitioned queue can meet when other queues in the schema have traffic. A shared client stays running while another scope still owns a reference.
+The redacted connection string is unwrapped only at the pg-boss adapter. Put connection, pool size, client factory, schema, migration and stop settings in `pgBossLayer`. Provide the same Layer to the merged registration, worker and producer services so native Layer memoization starts one client. `jobs` is the complete list of registrations for this Layer. The Layer captures `MailLive` for both the queue handler and the scheduled Effect. A startup or registration failure fails Layer acquisition with `PgBossError` or `PgBossQueueOptionsError` and closes its registrations. The owning app Layer releases the client. Registration creates a queue again, up to six times with a short backoff, when PostgreSQL rolls the creation back as a deadlock victim (SQLSTATE `40P01`), which a partitioned queue can meet when other queues in the schema have traffic. A shared client stays running while another scope still owns a reference.
 
 Keep the Layer in the application's worker runtime scope. A short scope is useful for an acquisition or health check; a worker process needs its scope to remain open while it handles jobs.
 
-Set `clientCacheKey` to share one reference-counted client across Layer builds with equal pg-boss constructor settings. Reusing a key with different settings fails acquisition with `PgBossClientOptionsError` before constructing another client. Its `key`, `options` and message identify the key and differing option names without exposing connection values. Nested options are compared by value.
+Set `clientCacheKey` on `pgBossLayer` to share one reference-counted client across Layer builds with equal pg-boss constructor settings. Reusing a key with different settings fails acquisition with `PgBossClientOptionsError` before constructing another client. Its `key`, `options` and message identify the key and differing option names without exposing connection values. Nested options are compared by value.
 
 ```ts
-import { Effect } from "effect";
+import { Effect, type Redacted } from "effect";
 import { jobsLayer } from "./runtime.ts";
 import { Jobs } from "./services.ts";
 
-const inspectJobs = (databaseUrl: string) =>
-  Effect.scoped(
-    Effect.gen(function* () {
-      const jobs = yield* Jobs;
-      return yield* jobs.health;
-    }).pipe(Effect.provide(jobsLayer(databaseUrl))),
-  );
+const inspectJobs = (databaseUrl: Redacted.Redacted<string>) =>
+	Effect.scoped(
+		Effect.gen(function* () {
+			const jobs = yield* Jobs;
+			return yield* jobs.health();
+		}).pipe(Effect.provide(jobsLayer(databaseUrl))),
+	);
 ```
 
 This Effect starts the jobs Layer, reads health and closes the scope. The client stops when that scope closes.
@@ -284,10 +283,10 @@ import { SendEmail } from "./jobs.ts";
 import { Jobs } from "./services.ts";
 
 export const enqueueEmail = (userId: number) =>
-  Effect.gen(function* () {
-    const jobs = yield* Jobs;
-    return yield* jobs.enqueue(SendEmail, { userId });
-  });
+	Effect.gen(function* () {
+		const jobs = yield* Jobs;
+		return yield* jobs.enqueue(SendEmail, { userId });
+	});
 ```
 
 Provide `Jobs` through the application's existing runtime. `enqueue` takes the decoded payload, so passing a string `userId` is a type error. It encodes the number to a string before calling pg-boss. The result type is `Option.Option<string>`: a job identifier becomes `Some`, and a `null` send result becomes `None`.
@@ -309,15 +308,15 @@ import { Effect } from "effect";
 import { Jobs } from "./services.ts";
 
 export const readJobCounts = Effect.gen(function* () {
-  const jobs = yield* Jobs;
-  const health = yield* jobs.health;
-  return {
-    active: health.activeTotal,
-    deadLettered: health.deadLetteredTotal,
-    failed: health.failedTotal,
-    queued: health.queuedTotal,
-    ready: health.readyTotal,
-  };
+	const jobs = yield* Jobs;
+	const health = yield* jobs.health();
+	return {
+		active: health.activeTotal,
+		deadLettered: health.deadLetteredTotal,
+		failed: health.failedTotal,
+		queued: health.queuedTotal,
+		ready: health.readyTotal,
+	};
 });
 ```
 
@@ -330,15 +329,16 @@ import { Effect, Option } from "effect";
 import { SendEmail } from "./jobs.ts";
 import { Jobs } from "./services.ts";
 
-export const inspectEmail = (id: string) => Effect.gen(function* () {
-  const jobs = yield* Jobs;
-  const job = yield* jobs.getJob(SendEmail, id);
-  if (Option.isSome(job) && job.value.state === "failed") {
-    yield* jobs.retry(SendEmail, id);
-  }
-  const counts = yield* jobs.counts(SendEmail);
-  return counts.queuedCount === 0 && counts.activeCount === 0;
-});
+export const inspectEmail = (id: string) =>
+	Effect.gen(function* () {
+		const jobs = yield* Jobs;
+		const job = yield* jobs.getJob(SendEmail, id);
+		if (Option.isSome(job) && job.value.state === "failed") {
+			yield* jobs.retry(SendEmail, id);
+		}
+		const counts = yield* jobs.counts(SendEmail);
+		return counts.queuedCount === 0 && counts.activeCount === 0;
+	});
 ```
 
 `counts(queue)` reads the job table directly on each call. `queuedCount` includes created and retry-waiting jobs, including future jobs; `activeCount` counts running jobs, `failedCount` counts retained failures, and `totalCount` includes retained terminal jobs. A queue has drained when queued and active counts are both zero. These counts are a snapshot, so a producer can enqueue more work after the query returns.
@@ -352,23 +352,24 @@ import { Effect, Option } from "effect";
 import { SendEmail } from "./jobs.ts";
 import { Jobs } from "./services.ts";
 
-export const failedEmails = (cursor?: string) => Effect.gen(function* () {
-  const jobs = yield* Jobs;
-  const failed = yield* jobs.failedJobs(SendEmail, { cursor, limit: 20 });
-  const deadLettered = yield* jobs.deadLetteredJobs(SendEmail, { limit: 20 });
-  return {
-    deadLettered: deadLettered.jobs.map((job) => ({ id: job.id, original: Option.getOrNull(job.sourceId), error: job.sourceOutput })),
-    failed: failed.jobs.map((job) => ({ id: job.id, attempt: job.attempt, error: job.output, userId: job.data.userId })),
-    next: Option.getOrUndefined(failed.next),
-  };
-});
+export const failedEmails = (cursor?: string) =>
+	Effect.gen(function* () {
+		const jobs = yield* Jobs;
+		const failed = yield* jobs.failedJobs(SendEmail, { cursor, limit: 20 });
+		const deadLettered = yield* jobs.deadLetteredJobs(SendEmail, { limit: 20 });
+		return {
+			deadLettered: deadLettered.jobs.map((job) => ({ id: job.id, original: Option.getOrNull(job.sourceId), error: job.sourceOutput })),
+			failed: failed.jobs.map((job) => ({ id: job.id, attempt: job.attempt, error: job.output, userId: job.data.userId })),
+			next: Option.getOrUndefined(failed.next),
+		};
+	});
 ```
 
 `health` and `counts` say how many jobs failed; these two listings say which ones and why. `failedJobs(queue, options)` lists the queue's jobs in the `failed` state, the ones that used up their retries. `deadLetteredJobs(queue, options)` lists every job in the queue's dead-letter queue. Dead-letter entries live in the `-dlq` queue: each is a new job with its own ID that pg-boss copied there when the original failed for good. Both listings read pg-boss's `job` table on each call, through the jobs Layer's own pg-boss connection and in its configured schema, so applications never query pg-boss tables themselves. A custom client needs the native `getDb` capability for them.
 
-Each page holds at most `limit` jobs, newest first by creation time; a dead-letter copy is created when its original fails for good. `limit` must be a positive integer. When more jobs remain, `next` is `Some` opaque cursor; pass it back as `cursor` for the following page, and stop when `next` is `None`. Paging continues from the last job it returned, so jobs that fail while you page appear in a fresh listing instead of shifting later pages, and no job appears twice. A malformed cursor or limit fails with `PgBossError` whose `operation` names the listing.
+Each page holds at most `limit` jobs, newest first by creation time; a dead-letter copy is created when its original fails for good. `limit` must be a positive integer. When more jobs remain, `next` is `Some` opaque cursor; pass it back as `cursor` for the following page, and stop when `next` is `None`. Paging continues from the last job it returned, so jobs that fail while you page appear in a fresh listing instead of shifting later pages, and no job appears twice. A malformed cursor or limit fails with `SchemaError` before pg-boss is called.
 
-An entry carries the job's `id`, `queue`, native `state`, `retryCount`, `retryLimit` and `attempt`, the one-based number of its last started attempt (zero for a job that never started). `createdOn` is a UTC `DateTime`; `startedOn` and `completedOn` are `Option`s of UTC `DateTime`s. `output` is the job's stored output as pg-boss recorded it: for a failed job, the error its last attempt failed with, and `null` when pg-boss stored none. `data` is decoded by the queue's Schema, including traced payloads; invalid stored data fails the listing with `PgBossPayloadError`, as `getJob` does, and the Effect requires the Schema's decoding services. A dead-letter entry adds `sourceId`, the original job's ID as an `Option`, and `sourceOutput`, the error the original failed with. The copy has not run, so its own `output` stays `null` and its `attempt` is zero.
+An entry carries the job's `id`, `queue`, native `state`, `retryCount`, `retryLimit` and `attempt`, the one-based number of its last started attempt (zero for a job that never started). `createdOn` is a UTC `DateTime`; `startedOn` and `completedOn` are `Option`s of UTC `DateTime`s. `output` is `JobFailure | null`, decoded through `JobFailure` from `@shivaedev/jobs/JobFailure.ts`. Handler failures store only `{ _tag: string, message: string }`, with the message redacted through `@shivaedev/errors`; stack traces, cause chains and other error fields are omitted. `null` means pg-boss stored no output. Native pg-boss failures without a tag decode with `_tag: "Error"`; decoding also redacts messages from older stored failures. Stored output that does not match the Schema fails the listing with `PgBossPayloadError`. `data` is decoded by the queue's Schema, including traced payloads; invalid stored data fails the listing with `PgBossPayloadError`, as `getJob` does, and the Effect requires the Schema's decoding services. A dead-letter entry adds `sourceId`, the original job's ID as an `Option`, and `sourceOutput`, the original's decoded `JobFailure | null`. The copy has not run, so its own `output` stays `null` and its `attempt` is zero.
 
 Pass a failed entry's `id` to `retry(queue, id)` to run that job again under its original ID; once it completes it leaves the failed listing. Dead-letter IDs belong to the `-dlq` queue, so `retry(queue, id)` does not find them and leaves them unchanged.
 
@@ -381,20 +382,19 @@ Startup creates missing queues and reconciles declared settings on existing queu
 ### Share a client between Layer builds
 
 ```ts
-import { Layer } from "effect";
+import { Layer, type Redacted } from "effect";
+import { pgBossLayer } from "@shivaedev/jobs/server/service.ts";
 import { cleanupWorker, emailWorker } from "./jobs.ts";
 import { Jobs, MailLive } from "./services.ts";
 
-const sharedJobsLayer = (databaseUrl: string) =>
-  Jobs.layer({
-    connectionString: databaseUrl,
-    schema: "app_jobs",
-    clientCacheKey: "app-jobs",
-    jobs: [emailWorker, cleanupWorker],
-  }).pipe(Layer.provide(MailLive));
+const sharedJobsLayer = (databaseUrl: Redacted.Redacted<string>) =>
+	Jobs.layer({ jobs: [emailWorker, cleanupWorker] }).pipe(
+		Layer.provide(MailLive),
+		Layer.provide(pgBossLayer({ connectionString: databaseUrl, schema: "app_jobs", clientCacheKey: "app-jobs" })),
+	);
 ```
 
-Overlapping Layer builds with the same `clientCacheKey` share one started client. The later build replaces the registered worker, and the final scope release stops the shared client. A later build after that release starts a new client. Without a key, each build creates its own client. The application chooses whether to pass a key; give each distinct constructor configuration its own key.
+Overlapping Layer builds with the same `clientCacheKey` share one started client. The later build replaces the registered worker, and the final scope release stops the shared client. A later build after that release starts a new client. Within one Layer graph, merged feature services share the provided app client without a cache key. Separate app Layer builds create separate clients without a key. The application chooses whether to pass a key; give each distinct constructor configuration its own key.
 
 ### Separate producers and workers
 
@@ -404,11 +404,10 @@ Pass a queue definition directly in the jobs Layer to create its queue and dead-
 import { SendEmail } from "./jobs.ts";
 import { Jobs } from "./services.ts";
 
-export const producerLayer = (databaseUrl: string) =>
-  Jobs.layer({ connectionString: databaseUrl, jobs: [SendEmail] });
+export const producerLayer = Jobs.layer({ jobs: [SendEmail] });
 ```
 
-Provide this Layer to the request runtime and call `jobs.enqueue(SendEmail, { userId })` as above. A separate worker process registers `SendEmail.handle(...)` against the same database. Producer queues use the same retry options and appear in `health`; only worker registrations capture handler services.
+Provide the app `pgBossLayer` to this Layer in the request runtime and call `jobs.enqueue(SendEmail, { userId })` as above. A separate worker process registers `SendEmail.handle(...)` against the same database. Producer queues use the same retry options and appear in `health`; only worker registrations capture handler services.
 
 ### Enqueue follow-ups from a handler
 
@@ -416,30 +415,27 @@ A handler can yield the same `Jobs` service that owns it. The Layer supplies tha
 
 ```ts
 const Receipt = defineQueue({
-  name: "receipt",
-  schema: Schema.Struct({ userId: Schema.Number }),
+	name: "receipt",
+	schema: Schema.Struct({ userId: Schema.Number }),
 });
 
 const sendAndQueueReceipt = SendEmail.handle(({ userId }) =>
-  Effect.gen(function* () {
-    const mail = yield* Mail;
-    yield* mail.send(userId);
-    const jobs = yield* Jobs;
-    yield* jobs.enqueue(Receipt, { userId });
-  }),
+	Effect.gen(function* () {
+		const mail = yield* Mail;
+		yield* mail.send(userId);
+		const jobs = yield* Jobs;
+		yield* jobs.enqueue(Receipt, { userId });
+	}),
 );
 
-const live = Jobs.layer({
-  connectionString: databaseUrl,
-  jobs: [sendAndQueueReceipt, Receipt],
-}).pipe(Layer.provide(MailLive));
+const live = Jobs.layer({ jobs: [sendAndQueueReceipt, Receipt] }).pipe(Layer.provide(MailLive));
 ```
 
 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.
 
 ### 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.
+`testing.ts` gives story kits a controller for one real pg-boss client. Create a fresh controller per runtime, pass its `clientFactory` to `pgBossLayer`, 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:
 
@@ -447,32 +443,29 @@ This producer story uses the `SendEmail` definition and `Jobs` service from abov
 import { Context, Layer, Option } from "effect";
 import { expect } from "vitest";
 import { storyKit } from "@shivaedev/test-story/server/storyKit.ts";
+import { pgBossLayer } from "@shivaedev/jobs/server/service.ts";
 import { makePgBossTesting, testRetryPolicy } from "@shivaedev/jobs/server/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,
-  }),
+	clock: "live",
+	*create() {
+		const testing = makePgBossTesting({ retryPolicy: testRetryPolicy });
+		const context = yield* Layer.build(
+			Jobs.layer({ jobs: [SendEmail] }).pipe(Layer.provide(pgBossLayer({ connectionString: databaseUrl, clientFactory: testing.clientFactory }))),
+		);
+		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" },
-  ]);
+	const id = Option.getOrThrow(yield* enqueue(42));
+	expect(yield* testing.jobs(SendEmail)).toMatchObject([{ id, data: { userId: 42 }, state: "created" }]);
 });
 ```
 
@@ -500,15 +493,16 @@ A kit can also capture `revision` before reading jobs and yield `waitForChange(r
 
 Import the module that defines the name; the package has no root entry.
 
-| Module | Public names |
-| --- | --- |
+| Module                                 | Public names                                                                                                                                                                                                                                                                                       |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@shivaedev/jobs/server/definition.ts` | `defineQueue`, `defineSchedule`, `jobContext`, `RetryAt`; `DefineQueueOptions`, `DefineScheduleOptions`, `JobContext`, `JobPayloadSchema`, `JobRegistration`, `QueueDefinition`, `QueueOptions`, `QueuePolicy`, `QueueWorker`, `RegistrationRequirements`, `ScheduleDefinition`, `ScheduledWorker` |
-| `@shivaedev/jobs/server/service.ts` | `makePgBoss`; `PgBossDefinition`, `PgBossLayerOptions`, `PgBossService` |
-| `@shivaedev/jobs/server/schema.ts` | `installPgBossSchema`, `pgBossSchema`; `PgBossSchemaOptions` |
-| `@shivaedev/jobs/server/health.ts` | `deadLetterQueueName`; `DeadLetteredJob`, `JobPage`, `JobPageOptions`, `JobsHealth`, `ListedJob`, `QueueCounts`, `QueueHealth` |
-| `@shivaedev/jobs/server/error.ts` | `PgBossError`, `PgBossPayloadError`, `PgBossQueueOptionsError`, `PgBossClientOptionsError`, `PgBossTestingError`, `toPgBossError`; `PgBossOperation` |
-| `@shivaedev/jobs/server/client.ts` | `defaultClientFactory`; `PgBossClient`, `PgBossClientFactory` |
-| `@shivaedev/jobs/server/testing.ts` | `makePgBossTesting`, `testRetryPolicy`; `PgBossTesting`, `PgBossTestingOptions`, `SnapshotQueue`, `UnfinishedJob` |
+| `@shivaedev/jobs/server/service.ts`    | `makePgBoss`, `pgBossLayer`; `PgBossDefinition`, `PgBossLayerOptions`, `PgBossOptions`, `PgBossService`                                                                                                                                                                                            |
+| `@shivaedev/jobs/server/PgBoss.ts`     | `PgBoss`: the shared client Context service.                                                                                                                                                                                                                                                       |
+| `@shivaedev/jobs/server/schema.ts`     | `installPgBossSchema`, `pgBossSchema`; `PgBossSchemaOptions`                                                                                                                                                                                                                                       |
+| `@shivaedev/jobs/server/health.ts`     | `deadLetterQueueName`; `DeadLetteredJob`, `JobPage`, `JobPageOptions`, `JobsHealth`, `ListedJob`, `QueueCounts`, `QueueHealth`                                                                                                                                                                     |
+| `@shivaedev/jobs/server/error.ts`      | `PgBossError`, `PgBossPayloadError`, `PgBossQueueOptionsError`, `PgBossClientOptionsError`, `PgBossTestingError`, `toPgBossError`; `PgBossOperation`                                                                                                                                               |
+| `@shivaedev/jobs/server/client.ts`     | `defaultClientFactory`; `PgBossClient`, `PgBossClientFactory`                                                                                                                                                                                                                                      |
+| `@shivaedev/jobs/server/testing.ts`    | `makePgBossTesting`, `testRetryPolicy`; `PgBossTesting`, `PgBossTestingOptions`, `SnapshotQueue`, `UnfinishedJob`                                                                                                                                                                                  |
 
 The definition options keep the pg-boss names: `queue` uses `QueueOptions` (`Queue` except `name` and `deadLetter`, with literal `QueuePolicy` values and `maxDeferrals`), `worker` uses `WorkOptions`, and a schedule's `schedule` uses `ScheduleOptions`. A queue also requires `name` and `schema`; a schedule requires `name` and `cron`.
 
@@ -523,11 +517,11 @@ Worker registration always requests `includeMetadata: true`, including when `wor
 ### Install, setup and limits
 
 ```sh
-pnpm add @shivaedev/jobs effect@4.0.5 pg-boss@12.37.0
+pnpm add @shivaedev/jobs effect pg-boss
 ```
 
 The package requires Node.js 24 or later and PostgreSQL. `effect` and `pg-boss` are peers; use versions that satisfy the package's published peer ranges.
 
-`connectionString` configures pg-boss's own `pg` Pool, separately from the application's Effect SQL pool. In the default configuration a URL without `sslmode` uses plaintext. Outside a private network, add `sslmode=verify-full` (or `require`) to require TLS. The installed `pg` 8.23 driver verifies certificates for both modes and refuses servers without TLS. For private CAs, start Node with `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`. See the [framework database connection security guide](https://github.com/ShivaeDev/platform/blob/main/docs/framework/quickstart.md#database-connection-security) for all three connection paths and the driver's differences from libpq.
+`connectionString` configures pg-boss's own `pg` Pool, separately from the application's Effect SQL pool, and pg-boss's driver decides how its `sslmode` behaves. Set the TLS mode in that URL; the [framework database connection security guide](https://github.com/ShivaeDev/platform/blob/main/docs/framework/quickstart.md#database-connection-security) compares the drivers and the application's connection paths.
 
 Provide the database connection and job registrations at the application runtime boundary. Application services own the domain work and provider calls; pg-boss owns queue execution. When `SqlClient` is provided and a SQL transaction is active, `enqueue` uses pg-boss’s per-call `db` option on that transaction’s connection. The application write and queued jobs commit or roll back together. The jobs client and SQL client must use the same PostgreSQL database. Outside a transaction, enqueueing keeps using the jobs client as usual. To keep enqueueing independent of an application transaction, move it after the transaction returns and handle its failure separately.

package/dist/JobFailure.d.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+export declare const JobFailure: Schema.Struct<{
+    readonly _tag: Schema.withDecodingDefaultKey<Schema.String, never>;
+    readonly message: Schema.decodeTo<Schema.String, Schema.String, never, never>;
+}>;
+export type JobFailure = typeof JobFailure.Type;
+//# sourceMappingURL=JobFailure.d.ts.map

package/dist/JobFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JobFailure.d.ts","sourceRoot":"","sources":["../src/JobFailure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAgB,MAAM,QAAQ,CAAC;AAItD,eAAO,MAAM,UAAU;;;EAGrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC"}

package/dist/JobFailure.js

@@ -0,0 +1,8 @@
+import { Effect, Schema, SchemaGetter } from "effect";
+import { isSensitiveKey, redactText } from "@shivaedev/errors/sensitive.ts";
+const redactMessage = SchemaGetter.transform((message) => redactText(message, isSensitiveKey));
+export const JobFailure = Schema.Struct({
+    _tag: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed("Error"))),
+    message: Schema.String.pipe(Schema.decodeTo(Schema.String, { decode: redactMessage, encode: redactMessage })),
+});
+//# sourceMappingURL=JobFailure.js.map

package/dist/JobFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JobFailure.js","sourceRoot":"","sources":["../src/JobFailure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAE5E,MAAM,aAAa,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;AACvG,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAChF,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;CAC7G,CAAC,CAAC"}