@ultimat3/entity 12.0.0 → 13.0.0

package/src/errors.ts

@@ -21,6 +21,11 @@ export const ENTITY_OWNED_ERROR_CODES = [
   'X_AGGREGATE_UNSUPPORTED',
   'X_AGGREGATE_MIXED_CURRENCY',
   'X_APPROXIMATE_COUNT_FILTERED',
+  'X_SEARCH_UNDECLARED',
+  'X_SEARCH_IN_MEMORY',
+  'X_STATE_UNDECLARED',
+  'X_STATE_TRANSITION_ILLEGAL',
+  'X_STATE_CONFLICT',
 ] as const;
 
 /**
@@ -58,6 +63,11 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>>
   X_AGGREGATE_UNSUPPORTED: 'that column has no aggregate both drivers can answer alike',
   X_AGGREGATE_MIXED_CURRENCY: 'an amount was aggregated across currencies',
   X_APPROXIMATE_COUNT_FILTERED: 'an estimate was asked of a filtered chain',
+  X_SEARCH_UNDECLARED: 'this entity has no searchable column',
+  X_SEARCH_IN_MEMORY: 'the in-memory driver cannot answer a full-text match',
+  X_STATE_UNDECLARED: 'that column declares no state machine',
+  X_STATE_TRANSITION_ILLEGAL: 'the machine has no such transition',
+  X_STATE_CONFLICT: 'the row is no longer in the state this transition named',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the

package/src/feature-errors.ts

@@ -0,0 +1,121 @@
+// The refusals the two DECLARED capabilities raise at call time — full-text search and a state
+// machine. Split from `errors.ts` at the 500-line ceiling; the codes and their titles stay there,
+// because a registry with two homes is a registry that disagrees with itself.
+
+import { EntityError } from './errors';
+
+/**
+ * A `matches` predicate on an entity whose columns declare no `.searchable()`.
+ *
+ * Raised where the STATEMENT would be built, not where the chain was written, because both drivers
+ * reach it: an entity's search vector is derived from its columns, so there is nothing else the
+ * predicate could name and no vector to guess at.
+ */
+export const searchUndeclared = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_SEARCH_UNDECLARED',
+    cause: `${entityName} has no searchable column, so there is no tsvector to match against`,
+    fix: `add .searchable() to a text() column of ${entityName}, then: x db gen "search ${entityName}"`,
+  });
+
+/**
+ * A full-text match asked of `memoryDriver()`. REFUSED rather than emulated, and that is the whole
+ * decision: `to_tsvector` stems, drops stop words and applies a language's own rules, and
+ * `websearch_to_tsquery` parses quoted phrases and `-`negation — a JS token comparison is a
+ * DIFFERENT question with the same shape, so it would answer green in a unit test and differently
+ * in production, which is the one outcome the two-driver split exists to prevent.
+ */
+export const searchInMemory = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_SEARCH_IN_MEMORY',
+    cause: `memoryDriver() cannot stem, weight or rank a tsvector, so a search of ${entityName} has no answer it could give that Postgres would agree with`,
+    fix: `move this read into a <name>.live.test.ts and run it with TEST_DATABASE_URL set — bun test packages/entity/src/pg-search.live.test.ts is the model`,
+  });
+
+/**
+ * `transition()` on a column that declares no `.transitions()`.
+ *
+ * A declaration bug and not a caller's, which is why it lists the columns that DO declare one: the
+ * repair is naming a different column or writing the table, and both are edits to source.
+ */
+export const stateUndeclared = (
+  entityName: string,
+  column: string,
+  machines: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_STATE_UNDECLARED',
+    cause: `${entityName}.${column} declares no state machine, so there is no transition to check`,
+    fix:
+      machines.length === 0
+        ? `add .transitions(…) to ${entityName}.${column} — it must be an enumerated() column, and every value that set declares needs an entry`
+        : `${entityName} declares a machine on: ${machines.join(', ')}`,
+  });
+
+/**
+ * Why a move is not in the machine. THREE conditions and one code, because they share one repair —
+ * the move is not in the table — and each states its own fact, because they are not the same
+ * mistake and the fix line differs.
+ *
+ * `unknown-state` is separate from `terminal` for a reason a test found: an unknown state has no
+ * outgoing moves either, so a single "no legal moves" branch reported a typo as "the row is
+ * terminal in <typo>" — a sentence about a state that does not exist. Reachable from JS, and from
+ * a `from` that came out of parsed JSON.
+ *
+ * `terminal` is separate from the ordinary case because "no legal moves" reads like a missing
+ * declaration and is not one: an empty list is how a terminal state is written.
+ */
+export type IllegalTransition =
+  | { readonly reason: 'unknown-state'; readonly states: readonly string[] }
+  | { readonly reason: 'terminal' }
+  | { readonly reason: 'not-declared'; readonly legal: readonly string[] };
+
+export const stateTransitionIllegal = (
+  entityName: string,
+  column: string,
+  from: string,
+  to: string,
+  detail: IllegalTransition,
+): EntityError => {
+  const subject = `${entityName}.${column}`;
+  if (detail.reason === 'unknown-state') {
+    return new EntityError({
+      code: 'X_STATE_TRANSITION_ILLEGAL',
+      cause: `"${from}" is not a state of ${subject} — it declares: ${detail.states.join(' | ')}`,
+      fix: `${entityName}.transition('${column}', id, { from: '${detail.states[0] ?? from}', to: '${to}' })   # name a state the enumerated() set declares`,
+    });
+  }
+  if (detail.reason === 'terminal') {
+    return new EntityError({
+      code: 'X_STATE_TRANSITION_ILLEGAL',
+      cause: `${subject} is terminal in "${from}": the machine declares no move out of it, so "${to}" is not one`,
+      fix: `move the row before it reaches "${from}", or add "${to}" to the "${from}" entry of the transitions() table`,
+    });
+  }
+  return new EntityError({
+    code: 'X_STATE_TRANSITION_ILLEGAL',
+    cause: `${subject} has no move from "${from}" to "${to}" — from "${from}" it may go to: ${detail.legal.join(', ')}`,
+    fix: `${entityName}.transition('${column}', id, { from: '${from}', to: '${detail.legal[0]}' })   # or add "${to}" to the "${from}" entry of the transitions() table`,
+  });
+};
+
+/**
+ * The conditional update matched no row, and the row is in a different state than the caller named.
+ *
+ * This is the lost update, caught: two callers both read "pending", both found the move legal, and
+ * the second one's statement carried `status = 'pending'` in its predicate and matched nothing. The
+ * state in the cause is READ BACK after the refusal, so it is a diagnosis and never the decision —
+ * the decision was the statement, and it was atomic.
+ */
+export const stateConflict = (
+  entityName: string,
+  column: string,
+  id: string,
+  expected: string,
+  actual: string,
+): EntityError =>
+  new EntityError({
+    code: 'X_STATE_CONFLICT',
+    cause: `${entityName}.${column} named "${expected}" for row ${id}, which is in "${actual}" — something moved it first`,
+    fix: `re-read the row and decide again against "${actual}": ${entityName}.findById(id) — a transition names the state it expects, so a stale read is refused rather than overwritten`,
+  });

