@shivaedev/sql 0.23.0 → 0.25.0

package/README.md

@@ -23,7 +23,7 @@ const rows = yield* lines.findMany({
 
 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.
 
-Repository writes announce their table and returned row keys automatically. A single write returning more than 1,000 rows across all its chunks announces only the table and `<table>:*`; writes returning up to 1,000 rows keep their item keys. Effect-contract item reads also react to the collection-wide key. 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.
+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.
 
 Migrations are ordinary Effects loaded by native Migrator. `migratePostgres` adds coordination for PostgreSQL runners sharing a ledger. It does not derive a table from a model: migration SQL and row codecs must agree.
 
@@ -36,14 +36,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 +55,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 +80,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 +95,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 +113,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 +144,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 +267,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 +298,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: [...] }` | The decoded inserted or updated model. |
-| `insertManyOrIgnore` | Readonly array of model insert inputs | Decoded inserted models; conflicting rows are omitted. |
-| `upsertMany` | Readonly array of model insert inputs and `{ updateColumns: [...] }` | Decoded inserted or updated models. |
+| 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`.
 
@@ -337,7 +333,9 @@ const result = yield* pullRequests.upsert(incoming, {
 
 `updateWhere` uses the repository filter shape: equality, `in`, ranges and text patterns combine with AND. A field names the stored column; `{ excluded: "field" }` refers to an incoming column of the same decoded type, in equality or range operands. Literal values pass through their field codecs. The condition becomes `DO UPDATE SET ... WHERE ...`, separate from the index predicate `conflictWhere`, and does not restrict inserts. PostgreSQL evaluates it while holding the conflicting row lock, so an older or equal incoming timestamp cannot overwrite a newer stored revision.
 
-With `updateWhere`, the typed result is `{ _tag: "Inserted", row }`, `{ _tag: "Updated", row }` or `{ _tag: "Unchanged" }`. Changed rows are decoded models; unchanged results carry no row and announce no change keys. Omitting `updateWhere` keeps the model result. `UpsertFilter` and `UpsertResult` are exported from `@shivaedev/sql/conditionalUpsert.ts`.
+On PostgreSQL, `upsert` returns `{ row, inserted }`: `row` is the decoded model and `inserted` is `true` for an insert and `false` for an update. Read the model from `saved.row` or destructure `{ row }`. `upsertMany` returns the same shape for each returned row. `UpsertRow` is exported from `@shivaedev/sql/upsertResult.ts`.
+
+With `updateWhere`, the typed result is `{ _tag: "Inserted", row, inserted: true }`, `{ _tag: "Updated", row, inserted: false }` or `{ _tag: "Unchanged" }`. Unchanged results carry no row and announce no change keys. `UpsertFilter` and `UpsertResult` are exported from `@shivaedev/sql/conditionalUpsert.ts`.
 
 `upsertMany(inputs, { updateColumns, updateWhere })` accepts the same condition and returns one tagged result per input, in input order. It executes one statement per input inside one transaction, so a later failure rolls back earlier writes. This uses more database round trips than an unconditional batch. Other batch calls use the chunked statements described below.
 
@@ -345,7 +343,7 @@ Versioned repositories with `conflictColumns` offer `insertOrIgnore`, including
 
 ### Batch writes
 
-Every unversioned repository also offers `insertMany(inputs)`, without requiring `conflictColumns`. Each batch method accepts a readonly array of decoded model insert inputs. Unconditional batch methods return an array of decoded models; conditional upserts return the tagged outcomes described above. Empty inputs return `[]` without writing.
+Every unversioned repository also offers `insertMany(inputs)`, without requiring `conflictColumns`. Each batch method accepts a readonly array of decoded model insert inputs. `insertMany` and `insertManyOrIgnore` return decoded models; `upsertMany` returns `{ row, inserted }` results, or the tagged outcomes described above when conditional. Empty inputs return `[]` without writing.
 
 ```ts
 const saved = yield* readings.upsertMany(
@@ -367,27 +365,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: 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);
 });
 ```
 
@@ -406,27 +404,44 @@ 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.
 
-Repository writes returning more than 1,000 rows announce the table key and `<table>:*` instead of per-row item keys, counted across all chunks of each call. Calls returning up to 1,000 rows keep their table and item keys. Effect-contract item reads register the collection-wide key automatically; code registering raw `<table>:<id>` Reactivity keys must also register `<table>:*`. Command invalidation keys are unchanged.
+Mark bucket fields on the model with `bucket` from `@shivaedev/changes/buckets.ts`:
 
-The transaction rules follow the database owner:
+```ts
+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,
+}) {}
+
+const notes = collection("notes", Note.fields.id, { listId: Note.fields.listId, owner: Note.fields.owner });
+```
 
+Use the repository's table name as the collection name in query read keys. Every inserted, updated or deleted row announces its record key and each declared bucket from the old and new stored values. An insert belongs only to its new buckets; a move announces both sides; a delete announces the old buckets. Bucket codecs decode stored values before producing keys, so a `bucket(Schema.NumberFromString)` field matches a numeric query bucket even when stored as text. Nullable and optional bucket values contribute no key when absent. Bucket codecs must need no services and decode to strings, numbers or absent values.
+
+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:
 - 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.
@@ -446,14 +461,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.
@@ -467,8 +483,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)`;
 });
 ```
 
@@ -481,9 +497,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)),
 });
 ```
 
@@ -497,7 +513,7 @@ 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.
 
@@ -507,8 +523,7 @@ For a structured readiness readout, use `pendingPostgresMigrations({ loader, tab
 
 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; 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
 
@@ -516,9 +531,9 @@ 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,
 });
 ```
 
@@ -531,26 +546,29 @@ NOTIFY is a wake-up signal, not a durable log. Transaction payloads contain only
 ### 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`:
@@ -561,16 +579,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));
 ```
 
@@ -580,29 +595,27 @@ The application's startup runs migrations and keeps its database scope alive for
 
 Query decoding and invalid limits can fail with `SchemaError`; SQL statement failures remain `SqlError`. `findById` adds `NoSuchElementError` for a missing row. Unversioned `update` defects if it returns no row unless called with `{ onMissing: "fail" }`, which keeps `NoSuchElementError` in the error channel. Versioned updates and deletes instead fail with typed `OptimisticConcurrencyError` when their ID and expected version match no row. A failed `COMMIT` is a typed `SqlError` like any other statement failure.
 
-Map a known constraint at the operation that understands it, after the transaction has rolled back:
+Map named constraints at the operation that understands them. `mapSqlError` returns a mapper for `transact`'s `onSqlError` or `Effect.mapError` on an Effect whose error is `SqlError`:
 
 ```ts
-import type { SqlError } from "effect/sql/SqlError";
-
-class NameTaken extends Data.TaggedError("NameTaken") {}
-
-const knownNameConflict = (error: SqlError): Effect.Effect<never, NameTaken | SqlError> =>
-  error.reason._tag === "UniqueViolation" &&
-  error.reason.constraint === "invoice_line_name_key"
-    ? Effect.fail(new NameTaken())
-    : Effect.fail(error);
-
-const insertNamedLine = Effect.gen(function* () {
-  const sql = yield* SqlClient.SqlClient;
-  const lines = yield* makeInvoiceLines;
-  return yield* sql
-    .withTransaction(lines.insert({ amount: 52, name: "Consulting", note: null }))
-    .pipe(Effect.catchTag("SqlError", knownNameConflict));
+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 }),
 });
+
+const insertNamedLine = lines.insert({ amount: 52, name: "Consulting", note: null }).pipe(transact({ onSqlError }));
 ```
 
-The migration owns the constraint name `invoice_line_name_key`. The mapper recognizes that named unique violation and keeps other failures intact. Put recovery outside the transaction so earlier writes in the operation roll back too. Domain error presentation belongs to the application.
+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](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.
 
@@ -612,18 +625,20 @@ JSON and JSONB columns are not supported. A repository write of a plain object t
 
 The package's PostgreSQL tests use a disposable database through `PLATFORM_SQL_TEST_DATABASE_URL`. Without the URL they skip locally; under `CI`, collection fails at the shared gate.
 
-The sql story kit exposes `withChangeCoverage` and `expectPublished`, also exported from `@shivaedev/sql/testing.ts`. `withChangeCoverage(body, { covers })` checks PostgreSQL transaction write counters before commit. Each written table must have its table key or at least one declared covering key recorded; otherwise `UnannouncedWrites` fails the transaction. Declare a module's domain read keys by table, including for raw SQL writes:
+The sql story kit exposes `withChangeCoverage` and `expectPublished`, also exported from `@shivaedev/sql/testing.ts`. `withChangeCoverage(body, { covers })` checks PostgreSQL transaction write counters before commit and requires every declared record and bucket key to be recorded. Repository writes supply these declarations automatically. Raw writes must declare their affected keys through `covers` and record them through the same after-commit path; a table key alone covers nothing. Missing announcements fail with `UnannouncedWrites` and roll back the transaction.
 
 ```ts
