@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/conformance/seed-contract/members.js

@@ -0,0 +1,145 @@
+/**
+ * An invite-only member API: `org.inviteMember` is how a member comes to exist, so it must stay
+ * on `entity.invite` and never be seeded as `POST /things` with a generated email.
+ */
+import { bearerSecurity } from "../harness/security.js";
+import { answer, guarded, readJson } from "../harness/serve.js";
+const MEMBER = {
+    properties: { email: { format: "email", type: "string" }, id: { type: "string" } },
+    required: ["id", "email"],
+    type: "object",
+};
+const ORG_ID = { in: "path", name: "org_id", required: true, schema: { type: "string" } };
+function list() {
+    return {
+        operationId: "member.list",
+        parameters: [ORG_ID],
+        responses: {
+            "200": {
+                content: {
+                    "application/json": {
+                        schema: {
+                            properties: { members: { items: MEMBER, type: "array" } },
+                            required: ["members"],
+                            type: "object",
+                        },
+                    },
+                },
+                description: "ok",
+            },
+        },
+        "x-entity": { action: "list", identity: "id", name: "member" },
+    };
+}
+const INVITE = {
+    accept: "invite.accept",
+    grantPointer: "$.grant_id",
+    granteeField: "invite_email",
+    invite: "org.inviteMember",
+    revoke: "invite.revoke",
+    tokenPointer: "$.token",
+};
+function invite() {
+    return {
+        operationId: "org.inviteMember",
+        parameters: [ORG_ID],
+        requestBody: {
+            content: {
+                "application/json": {
+                    schema: {
+                        properties: { invite_email: { format: "email", type: "string" } },
+                        required: ["invite_email"],
+                        type: "object",
+                    },
+                },
+            },
+            required: true,
+        },
+        responses: {
+            "201": {
+                content: {
+                    "application/json": {
+                        schema: {
+                            properties: { grant_id: { type: "string" }, token: { type: "string" } },
+                            required: ["grant_id", "token"],
+                            type: "object",
+                        },
+                    },
+                },
+                description: "invited",
+            },
+        },
+        "x-entity": { action: "create", identity: "id", name: "member" },
+        "x-invite": INVITE,
+    };
+}
+/* The invite's accept and revoke steps. */
+function grantPaths() {
+    return {
+        "/v1/invites/{token}/accept": {
+            post: {
+                operationId: "invite.accept",
+                parameters: [{ in: "path", name: "token", required: true, schema: { type: "string" } }],
+                responses: { "200": { description: "ok" } },
+                "x-entity": { action: "action", identity: "id", name: "member" },
+            },
+        },
+        "/v1/orgs/{org_id}/grants/{grant_id}": {
+            delete: {
+                operationId: "invite.revoke",
+                parameters: [ORG_ID, { in: "path", name: "grant_id", required: true, schema: { type: "string" } }],
+                responses: { "200": { description: "ok" } },
+                "x-entity": { action: "action", identity: "id", name: "member" },
+            },
+        },
+    };
+}
+export function memberSpec() {
+    return {
+        info: { title: "invite-only", version: "1" },
+        openapi: "3.1.0",
+        paths: {
+            "/v1/orgs/{org_id}/members": { get: list(), post: invite() },
+            "/v1/orgs/{org_id}/members/{member_id}": {
+                get: {
+                    operationId: "member.read",
+                    parameters: [ORG_ID, { in: "path", name: "member_id", required: true, schema: { type: "string" } }],
+                    responses: { "200": { content: { "application/json": { schema: MEMBER } }, description: "ok" } },
+                    "x-entity": { action: "read", identity: "id", name: "member" },
+                },
+            },
+            ...grantPaths(),
+        },
+        ...bearerSecurity(),
+    };
+}
+export function memberBackend() {
+    const spec = memberSpec();
+    const inviteBodies = [];
+    const seedBodies = [];
+    const handle = async (request) => {
+        const { pathname } = request.url;
+        const { method } = request;
+        if (pathname === "/v1/openapi/spec" && method === "GET")
+            return answer(200, spec);
+        if (pathname === "/v1/orgs/org_1/members" && method === "GET")
+            return answer(200, { members: [] });
+        if (pathname === "/v1/orgs/org_1/members" && method === "POST") {
+            const body = await readJson(request);
+            inviteBodies.push(body);
+            const email = body?.invite_email;
+            if (typeof email === "string" && !email.includes("@")) {
+                seedBodies.push(body);
+                return answer(400, { error: "invalid email" });
+            }
+            return answer(201, { grant_id: "g1", token: "tok" });
+        }
+        if (pathname === "/v1/invites/tok/accept" && method === "POST")
+            return answer(200, { ok: true });
+        if (pathname === "/v1/orgs/org_1/grants/g1" && method === "DELETE")
+            return answer(200, { ok: true });
+        return answer(404);
+    };
+    return { handle: guarded(handle), inviteBodies, seedBodies };
+}
+//# sourceMappingURL=members.js.map

