@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/grades.d.ts

@@ -0,0 +1,40 @@
+/** Exchanges by `seq`, which is unique within a run; the journal saves each with its `seq`. */
+export interface PassEvidence {
+    call: number;
+    /**
+     * A later exchange holding `value` at `path`. For a delete: a later read of the same resource
+     * answering `status`, or a later list of its collection where `value` is `absent`.
+     */
+    observation?: {
+        seq: number;
+        path: string;
+        value: string;
+        absent?: true;
+    } | {
+        seq: number;
+        status: number;
+    };
+}
+/** Which checks graded which operations, filled as checks run. */
+export declare class GradeLedger {
+    #private;
+    readonly ran: Map<string, Set<string>>;
+    /** The checks in `ran` that only probed the operation: none of them judged its documented success. */
+    readonly probed: Map<string, Set<string>>;
+    readonly suppressed: Map<string, Set<string>>;
+    readonly needs: Map<string, Set<string>>;
+    readonly evidence: Map<string, PassEvidence>;
+    graded(operations: readonly string[], check: string): void;
+    /**
+     * Graded by a security probe: listed in `ran` for the report, but a probe never judges the
+     * documented success, so it never stands in for the contract floor or for pass evidence.
+     */
+    probedBy(operations: readonly string[], check: string): void;
+    /** Whether some check other than a probe graded the operation. */
+    judged(operation: string): boolean;
+    suppress(operations: readonly string[], check: string): void;
+    skipped(operations: readonly string[], needs: string): void;
+    /** The call behind a pass, and the later read that showed it. An observation is never downgraded. */
+    prove(operation: string, evidence: PassEvidence): void;
+}
+//# sourceMappingURL=grades.d.ts.map

package/dist/api/runtime/grades.js

@@ -0,0 +1,47 @@
+/* What each operation was graded by during a run, and the exchange that proved each pass. */
+/** Which checks graded which operations, filled as checks run. */
+export class GradeLedger {
+    ran = new Map();
+    /** The checks in `ran` that only probed the operation: none of them judged its documented success. */
+    probed = new Map();
+    suppressed = new Map();
+    needs = new Map();
+    evidence = new Map();
+    #add(map, operations, value) {
+        for (const op of operations) {
+            const set = map.get(op) ?? new Set();
+            set.add(value);
+            map.set(op, set);
+        }
+    }
+    graded(operations, check) {
+        this.#add(this.ran, operations, check);
+    }
+    /**
+     * Graded by a security probe: listed in `ran` for the report, but a probe never judges the
+     * documented success, so it never stands in for the contract floor or for pass evidence.
+     */
+    probedBy(operations, check) {
+        this.#add(this.ran, operations, check);
+        this.#add(this.probed, operations, check);
+    }
+    /** Whether some check other than a probe graded the operation. */
+    judged(operation) {
+        const probed = this.probed.get(operation);
+        return [...(this.ran.get(operation) ?? [])].some((check) => probed?.has(check) !== true);
+    }
+    suppress(operations, check) {
+        this.#add(this.suppressed, operations, check);
+    }
+    skipped(operations, needs) {
+        this.#add(this.needs, operations, needs);
+    }
+    /** The call behind a pass, and the later read that showed it. An observation is never downgraded. */
+    prove(operation, evidence) {
+        const known = this.evidence.get(operation);
+        if (known?.observation !== undefined && evidence.observation === undefined)
+            return;
+        this.evidence.set(operation, evidence);
+    }
+}
+//# sourceMappingURL=grades.js.map

package/dist/api/runtime/headers.d.ts

@@ -0,0 +1,6 @@
+/** Header lookup, once: HTTP header names are case-insensitive, and every reader must agree. */
+/** The value of header `name`, matched case-insensitively. */
+export declare function headerValue(headers: Record<string, string>, name: string): string | undefined;
+/** The value of header `name`, unless it is blank — a header sent empty says nothing. */
+export declare function presentHeader(headers: Record<string, string>, name: string): string | undefined;
+//# sourceMappingURL=headers.d.ts.map

package/dist/api/runtime/headers.js

