# ADR 0002: Pagination is declared as an audited discriminated union, not inferred

- Status: accepted
- Date: 2026-08-06 (carried over 2026-09-06)

## Context

Before this, pagination was reinvented per client. One backend matched a page parameter by the literal name `page_num` and then sniffed `totalPage`, `totalPageNum`, `data.totalPage` and empty lists at runtime to decide when to stop. Others shipped no iterator at all; one client's own ledger recorded eleven paginated endpoints with nothing generated for them. A survey across roughly 750 endpoints found the ad hoc shapes in use clustered into a small number of families: page number, opaque token, offset plus limit, a time window, and a cursor read off the last row.

## Decision

`pagination` is an optional field on the endpoint, a sibling of `spec` rather than part of the request schema, typed as a discriminated union on `strategy`: `page`, `token`, `offset`, `window`, `seek`. Each strategy is a closed model. A field borrowed from another strategy (a `cursor` under `strategy: page`) fails to load rather than being silently ignored.

A declared block is checked, not trusted. `truewire check` verifies that every parameter it names is a real request parameter, that the parameters a walk does arithmetic on (`page`'s index, `offset`'s offset, `window`'s two bounds) are numerically typed, that every response path it names (`done.path`, `done.rows`, `cursor.from`) resolves against the response schema, and that a terminator only appears alongside the declarations it needs (`short_page` needs a `size` to be short relative to). The audit judges only a declaration that is present. An endpoint with no block is never flagged for lacking one, because that would resurrect the name-sniffing this replaces, just moved into the checker.

A declared block generates. The Python generator turns it into a `<method>_paged` variant beside the single-request method. Where the strategy can compute `(rows, next_state)` per page, the variant is a `PaginatedResponse`: usable both as `async for page in ...` and as `await ...` for the flattened rows.

Each strategy admits only the terminators it can decide: `page` and `offset` take `total`, `short_page` or `empty`; `token` takes `absent_cursor` or `empty`; `seek` takes `short_page`, `empty` or `unchanged`; `window` takes `empty` alone, plus the caller's own far bound. A `window` with a declared `size` also gets a runtime guard: a page as full as the requested size means the venue likely truncated it, so the walk raises rather than silently skipping rows, unless the caller passes `allow_truncation=True`.

## Consequences

Declaring the model surfaced two real bugs a heuristic never would have: a window's advance and its terminator disagreeing on step size when `size` was omitted, and a truncation guard that read `size is not None` and stayed silent on the common call that omits `limit` entirely. Both were fixed by making the declaration, not the generated code, the place that states the default.

Response paths admit a narrow grammar: dotted keys and bracket integer indices (`data.totalPage`, `[-1].id`, `list[-1][0]`), nothing more. No wildcards, no slices, no JSONPath. That grammar was refused entirely at first and widened once `seek` and `window` over positional rows made the gap impossible to route around; it stays deliberately small.

Left open: bound inclusivity and sort order are facts about the API, not about the spec. Nothing in a declaration states either, so a wrong `step` or `order` reads as a clean spec and shows up as a duplicated or missing row at runtime. Establish both by calling the endpoint before declaring it. See `docs/spec/authoring.md` rule 8.