@shivaedev/sql 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.26.0 - 2026-10-30
+
+### Added
+
+- `@shivaedev/server`: Configure a direct or session-mode change listener with `config.listenDatabaseUrl` or `LISTEN_DATABASE_URL`, falling back to the application connection when unset.
+- `@shivaedev/sql`: Supply `listenerClient` separately from the writing `client` to `postgresChanges`; set `connectionSetting` to identify that connection in diagnostics.
+- `@shivaedev/sql/postgresLayer.ts` provides `postgresLayer(url, options)` with one native `PgPool` shared by `PgClient` and `SqlClient`. Reserved connections and client queries share `maxConnections`, and Layer shutdown waits for every socket to close.
+- `appDatabase` and database-backed `appHost` expose the application's native `PgPool` service for packages that need reserved PostgreSQL connections.
+
+### Fixed
+
+- Retry command-declared invalidation publication after the handler returns, with two bounded exponential backoffs. Exhausted retries preserve the committed result and resynchronize local live streams, then broadcast Resync to other PostgreSQL hosts when the change channel is reachable.
+- Clarify that atomic record and bucket invalidation comes from the stored model and repository; command `invalidates` keys remain after-commit. No consumer API changes or migration are required.
+- Retry worker-release heartbeat and poll failures on a bounded schedule, log their causes, and close the worker scope with the original cause when recovery fails. Heartbeats continue while jobs drain after a connection blip.
+- Log change-listener loss and reconnect causes, and bound listener sub-scope cleanup without rewriting scope finalizers.
+- Fail application database startup when its first PostgreSQL LISTEN or heartbeat fails, instead of waiting indefinitely.
+- SQL decodes migration ledger, release ownership and change-coverage rows before using them. Malformed rows fail with `SchemaError` instead of being treated as current, pending or a different owner.
+- SQL generates worker identities and change-listener heartbeat tokens through Effect's `Random` service.
+
+### Breaking
+
+- Listener startup deadlines now fail with `PostgresListenerError`, naming the connection setting, instead of `SqlError`. Consumers handling startup failures must also handle `PostgresListenerError` from `@shivaedev/sql/PostgresListenerError.ts`. Hosts using transaction-pooled application URLs must set `LISTEN_DATABASE_URL` or `config.listenDatabaseUrl` to a direct or session-mode connection to the same database. Native SQL startup failures still use `SqlError`.
+- Server's PostgreSQL construction and address helpers move to sql. Consumers of `@shivaedev/server/adapters/postgresClient.ts` must compose `postgresLayer` from `@shivaedev/sql/postgresLayer.ts` and read the native `PgPool` or `PgClient` service instead. Address-only consumers import `databaseAddress` from `@shivaedev/sql/databaseAddress.ts` instead of `@shivaedev/server/databaseAddress.ts`.
+- `postgresChanges` and `listenForChanges` now expose `SqlError` during acquisition. Consumers that required an infallible Layer or Effect must handle or propagate this error. `heartbeatTimeout` bounds the first LISTEN acquisition and its first heartbeat; retry startup at the application boundary if desired. Established listeners continue to reconnect.
+- Schema component failures now reach SQL migration and readiness callers, server startup and test-sql migration helpers with their original error, tag and cause, and log the component name. Handle the component's own error instead of a wrapping `MigrationError` with kind `Failed`. When annotating migration options with fallible components, supply their error type as the second generic parameter; the default describes components that cannot fail.
+- Declare `WorkerRelease` through `defineService`. Consumers using the old class as a type must use `Context.Service.Identifier<typeof WorkerRelease>`; yielding the service and providing its value stay the same.
+
+## 0.25.0 - 2026-10-30
+
+### Changed
+
+- Require the Effect 4.0.6 stack.
+
+### Fixed
+
+- Publish committed SQL invalidations immediately for their owning database, including when another database has an open transaction.
+
+### Breaking
+
+- `@shivaedev/sql`: migration-body SQL failures now propagate as native typed `MigrationError` failures. Handle them with `Effect.catchTag("MigrationError", ...)` instead of defect recovery; migration-body defects remain defects.
+- `@shivaedev/http`: bounded request-body reads use the native reader and its connection cleanup. Do not assume a rejected upload can drain an arbitrarily large unread body and reuse its connection; allow the HTTP client to open a new connection. The optional Node platform peer is no longer required by this package.
+
 ## 0.24.0 - 2026-10-28
 
 ### Added

package/README.md

