@ultimat3/action 30.7.0 → 30.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "30.7.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.7.0",
-    "@ultimat3/core": "30.7.0",
-    "@ultimat3/db": "30.7.0",
-    "@ultimat3/entity": "30.7.0",
-    "@ultimat3/http": "30.7.0",
-    "@ultimat3/policy": "30.7.0",
-    "@ultimat3/schema": "30.7.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/exercise-declarations.ts

@@ -23,11 +23,15 @@ 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. */
+/**
+ * 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(name);
+  return exercise.entries.get(`action:${name}`) ?? exercise.entries.get(name);
 }

package/src/exercise.ts

@@ -13,7 +13,8 @@ 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';
@@ -48,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. */
@@ -95,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, 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 };