@databehave/server 0.1.1 → 0.1.2

package/docs/config/endpoints.md

@@ -1,162 +0,0 @@
-# `endpoints`
-
-The route table. Keys are `"METHOD <path>"`. Values pick one of three
-forms:
-
-## 1. String (handler module path)
-
-```jsonc
-"GET products/list": "./src/routes/products/get/list.js"
-```
-
-Shorthand for `{ "handler": "..." }`. The module must:
-
-- be loadable via the runtime's native ESM `import()`,
-- `export default` a `Handler` (a function returning a
-  `MockResponse` POJO, sync or async).
-
-CommonJS modules are not supported by the JSONC loader's resolver —
-its dynamic-import path runs through `pathToFileURL()` and assumes
-ESM. If the module's default export is missing or is not a function,
-boot fails with:
-
-```text
-@databehave/server/config: ./src/routes/products/get/list.js (mapped to GET /api/v1/products/list) has no default-exported handler function
-```
-
-### Handler resolution
-
-Config files reference handlers by their compiled `.js` path so they
-stay valid for production `tsc`-built deployments. In dev / test
-scenarios where only the TypeScript source exists on disk, the
-resolver falls back to a sibling extension automatically — `.js`
-becomes `.ts`, `.tsx`, `.mts`, or `.cts` (in that order) — so test
-runners that register a TS loader (`vitest`, `tsx`, `ts-node`) pick
-the right file without any config change.
-
-Set `DATABEHAVE_PREFER_TS=1` to **prefer** `.ts` siblings over the
-declared `.js` even when both exist on disk. Useful in dev when an
-outdated `dist/` is still around and would otherwise win. The
-variable accepts only the literal string `"1"`; any other value
-(including `true`) is treated as off.
-
-## 2. Handler object
-
-```jsonc
-"POST products/bulk-update": {
-  "handler": "./src/routes/products/update/bulk-update.js",
-  "status": 500
-}
-```
-
-The optional `status` field is a shortcut that registers an entry in
-`mockMode.pathOverrides` for this route. Use it to force an error
-status without editing the handler.
-
-## 3. Static response
-
-```jsonc
-"GET /health": {
-  "response": {
-    "status": 200,
-    "json":   { "ok": true },
-    "headers": { "cache-control": "no-store" }
-  }
-}
-```
-
-No handler module is loaded; the response is returned verbatim. Use
-`"empty": true` instead of `"json"` for an empty body.
-
-### `EndpointResponse` fields
-
-| Field     | Required | Meaning |
-| --------- | -------- | --- |
-| `status`  | yes      | HTTP status integer. Boot fails with `endpoints["KEY"].response.status must be a number` if missing or non-numeric — there is no implicit `200`. |
-| `json`    | no       | JSON body. Mutually exclusive with `empty`. May be any JSON value (`null`, `[]`, `{}` are all valid). When omitted on a non-`empty` response the body is `null`. |
-| `empty`   | no       | When `true`, the response carries no body. Boot fails with `endpoints["KEY"].response.empty must be a boolean` if the value is non-boolean. |
-| `headers` | no       | Plain `Record<string, string>` merged into the response. Non-string values raise `endpoints["KEY"].response.headers["H"] must be a string` at boot. Header keys are case-preserved as written. |
-
-`handler` and `response` are mutually exclusive. Setting both raises:
-
-```text
-@databehave/server/config: endpoints["KEY"] cannot have both "handler" and "response"
-```
-
-An empty `{}` value is also rejected:
-
-```text
-@databehave/server/config: endpoints["KEY"] must have either "handler" or "response"
-```
-
-A `status` field next to `response` (instead of inside it) is rejected
-with a hint pointing at the correct location:
-
-```text
-@databehave/server/config: endpoints["KEY"].status cannot be combined with "response" (put status inside response)
-```
-
-## Programmatic `handlers` override
-
-`loadConfig(path, { handlers })` accepts an explicit
-module-path → function map that short-circuits the dynamic `import()`
-for matching keys. Use case: test environments (vitest under plain
-Node 18) that cannot load `.ts` source files through native
-`import()`. Construct the map via static imports or
-`import.meta.glob('eager')`, then pass it in.
-
-```ts
-import { loadConfig } from '@databehave/server'
-import healthHandler from './src/routes/health.ts'
-
-await loadConfig('./databehave.jsonc', {
-  handlers: {
-    './src/routes/health.js': healthHandler,
-  },
-})
-```
-
-Keys are canonicalised before lookup: a leading `./` is stripped,
-repeated `/` are collapsed, and the trailing
-`.js` / `.mjs` / `.cjs` / `.ts` / `.tsx` / `.mts` / `.cts` is dropped
-— so `./src/routes/health.js`, `src/routes/health`, and
-`./src/routes/health.ts` all collapse to the same lookup key.
-Handlers not present in the map fall back to dynamic import. Values
-that are not functions raise at boot:
-
-```text
-@databehave/server/config: handlers override for "./src/routes/health.js" (mapped to GET /health) is not a function (got TYPE)
-```
-
-## Programmatic `logger` injection
-
-`loadConfig(path, { logger })` redirects non-fatal
-warnings (OAS walker errors, empty schemas, mock-mode header
-diagnostics) to a custom sink. Defaults to `console.warn`. Inject a
-no-op logger from tests to silence the output, or a structured logger
-in production:
-
-```ts
-await loadConfig('./databehave.jsonc', {
-  logger: { warn: (m) => myLogger.warn({ src: 'databehave', m }) },
-})
-```
-
-The injected logger only catches warnings emitted while loading the
-config and wiring the OpenAPI / mock-mode adapters — it does not
-intercept access logs (those go through the [`log`](./log.md)
-config) or per-request `console.warn` calls from user handlers.
-
-## `basePath` collisions
-
-When the JSONC config sets `basePath`, every relative endpoint key
-(e.g. `"GET products/list"`) is rewritten to absolute
-(`"GET /api/v1/products/list"`). If two distinct keys collide after
-rewriting — typically because one was already absolute and the other
-relative to the same final path — the loader fails fast at boot:
-
-```text
-@databehave/server/config: endpoints keys "GET /api/v1/products/list" and "GET products/list" both resolve to "GET /api/v1/products/list" after applying basePath
-```
-
-There is no last-write-wins fallback. Pick one form per route.

