@ultimat3/action 30.6.0 → 30.8.0

package/CLAUDE.md

@@ -42,6 +42,7 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 | `contract-test.ts` | assertions `x g action` emits |
 | `exercise.ts` | the fourth contract assertion: run loop, verdict, `exerciseContract` |
 | `exercise-errors.ts` | the three `X_CONTRACT_*` classes, off-socket |
+| `exercise-declarations.ts` | `.contract({ exercise })` takes the app's `defineExercise()` value (structural `ExerciseDeclarations`) and reads the entry by the action's name: one declaration in `apps/web/exercise.ts`, read by the contract step and `x exercise` |
 | `declared-errors.ts` | the wrap `invoke` puts around `handle` and `row`, the ONLY judged throws. `errors:` is checked, sorted and frozen at `action()` |
 | `declared-errors-contract.ts` | `.contract()`'s source scan |
 | `openapi-errors.ts` | core's builder bound to http's status and `problemTypeFor` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "30.6.0",
+  "version": "30.8.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "keywords": [
     "ultimate",
@@ -46,12 +46,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "30.6.0",
-    "@ultimat3/core": "30.6.0",
-    "@ultimat3/db": "30.6.0",
-    "@ultimat3/entity": "30.6.0",
-    "@ultimat3/http": "30.6.0",
-    "@ultimat3/policy": "30.6.0",
-    "@ultimat3/schema": "30.6.0"
+    "@ultimat3/cache": "30.8.0",
+    "@ultimat3/core": "30.8.0",
+    "@ultimat3/db": "30.8.0",
+    "@ultimat3/entity": "30.8.0",
+    "@ultimat3/http": "30.8.0",
+    "@ultimat3/policy": "30.8.0",
+    "@ultimat3/schema": "30.8.0"
   }
 }

package/src/contract-test.ts

@@ -17,8 +17,8 @@ import { describeSampleGap, sampleGaps, sampleInput } from '@ultimat3/schema/sam
 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 type { ContractExercise } from './exercise-declarations';
 import { toOpenApiOperation } from './http';
 import { methodOfHttp, servedActionRoute } from './http-path';
 import { actionName, defOf, invoke } from './invoke';
@@ -44,10 +44,12 @@ export interface ContractTestOptions {
   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.
+   * rolled-back transaction. In an app, the `exercise` export of `apps/web/exercise.ts` — the
+   * `defineExercise()` value `x exercise` reads — and this action's entry in it is the one used:
+   * one declaration, both runners. One entry inline (`{ actor }`, `{ off: '<reason>' }`) is for a
+   * test binding rows of its own world. Required unless the policy admits an anonymous caller.
    */
-  readonly exercise?: ExerciseOptions;
+  readonly exercise?: ContractExercise;
 }
 
 /** A context whose actor is core's anonymous actor — what a signed-out caller has. */
@@ -176,8 +178,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>' } }\`.
+// A guarded action also needs who its handler runs as for the generated-input runs: its entry in
+// apps/web/exercise.ts (\`{ actor }\` or \`{ off: '<reason>' }\`), handed in as \`{ exercise }\`.
 for (const contract of contractTestsFor(${name})) {
   test(contract.name, async () => {
     await contract.run();

package/src/exercise-declarations.ts

@@ -0,0 +1,37 @@
+/**
+ * One declaration of a primitive's exercise: the app's `defineExercise()` value (apps/web/exercise.ts,
+ * the file `x exercise` reads), handed whole to `.contract({ exercise })`, resolved here by the
+ * primitive's own name. Structural, so `@ultimat3/testing`'s value satisfies it without an import up.
+ */
+
+import type { ExerciseOptions } from './exercise';
+
+export type { ExerciseOptions };
+
+/** The one file an app declares its exercise in — every refusal's fix names it. */
+export const EXERCISE_DECLARATIONS_FILE = 'apps/web/exercise.ts';
+
+/** `defineExercise()`'s value, as far as a contract reads it: the entries, by primitive name. */
+export interface ExerciseDeclarations {
+  readonly kind: 'exercise-overrides';
+  readonly entries: ReadonlyMap<string, ExerciseOptions>;
+}
+
+/** What `.contract({ exercise })` takes: the app's declarations, or one entry inline. */
+export type ContractExercise = ExerciseOptions | ExerciseDeclarations;
+
+export const isExerciseDeclarations = (value: ContractExercise): value is ExerciseDeclarations =>
+  'kind' in value && value.kind === 'exercise-overrides';
+
+/**
+ * The entry `name` reads: the declarations' own, or the inline one. `undefined` when none. An
+ * `'action:<name>'` key wins over the bare name — the one `x exercise` reads for an action whose
+ * name a job shares (`@ultimat3/testing`'s `overrideFor`; query's twin keeps the same rule).
+ */
+export function resolveExercise(
+  name: string,
+  exercise: ContractExercise | undefined,
+): ExerciseOptions | undefined {
+  if (exercise === undefined || !isExerciseDeclarations(exercise)) return exercise;
+  return exercise.entries.get(`action:${name}`) ?? exercise.entries.get(name);
+}

package/src/exercise-errors.ts

@@ -4,9 +4,19 @@
  * three codes from its own twin (it cannot import this tier), borrowing the titles registered here.
  */
 
-import { isUltimateError, renderFixShellArg, UltimateError } from '@ultimat3/core';
+import {
+  isUltimateError,
+  renderDrawnInput,
+  renderExerciseKey,
+  renderFixShellArg,
+  sampleGapBinding,
+  UltimateError,
+} from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { describeSampleGap, sampleGaps } from '@ultimat3/schema/sample';
 import './error-titles';
 import { ContractDriftError } from './errors';
+import { EXERCISE_DECLARATIONS_FILE } from './exercise-declarations';
 
 /** A generated legal input made the handler fail: an uncoded throw, a bad output, a coded 5xx. */
 export class ContractDefectError extends UltimateError {
@@ -42,33 +52,64 @@ export class ExerciseUnreachedError extends UltimateError {
     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 }) } }`,
+      fix: `defineExercise({ ${call}: { actor } })   # in ${EXERCISE_DECLARATIONS_FILE}, an actor the policy permits — or bind a real row: { actor, input: (drawn) => ({ ...drawn, id }) }`,
       meta: { outcomes },
     });
   }
 }
 
