@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/families/filter/filter-in-is-union-of-eq.js

@@ -0,0 +1,57 @@
+import { defineCheck } from "../../core/define.js";
+import { filterTerm } from "../../../../spec/conventions/filter.js";
+import { ASSERTED } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { asTermValue, conv, filterable, FOUNDATIONS, MOVING_COLLECTION } from "../../query/capabilities.js";
+import { readSettled, sameSet, setOf } from "../../sets/compare.js";
+import { ids } from "../../sets/list.js";
+import { pickFieldForOp } from "./fields.js";
+export const filterInIsUnionOfEq = defineCheck({
+    plan: (ctx) => {
+        const picked = filterable(ctx) ? pickFieldForOp(ctx, "in", 2) : null;
+        const [a, b] = picked?.values ?? [];
+        if (picked === null || a === undefined || b === undefined)
+            return cannot();
+        const conventions = conv(ctx);
+        const field = picked.field.field;
+        const inTerm = filterTerm(conventions, { field, op: "in", value: [asTermValue(a), asTermValue(b)] });
+        const eqA = filterTerm(conventions, { field, op: "eq", value: asTermValue(a) });
+        const eqB = filterTerm(conventions, { field, op: "eq", value: asTermValue(b) });
+        if (inTerm === null || eqA === null || eqB === null)
+            return cannot("a filter grammar that can express in and eq");
+        return ready({ a, b, eqA, eqB, field, inTerm });
+    },
+    dependsOn: ["query.filter-selects-from-whole-set", ...FOUNDATIONS, "filter.equality-selects-exactly-one"],
+    id: "filter.in-is-union-of-eq",
+    lists: true,
+    needs: "a field that allows `in` and at least two distinct values",
+    subjects: subjectsOf.list,
+    async run(ctx, { a, b, eqA, eqB, field, inTerm }) {
+        const union = (left, right) => new Set([...ids(left.items, ctx.identity), ...ids(right.items, ctx.identity)]);
+        const reads = await readSettled(ctx, [inTerm, eqA, eqB], (sets) => {
+            const [inRead, eqARead, eqBRead] = sets;
+            return sameSet(union(eqARead, eqBRead), setOf(inRead.items, ctx.identity));
+        });
+        if (reads === "rejected")
+            return ctx.findings.unresolved(this.id, ctx.entityName, "one of the listings needed for in() was rejected");
+        if (reads === "incomplete") {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the collection is larger than the walk covers");
+        }
+        if (reads === "moving")
+            return ctx.findings.unresolved(this.id, ctx.entityName, MOVING_COLLECTION);
+        /* One read per term, in the order the terms were given. */
+        const [together, onlyA, onlyB] = reads;
+        const expected = union(onlyA, onlyB);
+        const got = setOf(together.items, ctx.identity);
+        if (sameSet(expected, got))
+            return ASSERTED;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "in() is not the union of the equalities it lists",
+            detail: `${field}.in.(${String(a)},${String(b)}) returned ${got.size} record(s); ` +
+                `eq on each value together match ${expected.size}.`,
+            evidence: [together.last.exchange, onlyA.last.exchange, onlyB.last.exchange],
+        });
+    },
+});
+//# sourceMappingURL=filter-in-is-union-of-eq.js.map

package/dist/api/runtime/checks/families/filter/filter-in-over-limit-rejected.d.ts

@@ -0,0 +1,7 @@
+import type { Check } from "../../core/check.ts";
+export declare const filterInOverLimitRejected: Check<{
+    field: string;
+    max: number;
+    term: Record<string, string>;
+}>;
+//# sourceMappingURL=filter-in-over-limit-rejected.d.ts.map

package/dist/api/runtime/checks/families/filter/filter-in-over-limit-rejected.js

