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

@@ -256,7 +256,7 @@ Under the default style:
 | `checkout` (single word) | `POST /api/checkouts/invoke` | `checkout` |
 
 **One name, three surfaces** — `openapi.json`'s `x-ultimate.mcpTool`,
-`describeAction().mcp.tool` (what `x actions describe --json`, `x actions list --json`, the
+`describeAction().mcp.tool` (what `x actions show --json`, `x actions list --json`, the
 `actions.describe` dev MCP tool and the `/_x` Routes panel show) and the catalog `@ultimat3/mcp`
 serves. It was two until 2026-08: a `toToolName()` here snake_cased the published ones to
 `publish_post` while the server answered only `publishPost`, so an agent that read the published
@@ -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
@@ -838,7 +839,7 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `X_ACTION_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
 | `X_RATE_LIMIT_INVALID` | `rateLimit:` with a non-positive or non-finite half — `windowMs: 0` refills infinitely. Owned by `@ultimat3/http`, which owns the conversion | make both positive, or delete the block |
 | `X_ACTION_DEPRECATION_INVALID` | `deprecated:` with a `since`/`sunset` that is not a date | use an ISO-8601 instant |
-| `X_INPUT_INVALID` | input failed the Standard Schema. Carries the rejections **twice**: the flattened line in `cause`, and the structured list in `meta.issues` — one value rendered two ways, `As of 2026-08-24` | `x actions describe <name> --json` |
+| `X_INPUT_INVALID` | input failed the Standard Schema. Carries the rejections **twice**: the flattened line in `cause`, and the structured list in `meta.issues` — one value rendered two ways, `As of 2026-08-24` | `x actions show <name> --json` |
 | `X_IDEMPOTENCY_CONFLICT` | key reused with a new payload / still in flight | new key, or retry later |
 | `X_IDEMPOTENCY_KEY_INVALID` | `Idempotency-Key:` sent blank (`Headers.get()` answers `''`, not `null`) or past 255 characters | send one unique value per request, or omit the header |
 | `X_IDEMPOTENCY_NOT_SHARED` | `configureIdempotency({ scope: 'shared' })` over a per-process (or scope-less) store | install `postgresIdempotencyStore({ executor, origin, reclaimAfterMs })` at boot |

package/package.json

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

package/src/action.ts

@@ -348,7 +348,7 @@ export function describeAction(target: AnyAction): ActionDescriptor {
       // a first honest `expose: false` read as a withdrawn capability and demand a major bump.
       expose: isMcpExposed(mcp),
       // The export name verbatim, which is the only name `@ultimat3/mcp` will answer a
-      // `tools/call` for. A derived one made every descriptor reader — `x actions describe
+      // `tools/call` for. A derived one made every descriptor reader — `x actions show
       // --json`, the `actions.describe` dev tool, the `/_x` panel — name a tool no surface
       // serves. `x.manifest.json` is not among them: it copies `expose` and `description` only.
       tool: name,

package/src/client.ts

@@ -224,7 +224,7 @@ function toUltimateError(
     issues: issuesFromWire(body['issues']),
     meta: metaFromWire(body['meta']),
     cause: stringOr(body['cause'] ?? body['detail'], `${name} failed with ${status}`),
-    fix: stringOr(body['fix'], `x actions describe ${name} --json`),
+    fix: stringOr(body['fix'], `x actions show ${name} --json`),
     // RFC-9457's `type` IS a documentation URI, so a server that sends no `docs` extension has
     // still offered one. Both travel, in preference order: `??` picked `docs` on presence alone,
     // so a `javascript:` one hid a perfectly good `type` behind it. `remoteDocs` takes the first

package/src/contract-test.ts

@@ -100,7 +100,7 @@ function assertDocumented(target: AnyAction, name: string): void {
 /**
  * The refusal when the published document does not name this action at its route. `name` is
  * whatever `.named()` was handed — nothing validates its alphabet — so it is screened where it
- * enters the `x actions describe` command (security audit of plan 101 sweep 1c).
+ * enters the `x actions show` command (security audit of plan 101 sweep 1c).
  */
 export function documentedDrift(
   path: string,
@@ -113,7 +113,7 @@ export function documentedDrift(
       : `OpenAPI document serves ${path} as ${owner}, so ${name} is not in the published contract`,
     owner === undefined
       ? 'x verify --json   # the contract suite is a step of it'
-      : `x actions describe ${renderFixShellArg(name, '<action>')} --json   # then rename it, or pin its own route with http: { path } in the ${name} definition`,
+      : `x actions show ${renderFixShellArg(name, '<action>')} --json   # then rename it, or pin its own route with http: { path } in the ${name} definition`,
   );
 }
 
@@ -138,7 +138,7 @@ function assertSampleable(target: AnyAction, name: string): void {
   const described = gaps.map((path) => describeSampleGap(target.input, path)).join(', ');
   throw new ContractDriftError(
     `${name}: no value can be synthesized for ${described}, so the denial would be unproven`,
-    `contractTestsFor(${name}, { input: { … } })   # x actions describe ${name} --json prints the schema`,
+    `contractTestsFor(${name}, { input: { … } })   # x actions show ${name} --json prints the schema`,
   );
 }
 
@@ -196,7 +196,7 @@ async function expectDenied(
     if (error.code !== 'X_INPUT_INVALID') throw error;
     throw new ContractDriftError(
       `${name} failed with ${error.code} before its policy decided, so the denial is unproven`,
-      `pass \`input:\` to contractTestsFor(${name}) — x actions describe ${name} --json prints the schema`,
+      `pass \`input:\` to contractTestsFor(${name}) — x actions show ${name} --json prints the schema`,
     );
   }
   throw new ContractDriftError(

package/src/errors-idempotency.ts

@@ -185,7 +185,7 @@ export class IdempotentReplayRedactedError extends UltimateError {
     super({
       code: 'X_IDEMPOTENT_REPLAY_REDACTED',
       cause: `the answer stored for idempotency key "${key}" had a secret-named field redacted when it settled, so it cannot be replayed faithfully`,
-      fix: "x actions describe '<action>' --json   # the call already ran and showed its secret once — read its effect with a query; a new Idempotency-Key runs it again (a second credential)",
+      fix: "x actions show '<action>' --json   # the call already ran and showed its secret once — read its effect with a query; a new Idempotency-Key runs it again (a second credential)",
       meta: { key, replayed: true },
     });
   }

package/src/errors.ts

@@ -187,9 +187,9 @@ export class InputInvalidError extends UltimateError {
     super({
       code: 'X_INPUT_INVALID',
       cause: `input for ${subject} "${name}" failed validation: ${detail}`,
-      fix: `x actions describe ${renderFixShellArg(name, '<action-name>')} --json  # prints the expected input schema`,
+      fix: `x actions show ${renderFixShellArg(name, '<action-name>')} --json  # prints the expected input schema`,
       // A remote caller holds the published schema — the MCP `inputSchema`, the OpenAPI request
-      // body — and cannot run `x actions describe`.
+      // body — and cannot run `x actions show`.
       callerFix:
         'correct the fields named in cause to match the published input schema (the tool inputSchema, or the OpenAPI request body) and send again — the same input is refused the same way',
       ...(issues === undefined ? {} : { meta: { issues } }),
@@ -208,7 +208,7 @@ export class OutputInvalidError extends UltimateError {
     super({
       code: 'X_OUTPUT_INVALID',
       cause: `action "${name}" returned a value its output schema rejects: ${detail}`,
-      fix: `x actions describe ${renderFixShellArg(name, '<action-name>')} --json  # compare the handler's return against \`output:\``,
+      fix: `x actions show ${renderFixShellArg(name, '<action-name>')} --json  # compare the handler's return against \`output:\``,
     });
   }
 }
@@ -353,7 +353,7 @@ export class RpcFailedError extends UltimateError {
     super({
       code: 'X_RPC_FAILED',
       cause: `${name} returned HTTP ${status} without a problem+json body`,
-      fix: `check the gateway in front of the app, then: x actions describe ${renderFixShellArg(name, '<action-name>')} --json`,
+      fix: `check the gateway in front of the app, then: x actions show ${renderFixShellArg(name, '<action-name>')} --json`,
       retry: retryForStatus('X_RPC_FAILED', status),
     });
   }

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/mutator.ts

@@ -226,7 +226,7 @@ function wrap<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>
   return self;
 }
 
-/** The descriptor's name for a policy — the manifest and `x actions describe` print this. */
+/** The descriptor's name for a policy — the manifest and `x actions show` print this. */
 function strategyOf(conflict: ConflictPolicy): MutatorDescriptor['conflict'] {
   return typeof conflict === 'string' ? conflict : conflict.kind;
 }

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