-/** A guarded handler with no `exercise` said, or an opt-out with no reason. */
+/**
+ * Why no exercise could run: an `off` with no reason, nothing declared, no entry by this name, or
+ * an entry with no `actor` on a guarded handler — `x exercise` picks one its policy allows, a
+ * contract test has no role set to pick from.
+ */
+export type ExerciseUndeclaredWhy = 'blank' | 'undeclared' | 'no-entry' | 'no-actor';
+
+/**
+ * A guarded handler with no exercise. The fix is the paste in the ONE home, `apps/web/exercise.ts`
+ * — the file `x exercise` reads and `.contract({ exercise })` is handed — never an inline option:
+ * an entry declared only in a test is one `x exercise` cannot see. `@ultimat3/query` twins it.
+ */
 export class ExerciseUndeclaredError extends UltimateError {
-  constructor(name: string, blankReason: boolean) {
+  constructor(name: string, why: ExerciseUndeclaredWhy) {
     const call = renderFixShellArg(name, '<name>');
+    const refuses = `${name} refuses an anonymous caller`;
     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>' } })`,
+      cause: undeclaredCause(name, why, refuses),
+      fix: `defineExercise({ ${call}: { actor } })   # in ${EXERCISE_DECLARATIONS_FILE}, then ${call}.contract({ exercise }) with that file's export — or { off: '<why this handler cannot run in a test>' } there`,
     });
   }
 }
 
+/** What was missing, said in the file it is missing from. A `switch`, never a key lookup on a table. */
+function undeclaredCause(name: string, why: ExerciseUndeclaredWhy, refuses: string): string {
+  switch (why) {
+    case 'blank':
+      return `${name}.contract({ exercise: { off } }) gives a blank reason, so the skip is silent`;
+    case 'no-entry':
+      return `${refuses} and ${EXERCISE_DECLARATIONS_FILE} declares no entry for it, so no actor to exercise its handler as is known`;
+  }
+  return `${refuses} and its .contract() names no actor to exercise its handler as`;
+}
+
 /**
- * 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.
+ * Every draw failed the schema it was drawn from. `X_CONTRACT_DRIFT`, the code the policy
+ * assertion already raises for the same gap. A field whose `pattern` (or item count) the sampler
+ * cannot meet is named in the cause and bound in the fix's `input:`; a provider refinement the IR
+ * does not carry leaves only the placeholder field, honestly.
  */
-export function everyDrawRefused(name: string): ContractDriftError {
+export function everyDrawRefused(name: string, schema: StandardSchemaV1): ContractDriftError {
+  const gaps = sampleGaps(schema);
+  const described = gaps.map((path) => describeSampleGap(schema, path));
+  const input =
+    gaps.length === 0
+      ? "(drawn) => ({ ...drawn, field: '<a value the refinement accepts>' })"
+      : renderDrawnInput(gaps.map((path, i) => sampleGapBinding(path, described[i] ?? path)));
   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>' }) } })`,
+    gaps.length === 0
+      ? `${name}: its input schema refused every generated value, so the handler was never exercised`
+      : `${name}: its input schema refused every generated value — no value can be generated for ${described.join(', ')} — so the handler was never exercised`,
+    `defineExercise({ ${renderExerciseKey(name)}: { input: ${input} } })   # in ${EXERCISE_DECLARATIONS_FILE}`,
   );
 }

package/src/exercise.ts

@@ -13,11 +13,14 @@ import {
   runExercise,
   tryUseContext,
 } from '@ultimat3/core';
