@lovrozagar/oat 0.9.0 → 0.10.0

package/dist/runtime/checks.js

@@ -21,6 +21,44 @@ import { driveWait } from "./wait.js";
 import { fillPath, isPlanLimitResponse } from "./world.js";
 import { bodyPropertyNames, collisionCreateBody, collisionUpdatePatch, idempotencyHeaderRequired, probeableUniqueSets, reportUniqueSchemaDrift, uniquifyProbeBody, uniqueProbeHeaders, } from "./unique.js";
 import { bindAfterCreateEffects, bindCreatedScope, bindMissingPathParams, canFillPath, describeEffectHold, effectHolds, identityPathParam, } from "./effects.js";
+const graded = (ctx, op) => ctx.inScope?.(op) ?? true;
+/** The context a multi-operation check uses for one subject: its findings land on that operation. */
+function forOperation(ctx, op) {
+    return { ...ctx, findings: ctx.findings.attributed([op.operationId]) };
+}
+const declared = (...operationIds) => operationIds.filter((id) => id !== undefined && id !== "");
+const ownOps = (entity, model, keep) => model.operations.filter((op) => op.entity === entity.name && keep(op)).map((op) => op.operationId);
+/** Subject sets shared by the registry. Each reads the same fields the check's context is built from. */
+export const subjectsOf = {
+    async: (entity, model) => ownOps(entity, model, (op) => op.async !== null),
+    asyncReceipt: (entity, model) => ownOps(entity, model, (op) => op.async?.idFrom !== undefined),
+    create: (entity) => declared(entity.create),
+    createAndForeignReads: (entity, model) => {
+        const create = model.byOperationId.get(entity.create ?? "");
+        if (create === undefined)
+            return [];
+        const foreign = create.invalidates
+            .map((route) => model.byRoute.get(route))
+            .filter((op) => op !== undefined && op.entity !== entity.name && op.method.toUpperCase() === "GET")
+            .map((op) => op.operationId);
+        return [create.operationId, ...foreign];
+    },
+    createAndList: (entity) => declared(entity.create, entity.list),
+    delete: (entity) => declared(entity.delete),
+    deleteAndList: (entity) => declared(entity.delete, entity.list),
+    effects: (entity, model) => ownOps(entity, model, (op) => op.effects.length > 0),
+    invite: (entity) => entity.invite === null ? [] : declared(entity.invite.invite, entity.invite.accept, entity.invite.revoke),
+    list: (entity) => declared(entity.list),
+    nonCreate: (entity, model) => ownOps(entity, model, (op) => op.action !== "create"),
+    read: (entity) => declared(entity.read),
+    readAndGated: (entity, model) => [
+        ...new Set([...declared(entity.read), ...ownOps(entity, model, (op) => op.featureGate !== null)]),
+    ],
+    readAndList: (entity) => declared(entity.read, entity.list),
+    update: (entity) => declared(entity.update),
+    waits: (entity, model) => ownOps(entity, model, (op) => op.wait !== null),
+    writeAndRead: (entity) => declared(entity.update ?? entity.create, entity.read),
+};
 /* ------------------------------------------------------------------- helpers */
 /**
  * A documented feature-gate 403 is not a 2xx-check failure and not SECURITY.
@@ -473,6 +511,7 @@ const readAfterWrite = {
     mutates: true,
     id: "list.read-after-write",
     needs: "a create operation and at least one seeded record",
+    subjects: subjectsOf.createAndList,
     async run(ctx) {
         const target = ctx.records[0];
         if (target === undefined)
@@ -554,6 +593,7 @@ const unknownFilterRejected = {
     applicable: (ctx) => conv(ctx).filter !== undefined,
     id: "filter.unknown-field-rejected",
     needs: "a way to express a filter — a filter expression parameter, or filterable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const baseline = await list(ctx, q(ctx, { limit: 100 }));
         const unknownField = filterTerm(conv(ctx), "oat_no_such_field_xyz", "eq", 1);
@@ -579,6 +619,7 @@ const equalityFilterSelectsOne = {
     dependsOn: ["list.read-after-write"],
     id: "filter.equality-selects-exactly-one",
     needs: "a `filter` parameter that accepts the identity field",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const target = ctx.records[0];
         if (target === undefined)
@@ -605,6 +646,7 @@ const zeroMatchFilter = {
     dependsOn: ["list.read-after-write"],
     id: "filter.zero-match-returns-none",
     needs: "a `filter` parameter that accepts the identity field",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const term = filterTerm(conv(ctx), filterIdentity(ctx), "eq", "oat-nonexistent-value-000");
         if (term === null)
@@ -631,6 +673,7 @@ const negationPartitions = {
     ],
     id: "filter.negation-partitions-the-set",
     needs: "a `filter` parameter supporting eq and neq",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const target = ctx.records[0];
         if (target === undefined)
@@ -704,6 +747,7 @@ const filterAndComposesAsIntersection = {
     ],
     id: "filter.and-composes-as-intersection",
     needs: "two filterable fields and a filter parameter or grammar supporting eq",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const picked = twoFilterableFields(ctx);
@@ -766,6 +810,7 @@ const filterOrComposesAsUnion = {
     ],
     id: "filter.or-composes-as-union",
     needs: "two filterable fields and an or() combinator (postgrest-shaped filter grammar)",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const picked = twoFilterableFields(ctx);
@@ -823,6 +868,7 @@ const sortReverseSymmetry = {
     ],
     id: "sort.reverse-symmetry",
     needs: "an `order` parameter supporting asc and desc",
+    subjects: subjectsOf.list,
     async run(ctx) {
         /* A nullable sort key exercises null ordering, where the interesting bugs live. */
         const field = nullableField(ctx, ctx.query?.sortable ?? []) ??
