@classytic/arc-testkit 0.6.0 → 0.7.0

package/README.md

@@ -10,7 +10,7 @@ The ecosystem's contributor contract for the `@classytic/arc-*` module fleet: **
 npm i -D @classytic/arc-testkit mongodb-memory-server
 ```
 
-`mongoose` (>=9.4.1) is needed by `.`, `/pool`, `/mongo` and `/mongo-commands`; `/conformance` and `/story` need only `vitest` (>=3) and a booted arc app. `mongodb-memory-server` is imported lazily by the default database.
+`@classytic/arc` (>=2.49.0) is an optional peer: only `.` (`bootModuleApp`) imports it; the guards and stories take a booted app from the caller, and a client project that uses only the client drift guard installs neither arc nor mongoose. `mongoose` (>=9.11.4) is needed by `.`, `/pool`, `/mongo` and `/mongo-commands`; `/conformance` and `/story` need only `vitest` (>=4.1.11, tested on 4.1.11 and 5.0.5) and a booted arc app. `mongodb-memory-server` is imported lazily by the default database.
 
 ## Usage
 
@@ -47,6 +47,10 @@ Pass a `TestDatabaseFactory` (from `@classytic/arc/testing`) as `database`, for
 const t = await bootModuleApp(mods, { database: dbPool.factory });
 ```
 
+## Temp dirs of killed runs
+
+Every in-memory server writes a `mongo-mem-*` data dir. `mongoServerProvider` removes it on stop, after a failed start, and synchronously when the process exits without teardown. A run killed outright (task manager, a terminated worker) cannot clean up, so before its first server each process removes `mongo-mem-*` dirs that are older than `TEST_MONGO_SWEEP_HOURS` (default 6; `off` disables) and whose `mongod.lock` names no live process. Set `TEST_MONGO_TMPDIR` (for example `.tmp/mongo`) to keep the data dirs under one project-local dir instead of the system temp dir.
+
 ## API
 
 | Export | |
@@ -56,8 +60,8 @@ const t = await bootModuleApp(mods, { database: dbPool.factory });
 | `BootModuleAppOptions` | `{ replset?, database?, app?, actor?, ports? }` |
 | `ModulesInput`, `ModuleTestApp` | the modules argument and the boot result types |
 | `/pool` | `createTestDatabasePool`, `publishPoolServers` |
-| `/mongo` | `mongoServerProvider`, `safeWorkerCount`, `safePoolSize`, `awaitIndexBuilds`, `withDbName`, `cacheSizeGB`, `mongodMemoryArgs` |
-| `/mongo-commands`, `/mongo-explain` | `countCommands`, `assertConstantCommands`, `summarizeExplain`, `assertIndexServed` |
+| `/mongo` | `mongoServerProvider`, `safeWorkerCount`, `safePoolSize`, `awaitIndexBuilds`, `withDbName`, `cacheSizeGB`, `mongodMemoryArgs`, `sweepStaleMongoMemoryDirs`, `launchMongoMemory`, `stopOnProcessExit` |
+| `/mongo-commands`, `/mongo-explain` | `countCommands`, `assertConstantCommands`, `summarizeExplain`, `assertIndexServed`, `explainCaptured` |
 | `/conformance` | `check*` / `register*` for list envelope, route schemas, naming, OpenAPI, client drift, collection routes, error contract; `expectClean`, `injectCaller`, `fetchOpenApi`, `routeTable` |
 | `/story` | `describeStory`, `createCast`, `createStoryClock`, `createStoryAssertions`, `createEventLog`, `expectIdempotent`, `expectSweepsIdempotent` |
 
