@ultimat3/entity 1.2.0 → 3.0.0

package/src/pg-driver.ts

@@ -7,24 +7,47 @@
 // 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 { snake } from './column';
+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 { 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 { bindValues, decodeRow, type PhysicalRow } from './pg-row';
+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 } 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 +56,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 +73,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 +118,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([[physicalName(entity, 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 +235,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 +287,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

@@ -4,7 +4,8 @@
 // from the driver is re-parsed by the column that declared it rather than trusted — int8 arrives
 // as a string, timestamptz may arrive as one, and a silent `NaN` is worse than a loud throw.
 
-import { snake } from './column';
+import { columnName, moneyColumns } from './column';
+import { narrowMoney } from './columns';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
 import type { AnyColumn, MoneyValue } from './types';
@@ -13,11 +14,24 @@ 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. */
-export const columnsOf = (property: string, column: AnyColumn): readonly string[] =>
-  column.$meta.kind === 'money'
-    ? [`${snake(property)}_minor`, `${snake(property)}_currency`]
-    : [snake(property)];
+/**
+ * `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[] => {
+  if (column.$meta.kind !== 'money') return [columnName(property, column.$meta)];
+  const parts = moneyColumns(property, column.$meta);
+  // Two columns for an adopted amount that has no scale column: the list IS the projection, so a
+  // name here that the table does not have is a `42703` on the first select.
+  return parts.scale === null
+    ? [parts.minor, parts.currency]
+    : [parts.minor, parts.currency, parts.scale];
+};
 
 /**
  * A predicate or sort key names a property, never a physical column — so `orgId` becomes
@@ -35,7 +49,7 @@ export const physicalName = <Row>(entity: EntityCore<Row>, path: string): string
   }
   const isMoney = column.$meta.kind === 'money';
   if (part === undefined) {
-    if (!isMoney) return snake(property);
+    if (!isMoney) return columnName(property, column.$meta);
     throw invariantViolated(
       entity.$name,
       property,
@@ -45,7 +59,8 @@ export const physicalName = <Row>(entity: EntityCore<Row>, path: string): string
   if (!isMoney || !MONEY_PARTS.has(part)) {
     throw invariantViolated(entity.$name, property, `${property} has no part "${part}"`);
   }
-  return `${snake(property)}_${part}`;
+  const parts = moneyColumns(property, column.$meta);
+  return part === 'minor' ? parts.minor : parts.currency;
 };
 
 /** Every physical column of the entity, in declaration order. */
@@ -61,25 +76,75 @@ 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];
     if (column.$meta.kind !== 'money') {
-      bound.set(snake(property), value ?? null);
+      bound.set(columnName(property, column.$meta), bindable(column, value));
       continue;
     }
+    const parts = moneyColumns(property, column.$meta);
     const money = value as MoneyValue | null | undefined;
-    bound.set(`${snake(property)}_minor`, money?.minor ?? null);
-    bound.set(`${snake(property)}_currency`, money?.currency ?? null);
+    bound.set(parts.minor, money?.minor ?? null);
+    bound.set(parts.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.
+    if (parts.scale !== null) bound.set(parts.scale, money?.scale ?? null);
   }
   return bound;
 };
 
-const moneyOf = (source: PhysicalRow, minor: string, currency: string): unknown => {
+/**
+ * One array element, as a Postgres array literal spells it. Quoted always: an unquoted element
+ * containing a comma, a brace or a backslash is a different array, and an empty string unquoted
+ * is nothing at all.
+ */
+const arrayElement = (value: unknown): string => {
+  if (value === null || value === undefined) return 'NULL';
+  const text =
+    value instanceof Date ? value.toISOString() : typeof value === 'object' ? '' : String(value);
+  return `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+};
+
+/**
+ * The value a parameter carries. Every column but one hands its row value straight over — the
+ * measured driver behaviour is that an object binds to `jsonb`, a string binds to `numeric`,
+ * `int8` and `date`, and a `Uint8Array` binds to `bytea`.
+ *
+ * An array is the one that cannot: Bun's `sql` serialises a JS array to `x,y`, which Postgres
+ * answers with `malformed array literal` (measured). What it accepts is the literal, so this is
+ * where a JS array becomes one.
+ */
+const bindable = (column: AnyColumn, value: unknown): unknown => {
+  if (value === null || value === undefined) return null;
+  // A plain object is not a bindable parameter (`X_SQL_UNSAFE`), so a `jsonb` value crosses as its
+  // TEXT and `pg-sql.ts`'s cell casts it back — see `cellCast` for why the cast is `::text::jsonb`.
+  if (column.$meta.kind === 'jsonb') return JSON.stringify(value);
+  if (column.$meta.kind !== 'array' || !Array.isArray(value)) return value;
+  return `{${value.map(arrayElement).join(',')}}`;
+};
+
+const moneyOf = (
+  source: PhysicalRow,
+  minor: string,
+  currency: string,
+  scale: string | undefined,
+): 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. So does a table that has no
+  // scale column at all, which is why the name itself may be `undefined`.
+  const declared = scale === undefined ? undefined : source[scale];
+  return {
+    minor: amount,
+    currency: String(source[currency] ?? '').trim(),
+    ...(declared === null || declared === undefined ? {} : { scale: declared }),
+  };
 };
 
 /**
@@ -89,9 +154,15 @@ 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);
+    // Decided by the column's KIND and never by how many names came back: a money column whose
+    // table has no scale column projects two names, and reading that as a non-money column handed
+    // the caller a raw minor unit where a `Money` belongs.
+    const value =
+      column.$meta.kind === 'money' && currency !== undefined
+        ? moneyOf(source, head, currency, scale)
+        : source[head];
     if (value !== null && value !== undefined) {
       row[property] = column.$parse(value);
       continue;