@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/reference/defects/catalog.js

@@ -0,0 +1,88 @@
+/** What the declared query catalog, ids, tenancy and side effects promise and the backend breaks. */
+export const CATALOG_DEFECTS = {
+    /** The alias table maps `ne` to the wrong operator: it behaves as `eq`. */
+    FILTER_ALIAS_MISMAPPED: "the ne alias is mapped to eq instead of neq",
+    /** A filter with more terms than `maxFilterConditions` is evaluated instead of rejected. */
+    FILTER_CONDITION_CAP_IGNORED: "a filter over the documented condition cap is accepted",
+    /** An `in()` list longer than `maxInValues` is evaluated instead of rejected. */
+    FILTER_IN_CAP_IGNORED: "an in() list over the documented maximum is accepted",
+    /** `lte` is compiled as `lt`. */
+    FILTER_LTE_IS_LT: "lte is implemented as lt",
+    /** `lt` is compiled as `lte`, so a boundary value is both below and equal to itself. */
+    FILTER_LT_IS_LTE: "lt is implemented as lte",
+    /**
+     * A builder that keeps one "current joiner": once a nested group sets it, the enclosing group
+     * joins its remaining terms with the nested group's combinator. Flat and()/or() are unaffected.
+     */
+    FILTER_NESTED_COMBINATOR_LEAKS: "a nested group's combinator replaces the enclosing group's",
+    /** `nin.(a,b)` only excludes the first listed value. */
+    FILTER_NIN_FIRST_ONLY: "nin() excludes only the first listed value",
+    /** Every pair and triple of axes composes; all four together drop the filter. */
+    FILTER_DROPPED_WHEN_SORTED_SEARCHED_AND_SELECTED: "a filter stops being applied once a sort, a search and a select are requested together",
+    /** A free-text search is dropped once a sparse fieldset joins it. */
+    SEARCH_DROPPED_WHEN_SELECTED: "a search stops being applied once a select is also requested",
+    /** A free-text search is dropped once a sort joins it. */
+    SEARCH_DROPPED_WHEN_SORTED: "a search stops being applied once a sort is also requested",
+    /** The sort is dropped once a sparse fieldset joins it. */
+    ORDER_DROPPED_WHEN_SELECTED: "a sort stops being applied once a select is also requested",
+    /** Search compares case-sensitively although the document declares it insensitive. */
+    SEARCH_CASE_SENSITIVE: "search is case-sensitive despite searchCase: insensitive",
+    /** An empty `q` matches nothing although the document declares it matches everything. */
+    SEARCH_EMPTY_MATCHES_NONE: "an empty search matches nothing despite searchEmpty: match-all",
+    /** Only the first whitespace-separated search token is applied. */
+    SEARCH_ONLY_FIRST_TOKEN: "only the first search token is applied",
+    /** An unknown select field is dropped although the document says it is rejected. */
+    SELECT_UNKNOWN_IGNORED: "an unknown select field is ignored despite select.unknown: reject",
+    /** `nullsfirst` / `nullslast` are parsed and ignored. */
+    SORT_NULLS_MODIFIER_IGNORED: "nullsfirst and nullslast modifiers are ignored",
+    /** An order on a field that does not exist is dropped instead of rejected. */
+    SORT_UNKNOWN_FIELD_IGNORED: "an unknown sort field is silently ignored rather than rejected",
+    /** The document lists an operator for a field that the backend rejects. */
+    SPEC_OVERCLAIMS_FILTER_OP: "x-query declares a filter operator on a field that the backend rejects",
+    /** `contains` matches the serialized array as text, so an element also matches its superstrings. */
+    CONTAINS_MATCHES_SUBSTRING: "contains matches any element containing the value, not the element itself",
+    /** A search mode the document declares is rejected. */
+    SEARCH_MODE_REJECTED: "a declared search mode is rejected",
+    /** A nested select returns the whole related record rather than the requested fields. */
+    NESTED_SELECT_IGNORED: "a nested select returns every field of the relation",
+    /** Without an explicit order the listing does not use the documented default order. */
+    DEFAULT_ORDER_IGNORED: "the listing ignores the documented default order",
+    /**
+     * Create crashes on input outside ASCII. Only some records carry such input, so most of a
+     * cohort is created fine and one variant fails with a 500.
+     */
+    CREATE_500_ON_NON_ASCII: "create fails with a server error when a string holds non-ASCII text",
+    /** A write whose side effect is declared with x-wait never produces it. */
+    SIDE_EFFECT_NEVER_ARRIVES: "a side effect declared with x-wait never arrives",
+    /** The first listing of each entity is refused with 429, far inside the rate x-rate-limit declares. */
+    RATE_LIMIT_STRICTER_THAN_DECLARED: "a listing answers 429 well inside the rate x-rate-limit declares",
+    /**
+     * Under the client-ids shape: the create stores the table under an id of the server's own,
+     * ignoring the one the client chose, and still answers only an acknowledgment.
+     */
+    CLIENT_ID_IGNORED: "a create ignores the client-chosen id and stores the record under another",
+    /** Under the client-ids shape: a create with an id the tenant already holds overwrites that record. */
+    CLIENT_ID_OVERWRITES: "a create with an existing id silently overwrites that record",
+    /** Update and delete find the record by id alone, so another tenant can change or remove it. */
+    CROSS_TENANT_WRITE: "update and delete reach records belonging to another tenant",
+    /** A child route accepts another tenant's parent id under the caller's own root. */
+    FOREIGN_PARENT_ACCEPTED: "a child collection is reachable through another tenant's parent placed under one's own root",
+    /** A page number past the end returns the last page again instead of an empty page. */
+    PAGE_PAST_END_REPEATS: "a page past the end of the collection repeats the last page",
+    /** A query parameter the listing does not know empties the result instead of being ignored. */
+    UNKNOWN_PARAM_EMPTIES_LIST: "an unknown query parameter makes the listing return nothing",
+    /** The viewer may update records the member may not. */
+    ROLE_WRITE_INVERTED: "a lower-ranked role can update a record a higher-ranked same-tenant role cannot",
+    /** Ties are broken by another field than the declared `stableTiebreak`. */
+    TIEBREAK_NOT_APPLIED: "ties are ordered by another field than the documented tiebreak",
+    /** A replayed idempotency key is answered with the original record, but a second row is written too. */
+    IDEMPOTENT_REPLAY_INSERTS: "a replayed create returns the original record and still inserts another",
+    /**
+     * A row holding `testing-payload-probe` — the ASCII control `payload.string-survives` writes to a fresh
+     * record before any case of its catalog — is hidden from everyone, its creator included: no
+     * read or list serves it, and its delete answers 200 and keeps it. Only teardown's account of
+     * what its creator never saw can name it.
+     */
+    HIDDEN_FROM_CREATOR: "a row holding a given value is never served, not even to its creator, and outlives its delete",
+};
+//# sourceMappingURL=catalog.js.map

