@ultimat3/query 30.5.0 → 30.7.0

package/CLAUDE.md

@@ -16,6 +16,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `read.ts` | **the one read path** (`runQuery`, `sourceFor`) + the private declaration store `sql` lives in |
 | `contract-test.ts` | `.contract()`, the generated suite. The three `X_CONTRACT_*` codes and `X_CONTRACT_DRIFT` are borrowed (`QUERY_BORROWED_ERROR_CODES`) |
 | `exercise.ts` | the exercise twin. "Reached" means `sql()` built a source, read off the refusal (`beforeSql`), because `read.ts` keeps no counter. No transaction: a read writes nothing |
+| `exercise-declarations.ts` | action's twin: `.contract({ exercise })` takes the app's `defineExercise()` value and reads the entry by the query's name (`apps/web/exercise.ts`, the one home) |
 | `declared-errors.ts` | `judgedSql` / `judgedRead`, around `sql` and the source's `execute` in `read.ts`. `errors:` is checked where it is lifted (`facade.ts`), not in `query.ts` |
 | `declared-errors-contract.ts`, `openapi-errors.ts` | `.contract()`'s source scan; core's builder bound to http's status |
 | `http-pin.ts` | a read's pinned `http.path`, its check at `query()`, `servedQueryPath`, `queryHttpPinOf` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "30.5.0",
+  "version": "30.7.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.5.0",
-    "@ultimat3/core": "30.5.0",
-    "@ultimat3/db": "30.5.0",
-    "@ultimat3/entity": "30.5.0",
-    "@ultimat3/http": "30.5.0",
-    "@ultimat3/policy": "30.5.0",
-    "@ultimat3/schema": "30.5.0"
+    "@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"
   }
 }

package/src/contract-test.ts

@@ -7,8 +7,9 @@
 import type { Ctx } from '@ultimat3/core';
 import { admitsAnonymous } from '@ultimat3/policy';
 import { declaredErrorsContract } from './declared-errors-contract';
-import type { QueryExerciseOptions } from './exercise';
 import { exerciseQuery, queryExerciseTestName, queryExerciseUndeclared } from './exercise';
+import type { QueryContractExercise } from './exercise-declarations';
+import { isQueryExerciseDeclarations, resolveQueryExercise } from './exercise-declarations';
 import type { AnyQuery } from './query';
 import { queryName } from './read';
 