@@ -881,6 +927,7 @@ const pageWalkCoversSet = {
     ],
     id: "pagination.page-walk-covers-set",
     needs: "a way to page forward — a page number or a row offset — and at least three records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const limit = ctx.query?.maxLimit ?? 100;
         /* Walk under a low-cardinality sort. Distinct keys admit exactly one valid order, so an
@@ -934,6 +981,7 @@ const cursorAgreesWithPage = {
     ],
     id: "pagination.cursor-agrees-with-page",
     needs: "both `cursor` and `page` parameters",
+    subjects: subjectsOf.list,
     async run(ctx) {
         /* Walk under an explicit text sort. Cursor pagination is almost always used with one, and
          * a boundary resolved under a different collation than the listing can only diverge when
@@ -985,6 +1033,7 @@ const countIsConsistentWithPage = {
     dependsOn: ["list.read-after-write"],
     id: "count.consistent-with-returned-page",
     needs: "a total-count field in the list envelope",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const result = await list(ctx, q(ctx, { limit: ctx.query?.maxLimit ?? 100 }));
         if (result.exchange.status >= 400)
@@ -1011,6 +1060,7 @@ const countMatchesWalk = {
     dependsOn: ["list.read-after-write", "filter.equality-selects-exactly-one"],
     id: "count.matches-filtered-set",
     needs: "a total-count field and a `filter` parameter",
+    subjects: subjectsOf.list,
     async run(ctx) {
         if (!identityIsFilterable(ctx))
             return;
@@ -1037,6 +1087,7 @@ const selectProjection = {
     applicable: (ctx) => conv(ctx).select !== undefined && ctx.records.length > 0,
     id: "select.projection-honoured",
     needs: "a `select` sparse-fieldset parameter",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const requested = [ctx.identity];
         const extra = ctx.query?.selectable.find((f) => f !== ctx.identity);
@@ -1067,6 +1118,7 @@ const patchMinimality = {
     mutates: true,
     id: "patch.minimality",
     needs: "an update operation and an item route",
+    subjects: subjectsOf.update,
     async run(ctx) {
         const target = ctx.records.find((r) => Object.values(r).some((v) => typeof v === "string"));
         if (target === undefined || ctx.updateOp === undefined || ctx.readOp === undefined)
@@ -1183,6 +1235,7 @@ const immutableRejected = {
     mutates: true,
     id: "patch.immutable-field-rejected",
     needs: "fields declared immutable via x-immutable",
+    subjects: subjectsOf.update,
     async run(ctx) {
         /*
          * Deliberately not `records[0]`.
@@ -1230,6 +1283,7 @@ const likeEscaping = {
     dependsOn: ["list.read-after-write"],
     id: "filter.like-metacharacters-escaped",
     needs: "a `filter` parameter supporting a like operator",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = firstFilterable(ctx, (name) => (ctx.query?.searchable ?? []).includes(name));
         if (field === null) {
@@ -1259,6 +1313,7 @@ const createStatusMatchesSpec = {
     applicable: (ctx) => ctx.createOp !== undefined,
     id: "create.status-matches-document",
     needs: "a create operation",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.createOp;
         if (createOp === undefined)
@@ -1301,6 +1356,7 @@ const deleteMissingIs404 = {
     mutates: true,
     id: "delete.absent-record-returns-404",
     needs: "a delete operation",
+    subjects: subjectsOf.delete,
     async run(ctx) {
         if (ctx.deleteOp === undefined)
             return;
@@ -1326,6 +1382,7 @@ const softDeleteHidden = {
     dependsOn: ["list.read-after-write"],
     id: "softdelete.absent-from-default-list",
     needs: "a delete operation and x-soft-delete",
+    subjects: subjectsOf.deleteAndList,
     async run(ctx) {
         const target = ctx.records.at(-1);
         if (target === undefined || ctx.deleteOp === undefined)
@@ -1367,6 +1424,7 @@ const denialDoesNotRevealExistence = {
     ],
     id: "tenant.denial-does-not-reveal-existence",
     needs: "a second principal in a different tenant, and a tenant tagged or inferred from the path",
+    subjects: subjectsOf.read,
     async run(ctx) {
         const target = ctx.records[0];
         if (target === undefined || ctx.readOp === undefined || ctx.altAuth === undefined)
@@ -1411,6 +1469,7 @@ const idempotentReplay = {
     id: "idempotency.replay-does-not-duplicate",
     mutates: true,
     needs: "a create operation declaring an idempotency-key header",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.createOp;
         const header = createOp?.idempotencyHeader;
@@ -1466,13 +1525,20 @@ const declaredInvalidationHappens = {
     id: "invalidation.declared-route-changes",
     mutates: true,
     needs: "a create operation whose x-invalidate names another entity's read route",
+    subjects: subjectsOf.createAndForeignReads,
     async run(ctx) {
         const createOp = ctx.createOp;
         if (createOp === undefined)
             return;
+        /* A graded create is judged through every route it declares; a graded route alone is
+         * judged only itself, with the create as support. */
+        const createGraded = graded(ctx, createOp);
         const foreign = createOp.invalidates
             .map((route) => ctx.model.byRoute.get(route))