@@ -21,7 +21,7 @@ const rows = yield* lines.findMany({
 
 ### How to think about it
 
-The application owns the database schema and its native Effect `SqlClient` layer. Configure new clients with `clientOptions` to map camelCase model fields to snake_case PostgreSQL columns. A **model** describes decoded row fields and the variants used for insertion, updating and JSON. A **repository** combines native `SqlModel` CRUD with a small `findMany` query whose filters and selected results use those fields.
+The application owns the database schema. For PostgreSQL, `postgresLayer` provides one native pool and the Effect SQL clients that use it. Configure new clients with `clientOptions` to map camelCase model fields to snake_case PostgreSQL columns. A **model** describes decoded row fields and the variants used for insertion, updating and JSON. A **repository** combines native `SqlModel` CRUD with a small `findMany` query whose filters and selected results use those fields.
 
 Repository writes announce their table and returned row keys automatically. Every written row keeps its record key, including in bulk writes. Fields marked with `bucket` also announce their old and new bucket keys. Each write uses `transact`; start a surrounding multi-write boundary with `transact` too, so keys leave only after its owning database commits. Bare native transactions are refused because their commit cannot be observed. The change ownership comes from `changes`; this package supplies the SQL boundary and the Reactivity publisher.
 
@@ -29,6 +29,25 @@ Migrations are ordinary Effects loaded by native Migrator. `migratePostgres` add
 
 The work has three parts: describe the model and provide its database once, choose repository operations per feature, and put each changed write inside the transaction that owns its commit.
 
+### One PostgreSQL pool per application
+
+`postgresLayer(url, options)` from `@shivaedev/sql/postgresLayer.ts` provides the native `PgPool` service from `@effect/sql-pg/PgPool`, `PgClient` and `SqlClient` together. `options` accepts `applicationName`, `maxConnections`, `transformQueryNames` and `transformResultNames`. Queries, transactions and raw connections reserved with `yield* pool.reserve` share the same `maxConnections` budget. A reservation holds its connection until its scope closes; release it before waiting for work that needs that slot.
+
+```ts
+import * as PgPool from "@effect/sql-pg/PgPool";
+import { Effect, Redacted } from "effect";
+import { postgresLayer } from "@shivaedev/sql/postgresLayer.ts";
+
+const database = postgresLayer(Redacted.make("postgresql://localhost/example"), { maxConnections: 4 });
+const backend = Effect.gen(function* () {
+	const pool = yield* PgPool.PgPool;
+	const connection = yield* pool.reserve;
+	return yield* connection.query("select pg_backend_pid() as pid");
+}).pipe(Effect.scoped, Effect.provide(database));
+```
+
+The Layer owns the pool and waits for every socket to close during shutdown. A reserved connection sees committed writes from client transactions in the same database; it does not implicitly join a client's open transaction. `appDatabase` and database-backed `appHost` from `@shivaedev/server/appHost.ts` compose this Layer and expose the pool to application services.
+
 ### SQL names: configure the client once
 
 ```ts
@@ -36,14 +55,16 @@ import * as PgClient from "@effect/sql-pg/PgClient";
 import { Redacted } from "effect";
 import { clientOptions } from "@shivaedev/sql/clientOptions.ts";
 
-const database = PgClient.layer(clientOptions({
-  url: Redacted.make("postgresql://localhost/example"),
-}));
+const database = PgClient.layer(
+	clientOptions({
+		url: Redacted.make("postgresql://localhost/example"),
+	}),
+);
 ```
 
 `clientOptions` enables Effect SQL's `transformQueryNames` with Effect's `String.camelToSnake` and `transformResultNames` with `String.snakeToCamel` by default. A model field `createdAt` writes the migration-created `created_at` column, and returned rows contain `createdAt`. Inserts, selects, filters, ordering, updates and raw SQL share the client's transforms; column aliases are unnecessary. Write literal migration SQL with snake_case columns. In tagged SQL, interpolated identifiers such as `sql("createdAt")` are transformed; literal SQL text stays as written.
 
-To opt out for an existing database with quoted camelCase columns or models with snake_case fields, use `PgClient.layer(clientOptions(options, { snakeCase: false }))`. Existing native clients are unchanged until configured with this helper. Native `transformQueryNames` and `transformResultNames` supplied in `options` take precedence. For `platform`'s `appHost` or `appDatabase`, use `clientOptions` on their `config` object; the host forwards those native transforms to its client.
+To opt out for an existing database with quoted camelCase columns or models with snake_case fields, use `PgClient.layer(clientOptions(options, { snakeCase: false }))`. Existing native clients are unchanged until configured with this helper. Native `transformQueryNames` and `transformResultNames` supplied in `options` take precedence. For `appHost` or `appDatabase` from `@shivaedev/server/appHost.ts`, use `clientOptions` on their `config` object; the host forwards those native transforms to its client.
 
 ### 1. Once per model: fields and writable variants
 
@@ -53,20 +74,20 @@ import { Model } from "effect/schema";
 import { makeRepository } from "@shivaedev/sql/repository.ts";
 
 class InvoiceLine extends Model.Class<InvoiceLine>("InvoiceLine")({
-  amount: Schema.NumberFromString,
-  id: Model.Field({
-    select: Schema.Number,
-    update: Schema.Number,
-    json: Schema.Number,
-  }),
-  name: Schema.String,
-  note: Schema.NullOr(Schema.String),
+	amount: Schema.NumberFromString,
+	id: Model.Field({
+		select: Schema.Number,
+		update: Schema.Number,
+		json: Schema.Number,
+	}),
+	name: Schema.String,
+	note: Schema.NullOr(Schema.String),
 }) {}
 
 const makeInvoiceLines = makeRepository(InvoiceLine, {
-  tableName: "invoice_line",
-  idColumn: "id",
-  spanPrefix: "InvoiceLine",
+	tableName: "invoice_line",
+	idColumn: "id",
+	spanPrefix: "InvoiceLine",
 });
 ```
 
@@ -78,8 +99,8 @@ A generated creation time can have a different database and JSON representation:
 
 ```ts
 const createdAt = Model.Field({
-  select: Schema.Date,
-  json: Schema.DateFromString,
+	select: Schema.Date,
+	json: Schema.DateFromString,
 });
 ```
 
@@ -93,17 +114,15 @@ import { Result, SchemaGetter, SchemaParser } from "effect";
 
 const Integers = Schema.Array(Schema.Int);
 const StoredIntegers = Schema.Unknown.pipe(
-  Schema.decodeTo(Integers, {
-    decode: SchemaGetter.transformEffect((value) =>
-      SchemaParser.decodeUnknownEffect(Integers)(PgTypes.isParameter(value) ? value.value : value),
-    ),
-    encode: SchemaGetter.transform((values) => Result.getOrThrow(PgTypes.array(values, PgTypes.OID.int4))),
-  }),
+	Schema.decodeTo(Integers, {
+		decode: SchemaGetter.transformEffect((value) => SchemaParser.decodeUnknownEffect(Integers)(PgTypes.isParameter(value) ? value.value : value)),
+		encode: SchemaGetter.transform((values) => Result.getOrThrow(PgTypes.array(values, PgTypes.OID.int4))),
+	}),
 );
 
 class Sample extends Model.Class<Sample>("Sample")({
-  id: Schema.Int,
-  values: Model.Field({ insert: StoredIntegers, select: StoredIntegers, update: StoredIntegers, json: Integers }),
+	id: Schema.Int,
+	values: Model.Field({ insert: StoredIntegers, select: StoredIntegers, update: StoredIntegers, json: Integers }),
 }) {}
 ```
 
@@ -113,20 +132,20 @@ The decoded value is an integer array in every variant. The database variants en
 
 ```ts
 const reviseInvoiceLine = Effect.gen(function* () {
-  const lines = yield* makeInvoiceLines;
-  const inserted = yield* lines.insert({
-    amount: 52,
-    name: "Consulting",
-    note: null,
-  });
-  const updated = yield* lines.update({
-    ...inserted,
-    amount: 55,
-    name: "Onsite consulting",
-  });
-  const found = yield* lines.findById(updated.id);
-  yield* lines.delete(found.id);
-  return yield* lines.findMany({ where: { id: found.id } });
+	const lines = yield* makeInvoiceLines;
+	const inserted = yield* lines.insert({
+		amount: 52,
+		name: "Consulting",
+		note: null,
+	});
+	const updated = yield* lines.update({
+		...inserted,
+		amount: 55,
+		name: "Onsite consulting",
+	});
+	const found = yield* lines.findById(updated.id);
+	yield* lines.delete(found.id);
+	return yield* lines.findMany({ where: { id: found.id } });
 });
 ```
 
@@ -144,15 +163,15 @@ For lists, choose the fields the caller needs:
 
 ```ts
 const listInvoiceLines = (name: string | undefined) =>
-  Effect.gen(function* () {
-    const lines = yield* makeInvoiceLines;
-    return yield* lines.findMany({
-      where: { amount: 52, name, note: null },
-      select: ["name", "amount"],
-      orderBy: { field: "name", direction: "desc" },
-      limit: 20,
-    });
-  });
+	Effect.gen(function* () {
+		const lines = yield* makeInvoiceLines;
+		return yield* lines.findMany({
+			where: { amount: 52, name, note: null },
+			select: ["name", "amount"],
+			orderBy: { field: "name", direction: "desc" },
+			limit: 20,
+		});
+	});
 ```
 
 Filter entries are joined with `AND`. A field value uses equality; a null filter matches SQL `NULL`, and an omitted or `undefined` value leaves the field unconstrained. Filters use decoded field values, so `amount` takes a number. Selected results are decoded records with the selected fields' types; this function returns `Array<{ readonly name: string; readonly amount: number }>`.
@@ -267,34 +286,30 @@ Here `archive` is another unversioned `InvoiceLine` repository with its own tabl
 
 A repository configured with `conflictColumns` also exposes `insertFromSelectOrIgnore(source, columns)`. It uses the same conflict columns and optional `conflictWhere` predicate as `insertOrIgnore`, skips existing keys, and returns only inserted rows. An empty source returns `[]`. Both writes join `transact` and roll back with it. Source filter encoding services and target result decoding services remain in the write's Effect environment.
 
-
 ### Composite keys and idempotent writes
 
 A generated app can ingest the same reading more than once. Declare the table's primary key with an `idColumn` tuple and its unique conflict key with `conflictColumns`:
 
 ```ts
 class Reading extends Model.Class<Reading>("Reading")({
-  source: Schema.String,
-  sequence: Schema.NumberFromString,
-  amount: Schema.NumberFromString,
-  label: Schema.String,
+	source: Schema.String,
+	sequence: Schema.NumberFromString,
+	amount: Schema.NumberFromString,
+	label: Schema.String,
 }) {}
 
 const ingest = Effect.gen(function* () {
-  const readings = yield* makeRepository(Reading, {
-    tableName: "readings",
-    idColumn: ["source", "sequence"],
-    conflictColumns: ["source", "sequence"],
-    spanPrefix: "Reading",
-  });
-  const input = { source: "meter", sequence: 1, amount: 52, label: "Imported" };
-  const inserted = yield* readings.insertOrIgnore(input);
-  const saved = yield* readings.upsert(
-    { ...input, amount: 60 },
-    { updateColumns: ["amount"] },
-  );
-  const found = yield* readings.findById({ source: "meter", sequence: 1 });
-  return { inserted, saved, found };
+	const readings = yield* makeRepository(Reading, {
+		tableName: "readings",
+		idColumn: ["source", "sequence"],
+		conflictColumns: ["source", "sequence"],
+		spanPrefix: "Reading",
+	});
+	const input = { source: "meter", sequence: 1, amount: 52, label: "Imported" };
+	const inserted = yield* readings.insertOrIgnore(input);
+	const saved = yield* readings.upsert({ ...input, amount: 60 }, { updateColumns: ["amount"] });
+	const found = yield* readings.findById({ source: "meter", sequence: 1 });
+	return { inserted, saved, found };
 });
 ```
 
@@ -302,12 +317,12 @@ The application creates `readings` with `PRIMARY KEY (source, sequence)`; `seque
 
 `conflictColumns` is a nonempty tuple of inserted model fields backed by a database unique constraint or primary key. It can differ from the primary key, including a unique external key beside a generated ID. Declaring it adds these methods:
 
-| Method | Input | Result |
-| --- | --- | --- |
-| `insertOrIgnore` | Model insert input | `Option.some` of the decoded inserted model, or `Option.none` when the declared key conflicts. |
-| `upsert` | Model insert input and `{ updateColumns: [...] }` | `{ row, inserted }`, with the decoded model and a boolean identifying an insert. |
-| `insertManyOrIgnore` | Readonly array of model insert inputs | Decoded inserted models; conflicting rows are omitted. |
-| `upsertMany` | Readonly array of model insert inputs and `{ updateColumns: [...] }` | An array of `{ row, inserted }` results. |
+| Method               | Input                                                                | Result                                                                                         |
+| -------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `insertOrIgnore`     | Model insert input                                                   | `Option.some` of the decoded inserted model, or `Option.none` when the declared key conflicts. |
+| `upsert`             | Model insert input and `{ updateColumns: [...] }`                    | `{ row, inserted }`, with the decoded model and a boolean identifying an insert.               |
+| `insertManyOrIgnore` | Readonly array of model insert inputs                                | Decoded inserted models; conflicting rows are omitted.                                         |
+| `upsertMany`         | Readonly array of model insert inputs and `{ updateColumns: [...] }` | An array of `{ row, inserted }` results.                                                       |
 
 All four methods encode with the model's insert schema and retain its codec services. `upsert` and `upsertMany` require a nonempty list of inserted, updateable fields; primary-key, conflict-key and generated fields are excluded. Only those columns take their incoming encoded values on conflict. Other stored values stay intact. A selected optional field must be present in every encoded input. Unknown, empty, protected or absent update columns fail with `SchemaError`. A violation of another unique constraint remains a native `SqlError`.
 
@@ -369,27 +384,27 @@ Declare a numeric version field in the model's select and update variants, leave
 
 ```ts
 class Document extends Model.Class<Document>("Document")({
-  id: Schema.String,
-  ownerId: Schema.String,
-  name: Schema.String,
-  lockVersion: Model.Field({ select: Schema.Number, update: Schema.Number, json: Schema.Number }),
+	id: Schema.String,
+	ownerId: Schema.String,
+	name: Schema.String,
+	lockVersion: Model.Field({ select: Schema.Number, update: Schema.Number, json: Schema.Number }),
 }) {}
 
 const makeDocuments = makeRepository(Document, {
-  tableName: "documents",
-  idColumn: ["id", "ownerId"],
-  conflictColumns: ["id"],
-  spanPrefix: "Document",
-  versionColumn: "lockVersion",
+	tableName: "documents",
+	idColumn: ["id", "ownerId"],
+	conflictColumns: ["id"],
+	spanPrefix: "Document",
+	versionColumn: "lockVersion",
 });
 
 const reviseDocument = Effect.gen(function* () {
-  const documents = yield* makeDocuments;
-  const key = { id: crypto.randomUUID(), ownerId: "current-owner" };
-  yield* documents.insertOrIgnore({ ...key, name: "Draft" });
-  const original = yield* documents.findById(key);
-  const saved = yield* documents.update({ ...original, name: "Published" });
-  yield* documents.delete(key, saved.lockVersion);
+	const documents = yield* makeDocuments;
+	const key = { id: `${yield* Random.nextInt}:${yield* Random.nextInt}`, ownerId: "current-owner" };
+	yield* documents.insertOrIgnore({ ...key, name: "Draft" });
+	const original = yield* documents.findById(key);
+	const saved = yield* documents.update({ ...original, name: "Published" });
+	yield* documents.delete(key, saved.lockVersion);
 });
 ```
 
@@ -408,19 +423,19 @@ import { Data } from "effect";
 import { transact } from "@shivaedev/sql/transact.ts";
 
 class StorageUnavailable extends Data.TaggedError("StorageUnavailable")<{
-  readonly reason: string;
+	readonly reason: string;
 }> {}
 
 const saveInvoiceLine = (input: typeof InvoiceLine.update.Type) =>
-  Effect.gen(function* () {
-    const lines = yield* makeInvoiceLines;
-    const saved = yield* lines.update(input);
-    return saved;
-  }).pipe(
-    transact({
-      onSqlError: (error) => new StorageUnavailable({ reason: error.message }),
-    }),
-  );
+	Effect.gen(function* () {
+		const lines = yield* makeInvoiceLines;
+		const saved = yield* lines.update(input);
+		return saved;
+	}).pipe(
+		transact({
+			onSqlError: (error) => new StorageUnavailable({ reason: error.message }),
+		}),
+	);
 ```
 
 `transact` wraps native `sql.withTransaction`. It maps typed `SqlError` failures through `onSqlError` and keeps other typed failures and service requirements. `invalidateOnCommit` records derived reader keys that a repository or command declaration does not already name; after the owning outermost commit, they are deduplicated and passed to native `Reactivity.invalidate` once. The record `{ invoiceLines: [1] }` marks `"invoiceLines"` and `"invoiceLines:1"`. An array such as `["invoiceLines:1"]` marks only those keys.
@@ -432,10 +447,10 @@ import { bucket } from "@shivaedev/changes/buckets.ts";
 import { collection, invalidationKeys } from "@shivaedev/changes/keys.ts";
 
 class Note extends Model.Class<Note>("Note")({
-  id: Schema.Number,
-  listId: bucket(Schema.Number),
-  owner: bucket(Schema.String),
-  title: Schema.String,
+	id: Schema.Number,
+	listId: bucket(Schema.Number),
+	owner: bucket(Schema.String),
+	title: Schema.String,
 }) {}
 
 const notes = collection("notes", Note.fields.id, { listId: Note.fields.listId, owner: Note.fields.owner });
@@ -445,8 +460,9 @@ Use the repository's table name as the collection name in query read keys. Every
 
 Bucket writes require PostgreSQL 18 or later: native `RETURNING old` supplies old values atomically, including for conflict updates. Repositories without bucket fields keep their existing SQL dialect support. Bulk writes keep every record and bucket key; the PostgreSQL publisher splits large batches into NOTIFY payloads.
 
-The transaction rules follow the database owner:
+Record and bucket keys that must commit atomically with a write come from this model and repository path. A command's `invalidates(payload, result, viewer)` runs after its handler returns and uses a separate publication transaction. Failed publication retries twice with 50 ms and 100 ms backoffs. If those attempts fail, `postgresChanges` resynchronizes local live streams and broadcasts Resync on its change channel. If PostgreSQL also rejects the broadcast or cannot be reached, local streams still resynchronize, but healthy listeners on other hosts can miss the write until they reconnect or otherwise reconcile. The failure is logged; NOTIFY provides no durable replay.
 
+The transaction rules follow the database owner:
 - A typed failure or interruption before commit rolls back and announces nothing. A failed deferred `COMMIT` fails through `onSqlError` and also announces nothing.
 - A nested `transact` on the same client uses a native savepoint. Its successful keys join the outer set; a rolled-back savepoint's keys are discarded.
 - A transaction on a second client commits independently. Its keys publish when that client commits, even if the enclosing client's transaction later rolls back.
@@ -466,14 +482,15 @@ Serialize cooperating jobs inside `transact`:
 ```ts
 import { advisoryXactLock } from "@shivaedev/sql/advisoryXactLock.ts";
 
-const serializeInvoiceJob = (input: typeof InvoiceLine.update.Type) => Effect.gen(function* () {
-  yield* advisoryXactLock("jobs:invoice-import");
-  yield* saveInvoiceLine(input);
-}).pipe(
-  transact({
-    onSqlError: (error) => new StorageUnavailable({ reason: error.message }),
-  }),
-);
+const serializeInvoiceJob = (input: typeof InvoiceLine.update.Type) =>
+	Effect.gen(function* () {
+		yield* advisoryXactLock("jobs:invoice-import");
+		yield* saveInvoiceLine(input);
+	}).pipe(
+		transact({
+			onSqlError: (error) => new StorageUnavailable({ reason: error.message }),
+		}),
+	);
 ```
 
 `advisoryXactLock(key: bigint | string)` waits for PostgreSQL's `pg_advisory_xact_lock` on the current client's transaction. A bigint is passed as a signed 64-bit PostgreSQL key without converting it to a JavaScript number. A string uses PostgreSQL's `hashtextextended(key, 0)` as its bigint key; use the same string in cooperating callers. Hash collisions share a lock. Different keys proceed independently. The lock lasts until commit or rollback, including rollback when the holding fiber is interrupted. Outside a transaction, the function fails with typed `AdvisoryLockOutsideTransaction` from the same module. SQL failures remain typed `SqlError` and follow the surrounding `transact` mapper.
@@ -487,8 +504,8 @@ import { Effect } from "effect";
 import { SqlClient } from "effect/sql";
 
 export default Effect.gen(function* () {
-  const sql = yield* SqlClient.SqlClient;
-  yield* sql`create table orders (name text primary key)`;
+	const sql = yield* SqlClient.SqlClient;
+	yield* sql`create table orders (name text primary key)`;
 });
 ```
 
@@ -501,9 +518,9 @@ import { migrationsFromDirectory } from "@shivaedev/sql/migrationsFromDirectory.
 import { migratePostgres } from "@shivaedev/sql/migrations.ts";
 
 const migrateOrders = migratePostgres({
-  table: "app_migrations",
-  lockTimeout: "5 seconds",
-  loader: migrationsFromDirectory(process.cwd()).pipe(Effect.provide(NodeServices.layer)),
+	table: "app_migrations",
+	lockTimeout: "5 seconds",
+	loader: migrationsFromDirectory(process.cwd()).pipe(Effect.provide(NodeServices.layer)),
 });
 ```
 
@@ -517,18 +534,17 @@ Use sequential numbers, not timestamps. Effect's Migrator skips any migration wh
 
 `migratePostgres` takes a transaction-scoped advisory lock before creating the ledger and running native Migrator. Concurrent runners on a fresh or existing ledger wait, then see the committed ledger and avoid repeating the migrations. Every runner of that ledger must use this helper and the same ledger name. The required `lockTimeout` bounds PostgreSQL lock waits; `Duration.infinity` sets the transaction's lock timeout to zero. Choose deployment and execution timeouts in the application.
 
-A failed batch rolls back its DDL, data and ledger entries, retaining previously committed migrations. A failed first batch also rolls back the bootstrapped ledger. A lock timeout fails with typed `SqlError` and reason `LockTimeoutError`; a migration-body SQL failure is a native `MigrationError` defect. Inspect startup completion with `Effect.exit` when both typed failures and defects matter. Keep nontransactional DDL in schema components; external side effects, crash recovery and deployment compatibility need their own migration policy.
+A failed batch rolls back its DDL, data and ledger entries, retaining previously committed migrations. A failed first batch also rolls back the bootstrapped ledger. A lock timeout fails with typed `SqlError` and reason `LockTimeoutError`; a migration-body SQL failure is a typed native `MigrationError`. Inspect startup completion with `Effect.exit` when both typed failures and defects matter. Keep nontransactional DDL in schema components; external side effects, crash recovery and deployment compatibility need their own migration policy.
 
-Schema components describe storage owned by another engine alongside the numbered `loader`: pass `components: [{ name, apply, pending }]` to `migratePostgres` and `assertPostgresMigrations`. `apply` runs after the ledger transaction commits, outside that transaction, on every migration invocation; it must support repeated execution. `pending` returns a description when work remains and `undefined` when current. Components are never recorded as numbered ledger entries. Component failures become `MigrationError` (`kind: "Failed"`) with the component name and original cause; their failure leaves the application ledger committed.
+Schema components describe storage owned by another engine alongside the numbered `loader`: pass `components: [{ name, apply, pending }]` to `migratePostgres` and `assertPostgresMigrations`. `apply` runs after the ledger transaction commits, outside that transaction, on every migration invocation; it must support repeated execution. `pending` returns a description when work remains and `undefined` when current. Components are never recorded as numbered ledger entries. Component failures reach callers unchanged, including their original tags and causes, and are logged with the component name; their failure leaves the application ledger committed. Migration and readiness functions infer component error types. An explicitly annotated `PostgresMigrationOptions<R, E>` uses its second parameter for those errors; omitting it describes components that cannot fail.
 
 For processes whose deployment owns migration execution, call `assertPostgresMigrations({ loader, table?, components? })` from `@shivaedev/sql/assertPostgresMigrations.ts` before starting services. It checks the native loader’s required IDs and names against the ledger without running migration bodies or creating a ledger. A missing ledger, pending migration or mismatched name fails with native `MigrationError` (`kind: "BadState"`); database failures stay typed `SqlError`. Later ledger entries are allowed so an older application version can start during a rolling deployment. Pending ledger IDs and component names and details appear together in the error. This checks recorded migrations and component readouts, not physical schema drift.
 
-For a structured readiness readout, use `pendingPostgresMigrations({ loader, table?, components? })` from `@shivaedev/sql/pendingPostgresMigrations.ts`. It returns `{ migrations: [{ id, name }], components: [{ name, detail }] }` for pending work, with both arrays empty when current. It reads the same ledger and component checks as `assertPostgresMigrations` without running migrations.
+For a structured readiness readout, use `pendingPostgresMigrations({ loader, table?, components? })` from `@shivaedev/sql/pendingPostgresMigrations.ts`. It returns `{ migrations: [{ id, name }], components: [{ name, detail }] }` for pending work, with both arrays empty when current. It reads the same ledger and component checks as `assertPostgresMigrations` without running migrations. Malformed ledger and release rows fail with `SchemaError`.
 
 Pass an optional `release` string to `migratePostgres` to record the owning release after all ledger migrations and schema components succeed. The final `postgresRelease(release, table?)` schema component owns a one-row `<ledger>_release` table with typed `release` and UTC `recorded_at timestamptz` columns, plus a `<ledger>_workers` table with typed process identity, release and UTC heartbeat columns. `readPostgresRelease(table?)` from `postgresRelease.ts` returns the recorded release and `recordedAt` Date, or `undefined` for a missing marker. `pendingPostgresMigrations({ loader, release, table? })` reports a missing or different release as a pending component. Without `release`, migration and readiness calls neither write nor read these tables.
 
-Server's `appDatabase` supplies the optional `WorkerRelease` Context service in migration mode `"wait"` with a release. Startup waits for that marker within `waitTimeout`; subsequent checks run every `pollInterval`. Each worker database Layer claims a process row only when its release owns the marker and no live row of another release remains. Heartbeats continue every poll while jobs drain; completed drain and clean shutdown remove the row. Rows older than five polling intervals count as gone, bounding takeover after a crash (five seconds at the default one-second poll). Reserve SQL pool capacity for heartbeats alongside active jobs and the change listener. Release equality decides ownership, so rolling back the marker resumes the earlier worker. jobs reads the service automatically; applications do not connect a signal themselves. Web's `"check"` mode ignores the marker.
-
+`appDatabase` from `@shivaedev/server/appHost.ts` supplies the optional `WorkerRelease` Context service in migration mode `"wait"` with a release. Startup waits for that marker within `waitTimeout`; subsequent checks run every `pollInterval`. Each worker database Layer claims a process row only when its release owns the marker and no live row of another release remains. Heartbeats continue every poll while jobs drain, including after a connection blip. Each failed heartbeat or ownership poll logs its cause and retries three times, one quarter of a polling interval apart; exhausted retries close the worker scope with the failure cause. Completed drain and clean shutdown remove the row. Rows older than five polling intervals count as gone, bounding takeover after a crash (five seconds at the default one-second poll). Reserve SQL pool capacity for heartbeats alongside active jobs and the change listener. Release equality decides ownership, so rolling back the marker resumes the earlier worker. `@shivaedev/jobs` reads the service automatically; applications do not connect a signal themselves. Web's `"check"` mode ignores the marker.
 
 ### PostgreSQL delivery between processes
 
@@ -536,41 +552,44 @@ Server's `appDatabase` supplies the optional `WorkerRelease` Context service in
 
 ```ts
 const delivery = postgresChanges({
-  channel: "application_changes",
-  client: pg,
-  resync: hints.resync,
+	channel: "application_changes",
+	client: pg,
+	resync: hints.resync,
 });
 ```
 
-`pg` is the application's `@effect/sql-pg` client; the binding accepts its native SQL and `listen` methods without creating another pool. Reserve one session connection for LISTEN and another for writes and heartbeats; use a pool client with at least two connections. Compose `delivery` into the Layer that provides feature services using `transact`, alongside the existing SQL and Reactivity services. The [reference server](https://github.com/ShivaeDev/platform/blob/main/packages/react/src/test-support/postgres-example/server.ts) shows the complete composition. The binding sends `select pg_notify(...)` through the writing transaction's `SqlClient`, so a rollback wakes no process. Its transaction sink leaves delivery to the listener, including in the writing process. Unframed `invalidateOnCommit` calls retain local invalidation; cross-process writes must use `transact`.
+`pg` is the application's `@effect/sql-pg` client; the binding accepts its native SQL and `listen` methods without creating another pool. Optional `listenerClient` supplies a different native client for LISTEN; the application client still owns write notifications and heartbeat publication. Both clients must reach the same database. LISTEN requires a direct or session-mode connection. With one shared client, reserve one session connection for LISTEN and another for writes and heartbeats; use a pool client with at least two connections. With separate clients, the listener needs one connection of its own. Compose `delivery` into the Layer that provides feature services using `transact`, alongside the existing SQL and Reactivity services. The [reference server](https://github.com/ShivaeDev/platform/blob/main/packages/react/src/test-support/postgres-example/server.ts) shows the complete composition. The binding sends `select pg_notify(...)` through the writing transaction's `SqlClient`, so a rollback wakes no process. Its transaction sink leaves delivery to the listener, including in the writing process. Unframed `invalidateOnCommit` calls retain local invalidation; cross-process writes must use `transact`.
 
-`PostgresChangesOptions` takes `channel`, `client`, `resync`, and optional `heartbeatInterval`, `heartbeatTimeout` and `retryDelay` Effect durations. The defaults are 5 seconds, 10 seconds and 1 second. Acquisition waits for a heartbeat received through LISTEN. A missing heartbeat or a stream failure resyncs streams before listener cleanup; a successful reconnection resyncs again. Each listener finalizer has the same `heartbeatTimeout` deadline, so a stalled UNLISTEN cannot prevent the following native connection release or a fresh subscription. The heartbeat detects a listener that stops delivering without failing. `resync` is an infallible `Effect.Effect<number>` returning the number of open live streams it marked for reconciliation. `makeLiveServer.resync` provides this count and stops counting a stream when its scope closes. Direct bindings with another stream owner must return that owner's count. Provide the Layer for the process lifetime so scope release closes the listener.
+`PostgresChangesOptions` takes `channel`, `client`, `resync`, optional `listenerClient` and `connectionSetting` (a diagnostic label, default `"client"`), and optional `heartbeatInterval`, `heartbeatTimeout` and `retryDelay` Effect durations. The defaults are 5 seconds, 10 seconds and 1 second. Acquisition waits for LISTEN and then a heartbeat received through it, each within `heartbeatTimeout`. A deadline without a heartbeat fails startup with `PostgresListenerError` from `@shivaedev/sql/PostgresListenerError.ts`, whose `connectionSetting` and message identify the connection to fix. Native SQL failures still fail startup with `SqlError`. Established listeners reconnect after a loss. Loss and reconnect failures log their causes. A missing heartbeat or a stream failure resyncs streams before listener cleanup; a successful reconnection resyncs again. Listener cleanup runs in a parallel sub-scope bounded by `heartbeatTimeout`, so stalled listener cleanup cannot delay native connection release, a fresh subscription or scope shutdown. The heartbeat detects a listener that stops delivering without failing. `resync` is an infallible `Effect.Effect<number>` returning the number of open live streams it marked for reconciliation. `makeLiveServer.resync` provides this count and stops counting a stream when its scope closes. Direct bindings with another stream owner must return that owner's count. Provide the Layer for the process lifetime so scope release closes the listener.
 
 NOTIFY is a wake-up signal, not a durable log. Transaction payloads contain only string or finite-number invalidation keys, with no row values. PostgreSQL requires each payload to be smaller than 8,000 bytes in the default configuration. The binding splits JSON arrays by their UTF-8 byte length; one key that cannot fit, or a nonserializable key type, fails with `SqlError` before commit and rolls back the write. Heartbeats use a separate control payload on the same channel. Applications choose a channel shared only by their cooperating processes. LISTEN requires a session connection; PgBouncer transaction pooling needs another delivery adapter. Missed notifications are reconciled by querying again on resync, with no replay guarantee.
 
 ### API
 
 Import the module that defines the name; there is no root entry.
-
-| Module | Export | Input or role |
-| --- | --- | --- |
-| `@shivaedev/sql/clientOptions.ts` | `clientOptions(options, { snakeCase? })`, `SqlNameTransforms` | Add default native name transforms to driver or app host options; opt out with `snakeCase: false`. |
-| `@shivaedev/sql/repository.ts` | `makeRepository(model, options)` | `tableName`, scalar or composite `idColumn`, `spanPrefix`, optional `versionColumn`, `conflictColumns` and `conflictWhere`; requires native `SqlClient`. |
-| `@shivaedev/sql/repository.ts` | `OptimisticConcurrencyError` | Typed stale or missing-row failure for versioned writes, with `tableName`, `id`, `expectedVersion`, `reason: "missing" | "stale"`. |
-| `@shivaedev/sql/transact.ts` | `transact(effect, options)` or `effect.pipe(transact(options))` | Required `onSqlError` mapper; requires `SqlClient` and `Reactivity`. |
-| `@shivaedev/sql/transact.ts` | `invalidateOnCommit(keys)` | Records keys for its client, or invalidates immediately outside a transaction. |
-| `@shivaedev/sql/advisoryXactLock.ts` | `advisoryXactLock(key)`, `AdvisoryLockOutsideTransaction` | PostgreSQL transaction lock on a bigint or string hashed with `hashtextextended(key, 0)`; requires an active transaction on the current `SqlClient`. |
-| `@shivaedev/sql/migrationConvention.ts` | `MIGRATIONS_DIRECTORY`, `MIGRATION_FILE_PATTERN` | Application folder and four-digit sequential snake_case TypeScript filename pattern. |
-| `@shivaedev/sql/migrationsFromDirectory.ts` | `migrationsFromDirectory(root)` | Discover migrations under the application root with native `FileSystem` and `Path`. |
-| `@shivaedev/sql/migrations.ts` | `migratePostgres(options)` | Native loader, required `lockTimeout`, optional `components` and ledger `table`, default `effect_sql_migrations`. |
-| `@shivaedev/sql/assertPostgresMigrations.ts` | `assertPostgresMigrations({ loader, table?, components? })` | Read-only readiness check of required migration IDs and names in the native ledger and registered schema components. |
-| `@shivaedev/sql/pendingPostgresMigrations.ts` | `pendingPostgresMigrations({ loader, table?, components? })` | Pending ledger migrations as ID and name, and pending schema components as name and detail. |
-| `@shivaedev/sql/postgresChanges.ts` | `postgresChanges(options)` | Scoped PostgreSQL LISTEN/NOTIFY Layer for commit-bound invalidation. |
+- `@shivaedev/sql/clientOptions.ts`: `clientOptions(options, { snakeCase? })`, `SqlNameTransforms` — Add default native name transforms to driver or app host options; opt out with `snakeCase: false`.
+- `@shivaedev/sql/repository.ts`: `makeRepository(model, options)` — `tableName`, scalar or composite `idColumn`, `spanPrefix`, optional `versionColumn`, `conflictColumns` and `conflictWhere`; requires native `SqlClient`.
+- `@shivaedev/sql/repository.ts`: `OptimisticConcurrencyError` — Typed stale or missing-row failure for versioned writes, with `tableName`, `id`, `expectedVersion`, `reason: "missing" | "stale"`.
+- `@shivaedev/sql/tupleIn.ts`: `tupleIn(model, fields, tuples)` — Filter entry matching two or more fields together against a list of tuples, for `where` in reads and unversioned deletes.
+- `@shivaedev/sql/upsertResult.ts`: `UpsertRow` — The `{ row, inserted }` result of an unconditional upsert.
+- `@shivaedev/sql/conditionalUpsert.ts`: `UpsertFilter`, `UpsertResult` — The `updateWhere` filter shape and the tagged `Inserted`, `Updated` or `Unchanged` result of a conditional upsert.
+- `@shivaedev/sql/mapSqlError.ts`: `mapSqlError({ constraints, fallback })` — Mapper from named constraint violations to application errors, with a fallback for every other `SqlError`.
+- `@shivaedev/sql/transact.ts`: `transact(effect, options)` or `effect.pipe(transact(options))` — Required `onSqlError` mapper; requires `SqlClient` and `Reactivity`.
+- `@shivaedev/sql/transact.ts`: `invalidateOnCommit(keys)` — Records keys for its client, or invalidates immediately outside a transaction.
+- `@shivaedev/sql/advisoryXactLock.ts`: `advisoryXactLock(key)`, `AdvisoryLockOutsideTransaction` — PostgreSQL transaction lock on a bigint or string hashed with `hashtextextended(key, 0)`; requires an active transaction on the current `SqlClient`.
+- `@shivaedev/sql/migrationConvention.ts`: `MIGRATIONS_DIRECTORY`, `MIGRATION_FILE_PATTERN` — Application folder and four-digit sequential snake_case TypeScript filename pattern.
+- `@shivaedev/sql/migrationsFromDirectory.ts`: `migrationsFromDirectory(root)` — Discover migrations under the application root with native `FileSystem` and `Path`.
+- `@shivaedev/sql/migrations.ts`: `migratePostgres(options)` — Native loader, required `lockTimeout`, optional `components`, `release` and ledger `table`, default `effect_sql_migrations`.
+- `@shivaedev/sql/assertPostgresMigrations.ts`: `assertPostgresMigrations({ loader, table?, components? })` — Read-only readiness check of required migration IDs and names in the native ledger and registered schema components.
+- `@shivaedev/sql/pendingPostgresMigrations.ts`: `pendingPostgresMigrations({ loader, table?, components? })` — Pending ledger migrations as ID and name, and pending schema components as name and detail.
+- `@shivaedev/sql/postgresRelease.ts`: `postgresRelease(release, table?)`, `readPostgresRelease(table?)` — Release marker schema component and its reader.
+- `@shivaedev/sql/postgresChanges.ts`: `postgresChanges(options)` — Scoped PostgreSQL LISTEN/NOTIFY Layer for commit-bound invalidation.
+- `@shivaedev/sql/testing.ts`: `withChangeCoverage(body, { covers })`, `expectPublished(keys)`, `UnannouncedWrites`, `PublishedKeysMismatch` — Test assertions that every write announced its keys and that the expected keys were published.
 
 ### Install and database setup
 
 ```sh
-pnpm add @shivaedev/sql effect@4.0.5 @effect/sql-pg@4.0.5
+pnpm add @shivaedev/sql effect @effect/sql-pg
 ```
 
 `effect` is a peer. Install the native driver your application uses; this command chooses PostgreSQL. Provide its layer, and provide native Reactivity when using `transact` or `invalidateOnCommit`:
@@ -581,16 +600,13 @@ import { Layer, Redacted } from "effect";
 import * as Reactivity from "effect/reactivity/Reactivity";
 import { clientOptions } from "@shivaedev/sql/clientOptions.ts";
 
-const database = Layer.merge(
-  PgClient.layer(clientOptions({ url: Redacted.make("postgresql://localhost/example") })),
-  Reactivity.layer,
-);
+const database = Layer.merge(PgClient.layer(clientOptions({ url: Redacted.make("postgresql://localhost/example") })), Reactivity.layer);
 
 const save = saveInvoiceLine({
-  id: 1,
-  name: "Consulting",
-  amount: 52,
-  note: null,
+	id: 1,
+	name: "Consulting",
+	amount: 52,
+	note: null,
 }).pipe(Effect.provide(database));
 ```
 
@@ -607,22 +623,20 @@ import { mapSqlError } from "@shivaedev/sql/mapSqlError.ts";
 import { transact } from "@shivaedev/sql/transact.ts";
 
 const onSqlError = mapSqlError({
-  constraints: {
-    "invoice_line_name_key": () => new NameTaken(),
-    "invoice_line_invoice_fkey": () => new InvoiceMissing(),
-    "invoice_line_amount_check": () => new InvalidAmount(),
-  },
-  fallback: (error) => new StorageUnavailable({ reason: error.message }),
+	constraints: {
+		"invoice_line_name_key": () => new NameTaken(),
+		"invoice_line_invoice_fkey": () => new InvoiceMissing(),
+		"invoice_line_amount_check": () => new InvalidAmount(),
+	},
+	fallback: (error) => new StorageUnavailable({ reason: error.message }),
 });
 
-const insertNamedLine = lines.insert({ amount: 52, name: "Consulting", note: null }).pipe(
-  transact({ onSqlError }),
-);
+const insertNamedLine = lines.insert({ amount: 52, name: "Consulting", note: null }).pipe(transact({ onSqlError }));
 ```
 
 The mapper handles named unique violations and PostgreSQL foreign-key and check violations. Every other `SqlError`, including unknown constraints, goes to `fallback`. Each callback receives the original error. The inferred error type contains exactly the mapped errors and the fallback; `transact` also preserves other typed failures from the operation. Constraint names belong to the application's migration; error types and presentation belong to the application.
 
-Recover outside `transact` so earlier writes roll back before handling a mapped domain error. A losing unique-key insert can then catch `NameTaken` and read the winner's row without a private transaction error. See the [constraint-failures guide](../../docs/framework/constraint-errors.md).
+Recover outside `transact` so earlier writes roll back before handling a mapped domain error. A losing unique-key insert can then catch `NameTaken` and read the winner's row without a private transaction error. See the [constraint-failures guide](https://github.com/ShivaeDev/platform/blob/main/docs/framework/constraint-errors.md).
 
 For the native PostgreSQL driver's default representations, use precise numeric strings with `Schema.BigDecimalFromString`, `int8` values with `Schema.BigInt`, `date` values as `YYYY-MM-DD` strings with `Schema.String`, instants with `Schema.Date`, nullable text and generated values. A persisted value that violates its schema fails decoding; a write and read inside the enclosing transaction roll back together when that failure escapes.