@ultimat3/entity 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -742,6 +742,21 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   first would turn one statement into two and change what the code under test issues — so a count is
   reported and a consumer re-reads. It is NOT a second change-feed path: `selectChangeFeed` still
   decides what a real node reads, and this is never in that decision.
+- **A refusal raised before any entity exists carries an EDIT, never a lookup** — `refuse.ts`,
+  `As of 2026-08-22`. Both `reject()` helpers called `invariantViolated('column', rule, detail)`,
+  whose fix is `x entities describe <entityName> --json`, so 34 column and invariant refusals
+  emitted `x entities describe column --json` — which answers `X_DECLARATION_UNKNOWN`, because no
+  entity is named `column` and at declaration time there is no entity at all. A fix line that
+  raises a second, unrelated error is worse than none: the reader debugs the wrong subsystem, and
+  an agent follows it literally. So the fix is a PARAMETER — `refuseColumn(rule, detail, fix)` —
+  and every site names the column form the author should have written, the shape
+  `arrayElementRefused` already had. **`invariantViolated`'s entity name is a value, never a
+  literal**, and `refuse.test.ts` scans this package's source for one; it also holds every refusal
+  to naming a call or a command, carrying no `<placeholder>`, and having a case in its own table,
+  so a refusal added without a repair is a failing test. **The two builders construct their
+  `EntityError` inline** rather than delegating to a shared one, because `fix-scan.ts` reads a fix
+  literal only at a call site whose callee builds the error itself — a wrapper would take all 34
+  fix lines back out of `x verify`'s `errors` step (measured: `checked` 1040 -> 1071).
 - Never throw a bare `Error` — use `errors.ts`.
 - Tests restore the process-global registry in `afterAll` (`clearRegistry()`): a leaked registry
   breaks an unrelated package's tests, as it did in `@ultimat3/policy`.
@@ -753,6 +768,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `types.ts` | `Column`, `RowOf`, `Insertable`, `IdOf` — the type derivation. `COLUMN_KINDS` is the runtime array `ColumnKind` DERIVES from (the shape core's `PRIMITIVE_KINDS` uses), so a package answering "one case per kind" reads a real list rather than spelling its own |
 | `column.ts` / `columns.ts` | the chain + property-key binding; the blessed builders; `columnName`/`moneyColumns`, the ONE physical-name resolver; `narrowMoney`, the one write-side narrowing both drivers run |
 | `columns-data.ts` | the wide vocabulary an existing schema needs: `json`, `decimal`, `date`, `bigint`, `bytes`, `arrayOf` |
+| `array-element.ts` | which element kinds `arrayOf()` refuses, and the one-line edit that repairs each |
+| `refuse.ts` | `refuseColumn`/`refuseInvariant` — the refusals raised before any entity exists, each carrying the EDIT that repairs it |
 | `expr.ts` / `invariants.ts` | the `invariants: (c) => …` rule language; bind + `toSql()` DDL |
 | `entity.ts` / `describe.ts` | `entity()`, `$row`; the `EntityDescription` projection |
 | `view.ts` | `$view(keys)` — the row projection an action names as its `output` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "7.0.0",
+  "version": "9.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "7.0.0",
-    "@ultimat3/db": "7.0.0",
-    "@ultimat3/schema": "7.0.0",
-    "@ultimat3/time": "7.0.0"
+    "@ultimat3/core": "9.0.0",
+    "@ultimat3/db": "9.0.0",
+    "@ultimat3/schema": "9.0.0",
+    "@ultimat3/time": "9.0.0"
   }
 }

package/src/array-element.ts