@@ -0,0 +1,16 @@
+/** Header lookup, once: HTTP header names are case-insensitive, and every reader must agree. */
+/** The value of header `name`, matched case-insensitively. */
+export function headerValue(headers, name) {
+    const want = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === want)
+            return value;
+    }
+    return undefined;
+}
+/** The value of header `name`, unless it is blank — a header sent empty says nothing. */
+export function presentHeader(headers, name) {
+    const value = headerValue(headers, name);
+    return value === undefined || value.trim() === "" ? undefined : value;
+}
+//# sourceMappingURL=headers.js.map

package/dist/api/runtime/inferred-create.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A record made by a POST that is not its entity's create: an untagged document files `job.start`
+ * under job as an action, yet its answer names the job it started. Nothing declared it, so it is
+ * ledgered only on evidence: the answer names a new `<entity>_id`, and a read of that id answers
+ * 2xx as the principal that sent the POST. The record is marked inferred.
+ */
+import type { Client } from "../client/client.ts";
+import type { OperationModel, SpecModel } from "../spec/graph/types.ts";
+import type { Exchange } from "./exchange.ts";
+import type { Ledger } from "./teardown/ledger.ts";
+import type { Created } from "./teardown/types.ts";
+/** What an inference reads against: the model, the run's ledger, and the client that sent the POST. */
+export interface InferenceInput {
+    model: SpecModel;
+    ledger: Ledger;
+    client: Client;
+    readable: (op: OperationModel) => boolean;
+}
+/** The POST as the tracker read it: its operation, the parameters its path gave, and the sender. */
+export interface Posted {
+    exchange: Exchange;
+    op: OperationModel;
+    params: Record<string, string>;
+    sender: {
+        principal: string;
+        roots: Record<string, string>;
+    };
+}
+/** The record a POST made, when every condition holds; otherwise `undefined`, and nothing is ledgered. */
+export declare function inferredCreate(input: InferenceInput, posted: Posted): Promise<Created | undefined>;
+//# sourceMappingURL=inferred-create.d.ts.map

package/dist/api/runtime/inferred-create.js

