@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,113 @@
+/**
+ * Which checks each tag makes possible, measured rather than estimated.
+ *
+ * `testing api conformance` runs the reference backend twice — once with its tags, once with them
+ * stripped — and asserts this map matches the difference, so it cannot drift into marketing.
+ *
+ * The distinction below is the honest part. Some tags *unlock* checks that are otherwise
+ * impossible: nothing in a document reveals that a 202 is a receipt, or that a column is a
+ * tombstone. Others do not change how much runs at all — they change whether what runs is
+ * trustworthy. Without `x-query`, the API tester assumes every scalar property is filterable and probes
+ * fields the backend may never have indexed; without `x-tenant`, a matching path parameter still
+ * infers a tenant and a cross-tenant read is an ambiguity; with no tenant at all the check does
+ * not apply.
+ */
+export const TAG_UNLOCKS = {
+    "x-async": ["async.reaches-terminal-state", "async.receipt-identifies-the-job"],
+    "x-destructive": ["auth.destructive-spares-the-caller"],
+    "x-effects": ["effects.declared-effect-occurs"],
+    "x-immutable": ["patch.immutable-field-rejected"],
+    "x-invalidate": ["invalidation.declared-route-changes"],
+    /* Declaring filterable fields is itself a claim, and a claim is testable: the API tester probes each
+     * one and reports the document — not the backend — when a declared filter is refused. */
+    "x-query": [
+        "spec.declared-filterable-is-filterable",
+        "spec.declared-sortable-is-sortable",
+        "spec.declared-selectable-is-selectable",
+        "spec.declared-filterable-ops-accepted",
+        "spec.declared-sortable-nulls-accepted",
+        "filter.in-is-union-of-eq",
+        "filter.nin-complements-in",
+        "filter.ilike-is-case-insensitive",
+        "filter.is-null-selects-nulls",
+        "filter.alias-matches-canonical",
+        "filter.illegal-op-rejected",
+        /* A malformed term is probed only on a grammar x-query declares. (An unknown sort direction
+         * needs a declared sort grammar, which the reference declares only for its template dialect.) */
+        "filter.malformed-term-rejected",
+        "filter.empty-in",
+        "filter.in-over-limit-rejected",
+        "filter.condition-cap-rejected",
+        "sort.nulls-first-last",
+        "sort.stable-tiebreak",
+        "search.empty-q",
+        "search.mode-accepted",
+        "select.unknown-field-rejected",
+        "select.nested-honored",
+        "sort.default-order-applied",
+        /* An out-of-range page size is judged only where x-query declares it refused. */
+        "pagination.limit-bounds-enforced",
+        /* Membership needs an array the document marks filterable; untagged, no array is guessed. */
+        "filter.contains-membership",
+    ],
+    /* A declared rate is a claim the backend can break; an undeclared one is only the API tester's guess. */
+    "x-rate-limit": ["spec.declared-rate-limit-is-honored"],
+    "x-soft-delete": ["softdelete.absent-from-default-list"],
+    "x-wait": ["effects.side-effect-arrives"],
+    "x-invite": ["auth.invite-grants-then-revokes"],
+    /* identity: self is an x-entity value. Strip the tag and the caller is no longer the record. */
+    "x-entity": ["auth.self-is-the-caller", "read.matches-caller-root"],
+    "x-unique": ["create.unique-conflict-rejected", "update.unique-conflict-rejected"],
+};
+/** Tags that change the *confidence* of checks that already run, not the count. */
+export const TAG_SHARPENS = {
+    "x-query": "the remaining query checks run against every scalar property, including fields the " +
+        "backend never indexed — expect findings you will have to dismiss",
+    "x-tenant": "an inferred tenant makes a cross-tenant item or filter read an ambiguity, not a " +
+        "security finding; with no tenant tagged or inferred those checks do not apply",
+};
+/** What to declare to close a gap, by the tag the gap names. */
+export const TAG_REMEDY = {
+    "x-async": "declare the poll route so the operation's real outcome can be observed",
+    "x-entity": "name the entity and action so this operation joins a lifecycle",
+    "x-entity.identity": "name the property identifying an instance",
+    "x-invalidate": "list the read routes this mutation must change",
+    "x-query": "declare which fields support the filter / order / search / select roles",
+    "x-tenant": "name the path parameter that scopes this operation to a tenant",
+    "x-invite": "name the invite, accept and revoke operations for delegated access",
+    "x-wait": "name the GET to poll after this write until a JSON path is occupied",
+    "x-effects": "declare create/append/delete with count or min, not both",
+    "x-rate-limit": "declare the rate each category is held to, so a stricter real limit is reported",
+    "x-unique": "declare the column sets that must stay unique so a 409 duplicate can be scored",
+    security: "give each scheme in a security requirement a list of scopes, [] for none",
+    $ref: "define what each pointer names: a missing schema reads as unconstrained, a missing anything else leaves its operation untested",
+    /* What the document declares but the API tester never calls: no declaration closes these. */
+    webhooks: "not tested: the API tester makes no inbound or follow-up calls",
+    callbacks: "not tested: the API tester makes no inbound or follow-up calls",
+    links: "not tested: the API tester makes no inbound or follow-up calls",
+    additionalOperations: "not tested: the API tester sends only the methods OpenAPI fixes on a path item",
+    TRACE: "not tested: fetch cannot send TRACE",
+};
+/** The tags the document declares somewhere, as far as `TAG_UNLOCKS` and `TAG_SHARPENS` ask. */
+export function declaredTags(model) {
+    const declared = new Set(model.operations.flatMap((op) => [
+        ...(op.async === null ? [] : ["x-async"]),
+        ...(op.effects.length > 0 ? ["x-effects"] : []),
+        ...(op.immutable.length > 0 ? ["x-immutable"] : []),
+        ...(op.invalidates.length > 0 ? ["x-invalidate"] : []),
+        ...(op.softDelete === null ? [] : ["x-soft-delete"]),
+        ...(op.wait === null ? [] : ["x-wait"]),
+        ...(op.tenantSource === "tag" ? ["x-tenant"] : []),
+        ...(op.query?.source === "tag" ? ["x-query"] : []),
+        ...(op.unique !== null ? ["x-unique"] : []),
+    ]));
+    for (const entity of model.entities.values()) {
+        if (entity.invite !== null)
+            declared.add("x-invite");
+    }
+    if (model.operations.some((op) => op.entitySource === "tag" && op.identity === "self")) {
+        declared.add("x-entity");
+    }
+    return declared;
+}
+//# sourceMappingURL=tags.js.map

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

