@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,145 @@
+import { memoTable } from "../sets/read.js";
+import { sortTerm } from "../../../spec/conventions/sort.js";
+import { list } from "../sets/list.js";
+import { conv, q, resolvedCaps } from "./capabilities.js";
+/**
+ * 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 function tiedSortField(ctx) {
+    for (const field of ctx.query?.sortable ?? []) {
+        if (field === ctx.identity)
+            continue;
+        const values = ctx.records.map((r) => JSON.stringify(r[field]));
+        if (new Set(values).size < values.length)
+            return field;
+    }
+    return 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 function nullableField(ctx, candidates) {
+    return candidates.find((field) => field !== ctx.identity && holdsSomeNulls(ctx, field)) ?? null;
+}
+/** Null on some cohort records and set on others. */
+export function holdsSomeNulls(ctx, field) {
+    const nulls = ctx.records.filter((row) => row[field] === null || row[field] === undefined).length;
+    return nulls > 0 && nulls < ctx.records.length;
+}
+/** Numbers numerically, everything else by its text — the one ordering every collation shares on ids. */
+export function compareScalars(a, b) {
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    const as = String(a);
+    const bs = String(b);
+    return as < bs ? -1 : as > bs ? 1 : 0;
+}
+/**
+ * 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.
+ */
+const TEXT_ORDERS = {
+    binary: (a, b) => (a < b ? -1 : a > b ? 1 : 0),
+    folded: (a, b) => {
+        const x = a.toLowerCase();
+        const y = b.toLowerCase();
+        return x < y ? -1 : x > y ? 1 : 0;
+    },
+    locale: (a, b) => a.localeCompare(b),
+};
+const DECLARED_TEXT_ORDER = { binary: "binary", "case-insensitive": "folded", locale: "locale" };
+const isNull = (value) => value === null || value === undefined;
+/**
+ * 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 function sortedUnder(ctx, field, values) {
+    const present = values.filter((value) => !isNull(value));
+    const { candidates, known } = orderInForce(ctx, field);
+    if (!nullsPlaced(values, present.length, known?.nulls))
+        return null;
+    return candidates.find((order) => ascendingUnder(present, order)) ?? null;
+}
+/**
+ * What is known of how `field` is ordered — declared by the document, else shown by the backend —
+ * and the text orders an order may still be judged under.
+ */
+function orderInForce(ctx, field) {
+    const sortCaps = resolvedCaps(ctx).sort;
+    const observed = memoTable(ctx.memo.entity, "textOrders").get(field);
+    const known = sortCaps?.collation === undefined && sortCaps?.defaultNulls === undefined
+        ? observed
+        : {
+            text: sortCaps.collation === undefined ? (observed?.text ?? "binary") : DECLARED_TEXT_ORDER[sortCaps.collation],
+            ...(sortCaps.defaultNulls === undefined ? {} : { nulls: sortCaps.defaultNulls }),
+        };
+    const candidates = known === undefined || (sortCaps?.collation === undefined && observed === undefined)
+        ? ["binary", "folded", "locale"]
+        : [known.text];
+    return known === undefined ? { candidates } : { candidates, known };
+}
+/** Nulls together at one end — and the same end every time once one has been seen. */
+function nullsPlaced(values, present, end) {
+    const nulls = values.length - present;
+    if (nulls === 0 || present === 0)
+        return true;
+    const first = values.slice(0, nulls).every(isNull);
+    const last = values.slice(present).every(isNull);
+    if (!first && !last)
+        return false;
+    if (end === "first" && !first)
+        return false;
+    return end !== "last" || last;
+}
+/** Whether `present` ascends under `order`: numbers numerically, text under that order, ties either way. */
+function ascendingUnder(present, order) {
+    const text = TEXT_ORDERS[order];
+    return present.every((value, index) => {
+        if (index === 0)
+            return true;
+        const prior = present[index - 1];
+        if (typeof prior === "number" && typeof value === "number")
+            return prior <= value;
+        return text(String(prior), String(value)) <= 0;
+    });
+}
+/** Records how the backend ordered `field`, so later checks hold it to the same order. */
+export function observeTextOrder(ctx, field, text, values) {
+    const orders = memoTable(ctx.memo.entity, "textOrders");
+    if (orders.has(field))
+        return;
+    const nulls = values.some(isNull) && values.some((value) => !isNull(value))
+        ? isNull(values[0])
+            ? "first"
+            : "last"
+        : undefined;
+    orders.set(field, nulls === undefined ? { text } : { nulls, text });
+}
+/**
+ * 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 async function orderIgnored(ctx, { ascending, field, query }) {
+    const descending = await list(ctx, {
+        ...query,
+        ...q(ctx, { order: sortTerm(conv(ctx), { direction: "desc", field }) }),
+    });
+    const reversed = descending.items.map((item) => item[field]);
+    const distinct = new Set(ascending.map((value) => JSON.stringify(value))).size;
+    const same = JSON.stringify(reversed) === JSON.stringify(ascending);
+    return descending.exchange.status < 400 && distinct > 1 && same ? descending : null;
+}
+//# sourceMappingURL=order.js.map

package/dist/api/runtime/checks/registry.d.ts

@@ -0,0 +1,3 @@
+import type { RegisteredCheck } from "./core/check.ts";
+export declare const CHECKS: readonly RegisteredCheck[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/api/runtime/checks/registry.js

@@ -0,0 +1,289 @@
+import { contractCallCheck } from "../contract/check.js";
+import { disposableCheck } from "../disposable/check.js";
+import { publicGetCheck } from "../one-shot.js";
+import { rootReadCheck } from "../root-read.js";
+import { selfIdentityCheck } from "../self/check.js";
+import { serverErrorCheck } from "../server-errors.js";
+import { queryAxesCompose } from "./families/composition/query-axes-compose.js";
+import { filterAndSelectCompose } from "./families/composition/query-filter-and-select-compose.js";
+import { filterSearchSelectCompose } from "./families/composition/query-filter-search-select-compose.js";
+import { filterSearchSortCompose } from "./families/composition/query-filter-search-sort-compose.js";
+import { queryFilterSearchSortSelectCompose } from "./families/composition/query-filter-search-sort-select-compose.js";
+import { filterAndPagingCompose } from "./families/composition/query-filter-selects-from-whole-set.js";
+import { filterSortSelectCompose } from "./families/composition/query-filter-sort-select-compose.js";
+import { searchAndFilterCompose } from "./families/composition/query-search-and-filter-compose.js";
+import { querySearchAndSelectCompose } from "./families/composition/query-search-and-select-compose.js";
+import { querySearchAndSortCompose } from "./families/composition/query-search-and-sort-compose.js";
+import { querySortAndSelectCompose } from "./families/composition/query-sort-and-select-compose.js";
+import { unknownParameterConsistent } from "./families/composition/query-unknown-parameter-consistent.js";
+import { documentedStatusHonored } from "./families/conformance/response-status-is-documented.js";
+import { errorSchemaHonored } from "./families/conformance/schema-error-response-matches-document.js";
+import { problemJsonShape } from "./families/conformance/schema-problem-json-shape.js";
+import { readSchemaHonored } from "./families/conformance/schema-read-response-matches-document.js";
+import { writeOnlyNotReturned } from "./families/conformance/response-write-only-not-returned.js";
+import { successSchemaHonored } from "./families/conformance/schema-success-response-matches-document.js";
+import { projectionsAgree } from "./families/consistency/consistency-projections-agree.js";
+import { declaredInvalidationHappens } from "./families/consistency/invalidation-declared-route-changes.js";
+import { listedRowIsTheGet } from "./families/consistency/list-item-matches-listed-row.js";
+import { bypassIsFresh } from "./families/consistency/bypass-is-fresh.js";
+import { readAfterWrite } from "./families/consistency/list-read-after-write.js";
+import { stalenessWithinBound } from "./families/consistency/staleness-within-bound.js";
+import { asyncReachesTerminalState } from "./families/effects-async/async-reaches-terminal-state.js";
+import { asyncReceiptIsResolvable } from "./families/effects-async/async-receipt-identifies-the-job.js";
+import { declaredEffectsOccur } from "./families/effects-async/effects-declared-effect-occurs.js";
+import { sideEffectArrives } from "./families/effects-async/effects-side-effect-arrives.js";
+import { malformedFilterNot5xx } from "./families/filter/error-malformed-filter-not-5xx.js";
+import { filterAliasMatchesCanonical } from "./families/filter/filter-alias-matches-canonical.js";
+import { filterAndComposesAsIntersection } from "./families/filter/filter-and-composes-as-intersection.js";
+import { filterConditionCapRejected } from "./families/filter/filter-condition-cap-rejected.js";
+import { filterContainsMembership } from "./families/filter/filter-contains-membership.js";
+import { filterEmptyIn } from "./families/filter/filter-empty-in.js";
+import { equalityFilterSelectsOne } from "./families/filter/filter-equality-selects-exactly-one.js";
+import { filterGteIsGtOrEq } from "./families/filter/filter-gte-is-gt-or-eq.js";
+import { filterIlikeIsCaseInsensitive } from "./families/filter/filter-ilike-is-case-insensitive.js";
+import { filterIllegalOpRejected } from "./families/filter/filter-illegal-op-rejected.js";
+import { filterInIsUnionOfEq } from "./families/filter/filter-in-is-union-of-eq.js";
+import { filterInOverLimitRejected } from "./families/filter/filter-in-over-limit-rejected.js";
+import { filterIsNullSelectsNulls } from "./families/filter/filter-is-null-selects-nulls.js";
+import { likeEscaping } from "./families/filter/filter-like-metacharacters-escaped.js";
+import { filterLteIsLtOrEq } from "./families/filter/filter-lte-is-lt-or-eq.js";
+import { filterMalformedTermRejected } from "./families/filter/filter-malformed-term-rejected.js";
+import { negationPartitions } from "./families/filter/filter-negation-partitions-the-set.js";
+import { filterNestedAndOrDistributes } from "./families/filter/filter-nested-and-or-distributes.js";
+import { filterNinComplementsIn } from "./families/filter/filter-nin-complements-in.js";
+import { numericComparisonIsNumeric } from "./families/filter/filter-numeric-comparison-is-numeric.js";
+import { filterOrComposesAsUnion } from "./families/filter/filter-or-composes-as-union.js";
+import { filterOrderedTriplePartitions } from "./families/filter/filter-ordered-triple-partitions.js";
+import { unknownFilterRejected } from "./families/filter/filter-unknown-field-rejected.js";
+import { zeroMatchFilter } from "./families/filter/filter-zero-match-returns-none.js";
+import { alternativeAccepted } from "./families/security/auth-alternative-accepted.js";
+import { anonymousOperationOpen } from "./families/security/auth-anonymous-operation-open.js";
+import { crossTenantKeyRefused } from "./families/security/auth-cross-tenant-key-refused.js";
+import { invalidCredentialRefused } from "./families/security/auth-invalid-credential-refused.js";
+import { loginThrottled } from "./families/security/auth-login-throttled.js";
+import { missingCredentialRefused } from "./families/security/auth-missing-credential-refused.js";
+import { privilegedFieldIgnored } from "./families/security/auth-privileged-field-ignored.js";
+import { refreshReuseRefused } from "./families/security/auth-refresh-reuse-refused.js";
+import { revokedCredentialRefused } from "./families/security/auth-revoked-credential-refused.js";
+import { roleEnforced } from "./families/security/auth-role-enforced.js";
+import { scopeEnforced } from "./families/security/auth-scope-enforced.js";
+import { wrongSchemeRefused } from "./families/security/auth-wrong-scheme-refused.js";
+import { inviteGrantsThenRevokes } from "./families/isolation/auth-invite-grants-then-revokes.js";
+import { rankIsMonotonicOnWrites } from "./families/isolation/auth-rank-is-monotonic-on-writes.js";
+import { rankIsMonotonic } from "./families/isolation/auth-rank-is-monotonic.js";
+import { denialDoesNotRevealExistence } from "./families/isolation/tenant-denial-does-not-reveal-existence.js";
+import { crossTenantFilterBypass } from "./families/isolation/tenant-filter-does-not-bypass-scope.js";
+import { crossTenantItemRead } from "./families/isolation/tenant-item-not-readable-cross-tenant.js";
+import { crossTenantItemWrite } from "./families/isolation/tenant-item-not-writable-cross-tenant.js";
+import { foreignParentRejected } from "./families/isolation/tenant-parent-not-reachable-from-another-root.js";
+import { countIsConsistentWithPage } from "./families/pagination/count-consistent-with-returned-page.js";
+import { countMatchesWalk } from "./families/pagination/count-matches-filtered-set.js";
+import { paginationBoundsHandled } from "./families/pagination/pagination-bounds-handled.js";
+import { cursorAgreesWithPage } from "./families/pagination/pagination-cursor-agrees-with-page.js";
+import { hasMoreIsAccurate } from "./families/pagination/pagination-has-more-is-accurate.js";
+import { limitBoundsEnforced } from "./families/pagination/pagination-limit-bounds-enforced.js";
+import { limitBoundsPageSize } from "./families/pagination/pagination-limit-bounds-page-size.js";
+import { limitRespectsMax } from "./families/pagination/pagination-limit-respects-documented-max.js";
+import { pageWalkCoversSet } from "./families/pagination/pagination-page-walk-covers-set.js";
+import { searchCaseInsensitive } from "./families/search-select/search-case-insensitive.js";
+import { searchEmptyQ } from "./families/search-select/search-empty-q.js";
+import { searchModeAccepted } from "./families/search-select/search-mode-accepted.js";
+import { searchNarrowsResult } from "./families/search-select/search-q-narrows-result.js";
+import { searchTokensAnd } from "./families/search-select/search-tokens-and.js";
+import { selectNestedHonored } from "./families/search-select/select-nested-honored.js";
+import { selectProjection } from "./families/search-select/select-projection-honored.js";
+import { selectRequestedFieldsPresent } from "./families/search-select/select-requested-fields-present.js";
+import { selectUnknownFieldRejected } from "./families/search-select/select-unknown-field-rejected.js";
+import { sortDefaultOrderApplied } from "./families/sort/sort-default-order-applied.js";
+import { sortInvalidDirectionRejected } from "./families/sort/sort-invalid-direction-rejected.js";
+import { sortMultiKeyTiebreak } from "./families/sort/sort-multi-key-tiebreak.js";
+import { sortNullsFirstLast } from "./families/sort/sort-nulls-first-last.js";
+import { sortNumericOrderIsNumeric } from "./families/sort/sort-numeric-order-is-numeric.js";
+import { orderChangesResult } from "./families/sort/sort-order-is-applied.js";
+import { sortReverseSymmetry } from "./families/sort/sort-reverse-symmetry.js";
+import { sortStableTiebreak } from "./families/sort/sort-stable-tiebreak.js";
+import { sortUnknownFieldRejected } from "./families/sort/sort-unknown-field-rejected.js";
+import { declaredFilterableWorks } from "./families/spec-declarations/spec-declared-filterable-is-filterable.js";
+import { declaredFilterableOpsAccepted } from "./families/spec-declarations/spec-declared-filterable-ops-accepted.js";
+import { declaredRateLimitHonored } from "./families/spec-declarations/spec-declared-rate-limit-is-honored.js";
+import { declaredSelectableWorks } from "./families/spec-declarations/spec-declared-selectable-is-selectable.js";
+import { declaredSortableWorks } from "./families/spec-declarations/spec-declared-sortable-is-sortable.js";
+import { declaredSortableNullsAccepted } from "./families/spec-declarations/spec-declared-sortable-nulls-accepted.js";
+import { invalidBodyRefused } from "./families/validation/request-invalid-body-refused.js";
+import { contentTypeEnforced } from "./families/validation/validation-content-type-enforced.js";
+import { enumValidated } from "./families/validation/validation-enum-enforced.js";
+import { maxLengthValidated } from "./families/validation/validation-max-length-enforced.js";
+import { requiredValidated } from "./families/validation/validation-required-enforced.js";
+import { ifMatchEnforced } from "./families/write/concurrency-if-match-enforced.js";
+import { noLostUpdate } from "./families/write/concurrency-no-lost-update.js";
+import { createKeepsSubmittedIdentity } from "./families/write/create-keeps-submitted-identity.js";
+import { createPersistsFields } from "./families/write/create-persists-submitted-fields.js";
+import { createStatusMatchesSpec } from "./families/write/create-status-matches-document.js";
+import { uniqueConflictCreate } from "./families/write/create-unique-conflict-rejected.js";
+import { deleteMissingIs404 } from "./families/write/delete-absent-record-returns-404.js";
+import { idempotentReplay } from "./families/write/idempotency-replay-does-not-duplicate.js";
+import { immutableRejected } from "./families/write/patch-immutable-field-rejected.js";
+import { patchMinimality } from "./families/write/patch-minimality.js";
+import { stringPayloadSurvives } from "./families/write/payload-string-survives.js";
+import { softDeleteHidden } from "./families/write/softdelete-absent-from-default-list.js";
+import { updatePersistsFields } from "./families/write/update-persists-submitted-fields.js";
+import { uniqueConflictUpdate } from "./families/write/update-unique-conflict-rejected.js";
+export const CHECKS = [
+    /* foundations — did the write land, is it visible, and do the paging primitives work at all.
+     * Everything below assumes these hold, so they must be evaluated first for cascade
+     * suppression to have anything to consult. */
+    createKeepsSubmittedIdentity,
+    readAfterWrite,
+    listedRowIsTheGet,
+    createPersistsFields,
+    createStatusMatchesSpec,
+    successSchemaHonored,
+    limitBoundsPageSize,
+    limitRespectsMax,
+    hasMoreIsAccurate,
+    /* Ordering and the page walk are foundations too, not query niceties: the set-algebra checks
+     * below gather their sets *across pages*, so a broken walk would corrupt the very sets they
+     * compare. Establishing paging first is what lets those failures be suppressed as cascades
+     * rather than re-reported once per predicate. */
+    orderChangesResult,
+    pageWalkCoversSet,
+    cursorAgreesWithPage,
+    /* Where the filter is applied relative to paging: every filtered read below relies on it. */
+    filterAndPagingCompose,
+    paginationBoundsHandled,
+    sortNumericOrderIsNumeric,
+    sortStableTiebreak,
+    /* These read whole sets in both directions, so they come after the walk they rely on. */
+    sortReverseSymmetry,
+    sortNullsFirstLast,
+    sortMultiKeyTiebreak,
+    sortDefaultOrderApplied,
+    /* query semantics */
+    unknownFilterRejected,
+    malformedFilterNot5xx,
+    sortUnknownFieldRejected,
+    sortInvalidDirectionRejected,
+    equalityFilterSelectsOne,
+    zeroMatchFilter,
+    negationPartitions,
+    filterAndComposesAsIntersection,
+    filterOrComposesAsUnion,
+    filterInIsUnionOfEq,
+    filterNinComplementsIn,
+    filterNestedAndOrDistributes,
+    likeEscaping,
+    filterIlikeIsCaseInsensitive,
+    filterIsNullSelectsNulls,
+    filterContainsMembership,
+    searchNarrowsResult,
+    searchTokensAnd,
+    searchCaseInsensitive,
+    searchEmptyQ,
+    searchModeAccepted,
+    selectProjection,
+    selectRequestedFieldsPresent,
+    selectUnknownFieldRejected,
+    unknownParameterConsistent,
+    selectNestedHonored,
+    countIsConsistentWithPage,
+    countMatchesWalk,
+    numericComparisonIsNumeric,
+    filterGteIsGtOrEq,
+    filterLteIsLtOrEq,
+    filterOrderedTriplePartitions,
+    /* write semantics */
+    uniqueConflictCreate,
+    uniqueConflictUpdate,
+    /* After the paging checks, so its scratch record never shifts a page boundary they walk; before
+     * every check that writes a field, so they all pick around what the update drops. */
+    updatePersistsFields,
+    patchMinimality,
+    immutableRejected,
+    stringPayloadSurvives,
+    idempotentReplay,
+    declaredInvalidationHappens,
+    projectionsAgree,
+    queryAxesCompose,
+    filterAndSelectCompose,
+    searchAndFilterCompose,
+    filterSortSelectCompose,
+    filterSearchSortCompose,
+    filterSearchSelectCompose,
+    querySortAndSelectCompose,
+    querySearchAndSelectCompose,
+    querySearchAndSortCompose,
+    queryFilterSearchSortSelectCompose,
+    declaredFilterableWorks,
+    declaredFilterableOpsAccepted,
+    declaredSortableWorks,
+    declaredSortableNullsAccepted,
+    declaredSelectableWorks,
+    filterAliasMatchesCanonical,
+    filterIllegalOpRejected,
+    limitBoundsEnforced,
+    filterMalformedTermRejected,
+    filterEmptyIn,
+    filterInOverLimitRejected,
+    filterConditionCapRejected,
+    noLostUpdate,
+    deleteMissingIs404,
+    softDeleteHidden,
+    /* input validation */
+    enumValidated,
+    maxLengthValidated,
+    requiredValidated,
+    contentTypeEnforced,
+    /* security: planned per operation by the security stage, not by the entity lanes */
+    missingCredentialRefused,
+    invalidCredentialRefused,
+    wrongSchemeRefused,
+    scopeEnforced,
+    alternativeAccepted,
+    anonymousOperationOpen,
+    revokedCredentialRefused,
+    refreshReuseRefused,
+    roleEnforced,
+    crossTenantKeyRefused,
+    privilegedFieldIgnored,
+    loginThrottled,
+    /* input validation of every other write, planned per operation by the same stage, after the
+     * security probes so none of theirs moves */
+    invalidBodyRefused,
+    /* isolation */
+    crossTenantItemRead,
+    crossTenantItemWrite,
+    foreignParentRejected,
+    denialDoesNotRevealExistence,
+    crossTenantFilterBypass,
+    rankIsMonotonic,
+    rankIsMonotonicOnWrites,
+    inviteGrantsThenRevokes,
+    selfIdentityCheck,
+    rootReadCheck,
+    disposableCheck,
+    publicGetCheck,
+    contractCallCheck,
+    serverErrorCheck,
+    /* declared side effects and async lifecycles, last: both invoke operations that change the
+     * world, and both are meaningless if the read surface above is already known broken */
+    declaredEffectsOccur,
+    sideEffectArrives,
+    asyncReachesTerminalState,
+    asyncReceiptIsResolvable,
+    /* Freshness writes scratch records late, so registering them moved no earlier check's bodies; the
+     * judges after them still see their exchanges. */
+    stalenessWithinBound,
+    bypassIsFresh,
+    /* The last writer, right before the judges, so they see its 412. Only the judges come after it,
+     * and they draw no salt, so registering it moved no other check's bodies. */
+    ifMatchEnforced,
+    /* After every other check has written to the transcript — create is owned by
+     * create.status-matches-document. */
+    documentedStatusHonored,
+    errorSchemaHonored,
+    readSchemaHonored,
+    writeOnlyNotReturned,
+    problemJsonShape,
+    declaredRateLimitHonored,
+];
+//# sourceMappingURL=registry.js.map

