@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-filterable-is-filterable.js

@@ -0,0 +1,139 @@
+import { defineCheck } from "../../core/define.js";
+import { filterTerm } from "../../../../spec/conventions/filter.js";
+import { FILTER_OPS } from "../../../../spec/query/ops.js";
+import { ASSERTED } from "../../../finding.js";
+import { filterSentinel } from "../../../generate/identifiers.js";
+import { when } from "../../core/plan.js";
+import { declarationAnswer } from "../../planning/declarations.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { asTermValue, canUseOp, conv, q, resolvedCaps, schemaType } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+/**
+ * A capability the document declares must actually exist.
+ *
+ * `x-query.filterable` is a promise: every client generated from that document will offer a filter
+ * on each field named there. When the backend rejects one, the backend is not necessarily wrong —
+ * it is entitled to refuse a column it never indexed — but the *document* is, and it is wrong in
+ * the most expensive way, because the failure only appears at runtime in someone else's client.
+ *
+ * The API tester is uniquely positioned to catch this: it is the only thing that reads the claim and then
+ * tries it. Note the verdict is SPEC_BUG rather than BACKEND_BUG — the fix is to correct the
+ * document or index the column, and saying which is not the API tester's call.
+ *
+ * This also closes a silent-skip: every filter check treats a 4xx as a capability statement and
+ * stands down, which is right when the field was merely inferred and wrong when it was declared.
+ */
+export const declaredFilterableWorks = defineCheck({
+    plan: (ctx) => when(conv(ctx).filter !== undefined &&
+        ctx.query?.source === "tag" &&
+        (ctx.query?.filterable.length ?? 0) > 0 &&
+        ctx.records.length > 0),
+    dependsOn: [
+        "list.read-after-write",
+        /* The evidence is a *rejection*. A backend that silently drops unknown filter fields never
+         * rejects anything, so an overclaimed field comes back 200 and this check would report the
+         * document as honest — the dropped-filter defect is the finding to act on first. */
+        "filter.unknown-field-rejected",
+        /* And only a 4xx counts: a backend whose filter parser throws answers *every* bad filter
+         * with a 500, which makes "the document declared a field the backend refuses"
+         * indistinguishable from "the parser is broken". That is the finding to fix first. */
+        "error.malformed-filter-not-5xx",
+    ],
+    id: "spec.declared-filterable-is-filterable",
+    lists: true,
+    needs: "x-query naming filterable fields",
+    subjects: subjectsOf.list,
+    async run(ctx) {
+        const conventions = conv(ctx);
+        const rejected = [];
+        const unknown = [];
+        let probed = 0;
+        /* Every field at once; the answers are judged in declaration order. */
+        const answers = await Promise.all((ctx.query?.filterable ?? []).map(async (field) => {
+            /* A declared field that never appears on the cohort is still a promise — often the
+             * most expensive kind, a column the document invented. It is probed with an operator
+             * the field allows and a value of the field's own type: a backend that rejects a
+             * string compared with a number is right to, and that says nothing about the field. */
+            const probe = capabilityProbe(ctx, field);
+            if (probe === null)
+                return null;
+            const term = filterTerm(conventions, { field, op: probe.op, value: probe.value });
+            if (term === null)
+                return null;
+            return { field, result: await list(ctx, { ...q(ctx, { limit: 5 }), ...term }) };
+        }));
+        for (const answered of answers) {
+            if (answered === null)
+                continue;
+            const { field, result } = answered;
+            probed += 1;
+            /* Only a rejection counts. A filter that returns the wrong rows is a backend defect
+             * other checks own; this one is strictly about the capability existing. */
+            const answer = declarationAnswer(result.exchange.status);
+            if (answer === "refused")
+                rejected.push({ exchange: result.exchange, field, status: result.exchange.status });
+            if (answer === "unknown")
+                unknown.push(`${field} (${result.exchange.status})`);
+        }
+        if (probed === 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "no declared filterable field holds a non-null value in the cohort, so none could be probed");
+        }
+        if (rejected.length === 0 && unknown.length > 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `probes were turned away without a verdict: ${unknown.join(", ")}`);
+        }
+        if (rejected.length === 0)
+            return ASSERTED;
+        return ctx.findings.spec(this.id, ctx.entityName, {
+            summary: "the document declares a filter the backend does not accept",
+            detail: `x-query lists ${rejected.length} field(s) as filterable that the backend rejects: ` +
+                `${rejected.map((r) => `${r.field} (${r.status})`).join(", ")}. ` +
+                "Every client generated from this document will offer a filter that fails at runtime. " +
+                "Either the column needs an index or the declaration needs removing — but the " +
+                "document and the backend currently disagree about what this API can do.",
+            evidence: rejected.slice(0, 3).map((item) => item.exchange),
+        });
+    },
+});
+/**
+ * An operator the field allows and a value of the field's own type, to ask whether a declared
+ * filter exists at all. Equality where it is allowed; membership for an array.
+ */
+function capabilityProbe(ctx, name) {
+    const caps = resolvedCaps(ctx);
+    const field = caps.filterable.find((item) => item.field === name) ?? { field: name };
+    const type = field.type ?? schemaType(ctx, name);
+    const sample = ctx.records.find((record) => record[name] !== null && record[name] !== undefined)?.[name];
+    if (type === "array")
+        return membershipProbe(ctx, field, sample);
+    return equalityProbe(ctx, field, type, sample);
+}
+/** The item schema's declaration of property `name`, when it has one. */
+function propertySchemaOf(ctx, name) {
+    return ctx.listOp.collection?.itemSchema?.properties?.[name];
+}
+/** `contains` with an element the cohort holds, or else one drawn from the array's item schema. */
+function membershipProbe(ctx, field, sample) {
+    if (!canUseOp(ctx, field, "contains"))
+        return null;
+    const element = Array.isArray(sample) ? sample[0] : undefined;
+    if (element !== undefined)
+        return { op: "contains", value: asTermValue(element) };
+    const items = propertySchemaOf(ctx, field.field)?.items;
+    const sentinel = filterSentinel(items ?? { type: "string" }, ctx.nonce);
+    return sentinel.ok ? { op: "contains", value: asTermValue(sentinel.value) } : null;
+}
+/** `eq` with a scalar the cohort holds, or else a sentinel of the field's own type. */
+function equalityProbe(ctx, field, type, sample) {
+    if (!canUseOp(ctx, field, "eq"))
+        return null;
+    if (sample !== undefined && typeof sample !== "object")
+        return { op: "eq", value: asTermValue(sample) };
+    const sentinel = filterSentinel(propertySchemaOf(ctx, field.field) ?? { type: type ?? "string" }, ctx.nonce);
+    if (sentinel.ok && isScalar(sentinel.value))
+        return { op: "eq", value: sentinel.value };
+    return null;
+}
+function isScalar(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+//# sourceMappingURL=spec-declared-filterable-is-filterable.js.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-filterable-ops-accepted.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "../../core/check.ts";
+export declare const declaredFilterableOpsAccepted: Check;
+//# sourceMappingURL=spec-declared-filterable-ops-accepted.d.ts.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-filterable-ops-accepted.js

@@ -0,0 +1,90 @@
+import { defineCheck } from "../../core/define.js";
+import { canWriteFilterOp, filterTerm } from "../../../../spec/conventions/filter.js";
+import { opsAreClosed, opsForField } from "../../../../spec/query/field-ops.js";
+import { FILTER_OPS } from "../../../../spec/query/ops.js";
+import { ASSERTED } from "../../../finding.js";
+import { filterSentinel } from "../../../generate/identifiers.js";
+import { when } from "../../core/plan.js";
+import { declarationAnswer } from "../../planning/declarations.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { asTermValue, conv, q, resolvedCaps, schemaType } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+function probeValueForOp(ctx, field, op) {
+    const sample = ctx.records.find((row) => row[field.field] != null);
+    if (op === "is")
+        return "null";
+    if (op === "contains") {
+        const arr = sample?.[field.field];
+        if (Array.isArray(arr) && arr[0] !== undefined)
+            return asTermValue(arr[0]);
+        return "testing-probe";
+    }
+    /* A value of the field's own type: a backend that rejects a string compared with a date is
+     * right to, and that says nothing about whether the operator is supported. */
+    const value = sample === undefined ? typedSentinel(ctx, field) : asTermValue(sample[field.field]);
+    if (value === null)
+        return null;
+    return op === "in" || op === "nin" ? [value] : value;
+}
+/** A well-formed value of `field`'s declared type that no record holds, for probing a capability. */
+function typedSentinel(ctx, field) {
+    const propertySchema = ctx.listOp.collection?.itemSchema?.properties?.[field.field];
+    const made = filterSentinel(propertySchema ?? { type: field.type ?? schemaType(ctx, field.field) ?? "string" }, ctx.nonce);
+    return made.ok && (typeof made.value === "string" || typeof made.value === "number") ? made.value : null;
+}
+export const declaredFilterableOpsAccepted = defineCheck({
+    plan: (ctx) => when(ctx.query?.source === "tag" &&
+        resolvedCaps(ctx).filterable.some((field) => opsAreClosed(field, resolvedCaps(ctx)))),
+    dependsOn: ["list.read-after-write", "spec.declared-filterable-is-filterable", "error.malformed-filter-not-5xx"],
+    id: "spec.declared-filterable-ops-accepted",
+    lists: true,
+    needs: "a closed operator list on at least one declared field",
+    subjects: subjectsOf.list,
+    async run(ctx) {
+        const caps = resolvedCaps(ctx);
+        const rejected = [];
+        const refusedBy = [];
+        const unknown = [];
+        const probes = [];
+        for (const field of caps.filterable) {
+            if (!opsAreClosed(field, caps))
+                continue;
+            for (const op of opsForField(field, caps)) {
+                if (!canWriteFilterOp(conv(ctx), op))
+                    continue;
+                /* No value of the field's type: a null operand would test nullability, not the operator. */
+                const value = probeValueForOp(ctx, field, op);
+                if (value === null)
+                    continue;
+                const term = filterTerm(conv(ctx), { field: field.field, op, value });
+                if (term !== null)
+                    probes.push({ label: `${field.field}.${op}`, term });
+            }
+        }
+        if (probes.length === 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "no declared operator has a value of its field's type to probe with");
+        }
+        /* Every operator at once; the answers are judged in declaration order. */
+        const results = await Promise.all(probes.map(async ({ label, term }) => ({ label, result: await list(ctx, { ...q(ctx, { limit: 5 }), ...term }) })));
+        for (const { label, result } of results) {
+            const answer = declarationAnswer(result.exchange.status);
+            if (answer === "refused") {
+                refusedBy.push(result.exchange);
+                rejected.push(`${label} (${result.exchange.status})`);
+            }
+            if (answer === "unknown")
+                unknown.push(`${label} (${result.exchange.status})`);
+        }
+        if (rejected.length === 0 && unknown.length > 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `probes were turned away without a verdict: ${unknown.join(", ")}`);
+        }
+        if (rejected.length === 0)
+            return ASSERTED;
+        return ctx.findings.spec(this.id, ctx.entityName, {
+            summary: "the document declares a filter operator the backend rejects",
+            detail: `declared ops that 4xx: ${rejected.slice(0, 8).join(", ")}.`,
+            evidence: refusedBy.slice(0, 3),
+        });
+    },
+});
+//# sourceMappingURL=spec-declared-filterable-ops-accepted.js.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-rate-limit-is-honored.d.ts

