@ultimat3/query 30.7.0 → 30.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "30.7.0",
+  "version": "30.9.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "keywords": [
     "ultimate",
@@ -47,12 +47,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.9.0",
+    "@ultimat3/core": "30.9.0",
+    "@ultimat3/db": "30.9.0",
+    "@ultimat3/entity": "30.9.0",
+    "@ultimat3/http": "30.9.0",
+    "@ultimat3/policy": "30.9.0",
+    "@ultimat3/schema": "30.9.0"
   }
 }

package/src/exercise-declarations.ts

@@ -24,11 +24,15 @@ export const isQueryExerciseDeclarations = (
   value: QueryContractExercise,
 ): value is QueryExerciseDeclarations => '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. A
+ * `'query:<name>'` key wins over the bare name — the one `x exercise` reads for a query whose
+ * name another kind shares (`@ultimat3/testing`'s `overrideFor`; action's twin keeps the same rule).
+ */
 export function resolveQueryExercise(
   name: string,
   exercise: QueryContractExercise | undefined,
 ): QueryExerciseOptions | undefined {
   if (exercise === undefined || !isQueryExerciseDeclarations(exercise)) return exercise;
-  return exercise.entries.get(name);
+  return exercise.entries.get(`query:${name}`) ?? exercise.entries.get(name);
 }

package/src/exercise.ts

@@ -18,7 +18,8 @@ import {
   tryUseContext,
   UltimateError,
 } 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 type { StandardSchemaV1 } from '@ultimat3/schema';
 import { validateAsync } from '@ultimat3/schema';
@@ -38,6 +39,8 @@ export interface QueryExerciseActorOptions {
   readonly actor?: Actor | null | undefined;
   readonly input?: (drawn: DrawnInput) => unknown;
   readonly runs?: number;
+  /** What each run's request carries in; the read then runs inside it (action's `request`). */
+  readonly request?: ExerciseRequestOption;
 }
 
 export interface QueryExerciseOffOptions {
@@ -93,13 +96,16 @@ export async function exerciseQuery(
       bind: bindDrawn(options.input),
       accepts: (input) => accepts(target.input, input),
       attempt: async (input) => {
+        const { request } = options;
         try {
-          const source = await sourceFor(target, input, {
-            ctx: base,
-            actor,
-            surface: 'http',
-          });
-          await source.execute();
+          // On a declared request the reader is ON it, so `sourceFor` takes no actor.
+          if (request === undefined) {
+            await (await sourceFor(target, input, { ctx: base, actor, surface: 'http' })).execute();
+          } else {
+            await withRequestAs(name, actor, request, async () => {
+              await (await sourceFor(target, input, { surface: 'http' })).execute();
+            });
+          }
           return { ok: true, reached: true };
         } catch (error) {
           return { ok: false, reached: !beforeSql(error), error };