package/dist/api/runtime/checks/sets/compare.d.ts

@@ -0,0 +1,76 @@
+import type { SortValue } from "../../../spec/render/sort.ts";
+import type { Record_ } from "../../world/records.ts";
+import type { Listed } from "../core/context.ts";
+import type { Outcome } from "../../finding.ts";
+import { type Query } from "../query/capabilities.ts";
+import { type ListResult } from "./list.ts";
+import { type SetRead } from "./read.ts";
+/** A whole set in the shape of one listed page: `items` holds every record, `exchange` is the last page read. */
+export type Listing = ListResult & {
+    complete: boolean;
+};
+/**
+ * A whole set, as a `Listing`. For checks written against a single page that reason about the
+ * whole set; a refused page shows as the last exchange's status.
+ */
+export declare function listAll(ctx: Listed, query: Query): Promise<Listing>;
+/**
+ * A repeat `listAll` that sees the collection as it is now, for `settlePair`. `null` when a page was
+ * refused, so a refusal is not read as rows vanishing.
+ */
+export declare function listAgain(ctx: Listed, query: Query): Promise<Listing | null>;
+/**
+ * Collects a whole result set — `readSet`, shaped for the set-algebra checks. `null` when a page
+ * was refused, so the caller reports the check unresolved rather than reading "refused" as "empty".
+ */
+export declare function collectSet(ctx: Listed, requested: number, extra?: Query, { order, fresh }?: {
+    order?: SortValue | undefined;
+    fresh?: boolean | undefined;
+}): Promise<SetRead | null>;
+/** A read's rows as a set: two reads of one collection agree on it unless the collection moved. */
+export declare function membership(records: Record_[], identity: string): string;
+/** Two reads that must hold the same rows. */
+export interface ReadPair<T> {
+    first: T;
+    second: T;
+}
+/**
+ * Two reads that must hold the same rows and do not. Read the first again: when the same read
+ * now holds other rows, the collection is moving under the check — an append-only log the run
+ * itself writes to — and that is no defect of ordering. When it holds still, read the second again
+ * and compare that fresh pair; only a disagreement that survives it is the backend's.
+ */
+export declare function settlePair<T extends {
+    items: Record_[];
+}>(identity: string, { first, second }: ReadPair<T>, again: {
+    first: () => Promise<T | null>;
+    second: () => Promise<T | null>;
+}): Promise<ReadPair<T> | "moving" | null>;
+/**
+ * Reads every term and asks whether they agree. A disagreement is read again: when any read now
+ * holds other rows, another writer moved the collection between the reads (a record created after
+ * one term was read and before the next), and that is no defect of the query. Only a disagreement
+ * the fresh reads repeat is the backend's, and those fresh reads are what is returned.
+ */
+export declare function readSettled(ctx: Listed, terms: ReadonlyArray<Record<string, string>>, agree: (reads: SetRead[]) => boolean): Promise<SetRead[] | "rejected" | "incomplete" | "moving">;
+/** One term of a comparison as its check walked it: the query, and the walk's order and page size. */
+export interface SettledTerm {
+    query?: Query | undefined;
+    order?: SortValue | undefined;
+    size?: number;
+}
+/**
+ * What `check` reports for reads that disagree before it blames the backend: unresolved when the
+ * collection moved under them or a reread was refused, `null` when the disagreement is the backend's.
+ * `terms[i]` is how `reads[i]` was walked.
+ */
+export declare function unlessMoved(ctx: Listed, check: string, { terms, reads }: {
+    terms: ReadonlyArray<SettledTerm>;
+    reads: ReadonlyArray<{
+        items: Record_[];
+    }>;
+}): Promise<Outcome | null>;
+export declare function duplicates(values: string[]): string[];
+export declare function setOf(records: Record_[], identity: string): Set<string>;
+export declare function sameSet(a: Set<string>, b: Set<string>): boolean;
+//# sourceMappingURL=compare.d.ts.map

