@ultimat3/entity 25.1.0 → 25.2.0

package/CLAUDE.md

@@ -98,7 +98,6 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `MAX_GROUPS + 1`, never a truncation; absent is not `0`; NULL is one group keyed `null`; the order
   is applied after the rows are in, never in SQL; `group_value` / `group_count` are fixed aliases.
   The refusal names a groupable column of THIS entity, never `x entity explain`.
-  The argument for each: [`docs/history/entity.md`](../../docs/history/entity.md).
 - **The codec is `@ultimat3/core`'s**, reached through `cursorFor(entity, plan, row, id)` and
   `seekFrom(entity, plan)`; **`assertSeekable` runs in `planFor`**, before a statement exists. A
   `timestamptz` sort key is refused when its `<column>$US` alias would pass 63 bytes. A cursor is bound
@@ -237,7 +236,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `TransitionTable<S>`): a terminal state is one with no outgoing moves; the move is ONE statement with
   `from` in the predicate (`pg-transition.live.test.ts`: 1 winner of 20); `X_STATE_CONFLICT` is read
   after the refusal from a tenant-scoped `findById`; no DDL beyond `enumerated()`'s CHECK; a machine
-  column may not be nullable; `whyNot` asks unknown → terminal → legal list.
+  column may not be nullable; `whyNot` asks unknown → terminal → legal list. **`move.observed`
+  pins what a decision read** (#702, `transition-pins.ts`).
 
 ## Do not regress — sealed columns
 
@@ -286,7 +286,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 Each file's header states its one job. The map, by area: `types.ts` (derivation; `COLUMN_KINDS`),
 `column.ts` / `columns.ts` / `columns-data.ts` / `array-element.ts` / `enum-column.ts` /
 `column-values.ts` (builders, `columnName`, `narrowMoney`), `refuse.ts`, `expr.ts` / `invariants.ts`,
-`entity.ts` / `describe.ts` / `index-name.ts` / `search.ts`, `state-machine.ts` / `transition.ts`,
+`entity.ts` / `describe.ts` / `index-name.ts` / `search.ts`, `state-machine.ts` / `transition*.ts`,
 `feature-errors.ts`, `view.ts` / `row-schema.ts` / `record-projection.ts` / `record-key.ts` /
 `rows-of.ts` / `record-table.ts` / `record.ts`, `entity-error.ts` / `errors.ts`, `query.ts` /
 `database.ts` / `clock.ts`, `memory-match.ts` / `like.ts` / `numeric-compare.ts` / `unique-constraints.ts` / `repo.ts` /

package/README.md

@@ -593,6 +593,14 @@ const db = database({ orders });
 
 // One statement. `from` is the state you believe the row is in, and it rides in the predicate.
 const shipped = await db.orders.transition('status', id, { from: 'paid', to: 'shipped' });
+
+// Decided about the row? Say what the decision read, and the move is conditional on it too.
+const read = await db.orders.where({ id }).one();
+await db.orders.transition('status', id, {
+  from: 'shipped',
+  to: 'delivered',
+  observed: { row: read, read: ['orgId'] },
+});
 ```
 
 | Fact | Why |
@@ -607,6 +615,8 @@ const shipped = await db.orders.transition('status', id, { from: 'paid', to: 'sh
 | the CHECK comes from `enumerated()` | the machine emits no DDL of its own — one declaration of what a legal value is |
 | `memoryDriver()` answers it exactly as Postgres does | a compare-and-set over a map is the same question; unlike a `tsvector` match, there is nothing to fake |
 | an `undefined` or `null` id is `X_NOT_FOUND`, and moves no row | an absent id names no row — it is refused before the statement, where it used to drop out of the filter and move every row in the `from` state |
+| `observed: { row, read }` pins what a **decision** read, in the same statement | a move decided about the row (`row.authorId === actor.id`) is conditional on that row still holding it: each `read` property that is a plain column of THIS row (a row carrying another key is another record; a keyless projection is this one) joins `id` and `from` in the predicate. A reassignment committed first matches no row; one in flight holds the row's lock, and Postgres re-checks the predicate after it commits. Either way `X_STATE_CONFLICT`, naming the column and never its value. `@ultimat3/action`'s `transition()` fills it from what its policy read (#702) |
+| a `timestamptz`, `jsonb`, array, `bytea`, money or sealed column is **not** pinned | none has an `=` meaning one thing in both drivers — a `defaultNow()` column holds microseconds in Postgres and a decoded `Date` milliseconds, so a pin on it would refuse every move there and none in memory (`transition-observed.test.ts`) |
 
 What is deliberately **not** here: who may make a move, what happens on arrival, an approval chain,
 a reason code. Those differ per app — wrap `transition()` in your own function and put them there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "25.1.0",
+  "version": "25.2.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -33,9 +33,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.1.0",
-    "@ultimat3/db": "25.1.0",
-    "@ultimat3/schema": "25.1.0",
-    "@ultimat3/time": "25.1.0"
+    "@ultimat3/core": "25.2.0",
+    "@ultimat3/db": "25.2.0",
+    "@ultimat3/schema": "25.2.0",
+    "@ultimat3/time": "25.2.0"
   }
 }

package/src/entity-error.ts

@@ -66,7 +66,7 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   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',
+  X_STATE_CONFLICT: 'the row changed after the read this transition was decided on',
   X_RECORD_KEY_MISSING: 'a row reached its record key without a primary-key value',
   X_ENTITY_SEALED_PREDICATE:
     'a sealed column is read by a predicate, an order or a rule the database evaluates',

package/src/feature-errors.ts

@@ -121,3 +121,22 @@ export const stateConflict = (
     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`,
   });
