@ultimat3/entity 12.0.0 → 14.0.0

package/CLAUDE.md

@@ -33,6 +33,23 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `pg-driver-bulk.live.test.ts`, `pg-driver-tenancy.live.test.ts`). A method with only the first is
   unproven against Postgres itself; a method with only the second is unproven against memory. Both
   are the bar, not either one.
+- **Money's write shape is wider than its row shape, and both drivers narrow it at the WRITE
+  METHOD'S entry — `As of 2026-08-25`.** `MoneyInput` lets a writer hand a `bigint` minor unit read
+  straight off a `bigint` column; `MoneyValue` is what a row holds, because `JSON.stringify` refuses
+  a `bigint` and money crosses every wire this framework projects. `RowWrite<Row>` is the type that
+  says so at `Repo.insert`/`insertAll`/`upsertAll`, which took the ROW type instead — so the
+  widening this package documents, narrows and stores correctly was a **compile error at the only
+  call an app makes**, `postgresRepo()` being exported, and it was the last two entries on
+  `scripts/lib/test-typecheck-pins.ts`. `narrowRow` (`columns.ts`) is the narrowing, called at each
+  entry rather than deep inside `bindValues`/`write`, and the POSITION is the rule. `entity.$assert`
+  and `upsertPlan` both run before a statement exists, so an invariant reading `total.minor` was
+  handed the caller's `bigint` and never the `number` the row would hold — it rejected rows both
+  drivers then stored correctly. And it decides whether a refusal costs a row: Bun's client binds a
+  `bigint` verbatim (measured), so a minor unit past ±2^53 narrowed any later is INSERTed,
+  committed, and only then refused by the decode of its own `returning *` — a row the app wrote and
+  can never read. `pg-money-write.live.test.ts` is the proof, because only a real table can see
+  that; `money-write-parity.test.ts` pins both drivers together, and `type-pins.ts` fails the build
+  if those three writes stop taking `RowWrite` or start answering with it.
 - **What a PREDICATE means is decided by the column's declared KIND, and `memory-match.ts` is
   where that one meaning is written.** The database decides by the column's type, so a driver
   deciding by the JS `typeof` of the value in hand is answering a different question — four rules,
@@ -776,8 +793,28 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **Every framework member on an entity is `$`-prefixed** — the columns are `Object.assign`ed onto
   the core, so an unprefixed member would make `view`, `name` or `tenant` an illegal column name.
   `$view`, never `view`; no free `view(entity, keys)` either — one way to write a projection.
-- **Invariants run twice**: in the app on write AND as a Postgres CHECK/UNIQUE via `toSql()`. An
-  untranslatable JS predicate reports `kind: 'assert'`, `sql: null` — never a pretend CHECK.
+- **Invariants run twice, and only ONE side of the pair is rendered here.** In the app on write
+  (`assertInvariants`), and as a Postgres CHECK/UNIQUE emitted by `@ultimat3/db` —
+  `constraintNameFor`, `declaredChecks`, `declaredIndexes` (`invariant-ddl.ts`), reading
+  `$describe()`. An untranslatable JS predicate reports `kind: 'assert'`, `sql: null` — never a
+  pretend CHECK. **This package rendered a second copy of that DDL until 2026-08-25**
+  (`toSql`/`invariantsToSql`/`constraintName`, reachable through `entity.$migration()`), and the
+  copy is the argument: nothing but its own tests ever called it, so nobody noticed it passed the
+  entity NAME where the table belongs — `entity('account', { table: 'legacy_accounts' })` rendered
+  `ALTER TABLE "account" ADD CONSTRAINT "account_…_check"`, a relation Postgres answers `42P01` for
+  and a constraint name no migration has ever written. All four are deleted; `$migration()` was on
+  `EntityCore`, so this is a breaking change to a documented member. Never render constraint DDL
+  here again — the entity's job is to DESCRIBE the rule, and `<table>_<name>_<check|key>` now has
+  exactly one source.
+- **`InvariantDescription.columns` is projected, `As of 2026-08-25`** — the physical names the rule
+  reads, for every kind, straight off `Invariant.columns`. Same argument as `onDelete`, `generated`
+  and `default` on `ColumnDescription`: `@ultimat3/db` is tier 1 and cannot import this package, so
+  a fact this projection drops is a fact the generator must recover from a rendering. It was
+  recovering it — `uniqueColumns()` split a `unique` rule's `sql` on commas and re-validated each
+  part — which is the shape that made `posts_org_id_created_at_idx` read back as the single column
+  `"org_id_created_at"`. `snapshotOf` derives from `declaredChecks`/`declaredIndexes` and not from
+  this record, so the field changes no snapshot and nothing regenerates
+  (`describe-invariant.test.ts` pins both halves).
 - **And the two halves must AGREE, term by term** (`expr.ts`). A rule the app accepts and the CHECK
   refuses is not a stricter database: the write comes back as a raw constraint error instead of
   `X_INVARIANT_VIOLATED`, which is the framework's own invariant bypassed on the way out. Two
