@c9up/ream 0.2.16 → 0.2.18

package/src/graphql/GraphQLProvider.ts

@@ -9,8 +9,9 @@
  *       const gql = app.container.make<GraphQLEngine>('graphql')
  *       gql.resolver('Query', 'tasks', TaskResolver, 'tasks')
  *
- *   - `boot()` — mount the engine at `engine.path` (default `/graphql`) for both
- *     GET (playground/introspection) and POST (queries).
+ *   - `start()` — mount the engine at `engine.path` (default `/graphql`) for
+ *     both GET (playground/introspection) and POST (queries). In `start`, which
+ *     is the phase upstream documents for routes.
  *
  * @implements Story 24.5
  */
@@ -66,7 +67,17 @@ export class GraphQLProvider extends Provider {
     this.#registered = true
   }
 
-  override async boot(): Promise<void> {
+  /**
+   * Routes and server middleware go in `start`, not `boot`.
+   *
+   * Upstream documents that phase for exactly this, and the order is what makes
+   * it matter: providers boot, then providers START, then the preloads run —
+   * and the preloads are where an application writes its own routes and kernel.
+   * Mounted in `boot`, a framework route landed ahead of every application
+   * route, so an overlapping path was answered by the framework rather than by
+   * the app that meant to override it.
+   */
+  override async start(): Promise<void> {
     const engine = this.#engine
     if (!engine) return
     const router = await this.app.container.make<Router>('router')

package/src/hot.ts

@@ -0,0 +1,165 @@
+/**
+ * Dev-only entry hook: hot module replacement for the running server.
+ *
+ * `ream dev` loads this before the application entry:
+ *
+ *   node --import @swc-node/register/esm-register --import @c9up/ream/hot bin/server.ts
+ *
+ * It is a thin shim over `hot-hook`, which does the actual work: it registers
+ * an ESM loader that tracks the import graph, and when a file inside a declared
+ * boundary changes it invalidates just that module instead of the process. The
+ * `hotHook` key in the application's `package.json` configures it, exactly as
+ * upstream reads it.
+ *
+ * NAMED DEVIATION — why this file exists at all.
+ *
+ * Upstream's dev server is itself a Node process: it forks the app, so the two
+ * talk over Node's IPC channel, and `hot-hook` reports a change it cannot swap
+ * by calling `process.send({ type: 'hot-hook:full-reload' })`. Our dev server is
+ * a Rust binary. A process it spawns has NO IPC channel, so `process.send` is
+ * `undefined` and that message goes nowhere: the server would keep serving the
+ * old module and say nothing.
+ *
+ * `hot.init()` takes an `onFullReloadAsked` callback for exactly this case, and
+ * that is the whole of the shim: turn "I cannot hot-swap this" into an exit
+ * code the Rust parent understands and restarts on. Everything else is
+ * upstream's behaviour, unmodified.
+ */
+
+import { hotReloadHappened } from './dev/hmr.js'
+
+/** Exit code meaning "restart me" — see `EXIT_RESTART` in the CLI's dev module. */
+const FULL_RELOAD_EXIT_CODE = 75
+
+interface HotHook {
+  init(options: {
+    rootDirectory: string
+    root?: string
+    boundaries?: string[]
+    restart?: string[]
+    ignore?: string[]
+    throwWhenBoundariesAreNotDynamicallyImported?: boolean
+    onFullReloadAsked?: () => void
+  }): Promise<void>
+}
+
+interface HotHookConfig {
+  root?: string
+  boundaries?: string[]
+  restart?: string[]
+  ignore?: string[]
+  throwWhenBoundariesAreNotDynamicallyImported?: boolean
+}
+
+/** Read `hotHook` out of the application's package.json, with no assumptions. */
+function readConfig(pkg: unknown): HotHookConfig {
+  if (typeof pkg !== 'object' || pkg === null) return {}
+  const raw = Reflect.get(pkg, 'hotHook')
+  if (typeof raw !== 'object' || raw === null) return {}
+  const stringArray = (key: string): string[] | undefined => {
+    const value = Reflect.get(raw, key)
+    if (!Array.isArray(value)) return undefined
+    return value.filter((entry): entry is string => typeof entry === 'string')
+  }
+  const root = Reflect.get(raw, 'root')
+  const strict = Reflect.get(raw, 'throwWhenBoundariesAreNotDynamicallyImported')
+  return {
+    root: typeof root === 'string' ? root : undefined,
+    boundaries: stringArray('boundaries'),
+    restart: stringArray('restart'),
+    ignore: stringArray('ignore'),
+    throwWhenBoundariesAreNotDynamicallyImported: typeof strict === 'boolean' ? strict : undefined,
+  }
+}
+
+const { readFile } = await import('node:fs/promises')
+const { dirname, resolve } = await import('node:path')
+
+const packageJsonPath = resolve(process.cwd(), 'package.json')
+let config: HotHookConfig = {}
+try {
+  config = readConfig(JSON.parse(await readFile(packageJsonPath, 'utf8')))
+} catch {
+  // No package.json, or unreadable: hot-hook still works, it just has no
+  // boundaries, so every change asks for a restart. That is the old
+  // behaviour, not a failure worth stopping dev over.
+}
+
+// `hot-hook` is an optional peer, declared by the application because it is a
+// dev dependency there and has no business in a production install. Imported by
+// specifier built at runtime so a production bundle never resolves it.
+function isHotHook(value: unknown): value is HotHook {
+  return (
+    typeof value === 'object' && value !== null && typeof Reflect.get(value, 'init') === 'function'
+  )
+}
+
+// `hot-hook` belongs to the APPLICATION: it is a dev dependency there and has
+// no business in a production install of the framework. So it is resolved from
+// the project directory rather than from this file — under pnpm's strict layout
+// a bare `import("hot-hook")` here looks inside @c9up/ream and finds nothing.
+// It is the same reason upstream passes `hot-hook/register` from the app's own
+// cwd instead of re-exporting it from the framework.
+const { createRequire } = await import('node:module')
+const { pathToFileURL } = await import('node:url')
+
+let hot: HotHook | undefined
+try {
+  const resolved = createRequire(packageJsonPath).resolve('hot-hook')
+  const module: unknown = await import(pathToFileURL(resolved).href)
+  const candidate =
+    typeof module === 'object' && module !== null ? Reflect.get(module, 'hot') : undefined
+  if (!isHotHook(candidate)) {
+    throw new Error('hot-hook did not expose a `hot` object with init()')
+  }
+  hot = candidate
+} catch (error) {
+  // Loud, and it names the fix. Silence here would start a perfectly healthy
+  // server that never picks up an edit, which reads as "HMR is broken" rather
+  // than "HMR is not installed".
+  //
+  // It does NOT throw: a dev server that refuses to start is worse than one
+  // without hot reloading, and the CLI only loads this file when it has
+  // already seen hot-hook in the project — so reaching here means it went
+  // missing under a running session.
+  console.error(
+    `[ream] hot module replacement is unavailable: ${error instanceof Error ? error.message : String(error)}\n` +
+      '[ream] Install it with: pnpm add -D hot-hook, then restart `ream dev`.\n' +
+      '[ream] Until then the server runs, but an edit will not be picked up.',
+  )
+}
+
+// Impersonate the IPC channel upstream's dev server provides.
+//
+// hot-hook reports BOTH of its outcomes through `process.send`: a change it
+// swapped in place (`hot-hook:invalidated`) and one it could not
+// (`hot-hook:full-reload`). Under a Node parent that function exists and both
+// arrive; under our Rust parent it is `undefined` and both are dropped —
+// `onFullReloadAsked` alone recovers only half of that, leaving a hot swap
+// invisible to the very process it happened in, and so to the browser.
+//
+// This is not a trick played on hot-hook: it is exactly the contract it
+// expects, provided by us instead of by Node.
+const previousSend = process.send
+process.send = (message: unknown, ...rest: unknown[]): boolean => {
+  const type =
+    typeof message === 'object' && message !== null ? Reflect.get(message, 'type') : undefined
+  if (type === 'hot-hook:invalidated') {
+    hotReloadHappened()
+  }
+  // If a real channel ever exists (embedded under a Node supervisor) it still
+  // gets its message: this observes, it does not intercept.
+  if (typeof previousSend === 'function') {
+    return Reflect.apply(previousSend, process, [message, ...rest]) === true
+  }
+  return true
+}
+
+await hot?.init({
+  ...config,
+  rootDirectory: dirname(packageJsonPath),
+  root: config.root ? resolve(dirname(packageJsonPath), config.root) : undefined,
+  // Exiting on a known code is how the Rust parent learns it must restart —
+  // see `EXIT_RESTART` in the CLI's dev module.
+  onFullReloadAsked: () => process.exit(FULL_RELOAD_EXIT_CODE),
+})

package/src/http/Exception.ts

@@ -156,7 +156,7 @@ export class E_VALIDATION_ERROR extends Exception {
   static override code = 'E_VALIDATION_ERROR'
 
   /**
-   * Per-field failures. Named `messages` because that is what VineJS, rune and
+   * Per-field failures. Named `messages` because that is what rune and
    * AdonisJS's own validation renderers read — a handler copied from an Adonis
    * app reaches for `error.messages`.
    */
@@ -249,7 +249,7 @@ export type HttpError = {
   code: string
   stack?: string
   cause?: unknown
-  /** Per-field failures, on a validation error (VineJS / rune shape). */
+  /** Per-field failures, on a validation error (rune's shape). */
   messages?: unknown
   /** Extra detail an exception chose to carry. */
   errors?: unknown
@@ -487,7 +487,7 @@ export class ExceptionHandler extends Macroable {
 
     // Validation failures have per-field detail and their own renderers. Keyed
     // on the code plus the presence of `messages`, exactly as AdonisJS does, so
-    // rune's and VineJS's errors both land here.
+    // rune's errors land here.
     if (httpError.code === 'E_VALIDATION_ERROR' && httpError.messages !== undefined) {
       await this.renderValidationError(httpError, ctx)
       return
@@ -523,7 +523,7 @@ export class ExceptionHandler extends Macroable {
 }
 
 /**
- * The fields a validation message carries (VineJS / rune `RuneErrorNode`).
+ * The fields a validation message carries (rune's `RuneErrorNode`).
  *
  * Read defensively: the messages come from whichever validator the app wired,
  * and a renderer must not throw while rendering someone else's error.

package/src/http/Request.ts

@@ -13,6 +13,12 @@ import type { SignedUrl } from '../security/SignedUrl.js'
 import type { Dict } from '../types/helpers.js'
 import { Macroable } from '../utils/Macroable.js'
 import { getPath, omitPaths, pickPaths } from '../utils/objectPath.js'
+import type {
+  RequestAwareValidator,
+  RequestValidationOptions,
+  ValidatableContext,
+} from './RequestValidator.js'
+import { RequestValidator } from './RequestValidator.js'
 import { unpackCookieValue } from './Response.js'
 
 export interface RawRequest {
@@ -789,6 +795,44 @@ export class Request extends Macroable {
     return { ...this.#merged }
   }
 
+  /**
+   * The context a validation hook is handed.
+   *
+   * The whole context when this request has one, because that is where a hook
+   * finds what it needs — `ctx.i18n` for a translated message. A Request built
+   * by hand for a test has none, and stands in for itself.
+   */
+  #validationContext(): ValidatableContext {
+    const ctx = this.ctx
+    // Handed back as it is, never spread: a context carries accessors
+    // (`ctx.i18n` is one), and a spread would freeze each into a plain value
+    // read at this instant instead of when the hook asks for it.
+    if (ctx !== undefined && carriesRequest(ctx)) return ctx
+    return { request: this }
+  }
+
+  /**
+   * Validate this request, throwing `E_VALIDATION_ERROR` on failure.
+   *
+   * The entry point that lets a schema stay ignorant of the request: the
+   * per-request messages provider and error reporter are filled in here, from
+   * hooks a package installed at boot. See {@link RequestValidator}.
+   */
+  validateUsing<T>(
+    validator: RequestAwareValidator<T>,
+    options?: RequestValidationOptions,
+  ): Promise<T> {
+    return new RequestValidator(this.#validationContext()).validateUsing(validator, options)
+  }
+
+  /** Validate this request, answering `[error, null]` or `[null, data]`. */
+  tryValidateUsing<T>(
+    validator: RequestAwareValidator<T>,
+    options?: RequestValidationOptions,
+  ): Promise<[unknown, null] | [null, T]> {
+    return new RequestValidator(this.#validationContext()).tryValidateUsing(validator, options)
+  }
+
   /**
    * The original request input, captured once and never mutated (AdonisJS
    * `request.original`) — the basis for flash "old input" on validation errors.
@@ -1174,3 +1218,13 @@ function languageMatches(entry: string, offered: string): boolean {
   if (primary && primary === o.split('-')[0]) return true
   return false
 }
+
+/**
+ * Whether an object is a context wrapped around a real request.
+ *
+ * `Request.ctx` is deliberately typed `object` — the request must not depend
+ * on the context's shape — so this is where that opacity is paid back.
+ */
+function carriesRequest(value: object): value is ValidatableContext {
+  return 'request' in value && value.request instanceof Request
+}

package/src/http/RequestValidator.ts

@@ -0,0 +1,143 @@
+/**
+ * Per-request validation.
+ *
+ * A validator compiled when its module loaded knows nothing about the request
+ * about to run through it — yet the two things it most often needs are per
+ * request: which language to answer in, and where the errors go. The two
+ * static hooks below are that seam. An i18n package installs one at boot:
+ *
+ * ```ts
+ * RequestValidator.messagesProvider = (ctx) => ctx.i18n.createMessagesProvider()
+ * ```
+ *
+ * and every `request.validateUsing(...)` call picks it up, without a single
+ * schema mentioning translation. Nothing else in the framework reads them, so
+ * a validator called directly keeps whatever provider it was built with.
+ *
+ * Structural on purpose: ream never imports a validation package. Anything
+ * with a `validate(data, options)` fits, which is also what makes this
+ * testable without one.
+ */
+
+import type { HttpContext } from './HttpContext.ts'
+
+/** What a validator has to expose to be usable here. */
+export interface RequestAwareValidator<T> {
+  validate(data: Record<string, unknown>, options?: RequestValidationOptions): Promise<T>
+}
+
+/** Options forwarded to the validator, plus the data override. */
+export interface RequestValidationOptions {
+  /** Validate this instead of the request's own data. */
+  data?: Record<string, unknown>
+  /** Per-call messages provider — beats the static hook. */
+  messagesProvider?: unknown
+  /** Per-call error reporter factory — beats the static hook. */
+  errorReporter?: unknown
+  /** Arbitrary metadata a rule can read off the field context. */
+  meta?: Record<string, unknown>
+}
+
+/**
+ * The slice this class reads. A real {@link HttpContext} satisfies it, and so
+ * does a bare `{ request }` pair — which is what a Request built by hand, with
+ * no context around it, can still offer.
+ */
+export interface ValidatableContext {
+  request: {
+    all(): Record<string, unknown>
+    params(): Readonly<Record<string, string | string[]>>
+    headers(): Readonly<Record<string, unknown>>
+    cookiesList(): Record<string, unknown>
+  }
+}
+
+/**
+ * What a hook is handed. The full context when there is one — an i18n package
+ * reads `ctx.i18n` off it — and the narrow shape otherwise, which is why this
+ * is a union rather than just `HttpContext`.
+ */
+export type ValidationHookContext = HttpContext | ValidatableContext
+
+export class RequestValidator {
+  readonly #ctx: ValidatableContext
+
+  constructor(ctx: ValidatableContext) {
+    this.#ctx = ctx
+  }
+
+  /**
+   * Picks the error reporter for a request. Assigned once, at boot, by
+   * whatever package owns error formatting.
+   */
+  static errorReporter?: (ctx: ValidationHookContext) => unknown
+
+  /**
+   * Picks the messages provider for a request. Assigned once, at boot, by
+   * whatever package owns translations.
+   */
+  static messagesProvider?: (ctx: ValidationHookContext) => unknown
+
+  /**
+   * Everything a rule might address, in one object.
+   *
+   * `params`, `headers` and `cookies` are nested under their own keys rather
+   * than merged: a form field named `params` is ordinary, and flattening them
+   * would let a request rename its own route parameters.
+   */
+  #requestData(): Record<string, unknown> {
+    const { request } = this.#ctx
+    return {
+      ...request.all(),
+      params: request.params(),
+      headers: request.headers(),
+      cookies: request.cookiesList(),
+    }
+  }
+
+  /**
+   * Fill in the request-scoped reporter and provider, without overwriting
+   * anything the caller passed — an explicit option is a deliberate choice
+   * for this one call and must outrank a process-wide default.
+   */
+  #processOptions(options?: RequestValidationOptions): RequestValidationOptions {
+    const resolved: RequestValidationOptions = { ...options }
+    if (RequestValidator.errorReporter && resolved.errorReporter === undefined) {
+      const reporter = RequestValidator.errorReporter(this.#ctx)
+      // The validator expects a FACTORY, so a fresh reporter is built per run
+      // rather than one instance accumulating across requests.
+      resolved.errorReporter = () => reporter
+    }
+    if (RequestValidator.messagesProvider && resolved.messagesProvider === undefined) {
+      resolved.messagesProvider = RequestValidator.messagesProvider(this.#ctx)
+    }
+    return resolved
+  }
+
+  /** Validate the request, throwing `E_VALIDATION_ERROR` on failure. */
+  validateUsing<T>(
+    validator: RequestAwareValidator<T>,
+    options?: RequestValidationOptions,
+  ): Promise<T> {
+    const resolved = this.#processOptions(options)
+    return validator.validate(resolved.data ?? this.#requestData(), resolved)
+  }
+
+  /**
+   * Validate the request, returning `[error, null]` or `[null, data]`.
+   *
+   * The tuple form exists so a handler can answer a failure itself instead of
+   * letting the exception reach the error handler — a wizard step that
+   * re-renders the form, say.
+   */
+  async tryValidateUsing<T>(
+    validator: RequestAwareValidator<T>,
+    options?: RequestValidationOptions,
+  ): Promise<[unknown, null] | [null, T]> {
+    try {
+      return [null, await this.validateUsing(validator, options)]
+    } catch (error) {
+      return [error, null]
+    }
+  }
+}

package/src/index.ts

@@ -60,6 +60,13 @@ export { HttpContext } from './http/HttpContext.js'
 export { RedirectBuilder } from './http/RedirectBuilder.js'
 export type { RawRequest } from './http/Request.js'
 export { Request } from './http/Request.js'
+export type {
+  RequestAwareValidator,
+  RequestValidationOptions,
+  ValidatableContext,
+  ValidationHookContext,
+} from './http/RequestValidator.js'
+export { RequestValidator } from './http/RequestValidator.js'
 export { Response } from './http/Response.js'
 export type { SseStreamOptions } from './http/SseStream.js'
 export { SseStream } from './http/SseStream.js'
@@ -378,4 +385,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.16'
+export const VERSION = '0.2.18'

package/src/middleware/Pipeline.ts

@@ -32,7 +32,7 @@ export interface RuntimeValidationResult {
  * Structural contract for a route validator. ream stays decoupled from the
  * validation engine — any object exposing a result-returning check works.
  *
- * Three spellings are accepted because `@c9up/rune` follows VineJS: `validate()`
+ * Three spellings are accepted because `@c9up/rune` offers all three: `validate()`
  * is async and throws, `validateResult()` is synchronous and never throws, and
  * `validateResultAsync()` is the async result-based form.
  *
@@ -46,7 +46,7 @@ export interface RuntimeValidator {
   validateResultAsync?(data: unknown): Promise<RuntimeValidationResult>
 }
 
-/** A thrown validation failure, as raised by rune/VineJS `validate()`. */
+/** A thrown validation failure, as raised by rune's `validate()`. */
 interface ThrownValidationFailure {
   messages: unknown[]
 }
@@ -66,7 +66,7 @@ function isValidationResult(value: unknown): value is RuntimeValidationResult {
  * result object.
  *
  * Order matters: the async result form first (it is the only one that can run
- * `unique` / `exists`), then the synchronous one, then VineJS's throwing
+ * `unique` / `exists`), then the synchronous one, then the throwing
  * `validate()` — awaited, and with its `E_VALIDATION_ERROR` translated back
  * into a result so callers keep a single shape to handle.
  */
@@ -85,7 +85,7 @@ export async function runValidator(
   if (typeof validator.validate === 'function') {
     try {
       const outcome = await validator.validate(data)
-      // A result-returning `validate()` (not the VineJS contract) is honoured
+      // A result-returning `validate()` (not the throwing contract) is honoured
       // as-is; the throwing contract resolves to the validated payload.
       return isValidationResult(outcome) ? outcome : { valid: true, errors: [], data: outcome }
     } catch (err) {

package/src/migrations/MigrationRegistry.ts

@@ -27,6 +27,29 @@ export class MigrationRegistry {
     return this
   }
 
+  /**
+   * Remove a store's runner — only while it is still the one that registered.
+   *
+   * `register` refuses a duplicate name, deliberately: two providers claiming
+   * one name means one of them migrates nothing while the run reports success.
+   * But nothing ever removed a source, so a provider that shut down left its
+   * name taken and its runner holding a connection it had already closed. A
+   * second boot in the same process — a hot reload, a test that restarts the
+   * app — then failed on "already registered", and the CLI would have driven a
+   * runner pointing at a dead pool.
+   *
+   * `source` is the ownership guard. Two applications can share a process, and
+   * the one shutting down must not unregister the survivor's runner that
+   * happens to carry the same name.
+   */
+  unregister(name: string, source?: RegisteredMigrationSource): boolean {
+    const current = this.#sources.get(name)
+    if (current === undefined) return false
+    if (source !== undefined && current !== source) return false
+    this.#sources.delete(name)
+    return true
+  }
+
   /** Every registered store, in registration order. */
   all(): RegisteredMigrationSource[] {
     return [...this.#sources.values()]

package/src/openapi/OpenApiGenerator.ts

@@ -56,6 +56,16 @@ export class OpenApiGenerator {
   #router: Router
   #config: OpenApiConfig
   #runeSchemas: Map<string, Record<string, unknown>>
+  /**
+   * Schemas a validator produced itself, already in JSON Schema form.
+   *
+   * Kept apart from {@link #runeSchemas}, which holds rune FIELD MAPS that
+   * {@link #runeToJsonSchema} still has to convert. One map for both would
+   * mean guessing which kind a value is, and guessing wrong sends a finished
+   * schema back through the converter, which reads its `type` and `properties`
+   * keys as if they were field names.
+   */
+  #jsonSchemas = new Map<string, Record<string, unknown>>()
 
   constructor(
     router: Router,
@@ -72,6 +82,30 @@ export class OpenApiGenerator {
     this.#runeSchemas.set(name, definition)
   }
 
+  /**
+   * Fill the schema map from the validators the routes already name.
+   *
+   * `route.validate('createUser')` records a container token, and the
+   * validator behind it can describe itself. Without this step every one of
+   * those routes documented its body as a bare `{ type: 'object' }` unless the
+   * app ALSO called `registerSchema` by hand with a definition it had to keep
+   * in step with the schema — two descriptions of one payload, and nothing
+   * checking they agreed.
+   *
+   * Resolution happens once, here, because `generate()` is synchronous and the
+   * container is not. A validator that cannot be resolved, or that cannot
+   * describe itself, is skipped: a missing section of documentation is a
+   * smaller problem than a boot that fails over one.
+   */
+  async hydrateSchemas(resolve: (token: string) => Promise<unknown>): Promise<void> {
+    const names = new Set(this.#getRoutes().flatMap((route) => route.validators))
+    for (const name of names) {
+      if (this.#runeSchemas.has(name) || this.#jsonSchemas.has(name)) continue
+      const definition = await describeValidator(resolve, name)
+      if (definition !== undefined) this.#jsonSchemas.set(name, definition)
+    }
+  }
+
   /** Generate the complete OpenAPI 3.1 spec. */
   generate(): OpenApiSpec {
     const spec: OpenApiSpec = {
@@ -171,13 +205,13 @@ export class OpenApiGenerator {
 
     if (route.validators.length > 0 && ['post', 'put', 'patch'].includes(method)) {
       const [validatorName] = route.validators
-      const schema = validatorName === undefined ? undefined : this.#runeSchemas.get(validatorName)
-      if (schema && validatorName !== undefined) {
+      const body = validatorName === undefined ? undefined : this.#bodySchema(validatorName)
+      if (body && validatorName !== undefined) {
         operation.requestBody = {
           required: true,
-          content: { 'application/json': { schema: this.#runeToJsonSchema(schema) } },
+          content: { 'application/json': { schema: body } },
         }
-        schemas[validatorName] = this.#runeToJsonSchema(schema)
+        schemas[validatorName] = body
       } else {
         operation.requestBody = {
           required: true,
@@ -211,6 +245,17 @@ export class OpenApiGenerator {
     return `${route.method} ${route.path}`
   }
 
+  /**
+   * The JSON Schema for a named validator: what it described about itself
+   * first, then a hand-registered field map converted here.
+   */
+  #bodySchema(name: string): Record<string, unknown> | undefined {
+    const described = this.#jsonSchemas.get(name)
+    if (described !== undefined) return described
+    const fields = this.#runeSchemas.get(name)
+    return fields === undefined ? undefined : this.#runeToJsonSchema(fields)
+  }
+
   /** Convert a Rune schema (Record<string, RuleChain>) to JSON Schema. */
   #runeToJsonSchema(schema: Record<string, unknown>): Record<string, unknown> {
     const properties: Record<string, unknown> = {}
@@ -254,3 +299,38 @@ export class OpenApiGenerator {
     return this.#router.getRoutes()
   }
 }
+
+/** A validator that can describe its own shape as JSON Schema. */
+interface SelfDescribingValidator {
+  toJSONSchema(): Record<string, unknown>
+}
+
+function describesItself(value: unknown): value is SelfDescribingValidator {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'toJSONSchema' in value &&
+    typeof value.toJSONSchema === 'function'
+  )
+}
+
+/** Resolve one validator and ask it for its schema, or answer undefined. */
+async function describeValidator(
+  resolve: (token: string) => Promise<unknown>,
+  name: string,
+): Promise<Record<string, unknown> | undefined> {
+  let validator: unknown
+  try {
+    validator = await resolve(`validator:${name}`)
+  } catch {
+    // An unregistered validator is already a hard error at request time; the
+    // documentation is not the place to raise it a second time.
+    return undefined
+  }
+  if (!describesItself(validator)) return undefined
+  try {
+    return validator.toJSONSchema()
+  } catch {
+    return undefined
+  }
+}