@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/families/pagination/pagination-bounds-handled.d.ts

@@ -0,0 +1,14 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * Paging parameters at and past their bounds: a page size of zero, a negative one, one that is
+ * not a whole number, and a page past the end of the collection.
+ *
+ * Refusing an out-of-range size and serving a sane one are both fine; crashing is not. A page
+ * past the end must hold nothing — a server that serves the last page again there makes every
+ * client that pages until an empty page loop forever.
+ */
+export declare const paginationBoundsHandled: Check<{
+    limit: string | undefined;
+    page: string | undefined;
+}>;
+//# sourceMappingURL=pagination-bounds-handled.d.ts.map

package/dist/api/runtime/checks/families/pagination/pagination-bounds-handled.js

@@ -0,0 +1,74 @@
+import { defineCheck } from "../../core/define.js";
+import { ASSERTED, asserted } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { asProbe } from "../../planning/refusal.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, pageSize, q } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+import { readSet } from "../../sets/read.js";
+/**
+ * Paging parameters at and past their bounds: a page size of zero, a negative one, one that is
+ * not a whole number, and a page past the end of the collection.
+ *
+ * Refusing an out-of-range size and serving a sane one are both fine; crashing is not. A page
+ * past the end must hold nothing — a server that serves the last page again there makes every
+ * client that pages until an empty page loop forever.
+ */
+export const paginationBoundsHandled = defineCheck({
+    plan: (ctx) => {
+        const { limit, page } = conv(ctx);
+        if ((limit === undefined && page === undefined) || ctx.records.length === 0)
+            return cannot();
+        return ready({ limit, page });
+    },
+    dependsOn: ["list.read-after-write", "pagination.page-walk-covers-set"],
+    id: "pagination.bounds-handled",
+    lists: true,
+    needs: "a page-size or page-number parameter, and at least one record",
+    subjects: subjectsOf.list,
+    async run(ctx, { limit, page }) {
+        if (limit !== undefined) {
+            for (const value of ["0", "-1", "2.5", "abc"]) {
+                const result = await list(asProbe(ctx), { [limit]: value });
+                if (result.exchange.status >= 500) {
+                    return ctx.findings.backend(this.id, ctx.entityName, {
+                        summary: `a page size of ${value} crashes the listing`,
+                        detail: `?${limit}=${value} returned ${result.exchange.status}; an out-of-range page size must be ` +
+                            "refused with a 4xx, or served as a sane size.",
+                        evidence: [result.exchange],
+                    });
+                }
+            }
+        }
+        if (page === undefined)
+            return ASSERTED;
+        const whole = await readSet(ctx, {}, { fresh: true });
+        if (whole.status !== "ok" || !whole.complete) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, whole.reason);
+        }
+        const size = pageSize(ctx);
+        /* Past the end at any page size a server may serve — it may clamp below the size asked for,
+         * so a page number from the requested size could still fall inside the set. */
+        const beyond = whole.items.length + 2;
+        const result = await list(asProbe(ctx), { ...q(ctx, { limit: size }), [page]: beyond });
+        const status = result.exchange.status;
+        if (status >= 500) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "a page past the end crashes the listing",
+                detail: `?${page}=${beyond}, past the last of ${whole.items.length} record(s), returned ${status}.`,
+                evidence: [result.exchange],
+            });
+        }
+        if (status >= 400)
+            return asserted(`a page past the end is refused (${status})`);
+        if (result.items.length === 0)
+            return asserted("a page past the end is served empty");
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "a page past the end of the collection returns records",
+            detail: `?${page}=${beyond} lies past the last of ${whole.items.length} record(s) at ${size} per page, ` +
+                `yet returned ${result.items.length}. A client that pages until an empty page never stops.`,
+            evidence: [whole.last.exchange, result.exchange],
+        });
+    },
+});
+//# sourceMappingURL=pagination-bounds-handled.js.map

package/dist/api/runtime/checks/families/pagination/pagination-cursor-agrees-with-page.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "../../core/check.ts";
+export declare const cursorAgreesWithPage: Check;
+//# sourceMappingURL=pagination-cursor-agrees-with-page.d.ts.map

package/dist/api/runtime/checks/families/pagination/pagination-cursor-agrees-with-page.js