@@ -65,7 +69,7 @@ const t = await bootModuleApp(mods, { database: dbPool.factory });
 
 ```ts
 import { assertConstantCommands, countCommands } from '@classytic/arc-testkit/mongo-commands';
-import { assertIndexServed } from '@classytic/arc-testkit/mongo-explain';
+import { assertIndexServed, explainCaptured } from '@classytic/arc-testkit/mongo-explain';
 
 // What the driver sent (the connection needs `monitorCommands: true` — it refuses otherwise).
 const { total, byCollection } = await countCommands(conn, () => placeOrder(), { collections: ['orders'] });
@@ -73,6 +77,9 @@ const { total, byCollection } = await countCommands(conn, () => placeOrder(), {
 await assertConstantCommands(conn, (n) => reader.page(n), [5, 50]);
 // No COLLSCAN, an index scanned, optionally a named one and a docs-examined ceiling.
 assertIndexServed(await Model.find(filter).explain('executionStats'), { index: 'org_state', maxDocsExamined: 40 });
+// A query built inside a repository or plugin: capture what it sent, explain exactly that.
+const { explain } = await explainCaptured(conn, () => service.claim(now), { collection: 'timers', commands: ['findAndModify'] });
+assertIndexServed(explain, { index: 'state_due', maxDocsExamined: 6 });
 ```
 
 ## Conformance guards and story kit (opt-in, need `vitest`)