@@ -0,0 +1,99 @@
+/**
+ * A record made by a POST that is not its entity's create: an untagged document files `job.start`
+ * under job as an action, yet its answer names the job it started. Nothing declared it, so it is
+ * ledgered only on evidence: the answer names a new `<entity>_id`, and a read of that id answers
+ * 2xx as the principal that sent the POST. The record is marked inferred.
+ */
+import { UnsatisfiedSecurity } from "../client/credential-source.js";
+import { isNetworkError } from "../errors/network.js";
+import { FencedError } from "./fence.js";
+import { createdId } from "./proven-id.js";
+import { SELF_IDENTITY } from "../spec/sign-up.js";
+import { readPathOf } from "./teardown/routes.js";
+/** The record a POST made, when every condition holds; otherwise `undefined`, and nothing is ledgered. */
+export async function inferredCreate(input, posted) {
+    const named = namedRecord(input.model, posted);
+    if (named === undefined)
+        return undefined;
+    const { entity, id } = named;
+    if (input.ledger.holds(entity.name, id) || (await mentioned(input.client, posted.exchange, id)))
+        return undefined;
+    const created = {
+        entity: entity.name,
+        id,
+        inferred: true,
+        scope: { ...posted.sender.roots, ...posted.params },
+    };
+    return (await readsBack(input, created, posted.sender.principal)) ? created : undefined;
+}
+/* The entity and id a POST's answer names, when the POST could have made that record. */
+function namedRecord(model, posted) {
+    const entity = makerOf(model, posted);
+    const id = entity === undefined ? undefined : answeredId(posted.exchange.responseBody, `${entity.name}_id`);
+    return entity === undefined || id === undefined ? undefined : { entity, id };
+}
+/*
+ * The entity a POST could have made a record of: the one it is filed under, whose create it is not,
+ * with no declared effect, and a path that names no record of that entity.
+ */
+function makerOf(model, { exchange, op }) {
+    const entity = op.entity === null ? undefined : model.entities.get(op.entity);
+    if (exchange.method !== "POST" || entity === undefined || entity.create === op.operationId)
+        return undefined;
+    if (entity.identity === SELF_IDENTITY || op.effects.length > 0 || op.async !== null)
+        return undefined;
+    const read = entity.read === undefined ? undefined : model.byOperationId.get(entity.read);
+    const item = read?.pathParams.at(-1);
+    return item === undefined || op.pathParams.includes(item) ? undefined : entity;
+}
+/* The non-empty string an object answer holds at `key`. */
+function answeredId(answer, key) {
+    if (typeof answer !== "object" || answer === null || Array.isArray(answer))
+        return undefined;
+    const value = answer[key];
+    return typeof value === "string" && value !== "" ? createdId(value) : undefined;
+}
+/* Whether `id` appeared before the POST answered it: in its own request, or in any earlier exchange. */
+async function mentioned(client, exchange, id) {
+    if (names(exchange.url, exchange.requestBody, id))
+        return true;
+    for (const earlier of client.transcript) {
+        if (earlier.seq >= exchange.seq)
+            continue;
+        const whole = await client.hydrate(earlier);
+        if (names(whole.url, whole.requestBody, id) || holdsValue(whole.responseBody, id))
+            return true;
+    }
+    return false;
+}
+/* A URL that has `id` as a path segment or query value, or a body that holds it. */
+function names(url, body, id) {
+    const parsed = new URL(url);
+    const segments = parsed.pathname.split("/").map((segment) => decodeURIComponent(segment));
+    return segments.includes(id) || [...parsed.searchParams.values()].includes(id) || holdsValue(body, id);
+}
+/* Whether `id` is a string anywhere in `value`. */
+function holdsValue(value, id) {
+    if (value === id)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    return Object.values(value).some((inner) => holdsValue(inner, id));
+}
+/* One read of the record as the principal that sent the POST; only a 2xx shows the record exists. */
+async function readsBack(input, created, principal) {
+    const read = readPathOf(input.model, { ...created, owner: { id: principal } });
+    if (read === null || !input.readable(read.op))
+        return false;
+    try {
+        const client = input.client.view({ purpose: "assertion", subject: created.entity });
+        const exchange = await client.get(read.path, { as: { principal }, operationId: read.op.operationId });
+        return exchange.status >= 200 && exchange.status < 300;
+    }
+    catch (error) {
+        if (error instanceof FencedError || error instanceof UnsatisfiedSecurity || isNetworkError(error))
+            return false;
+        throw error;
+    }
+}
+//# sourceMappingURL=inferred-create.js.map

package/dist/api/runtime/input.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lets a hook replace generated JSON fields (Stripe tokens, vendor ids) before the request
+ * is encoded. `null` keeps the generator's value, same contract as `resolveUpload`.
+ */
+import type { Hooks } from "../config/types/hooks.ts";
+import type { JsonSchema } from "../spec/types.ts";
+/** The operation generated fields are sent to, and the schema they follow. */
+export interface InputTarget {
+    operationId: string;
+    schema: JsonSchema | undefined;
+}
+export declare function applyResolveInput(fields: Record<string, unknown>, hook: Hooks["resolveInput"], { operationId, schema }: InputTarget): Promise<Record<string, unknown>>;
+//# sourceMappingURL=input.d.ts.map

package/dist/api/runtime/input.js