@@ -0,0 +1,109 @@
+import { defineCheck } from "../../core/define.js";
+import { sortTerm } from "../../../../spec/conventions/sort.js";
+import { ASSERTED } from "../../../finding.js";
+import { idOf, recordsFromList } from "../../../world/records.js";
+import { when } from "../../core/plan.js";
+import { NO_KEY, subjectsOf } from "../../planning/subjects.js";
+import { conv, pageable } from "../../query/capabilities.js";
+import { duplicates } from "../../sets/compare.js";
+import { ids, rowsAt } from "../../sets/list.js";
+import { readSet } from "../../sets/read.js";
+import { MAX_WALK_PAGES, walkPages } from "./walk.js";
+async function walkCursor(ctx, perPage, order, maxPages = MAX_WALK_PAGES) {
+    const read = await readSet(ctx, {}, { byCursor: true, fresh: true, keepRepeats: true, maxPages, order, size: perPage });
+    return {
+        exchanges: read.pages.map((page) => page.exchange),
+        ids: ids(read.items, ctx.identity),
+        items: read.items,
+        truncated: !read.complete,
+    };
+}
+/**
+ * A sortable text field the cohort holds non-empty values for. Cursor pagination is almost always
+ * used with one, and a boundary resolved under a different collation than the listing can only
+ * diverge when the ordering key is text.
+ */
+function textSortField(ctx) {
+    return (ctx.query?.sortable.find((f) => {
+        if (f === ctx.identity)
+            return false;
+        return ctx.records.some((r) => typeof r[f] === "string" && r[f] !== "");
+    }) ?? undefined);
+}
+/** The cursor pages up to the one that served a record again. */
+function repeatEvidence(ctx, cursorWalk, repeated) {
+    return cursorWalk.exchanges.slice(0, Math.max(2, 1 +
+        cursorWalk.exchanges.findLastIndex((exchange) => recordsFromList(exchange.responseBody, rowsAt(ctx)).some((item) => repeated.includes(idOf(item, ctx.identity) ?? NO_KEY)))));
+}
+/**
+ * Two walks capped at the same number of equal pages cover the same prefix of one order, so their
+ * prefixes compare — except across a tie at the cut, where either of the tied records may
+ * legitimately fall inside. Those are left out. With no explicit order there is no prefix to speak
+ * of, and a capped walk proves nothing: `null`.
+ */
+function comparablePrefixes(pageWalk, cursorWalk, sortField) {
+    if (!pageWalk.truncated && !cursorWalk.truncated)
+        return { cursorItems: cursorWalk.items, pageItems: pageWalk.items };
+    if (sortField === undefined)
+        return null;
+    const length = Math.min(pageWalk.items.length, cursorWalk.items.length);
+    const atCut = JSON.stringify(pageWalk.items[length - 1]?.[sortField]);
+    const clear = (items) => items.slice(0, length).filter((item) => JSON.stringify(item[sortField]) !== atCut);
+    return { cursorItems: clear(cursorWalk.items), pageItems: clear(pageWalk.items) };
+}
+export const cursorAgreesWithPage = defineCheck({
+    plan: (ctx) => when(conv(ctx).cursor !== undefined && pageable(ctx) && ctx.records.length > 2),
+    dependsOn: [
+        "pagination.page-walk-covers-set",
+        /* Sorting by a field whose value never persisted is degenerate, so a pagination
+         * disagreement there describes a consequence rather than a pagination defect. */
+        "create.persists-submitted-fields",
+        /* Both walks are taken at a requested page size. If the backend serves a different size
+         * than asked for, the two walks step differently and disagree for that reason alone. */
+        "pagination.limit-respects-documented-max",
+    ],
+    id: "pagination.cursor-agrees-with-page",
+    lists: true,
+    needs: "both `cursor` and `page` parameters",
+    subjects: subjectsOf.list,
+    async run(ctx) {
+        /* Walk under an explicit text sort. */
+        const sortField = textSortField(ctx);
+        const order = sortField === undefined ? undefined : sortTerm(conv(ctx), { direction: "asc", field: sortField });
+        const pageWalk = await walkPages(ctx, 2, order);
+        const cursorWalk = await walkCursor(ctx, 2, order);
+        const byPage = pageWalk.ids;
+        const byCursor = cursorWalk.ids;
+        /* Repeats are their own defect: a cursor that resolves to the wrong boundary re-serves the
+         * previous page's tail, which set comparison alone would hide. */
+        const repeated = duplicates(byCursor).filter((id) => !duplicates(byPage).includes(id));
+        if (repeated.length > 0) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "cursor pagination re-serves records the previous page already returned",
+                detail: `walking by cursor returned ${repeated.length} record(s) more than once ` +
+                    `(${repeated.slice(0, 3).join(", ")}) while the offset walk returned each exactly once. ` +
+                    "The cursor is resolving to the wrong boundary.",
+                evidence: repeatEvidence(ctx, cursorWalk, repeated),
+            });
+        }
+        const prefixes = comparablePrefixes(pageWalk, cursorWalk, sortField);
+        if (prefixes === null) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "a walk was cut short, so the two cannot be compared");
+        }
+        const pageSet = [...new Set(ids(prefixes.pageItems, ctx.identity))].sort();
+        const cursorSet = [...new Set(ids(prefixes.cursorItems, ctx.identity))].sort();
+        if (pageSet.join(",") === cursorSet.join(","))
+            return ASSERTED;
+        const onlyPage = pageSet.filter((id) => !cursorSet.includes(id));
+        const onlyCursor = cursorSet.filter((id) => !pageSet.includes(id));
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "cursor pagination and offset pagination disagree",
+            detail: `offset walk yielded ${pageSet.length} distinct records, cursor walk yielded ${cursorSet.length}. ` +
+                `Only in offset: ${onlyPage.slice(0, 3).join(", ") || "—"}. ` +
+                `Only in cursor: ${onlyCursor.slice(0, 3).join(", ") || "—"}. ` +
+                "Both traverse the same collection, so one of them is losing or repeating rows.",
+            evidence: [...pageWalk.exchanges.slice(0, 2), ...cursorWalk.exchanges.slice(0, 2)],
+        });
+    },
+});
+//# sourceMappingURL=pagination-cursor-agrees-with-page.js.map

