@ultimat3/entity 11.3.0 → 13.0.0

package/src/aggregate-decode.ts

@@ -0,0 +1,35 @@
+// Single responsibility: turn the TEXT an aggregate statement returns into the value the column's
+// kind holds — the Postgres driver's half of `aggregate.ts`, opposite `aggregate-fold.ts`.
+//
+// The statement casts every aggregate to `::text` on purpose. `sum(bigint)` is a `numeric` the
+// client hands back as a string anyway, `min(timestamptz)` would arrive as a millisecond `Date`,
+// and pinning all of them to text means exactly one place decides what the value becomes.
+
+import type { AggregateFn } from './aggregate';
+import type { ColumnKind } from './types';
+
+/**
+ * `sum` and `avg` stay decimal TEXT whatever the column was, and that is the point: the sum of a
+ * million `integer` rows is not an `integer`, `Number()` on it loses digits past 2^53, and a
+ * binary float loses cents on a `numeric`. A caller who wants a JS number writes the `Number()`
+ * themselves, where the loss is a decision somebody made.
+ *
+ * `min` and `max` answer the ROW's own type, because the answer is one of the values that went in:
+ * a `timestamptz` back to a `Date` (the row property's type), everything else to the text it
+ * already is — `integer` becomes a `number` because that is what the row holds, and a minimum
+ * cannot exceed a value that already fitted in one.
+ */
+export const decodeAggregate = (fn: AggregateFn, kind: ColumnKind, text: string): unknown => {
+  // Decided by the FUNCTION first: `min('likeCount')` is one of the rows' own values and fits in
+  // whatever they fit in, while `sum('likeCount')` over a million of them does not.
+  if (fn === 'sum' || fn === 'avg') return text;
+  if (kind === 'timestamptz') {
+    const at = new Date(text);
+    return Number.isNaN(at.getTime()) ? null : at;
+  }
+  if (kind === 'integer') {
+    const value = Number(text);
+    return Number.isFinite(value) ? value : text;
+  }
+  return text;
+};

package/src/aggregate-fold.ts