@@ -938,6 +975,52 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `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).
+- **Full-text search is one generated `tsvector` per entity, and the TERM is never syntax.**
+  `.searchable()` on a `text()` column puts it in the vector (`search.ts`); `entity()` derives the
+  column, the `generated always as (…) stored` expression and the GIN index through the existing
+  `IndexInit` path. Rules, none optional. **`websearch_to_tsquery`, never `to_tsquery`**: the term
+  crosses as a bound parameter either way — that is what stops an injection — but bare `to_tsquery`
+  reads `&`, `|`, `!`, `<->`, `:*` and parentheses as OPERATORS, so a search box sends either a
+  `42601` or a query the caller did not write; `plainto_tsquery` is safe and throws the user's own
+  quotes and `-negation` away in silence. **The configuration is spliced, from a CLOSED set**
+  (`SEARCH_LANGUAGES`), because `regconfig` cannot be a bound parameter inside a generated column at
+  all — and `to_tsvector(text)` with no configuration is not immutable, so Postgres refuses it there.
+  **`coalesce(col, '')` on every source**: `to_tsvector(NULL)` is NULL and `NULL || tsvector` is
+  NULL, so one nullable column would erase the whole row's vector. **The vector column is NOT NULL**,
+  which is what makes a generator that does not render the `generated` clause fail on the first
+  insert (`23502`) instead of leaving a table of NULL vectors under a search that quietly answers
+  nothing. **The memory driver REFUSES** (`X_SEARCH_IN_MEMORY`) rather than emulating: stemming, stop
+  words and a phrase parser are not a JS token comparison, and a green unit test over a different
+  question is the one outcome the two-driver split exists to prevent — the parity rule inverted, and
+  `predicateSql`/`matchesPredicate` are exhaustive switches over `Operator`, so neither can be given
+  a case the other lacks. **RELEVANCE is not an order this chain serves**: `ts_rank` is a computed
+  value and the cursor carries columns, so `.search()` filters and the declared `orderBy` pages —
+  proven over 30 tied rows in `pg-search.live.test.ts`, which also explains the GIN index and pins
+  the plan the tenant predicate produces.
+- **A state machine on a column is the MECHANISM only, and the line is `19-mechanism-not-convention.md`'s.**
+  What ships: the transition table, the refusal of a move not in it, the ATOMICITY of check-and-move,
+  the terminal-state concept, and the stamp saying when the row moved. What never ships: the states,
+  an approval chain, a role that may perform a move, a side effect on arrival. **There is no enum of
+  state names anywhere in this package** — `.transitions()` hangs off `enumerated()`, so the states
+  are the app's own set and `TransitionTable<S>` is a MAPPED type over it: a missing state, an
+  unknown key and an unknown target are compile errors against a list the framework never saw.
+  **A terminal state is one whose outgoing list is empty** — derived, never declared, so "nothing
+  leaves cancelled" is structural and *which* state is terminal is not the framework's business.
+  **The move is ONE statement.** `from` rides in the predicate (`where id = $1 and status = $2`), so
+  the state that was OBSERVED and the state that was WRITTEN are one decision made under the row's
+  lock, and no rows is the refusal. A read-then-check-then-write is the same code with a window in
+  it: measured against a real server, twenty concurrent callers naming `pending` produced **14
+  winners** that way and **exactly 1** this way (`pg-transition.live.test.ts`). Legality is asked
+  BEFORE the statement, because the table is a property of the declaration and not of the database.
+  **The refusal is a read, and only ever after the decision** — `X_STATE_CONFLICT` names the state
+  the row is really in, from a tenant-scoped `findById` that runs once the statement has already
+  refused. Another org's row reads as absent, so the answer is `X_NOT_FOUND` and never a conflict
+  that would confirm it exists. **The machine adds no DDL**: `enumerated()` already emits the CHECK,
+  so there is one declaration of what a legal value is. **A machine column may not be nullable** —
+  NULL is not a state, and `= NULL` matches no row, so every move out of it would read as a
+  conflict. **`whyNot` asks three questions in one order** — unknown state, then terminal, then the
+  legal list — because an unknown state has no outgoing moves either, and a check that skipped it
+  reported a typo as "the row is terminal in `pendign`".
 - 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`.