package/dist/api/runtime/checks/families/pagination/pagination-has-more-is-accurate.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "../../core/check.ts";
+export declare const hasMoreIsAccurate: Check;
+//# sourceMappingURL=pagination-has-more-is-accurate.d.ts.map

package/dist/api/runtime/checks/families/pagination/pagination-has-more-is-accurate.js

@@ -0,0 +1,36 @@
+import { defineCheck } from "../../core/define.js";
+import { ASSERTED, standDown } from "../../../finding.js";
+import { when } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { pageable, q } from "../../query/capabilities.js";
+import { envelopeValue, list } from "../../sets/list.js";
+export const hasMoreIsAccurate = defineCheck({
+    plan: (ctx) => when(pageable(ctx) && ctx.records.length > 2),
+    dependsOn: ["pagination.limit-bounds-page-size"],
+    id: "pagination.has-more-is-accurate",
+    lists: true,
+    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)
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the first page was rejected or empty");
+        const flag = envelopeValue(ctx, first, "hasMore");
+        if (typeof flag !== "boolean")
+            return standDown("the listing has no has-more flag");
+        const second = await list(ctx, q(ctx, { limit: 1, page: 2 }));
+        const moreExist = second.items.length > 0;
+        if (flag === moreExist)
+            return ASSERTED;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: flag
+                ? "hasMore claims further pages exist when none do"
+                : "hasMore claims no further pages while the next page returns records",
+            detail: `page 1 at limit=1 reported hasMore=${flag}, but page 2 returned ` +
+                `${second.items.length} record(s). Callers that trust the flag will ` +
+                (flag ? "request an empty page" : "silently stop after the first page"),
+            evidence: [first.exchange, second.exchange],
+        });
+    },
+});
+//# sourceMappingURL=pagination-has-more-is-accurate.js.map

package/dist/api/runtime/checks/families/pagination/pagination-limit-bounds-enforced.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * A page size the document says is refused when out of range — `limitOutOfRange: reject` — must be
+ * refused. Clamping is a fine contract too, which is why nothing is judged without the declaration.
+ */
+export declare const limitBoundsEnforced: Check<{
+    limitParam: string;
+    max: number;
+}>;
+//# sourceMappingURL=pagination-limit-bounds-enforced.d.ts.map