@@ -0,0 +1,38 @@
+import { defineCheck } from "../../core/define.js";
+import { filterTerm } from "../../../../spec/conventions/filter.js";
+import { cannot, ready } from "../../core/plan.js";
+import { asProbe, judgeRefusal } from "../../planning/refusal.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, FOUNDATIONS, q, resolvedCaps } from "../../query/capabilities.js";
+import { list } from "../../sets/list.js";
+import { pickFieldForOp } from "./fields.js";
+export const filterInOverLimitRejected = defineCheck({
+    plan: (ctx) => {
+        const max = resolvedCaps(ctx).maxInValues;
+        const picked = pickFieldForOp(ctx, "in", 1);
+        if (max === undefined || picked === null)
+            return cannot();
+        const members = Array.from({ length: max + 1 }, (_, i) => `testing-over-limit-${i}`);
+        const term = filterTerm(conv(ctx), { field: picked.field.field, op: "in", value: members });
+        return term === null
+            ? cannot("a filter grammar that can express in()")
+            : ready({ field: picked.field.field, max, term });
+    },
+    dependsOn: [...FOUNDATIONS, "error.malformed-filter-not-5xx"],
+    id: "filter.in-over-limit-rejected",
+    lists: true,
+    needs: "`maxInValues` declared and a field that allows `in`",
+    subjects: subjectsOf.list,
+    async run(ctx, { field, max, term }) {
+        const result = await list(asProbe(ctx), { ...q(ctx, { limit: 5 }), ...term });
+        const refused = judgeRefusal(ctx, this.id, ["validation"], result.exchange);
+        if (refused !== null)
+            return refused;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "an over-limit in() list was accepted",
+            detail: `maxInValues=${max} but ${field}.in with ${max + 1} members returned ${result.exchange.status}.`,
+            evidence: [result.exchange],
+        });
+    },
+});
+//# sourceMappingURL=filter-in-over-limit-rejected.js.map

package/dist/api/runtime/checks/families/filter/filter-is-null-selects-nulls.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "../../core/check.ts";
+import type { EffectiveFilterField } from "../../../../spec/query/effective.ts";
+export declare const filterIsNullSelectsNulls: Check<{
+    field: EffectiveFilterField;
+    nullTerm: Record<string, string>;
+    notNullTerm: Record<string, string>;
+}>;
+//# sourceMappingURL=filter-is-null-selects-nulls.d.ts.map

package/dist/api/runtime/checks/families/filter/filter-is-null-selects-nulls.js

@@ -0,0 +1,71 @@
+import { defineCheck } from "../../core/define.js";
+import { filterTerm } from "../../../../spec/conventions/filter.js";
+import { ASSERTED } from "../../../finding.js";
+import { idOf } from "../../../world/records.js";
+import { cannot, ready } from "../../core/plan.js";
+import { storedFieldsUnknown } from "../../planning/stand-down.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, FOUNDATIONS, MOVING_COLLECTION } from "../../query/capabilities.js";
+import { holdsSomeNulls } from "../../query/order.js";
+import { readSettled, sameSet } from "../../sets/compare.js";
+import { fieldsAllowing, knownHits } from "./fields.js";
+function mixedNullField(ctx, field) {
+    if (ctx.softDelete !== null && field === ctx.softDelete)
+        return false;
+    return holdsSomeNulls(ctx, field);
+}
+export const filterIsNullSelectsNulls = defineCheck({
+    plan: (ctx) => {
+        const unverified = storedFieldsUnknown(ctx);
+        if (unverified !== undefined)
+            return unverified;
+        const field = fieldsAllowing(ctx, "is").find((item) => mixedNullField(ctx, item.field));
+        if (field === undefined)
+            return cannot();
+        const conventions = conv(ctx);
+        const nullTerm = filterTerm(conventions, { field: field.field, op: "is", value: "null" });
+        const notNullTerm = filterTerm(conventions, { field: field.field, op: "is", value: "notnull" });
+        if (nullTerm === null || notNullTerm === null)
+            return cannot("a filter grammar that can express is.null");
+        return ready({ field, notNullTerm, nullTerm });
+    },
+    dependsOn: ["query.filter-selects-from-whole-set", ...FOUNDATIONS],
+    id: "filter.is-null-selects-nulls",
+    lists: true,
+    needs: "a field that allows `is` and a cohort that contains a null",
+    subjects: subjectsOf.list,
+    async run(ctx, { field, notNullTerm, nullTerm }) {
+        const expectedOf = () => new Set(ctx.records
+            .filter((row) => row[field.field] === null || row[field.field] === undefined)
+            .flatMap((row) => idOf(row, ctx.identity) ?? []));
+        const reads = await readSettled(ctx, [{}, nullTerm, notNullTerm], (sets) => {
+            const [, n, p] = sets;
+            const got = knownHits(n.items, ctx);
+            return sameSet(expectedOf(), got) && ![...got].some((id) => knownHits(p.items, ctx).has(id));
+        });
+        if (reads === "rejected")
+            return ctx.findings.unresolved(this.id, ctx.entityName, "an is.null / is.notnull listing was rejected");
+        if (reads === "incomplete") {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the collection is larger than the walk covers");
+        }
+        if (reads === "moving")
+            return ctx.findings.unresolved(this.id, ctx.entityName, MOVING_COLLECTION);
+        /* One read per term, in the order the terms were given. */
+        const [, nulls, present] = reads;
+        const expectedNulls = new Set(ctx.records
+            .filter((row) => row[field.field] === null || row[field.field] === undefined)
+            .flatMap((row) => idOf(row, ctx.identity) ?? []));
+        const gotNulls = knownHits(nulls.items, ctx);
+        const overlap = [...gotNulls].filter((id) => knownHits(present.items, ctx).has(id));
+        if (!sameSet(expectedNulls, gotNulls) || overlap.length > 0) {
+            ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "is.null / is.notnull do not partition on nulls",
+                detail: `is.null returned ${gotNulls.size} record(s); ${expectedNulls.size} cohort rows are null. ` +
+                    (overlap.length > 0 ? `${overlap.length} appear on both sides.` : ""),
+                evidence: [nulls.last.exchange, present.last.exchange],
+            });
+        }
+        return ASSERTED;
+    },
+});
+//# sourceMappingURL=filter-is-null-selects-nulls.js.map

