@lovrozagar/oat 0.9.1 → 0.11.0

package/docs/model.md

@@ -0,0 +1,184 @@
+# oat — How oat reads a document
+
+[← back to the overview](../README.md)
+
+## How the model is derived
+
+`oat plan` is this model. Checks never see raw paths; they see entities, actions, and query **roles**.
+
+### Entity name and action
+
+**Explicit:** `x-entity: { name, action, identity? }` on the operation.
+
+**Heuristic** (when the tag is absent):
+
+1. Split the path on `/`. Ignore `{param}` segments.
+2. The last non-parameter segment is the noun. `v1` / `v2` / `vN` is never a noun.
+3. Singularise that noun (`stores` → `store`, `batches` → `batch`). Irregulars include `people→person`, `categories→category`, `campuses→campus`, `statuses→status`, `children→child`, `companies→company`, `addresses→address`, `indices→index`, `queries→query`, `properties→property`, `entities→entity`, `inboxes→inbox`. Endings `us|ss|is|os|as|ics|ews|ess|ous|sis` are left alone (`status` stays `status`).
+4. If a non-parameter segment follows the noun (`/rows/aggregate`, `/tables/{id}/restore`), action is `action`.
+5. Otherwise: `GET` collection → `list`, `GET` item → `read`, `POST` collection → `create`, `POST` item → `action`, `PUT`/`PATCH` → `update`, `DELETE` → `delete`.
+
+If no noun can be found, the operation is untracked and `doctor` records an `x-entity` gap.
+
+`--only` and report entity names are these singular names.
+
+### Identity
+
+`x-entity.identity` wins. Else the first of `id`, `uuid`, `slug`, `key`, `name` that is **required** on the item schema, else the first of those that exists, else the trailing path-param suffix (`{table_id}` → `id`). Without an identity the entity is not trackable.
+
+### Read surface
+
+The set of `GET` routes through which an instance is visible.
+
+- Declared: every `"METHOD /path"` in any `x-invalidate` that refers to this entity.
+- Inferred: sibling collection and item routes on the same path prefix as a mutator.
+
+`invalidation.declared-route-changes` only runs when a mutator's `x-invalidate` names **another** entity's route.
+
+### Generated / immutable / soft-delete / tenant
+
+See [OpenAPI meta tags](tags.md#openapi-meta-tags). Fallbacks:
+
+- `readOnly: true` counts as generated (omitted from create bodies).
+- No immutability testing without `x-immutable`.
+- Tenant param: `x-tenant` or a path param matching `org|organization|tenant|workspace|account|project|app` + optional `_id`/`_slug`. Inferred tenants make a cross-tenant read `AMBIGUITY`, not `SECURITY`. With neither a tag nor an inferred name, the check does not apply.
+
+### Idempotency
+
+No meta tag. If create declares a header matching `Idempotency-Key` / `Idempotence-Key` / `X-Idempotency-Key` (spaces ignored, case-insensitive), `idempotency.replay-does-not-duplicate` runs.
+
+## Seeding
+
+Per entity, oat POSTs the create body built from the request schema (JSON, multipart, or urlencoded).
+
+Default cohort is **7** records, one of each variant, sliced by `cohortSize`:
+
+| variant         | what it is for                                     |
+| --------------- | -------------------------------------------------- |
+| `baseline`      | `"Quarterly Report N"`                             |
+| `lexical-first` | sorts first (`"aaa first alphabetically"`)         |
+| `lexical-last`  | sorts last (`"zzz last alphabetically"`)           |
+| `null-heavy`    | `null` on every nullable field                     |
+| `unicode`       | `"äöüß čćžšđ 日本語 中文 한글 привет مرحبا 🙂"`    |
+| `metacharacter` | `"100% _off_ *everything*"` — LIKE / escape probes |
+| `boundary`      | empty / maxLength / numeric `maximum`              |
+
+Numbers use the ladder `1, 2, 5, 10, 20, 50, 100` so **lexical order ≠ numeric order** (otherwise a TEXT compare looks correct). Enums walk `index % enum.length`. `readOnly` / `x-generated` fields are omitted. Required fields that cannot be generated get a type fallback (`0`, `false`, `[]`, `{}`, `"value"`). Arrays honour `minItems` (never send `[]` when `minItems ≥ 1`). Nested objects stop at depth 4.
+
+Empty schemas (`{}`, `true`, `additionalProperties: {}`) and cyclic `$ref`s after inlining stop the walk — they become a scalar or `{}`, never another object descent. A `RangeError` during generation is a `COVERAGE_GAP` on that entity naming the operationId and JSON pointer (`fixture generation overflow on table.create (/)`), not `blocked by unknown`.
+
+String fields honour `format`, `pattern`, and `minLength` together: `email` → `oat-{variant}-{index}@example.test`, `uri` / `url` → `https://example.test/...`, `uuid` → a fixed-shape UUID, `pattern` → a string that matches (or the field is omitted / the entity is a gap). A generated string is padded to `minLength` (repeat the last character) without breaking `pattern`. `"Quarterly Report N"` is only used when the document does not constrain the string. `minLength` greater than `maxLength` omits an optional field and records `missingRequired` on a required one.
+
+An operation with `x-invite` is not `entity.create`. oat does not POST a generated invitee. The invite check sends `granteeField` = the peer's `inviteAs`. Missing `inviteAs` is a coverage gap naming the tag.
+
+A create whose `operationId` appears in any principal `auth.steps`, or that declares `x-fresh-principal`, is not seeded. Those rows were provisioned by the auth flow.
+
+Parent path parameters are created first (depth-first through the owning entity's create). Config / principal `roots` fill parameters oat cannot create.
+
+A create that returns `>= 300` on the first variant fails the entity (downstream checks `BLOCKED`). Later variants that fail just shorten the cohort — a partial cohort is still used.
+
+HTTP 429 is retried first — `Retry-After` or exponential backoff, up to five times — on seed, checks, and teardown, whether or not the operation declared `x-rate-limit`. The first 429 is never a seed failure. A leftover 429 after those retries is a gap, not a backend defect.
+
+A 402 / plan-limit (`payment_required`, `*_plan_limit`) on create is not a backend defect when the same-tenant list already has a row — typically an earlier `x-effects` create that filled a free-plan quota. oat reuses that id so children (a `row` after extract created a `table`) can still seed. It does not invent records. Write-path checks on the adopted entity stand down.
+
+A documented feature-gate 403 is the exception: if create declares `x-feature-gate` and the body is `vars.type: feature_gate` (and `vars.feature` matches the tag when present), oat records a `COVERAGE_GAP` naming the tag rather than a seed defect. See [`x-feature-gate`](tags.md#x-feature-gate).
+
+When create is tagged `x-unique`, a first-variant seed **409** with a nonempty same-tenant list **adopts** that row (`world.seed` `COVERAGE_GAP` naming `x-unique` — the create could not insert). Unique-conflict checks still run against that row. Write-path oracles that need a body oat submitted stay skipped. 409 with an empty list stays `BLOCKED` (`could not seed`). A 409 without the tag is still today's seed failure. The seed 409 itself is not `create.unique-conflict-rejected` passing — that check is the explicit second POST. See [`x-unique`](tags.md#x-unique). Later variants that 409 only shorten the cohort. Generated values for unique body columns differ across variants (a suffix) without weakening `maxLength` / `pattern`; if the document cannot express two distinct values, oat records a gap and skips extra variants.
+
+`--seed` / `seed` makes the bodies identical across runs. It does not make server-assigned ids identical.
+
+Teardown DELETEs created rows (or the `x-cleanup` route) newest-first. Failures and missing delete routes are printed as leftovers, not as check findings. `keepFixtures: true` skips this.
+
+## Query roles and grammars
+
+Checks do not look for a parameter _named_ `filter`. They resolve **roles** from aliases, then write values in the grammar the document demonstrates.
+
+| role              | aliases (normalised: case, `_` / `-`, `perPage` → `per_page`)                       |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| filter            | `filter`, `where`, `query`, `conditions`                                            |
+| order             | `order`, `order_by`, `sort`, `sort_by`, `ordering`                                  |
+| select            | `select`, `fields`, `field`, `include_fields`, `projection`, `only`                 |
+| search            | `q`, `search`, `query_text`, `term`, `keyword`, `text`                              |
+| search mode       | `search_mode`, `searchmode`, `search_type`, `mode` (only if a search role exists)   |
+| limit (page size) | `limit`, `per_page`, `page_size`, `pagesize`, `count`, `max_results`, `top`, `size` |
+| page              | `page`, `page_number`, `pagenum`, `p`                                               |
+| offset            | `offset`, `skip`, `start`, `from`                                                   |
+| cursor            | `cursor`, `after`, `starting_after`, `next`, `page_token`, `continuation`           |
+
+A bracketed suffix is a _value_ in the name (`fields[articles]`, `filter[status]`), not part of the role. `count` is a page size only when it looks like one (has `maximum` or a default); otherwise it is treated as a total.
+
+A bounded integer with a default that matches no alias is still taken as page size. A 1-based integer with no maximum is taken as page number.
+
+**Filter grammars** — how oat **writes** a term:
+
+| name        | example                                                                                              | `and` / `or`                       |
+| ----------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| `postgrest` | `status.eq.active`, `name.neq.x`, `id.in.(a,b)`, `name.ilike.FOO`, `note.is.null`, `tags.contains.x` | `and(a.eq.1,b.eq.2)`, `or(...)`    |
+| `colon`     | `filter=status=eq:active` (comma-joined terms; no grouping)                                          | not expressible; those checks skip |
+| `equality`  | `?status=active` (one query param per field). Only `eq` is expressible                               | not expressible                    |
+
+Operators the **postgrest** writer can emit: `eq`, `ne`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `like`, `ilike`, `is`, `contains`. Colon stays on `eq` / `neq` / `gt` / `gte` / `lt` / `lte` / `like`. Equality is `eq` only. Anything a grammar cannot write becomes **did not apply**, not a failed request.
+
+A check that needs `in`, `ilike`, `is`, `contains`, a search mode, or `nullsfirst` / `nullslast` also needs that capability **declared**. oat does not infer new operators, modes, or nulls tokens onto an API that never listed them.
+
+**Sort grammars:** `name.asc` (dotted), `-name` (prefixed / JSON:API; ascending is the bare name), `name:asc` (colon), `name asc` (spaced). Dotted (PostgREST-shaped) can also emit `name.asc.nullsfirst` / `name.desc.nullslast` when the capability map allows that token. Colon / prefixed / spaced stay as they are.
+
+**Select grammars:** `id,name` (csv) or `fields[table]=id,name` (bracketed). If the parameter is already named `fields[articles]`, that name is used verbatim.
+
+### How a grammar is inferred
+
+`x-query.grammar` wins when it is `postgrest` | `colon` | `equality`.
+
+Otherwise oat concatenates the filter/order/select parameter's `example`, `examples`, and `description`:
+
+- Filter: `/postgrest/i` or `field.op.value` / `status.eq.active` → `postgrest`; `status=eq:` → `colon`; else `equality`. A free-text `filter` string that still looks like equality produces an `x-query` gap telling you to declare the grammar.
+- Sort: `name.asc` → dotted; `name:desc` → colon; `name desc` → spaced; leading `-field` → prefixed; else dotted.
+- Select: parameter name or description contains `fields[…]` → bracketed; else csv.
+
+Without `x-query`, if a filter/order/select/search role resolves, oat assumes **every scalar** is filterable/sortable/selectable (`string` / `number` / `integer` / `boolean`, including nullable unions). Searchable-without-tag is further narrowed to names matching `name|title|slug|label|description|email`. `doctor` warns. Pagination-only lists stay uncovered.
+
+That heuristic runs **only** for an axis that was not tagged and not set in config. An explicit empty claim — `filterable: []`, `searchable: null`, `selectable: []`, `sortable: []` — is a claim of none. oat will not infer scalars over it.
+
+Searchable / filterable / sortable / selectable from the tag are used as given. `maxLimit` is also taken from a page-size parameter's `schema.maximum` when the tag omits it.
+
+### Declared or skip
+
+Every list check consults one **effective capability map** per entity. Precedence, unchanged in spirit:
+
+| order | source                          | what it contributes                                                                                  |
+| ----- | ------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 1     | `x-query` on the list operation | fields, structured rows, operators, modes, caps, harvest                                             |
+| 2     | `config.entities[name].query`   | union of fields; overlay of ops / modes / caps                                                       |
+| 3     | `config.query`                  | global defaults for the same keys                                                                    |
+| 4     | heuristic                       | today's scalars / name-regex searchable — **only if that axis was not tagged and not set in config** |
+| 5     | skip                            | the check does not apply                                                                             |
+
+`hooks.resolveQueryCapabilities` runs after 1–3 (and after any `*From` harvest) and may add or replace any axis. Return `null` to keep the merge. Called once per entity after seed, with the seeded parent scope so a follow-up GET can run.
+
+Missing capability → the check does not apply / unresolved. Never `BACKEND_BUG` for an undeclared op, mode, or nulls option.
+
+## Pagination and envelopes
+
+Three page models, all first-class:
+
+- **Page number** (`page` + `limit` roles).
+- **Offset** (`offset` + `limit`). Checks that say "page 3" translate to `offset = (page - 1) * size` (size defaults to 20 only for that translation).
+- **Cursor** (`cursor` role + envelope `nextCursor` or a `Link: rel=next` header).
+
+`hasMore` is taken from the body (`hasMore`, `has_more`, `hasNextPage`, `more`) **or** from a documented `Link` response header. Under Link pagination, **absence** of `rel="next"` means no more pages.
+
+Collection shape is derived from the success JSON schema, not from hardcoded wrapper names:
+
+- Response `type: array` → the body is the list (`key: null`).
+- Otherwise the array property whose items are objects, skipping sidecar names `error(s)`, `warning(s)`, `message(s)`, `meta`, `links`. Resource-named envelopes (`{ tables: [...] }`) work.
+- Sibling keys become envelope fields:
+
+| role       | accepted property names                                     |
+| ---------- | ----------------------------------------------------------- |
+| total      | `count`, `total`, `totalCount`, `total_count`, `totalItems` |
+| hasMore    | `hasMore`, `has_more`, `hasNextPage`, `more`                |
+| nextCursor | `nextCursor`, `next_cursor`, `cursor`, `next`, `endCursor`  |
+| page       | `page`, `pageNumber`, `page_number`, `offset`               |
+| limit      | `limit`, `perPage`, `per_page`, `pageSize`, `page_size`     |
+
+Success schema is the first JSON media type on responses `200`, `201`, `202`, `2XX`, or `default`. Request schema is taken from `requestBody` preferring `multipart/form-data`, then `application/x-www-form-urlencoded`, then JSON. A success response that lists `text/event-stream` is a stream: oat consumes it to the end and does not treat the raw body as a JSON schema defect. Media type is the stream tag — there is no `x-stream`.

package/docs/reference-defects.md

@@ -0,0 +1,94 @@
+# oat — Reference defects
+
+[← back to the overview](../README.md)
+
+## Reference defects (`oat serve --defects`)
+
+Comma-separated. Each is one named lie the demo API can tell. Primary check is what conformance asserts; extras in parentheses are accepted additional symptoms of the same lie.
+
+| defect                                      | primary check                                   | the lie                                                  |
+| ------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- |
+| `STALE_LIST`                                | `list.read-after-write`                         | create succeeds, list does not show the row              |
+| `CREATE_DROPS_FIELD`                        | `create.persists-submitted-fields`              | a submitted field is dropped                             |
+| `STRING_PAYLOAD_MANGLED`                    | `payload.string-survives`                       | non-ASCII / surrounding whitespace stripped on write     |
+| `RESPONSE_STATUS_UNDECLARED`                | `response.status-is-documented`                 | PATCH returns 201 when the document names 200            |
+| `CREATED_201_AS_200`                        | `create.status-matches-document`                | create returns 200 when the spec says 201                |
+| `RESPONSE_SCHEMA_DRIFT`                     | `schema.success-response-matches-document`      | success body does not match the schema                   |
+| `ERROR_SCHEMA_DRIFT`                        | `schema.error-response-matches-document`        | error body does not match the schema                     |
+| `LIMIT_IGNORED`                             | `pagination.limit-bounds-page-size`             | `limit` is accepted and ignored                          |
+| `LIMIT_EXCEEDS_MAX`                         | `pagination.limit-respects-documented-max`      | documented max is not capped                             |
+| `HASMORE_ALWAYS_FALSE`                      | `pagination.has-more-is-accurate`               | `hasMore` is always false                                |
+| `OFF_BY_ONE_PAGE`                           | `pagination.page-walk-covers-set`               | page walk skips or repeats                               |
+| `PAGE_PAST_END_REPEATS`                     | `pagination.bounds-handled`                     | a page past the end repeats the last page                |
+| `UNSTABLE_SORT`                             | `pagination.page-walk-covers-set`               | default order is not a total order                       |
+| `CURSOR_DRIFT`                              | `pagination.cursor-agrees-with-page`            | cursor and page disagree                                 |
+| `FILTER_IGNORED`                            | `filter.unknown-field-rejected`                 | unknown filter field is ignored                          |
+| `UNKNOWN_PARAM_EMPTIES_LIST`                | `query.unknown-parameter-consistent`            | an unknown query parameter empties the listing           |
+| `FILTER_EQ_NOT_APPLIED`                     | `filter.equality-selects-exactly-one`           | equality filter is ignored                               |
+| `EMPTY_RESULT_RETURNS_ALL`                  | `filter.zero-match-returns-none`                | empty match returns the whole set                        |
+| `NEQ_DROPS_NULLS`                           | `filter.negation-partitions-the-set`            | `neq` drops nulls so the partition leaks                 |
+| `FILTER_GROUP_COMBINATOR_SWAPPED`           | `filter.and-composes-as-intersection`           | `and`/`or` are swapped                                   |
+| `LIKE_UNESCAPED`                            | `filter.like-metacharacters-escaped`            | `%`/`_` are wildcards in values                          |
+| `NUMERIC_COMPARED_AS_TEXT`                  | `filter.numeric-comparison-is-numeric`          | numbers compared as strings                              |
+| `ERROR_500_ON_BAD_FILTER`                   | `error.malformed-filter-not-5xx`                | bad filter is 500                                        |
+| `FILTER_AFTER_PAGINATION`                   | `query.filter-selects-from-whole-set`           | filter applied after the page is cut                     |
+| `ORDER_IGNORED`                             | `sort.order-is-applied`                         | sort param is ignored                                    |
+| `SORT_DESC_DROPS_NULLS`                     | `sort.reverse-symmetry`                         | desc drops nulls                                         |
+| `SEARCH_IGNORED`                            | `search.q-narrows-result`                       | search param is ignored                                  |
+| `SELECT_IGNORED`                            | `select.projection-honoured`                    | select param is ignored                                  |
+| `COUNT_ALWAYS_ZERO`                         | `count.consistent-with-returned-page`           | total is always 0                                        |
+| `COUNT_IGNORES_FILTER`                      | `count.matches-filtered-set`                    | total ignores the filter                                 |
+| `FILTER_DROPPED_WHEN_SORTED`                | `query.axes-compose`                            | sort drops the filter                                    |
+| `FILTER_DROPPED_WHEN_SELECTED`              | `query.filter-and-select-compose`               | select drops the filter                                  |
+| `FILTER_DROPPED_WHEN_SEARCHED`              | `query.search-and-filter-compose`               | search drops the filter                                  |
+| `FILTER_DROPPED_WHEN_SORTED_AND_SELECTED`   | `query.filter-sort-select-compose`              | the triple drops the filter                              |
+| `FILTER_DROPPED_WHEN_SORTED_AND_SEARCHED`   | `query.filter-search-sort-compose`              | the triple drops the filter                              |
+| `FILTER_DROPPED_WHEN_SEARCHED_AND_SELECTED` | `query.filter-search-select-compose`            | the triple drops the filter                              |
+| `SPEC_OVERCLAIMS_FILTERABLE`                | `spec.declared-filterable-is-filterable`        | `x-query` lists a field that 400s                        |
+| `SPEC_OVERCLAIMS_SORTABLE`                  | `spec.declared-sortable-is-sortable`            | same for sort                                            |
+| `SPEC_OVERCLAIMS_SELECTABLE`                | `spec.declared-selectable-is-selectable`        | same for select                                          |
+| `FILTER_IN_FIRST_ONLY`                      | `filter.in-is-union-of-eq`                      | `in.(a,b)` matches only the first value                  |
+| `FILTER_GTE_IS_GT`                          | `filter.gte-is-gt-or-eq`                        | `gte` is compiled as `gt`                                |
+| `FILTER_ILIKE_IS_LIKE`                      | `filter.ilike-is-case-insensitive`              | `ilike` is compiled as `like`                            |
+| `FILTER_IS_NULL_MATCHES_ALL`                | `filter.is-null-selects-nulls`                  | `is.null` matches every row                              |
+| `FILTER_ILLEGAL_OP_IGNORED`                 | `filter.illegal-op-rejected`                    | an operator outside the allowlist is ignored             |
+| `SORT_NUMERIC_AS_TEXT`                      | `sort.numeric-order-is-numeric`                 | a numeric field is ordered lexicographically             |
+| `SORT_MULTI_KEY_IGNORED`                    | `sort.multi-key-tiebreak`                       | the second sort key is ignored                           |
+| `TIEBREAK_NOT_APPLIED`                      | `sort.stable-tiebreak`                          | ties are broken by another field than the declared one   |
+| `RATE_LIMIT_STRICTER_THAN_DECLARED`         | `spec.declared-rate-limit-is-honoured`          | 429 well inside the declared `x-rate-limit` rate         |
+| `SELECT_FIELD_MISSING`                      | `select.requested-fields-present`               | a requested select field is dropped                      |
+| `CROSS_TENANT_READ`                         | `tenant.item-not-readable-cross-tenant`         | item GET is global by id                                 |
+| `CROSS_TENANT_WRITE`                        | `tenant.item-not-writable-cross-tenant`         | update and delete reach another tenant's record          |
+| `EXISTENCE_LEAK_VIA_STATUS`                 | `tenant.denial-does-not-reveal-existence`       | 403 vs 404 reveals the other tenant's row                |
+| `TENANT_LEAK_VIA_FILTER`                    | `tenant.filter-does-not-bypass-scope`           | filter drops the tenant predicate                        |
+| `FOREIGN_PARENT_ACCEPTED`                   | `tenant.parent-not-reachable-from-another-root` | another tenant's parent is accepted under one's own root |
+| `ROLE_MONOTONICITY_BROKEN`                  | `auth.rank-is-monotonic`                        | a lower rank can do more                                 |
+| `ROLE_WRITE_INVERTED`                       | `auth.rank-is-monotonic-on-writes`              | a lower rank can update where a higher rank cannot       |
+| `INVITE_NEVER_GRANTS`                       | `auth.invite-grants-then-revokes`               | accept does not grant                                    |
+| `REVOKE_IGNORED`                            | `auth.invite-grants-then-revokes`               | revoke leaves the grant                                  |
+| `IMMUTABLE_WRITABLE`                        | `patch.immutable-field-rejected`                | immutable fields accept writes                           |
+| `SOFT_DELETE_LEAK`                          | `softdelete.absent-from-default-list`           | tombstone stays on the default list                      |
+| `PARENT_PROJECTION_STALE`                   | `invalidation.declared-route-changes`           | child write does not bump the parent                     |
+| `EFFECT_NOT_APPLIED`                        | `effects.declared-effect-occurs`                | declared cardinality delta does not happen               |
+| `ASYNC_NEVER_COMPLETES`                     | `async.reaches-terminal-state`                  | job stays pending                                        |
+| `ASYNC_RECEIPT_MISSING_ID`                  | `async.receipt-identifies-the-job`              | receipt has no id                                        |
+| `PATCH_REPLACES`                            | `patch.minimality`                              | PATCH is implemented as replace                          |
+| `IDEMPOTENCY_IGNORED`                       | `idempotency.replay-does-not-duplicate`         | Idempotency-Key is ignored                               |
+| `IDEMPOTENT_REPLAY_INSERTS`                 | `idempotency.replay-does-not-duplicate`         | a replay returns the original but inserts another row    |
+| `UNIQUE_NOT_ENFORCED`                       | `create.unique-conflict-rejected`               | a duplicate unique-set write is 2xx instead of 409       |
+| `DELETE_MISSING_OK`                         | `delete.absent-record-returns-404`              | DELETE missing returns 200                               |
+| `CONCURRENT_WRITE_LOST`                     | `concurrency.no-lost-update`                    | full-row write clobbers a parallel PATCH                 |
+| `ENUM_NOT_VALIDATED`                        | `validation.enum-enforced`                      | enum is not enforced                                     |
+| `MAXLENGTH_NOT_VALIDATED`                   | `validation.max-length-enforced`                | maxLength is not enforced                                |
+| `REQUIRED_NOT_VALIDATED`                    | `validation.required-enforced`                  | required is not enforced                                 |
+| `CONTENT_TYPE_NOT_ENFORCED`                 | `validation.content-type-enforced`              | wrong Content-Type is accepted                           |
+| `LIST_DETAIL_DISAGREE`                      | `consistency.projections-agree`                 | list and item show different values                      |
+| `COLUMN_NAME_MISMATCH`                      | `create.persists-submitted-fields`              | SQL identifier does not match the field (SQL backends)   |
+| `COLLATION_INCONSISTENT`                    | `pagination.cursor-agrees-with-page`            | cursor order ≠ page order (SQL)                          |
+
+```bash
+oat serve --defects STALE_LIST,PATCH_REPLACES
+oat run --config labs/local.config.ts --base-url <url>
+```
+
+`COLUMN_NAME_MISMATCH` is SQL-only in conformance (the in-memory store has no physical column names). `CONCURRENT_WRITE_LOST` runs on the in-memory engine only: the race it times does not depend on the store.

package/docs/reports.md

@@ -0,0 +1,211 @@
+# oat — Reports and progress logs
+
+[← back to the overview](../README.md)
+
+## Reports
+
+Written under `--out` (default `./.oat/runs`). Each invocation creates a UTC timestamp folder and points `latest` at it:
+
+```
+.oat/runs/2026-08-18T12-00-00Z/
+.oat/runs/latest -> 2026-08-18T12-00-00Z
+```
+
+`--out` / `outDir` replace the root, not the leaf — `--out .oat/runs/prod` writes `.oat/runs/prod/<datetime>/`.
+
+| file                         |                                                                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `oat-report.md`              | human report: scope, per-operation status, summary, findings with request/response excerpts, coverage, latency p50/p95/max |
+| `oat-report.json`            | same data for CI. Summary only — full exchanges are not inlined here                                                       |
+| `matrix.html`                | visual matrix of entities × checks                                                                                         |
+| `matrix.json`                | the same graph (AI-friendly), including a mermaid string                                                                   |
+| `issue-repro/*.sh`           | one executable `curl` script per finding that has evidence. Directory is omitted when the run is clean                     |
+| `progress.log`               | logfmt, one event per line, never truncated                                                                                |
+| `progress.jsonl`             | same events as JSON                                                                                                        |
+| `progress.tsv`               | same columns, tab-separated. `req_id` is the join key to the exchange journal                                              |
+| `progress.json`              | latest snapshot only (overwritten ~1s)                                                                                     |
+| `exchanges.jsonl`            | one line per request (`seq`, `requestId`, method, url, status, bytes, …). Greppable                                        |
+| `exchanges/<requestId>.json` | full exchange: status, headers, described bodies. Missing id → `seq-<n>.json`. Duplicate id → `-<seq>`                     |
+| `blobs/<sha256>`             | content-addressed file parts and oversized / binary bodies                                                                 |
+
+The journal is oat `Exchange` JSON, not HAR (HAR export is out of scope). Default **on** unless `--profile cheap`. `--no-save-exchanges` skips `exchanges/` entirely. `--quiet` does not. **`--no-save-exchanges` does not reduce transcript RAM** — it only skips the disk journal. The in-memory transcript always drops live `FormData` / `Blob` / `ArrayBuffer` / multi-MiB strings after each hop, keeping citeable metadata and content-addressed body descriptors. Reconstruct bytes from `blobs/<sha256>` when a check genuinely needs them.
+
+Bodies are described, never base64 multipart. JSON / text inline up to 256 KiB, then `blobs/<sha256>`. `FormData` file parts and binary downloads (`application/pdf`, spreadsheet, image, `octet-stream`) are always blobs; the same fixture bytes POSTed N times share one file. SSE is parsed incrementally into `{ event, data }[]` frames — the raw `text/event-stream` concatenation is not retained on the transcript.
+
+Redaction is on by default (not opt-in), applied on write:
+
+- Headers: `authorization`, `cookie`, `set-cookie`, `proxy-authorization`, and any `x-*-key` / `x-*-secret` / `x-ia-tester-key` (case-insensitive).
+- JSON bodies, any depth: `access_token`, `refresh_token`, `id_token`, `password`, `token`, `secret`, `api_key` → `"<redacted>"`.
+
+Every report names its scope. The console prints `scope: full · 141 of 212 operations graded` or `scope: targeted · 2 operations (--ops …)` followed by one line per target. `oat-report.md` has a **Scope** line and an **Operations** table: on a full run, every operation in the document with its status (so operations no check ever grades are visible); on a targeted run, the targets only, followed by **Support operations** with call and non-2xx counts. In `matrix.html` / `matrix.json` a check a targeted run did not ask for is `out-of-scope`, distinct from `skipped` (not applicable).
+
+Join `progress.tsv` `req_id` to `exchanges.jsonl` `requestId` (response `x-request-id` / `request-id` / `x-correlation-id` / `correlation-id` wins; else what oat sent). `oat-report.md` includes one line such as `1841 exchanges → exchanges/`.
+
+### `oat-report.json`
+
+```json
+{
+	"backend": "https://api.example.com",
+	"generatedAt": "2026-08-15T12:00:00.000Z",
+	"durationMs": 41200,
+	"requests": 842,
+	"entitiesTested": ["store", "product"],
+	"scope": {
+		"mode": "targeted",
+		"requested": { "ops": ["product.update"], "only": [] },
+		"operations": [
+			{
+				"operationId": "product.update",
+				"entity": "product",
+				"status": "failed",
+				"checks": {
+					"held": ["concurrency.no-lost-update"],
+					"failed": ["patch.minimality"],
+					"suppressed": [],
+					"inconclusive": [],
+					"gaps": []
+				},
+				"findings": 1,
+				"reason": null
+			}
+		],
+		"support": [{ "operationId": "product.create", "calls": 9, "non2xx": 0 }],
+		"excluded": [],
+		"originsSkipped": []
+	},
+	"checksOutOfScope": [{ "check": "filter.in-is-union-of-eq", "entity": "product" }],
+	"checksRun": ["list.read-after-write", "patch.minimality"],
+	"checksSkipped": [{ "check": "async.reaches-terminal-state", "entity": "store", "needs": "…" }],
+	"checksSuppressed": [{ "check": "query.axes-compose", "entity": "store", "because": "list.read-after-write" }],
+	"inconclusive": [{ "check": "filter.and-composes-as-intersection", "entity": "store", "reason": "…" }],
+	"summary": { "BACKEND_BUG": 1 },
+	"coverage": {
+		"neverApplied": ["async.reaches-terminal-state"],
+		"partial": [{ "check": "select.projection-honoured", "ran": 1, "skipped": 1 }]
+	},
+	"latency": {
+		"p50": 12,
+		"p95": 90,
+		"max": 400,
+		"slowest": { "method": "GET", "path": "/v1/products" }
+	},
+	"findings": [
+		{
+			"check": "patch.minimality",
+			"verdict": "BACKEND_BUG",
+			"entity": "product",
+			"summary": "PATCH { name } also cleared description",
+			"detail": "…",
+			"evidence": [
+				{
+					"method": "PATCH",
+					"url": "https://api.example.com/v1/products/p1",
+					"status": 200,
+					"requestBody": { "name": "x" },
+					"responseBody": { "name": "x", "description": null }
+				}
+			]
+		}
+	]
+}
+```
+
+Latency is reported, never asserted. oat has no baseline for "too slow".
+
+Gate in CI on process exit code, or on `findings` whose `verdict` is not `COVERAGE_GAP` / `BLOCKED`.
+
+### `matrix.json`
+
+```json
+{
+	"kind": "oat.matrix",
+	"version": 2,
+	"baseUrl": "…",
+	"generatedAt": "…",
+	"thesis": "…",
+	"summary": "…",
+	"index": { "entityCount": 5, "failed": ["product"], "parents": ["store"], "crossClaims": 1, "inbound": {} },
+	"counts": { "failed": 1, "blocked": 0, "held": 40, "skipped": 14 },
+	"entities": [
+		{
+			"name": "product",
+			"identity": "id",
+			"readSurface": ["GET /v1/products", "GET /v1/products/{id}"],
+			"counts": { "failed": 1, "blocked": 0, "held": 20, "skipped": 5 },
+			"roots": ["store_id"],
+			"nodes": [
+				{
+					"id": "product/patch.minimality",
+					"group": "product",
+					"layer": "axis",
+					"status": "failed",
+					"verdict": "BACKEND_BUG",
+					"summary": "…"
+				}
+			]
+		}
+	],
+	"invalidate": [
+		{
+			"fromEntity": "product",
+			"fromOp": "product.create",
+			"toEntity": "store",
+			"toRoute": "GET /v1/stores/{id}",
+			"cross": true
+		}
+	],
+	"edges": [{ "from": "product/list.read-after-write", "to": "product/patch.minimality", "kind": "dependsOn" }],
+	"mermaid": "flowchart LR\n…"
+}
+```
+
+Cell `status`: `held` (passed), `failed`, `blocked`, `skipped`. Edge `kind`: `dependsOn` (cascade) or `uses` (a composition check built from a single-axis check).
+
+### `issue-repro/<entity>-<check>.sh`
+
+Created only when a finding has HTTP evidence. Not created on a clean run.
+
+```bash
+#!/usr/bin/env bash
+# Generated by oat. Set TOKEN to a valid credential before running.
+# product — PATCH { name } also cleared description
+set -u
+BASE="${BASE:-https://api.example.com}"
+TOKEN="${TOKEN:?set TOKEN to a valid credential}"
+
+# step 1 — observed 200
+curl -sS -X PATCH "$BASE/v1/products/p1" \
+  -H "authorization: Bearer $TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"name":"x"}'
+```
+
+`authorization`, `cookie`, and `x-api-key` are redacted to `$TOKEN`. Replay needs a live credential; ids in the script are whatever the failing run created (gone if teardown ran). Use `--keep-fixtures` when you want to replay against the same rows.
+
+## Progress logs
+
+`progress.log` starts with a glossary. Fields:
+
+| key                        |                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| `ts`                       | ISO-8601 UTC when the line was written                                           |
+| `status`                   | `ok`, `stall` (`idle_ms` ≥ 15000 after the last call returned), or `in_flight`   |
+| `done` / `total`           | entity index / how many entities                                                 |
+| `phase`                    | `load` \| `auth` \| `seed` \| `test` \| `teardown` \| `done`                     |
+| `entity` / `check`         | current entity and check id                                                      |
+| `msg`                      | phase note. In-flight is `status`, not `msg`                                     |
+| `req` / `find`             | request count, finding count                                                     |
+| `method` / `path` / `http` | last completed call, or the in-flight call when `status=in_flight` (`http=-`)    |
+| `last_ms`                  | duration of the last completed call. `-` while `in_flight`                       |
+| `idle_ms`                  | while `in_flight`: ms since this request started. otherwise ms since it returned |
+| `elapsed_ms`               | wall clock since start                                                           |
+
+`--quiet` keeps the files and drops stderr.
+
+Every HTTP call emits a **start** line (`status=in_flight`, `http=-`, `last_ms=-`) when `fetch` is issued, then a **completed** line when it returns (`http=200`, `last_ms` ≈ wall time, `idle_ms=0`). The 5 s heartbeat keeps the in-flight path and climbs `idle_ms` until the call returns; after return it climbs on the completed call (and becomes `stall` at 15 s). A 300 s `POST /extract` therefore stays `/extract` in the log, not the previous refresh or GET.
+
+Lines are also written when the phase/entity/check/message changes, or every 2 s, or on `load`/`done`. `progress.json` is rewritten about once a second.
+
+If `idle_ms` climbs through a long poll (`x-async`) that is expected. If it climbs on a simple GET while `status` is not `in_flight`, the process or the network is stuck. Live `run` aborts a single `fetch` after `network.requestTimeoutMs` (default **180s**). A hung `text/event-stream` becomes `net.unreachable` (`kind=timeout`), not an unbounded buffer on the transcript. Set `requestTimeoutMs: 0` only if you intend to wait for the socket.
+
+Bun and Node both honour that timeout. If oat still runs away with RAM (a bug, or a caller holding the process open), treat the process like any other prefer-kill target for `earlyoom` / systemd — Bun is often **not** in a default `--prefer` list.