@ultimat3/entity 21.0.0 → 22.1.0

package/README.md

@@ -890,6 +890,15 @@ database from its boot code has decided to, and a library that overruled that wo
 `X_PRELOAD_UNKNOWN_RELATION` · `X_N_PLUS_ONE_QUERY` · `X_N_PLUS_ONE_WRITE` ·
 `X_RECORD_KEY_MISSING`
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `EntityError` | any `EntityErrorCode` — `ENTITY_ERROR_CODES` | `src/entity-error.ts` |
+
 ## Boundaries
 
 Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema` and `@ultimat3/db` only — `db` is tier 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "21.0.0",
+  "version": "22.1.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -32,9 +32,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "21.0.0",
-    "@ultimat3/db": "21.0.0",
-    "@ultimat3/schema": "21.0.0",
-    "@ultimat3/time": "21.0.0"
+    "@ultimat3/core": "22.1.0",
+    "@ultimat3/db": "22.1.0",
+    "@ultimat3/schema": "22.1.0",
+    "@ultimat3/time": "22.1.0"
   }
 }

package/src/aggregate-decode.ts

@@ -24,7 +24,8 @@ export const decodeAggregate = (fn: AggregateFn, kind: ColumnKind, text: string)
   // whatever they fit in, while `sum('likeCount')` over a million of them does not.
   if (fn === 'sum' || fn === 'avg') return text;
   if (kind === 'timestamptz') {
-    const at = new Date(text);
+    // Epoch milliseconds (`pg-sql.ts`), so no zone and no calendar is parsed here at all.
+    const at = new Date(Number(text));
     return Number.isNaN(at.getTime()) ? null : at;
   }
   if (kind === 'integer') {

package/src/columns-data.ts

@@ -47,6 +47,32 @@ export const json = <T>(schema: StandardSchemaV1<unknown, T>): Column<T> =>
 
 const DIGITS = /^-?\d+$/;
 
+/**
+ * The one spelling Postgres answers with: no leading zeros, and no `-0`. Memory stored `'007'`
+ * where Postgres returned `7`, so the same row was two values by driver. String work only — the
+ * digits never pass through a `Number`.
+ */
+const canonicalDigits = (digits: string): string => {
+  const negative = digits.startsWith('-');
+  const whole = digits.replace('-', '').replace(/^0+(?=\d)/, '');
+  return negative && whole !== '0' ? `-${whole}` : whole;
+};
+
+/**
+ * An ACCEPTED decimal in Postgres's spelling: leading zeros stripped, `-0` and `-0.00` unsigned,
+ * and a short fraction padded to the column's scale (`numeric(8, 2)` answers `7.50` for `7.5`).
+ * Never rounds — excess scale was refused above, and rounding here would widen what the column
+ * accepts. An unbounded `numeric` keeps the fraction it was given, as Postgres does.
+ */
+const canonicalDecimal = (text: string, scale: number | undefined): string => {
+  const negative = text.startsWith('-');
+  const [rawWhole = '', rawFraction = ''] = text.replace('-', '').split('.');
+  const whole = rawWhole.replace(/^0+(?=\d)/, '');
+  const fraction = scale === undefined ? rawFraction : rawFraction.padEnd(scale, '0');
+  const zero = /^0*$/.test(whole + fraction);
+  return `${negative && !zero ? '-' : ''}${whole}${fraction === '' ? '' : `.${fraction}`}`;
+};
+
 /**
  * `bigint`, whose row type is a decimal STRING. Neither alternative survives contact:
  * a JS `bigint` is what `JSON.stringify` throws on — the reason `money.minor` is a `number` — and
@@ -71,7 +97,7 @@ export const bigint = (): Column<string> =>
           );
     }
     return typeof value === 'string' && DIGITS.test(value)
-      ? value
+      ? canonicalDigits(value)
       : refuseColumn(
           'bigint',
           `expected whole digits, ${got(value)}`,
@@ -149,7 +175,7 @@ export const decimal = (options: DecimalOptions = {}): Column<string> => {
           `widen the column — decimal({ precision: ${whole + (scale ?? 0)}, scale: ${scale ?? 0} }) — and run x db gen "widen the numeric": what overflows is the digits BEFORE the point`,
         );
       }
-      return text;
+      return canonicalDecimal(text, scale);
     },
     precision === undefined || scale === undefined ? {} : { precision, numericScale: scale },
   );

package/src/columns-scalar.ts

@@ -0,0 +1,79 @@
+// Single responsibility: the three plain scalar columns — `text`, `integer`, `boolean` — each
+// refusing in `$parse` exactly what Postgres refuses at the column, so the memory driver cannot
+// store a value production answers 23514 or 22003 for. Split from `columns.ts` at its ceiling.
+
+import { charCount } from '@ultimat3/schema';
+import { column } from './column';
+import { got } from './column-values';
+import { refuseColumn } from './refuse';
+import type { Column } from './types';
+
+export interface TextOptions {
+  /** Emits `char_length(<column>) <= max`, so Postgres refuses an over-long string too. */
+  readonly max?: number;
+}
+
+export const text = (options: TextOptions = {}): Column<string> => {
+  const { max } = options;
+  // Refused where it is declared: a `NaN` or fractional max emitted `char_length(x) <= NaN` into
+  // the DDL, which Postgres refuses one migration later, far from the line that wrote it.
+  if (max !== undefined && !(Number.isSafeInteger(max) && max >= 1)) {
+    refuseColumn(
+      'length',
+      `text({ max }) must be a whole number of characters, at least 1, ${got(max)}`,
+      'text({ max: 200 }) — a whole count of characters, or text() for no bound',
+    );
+  }
+  return column<string>(
+    'text',
+    (value) => {
+      if (typeof value !== 'string') {
+        return refuseColumn(
+          'type',
+          `expected a string, ${got(value)}`,
+          'String(value) at the call site when this really is text — a number column is integer(), an exact decimal is decimal(), a structured payload is json(schema)',
+        );
+      }
+      // Code points, as `char_length` counts them: the CHECK refused an over-long value in
+      // Postgres (23514) while memory stored it, so a test passed a write production refuses.
+      if (max !== undefined && charCount(value) > max) {
+        return refuseColumn(
+          'length',
+          `expected at most ${max} characters, got ${charCount(value)}`,
+          `truncate at the call site, or widen the column — text({ max: ${charCount(value)} }) — and run x db gen "widen the text"`,
+        );
+      }
+      return value;
+    },
+    max === undefined ? {} : { length: max, check: (name) => `char_length(${name}) <= ${max}` },
+  );
+};
+
+/** Postgres `integer` is int4: a safe JS integer past this range is 22003 there. */
+const INT4_MIN = -2_147_483_648;
+const INT4_MAX = 2_147_483_647;
+
+export const integer = (): Column<number> =>
+  column<number>('integer', (value) =>
+    typeof value === 'number' &&
+    Number.isSafeInteger(value) &&
+    value >= INT4_MIN &&
+    value <= INT4_MAX
+      ? value
+      : refuseColumn(
+          'type',
+          `expected a whole number in the int4 range (${INT4_MIN}..${INT4_MAX}), ${got(value)}`,
+          'Math.trunc(value) for a float and Number(value) for a numeric string — a count past int4 is bigint(), a fractional value is decimal()',
+        ),
+  );
+
+export const boolean = (): Column<boolean> =>
+  column<boolean>('boolean', (value) =>
+    typeof value === 'boolean'
+      ? value
+      : refuseColumn(
+          'type',
+          `expected a boolean, ${got(value)}`,
+          "value === 'true' at the call site for a text flag, and boolean().nullable() when the column has a third state",
+        ),
+  );

package/src/columns.ts

@@ -6,6 +6,7 @@ import { uuid as uuidV7 } from '@ultimat3/core';
 import {
   CURRENCY_CODE_PATTERN,
   isCurrencyCode,
+  isIsoDateTime,
   isMoneyScale,
   MAX_MONEY_SCALE,
 } from '@ultimat3/schema';
@@ -85,59 +86,22 @@ const uuidWith = <T extends string>(meta: ColumnMeta): UuidColumn<T> => ({
   column: (name) => uuidWith<T>({ ...meta, name: assertColumnName(name) }),
 });
 
-export interface TextOptions {
-  /** Emits `char_length(<column>) <= max`, so Postgres refuses an over-long string too. */
-  readonly max?: number;
-}
-
-export const text = (options: TextOptions = {}): Column<string> =>
-  column<string>(
-    'text',
-    (value) =>
-      typeof value === 'string'
-        ? value
-        : refuseColumn(
-            'type',
-            `expected a string, ${got(value)}`,
-            'String(value) at the call site when this really is text — a number column is integer(), an exact decimal is decimal(), a structured payload is json(schema)',
-          ),
-    options.max === undefined
-      ? {}
-      : { length: options.max, check: (name) => `char_length(${name}) <= ${options.max}` },
-  );
-
-export const integer = (): Column<number> =>
-  column<number>('integer', (value) =>
-    typeof value === 'number' && Number.isSafeInteger(value)
-      ? value
-      : refuseColumn(
-          'type',
-          `expected a safe integer, ${got(value)}`,
-          'Math.trunc(value) for a float and Number(value) for a numeric string — a count past ±2^53 is bigint(), a fractional value is decimal()',
-        ),
-  );
-
-export const boolean = (): Column<boolean> =>
-  column<boolean>('boolean', (value) =>
-    typeof value === 'boolean'
-      ? value
-      : refuseColumn(
-          'type',
-          `expected a boolean, ${got(value)}`,
-          "value === 'true' at the call site for a text flag, and boolean().nullable() when the column has a third state",
-        ),
-  );
+export type { TextOptions } from './columns-scalar';
+export { boolean, integer, text } from './columns-scalar';
 
 const parseInstant = (value: unknown): Date => {
   if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
-  if (typeof value === 'string' || typeof value === 'number') {
+  // A string must be ISO-8601 naming its own instant (`@ultimat3/schema`'s `isIsoDateTime`):
+  // `new Date('2026-03-14T09:00')` and `new Date('March 14, 2026')` resolved through the HOST's
+  // zone on insert and seed, so one row was a different instant per container `TZ`.
+  if ((typeof value === 'string' && isIsoDateTime(value)) || typeof value === 'number') {
     const parsed = new Date(value);
     if (!Number.isNaN(parsed.getTime())) return parsed;
   }
   return refuseColumn(
     'format',
-    `expected a UTC instant, ${got(value)}`,
-    'new Date(value) at the call site — timestamp() stores an instant; a calendar date with no clock is date(), and an elapsed span is integer()',
+    `expected a UTC instant — a Date, epoch milliseconds, or an ISO-8601 string with Z or an offset — ${got(value)}`,
+    "'2026-03-14T09:00:00Z' or a Date — timestamp() stores an instant, so a string must name its zone; a calendar date with no clock is date(), and an elapsed span is integer()",
   );
 };
 
@@ -156,7 +120,12 @@ export const url = (): Column<string> =>
       if (typeof value === 'string') {
         try {
           const parsed = new URL(value);
-          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') return value;
+          // The scheme is stored in its canonical LOWER case: the CHECK is `~ '^https?://'`, so
+          // `HTTPS://a.b` was stored by memory and refused by Postgres. Only the scheme is
+          // rewritten — the rest of the URL is the caller's, byte for byte.
+          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+            return value.replace(/^https?(?=:)/i, (scheme) => scheme.toLowerCase());
+          }
         } catch {
           // fall through to the shared rejection so the error names the rule
         }

