@ultimat3/action 25.0.0 → 25.1.0

package/CLAUDE.md

@@ -120,7 +120,7 @@ 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`.
+  `t.uuid`; `row` goes to `mutator()` as declared, never loaded here (#687).
 - **A lookup table is read with `Object.hasOwn`** (`IRREGULAR` in `naming.ts`, `BY_FORMAT` in
   `sample-input.ts`) — caller- or provider-supplied keys.
 
@@ -222,8 +222,8 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
   inside `withWriteOrigin(writeDigest(key))` so the page recognises its own `records` echo. A label,
   never a gate.
 - **Both stores FENCE a settlement on the reservation `id` AND `in-flight`**:
-  `settle(key, value, reservationId, redacted)` / `fail(key, failure, reservationId)`. A fenced no-op is logged,
-  never thrown.
+  `settle(key, value, reservationId, redacted)` / `fail(key, failure, reservationId)` /
+  `release(key, reservationId)`. A fenced no-op is never thrown.
 - **An answer rests REDACTED** (#591): `withIdempotency` passes the store `restingAnswer(value)`
   (core's `isRedactedKey` + `isSecret` — never a second rule) and `redacted` as `settle`'s
   REQUIRED 4th argument; both stores keep it (`x_idempotency.redacted`, memory's record field).

package/README.md

@@ -410,6 +410,7 @@ 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 |
 | `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
@@ -519,7 +520,7 @@ export function counted(inner: IdempotencyStore, onSettle: () => void): Idempote
       onSettle();
       return inner.settle(key, value, reservationId, redacted);
     },
-    release: (key) => inner.release(key),
+    release: (key, reservationId) => inner.release(key, reservationId),
     get: (key) => inner.get(key),
   };
 }