@@ -0,0 +1,14 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * A 429 is a finding only when the request that drew it was demonstrably under a rate the
+ * *document* declared — the rate came from `x-rate-limit` and the bucket had a free token, so the API tester
+ * did not have to wait for one. A 429 against a config-supplied rate is the operator's own guess
+ * about the environment, not a claim the API made, so it is paced around and never reported; a
+ * 429 that only arrived after the API tester's own bucket made the request wait means the API tester's rate model was
+ * too generous, which is the API tester's fault, not the backend's.
+ *
+ * Grouped by category rather than reported per request: the point is "the declared rate for X is
+ * wrong", once, not one finding for every request that category serves.
+ */
+export declare const declaredRateLimitHonored: Check;
+//# sourceMappingURL=spec-declared-rate-limit-is-honored.d.ts.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-rate-limit-is-honored.js

@@ -0,0 +1,62 @@
+import { defineCheck } from "../../core/define.js";
+import { ASSERTED } from "../../../finding.js";
+import { when } from "../../core/plan.js";
+import { ownOps } from "../../planning/subjects.js";
+/**
+ * A 429 is a finding only when the request that drew it was demonstrably under a rate the
+ * *document* declared — the rate came from `x-rate-limit` and the bucket had a free token, so the API tester
+ * did not have to wait for one. A 429 against a config-supplied rate is the operator's own guess
+ * about the environment, not a claim the API made, so it is paced around and never reported; a
+ * 429 that only arrived after the API tester's own bucket made the request wait means the API tester's rate model was
+ * too generous, which is the API tester's fault, not the backend's.
+ *
+ * Grouped by category rather than reported per request: the point is "the declared rate for X is
+ * wrong", once, not one finding for every request that category serves.
+ */
+export const declaredRateLimitHonored = defineCheck({
+    plan: (ctx) => when(ctx.model.operations.some((op) => op.entity === ctx.entityName && op.rateLimit !== null && op.rateLimit.rps !== null)),
+    id: "spec.declared-rate-limit-is-honored",
+    judgesTranscript: true,
+    needs: "an operation on this entity with a rate declared by x-rate-limit",
+    subjects: (entity, model) => ownOps(entity, model, (op) => op.rateLimit !== null && op.rateLimit.rps !== null),
+    async run(ctx) {
+        const byCategory = new Map();
+        /* Only a route something actually sent was paced and judged. Claiming the rest would mark
+         * them graded with no request behind them, and the contract tier never calls a graded one. */
+        const observed = new Set();
+        for (const exchange of ctx.client.exchangesForEntity(ctx.entityName)) {
+            const paced = declaredRateOp(ctx, exchange);
+            if (paced !== undefined)
+                observed.add(paced);
+            if (!refusedUnderDeclaredRate(exchange))
+                continue;
+            const category = exchange.rateLimitCategory ?? "unknown";
+            byCategory.set(category, [...(byCategory.get(category) ?? []), exchange]);
+        }
+        for (const [category, exchanges] of byCategory) {
+            ctx.findings.spec(this.id, ctx.entityName, {
+                summary: `the declared "${category}" rate limit is not honored`,
+                detail: `${exchanges.length} request(s) to the "${category}" category returned 429 despite the API tester ` +
+                    "pacing them within the rate x-rate-limit declares — each had a free token in its own " +
+                    "bucket at the moment it was sent, so this is not the API tester outrunning its own model. Either " +
+                    `the declared rate is wrong, or the backend enforces a stricter one than "${category}" ` +
+                    "documents.",
+                evidence: exchanges.slice(0, 3),
+            });
+        }
+        ctx.judged?.([...observed]);
+        return ASSERTED;
+    },
+});
+/** The operation `exchange` was sent to, when the document declares a rate for it. */
+function declaredRateOp(ctx, exchange) {
+    const op = exchange.operationId === undefined ? undefined : ctx.model.byOperationId.get(exchange.operationId);
+    if (op?.rateLimit?.rps !== null && op?.rateLimit?.rps !== undefined)
+        return op.operationId;
+    return undefined;
+}
+/** A 429 to a request paced under a document-declared rate while its bucket still had a token. */
+function refusedUnderDeclaredRate(exchange) {
+    return exchange.status === 429 && exchange.rateLimitSource === "tag" && exchange.rateLimitHadRoom === true;
+}
+//# sourceMappingURL=spec-declared-rate-limit-is-honored.js.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-selectable-is-selectable.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * The select analog of `declaredFilterableWorks` and `declaredSortableWorks`:
+ * `x-query.selectable` is a promise too, and a sparse fieldset the backend rejects breaks every
+ * client generated from the document exactly the same way a rejected filter or sort does.
+ */
+export declare const declaredSelectableWorks: Check;
+//# sourceMappingURL=spec-declared-selectable-is-selectable.d.ts.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-selectable-is-selectable.js