package/src/entity.ts

@@ -423,6 +423,7 @@ export const entity = <const C extends ColumnMap>(
     tableName: table,
     persist: init.persist === true,
     projection: recordProjection(core),
+    core: core as EntityCore<unknown>,
     describe,
     references,
   });

package/src/index.ts

@@ -30,7 +30,6 @@ export { CROSS_TENANT_SCOPE, crossTenant } from './cross-tenant';
 export type { Database, DatabaseOptions, Driver, EntitySet } from './database';
 export { database, defaultDriver, memoryDriver } from './database';
 export type { DescribeInput } from './describe';
-export { sqlTypeOf } from './describe';
 export type { Entity, EntityCore, EntityInit, IndexInit } from './entity';
 export { entity, SOFT_DELETE_COLUMN } from './entity';
 // The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
@@ -82,7 +81,11 @@ export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
 export { persistedRecordTypes } from './persisted-types';
 export type { PostgresDriverOptions } from './pg-driver';
-export { postgresDriver, postgresRepo, postgresTransactor } from './pg-driver';
+export { postgresDriver, postgresRepo } from './pg-driver';
+// For a change feed holding a table name and raw columns: `entityForTable` + `decodeRow` is the row
+// the app declared, money and all. Exported for `@ultimat3/realtime` (plan 101, 06 i).
+export { decodeRow } from './pg-row';
+export { postgresTransactor } from './pg-transactor';
 // The two page bounds, beside `N_PLUS_ONE_THRESHOLD` and for the same reason: an app validating
 // its own `pageSize` input against a hardcoded 10_000 is a second declaration of one number.
 export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from './plan';