@@ -0,0 +1,47 @@
+/**
+ * Lets a hook replace generated JSON fields (Stripe tokens, vendor ids) before the request
+ * is encoded. `null` keeps the generator's value, same contract as `resolveUpload`.
+ */
+export async function applyResolveInput(fields, hook, { operationId, schema }) {
+    if (hook === undefined)
+        return fields;
+    return (await walk(fields, { pointer: "$", schema: schema ?? {} }, { hook, operationId }));
+}
+async function walk(value, { schema, pointer }, resolver) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const record = value;
+    const properties = propertiesOf(schema);
+    const out = { ...record };
+    const names = new Set([...Object.keys(record), ...Object.keys(properties)]);
+    for (const name of names) {
+        const childPointer = pointer === "$" ? `$.${name}` : `${pointer}.${name}`;
+        const childSchema = properties[name];
+        const request = {
+            field: name,
+            operationId: resolver.operationId,
+            pointer: childPointer,
+            schema: childSchema ?? {},
+            value: Object.prototype.hasOwnProperty.call(record, name) ? record[name] : undefined,
+        };
+        const resolved = await resolver.hook(request);
+        if (resolved !== null && resolved !== undefined) {
+            out[name] = resolved;
+            continue;
+        }
+        const current = record[name];
+        if (current !== undefined && childSchema !== undefined) {
+            out[name] = await walk(current, { pointer: childPointer, schema: childSchema }, resolver);
+        }
+    }
+    return out;
+}
+function propertiesOf(schema) {
+    if (schema === null || typeof schema !== "object")
+        return {};
+    const properties = schema.properties;
+    if (properties === null || typeof properties !== "object")
+        return {};
+    return properties;
+}
+//# sourceMappingURL=input.js.map

package/dist/api/runtime/network/fetch.d.ts

@@ -0,0 +1,19 @@
+/** `fetch` with the network policy applied, for the requests made outside the client: the spec load. */
+import { type NetworkWaitInfo } from "./gate.ts";
+export interface NetworkFetchOptions {
+    retries?: number;
+    waitMs?: number;
+    requestTimeoutMs?: number;
+    probe?: () => Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+    onWait?: (info: NetworkWaitInfo) => void;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/**
+ * `fetch` with the same classify / retry / wait policy Client uses, for spec load (no Exchange).
+ */
+export declare function fetchWithNetworkRetry(url: string, init?: RequestInit, options?: NetworkFetchOptions): Promise<Response>;
+/** An OpenAPI document by URL, with the same retries a request gets. Throws on a non-2xx answer. */
+export declare function fetchSpecText(url: string, network?: NetworkFetchOptions): Promise<string>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/api/runtime/network/fetch.js

@@ -0,0 +1,86 @@
+/** `fetch` with the network policy applied, for the requests made outside the client: the spec load. */
+import { classifyNetworkError, describeNetworkFailure, describeNetworkKind, isNetworkError, NetworkError, } from "../../errors/network.js";
+import { sleep } from "../poll.js";
+import { createNetworkGate } from "./gate.js";
+import { refineNetworkKind } from "./interfaces.js";
+import { DEFAULT_NETWORK_RETRIES, DEFAULT_NETWORK_WAIT_MS, networkRetryWaitMs } from "./policy.js";
+import { probeOrigin } from "./probe.js";
+/** One attempt; a network failure comes back as a `NetworkError` naming its kind. */
+async function attemptOnce(call, attempt) {
+    const { url, init, method, fetchImpl, options } = call;
+    try {
+        const initWithTimeout = options.requestTimeoutMs === undefined ? init : { ...init, signal: AbortSignal.timeout(options.requestTimeoutMs) };
+        return await fetchImpl(url, initWithTimeout);
+    }
+    catch (error) {
+        const raw = classifyNetworkError(error);
+        if (raw === null)
+            throw error;
+        const kind = refineNetworkKind(raw);
+        throw new NetworkError({
+            attempts: attempt + 1,
+            cause: error,
+            kind,
+            message: `${method} ${url} failed (${kind}: ${describeNetworkKind(kind)})`,
+            method,
+            url,
+        });
+    }
+}
+function gateOptions(call, pause) {
+    const { options, url, fetchImpl } = call;
+    return {
+        probe: options.probe ?? (() => probeOrigin(url, { fetchImpl })),
+        sleep: pause,
+        waitBudgetMs: options.waitMs ?? DEFAULT_NETWORK_WAIT_MS,
+        ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.onWait === undefined ? {} : { onWait: options.onWait }),
+    };
+}
+function exhaustedError(failed, waitedMs) {
+    return new NetworkError({
+        attempts: failed.attempts,
+        cause: failed,
+        kind: failed.kind,
+        message: describeNetworkFailure(failed, waitedMs),
+        method: failed.method,
+        url: failed.url,
+    });
+}
+/**
+ * `fetch` with the same classify / retry / wait policy Client uses, for spec load (no Exchange).
+ */
+export async function fetchWithNetworkRetry(url, init = {}, options = {}) {
+    const retries = Math.max(0, options.retries ?? DEFAULT_NETWORK_RETRIES);
+    const pause = options.sleep ?? sleep;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const method = (init.method ?? "GET").toUpperCase();
+    const call = { fetchImpl, init, method, options, url };
+    let last;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await attemptOnce(call, attempt);
+        }
+        catch (error) {
+            if (!isNetworkError(error))
+                throw error;
+            last = error;
+            if (attempt < retries)
+                await pause(networkRetryWaitMs(attempt));
+        }
+    }
+    const gate = createNetworkGate(gateOptions(call, pause));
+    /* The loop runs at least once and only falls through after a network failure. */
+    const failed = last;
+    if (await gate.awaitRecovery(failed))
+        return attemptOnce(call, retries + 1);
+    throw exhaustedError(failed, gate.waitedMs);
+}
+/** An OpenAPI document by URL, with the same retries a request gets. Throws on a non-2xx answer. */
+export async function fetchSpecText(url, network) {
+    const res = await fetchWithNetworkRetry(url, { headers: { accept: "application/json" } }, { retries: DEFAULT_NETWORK_RETRIES, waitMs: 0, ...network });
+    if (!res.ok)
+        throw new Error(`testing api: fetching ${url} returned ${res.status} ${res.statusText}`);
+    return res.text();
+}
+//# sourceMappingURL=fetch.js.map