+
+/**
+ * The conditional update matched no row, the row IS in the named state, and a column the decision
+ * read no longer holds the value it read (#702). The same code as the stale state because it is the
+ * same refusal — the caller decided about a row that has since changed — and the same remedy: read
+ * again and decide again. Names the columns, never their values: those are row data.
+ */
+export const stateRowChanged = (
+  entityName: string,
+  column: string,
+  id: string,
+  key: string,
+  changed: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_STATE_CONFLICT',
+    cause: `${entityName}.${column} move for row ${id} was decided on ${changed.join(', ')}, which changed before the move landed — something rewrote the row the decision read`,
+    fix: `${entityName}.where({ ${key}: id }).one()   # re-read the row and decide again: a transition carries what its decision read, so a stale decision is refused rather than applied`,
+  });

package/src/index.ts

@@ -189,6 +189,7 @@ export {
   scopedPlan,
 } from './tenancy';
 export type { Move } from './transition';
+export type { TransitionObservation } from './transition-pins';
 export type {
   AnyColumn,
   Column,

package/src/query.ts

@@ -18,7 +18,7 @@ import type { Repo, RepoOptions, UpsertArgs } from './repo';
 import { copyRow, pickRow } from './sealed';
 import { SEARCH_PROPERTY } from './search';
 import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
-import { transitionRow } from './transition';
+import { type Move, transitionRow } from './transition';
 import type {
   ColumnMap,
   Filterable,
@@ -198,14 +198,14 @@ export interface Table<Row, C extends ColumnMap = ColumnMap>
    * of the concept and the only part of it the framework owns. Which state is terminal, what any
    * of them mean, who may make a move and what happens on arrival are the app's, every one.
    *
-   * Tenant-scoped exactly as `updateWhere` is, because it IS one: a row in another org matches no
-   * statement and reads back as absent, so the answer is `X_NOT_FOUND` rather than a conflict that
-   * would confirm it exists.
+   * `observed` (the row a decision read, and what it read) pins those columns in the same statement
+   * — a row changed under the decision is `X_STATE_CONFLICT` too (#702, `transition-pins.ts`).
+   * Tenant-scoped as `updateWhere` is: another org's row reads back absent, `X_NOT_FOUND`.
    */
   transition<K extends keyof Row & string>(
     column: K,
     id: IdOf<Row>,
-    move: { readonly from: Row[K] & string; readonly to: Row[K] & string },
+    move: Move<Row[K] & string>,
     options?: RepoOptions,
   ): Promise<Row>;
   insert(values: Insertable<C>, options?: RepoOptions): Promise<Row>;

package/src/transition-pins.ts

@@ -0,0 +1,87 @@
+// What a transition's decision READ, turned into the equality the compare-and-set also carries
+// (#702): a row whose consulted columns changed between the read and the move matches no statement.
+// Split from `transition.ts` because which columns can be pinned — and which cannot, honestly — is
+// its own question, answered by the column's declared kind exactly as `memory-match.ts` answers one.
+
+import { columnFor } from './column';
+import type { EntityCore } from './entity';
+import { isNullish } from './is-null';
+import { sameValueOfKind } from './memory-match';
+import type { ColumnKind } from './types';
+
+/**
+ * The evidence a decision about a move was made on: the row as it was read, and the properties the
+ * decision consulted. `@ultimat3/action`'s `transition()` fills both — the row from its `row`
+ * loader, `read` from what the policy touched — and a direct caller names its own.
+ */
+export interface TransitionObservation {
+  readonly row: unknown;
+  readonly read: readonly string[];
+}
+
+/**
+ * The kinds whose `=` means one thing in both drivers for the value a READ hands back. Not the
+ * others, and each for a measured reason: a `timestamptz` holds microseconds in Postgres and a
+ * decoded `Date` milliseconds, so an equality pin on a `defaultNow()` column refuses every move
+ * there and none in memory; `jsonb`, `array` and `bytea` compare structurally in neither driver's
+ * `eq`; `money` is three physical columns. A sealed column is never pinned: its filter is refused.
+ */
+const PINNABLE: ReadonlySet<ColumnKind> = new Set<ColumnKind>([
+  'uuid',
+  'text',
+  'char',
+  'boolean',
+  'integer',
+  'bigint',
+  'numeric',
+  'date',
+]);
+
+/**
+ * The property → value pairs to add to the move's predicate. Empty — the move exactly as before —
+ * when there is no observation, when the observed row carries a key that is not THIS row's (a
+ * loader may read a parent record, and pinning its values onto this one's columns would refuse
+ * every move), or when nothing the decision read is a pinnable column. The key and the machine column are already in the
+ * predicate, so they are skipped rather than pinned twice.
+ */
+export const pinsOf = <Row>(
+  entity: EntityCore<Row>,
+  key: string,
+  machine: string,
+  id: unknown,
+  observed: TransitionObservation | undefined,
+): Readonly<Record<string, unknown>> => {
+  const row = observed?.row;
+  if (observed === undefined || typeof row !== 'object' || row === null) return {};
+  const values = row as Readonly<Record<string, unknown>>;
+  // A row that NAMES another key is another record. One that names none is a projection of this
+  // one (`select({ authorId: true })` — the loader is handed this row's id), and is pinned.
+  const keyKind = columnFor(entity.$columns, key)?.$meta.kind;
+  if (Object.hasOwn(values, key) && !sameValueOfKind(keyKind, values[key], id)) return {};
+  const pins: Record<string, unknown> = {};
+  for (const property of observed.read) {
+    if (property === key || property === machine || !Object.hasOwn(values, property)) continue;
+    const meta = columnFor(entity.$columns, property)?.$meta;
+    if (meta === undefined || meta.sealed !== undefined || !PINNABLE.has(meta.kind)) continue;
+    // `null` and never `undefined`: a pinned NULL is `is null` in both drivers, while an
+    // `undefined` filter value is DROPPED by `namedColumns` — a pin that silently vanished.
+    pins[property] = values[property] ?? null;
+  }
+  return pins;
+};
+
+/** Which pins the row as it stands now no longer satisfies — the diagnosis, never the decision. */
+export const changedPins = <Row>(
+  entity: EntityCore<Row>,
+  row: unknown,
+  pins: Readonly<Record<string, unknown>>,
+): readonly string[] => {
+  const now = typeof row === 'object' && row !== null ? (row as Record<string, unknown>) : {};
+  return Object.entries(pins)
+    .filter(([property, was]) => {
+      const is = now[property];
+      if (isNullish(was) || isNullish(is)) return isNullish(was) !== isNullish(is);
+      return !sameValueOfKind(columnFor(entity.$columns, property)?.$meta.kind, is, was);
+    })
+    .map(([property]) => property);
+};

package/src/transition.ts

@@ -7,16 +7,27 @@ 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 {
+  stateConflict,
+  stateRowChanged,
+  stateTransitionIllegal,
+  stateUndeclared,
+} from './feature-errors';
 import { singleKeyOf } from './plan';
 import type { Repo, RepoOptions } from './repo';
 import { canMove, isState, isTerminal, movesFrom, type StateMachine } from './state-machine';
+import { changedPins, pinsOf, type TransitionObservation } from './transition-pins';
 import type { ColumnMap, IdOf, RowPatch } from './types';
 
-/** What a caller names: the state it believes the row is in, and the one it wants. */
+/**
+ * What a caller names: the state it believes the row is in, the one it wants, and — when the move
+ * was DECIDED about the row — what that decision read, so the statement refuses a row that has
+ * changed under it (`transition-pins.ts`).
+ */
 export interface Move<S extends string = string> {
   readonly from: S;
   readonly to: S;
+  readonly observed?: TransitionObservation;
 }
 
 /** Every property whose column declares a machine — what `X_STATE_UNDECLARED` lists back. */
@@ -57,12 +68,20 @@ const diagnose = async <Row>(
   property: string,
   id: IdOf<Row>,
   move: Move,
+  pinned: { readonly key: string; readonly pins: Readonly<Record<string, unknown>> },
   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));
+  if (String(actual) !== move.from) {
+    return stateConflict(entity.$name, property, String(id), move.from, String(actual));
+  }
+  // The state is still the one named, so a PIN refused it. A pin that reads equal again (changed
+  // and changed back after the statement) is still named: the statement is what decided.
+  const changed = changedPins(entity, row, pinned.pins);
+  const named = changed.length > 0 ? changed : Object.keys(pinned.pins);
+  return stateRowChanged(entity.$name, property, String(id), pinned.key, named);
 };
 
 const whyNot = (machine: StateMachine, move: Move): IllegalTransition => {
@@ -117,10 +136,17 @@ export const transitionRow = async <Row, C extends ColumnMap>(
   // value, so the predicate below would be the from-state alone and move every row in it.
   if (id === undefined || id === null) throw notFound(entity.$name, String(id));
   const key = singleKeyOf(entity, 'transition');
-  const filter = { [key]: id, [property]: move.from } as unknown as RowPatch<Row>;
+  // The pins FIRST and the key and state after, so nothing observed can widen the address. The
+  // columns the decision read ride in the same statement as `from`, so a reassignment committed
+  // before it matches nothing, and one in flight is waited on and then re-checked by Postgres on
+  // the row it left behind — the window between a policy's read and the move, closed (#702).
+  const pins = pinsOf(entity, key, property, id, move.observed);
+  const filter = { ...pins, [key]: 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);
+  if (written === 0) {
+    throw await diagnose(entity, repo, property, id, move, { key, pins }, options);
+  }
   const row = await repo.findById(id, options);
   if (row === null) throw notFound(entity.$name, String(id));
   return row;