@@ -106,6 +109,7 @@ export type {
 export {
   clearRegistry,
   describeEntities,
+  entityForTable,
   entityNames,
   getEntity,
   registerEntity,
@@ -138,9 +142,7 @@ export {
   isSearchLanguage,
   isSearchWeight,
   SEARCH_LANGUAGES,
-  SEARCH_PROPERTY,
   SEARCH_WEIGHTS,
-  searchExpression,
 } from './search';
 export type {
   Seed,
@@ -168,14 +170,9 @@ export type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './t
 export {
   assertRowTenant,
   assertScoped,
-  describePlan,
-  emptyPlan,
-  hasOrgPredicate,
-  isOrgScoped,
   ORG_COLUMN,
   orgScoped,
   scopedPlan,
-  tenantColumnOf,
 } from './tenancy';
 export type { Move } from './transition';
 export type {

package/src/jit-preload.ts

@@ -235,6 +235,24 @@ const preload = <Row>(read: PointRead<Row>, bucket: Bucket, ids: readonly unknow
   void fill(read, wanted, settlers);
 };
 
+/**
+ * The ids a bucket can KEEP, from the one asked for onward. The bucket holds `MAX_SIBLING_KEYS`
+ * rows, so preloading a wider page read every id and then evicted the oldest — measured, 2,500
+ * ids read to keep 2,000. A sequential loop walks forward, so the window starts at this lookup.
+ */
+const keptWindow = <Row>(
+  read: PointRead<Row>,
+  ids: readonly unknown[],
+  filedAt: string,
+): readonly unknown[] => {
+  if (ids.length <= MAX_SIBLING_KEYS) return ids;
+  const start = Math.max(
+    0,
+    ids.findIndex((id) => keyOf(read.key.kind, id) === filedAt),
+  );
+  return ids.slice(start, start + MAX_SIBLING_KEYS);
+};
+
 const answered = <Row>(answer: Promise<Answer>): Promise<Row | null> =>
   answer.then((settled) =>
     'error' in settled ? Promise.reject(settled.error) : (settled.row as Row | null),
@@ -266,7 +284,7 @@ export const preloadedFindById = <Row>(
     rows: new Map<string, Promise<Answer>>(),
   };
   store.preloaded.set(scope, target);
-  preload(read, target, ids);
+  preload(read, target, keptWindow(read, ids, filedAt));
   const answer = target.rows.get(filedAt);
   return answer === undefined ? undefined : answered<Row>(answer);
 };

package/src/memory-repo.ts

@@ -18,6 +18,7 @@ import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { notFound } from './errors';
 import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
 import { compareByKind, matchesPredicate } from './memory-match';
+import { uniqueClash, uniqueViolation } from './memory-unique';
 import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions, Transactor, Tx } from './repo';
 import type { QueryPlan } from './tenancy';
@@ -69,6 +70,14 @@ const afterCursor = <Row>(
  * migration and tests use it everywhere. Postgres is the production driver and implements
  * this same interface.
  */
+/**
+ * The patch with every `undefined` property dropped — `bindValues` skips them in Postgres, so a
+ * patch built from optional input (`{ body: input.body }`) leaves the column alone in both drivers
+ * rather than erasing it. `null` is the value that clears a column.
+ */
+const defined = (patch: object): object =>
+  Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));
+
 export const memoryRepo = <Row>(
   entity: EntityCore<Row>,
   seed: readonly Row[] = [],
@@ -119,10 +128,16 @@ export const memoryRepo = <Row>(
   const narrowed = (batch: readonly RowWrite<Row>[]): readonly Row[] =>
     batch.map((row) => narrowRow<Row>(entity.$columns, row));
 
+  /**
+   * `from` is the key the row is stored under NOW, or `undefined` for a new row. A new row may not
+   * land on a stored key, and a moved one may not land on another row's — Postgres answers both
+   * `X_DB_UNIQUE_VIOLATION` — and a moved row leaves its old key, where this map used to keep it.
+   */
   const write = (
     given: RowWrite<Row>,
     options: RepoOptions | undefined,
     operation: string,
+    from?: string,
   ): Row => {
     // `MoneyInput` lets a writer hand a `bigint`; a stored row holds the value type. The Postgres
     // driver narrows at the same position — its write methods' entry — so without this an
@@ -135,11 +150,21 @@ export const memoryRepo = <Row>(
     assertRowTenant(entity.$name, entity.$tenantColumn, operation, row);
     entity.$assert(row);
     const key = storeKey(row);
+    if (key !== from && rows.has(key)) throw uniqueViolation(entity, `${entity.$table}_pkey`);
+    const clash = uniqueClash(
+      entity,
+      row,
+      [...rows.entries()].filter(([stored]) => stored !== from).map(([, other]) => other),
+    );
+    if (clash !== undefined) throw uniqueViolation(entity, clash);
+    const moved = from !== undefined && from !== key ? rows.get(from) : undefined;
     const previous = rows.get(key);
     options?.tx?.onRollback(() => {
       if (previous === undefined) rows.delete(key);
       else rows.set(key, previous);
+      if (from !== undefined && moved !== undefined) rows.set(from, moved);
     });
+    if (moved !== undefined && from !== undefined) rows.delete(from);
     rows.set(key, row);
     return row;
   };
@@ -203,9 +228,18 @@ export const memoryRepo = <Row>(
       // Narrowed FIRST, so what this loop judges is what `write` will store: `$assert` was handed
       // the caller's `bigint` minor unit here and the narrowed `number` one call later.
       const batch = narrowed(given);
-      for (const row of batch) {
+      const seen = new Set<string>();
+      for (const [position, row] of batch.entries()) {
         assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);
         entity.$assert(row);
+        // Keys too, before any row lands: one duplicate refuses the whole statement in Postgres.
+        const key = storeKey(row);
+        if (seen.has(key) || rows.has(key)) {
+          throw uniqueViolation(entity, `${entity.$table}_pkey`);
+        }
+        seen.add(key);
+        const clash = uniqueClash(entity, row, [...rows.values(), ...batch.slice(0, position)]);
+        if (clash !== undefined) throw uniqueViolation(entity, clash);
       }
       return batch.map((row) => write(row, options, 'insertAll'));
     },
@@ -248,7 +282,12 @@ export const memoryRepo = <Row>(
               );
         // `UpsertArgs extends RepoOptions`, so the args ARE the options — one bag, and a `tx`
         // passed to an upsert registers its undo exactly as it does for every other write here.
-        const result = write(merged, args, 'upsertAll');
+        const result = write(
+          merged,
+          args,
+          'upsertAll',
+          existing === undefined ? undefined : storeKey(existing),
+        );
         // Filed as it lands, so a later row of the same batch collides with an earlier one exactly
         // as it would with a row the request stored a moment before it.
         if (key !== undefined) stored.set(key, result);
@@ -258,14 +297,25 @@ export const memoryRepo = <Row>(
     },
 
     async update(id, patch, options) {
-      return write(Object.assign({}, addressed(id, options, 'update'), patch), options, 'update');
+      const current = addressed(id, options, 'update');
+      return write(
+        Object.assign({}, current, defined(patch)),
+        options,
+        'update',
+        storeKey(current),
+      );
     },
 
     async delete(id, options) {
       const current = addressed(id, options, 'delete');
       // Soft delete hides the row without losing it; the column's presence is the switch.
       if (entity.$softDelete) {
-        write(Object.assign({}, current, { [SOFT_DELETE_COLUMN]: entityNow() }), options, 'delete');
+        write(
+          Object.assign({}, current, { [SOFT_DELETE_COLUMN]: entityNow() }),
+          options,
+          'delete',
+          storeKey(current),
+        );
         return;
       }
       const key = storeKey(current);
@@ -285,6 +335,7 @@ export const memoryRepo = <Row>(
             Object.assign({}, row, { [SOFT_DELETE_COLUMN]: entityNow() }),
             options,
             'deleteWhere',
+            storeKey(row),
           );
           continue;
         }
@@ -316,7 +367,8 @@ export const memoryRepo = <Row>(
       if (hasJsOnlyInvariant(entity.$invariants) && found.length > MAX_ASSERTED_ROWS) {
         throw assertedRowsTooMany(entity.$name, 'updateWhere', found.length);
       }
-      for (const row of found) write(Object.assign({}, row, patch), options, 'updateWhere');
+      for (const row of found)
+        write(Object.assign({}, row, defined(patch)), options, 'updateWhere', storeKey(row));
       return found.length;
     },
 
@@ -370,13 +422,28 @@ let txCounter = 0;
 export const memoryTransactor = (): Transactor => ({
   async run(work) {
     const undos: (() => void)[] = [];
+    const commits: (() => void)[] = [];
     txCounter += 1;
-    const tx: Tx = { id: `tx-${txCounter}`, onRollback: (undo) => undos.push(undo) };
+    const tx: Tx = {
+      id: `tx-${txCounter}`,
+      onRollback: (undo) => undos.push(undo),
+      onCommit: (effect) => commits.push(effect),
+    };
+    let result: Awaited<ReturnType<typeof work>>;
     try {
-      return await work(tx);
+      result = await work(tx);
     } catch (error) {
       for (const undo of undos.reverse()) undo();
       throw error;
     }
+    // After the work succeeded — the memory "commit" — and best-effort, as `@ultimat3/db` runs them.
+    for (const effect of commits) {
+      try {
+        effect();
+      } catch {
+        // an effect is a report about a durable write; it may not fail the write
+      }
+    }
+    return result;
   },
 });

package/src/memory-unique.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the uniqueness Postgres enforces, enforced by the in-memory driver too —
+// the primary key and every non-partial `unique` index. Memory silently REPLACED a row on a
+// duplicate key and ignored `unique()` entirely, so a signup race that is a 409 in production was
+// a quiet overwrite under `x dev` and in every app test.
+
+import { driverError } from '@ultimat3/db';
+import type { EntityCore } from './entity';
+import { bindValues } from './pg-row';
+import type { RowPatch } from './types';
+
+/** The refusal Postgres answers `23505` with, in the shape `driverError` gives it there. */
+export const uniqueViolation = (entity: EntityCore, constraint: string): Error =>
+  driverError(`memory write into ${entity.$table}`, {
+    code: '23505',
+    constraint,
+    message: `duplicate key value violates unique constraint "${constraint}"`,
+  });
+
+/** A value as a comparable token; `null` answers `undefined` — NULLS DISTINCT, as Postgres. */
+const cellOf = (value: unknown): string | undefined => {
+  if (value === null || value === undefined) return undefined;
+  if (value instanceof Date) return `date:${value.getTime()}`;
+  if (typeof value === 'string') return `s:${value}`;
+  return `${typeof value}:${JSON.stringify(value)}`;
+};
+
+/**
+ * The first unique index `candidate` collides with among `others`, or `undefined`. Partial indexes
+ * are skipped: their predicate is SQL this driver cannot evaluate, and a guess would refuse rows
+ * Postgres accepts — the one direction that must never happen.
+ */
+export const uniqueClash = <Row>(
+  entity: EntityCore<Row>,
+  candidate: Row,
+  others: Iterable<Row>,
+): string | undefined => {
+  const unique = entity.$indexes.filter((index) => index.unique && index.where === undefined);
+  if (unique.length === 0) return undefined;
+  const bound = (row: Row) => bindValues(entity, row as unknown as RowPatch<Row>);
+  const incoming = bound(candidate);
+  for (const index of unique) {
+    const key = index.columns.map((name) => cellOf(incoming.get(name)));
+    if (key.some((part) => part === undefined)) continue;
+    for (const other of others) {
+      const stored = bound(other);
+      if (index.columns.every((name, at) => cellOf(stored.get(name)) === key[at]))
+        return index.name;
+    }
+  }
+  return undefined;
+};

package/src/pg-driver.ts

@@ -12,9 +12,7 @@ import {
   type DbClient,
   db,
   type SqlFragment,
-  type TransactionOptions,
   withStatementAttribution,
-  withTransaction,
 } from '@ultimat3/db';
 import { aggregateColumnOf, aggregateMinor, assertOneUnit } from './aggregate';
 import { decodeAggregate } from './aggregate-decode';
@@ -37,18 +35,16 @@ import { notFound, repoClientPinned } from './errors';
 import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
 import { forgetPreloaded, tagSiblings } from './jit-preload';
 import { bindValues, decodeRow, type PhysicalRow, physicalName, sortPrecision } from './pg-row';
+import { countStatement, type ReadShape, selectStatement } from './pg-sql';
 import {
   type AggregateRow,
   aggregateStatement,
   countByStatement,
-  countStatement,
   currenciesStatement,
   estimateStatement,
   type GroupRow,
   type MoneyUnitRow,
-  type ReadShape,
-  selectStatement,
-} from './pg-sql';
+} from './pg-sql-aggregate';
 import {
   type ConflictTarget,
   deleteStatement,
@@ -56,7 +52,7 @@ import {
   updateStatement,
 } from './pg-write-sql';
 import { deletePlan, idPlan, readPlan, updatePlan } from './plan';
-import type { FindManyArgs, Repo, Transactor, UpsertArgs } from './repo';
+import type { FindManyArgs, Repo, UpsertArgs } from './repo';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
 import type { RowWrite } from './types';
@@ -484,16 +480,3 @@ export const postgresRepo = <Row>(
 export const postgresDriver = (config: PostgresDriverOptions = {}): Driver => ({
   repo: <Row>(entity: EntityCore<Row>) => postgresRepo(entity, config),
 });
-
-/**
- * A real Postgres transaction behind the same `Transactor` the in-memory one implements. The
- * `Tx` handed to the callback is a token: repositories find the transaction through `db()`, so
- * nothing has to thread a connection through the call stack.
- */
-export const postgresTransactor = (options: TransactionOptions = {}): Transactor => ({
-  run: (work) =>
-    withTransaction(
-      (tx) => work({ id: tx.id, onRollback: (undo: () => void) => tx.onRollback(undo) }),
-      options,
-    ),
-});

package/src/pg-row.ts

@@ -72,7 +72,10 @@ export const allColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
 
 /**
  * Row (or patch) -> the columns to write. Absent properties are skipped rather than nulled,
- * which is what makes the same function serve `insert` and a partial `update`.
+ * which is what makes the same function serve `insert` and a partial `update` — and a property
+ * PRESENT with the value `undefined` is absent too, as `namedColumns` already reads it. The common
+ * patch is built from optional action input (`{ body: input.body }`), and binding that `undefined`
+ * as NULL wiped the column the caller never meant to touch. NULL is written only for `null`.
  */
 export const bindValues = <Row>(
   entity: EntityCore<Row>,
@@ -85,6 +88,7 @@ export const bindValues = <Row>(
   for (const [property, column] of Object.entries(entity.$columns)) {
     if (!Object.hasOwn(record, property)) continue;
     const value = record[property];
+    if (value === undefined) continue;
     if (column.$meta.kind !== 'money') {
       bound.set(columnName(property, column.$meta), bindable(column, value));
       continue;