@@ -0,0 +1,79 @@
+import { defineCheck } from "../../core/define.js";
+import { selectTerm } from "../../../../spec/conventions/select.js";
+import { ASSERTED } from "../../../finding.js";
+import { when } from "../../core/plan.js";
+import { declarationAnswer } from "../../planning/declarations.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, q } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+/**
+ * The select analog of `declaredFilterableWorks` and `declaredSortableWorks`:
+ * `x-query.selectable` is a promise too, and a sparse fieldset the backend rejects breaks every
+ * client generated from the document exactly the same way a rejected filter or sort does.
+ */
+export const declaredSelectableWorks = defineCheck({
+    plan: (ctx) => when(conv(ctx).select !== undefined &&
+        ctx.query?.source === "tag" &&
+        (ctx.query?.selectable.length ?? 0) > 0 &&
+        ctx.records.length > 0),
+    dependsOn: [
+        "list.read-after-write",
+        /* Same masking risk as the filter and sort overclaim checks: ERROR_500_ON_BAD_FILTER turns
+         * any rejection — this one included — into a 500, which would fall outside the 4xx window
+         * below and read as accepted. */
+        "error.malformed-filter-not-5xx",
+        /* Same shape as the sort check's dependency on sort.order-is-applied, found by inspection
+         * before the fuzzer had to: `project()` returns the row untouched under SELECT_IGNORED
+         * *before* the excluded-field check runs, so a backend that has stopped honoring `select`
+         * at all also stops rejecting an overclaimed field — the request just returns every column. */
+        "select.projection-honored",
+    ],
+    id: "spec.declared-selectable-is-selectable",
+    lists: true,
+    needs: "x-query naming selectable fields",
+    subjects: subjectsOf.list,
+    async run(ctx) {
+        const conventions = conv(ctx);
+        const rejected = [];
+        const unknown = [];
+        let probed = 0;
+        const answers = await Promise.all((ctx.query?.selectable ?? []).map(async (field) => {
+            const projection = selectTerm(conventions, [ctx.identity, field], ctx.entityName);
+            if (projection === null)
+                return null;
+            return { field, result: await list(ctx, { ...q(ctx, { limit: 5 }), ...projection }) };
+        }));
+        for (const answered of answers) {
+            if (answered === null)
+                continue;
+            const { field, result } = answered;
+            probed += 1;
+            /* Only a rejection counts. A field accepted and then ignored is select.projection-
+             * honored's finding, not a capability claim breaking. */
+            const answer = declarationAnswer(result.exchange.status);
+            if (answer === "refused")
+                rejected.push({ exchange: result.exchange, field, status: result.exchange.status });
+            if (answer === "unknown")
+                unknown.push(`${field} (${result.exchange.status})`);
+        }
+        if (probed === 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "no declared selectable field could be probed");
+        }
+        if (rejected.length === 0 && unknown.length > 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `probes were turned away without a verdict: ${unknown.join(", ")}`);
+        }
+        if (rejected.length === 0)
+            return ASSERTED;
+        return ctx.findings.spec(this.id, ctx.entityName, {
+            summary: "the document declares a select field the backend does not accept",
+            detail: `x-query lists ${rejected.length} field(s) as selectable that the backend rejects: ` +
+                `${rejected.map((r) => `${r.field} (${r.status})`).join(", ")}. ` +
+                "Every client generated from this document will offer a sparse fieldset that fails at " +
+                "runtime. Either the field needs to stay projectable or the declaration needs " +
+                "removing — but the document and the backend currently disagree about what this API " +
+                "can do.",
+            evidence: rejected.slice(0, 3).map((item) => item.exchange),
+        });
+    },
+});
+//# sourceMappingURL=spec-declared-selectable-is-selectable.js.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-sortable-is-sortable.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * The sort analog of `declaredFilterableWorks`: `x-query.sortable` is a promise too, and
+ * an `order` value the backend rejects breaks every client generated from the document exactly
+ * the same way a rejected filter does.
+ */
+export declare const declaredSortableWorks: Check;
+//# sourceMappingURL=spec-declared-sortable-is-sortable.d.ts.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-sortable-is-sortable.js

