@lovrozagar/oat 0.9.1 → 0.11.0

package/dist/spec/schema.js

@@ -0,0 +1,118 @@
+/**
+ * One reading of an OpenAPI schema, shared by everything that interprets one.
+ *
+ * The validator, the value generator and the model each used to interpret JSON Schema on their
+ * own, and they disagreed: one stripped `example` anywhere it appeared — including a property
+ * *named* example — another ignored `writeOnly`, a third read OpenAPI 3.0's boolean
+ * `exclusiveMinimum` as a number. A schema is now translated once into JSON Schema 2020-12, for a
+ * stated direction, and every consumer reads the result.
+ *
+ * Direction matters because OpenAPI schemas are shared between requests and responses:
+ * `readOnly` properties never appear in a request and `writeOnly` ones never in a response.
+ */
+/** Keywords whose value is one subschema. */
+const SINGLE = [
+    "items",
+    "additionalItems",
+    "additionalProperties",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+    "not",
+    "if",
+    "then",
+    "else",
+    "contains",
+    "propertyNames",
+];
+/** Keywords whose value is a list of subschemas. */
+const LIST = ["allOf", "anyOf", "oneOf", "prefixItems"];
+/** Keywords whose value maps names to subschemas. */
+const MAP = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"];
+/** OpenAPI annotations that are not JSON Schema keywords — removed from schema nodes only. */
+const OPENAPI_ONLY = new Set(["nullable", "example", "discriminator", "xml", "externalDocs"]);
+function isSchema(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Translates `schema` into JSON Schema 2020-12 as seen in `direction`. Never mutates its input. */
+export function normalizeSchema(schema, options) {
+    const seen = new Map();
+    const visit = (node) => {
+        const cached = seen.get(node);
+        if (cached !== undefined)
+            return cached;
+        const out = {};
+        seen.set(node, out);
+        for (const [key, value] of Object.entries(node)) {
+            if (OPENAPI_ONLY.has(key))
+                continue;
+            if (SINGLE.includes(key) && isSchema(value))
+                out[key] = visit(value);
+            else if (LIST.includes(key) && Array.isArray(value)) {
+                out[key] = value.map((item) => (isSchema(item) ? visit(item) : item));
+            }
+            else if (key === "items" && Array.isArray(value)) {
+                /* Draft-04 tuple form: positional item schemas. */
+                out.prefixItems = value.map((item) => (isSchema(item) ? visit(item) : item));
+            }
+            else if (MAP.includes(key) && isSchema(value)) {
+                const map = {};
+                for (const [name, sub] of Object.entries(value))
+                    map[name] = isSchema(sub) ? visit(sub) : sub;
+                out[key] = map;
+            }
+            else
+                out[key] = value;
+        }
+        /* OpenAPI 3.0 exclusive bounds are booleans qualifying `minimum` / `maximum`. */
+        for (const [flag, bound] of [
+            ["exclusiveMinimum", "minimum"],
+            ["exclusiveMaximum", "maximum"],
+        ]) {
+            if (typeof out[flag] !== "boolean")
+                continue;
+            if (out[flag] === true && typeof out[bound] === "number") {
+                out[flag] = out[bound];
+                delete out[bound];
+            }
+            else
+                delete out[flag];
+        }
+        /* Properties that do not travel in this direction are neither allowed nor required. */
+        const hidden = options.direction === "request" ? "readOnly" : "writeOnly";
+        if (isSchema(out.properties)) {
+            const properties = { ...out.properties };
+            const dropped = Object.entries(properties)
+                .filter(([, sub]) => isSchema(sub) && sub[hidden] === true)
+                .map(([name]) => name);
+            for (const name of dropped)
+                delete properties[name];
+            out.properties = properties;
+            if (Array.isArray(out.required))
+                out.required = out.required.filter((name) => !dropped.includes(String(name)));
+        }
+        /* `nullable` widens whatever the schema otherwise allows. 3.1 has no such keyword, but
+         * generators still emit it, and reading it there costs nothing. */
+        if (node.nullable === true)
+            return nullable(out);
+        return out;
+    };
+    return visit(schema);
+}
+/** `schema` or null — by widening `type` and `enum` where that is exact, by a union where not. */
+function nullable(schema) {
+    const type = schema.type;
+    const typed = typeof type === "string" || Array.isArray(type);
+    const composite = ["allOf", "anyOf", "oneOf", "$ref", "not", "const"].some((key) => key in schema);
+    if (typed && !composite) {
+        const out = { ...schema };
+        const types = Array.isArray(type) ? [...type] : [type];
+        if (!types.includes("null"))
+            types.push("null");
+        out.type = types;
+        if (Array.isArray(out.enum) && !out.enum.includes(null))
+            out.enum = [...out.enum, null];
+        return out;
+    }
+    return { anyOf: [schema, { type: "null" }] };
+}
+//# sourceMappingURL=schema.js.map

package/dist/spec/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/spec/schema.ts"],"names":[],"mappings":"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"}

package/dist/spec/tag-schema.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every oat tag, checked against its shape.
+ *
+ * Readers stay defensive — a tag they cannot use is ignored — but ignoring it silently meant a
+ * typo read as an absence: `x-destructive: yes` was simply not destructive. A tag that is present
+ * and malformed is a gap naming the tag and what is wrong with it, so `doctor` shows it.
+ */
+import type { GapCollector } from "./extensions.ts";
+import type { OperationObject } from "./types.ts";
+/** Records a gap for every oat tag on `op` (and its parameters) that is present but malformed. */
+export declare function validateTags(op: OperationObject, operationId: string, gaps: GapCollector): void;
+//# sourceMappingURL=tag-schema.d.ts.map

package/dist/spec/tag-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-schema.d.ts","sourceRoot":"","sources":["../../src/spec/tag-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,YAAY,CAAA;AA6IlE,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,EAAE,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAa/F"}

package/dist/spec/tag-schema.js

@@ -0,0 +1,143 @@
+/**
+ * Every oat tag, checked against its shape.
+ *
+ * Readers stay defensive — a tag they cannot use is ignored — but ignoring it silently meant a
+ * typo read as an absence: `x-destructive: yes` was simply not destructive. A tag that is present
+ * and malformed is a gap naming the tag and what is wrong with it, so `doctor` shows it.
+ */
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const ROUTE = /^[A-Za-z]+\s+\/\S*$/;
+const string = (value) => (typeof value === "string" && value !== "" ? null : "must be a non-empty string");
+const boolean = (value) => (typeof value === "boolean" ? null : "must be true or false");
+const route = (value) => typeof value === "string" && ROUTE.test(value.trim()) ? null : 'must be a route like "GET /path"';
+const strings = (value) => Array.isArray(value) && value.every((item) => typeof item === "string") ? null : "must be an array of strings";
+const oneOf = (...allowed) => (value) => allowed.includes(value) ? null : `must be one of ${allowed.map((a) => `"${a}"`).join(", ")}`;
+const positive = (value) => (typeof value === "number" && value > 0 ? null : "must be a positive number");
+const integer = (value) => typeof value === "number" && Number.isInteger(value) && value > 0 ? null : "must be a positive integer";
+const stringMap = (value) => isObject(value) && Object.values(value).every((item) => typeof item === "string") ? null : "must map names to strings";
+/** An object with these fields; `required` must be present, the rest are checked when present. */
+const shape = (fields, required = []) => (value) => {
+    if (!isObject(value))
+        return "must be an object";
+    for (const key of required)
+        if (value[key] === undefined)
+            return `needs "${key}"`;
+    for (const [key, entry] of Object.entries(value)) {
+        const check = fields[key];
+        if (check === undefined || entry === undefined)
+            continue;
+        const problem = check(entry);
+        if (problem !== null)
+            return `"${key}" ${problem}`;
+    }
+    return null;
+};
+/** One query axis: field names, structured rows, or `null` for an explicit "none". */
+const axis = (row) => {
+    const fieldRow = shape(row, ["field"]);
+    return (value) => {
+        if (value === null)
+            return null;
+        if (!Array.isArray(value))
+            return "must be an array of field names or { field } rows";
+        for (const item of value) {
+            if (typeof item === "string")
+                continue;
+            const problem = fieldRow(item);
+            if (problem !== null)
+                return `has a row that ${problem}`;
+        }
+        return null;
+    };
+};
+const harvest = shape({ operationId: string, path: string, typeMap: stringMap, typePath: string }, [
+    "operationId",
+    "path",
+]);
+/** `x-query`, as `docs/tags.md` documents it. */
+const xQuery = shape({
+    aliases: stringMap,
+    defaultOrder: string,
+    emptyIn: oneOf("reject", "match-none"),
+    filterable: axis({ field: string, ops: strings, type: string }),
+    filterableFrom: harvest,
+    grammar: oneOf("postgrest", "colon", "equality"),
+    identityFilter: string,
+    maxFilterConditions: integer,
+    maxInValues: integer,
+    maxLimit: integer,
+    maxSortKeys: integer,
+    operators: strings,
+    operatorsByType: (value) => isObject(value) && Object.values(value).every((ops) => strings(ops) === null)
+        ? null
+        : "must map type names to arrays of operators",
+    searchable: axis({ field: string }),
+    searchableFrom: harvest,
+    searchEmpty: oneOf("ignore", "match-all", "reject"),
+    searchModes: strings,
+    selectable: axis({ field: string }),
+    selectableFrom: harvest,
+    selectNested: boolean,
+    selectUnknown: oneOf("reject", "ignore"),
+    sortable: axis({ field: string, nulls: strings, type: string }),
+    sortableFrom: harvest,
+    sortCollation: oneOf("binary", "case-insensitive", "locale"),
+    sortDefaultNulls: oneOf("first", "last"),
+    sortNulls: strings,
+    stableTiebreak: string,
+});
+const OPERATION_TAGS = {
+    "x-async": shape({ idFrom: string, poll: string, pollIntervalMs: positive, successWhen: string, timeoutMs: positive, until: string }, ["poll"]),
+    "x-cleanup": route,
+    "x-cost": oneOf("low", "medium", "high"),
+    "x-destructive": boolean,
+    "x-entity": shape({
+        action: oneOf("create", "list", "read", "update", "delete", "action"),
+        identity: string,
+        name: string,
+    }, ["name", "action"]),
+    "x-feature-gate": string,
+    "x-fresh-principal": boolean,
+    "x-generated": strings,
+    "x-idempotent": boolean,
+    "x-immutable": strings,
+    "x-invalidate": (value) => Array.isArray(value) && value.every((item) => route(item) === null)
+        ? null
+        : 'must be an array of routes like "GET /path"',
+    "x-invite": shape({
+        accept: string,
+        acceptFrom: oneOf("link"),
+        grantPointer: string,
+        granteeField: string,
+        invite: string,
+        revoke: string,
+        tokenFrom: oneOf("response", "outOfBand"),
+        tokenKind: string,
+        tokenPointer: string,
+    }, ["invite", "accept", "revoke"]),
+    "x-query": xQuery,
+    "x-rate-limit": shape({ category: string, rps: positive }, ["category"]),
+    "x-soft-delete": string,
+    "x-tenant": string,
+    "x-wait": shape({ operationId: string, pollIntervalMs: positive, timeoutMs: positive, until: string }, [
+        "operationId",
+    ]),
+};
+/** Records a gap for every oat tag on `op` (and its parameters) that is present but malformed. */
+export function validateTags(op, operationId, gaps) {
+    const record = op;
+    for (const [tag, check] of Object.entries(OPERATION_TAGS)) {
+        if (record[tag] === undefined)
+            continue;
+        const problem = check(record[tag]);
+        if (problem !== null)
+            gaps.record(operationId, tag, `${tag} ${problem}; oat cannot use it`);
+    }
+    for (const parameter of (op.parameters ?? [])) {
+        const root = parameter["x-root"];
+        if (root !== undefined && typeof root !== "boolean") {
+            gaps.record(operationId, "x-root", `x-root on "${parameter.name}" must be true or false; oat cannot use it`);
+        }
+    }
+}
+//# sourceMappingURL=tag-schema.js.map

package/dist/spec/tag-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-schema.js","sourceRoot":"","sources":["../../src/spec/tag-schema.ts"],"names":[],"mappings":"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"}

package/dist/spec/types.js

@@ -10,7 +10,7 @@ export function listEndpoints(doc) {
             const op = item[method];
             if (op === null || typeof op !== "object")
                 continue;
-            const operation = op;
+            const operation = withPathParameters(op, item.parameters);
             out.push({
                 method,
                 op: operation,
@@ -21,4 +21,20 @@ export function listEndpoints(doc) {
     }
     return out;
 }
+/**
+ * An operation with its path item's `parameters` folded in.
+ *
+ * A path item may declare parameters once for every operation under it, and an operation may
+ * override one by name and location. Reading only the operation's own list lost every shared
+ * path parameter, and with it the declared schema of each identifier.
+ */
+function withPathParameters(op, shared) {
+    if (!Array.isArray(shared) || shared.length === 0)
+        return op;
+    const own = op.parameters ?? [];
+    const key = (p) => `${String(p.in)}:${String(p.name)}`;
+    const overridden = new Set(own.map(key));
+    const inherited = shared.filter((parameter) => parameter !== null && typeof parameter === "object" && !overridden.has(key(parameter)));
+    return inherited.length === 0 ? op : { ...op, parameters: [...inherited, ...own] };
+}
 //# sourceMappingURL=types.js.map

package/dist/spec/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/spec/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AA8ChF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAU,CAAA;AAGjG,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAA;AAUhG,MAAM,UAAU,aAAa,CAAC,GAAoB;IACjD,MAAM,GAAG,GAAe,EAAE,CAAA;IAC1B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAQ;QACvD,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;YACnC,MAAM,EAAE,GAAI,IAAgC,CAAC,MAAM,CAAC,CAAA;YACpD,IAAI,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,KAAK,QAAQ;gBAAE,SAAQ;YACnD,MAAM,SAAS,GAAG,EAAqB,CAAA;YACvC,GAAG,CAAC,IAAI,CAAC;gBACR,MAAM;gBACN,EAAE,EAAE,SAAS;gBACb,WAAW,EAAE,SAAS,CAAC,WAAW,IAAI,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,EAAE;gBACvE,IAAI;aACJ,CAAC,CAAA;QACH,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/spec/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AA8ChF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAU,CAAA;AAGjG,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAA;AAUhG,MAAM,UAAU,aAAa,CAAC,GAAoB;IACjD,MAAM,GAAG,GAAe,EAAE,CAAA;IAC1B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAQ;QACvD,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;YACnC,MAAM,EAAE,GAAI,IAAgC,CAAC,MAAM,CAAC,CAAA;YACpD,IAAI,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,KAAK,QAAQ;gBAAE,SAAQ;YACnD,MAAM,SAAS,GAAG,kBAAkB,CAAC,EAAqB,EAAG,IAAiC,CAAC,UAAU,CAAC,CAAA;YAC1G,GAAG,CAAC,IAAI,CAAC;gBACR,MAAM;gBACN,EAAE,EAAE,SAAS;gBACb,WAAW,EAAE,SAAS,CAAC,WAAW,IAAI,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,EAAE;gBACvE,IAAI;aACJ,CAAC,CAAA;QACH,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,EAAmB,EAAE,MAAe;IAC/D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IAC5D,MAAM,GAAG,GAAG,EAAE,CAAC,UAAU,IAAI,EAAE,CAAA;IAC/B,MAAM,GAAG,GAAG,CAAC,CAAmC,EAAU,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAA;IAChG,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;IACxC,MAAM,SAAS,GAAI,MAA4B,CAAC,MAAM,CACrD,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CACrG,CAAA;IACD,OAAO,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,UAAU,EAAE,CAAC,GAAG,SAAS,EAAE,GAAG,GAAG,CAAC,EAAE,CAAA;AACnF,CAAC"}

package/docs/api.md

@@ -0,0 +1,59 @@
+# oat — Programmatic API
+
+[← back to the overview](../README.md)
+
+## Programmatic API
+
+```ts
+import {
+	defineConfig,
+	loadConfig,
+	run,
+	loadSpec,
+	dereference,
+	buildModel,
+	renderJson,
+	renderMarkdown,
+} from "@lovrozagar/oat"
+
+const config = defineConfig({
+	spec: "./openapi.yaml",
+	baseUrl: "https://api.example.com",
+	principals: [{ id: "alpha", headers: { authorization: `Bearer ${process.env.API_TOKEN}` } }],
+})
+
+const result = await run({
+	spec: config.spec,
+	baseUrl: config.baseUrl,
+	principals: config.principals,
+	seed: 1,
+	maxInFlight: 4,
+	onProgress: (snap) => {
+		// snap.phase, snap.entity, snap.check, snap.inflight, snap.last, snap.message, …
+	},
+})
+
+// result.findings, result.checksSkipped, result.checksSuppressed,
+// result.inconclusive, result.entitiesTested, result.teardown, result.created,
+// result.scope (per-operation status), result.checksOutOfScope
+// pass `ops: ["product.update"]` to run() for a targeted run; ScopeError on an unknown name
+```
+
+`loadConfig(path)` loads `.ts` / `.js` / `.mjs` / `.json` the same way the CLI does. The CLI then expands `${NAME}` in every string. `defineConfig` is an identity function for typing; it does not interpolate. If you call `run()` with an in-process object, resolve secrets yourself (template literals, `process.env`) before passing it.
+
+`runVerdict(result)` is the verdict the CLI and every report state: `{ outcome, reason }`, where
+`outcome` is `clean`, `defects` or `failed` (a run that graded nothing, a network that went away, or
+a `--ops` target never judged). `exitCode(result)` is that outcome as the CLI's exit code, from
+`EXIT`: 0, 1 or 3.
+
+`run(options)` does not write files. The CLI writes reports after `run` returns. To produce the same artifacts, call `renderMarkdown` / `renderJson` / `renderMatrixHtml` / `renderMatrixGraph` / `renderRepros` with a `ReportInput` (`findings`, `model`, `client`, `baseUrl`, `entitiesTested`, `checksRun`, `startedAt`, `durationMs`, plus optional skip/suppress/inconclusive lists).
+
+Offline:
+
+```ts
+const doc = await loadSpec("./openapi.yaml")
+const { doc: resolved, externalRefs } = dereference(doc)
+const model = buildModel(resolved)
+```
+
+Types exported: `OatConfig`, `Principal`, `AuthFlow`, `AuthRefresh`, `AuthStep`, `HookAuth`, `Hooks`, `Uploads`, `UploadRequest`, `UploadFile`, `HeaderRequest`, `InputRequest`, `OriginSpec`, `OutOfBandConfig`, `OutOfBandRequest`, `TeardownPrincipalContext`, `RunOptions`, `RunResult`, `Finding`, `Verdict`, `Actor`, `SpecModel`, `EntityModel`, `OperationModel`, `OpenApiDocument`, `AuthRefreshRequiredError`, `loadPersistedPrincipals`, `worstCaseWaitMs`, `allocateRunDir`, `DEFAULT_RUNS_ROOT`, matrix types.

package/docs/assumptions.md

@@ -0,0 +1,99 @@
+# oat — Assumptions
+
+[← back to the overview](../README.md)
+
+oat tests a backend against its own document, and where the document is silent it has to assume
+something. This page lists every such assumption, what oat does when an API does not fit it, and
+how to declare the exception. An assumption that does not hold should never become a false
+finding: it should become a skip, an inconclusive verdict or a coverage gap that names the tag that
+would settle it. If one of these produces a finding against a correct backend, that is an oat bug.
+
+## Shape of the API
+
+| oat assumes                                                                                           | when it does not hold                                                 | declare                                                                       |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| A resource is a noun in the path: `/tables`, `/tables/{id}`                                           | the operation is untracked; `doctor` names the gap                    | [`x-entity`](tags.md#x-entity) `{ name, action }`                             |
+| An instance is identified by `id`, `uuid`, `slug`, `key` or `name`, or by the trailing path parameter | the entity is not trackable, and checks that need a record stand down | `x-entity.identity`                                                           |
+| Creating is `POST` to the collection, and the response carries the created record                     | the cohort cannot be seeded; dependent checks are blocked             | [`x-async`](tags.md#x-async) for a receipt, `x-entity` for a create elsewhere |
+| A record oat created can be deleted by its item route                                                 | teardown reports what it left behind                                  | [`x-cleanup`](tags.md#x-cleanup)                                              |
+| Path parameters oat cannot create are supplied                                                        | the entity cannot be reached                                          | [`x-root`](tags.md#x-root), or `roots` in the config                          |
+| A list answers with an array, or an object holding one                                                | list checks stand down                                                | the collection schema                                                         |
+
+## Lists and paging
+
+| oat assumes                                                                                                                                                                          | when it does not hold                                              | declare                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| Paging parameters carry recognisable names (`limit`, `page`, `offset`, `cursor`, …)                                                                                                  | the role is unresolved and the paging checks do not apply          | the parameter's name or default, or [`x-query`](tags.md#x-query) `maxLimit` |
+| A set has ended when a page is empty, shorter than a full page already seen, or the envelope says so — and, when the envelope carries both a total and a more-pages flag, they agree | oat keeps reading; it never takes the requested page size as proof | nothing: a server may serve fewer rows than asked for                       |
+| A server pages by one mechanism consistently                                                                                                                                         | a read that sees pages repeat stops and is unresolved              | —                                                                           |
+| A set larger than 500 records is too large to compare whole                                                                                                                          | checks that need the whole set are unresolved, not failed          | smaller cohorts, or a filtered scope                                        |
+
+## Queries
+
+| oat assumes                                                                              | when it does not hold                                                  | declare                                            |
+| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- |
+| Filtering is written in a grammar the document demonstrates (PostgREST, colon, equality) | filter checks do not apply                                             | `x-query.grammar`                                  |
+| Without `x-query`, every scalar property can be filtered, sorted and selected            | probes reach fields the backend never indexed; findings name the guess | `x-query` `filterable` / `sortable` / `selectable` |
+| A declared operator is accepted for a value of the field's own type                      | —                                                                      | per-field `ops` and `type` in `x-query`            |
+| Only 400 and 422 mean "this capability is not supported"                                 | 401, 403, 404 and 429 leave the check unresolved; a 5xx is a finding   | —                                                  |
+| An alias of an allowed operator is allowed                                               | —                                                                      | `x-query.aliases`                                  |
+
+## Ordering
+
+| oat assumes                                                                                                     | when it does not hold                                | declare                    |
+| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------- |
+| Numbers sort numerically                                                                                        | `sort.numeric-order-is-numeric` reports text order   | —                          |
+| Text sorts by one consistent collation — binary, case-insensitive or locale — whichever the backend shows first | a sequence sorted under none of them is a finding    | `x-query.sortCollation`    |
+| Nulls sit together at one end, the same end every time                                                          | nulls in the middle, or switching ends, is a finding | `x-query.sortDefaultNulls` |
+| Descending is ascending reversed, up to ties                                                                    | —                                                    | —                          |
+| Tied records may come back in any order unless a tiebreak is declared                                           | —                                                    | `x-query.stableTiebreak`   |
+
+## Writes
+
+| oat assumes                                                           | when it does not hold                              | declare                                                          |
+| --------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
+| `PATCH` changes only the fields it names                              | the minimality and lost-update checks report it    | —                                                                |
+| `PUT` replaces the whole record                                       | partial-update checks stand down on a PUT-only API | the update operation's method                                    |
+| A field the server owns is marked `readOnly` or generated             | oat would try to write it                          | `readOnly`, or [`x-generated`](tags.md#x-immutable--x-generated) |
+| A field that must never change after create is declared               | not tested                                         | [`x-immutable`](tags.md#x-immutable--x-generated)                |
+| A `writeOnly` field is accepted and not returned                      | —                                                  | `writeOnly`                                                      |
+| A header named like `Idempotency-Key` promises replay                 | the replay check does not apply                    | the header's name                                                |
+| A unique column set is declared, and a duplicate is refused with 409  | —                                                  | [`x-unique`](tags.md#x-unique)                                   |
+| A deleted record leaves the default listing, unless it is a tombstone | —                                                  | [`x-soft-delete`](tags.md#x-soft-delete)                         |
+
+## Errors and statuses
+
+| oat assumes                                                                                                  | when it does not hold                                                              | declare                                    |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------ |
+| A refusal of invalid input is 400 or 422; of a wrong content type, 415 (when documented); of a conflict, 409 | any other refusal leaves the check unresolved                                      | —                                          |
+| A 5xx is never the right answer to bad input                                                                 | it is a finding                                                                    | —                                          |
+| Every status an operation returns is documented, ranges (`2XX`) and `default` included                       | the status check reports the gap, apart from what deliberately invalid probes drew | the response                               |
+| A documented feature gate answers 403 with `vars.type: feature_gate`                                         | the 403 is a backend failure                                                       | [`x-feature-gate`](tags.md#x-feature-gate) |
+
+## Isolation and authorization
+
+| oat assumes                                                             | when it does not hold                                                             | declare                                                |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| A second principal with different `roots` is another tenant             | isolation checks do not apply                                                     | `principals`                                           |
+| The tenant is a path parameter, or declared                             | an inferred tenant makes a cross-tenant read an ambiguity, not a security finding | [`x-tenant`](tags.md#x-tenant)                         |
+| A denial does not depend on whether the record exists                   | —                                                                                 | —                                                      |
+| Higher `rank` can do everything a lower rank can                        | a lower rank seeing more is a finding                                             | `rank` on principals                                   |
+| An invite grants nothing until accepted, and a revoke takes access away | —                                                                                 | [`x-invite`](tags.md#x-invite) and a peer's `inviteAs` |
+
+## Async work, effects and pacing
+
+| oat assumes                                                                          | when it does not hold                                                    | declare                                                                  |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| A write is complete when it answers                                                  | —                                                                        | [`x-async`](tags.md#x-async), [`x-wait`](tags.md#x-wait)                 |
+| A write affects only its own entity and the routes it declares                       | other entities' changes are not tested                                   | [`x-invalidate`](tags.md#x-invalidate), [`x-effects`](tags.md#x-effects) |
+| Entities that share no parent, invalidated route or effect cannot observe each other | they are tested side by side                                             | the shared relation, declared                                            |
+| A rate the document declares is the rate the backend enforces                        | a 429 under it is a finding; a config-supplied rate is only paced around | [`x-rate-limit`](tags.md#x-rate-limit--pacing-oats-own-traffic)          |
+
+## What oat never assumes
+
+- That your data has a ground truth. Every oracle compares the API with itself.
+- That the requested page size is the size served.
+- That a field absent from the cohort cannot exist: a declared field is probed with a value of its
+  own type.
+- That an unanswered question is a pass: a check that cannot conclude says why, and a check that
+  does not apply says what it needs.