package/src/index-name.ts

@@ -0,0 +1,83 @@
+// What an index is CALLED. Split out of `entity.ts` at the 500-line ceiling, and it is one job:
+// two indexes that differ only in their predicate, their direction or their access method must not
+// share a name, and no name may cross the 63 bytes Postgres silently truncates at.
+
+import type { IndexMethod } from '@ultimat3/db';
+import { invariantViolated } from './errors';
+
+/**
+ * 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;
+
+export 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',
+  );
+};

package/src/index.ts

@@ -22,9 +22,6 @@ export {
   url,
   uuid,
 } from './columns';
-// The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
-// are decisions this framework made for a table it was going to create, and these are the shapes
-// a table already has (`docs`: Entities-And-Migrations, "Adopting an existing database").
 export type { DecimalOptions } from './columns-data';
 export { arrayOf, bigint, bytes, date, decimal, json } from './columns-data';
 // `crossTenantReason` stays internal: an app that could read the flag would have a second way to
@@ -36,6 +33,9 @@ export type { DescribeInput } from './describe';
 export { sqlTypeOf } from './describe';
 export type { Entity, EntityCore, EntityInit, IndexInit } from './entity';
 export { entity, SOFT_DELETE_COLUMN } from './entity';
+// The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
+// are decisions this framework made for a table it was going to create, and these are the shapes
+// a table already has (`docs`: Entities-And-Migrations, "Adopting an existing database").
 export type {
   EntityErrorCode,
   PreloadCandidate,
@@ -65,6 +65,15 @@ export {
   writeUnfiltered,
 } from './errors';
 export type { ColumnExpr, Expr, InvariantColumns, Resolve } from './expr';
+/** The two DECLARED capabilities' refusals — a third-party driver raises the same ones. */
+export type { IllegalTransition } from './feature-errors';
+export {
+  searchInMemory,
+  searchUndeclared,
+  stateConflict,
+  stateTransitionIllegal,
+  stateUndeclared,
+} from './feature-errors';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
 export {
   assertInvariants,
@@ -116,6 +125,20 @@ export type {
 } from './repo';
 export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-observer';
 export { observedRepo, rowObserver, setRowObserver } from './row-observer';
+// Full-text search. The LANGUAGE set and the weights are values an app reads to build a form;
+// `SEARCH_PROPERTY` is what a `matches` predicate names, which a hand-built `QueryPlan` needs.
+export type { SearchInit, SearchLanguage, SearchSource, SearchVector } from './search';
+export {
+  DEFAULT_SEARCH_COLUMN,
+  DEFAULT_SEARCH_LANGUAGE,
+  DEFAULT_SEARCH_WEIGHT,
+  isSearchLanguage,
+  isSearchWeight,
+  SEARCH_LANGUAGES,
+  SEARCH_PROPERTY,
+  SEARCH_WEIGHTS,
+  searchExpression,
+} from './search';
 export type {
   Seed,
   SeedContext,
@@ -128,6 +151,16 @@ export type {
   SeedWrite,
 } from './seed';
 export { defineSeed, isSeed, SEED_TIERS, seedId, seedTiersFor } from './seed';
+// A state machine over a column. The MECHANISM only: the table, the refusal, the terminal concept.
+// The states are the app's `enumerated()` set and nothing here names one.
+export type { StateMachine, TransitionTable } from './state-machine';
+export {
+  canMove,
+  isState,
+  isTerminal,
+  movesFrom,
+  stateMachineOf,
+} from './state-machine';
 export type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
 export {
   assertRowTenant,
@@ -141,6 +174,7 @@ export {
   scopedPlan,
   tenantColumnOf,
 } from './tenancy';
+export type { Move } from './transition';
 export type {
   AnyColumn,
   Column,
@@ -148,6 +182,7 @@ export type {
   ColumnKind,
   ColumnMap,
   ColumnMeta,
+  EnumeratedColumn,
   IdOf,
   IndexDef,
   Insertable,
@@ -158,6 +193,7 @@ export type {
   ReferenceOptions,
   RowOf,
   RowPatch,
+  SearchWeight,
   TimestampColumn,
   TypeOf,
   UuidColumn,

package/src/memory-match.ts

@@ -10,6 +10,7 @@ import { arrayContains, arrayOverlaps, jsonContains, jsonHasKey } from './contai
 import { kindOf, valueAt } from './cursor';
 import type { EntityCore } from './entity';
 import { EntityError } from './errors';
+import { searchInMemory } from './feature-errors';
 import { instantMicros } from './instant';
 import type { Predicate } from './tenancy';
 import type { ColumnKind } from './types';
@@ -158,6 +159,10 @@ export const matchesPredicate = <Row>(
   row: unknown,
   predicate: Predicate,
 ): boolean => {
+  // BEFORE anything is read off the row. A full-text match has no in-memory meaning — see
+  // `searchInMemory` — and `valueAt(row, '$search')` would answer `undefined`, which every
+  // comparison below reads as NULL and silently turns into "no rows".
+  if (predicate.op === 'matches') throw searchInMemory(entity.$name);
   // The column's declared kind, resolved once — `price.minor` included, which is the path a money
   // predicate and a money sort key both name.
   const kind = kindOf(entity, predicate.column);

package/src/pg-sql.ts

@@ -10,6 +10,7 @@ import { columnFor } from './column';
 import { isNullableKey, kindOf } from './cursor';
 import type { EntityCore } from './entity';
 import { SOFT_DELETE_COLUMN } from './entity';
+import { searchUndeclared } from './feature-errors';
 import { microsToIso, seekAlias } from './instant';
 import { allColumns, arrayLiteral, columnsOf, physicalName } from './pg-row';
 import type { Predicate, QueryPlan, SortKey } from './tenancy';
@@ -28,7 +29,38 @@ export interface ReadShape {
 const columnRef = <Row>(entity: EntityCore<Row>, path: string): SqlFragment =>
   identifier(physicalName(entity, path));
 
+/**
+ * `websearch_to_tsquery`, and the choice is the point of the whole feature.
+ *
+ * `to_tsquery` reads its argument as tsquery SYNTAX — `&`, `|`, `!`, `<->`, `:*`, parentheses — so
+ * a term straight out of a search box is either a `42601` on the first unbalanced paren or, worse,
+ * an operator the caller did not write. `plainto_tsquery` is safe but ANDs every word and throws
+ * the user's own operators away silently. `websearch_to_tsquery` is the parser Postgres ships for
+ * untrusted input: it never raises a syntax error, and it gives `"quoted phrase"`, `or` and a
+ * leading `-` the meaning every search box on the web already has. Cats & dogs is three terms.
+ *
+ * The term crosses as a BOUND PARAMETER either way — nothing here interpolates it — so the choice
+ * is not what stops an injection; the parameter is. What the parser decides is whether the user's
+ * punctuation is read as syntax, which is the second half of the same question.
+ *
+ * The configuration is spliced through `raw()`, from `SEARCH_LANGUAGES`, exactly as `asc|desc` is:
+ * a closed set of one word, chosen by this file from the ENTITY's declaration and never from a
+ * value on the wire. `regconfig` cannot be a bound parameter and stay index-matchable anyway.
+ */
+const searchSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFragment => {
+  const vector = entity.$search;
+  if (vector === null) throw searchUndeclared(entity.$name);
+  const column = identifier(vector.column);
+  // The term as TEXT, whatever arrived: `websearch_to_tsquery` takes text, and a number or a null
+  // reaching it as a parameter is a `42883` where the caller is owed "no rows".
+  const term = predicate.value === null || predicate.value === undefined ? '' : predicate.value;
+  return sql`${column} @@ websearch_to_tsquery(${raw(`'${vector.language}'`)}, ${String(term)})`;
+};
+
 const predicateSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFragment => {
+  // BEFORE the column is resolved: a `matches` predicate names `SEARCH_PROPERTY`, which is not a
+  // column and must never be looked up as one.
+  if (predicate.op === 'matches') return searchSql(entity, predicate);
   const column = columnRef(entity, predicate.column);
   const value = predicate.value;
   switch (predicate.op) {

package/src/query.ts

@@ -8,13 +8,16 @@ import type { BatchIterator } from './batch';
 import { assertBatchable, batchIterator } from './batch';
 import { entityNow } from './clock';
 import type { EntityCore } from './entity';
+import { searchUndeclared } from './feature-errors';
 import { assertPageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
 import type { RelatedTables } from './preload';
 import { preloaded } from './preload';
 import type { Relation } from './relations';
 import { relationNamed } from './relations';
 import type { Page, Repo, RepoOptions, UpsertArgs } from './repo';
+import { SEARCH_PROPERTY } from './search';
 import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
+import { transitionRow } from './transition';
 import type { ColumnMap, IdOf, Insertable, MoneyValue, RowPatch } from './types';
 
 /**
@@ -28,6 +31,23 @@ export interface ReadBuilder<Row> {
   /** Equality on the columns given. `where({ orgId })` is what satisfies the tenancy guard. */
   where(filter: RowPatch<Row>): ReadBuilder<Row>;
   andWhere(column: keyof Row & string, op: Operator, value: unknown): ReadBuilder<Row>;
+  /**
+   * Full-text search over the entity's generated `tsvector` — every `.searchable()` column at
+   * once, one GIN index, one predicate. `posts.where({ orgId }).search(input.q).limit(20).page()`.
+   *
+   * `term` is USER TEXT and is treated as such end to end: it crosses as a bound parameter and is
+   * parsed by `websearch_to_tsquery`, so `&`, `|`, `!`, `:*` and an unbalanced paren are characters
+   * to be matched, never operators and never a syntax error. There is deliberately no way to hand
+   * this layer a tsquery — a query language inside the query language is a second way to ask, and
+   * the one caller that would want it is the injection this method exists to make unreachable.
+   *
+   * It is an ordinary predicate, so the chain's tenancy, soft delete, projection, order, cursor
+   * and page size all mean here exactly what they mean without it. RELEVANCE is not an order this
+   * chain can serve: `ts_rank` is a computed value and the cursor carries columns, so the order
+   * stays the one the caller declared. An entity with no searchable column is `X_SEARCH_UNDECLARED`
+   * and the in-memory driver is `X_SEARCH_IN_MEMORY` — never a different answer from the two.
+   */
+  search(term: string): ReadBuilder<Row>;
   orderBy(column: keyof Row & string, direction?: SortDirection): ReadBuilder<Row>;
   limit(rows: number): ReadBuilder<Row>;
   /** The cursor from the previous page. */
@@ -128,6 +148,32 @@ export interface ReadBuilder<Row> {
 }
 
 export interface Table<Row, C extends ColumnMap = ColumnMap> extends ReadBuilder<Row> {
+  /**
+   * Move one row through the state machine `column` declares, in ONE statement.
+   *
+   * `from` is the state the caller believes the row is in, and it rides in the statement's own
+   * predicate — so the state that was observed and the state that was written are one decision,
+   * made under the row's lock. A read-then-check-then-write is the same call with a window in it,
+   * and under two concurrent callers the second one writes a transition out of a state the row had
+   * already left. Here the second statement matches no row: `X_STATE_CONFLICT`, naming the state
+   * the row is really in.
+   *
+   * A move the machine does not hold is `X_STATE_TRANSITION_ILLEGAL` and never reaches the
+   * database — the table is a property of the declaration. A move out of a TERMINAL state is the
+   * same code saying so; a terminal state is one whose outgoing list is empty, which is the whole
+   * of the concept and the only part of it the framework owns. Which state is terminal, what any
+   * of them mean, who may make a move and what happens on arrival are the app's, every one.
+   *
+   * Tenant-scoped exactly as `updateWhere` is, because it IS one: a row in another org matches no
+   * statement and reads back as absent, so the answer is `X_NOT_FOUND` rather than a conflict that
+   * would confirm it exists.
+   */
+  transition<K extends keyof Row & string>(
+    column: K,
+    id: IdOf<Row>,
+    move: { readonly from: Row[K] & string; readonly to: Row[K] & string },
+    options?: RepoOptions,
+  ): Promise<Row>;
   insert(values: Insertable<C>, options?: RepoOptions): Promise<Row>;
   /**
    * Many rows, one statement — the bulk write a per-row `insert` loop is the N+1 of, and the line
@@ -241,6 +287,16 @@ const builder = <Source, Row>(
 
     andWhere: (column, op, value) => next({ where: [...state.where, { column, op, value }] }),
 
+    // Refused HERE as well as at the statement, because this is the line the author wrote: a chain
+    // over an entity that declares nothing searchable can never produce a match, and the repair is
+    // one edit to the schema rather than anything about this call.
+    search: (term) => {
+      if (entity.$search === null) throw searchUndeclared(entity.$name);
+      return next({
+        where: [...state.where, { column: SEARCH_PROPERTY, op: 'matches', value: term }],
+      });
+    },
+
     orderBy: (column, direction = 'asc') =>
       next({ orderBy: [...state.orderBy, { column, direction }] }),
 
@@ -401,4 +457,9 @@ export const tableFor = <Row, C extends ColumnMap>(
   deleteWhere: async (filter, options) => repo.deleteWhere(filter, options),
   updateWhere: async (filter, patch, options) =>
     repo.updateWhere(filter, touch(entity, patch), options),
+  // `touch` is passed rather than applied here: a transition IS an update, so an `onUpdateNow()`
+  // column has to move exactly as `update(id, patch)` moves it — which is also the audit of WHEN
+  // the row moved, using the stamp already declared instead of a second one beside it.
+  transition: async (column, id, move, options) =>
+    transitionRow(entity, repo, column, id, move, (patch) => touch(entity, patch), options),
 });

package/src/registry.ts

@@ -25,6 +25,15 @@ export interface ColumnDescription {
    * projection reaches no `alter table` at all. It reached none until 3.0.
    */
   readonly onDelete: OnDelete | null;
+  /**
+   * The `generated always as (<expr>) stored` body, when the DATABASE computes this column rather
+   * than a writer. Absent on every ordinary column, matching `IndexDescription.using`: a
+   * description written before this existed reads the same, so nothing regenerates.
+   *
+   * `@ultimat3/db` is tier 1 and cannot import this package, so — exactly like `onDelete` — a
+   * field that is not on this projection reaches no DDL at all.
+   */
+  readonly generated?: string;
 }
 
 /**

package/src/search.ts

@@ -0,0 +1,153 @@
+// The full-text search vector an entity DERIVES from its `.searchable()` columns: one generated
+// `tsvector` column, one language, one weight per source. Everything spliced into the expression
+// here comes from a closed set or from a physical column name `assertColumnName` already checked —
+// a search TERM never reaches this file, because a term is bound as a parameter (`pg-sql.ts`).
+
+import type { SearchWeight } from './types';
+
+/**
+ * Postgres' own default text search configurations, as `\dF` lists them on 13 and later. A CLOSED
+ * set because the configuration is the one part of `to_tsvector(config, text)` that cannot be a
+ * bound parameter inside a generated column — it is spliced — so it may only ever be a value this
+ * file already contains. A server without one of these answers `3F000` at `create table`, which is
+ * loud and lands on the author, not on a search.
+ */
+export const SEARCH_LANGUAGES = [
+  'arabic',
+  'armenian',
+  'basque',
+  'catalan',
+  'danish',
+  'dutch',
+  'english',
+  'finnish',
+  'french',
+  'german',
+  'greek',
+  'hindi',
+  'hungarian',
+  'indonesian',
+  'irish',
+  'italian',
+  'lithuanian',
+  'nepali',
+  'norwegian',
+  'portuguese',
+  'romanian',
+  'russian',
+  'serbian',
+  'simple',
+  'spanish',
+  'swedish',
+  'tamil',
+  'turkish',
+  'yiddish',
+] as const;
+
+export type SearchLanguage = (typeof SEARCH_LANGUAGES)[number];
+
+/** The one membership test. `includes` on the tuple, never a computed read of a table. */
+export const isSearchLanguage = (value: unknown): value is SearchLanguage =>
+  typeof value === 'string' && (SEARCH_LANGUAGES as readonly string[]).includes(value);
+
+export const SEARCH_WEIGHTS = ['A', 'B', 'C', 'D'] as const;
+
+export const isSearchWeight = (value: unknown): value is SearchWeight =>
+  typeof value === 'string' && (SEARCH_WEIGHTS as readonly string[]).includes(value);
+
+/** Postgres' own default weight, so an unweighted source ranks exactly as an unweighted vector. */
+export const DEFAULT_SEARCH_WEIGHT: SearchWeight = 'D';
+
+export const DEFAULT_SEARCH_LANGUAGE: SearchLanguage = 'english';
+
+export const DEFAULT_SEARCH_COLUMN = 'search_tsv';
+
+/**
+ * What a `matches` predicate names instead of a column. `$`-prefixed for the reason every member
+ * of `EntityCore` is: `assertColumnName` requires `[a-z_]` first, so no declared column can ever
+ * be spelled this, and a `matches` predicate can therefore never be confused with one on a real
+ * column. Nothing resolves it through `physicalName` — both drivers branch on the OPERATOR.
+ */
+export const SEARCH_PROPERTY = '$search';
+
+export interface SearchSource {
+  /** Physical column, already through `assertColumnName`. */
+  readonly column: string;
+  readonly weight: SearchWeight;
+}
+
+/** How an entity's search is declared, when the defaults do not fit the table it adopted. */
+export interface SearchInit {
+  /** The physical vector column, when `search_tsv` is taken or the table already named one. */
+  readonly column?: string;
+  readonly language?: SearchLanguage;
+}
+
+export interface SearchVector {
+  /** The physical `tsvector` column. Never a row property. */
+  readonly column: string;
+  readonly language: SearchLanguage;
+  readonly sources: readonly SearchSource[];
+  /** The `generated always as (…) stored` body. Deterministic in declaration order. */
+  readonly expression: string;
+}
+
+/**
+ * One `setweight(to_tsvector(…))` per source, concatenated in DECLARATION order.
+ *
+ * `setweight` even for a single unweighted source, so adding a second column never rewrites the
+ * first one's spelling — and a spelling change here is a `drop column` + `add column` on a table
+ * that may hold every row an app has. `coalesce(…, '')` because `to_tsvector` of NULL is NULL and
+ * `NULL || tsvector` is NULL: one nullable source would erase the whole vector for that row.
+ *
+ * Every function in it is immutable, which is what Postgres requires of a generated column —
+ * `to_tsvector(text)` with no configuration is NOT (it reads `default_text_search_config`), which
+ * is why the language is named here and never left to the server.
+ */
+export const searchExpression = (
+  language: SearchLanguage,
+  sources: readonly SearchSource[],
+): string =>
+  sources
+    .map(
+      (source) =>
+        `setweight(to_tsvector('${language}', coalesce("${source.column}", '')), '${source.weight}')`,
+    )
+    .join(' || ');
+
+/**
+ * The vector a set of already-resolved sources describes, or `null` when there are none.
+ *
+ * The physical names arrive resolved and the collision check arrives as `taken`, so this module
+ * imports nothing from `column.ts` — which imports THIS one for `.searchable()`. A cycle between
+ * the column chain and the thing a column modifier declares is avoidable, so it is avoided.
+ */
+export const searchVectorOf = (
+  sources: readonly SearchSource[],
+  init: SearchInit | undefined,
+  taken: (column: string) => boolean,
+  refuse: (subject: string, detail: string) => never,
+): SearchVector | null => {
+  if (sources.length === 0) {
+    if (init === undefined) return null;
+    return refuse(
+      'search',
+      'search is declared but no column is searchable — add .searchable() to a text() column, or drop the search option',
+    );
+  }
+  const language = init?.language ?? DEFAULT_SEARCH_LANGUAGE;
+  if (!isSearchLanguage(language)) {
+    return refuse(
+      'search',
+      `"${String(language)}" is not a Postgres text search configuration — one of: ${SEARCH_LANGUAGES.join(', ')}`,
+    );
+  }
+  const column = init?.column ?? DEFAULT_SEARCH_COLUMN;
+  if (taken(column)) {
+    return refuse(
+      'search',
+      `the search vector column "${column}" is already a declared column — rename it, or name another with search: { column: '<name>' }`,
+    );
+  }
+  return { column, language, sources, expression: searchExpression(language, sources) };
+};