@ultimat3/entity 25.1.0 → 26.0.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

@@ -263,7 +263,7 @@ export const accounts = entity('account', {
 
 | Override | What follows it |
 |---|---|
-| `entity(name, { table })` | every statement, index name and foreign key. The entity NAME stays the framework's key — the registry, the cache tag (`entity:account`), `x entities describe` and every relation are keyed by it, so renaming a table never moves a cache tag or a policy |
+| `entity(name, { table })` | every statement, index name and foreign key. The entity NAME stays the framework's key — the registry, the cache tag (`entity:account`), `x entities show` and every relation are keyed by it, so renaming a table never moves a cache tag or a policy |
 | `.column(name)` | the DDL, the binding, the decoder, the predicate, the sort key, the cursor. Name it LAST in a chain — the link returns the general column, and only `uuid()` and `timestamp()` keep their own methods across it |
 | `money({ columns })` | per part, merged over `<name>_minor` / `<name>_currency` / `<name>_scale`, so a table that renamed one does not restate the other two. `scale: null` says the table has no scale column: every amount is then at the currency's own minor unit, which is what an absent scale already means |
 
@@ -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.
@@ -803,7 +813,7 @@ page.rows[0].author;        // the member row, or null — always present
 | Unknown name | `X_PRELOAD_UNKNOWN_RELATION` at `preload()` itself, not a page later |
 | Shape | `belongsTo` attaches the row or `null`; `hasMany` an array — always present |
 | Statements | one extra per relation, resolved concurrently; naming one twice is one statement |
-| Ceiling | `preload('<relation>', { max })` — the most related rows one relation may attach to one page. Default `MAX_PRELOADED_ROWS` (10,000, the largest page a read may ask for). Past it the read is **refused** (`X_INVARIANT_VIOLATED`), never truncated, and it reads at most one row past the ceiling to know. Naming a relation twice is still one statement: a later call that states `max` replaces the earlier one, as a second `.limit()` does, and one that states none leaves it. The refusal's cause spells the call to write (`.preload('<relation>', { max: n })`); its fix is `x entities describe <entity> --json` |
+| Ceiling | `preload('<relation>', { max })` — the most related rows one relation may attach to one page. Default `MAX_PRELOADED_ROWS` (10,000, the largest page a read may ask for). Past it the read is **refused** (`X_INVARIANT_VIOLATED`), never truncated, and it reads at most one row past the ceiling to know. Naming a relation twice is still one statement: a later call that states `max` replaces the earlier one, as a second `.limit()` does, and one that states none leaves it. The refusal's cause spells the call to write (`.preload('<relation>', { max: n })`); its fix is `x entities show <entity> --json` |
 | Tenancy | carried onto the related read only when the other entity's tenant column shares the name; otherwise `X_TENANCY_UNSCOPED` refuses the related read rather than guess |
 | Terminals | `page()`, `all()`, `one()` preload; `count()`, `countBy()` and `plan()` don't — none reads a row to attach one to |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "25.1.0",
+  "version": "26.0.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": "26.0.0",
+    "@ultimat3/db": "26.0.0",
+    "@ultimat3/schema": "26.0.0",
+    "@ultimat3/time": "26.0.0"
   }
 }

package/src/aggregate.ts

@@ -64,7 +64,7 @@ export const notAggregatable = (
       fn === 'avg' && kind === 'money'
         ? `${entityName}.sum('${property}') and ${entityName}.count() — divide at the call site, where the rounding is a decision somebody made`
         : candidates.length === 0
-          ? `x entities describe ${entityName} --json   # this entity declares no column ${fn} can be applied to`
+          ? `x entities show ${entityName} --json   # this entity declares no column ${fn} can be applied to`
           : `${entityName}.${fn}('${candidates[0]}')   # ${fn} takes one of: ${candidates.join(', ')}`,
   });
 

package/src/array-element.ts

