@ultimat3/entity 12.0.0 → 13.0.0

package/src/state-machine.ts

@@ -0,0 +1,132 @@
+// The MECHANISM half of a state machine on a column: the transition table, what a terminal state
+// is, and the one legality question. The states themselves never ship — they arrive as the
+// `enumerated()` set the column already declares, and nothing in this file knows what any of them
+// means. An illegal transition is a defect in every business; an approval chain is not.
+
+import { refuseColumn } from './refuse';
+
+/**
+ * Every state names the states it may move to. A MAPPED type over the union, so the exhaustiveness
+ * is the compiler's: a state left out, a key that is not a state and a target that is not a state
+ * are each a compile error at the declaration, and the runtime checks below are what a JS caller
+ * and a table built from parsed JSON get instead.
+ *
+ * A state with an empty list is TERMINAL. That is the whole of the terminal concept — nothing to
+ * declare, nothing to name, and no way for the framework to have an opinion about which one it is.
+ */
+export type TransitionTable<S extends string> = { readonly [K in S]: readonly S[] };
+
+export interface StateMachine<S extends string = string> {
+  /** The declared states, in declaration order. */
+  readonly states: readonly S[];
+  /**
+   * A `Map`, never the table object itself: `table[from]` with a caller's string answers an
+   * `Object.prototype` member, so `canMove(machine, 'constructor', …)` would read the `Object`
+   * function and every guard downstream would pass. The rule `bun run proto-index` enforces.
+   */
+  readonly moves: ReadonlyMap<S, ReadonlySet<S>>;
+  /** Derived: every state whose outgoing set is empty. */
+  readonly terminal: ReadonlySet<S>;
+}
+
+/**
+ * One `refuseColumn` site, five conditions, and the FIX comes from the caller — because a fix line
+ * carrying a `<placeholder>` is advice, not an edit, and `refuse.test.ts` refuses one. Every caller
+ * below names real states out of the set the column already declared, so each answer is pasteable.
+ */
+const refuse = (detail: string, fix: string): never => refuseColumn('transitions', detail, fix);
+
+/**
+ * The machine a set of states and a table describe, validated once at declaration.
+ *
+ * Every rule here is structural: it is about whether the table describes a machine at all, never
+ * about which machine is the right one. A table missing a state cannot answer "may this row move",
+ * a self-loop is a transition that transitions nothing — and under the compare-and-set the write
+ * path uses it would report a move that did not happen — and a repeated target is a typo whose
+ * only effect is to make the declaration read as though it meant something.
+ */
+export const stateMachineOf = <S extends string>(
+  states: readonly S[],
+  table: TransitionTable<S>,
+): StateMachine<S> => {
+  const declared = new Set<string>(states);
+  const keys = Object.keys(table);
+  const unknown = keys.filter((key) => !declared.has(key));
+  if (unknown.length > 0) {
+    refuse(
+      `${unknown.join(', ')} ${unknown.length === 1 ? 'is not one of' : 'are not among'} the declared states: ${states.join(' | ')}`,
+      `delete the ${unknown.map((key) => `"${key}"`).join(', ')} entry from transitions(), or add it to the enumerated([${states.map((state) => `'${state}'`).join(', ')}]) set on this column`,
+    );
+  }
+  const named = new Set(keys);
+  const missing = states.filter((state) => !named.has(state));
+  if (missing.length > 0) {
+    refuse(
+      `no entry for ${missing.join(', ')} — every state needs one, and a terminal state is written as an empty list`,
+      `add ${missing.map((state) => `${state}: []`).join(', ')} to transitions() — an empty list is how a state nothing leaves is written`,
+    );
+  }
+  const moves = new Map<S, ReadonlySet<S>>();
+  // `origin` and not `state`, which is the word this loop is about: `bun run secret-compare` reads
+  // a NAME, and `state` is in its vocabulary because an OAuth CSRF `state` is a credential compared
+  // with `===` — so a state machine, whose domain word is literally that, trips a rule written for
+  // a different thing. Renaming is the honest repair; a package-wide pin would spend the rule.
+  for (const origin of states) {
+    // Through `Object.hasOwn` even though the keys were just checked: this is the one read of a
+    // caller's object literal by a name, and the guard is what makes it a read of DATA.
+    const targets: readonly string[] = Object.hasOwn(table, origin) ? table[origin] : [];
+    const seen = new Set<S>();
+    for (const target of targets) {
+      if (!declared.has(target)) {
+        refuse(
+          `${origin} may move to ${target}, which is not one of: ${states.join(' | ')}`,
+          `remove '${target}' from the ${origin} entry of transitions(), or add it to the enumerated([${states.map((each) => `'${each}'`).join(', ')}]) set on this column`,
+        );
+      }
+      if (target === origin) {
+        refuse(
+          `${origin} lists itself as a target; a transition that changes nothing is not one`,
+          `remove '${origin}' from its own entry of transitions() — write ${origin}: [] if nothing leaves it`,
+        );
+      }
+      if (seen.has(target as S)) {
+        refuse(
+          `${origin} lists ${target} twice`,
+          `remove the second '${target}' from the ${origin} entry of transitions()`,
+        );
+      }
+      seen.add(target as S);
+    }
+    moves.set(origin, seen);
+  }
+  const terminal = new Set<S>(states.filter((state) => (moves.get(state)?.size ?? 0) === 0));
+  return { states: [...states], moves, terminal };
+};
+
+/** Whether the machine holds this exact move. Unknown states answer `false`, never throw. */
+export const canMove = <S extends string>(
+  machine: StateMachine<S>,
+  from: string,
+  to: string,
+): boolean => machine.moves.get(from as S)?.has(to as S) === true;
+
+export const isTerminal = <S extends string>(machine: StateMachine<S>, state: string): boolean =>
+  machine.terminal.has(state as S);
+
+/**
+ * Whether the machine declares this state at all — the question `isTerminal` cannot answer, and the
+ * reason it is asked FIRST at the call site. An unknown state has no outgoing moves either, so
+ * without this the refusal for a typo read "the row is terminal in <typo>", which is a sentence
+ * about a state that does not exist.
+ */
+export const isState = <S extends string>(machine: StateMachine<S>, state: string): boolean =>
+  machine.moves.has(state as S);
+
+/** Everywhere this state may go, in declaration order — what a refusal lists back at the caller. */
+export const movesFrom = <S extends string>(
+  machine: StateMachine<S>,
+  from: string,
+): readonly S[] => {
+  const targets = machine.moves.get(from as S);
+  return targets === undefined ? [] : machine.states.filter((state) => targets.has(state));
+};

