@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/checks/payloads/lanes.js

@@ -0,0 +1,10 @@
+/**
+ * How many lanes `payload.string-survives` runs. Through an update each lane writes a record of
+ * its own, so there are never more lanes than records: shared, two lanes would read back each
+ * other's writes. Through create every case is its own record.
+ */
+export function payloadLanes(input) {
+    const bound = Math.min(input.max, input.cases);
+    return Math.max(1, input.viaPatch ? Math.min(bound, input.records) : bound);
+}
+//# sourceMappingURL=lanes.js.map

package/dist/api/runtime/checks/payloads/stored-as.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether a field a write was sent reads back as stored. A backend may store a string trimmed or
+ * case-folded, as one lowercasing a slug does: that is the value it was sent, normalized, not a
+ * field it discarded. Any other difference is.
+ */
+export declare function storedAs(stored: unknown, sent: unknown): boolean;
+//# sourceMappingURL=stored-as.d.ts.map

package/dist/api/runtime/checks/payloads/stored-as.js

@@ -0,0 +1,14 @@
+/**
+ * Whether a field a write was sent reads back as stored. A backend may store a string trimmed or
+ * case-folded, as one lowercasing a slug does: that is the value it was sent, normalized, not a
+ * field it discarded. Any other difference is.
+ */
+export function storedAs(stored, sent) {
+    if (typeof stored === "string" && typeof sent === "string")
+        return folded(stored) === folded(sent);
+    return JSON.stringify(stored) === JSON.stringify(sent);
+}
+function folded(text) {
+    return text.trim().toLowerCase();
+}
+//# sourceMappingURL=stored-as.js.map

package/dist/api/runtime/checks/payloads/update-drops.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The fields an entity's update answers success to and does not store, as
+ * `update.persists-submitted-fields` found them. Every check that writes a field picks around them,
+ * so the one defect is reported once, by that check, never as a stale cache or a lost race.
+ */
+import type { CheckContext } from "../core/context.ts";
+/** What the update is known to drop on this entity; empty until the check has run. */
+export declare function updateDrops(ctx: Pick<CheckContext, "memo">): ReadonlySet<string>;
+export declare function recordUpdateDrops(ctx: Pick<CheckContext, "memo">, fields: readonly string[]): void;
+//# sourceMappingURL=update-drops.d.ts.map

package/dist/api/runtime/checks/payloads/update-drops.js

@@ -0,0 +1,16 @@
+/**
+ * The fields an entity's update answers success to and does not store, as
+ * `update.persists-submitted-fields` found them. Every check that writes a field picks around them,
+ * so the one defect is reported once, by that check, never as a stale cache or a lost race.
+ */
+import { memoTable } from "../sets/read.js";
+const TABLE = "updateDrops";
+const KEY = "fields";
+/** What the update is known to drop on this entity; empty until the check has run. */
+export function updateDrops(ctx) {
+    return new Set(memoTable(ctx.memo.entity, TABLE).get(KEY) ?? []);
+}
+export function recordUpdateDrops(ctx, fields) {
+    memoTable(ctx.memo.entity, TABLE).set(KEY, [...fields]);
+}
+//# sourceMappingURL=update-drops.js.map

package/dist/api/runtime/checks/planning/declarations.d.ts

@@ -0,0 +1,7 @@
+/**
+ * How a backend answered a request exercising something the document declares. Only 400 and
+ * 422 say "this is not supported"; 401, 403, 404 and 429 turn the request away before the
+ * capability is ever consulted, and a 5xx is a crash, not a refusal.
+ */
+export declare function declarationAnswer(status: number): "accepted" | "refused" | "unknown";
+//# sourceMappingURL=declarations.d.ts.map

package/dist/api/runtime/checks/planning/declarations.js

@@ -0,0 +1,11 @@
+/**
+ * How a backend answered a request exercising something the document declares. Only 400 and
+ * 422 say "this is not supported"; 401, 403, 404 and 429 turn the request away before the
+ * capability is ever consulted, and a 5xx is a crash, not a refusal.
+ */
+export function declarationAnswer(status) {
+    if (status > 0 && status < 400)
+        return "accepted";
+    return status === 400 || status === 422 ? "refused" : "unknown";
+}
+//# sourceMappingURL=declarations.js.map