@@ -0,0 +1,76 @@
+import { defineCheck } from "../../core/define.js";
+import { sortTerm } from "../../../../spec/conventions/sort.js";
+import { ASSERTED } from "../../../finding.js";
+import { when } from "../../core/plan.js";
+import { declarationAnswer } from "../../planning/declarations.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, q } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+/**
+ * The sort analog of `declaredFilterableWorks`: `x-query.sortable` is a promise too, and
+ * an `order` value the backend rejects breaks every client generated from the document exactly
+ * the same way a rejected filter does.
+ */
+export const declaredSortableWorks = defineCheck({
+    plan: (ctx) => when(conv(ctx).order !== undefined &&
+        ctx.query?.source === "tag" &&
+        (ctx.query?.sortable.length ?? 0) > 0 &&
+        ctx.records.length > 0),
+    dependsOn: [
+        "list.read-after-write",
+        /* ERROR_500_ON_BAD_FILTER, despite its name, turns *any* SqlError the reference throws
+         * into a 500 — including a rejected `order` field, not just a malformed filter. Without
+         * this dependency a rejection lands outside the 4xx window this check looks for and the
+         * overclaim goes unreported: the same "SILENT" failure error.malformed-filter-not-5xx
+         * exists to catch, just reached from the sort path instead of the filter path. */
+        "error.malformed-filter-not-5xx",
+        /* Found by the fuzzer, not the matrix: on the SQL stores, ORDER_IGNORED short-circuits
+         * before the sortable whitelist is even consulted (the field-rejection check sits *after*
+         * the ignore-order early return), so a backend that has stopped applying `order` at all
+         * also stops rejecting an overclaimed field — the request simply succeeds with the default
+         * order. The overclaim is real but unobservable until ordering itself works again. */
+        "sort.order-is-applied",
+    ],
+    id: "spec.declared-sortable-is-sortable",
+    lists: true,
+    needs: "x-query naming sortable fields",
+    subjects: subjectsOf.list,
+    async run(ctx) {
+        const conventions = conv(ctx);
+        const rejected = [];
+        const unknown = [];
+        let probed = 0;
+        const answers = await Promise.all((ctx.query?.sortable ?? []).map(async (field) => ({
+            field,
+            result: await list(ctx, q(ctx, { limit: 5, order: sortTerm(conventions, { direction: "asc", field }) })),
+        })));
+        for (const { field, result } of answers) {
+            probed += 1;
+            /* Only a rejection counts. Order accepted but not applied is sort.order-is-applied's
+             * finding, not a capability claim breaking. */
+            const answer = declarationAnswer(result.exchange.status);
+            if (answer === "refused")
+                rejected.push({ exchange: result.exchange, field, status: result.exchange.status });
+            if (answer === "unknown")
+                unknown.push(`${field} (${result.exchange.status})`);
+        }
+        if (probed === 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "no declared sortable field could be probed");
+        }
+        if (rejected.length === 0 && unknown.length > 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `probes were turned away without a verdict: ${unknown.join(", ")}`);
+        }
+        if (rejected.length === 0)
+            return ASSERTED;
+        return ctx.findings.spec(this.id, ctx.entityName, {
+            summary: "the document declares a sort field the backend does not accept",
+            detail: `x-query lists ${rejected.length} field(s) as sortable that the backend rejects: ` +
+                `${rejected.map((r) => `${r.field} (${r.status})`).join(", ")}. ` +
+                "Every client generated from this document will offer an order value that fails at " +
+                "runtime. Either the column needs an index or the declaration needs removing — but " +
+                "the document and the backend currently disagree about what this API can do.",
+            evidence: rejected.slice(0, 3).map((item) => item.exchange),
+        });
+    },
+});
+//# sourceMappingURL=spec-declared-sortable-is-sortable.js.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-sortable-nulls-accepted.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "../../core/check.ts";
+export declare const declaredSortableNullsAccepted: Check;
+//# sourceMappingURL=spec-declared-sortable-nulls-accepted.d.ts.map

