@ultimat3/entity 1.1.0 → 2.0.0

package/src/pg-driver.ts

@@ -7,24 +7,48 @@
 // being told — which is how `ctx.jobs.enqueue()` lands its outbox row atomically with the write
 // that caused it. `RepoOptions.tx` is the in-memory driver's undo hook and is ignored here.
 
-import { type DbClient, db, type TransactionOptions, withTransaction } from '@ultimat3/db';
+import { systemClock } from '@ultimat3/core';
+import {
+  currentTx,
+  type DbClient,
+  db,
+  type SqlFragment,
+  type TransactionOptions,
+  withStatementAttribution,
+  withTransaction,
+} from '@ultimat3/db';
+import {
+  conflictKeys,
+  insertChunks,
+  insertColumns,
+  namedProperties,
+  upsertPlan,
+} from './bulk-write';
+import { coalesceFindById } from './coalesce';
 import { snake } from './column';
+import { countsFrom, groupColumnOf, groupValue, MAX_GROUPS } from './count-by';
 import { cursorFor, seekFrom, valueAt } from './cursor';
 import type { Driver } from './database';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
-import { notFound } from './errors';
+import { notFound, repoClientPinned } from './errors';
+import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
+import { forgetPreloaded, tagSiblings } from './jit-preload';
 import { bindValues, decodeRow, type PhysicalRow } from './pg-row';
 import {
+  type ConflictTarget,
+  countByStatement,
   countStatement,
   deleteStatement,
+  type GroupRow,
   insertStatement,
   type ReadShape,
   selectStatement,
   updateStatement,
 } from './pg-sql';
-import { idPlan, readPlan } from './plan';
-import type { FindManyArgs, Repo, Transactor } from './repo';
+import { deletePlan, idPlan, readPlan, updatePlan } from './plan';
+import type { FindManyArgs, Repo, Transactor, UpsertArgs } from './repo';
 import type { QueryPlan } from './tenancy';
