@ultimat3/entity 20.2.1 → 22.0.0

package/src/errors.ts

@@ -1,102 +1,20 @@
 // The entity layer's stable error codes. Each factory produces the exact command
 // that fixes the situation — `X_DB_DRIFT` is the flagship: it names the table, the
-// column and the generator invocation.
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+// column and the generator invocation. The code registry, the class, `invariantViolated` and
+// `entityDuplicate` live in `entity-error.ts`, which imports no `@ultimat3/db`; re-exported here.
 import { shellInertIdentifier } from '@ultimat3/db';
+import { EntityError } from './entity-error';
 
-/** Codes this package declares and owns. */
-export const ENTITY_OWNED_ERROR_CODES = [
-  'X_ENTITY_DUPLICATE',
-  'X_INVARIANT_VIOLATED',
-  'X_TENANCY_UNSCOPED',
-  'X_TENANCY_ACTOR_MISMATCH',
-  'X_TENANCY_ACTOR_ORG_REQUIRED',
-  'X_TENANCY_CROSS_DENIED',
-  'X_NOT_FOUND',
-  'X_WRITE_UNFILTERED',
-  'X_PATCH_EMPTY',
-  'X_PRELOAD_UNKNOWN_RELATION',
-  'X_N_PLUS_ONE_QUERY',
-  'X_N_PLUS_ONE_WRITE',
-  'X_REPO_CLIENT_PINNED',
-  'X_AGGREGATE_UNSUPPORTED',
-  'X_AGGREGATE_MIXED_CURRENCY',
-  'X_APPROXIMATE_COUNT_FILTERED',
-  'X_SEARCH_UNDECLARED',
-  'X_SEARCH_IN_MEMORY',
-  'X_STATE_UNDECLARED',
-  'X_STATE_TRANSITION_ILLEGAL',
-  'X_STATE_CONFLICT',
-] as const;
-
-/**
- * `X_DB_DRIFT` is `@ultimat3/db`'s — drift is a fact about migrations, and this package imports db
- * rather than the other way round. `dbDrift()` below throws it; nothing here titles it, because a
- * second copy of the title is what lets the two packages disagree about what the code means.
- */
-export const ENTITY_BORROWED_ERROR_CODES = ['X_DB_DRIFT'] as const;
-
-/** Every code entity can throw: the ones it owns plus the one it borrows. */
-export const ENTITY_ERROR_CODES = [
-  ...ENTITY_OWNED_ERROR_CODES,
-  ...ENTITY_BORROWED_ERROR_CODES,
-] as const;
-
-export type EntityOwnedErrorCode = (typeof ENTITY_OWNED_ERROR_CODES)[number];
-export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
-
-export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>> = {
-  X_ENTITY_DUPLICATE: 'two entities claim the same name',
-  X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
-  X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
-  // "call", not "query": the same code covers a predicate that names another tenant and a row or
-  // patch that writes one, because they are one mistake made in two places.
-  X_TENANCY_ACTOR_MISMATCH: "a call named a tenant other than the actor's",
-  X_TENANCY_ACTOR_ORG_REQUIRED: 'the acting actor carries no tenant',
-  X_TENANCY_CROSS_DENIED: 'a cross-tenant read was entered without the capability',
-  X_NOT_FOUND: 'no row for that id',
-  X_WRITE_UNFILTERED: 'a filtered write named no filter columns',
-  X_PATCH_EMPTY: 'a filtered update named no columns to write',
-  X_PRELOAD_UNKNOWN_RELATION: 'no relation of that name on this entity',
-  X_N_PLUS_ONE_QUERY: 'a read repeated once per row',
-  X_N_PLUS_ONE_WRITE: 'a write repeated once per row',
-  X_REPO_CLIENT_PINNED: 'a repository pinned to its own client cannot join the open transaction',
-  X_AGGREGATE_UNSUPPORTED: 'that column has no aggregate both drivers can answer alike',
-  X_AGGREGATE_MIXED_CURRENCY: 'an amount was aggregated across currencies',
-  X_APPROXIMATE_COUNT_FILTERED: 'an estimate was asked of a filtered chain',
-  X_SEARCH_UNDECLARED: 'this entity has no searchable column',
-  X_SEARCH_IN_MEMORY: 'the in-memory driver cannot answer a full-text match',
-  X_STATE_UNDECLARED: 'that column declares no state machine',
-  X_STATE_TRANSITION_ILLEGAL: 'the machine has no such transition',
-  X_STATE_CONFLICT: 'the row is no longer in the state this transition named',
-};
-
-// Registered at module load, unconditionally, in one call. Without this the registry humanises the
-// code and every surface renders a title this package never wrote; with a presence guard, a second
-// package claiming one of these codes would silently win instead of throwing X_ERROR_CODE_DUPLICATE.
-registerErrorCodes(
-  Object.fromEntries(Object.entries(ENTITY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
-);
-
-/**
- * Base for every error this package throws. No `docs:` — `UltimateError` fills it from
- * `describeErrorCode(code).docs`, which is `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every
- * code, never one per code, because `wiki/` is the framework's only public documentation surface
- * and a code lives there in a TABLE ROW, which has no anchor. The
- * `https://ultimate.dev/errors/<code>` links this class built until 9.x answered 404, host
- * included, on every refusal it has ever raised.
- */
-export class EntityError extends UltimateError {
-  override readonly name = 'EntityError';
-
-  constructor(init: { code: EntityErrorCode; cause: string; fix: string }) {
-    super({
-      code: init.code,
-      cause: init.cause,
-      fix: init.fix,
-    });
-  }
-}
+export type { EntityErrorCode, EntityOwnedErrorCode } from './entity-error';
+export {
+  ENTITY_BORROWED_ERROR_CODES,
+  ENTITY_ERROR_CODES,
+  ENTITY_ERROR_TITLES,
+  ENTITY_OWNED_ERROR_CODES,
+  EntityError,
+  entityDuplicate,
+  invariantViolated,
+} from './entity-error';
 
 /**
  * A value from an app, rendered for a `cause` — and it may not throw, whatever the app put there.
@@ -130,31 +48,6 @@ const renderValue = (value: unknown): string => {
 const asLiteral = (value: unknown, placeholder: string): string =>
   typeof value === 'string' ? JSON.stringify(value) : placeholder;
 
-export const entityDuplicate = (name: string, existingTable: string): EntityError =>
-  new EntityError({
-    code: 'X_ENTITY_DUPLICATE',
-    cause: `entity "${name}" is already registered for table "${existingTable}"`,
-    fix: `x entities list --json   # then rename one of the two entity({ name }) declarations`,
-  });
-
-/**
- * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
- * given. A literal is an entity that does not exist, and this fix then hands the reader
- * `x entities describe column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
- * refusal raised before any entity exists belongs in `refuse.ts`, where the caller supplies the
- * edit; `refuse.test.ts` fails on a literal here.
- */
-export const invariantViolated = (
-  entityName: string,
-  invariantName: string,
-  message: string,
-): EntityError =>
-  new EntityError({
-    code: 'X_INVARIANT_VIOLATED',
-    cause: `${entityName}.${invariantName}: ${message}`,
-    fix: `x entities describe ${entityName} --json   # shows the invariant and its SQL CHECK`,
-  });
-
 /**
  * One code, two situations, and they do not share a repair — so the cause and the fix branch on
  * which one it is rather than one wording claiming the other's facts.

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
@@ -80,14 +79,25 @@ export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
 export { memoryRepo, memoryTransactor } from './memory-repo';
 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';
 export type { RelatedTable, RelatedTables } from './preload';
 export type { Preloaded, ReadBuilder, Table } from './query';
 export { tableFor } from './query';
+// The client projection of an entity (plan 101): record type, record key, and the brand on
+// `$schema` that lets an action or query derive its record envelope from its output schema.
+// Value-light — no Postgres driver behind any of them — so a browser store may import them here.
+export type { ProjectedEntity, RecordProjection } from './record-projection';
+export { ENTITY_BRAND, recordProjection } from './record-projection';
+export { recordProjectionForTable, recordTypeForTable } from './record-table';
 export type {
   ColumnDescription,
   EntityDescription,
@@ -99,6 +109,7 @@ export type {
 export {
   clearRegistry,
   describeEntities,
+  entityForTable,
   entityNames,
   getEntity,
   registerEntity,
@@ -119,6 +130,8 @@ export type {
 } from './repo';
 export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-observer';
 export { observedRepo, rowObserver, setRowObserver } from './row-observer';
+export type { RecordsByKey, RecordsByType } from './rows-of';
+export { hasEntityRows, projectionsIn, rowsOf } from './rows-of';
 // Full-text search. The LANGUAGE set and the weights are values an app reads to build a form;
 // `SEARCH_PROPERTY` is what a `matches` predicate names, which a hand-built `QueryPlan` needs.
 export type { SearchInit, SearchLanguage, SearchSource, SearchVector } from './search';
@@ -129,9 +142,7 @@ export {
   isSearchLanguage,
   isSearchWeight,
   SEARCH_LANGUAGES,
-  SEARCH_PROPERTY,
   SEARCH_WEIGHTS,
-  searchExpression,
 } from './search';
 export type {
   Seed,
@@ -159,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/persisted-types.ts

@@ -0,0 +1,21 @@
+// The record types the client keeps on disk — every registered entity declared `persist: true`,
+// by name, sorted. What the server renders as `<meta name="ultimate-persist">`, since the browser
+// holds no entity declarations. Memoised against the registry's generation, like `record-table.ts`.
+
+import { registeredEntities, registryGeneration } from './registry';
+
+let cached: { readonly generation: number; readonly types: readonly string[] } | null = null;
+
+/** Sorted, so the rendered meta is byte-identical for one set of declarations. */
+export const persistedRecordTypes = (): readonly string[] => {
+  const generation = registryGeneration();
+  if (cached !== null && cached.generation === generation) return cached.types;
+  const types = Object.freeze(
+    registeredEntities()
+      .filter((entry) => entry.persist === true)
+      .map((entry) => entry.name)
+      .sort(),
+  );
+  cached = { generation, types };
+  return types;
+};

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,10 +52,11 @@ 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';
+import { taggedWrite } from './write-tag';
 
 export interface PostgresDriverOptions {
   /**
@@ -156,14 +153,14 @@ export const postgresRepo = <Row>(
       : deleteStatement(entity, plan);
 
   /**
-   * Every write goes out through here, which makes it the ONE place the request's preloaded rows
-   * are dropped: a row this statement changes must not be served afterwards from a page read
-   * before it. Before the statement, not after — a row read back afterwards is the row this write
-   * left, and one read concurrently with it was concurrent either way.
+   * Every write goes out through here: the ONE place the request's preloaded rows are dropped (a
+   * row this statement changes must not be served afterwards from a page read before it — so
+   * before the statement, not after), and where a keyed request's write names itself in the WAL
+   * (`write-tag.ts`).
    */
   const writing = <T>(send: () => Promise<T>): Promise<T> => {
     forgetPreloaded(entity.$name);
-    return send();
+    return taggedWrite(config.client !== undefined, send);
   };
 
   /**
@@ -483,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;