package/dist/api/runtime/checks/planning/refusal.d.ts

@@ -0,0 +1,21 @@
+import type { ReadClient } from "../../../client/client.ts";
+import type { Exchange } from "../../exchange.ts";
+import { type Outcome } from "../../finding.ts";
+import type { CheckContext } from "../core/context.ts";
+/** What a negative probe gets wrong, and so the reason it should be refused for. */
+type RefusalReason = "conflict" | "content-type" | "validation";
+/**
+ * Judges the answer to a request sent to be refused. `null` when it was accepted, which the
+ * caller judges. Only the statuses that mean "refused for this reason" assert the property; a 5xx
+ * is a finding; any other refusal — unauthorized, forbidden, not found, rate limited — turned the
+ * request away before the property was ever consulted, so nothing was learned.
+ */
+export declare function judgeRefusal(ctx: CheckContext, check: string, reasons: readonly RefusalReason[], exchange: Exchange): Outcome | null;
+/**
+ * The context for a request the API tester sends expecting it to be refused. Its exchanges are marked as
+ * probes, so a status the document leaves out for deliberately invalid input is reported apart
+ * from what ordinary traffic got.
+ */
+export declare function asProbe<X extends CheckContext<ReadClient>>(ctx: X): X;
+export {};
+//# sourceMappingURL=refusal.d.ts.map

package/dist/api/runtime/checks/planning/refusal.js

@@ -0,0 +1,39 @@
+import { ASSERTED } from "../../finding.js";
+/** The statuses that mean "refused for this reason", by what a negative probe gets wrong. */
+const REFUSED_FOR = {
+    conflict: [409],
+    "content-type": [415],
+    validation: [400, 422],
+};
+/**
+ * Judges the answer to a request sent to be refused. `null` when it was accepted, which the
+ * caller judges. Only the statuses that mean "refused for this reason" assert the property; a 5xx
+ * is a finding; any other refusal — unauthorized, forbidden, not found, rate limited — turned the
+ * request away before the property was ever consulted, so nothing was learned.
+ */
+export function judgeRefusal(ctx, check, reasons, exchange) {
+    const status = exchange.status;
+    if (status > 0 && status < 400)
+        return null;
+    if (reasons.some((reason) => REFUSED_FOR[reason].includes(status)))
+        return ASSERTED;
+    if (status >= 500) {
+        return ctx.findings.backend(check, ctx.entityName, {
+            summary: "a request that should be refused drew a server error",
+            detail: `${exchange.method} ${exchange.url} returned ${status}; invalid input should be refused with ` +
+                `${reasons.flatMap((reason) => REFUSED_FOR[reason]).join(" or ")}, not crash the handler.`,
+            evidence: [exchange],
+        });
+    }
+    return ctx.findings.unresolved(check, ctx.entityName, `the probe was turned away with ${status}, which does not say the input itself was refused`);
+}
+/**
+ * The context for a request the API tester sends expecting it to be refused. Its exchanges are marked as
+ * probes, so a status the document leaves out for deliberately invalid input is reported apart
+ * from what ordinary traffic got.
+ */
+export function asProbe(ctx) {
+    /* What a probe the server accepts anyway creates is ledgered like any other create. */
+    return { ...ctx, client: ctx.client.view({ purpose: "probe" }) };
+}
+//# sourceMappingURL=refusal.js.map

package/dist/api/runtime/checks/planning/stand-down.d.ts