package/dist/api/reference/defects/composition.d.ts

@@ -0,0 +1,59 @@
+/** Query axes that are each correct alone and break once combined, and paging cut before the filter. */
+export declare const COMPOSITION_DEFECTS: {
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a sort joins it.
+     *
+     * Models the real failure: adding an ORDER BY changes which index the planner picks, and the
+     * predicate rides on the index that is no longer chosen. Each axis is provably correct on its
+     * own, so a suite that only ever tests one at a time reports the API as clean.
+     */
+    readonly FILTER_DROPPED_WHEN_SORTED: "a filter stops being applied once a sort is also requested";
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a sparse
+     * fieldset joins it.
+     *
+     * The realistic shape: a query builder that projects first and then cannot (or does not)
+     * apply a predicate to a column it just omitted — or that takes a different code path the
+     * moment `fields=` is present and forgets the WHERE. Each axis is correct alone.
+     */
+    readonly FILTER_DROPPED_WHEN_SELECTED: "a filter stops being applied once a select is also requested";
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a free-text
+     * search joins it.
+     *
+     * Adding `q` often switches the backend onto a search-index path that does not honor the
+     * structured predicate. Search alone is correct, the filter alone is correct, and together
+     * the filter silently vanishes.
+     */
+    readonly FILTER_DROPPED_WHEN_SEARCHED: "a filter stops being applied once a search is also requested";
+    /**
+     * The filter survives each pair — filter+sort and filter+select — and vanishes only when
+     * both extra axes are present at once.
+     *
+     * A query planner that has a two-axis path and a three-axis path, and only the latter
+     * forgets the WHERE. Every pairwise check passes; the bug is the triple.
+     */
+    readonly FILTER_DROPPED_WHEN_SORTED_AND_SELECTED: "a filter stops being applied once a sort and a select are requested together";
+    /**
+     * The filter survives filter+search and filter+sort, and vanishes only when a search and a
+     * sort are requested together — typically the search-index path that also tries to honor
+     * an ORDER BY and drops the structured predicate to do it.
+     */
+    readonly FILTER_DROPPED_WHEN_SORTED_AND_SEARCHED: "a filter stops being applied once a sort and a search are requested together";
+    /**
+     * The filter survives filter+search and filter+select, and vanishes only when a search and
+     * a sparse fieldset are requested together.
+     */
+    readonly FILTER_DROPPED_WHEN_SEARCHED_AND_SELECTED: "a filter stops being applied once a search and a select are requested together";
+    /**
+     * The page window is computed over the *unfiltered* set, and the filter is applied to whatever
+     * that window happened to contain.
+     *
+     * Page one usually looks right, which is what makes it survive review. The damage shows up
+     * further in: pages come back short, records that match the predicate are never returned at
+     * all, and the total is computed over a different set than the rows. Any code that resolves a
+     * cursor or an offset before applying the predicate has this bug.
+     */
+    readonly FILTER_AFTER_PAGINATION: "paging is applied before filtering, so pages miss matching records";
+};
+//# sourceMappingURL=composition.d.ts.map