@@ -951,8 +1034,15 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `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 |
+| `expr.ts` / `invariants.ts` | the `invariants: (c) => …` rule language; `bindInvariant` resolves property paths to physical names. No DDL — that is `@ultimat3/db`'s `invariant-ddl.ts` |
 | `entity.ts` / `describe.ts` | `entity()`, `$row`; the `EntityDescription` projection |
+| `index-name.ts` | what an index is CALLED — the predicate/direction/method discriminator and the 63-byte bound |
+| `search.ts` | the generated `tsvector` a `.searchable()` column set derives: the closed language list, the weights, the expression |
+| `state-machine.ts` | the transition table, its five declaration rules, and what a terminal state IS |
+| `transition.ts` | one atomic move: the legality question, the conditional statement, the diagnosis of a statement that matched nothing |
+| `enum-column.ts` | `enumerated()` and its own chain — the one builder that may declare a machine |
+| `column-values.ts` | `got()` and `oneOf()`, so `enum-column.ts` needs no import of the file that imports it |
+| `feature-errors.ts` | the refusals search and the state machine raise at call time; the codes and titles stay in `errors.ts` |
 | `view.ts` | `$view(keys)` — the row projection an action names as its `output` |
 | `query.ts` / `database.ts` | chainable read to a cursor page; `database()` + `Driver` |
 | `clock.ts` | `entityNow()` — the ONE clock read on the write path, `ctx.clock` else the system's |

package/README.md

@@ -61,7 +61,7 @@ still imports one package: `import { entity, t } from '@ultimat3/entity'`.
 |---|---|---|
 | `uuid()`, `uuid<PostId>()` | `uuid`; `.primaryKey()` defaults to v7 | time-ordered keys keep the pk index append-friendly; the optional brand is declared once and survives to every signature |
 | `timestamp()` | `timestamptz` | UTC storage is not a per-table decision; there is no naive variant |
-| `money()` | `<name>_minor bigint` + `<name>_currency char(3)` + `<name>_scale integer null` | never a float, never one implied currency. The row value is `@ultimat3/schema`'s `MoneyValue` — the same declaration `@ultimat3/money`'s `Money` is — so a decoded row goes straight to `add()`/`formatMoney()`. A writer may hand a `bigint`; a stored minor unit past ±2^53 is refused on read, never rounded. `scale` is the decimal exponent `minor` counts in when it is not the currency's own (`{ minor: 2, currency: 'USD', scale: 6 }` is $0.000002); NULL in the column means "the currency's own minor unit" and round-trips as an ABSENT key, never as `0` |
+| `money()` | `<name>_minor bigint` + `<name>_currency char(3)` + `<name>_scale integer null` | never a float, never one implied currency. The row value is `@ultimat3/schema`'s `MoneyValue` — the same declaration `@ultimat3/money`'s `Money` is — so a decoded row goes straight to `add()`/`formatMoney()`. A writer may hand a `bigint` — `Insertable` says so on a table, `RowWrite<Row>` at a repository, and every whole-row write narrows it at its own entry, before an invariant or a statement sees it; a minor unit past ±2^53 is refused there and on read, never rounded. `scale` is the decimal exponent `minor` counts in when it is not the currency's own (`{ minor: 2, currency: 'USD', scale: 6 }` is $0.000002); NULL in the column means "the currency's own minor unit" and round-trips as an ABSENT key, never as `0` |
 | `enumerated(v)` | `text` + CHECK | a variant is a one-line migration, not `ALTER TYPE` |
 | `tz(zones)`, `locale(tags)` | `text` + CHECK, `Intl`-validated at declaration | an offset is not a time zone |
 | `text({ max })`, `integer()`, `boolean()`, `url()` | `text`/`integer`/`boolean` + CHECK | format is enforced by the database too |
@@ -142,9 +142,13 @@ Nothing is checked at runtime: a brand has no witness, `$parse` still validates
 One declaration, two enforcement points: the app checks it on every write, and the migration
 emits it. A bulk import or a `psql` session hits the same rule.
 
+The DDL is `@ultimat3/db`'s — one renderer, reading `$describe()`, so what `x db gen` writes is the
+only spelling there is. On a table this migration creates the check is an inline clause; on one that
+already exists it is the `alter table` beside it.
+
 ```sql