@@ -0,0 +1,26 @@
+import type { OperationModel } from "../../../spec/graph/types.ts";
+import type { Exchange } from "../../exchange.ts";
+import type { CheckContext } from "../core/context.ts";
+import { type Plan } from "../core/plan.ts";
+/** What a check that predicts stored values from the cohort's fields needs, when the records are what the API tester sent. */
+export declare const STORED_FIELDS_UNKNOWN: string;
+/**
+ * The stand-down for a check that works out from a record's fields what the server must answer —
+ * which records a filter selects, which hold a null — when the records are the bodies the API tester sent
+ * (`recordsUnverified`): a field the server defaulted or normalized would read as a defect.
+ * `undefined` when the records are the server's.
+ */
+export declare function storedFieldsUnknown(ctx: Pick<CheckContext, "recordsUnverified">): Plan<never> | undefined;
+/**
+ * A documented feature-gate 403 is not a 2xx-check failure and not SECURITY.
+ *
+ * The check that needed a success stands down with a named gap. The 403 body is still judged
+ * against the documented error schema, by schema.error-response-matches-document.
+ */
+export declare function standDownForFeatureGate(ctx: CheckContext, op: OperationModel | undefined, exchange: Exchange, check: string): boolean;
+/**
+ * A 429 that survived Client retries is the bucket, not the backend. The check that needed a
+ * 2xx stands down; it is not a defect and it is not a concurrency conclusion.
+ */
+export declare function standDownForRateLimit(ctx: CheckContext, exchange: Exchange, check: string): boolean;
+//# sourceMappingURL=stand-down.d.ts.map

package/dist/api/runtime/checks/planning/stand-down.js

@@ -0,0 +1,47 @@
+import { describeFeatureGate, isDocumentedFeatureGateDenial } from "../../feature-gate.js";
+import { describeExceeded } from "../../rate-limit/retry-after.js";
+import { cannot } from "../core/plan.js";
+/* ------------------------------------------------------------------- helpers */
+/** What a check that predicts stored values from the cohort's fields needs, when the records are what the API tester sent. */
+export const STORED_FIELDS_UNKNOWN = "records read back from the server: the create answered without the record and there was no item read, " +
+    "so the cohort holds only the bodies the API tester sent";
+/**
+ * The stand-down for a check that works out from a record's fields what the server must answer —
+ * which records a filter selects, which hold a null — when the records are the bodies the API tester sent
+ * (`recordsUnverified`): a field the server defaulted or normalized would read as a defect.
+ * `undefined` when the records are the server's.
+ */
+export function storedFieldsUnknown(ctx) {
+    return ctx.recordsUnverified === true ? cannot(STORED_FIELDS_UNKNOWN) : undefined;
+}
+/**
+ * A documented feature-gate 403 is not a 2xx-check failure and not SECURITY.
+ *
+ * The check that needed a success stands down with a named gap. The 403 body is still judged
+ * against the documented error schema, by schema.error-response-matches-document.
+ */
+export function standDownForFeatureGate(ctx, op, exchange, check) {
+    if (op === undefined)
+        return false;
+    if (!isDocumentedFeatureGateDenial(op, exchange.status, exchange.responseBody))
+        return false;
+    /* The 403 body is judged against its schema by schema.error-response-matches-document. */
+    ctx.findings.gap(check, ctx.entityName, {
+        summary: `${op.operationId} did not apply`,
+        detail: `${describeFeatureGate(op, exchange.responseBody)}. The check that needed a 2xx stands ` +
+            "down rather than treat the documented 403 as a defect.",
+    });
+    return true;
+}
+/**
+ * A 429 that survived Client retries is the bucket, not the backend. The check that needed a
+ * 2xx stands down; it is not a defect and it is not a concurrency conclusion.
+ */
+export function standDownForRateLimit(ctx, exchange, check) {
+    if (exchange.status !== 429)
+        return false;
+    const why = exchange.retryAfterExceeded === undefined ? "after retries" : `and ${describeExceeded(exchange.retryAfterExceeded)}`;
+    ctx.findings.unresolved(check, ctx.entityName, `the request was rate-limited (429) ${why}, so this check could not complete`);
+    return true;
+}
+//# sourceMappingURL=stand-down.js.map

package/dist/api/runtime/checks/planning/subjects.d.ts