package/dist/api/runtime/network/gate.d.ts

@@ -0,0 +1,23 @@
+/** The one wait for the link a run makes once its retries are spent, shared by every request. */
+import type { NetworkError, NetworkKind } from "../../errors/network.ts";
+export interface NetworkWaitInfo {
+    kind: NetworkKind;
+    elapsedMs: number;
+    remainingMs: number;
+}
+export interface NetworkGate {
+    readonly exhausted: boolean;
+    readonly waitedMs: number;
+    readonly lastKind: NetworkKind | undefined;
+    awaitRecovery(error: NetworkError): Promise<boolean>;
+}
+export interface NetworkGateOptions {
+    waitBudgetMs?: number;
+    probeIntervalMs?: number;
+    probe: () => Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    onWait?: (info: NetworkWaitInfo) => void;
+}
+export declare function createNetworkGate(options: NetworkGateOptions): NetworkGate;
+//# sourceMappingURL=gate.d.ts.map

package/dist/api/runtime/network/gate.js

@@ -0,0 +1,63 @@
+/** The one wait for the link a run makes once its retries are spent, shared by every request. */
+import { sleep } from "../poll.js";
+import { DEFAULT_NETWORK_PROBE_MS, DEFAULT_NETWORK_WAIT_MS } from "./policy.js";
+/** Probes until the link answers or the budget runs out; `false` exhausts the gate for good. */
+async function waitOnce(state, timing, error) {
+    const { options, waitBudgetMs, probeIntervalMs, pause, now } = timing;
+    state.lastKind = error.kind;
+    if (waitBudgetMs === 0) {
+        state.exhausted = true;
+        return false;
+    }
+    const began = now();
+    const deadline = began + waitBudgetMs;
+    options.onWait?.({ elapsedMs: 0, kind: error.kind, remainingMs: waitBudgetMs });
+    while (now() < deadline) {
+        const remaining = deadline - now();
+        await pause(Math.min(probeIntervalMs, Math.max(0, remaining)));
+        state.waitedMs = now() - began;
+        options.onWait?.({
+            elapsedMs: state.waitedMs,
+            kind: error.kind,
+            remainingMs: Math.max(0, deadline - now()),
+        });
+        if (await options.probe())
+            return true;
+    }
+    state.waitedMs = Math.max(state.waitedMs, now() - began);
+    state.exhausted = true;
+    return false;
+}
+export function createNetworkGate(options) {
+    const timing = {
+        now: options.now ?? Date.now,
+        options,
+        pause: options.sleep ?? sleep,
+        probeIntervalMs: Math.max(50, options.probeIntervalMs ?? DEFAULT_NETWORK_PROBE_MS),
+        waitBudgetMs: Math.max(0, options.waitBudgetMs ?? DEFAULT_NETWORK_WAIT_MS),
+    };
+    const state = { exhausted: false, lastKind: undefined, waitedMs: 0 };
+    let inflight;
+    return {
+        get exhausted() {
+            return state.exhausted;
+        },
+        get lastKind() {
+            return state.lastKind;
+        },
+        get waitedMs() {
+            return state.waitedMs;
+        },
+        awaitRecovery(error) {
+            if (state.exhausted)
+                return Promise.resolve(false);
+            if (inflight !== undefined)
+                return inflight;
+            inflight = waitOnce(state, timing, error).finally(() => {
+                inflight = undefined;
+            });
+            return inflight;
+        },
+    };
+}
+//# sourceMappingURL=gate.js.map

