@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/config/types/steps.d.ts

@@ -0,0 +1,166 @@
+interface StepBase {
+    /**
+     * Binds parts of the response into the flow's scope. Later steps interpolate them as
+     * `{name}`, and `rootsFromFlow` can promote them to path parameters.
+     *
+     * Address forms:
+     * - `$.access_token` / `$.orgs.0.id` — JSON body (dot + numeric index only)
+     * - `cookie:<name>` — that cookie on `Set-Cookie` for this hop (and followed hops)
+     * - `header:<name>` — a non-set-cookie response header, case-insensitive
+     *
+     * Missing cookie / header / JSON path fails the auth step closed.
+     */
+    saveAs?: Record<string, string>;
+    /**
+     * Binds values out of a JWT's claims. Tenancy commonly rides in the token rather than the
+     * response body, and a principal that can name its own tenant needs no roots configured. The
+     * signature is not verified — the API tester is reading its own credential, not trusting a third party.
+     * `token` is a JSON path into the response body (`$.access_token`) or a scope key already
+     * bound by `saveAs` (`credential`).
+     */
+    saveClaimsFrom?: {
+        token: string;
+        bind: Record<string, string>;
+    };
+    /** Literal values bound before the step runs, with `{name}` interpolation. */
+    bind?: Record<string, string>;
+    /** Accepted statuses. Defaults to any 2xx. */
+    expect?: number[];
+}
+/** Calls an operation named in the document. Prefer this — it survives the path moving. */
+export interface OperationStep extends StepBase {
+    operationId: string;
+    body?: unknown;
+    /** One of the request media types the operation documents. Default: the API tester's preferred one. */
+    mediaType?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    /** Named `origins[]` entry. Omit to hit the primary `baseUrl`. */
+    origin?: string;
+}
+/** Calls a raw path, for endpoints the document does not describe. */
+export interface RequestStep extends StepBase {
+    method: string;
+    /**
+     * Path relative to this origin's `baseUrl`, or an absolute `http://` / `https://` URL.
+     * Absolute URLs are not joined to `baseUrl` — that is how a consume page on the app origin
+     * is a recorded hop when the spec origin is the API.
+     */
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    /** Named `origins[]` entry. Omit to hit the primary `baseUrl`. Ignored for absolute URLs. */
+    origin?: string;
+    /**
+     * Redirect policy for this hop. Default `follow` uses a per-request cookie jar so a 303
+     * that sets `Set-Cookie` still leaves that cookie visible to `saveAs`. `manual` stops at
+     * the first 3xx (`expect: [303]` then reads cookies from that response).
+     */
+    redirect?: "follow" | "manual";
+}
+/**
+ * A value that never travels over HTTP — an emailed verification token, an OTP, a magic link.
+ *
+ * The API tester declares the need and calls `hooks.resolveOutOfBand` to satisfy it, polling with backoff
+ * because such stores are usually eventually consistent. That hook is the entire coupling
+ * surface between the API tester and one specific backend. The hook returns a string (a token, or the
+ * mailed URL); the API tester records the consume hop only when a later RequestStep GETs that URL.
+ */
+export interface OutOfBandStep {
+    outOfBand: {
+        address: string;
+        kind: string;
+        as: string;
+        /**
+         * The value was sent before this scenario or flow began — by a schedule, or into a seeded
+         * inbox — so no request here triggered it and the hook gets no `since`.
+         */
+        sentEarlier?: boolean;
+    };
+}
+export type AuthStep = OperationStep | RequestStep | OutOfBandStep;
+/**
+ * The value at `from` in a step's response must equal, contain, or no longer hold the text after
+ * `{name}` interpolation. `from` is a JSON path; `[*]` fans out over an array, so
+ * `$.items[*].name` passes when any item's name matches.
+ */
+export interface ScenarioAssert {
+    from: string;
+    equals?: string;
+    contains?: string;
+    /** The value must no longer appear at `from` — a removal, proven by a later read. */
+    excludes?: string;
+    /**
+     * No node at `from` may contain this text, an object's JSON text included: what a response must
+     * never carry (`'"token":'` is a key named `token` at any depth). No node at all passes.
+     */
+    omits?: string;
+    /**
+     * The number at `from` must be at least this. A count read from a sampled or eventually
+     * consistent store (a usage chart, an analytics total) promises a floor, not an exact value.
+     */
+    atLeast?: number;
+    /**
+     * Earlier operations this read proves. A passing assert marks each one `verified`, with this
+     * exchange as the observation. The step's own operation always counts.
+     */
+    observes?: string[];
+}
+/** A request in a scenario: an `OperationStep` or `RequestStep`, plus what to check. */
+export type ScenarioRequestStep = (OperationStep | RequestStep) & {
+    /** What the response must show; a list must all hold on the same exchange. */
+    assert?: ScenarioAssert | ScenarioAssert[];
+    /** Re-send until the assert passes or `within` (`"30s"`, `"500ms"`, `"2m"`) runs out. */
+    poll?: {
+        within: string;
+        everyMs?: number;
+    };
+    /** Send with no credential at all. */
+    anonymous?: boolean;
+    /** Send as this config principal instead of the scenario's — an invitee accepting, a peer reading. */
+    principal?: string;
+    /**
+     * Send only this scheme's credential, e.g. `apiKey` on an operation that also takes a session.
+     * Default: the first alternative of the operation's security the principal can satisfy.
+     */
+    scheme?: string;
+};
+/**
+ * Something only a person or a browser can do — pay with a test card, give OAuth consent.
+ * The API tester calls `hooks.external(name, input)` and binds the string it returns to `as`.
+ */
+export interface ExternalStep {
+    external: string;
+    input?: Record<string, unknown>;
+    as: string;
+}
+export type ScenarioStep = ScenarioRequestStep | OutOfBandStep | ExternalStep;
+/** What the scenario `external` steps need from the machine that runs them, so a profile can leave them out. */
+export interface ExternalsConfig {
+    /**
+     * Each external's kind by name, in your own words (`"device"`, `"headless"`). A profile's
+     * `excludeExternalKinds` skips a scenario whose step names an external of an excluded kind.
+     */
+    kinds?: Record<string, string>;
+}
+/**
+ * A declared flow for operations the matrix cannot reach on its own: steps run in order as one
+ * principal, values flow forward through `{name}`, and each operation in `covers` is graded by
+ * what the steps observed. Product knowledge lives here, in the config — not in the API tester.
+ */
+export interface Scenario {
+    id: string;
+    /** Operations this scenario grades. Each must be called by one of its steps. */
+    covers: string[];
+    /** Config principal whose credential the steps send. Default: the writer (`writer`, else the first principal). */
+    principal?: string;
+    /**
+     * A configured origin this scenario belongs to: its steps and `covers` are that origin's
+     * operations, and it runs where that origin is graded. Default: the main document.
+     */
+    origin?: string;
+    steps: ScenarioStep[];
+}
+export {};
+//# sourceMappingURL=steps.d.ts.map