@@ -0,0 +1,67 @@
+// Which element kinds `arrayOf()` refuses, and the one-line edit that repairs each. Split from
+// `columns-data.ts`, which parses columns: a refusal POLICY and four repair strings are a second
+// responsibility, and the file was 250 lines with both in it.
+
+import { EntityError } from './errors';
+
+/** The element kinds `arrayElement` (`pg-row.ts`) has no literal for, and why each one is refused. */
+const ARRAY_ELEMENT_REFUSED = ['money', 'array', 'jsonb', 'bytea'] as const;
+
+export type RefusedElement = (typeof ARRAY_ELEMENT_REFUSED)[number];
+
+export const isRefusedElement = (kind: string): kind is RefusedElement =>
+  (ARRAY_ELEMENT_REFUSED as readonly string[]).includes(kind);
+
+/**
+ * One column per refused element kind: the shape that holds the same list and can be written.
+ * `Object.freeze<Record<K, V>>` and never `Readonly<Record<K, V>> = Object.freeze({…})`, which
+ * infers the key set from the literal and would accept a fifth key in silence.
+ *
+ * Each value is a MECHANICAL edit with nothing for the reader to supply — the placeholder form
+ * `json(t.array(<element schema>))` was the defect: a `fix:` a reader has to complete is one they
+ * can complete wrongly, and `<element schema>` pasted verbatim is a syntax error. The two that
+ * need a second table name it (`amounts`, `blobs`) rather than saying "a child table", so every
+ * line is text that runs.
+ */
+const ARRAY_ELEMENT_FIXES = Object.freeze<Record<RefusedElement, string>>({
+  money:
+    'move the list to its own entity and relate it — ' +
+    "entity('amounts', { columns: { amount: money() } }) — then drop this column: an array column " +
+    'is ONE column and money() is three (minor, currency, scale)',
+  array:
+    'rewrite arrayOf(arrayOf(x)) as arrayOf(x) if the nesting carries no meaning, or move the ' +
+    "inner list to its own entity and relate it — entity('items', { columns: { value: text() } })",
+  jsonb:
+    'rewrite arrayOf(json(S)) as json(t.array(S)) with S unchanged — one jsonb column holds the ' +
+    'whole list and t.array still validates every member',
+  bytea:
+    'move the list to its own entity and relate it — ' +
+    "entity('blobs', { columns: { data: bytes() } }) — then drop this column: one row per blob, " +
+    'and bytea has no array literal that survives the driver',
+});
+
+/**
+ * An element the Postgres array literal cannot carry, refused where the schema is still being
+ * written. Two different reasons, one code — the situation is a single one, "this list needs a
+ * different column" — so only the cause and the fix branch.
+ *
+ * `money` and `array` are not ONE column: three physical columns for an amount, and a nested array
+ * has no unambiguous literal form. `jsonb` and `bytea` are one column each and were the silent
+ * half: `arrayElement` renders any object as `""`, so two objects bound as `{"",""}` and one blob
+ * as `{""}` (measured), while `memoryRepo` kept the value — a loss no test in this tree could see
+ * and only a table could show.
+ *
+ * Not `reject()`: a declaration is repaired by an EDIT, and `reject`'s
+ * `x entities describe column --json` is `X_DECLARATION_UNKNOWN` — no entity is named `column`, and
+ * there is no entity at all yet. So each fix is the edit that holds the list instead.
+ */
+export const arrayElementRefused = (kind: RefusedElement): EntityError => {
+  const singleColumn = kind === 'money' || kind === 'array';
+  return new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: singleColumn
+      ? `arrayOf(${kind}) has no single column behind it — an array element is one scalar column, and ${kind === 'money' ? 'money is three (minor, currency, scale)' : 'a nested array has no unambiguous literal form'}`
+      : `arrayOf(${kind}) has no array literal form — every element would cross to Postgres as an empty string while memoryRepo kept the value, so the loss is invisible until the row is read back`,
+    fix: ARRAY_ELEMENT_FIXES[kind],
+  });
+};

package/src/column.ts

@@ -7,6 +7,7 @@
 // physical name even though two schema modules import each other in a cycle.
 
 import { invariantViolated } from './errors';