package/src/tenancy.ts

@@ -39,7 +39,12 @@ export type Operator =
   | 'contains'
   | 'contained-by'
   | 'overlaps'
-  | 'has-key';
+  | 'has-key'
+  // The FULL-TEXT half, added 2026-08-24. `column` is not a column: it is `SEARCH_PROPERTY`, and
+  // both drivers branch on the OPERATOR and read the entity's own `$search` — a `tsvector` is a
+  // physical column no row carries, so resolving it as a property would be a lie in two places.
+  // The operand is a search TERM, always bound, never parsed as tsquery syntax.
+  | 'matches';
 
 export interface Predicate {
   readonly column: string;

package/src/transition.ts

@@ -0,0 +1,119 @@
+// One atomic move of one row through its column's state machine: the legality question answered
+// from the declaration, the move made by a single conditional statement, and the diagnosis of a
+// statement that matched nothing. Split from `query.ts` for the line ceiling and because this is
+// the one write whose refusal is a READ — see `diagnose`.
+
+import { columnFor } from './column';
+import type { EntityCore } from './entity';
+import { notFound } from './errors';
+import type { IllegalTransition } from './feature-errors';
+import { stateConflict, stateTransitionIllegal, stateUndeclared } from './feature-errors';
+import type { Repo, RepoOptions } from './repo';
+import { canMove, isState, isTerminal, movesFrom, type StateMachine } from './state-machine';
+import type { ColumnMap, IdOf, RowPatch } from './types';
+
+/** What a caller names: the state it believes the row is in, and the one it wants. */
+export interface Move<S extends string = string> {
+  readonly from: S;
+  readonly to: S;
+}
+
+/** Every property whose column declares a machine — what `X_STATE_UNDECLARED` lists back. */
+export const machineColumns = <Row, C extends ColumnMap>(
+  entity: EntityCore<Row, C>,
+): readonly string[] =>
+  Object.entries(entity.$columns)
+    .filter(([, column]) => column.$meta.machine !== undefined)
+    .map(([property]) => property);
+
+/**
+ * The machine on a named column, or the refusal. `columnFor` and not `$columns[property]`: the name
+ * is caller data on this path, and a plain read answers an `Object.prototype` member.
+ */
+export const machineFor = <Row, C extends ColumnMap>(
+  entity: EntityCore<Row, C>,
+  property: string,
+): StateMachine => {
+  const machine = columnFor(entity.$columns, property)?.$meta.machine;
+  if (machine === undefined) {
+    throw stateUndeclared(entity.$name, property, machineColumns(entity));
+  }
+  return machine;
+};
+
+/**
+ * Why the statement matched no row, asked only once it already has.
+ *
+ * A read AFTER the decision, never before one: the conditional update is what refused, and this
+ * exists so the refusal carries the state the row is really in instead of "0 rows". It is
+ * tenant-scoped like every other read, so a row belonging to another org reads as absent and the
+ * caller is told `X_NOT_FOUND` — which is the truth available to them, and the only answer that
+ * does not confirm the row exists somewhere.
+ */
+const diagnose = async <Row>(
+  entity: EntityCore<Row>,
+  repo: Repo<Row>,
+  property: string,
+  id: IdOf<Row>,
+  move: Move,
+  options: RepoOptions | undefined,
+): Promise<Error> => {
+  const row = await repo.findById(id, options);
+  if (row === null) return notFound(entity.$name, String(id));
+  const actual = (row as Readonly<Record<string, unknown>>)[property];
+  return stateConflict(entity.$name, property, String(id), move.from, String(actual));
+};
+
+const whyNot = (machine: StateMachine, move: Move): IllegalTransition => {
+  if (!isState(machine, move.from)) return { reason: 'unknown-state', states: machine.states };
+  if (isTerminal(machine, move.from)) return { reason: 'terminal' };
+  return { reason: 'not-declared', legal: movesFrom(machine, move.from) };
+};
+
+/**
+ * The move, made by ONE statement.
+ *
+ * The predicate carries the state the caller expects, so the state that was OBSERVED and the state
+ * that was WRITTEN are one decision the database made under its own row lock. A read-then-check-
+ * then-write is the same code with a window in it: two callers both read `pending`, both find the
+ * move legal, and both write — and the second write is a transition out of a state the row had
+ * already left. Here the second statement's `status = 'pending'` matches nothing, and no rows is
+ * the refusal.
+ *
+ * The legality question is answered before the statement rather than inside it, because the
+ * transition table is not in the database and does not belong there: it is a property of the
+ * declaration, so an illegal move is refused without a round trip and without touching the row.
+ *
+ * The row is READ BACK afterwards rather than returned by the statement. `updateWhere` answers a
+ * count in both drivers, and a second read is honest about what it is — the row as it stands now,
+ * which is the row this call moved unless something moved it again, and something moving it again
+ * is exactly what this design permits and reports.
+ */
+export const transitionRow = async <Row, C extends ColumnMap>(
+  entity: EntityCore<Row, C>,
+  repo: Repo<Row>,
+  property: string,
+  id: IdOf<Row>,
+  move: Move,
+  patch: (values: RowPatch<Row>) => RowPatch<Row>,
+  options: RepoOptions | undefined,
+): Promise<Row> => {
+  const machine = machineFor(entity, property);
+  if (!canMove(machine, move.from, move.to)) {
+    // Asked in this order and no other: an unknown state is terminal-looking (no outgoing moves)
+    // and a terminal state is legal-list-looking (an empty list), so a check that skipped either
+    // one would answer a true sentence about the wrong thing.
+    throw stateTransitionIllegal(entity.$name, property, move.from, move.to, whyNot(machine, move));
+  }
+  // `as unknown as`, and the double step is the honest one: `RowPatch<Row>` is a mapped type over
+  // an UNRESOLVED `Row`, so it never reduces and no object literal is ever assignable to it — the
+  // same reason `expr.ts` and `@ultimat3/query`'s `paginate` spell theirs the same way. The column
+  // name came from `machineFor`, which resolved it against the entity, so the shape is a real one.
+  const filter = { id, [property]: move.from } as unknown as RowPatch<Row>;
+  const values = { [property]: move.to } as unknown as RowPatch<Row>;
+  const written = await repo.updateWhere(filter, patch(values), options);
+  if (written === 0) throw await diagnose(entity, repo, property, id, move, options);
+  const row = await repo.findById(id, options);
+  if (row === null) throw notFound(entity.$name, String(id));
+  return row;
+};

package/src/types.ts

@@ -48,6 +48,13 @@ export type ColumnDefault =
 
 export type OnDelete = 'cascade' | 'restrict' | 'set null';
 
+/**
+ * A source column's contribution to the entity's search vector — Postgres' own four labels, which
+ * `ts_rank` weights `{D, C, B, A}` = `{0.1, 0.2, 0.4, 1.0}` by default. `D` is what an unweighted
+ * `to_tsvector` produces, so it is the default here too.
+ */
+export type SearchWeight = 'A' | 'B' | 'C' | 'D';
+
 export interface ReferenceOptions {
   readonly onDelete?: OnDelete;
 }
@@ -63,6 +70,7 @@ export interface ReferenceOptions {
  * `t.money` — the schema node that becomes the OpenAPI contract — rejected the framework's own row.
  */
 import type { MoneyValue } from '@ultimat3/schema';
+import type { StateMachine, TransitionTable } from './state-machine';
 
 export type { MoneyValue };
 
@@ -133,6 +141,20 @@ export interface ColumnMeta {
   /** A thunk: schema modules reference each other in a cycle. */
   readonly references?: () => AnyColumn;
   readonly onDelete?: OnDelete;
+  /**
+   * Presence is what puts this column in the entity's generated `tsvector`, and the value is its
+   * weight. A modifier and not a column of its own: the vector is derived from every searchable
+   * column at once (`search.ts`), so declaring it per column would be one vector per column and
+   * one GIN index per column.
+   */
+  readonly searchable?: SearchWeight;
+  /**
+   * The state machine this column's values move through, when one was declared. Built once at
+   * declaration (`stateMachineOf`) so an illegal table is a refusal where it was written, and held
+   * as the built machine rather than the literal table because the literal is an object a caller
+   * indexes by a data key.
+   */
+  readonly machine?: StateMachine;
 }
 
 /**
@@ -159,6 +181,34 @@ export interface Column<T, Optional extends boolean = false> {
    * override it to keep theirs, and nothing else has any.
    */
   column(name: string): Column<T, Optional>;
+  /**
+   * Adds this column to the entity's one generated `tsvector`, at `weight` (default `D`). Text
+   * only — every other kind is refused here, where the chain was written.
+   */
+  searchable(weight?: SearchWeight): Column<T, Optional>;
+}
+
+/**
+ * `enumerated()`'s own column: the one that may declare a state machine, because it is the one
+ * that already declares a closed set of values for the machine to move through.
+ *
+ * The links below are overridden for the reason `UuidColumn`'s and `TimestampColumn`'s are — the
+ * generic chain answers the general `Column`, so `enumerated(S).default('draft')` would lose
+ * `transitions` and `enumerated(S).transitions(T).column('c')` would lose the machine's own type.
+ */
+export interface EnumeratedColumn<V extends readonly string[], Optional extends boolean = false>
+  extends Column<V[number], Optional> {
+  /**
+   * Declares which values may follow which. The states are `V` — this column's own — so the
+   * framework never names one: a missing state, an unknown key and an unknown target are each a
+   * compile error against the set the app already wrote.
+   *
+   * A state machine column may not be nullable: NULL is not a state, so nothing could say what it
+   * may move to.
+   */
+  transitions(table: TransitionTable<V[number]>): EnumeratedColumn<V, Optional>;
+  default(value: V[number]): EnumeratedColumn<V, true>;
+  column(name: string): EnumeratedColumn<V, Optional>;
 }
 
 /**