@@ -601,6 +602,14 @@ Both stores fence on it AND on `in-flight` `As of 2026-08`, the way `@ultimat3/j
 so a straggler from the first attempt satisfied a status-only fence exactly and overwrote a live
 reservation.
 
+`release` takes it too (`As of 2026-10-07`): it is the pre-handler cleanup when `beforeRun` refuses,
+and keyed alone it DELETED whatever record the key held — a replacement's reservation, or its
+settled answer, so the next retry re-ran a handler that had already committed. A release that
+matches nothing does nothing (`idempotency-release.test.ts`, both stores). **A custom store's
+`release(key, reservationId)` must delete only the record whose id is `reservationId` and whose
+status is `in-flight`** — one that ignores the second argument reopens the double-run window, and
+type-checking cannot catch it: a one-parameter function still satisfies the signature.
+
 **Inside a transaction the settlement commits with the write** (`As of 2026-10-02`, BOTH stores —
 `idempotency-parity.test.ts` runs one set of cases over memory and Postgres). An action invoked
 inside `withTransaction` settles with that transaction: on its own connection (Postgres), or at

package/package.json

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

package/src/idempotency-memory.ts

@@ -200,8 +200,9 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     return existing;
   }
 
-  release(key: string): Promise<void> {
-    this.#records.delete(key);
+  /** Fenced by `#owned`, as both settlements are: a record that is not this reservation stays. */
+  release(key: string, reservationId: string): Promise<void> {
+    if (this.#owned(key, reservationId) !== undefined) this.#records.delete(key);
     return Promise.resolve();
   }
 

package/src/idempotency-postgres.ts

@@ -109,7 +109,9 @@ update x_idempotency set status = 'failed', value = null, failure = $2::jsonb,
 returning key
 `;
 
-export const SQL_IDEMPOTENCY_RELEASE = `delete from x_idempotency where key = $1`;
+export const SQL_IDEMPOTENCY_RELEASE = `
+delete from x_idempotency where key = $1 and id = $2::uuid and status = 'in-flight'
+`;
 
 export const SQL_IDEMPOTENCY_PURGE = `
 delete from x_idempotency where created_at < now() - make_interval(secs => $1::double precision)
@@ -294,8 +296,10 @@ export function postgresIdempotencyStore(
       fenced(rows, key, reservationId, 'fail');
     },
 
-    async release(key): Promise<void> {
-      await exec.query(SQL_IDEMPOTENCY_RELEASE, [key]);
+    // Fenced, and silent when it matches nothing: a release is a pre-handler cleanup, so a record
+    // that is no longer this reservation's is somebody else's to settle.
+    async release(key, reservationId): Promise<void> {
+      await exec.query(SQL_IDEMPOTENCY_RELEASE, [key, reservationId]);
     },
 
     get: fetch,

package/src/idempotency.ts

@@ -137,8 +137,13 @@ export interface IdempotencyStore {
    * and re-running it is the double charge.
    */
   fail?(key: string, failure: IdempotencyFailure, reservationId: string): Promise<void>;
-  /** Drop a reservation, so a retry can run. Only ever correct BEFORE the handler starts. */
-  release(key: string): Promise<void>;
+  /**
+   * Drop the reservation `reservationId` owns, so a retry can run. Only ever correct BEFORE the
+   * handler starts. Fenced like `settle` and `fail`: a straggler whose reservation was reclaimed
+   * past the deadline deleted the REPLACEMENT's record by key — settled, the next retry re-ran a
+   * handler that had committed. A release that matches nothing is a no-op.
+   */
+  release(key: string, reservationId: string): Promise<void>;
   get(key: string): Promise<IdempotencyRecord | undefined>;
 }
 
@@ -252,7 +257,15 @@ export async function withIdempotency<T>(
     try {
       await options.beforeRun();
     } catch (error) {
-      await store.release(key);
+      // THIS reservation's id: one reclaimed while `beforeRun` waited is no longer ours to drop.
+      // A release the store refuses never replaces the refusal: the caller is owed the 429, not a
+      // driver error. The reservation then stays in flight until the window lapses (an autocommit
+      // one is never reclaimed early), so a retry inside it is a 409 — logged, so it is findable.
+      try {
+        await store.release(key, record.id);
+      } catch (storeError) {
+        logger.error('action.idempotency.release-refused', { key, error: storeError });
+      }
       throw error;
     }
   }

package/src/sample-input.ts

@@ -99,6 +99,25 @@ function sampleObject(node: SchemaNode): Record<string, unknown> {
   return sample;
 }
 
+/**
+ * The most items a sample will hold. A contract sample is a handful of values; `minItems` past
+ * this is an input the framework does not invent — `2 ** 32` made `Array.from` throw, and anything
+ * below it allocated that many samples first. Such an array is a GAP (`sampleGaps`), reported as
+ * `X_CONTRACT_DRIFT` with the instruction to pass the input, never silently under-sampled.
+ */
+export const SAMPLE_ITEMS_MAX = 1000;
+
+/**
+ * The `minItems` an array sample owes, or `undefined` when none can be built: past the ceiling,
+ * or not a count at all. The builtin `t.array` refuses a bad bound at declaration
+ * (`X_SCHEMA_BOUNDS_INVALID`), but this IR may come from a swapped provider.
+ */
+function owedItems(node: SchemaNode): number | undefined {
+  const min = node.minItems;
+  if (min === undefined) return 0;
+  return Number.isSafeInteger(min) && min >= 0 && min <= SAMPLE_ITEMS_MAX ? min : undefined;
+}
+
 function sampleFor(node: SchemaNode): unknown {
   // A nullable field accepts `null`, and `null` is the smallest thing it accepts.
   if (node.nullable === true) return null;
@@ -115,8 +134,13 @@ function sampleFor(node: SchemaNode): unknown {
       return node.values?.[0] ?? SAMPLE_STRING;
     case 'literal':
       return node.literal ?? null;
+    // The fewest items the array accepts: `[]` under a `minItems` is a sample its own schema
+    // refuses. Items repeat the one item sample; a uniqueness rule would be a refinement.
     case 'array':
-      return [];
+      // An unbuildable count samples `[]`, which the schema refuses — `sampleGaps` names why.
+      return Array.from({ length: owedItems(node) ?? 0 }, () =>
+        node.items === undefined ? null : sampleFor(node.items),
+      );
     case 'union': {
       const first = node.anyOf?.[0];
       return first === undefined ? null : sampleFor(first);
@@ -174,24 +198,29 @@ function gapsIn(node: SchemaNode, path: string): string[] {
     }
     return out;
   }
-  if (satisfiesPattern(node, sampleFor(node))) return [];
+  const unbuildable = node.kind === 'array' && owedItems(node) === undefined;
+  if (!unbuildable && satisfiesPattern(node, sampleFor(node))) return [];
   return [path === '' ? ROOT_PATH : path];
 }
 
 /** `orderRef` -> `orderRef (must match ^ORD-\d{4}$)`, for a cause a reader can act on. */
 export function describeSampleGap(schema: StandardSchemaV1, path: string): string {
-  const pattern = patternAt(tryIntrospect(schema), path);
+  const node = nodeAt(tryIntrospect(schema), path);
+  if (node?.kind === 'array' && node.minItems !== undefined && owedItems(node) === undefined) {
+    return `${path} (needs at least ${node.minItems} items)`;
+  }
+  const pattern = node?.pattern;
   return pattern === undefined ? path : `${path} (must match ${pattern})`;
 }
 
-function patternAt(node: SchemaNode | undefined, path: string): string | undefined {
+function nodeAt(node: SchemaNode | undefined, path: string): SchemaNode | undefined {
   if (node === undefined) return undefined;
-  if (path === '' || path === ROOT_PATH) return node.pattern;
+  if (path === '' || path === ROOT_PATH) return node;
   const [head, ...rest] = path.split('.');
   // `path` is the caller's — `describeSampleGap` is exported — so the same own-property read the
   // format table takes: `properties['constructor']` is otherwise the `Object` function.
   const properties = node.properties ?? {};
   const child =
     head === undefined || !Object.hasOwn(properties, head) ? undefined : properties[head];
-  return child === undefined ? undefined : patternAt(child, rest.join('.'));
+  return child === undefined ? undefined : nodeAt(child, rest.join('.'));
 }

package/src/transition.ts

@@ -18,6 +18,7 @@ import type {
   StringSchema,
 } from '@ultimat3/schema';
 import { nodeOf, t } from '@ultimat3/schema';
+import type { ActionRowArgs } from './action';
 import { type Mutator, mutator } from './mutator';
 import type { ActionPolicy } from './policy-gate';
 
@@ -57,6 +58,7 @@ export interface TransitionDef<
   Row extends InferOutput<TOutput> & object,
   K extends keyof Row & string,
   S extends Row[K] & string,
+  TRow = unknown,
 > {
   /** The request's table — `(ctx) => posts(ctx)`, so the move is tenant-scoped like every write. */
   readonly table: (ctx: Ctx) => TransitionTarget<Row, S>;
@@ -84,7 +86,21 @@ export interface TransitionDef<
    * column's own shape.
    */
   readonly id?: StringSchema;
-  readonly policy: ActionPolicy;
+  readonly policy: ActionPolicy<TRow>;
+  /**
+   * The row a row-level `policy` decides about — an action's own `row` loader, handed through
+   * unchanged: loaded once, after the input parse, before the guard and before the statement. The
+   * 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.
+   */
+  row?(args: ActionRowArgs<TransitionInput<S>>): TRow | null | Promise<TRow | null>;
   /**
    * OFF unless the app says otherwise, and deliberately not `?? true`.
    *
@@ -110,7 +126,8 @@ export function transition<
   Row extends InferOutput<TOutput> & object,
   K extends keyof Row & string,
   const S extends Row[K] & string,
->(def: TransitionDef<TOutput, Row, K, S>): Mutator<TransitionInput<S>, TOutput> {
+  TRow = unknown,
+>(def: TransitionDef<TOutput, Row, K, S, TRow>): Mutator<TransitionInput<S>, TOutput> {
   const state = t.enum(def.states);
   // ONE cast, and it is a compiler limitation rather than an unknown value: `t.object`'s output is
   // a mapped type over its shape, and a mapped type does not reduce while a type parameter is still
@@ -119,13 +136,16 @@ export function transition<
   // reason. What arrives here has already been parsed by the schema two lines up, and nothing else
   // can reach these two callbacks.
   const valuesOf = (raw: unknown): TransitionValues<S> => raw as TransitionValues<S>;
-  return mutator({
+  const row = def.row;
+  return mutator<TransitionInput<S>, TOutput, TRow>({
     input: t.object({ id: def.id ?? keySchemaOf(def.output), from: state, to: state }),
     output: def.output,
     policy: def.policy,
     // A compare-and-set move replayed under its key answers the first outcome, never a second
     // `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) }),
     ...(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.

package/src/tx-scope.ts

@@ -40,7 +40,7 @@ export interface LiveTransaction extends CommitScope {
  * settlement bound to a transaction that already ended is bound to nothing: it would run as its
  * own commit while the record claimed otherwise, and that record is the one a retry may reclaim.
  *
- * The fragment is assembled by hand, exactly as `@ultimat3/cli`'s `pgExecutorFor` does: the caller
+ * The fragment is assembled by hand, exactly as `@ultimat3/db`'s `dbExecutor` does: the caller
  * wrote the `$1..$n` text itself and hands over already-bound values.
  */
 export function liveTransaction(): LiveTransaction | undefined {

package/src/type-pins.ts

@@ -92,6 +92,11 @@ export type _APreRedactionStoreIsNotAStore = Assert<
   Equals<PreRedactionStore extends IdempotencyStore ? true : false, false>
 >;
 
+/** A release names the reservation it drops — the fence `settle` and `fail` already carry. */
+export type _ReleaseNamesTheReservation = Assert<
+  Equals<Parameters<IdempotencyStore['release']>['length'], 2>
+>;
+
 /** …and `settle`'s flag is required of every CALLER, so a wrapping store cannot drop it either. */
 export type _SettleRequiresTheRedactedFlag = Assert<
   Equals<Parameters<IdempotencyStore['settle']>['length'], 4>