@ultimat3/entity 11.3.0 → 13.0.0

package/src/repo.ts

@@ -7,18 +7,8 @@
 //     table silently skips and repeats rows. A keyset cursor is stable because it names a
 //     position in the sort order, not a row count.
 
-import { keyOf } from './batch-read';
-import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
-import { entityNow } from './clock';
-import { narrowMoney } from './columns';
-import { countsFrom, groupColumnOf } from './count-by';
-import { cursorFor, kindOf, seekFrom, valueAt } from './cursor';
-import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
-import { notFound } from './errors';
-import { compareByKind, matchesPredicate } from './memory-match';
-import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
-import type { Predicate, QueryPlan, SortKey } from './tenancy';
-import { assertRowTenant } from './tenancy';
+import type { AggregateFn } from './aggregate';
+import type { Predicate, SortKey } from './tenancy';
 import type { IdOf, RowPatch } from './types';
 
 export interface Tx {
@@ -136,6 +126,20 @@ export interface Repo<T = unknown> {
    * `ReadBuilder.countBy`, which knows the row. Ordered by count, biggest group first.
    */
   countBy(column: string, args?: FindManyArgs): Promise<ReadonlyMap<unknown, number>>;
+  /**
+   * One aggregate over exactly the rows `count(args)` counts. Row-agnostic here and typed on the
+   * chain, the same seam `countBy` has: a column name is a runtime string at this contract.
+   *
+   * `null` for an empty set in every function, which is what SQL answers — a `0` would claim rows
+   * were seen. A `sum` or an `avg` comes back as decimal TEXT and a money aggregate as a
+   * `MoneyValue`; neither is ever a float.
+   */
+  aggregate(fn: AggregateFn, column: string, args?: FindManyArgs): Promise<unknown>;
+  /**
+   * The planner's own row estimate for the table — not a count, and never filtered. `null` when
+   * the table has never been analysed, which is a fact and not an estimate.
+   */
+  approximateCount(args?: FindManyArgs): Promise<number | null>;
 }
 
 /**
@@ -154,319 +158,3 @@ export interface MemoryRepo<Row> extends Repo<Row> {
 export interface Transactor {
   run<R>(work: (tx: Tx) => Promise<R>): Promise<R>;
 }
-
-const field = (row: unknown, property: string): unknown =>
-  typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
-
-/** Lexicographic over the sort keys, direction applied. `> 0` means "after the cursor". */
-const compareToSeek = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  row: unknown,
-  seek: readonly unknown[],
-): number => {
-  for (const [index, entry] of plan.orderBy.entries()) {
-    // The COLUMN's kind, not the value's: the seek was revived from the same kind (`cursor.ts`),
-    // so a `bigint` column compares its stored decimal string against a revived `BigInt` as one
-    // number instead of as two pieces of text.
-    const order = compareByKind(
-      kindOf(entity, entry.column),
-      valueAt(row, entry.column),
-      seek[index],
-    );
-    if (order !== 0) return entry.direction === 'desc' ? -order : order;
-  }
-  return 0;
-};
-
-/**
- * Where the next page starts. By sort position, not by the previous row's id: that row may have
- * been deleted between the two requests, and an id that is no longer there would restart
- * pagination at the top instead of continuing it.
- */
-const afterCursor = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  found: readonly Row[],
-): number => {
-  const seek = seekFrom(entity, plan);
-  if (seek === undefined) return 0;
-  const start = found.findIndex((row) => compareToSeek(entity, plan, row, seek) > 0);
-  return start === -1 ? found.length : start;
-};
-
-/**
- * The default driver: correct semantics, no database. `x dev` uses it before the first
- * migration and tests use it everywhere. Postgres is the production driver and implements
- * this same interface.
- */
-export const memoryRepo = <Row>(
-  entity: EntityCore<Row>,
-  seed: readonly Row[] = [],
-): MemoryRepo<Row> => {
-  /**
-   * A stored row's key, spelled the way `batch-read.ts` spells an id — because Postgres compares a
-   * `uuid` as a VALUE and prints it lower-cased, so `findById(UPPER)` reads the row there while
-   * `String(...)` missed it here: `null` from a read and `X_NOT_FOUND` from a write, against a row
-   * that exists, reachable from a path parameter, a client-supplied id or a legacy import.
-   */
-  const storeKey = (row: unknown): string =>
-    entity.$primaryKey
-      .map((property) => keyOf(kindOf(entity, property) ?? '', field(row, property)))
-      .join('
');
-  /** The same key, from the id a caller named rather than from a row it has in hand. */
-  const idStoreKey = (id: unknown, operation: string): string =>
-    keyOf(kindOf(entity, singleKeyOf(entity, operation)) ?? '', id);
-  const rows = new Map<string, Row>(seed.map((row) => [storeKey(row), row]));
-
-  const rowsOf = (plan: QueryPlan, args: FindManyArgs): Row[] => {
-    const visible = (row: Row): boolean =>
-      !entity.$softDelete ||
-      args.includeDeleted === true ||
-      field(row, SOFT_DELETE_COLUMN) === null ||
-      field(row, SOFT_DELETE_COLUMN) === undefined;
-    return [...rows.values()]
-      .filter((row) => plan.where.every((predicate) => matchesPredicate(entity, row, predicate)))
-      .filter(visible)
-      .sort((left, right) => {
-        for (const entry of plan.orderBy) {
-          const order = compareByKind(
-            kindOf(entity, entry.column),
-            valueAt(left, entry.column),
-            valueAt(right, entry.column),
-          );
-          if (order !== 0) return entry.direction === 'desc' ? -order : order;
-        }
-        return 0;
-      });
-  };
-
-  const select = (args: FindManyArgs, operation: string): { plan: QueryPlan; found: Row[] } => {
-    const plan = readPlan(entity, args, operation);
-    return { plan, found: rowsOf(plan, args) };
-  };
-
-  const write = (given: Row, options: RepoOptions | undefined, operation: string): Row => {
-    // `MoneyInput` lets a writer hand a `bigint`; a stored row holds the value type. The Postgres
-    // driver narrows in `bindValues` and reads its answer back through `returning *`, so without
-    // this an in-memory row would be the one row in the framework `JSON.stringify` refuses.
-    const row = narrowMoney(entity.$columns, given);
-    // Beside `$assert`, and before the row lands: a write is judged by the tenant it names as well
-    // as by the invariants it declares, and the Postgres driver runs the same pair in `writeRows`.
-    // `update` reaches here with the STORED row merged under its patch, so a patch that moves a row
-    // out of this tenant is refused by the same call that refuses an insert into another one.
-    assertRowTenant(entity.$name, entity.$tenantColumn, operation, row);
-    entity.$assert(row);
-    const key = storeKey(row);
-    const previous = rows.get(key);
-    options?.tx?.onRollback(() => {
-      if (previous === undefined) rows.delete(key);
-      else rows.set(key, previous);
-    });
-    rows.set(key, row);
-    return row;
-  };
-
-  // The same guard the read path applies: on a tenant-scoped entity an id alone is not enough
-  // to name a row, so `update`/`delete` resolve through a plan rather than through the map.
-  const addressed = (id: string, options: RepoOptions | undefined, operation: string): Row => {
-    const plan = idPlan(entity, id, options, operation);
-    const current = rows.get(idStoreKey(id, operation));
-    // A soft-deleted row is hidden from writes too — `delete` on one is `X_NOT_FOUND`, not a
-    // second stamp, which is what the Postgres driver's `deleted_at is null` clause already says.
-    const hidden =
-      current !== undefined &&
-      entity.$softDelete &&
-      field(current, SOFT_DELETE_COLUMN) !== null &&
-      field(current, SOFT_DELETE_COLUMN) !== undefined;
-    if (
-      current === undefined ||
-      hidden ||
-      !plan.where.every((predicate) => matchesPredicate(entity, current, predicate))
-    ) {
-      throw notFound(entity.$name, id);
-    }
-    return current;
-  };
-
-  // Every method is async: a repository call that fails must reject, never throw
-  // synchronously, or half the call sites would need two error paths.
-  return {
-    async findById(id, options) {
-      const { found } = select(
-        { ...options, where: [{ column: singleKeyOf(entity, 'findById'), op: 'eq', value: id }] },
-        'findById',
-      );
-      return found[0] ?? null;
-    },
-
-    async findMany(args = {}) {
-      const { plan, found } = select(args, 'findMany');
-      const start = afterCursor(entity, plan, found);
-      const page = found.slice(start, start + plan.limit);
-      const last = page.at(-1);
-      const more = start + page.length < found.length;
-      return {
-        rows: page,
-        nextCursor:
-          more && last !== undefined ? cursorFor(entity, plan, last, storeKey(last)) : null,
-      };
-    },
-
-    async insert(values, options) {
-      return write(values, options, 'insert');
-    },
-
-    async insertAll(batch, options) {
-      // The whole batch is judged before any of it lands: Postgres refuses the statement as one,
-      // so a row an invariant rejects — or one naming a tenant this actor may not write — must not
-      // leave the rows before it stored here either. `write` re-checks both per row; this loop is
-      // what makes the batch all-or-nothing, which is the half a per-row check cannot give.
-      for (const row of batch) {
-        assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);
-        entity.$assert(row);
-      }
-      return batch.map((row) => write(row, options, 'insertAll'));
-    },
-
-    async upsertAll(batch, args) {
-      // The INCOMING rows, judged before any of them is matched: under `onMatch: 'nothing'` a
-      // colliding row is skipped and never reaches `write()`, so checking only what lands would
-      // let a row naming another tenant through whenever it happened to collide.
-      for (const row of batch) {
-        assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
-        entity.$assert(row);
-      }
-      const plan = upsertPlan(entity, batch, args.onConflict, args.onMatch ?? 'update');
-      const keys = conflictKeys(entity, plan, batch);
-      // The stored rows under the same key, so "does this collide" is the question the unique
-      // index answers in Postgres and not a scan per row. A soft-deleted row still occupies its
-      // key here, because the index it would collide with there is not partial either — and a row
-      // whose target holds a null occupies none, because the index is `NULLS DISTINCT`.
-      const stored = new Map<string, Row>();
-      for (const row of rows.values()) {
-        const key = conflictKeyOf(entity, plan.on, row);
-        if (key !== undefined) stored.set(key, row);
-      }
-      const written: Row[] = [];
-      for (const [position, row] of batch.entries()) {
-        const key = keys[position];
-        const existing = key === undefined ? undefined : stored.get(key);
-        // `do nothing` writes no row, and `returning *` therefore names none: a skipped row is
-        // absent from the result rather than present and unchanged.
-        if (existing !== undefined && plan.set.length === 0) continue;
-        const merged =
-          existing === undefined
-            ? row
-            : Object.assign(
-                {},
-                existing,
-                Object.fromEntries(plan.set.map((property) => [property, field(row, property)])),
-              );
-        // `UpsertArgs extends RepoOptions`, so the args ARE the options — one bag, and a `tx`
-        // passed to an upsert registers its undo exactly as it does for every other write here.
-        const result = write(merged, args, 'upsertAll');
-        // Filed as it lands, so a later row of the same batch collides with an earlier one exactly
-        // as it would with a row the request stored a moment before it.
-        if (key !== undefined) stored.set(key, result);
-        written.push(result);
-      }
-      return written;
-    },
-
-    async update(id, patch, options) {
-      return write(Object.assign({}, addressed(id, options, 'update'), patch), options, 'update');
-    },
-
-    async delete(id, options) {
-      const current = addressed(id, options, 'delete');
-      // Soft delete hides the row without losing it; the column's presence is the switch.
-      if (entity.$softDelete) {
-        write(Object.assign({}, current, { [SOFT_DELETE_COLUMN]: entityNow() }), options, 'delete');
-        return;
-      }
-      const key = storeKey(current);
-      options?.tx?.onRollback(() => rows.set(key, current));
-      rows.delete(key);
-    },
-
-    async deleteWhere(filter, options) {
-      // `rowsOf` is the read path: the same predicates, the same tenant scoping, and the same
-      // soft-delete visibility. A row already stamped is not matched, so a second call cannot
-      // move `deletedAt` forward — which is what the Postgres driver's `deleted_at is null`
-      // clause says there.
-      const doomed = rowsOf(deletePlan(entity, filter, options, 'deleteWhere'), {});
-      for (const row of doomed) {
-        if (entity.$softDelete) {
-          write(
-            Object.assign({}, row, { [SOFT_DELETE_COLUMN]: entityNow() }),
-            options,
-            'deleteWhere',
-          );
-          continue;
-        }
-        const key = storeKey(row);
-        options?.tx?.onRollback(() => rows.set(key, row));
-        rows.delete(key);
-      }
-      return doomed.length;
-    },
-
-    async updateWhere(filter, patch, options) {
-      const plan = updatePlan(entity, filter, patch, options, 'updateWhere');
-      // The PATCH, judged whole and before the rows are read — the same call `postgresRepo` makes
-      // before its statement exists. Inside the loop below it is judged only where a row was
-      // matched, so a patch handing rows to another tenant was refused or accepted depending on
-      // what the table happened to hold: `updateWhere(filter, { orgId: theirs })` over a filter
-      // matching nothing answered `0` here and threw there, from one call.
-      assertRowTenant(entity.$name, entity.$tenantColumn, 'updateWhere', patch);
-      // `rowsOf` again, so a soft-deleted row is as unreachable here as it is through
-      // `addressed()` — patching a row the app has already deleted is not an update, it is a
-      // resurrection nobody asked for. `write` re-asserts the invariants on each result.
-      const found = rowsOf(plan, {});
-      for (const row of found) write(Object.assign({}, row, patch), options, 'updateWhere');
-      return found.length;
-    },
-
-    async count(args = {}) {
-      return select(args, 'count').found.length;
-    },
-
-    async countBy(column, args = {}) {
-      // Refused before a row is read, and by the same function the Postgres driver calls: a column
-      // a map cannot be keyed by is that mistake in both drivers or in neither.
-      groupColumnOf(entity, column, 'countBy');
-      const { found } = select(args, 'countBy');
-      const groups = new Map<unknown, number>();
-      for (const row of found) {
-        // `?? null`, so a property this row never carried lands in the same group Postgres puts a
-        // NULL row in — and `0`, `''` and `false` stay the values they are.
-        const value = field(row, column) ?? null;
-        groups.set(value, (groups.get(value) ?? 0) + 1);
-      }
-      return countsFrom(entity, column, 'countBy', [...groups]);
-    },
-
-    reset() {
-      rows.clear();
-      for (const row of seed) rows.set(storeKey(row), row);
-    },
-  };
-};
-
-let txCounter = 0;
-
-/** In-memory transactor: undo closures registered by drivers run on failure. */
-export const memoryTransactor = (): Transactor => ({
-  async run(work) {
-    const undos: (() => void)[] = [];
-    txCounter += 1;
-    const tx: Tx = { id: `tx-${txCounter}`, onRollback: (undo) => undos.push(undo) };
-    try {
-      return await work(tx);
-    } catch (error) {
-      for (const undo of undos.reverse()) undo();
-      throw error;
-    }
-  },
-});

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) };
+};

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));
+};