@ultimat3/entity 11.3.0 → 13.0.0

package/src/cursor.ts

@@ -10,6 +10,7 @@ import { CursorInvalidError, decodeCursor, encodeCursor } from '@ultimat3/core';
 import { columnFor } from './column';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
+import { instantMicros } from './instant';
 import type { QueryPlan } from './tenancy';
 import type { AnyColumn, ColumnKind } from './types';
 
@@ -89,8 +90,36 @@ export const valueAt = (row: unknown, path: string): unknown => {
     : undefined;
 };
 
-/** Stringified so the cursor is JSON; `revive` restores the type from the column's kind. */
-const serializeSortValue = (value: unknown): string => {
+/**
+ * Stringified so the cursor is JSON; `revive` restores the type from the column's kind — and the
+ * KIND decides how, never the JS type in hand, because those are two different questions on
+ * exactly the column that made this file wrong.
+ *
+ * A `timestamptz` is carried as MICROSECONDS since the epoch, not as `toISOString()`. The column
+ * holds microseconds and a `Date` holds milliseconds, so an ISO rendition of a decoded row is the
+ * row's own position FLOORED — and a seek built from a floored position ranks rows differently
+ * from the `order by` that produced them, which silently drops every row inside the boundary
+ * millisecond. Proven against a real server: `pg-cursor-precision.live.test.ts`.
+ */
+const ABSENT_MARK = '~';
+const PRESENT_MARK = '!';
+
+/**
+ * A sort value's place in the cursor is TAGGED, so absence can be told from the text that spells
+ * it: `~` alone is NULL, `!` prefixes a present value. Positional, therefore total — a `text`
+ * column holding the four characters `null` encodes as `!null` and can never be read as an absent
+ * one, which is the collision a bare sentinel value would reopen.
+ *
+ * The tag exists because a nullable sort key is legal `As of 2026-08-24` (`asc nulls last` /
+ * `desc nulls first`, `@ultimat3/query`'s spelling), and a keyset position over one has to be able
+ * to say "the boundary row had none".
+ */
+const tagged = (text: string): string => `${PRESENT_MARK}${text}`;
+
+const serializeSortValue = (kind: ColumnKind, value: unknown): string | undefined => {
+  // `undefined`, never `'0'`: a position nothing could read would decode to the epoch, which is
+  // "start from the top" wearing a signature — the one thing a cursor must never mean.
+  if (kind === 'timestamptz') return instantMicros(value)?.toString();
   if (value instanceof Date) return value.toISOString();
   if (typeof value === 'bigint') return value.toString();
   return String(value);
@@ -108,8 +137,16 @@ const serializeSortValue = (value: unknown): string => {
 // constant three lines above it.
 const reviveSortValue = (kind: ColumnKind, text: string): unknown => {
   switch (kind) {
-    case 'timestamptz':
-      return new Date(text);
+    case 'timestamptz': {
+      // Microseconds since the epoch — the precision the COLUMN keeps, which a `Date` cannot.
+      // A cursor minted before that decision carries an ISO string, so this is where it is
+      // refused: `BigInt('2026-…')` is a bare `SyntaxError` with no code and no fix.
+      const micros = instantMicros(text);
+      if (micros === undefined) {
+        throw new CursorInvalidError('its position is not a microsecond instant');
+      }
+      return micros;
+    }
     case 'bigint':
       return BigInt(text);
     case 'integer':
@@ -125,9 +162,12 @@ const reviveSortValue = (kind: ColumnKind, text: string): unknown => {
  * A keyset seek only has a total order when every sort column is present on every row —
  * `null > 'x'` is unknown in SQL and would drop rows from the middle of a listing.
  *
- * Checked when a cursor is minted as well as when one is decoded: an ordering that cannot carry
- * a position is the author's mistake, and reporting it on the *second* page hides it behind
- * whatever page size the caller happened to use.
+ * Checked where the PLAN is built (`planFor`), which is every read either driver sends, as well as
+ * when a cursor is minted and when one is decoded. The plan is the load-bearing one: `cursorFor`
+ * runs only when a page found a row past its limit, so the refusal used to depend on how many rows
+ * the table happened to hold — green on fifteen seeded rows, `X_INVARIANT_VIOLATED` on the first
+ * read past a page of twenty in production. An ordering that cannot carry a position is the
+ * author's mistake at any row count.
  */
 export const assertSeekable = <Row>(
   entity: EntityCore<Row>,
@@ -138,15 +178,28 @@ export const assertSeekable = <Row>(
     // money property named without its part — both mint a cursor nothing can decode.
     kindAt(entity, key.column);
     if (columnAt(entity, key.column).$meta.notNull) continue;
+    // An ORDINARY nullable key is orderable, `As of 2026-08-24`: NULL has a declared place
+    // (`asc nulls last` / `desc nulls first`), the cursor carries that place, and the seek reaches
+    // it. What is left is the TIEBREAK — `totalOrder` appends the primary key precisely so two
+    // rows sharing a sort value cannot straddle a page boundary, and a nullable primary-key column
+    // cannot do that job: `null = null` is unknown, so two such rows are indistinguishable to the
+    // seek and one of them is served twice or never. Reachable only through `primaryKey: [...]`,
+    // which takes the columns as declared.
+    if (!entity.$primaryKey.includes(key.column)) continue;
     throw invariantViolated(
       entity.$name,
       'cursor',
-      `${key.column} is nullable and cannot carry a cursor — order by a not-null column ` +
-        `(add .orderBy('${entity.$primaryKey[0] ?? 'id'}') or make ${key.column} not null)`,
+      `${key.column} is part of the primary key and is nullable, so no ordering can be total — ` +
+        'an ordinary nullable column orders fine (nulls last ascending, nulls first descending), ' +
+        `but the tiebreak cannot: drop .nullable() from ${key.column}`,
     );
   }
 };
 
+/** Whether a sort key may hold NULL — what decides the seek's SHAPE, not only its values. */
+export const isNullableKey = <Row>(entity: EntityCore<Row>, path: string): boolean =>
+  !columnAt(entity, path).$meta.notNull;
+
 /** Deterministic, and total over the value shapes a predicate can hold. */
 const renderValue = (value: unknown): string => {
   if (value === null || value === undefined) return 'null';
@@ -182,17 +235,37 @@ export const planScope = (plan: QueryPlan): string => {
     .slice(0, 16);
 };
 
-/** The cursor that continues this plan after `row`. Signed by core, scoped by the plan. */
+/**
+ * The cursor that continues this plan after `row`. Signed by core, scoped by the plan.
+ *
+ * `exact` is how a driver hands over a value the DECODED row cannot hold: a `timestamptz` comes
+ * back as a `Date`, which is milliseconds, and the microseconds it dropped are the difference
+ * between a position the `order by` agrees with and one it does not. Optional because the
+ * in-memory driver stores millisecond `Date`s and therefore has nothing finer to give.
+ */
 export const cursorFor = <Row>(
   entity: EntityCore<Row>,
   plan: QueryPlan,
   row: unknown,
   id: string,
+  exact?: ReadonlyMap<string, unknown>,
 ): string => {
   assertSeekable(entity, plan.orderBy);
   return encodeCursor({
     scope: planScope(plan),
-    key: plan.orderBy.map((entry) => serializeSortValue(valueAt(row, entry.column))),
+    key: plan.orderBy.map((entry) => {
+      const value = exact?.get(entry.column) ?? valueAt(row, entry.column);
+      // A column the row never named and a stored NULL are one absence everywhere else in this
+      // package (`isNull`), and they are one position here too.
+      if (value === null || value === undefined) return ABSENT_MARK;
+      const text = serializeSortValue(kindAt(entity, entry.column), value);
+      if (text !== undefined) return tagged(text);
+      throw invariantViolated(
+        entity.$name,
+        'cursor',
+        `${entry.column} on the last row of the page holds no instant a cursor can carry`,
+      );
+    }),
     id,
   });
 };
@@ -216,7 +289,20 @@ export const seekFrom = <Row>(
       `it carries ${key.length} sort values, this order needs ${plan.orderBy.length}`,
     );
   }
-  return plan.orderBy.map((entry, index) =>
-    reviveSortValue(kindAt(entity, entry.column), String(key[index])),
-  );
+  return plan.orderBy.map((entry, index) => {
+    // `segment` and `ABSENT_MARK`, never `token` and `NULL_KEY`: both names said CREDENTIAL to
+    // `bun run secret-compare`, whose rule is that a `===` on one leaks it a byte at a time. What
+    // this compares is a page POSITION against a one-character tag, where the repair the guard
+    // names — `timingSafeEqual` — would be constant-time nonsense. The guard reads names because a
+    // unit test cannot assert timing, so the name is the thing that has to be right.
+    const segment = String(key[index]);
+    if (segment === ABSENT_MARK) return null;
+    if (!segment.startsWith(PRESENT_MARK)) {
+      // Every cursor this package mints carries a tag. An untagged one was forged past the
+      // signature or minted before nullable sort keys existed; either way the alternative is a
+      // silent restart at the top, which is the one thing a cursor may never mean.
+      throw new CursorInvalidError('a sort value carries no null-or-value tag');
+    }
+    return reviveSortValue(kindAt(entity, entry.column), segment.slice(PRESENT_MARK.length));
+  });
 };

package/src/database.ts

@@ -2,11 +2,11 @@
 // writes a repository class per entity, and nobody can reach a table that is not in the set.
 
 import type { EntityCore } from './entity';
+import { memoryRepo } from './memory-repo';
 import type { RelatedTables } from './preload';
 import type { Table } from './query';
 import { tableFor } from './query';
 import type { Repo } from './repo';
-import { memoryRepo } from './repo';
 import { observedRepo } from './row-observer';
 
 export type EntitySet = Readonly<Record<string, EntityCore>>;

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,
@@ -188,6 +220,9 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
       unique: index.unique,
       where: index.where ?? null,
       order: index.order ?? null,
+      // Spread, never `?? null`: absent is what `@ultimat3/db` reads as the btree it always was,
+      // and a written-out `null` would be a field no existing snapshot carries.
+      ...(index.using === undefined ? {} : { using: index.using }),
     })),
     tags: input.tags,
     cacheTag: input.cacheTag,

package/src/entity.ts

@@ -4,6 +4,7 @@
 // this one call.
 
 import { renderThrowable } from '@ultimat3/core';
+import type { IndexMethod } from '@ultimat3/db';
 import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
 import { entityNow } from './clock';
 import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
@@ -12,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';
@@ -30,6 +34,21 @@ export interface IndexInit<C extends ColumnMap> {
   readonly unique?: boolean;
   /** Partial index predicate, written in the same language as an invariant. */
   readonly where?: (columns: InvariantColumns<C>) => Expr;
+  /**
+   * The access method. Omitted is `btree`, which is Postgres' own default and what every index
+   * declared before this existed is — so an entity that names none emits the statement it always
+   * emitted and nothing regenerates.
+   *
+   * `'gin'` is the one with a caller, and it is the whole point of the containment operators:
+   * measured on Postgres 16 over 20,000 rows, `tags @> …`, `tags <@ …`, `tags && …` and
+   * `data @> …` are each a Bitmap Index Scan with one and a Seq Scan without. The set is
+   * `@ultimat3/db`'s `INDEX_METHODS`, imported rather than restated — one declaration of one fact.
+   *
+   * Two Postgres rules ride with it and both are refused HERE, where the author is, rather than at
+   * `x db gen` or inside `ROLE=migrate` as the server's own syntax error: a GIN index cannot be
+   * unique and cannot order its keys.
+   */
+  readonly using?: IndexMethod;
 }
 
 export interface EntityInit<C extends ColumnMap> {
@@ -57,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[];
 }
@@ -79,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. */
@@ -109,9 +139,6 @@ export type Entity<Row, C extends ColumnMap = ColumnMap> = EntityCore<Row, C> &
 
 const MONEY_PARTS = new Set(['minor', 'currency']);
 
-const indexName = (table: string, columns: readonly string[], unique: boolean): string =>
-  `${table}_${columns.join('_')}_${unique ? 'key' : 'idx'}`;
-
 const defaultValue = (meta: ColumnMeta): unknown => {
   const declared = meta.default;
   if (declared === undefined) return undefined;
@@ -127,11 +154,30 @@ export const entity = <const C extends ColumnMap>(
   const entries: readonly (readonly [string, AnyColumn])[] = Object.entries(init.columns);
   for (const [property, column] of entries) bindColumn(column, name, property);
 
-  const table = init.table === undefined ? name : assertColumnName(init.table);
+  // Both branches. The declared table was checked and the fallback — which is every entity that
+  // does not rename its table — was not, so an entity NAME closed the identifier in the same way a
+  // column name could: `entity('t" (x int); drop table u; --')` emitted that `drop table` verbatim.
+  const table = assertColumnName(init.table ?? name);
   const cacheTag = `entity:${name}`;
   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) {
@@ -187,7 +233,11 @@ export const entity = <const C extends ColumnMap>(
         meta.kind === 'money' ? moneyColumns(property, meta).minor : columnName(property, meta),
       ];
       return [
-        { name: indexName(table, physical, meta.unique), columns: physical, unique: meta.unique },
+        {
+          name: indexName(name, table, physical, meta.unique),
+          columns: physical,
+          unique: meta.unique,
+        },
       ];
     }),
     ...(init.indexes ?? []).map((index) => {
@@ -206,18 +256,75 @@ export const entity = <const C extends ColumnMap>(
           'a partial index predicate must be expressible in SQL; a JS predicate cannot be one',
         );
       }
+      // Two rules Postgres has that a declaration can break, refused where the author wrote it.
+      // `@ultimat3/db` refuses both again at `createIndex` — that is not a duplicate, it is the
+      // guard for a description nobody built here — but its refusal lands at `x db gen` or, if a
+      // migration was already written, inside `ROLE=migrate` as the server's own syntax error with
+      // none of the entity's words in it.
+      if (index.using !== undefined && index.using !== 'btree') {
+        if (unique) {
+          throw invariantViolated(
+            name,
+            'index',
+            `the index on (${columns.join(', ')}) is unique and ${index.using}; ` +
+              `Postgres has no unique ${index.using} index — drop unique, or drop using`,
+          );
+        }
+        if (index.order !== undefined) {
+          throw invariantViolated(
+            name,
+            'index',
+            `the index on (${columns.join(', ')}) is ${index.using} and ${index.order}; ` +
+              'only a btree orders its keys — drop order, or drop using',
+          );
+        }
+      }
       return {
-        name: indexName(table, columns, unique),
+        name: indexName(name, table, columns, unique, index.order, where, index.using),
         columns,
         unique,
         ...(index.order === undefined ? {} : { order: index.order }),
         ...(where === null ? {} : { where }),
+        // Absent stays absent: `btree` written out would be a field every existing snapshot lacks,
+        // and `indexMethodOf` reads the two the same way precisely so nothing regenerates.
+        ...(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.
+  /**
+   * A foreign key already indexes its column; naming it again in `indexes` is not two indexes.
+   *
+   * On the WHOLE definition and not on the name. With the discriminator above the two rules agree
+   * exactly, so this is not a behaviour change on its own — it is which one FAILS LOUDLY if the
+   * naming is ever weakened again. Matching on the name drops the second index in silence, which
+   * is how two different partial indexes became one for three majors; matching on the definition
+   * keeps both, and two `create index` statements sharing a name is `42P07` on the next migration.
+   */
+  const identity = (index: IndexDef): string =>
+    [
+      index.name,
+      index.columns.join(','),
+      index.unique,
+      index.order ?? '',
+      index.where ?? '',
+      index.using ?? '',
+    ].join('|');
   const indexes: readonly IndexDef[] = declared.filter(
-    (index, position) => declared.findIndex((other) => other.name === index.name) === position,
+    (index, position) =>
+      declared.findIndex((other) => identity(other) === identity(index)) === position,
   );
 
   const tags = [cacheTag, ...(init.tags ?? [])];
@@ -233,6 +340,7 @@ export const entity = <const C extends ColumnMap>(
       cacheTag,
       softDelete,
       tenantColumn,
+      search,
     });
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);
 
@@ -277,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();
+    },
+  };
+};

package/src/errors.ts

@@ -18,6 +18,14 @@ export const ENTITY_OWNED_ERROR_CODES = [
   'X_N_PLUS_ONE_QUERY',
   'X_N_PLUS_ONE_WRITE',
   'X_REPO_CLIENT_PINNED',
+  '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;
 
 /**
@@ -52,6 +60,14 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>>
   X_N_PLUS_ONE_QUERY: 'a read repeated once per row',
   X_N_PLUS_ONE_WRITE: 'a write repeated once per row',
   X_REPO_CLIENT_PINNED: 'a repository pinned to its own client cannot join the open transaction',
+  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