@@ -0,0 +1,32 @@
+import type { EntityModel, OperationModel, SpecModel } from "../../../spec/graph/types.ts";
+import type { Exchange } from "../../exchange.ts";
+import type { CheckContext } from "../core/context.ts";
+export declare const graded: (ctx: CheckContext, op: OperationModel) => boolean;
+export declare const NO_IDENTITY = "a record that carries its identity";
+export declare const NO_KEY = "\0no-identity";
+export declare const declared: (...operationIds: Array<string | undefined>) => string[];
+export declare const ownOps: (entity: EntityModel, model: SpecModel, keep: (op: OperationModel) => boolean) => string[];
+/** Subject sets shared by the registry. Each reads the same fields the check's context is built from. */
+export declare const subjectsOf: {
+    async: (entity: EntityModel, model: SpecModel) => string[];
+    asyncReceipt: (entity: EntityModel, model: SpecModel) => string[];
+    create: (entity: EntityModel) => string[];
+    createAndForeignReads: (entity: EntityModel, model: SpecModel) => string[];
+    createAndList: (entity: EntityModel) => string[];
+    delete: (entity: EntityModel) => string[];
+    deleteAndList: (entity: EntityModel) => string[];
+    effects: (entity: EntityModel, model: SpecModel) => string[];
+    invite: (entity: EntityModel) => string[];
+    list: (entity: EntityModel) => string[];
+    nonCreate: (entity: EntityModel, model: SpecModel) => string[];
+    read: (entity: EntityModel) => string[];
+    readAndGated: (entity: EntityModel, model: SpecModel) => string[];
+    readAndList: (entity: EntityModel) => string[];
+    update: (entity: EntityModel) => string[];
+    waits: (entity: EntityModel, model: SpecModel) => string[];
+    writeAndRead: (entity: EntityModel) => string[];
+};
+export declare function itemParamFor(ctx: CheckContext, id: string): Record<string, string>;
+/** Document first, then the live `Content-Type`. Media type is the stream tag — not `x-async`. */
+export declare function isEventStream(exchange: Exchange, op?: OperationModel): boolean;
+//# sourceMappingURL=subjects.d.ts.map

package/dist/api/runtime/checks/planning/subjects.js

@@ -0,0 +1,51 @@
+export const graded = (ctx, op) => ctx.inScope?.(op) ?? true;
+/* A record that does not carry its identity names nothing a request could address. */
+export const NO_IDENTITY = "a record that carries its identity";
+/* Matches no id: what a record without an identity is looked up as. */
+export const NO_KEY = "\u0000no-identity";
+export const declared = (...operationIds) => operationIds.filter((id) => id !== undefined && id !== "");
+export const ownOps = (entity, model, keep) => model.operations.filter((op) => op.entity === entity.name && keep(op)).map((op) => op.operationId);
+/** Subject sets shared by the registry. Each reads the same fields the check's context is built from. */
+export const subjectsOf = {
+    async: (entity, model) => ownOps(entity, model, (op) => op.async !== null),
+    asyncReceipt: (entity, model) => ownOps(entity, model, (op) => op.async?.idFrom !== undefined),
+    create: (entity) => declared(entity.create),
+    createAndForeignReads: (entity, model) => {
+        const create = model.byOperationId.get(entity.create ?? "");
+        if (create === undefined)
+            return [];
+        const foreign = create.invalidates
+            .map((route) => model.byRoute.get(route))
+            .filter((op) => op !== undefined && op.entity !== entity.name && op.method.toUpperCase() === "GET")
+            .map((op) => op.operationId);
+        return [create.operationId, ...foreign];
+    },
+    createAndList: (entity) => declared(entity.create, entity.list),
+    delete: (entity) => declared(entity.delete),
+    deleteAndList: (entity) => declared(entity.delete, entity.list),
+    effects: (entity, model) => ownOps(entity, model, (op) => op.effects.length > 0),
+    invite: (entity) => entity.invite === null ? [] : declared(entity.invite.invite, entity.invite.accept, entity.invite.revoke),
+    list: (entity) => declared(entity.list),
+    nonCreate: (entity, model) => ownOps(entity, model, (op) => op.action !== "create"),
+    read: (entity) => declared(entity.read),
+    readAndGated: (entity, model) => [
+        ...new Set([...declared(entity.read), ...ownOps(entity, model, (op) => op.featureGate !== null)]),
+    ],
+    readAndList: (entity) => declared(entity.read, entity.list),
+    update: (entity) => declared(entity.update),
+    waits: (entity, model) => ownOps(entity, model, (op) => op.wait !== null),
+    writeAndRead: (entity) => declared(entity.update ?? entity.create, entity.read),
+};
+export function itemParamFor(ctx, id) {
+    const op = ctx.readOp ?? ctx.updateOp ?? ctx.deleteOp;
+    const param = op?.pathParams.at(-1);
+    return param === undefined ? {} : { [param]: id };
+}
+/** Document first, then the live `Content-Type`. Media type is the stream tag — not `x-async`. */
+export function isEventStream(exchange, op) {
+    if (op?.eventStream === true)
+        return true;
+    const type = exchange.responseHeaders["content-type"] ?? "";
+    return type.includes("text/event-stream");
+}
+//# sourceMappingURL=subjects.js.map