package/dist/api/conformance/seed-contract/project.d.ts

@@ -0,0 +1,11 @@
+/** A project API whose `extract.once` is paid inference: `--profile cheap` must never POST it. */
+import type { Handle } from "../../reference/http/node.ts";
+import type { OpenApiDocument } from "../../spec/types.ts";
+export declare function projectSpec(): OpenApiDocument;
+/** The project API, and how many times its paid extract was invoked. */
+export interface ProjectBackend {
+    handle: Handle;
+    extractHits: () => number;
+}
+export declare function projectBackend(): ProjectBackend;
+//# sourceMappingURL=project.d.ts.map

package/dist/api/conformance/seed-contract/project.js

@@ -0,0 +1,113 @@
+/** A project API whose `extract.once` is paid inference: `--profile cheap` must never POST it. */
+import { bearerSecurity } from "../harness/security.js";
+import { answer, guarded, readJson } from "../harness/serve.js";
+const PROJECT = {
+    properties: { id: { type: "string" }, name: { type: "string" } },
+    required: ["id", "name"],
+    type: "object",
+};
+const PROJECT_ID = { in: "path", name: "project_id", required: true, schema: { type: "string" } };
+function collection() {
+    return {
+        get: {
+            operationId: "project.list",
+            responses: {
+                "200": {
+                    content: {
+                        "application/json": {
+                            schema: {
+                                properties: { projects: { items: PROJECT, type: "array" } },
+                                required: ["projects"],
+                                type: "object",
+                            },
+                        },
+                    },
+                    description: "ok",
+                },
+            },
+            "x-entity": { action: "list", identity: "id", name: "project" },
+        },
+        post: {
+            operationId: "project.create",
+            requestBody: {
+                content: {
+                    "application/json": {
+                        schema: { properties: { name: { type: "string" } }, required: ["name"], type: "object" },
+                    },
+                },
+                required: true,
+            },
+            responses: {
+                "201": { content: { "application/json": { schema: PROJECT } }, description: "created" },
+            },
+            "x-entity": { action: "create", identity: "id", name: "project" },
+        },
+    };
+}
+function extract() {
+    return {
+        post: {
+            operationId: "extract.once",
+            parameters: [PROJECT_ID],
+            responses: {
+                "200": { content: { "application/json": { schema: PROJECT } }, description: "ok" },
+                "500": { description: "paid inference failed" },
+            },
+            "x-cost": "high",
+            "x-effects": [{ entity: "project", op: "update" }],
+            "x-entity": { action: "action", identity: "id", name: "project" },
+        },
+    };
+}
+export function projectSpec() {
+    return {
+        info: { title: "cheap-effects", version: "1" },
+        openapi: "3.1.0",
+        paths: {
+            "/v1/projects": collection(),
+            "/v1/projects/{project_id}": {
+                get: {
+                    operationId: "project.read",
+                    parameters: [PROJECT_ID],
+                    responses: { "200": { content: { "application/json": { schema: PROJECT } }, description: "ok" } },
+                    "x-entity": { action: "read", identity: "id", name: "project" },
+                },
+            },
+            "/v1/projects/{project_id}/extract": extract(),
+        },
+        ...bearerSecurity(),
+    };
+}
+export function projectBackend() {
+    const spec = projectSpec();
+    const rows = new Map();
+    let seq = 0;
+    let extractHits = 0;
+    const handle = async (request) => {
+        const { pathname } = request.url;
+        const { method } = request;
+        if (pathname === "/v1/openapi/spec" && method === "GET")
+            return answer(200, spec);
+        if (pathname === "/v1/projects" && method === "GET")
+            return answer(200, { projects: [...rows.values()] });
+        if (pathname === "/v1/projects" && method === "POST") {
+            const body = (await readJson(request));
+            seq += 1;
+            const id = `p_${String(seq)}`;
+            const row = { id, name: typeof body?.name === "string" ? body.name : "n" };
+            rows.set(id, row);
+            return answer(201, row);
+        }
+        if (/^\/v1\/projects\/[^/]+$/.test(pathname) && method === "GET") {
+            const row = rows.get(decodeURIComponent(pathname.slice("/v1/projects/".length)));
+            return row === undefined ? answer(404) : answer(200, row);
+        }
+        if (/^\/v1\/projects\/[^/]+\/extract$/.test(pathname) && method === "POST") {
+            extractHits += 1;
+            return answer(500, { error: "paid inference" });
+        }
+        return answer(404);
+    };
+    return { extractHits: () => extractHits, handle: guarded(handle) };
+}
+//# sourceMappingURL=project.js.map