-import { statusFor, withScratchRateLimitStore } from '@ultimat3/http';
+import type { ExerciseRequestOption } from '@ultimat3/http';
+import { statusFor, withRequestAs, withScratchRateLimitStore } 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 type { ContractExercise } from './exercise-declarations';
+import { isExerciseDeclarations, resolveExercise } from './exercise-declarations';
 import {
   ContractDefectError,
   ExerciseUndeclaredError,
@@ -32,8 +35,12 @@ 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;
+  /**
+   * The caller each run is invoked as. `null` is the signed-out caller. Omitted, `x exercise`
+   * picks the first actor the policy allows (as it does with no entry); a contract test runs as
+   * the signed-out caller when the policy admits one, else `X_CONTRACT_EXERCISE_UNDECLARED`.
+   */
+  readonly actor?: Actor | null | undefined;
   /**
    * `(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`
@@ -42,6 +49,13 @@ export interface ExerciseActorOptions {
   readonly input?: (drawn: DrawnInput) => unknown;
   /** 1 to `EXERCISE_RUNS_MAX`; `EXERCISE_RUNS` when omitted. */
   readonly runs?: number;
+  /**
+   * What the call's request carries in: the cookie a first step set (a pending sign-in, an OAuth
+   * state), a header. A function is awaited before EACH call, as that call's actor, so it can mint
+   * a session for whoever acts. Read by `x exercise` and the contract step alike: each run is then
+   * invoked inside that request (`@ultimat3/http`'s `withRequestAs`) instead of the bare context.
+   */
+  readonly request?: ExerciseRequestOption;
 }
 
 /** No exercise, said out loud: the reason is listed in the assertion's name. */
@@ -75,6 +89,7 @@ export async function exerciseAction(
   ctx?: Ctx,
 ): Promise<ExerciseReport> {
   const name = actionName(target);
+  const actor = exerciseActor(target, options, name);
   const base = ctx ?? tryUseContext() ?? ctxOf({});
   // Counted in a scratch store: a spent bucket would make the file's next real call a 429.
   const verdict = await withScratchRateLimitStore(() =>
@@ -88,8 +103,13 @@ export async function exerciseAction(
       accepts: (input) => acceptedBy(target, input, name),
       attempt: async (input): Promise<ExerciseAttempt> => {
         const before = handlerReached(target);
+        // The actor is ON the declared request, so `invoke` takes none: its impersonation path
+        // would rebuild a plain child context and drop the request's headers.
+        const { request } = options;
         const settled = await inRolledBackScope(() =>
-          invoke(target, input, { ctx: base, actor: options.actor, surface: 'http' }),
+          request === undefined
+            ? invoke(target, input, { ctx: base, actor, surface: 'http' })
+            : withRequestAs(name, actor, request, () => invoke(target, input, { surface: 'http' })),
         );
         const reached = handlerReached(target) > before;
         return settled.ok ? { ok: true, reached } : { ok: false, reached, error: settled.error };
@@ -101,7 +121,7 @@ export async function exerciseAction(
     case 'pass':
       return verdict.report;
     case 'drift':
-      throw everyDrawRefused(name);
+      throw everyDrawRefused(name, target.input);
     case 'unreached':
       throw new ExerciseUnreachedError(name, verdict.outcomes);
     case 'defect':
@@ -116,6 +136,13 @@ export async function exerciseAction(
   }
 }
 
+/** An entry's actor; none declared is the signed-out caller where the policy admits one. */
+function exerciseActor(target: AnyAction, options: ExerciseActorOptions, name: string) {
+  if (options.actor !== undefined) return options.actor;
+  if (admitsAnonymous(target.policy)) return null;
+  throw new ExerciseUndeclaredError(name, 'no-actor');
+}
+
 async function acceptedBy(target: AnyAction, input: unknown, name: string): Promise<boolean> {
   try {
     await parseActionInput(target.input, input, name);
@@ -133,16 +160,17 @@ async function acceptedBy(target: AnyAction, input: unknown, name: string): Prom
  */
 export function exerciseContract(
   target: AnyAction,
-  exercise: ExerciseOptions | undefined,
+  declared: ContractExercise | undefined,
   ctx: Ctx | undefined,
 ): ContractTest {
   const name = actionName(target);
+  const exercise = resolveExercise(name, declared);
   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)),
+          run: () => Promise.reject(new ExerciseUndeclaredError(name, 'blank')),
         }
       : { name: `${name}: handler exercise off: ${reason}`, run: () => Promise.resolve() };
   }
@@ -150,7 +178,11 @@ export function exerciseContract(
   return {
     name: exerciseTestName(name),
     run: async () => {
-      if (options === undefined) throw new ExerciseUndeclaredError(name, false);
+      if (options === undefined) {
+        const why =
+          declared !== undefined && isExerciseDeclarations(declared) ? 'no-entry' : 'undeclared';
+        throw new ExerciseUndeclaredError(name, why);
+      }
       await exerciseAction(target, options, ctx);
     },
   };

package/src/index.ts

@@ -135,6 +135,7 @@ export type {
   ExerciseReport,
 } from './exercise';
 export { exerciseAction } from './exercise';
+export type { ContractExercise, ExerciseDeclarations } from './exercise-declarations';
 export type { OpenApiOperation } from './http';
 export {
   operationTagOf,