@@ -0,0 +1,57 @@
+/**
+ * Two runs of one backend, compared.
+ *
+ * Root causes are matched by `findingKey`, so a defect two runs both found reads as persisting
+ * though its ids and ports differ; operations are matched by id, so a target that passed before
+ * and fails now stands out. Reports from other the API tester versions may lack fields: a missing `scope`
+ * makes coverage not comparable rather than an error.
+ */
+export interface SavedFinding {
+    check: string;
+    entity: string;
+    detail: string;
+    summary: string;
+    verdict: string;
+    operations?: string[];
+    origin?: string;
+}
+export interface SavedReport {
+    /** Absent in a 0.24 report, which this the API tester still reads. */
+    schemaVersion?: number;
+    findings: SavedFinding[];
+    scope?: {
+        operations: Array<{
+            operationId?: string;
+            status: string;
+        }>;
+    };
+    targetVersion?: {
+        value?: string;
+        error?: string;
+    };
+}
+/**
+ * Why this the API tester cannot read the saved report at `file`, or `undefined` when it can: one with no
+ * `schemaVersion` (0.24) or with the one this the API tester writes. A later shape is refused, not misread.
+ */
+export declare function schemaRefusal(saved: {
+    schemaVersion?: unknown;
+}, file: string): string | undefined;
+export interface RunDiff {
+    new: SavedFinding[];
+    fixed: SavedFinding[];
+    persisting: SavedFinding[];
+    /** Operations whose status changed; `null` when either report has no scope to compare. */
+    coverage: Array<{
+        operationId: string;
+        from: string;
+        to: string;
+    }> | null;
+    versions: {
+        a?: string;
+        b?: string;
+    };
+}
+export declare function diffReports(a: SavedReport, b: SavedReport): RunDiff;
+export declare function renderDiff(diff: RunDiff): string;
+//# sourceMappingURL=diff.d.ts.map