-            .filter((op) => op !== undefined && op.entity !== ctx.entityName && op.method.toUpperCase() === "GET");
+            .filter((op) => op !== undefined &&
+            op.entity !== ctx.entityName &&
+            op.method.toUpperCase() === "GET" &&
+            (createGraded || graded(ctx, op)));
         if (foreign.length === 0)
             return;
         const schema = requestSchemaOf(ctx, createOp);
@@ -1519,7 +1585,12 @@ const declaredInvalidationHappens = {
                 continue;
             if (JSON.stringify(after.responseBody) !== snapshot)
                 continue;
-            ctx.findings.backend(this.id, ctx.entityName, "a route the document says is invalidated by this write did not change", `creating a ${ctx.entityName} declares x-invalidate on "${probe.op.route}", but that ` +
+            ctx.findings
+                .attributed([
+                ...(createGraded ? [createOp.operationId] : []),
+                ...(graded(ctx, probe.op) ? [probe.op.operationId] : []),
+            ])
+                .backend(this.id, ctx.entityName, "a route the document says is invalidated by this write did not change", `creating a ${ctx.entityName} declares x-invalidate on "${probe.op.route}", but that ` +
                 "route returned a byte-identical body before and after the write. Either it serves " +
                 "a value derived from this entity and that value is stale — a denormalised counter " +
                 "or a cached projection nobody refreshed — or the declaration is wrong and every " +
@@ -1560,6 +1631,7 @@ const projectionsAgree = {
     ],
     id: "consistency.projections-agree",
     needs: "an item route and a record with a comparable field",
+    subjects: subjectsOf.readAndList,
     async run(ctx) {
         const target = ctx.records[0];
         if (target === undefined || ctx.readOp === undefined)
@@ -1672,6 +1744,7 @@ const queryAxesCompose = {
     ],
     id: "query.axes-compose",
     needs: "a filterable field, a sortable field, and more than two records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const limit = ctx.query?.maxLimit ?? 100;
@@ -1764,6 +1837,7 @@ const filterAndPagingCompose = {
     ],
     id: "query.filter-selects-from-whole-set",
     needs: "a filterable field and more than two records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         /* A small page deliberately: the bug only shows once the window excludes matching rows,
@@ -1856,6 +1930,7 @@ const filterAndSelectCompose = {
     ],
     id: "query.filter-and-select-compose",
     needs: "a filterable field, a select parameter, and more than two records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const limit = ctx.query?.maxLimit ?? 100;
@@ -1944,6 +2019,7 @@ const searchAndFilterCompose = {
     ],
     id: "query.search-and-filter-compose",
     needs: "a filterable field, a free-text search parameter, and more than two records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const limit = ctx.query?.maxLimit ?? 100;
@@ -2058,6 +2134,7 @@ const filterSortSelectCompose = {
     ],
     id: "query.filter-sort-select-compose",
     needs: "a filterable field, a sortable field, a select parameter, and more than two records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const limit = ctx.query?.maxLimit ?? 100;
@@ -2126,6 +2203,7 @@ const filterSearchSortCompose = {
     ],
     id: "query.filter-search-sort-compose",
     needs: "a filterable field, a search parameter, a sortable field, and more than two records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const limit = ctx.query?.maxLimit ?? 100;
@@ -2185,6 +2263,7 @@ const filterSearchSelectCompose = {
     ],
     id: "query.filter-search-select-compose",
     needs: "a filterable field, a search parameter, a select parameter, and more than two records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const limit = ctx.query?.maxLimit ?? 100;
@@ -2357,6 +2436,7 @@ const declaredFilterableWorks = {
     ],
     id: "spec.declared-filterable-is-filterable",
     needs: "x-query naming filterable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const rejected = [];
@@ -2415,6 +2495,7 @@ const declaredSortableWorks = {
     ],
     id: "spec.declared-sortable-is-sortable",
     needs: "x-query naming sortable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const rejected = [];
@@ -2464,6 +2545,7 @@ const declaredSelectableWorks = {
     ],
     id: "spec.declared-selectable-is-selectable",
     needs: "x-query naming selectable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const conventions = conv(ctx);
         const rejected = [];
@@ -2497,6 +2579,7 @@ const crossTenantItemRead = {
     applicable: (ctx) => ctx.altAuth !== undefined && ctx.readOp !== undefined && ctx.records.length > 0 && tenantBoundary(ctx.readOp),
     id: "tenant.item-not-readable-cross-tenant",
     needs: "a second principal in a different tenant, and a tenant tagged or inferred from the path",
+    subjects: subjectsOf.read,
     async run(ctx) {
         const target = ctx.records[0];
         if (target === undefined || ctx.readOp === undefined || ctx.altAuth === undefined)
@@ -2546,6 +2629,7 @@ const crossTenantFilterBypass = {
     dependsOn: ["query.filter-selects-from-whole-set"],
     id: "tenant.filter-does-not-bypass-scope",
     needs: "a second principal, a filter, and a tenant tagged or inferred from the path",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const target = ctx.records[0];
         if (target === undefined || ctx.altAuth === undefined || ctx.altScope === undefined)
@@ -2613,6 +2697,7 @@ const rankIsMonotonic = {
     dependsOn: ["list.read-after-write"],
     id: "auth.rank-is-monotonic",
     needs: "two same-tenant principals at different ranks, and an item route",
+    subjects: subjectsOf.read,
     async run(ctx) {
         const target = ctx.records[0];
         const primary = ctx.actors[0];
@@ -2678,6 +2763,7 @@ const inviteGrantsThenRevokes = {
     dependsOn: ["list.read-after-write", "tenant.item-not-readable-cross-tenant"],
     id: "auth.invite-grants-then-revokes",
     needs: "x-invite naming invite/accept/revoke, a peer principal with inviteAs, and an item or list route",
+    subjects: subjectsOf.invite,
     async run(ctx) {
         const spec = ctx.invite;
         const owner = ctx.actors[0];
@@ -2812,6 +2898,7 @@ const malformedFilterNot5xx = {
     applicable: (ctx) => filterable(ctx),
     id: "error.malformed-filter-not-5xx",
     needs: "a way to express a filter — a filter expression parameter, or filterable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const result = await list(ctx, q(ctx, { filter: "((((", limit: 10 }));
         if (result.exchange.status < 500)
@@ -2825,6 +2912,7 @@ const limitBoundsPageSize = {
     dependsOn: ["list.read-after-write"],
     id: "pagination.limit-bounds-page-size",
     needs: "a page-size query parameter named `limit`",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const result = await list(ctx, q(ctx, { limit: 2 }));
         if (result.exchange.status >= 400)
@@ -2844,6 +2932,7 @@ const limitRespectsMax = {
     dependsOn: ["pagination.limit-bounds-page-size"],
     id: "pagination.limit-respects-documented-max",
     needs: "a declared maxLimit, and more records than it",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const max = ctx.query?.maxLimit;
         if (max === undefined)
@@ -2862,6 +2951,7 @@ const hasMoreIsAccurate = {
     dependsOn: ["pagination.limit-bounds-page-size"],
     id: "pagination.has-more-is-accurate",
     needs: "a way to page forward, and a more-pages signal in the body or a Link header",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const first = await list(ctx, q(ctx, { limit: 1, page: 1 }));
         if (first.exchange.status >= 400 || first.items.length === 0)
@@ -2885,6 +2975,7 @@ const orderChangesResult = {
     dependsOn: ["pagination.limit-bounds-page-size"],
     id: "sort.order-is-applied",
     needs: "an `order` parameter and a sortable field",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = ctx.query?.sortable.find((f) => f !== ctx.identity) ?? ctx.query?.sortable[0];
         if (field === undefined)
@@ -2932,6 +3023,7 @@ const searchNarrowsResult = {
     dependsOn: ["list.read-after-write"],
     id: "search.q-narrows-result",
     needs: "a free-text `q` parameter and declared searchable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = ctx.query?.searchable[0];
         if (field === undefined)
@@ -2955,6 +3047,7 @@ const createPersistsFields = {
     dependsOn: ["list.read-after-write"],
     id: "create.persists-submitted-fields",
     needs: "a create operation that echoes the record back",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.createOp;
         if (createOp === undefined)
@@ -2988,6 +3081,7 @@ const enumValidated = {
     mutates: true,
     id: "validation.enum-enforced",
     needs: "a request schema with an enum field",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.createOp;
         if (createOp === undefined)
@@ -3018,6 +3112,7 @@ const maxLengthValidated = {
     mutates: true,
     id: "validation.max-length-enforced",
     needs: "a request schema with a maxLength constraint",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.createOp;
         if (createOp === undefined)
@@ -3047,6 +3142,7 @@ const requiredValidated = {
     mutates: true,
     id: "validation.required-enforced",
     needs: "a request schema with a required field",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.createOp;
         if (createOp === undefined)
@@ -3077,6 +3173,7 @@ const contentTypeEnforced = {
     mutates: true,
     id: "validation.content-type-enforced",
     needs: "a documented 415 response",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.createOp;
         if (createOp === undefined)
@@ -3102,6 +3199,7 @@ const errorSchemaHonoured = {
     applicable: (ctx) => ctx.validator !== undefined && ctx.readOp !== undefined,
     id: "schema.error-response-matches-document",
     needs: "a documented error schema on the item route",
+    subjects: subjectsOf.readAndGated,
     async run(ctx) {
         const readOp = ctx.readOp;
         const validator = ctx.validator;
@@ -3110,21 +3208,16 @@ const errorSchemaHonoured = {
         const raw = ctx.model.rawOperations.get(readOp.operationId);
         if (raw === undefined)
             return;
-        const params = { ...ctx.scope, ...itemParamFor(ctx, "oat-definitely-missing-id") };
-        const exchange = await ctx.client.get(fillPath(readOp.path, params), { headers: ctx.auth() });
-        if (exchange.status >= 400 && validator.documents(raw, exchange.status)) {
-            const result = validator.validate(readOp.operationId, raw, exchange.status, exchange.responseBody);
-            if (!result.ok) {
-                ctx.findings.spec(this.id, ctx.entityName, `${exchange.status} error body does not match its documented schema`, `${readOp.operationId} returned ${exchange.status} with a body that fails the schema the ` +
-                    `document declares for it: ${result.errors.join("; ")}. Clients that parse errors ` +
-                    "from the spec will not understand this response.", [exchange]);
-            }
+        const judged = [];
+        if (graded(ctx, readOp)) {
+            await probeMissingItemError(ctx, readOp, raw, validator, this.id);
+            judged.push(readOp.operationId);
         }
         /* A documented feature-gate 403 is coverage for the 2xx check, not for the error schema.
          * Walk this entity's already-observed gate denials so an undeclared body is still drift. */
         const seen = new Set();
         for (const op of ctx.model.operations) {
-            if (op.entity !== ctx.entityName || op.featureGate === null)
+            if (op.entity !== ctx.entityName || op.featureGate === null || !graded(ctx, op))
                 continue;
             const opRaw = ctx.model.rawOperations.get(op.operationId);
             if (opRaw === undefined)
@@ -3136,11 +3229,26 @@ const errorSchemaHonoured = {
                 if (seen.has(key))
                     continue;
                 seen.add(key);
-                reportFeatureGateSchemaDrift(ctx.findings, validator, op, opRaw, prior, ctx.entityName);
+                judged.push(op.operationId);
+                reportFeatureGateSchemaDrift(ctx.findings.attributed([op.operationId]), validator, op, opRaw, prior, ctx.entityName);
             }
         }
     },
 };
+async function probeMissingItemError(ctx, readOp, raw, validator, check) {
+    const params = { ...ctx.scope, ...itemParamFor(ctx, "oat-definitely-missing-id") };
+    const exchange = await ctx.client.get(fillPath(readOp.path, params), { headers: ctx.auth() });
+    if (exchange.status < 400 || !validator.documents(raw, exchange.status))
+        return;
+    const result = validator.validate(readOp.operationId, raw, exchange.status, exchange.responseBody);
+    if (result.ok)
+        return;
+    ctx.findings
+        .attributed([readOp.operationId])
+        .spec(check, ctx.entityName, `${exchange.status} error body does not match its documented schema`, `${readOp.operationId} returned ${exchange.status} with a body that fails the schema the ` +
+        `document declares for it: ${result.errors.join("; ")}. Clients that parse errors ` +
+        "from the spec will not understand this response.", [exchange]);
+}
 const successSchemaHonoured = {
     applicable: (ctx) => ctx.validator !== undefined && ctx.createOp !== undefined,
     /* The body is validated against the schema declared *for the status that came back*. When the
@@ -3149,6 +3257,7 @@ const successSchemaHonoured = {
     dependsOn: ["create.status-matches-document"],
     id: "schema.success-response-matches-document",
     needs: "a documented success schema on create",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.createOp;
         const validator = ctx.validator;
@@ -3325,6 +3434,7 @@ const numericComparisonIsNumeric = {
     dependsOn: ["list.read-after-write", "filter.unknown-field-rejected"],
     id: "filter.numeric-comparison-is-numeric",
     needs: "a `filter` parameter and a numeric field",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = numericFilterField(ctx);
         if (field === null)
@@ -3409,6 +3519,7 @@ const noLostUpdate = {
     id: "concurrency.no-lost-update",
     needs: "an update operation and two writable string fields",
     mutates: true,
+    subjects: subjectsOf.update,
     async run(ctx) {
         const target = ctx.records[0];
         if (target === undefined || ctx.updateOp === undefined || ctx.readOp === undefined)
@@ -3522,8 +3633,10 @@ const declaredEffectsOccur = {
     mutates: true,
     id: "effects.declared-effect-occurs",
     needs: "an operation declaring x-effects",
-    async run(ctx) {
-        for (const op of ctx.effectOps) {
+    subjects: subjectsOf.effects,
+    async run(all) {
+        for (const op of all.effectOps) {
+            const ctx = forOperation(all, op);
             await forEachInvocation(op.operationId, ctx.uploads, async (uploads, slot) => {
                 const fixture = slot?.filename;
                 const effects = op.effects;
@@ -3639,8 +3752,10 @@ const sideEffectArrives = {
     mutates: true,
     id: "effects.side-effect-arrives",
     needs: "an operation declaring x-wait",
-    async run(ctx) {
-        for (const op of ctx.waitOps) {
+    subjects: subjectsOf.waits,
+    async run(all) {
+        for (const op of all.waitOps) {
+            const ctx = forOperation(all, op);
             const spec = op.wait;
             if (spec === null)
                 continue;
@@ -3723,8 +3838,10 @@ const asyncReachesTerminalState = {
     mutates: true,
     id: "async.reaches-terminal-state",
     needs: "an operation declaring x-async",
-    async run(ctx) {
-        for (const op of ctx.asyncOps) {
+    subjects: subjectsOf.async,
+    async run(all) {
+        for (const op of all.asyncOps) {
+            const ctx = forOperation(all, op);
             const spec = op.async;
             if (spec === null)
                 continue;
@@ -3779,8 +3896,10 @@ const asyncReceiptIsResolvable = {
     applicable: (ctx) => ctx.asyncOps.some((op) => op.async?.idFrom !== undefined),
     id: "async.receipt-identifies-the-job",
     needs: "x-async with an idFrom pointer",
-    async run(ctx) {
-        for (const op of ctx.asyncOps) {
+    subjects: subjectsOf.asyncReceipt,
+    async run(all) {
+        for (const op of all.asyncOps) {
+            const ctx = forOperation(all, op);
             const spec = op.async;
             if (spec?.idFrom === undefined)
                 continue;
@@ -3859,6 +3978,7 @@ const stringPayloadSurvives = {
     id: "payload.string-survives",
     mutates: true,
     needs: "an update or create+delete, an item route, and a writable unconstrained string",
+    subjects: subjectsOf.writeAndRead,
     async run(ctx) {
         const writeOp = ctx.updateOp ?? ctx.createOp;
         const readOp = ctx.readOp;
@@ -4040,9 +4160,11 @@ const documentedStatusHonoured = {
     applicable: (ctx) => ctx.model.operations.some((op) => op.entity === ctx.entityName && op.action !== "create"),
     id: "response.status-is-documented",
     needs: "a modeled non-create operation on this entity",
+    subjects: subjectsOf.nonCreate,
     async run(ctx) {
         const createId = ctx.createOp?.operationId;
         const byOp = new Map();
+        const observed = new Set();
         for (const exchange of ctx.client.transcript) {
             let pathname;
             try {
@@ -4054,21 +4176,25 @@ const documentedStatusHonoured = {
             const op = resolveEntityOperation(ctx, exchange.method, pathname);
             if (op === null)
                 continue;
-            if (op.operationId === createId || op.action === "create")
+            if (!graded(ctx, op))
                 continue;
-            if (isDocumentedFeatureGateDenial(op, exchange.status, exchange.responseBody))
+            if (op.operationId === createId || op.action === "create")
                 continue;
             if (exchange.status === 429)
                 continue;
             const raw = ctx.model.rawOperations.get(op.operationId);
             if (!declaresConcreteStatuses(raw))
                 continue;
+            observed.add(op.operationId);
+            if (isDocumentedFeatureGateDenial(op, exchange.status, exchange.responseBody))
+                continue;
             if (statusIsDeclared(raw, exchange.status))
                 continue;
             const seen = byOp.get(op.operationId) ?? [];
             seen.push(exchange);
             byOp.set(op.operationId, seen);
         }
+        ctx.judged?.([...observed]);
         if (byOp.size === 0)
             return;
         const lines = [];
@@ -4085,7 +4211,9 @@ const documentedStatusHonoured = {
             if (first !== undefined && evidence.length < 6)
                 evidence.push(first);
         }
-        ctx.findings.spec(this.id, ctx.entityName, "an operation returned a status the document does not declare", `${lines.join(". ")}. Clients generated from this document will not recognise the response.`, evidence);
+        ctx.findings
+            .attributed([...byOp.keys()])
+            .spec(this.id, ctx.entityName, "an operation returned a status the document does not declare", `${lines.join(". ")}. Clients generated from this document will not recognise the response.`, evidence);
     },
 };
 function pickFieldForOp(ctx, op, minDistinct = 2) {
@@ -4120,6 +4248,7 @@ const filterInIsUnionOfEq = {
     dependsOn: [...FOUNDATIONS, "filter.equality-selects-exactly-one"],
     id: "filter.in-is-union-of-eq",
     needs: "a field that allows `in` and at least two distinct values",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const picked = pickFieldForOp(ctx, "in", 2);
         if (picked === null)
@@ -4156,6 +4285,7 @@ const filterNinComplementsIn = {
     dependsOn: [...FOUNDATIONS, "filter.in-is-union-of-eq"],
     id: "filter.nin-complements-in",
     needs: "a field that allows both `in` and `nin`",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const picked = pickFieldForOp(ctx, "in", 1);
         if (picked === null || !canUseOp(ctx, picked.field, "nin"))
@@ -4201,6 +4331,7 @@ const filterGteIsGtOrEq = {
     dependsOn: [...FOUNDATIONS, "filter.equality-selects-exactly-one", "filter.numeric-comparison-is-numeric"],
     id: "filter.gte-is-gt-or-eq",
     needs: "an ordered field that allows `gte` and `gt`",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const picked = pickOrderedField(ctx);
         if (picked === null || !canUseOp(ctx, picked.field, "gte"))
@@ -4216,6 +4347,7 @@ const filterLteIsLtOrEq = {
     dependsOn: [...FOUNDATIONS, "filter.equality-selects-exactly-one", "filter.numeric-comparison-is-numeric"],
     id: "filter.lte-is-lt-or-eq",
     needs: "an ordered field that allows `lte` and `lt`",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const picked = pickOrderedField(ctx);
         if (picked === null || !canUseOp(ctx, picked.field, "lte"))
@@ -4254,6 +4386,7 @@ const filterOrderedTriplePartitions = {
     dependsOn: [...FOUNDATIONS, "filter.equality-selects-exactly-one", "filter.numeric-comparison-is-numeric"],
     id: "filter.ordered-triple-partitions",
     needs: "an ordered field that allows `lt`, `eq`, and `gt`",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const picked = pickOrderedField(ctx);
         if (picked === null)
@@ -4308,6 +4441,7 @@ const filterIlikeIsCaseInsensitive = {
     dependsOn: [...FOUNDATIONS, "filter.like-metacharacters-escaped"],
     id: "filter.ilike-is-case-insensitive",
     needs: "a field that allows both `ilike` and `like`, and a string with a letter",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = fieldsAllowing(ctx, "ilike").find((item) => canUseOp(ctx, item, "like"));
         if (field === undefined)
@@ -4356,6 +4490,7 @@ const filterIsNullSelectsNulls = {
     dependsOn: [...FOUNDATIONS],
     id: "filter.is-null-selects-nulls",
     needs: "a field that allows `is` and a cohort that contains a null",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = fieldsAllowing(ctx, "is").find((item) => mixedNullField(ctx, item.field));
         if (field === undefined)
@@ -4393,6 +4528,7 @@ const filterContainsMembership = {
     dependsOn: [...FOUNDATIONS],
     id: "filter.contains-membership",
     needs: "an array field that allows `contains` and a known element",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = resolvedCaps(ctx).filterable.find((item) => canUseOp(ctx, item, "contains") &&
             ctx.records.some((row) => Array.isArray(row[item.field]) && row[item.field].length > 0));
@@ -4427,6 +4563,7 @@ const filterNestedAndOrDistributes = {
     dependsOn: [...FOUNDATIONS, "filter.and-composes-as-intersection", "filter.or-composes-as-union"],
     id: "filter.nested-and-or-distributes",
     needs: "a postgrest-shaped grammar and two filterable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const picked = twoFilterableFields(ctx);
         if (picked === null) {
@@ -4474,6 +4611,7 @@ const filterAliasMatchesCanonical = {
     dependsOn: [...FOUNDATIONS, "filter.equality-selects-exactly-one"],
     id: "filter.alias-matches-canonical",
     needs: "a declared filter operator alias",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const caps = resolvedCaps(ctx);
         const conventions = conv(ctx);
@@ -4516,6 +4654,7 @@ const filterIllegalOpRejected = {
     dependsOn: ["list.read-after-write", "filter.unknown-field-rejected", "error.malformed-filter-not-5xx"],
     id: "filter.illegal-op-rejected",
     needs: "a field with a closed operator list",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = resolvedCaps(ctx).filterable.find((item) => firstIllegalOp(ctx, item) !== undefined);
         const op = field === undefined ? undefined : firstIllegalOp(ctx, field);
@@ -4544,6 +4683,7 @@ const filterEmptyIn = {
     dependsOn: [...FOUNDATIONS, "filter.in-is-union-of-eq"],
     id: "filter.empty-in",
     needs: "`emptyIn` declared and a field that allows `in`",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const picked = pickFieldForOp(ctx, "in", 1);
         const policy = resolvedCaps(ctx).emptyIn;
@@ -4576,6 +4716,7 @@ const filterInOverLimitRejected = {
     dependsOn: [...FOUNDATIONS, "error.malformed-filter-not-5xx"],
     id: "filter.in-over-limit-rejected",
     needs: "`maxInValues` declared and a field that allows `in`",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const max = resolvedCaps(ctx).maxInValues;
         const picked = pickFieldForOp(ctx, "in", 1);
@@ -4598,6 +4739,7 @@ const filterConditionCapRejected = {
     dependsOn: [...FOUNDATIONS, "error.malformed-filter-not-5xx"],
     id: "filter.condition-cap-rejected",
     needs: "`maxFilterConditions` declared and a grammar that can group eq terms",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const max = resolvedCaps(ctx).maxFilterConditions;
         const parameter = conv(ctx).filter;
@@ -4632,6 +4774,7 @@ const declaredFilterableOpsAccepted = {
     dependsOn: ["list.read-after-write", "spec.declared-filterable-is-filterable", "error.malformed-filter-not-5xx"],
     id: "spec.declared-filterable-ops-accepted",
     needs: "a closed operator list on at least one declared field",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const caps = resolvedCaps(ctx);
         const rejected = [];
@@ -4661,6 +4804,7 @@ const declaredFilterableIllegalOpRejected = {
     dependsOn: ["filter.illegal-op-rejected", "spec.declared-filterable-is-filterable"],
     id: "spec.declared-filterable-illegal-op-rejected",
     needs: "a closed operator list on a declared field",
+    subjects: subjectsOf.list,
     async run(ctx) {
         await filterIllegalOpRejected.run(ctx);
     },
@@ -4670,6 +4814,7 @@ const sortUnknownFieldRejected = {
     dependsOn: ["error.malformed-filter-not-5xx"],
     id: "sort.unknown-field-rejected",
     needs: "an order parameter",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const result = await list(ctx, q(ctx, { limit: 5, order: sortTerm(conv(ctx), "oat_no_such_sort_xyz", "asc") }));
         if (result.exchange.status >= 500) {
@@ -4691,6 +4836,7 @@ const sortNumericOrderIsNumeric = {
     dependsOn: ["sort.order-is-applied"],
     id: "sort.numeric-order-is-numeric",
     needs: "a numeric sortable field whose lexical order disagrees with numeric order",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = resolvedCaps(ctx).sortable.find((item) => numericLexicalDisagrees(ctx, item.field));
         if (field === undefined)
@@ -4713,6 +4859,7 @@ const sortNullsFirstLast = {
     dependsOn: ["sort.order-is-applied", "sort.reverse-symmetry"],
     id: "sort.nulls-first-last",
     needs: "a declared nulls token, a dotted sort grammar, and a null in the cohort",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = resolvedCaps(ctx).sortable.find((item) => (fieldAllowsNulls(item, resolvedCaps(ctx), "first") || fieldAllowsNulls(item, resolvedCaps(ctx), "last")) &&
             ctx.records.some((row) => row[item.field] === null || row[item.field] === undefined));
@@ -4774,6 +4921,7 @@ const sortMultiKeyTiebreak = {
     dependsOn: ["sort.order-is-applied", "sort.reverse-symmetry"],
     id: "sort.multi-key-tiebreak",
     needs: "two sortable fields and rows that tie on the first and differ on the second",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const pair = pickMultiKeyPair(ctx);
         if (pair === null) {
@@ -4798,6 +4946,7 @@ const sortDefaultOrderApplied = {
     dependsOn: ["sort.order-is-applied", "pagination.page-walk-covers-set"],
     id: "sort.default-order-applied",
     needs: "a declared defaultOrder and a complete walk",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const declared = resolvedCaps(ctx).sort?.defaultOrder ?? ctx.query?.defaultOrder;
         if (declared === undefined)
@@ -4821,6 +4970,7 @@ const sortStableTiebreak = {
     dependsOn: ["sort.order-is-applied"],
     id: "sort.stable-tiebreak",
     needs: "a declared stableTiebreak and a tie on the primary key",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const tiebreak = resolvedCaps(ctx).sort?.stableTiebreak ?? ctx.query?.stableTiebreak;
         const primary = ctx.query?.sortable.find((name) => name !== tiebreak) ?? ctx.query?.sortable[0];
@@ -4843,6 +4993,7 @@ const declaredSortableNullsAccepted = {
     dependsOn: ["sort.order-is-applied"],
     id: "spec.declared-sortable-nulls-accepted",
     needs: "a declared nulls token on a sortable field",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const rejected = [];
         for (const field of resolvedCaps(ctx).sortable) {
@@ -4868,6 +5019,7 @@ const searchTokensAnd = {
     dependsOn: ["search.q-narrows-result"],
     id: "search.tokens-and",
     needs: "searchable fields and two tokens that split the cohort",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = ctx.query?.searchable[0];
         if (field === undefined)
@@ -4911,6 +5063,7 @@ const searchCaseInsensitive = {
     dependsOn: ["search.q-narrows-result"],
     id: "search.case-insensitive",
     needs: "a searchable string with a letter",
+    subjects: subjectsOf.list,
     async run(ctx) {
         let sample;
         for (const field of ctx.query?.searchable ?? []) {
@@ -4947,6 +5100,7 @@ const searchEmptyQ = {
     dependsOn: ["search.q-narrows-result"],
     id: "search.empty-q",
     needs: "`searchEmpty` declared",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const policy = resolvedCaps(ctx).searchEmpty;
         if (policy === undefined)
@@ -4978,6 +5132,7 @@ const searchUndeclaredFieldNotRequired = {
     dependsOn: ["search.q-narrows-result"],
     id: "search.undeclared-field-not-required",
     needs: "a searchable field and a non-searchable string",
+    subjects: subjectsOf.list,
     async run() {
         /* Extra recall is not a defect. This check exists so undeclared-field hits are not
          * reported as SEARCH_IGNORED by other checks. */
@@ -4995,6 +5150,7 @@ const searchModeAccepted = {
         conv(ctx).search !== undefined,
     id: "search.mode-accepted",
     needs: "declared searchModes and a search-mode parameter",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const rejected = [];
         for (const mode of resolvedCaps(ctx).searchModes ?? []) {
@@ -5014,6 +5170,7 @@ const searchModesDiffer = {
     dependsOn: ["search.mode-accepted"],
     id: "search.modes-differ",
     needs: "at least two declared searchModes and a mode parameter",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const modes = resolvedCaps(ctx).searchModes ?? [];
         const a = modes[0];
@@ -5042,6 +5199,7 @@ const selectRequestedFieldsPresent = {
     dependsOn: ["select.projection-honoured"],
     id: "select.requested-fields-present",
     needs: "a select parameter and at least one selectable field",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const requested = [
             ctx.identity,
@@ -5070,6 +5228,7 @@ const selectUnknownFieldRejected = {
     dependsOn: ["select.projection-honoured", "error.malformed-filter-not-5xx"],
     id: "select.unknown-field-rejected",
     needs: "`select.unknown` declared",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const policy = resolvedCaps(ctx).select?.unknown;
         if (policy === undefined)
@@ -5101,6 +5260,7 @@ const selectNestedHonoured = {
     dependsOn: ["select.projection-honoured"],
     id: "select.nested-honoured",
     needs: "select.nested and a named relation",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const relation = resolvedCaps(ctx).select?.relations?.[0];
         if (relation === undefined || relation.fields[0] === undefined)
@@ -5133,6 +5293,7 @@ const querySortAndSelectCompose = {
     dependsOn: ["sort.order-is-applied", "select.projection-honoured", "select.requested-fields-present"],
     id: "query.sort-and-select-compose",
     needs: "sortable and selectable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = ctx.query?.sortable.find((name) => name !== ctx.identity) ?? ctx.query?.sortable[0];
         const extra = ctx.query?.selectable.find((name) => name !== ctx.identity);
@@ -5167,6 +5328,7 @@ const querySearchAndSelectCompose = {
     dependsOn: ["search.q-narrows-result", "select.projection-honoured"],
     id: "query.search-and-select-compose",
     needs: "searchable and selectable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const field = ctx.query?.searchable[0];
         if (field === undefined)
@@ -5201,6 +5363,7 @@ const querySearchAndSortCompose = {
     dependsOn: ["search.q-narrows-result", "sort.order-is-applied"],
     id: "query.search-and-sort-compose",
     needs: "searchable and sortable fields",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const searchField = ctx.query?.searchable[0];
         const sortField = ctx.query?.sortable.find((name) => name !== ctx.identity) ?? ctx.query?.sortable[0];
@@ -5248,6 +5411,7 @@ const queryFilterSearchSortSelectCompose = {
     ],
     id: "query.filter-search-sort-select-compose",
     needs: "all four list axes declared and at least three records",
+    subjects: subjectsOf.list,
     async run(ctx) {
         const picked = overlappingFilterAndSearch(ctx);
         if (picked === null) {
@@ -5319,6 +5483,7 @@ const uniqueConflictCreate = {
     id: "create.unique-conflict-rejected",
     mutates: true,
     needs: "x-unique on create with at least one probeable column set, and a known row",
+    subjects: subjectsOf.create,
     async run(ctx) {
         const createOp = ctx.uniqueCreateOp;
         if (createOp === undefined)
@@ -5387,6 +5552,7 @@ const uniqueConflictUpdate = {
     id: "update.unique-conflict-rejected",
     mutates: true,
     needs: "x-unique, an update operation with a probeable set, and two known rows",
+    subjects: subjectsOf.update,
     async run(ctx) {
         const updateOp = ctx.uniqueUpdateOp;
         if (updateOp === undefined)