package/dist/api/runtime/checks/families/pagination/pagination-limit-bounds-enforced.js

@@ -0,0 +1,54 @@
+import { defineCheck } from "../../core/define.js";
+import { ASSERTED } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { asProbe, judgeRefusal } from "../../planning/refusal.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, resolvedCaps } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+/**
+ * A page size the document says is refused when out of range — `limitOutOfRange: reject` — must be
+ * refused. Clamping is a fine contract too, which is why nothing is judged without the declaration.
+ */
+export const limitBoundsEnforced = defineCheck({
+    plan: (ctx) => {
+        const max = ctx.query?.maxLimit;
+        const limitParam = conv(ctx).limit;
+        if (resolvedCaps(ctx).limitOutOfRange !== "reject")
+            return cannot("a declared limitOutOfRange: reject");
+        if (max === undefined || limitParam === undefined)
+            return cannot("a page-size parameter with a maximum");
+        return ready({ limitParam, max });
+    },
+    dependsOn: ["pagination.limit-bounds-page-size"],
+    id: "pagination.limit-bounds-enforced",
+    lists: true,
+    needs: "a declared limitOutOfRange: reject, and a page size with a maximum",
+    subjects: subjectsOf.list,
+    async run(ctx, { limitParam, max }) {
+        for (const size of [0, max + 1]) {
+            /* Deliberately out of range: these are the requests that may break the documented bound. */
+            const result = await list(asProbe(ctx), { [limitParam]: size });
+            if (result.exchange.status >= 500) {
+                return ctx.findings.backend(this.id, ctx.entityName, {
+                    summary: "an out-of-range page size produces a server error",
+                    detail: `${limitParam}=${size} returned ${result.exchange.status}; a refused input should be 4xx.`,
+                    evidence: [result.exchange],
+                });
+            }
+            const refused = judgeRefusal(ctx, this.id, ["validation"], result.exchange);
+            /* Refused for the bound: try the other side. Turned away for another reason: nothing learned. */
+            if (refused === ASSERTED)
+                continue;
+            if (refused !== null)
+                return refused;
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "an out-of-range page size is served",
+                detail: `${limitParam}=${size} returned ${result.exchange.status}; the document declares that a page size ` +
+                    `outside 1..${max} is refused.`,
+                evidence: [result.exchange],
+            });
+        }
+        return ASSERTED;
+    },
+});
+//# sourceMappingURL=pagination-limit-bounds-enforced.js.map

package/dist/api/runtime/checks/families/pagination/pagination-limit-bounds-page-size.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "../../core/check.ts";
+export declare const limitBoundsPageSize: Check;
+//# sourceMappingURL=pagination-limit-bounds-page-size.d.ts.map

package/dist/api/runtime/checks/families/pagination/pagination-limit-bounds-page-size.js

@@ -0,0 +1,28 @@
+import { defineCheck } from "../../core/define.js";
+import { ASSERTED } from "../../../finding.js";
+import { when } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, q } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+export const limitBoundsPageSize = defineCheck({
+    plan: (ctx) => when(conv(ctx).limit !== undefined && ctx.records.length > 2),
+    dependsOn: ["list.read-after-write"],
+    id: "pagination.limit-bounds-page-size",
+    lists: true,
+    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)
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the listing was rejected");
+        if (result.items.length <= 2)
+            return ASSERTED;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "limit does not bound the number of records returned",
+            detail: `limit=2 returned ${result.items.length} records. A page size the backend accepts and ` +
+                "ignores means callers cannot bound response size, and every paging loop is wrong.",
+            evidence: [result.exchange],
+        });
+    },
+});
+//# sourceMappingURL=pagination-limit-bounds-page-size.js.map

package/dist/api/runtime/checks/families/pagination/pagination-limit-respects-documented-max.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "../../core/check.ts";
+export declare const limitRespectsMax: Check<{
+    max: number;
+    limitParam: string;
+}>;
+//# sourceMappingURL=pagination-limit-respects-documented-max.d.ts.map

package/dist/api/runtime/checks/families/pagination/pagination-limit-respects-documented-max.js

