@shivaedev/sql 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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

@@ -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: [...] }` | `{ 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 +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);
 });
 ```
 
@@ -408,19 +404,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 +428,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 });
@@ -446,7 +442,6 @@ 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:
-
 - 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 +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.
@@ -487,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)`;
 });
 ```
 
@@ -501,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)),
 });
 ```
 
@@ -517,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.
 
@@ -527,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
 
@@ -536,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,
 });
 ```
 
@@ -551,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`:
@@ -581,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));
 ```
 
@@ -607,22 +602,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.
 

package/dist/transact.js

@@ -25,7 +25,7 @@ const guard = Effect.fn("Transact.guard")(function* () {
 const invalidations = makeChannel({
     name: "@shivaedev/sql/transact",
     owner: Effect.map(SqlClient.SqlClient, (sql) => sql.transactionService),
-    publish: (keys) => Reactivity.invalidate(keys),
+    publish: (keys) => Reactivity.Reactivity.use((reactivity) => Effect.sync(() => reactivity.invalidateUnsafe(keys))),
     unowned: guard(),
 });
 export const ChangeObserver = invalidations.Observer;

package/dist/transact.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/sql",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Schema-derived repositories over native Effect SQL",
   "keywords": [
     "effect"
@@ -43,23 +43,24 @@
     "README.md"
   ],
   "dependencies": {
-    "@shivaedev/changes": "0.5.0"
+    "@shivaedev/changes": "0.5.1"
   },
   "devDependencies": {
-    "@effect/platform-node": "4.0.5",
-    "@effect/sql-pg": "4.0.5",
-    "@effect/sql-sqlite-node": "4.0.5",
-    "@shivaedev/quality": "0.43.0",
-    "@shivaedev/service": "0.5.0",
-    "@shivaedev/test": "0.10.0",
-    "@shivaedev/test-story": "0.22.0",
+    "@effect/platform-node": "4.0.6",
+    "@effect/sql-pg": "4.0.6",
+    "@effect/sql-sqlite-node": "4.0.6",
+    "@shivaedev/quality": "0.45.0",
+    "@shivaedev/service": "0.5.1",
+    "@shivaedev/test": "0.10.1",
+    "@shivaedev/test-sql": "0.11.0",
+    "@shivaedev/test-story": "0.24.0",
     "@types/node": "24.19.2",
-    "effect": "4.0.5",
+    "effect": "4.0.6",
     "typescript": "7.0.2",
     "vitest": "5.0.5"
   },
   "peerDependencies": {
-    "effect": "4.0.5"
+    "effect": "4.0.6"
   },
   "engines": {
     "node": ">=24"

package/src/transact.ts

@@ -35,7 +35,7 @@ const guard = Effect.fn("Transact.guard")(function* () {
 const invalidations = makeChannel<unknown, SqlClient.SqlClient | Reactivity.Reactivity, SqlError>({
 	name: "@shivaedev/sql/transact",
 	owner: Effect.map(SqlClient.SqlClient, (sql) => sql.transactionService),
-	publish: (keys) => Reactivity.invalidate(keys),
+	publish: (keys) => Reactivity.Reactivity.use((reactivity) => Effect.sync(() => reactivity.invalidateUnsafe(keys))),
 	unowned: guard(),
 });