package/dist/api/reference/defects/composition.js

@@ -0,0 +1,59 @@
+/** Query axes that are each correct alone and break once combined, and paging cut before the filter. */
+export const COMPOSITION_DEFECTS = {
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a sort joins it.
+     *
+     * Models the real failure: adding an ORDER BY changes which index the planner picks, and the
+     * predicate rides on the index that is no longer chosen. Each axis is provably correct on its
+     * own, so a suite that only ever tests one at a time reports the API as clean.
+     */
+    FILTER_DROPPED_WHEN_SORTED: "a filter stops being applied once a sort is also requested",
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a sparse
+     * fieldset joins it.
+     *
+     * The realistic shape: a query builder that projects first and then cannot (or does not)
+     * apply a predicate to a column it just omitted — or that takes a different code path the
+     * moment `fields=` is present and forgets the WHERE. Each axis is correct alone.
+     */
+    FILTER_DROPPED_WHEN_SELECTED: "a filter stops being applied once a select is also requested",
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a free-text
+     * search joins it.
+     *
+     * Adding `q` often switches the backend onto a search-index path that does not honor the
+     * structured predicate. Search alone is correct, the filter alone is correct, and together
+     * the filter silently vanishes.
+     */
+    FILTER_DROPPED_WHEN_SEARCHED: "a filter stops being applied once a search is also requested",
+    /**
+     * The filter survives each pair — filter+sort and filter+select — and vanishes only when
+     * both extra axes are present at once.
+     *
+     * A query planner that has a two-axis path and a three-axis path, and only the latter
+     * forgets the WHERE. Every pairwise check passes; the bug is the triple.
+     */
+    FILTER_DROPPED_WHEN_SORTED_AND_SELECTED: "a filter stops being applied once a sort and a select are requested together",
+    /**
+     * The filter survives filter+search and filter+sort, and vanishes only when a search and a
+     * sort are requested together — typically the search-index path that also tries to honor
+     * an ORDER BY and drops the structured predicate to do it.
+     */
+    FILTER_DROPPED_WHEN_SORTED_AND_SEARCHED: "a filter stops being applied once a sort and a search are requested together",
+    /**
+     * The filter survives filter+search and filter+select, and vanishes only when a search and
+     * a sparse fieldset are requested together.
+     */
+    FILTER_DROPPED_WHEN_SEARCHED_AND_SELECTED: "a filter stops being applied once a search and a select are requested together",
+    /**
+     * The page window is computed over the *unfiltered* set, and the filter is applied to whatever
+     * that window happened to contain.
+     *
+     * Page one usually looks right, which is what makes it survive review. The damage shows up
+     * further in: pages come back short, records that match the predicate are never returned at
+     * all, and the total is computed over a different set than the rows. Any code that resolves a
+     * cursor or an offset before applying the predicate has this bug.
+     */
+    FILTER_AFTER_PAGINATION: "paging is applied before filtering, so pages miss matching records",
+};
+//# sourceMappingURL=composition.js.map

package/dist/api/reference/defects/core.d.ts