package/dist/api/runtime/checks/sets/compare.js

@@ -0,0 +1,148 @@
+import { conv, MOVING_COLLECTION, pageSize, REREAD_REFUSED } from "../query/capabilities.js";
+import { ids } from "./list.js";
+import { readSet } from "./read.js";
+/**
+ * A whole set, as a `Listing`. For checks written against a single page that reason about the
+ * whole set; a refused page shows as the last exchange's status.
+ */
+export async function listAll(ctx, query) {
+    return toListing(await readListing(ctx, query, false));
+}
+/**
+ * A repeat `listAll` that sees the collection as it is now, for `settlePair`. `null` when a page was
+ * refused, so a refusal is not read as rows vanishing.
+ */
+export async function listAgain(ctx, query) {
+    const read = await readListing(ctx, query, true);
+    return read.status === "ok" ? toListing(read) : null;
+}
+function toListing(read) {
+    return {
+        complete: read.status === "ok" && read.complete,
+        envelope: read.last.envelope,
+        exchange: read.last.exchange,
+        items: read.items,
+    };
+}
+/** `readSet` for a query written as one page's: paging keys dropped, the order key taken apart. */
+function readListing(ctx, query, fresh) {
+    const c = conv(ctx);
+    const extra = {};
+    let order;
+    for (const [key, value] of Object.entries(query)) {
+        if (key === c.limit || key === c.page || key === c.offset || key === c.cursor)
+            continue;
+        if (key === c.order)
+            order = value === undefined ? undefined : String(value);
+        else
+            extra[key] = value;
+    }
+    return readSet(ctx, extra, { ...(fresh ? { fresh: true } : {}), order });
+}
+/**
+ * Collects a whole result set — `readSet`, shaped for the set-algebra checks. `null` when a page
+ * was refused, so the caller reports the check unresolved rather than reading "refused" as "empty".
+ */
+export async function collectSet(ctx, requested, extra = {}, 
+/* `fresh`: a repeat read that must see the collection as it is now, not as an earlier read saw it. */
+{ order, fresh = false } = {}) {
+    const read = await readSet(ctx, extra, { ...(fresh ? { fresh: true } : {}), order, size: requested });
+    return read.status === "ok" ? read : null;
+}
+/** A read's rows as a set: two reads of one collection agree on it unless the collection moved. */
+export function membership(records, identity) {
+    return ids(records, identity).sort().join(",");
+}
+/**
+ * Two reads that must hold the same rows and do not. Read the first again: when the same read
+ * now holds other rows, the collection is moving under the check — an append-only log the run
+ * itself writes to — and that is no defect of ordering. When it holds still, read the second again
+ * and compare that fresh pair; only a disagreement that survives it is the backend's.
+ */
+export async function settlePair(identity, { first, second }, again) {
+    if (membership(first.items, identity) === membership(second.items, identity))
+        return { first, second };
+    const firstAgain = await again.first();
+    if (firstAgain === null)
+        return null;
+    if (membership(firstAgain.items, identity) !== membership(first.items, identity))
+        return "moving";
+    const secondAgain = await again.second();
+    if (secondAgain === null)
+        return null;
+    if (membership(secondAgain.items, identity) !== membership(second.items, identity))
+        return "moving";
+    return { first: firstAgain, second: secondAgain };
+}
+/**
+ * Reads every term and asks whether they agree. A disagreement is read again: when any read now
+ * holds other rows, another writer moved the collection between the reads (a record created after
+ * one term was read and before the next), and that is no defect of the query. Only a disagreement
+ * the fresh reads repeat is the backend's, and those fresh reads are what is returned.
+ */
+export async function readSettled(ctx, terms, agree) {
+    const limit = pageSize(ctx);
+    const reads = [];
+    for (const term of terms) {
+        const set = await collectSet(ctx, limit, term);
+        if (set === null)
+            return "rejected";
+        reads.push(set);
+    }
+    if (!reads.every((set) => set.complete))
+        return "incomplete";
+    if (agree(reads))
+        return reads;
+    const moved = await movedSince(ctx, reads.map((read, index) => ({ query: terms[index], read })));
+    return moved === null ? "rejected" : moved ? "moving" : reads;
+}
+/**
+ * Whether the collection moved under reads that disagree. Each term is walked again as it was
+ * walked; when one now holds other rows, another writer (an entity in another lane, writing to the
+ * same collection) moved it between the reads, and the disagreement is no defect of the query. When
+ * none moved, the reads hold what the backend serves and their disagreement is its own. `null` when
+ * a walk was refused this time.
+ */
+async function movedSince(ctx, walked) {
+    for (const { order, query, read, size } of walked) {
+        const again = await collectSet(ctx, size ?? pageSize(ctx), query ?? {}, { fresh: true, order });
+        if (again === null)
+            return null;
+        if (membership(again.items, ctx.identity) !== membership(read.items, ctx.identity))
+            return true;
+    }
+    return false;
+}
+/**
+ * What `check` reports for reads that disagree before it blames the backend: unresolved when the
+ * collection moved under them or a reread was refused, `null` when the disagreement is the backend's.
+ * `terms[i]` is how `reads[i]` was walked.
+ */
+export async function unlessMoved(ctx, check, { terms, reads }) {
+    const moved = await movedSince(ctx, reads.map((read, index) => ({ ...terms[index], read })));
+    if (moved === false)
+        return null;
+    return ctx.findings.unresolved(check, ctx.entityName, moved === null ? REREAD_REFUSED : MOVING_COLLECTION);
+}
+export function duplicates(values) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            dupes.add(value);
+        seen.add(value);
+    }
+    return [...dupes];
+}
+export function setOf(records, identity) {
+    return new Set(ids(records, identity));
+}
+export function sameSet(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const item of a)
+        if (!b.has(item))
+            return false;
+    return true;
+}
+//# sourceMappingURL=compare.js.map