package/dist/api/runtime/checks/families/filter/filter-like-metacharacters-escaped.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "../../core/check.ts";
+export declare const likeEscaping: Check<{
+    field: string;
+    likeTerm: Record<string, string>;
+}>;
+//# sourceMappingURL=filter-like-metacharacters-escaped.d.ts.map

package/dist/api/runtime/checks/families/filter/filter-like-metacharacters-escaped.js

@@ -0,0 +1,56 @@
+import { defineCheck } from "../../core/define.js";
+import { filterSpec, filterTerm } from "../../../../spec/conventions/filter.js";
+import { ASSERTED } from "../../../finding.js";
+import { cannot, ready } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, filterable, filterableNames } from "../../query/capabilities.js";
+import { readSet } from "../../sets/read.js";
+function firstFilterable(ctx, predicate) {
+    return filterableNames(ctx).find(predicate) ?? null;
+}
+export const likeEscaping = defineCheck({
+    plan: (ctx) => {
+        if (!filterable(ctx) || ctx.records.length <= 1)
+            return cannot();
+        const field = firstFilterable(ctx, (name) => (ctx.query?.searchable ?? []).includes(name));
+        if (field === null)
+            return cannot("a field that is both filterable and searchable");
+        /* A literal `%` is not a wildcard in this grammar — `*` is, or the value is a bare substring.
+         * Matching everything means the value was interpolated into a LIKE pattern unescaped. Where
+         * the grammar declares `%` its wildcard, matching everything is the answer, not a leak. */
+        if (filterSpec(conv(ctx)).likeWildcard === "%")
+            return cannot("a like operator that reads % literally");
+        const likeTerm = filterTerm(conv(ctx), { field, op: "like", value: "%" });
+        return likeTerm === null ? cannot("a filter grammar with a like operator") : ready({ field, likeTerm });
+    },
+    /* The tell is "the filtered result equals the whole listing". Where the listing is already
+     * wrong, that comparison is against a set the backend never served correctly. */
+    dependsOn: ["query.filter-selects-from-whole-set", "pagination.page-walk-covers-set", "list.read-after-write"],
+    id: "filter.like-metacharacters-escaped",
+    lists: true,
+    needs: "a `filter` parameter supporting a like operator",
+    subjects: subjectsOf.list,
+    async run(ctx, { field, likeTerm }) {
+        const total = await readSet(ctx);
+        const probe = await readSet(ctx, likeTerm);
+        if (probe.status !== "ok") {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `the like probe was rejected with ${probe.last.exchange.status}, so escaping was never exercised`);
+        }
+        if (total.status !== "ok" || !total.complete || !probe.complete) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the sets are larger than a read covers");
+        }
+        if (total.items.length === 0) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the unfiltered listing returned nothing, leaving no baseline to compare the probe against");
+        }
+        if (probe.items.length < total.items.length)
+            return ASSERTED;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "LIKE metacharacters in a filter value are not escaped",
+            detail: `filter=${field}.like.%25 matched all ${probe.items.length} records. "%" is a literal in ` +
+                "this grammar; treating it as a wildcard means user input is being interpolated into a " +
+                "pattern unescaped.",
+            evidence: [total.last.exchange, probe.last.exchange],
+        });
+    },
+});
+//# sourceMappingURL=filter-like-metacharacters-escaped.js.map

