@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/client/types.d.ts

@@ -0,0 +1,149 @@
+/** The client's request, wiring and policy shapes. */
+import type { NetworkInterfaceInfo } from "node:os";
+import type { HeaderRequest } from "../config/types/hooks.ts";
+import type { Redactor } from "../security/redact.ts";
+import type { Exchange, Purpose, SchemaVerdict } from "../runtime/exchange.ts";
+import type { Fence } from "../runtime/fence.ts";
+import type { NetworkError } from "../errors/network.ts";
+import type { RateLimiter } from "../runtime/rate-limit/limiter.ts";
+import type { Actor, CredentialSource } from "./credential-source.ts";
+import type { SpoolOptions } from "../runtime/transcript/spool.ts";
+import type { ParamStyles } from "../spec/graph/parameters.ts";
+import type { CacheBypass } from "../spec/extensions/consistency.ts";
+export type { SafeMethod } from "../spec/methods.ts";
+/** Who is asking, and why: carried onto every exchange a view sends. */
+export interface ExchangeContext {
+    check?: string;
+    subject?: string;
+    purpose?: Purpose;
+    /**
+     * Where each answer holds a credential, as a recipe's `from` or `saveAs` addresses it: a JSON path
+     * of the body, `header:<name>` or `cookie:<name>`. What is there registers on the redactor before
+     * the exchange is recorded, so the journal never writes it down, whatever its key is called.
+     */
+    secrets?: readonly string[];
+    /** The credential store sent it: what it creates is the store's to revoke, never a ledgered record. */
+    issuedBy?: "credentials";
+}
+/** The documented operation a request is an instance of. */
+export interface ResolvedOperation {
+    operationId: string;
+    template: string;
+    entity?: string | null;
+    redirects?: boolean;
+    /** Required parameters the request is sent with unless it sets them: the document's values. */
+    requiredQuery?: Record<string, unknown>;
+    requiredHeaders?: Record<string, unknown>;
+    requiredCookies?: Record<string, unknown>;
+    /** How each parameter is written, where the document says other than the OAS default. */
+    paramStyles?: ParamStyles;
+    pathParams?: Record<string, string>;
+    /** The `x-consistency` bypass a read declares; a read without one is sent `Cache-Control: no-cache`. */
+    bypass?: CacheBypass | null;
+}
+/** Maps a request to the documented operation it is an instance of. */
+export type OperationResolver = (method: string, relativePath: string) => ResolvedOperation | null;
+/** Per-request headers from the config's `resolveHeaders` hook; `null` adds none. */
+export type HeaderResolver = (request: HeaderRequest) => Promise<Record<string, string> | null>;
+/** Fired around `fetch` — start is on the wire, end is return or throw. */
+export interface RequestStart {
+    method: string;
+    url: string;
+    at: number;
+    requestId: string;
+    requestBytes: number;
+}
+export interface HttpHooks {
+    start?: (probe: RequestStart) => void;
+    end?: (probe: RequestStart) => void;
+}
+export interface RequestOptions {
+    /**
+     * Who the request acts as. There is no default: anonymous is `{ anonymous: true }`. The credential
+     * it sends comes from this and the operation's security, never from `headers`.
+     */
+    as: Actor;
+    /** The request expects a refusal: a 401 is its answer, never refreshed or retried. A forged actor is always one. */
+    probe?: boolean;
+    /** Set only on the client's own control read (`control.ts`): its answer is the verdict, never renewed or judged. */
+    control?: true;
+    /** Non-credential headers only: one under a name the credential is placed in is a `CredentialCollision`. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Each value is written in the style the resolved operation declares for it; by default an array
+     * repeats the parameter once per item, in order, and an object spreads its keys.
+     */
+    query?: Record<string, unknown>;
+    /** Plain object (JSON), FormData, URLSearchParams, or any BodyInit. */
+    body?: unknown;
+    /**
+     * Explicit type, or `null` when headers are already final.
+     * FormData never gets a Content-Type here — fetch must set the boundary.
+     */
+    contentType?: string | null;
+    /** Who is asking and why. A view fills this in; a caller may narrow `purpose` per request. */
+    context?: ExchangeContext;
+    /** Named operation, when the caller knows it — `resolveHeaders` uses this to attach captcha. */
+    operationId?: string;
+    /** `uploads.each` filename, recorded on the exchange for the journal. */
+    fixture?: string;
+    /**
+     * `follow` (jar) keeps intermediate `Set-Cookie` visible to `saveAs`.
+     * `manual` returns the first 3xx. Unset: native fetch follow, no jar.
+     */
+    redirect?: "follow" | "manual";
+    /** `use` reads as a client would, past no cache: the staleness measurement. Default `bypass`. */
+    cache?: "bypass" | "use";
+}
+/** Optional retry / wait-for-link policy. Unset keeps today's "throw and hope". */
+export interface NetworkClientOptions {
+    retries?: number;
+    requestTimeoutMs?: number;
+    /** Total time one request may take across every attempt and wait. */
+    deadlineMs?: number;
+    /** The longest `Retry-After` a 429 or 503 is waited out for; a longer one stands. Default 60s. */
+    maxRetryAfterMs?: number;
+    awaitRecovery?: (error: NetworkError) => Promise<boolean>;
+    /** The transport. The global `fetch` unless a caller supplies its own. */
+    fetchImpl?: typeof fetch;
+    /** This machine's network interfaces, read to tell a failed request from being offline. `os.networkInterfaces` unless given. */
+    interfaces?: () => NodeJS.Dict<NetworkInterfaceInfo[]>;
+}
+export interface ClientOptions {
+    baseUrl: string;
+    /** What the transcript, curl and reports scrub with: one per run, shared by its origin clients. */
+    redactor: Redactor;
+    /** Sent on every request, under everything else. */
+    headers?: Record<string, string> | undefined;
+    /** The config's `cache.bypass`. Default true: every documented read asks past the caches. */
+    cacheBypass?: boolean;
+    /**
+     * Requests allowed in flight at once. Default 4.
+     *
+     * Parallelism past a server's comfort makes every request slower rather than the run
+     * faster — many APIs queue or throttle, so an unbounded burst trades wall-clock for
+     * nothing and risks tripping rate limits that then look like backend defects.
+     */
+    maxInFlight?: number | undefined;
+    onExchange?: (exchange: Exchange) => void | Promise<void> | undefined;
+    /** Paces requests per declared category. */
+    rateLimiter?: RateLimiter | undefined;
+    /** Observes each dispatch. `start` runs just before `fetch`; `end` always follows. */
+    httpHooks?: HttpHooks | undefined;
+    network?: NetworkClientOptions | undefined;
+    /** Every request, redirect hops included, asks this first; a refused one is never sent. */
+    fence?: Fence | undefined;
+    /** Per-request headers, merged after `headers` and before the principal's credential. */
+    resolveHeaders?: HeaderResolver | undefined;
+    operationResolver?: OperationResolver | undefined;
+    /** What each request's actor sends. Without one, only anonymous requests can be sent. */
+    credentials?: CredentialSource | undefined;
+    /** How much of the transcript's bodies stays in memory, and where the encrypted rest is spooled. */
+    transcript?: SpoolOptions | undefined;
+    /**
+     * The schema verdict on a response body the transcript keeps only by reference, taken while the
+     * whole body is still at hand; `undefined` when its operation documents no schema for the status.
+     */
+    validateAtCapture?: ((exchange: Exchange) => SchemaVerdict | undefined) | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/client/types.js

@@ -0,0 +1,3 @@
+/** The client's request, wiring and policy shapes. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/config/define/define-config.d.ts

@@ -0,0 +1,18 @@
+/** `defineConfig`: the typed entry point of a config file. */
+import type { ApiConfig } from "../types/config.ts";
+/**
+ * Identity function that gives a config file full type checking and editor completion.
+ *
+ * ```ts
+ * import { defineConfig, env } from "@workerstack/testing/api"
+ *
+ * export default defineConfig({
+ *   spec: "https://api.example.com/openapi.json",
+ *   baseUrl: "https://api.example.com",
+ *   security: { bearer: { static: env("TOKEN") } },
+ *   principals: { alpha: { tenant: "acme" } },
+ * })
+ * ```
+ */
+export declare function defineConfig(config: ApiConfig): ApiConfig;
+//# sourceMappingURL=define-config.d.ts.map

package/dist/api/config/define/define-config.js

@@ -0,0 +1,19 @@
+/** `defineConfig`: the typed entry point of a config file. */
+/**
+ * Identity function that gives a config file full type checking and editor completion.
+ *
+ * ```ts
+ * import { defineConfig, env } from "@workerstack/testing/api"
+ *
+ * export default defineConfig({
+ *   spec: "https://api.example.com/openapi.json",
+ *   baseUrl: "https://api.example.com",
+ *   security: { bearer: { static: env("TOKEN") } },
+ *   principals: { alpha: { tenant: "acme" } },
+ * })
+ * ```
+ */
+export function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=define-config.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * The public configuration surface — and the single source of truth for its types.
+ *
+ * The runtime imports these definitions rather than declaring its own, so a mistake in a config
+ * is a compile error rather than a surprise at request time. Everything backend-specific lives
+ * here or in `x-*` spec tags; the API tester itself knows nothing about any particular API.
+ */
+export type { EntityConfig, ApiConfig, OriginSpec, PayloadPolicy, ProfileSpec, QueryConfig, RateLimitSpec, SpecOverlay, TargetVersionSpec, } from "../types/config.ts";
+export type { FenceDecision, FenceRequest, HeaderRequest, Hooks, InputRequest, OutOfBandConfig, OutOfBandRequest, PathValueRequest, QueryCapabilitiesRequest, RemovalVerdict, RemovedRecord, SideEffectRequest, TeardownPrincipalContext, UploadFile, UploadRequest, UploadResolution, Uploads, } from "../types/hooks.ts";
+export type { PrincipalEntry, PrincipalsConfig, Recipe, SecurityConfig } from "../types/security.ts";
+export type { DeclaredFilterGrammar, DeclaredSortGrammar, FieldType, FilterableField, FilterableFrom, FilterOp, Nulls, QueryCapabilities, QueryEnvelopeNames, QueryEnvelopeRole, QueryParamNames, QueryParamRole, SearchMode, SelectRelation, SortableField, } from "../types/query.ts";
+export type { AuthStep, ExternalStep, ExternalsConfig, OperationStep, OutOfBandStep, RequestStep, Scenario, ScenarioAssert, ScenarioRequestStep, ScenarioStep, } from "../types/steps.ts";
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * The public configuration surface — and the single source of truth for its types.
+ *
+ * The runtime imports these definitions rather than declaring its own, so a mistake in a config
+ * is a compile error rather than a surprise at request time. Everything backend-specific lives
+ * here or in `x-*` spec tags; the API tester itself knows nothing about any particular API.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,10 @@
+/** The variable that defers an unset `env()` to its `${NAME}` literal, when it is exactly "1". */
+export declare const DEFER_ENV = "TESTING_API_DEFER_ENV";
+export declare class MissingEnvError extends Error {
+    readonly variable: string;
+    name: string;
+    constructor(variable: string);
+}
+/** The value of `name` in the environment; throws when it is unset or empty, unless the load defers it. */
+export declare function env(name: string, environment?: Readonly<Record<string, string | undefined>>): string;
+//# sourceMappingURL=env.d.ts.map

package/dist/api/config/env.js

@@ -0,0 +1,31 @@
+/*
+ * A config reads its secrets through `env(name)`. An unset or empty variable stops the load,
+ * naming the variable and the config file: `process.env.TOKEN ?? ""` once sent `Bearer ` with
+ * nothing after it, and every request after that failed as if the backend were at fault.
+ *
+ * `doctor` and `plan` send nothing, so they read a config whose secrets are not set yet: while
+ * their load runs, `TESTING_API_DEFER_ENV` is exactly "1" and an unset variable reads as its `${NAME}`
+ * literal, which the command lists. A process variable is the one signal that reaches the copy of
+ * this module a config imports from the published package. `loadConfig` sets it, or clears it for a
+ * run, around the import alone, so a run never inherits it from the shell.
+ */
+/** The variable that defers an unset `env()` to its `${NAME}` literal, when it is exactly "1". */
+export const DEFER_ENV = "TESTING_API_DEFER_ENV";
+export class MissingEnvError extends Error {
+    variable;
+    name = "MissingEnvError";
+    constructor(variable) {
+        super(`testing api: env ${variable} is not set`);
+        this.variable = variable;
+    }
+}
+/** The value of `name` in the environment; throws when it is unset or empty, unless the load defers it. */
+export function env(name, environment = process.env) {
+    const value = environment[name];
+    if (value !== undefined && value !== "")
+        return value;
+    if (environment[DEFER_ENV] === "1")
+        return `\${${name}}`;
+    throw new MissingEnvError(name);
+}
+//# sourceMappingURL=env.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * Config loading. A config is a `.js`/`.mjs`/`.ts` module with a default export, or a `.json`
+ * file. TypeScript configs load where the runtime strips types, which the API tester's Node floor (22.18) does
+ * by default; the error says so rather than failing obscurely.
+ */
+import type { ApiConfig } from "./types/config.ts";
+/** How a config is loaded: `doctor` and `plan` defer an unset `env()` instead of stopping. */
+export interface LoadOptions {
+    deferEnv?: boolean;
+}
+export declare function loadConfig(path: string, options?: LoadOptions): Promise<ApiConfig>;
+/** How `interpolate` treats a name the environment lacks. */
+export interface InterpolateOptions {
+    /** When given, an unset `${NAME}` is left as written and its name added here, instead of stopping. */
+    unset?: Set<string>;
+}
+/** Env-var interpolation so configs can carry `${API_TOKEN}` without embedding secrets. */
+export declare function interpolate<T>(value: T, env?: Record<string, string | undefined>, options?: InterpolateOptions): T;
+//# sourceMappingURL=load.d.ts.map

package/dist/api/config/load.js

@@ -0,0 +1,87 @@
+/**
+ * Config loading. A config is a `.js`/`.mjs`/`.ts` module with a default export, or a `.json`
+ * file. TypeScript configs load where the runtime strips types, which the API tester's Node floor (22.18) does
+ * by default; the error says so rather than failing obscurely.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DEFER_ENV, MissingEnvError } from "./env.js";
+export async function loadConfig(path, options = {}) {
+    const absolute = isAbsolute(path) ? path : resolve(process.cwd(), path);
+    if (absolute.endsWith(".json")) {
+        return JSON.parse(await readFile(absolute, "utf8"));
+    }
+    const deferEnv = options.deferEnv === true;
+    const previous = process.env[DEFER_ENV];
+    /* Set for doctor and plan, cleared for a run: a run never inherits deferral from the shell. */
+    if (deferEnv)
+        process.env[DEFER_ENV] = "1";
+    else
+        delete process.env[DEFER_ENV];
+    try {
+        /* Each mode is its own module instance: a load in one mode never hands back the other's values. */
+        const url = `${pathToFileURL(absolute).href}${deferEnv ? "?testing-defer-env" : ""}`;
+        const module = (await import(__rewriteRelativeImportExtension(url)));
+        const config = module.default ?? module;
+        if (typeof config !== "object") {
+            throw new Error("config module has no default export");
+        }
+        return config;
+    }
+    catch (error) {
+        if (error instanceof MissingEnvError)
+            throw new Error(`${error.message} (${path})`, { cause: error });
+        const message = error instanceof Error ? error.message : String(error);
+        if (absolute.endsWith(".ts") && /Unknown file extension|strip-types/.test(message)) {
+            throw new Error(`testing api: cannot load ${path} — this Node cannot import TypeScript ` +
+                "(the API tester needs 22.18 or later, without --no-experimental-strip-types); or use a .js/.mjs config", { cause: error });
+        }
+        throw new Error(`testing api: failed to load config ${path}: ${message}`, { cause: error });
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env[DEFER_ENV];
+        else
+            process.env[DEFER_ENV] = previous;
+    }
+}
+function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Env-var interpolation so configs can carry `${API_TOKEN}` without embedding secrets. */
+export function interpolate(value, env = process.env, options = {}) {
+    if (typeof value === "string") {
+        return value.replace(/\$\{([A-Z0-9_]+)\}/gi, (match, name) => {
+            const resolved = env[name];
+            if (resolved !== undefined)
+                return resolved;
+            if (options.unset === undefined) {
+                throw new Error(`testing api: config references \${${name}}, which is not set in the environment`);
+            }
+            options.unset.add(name);
+            return match;
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((item) => interpolate(item, env, options));
+    /* Only plain data is walked. Anything else — an upload's bytes, a date — is the author's object. */
+    if (value !== null && typeof value === "object" && isPlainObject(value)) {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = interpolate(item, env, options);
+        }
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=load.js.map

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

@@ -0,0 +1,282 @@
+import type { Hooks, OutOfBandConfig, Uploads } from "./hooks.ts";
+import type { DeclaredFilterGrammar, DeclaredSortGrammar, QueryCapabilities, QueryEnvelopeNames, QueryParamNames } from "./query.ts";
+import type { PrincipalsConfig, SecurityConfig } from "./security.ts";
+import type { ExternalsConfig, Scenario } from "./steps.ts";
+/** Per-entity overlays. Only `query` is in scope this release. Unknown names are ignored. */
+export interface EntityConfig {
+    query?: QueryConfig;
+}
+/** Query capabilities, plus the grammar filter terms are written in when the API tester cannot infer it. */
+export type QueryConfig = QueryCapabilities & {
+    /** A preset name or a template; outranks `x-query.grammar`. See docs/api/configuration/reference.md. */
+    grammar?: DeclaredFilterGrammar;
+    /** A preset name or a template; outranks `x-query.sortGrammar`. */
+    sortGrammar?: DeclaredSortGrammar;
+    /**
+     * The parameter each role is sent in, run-wide; outranks `x-query.params`. Per operation, use the
+     * overlay. A name no operation declares stops the run.
+     */
+    params?: QueryParamNames;
+    /**
+     * The response field each paging fact is read from, run-wide; outranks `x-query.envelope`. A name no
+     * list response declares stops the run.
+     */
+    envelope?: QueryEnvelopeNames;
+};
+/** A second host with its own OpenAPI. Its schemes send the primary's credentials only where `security` maps them. */
+export interface OriginSpec {
+    id: string;
+    baseUrl: string;
+    /** This origin's document, read as the primary `spec` is: a relative path from this config's folder. */
+    spec: string;
+    /** Requests per second this origin takes from the API tester in all, as `maxRps` is for `baseUrl`. */
+    maxRps?: number;
+    /** Patches to this origin's document, as `overlay` is for the primary. */
+    overlay?: SpecOverlay;
+    /** Which primary recipe each of this origin's schemes sends, e.g. `{ bearer: "jwt" }`. An unmapped scheme sends nothing. */
+    security?: Record<string, string>;
+}
+/**
+ * Which operations a run is allowed to touch, filtering on what `x-cost` / `x-destructive`
+ * already declare (parsed onto every `OperationModel`, unconsulted until a profile selects one).
+ *
+ * Two profiles always exist without being declared here: `"full"` (no gating — today's default
+ * behavior) and `"cheap"` (`{ maxCost: "low" }`). Anything more specific than a cost band —
+ * "skip the extraction endpoints that call a paid inference API" — is a named entry here.
+ */
+export interface ProfileSpec {
+    /** Inclusive ceiling. An operation costing more than this is excluded. */
+    maxCost?: "low" | "medium" | "high";
+    /** Excludes every operation declaring `x-destructive: true`. */
+    excludeDestructive?: boolean;
+    /** Exact `operationId`s to exclude regardless of cost or destructiveness — the escape hatch. */
+    exclude?: string[];
+    /** Skips each scenario with a step whose external has one of these `externals.kinds`. */
+    excludeExternalKinds?: string[];
+}
+/**
+ * A path/operation matcher paired with a rate, independent of any `x-rate-limit` tag — this is
+ * what keeps the API tester able to pace itself against a backend that has not adopted the tag yet, or
+ * against an environment (staging, usually) whose real limit differs from what the document
+ * claims for production.
+ */
+export interface RateLimitSpec {
+    /**
+     * One of: an exact `operationId`; a path pattern such as `/v1/auth/*` (optionally prefixed
+     * with a method, `POST /v1/auth/login`), `*` matching one path segment; or `category:<name>`
+     * to target every operation whose `x-rate-limit` tag declares that category, without
+     * enumerating its routes.
+     */
+    match: string;
+    rps: number;
+    /**
+     * Bucket name to share with a tag-declared category — lets one rule override the rate for an
+     * entire category. Defaults to `match`, so a route-scoped rule still works standalone.
+     */
+    category?: string;
+}
+/** How much of the string payload catalog a run sends. */
+export type PayloadPolicy = "full" | "per-write-path";
+/** Checks that run only when switched on, by check id. Every other check runs wherever it applies. */
+export interface CheckSwitches {
+    /**
+     * Sends failed logins, for an identity that does not exist, until the login answers 429 or a cap
+     * is reached. Off by default: a throttle that counts by address or client can still slow every
+     * login from the machine running the API tester for a while.
+     */
+    "auth.login-throttled"?: boolean;
+}
+export interface ApiConfig {
+    /** Declared flows for operations the matrix cannot reach. See `Scenario`. */
+    scenarios?: Scenario[];
+    /** Each scenario external's kind, which a profile's `excludeExternalKinds` can leave out. */
+    externals?: ExternalsConfig;
+    /** OpenAPI document — an http(s) URL, a filesystem path relative to this config, or a route below `baseUrl`. JSON or YAML. */
+    spec: string;
+    /** Backend under test. */
+    baseUrl: string;
+    /**
+     * At least one principal, by id. Isolation needs a second with a different `tenant`. A lattice
+     * needs several that share a tenant and differ in `rank`. Extra principals are not ignored.
+     */
+    principals: PrincipalsConfig;
+    /** The principal that writes: makes the records every check works on. Unset, the first principal. */
+    writer?: string;
+    /** How each scheme the document declares gets its credential: one recipe per scheme. */
+    security?: SecurityConfig;
+    hooks?: Hooks;
+    /** File pool for multipart / binary parts. `resolveUpload` lives on `hooks`. */
+    uploads?: Uploads;
+    /**
+     * Sent on every request; never a credential, which its scheme places. Request-id / correlation-id
+     * headers are recorded on each exchange; the rest is opaque.
+     */
+    globalHeaders?: Record<string, string>;
+    /**
+     * The cache bypass the API tester sends on every documented read: the read's `x-consistency` bypass, else
+     * `Cache-Control: no-cache`. `bypass: false` sends none, for an API whose firewall refuses the
+     * header or whose caches are to be tested as they are. A header `globalHeaders` sets wins.
+     */
+    cache?: {
+        bypass?: boolean;
+    };
+    /** Header names whose values are secret though they carry no credential, scrubbed wherever a run records them. */
+    redact?: {
+        headers?: string[];
+    };
+    /**
+     * Extra hosts, each with its own document. Do not merge those routes into the primary spec.
+     * After primary auth, the API tester binds the same principals and runs the matrix against each origin.
+     * A second `defineConfig` can also reuse `.testing/api/runs/latest/principals.json` via `loadPersistedPrincipals`.
+     */
+    origins?: OriginSpec[];
+    /**
+     * Patches to a document you cannot change, applied before the API tester reads it: operations by
+     * `operationId`, component schemas by name. Objects merge, arrays replace, `null` deletes. A
+     * patch naming nothing in the document stops the run with a usage error.
+     */
+    overlay?: SpecOverlay;
+    /**
+     * The only operationIds the API tester may call. Every other operation leaves the document after the
+     * overlay and before the API tester reads it, so neither the matrix, the contract floor, scenarios nor
+     * teardown can reach it. An entry naming nothing, or an auth or scenario step needing a removed
+     * operation, stops the run with a usage error.
+     */
+    allow?: string[];
+    /** `failRun: false` keeps a run whose requests `hooks.beforeRequest` refused from failing on that alone. */
+    fence?: {
+        failRun?: boolean;
+    };
+    /**
+     * `verify: false` skips reading each list again after teardown. By default a record still
+     * listed after its delete answered 2xx is reported as a leftover.
+     */
+    teardown?: {
+        verify?: boolean;
+    };
+    /**
+     * A file of known findings, as `testing api baseline --from <run>` writes it, relative to this config.
+     * A finding it names is reported as known and does not fail the run; an entry nothing matches
+     * is reported as fixed.
+     */
+    baseline?: string;
+    /**
+     * Where the backend says which build it is, read once after sign-in: an `operationId` or a
+     * `path`, and `from` — `$.json.path` into the body or `header:<name>`. Reports and `testing api diff`
+     * show it; a version that cannot be read is noted and never fails the run.
+     */
+    targetVersion?: TargetVersionSpec;
+    /**
+     * Backoff for `resolveOutOfBand`.
+     * Defaults: `{ attempts: 6, initialMs: 200, maxMs: 3000 }` (~9s worst case).
+     */
+    outOfBand?: OutOfBandConfig;
+    /**
+     * How much of the 159-case string payload catalog to send. `"per-write-path"` (the default)
+     * sends all of it once per distinct write path — request media type and field type — and a
+     * representative family of each kind elsewhere; `"full"` sends all of it to every field.
+     */
+    payloads?: PayloadPolicy;
+    /** Checks switched on that do not run by default: `{ "auth.login-throttled": true }`. */
+    checks?: CheckSwitches;
+    /** Fixture generation derives from this, so a failing run is exactly reproducible. */
+    seed?: number;
+    /** Instances seeded per entity. Larger cohorts discriminate more, and cost more. */
+    cohortSize?: number;
+    /** Requests allowed in flight at once. Past a server's comfort this makes runs slower. */
+    maxInFlight?: number;
+    /**
+     * Requests per second the API tester sends to `baseUrl` in all, across every route. For a limit no route
+     * declares, such as a CDN or firewall that caps each client IP: tripping it blocks the whole
+     * run. Routes still keep their own `rateLimits` and `x-rate-limit` budgets under it.
+     */
+    maxRps?: number;
+    /** Grade every operation these entities own, and nothing else. Joins `ops` as a union. */
+    only?: string[];
+    /**
+     * Grade only these operationIds; every other operation is support — called to reach or observe
+     * a target, never graded. `*` globs within an id (`row.*`); `<originId>:<operationId>` targets a
+     * secondary origin. `--ops` on the CLI replaces this list.
+     */
+    ops?: string[];
+    /**
+     * Named profiles this run can select between, keyed by name. `"full"` and `"cheap"` exist
+     * implicitly and need no entry here; add one only for a profile a cost band can't express.
+     */
+    profiles?: Record<string, ProfileSpec>;
+    /** Active profile by name. `--profile` on the CLI overrides this. Defaults to `"full"`. */
+    profile?: string;
+    /**
+     * Paces requests per category so the API tester's own traffic never trips a documented rate limit and
+     * reports the trip as a backend defect. Checked before `x-rate-limit` tags for the same
+     * request — the environment-specific belief wins over the document's general claim.
+     */
+    rateLimits?: RateLimitSpec[];
+    /**
+     * Global filter catalog defaults. Overlay on every entity after the list operation's `x-query`.
+     * Does not invent operators — new ops still have to be listed here or on the tag.
+     */
+    query?: QueryConfig;
+    /** Per-entity overlays. Unknown names are ignored (`testing api doctor` warns). */
+    entities?: Record<string, EntityConfig>;
+    /** Leave created records in place instead of tearing them down. */
+    keepFixtures?: boolean;
+    /**
+     * History root, relative to this config. Each run writes `<outDir>/<datetime>/` and updates
+     * `<outDir>/latest`. Defaults to `./.testing/api/runs` in the working directory.
+     */
+    outDir?: string;
+    /**
+     * Persist every HTTP exchange under the run dir (`exchanges.jsonl`, `exchanges/`, `blobs/`).
+     * Default on unless the active profile is `cheap`. CLI `--save-exchanges` /
+     * `--no-save-exchanges` override this. `--quiet` does not.
+     */
+    saveExchanges?: boolean;
+    /**
+     * How a request is asked again. When `fetch` throws (offline, DNS, reset, timeout): 4 retries
+     * (~8s), then wait up to 60s for the link, then stop. A 429 or 503 is waited out per `maxRetryAfterMs`.
+     */
+    network?: {
+        /** The longest `Retry-After` the API tester waits out, in ms (default 60_000); a longer one stands, unretried. */
+        maxRetryAfterMs?: number;
+        retries?: number;
+        /** Pause-and-probe budget after per-request retries, in ms. `0` skips the wait. */
+        waitMs?: number;
+        /**
+         * `AbortSignal` timeout per attempt, in ms. Live `run` defaults to 180_000.
+         * `0` disables it (the request waits for the socket — not recommended for streams).
+         */
+        requestTimeoutMs?: number;
+    };
+}
+/** Where a run reads the target's version from, to stamp the report with it. */
+export interface TargetVersionSpec {
+    /** The operation to read it from. Its path parameters come from the writer's scope. */
+    operationId?: string;
+    /**
+     * A path below the base URL, when no operation in the document serves it. It is read anonymously,
+     * unless `scheme` names the credential the writer sends.
+     */
+    path?: string;
+    /** The declared scheme a `path` read sends as the writer. Without it the read is anonymous. */
+    scheme?: string;
+    /** `$.json.path` into the body, or `header:<name>`. */
+    from: string;
+}
+/**
+ * Patches to a document the tester cannot change, applied from config before anything reads it.
+ */
+export interface SpecOverlay {
+    /** Patches by `operationId`. A patch's own `operationId` renames the operation. */
+    operations?: Record<string, Record<string, unknown>>;
+    /** Patches by component schema name. */
+    schemas?: Record<string, Record<string, unknown>>;
+    /**
+     * Security schemes merged into `components.securitySchemes`: a new name declares a scheme the
+     * document lacks, a known one is patched, and `null` deletes it.
+     */
+    securitySchemes?: Record<string, Record<string, unknown> | null>;
+    /** The document's root `security`, replaced: `[{ bearer: [] }]` requires that scheme everywhere it is not overridden. */
+    security?: Array<Record<string, string[]>>;
+}
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1,3 @@
+/* The config file's top level: the target, the principals, and every knob a run reads. */
+export {};
+//# sourceMappingURL=config.js.map