@ultimat3/entity 12.0.0 → 14.0.0

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 { assertInvariants, bindInvariant } 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. */
@@ -110,8 +124,10 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   $view<K extends keyof Row & string>(keys: readonly K[]): EntityView<Row, K>;
   /** Runs every invariant. Called by the repository on insert and update. */
   $assert(row: Row): void;
-  /** The CHECK/UNIQUE statements the migration emits for this entity. */
-  $migration(): string;
+  // No `$migration()`. The CHECK/UNIQUE statements an entity contributes are `@ultimat3/db`'s to
+  // render, off `$describe()`, beside the columns, indexes and foreign keys they have to be
+  // ordered against — a fragment of a migration is not one, and the one here named the wrong
+  // relation for three majors because nothing but its own test ever read it.
   $describe(): EntityDescription;
   /**
    * The foreign keys this entity declares, resolved — one record per `references()`, both ends
@@ -125,88 +141,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 +164,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 +292,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 +342,7 @@ export const entity = <const C extends ColumnMap>(
       cacheTag,
       softDelete,
       tenantColumn,
+      search,
     });
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);
 
@@ -423,6 +387,7 @@ export const entity = <const C extends ColumnMap>(
     $cacheTag: cacheTag,
     $softDelete: softDelete,
     $tenantColumn: tenantColumn,
+    $search: search,
     $schema: {
       '~standard': {
         version: 1,
@@ -451,7 +416,6 @@ export const entity = <const C extends ColumnMap>(
     $view: <K extends keyof Row & string>(keys: readonly K[]) =>
       viewFor<Row, K>(name, init.columns, keys),
     $assert: (row) => assertInvariants(name, invariants, row),
-    $migration: () => invariantsToSql(name, invariants),
     $describe: describe,
     $references: references,
   };

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

@@ -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,15 +65,17 @@ export {
   writeUnfiltered,
 } from './errors';
 export type { ColumnExpr, Expr, InvariantColumns, Resolve } from './expr';
-export type { Invariant, InvariantDef, InvariantKind } from './invariants';
+/** The two DECLARED capabilities' refusals — a third-party driver raises the same ones. */
+export type { IllegalTransition } from './feature-errors';
 export {
-  assertInvariants,
-  constraintName,
-  invariant,
-  invariantsToSql,
-  MAX_ASSERTED_ROWS,
-  toSql,
-} from './invariants';
+  searchInMemory,
+  searchUndeclared,
+  stateConflict,
+  stateTransitionIllegal,
+  stateUndeclared,
+} from './feature-errors';
+export type { Invariant, InvariantDef, InvariantKind } from './invariants';
+export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
 export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
@@ -116,6 +118,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 +144,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 +167,7 @@ export {
   scopedPlan,
   tenantColumnOf,
 } from './tenancy';
+export type { Move } from './transition';
 export type {
   AnyColumn,
   Column,
@@ -148,6 +175,7 @@ export type {
   ColumnKind,
   ColumnMap,
   ColumnMeta,
+  EnumeratedColumn,
   IdOf,
   IndexDef,
   Insertable,
@@ -158,6 +186,8 @@ export type {
   ReferenceOptions,
   RowOf,
   RowPatch,
+  RowWrite,
+  SearchWeight,
   TimestampColumn,
   TypeOf,
   UuidColumn,

package/src/invariants.ts

@@ -69,28 +69,13 @@ export const bindInvariant = <T>(
   };
 };
 
-export const constraintName = (
-  table: string,
-  inv: { readonly name: string; readonly kind: InvariantKind },
-): string => `${table}_${inv.name}_${inv.kind === 'unique' ? 'key' : 'check'}`;
-
-/** The DDL the migration emits. One statement, terminated, ready to diff. */
-export const toSql = <T>(table: string, inv: Invariant<T>): string | null => {
-  if (inv.sql === null) return null;
-  const name = constraintName(table, inv);
-  if (inv.kind === 'check') {
-    return `ALTER TABLE "${table}" ADD CONSTRAINT "${name}" CHECK (${inv.sql});`;
-  }
-  const where = inv.where === undefined ? '' : ` WHERE ${inv.where}`;
-  const columns = inv.columns.map((column) => `"${column}"`).join(', ');
-  return `CREATE UNIQUE INDEX "${name}" ON "${table}" (${columns})${where};`;
-};
-
-export const invariantsToSql = <T>(table: string, invariants: readonly Invariant<T>[]): string =>
-  invariants
-    .map((inv) => toSql(table, inv))
-    .filter((statement): statement is string => statement !== null)
-    .join('\n');
+// The DDL an invariant becomes is NOT rendered here. `@ultimat3/db` owns it — `constraintNameFor`,
+// `declaredChecks` and `declaredIndexes` (`invariant-ddl.ts`), reading `$describe()` — and this
+// package rendered a second copy of the same fact until 2026-08-25. The copy is what made the case
+// for one renderer: it was reachable only through `entity.$migration()`, which passed the entity
+// NAME where the table belongs, so `entity('account', { table: 'legacy_accounts' })` rendered
+// `ALTER TABLE "account" ADD CONSTRAINT "account_seats_non_negative_check" …` — a relation that
+// does not exist and a constraint name no migration ever wrote. Never re-render it here.
 
 /**
  * Whether any rule here can only be judged in the app. This is what decides whether a FILTERED