@databehave/server 0.1.1 → 0.1.2

package/docs/openapi/fallback.md

@@ -1,242 +0,0 @@
-# OpenAPI fallback
-
-Paths declared in the OpenAPI document but absent from `endpoints` are
-auto-served by the walker. **Hand-written routes always win** — the
-walker silently skips any key already declared in `endpoints`. There
-is no precedence flag; the OAS doc is the source of truth for *gaps*,
-not for overrides. This rule is canonical here; other pages link back.
-
-This is intentional. The OAS document is your spec; @databehave/server treats it
-as the source of truth for *gaps*, not as an override.
-
-## Input format
-
-@databehave/server accepts **JSON** OpenAPI documents only — convert
-YAML first via `yq -o=json openapi.yaml > openapi.json` and pass the
-JSON path or string to the loader. YAML inputs are rejected at boot;
-see [config/openapi.md](../config/openapi.md) for the canonical
-error wording.
-
-A leading UTF-8 byte-order mark (`U+FEFF`) is stripped before parsing,
-so files exported from Windows tooling load without manual cleanup.
-After BOM stripping, the input must parse as plain JSON or
-`JSON.parse` raises (caught and re-thrown with the file path
-prepended).
-
-## Pipeline
-
-```bash
-openapi.json ─▶ parser ─▶ paths.<p>.<m> ─▶ walker ─▶ generateFromOasSchema ─▶ response
-                                       │
-                                       ├─▶ onOpenApiWalkError   (recoverable)
-                                       └─▶ onOpenApiEmptySchema (advisory)
-```
-
-The walker visits every `paths.*.<method>.responses['200'].content
-['application/json'].schema` and feeds the OAS node to the in-server,
-zero-dep generator (`src/openapi/generate.ts`), which produces a
-deterministic placeholder JSON value. For non-200 responses (used by
-`mockMode`), the same generator feeds the per-status body builders.
-For richer mock data (distributions, datasets, FK-aware generation),
-install `@databehave/schema` separately and pre-generate fixtures —
-the server itself pulls no DSL dependency at runtime.
-
-### What the walker visits
-
-- `paths['/']` (root) is **skipped**. Use an explicit `endpoints`
-  entry if you need to serve `/`.
-- HTTP methods walked are exactly `get`, `post`, `put`, `delete`,
-  `patch`. `head` and `options` are handled by the dispatcher
-  (HEAD auto-derives from GET; OPTIONS is owned by CORS / admin).
-- Vendor extensions (`x-*` keys) on path items are ignored.
-- The OAS-only generator (`src/openapi/generate.ts`) is **not**
-  depth-capped; cyclic `$ref`s are detected via a visited-pointer
-  set and collapse to `{}` rather than infinite-loop. The
-  auto-schema translator and the request validator both hard-cap
-  recursion at **64** levels of nested `properties` / `items` /
-  `allOf` / `oneOf` / `anyOf` and **fail loud** past that — see
-  [`keywords.md` → Auto-schema translator](./keywords.md#auto-schema-translator-schema-set)
-  and [`config/validation.md#security-guarantees`](../config/validation.md#security-guarantees).
-  Hit either in practice → flatten the schema or declare the
-  route in `endpoints` directly.
-
-### Status code picked
-
-For mock-mode passthrough (no override) the walker picks the
-response body from `responses['200']`. For mock-mode injected
-statuses, the body comes from the smallest `2xx` declared in the
-spec when an exact match is missing, falling back to the OAS
-`default` response, falling back to the envelope
-`{ error: true, status: N }`. `204` always renders as an empty
-body regardless of what the spec declares.
-
-### Per-status body generators
-
-`buildOpenApiResponseGenerators(doc)` exposes the per-status body
-table the dispatcher uses internally — keyed by `"METHOD path"`,
-each entry maps a status code to a memoised body generator. The
-function is exported so consumers wiring mock-mode into a custom
-dispatch can reuse the same body shapes the kit ships with. See
-[../config/mock-mode.md#body-resolution](../config/mock-mode.md#body-resolution)
-for how the dispatcher consumes the table.
-
-## Deterministic seeds
-
-For a route `/users/:id` matched against `/users/42?expand=profile`:
-
-```text
-seed = sha256(
-  '/users/:id'                        // @databehave/server pattern, not the live URL
-    + '|param:id=42'                  // path params first (sorted)
-    + '|expand=profile'               // query params (sorted)
-)
-```
-
-Same URL → same JSON body, byte-for-byte, on every machine. This is
-what makes snapshot tests stable across CI runs.
-
-Per-status bodies use `endpoint|status` as the seed, so the 500 body
-for `/users/:id` is stable but different from the 404 body.
-
-## Empty / permissive schemas (`schema: {}`)
-
-```jsonc
-{
-  "/api/v1/anything": {
-    "get": {
-      "responses": {
-        "200": {
-          "content": {
-            "application/json": {
-              "schema": {}   // ← "any JSON value" per JSON Schema
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-Per JSON Schema spec this matches any value, so @databehave/server:
-
-1. Does **not** raise this via `onOpenApiWalkError` — it is a valid
-   OAS construct.
-2. Serves a small stub body (`{}` for GET, `{ success: true, message:
-   null }` for mutations).
-3. Surfaces the gap via the dedicated `onOpenApiEmptySchema` callback
-   so you can fix the spec.
-
-The default JSONC loader wires this to a friendly warning:
-
-```text
-[@databehave/server] OAS response schema is empty for GET /api/v1/anything (status 200)
-        — serving stub. Consider filling the schema in your OpenAPI document.
-```
-
-To handle it yourself programmatically:
-
-```ts
-createServer({
-  openapi: doc,
-  onOpenApiEmptySchema: (method, path, status) => {
-    metrics.increment('@databehave/server.empty_schema', { method, path, status })
-  },
-})
-```
-
-## Walker failures
-
-When the walker hits an OAS construct it genuinely cannot translate
-(unsupported keyword, unresolvable `$ref`, etc.), it falls back to a
-stub and reports via `onOpenApiWalkError`:
-
-```text
-[@databehave/server] openapi walk failed for GET /api/v1/weird: $ref not found: #/components/schemas/Missing
-```
-
-The route stays usable (the stub body keeps clients happy) but the
-gap is visible. The JSONC loader wires this to `console.warn` by
-default; override with:
-
-```ts
-createServer({
-  openapi: doc,
-  onOpenApiWalkError: (method, path, err) => {
-    // Fail CI on any walker error:
-    throw err
-  },
-})
-```
-
-## Skipping OAS-declared routes
-
-Routes that exist in `endpoints` (hand-written or static) are
-automatically skipped by the walker — no extra configuration needed.
-This is the recommended way to override an OAS path: declare it in
-`endpoints` and the walker leaves it alone.
-
-If you need to skip an OAS path without declaring a replacement
-(e.g. a deprecated endpoint), declare it as an `EndpointResponse`
-returning the deprecation message:
-
-```jsonc
-"endpoints": {
-  "GET /api/v1/legacy": {
-    "response": {
-      "status": 410,
-      "json": { "error": "gone", "message": "Use /api/v2/replacement" }
-    }
-  }
-}
-```
-
-## Trust model
-
-@databehave/server assumes the OpenAPI document comes from a **trusted source**
-(your own repo, your own build pipeline). The walker passes `pattern` fields
-straight to `new RegExp(...)` and that compiled regex is consulted by
-`parse()` on incoming request bodies. A hostile OAS author could therefore
-supply a catastrophic-backtracking pattern (e.g. `(a+)+b`) that would slow
-down request validation against attacker-controlled input.
-
-Mock-body generation (`mock()`) does **not** evaluate the regex, so simply
-*loading* a hostile OAS is safe — but if you also turn on request-body
-validation in front of untrusted input, validate or sandbox patterns from
-untrusted OAS docs before passing them in.
-
-### `pattern` requires a `maxLength` sibling
-
-To make this concrete, the generator refuses to mock a string node
-that declares a `pattern` without a `maxLength`. The boot-time error
-is:
-
-```text
-@databehave/server/openapi: pattern at <pointer> requires a sibling maxLength to bound generation (ReDoS guard)
-```
-
-This is a hard guard, not a warning — fixing the OAS to add a
-sensible `maxLength` is required before the kit will boot. The same
-guard fires on nested string nodes, e.g. `items.pattern` inside an
-array.
-
-The `pattern` source itself is also length-capped at **1024
-characters** in both the auto-schema translator and the request
-validator. A pattern longer than the cap is rejected at boot with:
-
-```text
-@databehave/server/openapi: pattern length <N> exceeds cap of 1024 (ReDoS guard) (at <pointer>)
-```
-
-The cap exists because regex engines have super-linear behaviour on
-sufficiently long pathological patterns even with `maxLength`-bounded
-input — capping the pattern source is the cheap belt-and-braces.
-
-## Admin route picker
-
-The OAS document is also consumed by the admin panel. When
-`admin.enabled`, the kit serves `GET {admin.path}/openapi-routes`
-which returns `{ routes: { method, path, summary }[], discoveredAt }`
-derived from the same OAS doc the walker uses. The admin UI calls this
-endpoint to populate its route picker — no separate spec is needed.
-See [../admin/rest-api.md](../admin/rest-api.md).

package/docs/openapi/keywords.md

@@ -1,78 +0,0 @@
-# Supported OAS keywords
-
-The kit ships **two** OAS readers and they support different
-keyword sets. Pick the one that matches your config:
-
-- The **OAS-only generator** runs by default — when `schema:` is
-  absent from `databehave.jsonc`. Zero-dep, conservative subset.
-- The **auto-schema translator** runs when `schema:` is set. Lifts
-  the OAS into the `@databehave/schema` IR, so it accepts a wider
-  keyword set and can fail loudly on constructs it cannot model.
-  See [auto-schema.md](./auto-schema.md).
-
-## OAS-only generator (default)
-
-```text
-$ref ……………… resolved against components.schemas
-              circular refs collapse to {} (recursion guard)
-type: 'object'  properties + required
-type: 'array'   items
-type: 'string'  + minLength / maxLength / pattern (with maxLength sibling — see fallback.md)
-type: 'integer' + minimum / maximum
-type: 'number'  + minimum / maximum
-type: 'boolean'
-enum            string enums sampled from the list, deterministically
-const           literal value emitted verbatim
-allOf           merged left-to-right
-oneOf           first branch picked deterministically
-anyOf           first branch picked deterministically
-nullable: true  string types may emit null
-```
-
-`format` **is** consumed for the five common cases:
-
-| `format`     | Emitted value |
-| ------------ | --- |
-| `date`       | `"2024-01-01"` |
-| `date-time`  | `"2024-01-01T00:00:00Z"` |
-| `email`      | `"user@example.com"` |
-| `uuid`       | `"00000000-0000-4000-8000-000000000000"` |
-| `uri` / `url`| `"https://example.com/"` |
-
-Any other `format` falls through to the bare-type default
-(`"string"`, `0`, `false`, …). File an issue if you need
-format-aware sampling beyond this list.
-
-## Auto-schema translator (`schema:` set)
-
-The translator (`translateOasToIR` in `src/openapi/translate.ts`)
-accepts everything the OAS-only generator does, plus:
-
-- `format`: `date`, `date-time`, `email`, `uuid`, `uri`, `url`.
-- `nullable: true` (lifts the IR node to `union(t, null)`).
-- `minLength`, `maxLength`, `pattern` (passed through).
-- `exclusiveMinimum`, `exclusiveMaximum` (boolean OAS-3.0 form
-  and numeric OAS-3.1 form both accepted).
-- `minItems`, `maxItems`.
-- `discriminator` on `oneOf` / `anyOf` (resolves to the right
-  branch when the input has the discriminator property).
-- `additionalProperties` (boolean and schema-shaped both honoured).
-- `example` / `examples` (first usable value picked when present).
-
-### Unsupported — fail loud
-
-The translator refuses these keywords at boot rather than silently
-dropping them. The error wording is
-`@databehave/server: translateOasToIR failed for <route> responses[<status>]: unsupported keyword <name>`:
-
-- `if` / `then` / `else`
-- `dependentSchemas`, `dependentRequired`
-- `unevaluatedProperties`, `unevaluatedItems`
-- `propertyNames`
-- `patternProperties`
-- `contentEncoding`, `contentMediaType`
-- Remote `$ref` (anything not under `#/components/schemas/...`)
-
-The fail-loud list is intentionally short — the goal is to expose
-gaps in the IR, not silently drift away from the spec. File an
-issue if you hit one and need it modelled.

package/docs/recipes.md

@@ -1,258 +0,0 @@
-# Recipes
-
-Practical patterns for common mocking problems. Each example is
-self-contained and runnable against the public surface.
-
-## Static health endpoint
-
-```jsonc
-"endpoints": {
-  "GET /health": {
-    "response": {
-      "status": 200,
-      "json":   { "ok": true }
-    }
-  }
-}
-```
-
-No handler module to write, no OAS entry needed. Add the path to
-`mockMode.healthPaths` so `mockMode` does not inject an error status
-into your probes:
-
-```jsonc
-"mockMode": {
-  "enabled": true,
-  "healthPaths": ["/health"]
-}
-```
-
-## Force a single endpoint to 500
-
-```jsonc
-"endpoints": {
-  "POST products/bulk-update": {
-    "handler": "./src/routes/bulk-update.js",
-    "status": 500
-  }
-}
-```
-
-The handler still loads (and stays valid for tests that call it
-directly), but live HTTP requests get a 500 with the OAS-derived
-error body. To remove the override, delete the `status` field.
-
-## Force every endpoint to 500 (chaos mode)
-
-```jsonc
-"mockMode": {
-  "enabled":       true,
-  "defaultStatus": 500,
-  "healthPaths":   ["/health"]
-}
-```
-
-Health probes pass through, everything else returns 500 with the
-OAS-derived error body. Useful for client-side error-path testing.
-
-## In-process testing with `fetch()`
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { createServer } from '@databehave/server'
-import { loadConfig } from '@databehave/server'
-
-describe('mock server', () => {
-  it('serves the OAS-derived east inventory', async () => {
-    const { config } = await loadConfig('./databehave.jsonc')
-    const server = createServer(config)
-
-    const res = await server.fetch(
-      new Request(
-        'http://localhost/api/v1/products/list?date_from=2024-01-01',
-      ),
-    )
-
-    expect(res.status).toBe(200)
-    expect(res.headers.get('x-mock-status')).toBe('200')
-    const body = await res.json()
-    expect(body).toHaveProperty('result')
-  })
-})
-```
-
-No sockets, no `listen()`. The same `Request` URL always yields the
-same JSON body — assert against it directly or use a snapshot.
-
-## Auth short-circuit via `hooks.onRequest`
-
-```ts
-import { createServer } from '@databehave/server'
-
-const server = createServer({
-  routes: { /* ... */ },
-  hooks: {
-    onRequest: (req) => {
-      if (req.headers.authorization !== 'Bearer test-token') {
-        return { status: 401, json: { error: 'unauthorized' } }
-      }
-      // returning void → continue to the route handler
-    },
-  },
-})
-```
-
-The handler is never reached for requests without the token. Pair
-with `mockMode.healthPaths` if you want probes to bypass auth.
-
-## Inject a header on every response
-
-```ts
-createServer({
-  routes: { /* ... */ },
-  hooks: {
-    onResponse: (_req, res) => ({
-      ...res,
-      headers: { ...(res.headers ?? {}), 'x-build-id': process.env.BUILD_ID ?? 'local' },
-    }),
-  },
-})
-```
-
-`onResponse` runs after the handler but before the runtime adapts the
-POJO into a web `Response`.
-
-## Generate deterministic bodies with `databehave`
-
-```ts
-// src/routes/products/list.ts
-import { mock, obj, str, decimal, arr, seedFor } from '@databehave/server'
-import type { Handler } from '@databehave/server'
-
-const Product = obj({
-  category: str().in(['books', 'movies']),
-  price:    decimal(10, 2).min('0').max('1000').typically(400, 700),
-})
-
-const Body = obj({ result: arr(Product).length(48) })
-
-const handler: Handler = (req) => {
-  const seed = seedFor({
-    endpoint: '/api/v1/products/list',
-    extra: Object.fromEntries(new URL(req.url).searchParams),
-  })
-  return { json: mock(Body, { seed }) }
-}
-
-export default handler
-```
-
-Same URL → same body. `databehave` is re-exported from `@databehave/server` so a
-single import covers schema authoring and server wiring.
-
-## Per-variant sub-routes (one handler each — no shared helpers)
-
-When granularity matters, write each endpoint as a separate handler
-with its own seed namespace. Do **not** extract a helper that loops
-over variants — you lose the ability to tune `min` / `max` / `typically`
-per endpoint without disturbing the others.
-
-```jsonc
-"endpoints": {
-  "GET products/list":  "./src/routes/products/list.js",
-  "GET products/featured":  "./src/routes/products/featured.js",
-  "GET products/summary": "./src/routes/products/summary.js"
-}
-```
-
-Each handler controls its own `min` / `max` / `typically` ranges
-independently.
-
-## Custom CORS origin reflector
-
-The JSONC form mirrors the request `Origin` by default. To customise:
-
-```ts
-createServer({
-  routes: { /* ... */ },
-  cors: {
-    origin: (o) => (o.endsWith('.example.com') ? o : 'https://app.example.com'),
-    credentials: true,
-    exposeHeaders: ['x-mock-status'],
-  },
-})
-```
-
-## Bind to a random port in tests
-
-```ts
-const server = createServer(config)
-const { port, close } = await server.listen({ port: 0 })
-
-// ... run tests against http://127.0.0.1:${port} ...
-
-await close()
-```
-
-`port: 0` asks the OS for a free port; the actual port comes back in
-the handle.
-
-## Inject a 503 on every route via the admin REST API
-
-Enable `admin` (see [admin.md](./admin.md)), then POST a global
-sticky override. Every subsequent request returns 503 until cleared.
-
-```sh
-curl -sS -X POST http://127.0.0.1:8000/databehave/overrides \
-  -H 'content-type: application/json' \
-  -d '{"matcher":{"kind":"global"},"mode":{"kind":"http-status","status":503}}'
-
-curl -sS -X DELETE http://127.0.0.1:8000/databehave/overrides   # clear
-```
-
-## Replay a captured response as a custom-body override
-
-Paste a real response payload as base64 JSON into a sticky `custom-body`
-override; the mock returns it verbatim, with the status of your choice.
-
-```sh
-BODY_B64=$(printf '{"result":[{"id":1,"name":"replayed"}]}' | base64)
-curl -sS -X POST http://127.0.0.1:8000/databehave/overrides \
-  -H 'content-type: application/json' \
-  -d "{\"matcher\":{\"kind\":\"exact\",\"method\":\"GET\",\"path\":\"/api/v1/products/list\"},
-       \"mode\":{\"kind\":\"custom-body\",\"status\":200,\"body\":$(echo "$BODY_B64" | base64 -d)}}"
-```
-
-## Simulate slow networks with a sticky delay
-
-A `delay` override wraps another mode (or passthrough). 3 seconds is
-enough to exercise loading indicators without a test timing out.
-
-```sh
-curl -sS -X POST http://127.0.0.1:8000/databehave/overrides \
-  -H 'content-type: application/json' \
-  -d '{"matcher":{"kind":"global"},"mode":{"kind":"delay","ms":3000}}'
-```
-
-## Save and load named scenarios
-
-Snapshot the current sticky overrides under a name, then re-apply later
-in one step.
-
-```sh
-curl -sS -X POST http://127.0.0.1:8000/databehave/scenarios \
-  -H 'content-type: application/json' -d '{"name":"all-503"}'
-
-curl -sS -X POST http://127.0.0.1:8000/databehave/scenarios/all-503/load
-# → {"loaded":1}
-```
-
-Scenarios live on disk under `admin.scenariosDir` (default
-`${cwd}/mock-scenarios`). See [admin.md](./admin.md#scenarios).
-
-## Enable per-request access logs
-
-Set `"log": true` (shorthand for `{ "access": true }`) to emit one
-stdout line per request, with override-tag suffixes such as
-`[override:http-status]`. Full field reference, JSON format, and
-admin-traffic toggle live in [config/log.md](./config/log.md).

package/docs/stability.md

@@ -1,118 +0,0 @@
-# Stability Contract
-
-This document defines what `@databehave/server` guarantees across versions, in
-addition to the contract inherited from
-[`@databehave/schema`](../../schema/docs/stability.md).
-
-## Public surface
-
-The **public surface** is exactly the symbols re-exported from `src/index.ts`,
-plus the runtime shape of `Config` and the JSONC config schema
-accepted by `loadConfig`. Anything reachable only through
-deeper paths (`@databehave/server/src/...`, `_internal`, identifiers prefixed with
-`_`) is **internal** and may change in any release, including `PATCH`.
-
-The set of public symbols is locked by `test/public-surface.test.ts`.
-
-The `admin` admin REST endpoints (`/overrides`, `/scenarios`,
-`/openapi-routes`, `/ui*`) and their request / response shapes are part
-of the public surface; the versioning rules below apply to them too.
-
-## Versioning rules
-
-Same `PATCH` / `MINOR` / `MAJOR` rules as `@databehave/schema` apply, plus:
-
-| Bump      | Additional triggers for `@databehave/server`                                                                                                         |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **PATCH** | Wire-level behaviour of `fetch(Request) → Response` for handlers that previously returned identical bodies. Header casing fixes.                  |
-| **MINOR** | New CORS options, new mock-mode hooks, new JSONC fields with backwards-compatible defaults. Additive `admin` admin REST endpoints, additive fields on admin request / response shapes, new `x-mock-*` headers. |
-| **MAJOR** | Default CORS policy changes that may close previously-permitted requests. Removal or renaming of JSONC fields. Changes to OAS path dispatch order. Removal / renaming of admin REST endpoints, breaking admin request / response shape changes, removal / renaming of `x-mock-*` headers, changes to sticky-override resolution priority. |
-
-## Determinism contract
-
-For a fixed config (`Config`, JSONC, OAS document) and a fixed
-request, the **response body** generated by @databehave/server is deterministic
-across `PATCH` and `MINOR` releases. The same per-request seeding rules
-documented in `docs/seeding.md` apply.
-
-## Mock-mode dispatch order
-
-Within a single config, mock-mode resolves the response status and body in
-this order, in this priority (first match wins):
-
-1. Explicit `pathOverrides` entry keyed by `'<METHOD> /path'` (concrete path).
-2. Explicit `pathOverrides` entry keyed by `'/path'` (any method).
-3. Per-endpoint `status` set in JSONC `endpoints`.
-4. `mockMode.defaultStatus` (when set).
-
-Body resolution, once a status is chosen, follows this priority:
-
-1. Hand-written handler body (when registered for the route).
-2. OAS `responses[N]` schema match by **specificity**:
-   1. Static path patterns (`/items/me`) before parametric (`/items/:id`).
-   2. Within the same kind, longer paths before shorter wildcards.
-   3. Lexical fallback for ties (deterministic, declaration-order
-      independent).
-3. Generic envelope `{ error: true, status: N }`.
-
-This order is part of the public contract; changes are `MAJOR`.
-
-## CORS defaults
-
-- `cors: undefined`            → no CORS headers added (handlers fully control).
-- `cors: {}`                   → permissive default for **mock development**:
-  `Access-Control-Allow-Origin` mirrors the request `Origin` (or `*` if absent).
-  This is intentionally lax because @databehave/server is a developer mock server.
-- `cors: { origin: ... }`      → strict; the resolver function is authoritative.
-- `cors: { allowHeaders: [] }` → hard lockdown; preflight omits the header.
-
-When a deployment must run on a network where third parties can reach the
-mock server, set `cors: { origin: '...' }` explicitly. The README documents
-this.
-
-## Fail-loud policy
-
-Configuration that is structurally valid but semantically nonsensical throws
-at config-load time, not at request time. Examples already enforced:
-
-- `pathOverrides` keys that do not start with `/` or `<METHOD> /`.
-- `pathOverrides` values that are not numbers.
-- OpenAPI documents that fail to parse as JSON (convert YAML first via `yq -o=json`).
-
-## Logger injection
-
-Every diagnostic the kit emits goes through `LoadConfigOptions.logger.warn`
-(or the equivalent `MockModeConfig.logger`). The kit never calls
-`console.warn` / `console.error` directly. Callers may pipe to their preferred
-sink (pino, winston, structured JSON, /dev/null).
-
-The opt-in `log` feature (top-level `log` config, see
-[config.md](./config.md#log)) is **separate** from diagnostics. It writes
-one line per request to **stdout** by design, is off by default
-(`log: false`), and is intentionally not routed through the logger
-injection hook — access logs and diagnostic warnings have different
-audiences and different destinations. This split is intentional and is
-not a contract violation.
-
-## Admin mode contract
-
-When `admin` is opt-in, the following defaults are part of the
-public contract — changing any default is **MAJOR**:
-
-- `enabled: false`
-- `path: '/databehave'`
-- `bind: 'loopback-only'`
-- `allowDestroy: true`
-- `cors: 'auto'`
-
-Additional rules:
-
-- **`x-mock-*` header semantics.** Adding a new header is **MINOR**.
-  Removing or renaming a header, or changing the ErrorMode kind a
-  header resolves to, is **MAJOR**.
-- **Sticky-override resolution priority.** The order
-  `header > exact > path > global > existing mockMode > passthrough`
-  is part of the contract — changes are **MAJOR**.
-- **Scenarios file format.** Adding new top-level fields to a saved
-  scenario JSON is **MINOR**. Changing the directory layout, the file
-  naming, or the meaning of an existing field is **MAJOR**.