+import { assertRowTenant } from './tenancy';
 
 export interface PostgresDriverOptions {
   /**
@@ -33,6 +57,12 @@ export interface PostgresDriverOptions {
    * globally with `setDbClient()`.
    */
   readonly client?: DbClient | undefined;
+  /**
+   * Preload foreign keys resolved by a page into a request-scoped cache, so the first
+   * `findById` for any one of them resolves that key for the whole page in one statement.
+   * Default: true.
+   */
+  readonly jitPreload?: boolean | undefined;
 }
 
 const shapeOf = (args: FindManyArgs, seek?: readonly unknown[]): ReadShape => ({
@@ -44,7 +74,41 @@ export const postgresRepo = <Row>(
   entity: EntityCore<Row>,
   config: PostgresDriverOptions = {},
 ): Repo<Row> => {
-  const client = (): DbClient => config.client ?? db();
+  /**
+   * The one place a connection is chosen, which is why the transaction guard is here and not on
+   * each method. Unpinned, `db()` answers with the open transaction when there is one — that is
+   * how a repository call inside `withTransaction` joins it without being told. Pinned, it cannot:
+   * `withTransaction` ran `BEGIN` on a connection IT reserved, and a statement sent straight to
+   * `config.client` takes a different connection out of the pool, so the write commits whatever
+   * the transaction decides and the read cannot see what the transaction has written. Refused
+   * rather than resolved — a `DbTx` does not name the client it was opened on, so this layer
+   * cannot even tell whether the two are the same database.
+   */
+  const client = (): DbClient => {
+    const pinned = config.client;
+    if (pinned === undefined) return db();
+    if (currentTx() !== undefined) throw repoClientPinned(entity.$name);
+    return pinned;
+  };
+
+  /**
+   * Every statement a repository call sends carries the entity and the operation that compiled it,
+   * which is what turns "50× `select … where "id" = $1`" into "50× `findById` on `members`" in a
+   * diagnostic. This is the last frame that knows both: below it there is only SQL.
+   *
+   * It wraps the whole call rather than the `client()` handle because the statement is often sent
+   * well below — inside the coalescer's microtask flush, inside a chunked write, inside the
+   * preload's `readByIds` — and threading a parameter through all of them is the same fact written
+   * five times. The scope is an `AsyncLocalStorage` in `@ultimat3/db` (tier 1, downward), so it
+   * survives every one of those awaits, and with no observer installed it is not entered at all:
+   * one property read and one branch on the production path (axiom 6).
+   *
+   * `op` is the string the plan builder was already given, named once per method so the operation
+   * a refusal reports and the operation a diagnostic reports cannot drift.
+   */
+  const attributed = <T>(op: string, send: () => Promise<T>): Promise<T> =>
+    withStatementAttribution(entity.$name, op, send);
+
   const idOf = (row: Row): string =>
     entity.$primaryKey.map((property) => String(valueAt(row, property))).join('');
 
@@ -55,20 +119,112 @@ export const postgresRepo = <Row>(
     return found === undefined ? null : decodeRow(entity, found);
   };
 
+  /**
+   * Hard or soft, decided once so `delete(id)` and `deleteWhere(filter)` cannot drift apart. Soft
+   * delete hides the row without losing it; the column's presence is the switch, and `shapeOf({})`
+   * keeps the `deleted_at is null` clause so a second call cannot move an existing stamp forward.
+   *
+   * No `returning`: both callers send this through `execute()` and read a count, so the rows would
+   * be a whole tenant's table crossing the wire for nobody — the same cost `updateWhere` used to
+   * pay unconditionally, on the sibling path that looked like the one doing it right.
+   */
+  const removal = (plan: QueryPlan): SqlFragment =>
+    entity.$softDelete
+      ? updateStatement(
+          entity,
+          plan,
+          new Map([[snake(SOFT_DELETE_COLUMN), systemClock.now()]]),
+          shapeOf({}),
+          false,
+        )
+      : 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.
+   */
+  const writing = <T>(send: () => Promise<T>): Promise<T> => {
+    forgetPreloaded(entity.$name);
+    return send();
+  };
+
+  /**
+   * The one insert path, for one row or ten thousand: the batch's own column list, split into as
+   * many statements as Postgres's bind count allows, and the rows the server stored. `insert(row)`
+   * comes through here too, so there is no second builder for the two to drift apart in — and a
+   * batch wide enough to split is several statements, which is why an all-or-nothing caller wraps
+   * the call in `withTransaction` rather than trusting one statement's atomicity.
+   */
+  const writeRows = async (
+    op: string,
+    batch: readonly Row[],
+    conflict: ConflictTarget | undefined,
+  ): Promise<readonly Row[]> => {
+    if (batch.length === 0) return [];
+    // The whole batch is judged before any statement exists, tenant and invariants together, in
+    // the same loop and for the same reason: Postgres refuses one statement as one, so a row this
+    // actor may not write must stop the rows beside it too. `memoryRepo`'s `write` runs the same
+    // pair — an insert builds no read plan, so this is the only place the tenant is checked.
+    for (const row of batch) {
+      assertRowTenant(entity.$name, entity.$tenantColumn, op, row);
+      entity.$assert(row);
+    }
+    const columns = insertColumns(entity, namedProperties(entity, batch));
+    const bound = batch.map((row) => bindValues(entity, row));
+    const shape = { columns, ...(conflict === undefined ? {} : { conflict }) };
+    const written: Row[] = [];
+    // Attributed here rather than in each of the three callers: a batch wide enough to split is
+    // several statements sent inside this loop, and every one of them belongs to the call that
+    // asked for it — `insert`, `insertAll` or `upsertAll`, which is why the op is a parameter.
+    await attributed(op, () =>
+      writing(async () => {
+        for (const chunk of insertChunks(bound, columns.length)) {
+          for (const row of await client().query<PhysicalRow>(
+            insertStatement(entity, chunk, shape),
+          )) {
+            written.push(decodeRow(entity, row));
+          }
+        }
+      }),
+    );
+    return written;
+  };
+
   return {
     async findById(id, options) {
-      const plan = idPlan(entity, id, options, 'findById');
-      return one(plan, options ?? {});
+      const op = 'findById';
+      const plan = idPlan(entity, id, options, op);
+      const args = options ?? {};
+      // Every point lookup a request issues in one microtask is one statement: a page that
+      // resolves an author per row pays for one round trip, not one per row. The statement is the
+      // one this call would have sent — same scope, same soft-delete filter, `in` instead of `=` —
+      // and with no request in scope (a job, a script) it is exactly that statement, alone.
+      //
+      // The batch is flushed from a microtask scheduled inside this scope, so the statement one
+      // lookup sends for fifty carries the pair every one of those fifty would have carried.
+      return attributed(
+        op,
+        () => coalesceFindById(entity, client(), plan, shapeOf(args), id) ?? one(plan, args),
+      );
     },
 
     async findMany(args = {}) {
-      const plan = readPlan(entity, args, 'findMany');
+      const op = 'findMany';
+      const plan = readPlan(entity, args, op);
       // One row past the page: the presence of that row is what says there is a next cursor,
       // and it costs one row instead of a second `count(*)` over the same predicate.
-      const found = await client().query<PhysicalRow>(
-        selectStatement(entity, plan, shapeOf(args, seekFrom(entity, plan)), plan.limit + 1),
+      const found = await attributed(op, () =>
+        client().query<PhysicalRow>(
+          selectStatement(entity, plan, shapeOf(args, seekFrom(entity, plan)), plan.limit + 1),
+        ),
       );
       const rows = found.slice(0, plan.limit).map((row) => decodeRow(entity, row));
+      // What the page leaves behind: its foreign key values, so the first `findById` for any one
+      // of them resolves the key for the whole page. A `for … of` loop over these rows costs one
+      // statement, not one per row — its `await` already ended the coalescing window.
+      if (config.jitPreload !== false) tagSiblings(entity, rows);
       const last = rows.at(-1);
       return {
         rows,
@@ -80,24 +236,47 @@ export const postgresRepo = <Row>(
     },
 
     async insert(values) {
-      entity.$assert(values);
-      const written = await client().one<PhysicalRow>(
-        insertStatement(entity, bindValues(entity, values)),
-      );
+      const [written] = await writeRows('insert', [values], undefined);
       // `returning *` is the row Postgres actually stored, defaults included.
-      return written === null ? values : decodeRow(entity, written);
+      return written ?? values;
+    },
+
+    async insertAll(batch) {
+      return writeRows('insertAll', batch, undefined);
+    },
+
+    async upsertAll(batch, args: UpsertArgs<Row>) {
+      const plan = upsertPlan(entity, batch, args.onConflict, args.onMatch ?? 'update');
+      // Refused here, not by the server: a batch that repeats a conflict target is `21000` in
+      // Postgres and a silent overwrite in memory, and the two drivers have to mean one thing.
+      conflictKeys(entity, plan, batch);
+      return writeRows('upsertAll', batch, {
+        columns: insertColumns(entity, plan.on),
+        set: insertColumns(entity, plan.set),
+      });
     },
 
     async update(id, patch, options) {
-      const plan = idPlan(entity, id, options, 'update');
+      const op = 'update';
+      const plan = idPlan(entity, id, options, op);
+      // The plan bounds WHICH row is written; the patch decides what it becomes, and a patch
+      // naming another tenant would hand this row away — a leak out of the actor's tenant that no
+      // predicate can refuse.
+      assertRowTenant(entity.$name, entity.$tenantColumn, op, patch);
       const values = bindValues(entity, patch);
+      // The read an empty patch degrades to is still this call: attributed to `update`, because
+      // that is the line an author would go and change.
       if (values.size === 0) {
-        const current = await one(plan, options ?? {});
+        const current = await attributed(op, () => one(plan, options ?? {}));
         if (current === null) throw notFound(entity.$name, id);
         return current;
       }
-      const written = await client().one<PhysicalRow>(
-        updateStatement(entity, plan, values, shapeOf(options ?? {})),
+      const written = await attributed(op, () =>
+        writing(() =>
+          client().one<PhysicalRow>(
+            updateStatement(entity, plan, values, shapeOf(options ?? {}), true),
+          ),
+        ),
       );
       if (written === null) throw notFound(entity.$name, id);
       const after = decodeRow(entity, written);
@@ -109,26 +288,95 @@ export const postgresRepo = <Row>(
     },
 
     async delete(id, options) {
-      const plan = idPlan(entity, id, options, 'delete');
-      // Soft delete hides the row without losing it; the column's presence is the switch.
-      const statement = entity.$softDelete
-        ? updateStatement(
-            entity,
-            plan,
-            new Map([[snake(SOFT_DELETE_COLUMN), new Date()]]),
-            shapeOf({}),
-          )
-        : deleteStatement(entity, plan);
-      if ((await client().execute(statement)) === 0) throw notFound(entity.$name, id);
+      const op = 'delete';
+      const plan = idPlan(entity, id, options, op);
+      if ((await attributed(op, () => writing(() => client().execute(removal(plan))))) === 0) {
+        throw notFound(entity.$name, id);
+      }
+    },
+
+    // No `X_NOT_FOUND` here: a filter that matches nothing is a fact the caller asked for, not a
+    // failed address. The count is the answer, which is why it is a `number` and not `void`.
+    //
+    // `deleteWhere`/`updateWhere` are the bulk forms of `delete(id)`/`update(id, patch)` — same
+    // role `insertAll`/`upsertAll` play for a per-row insert loop, one statement instead of one
+    // per row. They are also the *only* filtered writes a composite-key entity has: `likes`,
+    // `blocks`, `participants`, any join table has no single-column id for `delete`/`update` to
+    // address, so without this pair such an entity would be create-only.
+    async deleteWhere(filter, options) {
+      const op = 'deleteWhere';
+      // The plan is built before the write is announced: a refused filter never happened.
+      const plan = deletePlan(entity, filter, options, op);
+      return attributed(op, () => writing(() => client().execute(removal(plan))));
+    },
+
+    async updateWhere(filter, patch, options) {
+      const op = 'updateWhere';
+      const plan = updatePlan(entity, filter, patch, options, op);
+      // The same move, filtered: one statement can hand away every row it matches.
+      assertRowTenant(entity.$name, entity.$tenantColumn, op, patch);
+      const values = bindValues(entity, patch);
+      // `shapeOf({})` keeps the `deleted_at is null` clause `update(id, patch)` already carries,
+      // so a soft-deleted row is not silently patched back into shape.
+      const shape = shapeOf({});
+      // The rows come back only when something here can still refuse them. A `check` or a `unique`
+      // invariant is a constraint Postgres enforced on the statement itself, so the answer is
+      // already a count; only a JS-only rule (`kind: 'assert'`, `sql: null`) has to be judged on
+      // the result. Unconditional, this was `returning *` on every filtered write in the framework
+      // — a GDPR sweep patching twelve million rows streamed all twelve million into the process,
+      // decoded each one, asserted nothing about any of them, and answered with a number.
+      // `deleteWhere` was the tell: same predicate, same table, `execute()` and a count.
+      if (!hasJsOnlyInvariant(entity.$invariants)) {
+        const statement = updateStatement(entity, plan, values, shape, false);
+        return attributed(op, () => writing(() => client().execute(statement)));
+      }
+      // Rows ARE needed, so how many is a memory bound rather than a detail — this is the one
+      // statement in the driver whose result size is the caller's filter and not a page. Counted
+      // BEFORE the write, because a refusal after `returning *` has already allocated the thing it
+      // is refusing; the count can drift by whatever a concurrent writer adds between the two,
+      // which moves a bound, never a decision.
+      const matched = await attributed(op, () =>
+        client().one<{ count: unknown }>(countStatement(entity, plan, shape)),
+      );
+      const rows = Number(matched?.count ?? 0);
+      if (rows > MAX_ASSERTED_ROWS) throw assertedRowsTooMany(entity.$name, op, rows);
+      const statement = updateStatement(entity, plan, values, shape, true);
+      // Inside `withTransaction` a failed assert takes the whole statement with it.
+      const written = await attributed(op, () =>
+        writing(() => client().query<PhysicalRow>(statement)),
+      );
+      for (const row of written) entity.$assert(decodeRow(entity, row));
+      return written.length;
     },
 
     async count(args = {}) {
-      const plan = readPlan(entity, args, 'count');
-      const row = await client().one<{ count: unknown }>(
-        countStatement(entity, plan, shapeOf(args)),
+      const op = 'count';
+      const plan = readPlan(entity, args, op);
+      const row = await attributed(op, () =>
+        client().one<{ count: unknown }>(countStatement(entity, plan, shapeOf(args))),
       );
       return Number(row?.count ?? 0);
     },
+
+    async countBy(column, args = {}) {
+      const op = 'countBy';
+      const grouped = groupColumnOf(entity, column, op);
+      const plan = readPlan(entity, args, op);
+      // One group past the bound, for the same reason a page reads one row past its limit: the
+      // presence of that group is what says the answer was never going to fit, and `countsFrom`
+      // refuses it rather than hand back a breakdown missing its tail.
+      const rows = await attributed(op, () =>
+        client().query<GroupRow>(
+          countByStatement(entity, plan, shapeOf(args), column, MAX_GROUPS + 1),
+        ),
+      );
+      return countsFrom(
+        entity,
+        column,
+        op,
+        rows.map((row) => [groupValue(grouped, row.group_value), Number(row.group_count)] as const),
+      );
+    },
   };
 };
 

package/src/pg-row.ts

@@ -5,6 +5,7 @@
 // as a string, timestamptz may arrive as one, and a silent `NaN` is worse than a loud throw.
 
 import { snake } from './column';
+import { narrowMoney } from './columns';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
 import type { AnyColumn, MoneyValue } from './types';
@@ -13,10 +14,18 @@ export type PhysicalRow = Readonly<Record<string, unknown>>;
 
 const MONEY_PARTS = new Set(['minor', 'currency']);
 
-/** `price` -> `price_minor`, `price_currency`. Everything else is one snake_case column. */
+/**
+ * `price` -> `price_minor`, `price_currency`, `price_scale`. Everything else is one snake_case
+ * column.
+ *
+ * The scale column is nullable and is the only one of the three an amount may omit: `null` means
+ * "the currency's own minor unit", which is every row written before the column existed. It is NOT
+ * addressable as a predicate or a sort key (`MONEY_PARTS` below, and `cursor.ts`'s copy) — a scale
+ * says which units `minor` counts, so ordering or filtering by it compares two different questions.
+ */
 export const columnsOf = (property: string, column: AnyColumn): readonly string[] =>
   column.$meta.kind === 'money'
-    ? [`${snake(property)}_minor`, `${snake(property)}_currency`]
+    ? [`${snake(property)}_minor`, `${snake(property)}_currency`, `${snake(property)}_scale`]
     : [snake(property)];
 
 /**
@@ -61,7 +70,9 @@ export const bindValues = <Row>(
   values: Partial<Row>,
 ): ReadonlyMap<string, unknown> => {
   const bound = new Map<string, unknown>();
-  const record = values as Readonly<Record<string, unknown>>;
+  // `MoneyInput` lets a writer hand a `bigint`; the row type is `MoneyValue`. `memoryRepo` calls
+  // the same narrowing before it stores, so what the two drivers write is one value.
+  const record = narrowMoney(entity.$columns, values) as Readonly<Record<string, unknown>>;
   for (const [property, column] of Object.entries(entity.$columns)) {
     if (!Object.hasOwn(record, property)) continue;
     const value = record[property];
@@ -72,14 +83,25 @@ export const bindValues = <Row>(
     const money = value as MoneyValue | null | undefined;
     bound.set(`${snake(property)}_minor`, money?.minor ?? null);
     bound.set(`${snake(property)}_currency`, money?.currency ?? null);
+    // `?? null` and not `!== undefined`: an amount at the currency's own scale carries no key at
+    // all, and that absence is what the nullable column stores. A `0` written here for it would
+    // claim whole units — a 100x reinterpretation of every ordinary price.
+    bound.set(`${snake(property)}_scale`, money?.scale ?? null);
   }
   return bound;
 };
 
-const moneyOf = (source: PhysicalRow, minor: string, currency: string): unknown => {
+const moneyOf = (source: PhysicalRow, minor: string, currency: string, scale: string): unknown => {
   const amount = source[minor];
   if (amount === null || amount === undefined) return null;
-  return { minor: amount, currency: String(source[currency] ?? '').trim() };
+  // A column the projection left out is absent, not null — and absent must read as "no scale"
+  // exactly as a stored NULL does, so both take the same branch.
+  const declared = source[scale];
+  return {
+    minor: amount,
+    currency: String(source[currency] ?? '').trim(),
+    ...(declared === null || declared === undefined ? {} : { scale: declared }),
+  };
 };
 
 /**
@@ -89,9 +111,12 @@ const moneyOf = (source: PhysicalRow, minor: string, currency: string): unknown
 export const decodeRow = <Row>(entity: EntityCore<Row>, source: PhysicalRow): Row => {
   const row: Record<string, unknown> = {};
   for (const [property, column] of Object.entries(entity.$columns)) {
-    const [head, tail] = columnsOf(property, column);
+    const [head, currency, scale] = columnsOf(property, column);
     if (head === undefined || !(head in source)) continue;
-    const value = tail === undefined ? source[head] : moneyOf(source, head, tail);
+    const value =
+      currency === undefined || scale === undefined
+        ? source[head]
+        : moneyOf(source, head, currency, scale);
     if (value !== null && value !== undefined) {
       row[property] = column.$parse(value);
       continue;

package/src/pg-sql.ts

@@ -55,6 +55,34 @@ const predicateSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFr
   }
 };
 
+/**
+ * A cursor's timestamp is the row's own value FLOORED: a `Date` holds milliseconds and a
+ * `timestamptz` column holds microseconds, so `created_at > '…123'` is satisfied by the very row
+ * at `…123456` the cursor was minted from — the same row, returned again, on every page boundary.
+ * Under `desc` the same gap does the opposite and silently drops every row inside that
+ * millisecond, which no `id` tiebreak can recover because the first `or` term never matched.
+ *
+ * So a timestamp seek compares against the millisecond WINDOW its value stands for — what
+ * `date_trunc('milliseconds', …)` would say, spelled as a half-open range so the column stays
+ * bare and an index can still range-scan it. `timestamptz` is the only sort kind revived as a
+ * `Date` (`cursor.ts`), so the type test IS the kind test.
+ */
+const nextMillisecond = (value: Date): Date => new Date(value.getTime() + 1);
+
+/** Strictly past the cursor's position in this key's direction. */
+const seekAfter = (column: SqlFragment, direction: string, value: unknown): SqlFragment => {
+  if (direction === 'desc') return sql`${column} < ${value}`;
+  // `>= v + 1ms` is `trunc(col) > v`; `< v` already is `trunc(col) < v`, so only asc moves.
+  if (value instanceof Date) return sql`${column} >= ${nextMillisecond(value)}`;
+  return sql`${column} > ${value}`;
+};
+
+/** At the cursor's position for this key — the prefix a later key's tiebreak hangs off. */
+const seekEqual = (column: SqlFragment, value: unknown): SqlFragment =>
+  value instanceof Date
+    ? sql`(${column} >= ${value} and ${column} < ${nextMillisecond(value)})`
+    : sql`${column} = ${value}`;
+
 /**
  * The keyset seek, spelled out rather than as a row comparison: `(a, b) > (x, y)` requires every
  * key to sort the same way, and a listing that is `published_at desc, id asc` does not.
@@ -67,10 +95,9 @@ const seekSql = <Row>(
   const terms = orderBy.map((entry, index) => {
     const equal = orderBy
       .slice(0, index)
-      .map((earlier, position) => sql`${columnRef(entity, earlier.column)} = ${seek[position]}`);
-    const after = raw(entry.direction === 'desc' ? '<' : '>');
+      .map((earlier, position) => seekEqual(columnRef(entity, earlier.column), seek[position]));
     return sql`(${join(
-      [...equal, sql`${columnRef(entity, entry.column)} ${after} ${seek[index]}`],
+      [...equal, seekAfter(columnRef(entity, entry.column), entry.direction, seek[index])],
       ' and ',
     )})`;
   });
@@ -135,25 +162,107 @@ export const countStatement = <Row>(
 ): SqlFragment =>
   sql`select count(*) as count from ${identifier(entity.$table)} where ${conditions(entity, plan, shape)}`;
 
+/** What a grouped count comes back as. Both names are fixed, so neither can be a column's. */
+export interface GroupRow {
+  readonly group_value: unknown;
+  readonly group_count: unknown;
+}
+
+/**
+ * The grouped count: one row per distinct value of one column, over exactly the rows
+ * `countStatement` would have counted — the same predicates, the same soft-delete filter, one
+ * `group by` more. `limit` bounds the groups, not the rows, which is what turns a whole-table
+ * breakdown into a refusal instead of a result set nobody sized.
+ *
+ * Both output names are aliases and fixed, so they cannot collide with each other whatever the
+ * table declares: an entity is free to have a column called `count`, and the un-aliased form would
+ * then return two outputs of one name.
+ */
+export const countByStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  shape: ReadShape,
+  column: string,
+  limit: number,
+): SqlFragment => {
+  const grouped = columnRef(entity, column);
+  return sql`select ${grouped} as group_value, count(*) as group_count from ${identifier(
+    entity.$table,
+  )} where ${conditions(entity, plan, shape)} group by ${grouped} limit ${limit}`;
+};
+
+/** `on conflict (…) do update set …`, or `do nothing` when there is nothing to overwrite. */
+export interface ConflictTarget {
+  /** Physical columns of the unique index a collision is judged against. */
+  readonly columns: readonly string[];
+  /** Physical columns a colliding row takes from the incoming one. Empty is `do nothing`. */
+  readonly set: readonly string[];
+}
+
+export interface InsertShape {
+  /** Every physical column written — one list, shared by every row of the statement. */
+  readonly columns: readonly string[];
+  /** How a collision resolves. Absent, it is the caller's error, exactly as it is for one row. */
+  readonly conflict?: ConflictTarget | undefined;
+}
+
+/**
+ * The cell of a row that did not name this column. `default` is the second and last `raw()` in
+ * this file and, like `asc|desc` above it, a closed set of one word: it is what makes a row inside
+ * a many-row `insert` mean what the same row means on its own, where an unnamed column is simply
+ * left out. The seek operator used to be a third — it is chosen in TypeScript now
+ * (`seekAfter`/`seekEqual`), because a timestamp seek is not one operator.
+ */
+const DEFAULT_CELL = raw('default');
+
+const conflictSql = (conflict: ConflictTarget): SqlFragment => {
+  const target = join(conflict.columns.map(identifier));
+  return conflict.set.length === 0
+    ? sql` on conflict (${target}) do nothing`
+    : sql` on conflict (${target}) do update set ${join(
+        conflict.set.map((column) => sql`${identifier(column)} = excluded.${identifier(column)}`),
+      )}`;
+};
+
+/**
+ * One statement for any number of rows. A single row compiles to exactly the text it always did,
+ * which is the point: `insertAll([row])` and `insert(row)` are one code path, so there is no
+ * second insert builder for the two to drift apart in.
+ */
 export const insertStatement = <Row>(
   entity: EntityCore<Row>,
-  values: ReadonlyMap<string, unknown>,
+  rows: readonly ReadonlyMap<string, unknown>[],
+  shape: InsertShape,
 ): SqlFragment => {
-  const entries = [...values];
+  const tuples = rows.map(
+    (row) =>
+      sql`(${join(
+        shape.columns.map((column) => (row.has(column) ? sql`${row.get(column)}` : DEFAULT_CELL)),
+      )})`,
+  );
+  const conflict = shape.conflict === undefined ? sql`` : conflictSql(shape.conflict);
   return sql`insert into ${identifier(entity.$table)} (${join(
-    entries.map(([column]) => identifier(column)),
-  )}) values (${join(entries.map(([, value]) => sql`${value}`))}) returning *`;
+    shape.columns.map(identifier),
+  )}) values ${join(tuples)}${conflict} returning *`;
 };
 
+/**
+ * `returning` is a parameter and has no default, because the three callers want three different
+ * answers and the wrong one is not visible in the result: `update(id, patch)` needs the stored row,
+ * a soft delete and a filtered write need a count, and `returning *` on a filtered write over a
+ * whole tenant streams every matched row into the process for nobody to read. A default would make
+ * that the quiet case.
+ */
 export const updateStatement = <Row>(
   entity: EntityCore<Row>,
   plan: QueryPlan,
   values: ReadonlyMap<string, unknown>,
   shape: ReadShape,
+  returning: boolean,
 ): SqlFragment =>
   sql`update ${identifier(entity.$table)} set ${join(
     [...values].map(([column, value]) => sql`${identifier(column)} = ${value}`),
-  )} where ${conditions(entity, plan, shape)} returning *`;
+  )} where ${conditions(entity, plan, shape)}${returning ? sql` returning *` : sql``}`;
 
 /** Only reached when the entity has no soft-delete column, so there is no filter to apply. */
 export const deleteStatement = <Row>(entity: EntityCore<Row>, plan: QueryPlan): SqlFragment =>