@@ -0,0 +1,63 @@
+/** The first defects: sessions, listings, writes, tenancy and the projections a write must reach. */
+export declare const CORE_DEFECTS: {
+    /** A destructive call, run as the second user, also kills the suite caller's session. */
+    readonly DISPOSABLE_KILLS_CALLER: "logout revokes the suite caller along with the disposable session";
+    /** The caller's project read answers with no credential. */
+    readonly ROOT_READ_OPEN: "the caller project read answers with no token";
+    /** Sort has no total order, so keyset paging silently drops and repeats rows. */
+    readonly UNSTABLE_SORT: "sort lacks a tiebreak; page walks drop or duplicate rows";
+    /** Writes land in the item store but the list projection serves a stale snapshot. */
+    readonly STALE_LIST: "list projection does not reflect writes visible on the item route";
+    /** Unrecognized filter fields are dropped instead of rejected. */
+    readonly FILTER_IGNORED: "unknown filter field is silently ignored rather than rejected";
+    /** Cursor pagination and offset pagination disagree about the underlying set. */
+    readonly CURSOR_DRIFT: "cursor pagination yields a different set than offset pagination";
+    /** PATCH behaves as PUT, clearing fields the caller never mentioned. */
+    readonly PATCH_REPLACES: "PATCH clears fields absent from the request body";
+    /** Total count ignores the active filter. */
+    readonly COUNT_IGNORES_FILTER: "count reflects the unfiltered set";
+    /** The tenant predicate is applied to the list query but not to filter matches. */
+    readonly TENANT_LEAK_VIA_FILTER: "filter bypasses the tenant predicate";
+    /**
+     * Denies cross-tenant reads with 403 rather than 404.
+     *
+     * The access decision is correct — the record is not served — but the status distinguishes
+     * "exists, not yours" from "does not exist", which turns the item route into an oracle for
+     * enumerating other tenants' identifiers.
+     */
+    readonly EXISTENCE_LEAK_VIA_STATUS: "cross-tenant denial uses 403, revealing that the record exists";
+    /**
+     * Accepts a second create (or a colliding PATCH) of a documented unique column set.
+     *
+     * The document said these columns are unique. Returning 2xx instead of 409 is the backend
+     * ignoring that constraint — the unique-conflict checks exist to name that lie.
+     */
+    readonly UNIQUE_NOT_ENFORCED: "a duplicate unique-set write is accepted instead of 409";
+    /**
+     * Accepts an Idempotency-Key and creates a second record anyway.
+     *
+     * The failure mode is a retry — a timeout, a proxy replay, a double-click — silently
+     * duplicating a charge or an order. The key is the client's only defense against that, and
+     * whether it is honored cannot be established without replaying a request.
+     */
+    readonly IDEMPOTENCY_IGNORED: "Idempotency-Key is accepted but replay creates a duplicate record";
+    /**
+     * A write invalidates a route the document says it invalidates — except it does not.
+     *
+     * The parent keeps serving a derived value computed before the child write: a denormalized
+     * counter nobody refreshes, or a cached projection whose key was never busted. The write
+     * succeeds, the child's own listing is correct, and only the *other* route the document named
+     * is wrong — which is why nothing short of following `x-invalidate` finds it.
+     */
+    readonly PARENT_PROJECTION_STALE: "a route named by x-invalidate keeps serving pre-write data";
+    /**
+     * The collection serves a different value for a field than the item route does.
+     *
+     * A denormalized listing, a search index rebuilt on a lag, a cached projection: each read path
+     * is internally consistent and individually plausible, so every per-projection check passes.
+     * Only comparing the paths against each other reveals that a client's view of a record depends
+     * on which route it happened to use.
+     */
+    readonly LIST_DETAIL_DISAGREE: "the collection and the item route serve different values for a field";
+};
+//# sourceMappingURL=core.d.ts.map

package/dist/api/reference/defects/core.js