package/dist/api/runtime/checks/families/spec-declarations/spec-declared-sortable-nulls-accepted.js

@@ -0,0 +1,52 @@
+import { defineCheck } from "../../core/define.js";
+import { sortTermWithNulls } from "../../../../spec/conventions/sort.js";
+import { fieldAllowsNulls } from "../../../../spec/query/field-ops.js";
+import { ASSERTED } from "../../../finding.js";
+import { when } from "../../core/plan.js";
+import { declarationAnswer } from "../../planning/declarations.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, q, resolvedCaps } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+export const declaredSortableNullsAccepted = defineCheck({
+    plan: (ctx) => when(conv(ctx).order !== undefined &&
+        sortTermWithNulls(conv(ctx), { direction: "asc", field: "x", nulls: "first" }) !== null &&
+        resolvedCaps(ctx).sortable.some((field) => fieldAllowsNulls(field, resolvedCaps(ctx), "first") || fieldAllowsNulls(field, resolvedCaps(ctx), "last"))),
+    dependsOn: ["sort.order-is-applied"],
+    id: "spec.declared-sortable-nulls-accepted",
+    lists: true,
+    needs: "a declared nulls token on a sortable field",
+    subjects: subjectsOf.list,
+    async run(ctx) {
+        const rejected = [];
+        const refusedBy = [];
+        const unknown = [];
+        for (const field of resolvedCaps(ctx).sortable) {
+            for (const token of ["first", "last"]) {
+                if (!fieldAllowsNulls(field, resolvedCaps(ctx), token))
+                    continue;
+                const clause = sortTermWithNulls(conv(ctx), { direction: "asc", field: field.field, nulls: token });
+                if (clause === null)
+                    continue;
+                const result = await list(ctx, q(ctx, { limit: 5, order: clause }));
+                const answer = declarationAnswer(result.exchange.status);
+                if (answer === "refused") {
+                    refusedBy.push(result.exchange);
+                    rejected.push(`${clause} (${result.exchange.status})`);
+                }
+                if (answer === "unknown")
+                    unknown.push(`${clause} (${result.exchange.status})`);
+            }
+        }
+        if (rejected.length === 0 && unknown.length > 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `probes were turned away without a verdict: ${unknown.join(", ")}`);
+        }
+        if (rejected.length === 0)
+            return ASSERTED;
+        return ctx.findings.spec(this.id, ctx.entityName, {
+            summary: "the document declares a nulls sort token the backend rejects",
+            detail: `rejected: ${rejected.join(", ")}.`,
+            evidence: refusedBy.slice(0, 3),
+        });
+    },
+});
+//# sourceMappingURL=spec-declared-sortable-nulls-accepted.js.map