package/docs/config/index.md

@@ -1,107 +0,0 @@
-# Configuration reference
-
-`@databehave/server` is configured by one file (`databehave.jsonc`) or one
-`Config` object passed to `createServer`. This page covers
-the file form; the programmatic form mirrors it field-for-field.
-
-## File format
-
-- Extension can be `.json` or `.jsonc`. Either way, JSONC features are
-  accepted:
-  - `// line` comments
-  - `/* block */` comments
-  - trailing commas
-- Every string value supports `${VAR}` and `${VAR:default}` env
-  interpolation. Missing env without default → empty string.
-- Variable names accept ASCII letters, digits, and `_`, with the
-  leading character restricted to a letter or `_`. Lowercase and
-  mixed-case names are allowed (`${path}`, `${myVar}`); the loader
-  does not require ALL_CAPS shell convention.
-- Every relative path is resolved against the **directory of the
-  config file**.
-
-## Environment variables (process-level)
-
-Two env vars influence boot behaviour beyond `${VAR}` interpolation:
-
-| Variable | Effect |
-| --- | --- |
-| `NODE_ENV` | When **not** equal to `'production'`, both `defineConfig` and the JSONC loader deep-freeze the resolved config so accidental mutation throws in tests. Production skips the freeze so callers may legitimately patch the object after construction. |
-| `DATABEHAVE_PREFER_TS=1` | Prefer a `.ts` / `.tsx` / `.mts` / `.cts` sibling over the declared `.js` for handler resolution, even when the `.js` exists on disk. Useful in dev when an outdated `dist/` is still around. Default off. |
-
-## Top-level shape
-
-```jsonc
-{
-  "openapi":   "./openapi.json",        // optional, JSON only
-  "server":    { "host": "...", "port": 8000 },
-  "basePath":  "/api/v1",               // optional
-  "cors":      { /* ... */ },           // optional
-  "mockMode":  { /* ... */ },           // optional
-  "admin": { /* ... */ },           // optional, default off
-  "log":       false,                   // optional, default off
-  "endpoints": { /* ... */ }            // route → handler / response
-}
-```
-
-## Field reference
-
-- [openapi.md](./openapi.md) — `openapi:` (path to the OAS document).
-- [server.md](./server.md) — `server:` host / port and `basePath:`.
-- [endpoints.md](./endpoints.md) — `endpoints:` route table and handler shorthand forms.
-- [cors.md](./cors.md) — `cors:` block.
-- [mock-mode.md](./mock-mode.md) — `mockMode:` block.
-- [admin.md](./admin.md) — `admin:` block (config knobs only — admin behaviour is in [../admin/](../admin/index.md)).
-- [log.md](./log.md) — `log:` block.
-- [schema.md](./schema.md) — `schema:` (auto-schema config knobs — auto-mode behaviour is in [../openapi/auto-schema.md](../openapi/auto-schema.md)).
-- [validation.md](./validation.md) — `validation:` block.
-
-For the CLI that consumes the `server` section, see [../cli.md](../cli.md).
-
-## Programmatic `Config`
-
-```ts
-import { createServer, defineConfig } from '@databehave/server'
-
-const config = defineConfig({
-  routes: {
-    'GET /api/v1/ping': () => ({ json: { ok: true } }),
-  },
-  hooks: {
-    onRequest:  (req) => { /* short-circuit by returning a MockResponse */ },
-    onResponse: (req, res) => res,
-    onError:    (req, err) => ({ status: 500, json: { error: true } }),
-  },
-  cors: { origin: (o) => o || '*', credentials: true },
-  openapi: undefined,                   // pass JSON OAS text here to enable
-  onOpenApiWalkError:   (m, p, err) => console.warn(`walk failed: ${m} ${p}`, err),
-  onOpenApiEmptySchema: (m, p, s) => console.warn(`empty schema: ${m} ${p} ${s}`),
-})
-
-const server = createServer(config)
-```
-
-`defineConfig` is an identity function — present for IDE support, it
-gives you the strict `Config` type inline. When `NODE_ENV !==
-'production'` it also deep-freezes the returned config so accidental
-mutation (e.g. `config.routes['GET /x'] = …`, pushing into
-`cors.allowMethods`) throws in tests instead of silently corrupting the
-running server. Handler functions are intentionally left mutable — freeze
-stops at function boundaries. Production skips the freeze so callers may
-legitimately patch the object for env-specific wiring.
-
-## Programmatic API surface
-
-Everything reachable from the package entry point. Every field above
-maps to a typed member of `Config` (see the source
-declaration in `src/types.ts`).
-
-| Export | What it is |
-| --- | --- |
-| `createServer(config)` | Build a `Server` from an in-memory config. Returns `{ fetch, listen }`. The HTTP runtime is `node:http` ↔ Web Fetch under the hood. |
-| `defineConfig(config)` | Identity helper for IDE intellisense + dev-mode deep-freeze (see above). |
-| `loadConfig(path, opts?)` | Read a JSONC file from disk and resolve every handler module. `opts.handlers` short-circuits dynamic `import()` (test-friendly bypass — see [endpoints.md](./endpoints.md#programmatic-handlers-override)); `opts.logger` redirects walker / mock-mode warnings to your sink (defaults to `console.warn`). |
-| `run({ config, open? })` / `RunHandle` | One-call boot: load JSONC, build the server, bind the listen port, optionally open the admin URL. `RunHandle.close()` is idempotent. Used by both the CLI and direct library consumers so log lines and error model match exactly. |
-| `seedFor({ endpoint, from?, dayOffset?, extra? })` | Pure helper for building deterministic databehave seed strings (`<endpoint>|<key>=<val>|date=<YYYY-MM-DD>|day=<n>`). Re-exported so consumers can derive their own seeds without reimplementing the format. |
-| `resolveStatus` / `MockModeConfig` / `MockModeLogger` | `resolveStatus(method, path, config)` is exported for unit tests. `MockModeConfig` (and its `logger` sink `MockModeLogger`) is the type of `JsonConfig.mockMode`. The wiring (`buildMockModeHooks`, `BodyResolver`, `MockModeHooks`) is internal — set `mockMode.enabled: true` in JSONC. |
-| `Config` and sibling types (`Method`, `MockRequest`, `MockResponse`, `Cors`, `Handler`, `ListenOptions`, `Server`, `AdminModeConfig`, `ErrorMode`, …) | Strict type declarations exported from `src/types.ts` / `src/admin/admin-types.ts`. |

package/docs/config/log.md

@@ -1,43 +0,0 @@
-# `log`
-
-Opt-in per-request access log written to **stdout**. Off by default —
-no output and no per-request overhead.
-
-```jsonc
-"log": true                                // shorthand: { access: true }
-```
-
-Or as an object:
-
-```jsonc
-"log": {
-  "access":       true,                    // default true when object given
-  "includeAdmin": false,                   // log admin-panel hits too
-  "colors":       "auto",                  // 'auto' | 'always' | 'never'
-  "format":       "pretty"                 // 'pretty' | 'json'
-}
-```
-
-| Field          | Default     | Meaning |
-| -------------- | ----------- | --- |
-| `access`       | `true`      | One line per request when `true`. |
-| `includeAdmin` | `false`     | When `true`, log hits to `admin.path/*`. |
-| `colors`       | `'auto'`    | `'auto'` honours `process.stdout.isTTY`. No effect on `json` format. |
-| `format`       | `'pretty'`  | `'pretty'` (ANSI one-liner) or `'json'` (newline-terminated object). |
-
-Sticky / header-driven overrides are flagged with
-`[override:<mode.kind>]` (pretty) or `"override":"<kind>"` (json).
-
-Pretty (colours stripped):
-
-```txt
-GET /api/v1/health → 200 4 ms · 56
-POST /api/v1/widgets/copy → 500 2 ms · 78 [override:http-status]
-```
-
-JSON:
-
-```json
-{"t":"2026-05-28T10:00:00.000Z","method":"GET","path":"/api/v1/health","status":200,"ms":4,"bytes":"56"}
-{"t":"2026-05-28T10:00:00.000Z","method":"POST","path":"/api/v1/widgets/copy","status":500,"ms":2,"bytes":"78","override":"http-status"}
-```

package/docs/config/mock-mode.md

@@ -1,84 +0,0 @@
-# `mockMode`
-
-```jsonc
-"mockMode": {
-  "enabled":             true,
-  "header":              "x-mock-status",
-  "healthPaths":         ["/health", "/healthz", "/api/v1/health"],
-  "defaultStatus":       200,
-  "allowHeaderOverride": false,
-  "pathOverrides": {
-    "GET /api/v1/products/list": 500,
-    "/api/v1/admin/users-delete": 401
-  }
-}
-```
-
-| Field | Default | Meaning |
-| --- | --- | --- |
-| `enabled` | `false` | Master switch. `false` / absent = feature off. |
-| `header` | `'x-mock-status'` | Response header tagged with the resolved status. Also the request header consulted when `allowHeaderOverride: true`. |
-| `healthPaths` | `[]` | Paths exempt from injection (typically health probes). |
-| `defaultStatus` | undefined | Status applied when no override matches. Omit for passthrough. |
-| `allowHeaderOverride` | `false` | When `true`, an incoming request may flip the mocked status by sending the same `header` (default `x-mock-status: 500`). Disabled by default so production-style mock servers don't expose status injection to arbitrary clients. |
-| `pathOverrides` | `{}` | Per-route status overrides. Keys are `"METHOD /path"` or `"/path"` (path must start with `/`). Values are HTTP status codes. |
-| `logger` | `console` | Programmatic-only sink for non-fatal mock-mode diagnostics (e.g. out-of-range header overrides). Pass the host application's logger to keep mock-server output in one place. Not settable from JSONC. |
-
-## Resolution priority (canonical)
-
-For each request, mock-mode picks a status in this order — first hit
-wins. When `admin.enabled` is also set, the admin inject hook
-runs **before** mock-mode and can short-circuit any of the steps
-below; see [../admin/overrides.md#sticky-override-resolution](../admin/overrides.md#sticky-override-resolution)
-for the unified pipeline.
-
-1. Request `header` value (only when `allowHeaderOverride: true`).
-2. `pathOverrides["<METHOD> <path>"]` (method-scoped exact match).
-3. `pathOverrides["<path>"]` (any-method exact match).
-4. `defaultStatus`.
-5. Passthrough — the real handler runs.
-
-`healthPaths` short-circuits the entire chain: matching paths are
-served by their handler regardless of any override.
-
-## `pathOverrides` key validation
-
-Keys are validated at config load. Malformed keys raise at boot
-(via `AggregateError` so every gap surfaces at once) — there is no
-silent "this key never matches" failure mode.
-
-- Keys must match `(?:METHOD\s+)?/path`. The optional method prefix
-  is one of `GET POST PUT DELETE PATCH HEAD OPTIONS`. The path must
-  start with `/` and contain no whitespace.
-- Method names are normalised to upper-case: `"get /api/x"`,
-  `"GET /api/x"`, and `"Get /api/x"` all canonicalise to
-  `"GET /api/x"` so a lower-case key still matches.
-- Values must be finite numbers (HTTP status codes).
-
-## Body resolution
-
-When a non-passthrough status `N` fires:
-
-1. `status === 204` → empty body.
-2. The body resolver returns the OAS `responses[N]` schema mock when
-   the route is OAS-walker-backed and a response schema exists for
-   that status (see [../openapi/fallback.md#per-status-body-generators](../openapi/fallback.md#per-status-body-generators)).
-3. Fallback envelope `{ error: true, status: N }`.
-
-The configured `header` (default `x-mock-status`) is always tagged on
-the response with the resolved status code so a client can confirm
-which override fired.
-
-## `allowHeaderOverride` validation
-
-When the request header is set but the value is not a finite integer
-in `[200, 600)`, the value is **ignored** and a single `warn` line
-is emitted via `logger` (default `console`) so the typo is visible
-without breaking legitimate clients that ship the header for other
-reasons:
-
-```text
-@databehave/server/mock-mode: ignored x-mock-status="abc" (must be an integer in [200, 600))
-```
-
-A per-endpoint shortcut also exists — see [endpoints.md](./endpoints.md).

package/docs/config/openapi.md

@@ -1,8 +0,0 @@
-# `openapi`
-
-Path (relative to the config file) to an OpenAPI 3.x document.
-**JSON only** — convert YAML first via `yq -o=json openapi.yaml > openapi.json`.
-When set, the walker registers fallback handlers for every
-`paths.*.<method>` not declared in `endpoints`.
-
-See [../openapi/fallback.md](../openapi/fallback.md) for walker behaviour.

package/docs/config/schema.md

@@ -1,34 +0,0 @@
-# `schema`
-
-Top-level field that opts the server into **auto-schema mode** — every
-endpoint absent from `endpoints` is served from data generated by
-`@databehave/schema`'s `mock()` engine, derived directly from your
-OpenAPI document.
-
-**Minimal:**
-
-```jsonc
-{
-  "openapi": "./openapi.json",
-  "schema": { "enabled": true }, // "enabled" gates auto-mode; defaults equivalent to { "seed": "stable" }
-  "endpoints": {}
-}
-```
-
-**With knobs:**
-
-```jsonc
-{
-  "openapi": "./openapi.json",
-  "schema": {
-    "enabled": true,
-    "seed": 42, // number = fixed; "stable" = derive from endpoint|query|params; "random" = fresh per request; default "stable"
-    "locale": "ja",
-    "arrayCount": 20 // default array length when the OAS lacks minItems
-  }
-}
-```
-
-For the architecture, install path, missing-install error, precedence,
-and default-behaviour rules, see
-[../openapi/auto-schema.md](../openapi/auto-schema.md).

package/docs/config/server.md

@@ -1,32 +0,0 @@
-# `server` and `basePath`
-
-## `server`
-
-```jsonc
-"server": {
-  "host": "${MOCK_SERVER_HOST:127.0.0.1}",
-  "port": "${MOCK_SERVER_PORT:8000}"
-}
-```
-
-`host` defaults to `127.0.0.1`, `port` to `3000`. The CLI reads this
-section; the programmatic API ignores it (you pass `listen({ host,
-port })` directly).
-
-## `basePath`
-
-```jsonc
-"basePath": "/api/v1"
-```
-
-Automatically prepended to every `endpoints` key that does NOT start
-with `/` after the method. Must start with `/` and must not end with
-`/`. OpenAPI paths are left untouched — they already carry their full
-path in the OAS document.
-
-```jsonc
-"endpoints": {
-  "GET products/list": "./src/list.js",  // → /api/v1/products/list
-  "GET /health":              "./src/health.js" // → /health (absolute)
-}
-```

package/docs/config/validation.md

@@ -1,161 +0,0 @@
-# `validation`
-
-Opt-in inbound request validation against the OpenAPI document.
-Disabled by default — when `validation` is omitted or
-`validation.request !== true`, `server.fetch(Request)` is
-byte-identical to the no-validation behaviour.
-
-```jsonc
-"validation": {
-  "request": true,        // master switch; default false
-  "maxBodyBytes": 102400  // default 100 KB (matches express body-parser)
-}
-```
-
-Source: `src/types.ts:Config.validation`,
-`src/middleware/request-validation.ts`,
-`src/validation/validate.ts`.
-
-## Field reference
-
-### `validation.request` (boolean)
-
-Master switch. Default `false`. When `true`, every inbound request
-is matched against the OAS document and runs through the
-build-time-compiled validators below before reaching the
-dispatcher. Routes outside the OAS (hand-written `endpoints` keys
-that have no matching OAS path) are passed through unchanged — the
-validator has no contract to enforce.
-
-### `validation.maxBodyBytes` (number)
-
-Hard cap on the JSON request body size, measured in **UTF-8 bytes**
-(not JS string length). Default `102400` (100 KB) — matches
-express's body-parser default. Bodies above the cap are rejected
-with `413 Payload Too Large` before `JSON.parse` runs. Raise only
-if the OpenAPI document genuinely declares large request bodies.
-
-Source: `src/middleware/request-validation.ts:42-46`,
-`:300-380`.
-
-## Validation pipeline
-
-For every matching route (built once at server-creation,
-re-used per request) the validator runs four steps in order:
-
-1. **Security gate** — if the OAS declares a `security` block on
-   the operation (or globally), at least one requirement must be
-   satisfied. Failure → `401` with a `WWW-Authenticate` challenge.
-   Schemes recognised: `http` (presence-only `Authorization: <scheme> …`
-   match), `apiKey` (`in: header | query`; cookie schemes are
-   ignored), `oauth2`, `openIdConnect` (presence-only
-   `Authorization` check; full token introspection is out of scope
-   for a zero-dep mock — layer it via `hooks.onRequest` if needed).
-2. **Content-Type guard** — for routes whose `requestBody.content`
-   declares only `application/json`, requests with a non-JSON
-   `Content-Type` are rejected with `415`.
-3. **Body parse + validate** — the body is read once, capped at
-   `maxBodyBytes`, then `JSON.parse`-d. Parse failure → `400`. Any
-   schema violations are collected as `Violation[]` and emitted in
-   the `422` response. **Body validation is strict** — no type
-   coercion. A JSON `"42"` will not satisfy a schema with
-   `type: integer`.
-4. **Param validation (with coercion)** — query, path, and header
-   parameters arrive as strings on the wire and are coerced
-   (`integer`, `number`, `boolean`) before validation. Required
-   params missing from the request emit a `required`-keyword
-   violation. Cookie parameters are ignored.
-
-Source: `src/middleware/request-validation.ts:300-460`.
-
-## RFC 7807 problem-detail response
-
-All rejections use `Content-Type: application/problem+json` and the
-shape:
-
-```json
-{
-  "type": "https://github.com/ochairo/databehave/blob/main/docs/errors/<slug>.md",
-  "title": "Request validation failed",
-  "status": 422,
-  "detail": "request validation failed (3 violations)",
-  "violations": [
-    { "path": "/body/items/0/sku", "keyword": "minLength", "message": "..." },
-    { "path": "/query/page",       "keyword": "minimum",   "message": "..." },
-    { "path": "/header/x-id",      "keyword": "required",  "message": "..." }
-  ]
-}
-```
-
-Source: `src/middleware/request-validation.ts:24-50` (slug map +
-title map), `:240-280` (envelope builder).
-
-| Status | `title` | `type` slug |
-| --- | --- | --- |
-| `400` | `Malformed request` | `malformed-body` |
-| `401` | `Unauthorized` | `unauthorized` |
-| `413` | `Payload too large` | `payload-too-large` |
-| `415` | `Unsupported media type` | `unsupported-media-type` |
-| `422` | `Request validation failed` | `request-validation` |
-
-`violations` is omitted when empty (e.g. on `400` / `415` / `413`).
-The `Violation` shape (`{ path, keyword, message }`) is documented
-in `src/validation/validate.ts:Violation`. Each `path` is a
-JSON-Pointer rooted at one of `/body`, `/query/<name>`, `/path/<name>`,
-or `/header/<name>`.
-
-## Validator scope
-
-The hand-rolled validator is intentionally a JSON-Schema **subset**
-(audit-it-yourself: ~600 LoC, zero dependencies). Supported
-keywords: `type`, `enum`, `required`, `properties`,
-`additionalProperties`, `items`, `pattern`, `minLength`,
-`maxLength`, `minimum`, `maximum`, `exclusiveMinimum`,
-`exclusiveMaximum`, `minItems`, `maxItems`, `$ref`
-(intra-document only — `#/components/schemas/...`), `oneOf`,
-`anyOf`, `allOf`, `discriminator`, `format` (`date`, `date-time`,
-`email`, `uuid`, `uri`), and `nullable` (OAS 3.0) /
-`["X","null"]` (OAS 3.1).
-
-Unsupported keywords are **rejected at server-start, not runtime**:
-`if`, `then`, `else`, `dependentSchemas`, `dependentRequired`,
-`unevaluatedProperties`, `unevaluatedItems`, `contentEncoding`,
-`contentMediaType`, `propertyNames`, `patternProperties`, and
-remote (`http://…` / `https://…`) `$ref`. The same set is rejected
-by the auto-schema translator (single source of truth on JSON
-Schema parity).
-
-Source: `src/validation/validate.ts:51-58` (unsupported set),
-`:21-44` (supported set; mirrored in
-`src/openapi/translate.ts`).
-
-## Security guarantees
-
-The validator is built to be hostile-input safe:
-
-- **No `eval`, no `new Function`, no dynamic `require`** — pure
-  recursion (`src/validation/validate.ts:18-23`).
-- **Prototype-pollution guard** — input objects whose own keys
-  include `__proto__` / `constructor` / `prototype` are rejected as
-  per-property violations (`:50-56`).
-- **ReDoS mitigation** — `pattern` length capped at 1024 chars;
-  invalid regexes rejected at build time, never request time
-  (`:42`).
-- **Recursion depth cap 64** — both schema build (`$ref` cycles)
-  and `deepEqual` (used to compare against `enum` choices)
-  (`:38-41`).
-
-## Cross-references
-
-- Symptoms and diagnosis: [../troubleshooting.md](../troubleshooting.md).
-- Verbatim error catalogue (status mapping, `WWW-Authenticate`,
-  parser errors): [../errors.md](../errors.md).
-- Which OAS keywords each pipeline accepts:
-  [../openapi/keywords.md](../openapi/keywords.md).
-- Trust model for OAS-author input (the validator's caps are part
-  of it): [../openapi/fallback.md#trust-model](../openapi/fallback.md#trust-model).
-- Bypass via custom handlers: a hand-written `endpoints` route
-  receives the raw `Request` (post-security, post-content-type,
-  post-body checks unless you opt out at the route level — but the
-  route is still part of the validation universe). To skip
-  validation entirely for a route, omit it from the OAS document.