@@ -0,0 +1,39 @@
+import { defineCheck } from "../../core/define.js";
+import { ASSERTED } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { asProbe, judgeRefusal } from "../../planning/refusal.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+export const limitRespectsMax = defineCheck({
+    plan: (ctx) => {
+        const max = ctx.query?.maxLimit;
+        const limitParam = conv(ctx).limit;
+        /* Unless the collection holds more records than the cap, an uncapped backend and a
+         * capped one return the same thing and the check would prove nothing. */
+        if (max === undefined || limitParam === undefined || ctx.records.length <= max)
+            return cannot();
+        return ready({ limitParam, max });
+    },
+    dependsOn: ["pagination.limit-bounds-page-size"],
+    id: "pagination.limit-respects-documented-max",
+    lists: true,
+    needs: "a declared maxLimit, and more records than it",
+    subjects: subjectsOf.list,
+    async run(ctx, { limitParam, max }) {
+        /* Deliberately past the cap — the one request that may break the documented bound. */
+        const result = await list(asProbe(ctx), { [limitParam]: max + 50 });
+        const refused = judgeRefusal(ctx, this.id, ["validation"], result.exchange);
+        if (refused !== null)
+            return refused;
+        if (result.items.length <= max)
+            return ASSERTED;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "page size exceeds the documented maximum",
+            detail: `limit=${max + 50} returned ${result.items.length} records; the document caps limit at ` +
+                `${max}. Either the cap is not enforced or the document overstates it.`,
+            evidence: [result.exchange],
+        });
+    },
+});
+//# sourceMappingURL=pagination-limit-respects-documented-max.js.map

package/dist/api/runtime/checks/families/pagination/pagination-page-walk-covers-set.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "../../core/check.ts";
+export declare const pageWalkCoversSet: Check;
+//# sourceMappingURL=pagination-page-walk-covers-set.d.ts.map

package/dist/api/runtime/checks/families/pagination/pagination-page-walk-covers-set.js