@@ -0,0 +1,63 @@
+/** The first defects: sessions, listings, writes, tenancy and the projections a write must reach. */
+export const CORE_DEFECTS = {
+    /** A destructive call, run as the second user, also kills the suite caller's session. */
+    DISPOSABLE_KILLS_CALLER: "logout revokes the suite caller along with the disposable session",
+    /** The caller's project read answers with no credential. */
+    ROOT_READ_OPEN: "the caller project read answers with no token",
+    /** Sort has no total order, so keyset paging silently drops and repeats rows. */
+    UNSTABLE_SORT: "sort lacks a tiebreak; page walks drop or duplicate rows",
+    /** Writes land in the item store but the list projection serves a stale snapshot. */
+    STALE_LIST: "list projection does not reflect writes visible on the item route",
+    /** Unrecognized filter fields are dropped instead of rejected. */
+    FILTER_IGNORED: "unknown filter field is silently ignored rather than rejected",
+    /** Cursor pagination and offset pagination disagree about the underlying set. */
+    CURSOR_DRIFT: "cursor pagination yields a different set than offset pagination",
+    /** PATCH behaves as PUT, clearing fields the caller never mentioned. */
+    PATCH_REPLACES: "PATCH clears fields absent from the request body",
+    /** Total count ignores the active filter. */
+    COUNT_IGNORES_FILTER: "count reflects the unfiltered set",
+    /** The tenant predicate is applied to the list query but not to filter matches. */
+    TENANT_LEAK_VIA_FILTER: "filter bypasses the tenant predicate",
+    /**
+     * Denies cross-tenant reads with 403 rather than 404.
+     *
+     * The access decision is correct — the record is not served — but the status distinguishes
+     * "exists, not yours" from "does not exist", which turns the item route into an oracle for
+     * enumerating other tenants' identifiers.
+     */
+    EXISTENCE_LEAK_VIA_STATUS: "cross-tenant denial uses 403, revealing that the record exists",
+    /**
+     * Accepts a second create (or a colliding PATCH) of a documented unique column set.
+     *
+     * The document said these columns are unique. Returning 2xx instead of 409 is the backend
+     * ignoring that constraint — the unique-conflict checks exist to name that lie.
+     */
+    UNIQUE_NOT_ENFORCED: "a duplicate unique-set write is accepted instead of 409",
+    /**
+     * Accepts an Idempotency-Key and creates a second record anyway.
+     *
+     * The failure mode is a retry — a timeout, a proxy replay, a double-click — silently
+     * duplicating a charge or an order. The key is the client's only defense against that, and
+     * whether it is honored cannot be established without replaying a request.
+     */
+    IDEMPOTENCY_IGNORED: "Idempotency-Key is accepted but replay creates a duplicate record",
+    /**
+     * A write invalidates a route the document says it invalidates — except it does not.
+     *
+     * The parent keeps serving a derived value computed before the child write: a denormalized
+     * counter nobody refreshes, or a cached projection whose key was never busted. The write
+     * succeeds, the child's own listing is correct, and only the *other* route the document named
+     * is wrong — which is why nothing short of following `x-invalidate` finds it.
+     */
+    PARENT_PROJECTION_STALE: "a route named by x-invalidate keeps serving pre-write data",
+    /**
+     * The collection serves a different value for a field than the item route does.
+     *
+     * A denormalized listing, a search index rebuilt on a lag, a cached projection: each read path
+     * is internally consistent and individually plausible, so every per-projection check passes.
+     * Only comparing the paths against each other reveals that a client's view of a record depends
+     * on which route it happened to use.
+     */
+    LIST_DETAIL_DISAGREE: "the collection and the item route serve different values for a field",
+};
+//# sourceMappingURL=core.js.map

package/dist/api/reference/defects/defect-set.d.ts

@@ -0,0 +1,10 @@
+import { type DefectName } from "./table.ts";
+/** The defects one reference exhibits. */
+export declare class DefectSet {
+    private readonly enabled;
+    /** Throws on a name that is not a defect: a typo must not silently run a clean backend. */
+    constructor(names?: readonly string[]);
+    has(name: DefectName): boolean;
+    list(): DefectName[];
+}
+//# sourceMappingURL=defect-set.d.ts.map

package/dist/api/reference/defects/defect-set.js

@@ -0,0 +1,19 @@
+import { isDefectName } from "./table.js";
+/** The defects one reference exhibits. */
+export class DefectSet {
+    enabled;
+    /** Throws on a name that is not a defect: a typo must not silently run a clean backend. */
+    constructor(names = []) {
+        const unknown = names.filter((name) => !isDefectName(name));
+        if (unknown.length > 0)
+            throw new Error(`unknown defect(s): ${unknown.join(", ")}`);
+        this.enabled = new Set(names);
+    }
+    has(name) {
+        return this.enabled.has(name);
+    }
+    list() {
+        return [...this.enabled];
+    }
+}
+//# sourceMappingURL=defect-set.js.map

