@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/conformance/matrix/engines.d.ts

@@ -0,0 +1,26 @@
+import type postgres from "postgres";
+export type Backend = "memory" | "sqlite" | "postgres" | "d1";
+/** Loads `node:sqlite`; a test brings a runtime that cannot. */
+type LoadSqlite = () => Promise<Pick<typeof import("node:sqlite"), "DatabaseSync">>;
+/** Whether this runtime can host the SQLite backend: a Node built without SQLite cannot. */
+export declare function sqliteAvailable(load?: LoadSqlite): Promise<boolean>;
+/**
+ * Whether D1 credentials are present. Deliberately not a live probe: a network call on every
+ * `testing api conformance` would tax the common path to answer a question about an opt-in backend.
+ */
+export declare function d1Available(): boolean;
+/** What the probe needs of a Postgres connection; postgres.js's client is one. */
+export interface ProbeConnection {
+    unsafe(query: string): PromiseLike<unknown>;
+    end(options: {
+        timeout: number;
+    }): Promise<void>;
+}
+/** The real driver against the server the environment names: one short-lived session, notices silenced. */
+export declare function connectProbe(): Promise<ReturnType<typeof postgres>>;
+/** Whether Postgres can host a pass: a server answers, none does, or this install lacks the driver. */
+export type PostgresStatus = "ready" | "unreachable" | "no-driver";
+/** Whether a Postgres server is reachable through the installed driver. */
+export declare function postgresStatus(connect?: () => Promise<ProbeConnection>): Promise<PostgresStatus>;
+export {};
+//# sourceMappingURL=engines.d.ts.map

package/dist/api/conformance/matrix/engines.js