package/dist/api/runtime/checks/query/capabilities.d.ts

@@ -0,0 +1,66 @@
+import type { QueryConventions } from "../../../spec/conventions/types.ts";
+import type { EffectiveFilterField, EffectiveQueryCapabilities } from "../../../spec/query/effective.ts";
+import { FILTER_OPS } from "../../../spec/query/ops.ts";
+import type { SortValue } from "../../../spec/render/sort.ts";
+import type { RequestOptions } from "../../../client/types.ts";
+import type { CheckContext, Listed } from "../core/context.ts";
+/** The list endpoint's derived conventions — parameter roles and envelope spellings. */
+export declare function conv(ctx: Listed): QueryConventions;
+/** Query parameters as the client sends them; an array value repeats its parameter. */
+export type Query = NonNullable<RequestOptions["query"]>;
+/**
+ * Builds a query using whatever this endpoint actually calls each role.
+ *
+ * `{ limit: 2, page: 1 }` becomes `?per_page=2&page_number=1` where that is how the document
+ * spells them, so a check written once works against an API that shares no parameter names with
+ * the fixture.
+ */
+export declare function q(ctx: Listed, roles: QueryRoles): Query;
+/** The roles a check asks for, by what they mean rather than what this endpoint calls them. */
+export interface QueryRoles {
+    limit?: number | undefined;
+    page?: number | undefined;
+    cursor?: string | undefined;
+    order?: SortValue | undefined;
+    search?: string | undefined;
+    searchMode?: string | undefined;
+    filter?: string | undefined;
+}
+/** The largest page this endpoint documents — see `documentedPage`. */
+export declare function pageSize(ctx: Listed): number;
+/**
+ * Whether an equality predicate can be expressed against this endpoint at all.
+ *
+ * Not "is there a `filter` parameter": the most common shape in the wild has no such parameter and
+ * instead accepts one query parameter per field — `?status=active`. Gating on the parameter meant
+ * every filter check silently skipped itself against those APIs, which is the same failure as a
+ * check that cannot express a request being mistaken for a backend that ignores one.
+ *
+ * Checks needing an operator the grammar cannot write — a negation under equality-only filtering —
+ * still stand down individually, because `filterTerm` returns null for them and there is genuinely
+ * no request to send.
+ */
+export declare function filterable(ctx: Listed): boolean;
+export declare function resolvedCaps(ctx: Listed): EffectiveQueryCapabilities;
+export declare function filterableNames(ctx: Listed): string[];
+/** Filter field for identity predicates when it differs from the JSON identity. */
+export declare function filterIdentity(ctx: Listed): string;
+export declare function identityIsFilterable(ctx: Listed): boolean;
+export declare function canUseOp(ctx: Listed, field: EffectiveFilterField, op: (typeof FILTER_OPS)[number]): boolean;
+/**
+ * Whether the endpoint can be walked forward at all, however it counts.
+ *
+ * Page numbers and row offsets are two ways of expressing the same request, and every paging
+ * property — that walking forward covers the set without gaps or repeats, that a more-pages
+ * signal is honest — holds identically under both. Gating those checks on a *page* parameter
+ * meant an offset-paged API silently skipped them, which reads exactly like a clean result.
+ */
+export declare function pageable(ctx: Listed): boolean;
+export declare const MOVING_COLLECTION: string;
+export declare const REREAD_REFUSED: string;
+export declare const MOVING: string;
+export declare function asTermValue(value: unknown): string | number;
+export declare const FOUNDATIONS: readonly ["list.read-after-write", "create.persists-submitted-fields", "pagination.page-walk-covers-set"];
+/** The JSON type the item schema gives a property, looking through a nullable union. */
+export declare function schemaType(ctx: CheckContext, field: string): string | undefined;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/api/runtime/checks/query/capabilities.js