-const coverage = { covers: { orders: ["dashboard:orders"] } };
+const changed = [notes.item(id), notes.bucket.listId(oldList), notes.bucket.listId(newList), notes.bucket.owner(owner)];
 
 yield* withChangeCoverage(
   Effect.gen(function* () {
-    yield* sql`update orders set status = 'closed' where id = ${id}`;
-    yield* invalidateOnCommit(["dashboard:orders"]);
+    yield* sql`update notes set "listId" = ${newList} where id = ${id}`;
+    yield* invalidateOnCommit(invalidationKeys(changed));
   }),
-  coverage,
-).pipe(expectPublished(["dashboard:orders"]));
+  { covers: { notes: changed } },
+);
 ```
 
+The coverage check verifies the declarations, not the contents of arbitrary SQL. Raw writers must declare every affected record and bucket, including unchanged buckets. Transaction statistics retain writes from rolled-back savepoints, so those writes still need declarations during a coverage check.
+
 `body.pipe(expectPublished(keys))` compares the distinct published keys, regardless of order, and preserves the body's result. Put it outside the committing transaction. It observes the existing change channel and leaves delivery intact; recorded keys from rolled-back writes do not count. A mismatch fails with `PublishedKeysMismatch`, whose `expected`, `actual` and message show both key sets. The assertion happens after the body, so a mismatch does not roll back a committed write. See [automatic change delivery](https://github.com/ShivaeDev/platform/blob/main/docs/framework/changes.md) for host defaults and coverage limits.

package/dist/ChangeDeclarations.d.ts

@@ -0,0 +1,5 @@
+import { Context, Effect } from "effect";
+export declare const ChangeDeclarations: Context.Reference<{
+    declare: (table: string, keys: readonly string[], rows: number) => Effect.Effect<void>;
+}>;
+//# sourceMappingURL=ChangeDeclarations.d.ts.map

package/dist/ChangeDeclarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangeDeclarations.d.ts","sourceRoot":"","sources":["../src/ChangeDeclarations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,eAAO,MAAM,kBAAkB;aACrB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;EACU,CAAC"}

package/dist/ChangeDeclarations.js

@@ -0,0 +1,3 @@
+import { Context, Effect } from "effect";
+export const ChangeDeclarations = Context.Reference("@shivaedev/sql/ChangeDeclarations", { defaultValue: () => ({ declare: () => Effect.void }) });
+//# sourceMappingURL=ChangeDeclarations.js.map

package/dist/ChangeDeclarations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangeDeclarations.js","sourceRoot":"","sources":["../src/ChangeDeclarations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAEhD,mCAAmC,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC"}

package/dist/batchWrites.d.ts

@@ -12,5 +12,5 @@ export declare function makeInsertMany<TServices = never>(model: Model.Any, sql:
     readonly tableName: string;
     readonly spanPrefix: string;
     readonly changes: RepositoryChanges;
-}, operation: string, prepare?: (row: Readonly<Record<string, unknown>>) => Effect.Effect<Fragment, Schema.SchemaError, TServices>): (inputs: readonly unknown[]) => Effect.Effect<unknown[], Schema.SchemaError | SqlError, unknown>;
+}, operation: string, prepare?: (row: Readonly<Record<string, unknown>>) => Effect.Effect<Fragment, Schema.SchemaError, TServices>, upsert?: boolean): (inputs: readonly unknown[]) => Effect.Effect<unknown[], Schema.SchemaError | SqlError, unknown>;
 //# sourceMappingURL=batchWrites.d.ts.map