@@ -0,0 +1,45 @@
+import { isMissingPostgres } from "../../reference/stores/postgres-driver.js";
+/** Whether this runtime can host the SQLite backend: a Node built without SQLite cannot. */
+export async function sqliteAvailable(load = () => import("node:sqlite")) {
+    try {
+        /* Constructing is the real test: on some builds the module resolves but the class is
+         * unusable, and a probe that only imports would report a false positive. */
+        const { DatabaseSync } = await load();
+        new DatabaseSync(":memory:").close();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether D1 credentials are present. Deliberately not a live probe: a network call on every
+ * `testing api conformance` would tax the common path to answer a question about an opt-in backend.
+ */
+export function d1Available() {
+    return (process.env["CLOUDFLARE_ACCOUNT_ID"] !== undefined &&
+        process.env["CLOUDFLARE_D1_DATABASE_ID"] !== undefined &&
+        process.env["CLOUDFLARE_API_TOKEN"] !== undefined);
+}
+/** The real driver against the server the environment names: one short-lived session, notices silenced. */
+export async function connectProbe() {
+    const { default: connect } = await import("postgres");
+    return connect({ connect_timeout: 3, database: "postgres", max: 1, onnotice: () => { } });
+}
+/** Whether a Postgres server is reachable through the installed driver. */
+export async function postgresStatus(connect = connectProbe) {
+    try {
+        const sql = await connect();
+        try {
+            await sql.unsafe("select 1");
+            return "ready";
+        }
+        finally {
+            await sql.end({ timeout: 3 });
+        }
+    }
+    catch (error) {
+        return isMissingPostgres(error) ? "no-driver" : "unreachable";
+    }
+}
+//# sourceMappingURL=engines.js.map

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

@@ -0,0 +1,9 @@
+import type { Finding } from "../../runtime/finding.ts";
+export declare function primaryOf(expected: string | string[]): string;
+export declare function acceptableOf(expected: string | string[]): string[];
+/**
+ * Every operation `check` judged among `findings`, once each and in first-seen order. A run-level
+ * finding judges no operation and adds none.
+ */
+export declare function judgedOperations(findings: readonly Finding[], check: string | null): string[];
+//# sourceMappingURL=expected.d.ts.map

package/dist/api/conformance/matrix/expected.js

@@ -0,0 +1,14 @@
+export function primaryOf(expected) {
+    return Array.isArray(expected) ? (expected[0] ?? "") : expected;
+}
+export function acceptableOf(expected) {
+    return Array.isArray(expected) ? expected : [expected];
+}
+/**
+ * Every operation `check` judged among `findings`, once each and in first-seen order. A run-level
+ * finding judges no operation and adds none.
+ */
+export function judgedOperations(findings, check) {
+    return [...new Set(findings.filter((item) => item.check === check).flatMap((item) => item.operations ?? []))];
+}
+//# sourceMappingURL=expected.js.map

package/dist/api/conformance/matrix/opt-in.d.ts

@@ -0,0 +1,14 @@
+import type { DefectName } from "../../reference/defects/table.ts";
+import type { ReferenceOptions } from "../../reference/http/state.ts";
+import type { RunOptions } from "../../runtime/run/index.ts";
+/**
+ * What a run switches on before a defect can show at all: a reference behavior that is off by
+ * default, and the opt-in check that looks for it. Every other defect runs with neither.
+ */
+export interface OptIn {
+    reference: Pick<ReferenceOptions, "throttleLogins">;
+    run: Pick<RunOptions, "checks">;
+}
+/** Everything `defects` need switched on, in the reference and in the API tester, merged. */
+export declare function optInFor(defects: readonly DefectName[]): OptIn;
+//# sourceMappingURL=opt-in.d.ts.map

package/dist/api/conformance/matrix/opt-in.js

@@ -0,0 +1,15 @@
+/** The defects that need an opt-in, and theirs. */
+const OPT_INS = {
+    /* A throttle that is off never answers 429, and the API tester sends failed logins only when asked to. */
+    LOGIN_NOT_THROTTLED: { reference: { throttleLogins: true }, run: { checks: { "auth.login-throttled": true } } },
+};
+/** Everything `defects` need switched on, in the reference and in the API tester, merged. */
+export function optInFor(defects) {
+    return defects.reduce((merged, defect) => {
+        const own = OPT_INS[defect];
+        if (own === undefined)
+            return merged;
+        return { reference: { ...merged.reference, ...own.reference }, run: { ...merged.run, ...own.run } };
+    }, { reference: {}, run: {} });
+}
+//# sourceMappingURL=opt-in.js.map

package/dist/api/conformance/matrix/principals.d.ts

@@ -0,0 +1,11 @@
+import type { PrincipalsConfig, SecurityConfig } from "../../config/types/security.ts";
+/**
+ * The reference's schemes: the jwt is what `auth.token` issues for the principal's key, rotated at
+ * `auth.refresh` with the refresh token each answer carries, and ended at `auth.logout`; the apiKey
+ * is minted with that jwt, holding the scopes the operation needs, revoked when the run is done, and
+ * sent as `ApiKey <key>`.
+ */
+export declare const SECURITY: SecurityConfig;
+/** Two tenants' owners, then the first tenant's member and its read-only viewer; alpha comes first, so it acts. */
+export declare const PRINCIPALS: PrincipalsConfig;
+//# sourceMappingURL=principals.d.ts.map

package/dist/api/conformance/matrix/principals.js

@@ -0,0 +1,51 @@
+/**
+ * The reference's schemes: the jwt is what `auth.token` issues for the principal's key, rotated at
+ * `auth.refresh` with the refresh token each answer carries, and ended at `auth.logout`; the apiKey
+ * is minted with that jwt, holding the scopes the operation needs, revoked when the run is done, and
+ * sent as `ApiKey <key>`.
+ */
+export const SECURITY = {
+    apiKey: {
+        format: "ApiKey {credential}",
+        mint: {
+            body: { scopes: "{scopes}" },
+            from: "$.key",
+            operationId: "apiKey.create",
+            revoke: "apiKey.revoke",
+            with: "jwt",
+        },
+    },
+    jwt: {
+        login: {
+            from: "$.access_token",
+            revoke: "auth.logout",
+            steps: [
+                { body: { key: "{principal.key}" }, operationId: "auth.token", saveAs: { refresh_token: "$.refresh_token" } },
+            ],
+        },
+        refresh: {
+            from: "$.access_token",
+            steps: [
+                {
+                    body: { refresh_token: "{refresh_token}" },
+                    operationId: "auth.refresh",
+                    saveAs: { refresh_token: "$.refresh_token" },
+                },
+            ],
+        },
+    },
+};
+/** Two tenants' owners, then the first tenant's member and its read-only viewer; alpha comes first, so it acts. */
+export const PRINCIPALS = {
+    alpha: { key: "key_alpha", rank: 2, scope: { project_id: "proj_alpha" }, tenant: "proj_alpha" },
+    beta: { inviteAs: "key_beta", key: "key_beta", rank: 2, scope: { project_id: "proj_beta" }, tenant: "proj_beta" },
+    alpha_member: { key: "key_alpha_member", rank: 1, scope: { project_id: "proj_alpha" }, tenant: "proj_alpha" },
+    alpha_viewer: {
+        key: "key_alpha_viewer",
+        rank: 0,
+        readOnly: true,
+        scope: { project_id: "proj_alpha" },
+        tenant: "proj_alpha",
+    },
+};
+//# sourceMappingURL=principals.js.map

package/dist/api/conformance/matrix/render.d.ts

@@ -0,0 +1,47 @@
+import type { CaseResult } from "./cases.ts";
+import type { Backend } from "./engines.ts";
+/**
+ * How many checks must actually run against each shape.
+ *
+ * The recurring bug in this tool has been a check that cannot *express* a request looking exactly
+ * like a backend that ignores one: gating on a `page` parameter against an offset-paged API, or on
+ * a `filter` parameter against one that filters per field. Every instance was found by adding a
+ * new dialect and noticing the number drop — which only works if someone is looking.
+ *
+ * These floors make it automatic. They are deliberately set at the current coverage, so any change
+ * that quietly stops a check from applying fails the suite and names it, rather than waiting for a
+ * sixth dialect to expose the same class again. Raising a floor when coverage genuinely improves
+ * is the intended maintenance; lowering one needs a reason stated in the commit.
+ */
+export declare const COVERAGE_FLOOR: Record<string, number>;
+/** A leg's answer, from its results in order: the two baselines first, then its defects. */
+export declare function passAnswer(results: CaseResult[], backend: Backend, dialect: string): {
+    text: string;
+    failures: number;
+    proven: string[];
+    baselines: {
+        tagged: string[];
+        untagged: string[];
+    };
+    primaryOps: Record<string, string[]>;
+};
+/** Inconclusive verdicts a clean baseline may return, per `backend:dialect`; see `expected-failures.ts`. */
+type Allowance = Readonly<Record<string, readonly string[]>>;
+/** One leg of the suite: the dialect and backend it ran on, and the inconclusive verdicts it may return. */
+export interface SuiteLeg {
+    dialect: string;
+    backend: Backend;
+    inconclusive: Allowance;
+}
+export declare function renderSuite(results: CaseResult[], { backend, dialect, inconclusive }?: Partial<SuiteLeg>): {
+    text: string;
+    failures: number;
+    proven: Set<string>;
+};
+/** Registered checks no injected defect made fire anywhere in the run. Each one fails the suite. */
+export declare function renderUnproven(proven: ReadonlySet<string>): {
+    text: string;
+    failures: number;
+};
+export {};
+//# sourceMappingURL=render.d.ts.map

package/dist/api/conformance/matrix/render.js

@@ -0,0 +1,211 @@
+import { CHECKS } from "../../runtime/checks/registry.js";
+import { EXPECTED_INCONCLUSIVE } from "../expected-failures.js";
+import { judgedOperations } from "./expected.js";
+/**
+ * How many checks must actually run against each shape.
+ *
+ * The recurring bug in this tool has been a check that cannot *express* a request looking exactly
+ * like a backend that ignores one: gating on a `page` parameter against an offset-paged API, or on
+ * a `filter` parameter against one that filters per field. Every instance was found by adding a
+ * new dialect and noticing the number drop — which only works if someone is looking.
+ *
+ * These floors make it automatic. They are deliberately set at the current coverage, so any change
+ * that quietly stops a check from applying fails the suite and names it, rather than waiting for a
+ * sixth dialect to expose the same class again. Raising a floor when coverage genuinely improves
+ * is the intended maintenance; lowering one needs a reason stated in the commit.
+ */
+export const COVERAGE_FLOOR = {
+    classic: 80,
+    jsonapi: 87,
+    linked: 89,
+    plain: 71,
+    postgrest: 90,
+};
+/** Every registered check, by id. */
+function allCheckIds() {
+    return CHECKS.map((check) => check.id);
+}
+/** A leg's answer, from its results in order: the two baselines first, then its defects. */
+export function passAnswer(results, backend, dialect) {
+    const rendered = renderSuite(results, { backend, dialect });
+    const primaryOps = {};
+    /* Every operation the primary check judged, not the first finding's alone: a defect seen on two
+     * entities is reported twice in no fixed order, and a targeted run must cover the one it shows on. */
+    for (const result of results) {
+        const operations = judgedOperations(result.findings, result.expected);
+        if (result.defect !== null && operations.length > 0)
+            primaryOps[result.defect] = operations;
+    }
+    return {
+        baselines: { tagged: results[0]?.checksRun ?? [], untagged: results[1]?.checksRun ?? [] },
+        failures: rendered.failures,
+        primaryOps,
+        proven: [...rendered.proven],
+        text: rendered.text,
+    };
+}
+/** Judges one case of a leg on `backend` under `dialect`. */
+function judge(result, leg) {
+    const { backend, dialect } = leg;
+    /*
+     * A baseline that reports nothing because it ran nothing is not evidence of precision — and a
+     * baseline that runs *fewer checks than this shape is known to support* is a coverage
+     * regression wearing a clean result's clothes.
+     */
+    const floor = COVERAGE_FLOOR[dialect] ?? 10;
+    /* A clean baseline that could not decide a check has not shown that check passes. Only a
+     * verdict declared expected for this backend and shape may stand. */
+    const variant = result.label === "baseline (untagged spec)" ? ":untagged" : "";
+    const allowed = leg.inconclusive[`${backend}:${dialect}${variant}`] ?? [];
+    const measured = {
+        bystanders: result.bystanders ?? [],
+        floor,
+        isBaseline: result.defect === null,
+        leaked: result.leaked ?? 0,
+        missingValues: result.missingValues ?? [],
+        strayLedger: result.strayLedger ?? [],
+        undecided: (result.inconclusive ?? []).filter((entry) => !allowed.some((prefix) => entry.startsWith(`${prefix}:`))),
+        unreported: result.unreported ?? [],
+        /* Only the *tagged* baseline is held to the floor. The untagged case deliberately strips
+         * every x-* tag to prove the API tester degrades gracefully without them, so running fewer checks
+         * there is the result being measured, not a regression. */
+        vacuous: result.label === "baseline (correct backend)" && result.checksRun.length < floor,
+    };
+    const holds = measured.isBaseline ? baselineHolds(result, measured) : defectHolds(result);
+    return { ...measured, ok: tidy(measured) && holds };
+}
+/** Nothing touched, ledgered, invented, or left behind unreported. */
+function tidy(measured) {
+    return (measured.bystanders.length === 0 &&
+        measured.strayLedger.length === 0 &&
+        measured.missingValues.length === 0 &&
+        measured.unreported.length === 0);
+}
+function baselineHolds(result, measured) {
+    return (result.spurious.length === 0 &&
+        !measured.vacuous &&
+        measured.leaked === 0 &&
+        measured.undecided.length === 0 &&
+        /* An untagged run that finds nothing *and* runs almost nothing proves nothing. */
+        result.checksRun.length >= 10);
+}
+function defectHolds(result) {
+    return result.detected && result.spurious.length === 0;
+}
+/** The detected column: how a baseline read, or whether the defect was caught. */
+function detectedLabel(result, judged) {
+    if (!judged.isBaseline)
+        return result.detected ? "yes" : "NO";
+    if (judged.vacuous)
+        return "VACUOUS";
+    return result.spurious.length === 0 ? "clean" : "noisy";
+}
+/** The case's row in the table. */
+function caseRow(result, judged) {
+    const mark = judged.ok ? "✓" : "✗";
+    const detected = detectedLabel(result, judged);
+    const coverage = judged.isBaseline ? `${result.checksRun.length} checks` : (result.expected ?? "—");
+    return `  ${mark} ${result.label.padEnd(26)} ${detected.padEnd(8)} ${String(result.spurious.length).padEnd(9)} ${coverage}`;
+}
+/** What the run did to the system under test that it must not. */
+function litterNotes(judged) {
+    const { bystanders, leaked, missingValues, strayLedger, unreported } = judged;
+    const notes = [];
+    if (bystanders.length > 0)
+        notes.push(`      touched ${bystanders.length} record(s) it did not create: ${bystanders.slice(0, 4).join("; ")}`);
+    if (strayLedger.length > 0)
+        notes.push(`      ledgered ${strayLedger.length} id(s) the server never created: ${strayLedger.slice(0, 4).join("; ")}`);
+    if (missingValues.length > 0)
+        notes.push(`      would have sent a value it did not have: ${missingValues.slice(0, 4).join("; ")}`);
+    if (unreported.length > 0)
+        notes.push(`      left ${unreported.length} record(s) behind without reporting them: ${unreported.slice(0, 4).join("; ")}`);
+    if (leaked > 0)
+        notes.push(`      left ${leaked} record(s) behind after teardown — a run must not litter the system under test`);
+    return notes;
+}
+/** Why a baseline ran too little to count, and which checks it left out. */
+function vacuousNotes(result, judged) {
+    if (!judged.vacuous)
+        return [];
+    const notes = [
+        `      only ${result.checksRun.length} check(s) ran, below the ${judged.floor} this shape ` +
+            "supports — a check that stopped applying reads exactly like a clean result",
+    ];
+    /* Every floor is below the registry's size, so a vacuous baseline always left some out. */
+    const missing = allCheckIds().filter((id) => !result.checksRun.includes(id));
+    notes.push(`      did not run: ${missing.join(", ")}`);
+    return notes;
+}
+/** The lines under a case's row: everything that made it fail, in a fixed order. */
+function caseNotes(result, judged) {
+    const notes = litterNotes(judged);
+    for (const entry of judged.isBaseline ? judged.undecided : []) {
+        notes.push(`      inconclusive on a correct backend: ${entry}`);
+    }
+    notes.push(...vacuousNotes(result, judged));
+    if (result.error !== undefined)
+        notes.push(`      error: ${result.error}`);
+    for (const finding of result.spurious.slice(0, 4)) {
+        notes.push(`      spurious: [${finding.check}] ${finding.summary}`);
+    }
+    if (!judged.isBaseline && !result.detected && result.error === undefined) {
+        const others = result.findings.filter((f) => f.verdict !== "COVERAGE_GAP");
+        notes.push(`      missed — reported instead: ${others.map((f) => f.check).join(", ") || "nothing"}`);
+    }
+    return notes;
+}
+/** Recall, precision and the pass count under the table. */
+function summaryLines(results, failures) {
+    const detectionCases = results.filter((r) => r.defect !== null);
+    const detected = detectionCases.filter((r) => r.detected).length;
+    const baseline = results.find((r) => r.defect === null);
+    return [
+        "",
+        `  recall     ${detected}/${detectionCases.length} injected defects detected`,
+        `  precision  ${baseline?.spurious.length === 0 ? "clean baseline — no findings against a correct backend" : `${baseline?.spurious.length ?? 0} false positive(s) on the correct backend`}`,
+        `  ${results.length - failures}/${results.length} cases passed`,
+        "",
+    ];
+}
+/* A check is proven by having fired against a defect built for it — not by appearing on a
+ * list of checks a defect may trip. Whether every registered check is proven is decided over
+ * the whole run, since some defects only exist in some shapes. */
+function provenChecks(results) {
+    return new Set(results
+        .filter((r) => r.defect !== null && r.detected)
+        .flatMap((r) => r.findings.filter((f) => f.verdict !== "COVERAGE_GAP").map((f) => f.check)));
+}
+export function renderSuite(results, { backend = "memory", dialect = "postgrest", inconclusive = EXPECTED_INCONCLUSIVE } = {}) {
+    const lines = [
+        "",
+        "  defect                     detected  spurious  expected check",
+        "  ─────────────────────────────────────────────────────────────────────────",
+    ];
+    let failures = 0;
+    for (const result of results) {
+        const judged = judge(result, { backend, dialect, inconclusive });
+        if (!judged.ok)
+            failures++;
+        lines.push(caseRow(result, judged), ...caseNotes(result, judged));
+    }
+    lines.push(...summaryLines(results, failures));
+    return { failures, proven: provenChecks(results), text: lines.join("\n") };
+}
+/** Registered checks no injected defect made fire anywhere in the run. Each one fails the suite. */
+export function renderUnproven(proven) {
+    const ids = allCheckIds();
+    const unproven = ids.filter((id) => !proven.has(id));
+    if (unproven.length === 0) {
+        return {
+            failures: 0,
+            text: `\n  every one of ${ids.length} registered checks fired on a defect built for it\n`,
+        };
+    }
+    const lines = ["", `  ✗ ${unproven.length} registered check(s) never fired on an injected defect:`];
+    for (const id of unproven)
+        lines.push(`      ${id}`);
+    lines.push("    a check never shown to detect anything proves nothing by passing — give it a defect or delete it");
+    lines.push("");
+    return { failures: unproven.length, text: lines.join("\n") };
+}
+//# sourceMappingURL=render.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * Conformance cases on worker processes.
+ *
+ * Every case already owns its server, so cases share nothing but the CPU — and the suite is
+ * CPU-bound: the API tester and the reference backend run in one process, so concurrency inside it buys
+ * nothing. Separate processes do, each with its own heap and event loop. A task is a slice of a
+ * leg (see `tasks.ts`) and comes back as plain data the parent assembles and prints in order.
+ * In process, the same tasks run one at a time in the caller's own process: for a test, or a
+ * machine short of memory.
+ */
+import { type AnswerFor, type ConformanceTask } from "./tasks.ts";
+import { type Via } from "./harness/launch.ts";
+import type { TaskReply } from "./serve-tasks.ts";
+export type { AnswerFor, ConformanceAnswer, ConformanceTask, MemoryUse } from "./tasks.ts";
+export interface ConformancePool {
+    run<T extends ConformanceTask>(task: T): Promise<AnswerFor<T>>;
+    close(): Promise<void>;
+}
+/** One worker as the pool drives it: a forked process, or anything that answers like one. */
+export interface PoolWorker {
+    send(task: ConformanceTask): unknown;
+    once(event: "message", listener: (reply: TaskReply) => void): unknown;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    once(event: "exit", listener: (code: number | null, signal: string | null) => void): unknown;
+    off(event: "message", listener: (reply: TaskReply) => void): unknown;
+    off(event: "error", listener: (error: Error) => void): unknown;
+    off(event: "exit", listener: (code: number | null, signal: string | null) => void): unknown;
+    kill(): unknown;
+    readonly exitCode: number | null;
+    readonly signalCode: string | null;
+}
+export interface PoolOptions {
+    /** Run every task in the caller's own process, one at a time. */
+    inProcess?: boolean;
+    /** Starts one worker; a forked `worker.js` unless a test brings its own. */
+    spawn?: () => PoolWorker;
+    /** How in-process tasks reach the reference: behind a socket, as the workers do, unless a test says otherwise. */
+    via?: Via;
+}
+/** Threads used when `--jobs` is not given: most of the machine, never more than four. */
+export declare function defaultJobs(): number;
+/** A worker process running `script`, the built `worker.js` beside this module by default. */
+export declare function forkWorker(script?: URL): PoolWorker;
+/** A pool of `jobs` worker processes, or the caller's own process when `inProcess`. */
+export declare function createPool(jobs: number, { inProcess, spawn, via }?: PoolOptions): ConformancePool;
+//# sourceMappingURL=pool.d.ts.map

package/dist/api/conformance/pool.js

@@ -0,0 +1,104 @@
+/**
+ * Conformance cases on worker processes.
+ *
+ * Every case already owns its server, so cases share nothing but the CPU — and the suite is
+ * CPU-bound: the API tester and the reference backend run in one process, so concurrency inside it buys
+ * nothing. Separate processes do, each with its own heap and event loop. A task is a slice of a
+ * leg (see `tasks.ts`) and comes back as plain data the parent assembles and prints in order.
+ * In process, the same tasks run one at a time in the caller's own process: for a test, or a
+ * machine short of memory.
+ */
+import { availableParallelism } from "node:os";
+import { fork } from "node:child_process";
+import { runTask } from "./tasks.js";
+import { listening } from "./harness/launch.js";
+/** Threads used when `--jobs` is not given: most of the machine, never more than four. */
+export function defaultJobs() {
+    return Math.max(1, Math.min(4, availableParallelism() - 1));
+}
+/** A worker process running `script`, the built `worker.js` beside this module by default. */
+export function forkWorker(script = new URL("./worker.js", import.meta.url)) {
+    /* Structured clone, as between threads: results carry Maps and Sets. */
+    return fork(script, { serialization: "advanced", stdio: ["ignore", "inherit", "inherit", "ipc"] });
+}
+/** A pool of `jobs` worker processes, or the caller's own process when `inProcess`. */
+export function createPool(jobs, { inProcess = false, spawn = forkWorker, via = listening } = {}) {
+    if (inProcess)
+        return inProcessPool(via);
+    return processPool(Array.from({ length: Math.max(1, jobs) }, () => spawn()));
+}
+/** Tasks handed to whichever worker is idle, in the order they were asked for. */
+function processPool(workers) {
+    const idle = [...workers];
+    const queue = [];
+    const next = (worker) => {
+        const job = queue.shift();
+        if (job === undefined)
+            idle.push(worker);
+        else
+            assign(worker, job, next);
+    };
+    return {
+        close: () => closeAll(workers),
+        /* A worker answers each task with its own kind of answer: the IPC boundary is where that is trusted. */
+        run: (task) => new Promise((resolve, reject) => {
+            queue.push({ reject, resolve: resolve, task });
+            const worker = idle.shift();
+            if (worker !== undefined)
+                next(worker);
+        }),
+    };
+}
+/** Sends `job` to `worker` and settles it on whatever comes first: a reply (which frees the worker), an error, or an exit. */
+function assign(worker, job, next) {
+    const settle = (reply) => {
+        worker.off("error", fail);
+        worker.off("exit", died);
+        if (reply.ok)
+            job.resolve(reply.answer);
+        else
+            job.reject(new Error(reply.error));
+        next(worker);
+    };
+    const fail = (error) => {
+        worker.off("message", settle);
+        worker.off("exit", died);
+        job.reject(error);
+    };
+    const died = (code, signal) => {
+        worker.off("message", settle);
+        worker.off("error", fail);
+        job.reject(new Error(`conformance worker exited (${signal ?? code}) during a task`));
+    };
+    worker.once("message", settle);
+    worker.once("error", fail);
+    worker.once("exit", died);
+    worker.send(job.task);
+}
+/** Stops every worker still running, and waits for each to exit. */
+async function closeAll(workers) {
+    await Promise.all(workers.map((worker) => new Promise((resolve) => {
+        if (worker.exitCode !== null || worker.signalCode !== null)
+            return resolve();
+        worker.once("exit", () => resolve());
+        worker.kill();
+    })));
+}
+/** Tasks run one at a time in this process, in the order they were asked for. */
+function inProcessPool(via) {
+    let sequence = 0;
+    let previous = Promise.resolve();
+    return {
+        close: async () => {
+            await previous.catch(() => undefined);
+        },
+        run: (task) => {
+            sequence += 1;
+            const turn = sequence;
+            const answer = previous.catch(() => undefined).then(() => runTask(task, turn, via));
+            previous = answer;
+            return answer;
+        },
+    };
+}
+//# sourceMappingURL=pool.js.map

package/dist/api/conformance/rate-limit/backend.d.ts

@@ -0,0 +1,9 @@
+/** The rate-limit suite's backends, each a fresh `Handle` with its own rows. */
+import type { Handle } from "../../reference/http/node.ts";
+/** Untagged things whose first create is a 429 with `Retry-After: 0`; every later create succeeds. */
+export declare function untaggedThings(): Handle;
+/** One table that already exists, a table create refused as a plan limit (402), and rows. */
+export declare function planLimitedTables(): Handle;
+/** Things whose every create is a 429 asking to come back in a day: a daily limit already spent. */
+export declare function dayLimitedThings(): Handle;
+//# sourceMappingURL=backend.d.ts.map