package/dist/api/config/types/steps.js

@@ -0,0 +1,3 @@
+/* The steps a sign-in flow or a scenario runs: operation calls, raw requests, out-of-band waits. */
+export {};
+//# sourceMappingURL=steps.js.map

package/dist/api/config/validate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The config, checked before anything runs.
+ *
+ * A misspelled key used to be ignored and a wrong type used to flow into the run — a
+ * `maxInFlight` of `"8"` silently became the default, a `cohortSize` of `0` seeded nothing. Each
+ * problem names the key path and what it should be, and the CLI exits 2 without sending a request.
+ */
+type Rule = (value: unknown, path: string) => string[];
+/** The rule for each top-level config key; its keys are the config keys the API tester knows. */
+export declare function configRules(): Record<string, Rule>;
+/** Every problem with `config`, by key path. `run` needs a spec, a base URL and a principal. */
+export declare function configProblems(config: unknown, options?: {
+    forRun?: boolean;
+}): string[];
+export {};
+//# sourceMappingURL=validate.d.ts.map

package/dist/api/config/validate.js

@@ -0,0 +1,176 @@
+/**
+ * The config, checked before anything runs.
+ *
+ * A misspelled key used to be ignored and a wrong type used to flow into the run — a
+ * `maxInFlight` of `"8"` silently became the default, a `cohortSize` of `0` seeded nothing. Each
+ * problem names the key path and what it should be, and the CLI exits 2 without sending a request.
+ */
+import { CREDENTIAL_HEADERS } from "../security/credential-names.js";
+import { principalMapProblems, REMOVED_KEYS, removedProblems } from "../credentials/validate/principals.js";
+import { scenarioPlaceholderProblems } from "../credentials/validate/scenario-placeholders.js";
+import { securityMapProblems } from "../credentials/validate/security.js";
+import { isRaw, isRecord } from "./types/raw.js";
+const string = (value, path) => (typeof value === "string" ? [] : [`${path} must be a string`]);
+const boolean = (value, path) => (typeof value === "boolean" ? [] : [`${path} must be true or false`]);
+const object = (value, path) => value !== null && typeof value === "object" && !Array.isArray(value) ? [] : [`${path} must be an object`];
+/* An object whose named keys, when set, hold functions; the rest are not checked here. */
+const functionsAt = (...keys) => (value, path) => {
+    const notObject = object(value, path);
+    if (notObject.length > 0)
+        return notObject;
+    const record = value;
+    return keys
+        .filter((key) => record[key] !== undefined && typeof record[key] !== "function")
+        .map((key) => `${path}.${key} must be a function`);
+};
+const integer = (min) => (value, path) => Number.isSafeInteger(value) && value >= min
+    ? []
+    : [`${path} must be an integer${min >= 0 ? ` of at least ${min}` : ""}`];
+const positive = (value, path) => typeof value === "number" && Number.isFinite(value) && value > 0 ? [] : [`${path} must be a number above 0`];
+const oneOf = (...allowed) => (value, path) => allowed.includes(value) ? [] : [`${path} must be one of ${allowed.map((a) => `"${a}"`).join(", ")}`];
+const arrayOf = (item) => (value, path) => Array.isArray(value)
+    ? value.flatMap((entry, index) => item(entry, `${path}[${index}]`))
+    : [`${path} must be an array`];
+const recordOf = (item) => (value, path) => object(value, path).length > 0
+    ? object(value, path)
+    : Object.entries(value).flatMap(([key, entry]) => item(entry, `${path}.${key}`));
+const shape = (fields, required = []) => (value, path) => {
+    const notObject = object(value, path);
+    if (notObject.length > 0)
+        return notObject;
+    const record = value;
+    const problems = [];
+    for (const key of required)
+        if (record[key] === undefined)
+            problems.push(`${path}.${key} is required`);
+    for (const [key, entry] of Object.entries(record)) {
+        const rule = fields[key];
+        if (rule === undefined)
+            problems.push(`${path}.${key} is not a config key`);
+        else if (entry !== undefined)
+            problems.push(...rule(entry, `${path}.${key}`));
+    }
+    return problems;
+};
+/* A profile: the kinds it excludes, when set, are strings. Its other fields are read where the run uses them. */
+const profile = (value, path) => {
+    const notObject = object(value, path);
+    if (notObject.length > 0)
+        return notObject;
+    const kinds = value["excludeExternalKinds"];
+    return kinds === undefined ? [] : arrayOf(string)(kinds, `${path}.excludeExternalKinds`);
+};
+/* A key checked as a whole by its own validator in `credentialProblems`, which reads other keys too. */
+const checkedWhole = () => [];
+const objectOrNull = (value, path) => value === null || isRecord(value) ? [] : [`${path} must be an object or null`];
+/**
+ * Patches by operationId and by schema name, each an object merged into the document; security
+ * schemes to merge (`null` deletes one), and the root security requirement.
+ */
+function overlayRule() {
+    return shape({
+        operations: recordOf(object),
+        schemas: recordOf(object),
+        security: arrayOf(recordOf(arrayOf(string))),
+        securitySchemes: recordOf(objectOrNull),
+    });
+}
+/** The rule for each top-level config key; its keys are the config keys the API tester knows. */
+export function configRules() {
+    const overlay = overlayRule();
+    return {
+        baseUrl: string,
+        cache: shape({ bypass: boolean }),
+        /* Opt-in checks by id: an unknown id is named, so a misspelled switch never reads as off. */
+        checks: shape({ "auth.login-throttled": boolean }),
+        cohortSize: integer(1),
+        entities: recordOf(object),
+        externals: shape({ kinds: recordOf(string) }),
+        globalHeaders: recordOf(string),
+        hooks: functionsAt("verifyRemoved", "resolveCredential"),
+        keepFixtures: boolean,
+        maxInFlight: integer(1),
+        maxRps: positive,
+        network: shape({
+            maxRetryAfterMs: integer(0),
+            requestTimeoutMs: integer(0),
+            retries: integer(0),
+            waitMs: integer(0),
+        }),
+        only: arrayOf(string),
+        ops: arrayOf(string),
+        origins: arrayOf(shape({ baseUrl: string, id: string, maxRps: positive, overlay, security: recordOf(string), spec: string }, [
+            "baseUrl",
+            "id",
+            "spec",
+        ])),
+        overlay,
+        allow: arrayOf(string),
+        fence: shape({ failRun: boolean }),
+        teardown: shape({ verify: boolean }),
+        baseline: string,
+        targetVersion: shape({ from: string, operationId: string, path: string, scheme: string }, ["from"]),
+        outDir: string,
+        outOfBand: shape({ attempts: integer(1), initialMs: integer(0), maxMs: integer(0) }),
+        payloads: oneOf("full", "per-write-path"),
+        principals: checkedWhole,
+        profile: string,
+        profiles: recordOf(profile),
+        query: object,
+        rateLimits: arrayOf(object),
+        redact: shape({ headers: arrayOf(string) }),
+        saveExchanges: boolean,
+        scenarios: arrayOf(object),
+        security: checkedWhole,
+        seed: integer(Number.MIN_SAFE_INTEGER),
+        spec: string,
+        uploads: object,
+        writer: string,
+    };
+}
+const CREDENTIAL_HEADER = "a credential is sent by its scheme; declare security.<scheme>";
+const REMOVED_HOOKS = {
+    resolvePrincipalAuth: "declare security.<scheme>: { hook: true } and return the credential from hooks.resolveCredential",
+};
+/* Keys a 0.25.0 credential recipe replaced: a credential header in globalHeaders, a hook no recipe calls. */
+function carrierProblems(config) {
+    const headers = isRecord(config.globalHeaders) ? Object.keys(config.globalHeaders) : [];
+    const hooks = isRaw(config.hooks) ? config.hooks : {};
+    return [
+        ...headers
+            .filter((name) => CREDENTIAL_HEADERS.has(name.toLowerCase()))
+            .map((name) => `globalHeaders.${name} was removed in 0.25.0: ${CREDENTIAL_HEADER}`),
+        ...Object.entries(REMOVED_HOOKS)
+            .filter(([name]) => name in hooks)
+            .map(([name, replacement]) => `hooks.${name} was removed in 0.25.0: ${replacement}`),
+    ];
+}
+/* A writer that names no principal: the run would write as someone the config does not declare. */
+function writerProblems(config) {
+    const { principals, writer } = config;
+    if (typeof writer !== "string" || !isRecord(principals) || writer in principals)
+        return [];
+    return [`writer names no principal: "${writer}" (principals: ${Object.keys(principals).join(", ")})`];
+}
+/* The credentials config, by the validators that also run against the document, minus what needs it. */
+function credentialProblems(config) {
+    return [
+        ...(config.principals === undefined ? [] : principalMapProblems(config)),
+        ...writerProblems(config),
+        ...securityMapProblems(config),
+        ...removedProblems(config),
+        ...carrierProblems(config),
+        ...scenarioPlaceholderProblems(config),
+    ];
+}
+/** Every problem with `config`, by key path. `run` needs a spec, a base URL and a principal. */
+export function configProblems(config, options = {}) {
+    const required = options.forRun === true ? ["spec", "baseUrl", "principals"] : [];
+    const rules = shape(configRules(), required);
+    if (!isRecord(config))
+        return rules(config, "config");
+    /* A removed key is named with its replacement below, not as a key the API tester does not know. */
+    const current = Object.fromEntries(Object.entries(config).filter(([key]) => !REMOVED_KEYS.includes(key)));
+    return [...rules(current, "config"), ...credentialProblems(config).map((problem) => `config.${problem}`)];
+}
+//# sourceMappingURL=validate.js.map

