@ultimat3/action 29.4.0 → 30.1.0

package/src/contract-test.ts

@@ -1,20 +1,30 @@
 /**
- * Projection 6: the tests. `x g action` emits these three assertions for every
- * new action, so an action that skips validation, skips authz, or never reaches
- * the spec fails CI on the day it is written.
+ * Projection 6: the tests. `x g action` emits these four assertions for every
+ * new action, so an action that skips validation, skips authz, never reaches
+ * the spec, or crashes on a legal input fails CI on the day it is written.
  */
 
 import type { Ctx } from '@ultimat3/core';
-import { ctxOf, isJsonObject, isUltimateError, logger, renderFixShellArg } from '@ultimat3/core';
+import {
+  ctxOf,
+  isJsonObject,
+  isUltimateError,
+  logger,
+  renderFixShellArg,
+  toOpenApiPath,
+} from '@ultimat3/core';
+import { describeSampleGap, sampleGaps, sampleInput } from '@ultimat3/schema/sample';
 import type { AnyAction } from './action';
+import { declaredErrorsContract } from './declared-errors-contract';
 import { ActionDeniedError, ContractDriftError } from './errors';
+import type { ExerciseOptions } from './exercise';
+import { exerciseContract } from './exercise';
 import { toOpenApiOperation } from './http';
-import { servedActionRoute } from './http-path';
-import { actionName, invoke } from './invoke';
+import { methodOfHttp, servedActionRoute } from './http-path';
+import { actionName, defOf, invoke } from './invoke';
 import { buildOpenApi } from './openapi';
 import { listActions } from './registry';