@@ -0,0 +1,90 @@
+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 { subjectsOf } from "../../planning/subjects.js";
+import { conv, pageable, pageSize } from "../../query/capabilities.js";
+import { tiedSortField } from "../../query/order.js";
+import { duplicates } from "../../sets/compare.js";
+import { ids } from "../../sets/list.js";
+import { readSet } from "../../sets/read.js";
+import { MAX_WALK_PAGES, walkPages } from "./walk.js";
+/** Two identical walks that disagree: on order alone, or on which records they hold. */
+function reportUnstableWalks(ctx, check, walks, evidence) {
+    const { orderParam, second, walked } = walks;
+    const sameMembers = [...second].sort().join(",") === [...walked].sort().join(",");
+    return ctx.findings.backend(check, ctx.entityName, {
+        summary: sameMembers
+            ? "identical page walks return records in different orders"
+            : "identical page walks return different records",
+        detail: `walking the collection twice with the same parameters` +
+            (orderParam === undefined ? "" : ` (order=${orderParam})`) +
+            ` produced ${sameMembers ? "the same records in a different order" : "different sets"}. ` +
+            "Pagination requires a total order; without a tiebreak the page boundary moves between " +
+            "requests and callers silently miss or repeat rows.",
+        evidence: [evidence],
+    });
+}
+export const pageWalkCoversSet = defineCheck({
+    /* Walked by whatever the endpoint pages by — a cursor alone is enough. */
+    plan: (ctx) => when((pageable(ctx) || conv(ctx).cursor !== undefined) && ctx.records.length > 2),
+    dependsOn: [
+        "list.read-after-write",
+        "pagination.limit-bounds-page-size",
+        "pagination.has-more-is-accurate",
+        /* A page walk is only sound over a total order. Where the requested order is discarded,
+         * the pages are windows onto an arbitrary sequence, and any drift they show is the
+         * missing sort rather than a pagination defect. */
+        "sort.order-is-applied",
+    ],
+    id: "pagination.page-walk-covers-set",
+    lists: true,
+    needs: "a way to page forward — a page number, a row offset or a cursor — and at least three records",
+    subjects: subjectsOf.list,
+    async run(ctx) {
+        const limit = pageSize(ctx);
+        /* Walk under a low-cardinality sort. Distinct keys admit exactly one valid order, so an
+         * unstable sort is indistinguishable from a correct one until values tie. */
+        const order = tiedSortField(ctx);
+        const orderParam = order === null ? undefined : sortTerm(conv(ctx), { direction: "asc", field: order });
+        /* The whole set, read at the largest page: what a walk at two per page must reproduce. */
+        void limit;
+        const whole = await readSet(ctx, {}, { order: orderParam });
+        const single = whole.last;
+        const expected = ids(whole.items, ctx.identity);
+        /* Two per page, so every record sits near a page boundary — unless the collection is too
+         * large to walk that way within the page cap, when pages grow just enough to reach its end.
+         * A walk cut short proves nothing about what it never reached. */
+        const walkSize = Math.min(limit, Math.max(2, Math.ceil(expected.length / (MAX_WALK_PAGES - 1))));
+        const walk = await walkPages(ctx, walkSize, orderParam);
+        const walked = walk.ids;
+        const repeated = duplicates(walked);
+        if (repeated.length > 0) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "paging returns the same record on more than one page",
+                detail: `walking at limit=${walkSize} returned ${repeated.length} duplicated id(s): ${repeated.slice(0, 3).join(", ")}. ` +
+                    "This is the signature of a sort without a total order — the page boundary is not stable.",
+                evidence: [single.exchange],
+            });
+        }
+        /* A capped walk saw only a prefix of the collection, so "missing" would just mean "beyond
+         * the cap". Duplicates above are still meaningful; absence is not. */
+        const missing = walk.truncated || !whole.complete ? [] : expected.filter((id) => !walked.includes(id));
+        if (missing.length > 0) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "paging skips records that a single large page returns",
+                detail: `a single page at limit=${limit} returned ${expected.length} records, but walking at ` +
+                    `limit=${walkSize} yielded ${walked.length} and missed ${missing.length}: ${missing.slice(0, 3).join(", ")}`,
+                evidence: [single.exchange],
+            });
+        }
+        /* Instability is probabilistic: one walk can come out intact by luck. Two identical walks
+         * must agree, so comparing them tests the ordering guarantee directly rather than waiting
+         * for a dropped row to happen to appear. */
+        const second = (await walkPages(ctx, walkSize, orderParam)).ids;
+        if (second.join(",") === walked.join(","))
+            return ASSERTED;
+        return reportUnstableWalks(ctx, this.id, { orderParam, second, walked }, single.exchange);
+    },
+});
+//# sourceMappingURL=pagination-page-walk-covers-set.js.map

package/dist/api/runtime/checks/families/pagination/walk.d.ts

@@ -0,0 +1,16 @@
+import type { SortValue } from "../../../../spec/render/sort.ts";
+import type { Listed } from "../../core/context.ts";
+import { type Walk } from "../../sets/list.ts";
+/**
+ * How many pages a walk will traverse.
+ *
+ * Walking a whole collection is O(n) strictly sequential requests, so against a large existing
+ * dataset it dominates the entire run — and buys nothing. Pagination defects manifest at the
+ * *first* page boundary: a missing tiebreak, an off-by-one offset, a drifting cursor all show up
+ * within the first few pages or not at all. Bounding the walk makes runtime independent of how
+ * much data the system under test happens to be holding.
+ */
+export declare const MAX_WALK_PAGES = 6;
+/** Walks pages in order, returning ids as encountered — repeats kept, since they are the finding. */
+export declare function walkPages(ctx: Listed, perPage: number, order?: SortValue, maxPages?: number): Promise<Walk>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/api/runtime/checks/families/pagination/walk.js

@@ -0,0 +1,23 @@
+import { ids } from "../../sets/list.js";
+import { readSet } from "../../sets/read.js";
+/**
+ * How many pages a walk will traverse.
+ *
+ * Walking a whole collection is O(n) strictly sequential requests, so against a large existing
+ * dataset it dominates the entire run — and buys nothing. Pagination defects manifest at the
+ * *first* page boundary: a missing tiebreak, an off-by-one offset, a drifting cursor all show up
+ * within the first few pages or not at all. Bounding the walk makes runtime independent of how
+ * much data the system under test happens to be holding.
+ */
+export const MAX_WALK_PAGES = 6;
+/** Walks pages in order, returning ids as encountered — repeats kept, since they are the finding. */
+export async function walkPages(ctx, perPage, order, maxPages = MAX_WALK_PAGES) {
+    const read = await readSet(ctx, {}, { fresh: true, keepRepeats: true, maxPages, order, size: perPage });
+    return {
+        exchanges: read.pages.map((page) => page.exchange),
+        ids: ids(read.items, ctx.identity),
+        items: read.items,
+        truncated: !read.complete,
+    };
+}
+//# sourceMappingURL=walk.js.map