package/dist/api/conformance/effects/backend.d.ts

@@ -0,0 +1,7 @@
+/** The effects suite's backend: tables in a project, and an extract that makes a table of `rowCount` rows. */
+import type { Handle } from "../../reference/http/node.ts";
+/** The bearer token the extract backend issues, and the only one it accepts. */
+export declare const EXTRACT_TOKEN = "t";
+/** The backend behind its declared bearer: a table list, create and read, row lists, and the extract. */
+export declare function extractBackend(rowCount: number): Handle;
+//# sourceMappingURL=backend.d.ts.map

package/dist/api/conformance/effects/backend.js

@@ -0,0 +1,56 @@
+/** The effects suite's backend: tables in a project, and an extract that makes a table of `rowCount` rows. */
+import { routed } from "../harness/routes.js";
+import { bearerGuarded } from "../harness/security.js";
+import { answer, guarded, readJson } from "../harness/serve.js";
+import { extractSpec } from "./spec.js";
+/** The bearer token the extract backend issues, and the only one it accepts. */
+export const EXTRACT_TOKEN = "t";
+/** The backend behind its declared bearer: a table list, create and read, row lists, and the extract. */
+export function extractBackend(rowCount) {
+    const spec = extractSpec();
+    /* A table and its rows are made together, so a table never lacks its row list. */
+    const tables = new Map();
+    let seq = 0;
+    const make = (name, rows) => {
+        const id = `t_${String((seq += 1))}`;
+        const table = { id, name, table_id: id };
+        tables.set(id, { rows: rows(id), table });
+        return table;
+    };
+    const list = /^\/v1\/projects\/([^/]+)\/tables$/;
+    const routes = routed([
+        { method: "GET", path: /^\/v1\/openapi\/spec$/, reply: () => answer(200, spec) },
+        { method: "GET", path: list, reply: () => answer(200, { tables: [...tables.values()].map((t) => t.table) }) },
+        {
+            method: "POST",
+            path: list,
+            reply: async (_, request) => {
+                const body = (await readJson(request));
+                return answer(201, make(typeof body?.name === "string" ? body.name : "n", () => []));
+            },
+        },
+        {
+            method: "GET",
+            path: /^\/v1\/projects\/[^/]+\/tables\/([^/]+)$/,
+            reply: (id) => {
+                const found = tables.get(decodeURIComponent(id));
+                return found === undefined ? answer(404) : answer(200, found.table);
+            },
+        },
+        {
+            method: "GET",
+            path: /^\/v1\/projects\/[^/]+\/tables\/([^/]+)\/rows$/,
+            reply: (id) => {
+                const found = tables.get(decodeURIComponent(id));
+                return found === undefined ? answer(404) : answer(200, { rows: found.rows });
+            },
+        },
+        {
+            method: "POST",
+            path: /^\/v1\/projects\/([^/]+)\/extract$/,
+            reply: () => answer(200, make("extracted", (id) => Array.from({ length: rowCount }, (_, i) => ({ id: `r_${id}_${String(i + 1)}`, table_id: id })))),
+        },
+    ]);
+    return guarded(bearerGuarded(routes, EXTRACT_TOKEN));
+}
+//# sourceMappingURL=backend.js.map

