# ADR: The Web API document is checked against the running daemon

- **Status:** Accepted
- **Date:** 2026-11-03
- **Related:** [Code documentation → Mechanical checks](/docs/contributing/code-documentation/index.md#mechanical-checks-ci),
  [CI → Web API contract](/docs/contributing/ci/index.md#web-api-contract),
  [CI → Coverage](/docs/contributing/ci/index.md#coverage)

## Context

The Web API reference is generated from the daemon's types and route
declarations (utoipa), and tests keep the document complete: every body
names a schema, every property and body carries an example, every error
response shows its body, and every example validates against its schema.
Two things stayed unchecked. A route's `#[utoipa::path]` declaration is a
hand-written list of statuses and bodies, so a handler can answer a status
the route does not declare, or a body of another shape, and nothing fails.
And an example is a value someone wrote, so it can describe a response the
daemon never produces. Reviewers caught both kinds by hand while the
examples were added, which is the sign a test should do it.

Three ways to close the gap were weighed: validating examples against
schemas (cheap, deterministic, but blind to what handlers do), checking
real responses against the document inside the tests (catches declaration
drift wherever a test reaches, blind where none does), and generating the
examples from recorded responses (the end state, but it needs the second
check's coverage first, plus stable rewrites of ids, times and paths and a
screen for secrets).

## Decision

1. Examples are validated against their schemas in the daemon's test
   suite (`every_example_matches_its_schema`): every example, on a
   schema, a property or a body, must validate against the schema it
   illustrates, references followed and formats asserted.
2. The daemon's test build layers a check over its router that compares
   every response the tests produce with the document: the matched route,
   the method, the status and the media type must be declared, and a JSON
   body must validate against the declared schema. The layer records each
   response, and CI Gate reports how many declared responses the tests
   observed and every disagreement. The layer is compiled only into the
   test binary; the daemon's own router does not change.
3. The report was informational first. With the disagreements the first
   report found fixed, a disagreement fails CI Gate and the observed share
   has a floor that only rises (`[contract] floor` in
   `scripts/coverage_areas.toml`), the way the coverage floors do; the
   floor is not checked when a selective run did not test the daemon.
4. Examples stay hand-written. Generating them from recorded responses is
   deferred until the observed share is high enough that recordings would
   replace most of them; a recording then replaces an example route by
   route, with the hand-written one kept until a recording exists.

## Consequences

- A handler that answers a status or body its route does not declare is
  listed in CI Gate's summary, by method, route, status, media type and
  the validator's message, as soon as a test exercises it, and fails
  CI Gate.
- Refusals a layer produces before any handler runs (the access layers'
  `401` and `403`, the second-factor enrollment `403`, CSRF, the timeout)
  are stated by the document builder for every route they apply to, so
  the first test that meets one on a new route does not fail the gate.
- A route no test reaches is invisible to the layer. The report's
  observed share makes that visible, and the floor keeps it from shrinking.
- The checks add one dev-dependency (`jsonschema`) to the daemon and one
  file per test process under `target/contract-report`, kept with the
  coverage reports in CI.
- Responses the tests buffer for validation are read once more; the test
  build is slower by that much, the daemon is not.