+import { refuseColumn } from './refuse';
 import type {
   AnyColumn,
   Column,
@@ -140,10 +141,10 @@ const literal = (value: unknown): ColumnDefault => {
   if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
     return { kind: 'value', value };
   }
-  throw invariantViolated(
-    'column',
+  return refuseColumn(
     'default',
-    `a default must be a literal; got ${typeof value}. For an instant use timestamp().defaultNow()`,
+    `a default must be a literal; got ${typeof value}`,
+    ".default('draft'), .default(0) or .default(false) — a literal the DDL can carry; for an instant use timestamp().defaultNow(), and a computed default belongs in the insert",
   );
 };
 
@@ -205,10 +206,10 @@ export const makeColumn = <T, Optional extends boolean>(
  */
 export const assertColumnName = (name: string): string => {
   if (!/^[a-z_][a-z0-9_$]*$/.test(name) || name.length > 63) {
-    throw invariantViolated(
-      'column',
+    refuseColumn(
       'column-name',
       `"${name}" is not a physical column name: lower-case letters, digits and underscores, at most 63 of them`,
+      ".column('created_at') — lower-case letters, digits and underscores, at most 63 of them",
     );
   }
   return name;

package/src/columns-data.ts

@@ -10,14 +10,11 @@
 
 import { describeValue, formatIssues, type StandardSchemaV1, validate } from '@ultimat3/schema';
 import { isPlainDate, type PlainDate, plainDateUtc } from '@ultimat3/time';
+import { arrayElementRefused, isRefusedElement } from './array-element';
 import { column } from './column';
-import { invariantViolated } from './errors';
+import { refuseColumn } from './refuse';
 import type { AnyColumn, Column, ColumnMeta } from './types';
 
-const reject = (rule: string, detail: string): never => {
-  throw invariantViolated('column', rule, detail);
-};
-
 /** The rejected value as its SHAPE, never its content — `columns.ts` explains why at length. */
 const got = (value: unknown): string => `got ${describeValue(value)}`;
 
@@ -27,9 +24,13 @@ const got = (value: unknown): string => `got ${describeValue(value)}`;
  * place for one — the value arrives from the DATABASE as often as from a caller, so the row type
  * would be a claim nothing ever checked.
  *
- * The object is bound as an object, never as a string: a JSON string parameter is stored as a JSON
- * *string* by Postgres (measured — `'{"a":1}'` comes back as the text, not the object), so
- * stringifying here would change the value's type in the table.
+ * The value crosses to Postgres as TEXT and is cast back — `bindValues` calls `JSON.stringify` and
+ * `cellCast` (`pg-sql.ts`) writes `::text::jsonb` — and both halves are load-bearing. The driver
+ * seam refuses a plain object as a parameter (`X_SQL_UNSAFE`), so the object cannot cross as
+ * itself; and under a bare `$1::jsonb` the server describes the parameter as `jsonb`, Bun's `sql`
+ * JSON-ENCODES the string it was handed, and `{"a":1}` lands as a JSON *string* — `jsonb_typeof`
+ * answers `string` (measured, Postgres 17.10). Pinning the parameter to `text` first is what makes
+ * the server parse the characters, so neither half may be changed without the other.
  */
 export const json = <T>(schema: StandardSchemaV1<unknown, T>): Column<T> =>
   column<T>('jsonb', (value) => {
@@ -37,9 +38,10 @@ export const json = <T>(schema: StandardSchemaV1<unknown, T>): Column<T> =>
     if (result.issues === undefined) return result.value;
     // The ISSUES, never the value: `formatIssues` renders path + message, and a column rejection
     // reaches the caller and the log line where a value has no key left to redact.
-    return reject(
+    return refuseColumn(
       'json',
       `does not match the column's schema — ${formatIssues(result.issues).join('; ')}`,
+      'correct the key the cause names, or widen the schema this column was declared with — json(t.object({ seats: t.number })) validates on the way in and on the way back',
     );
   });
 
@@ -62,14 +64,19 @@ export const bigint = (): Column<string> =>
     if (typeof value === 'number') {
       return Number.isSafeInteger(value)
         ? String(value)
-        : reject(
+        : refuseColumn(
             'bigint',
-            `${String(value)} is past ±2^53, where a JS number is no longer exact — pass the digits as a string`,
+            `${String(value)} is past ±2^53, where a JS number is no longer exact`,
+            "quote the digits — bigint() takes and returns a decimal string, so pass '9007199254740993' rather than a number literal",
           );
     }
     return typeof value === 'string' && DIGITS.test(value)
       ? value
-      : reject('bigint', `expected whole digits, ${got(value)}`);
+      : refuseColumn(
+          'bigint',
+          `expected whole digits, ${got(value)}`,
+          'String(value) when it is already whole digits — a fractional value is decimal({ precision: 18, scale: 8 }) and an amount is money()',
+        );
   });
 
 export interface DecimalOptions {
@@ -91,14 +98,26 @@ export interface DecimalOptions {
 export const decimal = (options: DecimalOptions = {}): Column<string> => {
   const { precision, scale } = options;
   if ((precision === undefined) !== (scale === undefined)) {
-    reject('numeric', 'precision and scale are declared together — numeric(18, 8), or neither');
+    refuseColumn(
+      'numeric',
+      'precision and scale are declared together — numeric(18, 8), or neither',
+      'decimal({ precision: 18, scale: 8 }) — both keys together, or decimal() for an unbounded numeric',
+    );
   }
   if (precision !== undefined && scale !== undefined) {
     if (!Number.isInteger(precision) || precision < 1 || precision > 1000) {
-      reject('numeric', `precision must be 1..1000, ${got(precision)}`);
+      refuseColumn(
+        'numeric',
+        `precision must be 1..1000, ${got(precision)}`,
+        'decimal({ precision: 18, scale: 8 }) — precision is the TOTAL digit count, from 1 to 1000',
+      );
     }
     if (!Number.isInteger(scale) || scale < 0 || scale > precision) {
-      reject('numeric', `scale must be 0..precision, ${got(scale)}`);
+      refuseColumn(
+        'numeric',
+        `scale must be 0..precision, ${got(scale)}`,
+        `decimal({ precision: ${precision}, scale: ${Math.min(2, precision)} }) — scale counts the digits AFTER the point and cannot exceed precision`,
+      );
     }
   }
   const shape = /^-?\d+(\.\d+)?$/;
@@ -107,21 +126,28 @@ export const decimal = (options: DecimalOptions = {}): Column<string> => {
     (value) => {
       const text = typeof value === 'number' ? decimalOfNumber(value) : value;
       if (typeof text !== 'string' || !shape.test(text)) {
-        return reject('numeric', `expected a decimal number, ${got(value)}`);
+        return refuseColumn(
+          'numeric',
+          `expected a decimal number, ${got(value)}`,
+          "pass the digits as a string — decimal() holds an exact decimal, so write '1.25'; a float is taken only where String(value) is already exact",
+        );
       }
       const digits = text.replace('-', '').split('.');
       const fraction = digits[1]?.length ?? 0;
       if (scale !== undefined && fraction > scale) {
-        return reject(
+        return refuseColumn(
           'numeric',
           `${text} has ${fraction} decimal places and the column stores ${scale} — Postgres would round it, silently`,
+          `Number(value).toFixed(${scale}) at the call site decides the rounding, or widen the column to decimal({ precision: ${(precision ?? fraction) + fraction - scale}, scale: ${fraction} }) and run x db gen "widen the numeric"`,
         );
       }
-      if (
-        precision !== undefined &&
-        (digits[0] ?? '').replace(/^0+(?=\d)/, '').length > precision - (scale ?? 0)
-      ) {
-        return reject('numeric', `${text} does not fit numeric(${precision}, ${scale ?? 0})`);
+      const whole = (digits[0] ?? '').replace(/^0+(?=\d)/, '').length;
+      if (precision !== undefined && whole > precision - (scale ?? 0)) {
+        return refuseColumn(
+          'numeric',
+          `${text} does not fit numeric(${precision}, ${scale ?? 0})`,
+          `widen the column — decimal({ precision: ${whole + (scale ?? 0)}, scale: ${scale ?? 0} }) — and run x db gen "widen the numeric": what overflows is the digits BEFORE the point`,
+        );
       }
       return text;
     },
@@ -152,12 +178,20 @@ export const date = (): Column<PlainDate> =>
   column<PlainDate>('date', (value) => {
     if (value instanceof Date) {
       return Number.isNaN(value.getTime())
-        ? reject('date', `expected a calendar date, ${got(value)}`)
+        ? refuseColumn(
+            'date',
+            `expected a calendar date, ${got(value)}`,
+            "pass a Date built from a real value — new Date('2026-08-22'); new Date(undefined) and a failed parse both produce the Invalid Date this refuses",
+          )
         : plainDateUtc(value);
     }
     return isPlainDate(value)
       ? value
-      : reject('date', `expected a YYYY-MM-DD calendar date, ${got(value)}`);
+      : refuseColumn(
+          'date',
+          `expected a YYYY-MM-DD calendar date, ${got(value)}`,
+          "pass '2026-08-22' or a Date — date() stores a calendar date with no clock and no zone; an instant is timestamp()",
+        );
   });
 
 /**
@@ -169,7 +203,11 @@ export const date = (): Column<PlainDate> =>
 export const bytes = (): Column<Uint8Array> =>
   column<Uint8Array>('bytea', (value) => {
     if (!(value instanceof Uint8Array)) {
-      return reject('bytea', `expected bytes, ${got(value)}`);
+      return refuseColumn(
+        'bytea',
+        `expected bytes, ${got(value)}`,
+        "Buffer.from(value, 'base64') for base64 and new TextEncoder().encode(value) for text — bytes() stores a Uint8Array; a structured payload is json(schema)",
+      );
     }
     // Already the plain form: the overwhelmingly common case, and it costs one prototype read.
     return Object.getPrototypeOf(value) === Uint8Array.prototype ? value : new Uint8Array(value);
@@ -180,21 +218,21 @@ export const bytes = (): Column<Uint8Array> =>
  * `$parse` decides every member: `arrayOf(text({ max: 40 }))` refuses a 41-character tag exactly
  * where a `text()` column would.
  *
- * Money and arrays of arrays are refused rather than approximated: money is three physical columns
- * and cannot be one array element, and a nested array has no unambiguous literal form.
+ * Four element kinds are refused rather than approximated — see `arrayElementRefused`.
  */
 export const arrayOf = <T>(element: Column<T>): Column<readonly T[]> => {
   const kind = element.$meta.kind;
-  if (kind === 'money' || kind === 'array') {
-    reject(
-      'array',
-      `arrayOf(${kind}) has no single column behind it — an array element is one scalar column`,
-    );
-  }
+  if (isRefusedElement(kind)) throw arrayElementRefused(kind);
   return column<readonly T[]>(
     'array',
     (value) => {
-      if (!Array.isArray(value)) return reject('array', `expected an array, ${got(value)}`);
+      if (!Array.isArray(value)) {
+        return refuseColumn(
+          'array',
+          `expected an array, ${got(value)}`,
+          'wrap it — [value] — or drop arrayOf() and declare the element column on its own when the table holds one scalar',
+        );
+      }
       return value.map((member) => element.$parse(member));
     },
     { element: element as AnyColumn },

package/src/columns.ts

@@ -19,7 +19,7 @@ import {
   makeColumn,
   makeTimestamp,
 } from './column';
-import { invariantViolated } from './errors';
+import { refuseColumn } from './refuse';
 import type {
   Column,
   ColumnMap,
@@ -31,10 +31,6 @@ import type {
   UuidColumn,
 } from './types';
 
-const reject = (rule: string, detail: string): never => {
-  throw invariantViolated('column', rule, detail);
-};
-
 /**
  * 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
@@ -60,7 +56,11 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const parseUuid = (value: unknown): string =>
   typeof value === 'string' && UUID.test(value)
     ? value
-    : reject('format', `expected a uuid, ${got(value)}`);
+    : refuseColumn(
+        'format',
+        `expected a uuid, ${got(value)}`,
+        'newId() mints a uuid v7, and a reference carries the exact id the target row was inserted with — a natural key that is not a uuid is text(), a legacy int8 key is bigint()',
+      );
 
 /**
  * The one place a brand is applied. A brand is a compile-time tag with no runtime witness, so
@@ -101,7 +101,13 @@ export const text = (options: TextOptions = {}): Column<string> =>
   column<string>(
     'text',
     (value) =>
-      typeof value === 'string' ? value : reject('type', `expected a string, ${got(value)}`),
+      typeof value === 'string'
+        ? value
+        : refuseColumn(
+            'type',
+            `expected a string, ${got(value)}`,
+            'String(value) at the call site when this really is text — a number column is integer(), an exact decimal is decimal(), a structured payload is json(schema)',
+          ),
     options.max === undefined
       ? {}
       : { length: options.max, check: (name) => `char_length(${name}) <= ${options.max}` },
@@ -111,12 +117,22 @@ export const integer = (): Column<number> =>
   column<number>('integer', (value) =>
     typeof value === 'number' && Number.isSafeInteger(value)
       ? value
-      : reject('type', `expected a safe integer, ${got(value)}`),
+      : refuseColumn(
+          'type',
+          `expected a safe integer, ${got(value)}`,
+          'Math.trunc(value) for a float and Number(value) for a numeric string — a count past ±2^53 is bigint(), a fractional value is decimal()',
+        ),
   );
 
 export const boolean = (): Column<boolean> =>
   column<boolean>('boolean', (value) =>
-    typeof value === 'boolean' ? value : reject('type', `expected a boolean, ${got(value)}`),
+    typeof value === 'boolean'
+      ? value
+      : refuseColumn(
+          'type',
+          `expected a boolean, ${got(value)}`,
+          "value === 'true' at the call site for a text flag, and boolean().nullable() when the column has a third state",
+        ),
   );
 
 const parseInstant = (value: unknown): Date => {
@@ -125,7 +141,11 @@ const parseInstant = (value: unknown): Date => {
     const parsed = new Date(value);
     if (!Number.isNaN(parsed.getTime())) return parsed;
   }
-  return reject('format', `expected a UTC instant, ${got(value)}`);
+  return refuseColumn(
+    'format',
+    `expected a UTC instant, ${got(value)}`,
+    'new Date(value) at the call site — timestamp() stores an instant; a calendar date with no clock is date(), and an elapsed span is integer()',
+  );
 };
 
 /** Always `timestamptz`. UTC storage is not a per-table decision. */
@@ -151,7 +171,11 @@ export const enumerated = <const V extends readonly string[]>(values: V): Column
     (value) =>
       typeof value === 'string' && allowed.has(value)
         ? value
-        : reject('enum', `expected one of ${values.join(' | ')}, ${got(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) },
   );
 };
@@ -172,7 +196,11 @@ export const url = (): Column<string> =>
           // fall through to the shared rejection so the error names the rule
         }
       }
-      return reject('format', `expected an absolute http(s) URL, ${got(value)}`);
+      return refuseColumn(
+        'format',
+        `expected an absolute http(s) URL, ${got(value)}`,
+        'prefix the value with https:// — url() stores an absolute http(s) URL; a path, a template or a mailto: address is text()',
+      );
     },
     { check: (name) => `${name} ~ '^https?://'` },
   );
@@ -192,7 +220,13 @@ export const url = (): Column<string> =>
  */
 export const tz = <const Z extends readonly string[]>(zones: Z): Column<Z[number]> => {
   for (const zone of zones) {
-    if (!isValidTimeZone(zone)) reject('iana-tz', `${zone} is not an IANA time zone`);
+    if (!isValidTimeZone(zone)) {
+      refuseColumn(
+        'iana-tz',
+        `${zone} is not an IANA time zone`,
+        "tz(['Europe/Bucharest']) — an IANA region/city name. An abbreviation (CET, EST) or an offset (+02:00) carries no DST rule; Intl.supportedValuesOf('timeZone') lists every name this accepts",
+      );
+    }
   }
   const allowed = new Set<string>(zones);
   return column<Z[number]>(
@@ -200,7 +234,11 @@ export const tz = <const Z extends readonly string[]>(zones: Z): Column<Z[number
     (value) =>
       typeof value === 'string' && allowed.has(value)
         ? value
-        : reject('iana-tz', `expected one of ${zones.join(' | ')}, ${got(value)}`),
+        : refuseColumn(
+            'iana-tz',
+            `expected one of ${zones.join(' | ')}, ${got(value)}`,
+            'store one of the zones tz() declares, or add it to that list and run x db gen "extend the time zone check" — the zones are a CHECK constraint',
+          ),
     { values: zones, check: oneOf(zones) },
   );
 };
@@ -209,7 +247,13 @@ const BCP47 = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
 
 export const locale = <const L extends readonly string[]>(locales: L): Column<L[number]> => {
   for (const tag of locales) {
-    if (!BCP47.test(tag)) reject('bcp-47', `${tag} is not a BCP-47 language tag`);
+    if (!BCP47.test(tag)) {
+      refuseColumn(
+        'bcp-47',
+        `${tag} is not a BCP-47 language tag`,
+        "locale(['en', 'en-GB', 'pt-BR']) — a 2-3 letter language, then optional subtags after a hyphen",
+      );
+    }
   }
   const allowed = new Set<string>(locales);
   return column<L[number]>(
@@ -217,7 +261,11 @@ export const locale = <const L extends readonly string[]>(locales: L): Column<L[
     (value) =>
       typeof value === 'string' && allowed.has(value)
         ? value
-        : reject('bcp-47', `expected one of ${locales.join(' | ')}, ${got(value)}`),
+        : refuseColumn(
+            'bcp-47',
+            `expected one of ${locales.join(' | ')}, ${got(value)}`,
+            'store one of the tags locale() declares, or add it to that list and run x db gen "extend the locale check" — the tags are a CHECK constraint',
+          ),
     { values: locales, check: oneOf(locales) },
   );
 };
@@ -240,19 +288,25 @@ const parseMinor = (value: unknown): number => {
       ? Number(value)
       : value;
   if (typeof minor !== 'number' || !Number.isFinite(minor)) {
-    return reject('money-minor-units', `expected integer minor units, ${got(value)}`);
+    return refuseColumn(
+      'money-minor-units',
+      `expected integer minor units, ${got(value)}`,
+      "pass integer minor units — { minor: 1234, currency: 'EUR' } is 12.34 EUR; a formatted amount is text() and an exact decimal is decimal()",
+    );
   }
   if (!Number.isInteger(minor)) {
-    return reject(
+    return refuseColumn(
       'money-minor-units',
       `got the float ${minor}; money is integer minor units — 12.34 EUR is 1234, not 12.34`,
+      "{ minor: Math.round(amount * 100), currency: 'EUR' } at the call site converts the major-unit amount and decides the rounding, or name the precision instead: { minor: 1250000, currency: 'EUR', scale: 6 } is 1.25 EUR at six decimal places",
     );
   }
   if (!Number.isSafeInteger(minor)) {
-    return reject(
+    return refuseColumn(
       'money-minor-units',
       `${String(value)} is past ±2^53 and no JS number holds it exactly — money is minor units ` +
-        'inside that range; store the overflow in its own column or split the amount',
+        'inside that range',
+      "split the amount across rows, or hold the digits beside it in a bigint() column — money()'s minor is a number so JSON.stringify carries it, and no JS number holds this one exactly",
     );
   }
   return minor;
@@ -267,7 +321,11 @@ const parseMinor = (value: unknown): number => {
 const parseCurrency = (value: unknown): string =>
   isCurrencyCode(value)
     ? value
-    : reject('iso-4217', `expected a 3-letter ISO-4217 code, ${got(value)}`);
+    : refuseColumn(
+        'iso-4217',
+        `expected a 3-letter ISO-4217 code, ${got(value)}`,
+        "pass money() a 3-letter uppercase ISO-4217 code — { minor: 1234, currency: 'EUR' }; a symbol or a currency name is not one",
+      );
 
 /**
  * The decimal exponent `minor` counts in, when it is not the currency's own. `undefined` and `0`
@@ -279,15 +337,20 @@ const parseScale = (value: unknown): number => {
   const scale = typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : value;
   return isMoneyScale(scale)
     ? scale
-    : reject(
+    : refuseColumn(
         'money-scale',
         `expected a whole number of decimal places between 0 and ${MAX_MONEY_SCALE}, ${got(value)}`,
+        `omit scale for the currency's own minor unit, or pass money() a whole number of decimal places from 0 to ${MAX_MONEY_SCALE} — { minor: 1250000, currency: 'EUR', scale: 6 }`,
       );
 };
 
 const parseMoney = (value: unknown): MoneyValue => {
   if (typeof value !== 'object' || value === null) {
-    return reject('money', `expected { minor, currency }, ${got(value)}`);
+    return refuseColumn(
+      'money',
+      `expected { minor, currency }, ${got(value)}`,
+      "{ minor: 1234, currency: 'EUR' } — money() is always both parts; a bare amount is integer() or decimal(), and a formatted string is text()",
+    );
   }
   const input: Partial<MoneyInput> = value;
   return {

package/src/describe.ts

@@ -67,9 +67,13 @@ export const sqlTypeOf = (meta: ColumnMeta): string => {
   }
   if (meta.kind === 'array') {
     const element = meta.element?.$meta;
-    // `arrayOf` refuses an element that is not one scalar column, so this is total in practice;
-    // `text[]` is the answer that keeps a description renderable rather than throwing inside a
-    // projection, which is the one place an error has no caller to instruct.
+    // The element KIND is bounded by `arrayOf`, which refuses money, a nested array, `jsonb` and
+    // `bytea` at declaration — it refused only the first two until 2026-08, so this line emitted a
+    // real `jsonb[]`/`bytea[]` for a column `bindValues` wrote as `{"",""}`: a DDL type for a value
+    // that could not survive the trip. What is NOT bounded is `element` itself, which is absent on
+    // any `ColumnMeta` nobody built through `arrayOf()`; `text[]` keeps such a description
+    // renderable rather than throwing inside a projection, the one place an error has no caller to
+    // instruct.
     return `${element === undefined ? 'text' : sqlTypeOf(element)}[]`;
   }
   return meta.kind;

package/src/errors.ts

@@ -113,6 +113,13 @@ export const entityDuplicate = (name: string, existingTable: string): EntityErro
     fix: `x entities list --json   # then rename one of the two entity({ name }) declarations`,
   });
 
+/**
+ * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
+ * given. A literal is an entity that does not exist, and this fix then hands the reader
+ * `x entities describe column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
+ * refusal raised before any entity exists belongs in `refuse.ts`, where the caller supplies the
+ * edit; `refuse.test.ts` fails on a literal here.
+ */
 export const invariantViolated = (
   entityName: string,
   invariantName: string,

package/src/expr.ts

@@ -9,6 +9,7 @@
 // does not know this rule — silently pretending it reached Postgres would be worse.
 
 import { invariantViolated } from './errors';
+import { refuseInvariant } from './refuse';
 import type { ColumnMap } from './types';
 
 export type Row = Readonly<Record<string, unknown>>;
@@ -93,12 +94,13 @@ const literal = (value: unknown): string =>
 const matchOperator = (pattern: RegExp): string => {
   const flags = pattern.flags.replaceAll('i', '');
   if (flags !== '') {
-    throw invariantViolated(
-      'invariant',
+    // The pasted predicate drops `g` and `y`: `.test()` under either advances `lastIndex`, so the
+    // rule would stop being a function of the row — the same reason the CHECK cannot carry them.
+    refuseInvariant(
       'matches',
       `/${pattern.source}/${pattern.flags} carries the flag${flags.length === 1 ? '' : 's'} ` +
-        `"${flags}", which Postgres has no operator for — drop it and fold the behaviour into ` +
-        `the pattern, or pass a function instead: matches((value) => /${pattern.source}/${pattern.flags}.test(value)), which is app-only and reports sql: null`,
+        `"${flags}", which Postgres has no operator for`,
+      `drop the flag and fold the behaviour into the pattern, or pass a predicate instead: matches((value) => /${pattern.source}/${pattern.flags.replaceAll(/[gy]/g, '')}.test(value)) — app-only, and it reports sql: null. Never g or y in that predicate: .test() advances lastIndex, so one row's verdict depends on the row before it`,
     );
   }
   return pattern.ignoreCase ? '~*' : '~';
@@ -213,8 +215,15 @@ const part = (term: Term, key: string): ColumnExpr =>
   });
 
 const sameAs = (left: Term, other: ColumnExpr): Expr => {
-  const right = terms.get(other);
-  if (right === undefined) throw invariantViolated('invariant', 'eq', 'not a column expression');
+  // `??` rather than an `if`: `eq` reaches here only past `isColumnExpr(other)`, which IS
+  // `terms.has(other)`, so this refusal is unreachable and exists to narrow `right` off the map.
+  const right =
+    terms.get(other) ??
+    refuseInvariant(
+      'eq',
+      'not a column expression',
+      "pass a column of the same c — c.total.eq(c.subtotal) — or compare against a value: c.total.eq(0). A column of another entity cannot appear in this table's CHECK",
+    );
   return check(
     [left.path, right.path],
     `${left.label} must equal ${right.label}`,

package/src/memory-match.ts

@@ -31,6 +31,9 @@ import type { ColumnKind } from './types';
  */
 const DECIMAL_TEXT: ReadonlySet<ColumnKind> = new Set<ColumnKind>(['bigint', 'numeric']);
 
+/** Absent and NULL are one thing to a predicate: a column the projection left out is not a value. */
+const isNull = (value: unknown): boolean => value === null || value === undefined;
+
 const sign = <T extends number | bigint | string>(left: T, right: T): number =>
   left < right ? -1 : left > right ? 1 : 0;
 
@@ -139,6 +142,13 @@ export const matchesPredicate = <Row>(
   const kind = kindOf(entity, predicate.column);
   const actual = valueAt(row, predicate.column);
   const same = (candidate: unknown): boolean => sameValueOfKind(kind, actual, candidate);
+  // `col > NULL` is UNKNOWN in SQL and UNKNOWN is not a match, so a NULL on EITHER side matches no
+  // row here either — `predicateSql` emits a bare `"col" > $1` and Postgres returns nothing. Without
+  // this the fall-through compared `String(null)` as the text `"null"`, which sorts after `"5"` and
+  // before `"z"`: `gt(seats, 5)` answered the null row in memory and never in production, and
+  // `lt(seats, null)` answered every row. The guard is HERE and not in `compareByKind`, which also
+  // orders a page — a sort puts NULLs last (`asc nulls last`) rather than dropping them.
+  const unknown = (): boolean => isNull(actual) || isNull(predicate.value);
   const order = (): number => compareByKind(kind, actual, predicate.value);
   switch (predicate.op) {
     case 'eq':
@@ -150,20 +160,20 @@ export const matchesPredicate = <Row>(
     case 'in':
       return Array.isArray(predicate.value) && predicate.value.some(same);
     case 'gt':
-      return order() > 0;
+      return !unknown() && order() > 0;
     case 'gte':
-      return order() >= 0;
+      return !unknown() && order() >= 0;
     case 'lt':
-      return order() < 0;
+      return !unknown() && order() < 0;
     case 'lte':
-      return order() <= 0;
+      return !unknown() && 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));
+      return !unknown() && likePattern(entity.$name, String(predicate.value)).test(String(actual));
     case 'is-null':
-      return actual === null || actual === undefined;
+      return isNull(actual);
     case 'is-not-null':
-      return actual !== null && actual !== undefined;
+      return !isNull(actual);
   }
 };

package/src/pg-row.ts

@@ -102,6 +102,12 @@ export const bindValues = <Row>(
  * 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.
+ *
+ * The `object` branch is the LAST resort and never a declared column's value: `arrayOf()` refuses
+ * `jsonb`, `bytea`, `money` and a nested array at declaration (`columns-data.ts`) precisely because
+ * this line has no literal for them and rendered every one as `""` — silently, and only against a
+ * real table, since `memoryRepo` stores the value it was handed. A `Date` is the one object shape
+ * with a literal, so it is named above.
  */
 const arrayElement = (value: unknown): string => {
   if (value === null || value === undefined) return 'NULL';

package/src/refuse.ts

@@ -0,0 +1,39 @@
+// The two refusals raised while a SCHEMA is still being written — a column and an invariant — and
+// why neither goes through `invariantViolated`: that builder's fix is
+// `x entities describe <entityName> --json`, which needs an entity that exists. Passing the
+// literal `'column'` emitted `x entities describe column --json`, which answers
+// `X_DECLARATION_UNKNOWN` — a fix line that raises a second, unrelated error (issue #290).
+//
+// So the fix is a parameter: every caller supplies the EDIT that repairs its own refusal, the
+// shape `arrayElementRefused` (`array-element.ts`) already ships. Two builders rather than one
+// with a `subject` parameter, because `fix-scan.ts` only reads a fix literal at a call site whose
+// callee constructs the error itself — a wrapper delegating to a shared inner one would take all
+// 30 of these fix lines back out of `x verify`'s `errors` step.
+
+import { EntityError } from './errors';
+
+/**
+ * A column refusing a value or its own declaration. `column.<rule>` is the cause's subject and is
+ * unchanged from what `invariantViolated('column', …)` rendered: the defect was the fix line, and
+ * a cause a hundred tests already read is not the place to make a second change.
+ */
+export const refuseColumn = (rule: string, detail: string, fix: string): never => {
+  throw new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `column.${rule}: ${detail}`,
+    fix,
+  });
+};
+
+/**
+ * An invariant refusing its own declaration, before any entity holds it — `matches(/…/g)` and an
+ * `eq` against a column of some other entity's `c`. Same reason as above: `invariantColumns` knows
+ * the entity name and passes it, these two are reached from the expression builder, which does not.
+ */
+export const refuseInvariant = (rule: string, detail: string, fix: string): never => {
+  throw new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `invariant.${rule}: ${detail}`,
+    fix,
+  });
+};