package/dist/api/conformance/effects/spec.d.ts

@@ -0,0 +1,4 @@
+/** The effects suite's document: tables in a project, their rows, and one extract that makes both. */
+import type { OpenApiDocument } from "../../spec/types.ts";
+export declare function extractSpec(): OpenApiDocument;
+//# sourceMappingURL=spec.d.ts.map

package/dist/api/conformance/effects/spec.js

@@ -0,0 +1,90 @@
+/** The effects suite's document: tables in a project, their rows, and one extract that makes both. */
+import { bearerSecurity } from "../harness/security.js";
+const TABLE = {
+    properties: { id: { type: "string" }, name: { type: "string" }, table_id: { type: "string" } },
+    required: ["id", "name"],
+    type: "object",
+};
+const ROW = {
+    properties: { id: { type: "string" }, table_id: { type: "string" } },
+    required: ["id", "table_id"],
+    type: "object",
+};
+const json = (schema) => ({ content: { "application/json": { schema } } });
+const param = (name) => ({ in: "path", name, required: true, schema: { type: "string" } });
+const entity = (action, name) => ({ "x-entity": { action, identity: "id", name } });
+/** A 200 whose body lists `items` of `item` under `key`. */
+function listed(key, item) {
+    return {
+        "200": {
+            ...json({ properties: { [key]: { items: item, type: "array" } }, required: [key], type: "object" }),
+            description: "ok",
+        },
+    };
+}
+const PROJECT = [/* @__PURE__ */ param("project_id")];
+const TABLE_IN_PROJECT = [/* @__PURE__ */ param("project_id"), /* @__PURE__ */ param("table_id")];
+function tables() {
+    return {
+        get: {
+            operationId: "table.list",
+            parameters: PROJECT,
+            responses: listed("tables", TABLE),
+            ...entity("list", "table"),
+        },
+        post: {
+            operationId: "table.create",
+            parameters: PROJECT,
+            requestBody: {
+                ...json({ properties: { name: { type: "string" } }, required: ["name"], type: "object" }),
+                required: true,
+            },
+            responses: { "201": { ...json(TABLE), description: "created" } },
+            ...entity("create", "table"),
+        },
+    };
+}
+/** The extract: one write that creates a table and appends at least one row to it, then waits for the rows. */
+function extract() {
+    return {
+        post: {
+            operationId: "extract.once",
+            parameters: PROJECT,
+            responses: { "200": { ...json(TABLE), description: "ok" } },
+            "x-effects": [
+                { entity: "table", op: "create" },
+                { entity: "row", min: 1, op: "append" },
+            ],
+            ...entity("action", "table"),
+            "x-wait": { operationId: "row.list", pollIntervalMs: 40, timeoutMs: 800, until: "$.rows.0" },
+        },
+    };
+}
+export function extractSpec() {
+    return {
+        info: { title: "extract-effects", version: "1" },
+        openapi: "3.1.0",
+        paths: {
+            "/v1/projects/{project_id}/tables": tables(),
+            "/v1/projects/{project_id}/tables/{table_id}": {
+                get: {
+                    operationId: "table.read",
+                    parameters: TABLE_IN_PROJECT,
+                    responses: { "200": { ...json(TABLE), description: "ok" } },
+                    ...entity("read", "table"),
+                },
+            },
+            "/v1/projects/{project_id}/tables/{table_id}/rows": {
+                get: {
+                    operationId: "row.list",
+                    parameters: TABLE_IN_PROJECT,
+                    responses: listed("rows", ROW),
+                    ...entity("list", "row"),
+                },
+            },
+            "/v1/projects/{project_id}/extract": extract(),
+        },
+        ...bearerSecurity(),
+    };
+}
+//# sourceMappingURL=spec.js.map