package/dist/api/runtime/checks/families/search-select/search-case-insensitive.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "../../core/check.ts";
+export declare const searchCaseInsensitive: Check<{
+    token: string;
+    flipped: string;
+}>;
+//# sourceMappingURL=search-case-insensitive.d.ts.map

package/dist/api/runtime/checks/families/search-select/search-case-insensitive.js

@@ -0,0 +1,63 @@
+import { defineCheck } from "../../core/define.js";
+import { ASSERTED } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, MOVING, pageSize, q, resolvedCaps } from "../../query/capabilities.js";
+import { listAgain, listAll, sameSet, setOf, settlePair } from "../../sets/compare.js";
+export const searchCaseInsensitive = defineCheck({
+    plan: (ctx) => {
+        if (conv(ctx).search === undefined)
+            return cannot();
+        /* The first word with a letter, searchable field by field and record by record: a word of
+         * the first text value that holds a letter at all. */
+        const token = (ctx.query?.searchable ?? [])
+            .flatMap((field) => ctx.records.map((row) => row[field]))
+            .filter((value) => typeof value === "string")
+            .flatMap((value) => value.split(/\s+/))
+            .find((part) => /[A-Za-z]/.test(part));
+        if (token === undefined)
+            return cannot();
+        const flipped = token.replace(/[A-Za-z]/, (ch) => (ch === ch.toLowerCase() ? ch.toUpperCase() : ch.toLowerCase()));
+        return ready({ flipped, token });
+    },
+    dependsOn: ["pagination.page-walk-covers-set", "search.q-narrows-result"],
+    id: "search.case-insensitive",
+    lists: true,
+    needs: "a searchable string with a letter",
+    subjects: subjectsOf.list,
+    async run(ctx, { flipped, token }) {
+        const limit = pageSize(ctx);
+        const query = (term) => q(ctx, { limit, search: term });
+        const first = await listAll(ctx, query(token));
+        const second = await listAll(ctx, query(flipped));
+        if (first.exchange.status >= 400 || second.exchange.status >= 400) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "a case-flipped search was rejected");
+        }
+        if (!first.complete || !second.complete) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the sets are larger than a read covers");
+        }
+        /* A record written between the two searches is the collection moving, not case mattering. */
+        const settled = await settlePair(ctx.identity, { first, second }, {
+            first: () => listAgain(ctx, query(token)),
+            second: () => listAgain(ctx, query(flipped)),
+        });
+        if (settled === null)
+            return ctx.findings.unresolved(this.id, ctx.entityName, "a case-flipped search was rejected");
+        if (settled === "moving")
+            return ctx.findings.unresolved(this.id, ctx.entityName, MOVING);
+        const { first: original, second: other } = settled;
+        const a = setOf(original.items, ctx.identity);
+        const b = setOf(other.items, ctx.identity);
+        if (sameSet(a, b))
+            return ASSERTED;
+        if (resolvedCaps(ctx).searchCase === "insensitive") {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "search is not case-insensitive",
+                detail: `q=${JSON.stringify(token)} and q=${JSON.stringify(flipped)} selected different sets.`,
+                evidence: [original.exchange, other.exchange],
+            });
+        }
+        return ctx.findings.unresolved(this.id, ctx.entityName, "case-flipped search selected a different set; declare searchCase: insensitive to treat that as a defect");
+    },
+});
+//# sourceMappingURL=search-case-insensitive.js.map

package/dist/api/runtime/checks/families/search-select/search-empty-q.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "../../core/check.ts";
+import type { EffectiveQueryCapabilities } from "../../../../spec/query/effective.ts";
+export declare const searchEmptyQ: Check<{
+    policy: NonNullable<EffectiveQueryCapabilities["searchEmpty"]>;
+}>;
+//# sourceMappingURL=search-empty-q.d.ts.map