@lovrozagar/oat 0.10.0 → 0.12.0

package/docs/checks.md

@@ -0,0 +1,183 @@
+# oat — Checks and verdicts
+
+[← back to the overview](../README.md)
+
+## Checks
+
+99 checks. A check that cannot run says so (`did not apply` + `needs`). A check that depends on a broken primitive is `BLOCKED`. A check that ran and stopped is inconclusive, not a pass.
+
+Order is fixed (foundations first) so cascade suppression has a cause to point at. Mutating checks run alone; read-only checks may share in-flight requests under `maxInFlight`.
+
+`depends` is the `dependsOn` list: if any of those already failed **for this entity**, this check is `BLOCKED` rather than reported as a second defect. Suppression is transitive.
+
+| id                                              | asserts                                                                                                                                    | needs                                                                | depends                                 |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | --------------------------------------- |
+| `list.read-after-write`                         | a just-created record appears on the list                                                                                                  | create + a seeded record                                             | —                                       |
+| `create.persists-submitted-fields`              | every writable field sent on create is echoed                                                                                              | create that echoes the record                                        | `list.read-after-write`                 |
+| `payload.string-survives`                       | a documented-valid string is stored exactly; 4xx after an ASCII control is a fail                                                          | update or create+delete, item GET, unconstrained string              | `list.read-after-write`                 |
+| `create.status-matches-document`                | create status is one the document declared                                                                                                 | create                                                               | —                                       |
+| `response.status-is-documented`                 | every non-create exchange returns a status that operation names (`default` ≠ 201)                                                          | a modeled non-create operation oat invoked                           | —                                       |
+| `schema.success-response-matches-document`      | create body validates against the success schema                                                                                           | success schema on create                                             | `create.status-matches-document`        |
+| `schema.error-response-matches-document`        | an error body validates against the documented error schema                                                                                | error schema on the item route                                       | —                                       |
+| `pagination.limit-bounds-page-size`             | page size ≤ the requested limit                                                                                                            | page-size _role_ (aliases include `limit`, `per_page`, …)            | `list.read-after-write`                 |
+| `pagination.limit-respects-documented-max`      | requesting more than `maxLimit` does not return more                                                                                       | declared `maxLimit` and a larger cohort                              | `pagination.limit-bounds-page-size`     |
+| `pagination.has-more-is-accurate`               | `hasMore` / `Link rel=next` matches whether another page exists                                                                            | page-forward + `hasMore` or `Link rel=next`                          | `pagination.limit-bounds-page-size`     |
+| `pagination.page-walk-covers-set`               | walking pages covers the collection with no gaps or dupes                                                                                  | page or offset + ≥3 records                                          | `pagination.limit-bounds-page-size`     |
+| `pagination.bounds-handled`                     | a zero, negative, fractional or non-numeric page size, and a page past the end, are refused or served sanely — never a 5xx or a repeat     | page-size or page-number parameter + ≥1 record                       | `pagination.page-walk-covers-set`       |
+| `pagination.cursor-agrees-with-page`            | cursor walk and page walk yield the same set                                                                                               | both cursor and page                                                 | `pagination.limit-bounds-page-size`     |
+| `filter.unknown-field-rejected`                 | a filter on a field that does not exist is not silently ignored                                                                            | a filter expression                                                  | —                                       |
+| `filter.equality-selects-exactly-one`           | `id.eq.<one>` returns that one record                                                                                                      | equality on the identity                                             | `list.read-after-write`                 |
+| `filter.zero-match-returns-none`                | a filter that matches nothing returns an empty page, not the whole set                                                                     | same                                                                 | `list.read-after-write`                 |
+| `filter.negation-partitions-the-set`            | `eq` ∪ `neq` = whole set, intersection empty                                                                                               | eq and neq                                                           | `list.read-after-write`, equality       |
+| `filter.and-composes-as-intersection`           | `and(A,B)` = A ∩ B                                                                                                                         | two filterable fields + AND                                          | equality / list                         |
+| `filter.or-composes-as-union`                   | `or(A,B)` = A ∪ B                                                                                                                          | `or()` — **postgrest grammar only**                                  | equality / list                         |
+| `filter.like-metacharacters-escaped`            | `%` `_` `*` in a value are literals, not wildcards                                                                                         | like operator                                                        | `list.read-after-write`                 |
+| `filter.numeric-comparison-is-numeric`          | `gt`/`lt` on a number uses numeric order, not TEXT (`1,10,2`)                                                                              | numeric field + a filter param                                       | `list.read-after-write`, unknown-field  |
+| `filter.in-is-union-of-eq`                      | `in.(a,b)` = `eq.a` ∪ `eq.b`                                                                                                               | field allows `in`; ≥2 distinct values                                | equality                                |
+| `filter.nin-complements-in`                     | `in` ∩ `nin` empty; union = set minus nulls                                                                                                | field allows `in` and `nin`                                          | `in`                                    |
+| `filter.gte-is-gt-or-eq`                        | `gte.x` = `gt.x` ∪ `eq.x`                                                                                                                  | field allows `gte` and `gt`; ordered type                            | numeric comparison                      |
+| `filter.lte-is-lt-or-eq`                        | `lte.x` = `lt.x` ∪ `eq.x`                                                                                                                  | field allows `lte` and `lt`                                          | numeric comparison                      |
+| `filter.ordered-triple-partitions`              | `lt` ∪ `eq` ∪ `gt` = set minus nulls; pairwise disjoint                                                                                    | field allows all three                                               | numeric comparison                      |
+| `filter.ilike-is-case-insensitive`              | case-flipped value: `ilike` matches; `like` does not (unresolved if both match)                                                            | field allows both                                                    | like                                    |
+| `filter.is-null-selects-nulls`                  | `is.null` = nulls; `is.notnull` = complement                                                                                               | field allows `is`; cohort has a null                                 | foundations                             |
+| `filter.contains-membership`                    | `contains.<el>` = records whose array value includes `el`                                                                                  | array field or ops include `contains`                                | foundations                             |
+| `filter.nested-and-or-distributes`              | `and(A,or(B,C))` = (A∩B) ∪ (A∩C)                                                                                                           | postgrest grammar; ≥2 filterable fields                              | `and` / `or`                            |
+| `filter.alias-matches-canonical`                | each declared alias token selects the same id-set as its target                                                                            | `aliases` non-empty                                                  | equality                                |
+| `filter.illegal-op-rejected`                    | one op **not** in that field's `ops` is 4xx                                                                                                | closed `ops` list                                                    | unknown-field                           |
+| `filter.empty-in`                               | `in.()` is 4xx (`reject`) or zero rows (`match-none`)                                                                                      | `emptyIn` set; field allows `in`                                     | `in`                                    |
+| `filter.in-over-limit-rejected`                 | `in` list of `maxInValues+1` is 4xx                                                                                                        | `maxInValues` set                                                    | foundations                             |
+| `filter.condition-cap-rejected`                 | `maxFilterConditions+1` `eq` terms is 4xx                                                                                                  | `maxFilterConditions` set                                            | foundations                             |
+| `spec.declared-filterable-ops-accepted`         | every declared field × every op in that field's `ops` returns <400                                                                         | closed `ops`                                                         | declared-filterable                     |
+| `error.malformed-filter-not-5xx`                | garbage filter text is 4xx, never 5xx                                                                                                      | a filter expression                                                  | —                                       |
+| `query.filter-selects-from-whole-set`           | a filter is applied to the collection, not to the current page                                                                             | filterable + ≥3 records                                              | list / walk                             |
+| `sort.order-is-applied`                         | requesting a sort actually rearranges the page                                                                                             | order + a sortable field                                             | `pagination.limit-bounds-page-size`     |
+| `sort.reverse-symmetry`                         | desc is the reverse of asc (nulls included)                                                                                                | order + asc/desc                                                     | order-is-applied                        |
+| `sort.unknown-field-rejected`                   | `order` on an undeclared field is 4xx, not silent ignore                                                                                   | order param                                                          | —                                       |
+| `sort.numeric-order-is-numeric`                 | `1,10,2` sorts as numbers, not text                                                                                                        | numeric sortable field whose lexical order disagrees                 | order-is-applied                        |
+| `sort.nulls-first-last`                         | `nullsfirst` / `nullslast` put nulls at the start / end of asc                                                                             | declared nulls token; dotted grammar; cohort has a null              | order + reverse                         |
+| `sort.multi-key-tiebreak`                       | ties on the first key are ordered by the second                                                                                            | ≥2 sortable fields; `maxKeys` absent or ≥2                           | order + reverse                         |
+| `sort.default-order-applied`                    | omitting `order` matches `defaultOrder`                                                                                                    | `defaultOrder` set; walk complete                                    | order + walk                            |
+| `sort.stable-tiebreak`                          | the same `order` twice yields the same sequence                                                                                            | `stableTiebreak` set                                                 | order-is-applied                        |
+| `spec.declared-sortable-nulls-accepted`         | each declared nulls token returns <400                                                                                                     | some field/global declares `nulls`                                   | order-is-applied                        |
+| `search.q-narrows-result`                       | a search term that matches one record does not return the whole set                                                                        | search param + searchable fields                                     | `list.read-after-write`                 |
+| `search.tokens-and`                             | `q=a b` = intersection (AND). Sameness of AND and OR passes                                                                                | searchable fields; two tokens that split the cohort                  | `q-narrows`                             |
+| `search.case-insensitive`                       | case-flipped token matches the same set (unresolved if the backend is case-sensitive)                                                      | searchable field with a letter                                       | `q-narrows`                             |
+| `search.empty-q`                                | `q=` is ignore / match-all / reject as declared                                                                                            | `searchEmpty` set                                                    | `q-narrows`                             |
+| `search.mode-accepted`                          | each declared `searchModes` value is <400 on the mode param                                                                                | `searchModes` set and a mode role                                    | —                                       |
+| `select.projection-honoured`                    | `select=id,name` does not return undeclared fields                                                                                         | select param                                                         | —                                       |
+| `select.requested-fields-present`               | every name in `select=` appears on each returned item                                                                                      | select param; ≥1 selectable field                                    | projection                              |
+| `select.unknown-field-rejected`                 | unknown select name is 4xx (`reject`) or dropped (`ignore`)                                                                                | `select.unknown` set                                                 | projection                              |
+| `select.nested-honoured`                        | `rel(col)` returns `rel` as an object/array carrying only `col`                                                                            | `select.nested` and a named relation                                 | projection                              |
+| `count.consistent-with-returned-page`           | envelope total ≥ rows on this page, and is not zero when the page is not                                                                   | envelope total                                                       | `list.read-after-write`                 |
+| `count.matches-filtered-set`                    | filtered total equals the size of the filtered walk                                                                                        | total + a filter                                                     | list, equality                          |
+| `query.axes-compose`                            | filter + sort together: filter still holds on the sorted page                                                                              | filterable + sortable                                                | filter + sort foundations               |
+| `query.filter-and-select-compose`               | filter + select together                                                                                                                   | filterable + select                                                  | same                                    |
+| `query.search-and-filter-compose`               | search + filter together                                                                                                                   | filterable + search                                                  | same                                    |
+| `query.filter-sort-select-compose`              | filter + sort + select                                                                                                                     | filter + sort + select                                               | same                                    |
+| `query.filter-search-sort-compose`              | filter + search + sort                                                                                                                     | filter + search + sort                                               | same                                    |
+| `query.filter-search-select-compose`            | filter + search + select                                                                                                                   | filter + search + select                                             | same                                    |
+| `query.sort-and-select-compose`                 | sort + select: order holds; extras dropped; requested fields present                                                                       | sortable + selectable                                                | sort + select                           |
+| `query.search-and-select-compose`               | search + select: search membership holds; extras dropped                                                                                   | searchable + selectable                                              | search + select                         |
+| `query.search-and-sort-compose`                 | search + sort: search membership holds; remaining rows ordered                                                                             | searchable + sortable                                                | search + sort                           |
+| `query.filter-search-sort-select-compose`       | all four: filter ∩ search; order holds; extras dropped                                                                                     | all four axes declared                                               | the triples                             |
+| `query.unknown-parameter-consistent`            | an undocumented query parameter is either refused or ignored — it never silently changes the set                                           | a listing + ≥1 record                                                | `pagination.page-walk-covers-set`       |
+| `spec.declared-filterable-is-filterable`        | every `x-query.filterable` field actually accepts a filter                                                                                 | `x-query` naming filterable fields                                   | filter foundations                      |
+| `spec.declared-sortable-is-sortable`            | every `x-query.sortable` field actually accepts a sort                                                                                     | `x-query` naming sortable fields                                     | sort foundations                        |
+| `spec.declared-selectable-is-selectable`        | every `x-query.selectable` field actually accepts a select                                                                                 | `x-query` naming selectable fields                                   | select                                  |
+| `tenant.item-not-readable-cross-tenant`         | principal B cannot GET principal A's item                                                                                                  | second principal, different `roots`, and a tagged or inferred tenant | —                                       |
+| `tenant.item-not-writable-cross-tenant`         | principal B cannot update or delete principal A's item                                                                                     | second principal in another tenant, create, and update or delete     | `tenant.item-not-readable-cross-tenant` |
+| `tenant.denial-does-not-reveal-existence`       | 404 vs 403 (or equivalent) does not distinguish "exists other tenant" from "missing"                                                       | second principal, and a tagged or inferred tenant                    | `tenant.item-not-readable-cross-tenant` |
+| `tenant.filter-does-not-bypass-scope`           | `filter=id.eq.<other tenant>` does not return that row                                                                                     | second principal, a filter, and a tagged or inferred tenant          | `query.filter-selects-from-whole-set`   |
+| `tenant.parent-not-reachable-from-another-root` | a nested collection does not accept another tenant's parent under the caller's own tenant                                                  | second tenant, a collection nested below the tenant                  | `tenant.item-not-readable-cross-tenant` |
+| `auth.rank-is-monotonic`                        | a lower rank cannot do what a higher rank is denied                                                                                        | two same-tenant principals at different `rank`                       | `list.read-after-write`                 |
+| `auth.rank-is-monotonic-on-writes`              | a lower rank cannot create, update or delete where a higher rank is denied                                                                 | two same-tenant principals at different `rank`, and a create         | `auth.rank-is-monotonic`                |
+| `auth.invite-grants-then-revokes`               | invite → accept grants; revoke takes it back                                                                                               | `x-invite` + peer with `inviteAs`                                    | list, cross-tenant                      |
+| `create.unique-conflict-rejected`               | a second create colliding a documented unique set is 409, not 2xx; the list does not grow                                                  | `x-unique` with a probeable create body column and a known row       | —                                       |
+| `update.unique-conflict-rejected`               | PATCHing a **different** row onto another row's unique-set values is 409, not 2xx                                                          | `x-unique`, update, two known rows; skip all-`x-immutable` sets      | —                                       |
+| `patch.immutable-field-rejected`                | PATCHing an `x-immutable` field is rejected or ignored                                                                                     | `x-immutable`                                                        | —                                       |
+| `softdelete.absent-from-default-list`           | a soft-deleted row is gone from the default list                                                                                           | `x-soft-delete`                                                      | `list.read-after-write`                 |
+| `invalidation.declared-route-changes`           | after a write, the other entity's listed route actually changes                                                                            | `x-invalidate` naming another entity                                 | list, persist                           |
+| `effects.declared-effect-occurs`                | `x-effects` cardinality delta is observed on the named list (`count` exact, `min` at-least; nested child lists bind the created parent id) | `x-effects`                                                          | `list.read-after-write`                 |
+| `effects.side-effect-arrives`                   | after the write, the named GET’s JSON path is occupied before `timeoutMs`                                                                  | `x-wait`                                                             | `list.read-after-write`                 |
+| `async.reaches-terminal-state`                  | `x-async` reaches `until` (poll, or a terminal SSE frame) before `timeoutMs`                                                               | `x-async`                                                            | —                                       |
+| `async.receipt-identifies-the-job`              | `idFrom` on the receipt (JSON object or SSE event JSON) resolves to a pollable job                                                         | `x-async` + `idFrom`                                                 | —                                       |
+| `patch.minimality`                              | PATCH `{ name }` does not clear other writable fields                                                                                      | update + item route                                                  | —                                       |
+| `idempotency.replay-does-not-duplicate`         | same Idempotency-Key + same body does not create a second row                                                                              | create + documented Idempotency-Key header                           | list, persist                           |
+| `delete.absent-record-returns-404`              | DELETE of a missing id is 404, not 200                                                                                                     | delete                                                               | —                                       |
+| `concurrency.no-lost-update`                    | two PATCHes to different fields do not clobber each other                                                                                  | update + two writable strings                                        | persist + patch                         |
+| `validation.enum-enforced`                      | a value outside the enum is rejected                                                                                                       | enum in the request schema                                           | —                                       |
+| `validation.max-length-enforced`                | a string over `maxLength` is rejected                                                                                                      | maxLength                                                            | —                                       |
+| `validation.required-enforced`                  | omitting a required field is rejected                                                                                                      | required field                                                       | —                                       |
+| `validation.content-type-enforced`              | a wrong Content-Type is 415 when 415 is documented                                                                                         | documented 415                                                       | —                                       |
+| `spec.declared-rate-limit-is-honoured`          | no 429 arrives while oat paces under the rate `x-rate-limit` declares                                                                      | `x-rate-limit` with a rate                                           | —                                       |
+| `consistency.projections-agree`                 | list, item, and filtered views of the same field agree                                                                                     | item route + a comparable field                                      | list + persist + filter                 |
+
+On a typical untagged CRUD document (create, list, item, `page`/`limit`, maybe `sort`):
+
+- Foundations, PATCH/delete, and schema checks usually run.
+- The query matrix runs when filter/order/select/search roles resolve.
+- Isolation runs only if you configured two principals.
+- Spec-as-adversary and tagged behaviour never run — `doctor` says so.
+
+Worked examples of what a finding looks like:
+
+```text
+BACKEND_BUG   table   created row missing from GET /tables
+              list.read-after-write
+
+BACKEND_BUG   product  PATCH { name } cleared description
+              patch.minimality
+
+SECURITY      table    GET /tables/{id} readable with the other tenant's key
+              tenant.item-not-readable-cross-tenant
+
+SPEC_BUG      table    x-query.filterable lists "ghost"; filter=ghost.eq.x is 400
+              spec.declared-filterable-is-filterable
+
+BACKEND_BUG   table    in() is not the union of the equalities it lists
+              filter.in-is-union-of-eq
+
+BACKEND_BUG   table    an illegal filter operator is accepted
+              filter.illegal-op-rejected
+
+COVERAGE_GAP  batch    no x-async; receipt treated as the result
+              async.reaches-terminal-state
+```
+
+## Verdicts, skips, and exit codes
+
+| verdict        | meaning                                                              | fails `oat run`? |
+| -------------- | -------------------------------------------------------------------- | ---------------- |
+| `BACKEND_BUG`  | the handler is wrong                                                 | yes              |
+| `SPEC_BUG`     | the document is wrong (or disagrees with the handler)                | yes              |
+| `SECURITY`     | isolation/authz failure and `x-tenant` (or equivalent) was declared  | yes              |
+| `AMBIGUITY`    | same evidence, but the tenant boundary was only inferred             | yes              |
+| `COVERAGE_GAP` | the check could not run; the report names the missing tag or surface | no               |
+| `BLOCKED`      | a check this one depends on already failed                           | no               |
+
+Separate from findings:
+
+- **did not apply** — entity never had what `needs` lists (printed in the report, not a pass). Example: no `select` parameter → `select.projection-honoured` did not apply.
+- **inconclusive** — the check ran and stopped (empty listing, probe 4xx, no shared filterable field, …). Not a pass. The report prints the reason.
+
+Coverage is split **never** (zero entities could run it) vs **partial** (ran on some entities, skipped on others). A clean run still prints both. "Nothing found" and "nothing was looked for" are different.
+
+Cascade suppression is transitive: one root cause is one finding, not a page of consequences. A blocked check has **not** been verified; re-run after the cause is fixed.
+
+`oat run` exit `1` if any finding has a failing verdict. Gaps and blocked entries do not fail a full run. A targeted run (`--ops`) also exits `1` when any target did not end `held`.
+
+Console (stdout) after a run:
+
+```
+  50 checks · 5 entities · 842 requests · 41.2s · p95 90ms · 4 checks did not apply
+
+  BACKEND DEFECTS (1)
+    product          PATCH { name } also cleared description
+                     patch.minimality
+
+  DID NOT APPLY — no entity had what these need
+    async.reaches-terminal-state             needs an operation declaring x-async
+
+  leftover teardown printed next
+  report / matrix / graph / progress paths
+```