package/dist/api/conformance/seed-contract/users.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A register-and-login API: `auth.registerWithEmail` provisions the principal through its auth
+ * steps, so it must never also be seeded as a fixture create.
+ */
+import type { Handle } from "../../reference/http/node.ts";
+import type { OpenApiDocument } from "../../spec/types.ts";
+export declare function userSpec(): OpenApiDocument;
+/** The user API, and who each register call came from: the auth steps (`auth`) or anything else. */
+export interface UserBackend {
+    handle: Handle;
+    registerFrom: string[];
+}
+export declare function userBackend(): UserBackend;
+//# sourceMappingURL=users.d.ts.map

package/dist/api/conformance/seed-contract/users.js

@@ -0,0 +1,103 @@
+/**
+ * A register-and-login API: `auth.registerWithEmail` provisions the principal through its auth
+ * steps, so it must never also be seeded as a fixture create.
+ */
+import { bearerSecurity } from "../harness/security.js";
+import { answer, guarded, readJson } from "../harness/serve.js";
+function register() {
+    const user = {
+        properties: { email: { format: "email", type: "string" }, id: { type: "string" } },
+        required: ["id", "email"],
+        type: "object",
+    };
+    return {
+        operationId: "auth.registerWithEmail",
+        requestBody: {
+            content: {
+                "application/json": {
+                    schema: {
+                        properties: { email: { format: "email", type: "string" }, password: { type: "string" } },
+                        required: ["email", "password"],
+                        type: "object",
+                    },
+                },
+            },
+            required: true,
+        },
+        responses: {
+            "201": { content: { "application/json": { schema: user } }, description: "created" },
+        },
+        security: [],
+        "x-entity": { action: "create", identity: "id", name: "user" },
+        "x-fresh-principal": true,
+    };
+}
+function login() {
+    return {
+        operationId: "auth.login",
+        requestBody: {
+            content: {
+                "application/json": {
+                    schema: { properties: { email: { type: "string" }, password: { type: "string" } }, type: "object" },
+                },
+            },
+        },
+        responses: {
+            "200": {
+                content: {
+                    "application/json": {
+                        schema: {
+                            properties: { access_token: { type: "string" } },
+                            required: ["access_token"],
+                            type: "object",
+                        },
+                    },
+                },
+                description: "ok",
+            },
+        },
+        security: [],
+    };
+}
+export function userSpec() {
+    return {
+        info: { title: "register-is-not-seed", version: "1" },
+        openapi: "3.1.0",
+        paths: { "/v1/auth/register": { post: register() }, "/v1/auth/login": { post: login() } },
+        ...bearerSecurity(),
+    };
+}
+/** The register body, or `undefined` when it is not JSON. */
+async function registerBody(request) {
+    try {
+        return ((await readJson(request)) ?? {});
+    }
+    catch {
+        return undefined;
+    }
+}
+export function userBackend() {
+    const spec = userSpec();
+    const registerFrom = [];
+    const handle = async (request) => {
+        const { pathname } = request.url;
+        const { method } = request;
+        if (pathname === "/v1/openapi/spec" && method === "GET")
+            return answer(200, spec);
+        if (pathname === "/v1/auth/register" && method === "POST") {
+            /* A body that does not parse registers no one, so it is refused before it is counted. */
+            const body = await registerBody(request);
+            if (body === undefined)
+                return answer(400, { error: "malformed json" });
+            registerFrom.push(request.headers["x-via"] === "auth" ? "auth" : "other");
+            if (typeof body.email === "string" && !body.email.includes("@"))
+                return answer(400, { error: "invalid email" });
+            return answer(201, { email: body.email, id: "u1" });
+        }
+        if (pathname === "/v1/auth/login" && method === "POST")
+            return answer(200, { access_token: "tok" });
+        return answer(404);
+    };
+    return { handle: guarded(handle), registerFrom };
+}
+//# sourceMappingURL=users.js.map

