@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/reference/stores/sqlite.js

@@ -0,0 +1,219 @@
+/**
+ * SQLite-backed storage for the reference backend.
+ *
+ * The in-memory store evaluates the query AST in JavaScript, which quietly sidesteps what breaks
+ * real APIs: collation, type affinity, and result order when a sort has no total order. Running
+ * the same predicates through a real engine is what makes a check that passes here mean something.
+ *
+ * The engine is supplied as a driver, so the same SQL runs in-process via `node:sqlite` and
+ * remotely against Cloudflare D1. That second target is not redundancy: D1 is a different build
+ * with different compile flags, reached over the network, backed by a database that persists
+ * between runs — three properties an in-process store cannot exhibit.
+ */
+import { ENTITIES } from "../model/entities.js";
+import { compileOrder, compileWhere, globText } from "./sql-compile.js";
+/** SQLite storage class per declared field type. */
+const AFFINITY = {
+    boolean: "INTEGER",
+    integer: "INTEGER",
+    number: "REAL",
+    array: "TEXT",
+    object: "TEXT",
+    string: "TEXT",
+};
+/**
+ * Physical column name.
+ *
+ * Deliberately the declared field name, quoted. A production API this was modeled on named
+ * columns one way in DDL and another way in every read, and SQLite's double-quoted-string
+ * fallback turned the mismatch into wrong data instead of an error — see the
+ * COLUMN_NAME_MISMATCH defect, which reproduces it.
+ */
+function col(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Physical table name.
+ *
+ * Prefixed per store instance because a remote database outlives the process that created it:
+ * two runs sharing one D1 would otherwise collide on both schema and data, and the resulting
+ * cross-talk would surface as findings that describe the harness rather than the backend.
+ */
+function tableName(entity, prefix) {
+    return `"${prefix}${entity.plural}"`;
+}
+export class SqlStore {
+    flavor;
+    defects;
+    db;
+    prefix;
+    entities;
+    constructor(parts) {
+        this.defects = parts.defects;
+        this.db = parts.db;
+        this.prefix = parts.prefix;
+        this.entities = parts.entities;
+        this.flavor = {
+            binary: (expr) => expr,
+            bind: (args, value) => {
+                args.push(value);
+                return "?";
+            },
+            bool: (value) => (value ? 1 : 0),
+            column: (_entity, field) => col(field),
+            hasElement: (expr, element, args) => {
+                args.push(element);
+                return `EXISTS (SELECT 1 FROM json_each(${expr}) WHERE value = ?)`;
+            },
+            /* GLOB is SQLite's case-sensitive matcher and needs no pragma, so the same SQL behaves
+             * identically in-process and on D1. Case-insensitive matching folds both sides with
+             * the engine's own LOWER so the two always agree on what "lower" means. */
+            like: (expr, { insensitive, segments }, args) => {
+                args.push(globText(segments));
+                return insensitive ? `LOWER(${expr}) GLOB LOWER(?)` : `${expr} GLOB ?`;
+            },
+            position: (expr, { caseSensitive, text }, args) => {
+                args.push(text);
+                return caseSensitive ? `instr(${expr}, ?)` : `instr(LOWER(${expr}), LOWER(?))`;
+            },
+            random: "random()",
+            toText: (expr) => `CAST(${expr} AS TEXT)`,
+        };
+    }
+    /**
+     * Schema creation is a set of round trips on a networked engine, so it cannot live in a
+     * constructor. `prefix` isolates one run's tables from another's on a shared database.
+     */
+    static async create(defects, driver, { prefix = "", entities = ENTITIES } = {}) {
+        const store = new SqlStore({ db: driver, defects, entities, prefix });
+        /* One statement per table would be one network round trip per table. Both drivers accept
+         * a multi-statement script, so the whole schema costs a single trip. */
+        await driver.exec(entities.map((entity) => store.ddl(entity)).join(";\n"));
+        return store;
+    }
+    async close() {
+        /* Persistent engines keep whatever this run created unless it is dropped. Failures here
+         * are swallowed: teardown must not mask the result the run was there to produce. */
+        if (this.prefix !== "") {
+            for (const entity of this.entities) {
+                try {
+                    await this.db.exec(`DROP TABLE IF EXISTS ${tableName(entity, this.prefix)}`);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        await this.db.close();
+    }
+    ddl(entity) {
+        const columns = entity.fields.map((field) => {
+            const physical = this.physical(field.name);
+            const notNull = field.required === true ? " NOT NULL" : "";
+            return `  ${physical} ${AFFINITY[field.type]}${notNull}`;
+        });
+        const table = tableName(entity, this.prefix);
+        return (`CREATE TABLE ${table} (\n${columns.join(",\n")}\n);\n` +
+            `CREATE INDEX "${this.prefix}idx_${entity.plural}_id" ON ${table} (${col(entity.identity)})`);
+    }
+    /** The stored column for a field — diverges from the declared name only under the defect. */
+    physical(name) {
+        return this.defects.has("COLUMN_NAME_MISMATCH") && name === "name" ? col("mislabeled_name") : col(name);
+    }
+    async insert(entity, record) {
+        const names = entity.fields.map((f) => f.name).filter((n) => record[n] !== undefined);
+        const placeholders = names.map(() => "?").join(", ");
+        const columns = names.map((n) => this.physical(n)).join(", ");
+        const values = names.map((n) => toSql(record[n]));
+        /* RETURNING reads the stored row back in the same statement. On a networked engine the
+         * separate SELECT this replaces doubled the cost of every write. */
+        const written = await this.db.all(`INSERT INTO ${tableName(entity, this.prefix)} (${columns}) VALUES (${placeholders}) ` +
+            `RETURNING ${this.selectList(entity)}`, values);
+        const row = written[0];
+        return row === undefined ? record : this.decode(entity, row);
+    }
+    /**
+     * Explicit column list, as production code writes it.
+     *
+     * `SELECT *` would paper over a DDL/read naming mismatch; naming columns is what lets
+     * SQLite's double-quoted-string fallback surface — an unresolvable "name" silently becomes
+     * the literal 'name' rather than an error. See COLUMN_NAME_MISMATCH.
+     */
+    selectList(entity) {
+        return entity.fields
+            .map((f) => {
+            if (!this.defects.has("COLUMN_NAME_MISMATCH") || f.name !== "name")
+                return col(f.name);
+            /*
+             * The bug is that DDL wrote `mislabeled_name` while reads ask for `name`.
+             *
+             * On an engine with double-quoted-string fallback ON, that is expressible in its
+             * natural form — `"name"` resolves to no column, so SQLite hands back the literal
+             * 'name' and the API serves the column's own name as every row's value. Writing
+             * it that way means the *engine* produces the damage, which is a materially
+             * stronger test than asserting the API tester catches a hand-written imitation.
+             *
+             * Where the fallback is compiled off the same SQL is an error, not a silent wrong
+             * answer, so the damaging outcome is emitted directly instead.
+             */
+            return this.db.dqs ? col(f.name) : `'${f.name}' AS ${col(f.name)}`;
+        })
+            .join(", ");
+    }
+    async byId(entity, id) {
+        const rows = await this.db.all(`SELECT ${this.selectList(entity)} FROM ${tableName(entity, this.prefix)} WHERE ${col(entity.identity)} = ?`, [id]);
+        const row = rows[0];
+        return row === undefined ? null : this.decode(entity, row);
+    }
+    async update(entity, id, patch) {
+        const names = Object.keys(patch).filter((n) => entity.fields.some((f) => f.name === n));
+        if (names.length === 0)
+            return this.byId(entity, id);
+        const assignments = names.map((n) => `${this.physical(n)} = ?`).join(", ");
+        const written = await this.db.all(`UPDATE ${tableName(entity, this.prefix)} SET ${assignments} ` +
+            `WHERE ${col(entity.identity)} = ? RETURNING ${this.selectList(entity)}`, [...names.map((n) => toSql(patch[n])), id]);
+        const row = written[0];
+        return row === undefined ? null : this.decode(entity, row);
+    }
+    async remove(entity, id) {
+        await this.db.run(`DELETE FROM ${tableName(entity, this.prefix)} WHERE ${col(entity.identity)} = ?`, [id]);
+    }
+    async select(entity, plan) {
+        const args = [];
+        const where = compileWhere(plan.where, { args, entity, flavor: this.flavor });
+        const order = compileOrder(plan, entity, this.flavor);
+        const rows = await this.db.all(`SELECT ${this.selectList(entity)} FROM ${tableName(entity, this.prefix)} WHERE ${where}${order}`, args.map(toSql));
+        return rows.map((row) => this.decode(entity, row));
+    }
+    /**
+     * Converts stored values back to their declared shape. SQLite has no boolean type, so a
+     * field declared boolean comes back as 0/1 and would fail its own response schema.
+     */
+    decode(entity, row) {
+        const out = {};
+        for (const field of entity.fields) {
+            const raw = row[field.name];
+            if (raw === undefined || raw === null) {
+                out[field.name] = null;
+                continue;
+            }
+            out[field.name] =
+                field.type === "boolean"
+                    ? raw === 1
+                    : (field.type === "object" || field.type === "array") && typeof raw === "string"
+                        ? JSON.parse(raw)
+                        : raw;
+        }
+        return out;
+    }
+}
+function toSql(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return value;
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/api/report/confidence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The page a person opens after a run. Every operation sits in exactly one group, worst first:
+ * what failed, what never got a verdict, what passed without its effect being seen, what was
+ * verified, and what was complete by its contract alone. Each row says why in one line and links
+ * the requests that prove it, so trust in a result never rests on a count.
+ */
+import type { ScopeReport } from "../runtime/scope/types.ts";
+export type ConfidenceKey = "failed" | "blocked" | "unproven" | "verified" | "complete";
+export interface ConfidenceRow {
+    operation: string;
+    entity: string | null;
+    why: string;
+    /** Exchange files behind the row: the call, then the exchange that observed its effect. */
+    evidence: string[];
+}
+export interface ConfidenceGroup {
+    key: ConfidenceKey;
+    title: string;
+    meaning: string;
+    rows: ConfidenceRow[];
+}
+export declare function confidenceGroups(scope: ScopeReport, files: ReadonlyMap<number, string>): ConfidenceGroup[];
+export declare function renderConfidenceHtml(run: {
+    baseUrl: string;
+    generatedAt: string;
+    scope: ScopeReport;
+}, files: ReadonlyMap<number, string>): string;
+/** Each request's saved file by its seq, from the journal index (`exchanges.jsonl`). */
+export declare function exchangeFilesFromIndex(index: string): Map<number, string>;
+/** The markdown report's opening count, one row per group, pointing at the page that lists them. */
+export declare function renderConfidenceMarkdown(scope: ScopeReport): string;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/api/report/confidence.js

@@ -0,0 +1,134 @@
+/**
+ * The page a person opens after a run. Every operation sits in exactly one group, worst first:
+ * what failed, what never got a verdict, what passed without its effect being seen, what was
+ * verified, and what was complete by its contract alone. Each row says why in one line and links
+ * the requests that prove it, so trust in a result never rests on a count.
+ */
+const GROUPS = [
+    { key: "failed", meaning: "A check found the backend wrong here.", title: "Failed" },
+    {
+        key: "blocked",
+        meaning: "No verdict: something this operation needed failed first, or no check could reach it.",
+        title: "Blocked",
+    },
+    {
+        key: "unproven",
+        meaning: "Met its contract, but what it changes was never observed. Add a read that shows the effect.",
+        title: "Effects unproven",
+    },
+    { key: "verified", meaning: "A later request shows what this call did.", title: "Verified" },
+    {
+        key: "complete",
+        meaning: "A read, or an operation that declares no effects: meeting its contract is all it promises.",
+        title: "Complete by contract",
+    },
+];
+function groupOf(op) {
+    if (op.status === "failed")
+        return "failed";
+    if (op.status !== "passed")
+        return "blocked";
+    return op.sufficiency ?? "unproven";
+}
+function whyOf(op) {
+    if (op.status === "failed") {
+        const checks = op.checks.failed.length > 0 ? op.checks.failed.join(", ") : "a check";
+        return `failed ${checks} (${op.findings} finding${op.findings === 1 ? "" : "s"})`;
+    }
+    return op.why ?? op.reason ?? "no reason recorded";
+}
+function evidenceOf(op, files) {
+    if (op.evidence === undefined)
+        return [];
+    const seqs = [op.evidence.call, ...(op.evidence.observation === undefined ? [] : [op.evidence.observation.seq])];
+    return seqs.flatMap((seq) => {
+        const file = files.get(seq);
+        return file === undefined ? [] : [file];
+    });
+}
+export function confidenceGroups(scope, files) {
+    return GROUPS.map((group) => ({
+        ...group,
+        rows: scope.operations
+            .filter((op) => groupOf(op) === group.key)
+            .map((op) => ({
+            entity: op.entity,
+            evidence: evidenceOf(op, files),
+            operation: op.origin === undefined ? op.operationId : `${op.origin}:${op.operationId}`,
+            why: whyOf(op),
+        }))
+            .sort((a, b) => a.operation.localeCompare(b.operation)),
+    }));
+}
+function escape(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+function rowHtml(row) {
+    const links = row.evidence
+        .map((file, i) => `<a href="${escape(file)}">${i === 0 ? "call" : "observed"}</a>`)
+        .join(" · ");
+    return (`<tr><td><code>${escape(row.operation)}</code>${row.entity === null ? "" : `<span class="entity">${escape(row.entity)}</span>`}</td>` +
+        `<td>${escape(row.why)}</td><td class="links">${links}</td></tr>`);
+}
+const STYLE = `
+:root{--bg:#fbfbfa;--fg:#1d1d1b;--muted:#6b6b66;--line:#e4e3df;--failed:#c0362c;--blocked:#b7791f;--unproven:#8a6d00;--verified:#2f7d4f;--complete:#3a6ea5}
+@media (prefers-color-scheme:dark){:root{--bg:#141413;--fg:#ecebe7;--muted:#9a9a94;--line:#2c2c2a;--failed:#ef6b5f;--blocked:#e3a94a;--unproven:#d8b84a;--verified:#5fbf86;--complete:#78a6dc}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,sans-serif}
+main{max-width:1100px;margin:0 auto;padding:24px 16px}h1{font-size:22px;margin:0 0 4px}p.meta{color:var(--muted);margin:0 0 20px}
+.bar{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px}.bar a{display:flex;gap:6px;align-items:baseline;padding:8px 12px;border:1px solid var(--line);border-radius:8px;color:inherit;text-decoration:none}
+.bar strong{font-size:20px}section{margin-bottom:28px}h2{font-size:17px;margin:0 0 2px;display:flex;gap:8px;align-items:center}
+h2 .dot{width:10px;height:10px;border-radius:50%}p.meaning{color:var(--muted);margin:0 0 8px}
+table{width:100%;border-collapse:collapse}td{border-top:1px solid var(--line);padding:6px 8px;vertical-align:top}
+td:first-child{width:34%;word-break:break-word}td.links{width:120px;white-space:nowrap}code{font-size:13px}
+.entity{display:block;color:var(--muted);font-size:12px}a{color:var(--complete)}
+@media (max-width:640px){td{display:block;width:auto!important;border:0;padding:2px 0}tr{display:block;border-top:1px solid var(--line);padding:8px 0}}
+`;
+export function renderConfidenceHtml(run, files) {
+    const groups = confidenceGroups(run.scope, files);
+    const total = groups.reduce((sum, group) => sum + group.rows.length, 0);
+    const bar = groups
+        .map((group) => `<a href="#${group.key}"><strong style="color:var(--${group.key})">${group.rows.length}</strong>${escape(group.title)}</a>`)
+        .join("");
+    const sections = groups
+        .filter((group) => group.rows.length > 0)
+        .map((group) => `<section id="${group.key}"><h2><span class="dot" style="background:var(--${group.key})"></span>${escape(group.title)} · ${group.rows.length}</h2>` +
+        `<p class="meaning">${escape(group.meaning)}</p><table>${group.rows.map(rowHtml).join("")}</table></section>`)
+        .join("");
+    return (`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">` +
+        `<title>the API tester confidence</title><style>${STYLE}</style></head><body><main>` +
+        `<h1>What this run proves</h1><p class="meta">${escape(run.baseUrl)} · ${escape(run.generatedAt)} · ${total} operations · ` +
+        `<a href="report.md">full report</a> · <a href="matrix.html">matrix</a></p>` +
+        `<nav class="bar">${bar}</nav>${sections}</main></body></html>\n`);
+}
+/** Each request's saved file by its seq, from the journal index (`exchanges.jsonl`). */
+export function exchangeFilesFromIndex(index) {
+    const files = new Map();
+    for (const line of index.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (typeof entry.seq === "number" && typeof entry.file === "string")
+                files.set(entry.seq, entry.file);
+        }
+        catch {
+            /* a torn last line from an interrupted run */
+        }
+    }
+    return files;
+}
+/** The markdown report's opening count, one row per group, pointing at the page that lists them. */
+export function renderConfidenceMarkdown(scope) {
+    const groups = confidenceGroups(scope, new Map());
+    return [
+        "## Confidence",
+        "",
+        "> Every operation in exactly one group. The rows, with why and the requests behind them: [report.html](./report.html).",
+        "",
+        "| group | operations | meaning |",
+        "| --- | --- | --- |",
+        ...groups.map((group) => `| ${group.title} | ${group.rows.length} | ${group.meaning} |`),
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=confidence.js.map

package/dist/api/report/console/bypass.d.ts

@@ -0,0 +1,13 @@
+/** The cache bypass each documented read is sent with, grouped for `doctor`. */
+import type { SpecModel } from "../../spec/graph/types.ts";
+export interface BypassGroup {
+    /** `name: value` as sent; null when the config sends none. */
+    bypass: string | null;
+    source: "declared" | "default" | "off";
+    operations: string[];
+}
+/** Declared bypasses first, each once, then the default; one `off` group when `enabled` is false. */
+export declare function bypassGroups(model: SpecModel, enabled: boolean): BypassGroup[];
+/** One row per group: how many reads, naming them only where the document declared the bypass. */
+export declare function bypassRows(groups: readonly BypassGroup[]): string[];
+//# sourceMappingURL=bypass.d.ts.map

package/dist/api/report/console/bypass.js

@@ -0,0 +1,29 @@
+/** The cache bypass each documented read is sent with, grouped for `doctor`. */
+/** Declared bypasses first, each once, then the default; one `off` group when `enabled` is false. */
+export function bypassGroups(model, enabled) {
+    const reads = model.operations.filter((op) => ["GET", "HEAD"].includes(op.method.toUpperCase()));
+    if (reads.length === 0)
+        return [];
+    if (!enabled)
+        return [{ bypass: null, operations: reads.map((op) => op.operationId).sort(), source: "off" }];
+    const groups = new Map();
+    for (const op of reads) {
+        const declared = op.consistency?.bypass;
+        const bypass = declared === undefined || declared === null ? "cache-control: no-cache" : `${declared.name}: ${declared.value}`;
+        const group = groups.get(bypass) ?? { bypass, operations: [], source: declared ? "declared" : "default" };
+        group.operations.push(op.operationId);
+        groups.set(bypass, group);
+    }
+    const sorted = [...groups.values()].map((group) => ({ ...group, operations: group.operations.sort() }));
+    return [...sorted.filter((g) => g.source === "declared"), ...sorted.filter((g) => g.source === "default")];
+}
+/** One row per group: how many reads, naming them only where the document declared the bypass. */
+export function bypassRows(groups) {
+    return groups.map((group) => {
+        const label = group.source === "off" ? "off (config cache.bypass)" : `${group.source} ${group.bypass}`;
+        const count = `${group.operations.length} read${group.operations.length === 1 ? "" : "s"}`;
+        const named = group.source === "declared" ? `: ${group.operations.join(", ")}` : "";
+        return `    ${label.padEnd(36)} ${count}${named}`;
+    });
+}
+//# sourceMappingURL=bypass.js.map

package/dist/api/report/console/catalog-checks.d.ts

@@ -0,0 +1,9 @@
+import type { QueryConventions } from "../../spec/conventions/types.ts";
+import type { EffectiveQueryCapabilities } from "../../spec/query/effective.ts";
+type Caps = EffectiveQueryCapabilities;
+/** The declared-or-skip query checks a list's capabilities and grammar let run, in catalog order. */
+export declare function catalogCheckPreview(caps: Caps, list: {
+    conventions: QueryConventions;
+}, source: Caps["source"]): string[];
+export {};
+//# sourceMappingURL=catalog-checks.d.ts.map

package/dist/api/report/console/catalog-checks.js

@@ -0,0 +1,106 @@
+import { canWriteFilterOp, filterSpec } from "../../spec/conventions/filter.js";
+import { canGroupAnd } from "../../spec/render/filter-term.js";
+import { anyFieldAllows, fieldAllowsNulls, opsAreClosed } from "../../spec/query/field-ops.js";
+/**
+ * Operator checks: each applies when some field allows every operator it compares and the list's
+ * grammar can write the operator it sends.
+ */
+const OPERATOR_CHECKS = [
+    { allows: ["in"], id: "filter.in-is-union-of-eq", writes: ["in"] },
+    { allows: ["in", "nin"], id: "filter.nin-complements-in", writes: ["in", "nin"] },
+    { allows: ["gte", "gt"], id: "filter.gte-is-gt-or-eq", writes: ["gte"] },
+    { allows: ["lte", "lt"], id: "filter.lte-is-lt-or-eq", writes: ["lte"] },
+    { allows: ["lt", "gt"], id: "filter.ordered-triple-partitions", writes: ["lt"] },
+    { allows: ["ilike", "like"], id: "filter.ilike-is-case-insensitive", writes: ["ilike"] },
+    { allows: ["is"], id: "filter.is-null-selects-nulls", writes: ["is"] },
+    { allows: ["contains"], id: "filter.contains-membership", writes: ["contains"] },
+];
+function filterChecks(caps, conventions, source) {
+    const spec = filterSpec(conventions);
+    const allows = (op) => anyFieldAllows(caps, op) !== undefined;
+    const write = (op) => canWriteFilterOp(conventions, op);
+    const ids = OPERATOR_CHECKS.filter((check) => check.allows.every(allows) && check.writes.every(write)).map((check) => check.id);
+    if (spec.mixed && caps.filterable.length > 1)
+        ids.push("filter.nested-and-or-distributes");
+    if (Object.keys(caps.aliases).length > 0)
+        ids.push("filter.alias-matches-canonical");
+    if (caps.filterable.some((field) => opsAreClosed(field, caps))) {
+        ids.push("filter.illegal-op-rejected");
+        if (source === "tag" || source === "mixed")
+            ids.push("spec.declared-filterable-ops-accepted");
+    }
+    const inWritable = allows("in") && write("in");
+    if (caps.emptyIn !== undefined && inWritable)
+        ids.push("filter.empty-in");
+    if (caps.maxInValues !== undefined && inWritable)
+        ids.push("filter.in-over-limit-rejected");
+    if (caps.maxFilterConditions !== undefined && canGroupAnd(spec))
+        ids.push("filter.condition-cap-rejected");
+    return ids;
+}
+function sortChecks(caps, conventions) {
+    if (conventions.order === undefined)
+        return [];
+    const ids = ["sort.unknown-field-rejected"];
+    if (caps.sortable.some((field) => field.type === "number"))
+        ids.push("sort.numeric-order-is-numeric");
+    if (caps.sortable.some((field) => fieldAllowsNulls(field, caps, "first") || fieldAllowsNulls(field, caps, "last"))) {
+        ids.push("sort.nulls-first-last", "spec.declared-sortable-nulls-accepted");
+    }
+    if (caps.sortable.length >= 2 && (caps.sort?.maxKeys === undefined || caps.sort.maxKeys >= 2)) {
+        ids.push("sort.multi-key-tiebreak");
+    }
+    if (caps.sort?.defaultOrder !== undefined)
+        ids.push("sort.default-order-applied");
+    if (caps.sort?.stableTiebreak !== undefined)
+        ids.push("sort.stable-tiebreak");
+    return ids;
+}
+function searchSelectChecks(caps, conventions) {
+    const ids = [];
+    if (conventions.search !== undefined && caps.searchable.length > 0) {
+        ids.push("search.tokens-and", "search.case-insensitive");
+        if (caps.searchEmpty !== undefined)
+            ids.push("search.empty-q");
+        if (caps.searchModes !== undefined && conventions.searchMode !== undefined)
+            ids.push("search.mode-accepted");
+    }
+    if (conventions.select !== undefined && caps.selectable.length > 0) {
+        ids.push("select.requested-fields-present");
+        if (caps.select?.unknown !== undefined)
+            ids.push("select.unknown-field-rejected");
+        if (caps.select?.nested === true && (caps.select.relations?.length ?? 0) > 0)
+            ids.push("select.nested-honored");
+    }
+    return ids;
+}
+/** Checks that compose two or more roles: each needs every role it combines usable. */
+function composeChecks(caps, conventions) {
+    const sort = conventions.order !== undefined && caps.sortable.length > 0;
+    const select = conventions.select !== undefined && caps.selectable.length > 0;
+    const search = conventions.search !== undefined && caps.searchable.length > 0;
+    const ids = [];
+    if (sort && select)
+        ids.push("query.sort-and-select-compose");
+    if (search && select)
+        ids.push("query.search-and-select-compose");
+    if (search && sort)
+        ids.push("query.search-and-sort-compose");
+    if (caps.filterable.length > 0 &&
+        caps.searchable.length > 0 &&
+        caps.sortable.length > 0 &&
+        caps.selectable.length > 0) {
+        ids.push("query.filter-search-sort-select-compose");
+    }
+    return ids;
+}
+/** The declared-or-skip query checks a list's capabilities and grammar let run, in catalog order. */
+export function catalogCheckPreview(caps, list, source) {
+    return [
+        ...filterChecks(caps, list.conventions, source),
+        ...sortChecks(caps, list.conventions),
+        ...searchSelectChecks(caps, list.conventions),
+        ...composeChecks(caps, list.conventions),
+    ];
+}
+//# sourceMappingURL=catalog-checks.js.map

package/dist/api/report/console/catalog.d.ts

@@ -0,0 +1,45 @@
+import type { EntityConfig, ApiConfig } from "../../config/types/config.ts";
+import type { QueryCapabilities } from "../../config/types/query.ts";
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { EffectiveQueryCapabilities } from "../../spec/query/effective.ts";
+type Caps = EffectiveQueryCapabilities;
+/** What config says about query capabilities, over and above the document. */
+export interface CatalogConfig {
+    query?: QueryCapabilities;
+    entities?: Record<string, EntityConfig>;
+    hooks?: Pick<NonNullable<ApiConfig["hooks"]>, "resolveQueryCapabilities">;
+}
+/** One listable entity's query capabilities, where they came from, and the checks they let run. */
+export interface QueryCatalog {
+    entity: string;
+    source: Caps["source"];
+    filterable: Caps["filterable"];
+    sortable: Caps["sortable"];
+    searchable: string[];
+    selectable: string[];
+    operators?: Caps["operators"];
+    operatorsByType?: Caps["operatorsByType"];
+    aliases: Caps["aliases"];
+    identityFilter?: string;
+    emptyIn?: Caps["emptyIn"];
+    maxInValues?: number;
+    maxFilterConditions?: number;
+    searchModes?: string[];
+    searchEmpty?: Caps["searchEmpty"];
+    sort?: Caps["sort"];
+    select?: Caps["select"];
+    harvest: string[];
+    hook: boolean;
+    checks: string[];
+    /** A declared template, described; absent for a named or inferred grammar. */
+    grammar?: string;
+    /** A declared sort template, described. */
+    sortGrammar?: string;
+}
+/** Per listable entity, the query capabilities document and config together give its list. */
+export declare function entityQueryCatalogs(model: SpecModel, config?: CatalogConfig): {
+    catalogs: QueryCatalog[];
+    unknownEntities: string[];
+};
+export {};
+//# sourceMappingURL=catalog.d.ts.map