@@ -0,0 +1,91 @@
+// Single responsibility: compute an aggregate from ROWS ALREADY IN HAND — the in-memory driver's
+// half of `aggregate.ts`, split out because that file is the shared RULES (which kinds, which
+// refusals, the decimal arithmetic) and this one is one driver's execution of them.
+//
+// Every path here is exact. A `sum` goes through `sumDecimalText`, not `+`: the rows of a
+// `bigint()` or `decimal()` column are decimal STRINGS, and `Number()` on one loses digits past
+// 2^53 and cents below it — which is the whole reason those columns hand back text.
+
+import type { AggregateFn, MoneyUnit } from './aggregate';
+import { aggregateMinor, assertOneUnit, averageDecimalText, sumDecimalText } from './aggregate';
+import { valueAt } from './cursor';
+import type { EntityCore } from './entity';
+import { compareByKind } from './memory-match';
+import type { ColumnKind, MoneyValue } from './types';
+
+/** A row's value for this aggregate, or `undefined` for the absences SQL does not count. */
+const present = (value: unknown): boolean => value !== null && value !== undefined;
+
+const moneyOf = (value: unknown): MoneyValue | undefined => {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const record = value as Partial<MoneyValue>;
+  return typeof record.minor === 'number' && typeof record.currency === 'string'
+    ? (record as MoneyValue)
+    : undefined;
+};
+
+/** The text form a decimal aggregate adds. `integer` rows are numbers; every other kind is text. */
+const decimalText = (value: unknown): string =>
+  typeof value === 'bigint' ? value.toString() : String(value);
+
+/**
+ * `min`/`max` by the column's DECLARED kind, never by the JS type in hand — the rule this package
+ * decides every comparison with. `compareByKind` is the same function the sort and the keyset seek
+ * read, so a minimum here is the row a `.orderBy(col, 'asc').one()` would have answered with.
+ */
+const extreme = (kind: ColumnKind, values: readonly unknown[], fn: 'min' | 'max'): unknown =>
+  values.reduce((best, value) => {
+    const order = compareByKind(kind, value, best);
+    return (fn === 'min' ? order < 0 : order > 0) ? value : best;
+  });
+
+/**
+ * The aggregate, over exactly the rows the caller's predicate matched. `null` for an empty set in
+ * every function, because that is what SQL answers — never `0`, which would claim rows were seen.
+ */
+export const foldAggregate = <Row>(
+  entity: EntityCore<Row>,
+  fn: AggregateFn,
+  property: string,
+  kind: ColumnKind,
+  rows: readonly Row[],
+): unknown => {
+  const values = rows.map((row) => valueAt(row, property)).filter(present);
+  if (values.length === 0) return null;
+  if (kind === 'money') {
+    const amounts = values.flatMap((value) => {
+      const money = moneyOf(value);
+      return money === undefined ? [] : [money];
+    });
+    if (amounts.length === 0) return null;
+    const unit = assertOneUnit(
+      entity,
+      fn,
+      property,
+      amounts.map((money): MoneyUnit => ({ currency: money.currency, scale: money.scale ?? null })),
+    );
+    if (unit === undefined) return null;
+    const minor =
+      fn === 'sum'
+        ? aggregateMinor(
+            entity,
+            fn,
+            property,
+            sumDecimalText(amounts.map((money) => String(money.minor))) ?? '0',
+          )
+        : (extreme(
+            'integer',
+            amounts.map((money) => money.minor),
+            fn === 'min' ? 'min' : 'max',
+          ) as number);
+    return {
+      minor,
+      currency: unit.currency,
+      ...(unit.scale === null ? {} : { scale: unit.scale }),
+    } satisfies MoneyValue;
+  }
+  if (fn === 'sum') return sumDecimalText(values.map(decimalText));
+  if (fn === 'avg')
+    return averageDecimalText(sumDecimalText(values.map(decimalText)), values.length);
+  return extreme(kind, values, fn);
+};

package/src/aggregate.ts