-ALTER TABLE "posts" ADD CONSTRAINT "posts_post_like_count_non_negative_check" CHECK (like_count >= 0);
-CREATE UNIQUE INDEX "posts_post_slug_unique_per_org_key" ON "posts" ("org_id", "slug");
+alter table "posts" add constraint "posts_post_like_count_non_negative_check" check (like_count >= 0);
+create unique index "posts_post_slug_unique_per_org_key" on "posts" ("org_id", "slug");
 ```
 
 A rule written as a JS predicate — `c.slug.matches(isValidSlug)`, `c.satisfies(fn, [...])` —
@@ -325,6 +329,92 @@ export const posts = entity('posts', {
 | Refused | a unique GIN and an ordered GIN, at `entity()` — Postgres has neither, and the refusal names the edit |
 | Naming | the method is part of what separates two indexes on the same columns, so a btree and a GIN on one column are two indexes with two names |
 
+## Full-text search
+
+`.searchable()` on a `text()` column puts it in the entity's **one** generated `tsvector`, with a
+GIN index on it. Nothing else to declare, and no second column on the row.
+
+```ts
+import { database, entity, text, timestamp, uuid } from '@ultimat3/entity';
+
+declare const orgId: string;
+declare const term: string;   // what the user typed, verbatim
+
+const posts = entity('posts', {
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid().tenant(),
+    title: text({ max: 120 }).searchable('A'),   // 'A' outranks 'D' under ts_rank
+    body: text().nullable().searchable(),        // 'D' by default, Postgres' own
+    createdAt: timestamp().defaultNow(),
+  },
+  // Only when the defaults do not fit: the column is `search_tsv`, the language is 'english'.
+  search: { column: 'search_tsv', language: 'english' },
+});
+
+const db = database({ posts });
+
+await db.posts.where({ orgId }).search(term).orderBy('createdAt', 'desc').limit(20).page();
+```
+
+| Fact | Why |
+|---|---|
+| the term is a **bound parameter**, parsed by `websearch_to_tsquery` | `&`, `\|`, `!`, `:*` and an unbalanced paren are characters to match, never operators and never a `42601`. `plainto_tsquery` is safe too and silently discards `"a phrase"` and `-negation`; bare `to_tsquery` on user text is the injection |
+| the language is spliced from a closed set (`SEARCH_LANGUAGES`) | `regconfig` cannot be a bound parameter inside a generated column, and `to_tsvector(text)` with no configuration is not immutable, so Postgres refuses it there |
+| the column is `generated always as (…) stored`, `not null` | the database computes it on every write, including one made from psql |
+| tenancy, soft delete, the projection, the order and the cursor are unchanged | `.search()` is one more predicate on the chain you already had |
+| `memoryDriver()` **refuses** it — `X_SEARCH_IN_MEMORY` | stemming, stop words and a phrase parser are not a JS token comparison, and an answer memory could give is one Postgres would contradict. Assert a search in a `.live.test.ts` |
+| relevance is **not** an order the chain serves | `ts_rank` is a computed value and a cursor carries columns; the order is the one you declared, and it pages |
+
+## A state machine over a column
+
+`.transitions()` on an `enumerated()` column. The states are yours; the machine is the framework's.
+
+```ts
+import { database, entity, enumerated, timestamp, uuid } from '@ultimat3/entity';
+
+declare const id: string;
+
+const ORDER_STATES = ['pending', 'paid', 'shipped', 'delivered', 'cancelled'] as const;
+
+const orders = entity('orders', {
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid().tenant(),
+    status: enumerated(ORDER_STATES)
+      .transitions({
+        pending: ['paid', 'cancelled'],
+        paid: ['shipped', 'cancelled'],
+        shipped: ['delivered'],
+        delivered: [],     // terminal — nothing leaves it, and an empty list is how you say so
+        cancelled: [],
+      })
+      .default('pending'),
+    updatedAt: timestamp().defaultNow().onUpdateNow(),
+  },
+});
+
+const db = database({ orders });
+
+// One statement. `from` is the state you believe the row is in, and it rides in the predicate.
+const shipped = await db.orders.transition('status', id, { from: 'paid', to: 'shipped' });
+```
+
+| Fact | Why |
+|---|---|
+| the table is a **mapped type** over your `enumerated()` set | a missing state, an unknown key and an unknown target are compile errors — the framework never names a state |
+| **one statement**, with `from` in its predicate | the state observed and the state written are one decision, under the row's lock. Two callers who both read `pending` cannot both move it: the second matches no row |
+| a move the table does not hold is `X_STATE_TRANSITION_ILLEGAL`, before any statement | the table is a property of the declaration, so an illegal move never reaches the database |
+| a row that moved first is `X_STATE_CONFLICT`, naming the state it is really in | read back **after** the refusal — a diagnosis, never the decision |
+| another org's row is `X_NOT_FOUND`, never a conflict | a conflict would confirm the row exists and name its state |
+| a terminal state is one with an empty list | derived. *Which* state is terminal is yours |
+| `onUpdateNow()` moves, because a transition is an update | the audit of *when* it moved, with no second mechanism beside it |
+| the CHECK comes from `enumerated()` | the machine emits no DDL of its own — one declaration of what a legal value is |
+| `memoryDriver()` answers it exactly as Postgres does | a compare-and-set over a map is the same question; unlike a `tsvector` match, there is nothing to fake |
+
+What is deliberately **not** here: who may make a move, what happens on arrival, an approval chain,
+a reason code. Those differ per app — wrap `transition()` in your own function and put them there.
+
 ## Counting by a column
 
 `As of 2026-08`. `count()` answers one number, so a screen or a backfill that needs one per row

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "12.0.0",
+  "version": "14.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": "12.0.0",
-    "@ultimat3/db": "12.0.0",
-    "@ultimat3/schema": "12.0.0",
-    "@ultimat3/time": "12.0.0"
+    "@ultimat3/core": "14.0.0",
+    "@ultimat3/db": "14.0.0",
+    "@ultimat3/schema": "14.0.0",
+    "@ultimat3/time": "14.0.0"
   }
 }

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,
@@ -181,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 = {}) =>

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,
@@ -27,27 +27,11 @@ import type {
   MoneyColumnNames,
   MoneyInput,
   MoneyValue,
+  RowWrite,
   TimestampColumn,
   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 +136,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.
@@ -432,6 +388,22 @@ export const narrowMoney = <Row>(columns: ColumnMap, row: Row): Row => {
   return (narrowed ?? row) as Row;
 };
 
+/**
+ * The same narrowing at a write METHOD'S entry, typed honestly: what a caller may spell in,
+ * the row the entity declares out.
+ *
+ * `narrowMoney` is `<Row>(columns, row: Row): Row` — sound for `bindValues`, whose input and
+ * output are both a patch, and a lie for a full row that arrived as `RowWrite<Row>`, which is
+ * exactly the position `Repo.insert`/`insertAll`/`upsertAll` are in. Narrowing here rather than at
+ * `bindValues` is also what makes an `assert` invariant judge the value the row will HOLD instead
+ * of the spelling a caller happened to use: `entity.$assert` runs before the statement exists, so
+ * a rule reading `total.minor` saw the caller's `bigint` in both drivers and the stored `number`
+ * nowhere. The `as` is the one assertion this file is for — every money property is a `MoneyValue`
+ * once `narrowMoney` has returned, and `parseMinor` threw for anything that could not become one.
+ */
+export const narrowRow = <Row>(columns: ColumnMap, values: RowWrite<Row>): Row =>
+  narrowMoney(columns, values) as Row;
+
 /**
  * The CHECK that stops a psql session writing a currency the app would refuse — the app's own
  * bound, projected into SQL rather than restated in it.
@@ -454,3 +426,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/describe.ts

@@ -9,6 +9,7 @@ import { columnName, moneyColumns, referenceBinding } from './column';
 import { currencyCheck, scaleCheck } from './columns';
 import type { Invariant } from './invariants';
 import type { ColumnDescription, EntityDescription, ReferenceDescription } from './registry';
+import type { SearchVector } from './search';
 import type { AnyColumn, ColumnMeta, IndexDef } from './types';
 
 export interface DescribeInput<Row> {
@@ -23,8 +24,34 @@ export interface DescribeInput<Row> {
   readonly cacheTag: string;
   readonly softDelete: boolean;
   readonly tenantColumn: string | null;
+  /** The generated `tsvector`, when any column is `.searchable()`. */
+  readonly search?: SearchVector | null;
 }
 
+/**
+ * The search vector as a physical column: `tsvector`, computed by the database, never written.
+ *
+ * `notNull` is what makes a missing `generated` clause LOUD rather than silent. Every function in
+ * the expression is total over a coalesced text, so the value can never be NULL — and if a
+ * generator that does not yet render `generated` emits the column as a plain `tsvector`, the first
+ * insert is a `23502` naming this column, instead of a table of NULL vectors where every search
+ * quietly answers nothing.
+ */
+const describeSearchColumn = (search: SearchVector): ColumnDescription => ({
+  // `$`-prefixed: a property key no column can be spelled as, because nothing may address it.
+  property: '$search',
+  column: search.column,
+  kind: 'tsvector',
+  notNull: true,
+  primaryKey: false,
+  unique: false,
+  hasDefault: false,
+  check: null,
+  references: null,
+  onDelete: null,
+  generated: search.expression,
+});
+
 /**
  * The foreign keys an entity declares, resolved through the one binding resolver. Money is
  * skipped for the reason the DDL projection drops a reference there too: one property is two
@@ -143,6 +170,9 @@ const describeColumn = <Row>(
       primaryKey: meta.primaryKey || input.primaryKey.includes(property),
       unique: meta.unique,
       hasDefault: meta.default !== undefined,
+      // The value beside the boolean: `@ultimat3/db` renders it, and without it the generator
+      // could only infer two expressions and dropped every other default without saying so.
+      ...(meta.default === undefined ? {} : { default: meta.default }),
       check: meta.check?.(physical) ?? null,
       // Rendered from the resolved record, so the string a migration reads and the record a
       // traversal reads can never disagree about what a `references()` points at.
@@ -170,15 +200,23 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
     name: input.name,
     table: input.table,
     primaryKey: input.primaryKey.map(physicalOf),
-    columns: input.columns.flatMap(([property, column]) =>
-      describeColumn(input, property, column.$meta, references.get(property)),
-    ),
+    columns: [
+      ...input.columns.flatMap(([property, column]) =>
+        describeColumn(input, property, column.$meta, references.get(property)),
+      ),
+      // LAST, so every column an author declared keeps the position it had and no snapshot of an
+      // entity without a search vector moves.
+      ...(input.search == null ? [] : [describeSearchColumn(input.search)]),
+    ],
+    // `columns` rides along whole: the generator needs the list a `unique` names, and recovering
+    // it by splitting `sql` is reading this package's own rendering back. See InvariantDescription.
     invariants: input.invariants.map((inv) => ({
       name: inv.name,
       kind: inv.kind,
       message: inv.message,
       sql: inv.sql,
       where: inv.where ?? null,
+      columns: inv.columns,
     })),
     // Projected whole, never reduced to the name: the generator spells the column list from this
     // and a name cannot be parsed back into one. See `IndexDescription`.