package/dist/api/reference/defects/freshness.d.ts

@@ -0,0 +1,8 @@
+/** Cached reads, under the cached-reads shape: how stale a read gets, and whether its bypass works. */
+export declare const FRESHNESS_DEFECTS: {
+    /** The cache keeps a copy past the staleness the read declares. */
+    STALE_PAST_BOUND: string;
+    /** The declared bypass header is accepted and ignored: the cache answers anyway. */
+    BYPASS_IGNORED: string;
+};
+//# sourceMappingURL=freshness.d.ts.map

package/dist/api/reference/defects/freshness.js

@@ -0,0 +1,8 @@
+/** Cached reads, under the cached-reads shape: how stale a read gets, and whether its bypass works. */
+export const FRESHNESS_DEFECTS = {
+    /** The cache keeps a copy past the staleness the read declares. */
+    STALE_PAST_BOUND: "a cached read stays stale past the staleness bound it declares",
+    /** The declared bypass header is accepted and ignored: the cache answers anyway. */
+    BYPASS_IGNORED: "a read's declared cache bypass is ignored and the cache answers",
+};
+//# sourceMappingURL=freshness.js.map

package/dist/api/reference/defects/query.d.ts

@@ -0,0 +1,58 @@
+/** What a filter, a sort or a sparse fieldset means: operators, keys, projections, and fields the document overclaims. */
+export declare const QUERY_DEFECTS: {
+    /**
+     * The document declares a field filterable that the backend rejects.
+     *
+     * Not a backend bug — the backend is entitled to refuse a field it never indexed. The document
+     * is what is wrong, and it is wrong in the most expensive way: every client generated from it
+     * offers a filter that 400s at runtime. The API tester is the only thing positioned to notice, because it
+     * is the only thing that reads the claim and then tries it.
+     */
+    readonly SPEC_OVERCLAIMS_FILTERABLE: "x-query declares a field filterable that the backend rejects";
+    /** `in.(a,b)` only honors the first member. */
+    readonly FILTER_IN_FIRST_ONLY: "in() matches only the first listed value";
+    /** `gte` is compiled as `gt`. */
+    readonly FILTER_GTE_IS_GT: "gte is implemented as gt";
+    /** `ilike` is compiled as case-sensitive `like`. */
+    readonly FILTER_ILIKE_IS_LIKE: "ilike is implemented as like";
+    /** `is.null` matches every row. */
+    readonly FILTER_IS_NULL_MATCHES_ALL: "is.null matches every row";
+    /** An operator outside the field's allowlist is ignored (200 + full set). */
+    readonly FILTER_ILLEGAL_OP_IGNORED: "an illegal filter operator is accepted and ignored";
+    /** A filter term the grammar cannot parse is dropped (200 + full set) instead of refused. */
+    readonly IGNORES_MALFORMED_FILTER: "a malformed filter term is dropped instead of refused";
+    /** A sort direction the grammar does not have is read as ascending instead of refused. */
+    readonly IGNORES_BAD_SORT_DIRECTION: "an unknown sort direction sorts ascending instead of being refused";
+    /** Numeric sort compares as text. */
+    readonly SORT_NUMERIC_AS_TEXT: "a numeric sortable field is ordered lexicographically";
+    /** Only the first order key is honored. */
+    readonly SORT_MULTI_KEY_IGNORED: "the second sort key is ignored";
+    /** A requested select field is omitted from the projection. */
+    readonly SELECT_FIELD_MISSING: "a requested select field is dropped from the projection";
+    /**
+     * The document declares a field sortable that the backend rejects.
+     *
+     * Same failure as SPEC_OVERCLAIMS_FILTERABLE, one role over: the backend is entitled to refuse
+     * a field it never indexed for ordering, but the document is wrong to promise it can. Every
+     * client generated from this document offers an `order` value that 400s at runtime.
+     */
+    readonly SPEC_OVERCLAIMS_SORTABLE: "x-query declares a field sortable that the backend rejects";
+    /**
+     * `and(a,b)` and `or(a,b)` are compiled with their joiner swapped: a conjunction evaluates as
+     * a disjunction and vice versa.
+     *
+     * A realistic shape for the bug: a query builder that always joins terms with the same
+     * operator regardless of which combinator the expression named, because the grouping was
+     * parsed but never actually consulted when assembling the join. Every single-predicate filter
+     * check still passes — the defect is invisible until two terms are combined.
+     */
+    readonly FILTER_GROUP_COMBINATOR_SWAPPED: "and() and or() combinators inside a filter expression are swapped";
+    /**
+     * The document declares a field selectable that the backend rejects.
+     *
+     * The select analog of SPEC_OVERCLAIMS_FILTERABLE and SPEC_OVERCLAIMS_SORTABLE: the backend
+     * is entitled to stop projecting a column, but the document is wrong to keep promising it can.
+     */
+    readonly SPEC_OVERCLAIMS_SELECTABLE: "x-query declares a field selectable that the backend rejects";
+};
+//# sourceMappingURL=query.d.ts.map