@@ -0,0 +1,232 @@
+// Single responsibility: what an aggregate MEANS — which column kinds each function may be applied
+// to, what its answer is shaped like, and the exact arithmetic. Both drivers read it from here, so
+// a `sum` against memory means what a `sum` against Postgres means; a rule added to one driver
+// alone is the drift the two-driver split exists to prevent.
+//
+// Nothing here is a float. `sum` and `avg` answer decimal TEXT, money answers `MoneyValue` — the
+// same reason `bigint()` and `decimal()` hand back strings: a `number` loses digits past 2^53 and
+// a binary float loses cents.
+
+import { columnFor } from './column';
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import type { AnyColumn, ColumnKind } from './types';
+
+/** The four, closed. A fifth is a new member here and a new case in both drivers, never one. */
+export type AggregateFn = 'sum' | 'avg' | 'min' | 'max';
+
+/**
+ * Which kinds each function may be applied to. Closed sets rather than "whatever Postgres accepts",
+ * because the bar is what BOTH drivers can answer identically.
+ *
+ * `text` and `char` are deliberately absent from `min`/`max` even though Postgres has them: text
+ * ordering there is the database's COLLATION and here it is JS's UTF-16 code-unit order, and the
+ * two disagree on ordinary data (`'a' < 'B'` under `en_US`, `'B' < 'a'` by code unit). A comparison
+ * this package cannot make agree is refused rather than answered twice differently — the same
+ * decision `memory-match.ts` records for decimal text, in the other direction.
+ *
+ * `boolean`, `uuid`, `jsonb`, `array` and `bytea` are absent everywhere: none of them has an
+ * ordering or a sum a caller would mean.
+ */
+const NUMERIC: readonly ColumnKind[] = ['integer', 'bigint', 'numeric'];
+const ORDERED: readonly ColumnKind[] = ['integer', 'bigint', 'numeric', 'timestamptz', 'date'];
+
+const ALLOWED = new Map<AggregateFn, ReadonlySet<ColumnKind>>([
+  ['sum', new Set<ColumnKind>([...NUMERIC, 'money'])],
+  ['avg', new Set<ColumnKind>(NUMERIC)],
+  ['min', new Set<ColumnKind>([...ORDERED, 'money'])],
+  ['max', new Set<ColumnKind>([...ORDERED, 'money'])],
+]);
+
+export const aggregatable = (fn: AggregateFn, kind: ColumnKind): boolean =>
+  ALLOWED.get(fn)?.has(kind) === true;
+
+/**
+ * `avg` over money is refused rather than rounded. The average of 1, 1 and 2 minor units is 4/3 of
+ * a unit, and every representable answer is a rounding — which is the defect `MoneyValue.scale`
+ * exists to prevent, so inventing one at the aggregate would reopen it one layer up. The caller
+ * decides the rounding, out of two exact numbers.
+ */
+export const notAggregatable = (
+  entityName: string,
+  fn: AggregateFn,
+  property: string,
+  kind: ColumnKind,
+  candidates: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_AGGREGATE_UNSUPPORTED',
+    cause:
+      fn === 'avg' && kind === 'money'
+        ? `${entityName}.avg('${property}') — the mean of an integer number of minor units is not one, and every answer would be a silent rounding`
+        : `${entityName}.${fn}('${property}') — a ${kind} column has no ${fn} both drivers can answer the same way`,
+    fix:
+      fn === 'avg' && kind === 'money'
+        ? `${entityName}.sum('${property}') and ${entityName}.count() — divide at the call site, where the rounding is a decision somebody made`
+        : candidates.length === 0
+          ? `x entities describe ${entityName} --json   # this entity declares no column ${fn} can be applied to`
+          : `${entityName}.${fn}('${candidates[0]}')   # ${fn} takes one of: ${candidates.join(', ')}`,
+  });
+
+/**
+ * Money crossing currencies has no sum, no minimum and no maximum: 100 JPY and 100 EUR are not
+ * comparable and adding them answers a number in no currency at all. Both drivers count the
+ * distinct currencies of the rows they are about to aggregate and refuse past one, rather than
+ * silently answering in whichever currency happened to come first.
+ */
+export const mixedCurrency = (
+  entityName: string,
+  fn: AggregateFn,
+  property: string,
+  currencies: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_AGGREGATE_MIXED_CURRENCY',
+    cause: `${entityName}.${fn}('${property}') covers ${currencies.length} currencies (${[...currencies].sort().join(', ')}) — they have no common unit`,
+    fix: `${entityName}.andWhere('${property}.currency', 'eq', '${[...currencies].sort()[0]}').${fn}('${property}')   # one currency per call, or countBy('${property}.currency') first`,
+  });
+
+/** Digits only, optionally signed, optionally with a fraction. What `decimal()` hands back. */
+const DECIMAL_TEXT = /^-?\d+(\.\d+)?$/;
+
+/** The scale `avg` answers at, in both drivers. Fixed, so the two cannot round to different places. */
+export const AVG_SCALE = 6;
+
+interface Decimal {
+  readonly units: bigint;
+  readonly scale: number;
+}
+
+const parseDecimal = (text: string): Decimal | undefined => {
+  if (!DECIMAL_TEXT.test(text)) return undefined;
+  const [whole = '0', fraction = ''] = text.split('.');
+  return { units: BigInt(`${whole}${fraction}`), scale: fraction.length };
+};
+
+const rescale = (value: Decimal, scale: number): bigint =>
+  value.units * 10n ** BigInt(scale - value.scale);
+
+const render = (units: bigint, scale: number): string => {
+  if (scale === 0) return units.toString();
+  const negative = units < 0n;
+  const digits = (negative ? -units : units).toString().padStart(scale + 1, '0');
+  const whole = digits.slice(0, digits.length - scale);
+  return `${negative ? '-' : ''}${whole}.${digits.slice(digits.length - scale)}`;
+};
+
+/**
+ * The exact sum of decimal text, at the widest scale any term carries — which is what Postgres'
+ * `sum(numeric)` answers, and what no `Number()` can: `0.1 + 0.2` is `0.30000000000000004` in a
+ * binary float and `0.3` here, and an `int8` past 2^53 keeps every digit.
+ *
+ * `null` for an empty set, exactly as `sum` over no rows is NULL in SQL — never `0`, which would
+ * claim rows were counted.
+ */
+export const sumDecimalText = (values: readonly string[]): string | null => {
+  if (values.length === 0) return null;
+  const parsed = values.map(parseDecimal);
+  if (parsed.some((value) => value === undefined)) return null;
+  const decimals = parsed as readonly Decimal[];
+  const scale = decimals.reduce((widest, value) => Math.max(widest, value.scale), 0);
+  return render(
+    decimals.reduce((total, value) => total + rescale(value, scale), 0n),
+    scale,
+  );
+};
+
+/**
+ * `sum / count`, rounded half away from zero at `AVG_SCALE` — which is what Postgres' `round()`
+ * does to a `numeric`, and the reason the statement asks for `round(avg(...), 6)` rather than the
+ * server's own default scale: two drivers rounding at different places answer two numbers.
+ */
+export const averageDecimalText = (total: string | null, count: number): string | null => {
+  if (total === null || count === 0) return null;
+  const parsed = parseDecimal(total);
+  if (parsed === undefined) return null;
+  // The EXACT rational, rounded once. Dividing first and rounding after would truncate digits the
+  // rounding decision depends on — and rescaling to a fixed number of digits rather than to
+  // AVG_SCALE is what made this answer 11000.000000 where Postgres said 1.100000: `rescale` takes
+  // an absolute target scale, and the first draft handed it a relative one.
+  const digits = Math.max(parsed.scale, AVG_SCALE);
+  const numerator = rescale(parsed, digits);
+  const denominator = BigInt(count) * 10n ** BigInt(digits - AVG_SCALE);
+  const negative = numerator < 0n;
+  const magnitude = negative ? -numerator : numerator;
+  // `(2m + d) / 2d` is `floor(m/d + 1/2)` in integers — half AWAY FROM ZERO once the sign is put
+  // back, which is what Postgres' `round(numeric)` does. No float, no intermediate truncation.
+  const rounded = (2n * magnitude + denominator) / (2n * denominator);
+  return render(negative ? -rounded : rounded, AVG_SCALE);
+};
+
+/**
+ * The column an aggregate runs over, resolved and judged before either driver builds anything —
+ * so `sum('title')` is refused with the same words and the same code whichever driver is attached.
+ */
+export const aggregateColumnOf = <Row>(
+  entity: EntityCore<Row>,
+  fn: AggregateFn,
+  property: string,
+): AnyColumn => {
+  const candidates = Object.entries(entity.$columns)
+    .filter(([, each]) => aggregatable(fn, each.$meta.kind))
+    .map(([name]) => name);
+  const column = columnFor(entity.$columns, property);
+  if (column === undefined) {
+    throw notAggregatable(entity.$name, fn, property, 'text', candidates);
+  }
+  if (!aggregatable(fn, column.$meta.kind)) {
+    throw notAggregatable(entity.$name, fn, property, column.$meta.kind, candidates);
+  }
+  return column;
+};
+
+/** One amount is one currency at one scale. Two of either have no common unit. */
+export interface MoneyUnit {
+  readonly currency: string;
+  readonly scale: number | null;
+}
+
+export const assertOneUnit = <Row>(
+  entity: EntityCore<Row>,
+  fn: AggregateFn,
+  property: string,
+  units: readonly MoneyUnit[],
+): MoneyUnit | undefined => {
+  const seen = new Map<string, MoneyUnit>();
+  for (const unit of units) seen.set(`${unit.currency}/${unit.scale ?? ''}`, unit);
+  if (seen.size > 1) {
+    throw mixedCurrency(entity.$name, fn, property, [...seen.values()].map(unitLabel));
+  }
+  return [...seen.values()][0];
+};
+
+/**
+ * What the refusal names. The scale rides along because it is half of what makes two amounts
+ * incomparable: `{ minor: 5, currency: 'USD' }` is five cents and `{ minor: 5, currency: 'USD',
+ * scale: 6 }` is five millionths of a dollar, and adding them is a 10,000x error with no symptom.
+ */
+const unitLabel = (unit: MoneyUnit): string =>
+  unit.scale === null ? unit.currency : `${unit.currency}@${unit.scale}`;
+
+/**
+ * The minor unit an aggregate answers with, narrowed exactly where every other reader of that
+ * column narrows it. The column is `bigint` and `MoneyValue.minor` is a `number`, so a total past
+ * ±2^53 is a REFUSAL and never a rounded amount — the same bound `parseMinor` applies to one row,
+ * applied to the sum of many, where it is far easier to reach.
+ */
+export const aggregateMinor = <Row>(
+  entity: EntityCore<Row>,
+  fn: AggregateFn,
+  property: string,
+  total: string,
+): number => {
+  const units = BigInt(total);
+  if (units <= BigInt(Number.MAX_SAFE_INTEGER) && units >= BigInt(-Number.MAX_SAFE_INTEGER)) {
+    return Number(units);
+  }
+  throw new EntityError({
+    code: 'X_AGGREGATE_UNSUPPORTED',
+    cause: `${entity.$name}.${fn}('${property}') is ${total} minor units, past ±2^53 — no JS number holds it and MoneyValue.minor is one`,
+    fix: `${entity.$name}.andWhere(…).${fn}('${property}')   # narrow the rows, or read the total as text with a hand-written statement`,
+  });
+};