package/dist/api/conformance/effects.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extract-shaped `x-effects`: one write creates a parent and appends a data-dependent child list.
+ *
+ * Nested observe must bind the new parent id (response `table_id` / identity, or the list delta).
+ * `min` is at-least — empty child list fails, five rows pass. `count` + `min` is rejected at load.
+ */
+import { type Via } from "./harness/launch.ts";
+import type { ParserResult } from "./harness/result.ts";
+export declare function runEffectsSuite(via?: Via): Promise<ParserResult[]>;
+//# sourceMappingURL=effects.d.ts.map

package/dist/api/conformance/effects.js

@@ -0,0 +1,97 @@
+/**
+ * Extract-shaped `x-effects`: one write creates a parent and appends a data-dependent child list.
+ *
+ * Nested observe must bind the new parent id (response `table_id` / identity, or the list delta).
+ * `min` is at-least — empty child list fails, five rows pass. `count` + `min` is rejected at load.
+ */
+import { messageOf } from "../errors/message.js";
+import { run } from "./harness/counting.js";
+import { buildModel } from "../spec/graph/build.js";
+import { readEffects } from "../spec/extensions/effects.js";
+import { GapCollector } from "../spec/extensions/gaps.js";
+import { EXTRACT_TOKEN, extractBackend } from "./effects/backend.js";
+import { extractSpec } from "./effects/spec.js";
+import { listening, reach } from "./harness/launch.js";
+const DECLARED = "effects.declared-effect-occurs";
+const isBug = (check) => (finding) => finding.check === check && finding.verdict === "BACKEND_BUG";
+const CASES = [
+    {
+        judge: ({ findings }) => {
+            const effectBug = findings.find(isBug(DECLARED));
+            return {
+                detail: effectBug === undefined
+                    ? `no effect finding; findings=${findings.map((f) => `${f.verdict}:${f.check}`).join(",") || "none"}`
+                    : effectBug.detail,
+                /* "row" in either text: the space between them cannot make one. */
+                ok: effectBug !== undefined && `${effectBug.detail} ${effectBug.summary}`.includes("row"),
+            };
+        },
+        name: "extract with an empty row list fails min: 1",
+        rowCount: 0,
+        why: "nested row list after table create must be observed",
+    },
+    {
+        judge: ({ findings }) => {
+            const effectBug = findings.find((finding) => finding.check === DECLARED);
+            const waitBug = findings.find(isBug("effects.side-effect-arrives"));
+            const ok = effectBug === undefined && waitBug === undefined;
+            return {
+                detail: ok
+                    ? "no effect/wait findings"
+                    : `effects=${effectBug?.detail ?? "none"}; wait=${waitBug?.detail ?? "none"}`,
+                ok,
+            };
+        },
+        name: "extract with 5 rows passes min: 1",
+        rowCount: 5,
+        why: "bound table_id must fill the nested row list and x-wait",
+    },
+];
+/** `count` and `min` on one effect: dropped with a gap at load, while the suite's own `min` is kept. */
+function contradictionCase() {
+    const gaps = new GapCollector();
+    const both = readEffects({ responses: {}, "x-effects": [{ count: 1, entity: "row", min: 1, op: "append" }] }, "extract.once", gaps);
+    const effects = buildModel(extractSpec())
+        .operations.filter((op) => op.operationId === "extract.once")
+        .flatMap((op) => op.effects);
+    return {
+        detail: `read=${JSON.stringify(both)} gaps=${JSON.stringify(gaps.gaps)} modeled=${JSON.stringify(effects)}`,
+        name: "count and min together are rejected at load",
+        ok: both.length === 0 &&
+            gaps.gaps.some((gap) => gap.tag === "x-effects" && gap.detail.includes("count and min")) &&
+            effects.some((effect) => effect.entity === "row" && effect.min === 1 && effect.count === undefined),
+        why: "doctor / readEffects must not keep a contradictory item",
+    };
+}
+async function runExtract(via, rowCount) {
+    const hosted = await via.host(extractBackend(rowCount));
+    try {
+        return await run({
+            baseUrl: hosted.url,
+            cohortSize: 1,
+            only: ["table"],
+            principals: { alpha: { scope: { project_id: "p1" }, tenant: "p1" } },
+            security: { bearer: { static: EXTRACT_TOKEN } },
+            seed: 1,
+            spec: `${hosted.url}/v1/openapi/spec`,
+            ...reach(hosted),
+        });
+    }
+    finally {
+        await hosted.close();
+    }
+}
+export async function runEffectsSuite(via = listening) {
+    const results = [contradictionCase()];
+    for (const { judge, name, rowCount, why } of CASES) {
+        try {
+            const { detail, ok } = judge(await runExtract(via, rowCount));
+            results.push({ detail, name, ok, why });
+        }
+        catch (error) {
+            results.push({ detail: messageOf(error), name, ok: false, why });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=effects.js.map

package/dist/api/conformance/expected/composition.d.ts

@@ -0,0 +1,8 @@
+import type { DefectName } from "../../reference/defects/table.ts";
+import type { FindingId } from "../../runtime/check-ids.ts";
+/** The defects with a row in the composition family; a name that is not a defect falls out and fails its row. */
+type CompositionDefect = Extract<DefectName, "FILTER_AFTER_PAGINATION" | "FILTER_DROPPED_WHEN_SORTED" | "FILTER_DROPPED_WHEN_SELECTED" | "FILTER_DROPPED_WHEN_SEARCHED" | "FILTER_DROPPED_WHEN_SORTED_AND_SELECTED" | "FILTER_DROPPED_WHEN_SORTED_AND_SEARCHED" | "FILTER_DROPPED_WHEN_SEARCHED_AND_SELECTED" | "FILTER_DROPPED_WHEN_SORTED_SEARCHED_AND_SELECTED" | "SEARCH_DROPPED_WHEN_SELECTED" | "SEARCH_DROPPED_WHEN_SORTED" | "ORDER_DROPPED_WHEN_SELECTED" | "UNKNOWN_PARAM_EMPTIES_LIST">;
+/** The defects whose primary check is in the composition family, and the check each must trip. */
+export declare const COMPOSITION_EXPECTED: Record<CompositionDefect, FindingId | FindingId[]>;
+export {};
+//# sourceMappingURL=composition.d.ts.map