@ultimat3/entity 2.0.0 → 4.0.0

package/src/index.ts

@@ -4,7 +4,9 @@
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 export type { BatchIterator } from './batch';
-export type { TextOptions } from './columns';
+export type { MoneyColumns } from './column';
+export { columnName, moneyColumns, snake } from './column';
+export type { MoneyOptions, TextOptions } from './columns';
 export {
   boolean,
   enumerated,
@@ -18,11 +20,18 @@ export {
   url,
   uuid,
 } from './columns';
+// The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
+// are decisions this framework made for a table it was going to create, and these are the shapes
+// a table already has (`docs`: Entities-And-Migrations, "Adopting an existing database").
+export type { DecimalOptions } from './columns-data';
+export { arrayOf, bigint, bytes, date, decimal, json } from './columns-data';
 // `crossTenantReason` stays internal: an app that could read the flag would have a second way to
 // reason about tenant scope — branch on it — next to the one way, which is entering the scope.
 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';
 export type {
@@ -92,6 +101,7 @@ export {
 export type { EntityRelations, Relation, RelationKind, RelationMap } from './relations';
 export { relationMap, relationNamed, relationsFor, relationsOf } from './relations';
 export type {
+  FindByIdOptions,
   FindManyArgs,
   MemoryRepo,
   Page,
@@ -102,8 +112,18 @@ export type {
   UpsertArgs,
 } from './repo';
 export { memoryRepo, memoryTransactor } from './repo';
-export type { Seed, SeedContext, SeedOptions } from './seed';
-export { defineSeed, seedId } from './seed';
+export type {
+  Seed,
+  SeedContext,
+  SeedInit,
+  SeedKey,
+  SeedMetrics,
+  SeedOptions,
+  SeedRun,
+  SeedTier,
+  SeedWrite,
+} from './seed';
+export { defineSeed, isSeed, SEED_TIERS, seedId, seedTiersFor } from './seed';
 export type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
 export {
   assertRowTenant,
@@ -127,14 +147,17 @@ export type {
   IdOf,
   IndexDef,
   Insertable,
+  MoneyColumnNames,
   MoneyInput,
   MoneyValue,
   OnDelete,
   ReferenceOptions,
   RowOf,
+  RowPatch,
   TimestampColumn,
   TypeOf,
   UuidColumn,
 } from './types';
+export { COLUMN_KINDS } from './types';
 // `viewFor` stays internal: a view is reached through the entity, as `posts.$view([...])`.
 export type { EntityView } from './view';

package/src/jit-preload.ts

@@ -5,7 +5,9 @@
 //
 // The trigger carries an id, not a row, so what a page leaves behind is an index of its foreign
 // key VALUES rather than a map keyed by row identity: an id is a thing that can be looked up in
-// it, and it holds values, so it pins no rows for the request's lifetime.
+// it, and a page therefore costs its keys rather than its rows. That was true PER PAGE and false
+// across them until `MAX_SIBLING_KEYS` — the store outlives every page and dies with the ctx,
+// which for a job is the whole attempt, so both maps here are bounded and evict the oldest page.
 //
 // The scope guard is a security boundary, not a tuning knob. A preloaded row is served only to a
 // lookup with the same scope key, the same client and no write since — anything else reads the
@@ -14,7 +16,15 @@
 import type { Ctx } from '@ultimat3/core';
 import { tryUseContext } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
-import { type Answer, keyOf, type PointRead, readByIds, statementChunks } from './batch-read';
+import {
+  type Answer,
+  keyOf,
+  MAX_IDS_PER_STATEMENT,
+  type PointRead,
+  readByIds,
+  statementChunks,
+} from './batch-read';
+import { columnFor } from './column';
 import type { EntityCore } from './entity';
 
 /** The rows one page's worth of foreign keys resolved to, under one scope. */
@@ -53,10 +63,54 @@ const storeFor = (ctx: Ctx): Store => {
   return created;
 };
 
+/**
+ * How many id keys ONE edge may hold, and how many rows one bucket may keep — a few pages' worth,
+ * the way `MAX_IDS_PER_STATEMENT` bounds a statement.
+ *
+ * `MAX_IDS_PER_STATEMENT` bounded the statement and nothing bounded the STORE: every page merged
+ * its keys in and the store died only with the ctx, which for a job is the whole attempt. Measured
+ * at 1,000 pages x 1,000 rows with distinct foreign keys, rows dropped after each call and
+ * `Bun.gc(true)` either side: **159.3 MB retained**, against 2.7 MB with the tagging off — so a
+ * 12M-row `backfill()` retains ~2 GB and OOMs the worker on the DEFAULT configuration, since
+ * `jitPreload` defaults to true and `backfill()` names no driver option.
+ *
+ * Four statements' worth. The keys of one page are filed contiguously, so the survivors are the
+ * newest pages' and the arrays every evicted key referenced go with them — which is what makes the
+ * bound a bound on bytes and not only on entries. Past it a lookup DECLINES, and declining is the
+ * old behaviour everywhere else in this file: the caller reads the statement it always read.
+ */
+export const MAX_SIBLING_KEYS = MAX_IDS_PER_STATEMENT * 4;
+
+/**
+ * Newest wins, oldest goes. A `Map` iterates in insertion order, so its first key is the oldest
+ * page's — and the page a sequential `for … of` loop is walking is the newest one, which is the
+ * only page this store exists to answer for. Re-filed rather than overwritten, so a key a later
+ * page carries again moves to the newest end instead of ageing out under it.
+ */
+const remember = <V>(index: Map<string, V>, key: string, value: V, cap: number): void => {
+  index.delete(key);
+  index.set(key, value);
+  while (index.size > cap) {
+    const oldest = index.keys().next();
+    if (oldest.done === true) return;
+    index.delete(oldest.value);
+  }
+};
+
 /** Both ends of the edge: a key pointing at another column of the same entity is another edge. */
 const siblingKey = (targetEntity: string, targetProperty: string): string =>
   JSON.stringify([targetEntity, targetProperty]);
 
+/** TEST SEAM: id keys this request is holding, across every edge. A bound nothing can observe is a
+ * bound nothing can pin, and `MAX_SIBLING_KEYS` is the number this answers against. */
+export const siblingKeysHeld = (ctx: Ctx): number => {
+  const store = requests.get(ctx);
+  if (store === undefined) return 0;
+  let held = 0;
+  for (const index of store.siblings.values()) held += index.size;
+  return held;
+};
+
 const writesTo = (store: Store, entity: string): number => store.writes.get(entity) ?? 0;
 
 /**
@@ -80,7 +134,7 @@ export const tagSiblings = <Row>(entity: EntityCore<Row>, rows: readonly Row[]):
   for (const reference of references) {
     // The declaring column's own kind: a foreign key mirrors the key it points at, and a value is
     // filed here exactly as `findById` will spell it when it comes looking.
-    const kind = entity.$columns[reference.property]?.$meta.kind;
+    const kind = columnFor(entity.$columns, reference.property)?.$meta.kind;
     if (kind === undefined) continue;
     const ids: unknown[] = [];
     const keys = new Set<string>();
@@ -96,7 +150,7 @@ export const tagSiblings = <Row>(entity: EntityCore<Row>, rows: readonly Row[]):
     if (ids.length === 0) continue;
     const at = siblingKey(reference.targetEntity, reference.targetProperty);
     const index = store.siblings.get(at) ?? new Map<string, readonly unknown[]>();
-    for (const key of keys) index.set(key, ids);
+    for (const key of keys) remember(index, key, ids, MAX_SIBLING_KEYS);
     store.siblings.set(at, index);
   }
 };
@@ -165,12 +219,14 @@ const preload = <Row>(read: PointRead<Row>, bucket: Bucket, ids: readonly unknow
     if (bucket.rows.has(at)) continue;
     // The executor runs synchronously, so `settle` is assigned before the promise is stored.
     let settle!: (answer: Answer) => void;
-    bucket.rows.set(
-      at,
-      new Promise<Answer>((resolve) => {
-        settle = resolve;
-      }),
-    );
+    const answer = new Promise<Answer>((resolve) => {
+      settle = resolve;
+    });
+    // Bounded for the reason the sibling index is: a bucket holds ROWS, so a long request that
+    // preloads page after page retains every row it ever resolved. An evicted entry still settles
+    // — `fill` holds its own settler — and a lookup that no longer finds one reads its own
+    // statement, which is what it would have read had no page indexed the id at all.
+    remember(bucket.rows, at, answer, MAX_SIBLING_KEYS);
     settlers.set(at, settle);
     wanted.push(id);
   }

package/src/memory-match.ts

@@ -0,0 +1,169 @@
+// Single responsibility: what a `Predicate` MEANS in the in-memory driver — equality, ordering and
+// LIKE. Every rule here exists so the answer matches the one Postgres gives for the same predicate
+// on the same column, which is why each is decided by the column's DECLARED KIND and never by the
+// JS type of whichever value is in hand: the database decides by the column's type, so a driver
+// deciding by `typeof` is answering a different question.
+
+import { compareDecimalText } from '@ultimat3/core';
+import { keyOf } from './batch-read';
+import { kindOf, valueAt } from './cursor';
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import type { Predicate } from './tenancy';
+import type { ColumnKind } from './types';
+
+/**
+ * The kinds whose ROW VALUE is a decimal string. `bigint()` and `decimal()` both hand back digits
+ * as text on purpose (`columns-data.ts`): a JS `bigint` is what `JSON.stringify` throws on and a
+ * `number` loses digits past 2^53, exactly where a legacy `int8` key lives.
+ *
+ * Which makes them the kinds no `typeof` branch can catch. `compare` had a `number`/`number` case
+ * and a `bigint`/`bigint` case and neither fired for these, so both fell to
+ * `String(left) < String(right)`: memory answered `["10","100","2","9"]` where Postgres answers
+ * `["2","9","10","100"]`, and a keyset page boundary was cut where the database never cuts one.
+ *
+ * This SET is the whole of what this package contributes; the comparison itself is
+ * `@ultimat3/core`'s `compareDecimalText`. The split is the point — the text arrives in more than
+ * one package and the DECLARED KIND does not, so a caller with no column kinds
+ * (`@ultimat3/query`, whose `OrderKey` is a name and a direction) deliberately never asks: a
+ * `text` column holding `"10"` and `"9"` is ordered lexically by Postgres, and a comparator
+ * guessing "both sides look like decimals" would trade this disagreement for that one.
+ */
+const DECIMAL_TEXT: ReadonlySet<ColumnKind> = new Set<ColumnKind>(['bigint', 'numeric']);
+
+const sign = <T extends number | bigint | string>(left: T, right: T): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+/**
+ * Two values of one column, ordered as Postgres orders that column. `-1`, `0` or `1` — never a
+ * difference, so a `bigint` pair needs no subtraction it cannot express in a `number`.
+ */
+export const compareByKind = (
+  kind: ColumnKind | undefined,
+  left: unknown,
+  right: unknown,
+): number => {
+  if (left instanceof Date && right instanceof Date) return sign(left.getTime(), right.getTime());
+  if (kind !== undefined && DECIMAL_TEXT.has(kind)) {
+    // `undefined` when either side is not a plain decimal — that pair is not a numeric comparison,
+    // so it falls through to the branches below rather than being guessed at.
+    const exact = compareDecimalText(left, right);
+    if (exact !== undefined) return exact;
+  }
+  if (typeof left === 'number' && typeof right === 'number') return sign(left, right);
+  if (typeof left === 'bigint' && typeof right === 'bigint') return sign(left, right);
+  return sign(String(left), String(right));
+};
+
+/**
+ * Equality, in the two places `===` is not what the database means. A `Date` compares by identity,
+ * so `where({ publishedAt })` would match nothing here and every row there. And Postgres compares a
+ * `uuid` as a VALUE — it parses the text and prints it lower-cased — so an id handed in upper case
+ * matches the row there and used to miss it here, which is `findById(UPPER)` answering `null` in
+ * memory and the row in production. `keyOf` is where that rule already lived, for the batched read.
+ */
+export const sameValueOfKind = (
+  kind: ColumnKind | undefined,
+  left: unknown,
+  right: unknown,
+): boolean => {
+  if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  if (kind === 'uuid' && typeof left === 'string' && typeof right === 'string') {
+    return keyOf('uuid', left) === keyOf('uuid', right);
+  }
+  return left === right;
+};
+
+const REGEX_SPECIAL = /[.*+?^${}()|[\]\\]/g;
+
+const quote = (text: string): string => text.replace(REGEX_SPECIAL, '\\$&');
+
+/**
+ * Postgres answers a `LIKE` pattern ending in the escape character with `22025 — LIKE pattern must
+ * not end with escape character`, so a pattern that means nothing there means nothing here either.
+ * The pattern itself is never echoed: a filter value is app data, and this cause is rendered into
+ * a log line.
+ */
+const danglingEscape = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}: a like pattern ends with a backslash, which is the escape character — Postgres answers that pattern with 22025 (LIKE pattern must not end with escape character)`,
+    fix: "double it — 'a\\\\' is the pattern that matches one literal backslash, and 'a\\%b' matches a literal %",
+  });
+
+/**
+ * A SQL `LIKE` pattern as a regex, with Postgres' DEFAULT escape handling: `%` and `_` are the
+ * wildcards, a backslash escapes either (or itself), and everything else is literal.
+ *
+ * The backslash used to be quoted for the regex BEFORE the wildcards were expanded, so `'a\%b'`
+ * matched the literal `a%b` in Postgres and `a\<anything>b` here — one pattern, two meanings, and
+ * the driver that disagreed was the one every test runs against.
+ *
+ * A RUN of `%` is still one `.*`, not one each: `%%%…x` compiled to twenty adjacent `.*` groups,
+ * and an anchored regex with twenty of them takes exponential time to fail on a long value — a
+ * filter value forwarded from a search box is then a CPU stall in the process. Postgres reads a run
+ * of `%` as one wildcard too, so this is the two drivers agreeing rather than a defensive
+ * narrowing.
+ */
+const likePattern = (entityName: string, pattern: string): RegExp => {
+  let source = '';
+  let at = 0;
+  while (at < pattern.length) {
+    const char = pattern[at];
+    if (char === '\\') {
+      const escaped = pattern[at + 1];
+      if (escaped === undefined) throw danglingEscape(entityName);
+      source += quote(escaped);
+      at += 2;
+      continue;
+    }
+    if (char === '%') {
+      while (pattern[at] === '%') at += 1;
+      source += '.*';
+      continue;
+    }
+    source += char === '_' ? '.' : quote(char ?? '');
+    at += 1;
+  }
+  return new RegExp(`^${source}$`, 's');
+};
+
+/** One predicate against one stored row, in the meaning the Postgres driver compiles it to. */
+export const matchesPredicate = <Row>(
+  entity: EntityCore<Row>,
+  row: unknown,
+  predicate: Predicate,
+): boolean => {
+  // The column's declared kind, resolved once — `price.minor` included, which is the path a money
+  // predicate and a money sort key both name.
+  const kind = kindOf(entity, predicate.column);
+  const actual = valueAt(row, predicate.column);
+  const same = (candidate: unknown): boolean => sameValueOfKind(kind, actual, candidate);
+  const order = (): number => compareByKind(kind, actual, predicate.value);
+  switch (predicate.op) {
+    case 'eq':
+      return same(predicate.value);
+    case 'neq':
+      return !same(predicate.value);
+    // `in` reads a LIST or nothing: an operand that is not an array matches no row, which is what
+    // `predicateSql` now compiles it to and what `@ultimat3/query` answers for the same operand.
+    case 'in':
+      return Array.isArray(predicate.value) && predicate.value.some(same);
+    case 'gt':
+      return order() > 0;
+    case 'gte':
+      return order() >= 0;
+    case 'lt':
+      return order() < 0;
+    case 'lte':
+      return order() <= 0;
+    // Real LIKE semantics, so `'draft%'` means "starts with" here exactly as it does in Postgres.
+    // Treating the pattern as a substring would make the two drivers disagree.
+    case 'like':
+      return likePattern(entity.$name, String(predicate.value)).test(String(actual));
+    case 'is-null':
+      return actual === null || actual === undefined;
+    case 'is-not-null':
+      return actual !== null && actual !== undefined;
+  }
+};

package/src/pg-driver.ts

@@ -7,7 +7,6 @@
 // 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 { systemClock } from '@ultimat3/core';
 import {
   currentTx,
   type DbClient,
@@ -24,8 +23,8 @@ import {
   namedProperties,
   upsertPlan,
 } from './bulk-write';
+import { entityNow } from './clock';
 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';
@@ -33,7 +32,7 @@ import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 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 { bindValues, decodeRow, type PhysicalRow, physicalName } from './pg-row';
 import {
   type ConflictTarget,
   countByStatement,
@@ -133,7 +132,7 @@ export const postgresRepo = <Row>(
       ? updateStatement(
           entity,
           plan,
-          new Map([[snake(SOFT_DELETE_COLUMN), systemClock.now()]]),
+          new Map([[physicalName(entity, SOFT_DELETE_COLUMN), entityNow()]]),
           shapeOf({}),
           false,
         )

package/src/pg-row.ts

@@ -4,11 +4,11 @@
 // 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 { columnFor, columnName, moneyColumns } from './column';
 import { narrowMoney } from './columns';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
-import type { AnyColumn, MoneyValue } from './types';
+import type { AnyColumn, MoneyValue, RowPatch } from './types';
 
 export type PhysicalRow = Readonly<Record<string, unknown>>;
 
@@ -23,10 +23,15 @@ const MONEY_PARTS = new Set(['minor', 'currency']);
  * 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)}_scale`]
-    : [snake(property)];
+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
@@ -34,7 +39,7 @@ export const columnsOf = (property: string, column: AnyColumn): readonly string[
  */
 export const physicalName = <Row>(entity: EntityCore<Row>, path: string): string => {
   const [property = path, part] = path.split('.');
-  const column = entity.$columns[property];
+  const column = columnFor(entity.$columns, property);
   if (column === undefined) {
     throw invariantViolated(
       entity.$name,
@@ -44,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,
@@ -54,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. */
@@ -67,7 +73,7 @@ export const allColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
  */
 export const bindValues = <Row>(
   entity: EntityCore<Row>,
-  values: Partial<Row>,
+  values: RowPatch<Row>,
 ): ReadonlyMap<string, unknown> => {
   const bound = new Map<string, unknown>();
   // `MoneyInput` lets a writer hand a `bigint`; the row type is `MoneyValue`. `memoryRepo` calls
@@ -77,26 +83,63 @@ export const bindValues = <Row>(
     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.
-    bound.set(`${snake(property)}_scale`, money?.scale ?? null);
+    if (parts.scale !== null) bound.set(parts.scale, money?.scale ?? null);
   }
   return bound;
 };
 
-const moneyOf = (source: PhysicalRow, minor: string, currency: string, scale: 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;
   // 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];
+  // 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(),
@@ -113,10 +156,13 @@ export const decodeRow = <Row>(entity: EntityCore<Row>, source: PhysicalRow): Ro
   for (const [property, column] of Object.entries(entity.$columns)) {
     const [head, currency, scale] = columnsOf(property, column);
     if (head === undefined || !(head in source)) continue;
+    // 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 =
-      currency === undefined || scale === undefined
-        ? source[head]
-        : moneyOf(source, head, currency, scale);
+      column.$meta.kind === 'money' && currency !== undefined
+        ? moneyOf(source, head, currency, scale)
+        : source[head];
     if (value !== null && value !== undefined) {
       row[property] = column.$parse(value);
       continue;