@@ -20,10 +21,12 @@ export interface QueryContractTest {
 
 export interface QueryContractTestOptions {
   /**
-   * Who the generated runs read as — required unless the policy admits an anonymous reader — or
-   * `{ off: '<reason>' }`, which skips the runs out loud: the reason is in the test's name.
+   * Who the generated runs read as. In an app, the `exercise` export of `apps/web/exercise.ts` —
+   * the `defineExercise()` value `x exercise` reads — and this query'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 reader.
    */
-  readonly exercise?: QueryExerciseOptions;
+  readonly exercise?: QueryContractExercise;
   /** The context each run starts from; the actor is swapped in, the rest kept. */
   readonly ctx?: Ctx;
 }
@@ -37,7 +40,7 @@ export function queryContractTestsFor(
 
 function exerciseContract(target: AnyQuery, options: QueryContractTestOptions): QueryContractTest {
   const name = queryName(target);
-  const exercise = options.exercise;
+  const exercise = resolveQueryExercise(name, options.exercise);
   if (exercise !== undefined && 'off' in exercise) {
     const reason = exercise.off.trim();
     if (reason.length > 0) {
@@ -45,14 +48,21 @@ function exerciseContract(target: AnyQuery, options: QueryContractTestOptions):
     }
     return {
       name: queryExerciseTestName(name),
-      run: () => Promise.reject(queryExerciseUndeclared(name, true)),
+      run: () => Promise.reject(queryExerciseUndeclared(name, 'blank')),
     };
   }
   const chosen = exercise ?? (admitsAnonymous(target.policy) ? { actor: null } : undefined);
   return {
     name: queryExerciseTestName(name),
     run: async () => {
-      if (chosen === undefined) throw queryExerciseUndeclared(name, false);
+      if (chosen === undefined) {
+        const declared = options.exercise;
+        const why =
+          declared !== undefined && isQueryExerciseDeclarations(declared)
+            ? 'no-entry'
+            : 'undeclared';
+        throw queryExerciseUndeclared(name, why);
+      }
       await exerciseQuery(target, chosen, options.ctx);
     },
   };

package/src/exercise-declarations.ts

@@ -0,0 +1,34 @@
+/**
+ * One declaration of a read'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
+ * query's own name. Action's twin (`exercise-declarations.ts` there): a sideways import is refused.
+ */
+
+import type { QueryExerciseOptions } from './exercise';
+
+export type { QueryExerciseOptions };
+
+/** The one file an app declares its exercise in — every refusal's fix names it. */
+export const QUERY_EXERCISE_DECLARATIONS_FILE = 'apps/web/exercise.ts';
+
+/** `defineExercise()`'s value, as far as a contract reads it: the entries, by primitive name. */
+export interface QueryExerciseDeclarations {
+  readonly kind: 'exercise-overrides';
+  readonly entries: ReadonlyMap<string, QueryExerciseOptions>;
+}
+
+/** What `.contract({ exercise })` takes: the app's declarations, or one entry inline. */
+export type QueryContractExercise = QueryExerciseOptions | QueryExerciseDeclarations;
+
+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. */
+export function resolveQueryExercise(
+  name: string,
+  exercise: QueryContractExercise | undefined,
+): QueryExerciseOptions | undefined {
+  if (exercise === undefined || !isQueryExerciseDeclarations(exercise)) return exercise;
+  return exercise.entries.get(name);
+}

package/src/exercise.ts

@@ -10,23 +10,32 @@ import {
   ctxOf,
   exerciseReplay,
   isUltimateError,
+  renderDrawnInput,
+  renderExerciseKey,
   renderFixShellArg,
   runExercise,
+  sampleGapBinding,
   tryUseContext,
   UltimateError,
 } from '@ultimat3/core';
 import { statusFor, withScratchRateLimitStore } from '@ultimat3/http';
+import { admitsAnonymous } from '@ultimat3/policy';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { validateAsync } from '@ultimat3/schema';
-import { arbitrary } from '@ultimat3/schema/sample';
+import { arbitrary, describeSampleGap, sampleGaps } from '@ultimat3/schema/sample';
 import { QueryAuditSinkMissingError } from './audit-errors';
 import { QueryDeniedError } from './errors';
+import { QUERY_EXERCISE_DECLARATIONS_FILE } from './exercise-declarations';
 import type { AnyQuery } from './query';
 import { queryName, sourceFor } from './read';
 
-/** Who reads, and what binds the parts a generated value cannot. Same shape as an action's. */
+/**
+ * Who reads, and what binds the parts a generated value cannot. Same shape as an action's: an
+ * omitted `actor` is `x exercise`'s pick, and here the signed-out reader where the policy admits
+ * one, else `X_CONTRACT_EXERCISE_UNDECLARED`.
+ */
 export interface QueryExerciseActorOptions {
-  readonly actor: Actor | null;
+  readonly actor?: Actor | null | undefined;
   readonly input?: (drawn: DrawnInput) => unknown;
   readonly runs?: number;
 }
@@ -72,6 +81,7 @@ export async function exerciseQuery(
   ctx?: Ctx,
 ): Promise<QueryExerciseReport> {
   const name = queryName(target);
+  const actor = readerOf(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(() =>
@@ -86,7 +96,7 @@ export async function exerciseQuery(
         try {
           const source = await sourceFor(target, input, {
             ctx: base,
-            actor: options.actor,
+            actor,
             surface: 'http',
           });
           await source.execute();
@@ -102,7 +112,7 @@ export async function exerciseQuery(
     case 'pass':
       return verdict.report;
     case 'drift':
-      throw queryDrawsRefused(name);
+      throw queryDrawsRefused(name, target.input);
     case 'unreached':
       throw queryUnreached(name, verdict.outcomes);
     case 'defect':
@@ -134,27 +144,68 @@ function queryUnreached(name: string, outcomes: readonly string[]): UltimateErro
   return new UltimateError({
     code: 'X_CONTRACT_EXERCISE_UNREACHED',
     cause: `none of ${outcomes.length} generated runs of query ${name} reached its sql() (meta.outcomes lists what each one hit)`,
-    fix: `${renderFixShellArg(name, '<name>')}.contract({ exercise: { actor } }) with an actor the policy permits`,
+    fix: `defineExercise({ ${renderFixShellArg(name, '<name>')}: { actor } })   # in ${QUERY_EXERCISE_DECLARATIONS_FILE}, an actor the policy permits`,
     meta: { outcomes },
   });
 }
 
-function queryDrawsRefused(name: string): UltimateError {
+/** An entry's reader; none declared is the signed-out reader where the policy admits one. */
+function readerOf(target: AnyQuery, options: QueryExerciseActorOptions, name: string) {
+  if (options.actor !== undefined) return options.actor;
+  if (admitsAnonymous(target.policy)) return null;
+  throw queryExerciseUndeclared(name, 'no-actor');
+}
+
+/** Action's `everyDrawRefused`, for a read: the field no draw can fill, named and bound. */
+function queryDrawsRefused(name: string, schema: StandardSchemaV1): UltimateError {
+  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 UltimateError({
     code: 'X_CONTRACT_DRIFT',
-    cause: `query ${name}: its input schema refused every generated value, so the read was never exercised`,
-    fix: `${renderFixShellArg(name, '<name>')}.contract({ exercise: { actor, input: (drawn) => ({ ...drawn, field: '<a value the refinement accepts>' }) } })`,
+    cause:
+      gaps.length === 0
+        ? `query ${name}: its input schema refused every generated value, so the read was never exercised`
+        : `query ${name}: its input schema refused every generated value — no value can be generated for ${described.join(', ')} — so the read was never exercised`,
+    fix: `defineExercise({ ${renderExerciseKey(name)}: { input: ${input} } })   # in ${QUERY_EXERCISE_DECLARATIONS_FILE}`,
   });
 }
 
-/** A guarded read with no exercise said, or an opt-out with a blank reason. */
-export function queryExerciseUndeclared(name: string, blankReason: boolean): UltimateError {
+/** Why no exercise could run: action's four (`ExerciseUndeclaredWhy`), for a read. */
+export type QueryExerciseUndeclaredWhy = 'blank' | 'undeclared' | 'no-entry' | 'no-actor';
+
+/**
+ * A guarded read 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. Action's twin.
+ */
+export function queryExerciseUndeclared(
+  name: string,
+  why: QueryExerciseUndeclaredWhy,
+): UltimateError {
   const call = renderFixShellArg(name, '<name>');
+  const refuses = `query ${name} refuses an anonymous reader`;
   return new UltimateError({
     code: 'X_CONTRACT_EXERCISE_UNDECLARED',
-    cause: blankReason
-      ? `${name}.contract({ exercise: { off } }) gives a blank reason, so the skip is silent`
-      : `query ${name} refuses an anonymous reader and its .contract() names no actor to read as`,
-    fix: `${call}.contract({ exercise: { actor } }) — or ${call}.contract({ exercise: { off: '<why this read cannot run in a test>' } })`,
+    cause: queryUndeclaredCause(name, why, refuses),
+    fix: `defineExercise({ ${call}: { actor } })   # in ${QUERY_EXERCISE_DECLARATIONS_FILE}, then ${call}.contract({ exercise }) with that file's export — or { off: '<why this read 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 queryUndeclaredCause(
+  name: string,
+  why: QueryExerciseUndeclaredWhy,
+  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 ${QUERY_EXERCISE_DECLARATIONS_FILE} declares no entry for it, so no actor to read as is known`;
+  }
+  return `${refuses} and its .contract() names no actor to read as`;
+}

package/src/index.ts

@@ -120,6 +120,10 @@ export type {
   QueryExerciseReport,
 } from './exercise';
 export { exerciseQuery } from './exercise';
+export type {
+  QueryContractExercise,
+  QueryExerciseDeclarations,
+} from './exercise-declarations';
 /** The HTTP projection: `GET /_x/query/<kebab>`, the URL `client()` derives. */
 export { toQueryRoute } from './http';
 export type { QueryHttp } from './http-pin';