package/src/batch.ts

@@ -56,7 +56,8 @@ export const assertBatchable = <Row>(
   if (chain.limit !== undefined) throw limitedBatches(entity.$name, chain.limit, size);
   // The order the driver will sort by, primary key included: the cursor between two batches is
   // minted from it, and an ordering that cannot carry one fails on the batch *after* the first —
-  // where whatever size the caller happened to pass decides whether anyone ever finds out.
+  // where whatever size the caller happened to pass decides whether anyone ever finds out. A
+  // nullable column is NOT such an ordering `As of 2026-08-24`; a nullable primary-key column is.
   assertSeekable(entity, totalOrder(entity, chain.orderBy));
 };
 

package/src/column-values.ts

@@ -0,0 +1,29 @@
+// Two things every column builder needs and neither owns: how a rejected value is DESCRIBED, and
+// the CHECK a closed set of values emits. Here rather than in `columns.ts` so `enum-column.ts` can
+// read them without importing the file that imports it.
+
+import { describeValue } from '@ultimat3/schema';
+
+/**
+ * The rejected value, rendered as its SHAPE and never its content — `@ultimat3/schema`'s
+ * `describeValue`, the same renderer every builtin validator fails through, so a column and a
+ * schema describe one bad value the same way.
+ *
+ * WHY it is not `String(value)`: a column rejection is not a private diagnostic. It becomes
+ * `X_INVARIANT_VIOLATED`'s `cause` and a `$view` issue, which `@ultimat3/http` returns to the
+ * caller AND writes into the log line — and core's logger redacts by KEY, so a value baked into a
+ * message has no key left to redact. `text()` on a password field wrote the mistyped password to
+ * the central log index in cleartext and into the user's own network tab; a `uuid()` holding an
+ * API key surrogate does the same. A column is the worse half of that pair, because the value can
+ * arrive from the DATABASE — so the leak is not bounded by what someone just typed.
+ *
+ * `got` stays `got` and the "expected …" half is untouched: only what follows it changes.
+ */
+export const got = (value: unknown): string => `got ${describeValue(value)}`;
+
+const quote = (value: string): string => `'${value.replaceAll("'", "''")}'`;
+
+export const oneOf =
+  (values: readonly string[]) =>
+  (name: string): string =>
+    `${name} in (${values.map(quote).join(', ')})`;