package/dist/api/runtime/checks/families/validation/bodies.d.ts

@@ -0,0 +1,16 @@
+import type { OperationModel } from "../../../../spec/graph/types.ts";
+import type { CheckContext } from "../../core/context.ts";
+import { type Plan } from "../../core/plan.ts";
+import type { JsonSchema } from "../../../../spec/types.ts";
+/** The create operation and its request schema: what every create-validation probe starts from. */
+export interface CreateBody {
+    createOp: OperationModel;
+    schema: JsonSchema;
+}
+export declare function createBodyPlan(ctx: CheckContext): Plan<CreateBody>;
+export interface ConstrainedField {
+    name: string;
+    schema: JsonSchema;
+}
+export declare function findConstrained(schema: JsonSchema, predicate: (s: JsonSchema) => boolean): ConstrainedField | null;
+//# sourceMappingURL=bodies.d.ts.map

package/dist/api/runtime/checks/families/validation/bodies.js

@@ -0,0 +1,30 @@
+import { cannot, ready } from "../../core/plan.js";
+import { requestSchemaOf } from "../../payloads/body.js";
+export function createBodyPlan(ctx) {
+    const createOp = ctx.createOp;
+    if (createOp === undefined)
+        return cannot();
+    const schema = requestSchemaOf(ctx, createOp);
+    return schema === null ? cannot("a create operation with a request schema") : ready({ createOp, schema });
+}
+export function findConstrained(schema, predicate) {
+    const props = schema.properties;
+    if (props === null || typeof props !== "object")
+        return null;
+    for (const [name, raw] of Object.entries(props)) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        if (raw.readOnly === true)
+            continue;
+        if (predicate(raw))
+            return { name, schema: raw };
+        const union = raw.oneOf ?? raw.anyOf;
+        if (Array.isArray(union)) {
+            const branch = union.find((candidate) => candidate !== null && typeof candidate === "object" && predicate(candidate));
+            if (branch !== undefined)
+                return { name, schema: branch };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=bodies.js.map

package/dist/api/runtime/checks/families/validation/invalid-body.d.ts

@@ -0,0 +1,29 @@
+import type { JsonSchema } from "../../../../spec/types.ts";
+/** How the body is made invalid: a required property left out, or a property sent the wrong type. */
+export type InvalidChoice = {
+    kind: "missing";
+    field: string;
+} | {
+    kind: "wrong-type";
+    field: string;
+    value: unknown;
+};
+/** What a write's own request already settles: whether it merges, and the properties its path names. */
+export interface ChoiceOptions {
+    /** A PATCH keeps what its body leaves out, so a required property it omits is no error. */
+    merge?: boolean;
+    /** The record's identity and the path's parameters: the server takes them from the path. */
+    kept?: ReadonlySet<string>;
+}
+/**
+ * The invalid body's recipe for `schema`, or null when it names no property to break. Neither choice
+ * touches a property the path already names (`kept`), nor a readOnly one, which no writer sends: a
+ * server may rightly take the one from the path and ignore the other. A merge write is sent the wrong
+ * type rather than missing a required property.
+ */
+export declare function invalidChoice(schema: JsonSchema | boolean, { merge, kept }?: ChoiceOptions): InvalidChoice | null;
+/** A value of a JSON type `type` does not admit; undefined when it admits them all or states none. */
+export declare function wrongTyped(type: unknown): unknown;
+/** `base` made invalid by `choice`: a copy, the property removed or set to the wrong type. */
+export declare function invalidated(base: Record<string, unknown>, choice: InvalidChoice): Record<string, unknown>;
+//# sourceMappingURL=invalid-body.d.ts.map