package/dist/api/report/diff.js

@@ -0,0 +1,95 @@
+/**
+ * Two runs of one backend, compared.
+ *
+ * Root causes are matched by `findingKey`, so a defect two runs both found reads as persisting
+ * though its ids and ports differ; operations are matched by id, so a target that passed before
+ * and fails now stands out. Reports from other the API tester versions may lack fields: a missing `scope`
+ * makes coverage not comparable rather than an error.
+ */
+import { isRootCause } from "../runtime/finding.js";
+import { findingKey } from "../runtime/finding-key.js";
+import { REPORT_SCHEMA_VERSION } from "./render/json.js";
+/**
+ * Why this the API tester cannot read the saved report at `file`, or `undefined` when it can: one with no
+ * `schemaVersion` (0.24) or with the one this the API tester writes. A later shape is refused, not misread.
+ */
+export function schemaRefusal(saved, file) {
+    const version = saved.schemaVersion;
+    if (version === undefined || version === REPORT_SCHEMA_VERSION)
+        return undefined;
+    return `${file} is report schemaVersion ${JSON.stringify(version)}; this the API tester reads ${REPORT_SCHEMA_VERSION} — upgrade the API tester`;
+}
+function byKey(report) {
+    const keyed = new Map();
+    for (const finding of report.findings) {
+        if (!isRootCause(finding))
+            continue;
+        keyed.set(findingKey(finding), finding);
+    }
+    return keyed;
+}
+function statuses(report) {
+    if (report.scope === undefined)
+        return null;
+    return new Map(report.scope.operations.flatMap((op) => (op.operationId === undefined ? [] : [[op.operationId, op.status]])));
+}
+function versionOf(report) {
+    return report.targetVersion?.value;
+}
+function order(findings) {
+    return findings.sort((x, y) => x.check.localeCompare(y.check) || x.entity.localeCompare(y.entity));
+}
+export function diffReports(a, b) {
+    const before = byKey(a);
+    const after = byKey(b);
+    const statusA = statuses(a);
+    const statusB = statuses(b);
+    let coverage = null;
+    if (statusA !== null && statusB !== null) {
+        coverage = [...new Set([...statusA.keys(), ...statusB.keys()])].sort().flatMap((operationId) => {
+            const from = statusA.get(operationId) ?? "absent";
+            const to = statusB.get(operationId) ?? "absent";
+            return from === to ? [] : [{ from, operationId, to }];
+        });
+    }
+    const versionA = versionOf(a);
+    const versionB = versionOf(b);
+    return {
+        coverage,
+        fixed: order([...before].filter(([key]) => !after.has(key)).map(([, finding]) => finding)),
+        new: order([...after].filter(([key]) => !before.has(key)).map(([, finding]) => finding)),
+        persisting: order([...after].filter(([key]) => before.has(key)).map(([, finding]) => finding)),
+        versions: {
+            ...(versionA === undefined ? {} : { a: versionA }),
+            ...(versionB === undefined ? {} : { b: versionB }),
+        },
+    };
+}
+export function renderDiff(diff) {
+    const lines = [""];
+    if (diff.versions.a !== undefined || diff.versions.b !== undefined) {
+        lines.push(`  target  ${diff.versions.a ?? "?"} → ${diff.versions.b ?? "?"}`);
+    }
+    lines.push(`  ${diff.new.length} new · ${diff.fixed.length} fixed · ${diff.persisting.length} persisting`);
+    const section = (title, findings) => {
+        if (findings.length === 0)
+            return;
+        lines.push("", `  ${title}`);
+        for (const finding of findings)
+            lines.push(`    ${finding.check.padEnd(40)} ${finding.entity} — ${finding.summary}`);
+    };
+    section("NEW", diff.new);
+    section("FIXED", diff.fixed);
+    section("PERSISTING", diff.persisting);
+    if (diff.coverage === null) {
+        lines.push("", "  coverage not comparable: a report has no scope");
+    }
+    else if (diff.coverage.length > 0) {
+        lines.push("", "  COVERAGE");
+        for (const change of diff.coverage)
+            lines.push(`    ${change.operationId.padEnd(40)} ${change.from} → ${change.to}`);
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=diff.js.map

package/dist/api/report/matrix/band.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The poster's top band: every entity as a pin, with an arrow for each cross-entity invalidate
+ * claim. A crowd of entities draws the parents that receive writes as bars instead.
+ */
+import type { MatrixGraph } from "./types.ts";
+export declare function entityBand(graph: MatrixGraph): string;
+//# sourceMappingURL=band.d.ts.map

package/dist/api/report/matrix/band.js

@@ -0,0 +1,113 @@
+/**
+ * The poster's top band: every entity as a pin, with an arrow for each cross-entity invalidate
+ * claim. A crowd of entities draws the parents that receive writes as bars instead.
+ */
+import { esc } from "./text.js";
+const WIDTH = 1120;
+const ROW_HEIGHT = 96;
+const TOP = 56;
+const PIN = "#f0c14b";
+export function entityBand(graph) {
+    if (graph.entities.length > 24)
+        return crowdedBand(graph);
+    const { height, pos } = bandLayout(graph.entities.map((e) => e.name));
+    const pins = graph.entities.map((entity) => pinSvg(entity, pos.get(entity.name)));
+    return `<svg viewBox="0 0 1120 ${height}" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Entity invalidate graph">
+    <defs>
+      <marker id="arrow-cross" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6" fill="#ff6b3d"/></marker>
+      <marker id="arrow-self" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6" fill="#6d7686"/></marker>
+    </defs>
+    ${emptyNote(graph)}
+    ${crossArrows(graph, pos).join("\n")}
+    ${pins.join("\n")}
+  </svg>`;
+}
+/** Pins in rows: all in one row up to six, two rows up to twelve, then rows of five. */
+function bandLayout(names) {
+    const n = names.length;
+    const perRow = n <= 6 ? n : n <= 12 ? Math.ceil(n / 2) : 5;
+    const rows = Math.ceil(n / perRow);
+    const pos = new Map(names.map((name, i) => {
+        const row = Math.floor(i / perRow);
+        const col = i % perRow;
+        const inRow = Math.min(perRow, n - row * perRow);
+        const slot = WIDTH / (inRow + 1);
+        return [name, { x: slot * (col + 1), y: TOP + row * ROW_HEIGHT }];
+    }));
+    return { height: Math.max(160, TOP + rows * ROW_HEIGHT + 20), pos };
+}
+function pinSvg(entity, at) {
+    const surfaces = entity.readSurface.length;
+    return `<g>
+      <circle cx="${at.x}" cy="${at.y}" r="16" fill="${PIN}"/>
+      <circle cx="${at.x}" cy="${at.y}" r="6" fill="#243044"/>
+      <text x="${at.x}" y="${at.y + 36}" text-anchor="middle" fill="${PIN}" font-size="14" font-family="Syne, sans-serif" font-weight="700">${esc(entity.name)}</text>
+      <text x="${at.x}" y="${at.y + 52}" text-anchor="middle" fill="#9aa3b2" font-size="10" font-family="IBM Plex Mono, monospace">${surfaces} read surface${surfaces === 1 ? "" : "s"}</text>
+    </g>`;
+}
+/** One arrow per writer → parent pair. A pair whose entity the run did not test has no pin, so no arrow. */
+function crossArrows(graph, pos) {
+    const pairs = new Map();
+    for (const invalidation of graph.invalidate) {
+        if (!invalidation.cross)
+            continue;
+        pairs.set(`${invalidation.fromEntity}\0${invalidation.toEntity}`, {
+            from: invalidation.fromEntity,
+            to: invalidation.toEntity,
+        });
+    }
+    const labelArrows = graph.entities.length <= 8;
+    return [...pairs.values()].map((pair) => {
+        const from = pos.get(pair.from);
+        const to = pos.get(pair.to);
+        if (from === undefined || to === undefined)
+            return "";
+        const midX = (from.x + to.x) / 2;
+        const lift = from.y === to.y ? 36 : Math.abs(to.y - from.y) / 2 + 16;
+        const midY = Math.min(from.y, to.y) - lift;
+        const label = labelArrows
+            ? `<text x="${midX}" y="${midY - 4}" text-anchor="middle" fill="#ff6b3d" font-size="11" font-family="IBM Plex Mono, monospace">${esc(`${pair.from} → ${pair.to}`)}</text>`
+            : "";
+        return `<path d="M ${from.x} ${from.y - 16} Q ${midX} ${midY}, ${to.x} ${to.y - 16}" fill="none" stroke="#ff6b3d" stroke-width="1.6" marker-end="url(#arrow-cross)"/>${label}`;
+    });
+}
+/** Why the band has no arrows, when it has none. */
+function emptyNote(graph) {
+    if (graph.invalidate.some((l) => l.cross))
+        return "";
+    return `<text x="560" y="36" text-anchor="middle" fill="#9aa3b2" font-size="12" font-family="IBM Plex Mono, monospace">${graph.invalidate.length === 0
+        ? "no x-invalidate edges in this document"
+        : "invalidate stays on the same entity — the cross-entity check did not apply"}</text>`;
+}
+/** The 24 parents with the most writers as bars, and how many entities sit outside every claim. */
+function crowdedBand(graph) {
+    const inbound = new Map();
+    for (const invalidation of graph.invalidate) {
+        if (!invalidation.cross)
+            continue;
+        const list = inbound.get(invalidation.toEntity) ?? [];
+        if (!list.includes(invalidation.fromEntity))
+            list.push(invalidation.fromEntity);
+        inbound.set(invalidation.toEntity, list);
+    }
+    const parents = [...inbound.entries()].sort((a, b) => b[1].length - a[1].length);
+    const max = Math.max(1, ...parents.map(([, w]) => w.length));
+    const rows = parents
+        .slice(0, 24)
+        .map(([parent, writers]) => {
+        const width = Math.max(4, Math.round((writers.length / max) * 240));
+        return `<div class="bar-row">
+        <div class="bar-name">${esc(parent)}</div>
+        <div class="bar-track"><div class="bar-fill" style="width:${width}px"></div></div>
+        <div class="bar-n">${writers.length} writers</div>
+      </div>`;
+    })
+        .join("");
+    const more = parents.length > 24 ? `<div class="bar-more">${parents.length - 24} more parents</div>` : "";
+    const orphans = graph.entities.length - new Set([...inbound.keys(), ...[...inbound.values()].flat()]).size;
+    return `<div class="forest">
+    <p class="forest-lead">${graph.entities.length} entities · ${graph.invalidate.filter((l) => l.cross).length} cross-entity claims · ${parents.length} parents · ${orphans} with no invalidate edge</p>
+    ${rows}${more}
+  </div>`;
+}
+//# sourceMappingURL=band.js.map

package/dist/api/report/matrix/cards.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Entity cards under the band: one per entity with its poster cells as dots, or, for a crowd, one
+ * per entity that disagreed or stood down.
+ */
+import type { MatrixGraph } from "./types.ts";
+export declare function entityCards(graph: MatrixGraph): string;
+/** A crowd's cards: every entity that disagreed, and up to eight that only stood down. */
+export declare function forestSummary(graph: MatrixGraph): string;
+//# sourceMappingURL=cards.d.ts.map

package/dist/api/report/matrix/cards.js

@@ -0,0 +1,41 @@
+/**
+ * Entity cards under the band: one per entity with its poster cells as dots, or, for a crowd, one
+ * per entity that disagreed or stood down.
+ */
+import { NODE_ORDER } from "./catalog.js";
+import { nodeOf } from "./slice.js";
+import { esc, unique } from "./text.js";
+/** Which other entities `entity`'s writes are declared to change. */
+function invalidatesText(graph, entity) {
+    const outbound = graph.invalidate.filter((l) => l.fromEntity === entity.name && l.cross);
+    return outbound.length === 0
+        ? "does not invalidate another entity"
+        : `invalidates ${unique(outbound.map((l) => l.toEntity)).join(", ")}`;
+}
+export function entityCards(graph) {
+    const cards = graph.entities.map((entity) => {
+        const loomDots = NODE_ORDER.map((spec) => `<span class="dot ${nodeOf(entity, spec.id).status}" title="${esc(spec.label)}"></span>`).join("");
+        return `<div class="card">
+      <h2>${esc(entity.name)}</h2>
+      <div class="meta">${entity.identity === null ? "no identity" : `id ${esc(entity.name)}.${esc(entity.identity)}`} · ${entity.readSurface.length} surfaces · ${esc(invalidatesText(graph, entity))}</div>
+      <div class="dots">${loomDots}</div>
+    </div>`;
+    });
+    return `<div class="cards">${cards.join("")}</div>`;
+}
+/** A crowd's cards: every entity that disagreed, and up to eight that only stood down. */
+export function forestSummary(graph) {
+    const failed = graph.entities.filter((e) => e.counts.failed > 0);
+    const blocked = graph.entities.filter((e) => e.counts.blocked > 0 && e.counts.failed === 0);
+    const passed = graph.entities.filter((e) => e.counts.failed === 0 && e.counts.blocked === 0);
+    const cards = [...failed, ...blocked.slice(0, 8)].map((entity) => `<div class="card">
+      <h2>${esc(entity.name)}</h2>
+      <div class="meta">${entity.counts.failed} disagreed · ${entity.counts.blocked} stood down · ${esc(invalidatesText(graph, entity))}</div>
+    </div>`);
+    return `<div class="crowd-note">
+    ${passed.length} entities passed every check that applied.
+    ${failed.length === 0 ? "Showing the detail view for one writer, not all 200 entities." : `Showing ${failed.length} entities that disagreed.`}
+  </div>
+  ${cards.length > 0 ? `<div class="cards">${cards.join("")}</div>` : ""}`;
+}
+//# sourceMappingURL=cards.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * The checks the matrix draws: the poster's cells in order, the composition edges between them, and
+ * every check grouped into the strips the poster lists.
+ */
+import type { MatrixGraphEdge, MatrixLayer } from "./types.ts";
+/** A poster cell: the check it shows, its short label, and what it asks. */
+export interface CellSpec {
+    id: string;
+    label: string;
+    hint: string;
+}
+/** A strip of related checks, the graph group its checks belong to, and the layer that group sits on. */
+export interface Strip {
+    title: string;
+    layer: MatrixLayer;
+    ids: readonly string[];
+}
+export declare const NODE_ORDER: readonly CellSpec[];
+export declare const USES: ReadonlyArray<{
+    from: string;
+    to: string;
+}>;
+export declare const STRIPS: readonly Strip[];
+/** The cataloged checks, each with its strip, what it needs, and the edges between them. */
+export interface CheckCatalog {
+    /** Every check id the matrix tracks, in strip order. */
+    ids: readonly string[];
+    stripOf: ReadonlyMap<string, Strip>;
+    needs: ReadonlyMap<string, string | undefined>;
+    edges: MatrixGraphEdge[];
+}
+export declare function checkCatalog(): CheckCatalog;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/api/report/matrix/catalog.js

@@ -0,0 +1,152 @@
+/**
+ * The checks the matrix draws: the poster's cells in order, the composition edges between them, and
+ * every check grouped into the strips the poster lists.
+ */
+import { entityChecks } from "../../runtime/checks/core/registry.js";
+import { CHECKS } from "../../runtime/checks/registry.js";
+export const NODE_ORDER = [
+    { hint: "create then list", id: "list.read-after-write", label: "list" },
+    { hint: "item GET agrees", id: "consistency.projections-agree", label: "item" },
+    { hint: "id.eq selects one", id: "filter.equality-selects-exactly-one", label: "filter" },
+    { hint: "order rearranges", id: "sort.order-is-applied", label: "sort" },
+    { hint: "sparse fieldset", id: "select.projection-honored", label: "select" },
+    { hint: "q narrows", id: "search.q-narrows-result", label: "search" },
+    { hint: "walk covers set", id: "pagination.page-walk-covers-set", label: "page" },
+    { hint: "other tenant 404", id: "tenant.item-not-readable-cross-tenant", label: "tenant" },
+    { hint: "membership unchanged", id: "query.axes-compose", label: "filter + sort" },
+    { hint: "same rows, fewer fields", id: "query.filter-and-select-compose", label: "filter + select" },
+    { hint: "both predicates hold", id: "query.search-and-filter-compose", label: "filter + search" },
+    { hint: "filter before page", id: "query.filter-selects-from-whole-set", label: "filter / page" },
+    { hint: "three axes at once", id: "query.filter-sort-select-compose", label: "filter + sort + select" },
+    { hint: "three axes at once", id: "query.filter-search-sort-compose", label: "filter + search + sort" },
+    { hint: "three axes at once", id: "query.filter-search-select-compose", label: "filter + search + select" },
+];
+export const USES = [
+    { from: "filter.equality-selects-exactly-one", to: "query.axes-compose" },
+    { from: "sort.order-is-applied", to: "query.axes-compose" },
+    { from: "filter.equality-selects-exactly-one", to: "query.filter-and-select-compose" },
+    { from: "select.projection-honored", to: "query.filter-and-select-compose" },
+    { from: "filter.equality-selects-exactly-one", to: "query.search-and-filter-compose" },
+    { from: "search.q-narrows-result", to: "query.search-and-filter-compose" },
+    { from: "filter.equality-selects-exactly-one", to: "query.filter-selects-from-whole-set" },
+    { from: "pagination.page-walk-covers-set", to: "query.filter-selects-from-whole-set" },
+    { from: "query.axes-compose", to: "query.filter-sort-select-compose" },
+    { from: "query.filter-and-select-compose", to: "query.filter-sort-select-compose" },
+    { from: "query.axes-compose", to: "query.filter-search-sort-compose" },
+    { from: "query.search-and-filter-compose", to: "query.filter-search-sort-compose" },
+    { from: "query.filter-and-select-compose", to: "query.filter-search-select-compose" },
+    { from: "query.search-and-filter-compose", to: "query.filter-search-select-compose" },
+];
+export const STRIPS = [
+    {
+        ids: [
+            "filter.unknown-field-rejected",
+            "filter.equality-selects-exactly-one",
+            "filter.zero-match-returns-none",
+            "filter.negation-partitions-the-set",
+            "filter.and-composes-as-intersection",
+            "filter.or-composes-as-union",
+            "filter.like-metacharacters-escaped",
+            "filter.numeric-comparison-is-numeric",
+            "error.malformed-filter-not-5xx",
+        ],
+        layer: "axis",
+        title: "filter",
+    },
+    { ids: ["sort.order-is-applied", "sort.reverse-symmetry"], layer: "axis", title: "sort" },
+    { ids: ["select.projection-honored"], layer: "axis", title: "select" },
+    { ids: ["search.q-narrows-result"], layer: "axis", title: "search" },
+    {
+        ids: [
+            "pagination.page-walk-covers-set",
+            "pagination.cursor-agrees-with-page",
+            "pagination.limit-bounds-page-size",
+            "pagination.limit-respects-documented-max",
+            "pagination.has-more-is-accurate",
+            "count.consistent-with-returned-page",
+            "count.matches-filtered-set",
+        ],
+        layer: "axis",
+        title: "page / count",
+    },
+    {
+        ids: [
+            "query.axes-compose",
+            "query.filter-and-select-compose",
+            "query.search-and-filter-compose",
+            "query.filter-selects-from-whole-set",
+            "query.filter-sort-select-compose",
+            "query.filter-search-sort-compose",
+            "query.filter-search-select-compose",
+        ],
+        layer: "composition",
+        title: "composition",
+    },
+    {
+        ids: [
+            "spec.declared-filterable-is-filterable",
+            "spec.declared-sortable-is-sortable",
+            "spec.declared-selectable-is-selectable",
+        ],
+        layer: "spec",
+        title: "spec promise",
+    },
+    {
+        ids: [
+            "tenant.item-not-readable-cross-tenant",
+            "tenant.denial-does-not-reveal-existence",
+            "tenant.filter-does-not-bypass-scope",
+            "auth.rank-is-monotonic",
+            "auth.invite-grants-then-revokes",
+        ],
+        layer: "auth",
+        title: "who may see it",
+    },
+    {
+        ids: [
+            "list.read-after-write",
+            "create.persists-submitted-fields",
+            "payload.string-survives",
+            "create.status-matches-document",
+            "response.status-is-documented",
+            "consistency.projections-agree",
+            "softdelete.absent-from-default-list",
+            "invalidation.declared-route-changes",
+            "patch.minimality",
+            "patch.immutable-field-rejected",
+            "idempotency.replay-does-not-duplicate",
+            "delete.absent-record-returns-404",
+            "concurrency.no-lost-update",
+            "effects.declared-effect-occurs",
+            "async.reaches-terminal-state",
+            "async.receipt-identifies-the-job",
+        ],
+        layer: "surface",
+        title: "write / surface",
+    },
+    {
+        ids: [
+            "validation.enum-enforced",
+            "validation.max-length-enforced",
+            "validation.required-enforced",
+            "validation.content-type-enforced",
+            "schema.success-response-matches-document",
+            "schema.error-response-matches-document",
+        ],
+        layer: "schema",
+        title: "schema",
+    },
+];
+export function checkCatalog() {
+    const stripOf = new Map(STRIPS.flatMap((strip) => strip.ids.map((id) => [id, strip])));
+    return {
+        edges: [
+            ...entityChecks(CHECKS).flatMap((check) => (check.dependsOn ?? []).map((dep) => ({ from: dep, kind: "dependsOn", to: check.id }))),
+            ...USES.map((use) => ({ ...use, kind: "uses" })),
+        ],
+        ids: [...stripOf.keys()],
+        needs: new Map(CHECKS.map((check) => [check.id, check.needs])),
+        stripOf,
+    };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/api/report/matrix/graph.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The machine graph of a run's matrix: every entity's slice, the `x-invalidate` links between
+ * entities, the check edges, and how to read them.
+ */
+import type { MatrixGraph, MatrixParts, MatrixReport } from "./types.ts";
+/** One entity's graph, given piece by piece. */
+export declare function buildMatrixGraph(parts: MatrixParts): MatrixGraph;
+/** Every entity the run tested; a report that tested none draws one placeholder `entity`. */
+export declare function buildMatrixGraphFromReport(input: MatrixReport): MatrixGraph;
+/** Drop per-check nodes for clean entities so a 2k-entity graph stays loadable. */
+export declare function compactMatrixGraph(graph: MatrixGraph): MatrixGraph;
+/** The graph as the run folder's `matrix.json`: compacted, two-space indented, newline-terminated. */
+export declare function graphJson(graph: MatrixGraph): string;
+export declare function renderMatrixGraph(input: MatrixReport): string;
+export declare function renderMatrixGraphFromParts(parts: MatrixParts): string;
+//# sourceMappingURL=graph.d.ts.map