package/dist/api/runtime/checks/families/filter/filter-lte-is-lt-or-eq.d.ts

@@ -0,0 +1,4 @@
+import type { Check } from "../../core/check.ts";
+import { type RangeProbe } from "./range.ts";
+export declare const filterLteIsLtOrEq: Check<RangeProbe>;
+//# sourceMappingURL=filter-lte-is-lt-or-eq.d.ts.map

package/dist/api/runtime/checks/families/filter/filter-lte-is-lt-or-eq.js

@@ -0,0 +1,21 @@
+import { defineCheck } from "../../core/define.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { FOUNDATIONS } from "../../query/capabilities.js";
+import { assertRangeUnion, rangePlan } from "./range.js";
+export const filterLteIsLtOrEq = defineCheck({
+    plan: (ctx) => rangePlan(ctx, "lte", "lt"),
+    dependsOn: [
+        "query.filter-selects-from-whole-set",
+        ...FOUNDATIONS,
+        "filter.equality-selects-exactly-one",
+        "filter.numeric-comparison-is-numeric",
+    ],
+    id: "filter.lte-is-lt-or-eq",
+    lists: true,
+    needs: "an ordered field that allows `lte` and `lt`",
+    subjects: subjectsOf.list,
+    async run(ctx, probe) {
+        return assertRangeUnion(ctx, this.id, probe);
+    },
+});
+//# sourceMappingURL=filter-lte-is-lt-or-eq.js.map

package/dist/api/runtime/checks/families/filter/filter-malformed-term-rejected.d.ts

@@ -0,0 +1,11 @@
+import type { Check } from "../../core/check.ts";
+/**
+ * A filter term missing a piece the declared grammar requires must be refused. Dropped instead,
+ * the caller gets the whole collection back as though it matched.
+ */
+export declare const filterMalformedTermRejected: Check<{
+    control: Record<string, string>;
+    field: string;
+    malformed: Record<string, string>;
+}>;
+//# sourceMappingURL=filter-malformed-term-rejected.d.ts.map

package/dist/api/runtime/checks/families/filter/filter-malformed-term-rejected.js

@@ -0,0 +1,72 @@
+import { defineCheck } from "../../core/define.js";
+import { filterSpec, filterTerm } from "../../../../spec/conventions/filter.js";
+import { renderMalformed } from "../../../../spec/render/filter-probe.js";
+import { cannot, ready } from "../../core/plan.js";
+import { asProbe, judgeRefusal } from "../../planning/refusal.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { asTermValue, conv, filterable, pageSize, q, resolvedCaps } from "../../query/capabilities.js";
+import { ids, list } from "../../sets/list.js";
+/**
+ * A filter term missing a piece the declared grammar requires must be refused. Dropped instead,
+ * the caller gets the whole collection back as though it matched.
+ */
+export const filterMalformedTermRejected = defineCheck({
+    plan: (ctx) => {
+        const conventions = conv(ctx);
+        if (conventions.grammarDeclared !== true || !filterable(ctx))
+            return cannot();
+        for (const field of resolvedCaps(ctx).filterable) {
+            const sample = ctx.records.find((row) => row[field.field] != null);
+            const value = sample === undefined ? "testing-probe" : String(asTermValue(sample[field.field]));
+            const malformed = renderMalformed({
+                field: field.field,
+                filterParam: conventions.filter,
+                spec: filterSpec(conventions),
+                value,
+            });
+            const control = filterTerm(conventions, { field: field.field, op: "eq", value });
+            if (malformed !== null && control !== null)
+                return ready({ control, field: field.field, malformed });
+        }
+        return cannot("a declared grammar whose terms carry a conjunction or an operator to leave out");
+    },
+    dependsOn: ["list.read-after-write", "filter.unknown-field-rejected", "error.malformed-filter-not-5xx"],
+    id: "filter.malformed-term-rejected",
+    lists: true,
+    needs: "a declared filter grammar whose terms carry a conjunction or an operator",
+    subjects: subjectsOf.list,
+    async run(ctx, { control, field, malformed }) {
+        const accepted = await list(ctx, { ...q(ctx, { limit: pageSize(ctx) }), ...control });
+        if (accepted.exchange.status >= 400) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `a well-formed term on "${field}" was refused, so a malformed one proves nothing`);
+        }
+        const result = await list(asProbe(ctx), { ...q(ctx, { limit: pageSize(ctx) }), ...malformed });
+        if (result.exchange.status >= 500) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "a malformed filter term produces a server error",
+                detail: `${Object.values(malformed).join("&")} returned ${result.exchange.status}; a rejected input should be 4xx.`,
+                evidence: [result.exchange],
+            });
+        }
+        const refused = judgeRefusal(ctx, this.id, ["validation"], result.exchange);
+        if (refused !== null)
+            return refused;
+        const baseline = await list(ctx, q(ctx, { limit: pageSize(ctx) }));
+        const selected = (items) => ids(items, ctx.identity).join(",");
+        const same = selected(result.items) === selected(baseline.items);
+        /* Applied, not dropped: a grammar that spells equality with or without its operator (Typesense's
+         * `year:1` is `year:=1`) has no malformed term here to refuse. */
+        if (!same && selected(result.items) === selected(accepted.items)) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, `${Object.values(malformed).join("&")} selected exactly what ${Object.values(control).join("&")} did: ` +
+                "the server reads a term without its operator as that equality, so there is no malformed term to send it");
+        }
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "a malformed filter term is accepted",
+            detail: `${Object.values(malformed).join("&")} returned ${result.exchange.status}` +
+                (same ? " with the unfiltered set, so the term was dropped" : "") +
+                ". A term the declared grammar cannot parse must be rejected.",
+            evidence: [baseline.exchange, result.exchange],
+        });
+    },
+});
+//# sourceMappingURL=filter-malformed-term-rejected.js.map