package/src/column.ts

@@ -8,6 +8,7 @@
 
 import { invariantViolated } from './errors';
 import { refuseColumn } from './refuse';
+import { DEFAULT_SEARCH_WEIGHT, isSearchWeight } from './search';
 import type {
   AnyColumn,
   Column,
@@ -105,7 +106,12 @@ export const bindColumn = (column: AnyColumn, table: string, property: string):
         'build a new column instead of sharing one between entities',
     );
   }
-  const binding: Binding = { table, property, name: columnName(property, column.$meta) };
+  // The DERIVED name too, not only a declared one: `snake(property)` lower-cases and nothing else.
+  const binding: Binding = {
+    table,
+    property,
+    name: assertColumnName(columnName(property, column.$meta)),
+  };
   bindings.set(column, binding);
   return binding;
 };
@@ -176,6 +182,27 @@ export const makeColumn = <T, Optional extends boolean>(
 
   unique: () => makeColumn<T, Optional>({ ...meta, unique: true }, parse, optional),
 
+  searchable: (weight = DEFAULT_SEARCH_WEIGHT) => {
+    // Refused where the chain was written, because the alternative is a `to_tsvector` over a cast
+    // the DDL cannot express: `to_tsvector` takes text, and a `jsonb` or a `timestamptz` reaching
+    // it is a `42883` inside `ROLE=migrate`, with the server's words and none of the column's.
+    if (meta.kind !== 'text') {
+      refuseColumn(
+        'searchable',
+        `a ${meta.kind} column is not searchable — full text search reads text`,
+        'text().searchable() — index a text() column, and store the searchable projection of a structured value in one of its own',
+      );
+    }
+    if (!isSearchWeight(weight)) {
+      refuseColumn(
+        'searchable',
+        `"${String(weight)}" is not a search weight`,
+        "text().searchable('A') — one of A, B, C or D, biggest first; omit it for D",
+      );
+    }
+    return makeColumn<T, Optional>({ ...meta, searchable: weight }, parse, optional);
+  },
+
   tenant: () => makeColumn<T, Optional>({ ...meta, tenant: true, index: true }, parse, optional),
 
   references: (target, options = {}) =>
@@ -203,6 +230,15 @@ export const makeColumn = <T, Optional extends boolean>(
  * identifier. `[a-z_][a-z0-9_$]*`, which is what an unquoted Postgres identifier may be, and the
  * bound is the same 63 bytes the server truncates at — a longer one silently addresses a
  * different column.
+ *
+ * **Every physical name, not only a declared one — `As of 2026-08-24`.** `columnName` is
+ * `meta.name ?? snake(property)` and for three majors only the first branch reached here, so a
+ * PROPERTY name went into the DDL untouched: `snake()` lower-cases and does nothing else, and a
+ * column named `n" , "x" text); drop table t; --` produced a `create table` carrying a real
+ * `drop table` (measured through `generateMigration`). Quoting is not a defence against a value
+ * that can close the quote, which is what the paragraph above already said. `bindColumn` is where
+ * the derived name is checked, because that runs once per column at `entity()` rather than on
+ * every statement.
  */
 export const assertColumnName = (name: string): string => {
   if (!/^[a-z_][a-z0-9_$]*$/.test(name) || name.length > 63) {

package/src/columns.ts

@@ -5,7 +5,6 @@
 import { uuid as uuidV7 } from '@ultimat3/core';
 import {
   CURRENCY_CODE_PATTERN,
-  describeValue,
   isCurrencyCode,
   isMoneyScale,
   MAX_MONEY_SCALE,
@@ -19,6 +18,7 @@ import {
   makeColumn,
   makeTimestamp,
 } from './column';
+import { got, oneOf } from './column-values';
 import { refuseColumn } from './refuse';
 import type {
   Column,
@@ -31,23 +31,6 @@ import type {
   UuidColumn,
 } from './types';
 
-/**
- * The rejected value, rendered as its SHAPE and never its content — `@ultimat3/schema`'s
- * `describeValue`, the same renderer every builtin validator fails through, so a column and a
- * schema describe one bad value the same way.
- *
- * WHY it is not `String(value)`: a column rejection is not a private diagnostic. It becomes
- * `X_INVARIANT_VIOLATED`'s `cause` and a `$view` issue, which `@ultimat3/http` returns to the
- * caller AND writes into the log line — and core's logger redacts by KEY, so a value baked into a
- * message has no key left to redact. `text()` on a password field wrote the mistyped password to
- * the central log index in cleartext and into the user's own network tab; a `uuid()` holding an
- * API key surrogate does the same. A column is the worse half of that pair, because the value can
- * arrive from the DATABASE — so the leak is not bounded by what someone just typed.
- *
- * `got` stays `got` and the "expected …" half is untouched: only what follows it changes.
- */
-const got = (value: unknown): string => `got ${describeValue(value)}`;
-
 /** uuid v7: time-ordered, so a primary key index stays append-friendly. */
 export const newId = (): string => uuidV7();
 
@@ -152,34 +135,6 @@ const parseInstant = (value: unknown): Date => {
 export const timestamp = (): TimestampColumn =>
   makeTimestamp<false>({ ...BARE, kind: 'timestamptz' }, parseInstant, false);
 
-const quote = (value: string): string => `'${value.replaceAll("'", "''")}'`;
-
-const oneOf =
-  (values: readonly string[]) =>
-  (name: string): string =>
-    `${name} in (${values.map(quote).join(', ')})`;
-
-/**
- * A closed set of strings, emitted as a CHECK rather than a Postgres `ENUM` type: adding a
- * variant is then a one-line migration instead of `ALTER TYPE`, which cannot run inside a
- * transaction on older servers.
- */
-export const enumerated = <const V extends readonly string[]>(values: V): Column<V[number]> => {
-  const allowed = new Set<string>(values);
-  return column<V[number]>(
-    'text',
-    (value) =>
-      typeof value === 'string' && allowed.has(value)
-        ? value
-        : refuseColumn(
-            'enum',
-            `expected one of ${values.join(' | ')}, ${got(value)}`,
-            'store one of the values enumerated() declares, or add the new variant to that list and run x db gen "extend the enum check" — the values are a CHECK constraint, so the table moves with them',
-          ),
-    { values, check: oneOf(values) },
-  );
-};
-
 /**
  * An absolute http(s) URL, validated on write rather than on render: a bad URL stored once is
  * served to every reader, and `<img src>` fails silently in the browser.
@@ -454,3 +409,7 @@ export const currencyCheck = (currencyColumn: string): string =>
  */
 export const scaleCheck = (scaleColumn: string): string =>
   `${scaleColumn} is null or (${scaleColumn} >= 0 and ${scaleColumn} <= ${MAX_MONEY_SCALE})`;
+
+// `enumerated()` lives in `enum-column.ts` — it is the one builder with a chain of its own, and
+// splitting it is what kept this file under the ceiling. Re-exported so no caller had to move.
+export { enumerated } from './enum-column';

package/src/containment.ts

@@ -0,0 +1,94 @@
+// Single responsibility: what `@>`, `<@`, `&&` and a JSON key test MEAN, written once so the
+// in-memory driver answers what Postgres answers. A `jsonb` or an `arrayOf()` column was declared
+// and then unfilterable — the ten-operator vocabulary had nothing that could look inside one — so
+// an app with either had to leave the query language for hand-written SQL, which is the one path
+// in this framework with no tenancy guard on it.
+//
+// Every rule here is Postgres', reproduced rather than approximated. Where the two could not be
+// made to agree the operator is refused instead (`memory-match.ts`), never guessed at.
+
+/** Absent and NULL are one thing, exactly as they are to every other predicate. */
+const isNull = (value: unknown): boolean => value === null || value === undefined;
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Neither an object nor an array — which is exactly the set the top-level exception below covers. */
+const isScalar = (value: unknown): boolean => !isRecord(value) && !Array.isArray(value);
+
+/**
+ * Two ELEMENTS, equal. `===` plus the one case it gets wrong here: an `arrayOf(timestamp())` row
+ * holds `Date` objects, and two Dates for the same instant are two references — the same trap
+ * `sameValueOfKind` closes for a predicate, one operator along.
+ *
+ * Nothing deeper, and that is a property rather than an omission: `arrayOf()` refuses `jsonb`,
+ * `bytea`, `money` and a nested array at declaration, so an element is always a scalar or a Date.
+ */
+const sameElement = (left: unknown, right: unknown): boolean => {
+  if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  return left === right;
+};
+
+/**
+ * `left @> right` for `jsonb`, to the letter of Postgres' definition — each clause below measured
+ * on Postgres 16 rather than read off a summary, because three of them are easy to state wrongly:
+ *
+ * - two objects: every key of `right` is present in `left` and its value is contained by the one
+ *   there — recursively, which is what makes `data @> '{"a":{"b":1}}'` a NESTED match and why this
+ *   package ships no second path-expression language beside it (axiom 1).
+ * - two arrays: every element of `right` is contained by SOME element of `left`, which is why
+ *   `[1,2,3] @> [3,1]` holds and order never matters.
+ * - an array on the left and a PRIMITIVE on the right, **at the top level only**: `'[1,2]' @> '2'`
+ *   is true. Both halves of that sentence are load-bearing and both were wrong here first —
+ *   `'{"list":[1,2,3]}' @> '{"list":2}'` is FALSE (the exception does not recurse) and
+ *   `'[{"a":1}]' @> '{"a":1}'` is FALSE (it does not extend to composites).
+ * - anything else: element equality, which for a jsonb scalar is what it sounds like.
+ */
+export const jsonContains = (left: unknown, right: unknown): boolean => contains(left, right, true);
+
+const contains = (left: unknown, right: unknown, top: boolean): boolean => {
+  if (Array.isArray(left)) {
+    if (Array.isArray(right)) {
+      return right.every((item) => left.some((candidate) => contains(candidate, item, false)));
+    }
+    return top && isScalar(right) && left.some((candidate) => sameElement(candidate, right));
+  }
+  if (isRecord(left) && isRecord(right)) {
+    return Object.keys(right).every(
+      (key) => Object.hasOwn(left, key) && contains(left[key], right[key], false),
+    );
+  }
+  return isScalar(left) && isScalar(right) && sameElement(left, right);
+};
+
+/**
+ * `left @> right` for a SQL array, which is a different operator with a different rule: element
+ * containment is plain equality, never the recursive one above, because an array's elements are
+ * scalars of one declared type rather than arbitrary JSON. An empty right-hand side is contained
+ * by every array, which is what Postgres answers.
+ */
+export const arrayContains = (left: readonly unknown[], right: readonly unknown[]): boolean =>
+  right.every((item) => left.some((candidate) => sameElement(candidate, item)));
+
+/**
+ * `left && right`: they share at least one element. Arrays only — `jsonb` has no `&&` — and the
+ * bound is the opposite way round from `@>`: an EMPTY operand overlaps nothing, where it is
+ * contained by everything.
+ */
+export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[]): boolean =>
+  right.some((item) => left.some((candidate) => sameElement(candidate, item)));
+
+/**
+ * `jsonb_exists(value, key)` — the function form of the `?` operator, which is what the SQL side
+ * emits so a literal `?` can never be read as a parameter placeholder by anything on the way.
+ *
+ * Three shapes, all of them Postgres': a top-level key of an object, a string ELEMENT of an array,
+ * and a string value equal to the key. A number never matches — `jsonb_exists('[1]', '1')` is
+ * false there, and a `String(item) === key` here would have made it true.
+ */
+export const jsonHasKey = (value: unknown, key: unknown): boolean => {
+  if (typeof key !== 'string' || isNull(value)) return false;
+  if (Array.isArray(value)) return value.some((item) => item === key);
+  if (isRecord(value)) return Object.hasOwn(value, key);
+  return value === key;
+};