@ultimat3/entity 12.0.0 → 13.0.0

package/CLAUDE.md

@@ -938,6 +938,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`.
@@ -953,6 +999,13 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `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 |
+| `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

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

package/src/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
@@ -170,9 +197,14 @@ 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)]),
+    ],
     invariants: input.invariants.map((inv) => ({
       name: inv.name,
       kind: inv.kind,

package/src/entity.ts

@@ -13,10 +13,13 @@ import { describeEntity, describeReferences } from './describe';
 import { invariantViolated } from './errors';
 import type { Expr, InvariantColumns, Resolve } from './expr';
 import { invariantColumns } from './expr';
+import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant, invariantsToSql } from './invariants';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
+import type { SearchInit, SearchSource, SearchVector } from './search';
+import { searchVectorOf } from './search';
 import { resolveTenantColumn } from './tenancy';
 import type { AnyColumn, ColumnMap, ColumnMeta, IndexDef, RowOf } from './types';
 import type { EntityView } from './view';
@@ -73,6 +76,12 @@ export interface EntityInit<C extends ColumnMap> {
    */
   readonly invariants?: (columns: InvariantColumns<C>) => readonly InvariantDef[];
   readonly indexes?: readonly IndexInit<C>[];
+  /**
+   * Full-text search, when the two defaults do not fit: `search_tsv` and `'english'`. WHICH columns
+   * are searched is `.searchable()` on the columns themselves, never restated here — this is the
+   * adoption escape, exactly as `table` and `.column()` are.
+   */
+  readonly search?: SearchInit;
   /** Extra cache tags this entity participates in, beyond its own. */
   readonly tags?: readonly string[];
 }
@@ -95,6 +104,11 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   readonly $softDelete: boolean;
   /** Property key of the tenant column, or `null`. Presence is what turns tenancy on. */
   readonly $tenantColumn: string | null;
+  /**
+   * The generated `tsvector` this entity's `.searchable()` columns derive, or `null` when none is.
+   * Presence is what makes `.search(text)` legal — both drivers read it, and neither invents one.
+   */
+  readonly $search: SearchVector | null;
   /** Phantom: `type Post = typeof posts.$row`. Reading it at runtime throws. */
   readonly $row: Row;
   /** The Standard Schema the columns already describe — forms and actions hand input to it. */
@@ -125,88 +139,6 @@ export type Entity<Row, C extends ColumnMap = ColumnMap> = EntityCore<Row, C> &
 
 const MONEY_PARTS = new Set(['minor', 'currency']);
 
-/**
- * What separates two indexes on the SAME columns: the predicate and the direction. Eight hex
- * characters of sha256 over both — deterministic across processes, so a name is a property of the
- * declaration and never of the run that generated it.
- */
-/**
- * What separates two indexes on the SAME columns: the predicate, the direction and the ACCESS
- * METHOD. Eight hex characters of sha256 over all three — deterministic across processes, so a
- * name is a property of the declaration and never of the run that generated it.
- *
- * The method belongs here for exactly the reason `where` does. A btree on an `arrayOf()` column
- * answers `=` and an ordering; a GIN on the same column answers `@>` / `<@` / `&&`. They are two
- * distinct indexes, and without the method in the name both are `<table>_<cols>_idx` — where the
- * dedup below drops one in silence (the defect this discriminator was added for) or, since that
- * dedup is now on the whole definition, two `create index` statements share one name and the
- * migration is `42P07`.
- */
-const indexDiscriminator = (
-  order: string | undefined,
-  where: string | null,
-  using: string | undefined,
-): string =>
-  new Bun.CryptoHasher('sha256')
-    // The method is APPENDED only when one was declared, never as an empty field: every name this
-    // function has ever minted for a partial or ordered index is therefore unchanged by the method
-    // existing, and an index that declares no method is byte-identical to the one it was.
-    .update(`${order ?? ''}|${where ?? ''}${using === undefined ? '' : `|${using}`}`)
-    .digest('hex')
-    .slice(0, 8);
-
-/**
- * `<table>_<columns>_idx`, plus a discriminator when — and only when — the index carries a
- * predicate, a direction or a non-default access method.
- *
- * Only then, because the plain name is load-bearing in two places: `unique()` on a column is an
- * inline column clause and Postgres names the index it creates exactly `<table>_<column>_key`, so
- * a discriminator there would make the generator emit a second `create unique index` for an index
- * that already exists (`42P07`); and a foreign key's own index is deduped against a hand-declared
- * one by this name.
- *
- * Without it, two DIFFERENT partial indexes on one column were one name — `posts_author_id_idx`
- * for both `where status = 'published'` and `where status = 'draft'` — and the dedup below dropped
- * the second with no error, no warning and no drift finding, since a declared index is matched by
- * name.
- */
-/**
- * `NAMEDATALEN - 1`. Postgres truncates a longer identifier and says NOTHING, so two index names
- * sharing their first 63 bytes become one index on the server — the same silent collapse the
- * discriminator above exists to prevent, one layer down, and invisible to a drift check comparing
- * DECLARED names because those still differ. Bytes and not characters: 63 is what the server
- * counts, and `.length` would stop seeing the truncation the moment a name is not ASCII.
- */
-const MAX_IDENTIFIER_BYTES = 63;
-
-const byteLength = (value: string): number => new TextEncoder().encode(value).length;
-
-const indexName = (
-  entityName: string,
-  table: string,
-  columns: readonly string[],
-  unique: boolean,
-  order?: string | undefined,
-  where: string | null = null,
-  using?: IndexMethod | undefined,
-): string => {
-  const suffix = unique ? 'key' : 'idx';
-  const base = `${table}_${columns.join('_')}`;
-  const plain = order === undefined && where === null && using === undefined;
-  const name = plain
-    ? `${base}_${suffix}`
-    : `${base}_${indexDiscriminator(order, where, using)}_${suffix}`;
-  const bytes = byteLength(name);
-  if (bytes <= MAX_IDENTIFIER_BYTES) return name;
-  throw invariantViolated(
-    entityName,
-    'index',
-    `the index on (${columns.join(', ')}) is named "${name}", which is ${bytes} bytes — ` +
-      `Postgres truncates an identifier at ${MAX_IDENTIFIER_BYTES} and does not say so, ` +
-      'so two indexes can silently become one',
-  );
-};
-
 const defaultValue = (meta: ColumnMeta): unknown => {
   const declared = meta.default;
   if (declared === undefined) return undefined;
@@ -230,6 +162,22 @@ export const entity = <const C extends ColumnMap>(
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
 
+  const searchSources: readonly SearchSource[] = entries.flatMap(([property, column]) => {
+    const weight = column.$meta.searchable;
+    return weight === undefined ? [] : [{ column: columnName(property, column.$meta), weight }];
+  });
+  const search = searchVectorOf(
+    searchSources,
+    init.search,
+    // `physical`, not `candidate`: a parameter whose NAME reads like a credential is what
+    // `bun run secret-compare` refuses an `===` on, and this is a column name.
+    (physical) =>
+      entries.some(([property, column]) => columnName(property, column.$meta) === physical),
+    (subject, detail) => {
+      throw invariantViolated(name, subject, detail);
+    },
+  );
+
   const primaryKey =
     init.primaryKey ?? entries.filter(([, column]) => column.$meta.primaryKey).map(([key]) => key);
   if (primaryKey.length === 0) {
@@ -342,6 +290,19 @@ export const entity = <const C extends ColumnMap>(
         ...(index.using === undefined || index.using === 'btree' ? {} : { using: index.using }),
       };
     }),
+    // The one index nobody declared and every search needs. Through the SAME `IndexInit` path a
+    // hand-written `using: 'gin'` takes — `indexName` gives it the method discriminator, so it can
+    // never collide with a btree an author declares on the same column.
+    ...(search === null
+      ? []
+      : [
+          {
+            name: indexName(name, table, [search.column], false, undefined, null, 'gin'),
+            columns: [search.column],
+            unique: false,
+            using: 'gin' as IndexMethod,
+          },
+        ]),
   ];
   /**
    * A foreign key already indexes its column; naming it again in `indexes` is not two indexes.
@@ -379,6 +340,7 @@ export const entity = <const C extends ColumnMap>(
       cacheTag,
       softDelete,
       tenantColumn,
+      search,
     });
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);
 
@@ -423,6 +385,7 @@ export const entity = <const C extends ColumnMap>(
     $cacheTag: cacheTag,
     $softDelete: softDelete,
     $tenantColumn: tenantColumn,
+    $search: search,
     $schema: {
       '~standard': {
         version: 1,

package/src/enum-column.ts

@@ -0,0 +1,81 @@
+// The one column that may declare a state machine, and the only one that could: `enumerated()`
+// already declares the closed set of values a machine moves through, as a CHECK the migration
+// emits. Split from `columns.ts` at the 500-line ceiling, along the seam the extra chain draws.
+
+import { BARE, makeColumn } from './column';
+import { got, oneOf } from './column-values';
+import { refuseColumn } from './refuse';
+import { stateMachineOf } from './state-machine';
+import type { ColumnMeta, EnumeratedColumn } from './types';
+
+/**
+ * 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): EnumeratedColumn<V> => {
+  const allowed = new Set<string>(values);
+  const parse = (value: unknown): V[number] =>
+    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',
+        );
+  return enumeratedWith<V, false>(
+    { ...BARE, kind: 'text', values, check: oneOf(values) },
+    values,
+    parse,
+    false,
+  );
+};
+
+/**
+ * Every link delegates to the general chain and re-wraps its `$meta`, so there is one definition of
+ * what `.default()` accepts and of how `.column()` validates a name — this file adds only the two
+ * rules the general chain cannot know: a machine may be declared here, and a column carrying one
+ * may not hold NULL.
+ */
+const enumeratedWith = <V extends readonly string[], Optional extends boolean>(
+  meta: ColumnMeta,
+  values: V,
+  parse: (value: unknown) => V[number],
+  optional: Optional,
+): EnumeratedColumn<V, Optional> => {
+  const base = makeColumn<V[number], Optional>(meta, parse, optional);
+  return {
+    ...base,
+    transitions: (table) => {
+      // Refused in BOTH directions, so neither order of the chain can produce the column that has
+      // no answer: NULL is not one of the declared states, so nothing could say what it may move
+      // to — and the compare-and-set the write path uses compares it with `=`, where NULL matches
+      // no row at all and every transition out of it would read as a conflict.
+      if (!meta.notNull) {
+        refuseColumn(
+          'transitions',
+          'a state machine column may not hold null — null is not one of the declared states',
+          'drop .nullable() from this column, or drop .transitions() — a row outside every state has no legal move',
+        );
+      }
+      return enumeratedWith<V, Optional>(
+        { ...meta, machine: stateMachineOf(values, table) },
+        values,
+        parse,
+        optional,
+      );
+    },
+    default: (value) => enumeratedWith<V, true>(base.default(value).$meta, values, parse, true),
+    column: (name) => enumeratedWith<V, Optional>(base.column(name).$meta, values, parse, optional),
+    nullable: () => {
+      if (meta.machine !== undefined) {
+        refuseColumn(
+          'transitions',
+          'a state machine column may not hold null — null is not one of the declared states',
+          'drop .nullable() from this column, or drop .transitions() — a row outside every state has no legal move',
+        );
+      }
+      return base.nullable();
+    },
+  };
+};