-import { describeSampleGap, sampleGaps, sampleInput } from './sample-input';
-import { validateInput } from './validate';
+import { parseActionInput } from './validate';
 
 export interface ContractTest {
   readonly name: string;
@@ -32,6 +42,12 @@ export interface ContractTestOptions {
    */
   readonly input?: unknown;
   readonly ctx?: Ctx;
+  /**
+   * The fourth assertion: the handler, called with generated input its schema accepts, inside a
+   * rolled-back transaction. `{ actor }` says who acts (required unless the policy admits an
+   * anonymous caller); `{ off: '<reason>' }` skips it out loud.
+   */
+  readonly exercise?: ExerciseOptions;
 }
 
 /** A context whose actor is core's anonymous actor — what a signed-out caller has. */
@@ -55,7 +71,7 @@ export function contractTestsFor(
       // refused 401 without the schema ever seeing the garbage. The claim is about `input:`.
       run: async () => {
         await expectThrow(
-          () => validateInput(target.input, garbage, name),
+          () => parseActionInput(target.input, garbage, name),
           'X_INPUT_INVALID',
           `${name} accepted the value this assertion sent as garbage`,
           `tighten \`input:\` in the ${name} definition`,
@@ -78,6 +94,9 @@ export function contractTestsFor(
       name: `${name}: OpenAPI document contains its operation`,
       run: async () => assertDocumented(target, name),
     },
+    exerciseContract(target, options.exercise, options.ctx),
+    // Only for an action declaring `errors:`: its handler's own source names nothing else.
+    ...declaredErrorsContract(target, name),
   ];
 }
 
@@ -90,9 +109,10 @@ export function contractTestsFor(
 function assertDocumented(target: AnyAction, name: string): void {
   const seated = listActions();
   const actions = seated.some((other) => other.name === name) ? seated : [...seated, target];
-  const { path } = servedActionRoute(name);
+  // The document's `{param}` spelling, under the verb the action declares (`http.method`).
+  const path = toOpenApiPath(servedActionRoute(name).path);
   const published = buildOpenApi({ actions }).paths[path];
-  const owner = operationIdAt(published);
+  const owner = operationIdAt(published, methodOfHttp(defOf(target).http).toLowerCase());
   if (owner === toOpenApiOperation(target).operationId) return;
   throw documentedDrift(path, owner, name);
 }
@@ -117,10 +137,12 @@ export function documentedDrift(
   );
 }
 
-/** `paths[path].post.operationId`, read off a value typed `unknown` — narrowed, never cast. */
-function operationIdAt(entry: unknown): string | undefined {
-  if (!isJsonObject(entry) || !isJsonObject(entry['post'])) return undefined;
-  const id = entry['post']['operationId'];
+/** `paths[path][verb].operationId`, read off a value typed `unknown` — narrowed, never cast. */
+function operationIdAt(entry: unknown, verb: string): string | undefined {
+  if (!isJsonObject(entry)) return undefined;
+  const operation = entry[verb];
+  if (!isJsonObject(operation)) return undefined;
+  const id = operation['operationId'];
   return typeof id === 'string' ? id : undefined;
 }
 
@@ -154,6 +176,8 @@ import { ${name} } from './actions';
 // Fill in: arrange a foreign actor, expect the policy to deny.
 // The contract tests below are framework-generated and always included. Pass
 // \`{ input }\` if the synthesized one cannot satisfy this action's schema or row loader.
+// A guarded action also needs \`{ exercise: { actor } }\` — who its handler runs as for the
+// generated-input runs — or \`{ exercise: { off: '<reason>' } }\`.
 for (const contract of contractTestsFor(${name})) {
   test(contract.name, async () => {
     await contract.run();
@@ -188,7 +212,7 @@ async function expectDenied(
     if (error instanceof ActionDeniedError) return;
     // `invoke` runs the policy's actor half → parse input → row → policy → handle → parse
     // output, and every stage lands here identically. Only `X_INPUT_INVALID` is attributable: it
-    // is what `validateInput` raises before `guardAction()` is reached (for a policy whose actor half
+    // is what `parseActionInput` raises before `guardAction()` is reached (for a policy whose actor half
     // could not decide), and `input:` is the knob that answers it. Any other
     // code — `X_TENANCY_UNSCOPED` from a `row:` loader, `X_DB_CONFLICT` from a handler,
     // `X_OUTPUT_INVALID` from the parse after it — keeps its own code and its own fix rather

package/src/declared-errors-contract.ts

@@ -0,0 +1,38 @@
+// Single responsibility: `.contract()`'s assertion for an action declaring `errors:` — the codes its
+// `handle` and `row` name in their own source, judged by core's rule. First hop only: what a
+// helper throws is the dynamic half's (`declared-errors.ts`), reached by any test of the path.
+
+import {
+  definedErrorClassCodes,
+  ErrorUndeclaredError,
+  judgeThrown,
+  scanHandlerSource,
+} from '@ultimat3/core';
+import { declaredStatusFor } from '@ultimat3/http';
+import type { AnyAction } from './action';
+import type { ContractTest } from './contract-test';
+import { defOf } from './invoke';
+
+/**
+ * The static half: one assertion, only for an action that declares `errors:`. A code literal or a
+ * `defineError` class in `handle`'s or `row`'s own source, 4xx and outside the list, is red here
+ * whether or not a test reaches the line. First hop only — a helper is the dynamic half's.
+ */
+export function declaredErrorsContract(target: AnyAction, name: string): readonly ContractTest[] {
+  const def = defOf(target);
+  if (def.errors === undefined) return [];
+  const declared = def.errors;
+  return [
+    {
+      name: `${name}: its handler names only the errors it declares`,
+      run: async () => {
+        const source = `${def.handle.toString()}\n${def.row?.toString() ?? ''}`;
+        const stray = scanHandlerSource(source, await definedErrorClassCodes()).filter(
+          (code) => judgeThrown(declared, code, declaredStatusFor(code)) === 'undeclared',
+        );
+        if (stray.length === 0) return;
+        throw new ErrorUndeclaredError({ primitive: 'action', name }, stray.join("', '"));
+      },
+    },
+  ];
+}

package/src/declared-errors.ts

@@ -0,0 +1,13 @@
+// Single responsibility: the wrap `invoke` puts around `handle` and `row` for an action declaring
+// `errors:`. Core owns the rule (`declared-errors.ts`, shared with `@ultimat3/query`) and
+// `@ultimat3/http` the status; the static half is `declared-errors-contract.ts`.
+
+import { withDeclaredErrors } from '@ultimat3/core';
+import { declaredStatusFor } from '@ultimat3/http';
+import type { AnyActionDef } from './action';
+
+/** A throw out of `run` judged against `def.errors`. Undeclared, the call is `run` itself. */
+export function judgedHandler<T>(def: AnyActionDef, name: string, run: () => T): Promise<T> | T {
+  if (def.errors === undefined) return run();
+  return withDeclaredErrors(def.errors, declaredStatusFor, { primitive: 'action', name }, run);
+}

package/src/error-titles.ts

@@ -4,7 +4,7 @@
 // `index.ts` imports this bare, because `problemError` rebuilds a server's refusal by code and reads
 // its title from the registry; `errors.ts` and its two siblings import it bare as well.
 
-import { registerErrorCodes } from '@ultimat3/core';
+import { registerErrorCodes, registerErrorRetry } from '@ultimat3/core';
 
 /**
  * Titles for the framework-wide code table — every one of them owned by this package.
@@ -34,7 +34,7 @@ export const ACTION_ERROR_TITLES: Readonly<Record<string, string>> = {
     "a mutator declares conflict: 'last-write-wins' and its entity has no number clock column",
   X_OUTPUT_INVALID: 'a handler returned a value its output schema rejects',
   X_RPC_FAILED: 'an RPC call failed without a problem+json body',
-  X_ACTION_HTTP_PATH_INVALID: "an action's pinned http.path is not a static lowercase path",
+  X_ACTION_HTTP_PATH_INVALID: "an action's pinned http.path is not a valid path or :param template",
   X_ACTION_PATH_STYLE_INVALID: "defineApi's http.pathStyle is not a known style",
   X_OPENAPI_CONFIG_INVALID: "defineApi's openapi block cannot produce a valid document",
   X_ACTION_PATH_DERIVED_EARLY: 'a path was derived before pathStyle changed',
@@ -42,6 +42,15 @@ export const ACTION_ERROR_TITLES: Readonly<Record<string, string>> = {
   X_IDEMPOTENCY_RESERVATION_LOST:
     "an idempotent action's reservation was taken over before its transaction could settle it",
   X_IDEMPOTENT_REPLAY_REDACTED: 'an idempotent replay would return a field redacted at rest',
+  X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE:
+    "an idempotent action's answer cannot be stored as JSON, so no retry could replay it",
+  X_IDEMPOTENCY_RUN_CEILING: 'a keyed run passed its hard ceiling',
+  X_CONTRACT_DEFECT: 'a generated legal input made a handler fail',
+  X_CONTRACT_EXERCISE_UNREACHED: 'no generated run reached the handler',
+  X_CONTRACT_EXERCISE_UNDECLARED: '.contract() on a non-public action names no exercise',
+  X_ACTION_STREAM_INVALID: 'a streaming action broke its stream contract',
+  X_METER_EXCEEDED: "an action's usage meter is spent for this period",
+  X_METER_INVALID: "an action's meter cannot be counted against",
 };
 
 // One unconditional call: a presence guard would turn "another package claims one of these codes"
@@ -49,3 +58,10 @@ export const ACTION_ERROR_TITLES: Readonly<Record<string, string>> = {
 registerErrorCodes(
   Object.fromEntries(Object.entries(ACTION_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
+
+/**
+ * The one code this package throws that a caller is SUPPOSED to come back from, and it says when:
+ * `meta.retryAfterSeconds` is the period's end, rendered onto `Retry-After`, and a job's retry
+ * waits for it instead of spending its attempts on an allowance that cannot refill sooner.
+ */
+registerErrorRetry({ X_METER_EXCEEDED: 'retry-after' });

package/src/errors-http.ts

@@ -9,16 +9,33 @@ import { renderCauseValue, UltimateError } from '@ultimat3/core';
 import './error-titles';
 
 export class ActionHttpPathInvalidError extends UltimateError {
-  constructor(input: { name: string; path: unknown; reason: string }) {
+  constructor(input: { name: string; path: unknown; reason: string; fix?: string }) {
     super({
       code: 'X_ACTION_HTTP_PATH_INVALID',
       cause: `action "${input.name}" pins http.path ${renderCauseValue(input.path)}, which ${input.reason}`,
-      fix: "pin a static lowercase path: http: { path: '/api/webhooks/wompi' } — a leading slash, segments of a-z 0-9 . _ ~ -, no :param or *wildcard, no trailing slash, never under /_x",
+      fix:
+        input.fix ??
+        "http: { path: '/orders/:id/refund', method: 'POST' } with input: t.object({ id: t.string }) — every :param a required t.string key of input:; segments of a-z 0-9 . _ ~ -, no *wildcard, no trailing slash, never under /_x; method POST, PUT, PATCH or DELETE",
       meta: { action: input.name },
     });
   }
 }
 
+/**
+ * `deprecated.replacedBy` names an action served at a `:param` template. The successor travels as a
+ * `Link` header, and a header cannot carry a template a client has no values for.
+ */
+export class ActionDeprecationSuccessorInvalidError extends UltimateError {
+  constructor(input: { name: string; successor: string; path: string }) {
+    super({
+      code: 'X_ACTION_DEPRECATION_INVALID',
+      cause: `action "${input.name}" declares deprecated.replacedBy "${input.successor}", which is served at the template ${input.path} — a Link header cannot carry a template`,
+      fix: `deprecated: { since, sunset } — on ${input.name}, drop replacedBy, or name an action whose http.path has no :param`,
+      meta: { action: input.name, field: 'replacedBy', value: input.successor },
+    });
+  }
+}
+
 export class ActionPathStyleInvalidError extends UltimateError {
   constructor(value: unknown) {
     super({

package/src/errors-idempotency.ts

@@ -174,6 +174,41 @@ export class IdempotencyReservationLostError extends UltimateError {
   }
 }
 
+/**
+ * A keyed handler's answer that JSON has no form for: in practice a `bigint`, since
+ * `restingAnswer` has already cut a cycle and everything else `JSON.stringify` could run app code
+ * on. Refused by `withIdempotency`, before either store is asked: memory would keep the live value
+ * and replay it while Postgres threw an uncoded `TypeError` from its settle and left the record in
+ * flight, so the same handler answered differently per store. Settled as a failure and replayed:
+ * the handler ran, and running it again is the double charge.
+ */
+export class IdempotencyOutputUnserializableError extends UltimateError {
+  constructor(key: string) {
+    super({
+      code: 'X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE',
+      cause: `the answer of the handler under idempotency key "${key}" holds a value JSON has no form for, so no retry could replay it. The handler has run`,
+      fix: 'handle: ({ input }) => ({ id: String(input.id) })   # return JSON: String(id) for a bigint, text with no NUL and no lone surrogate (a NaN is not this refusal: it rests as null), then send a fresh Idempotency-Key once the handler is fixed',
+      meta: { key },
+    });
+  }
+}
+
+/**
+ * A keyed run still going at its ceiling. It outlives the request deadline on purpose, and nothing
+ * else would end it: the request's in-flight count, the key's 409 and the drain would all wait. The
+ * handler may have written, so the failure is SETTLED and replayed, never released.
+ */
+export class IdempotencyRunCeilingError extends UltimateError {
+  constructor(key: string, ceilingMs: number) {
+    super({
+      code: 'X_IDEMPOTENCY_RUN_CEILING',
+      cause: `the handler under idempotency key "${key}" was still running ${ceilingMs}ms after it started: it was aborted and the key settled as this failure. It may have written before that, so read its effect before sending a fresh key`,
+      fix: 'configureIdempotency({ scope, ceilingMs: 300_000 })   # at boot, to raise the ceiling; or make the call that hung with outbound() from @ultimat3/core/outbound, which the ceiling aborts',
+      meta: { key, ceilingMs },
+    });
+  }
+}
+
 /**
  * A replay of a settled answer that had a field redacted at rest. Refused, never served: the
  * stored copy holds `[redacted]` where the first caller got a credential, and handing that back

package/src/errors-meter.ts

@@ -0,0 +1,48 @@
+/**
+ * The meter's two refusals: a period's allowance spent (`X_METER_EXCEEDED`, the caller's), and a
+ * declaration or a call-time limit that cannot be counted against (`X_METER_INVALID`, the app's).
+ * Codes and titles stay in `error-titles.ts`'s one registration; imported bare for that reason.
+ */
+import { renderCauseValue, renderFixShellArg, UltimateError } from '@ultimat3/core';
+import './error-titles';
+
+export interface MeterExceededInput {
+  readonly action: string;
+  readonly meter: string;
+  readonly period: string;
+  readonly limit: number;
+  readonly resetsAtMs: number;
+  readonly nowMs: number;
+}
+
+/**
+ * `meta.retryAfterSeconds` is the framework's one spelling of a stated delay: `@ultimat3/http`
+ * renders it onto `Retry-After`, and a job's retry waits the same number.
+ */
+export class MeterExceededError extends UltimateError {
+  constructor(input: MeterExceededInput) {
+    const resetsAt = new Date(input.resetsAtMs).toISOString();
+    const retryAfterSeconds = Math.max(1, Math.ceil((input.resetsAtMs - input.nowMs) / 1000));
+    super({
+      code: 'X_METER_EXCEEDED',
+      cause: `the "${input.meter}" meter on action "${input.action}" allows ${input.limit} calls per ${input.period} (UTC), and this caller's allowance for the period is spent; it resets at ${resetsAt}`,
+      fix: `x actions show ${renderFixShellArg(input.action, '<action>')} --json   # names the meter and its period; raise what meter.limit resolves to for this tenant in the action file, or retry after meta.resetsAt`,
+      callerFix: `retry after ${resetsAt} (the Retry-After header): the "${input.meter}" allowance resets then, and a larger one is the application's to grant`,
+      meta: { meter: input.meter, limit: input.limit, resetsAt, retryAfterSeconds },
+    });
+  }
+}
+
+export type MeterField = 'name' | 'period' | 'limit' | 'warnAt';
+
+/** A meter declared — or a limit resolved — that no counter could enforce. */
+export class MeterInvalidError extends UltimateError {
+  constructor(meter: string, field: MeterField, expected: string, value?: unknown) {
+    super({
+      code: 'X_METER_INVALID',
+      cause: `meter "${meter}" declares ${field}${value === undefined ? '' : ` = ${renderCauseValue(value)}`}, which is not ${expected}`,
+      fix: `meter: { name: 'calls', period: 'day', limit: ({ ctx }) => 500, warnAt: 0.8, onWarn: quotaWarning }   # edit the action declaring "${renderFixShellArg(meter, '<meter>')}" — ${field} must be ${expected}`,
+      meta: { meter, field },
+    });
+  }
+}

package/src/errors-stream.ts

@@ -0,0 +1,18 @@
+// The streaming action's one refusal, `X_ACTION_STREAM_INVALID`: a declaration that says it streams
+// and a handler that does not, or a chunk its own `stream` schema refuses.
+
+import { UltimateError } from '@ultimat3/core';
+
+const FIX =
+  'async *handle({ input, ctx }) { yield chunk; return output; } — yield only what stream: declares';
+
+export class ActionStreamInvalidError extends UltimateError {
+  constructor(action: string, reason: string) {
+    super({
+      code: 'X_ACTION_STREAM_INVALID',
+      cause: `action "${action}" declares stream: and ${reason}`,
+      fix: FIX,
+      meta: { action },
+    });
+  }
+}

package/src/errors.ts

@@ -12,6 +12,7 @@ import {
   renderFixShellArg,
   retryForStatus,
   UltimateError,
+  withRequestId,
   withStatedDelay,
 } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
@@ -29,8 +30,10 @@ export {
   IdempotencyConflictError,
   IdempotencyKeyInvalidError,
   IdempotencyNotSharedError,
+  IdempotencyOutputUnserializableError,
   IdempotencyReplayedFailureError,
   IdempotencyReservationLostError,
+  IdempotencyRunCeilingError,
   IdempotencyStatusUnknownError,
   IdempotentReplayRedactedError,
   MutatorNotIdempotentError,
@@ -264,6 +267,8 @@ export interface RemoteFailure {
   readonly title?: string | undefined;
   /** The delay the answer's `Retry-After` named, in seconds (core's `retryAfterSecondsOf`). */
   readonly retryAfterSeconds?: number | undefined;
+  /** The document's root `requestId`, as the wire had it: core's `withRequestId` judges it. */
+  readonly requestId?: unknown;
 }
 
 /** A link, not a string the server happened to put in a field the overlay renders as an href. */
@@ -323,18 +328,21 @@ export class RemoteActionError extends UltimateError {
       // Core's `withStatedDelay`, the rule `problemError` applies too: a `retryAfterSeconds` off the
       // body is dropped and only the header's is carried — the server never writes one there.
       meta: withStatedDelay(
-        {
-          // The server's declared keys FIRST, so the four this class owns win a collision: a
-          // server meta naming `status` would otherwise overwrite the one a report reads the HTTP
-          // status from, and `origin: 'remote'` marks the code as one this bundle never declared.
-          ...failure.meta,
-          origin: 'remote',
-          action: failure.action,
-          status: failure.status,
-          // Absent rather than `undefined`: `meta` is rendered into `--json` and the error
-          // reporter, and a null member reads as "the server sent an empty list".
-          ...(failure.issues === undefined ? {} : { issues: failure.issues }),
-        },
+        withRequestId(
+          {
+            // The server's declared keys FIRST, so the four this class owns win a collision: a
+            // server meta naming `status` would otherwise overwrite the one a report reads the HTTP
+            // status from, and `origin: 'remote'` marks the code as one this bundle never declared.
+            ...failure.meta,
+            origin: 'remote',
+            action: failure.action,
+            status: failure.status,
+            // Absent rather than `undefined`: `meta` is rendered into `--json` and the error
+            // reporter, and a null member reads as "the server sent an empty list".
+            ...(failure.issues === undefined ? {} : { issues: failure.issues }),
+          },
+          failure.requestId,
+        ),
         failure.retryAfterSeconds,
       ),
     });

package/src/exercise-errors.ts

@@ -0,0 +1,74 @@
+/**
+ * The exercise assertion's refusals. Off the socket: each is raised inside `bun test` by the
+ * contract step and never served, so none has an HTTP status. `@ultimat3/query` raises the same
+ * three codes from its own twin (it cannot import this tier), borrowing the titles registered here.
+ */
+
+import { isUltimateError, renderFixShellArg, UltimateError } from '@ultimat3/core';
+import './error-titles';
+import { ContractDriftError } from './errors';
+
+/** A generated legal input made the handler fail: an uncoded throw, a bad output, a coded 5xx. */
+export class ContractDefectError extends UltimateError {
+  constructor(input: {
+    name: string;
+    run: number;
+    input: unknown;
+    defect: string;
+    replay: string;
+    /** What the handler threw: kept whole as `sourceError`, its code and cause in `meta.failure`. */
+    error: unknown;
+  }) {
+    super({
+      code: 'X_CONTRACT_DEFECT',
+      cause: `${input.name} ${input.defect} on generated run ${input.run}, for input its own schema accepts (meta.input, meta.failure)`,
+      fix: `${input.replay}   # replays the run; fix the ${input.name} handler or tighten its input: first`,
+      meta: {
+        run: input.run,
+        input: input.input,
+        ...(isUltimateError(input.error)
+          ? { failure: { code: input.error.code, cause: input.error.cause } }
+          : {}),
+      },
+      sourceError: input.error,
+    });
+  }
+}
+
+/** Not one run got as far as the handler: the assertion would have proven nothing. */
+export class ExerciseUnreachedError extends UltimateError {
+  constructor(name: string, outcomes: readonly string[]) {
+    const call = renderFixShellArg(name, '<name>');
+    super({
+      code: 'X_CONTRACT_EXERCISE_UNREACHED',
+      cause: `none of ${outcomes.length} generated runs of ${name} reached its handler (meta.outcomes lists what each one hit)`,
+      fix: `${call}.contract({ exercise: { actor } }) with an actor the policy permits — or bind a real row: { exercise: { actor, input: (drawn) => ({ ...drawn, id }) } }`,
+      meta: { outcomes },
+    });
+  }
+}
+
+/** A guarded handler with no `exercise` said, or an opt-out with no reason. */
+export class ExerciseUndeclaredError extends UltimateError {
+  constructor(name: string, blankReason: boolean) {
+    const call = renderFixShellArg(name, '<name>');
+    super({
+      code: 'X_CONTRACT_EXERCISE_UNDECLARED',
+      cause: blankReason
+        ? `${name}.contract({ exercise: { off } }) gives a blank reason, so the skip is silent`
+        : `${name} refuses an anonymous caller and its .contract() names no actor to exercise its handler as`,
+      fix: `${call}.contract({ exercise: { actor } }) — or ${call}.contract({ exercise: { off: '<why this handler cannot run in a test>' } })`,
+    });
+  }
+}
+
+/**
+ * Every draw failed the schema it was drawn from — a provider refinement the IR does not carry.
+ * `X_CONTRACT_DRIFT`, the code the policy assertion already raises for the same gap.
+ */
+export function everyDrawRefused(name: string): ContractDriftError {
+  return new ContractDriftError(
+    `${name}: its input schema refused every generated value, so the handler was never exercised`,
+    `${renderFixShellArg(name, '<name>')}.contract({ exercise: { actor, input: (drawn) => ({ ...drawn, field: '<a value the refinement accepts>' }) } })`,
+  );
+}

package/src/exercise.ts

@@ -0,0 +1,153 @@
+/**
+ * The contract step's fourth assertion, as an action needs it: `@ultimat3/core`'s exercise loop
+ * (`runExercise`) over `invoke`, each run inside a rolled-back transaction, "reached" read off the
+ * handler counter. The verdict, the seed and the replay are the loop's, shared with `query`.
+ */
+
+import type { Actor, Ctx, DrawnInput, ExerciseAttempt, ExerciseReport } from '@ultimat3/core';
+import {
+  bindDrawn,
+  ctxOf,
+  exerciseReplay,
+  isUltimateError,
+  runExercise,
+  tryUseContext,
+} from '@ultimat3/core';
+import { statusFor } from '@ultimat3/http';
+import { admitsAnonymous } from '@ultimat3/policy';
+import { arbitrary } from '@ultimat3/schema/sample';
+import type { AnyAction } from './action';
+import type { ContractTest } from './contract-test';
+import {
+  ContractDefectError,
+  ExerciseUndeclaredError,
+  ExerciseUnreachedError,
+  everyDrawRefused,
+} from './exercise-errors';
+import { actionName, handlerReached, invoke } from './invoke';
+import { inRolledBackScope, rollbackAvailable } from './tx-scope';
+import { parseActionInput } from './validate';
+
+export type { ExerciseReport };
+
+/** Who the handler runs as, and what binds the parts a generated value cannot (a real row's id). */
+export interface ExerciseActorOptions {
+  /** The caller each run is invoked as. `null` is the signed-out caller. */
+  readonly actor: Actor | null;
+  /**
+   * `(drawn) => ({ ...drawn, postId })`: the generated value, with what must resolve bound in.
+   * May be `async`: `x exercise` awaits it inside the call's own request, so `useContext().actor`
+   * is the actor the call runs as (a token issued to that actor, a passkey it registered).
+   */
+  readonly input?: (drawn: DrawnInput) => unknown;
+  /** 1 to `EXERCISE_RUNS_MAX`; `EXERCISE_RUNS` when omitted. */
+  readonly runs?: number;
+}
+
+/** No exercise, said out loud: the reason is listed in the assertion's name. */
+export interface ExerciseOffOptions {
+  readonly off: string;
+}
+
+export type ExerciseOptions = ExerciseActorOptions | ExerciseOffOptions;
+
+/** The name the assertion runs under — also the `-t` that replays it. */
+export const exerciseTestName = (name: string): string =>
+  `${name}: handler survives generated input`;
+
+/**
+ * Exercise `target`: call its handler with generated input its own schema accepts. Throws
+ * `X_CONTRACT_DEFECT` on the first defect, `X_CONTRACT_EXERCISE_UNREACHED` when no run got to the
+ * handler, `X_CONTRACT_DRIFT` when the schema refused every draw.
+ *
+ * A test-time call: refused in `staging`/`production` (`X_CONTRACT_EXERCISE_ENVIRONMENT`). Each
+ * run's transaction rolls back the handler's SQL writes, its memory-store writes (`test` with no
+ * client installed, `tx` passed or not), the post-commit cache bust (either store) and, when a SQL
+ * transaction is open, the outbox stage. NOT rolled back: a write on a second client or
+ * `outsideTransaction`, a job enqueued with `outbox: false`, every job enqueue when no SQL
+ * transaction is open (the memory store: the jobs facade enqueues straight to the job driver),
+ * storage puts, mail, outbound fetch (sealed under the test preload) and rate-limit counters.
+ */
+export async function exerciseAction(
+  target: AnyAction,
+  options: ExerciseActorOptions,
+  ctx?: Ctx,
+): Promise<ExerciseReport> {
+  const name = actionName(target);
+  const base = ctx ?? tryUseContext() ?? ctxOf({});
+  const verdict = await runExercise({
+    name,
+    runs: options.runs,
+    stoppedLabel: 'stopped before the handler',
+    scoped: rollbackAvailable(),
+    draw: (seed, run) => arbitrary(target.input, { seed, run }),
+    bind: bindDrawn(options.input),
+    accepts: (input) => acceptedBy(target, input, name),
+    attempt: async (input): Promise<ExerciseAttempt> => {
+      const before = handlerReached(target);
+      const settled = await inRolledBackScope(() =>
+        invoke(target, input, { ctx: base, actor: options.actor, surface: 'http' }),
+      );
+      const reached = handlerReached(target) > before;
+      return settled.ok ? { ok: true, reached } : { ok: false, reached, error: settled.error };
+    },
+    statusOf: statusFor,
+  });
+  switch (verdict.kind) {
+    case 'pass':
+      return verdict.report;
+    case 'drift':
+      throw everyDrawRefused(name);
+    case 'unreached':
+      throw new ExerciseUnreachedError(name, verdict.outcomes);
+    case 'defect':
+      throw new ContractDefectError({
+        name,
+        run: verdict.run,
+        input: verdict.input,
+        defect: verdict.defect,
+        replay: exerciseReplay(name, exerciseTestName(name)),
+        error: verdict.error,
+      });
+  }
+}
+
+async function acceptedBy(target: AnyAction, input: unknown, name: string): Promise<boolean> {
+  try {
+    await parseActionInput(target.input, input, name);
+    return true;
+  } catch (error) {
+    if (isUltimateError(error) && error.code === 'X_INPUT_INVALID') return false;
+    throw error;
+  }
+}
+
+/**
+ * The assertion `.contract()` appends. A public action exercises as the signed-out caller unless
+ * told otherwise; a guarded one must say who acts or why not — there is no bypass and none is
+ * added, so a policy that denies the named actor is an unreached run, not a skipped one.
+ */
+export function exerciseContract(
+  target: AnyAction,
+  exercise: ExerciseOptions | undefined,
+  ctx: Ctx | undefined,
+): ContractTest {
+  const name = actionName(target);
+  if (exercise !== undefined && 'off' in exercise) {
+    const reason = exercise.off.trim();
+    return reason.length === 0
+      ? {
+          name: exerciseTestName(name),
+          run: () => Promise.reject(new ExerciseUndeclaredError(name, true)),
+        }
+      : { name: `${name}: handler exercise off: ${reason}`, run: () => Promise.resolve() };
+  }
+  const options = exercise ?? (admitsAnonymous(target.policy) ? { actor: null } : undefined);
+  return {
+    name: exerciseTestName(name),
+    run: async () => {
+      if (options === undefined) throw new ExerciseUndeclaredError(name, false);
+      await exerciseAction(target, options, ctx);
+    },
+  };
+}