package/docs/commands.md

@@ -0,0 +1,214 @@
+# oat — Commands
+
+[← back to the overview](../README.md)
+
+## Commands
+
+```
+oat run          --config <file>     test a live backend and write a report
+oat doctor       --spec <url|file>   what oat can and cannot test, and why
+oat plan         --spec <url|file>   print the derived model (offline)
+oat serve        [--defects A,B]     run the demo API
+oat conformance                      self-test: injected defects vs detection
+oat help
+```
+
+`--spec` for `doctor` / `plan` can be replaced by `--config` (the spec is read from the config). `--json` makes those two commands emit machine-readable output. `--base-url` on `doctor` / `plan` is only used to resolve a relative spec path.
+
+`--untagged` is a **serve** flag (and a conformance concern). It is not a `run` flag.
+
+### `oat run`
+
+Requires `--config`. CLI flags override the same field in the config when both are set.
+
+| flag                                       | default                          | meaning                                                                                                                                         |
+| ------------------------------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--config`                                 | required                         | module or JSON file, default export                                                                                                             |
+| `--base-url`                               | `config.baseUrl`                 | backend origin                                                                                                                                  |
+| `--ops`                                    | `config.ops` or every operation  | comma-separated operationIds to grade; everything else is support. `*` globs, `<originId>:` prefixes. See [Targeted runs](#targeted-runs---ops) |
+| `--only`                                   | `config.only` or all entities    | comma-separated entity names as `oat plan` prints them (singularised); each grades every operation it owns. Joins `--ops` as a union            |
+| `--seed`                                   | `config.seed` or `1`             | fixture generation seed (reproducible)                                                                                                          |
+| `--out`                                    | `config.outDir` or `./.oat/runs` | history root; each run writes `<out>/<datetime>/` and updates `latest`                                                                          |
+| `--max-in-flight`                          | `config.maxInFlight` or `4`      | HTTP requests allowed at once                                                                                                                   |
+| `--keep-fixtures`                          | `config.keepFixtures` or false   | do not DELETE what the run created                                                                                                              |
+| `--quiet`                                  | false                            | no stderr progress; files under `--out` still update                                                                                            |
+| `--save-exchanges` / `--no-save-exchanges` | on unless `--profile cheap`      | persist every HTTP exchange under the run dir (`exchanges.jsonl`, `exchanges/`, `blobs/`). Does **not** change in-memory transcript RAM         |
+
+**Exit codes:** `0` no defects, `1` at least one root-cause finding (`BACKEND_BUG`, `SPEC_BUG`, `SECURITY`, `AMBIGUITY`) **or**, on a targeted run, a target that `failed`, `2` usage error (missing `--config`, no principals, unknown flag, a flag without its value or with a value of the wrong kind, an `--ops` / `--only` name that matches nothing, a target the profile excludes), `3` oat could not do what it was asked — the network never came back, the run graded no operation at all, a target was never judged, or oat itself failed. `COVERAGE_GAP` and `BLOCKED` do not fail a full run. `latest` moves to a run only once its reports are written.
+
+Example:
+
+```bash
+oat run --config oat.config.ts --only store,product --out .oat/runs/prod
+```
+
+`--only store,product` matches the **entity names** from `oat plan`, not path segments. `/v1/stores` is usually the entity `store`. An unknown name exits `2` with the nearest names.
+
+A run with no principals exits `2`. Isolation checks then need a second principal; they are skipped, not failed, when only one is present.
+
+### Targeted runs (`--ops`)
+
+A full run grades every operation. After changing two endpoints you usually want those two, not the whole API:
+
+```bash
+oat run --config oat.config.ts --ops table.create,row.list
+oat run --config oat.config.ts --ops 'row.*'            # glob within an operationId
+oat run --config oat.config.ts --ops cdn:asset.get      # an operation on the origin with id "cdn"
+oat plan --config oat.config.ts --ops table.create      # dry run: what would be graded, queued, called
+```
+
+**Targets** are graded: every check whose subjects include a target runs the full matrix against it. **Support** operations are called and never graded: principal sign-up, parent creates, the cohort create behind a list, reads used as an oracle, teardown deletes. A list route cannot be tested without rows in it, so its create still runs, but a defect in that create is out of this run's scope.
+
+How the scope is decided:
+
+- Every check declares its **subjects**, the operations whose contract it judges (`filter.*` judges the list route, `patch.minimality` the update, `effects.declared-effect-occurs` each `x-effects` operation). A check runs when one of its subjects is a target. Others are **out of scope**: not run, not skipped.
+- An entity is seeded only when one of its checks grades a target. Declared edges pull in the other direction too: targeting a read route that another entity's create names in `x-invalidate` queues that entity, so its invalidation check grades the route.
+- Checks that judge several operations (`effects.*`, `async.*`, `response.status-is-documented`, `schema.error-response-matches-document`, `invalidation.declared-route-changes`) invoke and judge only the targeted ones. An untargeted `x-effects` upload is never POSTed.
+- Every finding names the operations it judges (`operations` in `oat-report.json`).
+- An operation counts as graded only when a check exercised it. A check that judges after the fact (`response.status-is-documented` reads the transcript) grades only the operations it saw. A check that reports a coverage gap for an operation did not grade it. `--only <entity>` therefore surfaces every action no check can reach as `untested`.
+
+Each target ends with one status:
+
+| status         | meaning                                                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `held`         | at least one check graded it and none failed                                                                                                            |
+| `failed`       | a defect finding is attributed to it                                                                                                                    |
+| `inconclusive` | checks ran and none could decide                                                                                                                        |
+| `blocked`      | every check was suppressed, or a support operation it needed failed (named, with evidence)                                                              |
+| `untested`     | nothing exercised it. The reason says why (`unmodeled`, `entity-not-testable`, `coverage gap: …`, `no check applied: needs …`, `no check exercised it`) |
+
+A targeted run exits `0` only when every target is `held`. A target nothing could grade must not read as a pass.
+
+Validation happens before any principal signs up: a name that matches nothing exits `2` with the nearest operationIds; an exact target the active `--profile` excludes exits `2`; a glob or `--only` match the profile excludes is dropped and listed. An origin no target names is not run.
+
+A targeted run is for iterating. It grades what you named and what those operations observably affect through declared edges. It does not catch a regression in an untargeted operation caused by shared code, so run the full suite before a release.
+
+### `oat doctor`
+
+Offline. Loads the document, builds the model, prints coverage.
+
+```bash
+oat doctor --spec https://api.example.com/openapi.json
+oat doctor --config oat.config.ts --json
+oat doctor --spec ./openapi.yaml --base-url https://api.example.com
+```
+
+Human output:
+
+- `trackable` — entities with an identity and a read surface
+- `listable` — those that also have a list (query checks need this)
+- tags that are absent, and the checks each tag would unlock
+- tags that would **sharpen** checks that already run (`x-query`, `x-tenant`)
+- per-operation gaps (`x-entity` could not be inferred, assumed tenant param, …)
+- external `$ref`s that were not fetched
+
+`--json` shape:
+
+```json
+{
+	"blocking": 1,
+	"entities": 12,
+	"trackableEntities": 10,
+	"testableEntities": 10,
+	"listableEntities": 8,
+	"roots": ["organization_id"],
+	"externalRefs": ["https://example.com/shared.yaml"],
+	"gaps": [{ "operationId": "table.list", "tag": "x-query", "detail": "…" }]
+}
+```
+
+Exit `1` if there are **blocking** gaps: entities that are not trackable (no identity / no read), or the document has roots oat cannot create. Advisory gaps (missing `x-query`, no `x-async`) print and still exit `0`.
+
+### `oat plan`
+
+Offline. Prints the derived entity graph, operations, and query capability.
+
+```bash
+oat plan --spec ./openapi.yaml
+oat plan --config oat.config.ts --json
+```
+
+Human columns:
+
+```
+entity              CLRUD  ident      read surface
+store               CLRU·  id         2 route(s) (inferred)
+                                      GET /v1/stores
+                                      GET /v1/stores/{store_id}
+```
+
+`CLRUD` is Create / List / Read / Update / Delete. `·` means that slot is missing. `ident` is the identity property. Read surface is declared (`x-invalidate`) or inferred (sibling collection/item routes).
+
+`--json` is `{ entities, operations, roots }` — the full `SpecModel` maps, including conventions, query capability, async, invite, and path params. Use this when you need to know what oat will call something.
+
+With `--ops` / `--only` (flag or config), `plan` prints the targeted scope instead: each target with its entity and the checks that would grade it, untestable targets with the reason, the entities that would be queued, and the support operations predicted from the graph. `--json` adds a `scope` object with the same fields. An unknown name exits `2`.
+
+### `oat serve`
+
+In-process demo API. Same fixture as conformance.
+
+```bash
+oat serve
+oat serve --defects STALE_LIST,PATCH_REPLACES
+oat serve --backend sqlite --dialect classic
+oat serve --untagged
+```
+
+| flag         | default     | meaning                                                                                                    |
+| ------------ | ----------- | ---------------------------------------------------------------------------------------------------------- |
+| `--backend`  | `memory`    | `memory` \| `sqlite` \| `postgres`                                                                         |
+| `--dialect`  | `postgrest` | `postgrest` \| `classic` \| `linked` \| `jsonapi` \| `plain`                                               |
+| `--defects`  | none        | comma-separated names from [Reference defects](reference-defects.md#reference-defects-oat-serve---defects) |
+| `--untagged` | false       | serve the same API behind a spec with every `x-*` tag stripped                                             |
+
+Printed keys: `key_alpha` (tenant `proj_alpha`), `key_beta` (tenant `proj_beta`). Spec: `{url}/v1/openapi/spec`. Stop with ctrl-c.
+
+`labs/local.config.ts` is written for this server.
+
+Dialects are **reference-backend shapes**, not something you configure against your API. They exist so conformance proves checks read the document rather than one fixture's spelling:
+
+| dialect     | filter                      | sort       | select           | page model          | envelope                          |
+| ----------- | --------------------------- | ---------- | ---------------- | ------------------- | --------------------------------- |
+| `postgrest` | `filter=status.eq.active`   | `name.asc` | `select=id,name` | `page` + `cursor`   | entity-named + `count`/`hasMore`  |
+| `classic`   | `filter=status=eq:active`   | `sort=`    | `fields=`        | `page` + `per_page` | `{ data, total_count, has_more }` |
+| `linked`    | postgrest                   | dotted     | `fields=`        | `offset` + `limit`  | raw array + `Link: rel=next`      |
+| `jsonapi`   | postgrest                   | `-name`    | `fields[table]=` | `page` + `size`     | `{ data, total, has_more }`       |
+| `plain`     | `?status=active` (equality) | `name:asc` | `fields=`        | `page` + `limit`    | `{ items, total, has_more }`      |
+
+`postgres` needs a server on the default `postgres` database (local, default `postgres` driver connection). `sqlite` needs Node's `node:sqlite` (`--experimental-sqlite` on Node 22). Missing backends fail at serve time rather than falling back.
+
+### `oat conformance`
+
+Self-test. Not for your API. Injects named defects into the reference backend and asserts oat reports the matching check.
+
+```bash
+# this repo
+npm test
+
+# after install, from a checkout with --experimental-sqlite if you want sqlite
+oat conformance
+oat conformance --backend memory --dialect plain
+oat conformance --fuzz 300 --max-defects 12 --seed 7
+oat conformance --precision 60 --backend memory
+oat conformance --parser
+oat conformance --backend d1
+oat conformance --only STALE_LIST,PATCH_REPLACES
+```
+
+| flag              | meaning                                                                                                                            |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `--backend`       | `memory` \| `sqlite` \| `postgres` \| `d1`. Default: every _local_ backend that is available. `d1` is never default — it is remote |
+| `--dialect`       | pin one shape; default runs postgrest on each backend plus classic/linked/jsonapi/plain on memory                                  |
+| `--fuzz [n]`      | random _sets_ of defects (default 25 if flag is bare)                                                                              |
+| `--max-defects`   | cap per fuzz combination (default 4)                                                                                               |
+| `--precision [n]` | vary _data_ against a correct backend; any finding is a false positive (default 50 if flag is bare)                                |
+| `--seed`          | replay a fuzz/precision run                                                                                                        |
+| `--parser`        | only the hostile-document + example-spec + tag-unlock suites                                                                       |
+| `--only`          | restrict injected defects (comma-separated `STALE_LIST,…`)                                                                         |
+| `--jobs`          | legs run at once, each on its own thread (default: CPUs − 1, at most 4)                                                            |
+
+A default `oat conformance` (no `--fuzz` / `--precision` / `--parser`) also runs a 40-case combination smoke on memory after the one-at-a-time matrix, and `--ops` recall for every defect, reusing the matrix's own runs. The extra dialects run only the defects whose symptom depends on how a listing is asked for and answered.
+
+D1 needs `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_D1_DATABASE_ID`, `CLOUDFLARE_API_TOKEN`. Postgres needs a reachable server on the default connection (`database: "postgres"`). Missing backends are skipped with a printed reason, not treated as a pass.
+
+`--parser` still always runs first (hostile documents, `labs/annotated-openapi.yaml` model lock, tag-unlock map). Exit `1` if any parser, matrix, fuzz, or precision case fails.