@classytic/arc-testkit 0.5.0 → 0.7.0

package/README.md

@@ -7,10 +7,10 @@ The ecosystem's contributor contract for the `@classytic/arc-*` module fleet: **
 ## Install
 
 ```bash
-npm i -D @classytic/arc-testkit @classytic/mongokit mongodb-memory-server
+npm i -D @classytic/arc-testkit mongodb-memory-server
 ```
 
-`@classytic/mongokit` + `mongodb-memory-server` are **optional peers** — needed only for the default backend, and dynamically imported so they never enter a production bundle. Pass your own `backend` to skip them entirely.
+`@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
 
@@ -39,32 +39,37 @@ const t = await bootModuleApp(({ connection }) => [createReservationModule({ con
   { replset: true });
 ```
 
-## Bring your own backend
+## Bring your own database
 
-The default backend is `mongoMemoryBackend()` from `@classytic/mongokit/testkit`. Override it to point at a shared server, a real Atlas cluster, or a different kit's backend — anything that satisfies the `TestBackend` shape (`setup() → { ctx: { connection, uri }, teardown }`):
+Pass a `TestDatabaseFactory` (from `@classytic/arc/testing`) as `database`, for example a pooled one from `createTestDatabasePool(mongoServerProvider({ mongoose })).factory` (`/pool`, `/mongo`):
 
 ```ts
-import { mongoMemoryBackend } from '@classytic/mongokit/testkit';
-
-const t = await bootModuleApp(mods, {
-  backend: mongoMemoryBackend({ uri: process.env.ATLAS_TEST_URI }), // real cluster
-});
+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 | |
 | --- | --- |
-| `bootModuleApp(modules, options?)` | boot arc around modules on a backend; returns `{ app, connection, mongoUri, close }` |
-| `TestBackend` | the backend seam — `setup() → { ctx: { connection, uri }, teardown }` |
+| `bootModuleApp(modules, options?)` | boot arc around modules; returns `{ app, uri, connection, exports(name), close }` |
 | `TestkitContext` | what a module factory receives: `{ connection, mongoUri }` |
-| `BootModuleAppOptions` | `{ replset?, app?, backend? }` |
+| `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`, `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` |
 
 ## Cost and plan assertions (MongoDB)
 
 ```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'] });
