@ultimat3/action 25.1.0 → 25.2.0

package/CLAUDE.md

@@ -120,7 +120,8 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 - **`transition()` is a mutator factory that decides nothing about the machine**: entity's three
   codes propagate; `from` is REQUIRED (it is the UPDATE's predicate); `conflict: 'server-wins'` fixed;
   `audit` off unless declared; `id` is the key `output.id` declares (`keySchemaOf`), never a fixed
-  `t.uuid`; `row` goes to `mutator()` as declared, never loaded here (#687).
+  `t.uuid`; `row` goes to `mutator()` as declared, never loaded here (#687); **the rule's reads
+  are pinned in the move** (#702, `transition-observe.ts`: `def.row`, `def.handle` share `input`).
 - **A lookup table is read with `Object.hasOwn`** (`IRREGULAR` in `naming.ts`, `BY_FORMAT` in
   `sample-input.ts`) — caller- or provider-supplied keys.
 
@@ -203,7 +204,6 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
   | `rpc` | 19,671 B (+181 B for the document's path-style stamp) |
   | `rpc` + core's `clientFlight` | 25,954 B |
 
-  Earlier columns (pre-transport 18,097 B, +977 B net for the envelope decoder) are in git history.
 - **`sideEffects` is `["./src/error-titles.ts"]`**, never `false` (drops its bare imports): the
   titles ride into every barrel chunk (`problemError` decodes by code), `errors.ts`'s classes do
   not. An http refusal needs no http module: core's decoders take its title off the body and its

package/README.md

@@ -410,7 +410,8 @@ await moveOrder({ id, from: 'pending', to: 'paid' }, { ctx });
 | `id` is the entity's **key**, read off `output.id` | a uuid key stays `t.uuid` (a malformed one is `X_INPUT_INVALID` before a database reads it); a `text()` key keeps its length and a `bigint()` key its digits pattern — never a fixed `t.uuid`, which refused every move on an entity keyed by anything else. An `output` that does not carry the key as `id` passes the key's schema as `id:`; with neither, the id is a uuid |
 | `idempotent: true`, always | a move replayed under its `Idempotency-Key` answers the first outcome, not an `X_STATE_CONFLICT` for a move that already happened |
 | `audit` is **off** unless the app says so | `audit: true` with no sink installed is `X_AUDIT_SINK_MISSING`, raised before the input parse — an on-by-default audit would make every `transition()` refuse until an unrelated decision was made. What the row is kept for, and for how long, is the same compliance question that kept a purge out of `postgresAuditSink` |
-| a row-level `policy` gets its row from **`row`** | the action's own loader, handed through: `row: ({ input, ctx }) => posts(ctx).find(input.id)`, then `can<TransitionValues<S>, Post>('post:move', ({ actor, row }) => row !== null && row.authorId === actor?.id)`. Loaded once, after the input parse, before the guard and the statement; the factory reads no row itself. Omitted, the rule sees `row: null` and must fail closed. **Check-then-act**, as every row-policy action's: the read is unlocked and outside any transaction, and the move's predicate is `id` + `from` only, so a concurrent change to a column the rule read (an `authorId` reassigned in between) is not seen. Where that matters, write an `action` whose handler opens `withTransaction`, reads the row `for update`, decides and calls `Table.transition` inside it |
+| a row-level `policy` gets its row from **`row`** | the action's own loader, handed through: `row: ({ input, ctx }) => posts(ctx).find(input.id)`, then `can<TransitionValues<S>, Post>('post:move', ({ actor, row }) => row !== null && row.authorId === actor?.id)`. Loaded once, after the input parse, before the guard and the statement; the factory reads no row itself. Omitted, the rule sees `row: null` and must fail closed |
+| **what the rule read rides in the move** (#702) | the rule is handed a view of the loaded row that records which properties it reads; the move passes the row and that list to `Table.transition` as `observed`, and entity pins each one that is a plain column of the moved row beside `id` and `from`. An `authorId` reassigned between the read and the move — committed first, or in flight and waited on by Postgres — matches no statement: `X_STATE_CONFLICT` naming the column, and the row does not move. A column the rule never read may change freely. Not pinned: a row carrying another record's key (a loader reading a parent record; a keyless projection such as `select({ authorId: true })` is this row), a property that names no column, and a `timestamptz`, `jsonb`, array, `bytea`, money or sealed column — none has an `=` that means one thing in both drivers. Nor a column read inside a getter or method of a class-shaped row: only the accessor's name is recorded, so return a plain row from the loader |
 | `X_STATE_TRANSITION_ILLEGAL`, `X_STATE_CONFLICT` and `X_STATE_UNDECLARED` propagate untouched | they are `@ultimat3/entity`'s. A second error class over one failure is a second path |
 
 `table` is typed structurally (`TransitionTarget`), not imported — a real `Table` satisfies the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "25.1.0",
+  "version": "25.2.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -35,12 +35,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "25.1.0",
-    "@ultimat3/core": "25.1.0",
-    "@ultimat3/db": "25.1.0",
-    "@ultimat3/entity": "25.1.0",
-    "@ultimat3/http": "25.1.0",
-    "@ultimat3/policy": "25.1.0",
-    "@ultimat3/schema": "25.1.0"
+    "@ultimat3/cache": "25.2.0",
+    "@ultimat3/core": "25.2.0",
+    "@ultimat3/db": "25.2.0",
+    "@ultimat3/entity": "25.2.0",
+    "@ultimat3/http": "25.2.0",
+    "@ultimat3/policy": "25.2.0",
+    "@ultimat3/schema": "25.2.0"
   }
 }

package/src/invoke.ts

@@ -274,6 +274,8 @@ async function perform(
   // re-evaluate the same policy per subscriber without a query per change event. An
   // action with no loader hands the rule `null` — unchanged, and never a silent allow,
   // because a rule that reads `row` has to decide what `null` means.
+  // The SAME `input` object reaches `def.row` here and `def.handle` below, by reference:
+  // `transition()` keys what its rule read on it (`transition-observe.ts`, #702).
   const row = def.row === undefined ? null : ((await def.row({ input, ctx })) ?? null);
   guardAction(def.policy, { actor: actorOf(ctx), input, row, ctx, action: name }, surface);
 

package/src/transition-observe.ts

@@ -0,0 +1,67 @@
+/**
+ * What a `transition()`'s policy READ off the loaded row, carried from the guard to the
+ * compare-and-set (#702). The loader's row reaches the rule as a recording view; the move hands the
+ * raw row and the properties the rule touched to `Table.transition`, which pins them in its predicate.
+ */
+
+import type { TransitionObservation } from '@ultimat3/entity';
+
+/**
+ * Keyed by the PARSED INPUT object, which `invoke` hands to the loader and then to the handler by
+ * reference — a fresh object per invocation, so two concurrent moves of one row never share an
+ * entry, and a denied call's entry goes with its input. Module-private: nothing else can write one.
+ */
+const OBSERVED = new WeakMap<object, { readonly row: unknown; readonly read: Set<string> }>();
+
+/**
+ * The view the rule is handed: the same row, recording every property it asks about. Anything that
+ * enumerates the row (a spread, `Object.keys`, a serialiser) records every key it enumerates — it
+ * may have looked at all of them, so all of them are pinned. Only own string keys mean anything:
+ * entity pins the ones that name a column of the moved entity and ignores the rest.
+ */
+const recording = (row: object, read: Set<string>): object =>
+  new Proxy(row, {
+    get(target, property) {
+      // `then` is the promise machinery asking whether the loader's answer is a thenable — the
+      // `await` in `invoke`, never the rule. The one name this view cannot attribute, so a column
+      // named `then` is never pinned.
+      if (typeof property === 'string' && property !== 'then') read.add(property);
+      // `target` as the receiver, not the proxy: a getter on a class row runs against the object
+      // that owns its private state, exactly as it would unobserved — which also means a column it
+      // reads through `this` is NOT recorded, only the getter's own name. Documented on
+      // `TransitionDef.row` as unpinned; a proxy receiver would throw on any `#private` access.
+      return Reflect.get(target, property, target);
+    },
+    has(target, property) {
+      if (typeof property === 'string') read.add(property);
+      return Reflect.has(target, property);
+    },
+    getOwnPropertyDescriptor(target, property) {
+      if (typeof property === 'string') read.add(property);
+      return Reflect.getOwnPropertyDescriptor(target, property);
+    },
+    ownKeys(target) {
+      const keys = Reflect.ownKeys(target);
+      for (const key of keys) if (typeof key === 'string') read.add(key);
+      return keys;
+    },
+  });
+
+/** Remember the loaded row for this invocation, and hand back what the rule should see. */
+export function observeRow<TRow>(input: unknown, row: TRow | null): TRow | null {
+  if (typeof input !== 'object' || input === null) return row;
+  const read = new Set<string>();
+  OBSERVED.set(input, { row, read });
+  // A non-object row has nothing to read off; the rule gets it unchanged. The cast is the Proxy's
+  // own: a proxy over `row` presents exactly `row`'s shape.
+  return typeof row === 'object' && row !== null ? (recording(row, read) as TRow) : row;
+}
+
+/** What the rule read for this invocation, once — `undefined` when no loader ran for it. */
+export function takeObservation(input: unknown): TransitionObservation | undefined {
+  if (typeof input !== 'object' || input === null) return undefined;
+  const seen = OBSERVED.get(input);
+  if (seen === undefined) return undefined;
+  OBSERVED.delete(input);
+  return { row: seen.row, read: [...seen.read] };
+}

package/src/transition.ts

@@ -10,6 +10,7 @@
  */
 
 import type { Ctx } from '@ultimat3/core';
+import type { TransitionObservation } from '@ultimat3/entity';
 import type {
   InferOutput,
   ObjectSchema,
@@ -21,6 +22,7 @@ import { nodeOf, t } from '@ultimat3/schema';
 import type { ActionRowArgs } from './action';
 import { type Mutator, mutator } from './mutator';
 import type { ActionPolicy } from './policy-gate';
+import { observeRow, takeObservation } from './transition-observe';
 
 /**
  * The one method this factory calls, declared structurally: `@ultimat3/entity`'s `Table.transition`
@@ -50,7 +52,11 @@ export type TransitionInput<S extends string> = ObjectSchema<{
 }>;
 
 export interface TransitionTarget<Row, S extends string> {
-  transition(column: string, id: string, move: { readonly from: S; readonly to: S }): Promise<Row>;
+  transition(
+    column: string,
+    id: string,
+    move: { readonly from: S; readonly to: S; readonly observed?: TransitionObservation },
+  ): Promise<Row>;
 }
 
 export interface TransitionDef<
@@ -93,12 +99,21 @@ export interface TransitionDef<
    * factory reads no row itself; which columns a rule needs (an `authorId` the `output` view may not
    * carry) is the app's. Omitted, the rule sees `row: null` — and must fail closed on it.
    *
-   * CHECK-THEN-ACT, as every row-policy action's: the read is unlocked and outside any transaction,
-   * and the compare-and-set predicate is `id` + `from` only. A concurrent write to a column the
-   * rule read (an `authorId` reassigned between the read and the move) is not seen, so the move
-   * lands on the decision about the older row. Where that matters, do not use `transition()`: an
-   * `action` whose handler runs `withTransaction`, reads the row `for update`, decides, and calls
-   * `Table.transition` in that transaction closes the window.
+   * The DECISION rides in the compare-and-set (#702). The rule is handed a view of the loaded row
+   * that records which properties it read; the move then carries the row and that list to
+   * `Table.transition` (`observed`), which pins every one that is a plain column of the moved row
+   * beside `id` and `from`. An `authorId` reassigned between the read and the move — committed
+   * first, or in flight and waited on — matches no statement: `X_STATE_CONFLICT`, naming the
+   * column, and the row does not move. A column the rule never read may change freely.
+   *
+   * What is NOT pinned, by entity's rules (`transition-pins.ts`): a row carrying a key that is not
+   * the moved row's (a loader that reads a parent record — a keyless projection IS this row), a
+   * property that names no column, and a `timestamptz`, `jsonb`, array, `bytea`, money or sealed
+   * column — none has an `=` that means one thing in both drivers. Nor, by this factory's: a column
+   * read INSIDE a getter or method of a class-shaped row (only the accessor's own name is recorded,
+   * and it runs against the unobserved row) — return a plain row from the loader. A rule that
+   * decides on any of those, or on another table's rows, decides on a read the statement cannot
+   * re-check.
    */
   row?(args: ActionRowArgs<TransitionInput<S>>): TRow | null | Promise<TRow | null>;
   /**
@@ -145,7 +160,10 @@ export function transition<
     // `X_STATE_CONFLICT` for a move that already happened.
     idempotent: true,
     // `.call(def, …)`, as `mutator()` hands its own on: a loader written as a method keeps `this`.
-    ...(row === undefined ? {} : { row: (args) => row.call(def, args) }),
+    // The row is remembered for `server` below and the rule sees a view recording what it reads.
+    ...(row === undefined
+      ? {}
+      : { row: async (args) => observeRow(args.input, await row.call(def, args)) }),
     ...(def.audit === undefined ? {} : { audit: def.audit }),
     // Never overridable: the server is the half that REFUSED the move, and a local twin that won
     // the rebase would leave the client showing a state the database rejected.
@@ -163,9 +181,11 @@ export function transition<
     // entity's and propagate as they are. A second error class over one failure is a second path.
     server: (ctx, raw) => {
       const input = valuesOf(raw);
+      const observed = takeObservation(raw);
       return def.table(ctx).transition(def.column, input.id, {
         from: input.from,
         to: input.to,
+        ...(observed === undefined ? {} : { observed }),
       });
     },
   });