@ultimat3/entity 8.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`.
@@ -754,6 +769,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `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": "8.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": "8.0.0",
-    "@ultimat3/db": "8.0.0",
-    "@ultimat3/schema": "8.0.0",
-    "@ultimat3/time": "8.0.0"
+    "@ultimat3/core": "9.0.0",
+    "@ultimat3/db": "9.0.0",
+    "@ultimat3/schema": "9.0.0",
+    "@ultimat3/time": "9.0.0"
   }
 }

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

@@ -12,13 +12,9 @@ import { describeValue, formatIssues, type StandardSchemaV1, validate } from '@u
 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)}`;
 
@@ -42,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',
     );
   });
 
@@ -67,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 {
@@ -96,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+)?$/;
@@ -112,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;
     },
@@ -157,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()",
+        );
   });
 
 /**
@@ -174,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);
@@ -193,7 +226,13 @@ export const arrayOf = <T>(element: Column<T>): Column<readonly T[]> => {
   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/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/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,
+  });
+};