package/dist/api/runtime/network/interfaces.d.ts

@@ -0,0 +1,6 @@
+/** Whether this machine has a link at all: a failure with no usable interface is "offline". */
+import { type NetworkInterfaceInfo } from "node:os";
+import type { NetworkKind } from "../../errors/network.ts";
+export declare function refineNetworkKind(kind: NetworkKind, read?: () => NodeJS.Dict<NetworkInterfaceInfo[]>): NetworkKind;
+export declare function hasUsableInterface(read?: () => NodeJS.Dict<NetworkInterfaceInfo[]>): boolean;
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/api/runtime/network/interfaces.js

@@ -0,0 +1,17 @@
+/** Whether this machine has a link at all: a failure with no usable interface is "offline". */
+import { networkInterfaces } from "node:os";
+export function refineNetworkKind(kind, read = networkInterfaces) {
+    if (kind === "offline")
+        return kind;
+    return hasUsableInterface(read) ? kind : "offline";
+}
+export function hasUsableInterface(read = networkInterfaces) {
+    for (const list of Object.values(read())) {
+        for (const info of list ?? []) {
+            if (!info.internal && info.address !== "")
+                return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=interfaces.js.map

package/dist/api/runtime/network/policy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Network failures are not backend defects.
+ *
+ * `fetch` throwing is "the request never happened" — DNS, offline, reset, timeout — and must
+ * not look like a 4xx/5xx or an uncaught `TypeError: fetch failed`. Classify, retry the blip,
+ * then wait once for the link. If it does not come back, one finding names the kind and the
+ * rest of the run stands down. This module holds the policy's numbers.
+ */
+export declare const DEFAULT_NETWORK_RETRIES = 4;
+export declare const DEFAULT_NETWORK_WAIT_MS = 60000;
+export declare const DEFAULT_NETWORK_PROBE_MS = 2000;
+/** Per-attempt `AbortSignal` timeout for live `run`. `0` in config disables it. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 180000;
+/** `undefined` (caller omitted) → default. `0` / non-finite / negative → no timeout. */
+export declare function resolveRequestTimeoutMs(value: number | undefined): number | undefined;
+export declare function networkRetryWaitMs(attempt: number): number;
+//# sourceMappingURL=policy.d.ts.map

package/dist/api/runtime/network/policy.js

@@ -0,0 +1,25 @@
+/**
+ * Network failures are not backend defects.
+ *
+ * `fetch` throwing is "the request never happened" — DNS, offline, reset, timeout — and must
+ * not look like a 4xx/5xx or an uncaught `TypeError: fetch failed`. Classify, retry the blip,
+ * then wait once for the link. If it does not come back, one finding names the kind and the
+ * rest of the run stands down. This module holds the policy's numbers.
+ */
+export const DEFAULT_NETWORK_RETRIES = 4;
+export const DEFAULT_NETWORK_WAIT_MS = 60_000;
+export const DEFAULT_NETWORK_PROBE_MS = 2_000;
+/** Per-attempt `AbortSignal` timeout for live `run`. `0` in config disables it. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 180_000;
+/** `undefined` (caller omitted) → default. `0` / non-finite / negative → no timeout. */
+export function resolveRequestTimeoutMs(value) {
+    if (value === undefined)
+        return DEFAULT_REQUEST_TIMEOUT_MS;
+    if (!Number.isFinite(value) || value <= 0)
+        return undefined;
+    return value;
+}
+export function networkRetryWaitMs(attempt) {
+    return Math.min(4_000, 250 * 2 ** Math.max(0, attempt));
+}
+//# sourceMappingURL=policy.js.map

package/dist/api/runtime/network/probe.d.ts

@@ -0,0 +1,8 @@
+/** Whether an origin answers at all: any HTTP status is a link, only a network failure is not. */
+export interface ProbeOptions {
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    online?: () => boolean;
+}
+export declare function probeOrigin(origin: string, options?: ProbeOptions): Promise<boolean>;
+//# sourceMappingURL=probe.d.ts.map

package/dist/api/runtime/network/probe.js

@@ -0,0 +1,29 @@
+/** Whether an origin answers at all: any HTTP status is a link, only a network failure is not. */
+import { classifyNetworkError } from "../../errors/network.js";
+import { hasUsableInterface } from "./interfaces.js";
+export async function probeOrigin(origin, options = {}) {
+    const online = options.online ?? hasUsableInterface;
+    if (!online())
+        return false;
+    const timeoutMs = options.timeoutMs ?? 2_000;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const response = await fetchImpl(url.origin, {
+            method: "HEAD",
+            redirect: "manual",
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        return response.status > 0;
+    }
+    catch (error) {
+        return classifyNetworkError(error) === null;
+    }
+}
+//# sourceMappingURL=probe.js.map

package/dist/api/runtime/no-security.d.ts

@@ -0,0 +1,4 @@
+import type { OperationModel } from "../spec/graph/types.ts";
+/** Why an anonymous probe of `op` cannot be judged, or `undefined` when its security is declared. */
+export declare function noSecurityReason(op: OperationModel): string | undefined;
+//# sourceMappingURL=no-security.d.ts.map

package/dist/api/runtime/no-security.js

@@ -0,0 +1,9 @@
+/*
+ * An anonymous probe expects a refusal, and only a declared requirement says one is due. A document
+ * that declares no security at all says nothing either way, so the probe stands down untested.
+ */
+/** Why an anonymous probe of `op` cannot be judged, or `undefined` when its security is declared. */
+export function noSecurityReason(op) {
+    return op.security.source === "none" ? "the document declares no security; add an overlay" : undefined;
+}
+//# sourceMappingURL=no-security.js.map

package/dist/api/runtime/nonexistent-identity.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The identity for the field `name`, whose schema is `schema`: `testing-nonexistent-<nonce>`, at RFC
+ * 2606's reserved `.invalid` domain, which never resolves, where the field is an email.
+ */
+export declare function nonexistentIdentity(field: {
+    name: string;
+    schema: unknown;
+}, nonce: string): string;
+//# sourceMappingURL=nonexistent-identity.d.ts.map

package/dist/api/runtime/nonexistent-identity.js

@@ -0,0 +1,18 @@
+/*
+ * An identity no account can hold, for a sign-in the API tester sends without meaning to sign anyone in: a
+ * failed login a throttle counts, or the contract floor's own call. Failed attempts against a real
+ * address count toward that account's lockout, so neither ever names one.
+ */
+/* An email-shaped field: declared `format: email`, or named like one. */
+function isEmail(name, schema) {
+    return schema?.format === "email" || /e-?mail/i.test(name);
+}
+/**
+ * The identity for the field `name`, whose schema is `schema`: `testing-nonexistent-<nonce>`, at RFC
+ * 2606's reserved `.invalid` domain, which never resolves, where the field is an email.
+ */
+export function nonexistentIdentity(field, nonce) {
+    const marked = `testing-nonexistent-${nonce}`;
+    return isEmail(field.name, field.schema) ? `${marked}@example.invalid` : marked;
+}
+//# sourceMappingURL=nonexistent-identity.js.map