@@ -88,7 +95,21 @@ registerOpenApiGuard({ spec: () => fetchOpenApi(admin), app: () => t.app, anonym
 ```
 
 Every guard is also a `check*` function returning the problems found (empty when green). Exception
-lists fail when an entry matches nothing. `@classytic/arc-testkit/story` holds `describeStory`,
+lists fail when an entry matches nothing.
+
+The refusal guard calls every mutating route as an anonymous and a signed-in caller with no grant; each call must be
+refused AND leave your state snapshot unchanged. arc validates an action body before the verb's permission, so give
+it a body per verb; exclusions can differ per caller:
+
+```ts
+registerRefusalDoesNoWorkGuard({
+  name: 'no role: every write and every verb is refused',
+  app: () => t.app, anonymous: () => injectCaller(t.app), unprivileged: () => injectCaller(t.app, noRole), snapshot,
+  paramValue: ({ resource }) => (resource === 'ticket' ? seeded.ticketId : '000000000000000000000001'),
+  actionBodies: { 'ticket.close': { reason: 'Sample reason' }, 'ticket.reopen': {} },
+  exclude: { anonymous: PUBLIC_WRITES, unprivileged: { ...PUBLIC_WRITES, ...SELF_SERVICE } },
+});
+``` `@classytic/arc-testkit/story` holds `describeStory`,
 `createCast`, `createStoryClock`, `createStoryAssertions` (outbox / events / feed / mail / audit through
 readers you inject) and `expectIdempotent`; see the module docs.
 

package/dist/conformance.d.mts

@@ -18,12 +18,16 @@ interface AppLike {
     includeHooks?: boolean;
   }): string;
 }
-/** `app.arc.registry.getAll()` entries, as far as the schema guard reads them. */
+/** `app.arc.registry.getAll()` entries, as far as the guards read them. */
 interface RegistryEntryLike {
   name: string;
+  /** The resource's route prefix (`/widgets`); the app may mount it under a further prefix. */
+  prefix?: string;
+  /** `id: false` mounts the verb on `POST <prefix>/action` instead of `POST <prefix>/:id/action`. */
   actions?: Array<{
     name: string;
     schema?: unknown;
+    id?: boolean;
   }>;
   customRoutes?: Array<{
     method: string;
@@ -50,21 +54,21 @@ interface InjectCaller extends Caller {
   delete(path: string): Promise<Reply>;
 }
 /** A `Caller` over `app.inject`, JSON in and out, sending `headers` (an auth token) with every request. */
-declare function injectCaller(app: AppLike, headers?: Record<string, string>): InjectCaller;
+export declare function injectCaller(app: AppLike, headers?: Record<string, string>): InjectCaller;
 interface RouteRow {
   path: string;
   methods: string[];
 }
 /** The app's route table as `{ path, methods }` rows, read from Fastify's radix-tree dump. */
-declare function routeTable(app: Pick<AppLike, "printRoutes">): RouteRow[];
+export declare function routeTable(app: Pick<AppLike, "printRoutes">): RouteRow[];
 /** `/a/{id}/b`, `/a/:id|:other/b` and `/a/:id/b/` are one shape: `/a/:x/b`. */
-declare function shapeOf(path: string): string;
+export declare function shapeOf(path: string): string;
 /** An exception list: bare keys, or `key -> reason`. */
 type Exceptions = Iterable<string> | Readonly<Record<string, string>>;
 /** Fails with the problems listed, one per line; passes when there are none. Use it with the `check*` functions inside a host's own tests. */
-declare function expectClean(what: string, problems: readonly string[]): void;
-declare const OPENAPI_METHODS: readonly ["get", "put", "post", "delete", "patch"];
-interface OpenApiOperation {
+export declare function expectClean(what: string, problems: readonly string[]): void;
+export declare const OPENAPI_METHODS: readonly ["get", "put", "post", "delete", "patch"];
+export interface OpenApiOperation {
   [extension: string]: unknown;
   security?: unknown[];
   requestBody?: {
@@ -78,7 +82,7 @@ interface OpenApiOperation {
     }>;
   }>;
 }
-interface OpenApiSchema {
+export interface OpenApiSchema {
   $ref?: string;
   type?: string;
   properties?: Record<string, OpenApiSchema>;
@@ -86,9 +90,10 @@ interface OpenApiSchema {
   allOf?: OpenApiSchema[];
   anyOf?: OpenApiSchema[];
   enum?: unknown[];
+  const?: unknown;
   items?: OpenApiSchema;
 }
-interface OpenApiDocument {
+export interface OpenApiDocument {
   openapi?: string;
   security?: unknown[];
   paths: Record<string, Record<string, OpenApiOperation>>;
@@ -97,13 +102,13 @@ interface OpenApiDocument {
   };
 }
 /** Read the document from the running app (default `/openapi.json`). */
-declare function fetchOpenApi(caller: Caller, path?: string): Promise<OpenApiDocument>;
-interface PublicOperation {
+export declare function fetchOpenApi(caller: Caller, path?: string): Promise<OpenApiDocument>;
+export interface PublicOperation {
   /** A path template as it appears in the document, or a test for it. */
   path: string | RegExp | ((path: string) => boolean);
   why: string;
 }
-interface OpenApiOptions {
+export interface OpenApiOptions {
   spec: Source<OpenApiDocument>;
   /** The booted app: enables the "names every route" check. */
   app?: Source<AppLike>;
@@ -125,74 +130,84 @@ interface OpenApiOptions {
   secretPatterns?: readonly RegExp[];
 }
 /** The document is OpenAPI 3, prefixed, and has no trailing-slash path. */
-declare function checkOpenApiShape(opts: OpenApiOptions): Promise<string[]>;
+export declare function checkOpenApiShape(opts: OpenApiOptions): Promise<string[]>;
 /** Every route in the table is documented (once, in its bare form). */
-declare function checkRoutesDocumented(opts: OpenApiOptions): Promise<string[]>;
+export declare function checkRoutesDocumented(opts: OpenApiOptions): Promise<string[]>;
 /**
  * Every operation requires a security scheme (its own `security`, else the document's), except the
  * public list; a public rule that matches no operation fails as stale.
  */
-declare function checkSecurity(opts: OpenApiOptions): Promise<string[]>;
+export declare function checkSecurity(opts: OpenApiOptions): Promise<string[]>;
 /** An anonymous GET of every documented, protected, parameterless path is refused with 401. */
-declare function checkAnonymousRefused(opts: OpenApiOptions, expected?: number): Promise<string[]>;
+export declare function checkAnonymousRefused(opts: OpenApiOptions, expected?: number): Promise<string[]>;
 /** The serialised document carries no configuration value. */
-declare function checkNoSecrets(opts: OpenApiOptions): Promise<string[]>;
+export declare function checkNoSecrets(opts: OpenApiOptions): Promise<string[]>;
 /** Registers the OpenAPI guards as vitest tests (the optional ones only when their input is given). */
-declare function registerOpenApiGuard(opts: OpenApiOptions): void;
-interface ClientRoute {
+export declare function registerOpenApiGuard(opts: OpenApiOptions): void;
+export interface ClientRoute {
   method: string;
   path: string;
   /** Where the client emits it, named in the failure. */
   source?: string;
 }
 /** Spec path templates as matchers: `/api/x/{id}/y` accepts `/api/x/anything/y` and `/api/x/:id/y`. */
-declare function specMatcher(spec: OpenApiDocument): (method: string, path: string) => string | undefined;
+export declare function specMatcher(spec: OpenApiDocument): (method: string, path: string) => string | undefined;
 /** Client routes the document does not have (sorted, deduplicated, with their source). */
-declare function missingClientRoutes(spec: OpenApiDocument, routes: readonly ClientRoute[]): string[];
-declare function resolveRef(spec: OpenApiDocument, schema: OpenApiSchema | undefined): OpenApiSchema | undefined;
+export declare function missingClientRoutes(spec: OpenApiDocument, routes: readonly ClientRoute[]): string[];
+export declare function resolveRef(spec: OpenApiDocument, schema: OpenApiSchema | undefined): OpenApiSchema | undefined;
 /** Every property name a schema offers, through refs and unions. */
-declare function propertyNames(spec: OpenApiDocument, schema: OpenApiSchema | undefined, depth?: number): Set<string>;
-interface BodyFieldCheck {
+export declare function propertyNames(spec: OpenApiDocument, schema: OpenApiSchema | undefined, depth?: number): Set<string>;
+/**
+ * Every literal value a schema accepts: `enum` and `const` at its root, through refs and unions,
+ * and on its top-level properties (an action router's `action` discriminator).
+ */
+export declare function schemaValues(spec: OpenApiDocument, schema: OpenApiSchema | undefined, depth?: number): Set<unknown>;
+export interface BodyFieldCheck {
   name?: string;
   method: string;
   /** The path template as the document spells it. */
   path: string;
   /** Fields the client reads or sends. */
   fields: readonly string[];
+  /**
+   * Literal values the client sends in this body (an action router's verbs): each must be an
+   * `enum` / `const` value the schema declares (`schemaValues`). Default: none checked.
+   */
+  values?: readonly unknown[];
   /** Which body to read. Default: `request`. */
   in?: "request" | "response";
   /** Response status to read. Default: 200. */
   status?: string;
 }
-declare function bodyFieldProblems(spec: OpenApiDocument, check: BodyFieldCheck): string[];
-interface ClientDriftOptions {
+export declare function bodyFieldProblems(spec: OpenApiDocument, check: BodyFieldCheck): string[];
+export interface ClientDriftOptions {
   spec: Source<OpenApiDocument>;
   routes: Source<readonly ClientRoute[]>;
   bodyFields?: readonly BodyFieldCheck[];
   /** At least this many client routes must be supplied (guards against an empty probe). Default: 1. */
   minRoutes?: number;
 }
-declare function checkClientDrift(opts: ClientDriftOptions): Promise<string[]>;
+export declare function checkClientDrift(opts: ClientDriftOptions): Promise<string[]>;
 /** Registers the drift guard as vitest tests. */
-declare function registerClientDriftGuard(opts: ClientDriftOptions): void;
+export declare function registerClientDriftGuard(opts: ClientDriftOptions): void;
 /** Write the document to `file` (the server side of the dump: `npm run openapi:dump`). */
-declare function dumpOpenApi(spec: OpenApiDocument, file: string): void;
+export declare function dumpOpenApi(spec: OpenApiDocument, file: string): void;
 /**
  * Read a dumped document. Throws when the dump is missing or older than any `.ts` file under
  * `sources`, so a stale document can never pass for the current API. `regenerate` names the command
  * in the message.
  */
-declare function loadOpenApiDump(file: string, opts?: {
+export declare function loadOpenApiDump(file: string, opts?: {
   sources?: readonly string[];
   regenerate?: string;
 }): OpenApiDocument;
-interface CollectionRoute {
+export interface CollectionRoute {
   /** The bare collection path, e.g. `/api/things`. */
   path: string;
   /** The verbs the client sends to it. */
   methods: readonly string[];
 }
-interface CollectionRoutesOptions {
+export interface CollectionRoutesOptions {
   app: Source<AppLike>;
   collections: readonly CollectionRoute[];
   /** Bare GET paths that must answer 200 for `caller` (and the trailing-slash form is not what is registered). */
@@ -201,11 +216,11 @@ interface CollectionRoutesOptions {
     paths: readonly string[];
   };
 }
-declare function checkCollectionRoutes(opts: CollectionRoutesOptions): Promise<string[]>;
+export declare function checkCollectionRoutes(opts: CollectionRoutesOptions): Promise<string[]>;
 /** Registers the collection route guard as a vitest test. */
-declare function registerCollectionRoutesGuard(opts: CollectionRoutesOptions): void;
-type ErrorClass = "validation" | "unauthorized" | "forbidden" | "notFound" | "unknownRoute" | "conflict" | "duplicateKey";
-interface ErrorProbe {
+export declare function registerCollectionRoutesGuard(opts: CollectionRoutesOptions): void;
+export type ErrorClass = "validation" | "unauthorized" | "forbidden" | "notFound" | "unknownRoute" | "conflict" | "duplicateKey";
+export interface ErrorProbe {
   /** Send the request that fails this way. */
   provoke: () => Promise<Reply>;
   /** Default: 400 validation, 401, 403, 404, 409. */
@@ -217,7 +232,7 @@ interface ErrorProbe {
   /** Every `details[].code` equals this. Default: `duplicate_key` for duplicateKey. */
   detailCode?: string;
 }
-interface ErrorContractOptions {
+export interface ErrorContractOptions {
   probes: Partial<Record<ErrorClass, ErrorProbe | readonly ErrorProbe[]>>;
   /** An authenticated caller for the built-in `unknownRoute` probe (so a 404 is not a 401). */
   caller?: Source<Caller>;
@@ -226,25 +241,25 @@ interface ErrorContractOptions {
   /** Keys allowed on the body. Default: the ErrorContract keys. */
   allowedKeys?: readonly string[];
 }
-declare const ERROR_CLASSES: readonly ErrorClass[];
+export declare const ERROR_CLASSES: readonly ErrorClass[];
 /** The reasons a reply is not the expected `ErrorContract` (empty: it is one). */
-declare function errorContractProblems(reply: Reply, expected: {
+export declare function errorContractProblems(reply: Reply, expected: {
   status: number;
   code?: string | RegExp;
   details?: "some" | "none";
   detailCode?: string;
 }, allowedKeys?: readonly string[]): string[];
 /** Throws unless the reply is the expected `ErrorContract`; returns the body. */
-declare function expectErrorContract(reply: Reply, expected: {
+export declare function expectErrorContract(reply: Reply, expected: {
   status: number;
   code?: string | RegExp;
   details?: "some" | "none";
   detailCode?: string;
 }): Record<string, unknown>;
-declare function checkErrorContracts(opts: ErrorContractOptions): Promise<string[]>;
+export declare function checkErrorContracts(opts: ErrorContractOptions): Promise<string[]>;
 /** Registers the error contract guard as vitest tests. */
-declare function registerErrorContractGuard(opts: ErrorContractOptions): void;
-interface FilterDeclaration {
+export declare function registerErrorContractGuard(opts: ErrorContractOptions): void;
+export interface FilterDeclaration {
   /** The list route, concrete or a template (`/api/items`). */
   route: string;
   /** Filters the screen sends. `op` defaults to `eq`. */
@@ -257,14 +272,14 @@ interface FilterDeclaration {
   /** Sort fields the screen offers (`-name` and `name` are the same field). */
   sorts?: readonly string[];
 }
-interface FilterDeclarationsOptions {
+export interface FilterDeclarationsOptions {
   spec: Source<OpenApiDocument>;
   declarations: Source<readonly FilterDeclaration[]>;
 }
-declare function checkFilterDeclarations(opts: FilterDeclarationsOptions): Promise<string[]>;
+export declare function checkFilterDeclarations(opts: FilterDeclarationsOptions): Promise<string[]>;
 /** Registers the declaration check as a vitest test. */
-declare function registerFilterDeclarationsGuard(opts: FilterDeclarationsOptions): void;
-interface ListEnvelopeOptions {
+export declare function registerFilterDeclarationsGuard(opts: FilterDeclarationsOptions): void;
+export interface ListEnvelopeOptions {
   app: Source<AppLike>;
   /** An identity allowed to read every list (an admin). */
   caller: Source<Caller>;
@@ -286,25 +301,25 @@ interface ListEnvelopeOptions {
   expectLists?: readonly string[];
 }
 /** The reasons a body is not a canonical list (empty: it is one). */
-declare function listEnvelopeProblems(body: unknown, methods?: readonly string[], forbidden?: readonly string[]): string[];
-interface ListEnvelopeResult {
+export declare function listEnvelopeProblems(body: unknown, methods?: readonly string[], forbidden?: readonly string[]): string[];
+export interface ListEnvelopeResult {
   problems: string[];
   /** Paths that answered a list and were checked. */
   lists: string[];
   /** Static GET paths considered (after prefix and skip). */
   probed: string[];
 }
-declare function checkListEnvelopes(opts: ListEnvelopeOptions): Promise<ListEnvelopeResult>;
+export declare function checkListEnvelopes(opts: ListEnvelopeOptions): Promise<ListEnvelopeResult>;
 /** Registers the list envelope guard as vitest tests. */
-declare function registerListEnvelopeGuard(opts: ListEnvelopeOptions): void;
-interface PathRule {
+export declare function registerListEnvelopeGuard(opts: ListEnvelopeOptions): void;
+export interface PathRule {
   name: string;
   /** Routes whose path matches belong to the family. */
   match: RegExp;
   /** The complete `METHOD /path` set the family may have. */
   allowed: readonly string[];
 }
-interface NamingOptions {
+export interface NamingOptions {
   app: Source<AppLike>;
   /** Action verbs must match. Default: camelCase. */
   verbPattern?: RegExp;
@@ -317,16 +332,43 @@ interface NamingOptions {
   pathRules?: readonly PathRule[];
   forbiddenPaths?: readonly RegExp[];
 }
-declare function checkNaming(opts: NamingOptions): Promise<string[]>;
+export declare function checkNaming(opts: NamingOptions): Promise<string[]>;
 /** Registers the naming guard as vitest tests. */
-declare function registerNamingGuard(opts: NamingOptions): void;
-interface MutatingRoute {
+export declare function registerNamingGuard(opts: NamingOptions): void;
+export interface MutatingRoute {
   method: string;
   /** A concrete path (no `:param`); give `body` when the route needs one to reach its gate. */
   path: string;
   body?: unknown;
 }
-interface RefusalOptions {
+/** The two callers the guard sends requests as. */
+export type RefusalCaller = "anonymous" | "unprivileged";
+/** Exclusions per caller: a route one caller may legitimately use is still checked for the other. */
+export interface CallerExceptions {
+  readonly anonymous?: Exceptions;
+  readonly unprivileged?: Exceptions;
+}
+/** What an `actionBodies` factory is told about the call it builds a body for. */
+export interface ActionBodyContext {
+  /** Registry name of the resource (`app.arc.registry`). */
+  readonly resource: string;
+  /** The action verb. */
+  readonly action: string;
+  readonly caller: RefusalCaller;
+  /** The concrete path the body is sent to. */
+  readonly path: string;
+}
+/** A verb's extra body fields (`action` is added by the guard), or a factory called once per call. */
+export type ActionBodySource = Readonly<Record<string, unknown>> | ((ctx: ActionBodyContext) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>);
+/** What a `paramValue` function is told about the derived route. */
+export interface ParamValueContext {
+  readonly method: string;
+  /** The route-table path, `:params` and all. */
+  readonly path: string;
+  /** Registry name of the resource whose prefix the path carries (longest match), when the app has arc's registry. */
+  readonly resource: string | undefined;
+}
+export interface RefusalOptions {
   /** The booted app. Required unless `routes` is given. */
   app?: Source<AppLike>;
   /** Authenticated, but holding none of the privileges the mutating routes require. */
@@ -343,22 +385,39 @@ interface RefusalOptions {
   routes?: Source<readonly MutatingRoute[]>;
   /** Only table routes whose path starts with this. */
   prefix?: string;
-  /** `METHOD /path` keys (as the route table spells them) that legitimately accept the caller, with the reason. */
-  exclude?: Exceptions;
-  /** Value put in every `:param` of a derived path. Default: a 24-hex id. */
-  paramValue?: string;
+  /**
+   * Calls that legitimately accept the caller, with the reason: `METHOD /path` keys (as the route
+   * table spells them), or `resource.verb` for one action verb (with `actionBodies`). One list
+   * excludes for both callers; `{ anonymous, unprivileged }` excludes per caller. An exclusion that
+   * matches nothing is reported as stale.
+   */
+  exclude?: Exceptions | CallerExceptions;
+  /**
+   * Value put in every `:param` of a derived path. Default: a 24-hex id. A function picks one per
+   * route, e.g. a seeded row's id for a resource whose lookup would otherwise answer 404 before the gate.
+   */
+  paramValue?: string | ((ctx: ParamValueContext) => string | Promise<string>);
+  /**
+   * A body per arc action verb, keyed `resource.verb` (registry name and verb). When given, every
+   * derived action route (`POST …/:id/action`, `POST …/action`) is called once per verb it mounts,
+   * with `{ ...body, action: verb }`. A registered verb with no body (and no exclusion) is reported,
+   * and so is a body for a verb that is not checked. Needs `app` (booted by arc).
+   */
+  actionBodies?: Readonly<Record<string, ActionBodySource>>;
   /** Statuses that count as a refusal. Default: 401 and 403. */
   refusedStatuses?: readonly number[];
   /** Milliseconds to let a late handler finish before the second snapshot. Default: 25. */
   settleMs?: number;
-  /** At least this many routes must be checked. Default: 1. */
+  /** At least this many calls (routes, or route and verb) must be checked. Default: 1. */
   minRoutes?: number;
+  /** Title of the test `registerRefusalDoesNoWorkGuard` registers. */
+  name?: string;
 }
 /** Problems found; empty when every refusal answered and left the snapshot unchanged. */
-declare function checkRefusalDoesNoWork(opts: RefusalOptions): Promise<string[]>;
-/** Registers the refusal guard as a vitest test. */
-declare function registerRefusalDoesNoWorkGuard(opts: RefusalOptions): void;
-interface RouteSchemaOptions {
+export declare function checkRefusalDoesNoWork(opts: RefusalOptions): Promise<string[]>;
+/** Registers the refusal guard as a vitest test (title: `name`, or the default). */
+export declare function registerRefusalDoesNoWorkGuard(opts: RefusalOptions): void;
+export interface RouteSchemaOptions {
   app: Source<AppLike>;
   /** `<resource>.<action>` keys that need no schema (package-mounted actions), with the reason. */
   actionExceptions?: Exceptions;
@@ -369,12 +428,12 @@ interface RouteSchemaOptions {
   /** At least this many actions must exist (guards against reading an empty registry). Default: 1. */
   minActions?: number;
 }
-interface RouteSchemaResult {
+export interface RouteSchemaResult {
   problems: string[];
   actions: number;
   routes: number;
 }
-declare function checkRouteSchemas(opts: RouteSchemaOptions): Promise<RouteSchemaResult>;
+export declare function checkRouteSchemas(opts: RouteSchemaOptions): Promise<RouteSchemaResult>;
 /** Registers the schema guard as vitest tests. */
-declare function registerRouteSchemaGuard(opts: RouteSchemaOptions): void;
-export { type AppLike, BodyFieldCheck, type Caller, ClientDriftOptions, ClientRoute, CollectionRoute, CollectionRoutesOptions, ERROR_CLASSES, ErrorClass, ErrorContractOptions, ErrorProbe, type Exceptions, FilterDeclaration, FilterDeclarationsOptions, type InjectCaller, ListEnvelopeOptions, ListEnvelopeResult, MutatingRoute, NamingOptions, OPENAPI_METHODS, OpenApiDocument, OpenApiOperation, OpenApiOptions, OpenApiSchema, PathRule, PublicOperation, RefusalOptions, type RegistryEntryLike, type Reply, type RouteRow, RouteSchemaOptions, RouteSchemaResult, type Source, bodyFieldProblems, checkAnonymousRefused, checkClientDrift, checkCollectionRoutes, checkErrorContracts, checkFilterDeclarations, checkListEnvelopes, checkNaming, checkNoSecrets, checkOpenApiShape, checkRefusalDoesNoWork, checkRouteSchemas, checkRoutesDocumented, checkSecurity, dumpOpenApi, errorContractProblems, expectClean, expectErrorContract, fetchOpenApi, injectCaller, listEnvelopeProblems, loadOpenApiDump, missingClientRoutes, propertyNames, registerClientDriftGuard, registerCollectionRoutesGuard, registerErrorContractGuard, registerFilterDeclarationsGuard, registerListEnvelopeGuard, registerNamingGuard, registerOpenApiGuard, registerRefusalDoesNoWorkGuard, registerRouteSchemaGuard, resolveRef, routeTable, shapeOf, specMatcher };
+export declare function registerRouteSchemaGuard(opts: RouteSchemaOptions): void;
+export type { AppLike, Caller, Exceptions, InjectCaller, RegistryEntryLike, Reply, RouteRow, Source };