package/dist/api/conformance/seed-contract.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Fixture walk, cheap-profile effects, and invite/register-as-create contracts.
+ *
+ * These are the cases a real document trips: `z.unknown()` / `z.record` after `$ref` inlining,
+ * `--profile cheap` still POSTing `extract.once`, and `org.inviteMember` / `auth.registerWithEmail`
+ * being treated as `POST /things`.
+ */
+import { type Via } from "./harness/launch.ts";
+import type { ParserResult } from "./harness/result.ts";
+export { runFixtureWalkCases } from "./seed-contract/fixture-walk.ts";
+/** Every case; one that cannot run fails under its name with the error's message, and the rest still run. */
+export declare function runSeedContractSuite(via?: Via): Promise<ParserResult[]>;
+//# sourceMappingURL=seed-contract.d.ts.map

package/dist/api/conformance/seed-contract.js

@@ -0,0 +1,152 @@
+/**
+ * Fixture walk, cheap-profile effects, and invite/register-as-create contracts.
+ *
+ * These are the cases a real document trips: `z.unknown()` / `z.record` after `$ref` inlining,
+ * `--profile cheap` still POSTing `extract.once`, and `org.inviteMember` / `auth.registerWithEmail`
+ * being treated as `POST /things`.
+ */
+import { messageOf } from "../errors/message.js";
+import { run } from "./harness/counting.js";
+import { buildModel } from "../spec/graph/build.js";
+import { dereference } from "../spec/load/dereference.js";
+import { listening, reach } from "./harness/launch.js";
+import { runFixtureWalkCases } from "./seed-contract/fixture-walk.js";
+import { memberBackend, memberSpec } from "./seed-contract/members.js";
+import { projectBackend } from "./seed-contract/project.js";
+import { userBackend } from "./seed-contract/users.js";
+export { runFixtureWalkCases } from "./seed-contract/fixture-walk.js";
+/** testing api run once against `handle`, hosted through `via`, which serves its spec at `/v1/openapi/spec`. */
+async function hostedRun(via, handle, options) {
+    const hosted = await via.host(handle);
+    try {
+        return await run({ baseUrl: hosted.url, ...options, spec: `${hosted.url}/v1/openapi/spec`, ...reach(hosted) });
+    }
+    finally {
+        await hosted.close();
+    }
+}
+/** One principal in project p_seed, with a fixed bearer token. */
+const PROJECT = {
+    principals: { alpha: { scope: { project_id: "p_seed" }, tenant: "p_seed" } },
+    security: { bearer: { static: "t" } },
+};
+const CHEAP = "cheap profile does not POST extract.once";
+const HONORED = "effects must honor excludedByProfile";
+async function profiles(via, results) {
+    const cheapBackend = projectBackend();
+    const cheap = await hostedRun(via, cheapBackend.handle, {
+        only: ["project"],
+        ...PROJECT,
+        profile: "cheap",
+        seed: 1,
+    });
+    const cheapPosted = cheap.client.transcript.some((e) => e.url.includes("/extract"));
+    const skip = cheap.findings.find((f) => f.check === "profile.skip" && f.detail.includes("x-cost: high"));
+    results.push({
+        detail: `hits=${cheapBackend.extractHits()} skip=${skip?.detail ?? "none"}`,
+        name: CHEAP,
+        ok: !cheapPosted && skip !== undefined && cheapBackend.extractHits() === 0,
+        why: HONORED,
+    });
+    const fullBackend = projectBackend();
+    const full = await hostedRun(via, fullBackend.handle, {
+        only: ["project"],
+        ...PROJECT,
+        profile: "full",
+        seed: 1,
+    });
+    const fullPosted = full.client.transcript.some((e) => e.url.includes("/extract"));
+    results.push({
+        detail: `hits=${fullBackend.extractHits()} posted=${fullPosted}`,
+        name: "full profile still invokes extract.once",
+        ok: fullPosted && fullBackend.extractHits() > 0,
+        why: "cheap is a restriction, not a deletion",
+    });
+}
+/** An owner in each of two orgs, each with its own bearer token; beta is invited as its email. */
+const INVITE = {
+    principals: {
+        alpha: { scope: { org_id: "org_1" }, tenant: "org_1", token: "a" },
+        beta: { inviteAs: "beta@x.test", scope: { org_id: "org_2" }, tenant: "org_2", token: "b" },
+    },
+    security: { bearer: { static: "{principal.token}" } },
+};
+async function inviteOnly(via, results) {
+    const backend = memberBackend();
+    const result = await hostedRun(via, backend.handle, { only: ["member"], ...INVITE, seed: 1 });
+    const inviteWithPeer = backend.inviteBodies.some((body) => body?.invite_email === "beta@x.test");
+    const generated = backend.seedBodies.length > 0;
+    const ran = result.checksRun.includes("auth.invite-grants-then-revokes");
+    results.push({
+        detail: `seedJunk=${generated} inviteAsSent=${inviteWithPeer} ran=${ran} bodies=${JSON.stringify(backend.inviteBodies)}`,
+        name: "invite-only member is not seeded with a generated email",
+        ok: !generated && inviteWithPeer && ran,
+        why: "invite check sends inviteAs",
+    });
+}
+/** One principal that signs up, then logs in for its bearer token. */
+const REGISTER = {
+    principals: { alpha: {} },
+    security: {
+        bearer: {
+            login: {
+                from: "$.access_token",
+                steps: [
+                    {
+                        body: { email: "alpha@x.test", password: "pw" },
+                        headers: { "x-via": "auth" },
+                        operationId: "auth.registerWithEmail",
+                    },
+                    { body: { email: "alpha@x.test", password: "pw" }, operationId: "auth.login" },
+                ],
+            },
+        },
+    },
+};
+async function registerNotSeeded(via, results) {
+    const backend = userBackend();
+    await hostedRun(via, backend.handle, { only: ["user"], ...REGISTER, seed: 1 });
+    results.push({
+        detail: `register calls=${backend.registerFrom.join(",") || "none"}`,
+        name: "auth.registerWithEmail is not seeded",
+        ok: backend.registerFrom.length === 1 && backend.registerFrom[0] === "auth",
+        why: "auth-flow creates are provisioned, not fixtures",
+    });
+}
+const CASES = [
+    { name: CHEAP, probe: profiles, why: HONORED },
+    {
+        name: "invite-only member is not seeded with a generated email",
+        probe: inviteOnly,
+        why: "invite check sends inviteAs",
+    },
+    {
+        name: "auth.registerWithEmail is not seeded",
+        probe: registerNotSeeded,
+        why: "auth-flow creates are provisioned, not fixtures",
+    },
+];
+/* The invite operation is modeled as the entity's invite, never as its create. */
+function inviteModel() {
+    const member = buildModel(dereference(memberSpec()).doc).entities.get("member");
+    return {
+        detail: `create=${member?.create ?? "none"} invite=${String(member?.invite?.invite)}`,
+        name: "invite op is not entity.create",
+        ok: member?.create === undefined && member?.invite !== null,
+        why: "x-invite stays on entity.invite",
+    };
+}
+/** Every case; one that cannot run fails under its name with the error's message, and the rest still run. */
+export async function runSeedContractSuite(via = listening) {
+    const results = [...runFixtureWalkCases(), inviteModel()];
+    for (const { name, probe, why } of CASES) {
+        try {
+            await probe(via, results);
+        }
+        catch (error) {
+            results.push({ detail: messageOf(error), name, ok: false, why });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=seed-contract.js.map

package/dist/api/conformance/serve-tasks.d.ts

@@ -0,0 +1,20 @@
+/** A conformance worker's side of the pool: one task per message, each answered on the same channel. */
+import type { Via } from "./harness/launch.ts";
+import { type ConformanceAnswer, type ConformanceTask } from "./tasks.ts";
+/** What a worker sends back for each task: its answer, or why it has none. */
+export type TaskReply = {
+    ok: true;
+    answer: ConformanceAnswer;
+} | {
+    ok: false;
+    error: string;
+};
+/** Where tasks arrive and replies go: a forked process's IPC channel, or anything shaped like it. */
+export interface TaskPort {
+    on(event: "message", listener: (task: ConformanceTask) => void): unknown;
+    /** Absent when nothing is listening: the task still runs, and its reply is dropped. */
+    send?: ((reply: TaskReply) => unknown) | undefined;
+}
+/** Runs each task `port` delivers, numbered in arrival order, reaching the reference by `via`. */
+export declare function serveTasks(port: TaskPort, via: Via): void;
+//# sourceMappingURL=serve-tasks.d.ts.map

package/dist/api/conformance/serve-tasks.js

@@ -0,0 +1,14 @@
+/** A conformance worker's side of the pool: one task per message, each answered on the same channel. */
+import { runTask } from "./tasks.js";
+/** Runs each task `port` delivers, numbered in arrival order, reaching the reference by `via`. */
+export function serveTasks(port, via) {
+    let sequence = 0;
+    port.on("message", (task) => {
+        sequence += 1;
+        runTask(task, sequence, via).then((answer) => port.send?.({ answer, ok: true }), 
+        /* A task reports its own failures; only a malformed task or a failed heap snapshot rejects,
+         * always with an Error, and V8 gives every Error a stack. */
+        (error) => port.send?.({ error: String(error.stack), ok: false }));
+    });
+}
+//# sourceMappingURL=serve-tasks.js.map

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

@@ -0,0 +1,69 @@
+/**
+ * The correct-backend shape matrix.
+ *
+ * The defect matrix asks whether the API tester notices a broken backend. This asks the opposite question,
+ * which the defect matrix cannot: whether the API tester stays quiet on a *correct* backend shaped unlike the
+ * one it was written against. Each case serves the clean reference behind one shape and requires
+ * nothing from the API tester at all — no finding, no inconclusive verdict, no record left behind, and no
+ * check that quietly stopped applying.
+ *
+ * Cases the API tester still gets wrong are listed in `expected-failures.ts`, which may only shrink.
+ */
+import { type Target, type Via } from "./harness/launch.ts";
+import type { Backend } from "./matrix/engines.ts";
+import { type StoreSnapshot } from "./leaks.ts";
+import { type CaseResult } from "./matrix/cases.ts";
+import { type DefectName } from "../reference/defects/table.ts";
+import type { RunResult } from "../runtime/run/index.ts";
+export interface ShapeCase {
+    label: string;
+    why: string;
+    /** Everything that makes this case fail; empty when the API tester handled the shape. */
+    problems: string[];
+    /** Why the case is known to fail, when it is listed in `expected-failures.ts`. */
+    expected: string | undefined;
+}
+/** The default shape's target on `backend`: what every shape case starts from. */
+export declare function shapeTarget(backend: Backend, via: Via): Target;
+/** What a clean run showed: its result, and the reference's records either side of it. */
+export interface CleanRun {
+    result: Pick<RunResult, "checksRun" | "findings" | "inconclusive" | "teardown">;
+    before: StoreSnapshot;
+    after: StoreSnapshot;
+    /** The ids the reference created, per entity. */
+    created: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Everything a run against a correct backend got wrong: what it reported, what it did to the
+ * records, and any of the `reference` checks it no longer ran that the shape does not excuse.
+ */
+export declare function cleanRunProblems(clean: CleanRun, reference: ReadonlySet<string> | undefined, cannotRun: Readonly<Record<string, string>>): string[];
+/** Every shape the reference serves, by name, in order. */
+export declare const SHAPE_NAMES: readonly string[];
+/**
+ * The checks a clean run behind the default shape runs: what every other shape must also run.
+ * `null` when the default shape cannot be run at all, and then no shape is held to it.
+ */
+export declare function shapeReference(target: Target): Promise<string[] | null>;
+/** One shape, judged against the default shape's checks. */
+export declare function judgeShape(target: Target, name: string, reference: readonly string[] | null): Promise<ShapeCase>;
+export declare function renderShapeSuite(cases: ShapeCase[], quiet?: boolean): {
+    text: string;
+    failures: number;
+};
+/**
+ * Every defect again, behind each shape the API tester already handles.
+ *
+ * A clean baseline behind a shape says the API tester is quiet there; it does not say the API tester still *sees*
+ * anything. Mounting the API under a prefix once cost five detections while the clean run stayed
+ * spotless. Behind a shape whose clean baseline still fails, recall cannot mean anything yet, so
+ * that shape reports one case that waits on the shape itself (`waitingRecall`).
+ */
+export declare function recallDefects(backend: Backend, name: string): DefectName[];
+/** The one recall case of a shape that does not run clean yet. */
+export declare function waitingRecall(shapeCase: ShapeCase): ShapeCase;
+/** Recall of `defects` behind the shape `name`: a case per defect. */
+export declare function recallBehind(target: Target, name: string, defects: readonly DefectName[]): Promise<ShapeCase[]>;
+/** What a recall run got wrong: a miss, a spurious finding, a value it lacked, a record it left. */
+export declare function recallProblems(result: CaseResult): string[];
+//# sourceMappingURL=shapes.d.ts.map