@@ -52,7 +52,7 @@ const ARRAY_ELEMENT_FIXES = Object.freeze<Record<RefusedElement, string>>({
  * and only a table could show.
  *
  * Not `reject()`: a declaration is repaired by an EDIT, and `reject`'s
- * `x entities describe column --json` is `X_DECLARATION_UNKNOWN` — no entity is named `column`, and
+ * `x entities show column --json` is `X_DECLARATION_UNKNOWN` — no entity is named `column`, and
  * there is no entity at all yet. So each fix is the edit that holds the list instead.
  */
 export const arrayElementRefused = (kind: RefusedElement): EntityError => {

package/src/count-by.ts

@@ -42,7 +42,7 @@ const groupableColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
  * Not `invariantViolated`: its fix opens `x entity explain`, which describes invariants nobody
  * wrote here. What repairs this is one edit to the call — a different column, named in the message
  * because the entity is the only place the answer lives. Only when this entity offers no such
- * column does the fix become a command, and then it is `x entities describe`, which prints the
+ * column does the fix become a command, and then it is `x entities show`, which prints the
  * kinds: there is no call to suggest, since every column it declares would be refused the same way.
  */
 const notGroupable = <Row>(
@@ -57,7 +57,7 @@ const notGroupable = <Row>(
     cause: `${entity.$name}.${operation}('${property}'): ${reason}`,
     fix:
       first === undefined
-        ? `x entities describe ${entity.$name} --json   # this entity declares no column a count can be keyed by`
+        ? `x entities show ${entity.$name} --json   # this entity declares no column a count can be keyed by`
         : `${entity.$name}.${operation}('${first}')   # group by one of: ${groupableColumns(entity).join(', ')}`,
   });
 };

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',
@@ -124,14 +124,12 @@ export class EntityError extends UltimateError {
  * read is not spliced.
  */
 export const describeCommand = (entityName: string): string =>
-  isFixShellSafe(entityName)
-    ? `x entities describe ${entityName} --json`
-    : 'x entities list --json';
+  isFixShellSafe(entityName) ? `x entities show ${entityName} --json` : 'x entities list --json';
 
 /**
  * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
  * given. A literal is an entity that does not exist, and this fix then hands the reader
- * `x entities describe column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
+ * `x entities show column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
  * refusal raised before any entity exists belongs in `refuse.ts`, where the caller supplies the
  * edit; `refuse.test.ts` fails on a literal here.
  */
@@ -143,7 +141,7 @@ export const invariantViolated = (
   new EntityError({
     code: 'X_INVARIANT_VIOLATED',
     cause: `${entityName}.${invariantName}: ${message}`,
-    fix: `x entities describe ${entityName} --json   # shows the invariant and its SQL CHECK`,
+    fix: `x entities show ${entityName} --json   # shows the invariant and its SQL CHECK`,
   });
 
 export const entityDuplicate = (name: string, existingTable: string): EntityError =>

package/src/entity.ts

@@ -41,7 +41,7 @@ export interface EntityInit<C extends ColumnMap> {
    * cannot cover: `entity('user', { table: 'users', … })` reads and writes the table that is
    * already there, and every statement, index name and foreign key follows it.
    *
-   * The entity NAME stays the framework's key — the registry, the cache tag, `x entities describe`
+   * The entity NAME stays the framework's key — the registry, the cache tag, `x entities show`
    * and every relation are keyed by it — so renaming a table never moves a cache tag or a policy.
    */
   readonly table?: string;

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/record-key.ts

@@ -23,7 +23,7 @@ export const recordKeyMissing = (type: string, column: string, value: unknown):
     // `renderFixShellArg` inside the safe branch is verbatim there; it is the call
     // `bun run fix-shell-arg` recognises as the screen.
     fix: isFixShellSafe(type)
-      ? `x entities describe ${renderFixShellArg(type, 'ENTITY')} --json   # lists the primary key; return the whole row (every primary-key column) from the handler that built this one`
+      ? `x entities show ${renderFixShellArg(type, 'ENTITY')} --json   # lists the primary key; return the whole row (every primary-key column) from the handler that built this one`
       : 'x entities list --json   # find this entity, then return the whole row (every primary-key column) from the handler that built this one',
   });
 

package/src/refuse.ts

@@ -1,7 +1,7 @@
 // The two refusals raised while a SCHEMA is still being written — a column and an invariant — and
 // why neither goes through `invariantViolated`: that builder's fix is
-// `x entities describe <entityName> --json`, which needs an entity that exists. Passing the
-// literal `'column'` emitted `x entities describe column --json`, which answers
+// `x entities show <entityName> --json`, which needs an entity that exists. Passing the
+// literal `'column'` emitted `x entities show column --json`, which answers
 // `X_DECLARATION_UNKNOWN` — a fix line that raises a second, unrelated error (issue #290).
 //
 // So the fix is a parameter: every caller supplies the EDIT that repairs its own refusal, the

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;