@@ -0,0 +1,169 @@
+import { canWriteFilterOp, filterSpec } from "../../../spec/conventions/filter.js";
+import { documentedPage } from "../../../spec/graph/paging.js";
+import { fieldAllows } from "../../../spec/query/field-ops.js";
+import { mergeQueryCapabilities } from "../../../spec/query/merge.js";
+import { FILTER_OPS } from "../../../spec/query/ops.js";
+import { itemSchemaOf } from "../payloads/item-schema.js";
+/** The list endpoint's derived conventions — parameter roles and envelope spellings. */
+export function conv(ctx) {
+    return ctx.listOp.conventions;
+}
+/**
+ * Builds a query using whatever this endpoint actually calls each role.
+ *
+ * `{ limit: 2, page: 1 }` becomes `?per_page=2&page_number=1` where that is how the document
+ * spells them, so a check written once works against an API that shares no parameter names with
+ * the fixture.
+ */
+export function q(ctx, roles) {
+    const c = conv(ctx);
+    const out = {};
+    /* Never above the documented maximum: a backend is right to refuse a request that breaks the
+     * contract, and reading that refusal as anything about the backend would be the API tester's own fault.
+     * The one check that probes past the cap on purpose sets the parameter itself. */
+    const size = roles.limit === undefined ? undefined : Math.min(roles.limit, pageSize(ctx));
+    if (size !== undefined && c.limit !== undefined)
+        out[c.limit] = size;
+    placePage(out, c, { page: roles.page, size });
+    for (const role of NAMED_ROLES) {
+        const name = c[role];
+        const value = roles[role];
+        if (value !== undefined && name !== undefined)
+            out[name] = value;
+    }
+    return out;
+}
+/* The roles written as given under the endpoint's own name for each, in this order. */
+const NAMED_ROLES = ["cursor", "order", "search", "searchMode", "filter"];
+/** Writes the page number, or the offset it stands for where the endpoint skips rows instead. */
+function placePage(out, c, { page, size }) {
+    if (page === undefined)
+        return;
+    if (c.page !== undefined)
+        out[c.page] = page;
+    else if (c.offset !== undefined) {
+        /*
+         * Offset paging expressed from a page number.
+         *
+         * Some APIs count pages, some count rows skipped; the *property* every paging check is
+         * asserting — that walking forward covers the set without gaps or repeats — is identical
+         * either way. Translating here means a check says "page 3" once and works against both.
+         * Without it a page-numbered request against an offset API silently omits the parameter
+         * and every page comes back as the first one, which reads as a backend that ignores
+         * pagination rather than a tool that cannot express it.
+         */
+        /* A page size must be assumed when the caller did not state one; 20 is the common default
+         * and any consistent value keeps the walk's arithmetic self-consistent, which is what the
+         * property depends on. */
+        out[c.offset] = Math.max(page - 1, 0) * (size ?? 20);
+    }
+}
+/** The largest page this endpoint documents — see `documentedPage`. */
+export function pageSize(ctx) {
+    return documentedPage(ctx.model, ctx.listOp).size;
+}
+/**
+ * Whether an equality predicate can be expressed against this endpoint at all.
+ *
+ * Not "is there a `filter` parameter": the most common shape in the wild has no such parameter and
+ * instead accepts one query parameter per field — `?status=active`. Gating on the parameter meant
+ * every filter check silently skipped itself against those APIs, which is the same failure as a
+ * check that cannot express a request being mistaken for a backend that ignores one.
+ *
+ * Checks needing an operator the grammar cannot write — a negation under equality-only filtering —
+ * still stand down individually, because `filterTerm` returns null for them and there is genuinely
+ * no request to send.
+ */
+export function filterable(ctx) {
+    const c = conv(ctx);
+    if (c.filter !== undefined)
+        return true;
+    /* Equality-per-field needs a field to attach the predicate to, and the document has to say
+     * which fields are filterable — otherwise the API tester would be guessing at parameter names. */
+    return filterSpec(c).param === "field" && (ctx.query?.filterable.length ?? 0) > 0;
+}
+export function resolvedCaps(ctx) {
+    if (ctx.capabilities !== undefined)
+        return ctx.capabilities;
+    return mergeQueryCapabilities({
+        itemSchema: ctx.listOp.collection?.itemSchema ?? null,
+        tag: ctx.query === null
+            ? null
+            : {
+                filterable: ctx.query.filterable,
+                searchable: ctx.query.searchable,
+                selectable: ctx.query.selectable,
+                sortable: ctx.query.sortable,
+                source: ctx.query.source,
+                ...(ctx.query.filterableDeclared === undefined ? {} : { filterableDeclared: ctx.query.filterableDeclared }),
+                ...(ctx.query.sortableDeclared === undefined ? {} : { sortableDeclared: ctx.query.sortableDeclared }),
+                ...(ctx.query.searchableDeclared === undefined ? {} : { searchableDeclared: ctx.query.searchableDeclared }),
+                ...(ctx.query.selectableDeclared === undefined ? {} : { selectableDeclared: ctx.query.selectableDeclared }),
+                ...(ctx.query.filterFields === undefined ? {} : { filterFields: ctx.query.filterFields }),
+                ...(ctx.query.sortableFields === undefined ? {} : { sortableFields: ctx.query.sortableFields }),
+                ...(ctx.query.catalog === undefined ? {} : { catalog: ctx.query.catalog }),
+                ...(ctx.query.defaultOrder === undefined ? {} : { defaultOrder: ctx.query.defaultOrder }),
+                ...(ctx.query.stableTiebreak === undefined ? {} : { stableTiebreak: ctx.query.stableTiebreak }),
+            },
+    });
+}
+export function filterableNames(ctx) {
+    return resolvedCaps(ctx).filterable.map((field) => field.field);
+}
+/** Filter field for identity predicates when it differs from the JSON identity. */
+export function filterIdentity(ctx) {
+    return resolvedCaps(ctx).identityFilter ?? ctx.identity;
+}
+export function identityIsFilterable(ctx) {
+    const names = filterableNames(ctx);
+    return names.includes(filterIdentity(ctx)) || names.includes(ctx.identity);
+}
+export function canUseOp(ctx, field, op) {
+    return canWriteFilterOp(conv(ctx), op) && fieldAllows(field, op, resolvedCaps(ctx));
+}
+/**
+ * Whether the endpoint can be walked forward at all, however it counts.
+ *
+ * Page numbers and row offsets are two ways of expressing the same request, and every paging
+ * property — that walking forward covers the set without gaps or repeats, that a more-pages
+ * signal is honest — holds identically under both. Gating those checks on a *page* parameter
+ * meant an offset-paged API silently skipped them, which reads exactly like a clean result.
+ */
+export function pageable(ctx) {
+    const c = conv(ctx);
+    return c.page !== undefined || c.offset !== undefined;
+}
+export const MOVING_COLLECTION = "the collection gained or lost rows between the term reads and the combined read (something wrote " +
+    "to it while the check ran), so the reads cannot be compared";
+export const REREAD_REFUSED = "the reads disagreed, and reading them again to rule out another writer was refused, so the " +
+    "disagreement cannot be pinned on the backend";
+export const MOVING = "the collection gained or lost rows between two reads in the same direction (something wrote to it " +
+    "while the check ran), so the reads cannot be compared";
+export function asTermValue(value) {
+    return typeof value === "number" ? value : String(value);
+}
+export const FOUNDATIONS = [
+    "list.read-after-write",
+    "create.persists-submitted-fields",
+    "pagination.page-walk-covers-set",
+];
+/** The JSON type the item schema gives a property, looking through a nullable union. */
+export function schemaType(ctx, field) {
+    const properties = (itemSchemaOf(ctx)?.properties ?? {});
+    const propertySchema = properties[field];
+    if (propertySchema === undefined)
+        return undefined;
+    const branches = [propertySchema, ...(propertySchema.oneOf ?? propertySchema.anyOf ?? [])];
+    for (const branch of branches) {
+        const type = branch.type;
+        if (typeof type === "string" && type !== "null")
+            return type;
+        if (Array.isArray(type)) {
+            const named = type.find((item) => item !== "null");
+            if (typeof named === "string")
+                return named;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/api/runtime/checks/query/order.d.ts

@@ -0,0 +1,56 @@
+import type { CheckContext, Listed } from "../core/context.ts";
+import { type ListResult } from "../sets/list.ts";
+import { type Query } from "./capabilities.ts";
+/**
+ * A sortable field whose values repeat across the cohort. Ties are what expose an unstable sort:
+ * with distinct keys every implementation looks correct, because there is only one valid order.
+ */
+export declare function tiedSortField(ctx: Listed): string | null;
+/**
+ * A field that is null on some seeded records and populated on others.
+ *
+ * Null handling is where query engines break — SQL's three-valued logic means `col <> x` is NULL
+ * rather than true for null rows, so they silently vanish from negated predicates, and
+ * nullsfirst/nullslast is easy to get backwards. A check that only ever probes the identity
+ * column, which is never null, cannot see any of it.
+ */
+export declare function nullableField(ctx: Listed, candidates: readonly string[]): string | null;
+/** Null on some cohort records and set on others. */
+export declare function holdsSomeNulls(ctx: CheckContext, field: string): boolean;
+/** Numbers numerically, everything else by its text — the one ordering every collation shares on ids. */
+export declare function compareScalars(a: unknown, b: unknown): number;
+/**
+ * The ways a backend may order text. The API tester cannot know a backend's collation, so an order is
+ * judged sorted when it is sorted under one of these — and, once the backend has shown which,
+ * under that one from then on.
+ */
+declare const TEXT_ORDERS: {
+    readonly binary: (a: string, b: string) => number;
+    readonly folded: (a: string, b: string) => number;
+    readonly locale: (a: string, b: string) => number;
+};
+type TextOrder = keyof typeof TEXT_ORDERS;
+/**
+ * The text order under which `values` — one sort field, in the order the backend returned them,
+ * ascending — are sorted, or `null` when they are sorted under none.
+ *
+ * Collation-independent by construction: numbers must ascend numerically whatever the text
+ * order, nulls must sit together at one end, and ties may come in any order. Text is held to the
+ * order the backend already showed for this field when there is one, else to any of them.
+ */
+export declare function sortedUnder(ctx: Listed, field: string, values: readonly unknown[]): TextOrder | null;
+/** Records how the backend ordered `field`, so later checks hold it to the same order. */
+export declare function observeTextOrder(ctx: CheckContext, field: string, text: TextOrder, values: readonly unknown[]): void;
+/**
+ * Whether an order that came back ascending was ignored: `query` sent again ordered descending holds
+ * the same sequence of `field` values, more than one of them distinct. An ignored order can come back
+ * ascending by accident (a server's own tiebreak on this very field does it), but not ascending and
+ * descending at once. The descending read when the order was ignored, else null.
+ */
+export declare function orderIgnored(ctx: Listed, { ascending, field, query }: {
+    ascending: readonly unknown[];
+    field: string;
+    query: Query;
+}): Promise<ListResult | null>;
+export {};
+//# sourceMappingURL=order.d.ts.map