package/dist/api/runtime/checks/families/filter/filter-negation-partitions-the-set.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "../../core/check.ts";
+export declare const negationPartitions: Check<{
+    field: string;
+    value: string;
+    eqTerm: Record<string, string>;
+    neqTerm: Record<string, string>;
+}>;
+//# sourceMappingURL=filter-negation-partitions-the-set.d.ts.map

package/dist/api/runtime/checks/families/filter/filter-negation-partitions-the-set.js

@@ -0,0 +1,99 @@
+import { defineCheck } from "../../core/define.js";
+import { filterTerm } from "../../../../spec/conventions/filter.js";
+import { ASSERTED } from "../../../finding.js";
+import { idOf } from "../../../world/records.js";
+import { cannot, ready } from "../../core/plan.js";
+import { subjectsOf } from "../../planning/subjects.js";
+import { conv, filterable, filterableNames, filterIdentity, identityIsFilterable, pageSize, } from "../../query/capabilities.js";
+import { nullableField } from "../../query/order.js";
+import { collectSet, unlessMoved } from "../../sets/compare.js";
+import { ids } from "../../sets/list.js";
+export const negationPartitions = defineCheck({
+    plan: (ctx) => {
+        if (!filterable(ctx) || ctx.records.length <= 1 || !identityIsFilterable(ctx))
+            return cannot();
+        /* Prefer a field with nulls in the cohort: partitioning on the identity can never expose
+         * three-valued-logic bugs, because an identity is never null. */
+        const field = nullableField(ctx, filterableNames(ctx)) ?? filterIdentity(ctx);
+        const probe = ctx.records.map((r) => r[field]).find((v) => v !== null && v !== undefined);
+        if (probe === undefined)
+            return cannot(`a cohort record with a non-null "${field}" to negate`);
+        const value = String(probe);
+        const eqTerm = filterTerm(conv(ctx), { field, op: "eq", value });
+        const neqTerm = filterTerm(conv(ctx), { field, op: "neq", value });
+        /* Negation has no representation in an equality-only grammar, so this property simply
+         * cannot be expressed against such an API — better to stand down than to send something
+         * meaningless and read the answer as a defect. */
+        if (eqTerm === null || neqTerm === null)
+            return cannot("a filter grammar that can express negation");
+        return ready({ eqTerm, field, neqTerm, value });
+    },
+    dependsOn: [
+        "query.filter-selects-from-whole-set",
+        "list.read-after-write",
+        /* Partitioning is asserted over field *values*. A backend that drops submitted fields
+         * leaves the cohort without the value the predicate is built from. */
+        "create.persists-submitted-fields",
+        /* The three sets are gathered across pages, so a walk that skips or repeats records makes
+         * the partition fail for a reason that has nothing to do with the predicate. */
+        "pagination.page-walk-covers-set",
+    ],
+    id: "filter.negation-partitions-the-set",
+    lists: true,
+    needs: "a `filter` parameter supporting eq and neq",
+    subjects: subjectsOf.list,
+    async run(ctx, { eqTerm, field, neqTerm }) {
+        const limit = pageSize(ctx);
+        const all = await collectSet(ctx, limit);
+        const matching = await collectSet(ctx, limit, eqTerm);
+        const complement = await collectSet(ctx, limit, neqTerm);
+        if (all === null || matching === null || complement === null) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "one of the three listings needed for the partition was rejected");
+        }
+        /* Set algebra only holds over complete sets. A walk that hit the page cap has seen a
+         * prefix, and the union would legitimately miss whatever lies beyond it. */
+        if (!all.complete || !matching.complete || !complement.complete) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the collection is larger than the walk covers, so the union cannot be compared against the whole set");
+        }
+        const union = new Set([...ids(matching.items, ctx.identity), ...ids(complement.items, ctx.identity)]);
+        const expected = new Set(ids(all.items, ctx.identity));
+        const overlap = ids(matching.items, ctx.identity).filter((value) => ids(complement.items, ctx.identity).includes(value));
+        const missing = [...expected].filter((id) => !union.has(id));
+        if (overlap.length > 0 || missing.length > 0) {
+            const terms = [{}, { query: eqTerm }, { query: neqTerm }];
+            const moved = await unlessMoved(ctx, this.id, { reads: [all, matching, complement], terms });
+            if (moved !== null)
+                return moved;
+        }
+        if (overlap.length > 0) {
+            return ctx.findings.backend(this.id, ctx.entityName, {
+                summary: "a predicate and its negation both match the same record",
+                detail: `${overlap.length} record(s) appear in both ${field}.eq and ${field}.neq results: ` +
+                    overlap.slice(0, 3).join(", "),
+                evidence: [matching.last.exchange, complement.last.exchange],
+            });
+        }
+        if (missing.length > 0)
+            reportUncovered(ctx, this.id, { field, missing, reads: [all, matching, complement] });
+        return ASSERTED;
+    },
+});
+/** Records that match neither the predicate nor its negation, and whether nulls explain them. */
+function reportUncovered(ctx, check, { field, missing, reads }) {
+    const nulls = missing.filter((id) => {
+        const record = ctx.records.find((r) => idOf(r, ctx.identity) === id);
+        return record !== undefined && (record[field] === null || record[field] === undefined);
+    });
+    ctx.findings.backend(check, ctx.entityName, {
+        summary: "a predicate and its negation do not cover the full set",
+        detail: `${missing.length} record(s) match neither ${field}.eq nor ${field}.neq: ` +
+            `${missing.slice(0, 3).join(", ")}. ` +
+            (nulls.length === missing.length
+                ? `Every one of them has ${field} = null, so the negated predicate is dropping ` +
+                    "nulls — SQL evaluates `col <> x` as NULL, not true, unless the query also " +
+                    "tests `col IS NULL`."
+                : "A record must satisfy either a predicate or its negation."),
+        evidence: reads.map((read) => read.last.exchange),
+    });
+}
+//# sourceMappingURL=filter-negation-partitions-the-set.js.map

