@shivaedev/effect-pg-boss 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.10.0 - 2026-10-18
+
+### Added
+
+- `installPgBossSchema(options?: PgBossSchemaOptions)` in `schema.ts` installs or upgrades the pg-boss schema through an Effect SQL client without starting workers or schedules. Use it in a test template fixture or release step, then start jobs Layers with `migrate: false`. Failures use `PgBossError` with the new `"install"` operation. Retrying a failed concurrent upgrade rebuilds missing and invalid managed indexes even when the schema version has already committed.
+
 ## 0.9.0 - 2026-10-18
 
 ### Added

package/README.md

@@ -37,6 +37,20 @@ Use a distinct literal identifier for each jobs service. The service and its Lay
 
 The work separates naturally: declare the application services once, define a queue and its worker for each feature, provide the complete registration list at the runtime boundary, and enqueue from ordinary application Effects.
 
+### Once per database: install the schema
+
+`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:
+
+```ts
+import { installPgBossSchema } from "@shivaedev/effect-pg-boss/schema.ts";
+
+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.
+
 ### Once per application: the jobs service
 
 Define the application's jobs service and worker dependencies in `services.ts`:
@@ -114,7 +128,7 @@ const Compare = defineQueue({
 
 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. Override the backstop only when the application needs a different bound for work that becomes runnable without a notification, such as delayed jobs or retries. The PostgreSQL backlog tests insert 30 jobs at once and verify completion within 2.5 seconds with both defaults and configured batches and concurrency.
+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. Override the backstop only when the application needs a different bound for work that becomes runnable without a notification, such as delayed jobs or retries.
 
 ### Size batches against expiry
 
@@ -206,7 +220,7 @@ export const enqueueEmail = (userId: number) =>
 
 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`.
 
-`PgBossPayloadError` names a payload boundary failure; malformed durable input is rejected before the worker's domain code runs. The PostgreSQL test also checks that invalid data sent directly to pg-boss reaches the dead-letter queue without reaching the handler.
+`PgBossPayloadError` names a payload boundary failure; malformed durable input is rejected before the worker's domain code runs.
 
 ### Trace jobs
 
@@ -214,7 +228,7 @@ Each queue or scheduled job attempt runs in one root consumer span named for its
 
 `enqueue` captures the current Effect span, including an external parent span, when present. It stores that context in a typed envelope in pg-boss's existing job `data`; the adapter unwraps the envelope before Schema decoding in the handler and `getJob`, so the application's payload Schema stays unchanged. Jobs sent without a span keep their ordinary encoded payload, and workers also accept those unwrapped jobs. Direct pg-boss data readers see the envelope for traced sends.
 
-The consumer span links to the sender rather than sharing its parent trace, following OpenTelemetry messaging conventions for asynchronous processing. Each retry gets its own job trace. Provide the application's Effect tracer when building the worker Layer; the worker uses that captured tracer. The PostgreSQL tracing tests use Effect's in-memory tracer and a producer that shuts down before its worker starts; the scheduled-worker test checks the same span boundary with a fake client.
+The consumer span links to the sender rather than sharing its parent trace, following OpenTelemetry messaging conventions for asynchronous processing. Each retry gets its own job trace. Provide the application's Effect tracer when building the worker Layer; the worker uses that captured tracer.
 
 ### Read health
 
@@ -261,7 +275,7 @@ export const inspectEmail = (id: string) => Effect.gen(function* () {
 
 ### Queue settings on startup
 
-`queue` accepts pg-boss `Queue` options except `name` and `deadLetter`, which the definition and adapter own. For prompt delivery, set `queue: { notify: true }` and enable `useListenNotify: true` in the worker Layer's constructor options. The PostgreSQL notification test waits for an idle worker with a ten-second polling interval and verifies delivery within 1.5 seconds.
+`queue` accepts pg-boss `Queue` options except `name` and `deadLetter`, which the definition and adapter own. For prompt delivery, set `queue: { notify: true }` and enable `useListenNotify: true` in the worker Layer's constructor options.
 
 Startup creates missing queues and reconciles declared settings on existing queues through `updateQueue`. Unspecified settings keep their stored values; the adapter always supplies its default retry settings and dead-letter destination. Changing an explicitly declared `policy` or `partition` on an existing queue fails startup with `PgBossQueueOptionsError`; its `queue`, `options` and message identify the conflict. Queue setting changes apply to subsequently enqueued jobs. Schedule queues follow the same registration path.
 
@@ -281,7 +295,7 @@ const sharedJobsLayer = (databaseUrl: string) =>
   }).pipe(Layer.provide(MailLive));
 ```
 
-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.
+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.
 
 ### Separate producers and workers
 
@@ -295,7 +309,7 @@ export const producerLayer = (databaseUrl: string) =>
   Jobs.layer({ connectionString: databaseUrl, 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. The PostgreSQL producer test creates both queues through this Layer, enqueues a transformed payload, and observes a failing worker exhaust two retries before the job reaches its dead-letter queue.
+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.
 
 ### Enqueue follow-ups from a handler
 
@@ -322,7 +336,7 @@ const live = Jobs.layer({
 }).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. The PostgreSQL follow-up test completes a chain across two workers, enqueues to a producer-only queue and asserts one client acquisition and shutdown.
+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
 
@@ -365,11 +379,11 @@ emailStories.it("decodes the queued email", [], function* ({ enqueue, testing })
 
 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.
+`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.
 
 `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.
+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.
 
 ### API
 
@@ -379,6 +393,7 @@ 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/schema.ts` | `installPgBossSchema`; `PgBossSchemaOptions` |
 | `@shivaedev/effect-pg-boss/health.ts` | `deadLetterQueueName`; `JobsHealth`, `QueueCounts`, `QueueHealth` |
 | `@shivaedev/effect-pg-boss/error.ts` | `PgBossError`, `PgBossPayloadError`, `PgBossQueueOptionsError`, `PgBossTestingError`, `toPgBossError`; `PgBossOperation` |
 | `@shivaedev/effect-pg-boss/client.ts` | `defaultClientFactory`; `PgBossClient`, `PgBossClientFactory` |
@@ -386,19 +401,11 @@ Import the module that defines the name; the package has no root entry.
 
 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`.
 
-The application's service has these operations:
-
-- `enqueue(queue, payload, options?)`: an Effect returning `Option.Option<string>`, with `PgBossError | PgBossPayloadError` in its error type. Its options use pg-boss `SendOptions`.
-- `health`: an Effect returning cached `JobsHealth`, with `PgBossError` in its error type.
-- `counts(queue)`: an Effect returning live `QueueCounts`, with `PgBossError` in its error type.
-- `getJob(queue, id)`: an Effect returning `Option.Option<JobWithMetadata<Payload>>` with decoded payload data, `PgBossError | PgBossPayloadError` in its error type and the Schema's decoding services in its requirements.
-- `retry(queue, id)`: an Effect returning `void`, with `PgBossError` in its error type.
+`Jobs.layer(options)` accepts pg-boss `ConstructorOptions` plus the adapter's own options. Custom clients must supply native `complete` and `fail` capabilities to register queue or schedule workers; missing settlement capabilities fail Layer acquisition with a registration `PgBossError`. Producer-only clients do not need them. Custom clients can also supply the optional native capabilities `findJobs`, `retry`, `update`, `getDb` and `updateQueue` for lookup, retry, live counts and reconciliation; a requested operation fails with `PgBossError` if its required capability is absent.
 
-`Jobs.layer(options)` accepts pg-boss `ConstructorOptions` plus `jobs`, optional `clientCacheKey`, optional `clientFactory`, optional `onError` and optional `stop`. The factory type accepts constructor options and returns `PgBossClient`. Custom clients must supply native `complete` and `fail` capabilities to register queue or schedule workers; missing settlement capabilities fail Layer acquisition with a registration `PgBossError`. Producer-only clients do not need them. Custom clients can also supply the optional native capabilities `findJobs`, `retry`, `update`, `getDb` and `updateQueue` for lookup, retry, live counts and reconciliation; a requested operation fails with `PgBossError` if its required capability is absent. `onError` has the type `(error: Error) => Effect.Effect<unknown, never, R>`; `stop` uses pg-boss `StopOptions`.
+`onError` handles pg-boss client `error` events using the services captured by the Layer. Only the owning jobs service is supplied automatically; a handler using another jobs definition still requires that definition's Layer.
 
-`onError` handles pg-boss client `error` events using the services captured by the Layer. The Layer's requirement type includes the workers' services and their payload Schemas' `DecodingServices`, excluding its own jobs identifier, plus the callback's services. Only the owning jobs service is supplied automatically; a handler using another jobs definition still requires that definition's Layer. `enqueue` includes the payload Schema's `EncodingServices` in its requirement type.
-
-`JobContext` has `id`, `name`, `signal`, `expireInSeconds`, `heartbeatSeconds` and `remainingBudget`. Worker registration always requests `includeMetadata: true`, including when `worker` supplies `includeMetadata: false`; custom clients must return pg-boss's `startedOn` metadata. When calling `jobContext` directly, reading `remainingBudget` requires that same metadata. `QueueHealth` has `name`, `activeCount`, `deadLetteredCount`, `failedCount`, `queuedCount` and `readyCount`. `JobsHealth` has `jobs` and the corresponding `activeTotal`, `deadLetteredTotal`, `failedTotal`, `queuedTotal` and `readyTotal` fields.
+Worker registration always requests `includeMetadata: true`, including when `worker` supplies `includeMetadata: false`; custom clients must return pg-boss's `startedOn` metadata. When calling `jobContext` directly, reading `remainingBudget` requires that same metadata.
 
 `PgBossError` has `operation`, optional `queue` and a `Redacted` `original`. Its message names the operation, the queue and the original error's class and `code`, such as a PostgreSQL SQLSTATE, but never the original message, which can quote payloads or connection strings. A registration failure names the queue it was preparing. `PgBossPayloadError` has `direction`, `queue` and a `Redacted` `original`. Those fields distinguish the pg-boss operation from the payload boundary.
 
@@ -410,8 +417,4 @@ pnpm add @shivaedev/effect-pg-boss effect@4.0.4 pg-boss@12.37.0
 
 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.
 
-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. Treat enqueueing and an application database transaction as separate operations. Enqueue after the application write commits, and handle queue failures in the application so they cannot roll back the write. The starter logs enqueue failures and returns the saved note; a failed enqueue leaves its word count pending. The package supplies no application transaction adapter.
-
-For package development, the real PostgreSQL test uses `PLATFORM_EFFECT_PG_BOSS_TEST_DATABASE_URL` and skips when the variable is absent. A skipped test does not establish durable queue behavior. Fake-client tests cover registration and lifecycle calls; they do not establish real cron execution, retry timing or deployment behavior. The package is built for ShivaeDev applications and may change without a deprecation period.
-
-The [north star](./docs/north-star.md) explains the design trade-offs; the [roadmap](./docs/roadmap.md) owns package work and open choices.
+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. Treat enqueueing and an application database transaction as separate operations. Enqueue after the application write commits, and handle queue failures in the application so they cannot roll back the write. The package supplies no application transaction adapter.

package/dist/server/error.d.ts

@@ -1,5 +1,5 @@
 import { Redacted } from "effect";
-export type PgBossOperation = "counts" | "enqueue" | "getJob" | "health" | "register" | "retry" | "start" | "stop";
+export type PgBossOperation = "counts" | "enqueue" | "getJob" | "health" | "install" | "register" | "retry" | "start" | "stop";
 declare const PgBossError_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: "PgBossError";
 } & Readonly<A>;

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,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"}
+{"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,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;;;;AAE/H,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/internal/runSchemaPlan.d.ts

@@ -0,0 +1,7 @@
+import type { Effect } from "effect";
+import type { Connection } from "effect/sql/SqlConnection";
+export declare function runSchemaPlan(connection: Connection, plan: string, run: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>, upgrade?: {
+    readonly schema: string;
+    readonly version: number;
+}): Promise<void>;
+//# sourceMappingURL=runSchemaPlan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runSchemaPlan.d.ts","sourceRoot":"","sources":["../../../src/server/internal/runSchemaPlan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAG3D,wBAAsB,aAAa,CAClC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EACtD,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/server/internal/runSchemaPlan.js

@@ -0,0 +1,25 @@
+import { pendingIndexInserts } from "./schemaIndexBuilds.js";
+export async function runSchemaPlan(connection, plan, run, upgrade) {
+    // Native exported plans append concurrent index DDL after the migration transaction.
+    const parts = /^\s*BEGIN;(?<body>[\s\S]*)\n {4}COMMIT;(?<concurrent>[\s\S]*)$/u.exec(plan);
+    if (parts?.groups === undefined) {
+        throw new Error("Unrecognized pg-boss schema plan transaction");
+    }
+    const { body = "", concurrent = "" } = parts.groups;
+    function quote(text) {
+        return `'${text.replaceAll("'", "''")}'`;
+    }
+    const commands = concurrent
+        .trim()
+        .split(/;\s*(?:\n|$)/u)
+        .filter((statement) => statement.trim() !== "");
+    const pending = upgrade === undefined ? "" : pendingIndexInserts(upgrade.schema, upgrade.version, commands, quote);
+    // Effect SQL uses the extended protocol, which accepts one statement per command.
+    await run(connection.executeRaw(`DO ${quote(`BEGIN EXECUTE ${quote(`${body}\n${pending}`)}; END`)}`, []));
+    if (upgrade === undefined) {
+        for (const statement of commands) {
+            await run(connection.executeRaw(statement, []));
+        }
+    }
+}
+//# sourceMappingURL=runSchemaPlan.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runSchemaPlan.js","sourceRoot":"","sources":["../../../src/server/internal/runSchemaPlan.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,UAAsB,EACtB,IAAY,EACZ,GAAsD,EACtD,OAA+D;IAE/D,qFAAqF;IACrF,MAAM,KAAK,GAAG,iEAAiE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3F,IAAI,KAAK,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,UAAU,GAAG,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC;IACpD,SAAS,KAAK,CAAC,IAAY;QAC1B,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;IAC1C,CAAC;IACD,MAAM,QAAQ,GAAG,UAAU;SACzB,IAAI,EAAE;SACN,KAAK,CAAC,eAAe,CAAC;SACtB,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACnH,kFAAkF;IAClF,MAAM,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,iBAAiB,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1G,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC3B,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;YAClC,MAAM,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;QACjD,CAAC;IACF,CAAC;AACF,CAAC"}

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

@@ -0,0 +1,4 @@
+import type { PgBoss } from "pg-boss";
+export declare function pendingIndexInserts(schema: string, version: number, commands: readonly string[], quote: (text: string) => string): string;
+export declare function resumeSchemaIndexes(client: PgBoss, schema: string): Promise<void>;
+//# sourceMappingURL=schemaIndexBuilds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemaIndexBuilds.d.ts","sourceRoot":"","sources":["../../../src/server/internal/schemaIndexBuilds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAgBtC,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAQzI;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBvF"}

package/dist/server/internal/schemaIndexBuilds.js

@@ -0,0 +1,34 @@
+const BUILD_PREFIX = "effect-pg-boss-schema:";
+function indexName(command) {
+    const match = /^\s*(?:CREATE (?:UNIQUE )?INDEX CONCURRENTLY IF NOT EXISTS |DROP INDEX CONCURRENTLY IF EXISTS (?:(?:"[^"]+"|\w+)\.))(?<name>\w+)/mu.exec(command);
+    const name = match?.groups?.name;
+    if (name === undefined) {
+        throw new Error("Unrecognized pg-boss concurrent index command");
+    }
+    return name;
+}
+export function pendingIndexInserts(schema, version, commands, quote) {
+    return commands
+        .map((command, position) => {
+        const table = indexName(command).replace(/_i\d+$/u, "");
+        const name = `${BUILD_PREFIX}${String(position).padStart(6, "0")}`;
+        return `INSERT INTO ${schema}.bam (name, version, table_name, command) VALUES (${quote(name)}, ${version}, ${quote(table)}, ${quote(command)});`;
+    })
+        .join("\n");
+}
+export async function resumeSchemaIndexes(client, schema) {
+    const db = client.getDb();
+    const { rows } = await db.executeSql(`SELECT id, command FROM ${schema}.bam WHERE starts_with(name, $1) AND status <> 'completed' ORDER BY created_on, name`, [BUILD_PREFIX]);
+    for (const row of rows) {
+        const name = indexName(row.command);
+        if (/^\s*CREATE /mu.test(row.command)) {
+            const probe = await db.executeSql("SELECT NOT indisvalid AS invalid FROM pg_index WHERE indexrelid = to_regclass($1)", [`${schema}.${name}`]);
+            if (probe.rows[0]?.invalid === true) {
+                await db.executeSql(`DROP INDEX CONCURRENTLY IF EXISTS ${schema}."${name}"`);
+            }
+        }
+        await db.executeSql(row.command);
+        await db.executeSql(`UPDATE ${schema}.bam SET status = 'completed', completed_on = clock_timestamp() WHERE id = $1`, [row.id]);
+    }
+}
+//# sourceMappingURL=schemaIndexBuilds.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemaIndexBuilds.js","sourceRoot":"","sources":["../../../src/server/internal/schemaIndexBuilds.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAE9C,SAAS,SAAS,CAAC,OAAe;IACjC,MAAM,KAAK,GACV,oIAAoI,CAAC,IAAI,CACxI,OAAO,CACP,CAAC;IACH,MAAM,IAAI,GAAG,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC;IACjC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,OAAe,EAAE,QAA2B,EAAE,KAA+B;IAChI,OAAO,QAAQ;SACb,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,GAAG,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACnE,OAAO,eAAe,MAAM,qDAAqD,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,KAAK,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;IAClJ,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAc,EAAE,MAAc;IACvE,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;IAC1B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,UAAU,CACnC,2BAA2B,MAAM,sFAAsF,EACvH,CAAC,YAAY,CAAC,CACd,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpC,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,mFAAmF,EAAE,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;YAC9I,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrC,MAAM,EAAE,CAAC,UAAU,CAAC,qCAAqC,MAAM,KAAK,IAAI,GAAG,CAAC,CAAC;YAC9E,CAAC;QACF,CAAC;QACD,MAAM,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjC,MAAM,EAAE,CAAC,UAAU,CAAC,UAAU,MAAM,+EAA+E,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAChI,CAAC;AACF,CAAC"}

package/dist/server/schema.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { type PgBossError } from "#error.ts";
+export interface PgBossSchemaOptions {
+    readonly schema?: string;
+}
+export declare function installPgBossSchema(options?: PgBossSchemaOptions): Effect.Effect<void, PgBossError, SqlClient.SqlClient>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/server/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,WAAW,CAAC;AAI5D,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAoCD,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,SAAS,CAAC,CAS5H"}

package/dist/server/schema.js

@@ -0,0 +1,43 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { getConstructionPlans, getMigrationPlans, PgBoss } from "pg-boss";
+import pgBossPackage from "pg-boss/package.json" with { type: "json" };
+import { toPgBossError } from "#error.ts";
+import { runSchemaPlan } from "#internal/runSchemaPlan.ts";
+import { resumeSchemaIndexes } from "#internal/schemaIndexBuilds.ts";
+async function installSchema(connection, options, run) {
+    const schema = options.schema ?? "pgboss";
+    const construction = getConstructionPlans(schema);
+    const client = new PgBoss({
+        db: { executeSql: async (text, values = []) => ({ rows: Array.from(await run(connection.executeUnprepared(text, values, undefined))) }) },
+        schema,
+    });
+    if (!(await client.isInstalled())) {
+        await runSchemaPlan(connection, construction, run);
+        return;
+    }
+    const version = await client.schemaVersion();
+    if (version === null) {
+        throw new Error("The pg-boss version table is empty");
+    }
+    if (version > pgBossPackage.pgboss.schema) {
+        return;
+    }
+    if (version >= 27) {
+        await resumeSchemaIndexes(client, schema);
+    }
+    if (version < pgBossPackage.pgboss.schema) {
+        const partitionTables = Array.from(await run(connection.executeUnprepared(`SELECT table_name AS "tableName", policy FROM ${schema}.queue WHERE partition = true`, [], undefined)));
+        await runSchemaPlan(connection, getMigrationPlans(schema, version, { partitionTables }), run, { schema, version: pgBossPackage.pgboss.schema });
+        await resumeSchemaIndexes(client, schema);
+    }
+}
+export function installPgBossSchema(options = {}) {
+    return Effect.scoped(Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const connection = yield* sql.reserve;
+        const run = Effect.runPromiseWith(yield* Effect.context());
+        yield* Effect.tryPromise({ catch: (error) => error, try: () => installSchema(connection, options, run) });
+    }).pipe(Effect.mapError((error) => toPgBossError("install", error)))).pipe(Effect.uninterruptible);
+}
+//# sourceMappingURL=schema.js.map

package/dist/server/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/server/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAA2B,MAAM,EAAE,MAAM,SAAS,CAAC;AACnG,OAAO,aAAa,MAAM,sBAAsB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACvE,OAAO,EAAoB,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAMrE,KAAK,UAAU,aAAa,CAC3B,UAAsB,EACtB,OAA4B,EAC5B,GAAsD;IAEtD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC;IAC1C,MAAM,YAAY,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACzB,EAAE,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;QACzI,MAAM;KACN,CAAC,CAAC;IACH,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QACnC,MAAM,aAAa,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC;QACnD,OAAO;IACR,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,aAAa,EAAE,CAAC;IAC7C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC3C,OAAO;IACR,CAAC;IACD,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QACnB,MAAM,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC3C,MAAM,eAAe,GAAyB,KAAK,CAAC,IAAI,CACvD,MAAM,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,iDAAiD,MAAM,+BAA+B,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC,CAC9I,CAAC;QACF,MAAM,aAAa,CAAC,UAAU,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAChJ,MAAM,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAO,GAAwB,EAAE;IACpE,OAAO,MAAM,CAAC,MAAM,CACnB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC;QACvC,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;QACtC,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,EAAS,CAAC,CAAC;QAClE,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3G,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,CACpE,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AAChC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/effect-pg-boss",
-  "version": "0.9.0",
+  "version": "0.10.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": {
@@ -24,9 +24,8 @@
   },
   "exports": {
     "./*.ts": {
-      "types": "./dist/server/*.d.ts",
       "source": "./src/server/*.ts",
-      "import": "./dist/server/*.js",
+      "types": "./dist/server/*.d.ts",
       "default": "./dist/server/*.js"
     },
     "./internal/*": null,
@@ -38,19 +37,18 @@
     "!src/**/*.test.ts",
     "!src/**/*.spec.ts",
     "!src/**/test-support",
-    "docs",
     "CHANGELOG.md",
     "README.md"
   ],
   "devDependencies": {
-    "@shivaedev/effect-test-sql": "0.5.4",
-    "@shivaedev/quality": "0.23.0",
-    "@shivaedev/test-story": "0.6.0",
+    "@shivaedev/effect-test": "0.6.0",
+    "@shivaedev/effect-test-sql": "0.5.5",
+    "@shivaedev/quality": "0.27.0",
+    "@shivaedev/test-story": "0.9.0",
     "@types/node": "24.19.2",
-    "@typescript/native": "npm:typescript@7.0.2",
     "effect": "4.0.4",
     "pg-boss": "12.37.1",
-    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "typescript": "7.0.2",
     "vitest": "5.0.3"
   },
   "peerDependencies": {

package/src/server/error.ts

@@ -1,6 +1,6 @@
 import { Data, Redacted } from "effect";
 
-export type PgBossOperation = "counts" | "enqueue" | "getJob" | "health" | "register" | "retry" | "start" | "stop";
+export type PgBossOperation = "counts" | "enqueue" | "getJob" | "health" | "install" | "register" | "retry" | "start" | "stop";
 
 export class PgBossError extends Data.TaggedError("PgBossError")<{
 	readonly operation: PgBossOperation;

package/src/server/internal/runSchemaPlan.ts

@@ -0,0 +1,32 @@
+import type { Effect } from "effect";
+import type { Connection } from "effect/sql/SqlConnection";
+import { pendingIndexInserts } from "./schemaIndexBuilds.ts";
+
+export async function runSchemaPlan(
+	connection: Connection,
+	plan: string,
+	run: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>,
+	upgrade?: { readonly schema: string; readonly version: number },
+): Promise<void> {
+	// Native exported plans append concurrent index DDL after the migration transaction.
+	const parts = /^\s*BEGIN;(?<body>[\s\S]*)\n {4}COMMIT;(?<concurrent>[\s\S]*)$/u.exec(plan);
+	if (parts?.groups === undefined) {
+		throw new Error("Unrecognized pg-boss schema plan transaction");
+	}
+	const { body = "", concurrent = "" } = parts.groups;
+	function quote(text: string) {
+		return `'${text.replaceAll("'", "''")}'`;
+	}
+	const commands = concurrent
+		.trim()
+		.split(/;\s*(?:\n|$)/u)
+		.filter((statement) => statement.trim() !== "");
+	const pending = upgrade === undefined ? "" : pendingIndexInserts(upgrade.schema, upgrade.version, commands, quote);
+	// Effect SQL uses the extended protocol, which accepts one statement per command.
+	await run(connection.executeRaw(`DO ${quote(`BEGIN EXECUTE ${quote(`${body}\n${pending}`)}; END`)}`, []));
+	if (upgrade === undefined) {
+		for (const statement of commands) {
+			await run(connection.executeRaw(statement, []));
+		}
+	}
+}

package/src/server/internal/schemaIndexBuilds.ts

@@ -0,0 +1,44 @@
+import type { PgBoss } from "pg-boss";
+
+const BUILD_PREFIX = "effect-pg-boss-schema:";
+
+function indexName(command: string): string {
+	const match =
+		/^\s*(?:CREATE (?:UNIQUE )?INDEX CONCURRENTLY IF NOT EXISTS |DROP INDEX CONCURRENTLY IF EXISTS (?:(?:"[^"]+"|\w+)\.))(?<name>\w+)/mu.exec(
+			command,
+		);
+	const name = match?.groups?.name;
+	if (name === undefined) {
+		throw new Error("Unrecognized pg-boss concurrent index command");
+	}
+	return name;
+}
+
+export function pendingIndexInserts(schema: string, version: number, commands: readonly string[], quote: (text: string) => string): string {
+	return commands
+		.map((command, position) => {
+			const table = indexName(command).replace(/_i\d+$/u, "");
+			const name = `${BUILD_PREFIX}${String(position).padStart(6, "0")}`;
+			return `INSERT INTO ${schema}.bam (name, version, table_name, command) VALUES (${quote(name)}, ${version}, ${quote(table)}, ${quote(command)});`;
+		})
+		.join("\n");
+}
+
+export async function resumeSchemaIndexes(client: PgBoss, schema: string): Promise<void> {
+	const db = client.getDb();
+	const { rows } = await db.executeSql(
+		`SELECT id, command FROM ${schema}.bam WHERE starts_with(name, $1) AND status <> 'completed' ORDER BY created_on, name`,
+		[BUILD_PREFIX],
+	);
+	for (const row of rows) {
+		const name = indexName(row.command);
+		if (/^\s*CREATE /mu.test(row.command)) {
+			const probe = await db.executeSql("SELECT NOT indisvalid AS invalid FROM pg_index WHERE indexrelid = to_regclass($1)", [`${schema}.${name}`]);
+			if (probe.rows[0]?.invalid === true) {
+				await db.executeSql(`DROP INDEX CONCURRENTLY IF EXISTS ${schema}."${name}"`);
+			}
+		}
+		await db.executeSql(row.command);
+		await db.executeSql(`UPDATE ${schema}.bam SET status = 'completed', completed_on = clock_timestamp() WHERE id = $1`, [row.id]);
+	}
+}

package/src/server/schema.ts

@@ -0,0 +1,57 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { Connection } from "effect/sql/SqlConnection";
+import { getConstructionPlans, getMigrationPlans, type MigrationPartition, PgBoss } from "pg-boss";
+import pgBossPackage from "pg-boss/package.json" with { type: "json" };
+import { type PgBossError, toPgBossError } from "#error.ts";
+import { runSchemaPlan } from "#internal/runSchemaPlan.ts";
+import { resumeSchemaIndexes } from "#internal/schemaIndexBuilds.ts";
+
+export interface PgBossSchemaOptions {
+	readonly schema?: string;
+}
+
+async function installSchema(
+	connection: Connection,
+	options: PgBossSchemaOptions,
+	run: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>,
+): Promise<void> {
+	const schema = options.schema ?? "pgboss";
+	const construction = getConstructionPlans(schema);
+	const client = new PgBoss({
+		db: { executeSql: async (text, values = []) => ({ rows: Array.from(await run(connection.executeUnprepared(text, values, undefined))) }) },
+		schema,
+	});
+	if (!(await client.isInstalled())) {
+		await runSchemaPlan(connection, construction, run);
+		return;
+	}
+	const version = await client.schemaVersion();
+	if (version === null) {
+		throw new Error("The pg-boss version table is empty");
+	}
+	if (version > pgBossPackage.pgboss.schema) {
+		return;
+	}
+	if (version >= 27) {
+		await resumeSchemaIndexes(client, schema);
+	}
+	if (version < pgBossPackage.pgboss.schema) {
+		const partitionTables: MigrationPartition[] = Array.from(
+			await run(connection.executeUnprepared(`SELECT table_name AS "tableName", policy FROM ${schema}.queue WHERE partition = true`, [], undefined)),
+		);
+		await runSchemaPlan(connection, getMigrationPlans(schema, version, { partitionTables }), run, { schema, version: pgBossPackage.pgboss.schema });
+		await resumeSchemaIndexes(client, schema);
+	}
+}
+
+export function installPgBossSchema(options: PgBossSchemaOptions = {}): Effect.Effect<void, PgBossError, SqlClient.SqlClient> {
+	return Effect.scoped(
+		Effect.gen(function* () {
+			const sql = yield* SqlClient.SqlClient;
+			const connection = yield* sql.reserve;
+			const run = Effect.runPromiseWith(yield* Effect.context<never>());
+			yield* Effect.tryPromise({ catch: (error) => error, try: () => installSchema(connection, options, run) });
+		}).pipe(Effect.mapError((error) => toPgBossError("install", error))),
+	).pipe(Effect.uninterruptible);
+}

package/docs/north-star.md

@@ -1,48 +0,0 @@
-# North star
-
-## The problem
-
-A durable job crosses two boundaries at once. Data leaves the producer's process and is read later by a worker; execution leaves the request's Effect context and is called later by pg-boss. When applications bridge those boundaries by hand, they repeat payload validation, dependency capture, queue registration and shutdown logic. A producer can drift from its worker's payload shape, a worker can rebuild services differently from the rest of the application, and a client can outlive the scope that should own it.
-
-The package exists to make that boundary one reusable path. pg-boss remains the PostgreSQL queue engine. Effect remains the application's language for services, errors and resources. The adapter should join those pieces without making the application learn another execution model.
-
-## The ideal
-
-A feature declares one object Schema for a queue, then attaches an ordinary Effect handler. The producer uses its decoded type; the durable boundary uses its encoded type; the handler receives decoded data. Domain code never has to guess what an old or malformed stored payload means.
-
-A scheduled feature declares a name and cron expression, then attaches a payload-free Effect. Queue workers and scheduled workers become one list of registrations at the application's runtime boundary. The application's jobs Layer supplies the workers' services and owns the client that pg-boss calls through.
-
-An application that needs only queueing should not import a repository framework, transport or UI package. A worker that needs application services should declare them through ordinary Effect requirements. The jobs adapter should preserve those requirements rather than hiding them in a global runtime or making each callback rebuild its dependencies.
-
-## What good looks like
-
-- The payload contract is authored once, including transformations between application and durable representations.
-- Invalid stored data is rejected before the worker's domain handler executes.
-- Worker services are supplied where the jobs Layer is built, and their requirements remain visible to TypeScript.
-- The client starts under an Effect scope. Startup failure, registration failure and scope release have a clear resource owner.
-- Client reuse is requested with a key. Applications choose the environments and registrations that should share a client.
-- pg-boss options remain pg-boss options. The package removes repeated boundary plumbing, not the engine's vocabulary.
-- Operational observations are data, such as queue counts; an application decides what those observations mean for its health endpoint and alerts.
-- Documentation distinguishes a fake client's observed calls from durable behavior demonstrated against PostgreSQL.
-
-## Trade-offs
-
-**The durable contract wins over permissive input.** A queue Schema must describe object data on both sides. A malformed payload should not become a partially trusted value in domain code merely to keep a worker running.
-
-**Explicit dependencies win over callback convenience.** The jobs Layer requires the services its handlers use. Adding a hidden runtime or service locator would make a worker shorter while moving its real dependencies out of the type system.
-
-**Resource ownership wins over reuse.** Sharing a client can avoid duplicate starts across Layer builds, but a cache key is an application choice. It must not become a reason to ignore cleanup or silently infer environment policy.
-
-**A thin boundary wins over orchestration features.** pg-boss already owns queue execution and scheduling. A new helper earns its place by removing repeated application code at the Effect boundary, with tests for the semantics it preserves.
-
-**Proven behavior wins over a broader pitch.** Passing `retryBackoff: true` proves registration supplied that option. It does not prove retry timing. A fake client cannot establish a PostgreSQL delivery guarantee, and a PostgreSQL library test cannot establish application adoption or deployment behavior.
-
-## What it deliberately leaves out
-
-- A replacement for pg-boss storage, cron interpretation, queue policy or retry execution.
-- Domain workers, authorization rules, external-provider interfaces and application logging or health policy.
-- Another general service declaration system; native Context and Layer stay available, and general declaration ergonomics belong to `effect-service`.
-- Application repositories or migration ownership; those belong to `effect-sql`.
-- Transactional enqueueing: jobs use a separate connection from application SQL transactions. Applications own any required outbox policy; after-commit changes have their own path through `effect-changes`.
-- A promise of exactly-once domain side effects or provider idempotency. Those need application-specific decisions and evidence.
-- Browser, device or offline synchronization behavior. A PostgreSQL queue boundary cannot establish those product contracts.

package/docs/roadmap.md

@@ -1,35 +0,0 @@
-# Roadmap
-
-This file owns the package's implementation inventory and open API choices. The [framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md#next-application-and-deployment-acceptance) owns jobs integration with application services and external providers, including deployment and device validation.
-
-## Built
-
-- [x] `makePgBoss` retains its literal service identity in `PgBossDefinition` and its Layer type, so a different jobs Layer does not satisfy the required service. [Compiler evidence](https://github.com/ShivaeDev/platform/blob/main/packages/effect-pg-boss/src/server/service.typecheck.test.ts).
-- [x] Object payload Schema definitions, decoded enqueue types and queue workers. Type tests reject primitive schemas, missing fields and encoded values passed as decoded payloads.
-- [x] Encoding at enqueue and decoding before the handler. The PostgreSQL test round-trips a transformed payload and checks that malformed stored data reaches the dead-letter queue without calling the domain handler.
-- [x] Queue and schedule registration, with dead-letter queues, default retry settings and UTC schedule registration. The [PostgreSQL schedule test](../src/server/schedulePostgres.spec.ts) reads the stored cron, explicit UTC option, default retries and dead-letter queue through pg-boss. Fake-client tests also verify a retry-limit override.
-- [x] Producer-only queue definitions create queues and dead-letter queues through `Jobs.layer({ jobs: [Queue] })`, without starting a consumer. The [PostgreSQL producer test](../src/server/producerPostgres.spec.ts) enqueues a transformed payload and observes worker retry exhaustion and dead-letter delivery. The [starter producer](../../../examples/starter/src/server/noteProducer.ts) uses this API.
-- [x] Native pg-boss burst defaults (`batchSize: 10`, `burstWhenBatchFull: true`) and configurable batches and local concurrency. [PostgreSQL backlog evidence](../src/server/throughputPostgres.spec.ts) drains 30 jobs within 2.5 seconds.
-- [x] Handlers and scheduled effects can yield their owning jobs service without an external self requirement. [PostgreSQL follow-up evidence](../src/server/followUpPostgres.spec.ts) completes a worker chain and enqueues to a producer-only queue using one scoped client. All declared queues exist before consumers start.
-- [x] Worker and scheduled Effect service capture. Runtime and packed-consumer type tests preserve handler requirements.
-- [x] Scoped startup and shutdown, including cleanup when startup or registration fails.
-- [x] Explicit keyed client reuse and unkeyed per-build acquisition. Lifecycle tests cover two builds sharing one client and replacing the registered worker.
-- [x] Full pg-boss queue creation options, excluding the adapter's name and dead-letter setup. [PostgreSQL evidence](../src/server/notifyPostgres.spec.ts) verifies notification delivery to a waiting worker and immediate live counts after completion; [type tests](../src/server/service.typecheck.test.ts) enforce option ownership.
-- [x] Schema-decoded lookup by job ID and retry under the same ID for failed or retry-waiting jobs. [PostgreSQL evidence](../src/server/jobControlPostgres.spec.ts) verifies both states complete after a manual retry, missing lookups return `None` and duplicate-ID sends return `None`.
-- [x] Startup reconciles declared mutable queue settings and rejects immutable policy or partition changes with a typed error. [PostgreSQL restart evidence](../src/server/queueOptionsPostgres.spec.ts) checks expiry and retry-limit changes on an existing queue.
-- [x] Queue health totals for active, failed, queued, ready and dead-lettered counts. The [PostgreSQL health test](../src/server/healthPostgres.spec.ts) checks two populated queues and their totals after the pg-boss monitor refreshes its cached counts, including delayed jobs in queued counts.
-- [x] Background error events reach the captured reporting service and the listener is removed on release, verified with a [fake client](../src/server/edgeCases.spec.ts). Job AbortSignal cancellation interrupts the handler and leaves the rest of the batch to pg-boss expiry, verified with a [fake client](../src/server/settlement.spec.ts).
-- [x] Public defining-module imports and an installed-package type fixture.
-
-## Next
-
-No further package API expansion is selected. Let the framework's jobs integration work identify the next package change, and preserve the existing payload and lifecycle contracts while it does. That integration's status stays in the framework roadmap.
-
-## Decisions
-
-Enqueueing is separate from application SQL transactions. The package supplies no transactional enqueue adapter. Applications use transactions for database invariants and handle queue errors without failing those transactions. The starter enqueues after its note write transaction and logs queue failures; its [PostgreSQL queue-failure story](../../../examples/starter/src/server/queueFailure.spec.ts) proves that rejected enqueueing leaves create and edit writes saved. Its [rollback story](../../../examples/starter/src/server/committedJobs.spec.ts) also proves that an independently enqueued job survives an outer application rollback.
-
-## Open questions
-
-- Should a shared client key be checked against constructor settings and registration changes? The lifecycle fixture uses the same Layer twice; it does not settle incompatible configurations under one key.
-- What evidence is needed before the guide makes stronger claims about actual cron execution? PostgreSQL tests verify schedule registration; cron execution timing remains untested.