@@ -72,8 +77,42 @@ 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`)
+
+```ts
+// tests/conformance.test.ts — one call per guard, parameters are yours
+import { fetchOpenApi, registerListEnvelopeGuard, registerOpenApiGuard, registerRouteSchemaGuard } from '@classytic/arc-testkit/conformance';
+
+registerListEnvelopeGuard({ app: () => t.app, caller: () => admin, prefix: '/api', notLists: { '/api/me': 'one document' } });
+registerRouteSchemaGuard({ app: () => t.app, actionExceptions: { 'media.signed-url': 'package-mounted' } });
+registerOpenApiGuard({ spec: () => fetchOpenApi(admin), app: () => t.app, anonymous: () => anon, prefix: '/api',
+  publicOperations: [{ path: '/api/auth/sign-in', why: 'sign-in' }] });
 ```
 
+Every guard is also a `check*` function returning the problems found (empty when green). Exception
+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.
+
 ## License
 
 MIT © Classytic

package/dist/conformance.d.mts

@@ -0,0 +1,439 @@
+/** A lazily supplied value: build it in `beforeAll`, hand the suite a getter. */
+type Source<T> = T | (() => T | Promise<T>);
+interface InjectResponse {
+  statusCode: number;
+  body: string;
+  headers: Record<string, unknown>;
+}
+/** What the suites read of a booted arc app. Fastify's instance satisfies it. */
+interface AppLike {
+  inject(opts: {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    payload?: unknown;
+  }): PromiseLike<InjectResponse>;
+  printRoutes(opts?: {
+    commonPrefix?: boolean;
+    includeHooks?: boolean;
+  }): string;
+}
+/** `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;
+    path: string;
+    schema?: {
+      body?: unknown;
+    };
+  }>;
+}
+interface Reply {
+  status: number;
+  body: unknown;
+  headers?: Record<string, unknown>;
+}
+/** Sends requests as one identity. A host test client (`admin.get(path)`) already fits. */
+interface Caller {
+  get(path: string): Promise<Reply>;
+}
+interface InjectCaller extends Caller {
+  request(method: string, path: string, body?: unknown): Promise<Reply>;
+  post(path: string, body?: unknown): Promise<Reply>;
+  put(path: string, body?: unknown): Promise<Reply>;
+  patch(path: string, body?: unknown): Promise<Reply>;
+  delete(path: string): Promise<Reply>;
+}
+/** A `Caller` over `app.inject`, JSON in and out, sending `headers` (an auth token) with every request. */
+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. */
+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`. */
+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. */
+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?: {
+    content?: Record<string, {
+      schema?: OpenApiSchema;
+    }>;
+  };
+  responses?: Record<string, {
+    content?: Record<string, {
+      schema?: OpenApiSchema;
+    }>;
+  }>;
+}
+export interface OpenApiSchema {
+  $ref?: string;
+  type?: string;
+  properties?: Record<string, OpenApiSchema>;
+  oneOf?: OpenApiSchema[];
+  allOf?: OpenApiSchema[];
+  anyOf?: OpenApiSchema[];
+  enum?: unknown[];
+  const?: unknown;
+  items?: OpenApiSchema;
+}
+export interface OpenApiDocument {
+  openapi?: string;
+  security?: unknown[];
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  components?: {
+    schemas?: Record<string, OpenApiSchema>;
+  };
+}
+/** Read the document from the running app (default `/openapi.json`). */
+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;
+}
+export interface OpenApiOptions {
+  spec: Source<OpenApiDocument>;
+  /** The booted app: enables the "names every route" check. */
+  app?: Source<AppLike>;
+  /** An unauthenticated caller: enables the "protected GETs refuse anonymous" check. */
+  anonymous?: Source<Caller>;
+  /** Every documented path starts with this, except the public ones. */
+  prefix?: string;
+  /** Operations that are public on purpose; each must still match something. */
+  publicOperations?: readonly PublicOperation[];
+  /** Routes the document does not have to name (matched on the route-table path). */
+  undocumented?: RegExp;
+  /** Document paths never probed anonymously. Default: parameterised paths and `/stream`. */
+  skipAnonymous?: RegExp;
+  /** At least this many operations must be documented. Default: 1. */
+  minOperations?: number;
+  /** Configuration values (secrets, connection strings) that must not appear in the document; ignored under 6 characters. */
+  secretValues?: Source<readonly (string | undefined)[]>;
+  /** Patterns that must not match the serialised document. Default: mongodb and redis URLs. */
+  secretPatterns?: readonly RegExp[];
+}
+/** The document is OpenAPI 3, prefixed, and has no trailing-slash path. */
+export declare function checkOpenApiShape(opts: OpenApiOptions): Promise<string[]>;
+/** Every route in the table is documented (once, in its bare form). */
+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.
+ */
+export declare function checkSecurity(opts: OpenApiOptions): Promise<string[]>;
+/** An anonymous GET of every documented, protected, parameterless path is refused with 401. */
+export declare function checkAnonymousRefused(opts: OpenApiOptions, expected?: number): Promise<string[]>;
+/** The serialised document carries no configuration value. */
+export declare function checkNoSecrets(opts: OpenApiOptions): Promise<string[]>;
+/** Registers the OpenAPI guards as vitest tests (the optional ones only when their input is given). */
+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`. */
+export declare function specMatcher(spec: OpenApiDocument): (method: string, path: string) => string | undefined;
+/** Client routes the document does not have (sorted, deduplicated, with their source). */
+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. */
+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;
+}
+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;
+}
+export declare function checkClientDrift(opts: ClientDriftOptions): Promise<string[]>;
+/** Registers the drift guard as vitest tests. */
+export declare function registerClientDriftGuard(opts: ClientDriftOptions): void;
+/** Write the document to `file` (the server side of the dump: `npm run openapi:dump`). */
+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.
+ */
+export declare function loadOpenApiDump(file: string, opts?: {
+  sources?: readonly string[];
+  regenerate?: string;
+}): OpenApiDocument;
+export interface CollectionRoute {
+  /** The bare collection path, e.g. `/api/things`. */
+  path: string;
+  /** The verbs the client sends to it. */
+  methods: readonly string[];
+}
+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). */
+  served?: {
+    caller: Source<Caller>;
+    paths: readonly string[];
+  };
+}
+export declare function checkCollectionRoutes(opts: CollectionRoutesOptions): Promise<string[]>;
+/** Registers the collection route guard as a vitest test. */
+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. */
+  status?: number;
+  /** The exact `code`, or a test for it. Default: any non-empty string. */
+  code?: string | RegExp;
+  /** `some`: `details` is a non-empty array. `none`: absent. Default: some for validation and duplicateKey. */
+  details?: "some" | "none";
+  /** Every `details[].code` equals this. Default: `duplicate_key` for duplicateKey. */
+  detailCode?: string;
+}
+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>;
+  /** Every class listed here must have a probe. Default: all seven. */
+  require?: readonly ErrorClass[];
+  /** Keys allowed on the body. Default: the ErrorContract keys. */
+  allowedKeys?: readonly string[];
+}
+export declare const ERROR_CLASSES: readonly ErrorClass[];
+/** The reasons a reply is not the expected `ErrorContract` (empty: it is one). */
+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. */
+export declare function expectErrorContract(reply: Reply, expected: {
+  status: number;
+  code?: string | RegExp;
+  details?: "some" | "none";
+  detailCode?: string;
+}): Record<string, unknown>;
+export declare function checkErrorContracts(opts: ErrorContractOptions): Promise<string[]>;
+/** Registers the error contract guard as vitest tests. */
+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`. */
+  filters?: readonly {
+    queryField: string;
+    op?: string;
+  }[];
+  /** The screen sends free-text search. */
+  search?: boolean;
+  /** Sort fields the screen offers (`-name` and `name` are the same field). */
+  sorts?: readonly string[];
+}
+export interface FilterDeclarationsOptions {
+  spec: Source<OpenApiDocument>;
+  declarations: Source<readonly FilterDeclaration[]>;
+}
+export declare function checkFilterDeclarations(opts: FilterDeclarationsOptions): Promise<string[]>;
+/** Registers the declaration check as a vitest test. */
+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>;
+  /** Only GET routes under this prefix are probed. Default: all. */
+  prefix?: string;
+  /** Static GET paths that do not answer a list (single documents, tables, probes), with the reason. */
+  notLists?: Exceptions;
+  /** Paths that answer their own shape (package-owned routes), with the reason. */
+  customShapes?: Exceptions;
+  /** GET paths never probed (streams, downloads). Default: `/(stream|export|content|download)(/|$)`. */
+  skip?: RegExp;
+  /** Keys a list never carries beside `data`. */
+  forbiddenKeys?: readonly string[];
+  /** Page kinds accepted when a body carries `method`. Default: offset and keyset. */
+  methods?: readonly ("offset" | "keyset")[];
+  /** At least this many routes must be probed. Default: 1. */
+  minRoutes?: number;
+  /** Lists that must be among the checked ones (guards against a probe silently skipping them). */
+  expectLists?: readonly string[];
+}
+/** The reasons a body is not a canonical list (empty: it is one). */
+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[];
+}
+export declare function checkListEnvelopes(opts: ListEnvelopeOptions): Promise<ListEnvelopeResult>;
+/** Registers the list envelope guard as vitest tests. */
+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[];
+}
+export interface NamingOptions {
+  app: Source<AppLike>;
+  /** Action verbs must match. Default: camelCase. */
+  verbPattern?: RegExp;
+  /** Verbs owned by packages the host cannot change, with the reason. */
+  exemptVerbs?: Exceptions;
+  /** Verbs that must exist (guards against reading an empty registry). */
+  requiredVerbs?: readonly string[];
+  /** At least this many verbs must exist. Default: 1. */
+  minVerbs?: number;
+  pathRules?: readonly PathRule[];
+  forbiddenPaths?: readonly RegExp[];
+}
+export declare function checkNaming(opts: NamingOptions): Promise<string[]>;
+/** Registers the naming guard as vitest tests. */
+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;
+}
+/** 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. */
+  unprivileged?: Source<InjectCaller>;
+  /** No credentials. */
+  anonymous?: Source<InjectCaller>;
+  /**
+   * The host's state fingerprint: anything JSON-like that changes when a handler did work (row
+   * counts, a state machine's phase, an outbox length). Compared with deep equality, before and
+   * after every call.
+   */
+  snapshot: () => unknown | Promise<unknown>;
+  /** The routes to call. Default: every POST/PUT/PATCH/DELETE in the route table. */
+  routes?: Source<readonly MutatingRoute[]>;
+  /** Only table routes whose path starts with this. */
+  prefix?: 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 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. */
+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;
+  /** `<resource> <METHOD> <path>` keys of body-bearing routes that need no body schema, with the reason. */
+  routeExceptions?: Exceptions;
+  /** HTTP methods that must declare a body. Default: POST, PUT, PATCH. */
+  bodyMethods?: readonly string[];
+  /** At least this many actions must exist (guards against reading an empty registry). Default: 1. */
+  minActions?: number;
+}
+export interface RouteSchemaResult {
+  problems: string[];
+  actions: number;
+  routes: number;
+}
+export declare function checkRouteSchemas(opts: RouteSchemaOptions): Promise<RouteSchemaResult>;
+/** Registers the schema guard as vitest tests. */
+export declare function registerRouteSchemaGuard(opts: RouteSchemaOptions): void;
+export type { AppLike, Caller, Exceptions, InjectCaller, RegistryEntryLike, Reply, RouteRow, Source };