package/dist/api/runtime/checks/families/filter/filter-nested-and-or-distributes.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "../../core/check.ts";
+export declare const filterNestedAndOrDistributes: Check<{
+    nested: Record<string, string>;
+    termA: Record<string, string>;
+    termB: Record<string, string>;
+    termC: Record<string, string>;
+}>;
+//# sourceMappingURL=filter-nested-and-or-distributes.d.ts.map

package/dist/api/runtime/checks/families/filter/filter-nested-and-or-distributes.js

@@ -0,0 +1,80 @@
+import { defineCheck } from "../../core/define.js";
+import { filterSpec, filterTerm } from "../../../../spec/conventions/filter.js";
+import { renderAndOfOr } from "../../../../spec/render/filter-combine.js";
+import { ASSERTED } from "../../../finding.js";
+import { idOf } from "../../../world/records.js";
+import { cannot, ready } from "../../core/plan.js";
+import { NO_IDENTITY, subjectsOf } from "../../planning/subjects.js";
+import { conv, filterableNames, filterIdentity, FOUNDATIONS, identityIsFilterable, MOVING_COLLECTION, } from "../../query/capabilities.js";
+import { readSettled, sameSet, setOf } from "../../sets/compare.js";
+import { twoFilterableFields } from "./compound.js";
+export const filterNestedAndOrDistributes = defineCheck({
+    plan: (ctx) => {
+        if (!filterSpec(conv(ctx)).mixed || filterableNames(ctx).length <= 1)
+            return cannot();
+        const picked = twoFilterableFields(ctx);
+        if (picked === null)
+            return cannot("a cohort record with values on two distinct filterable fields");
+        const idField = filterIdentity(ctx);
+        if (idField === picked.fieldA || idField === picked.fieldB || !identityIsFilterable(ctx)) {
+            return cannot("a filterable identity as a third term to nest and/or");
+        }
+        const conventions = conv(ctx);
+        const a = { field: picked.fieldA, op: "eq", value: String(picked.target[picked.fieldA]) };
+        const b = { field: picked.fieldB, op: "eq", value: String(picked.target[picked.fieldB]) };
+        const pickedId = idOf(picked.target, ctx.identity);
+        if (pickedId === undefined)
+            return cannot(NO_IDENTITY);
+        const c = { field: idField, op: "eq", value: pickedId };
+        const nested = renderAndOfOr(filterSpec(conventions), conventions.filter, { either: [b, c], first: a });
+        const termA = filterTerm(conventions, { field: a.field, op: a.op, value: a.value });
+        const termB = filterTerm(conventions, { field: b.field, op: b.op, value: b.value });
+        const termC = filterTerm(conventions, { field: c.field, op: c.op, value: c.value });
+        if (nested === null || termA === null || termB === null || termC === null)
+            return cannot();
+        return ready({ nested, termA, termB, termC });
+    },
+    dependsOn: [
+        "query.filter-selects-from-whole-set",
+        ...FOUNDATIONS,
+        "filter.and-composes-as-intersection",
+        "filter.or-composes-as-union",
+    ],
+    id: "filter.nested-and-or-distributes",
+    lists: true,
+    needs: "a postgrest-shaped grammar and two filterable fields",
+    subjects: subjectsOf.list,
+    async run(ctx, { nested, termA, termB, termC }) {
+        const distributed = (a, b, c) => {
+            const setB = setOf(b.items, ctx.identity);
+            const setC = setOf(c.items, ctx.identity);
+            return new Set([...setOf(a.items, ctx.identity)].filter((id) => setB.has(id) || setC.has(id)));
+        };
+        const reads = await readSettled(ctx, [termA, termB, termC, nested], (sets) => {
+            const [a, b, c, n] = sets;
+            return sameSet(distributed(a, b, c), setOf(n.items, ctx.identity));
+        });
+        if (reads === "rejected")
+            return ctx.findings.unresolved(this.id, ctx.entityName, "a nested and/or listing was rejected");
+        if (reads === "incomplete") {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the collection is larger than the walk covers");
+        }
+        if (reads === "moving")
+            return ctx.findings.unresolved(this.id, ctx.entityName, MOVING_COLLECTION);
+        /* One read per term, in the order the terms were given. */
+        const [onlyA, onlyB, onlyC, combined] = reads;
+        const setA = setOf(onlyA.items, ctx.identity);
+        const setB = setOf(onlyB.items, ctx.identity);
+        const setC = setOf(onlyC.items, ctx.identity);
+        const expected = new Set([...setA].filter((id) => setB.has(id) || setC.has(id)));
+        const got = setOf(combined.items, ctx.identity);
+        if (sameSet(expected, got))
+            return ASSERTED;
+        return ctx.findings.backend(this.id, ctx.entityName, {
+            summary: "and(A,or(B,C)) is not (A∩B) ∪ (A∩C)",
+            detail: `nested combinator returned ${got.size}; the distributed form is ${expected.size}.`,
+            evidence: [combined.last.exchange, onlyA.last.exchange, onlyB.last.exchange, onlyC.last.exchange],
+        });
+    },
+});
+//# sourceMappingURL=filter-nested-and-or-distributes.js.map

package/dist/api/runtime/checks/families/filter/filter-nin-complements-in.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "../../core/check.ts";
+export declare const filterNinComplementsIn: Check<{
+    field: string;
+    members: Array<string | number>;
+    inTerm: Record<string, string>;
+    ninTerm: Record<string, string>;
+}>;
+//# sourceMappingURL=filter-nin-complements-in.d.ts.map