package/dist/api/reference/defects/query.js

@@ -0,0 +1,58 @@
+/** What a filter, a sort or a sparse fieldset means: operators, keys, projections, and fields the document overclaims. */
+export const QUERY_DEFECTS = {
+    /**
+     * The document declares a field filterable that the backend rejects.
+     *
+     * Not a backend bug — the backend is entitled to refuse a field it never indexed. The document
+     * is what is wrong, and it is wrong in the most expensive way: every client generated from it
+     * offers a filter that 400s at runtime. The API tester is the only thing positioned to notice, because it
+     * is the only thing that reads the claim and then tries it.
+     */
+    SPEC_OVERCLAIMS_FILTERABLE: "x-query declares a field filterable that the backend rejects",
+    /** `in.(a,b)` only honors the first member. */
+    FILTER_IN_FIRST_ONLY: "in() matches only the first listed value",
+    /** `gte` is compiled as `gt`. */
+    FILTER_GTE_IS_GT: "gte is implemented as gt",
+    /** `ilike` is compiled as case-sensitive `like`. */
+    FILTER_ILIKE_IS_LIKE: "ilike is implemented as like",
+    /** `is.null` matches every row. */
+    FILTER_IS_NULL_MATCHES_ALL: "is.null matches every row",
+    /** An operator outside the field's allowlist is ignored (200 + full set). */
+    FILTER_ILLEGAL_OP_IGNORED: "an illegal filter operator is accepted and ignored",
+    /** A filter term the grammar cannot parse is dropped (200 + full set) instead of refused. */
+    IGNORES_MALFORMED_FILTER: "a malformed filter term is dropped instead of refused",
+    /** A sort direction the grammar does not have is read as ascending instead of refused. */
+    IGNORES_BAD_SORT_DIRECTION: "an unknown sort direction sorts ascending instead of being refused",
+    /** Numeric sort compares as text. */
+    SORT_NUMERIC_AS_TEXT: "a numeric sortable field is ordered lexicographically",
+    /** Only the first order key is honored. */
+    SORT_MULTI_KEY_IGNORED: "the second sort key is ignored",
+    /** A requested select field is omitted from the projection. */
+    SELECT_FIELD_MISSING: "a requested select field is dropped from the projection",
+    /**
+     * The document declares a field sortable that the backend rejects.
+     *
+     * Same failure as SPEC_OVERCLAIMS_FILTERABLE, one role over: the backend is entitled to refuse
+     * a field it never indexed for ordering, but the document is wrong to promise it can. Every
+     * client generated from this document offers an `order` value that 400s at runtime.
+     */
+    SPEC_OVERCLAIMS_SORTABLE: "x-query declares a field sortable that the backend rejects",
+    /**
+     * `and(a,b)` and `or(a,b)` are compiled with their joiner swapped: a conjunction evaluates as
+     * a disjunction and vice versa.
+     *
+     * A realistic shape for the bug: a query builder that always joins terms with the same
+     * operator regardless of which combinator the expression named, because the grouping was
+     * parsed but never actually consulted when assembling the join. Every single-predicate filter
+     * check still passes — the defect is invisible until two terms are combined.
+     */
+    FILTER_GROUP_COMBINATOR_SWAPPED: "and() and or() combinators inside a filter expression are swapped",
+    /**
+     * The document declares a field selectable that the backend rejects.
+     *
+     * The select analog of SPEC_OVERCLAIMS_FILTERABLE and SPEC_OVERCLAIMS_SORTABLE: the backend
+     * is entitled to stop projecting a column, but the document is wrong to keep promising it can.
+     */
+    SPEC_OVERCLAIMS_SELECTABLE: "x-query declares a field selectable that the backend rejects",
+};
+//# sourceMappingURL=query.js.map