@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/README.md

@@ -1,3 +1,136 @@
 # @wirebench/engine
 
-`@wirebench/engine` is an internal dependency of [`@wirebench/cli`](https://github.com/wirebench/wirebench/tree/main/packages/cli) and is published so the CLI can depend on a versioned package rather than a workspace link; it has no stability promise of its own until a 3.0 release. See the [Wirebench repository](https://github.com/wirebench/wirebench) for usage, documentation, and issue tracking.
+`@wirebench/engine` is an internal dependency of [`@wirebench/cli`](https://github.com/wirebench/wirebench/tree/main/packages/cli) and is published so the CLI can depend on a versioned package rather than a workspace link. It has no stability promise of its own: a major release may rename or remove exports, as 3.1 did, and the exports tagged `@internal` may change in any release. See the [Wirebench repository](https://github.com/wirebench/wirebench) for usage, documentation, and issue tracking.
+
+## Migrating to 3.1
+
+3.1 puts every protocol behind one interface ([ADR-0017](https://github.com/wirebench/wirebench/blob/main/docs/adr/0017-a-protocol-is-a-module-behind-one-interface.md)). The main entry's exports changed; nothing was kept as a deprecated alias. The subpaths (`./xml`, `./rest`, `./json`, `./grpc`, `./asyncapi`, `./snapshot`, `./detect`) did not change.
+
+### Renamed
+
+These names read as every protocol's and were WSDL's and SOAP's. Signatures are unchanged.
+
+| 2.x                     | 3.1                        |
+| ----------------------- | -------------------------- |
+| `importDefinition`      | `importWsdl`               |
+| `ImportSource`          | `WsdlImportSource`         |
+| `ImportOptions`         | `WsdlImportOptions`        |
+| `ImportCacheOptions`    | `WsdlImportCacheOptions`   |
+| `ImportProgress`        | `WsdlImportProgress`       |
+| `ImportProblem`         | `WsdlImportProblem`        |
+| `ImportResult`          | `WsdlImportResult`         |
+| `summarizeOperations`   | `summarizeSoapOperations`  |
+| `OperationSummary`      | `SoapOperationSummary`     |
+| `generateRequest`       | `generateSoapRequest`      |
+| `generateEmptyRequest`  | `generateEmptySoapRequest` |
+| `toSendInput`           | `toSoapSendInput`          |
+| `ToSendInputArgs`       | `ToSoapSendInputArgs`      |
+| `SendRequestInput`      | `SoapSendRequestInput`     |
+| `SendAttachmentOptions` | `SoapAttachmentOptions`    |
+
+```ts
+// 2.x
+import { generateRequest, importDefinition } from '@wirebench/engine';
+import type { ImportResult } from '@wirebench/engine';
+
+const result: ImportResult = await importDefinition({ kind: 'file', path: 'calculator.wsdl' });
+const [operation] = result.operations;
+if (operation !== undefined) {
+  const sample = generateRequest(result, {
+    bindingName: operation.bindingName,
+    operationName: operation.operationName,
+  });
+}
+```
+
+```ts
+// 3.1
+import { generateSoapRequest, importWsdl } from '@wirebench/engine';
+import type { WsdlImportResult } from '@wirebench/engine';
+
+const result: WsdlImportResult = await importWsdl({ kind: 'file', path: 'calculator.wsdl' });
+const [operation] = result.operations;
+if (operation !== undefined) {
+  const sample = generateSoapRequest(result, {
+    bindingName: operation.bindingName,
+    operationName: operation.operationName,
+  });
+}
+```
+
+### Removed
+
+| 2.x                                                                              | Use instead                                                                                                                    |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `prepareSend`, `PreparedSend`                                                    | `createRunSender`. A module's own prepare function is internal.                                                                |
+| `assertSupportedKind`, `apiKindOf`                                               | `ProtocolRegistry.status(kind)`, which answers `enabled`, `disabled` or `unknown`.                                             |
+| `RequestDef`                                                                     | `SoapRequestDef`, which it was an alias of.                                                                                    |
+| `scriptTypesFor`                                                                 | The module's `run.scriptTypes`. A run that goes through `createRunSender` or `runRequests` needs neither.                      |
+| `RequestScriptTypes.soap`                                                        | `RequestScriptTypes.binding`, an opaque value the module that made it reads back.                                              |
+| `ProtocolRun.send`                                                               | `ProtocolRun.open`, which returns an `ExchangeHandle` whose `result` rejects with a send's failure, and `ProtocolRun.resolve`. |
+| `RunContext.getSecret`, `proxyFor`, `onSecretValue`, `fetchToken`, `tokenSource` | `RunContext.host`, a `SendHost`: `getSecret`, `proxyFor` (now async), `onSecretValue` and `tokens`.                            |
+| `prepareRest`, `prepareSoap`, `prepareGrpc`                                      | `openExchange` and `resolveExchange`. The modules' prepare functions are internal.                                             |
+| `ScriptProtocol`                                                                 | `string`.                                                                                                                      |
+
+`prepareSend` handed back one of three shapes, and the caller sent it with the matching function. `createRunSender` does both, with the run's caches and the request's scripts:
+
+```ts
+// 2.x
+import { prepareSend, selectRequests, sendRest } from '@wirebench/engine';
+
+const { selected } = selectRequests(project, ['Orders/List orders']);
+for (const item of selected) {
+  const prepared = await prepareSend(item, context);
+  if (prepared.kind === 'rest') {
+    const exchange = await sendRest(prepared.input);
+    console.log(item.path, exchange.status);
+  }
+}
+```
+
+```ts
+// 3.1
+import { createRunSender, selectRequests } from '@wirebench/engine';
+
+const { selected } = selectRequests(project, ['Orders/List orders']);
+const send = createRunSender(context);
+for (const item of selected) {
+  const sent = await send(item);
+  console.log(item.path, sent.subject.status);
+}
+```
+
+`sent.exchange` holds the whole SOAP or REST exchange when a host needs more than the status, and `sendSoapRequest`, `sendRest` and `callGrpc` are still exported for a caller that builds its own input.
+
+`ProtocolRun.send` returned the finished exchange. `open` starts the send and returns a handle: its `events` are the live events (read only when `ExchangeOptions.live` is true), `push`, `halfClose` and `close` drive a stream, `cancel` ends this send only, and `result` settles with what `send` returned or rejects with its error. `interactive` is true when the host drives the messages itself; otherwise the request's saved messages are sent. A push, half-close or close on a send that takes no messages is refused with `exchange-not-streaming`. `resolve` is the first step alone, with nothing connected.
+
+```ts
+// 2.x
+const context = { project, projectDir, overrides: {}, getSecret, proxyFor, tokenSource };
+const sent = await module.run.send(item, scope);
+```
+
+```ts
+// 3.1
+import { openExchange } from '@wirebench/engine';
+
+const context = { project, projectDir, overrides: {}, host: { getSecret, proxyFor, tokens } };
+const handle = openExchange(item, context.host, {
+  scope: createRunScope(context),
+  interactive: false,
+  run: true,
+});
+const sent = await handle.result;
+```
+
+`SendHost` carries what a host lends a send. Only `getSecret` is required; where a member is absent the send behaves as the command line's does. A run (`ExchangeOptions.run`) waits for a stream's answer within the run's timeout and fails a stream the timeout cuts with `timeout`.
+
+### Widened
+
+`RequestResult.protocol`, `AssertionSubject.protocol` and `ScriptedRequest.protocol` were the union `'soap' | 'rest' | 'grpc'` and are now `string`. Code that copies one of them into a closed union needs a check first; a comparison such as `result.protocol === 'grpc'` compiles as before.
+
+### Added
+
+`openExchange`, `resolveExchange`, `SendHost`, `SendFailure`, `ClientIdentity`, `AttemptedRequest`, `ExchangeHandle`, `ExchangeOptions`, `ExchangeController`, `exchangeController`, `notStreaming`, `PushMessage`, `StreamingSide`, `LiveEventBase`, `EventQueue` and `createRunScope`, for the send path above, and `ProtocolModule` and its facets (`ProtocolStorage`, `ProtocolRun`, `ProtocolScripting`), `defineProtocol`, `ProtocolRegistry`, `createProtocolRegistry`, `createBuiltinRegistry`, `BUILTIN_PROTOCOLS`, `FeatureDescriptor`, `FeatureSet`, `createFeatureSet`, `UnsupportedContainer`, `unsupportedOf`, `extraContainersOf`, `takenContainerSlugs`, `grpcStatusNames`, `StatusNames`, `SnapshotFacts`, `SelectedBase`, `RunGroup`, `RunScope`, `ScriptedSend`, `ContainerBase`, `ContainerDir`, `LoadContext`, `RequestSnapshotBase`, `ResponseSnapshotBase`, `ProtocolRegistryOptions`, `WhyDisabled`, `Project.unsupported`, `Project.extraContainers` and `AssertionSubject.statusNames`. They are exported for Wirebench's own hosts and tagged `@internal`: they are not a plugin API, and they may change in any release. `RunContext` also gains an optional `registry`; it is not tagged, as `RunContext` stays part of the run API.
+
+A project can now hold containers the engine did not load: one whose `kind` has no module in the build, or whose protocol is switched off. `loadProject` reports each as a `container-unsupported` problem and lists it in `Project.unsupported`; `saveProject` leaves its files untouched. A host that lists a project's containers should list these too, as not loaded.

package/dist/account/schema.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `userData/accounts.yaml` (identity spec §4.3): the servers this installation knows and who it
+ * is signed in as on each. The token itself is never here — `tokenRef` names a secret-store
+ * entry — so the file is safe to read by the CLI later and to show in a bug report.
+ */
+import { z } from 'zod';
+export declare const ACCOUNTS_FILE_VERSION = 1;
+export declare const serverAccountSchema: z.ZodObject<{
+    url: z.ZodString;
+    userId: z.ZodString;
+    email: z.ZodString;
+    displayName: z.ZodString;
+    deviceName: z.ZodString;
+    tokenRef: z.ZodString;
+    signedOut: z.ZodOptional<z.ZodLiteral<true>>;
+    addedAt: z.ZodString;
+}, z.core.$strip>;
+export type ServerAccount = z.infer<typeof serverAccountSchema>;
+export declare const accountsFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    servers: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        userId: z.ZodString;
+        email: z.ZodString;
+        displayName: z.ZodString;
+        deviceName: z.ZodString;
+        tokenRef: z.ZodString;
+        signedOut: z.ZodOptional<z.ZodLiteral<true>>;
+        addedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AccountsFile = z.infer<typeof accountsFileSchema>;
+/** A missing, malformed or newer file yields no accounts rather than a crash at start-up. */
+export declare function parseAccountsFile(document: unknown): AccountsFile;

package/dist/account/schema.js

@@ -0,0 +1,29 @@
+/**
+ * `userData/accounts.yaml` (identity spec §4.3): the servers this installation knows and who it
+ * is signed in as on each. The token itself is never here — `tokenRef` names a secret-store
+ * entry — so the file is safe to read by the CLI later and to show in a bug report.
+ */
+import { z } from 'zod';
+export const ACCOUNTS_FILE_VERSION = 1;
+export const serverAccountSchema = z.object({
+    /** The server's origin, as `GET /api/v1/meta` reports its `publicUrl`. */
+    url: z.string().url(),
+    userId: z.string(),
+    email: z.string(),
+    displayName: z.string(),
+    deviceName: z.string(),
+    /** A `SecretStore` ref (`sec_…`), never the token. */
+    tokenRef: z.string().regex(/^sec_[0-9a-f]{26}$/),
+    /** Set when the server last answered `identity-unauthenticated`; cleared by a new sign-in. */
+    signedOut: z.literal(true).optional(),
+    addedAt: z.string(),
+});
+export const accountsFileSchema = z.object({
+    version: z.literal(ACCOUNTS_FILE_VERSION),
+    servers: z.array(serverAccountSchema),
+});
+/** A missing, malformed or newer file yields no accounts rather than a crash at start-up. */
+export function parseAccountsFile(document) {
+    const parsed = accountsFileSchema.safeParse(document);
+    return parsed.success ? parsed.data : { version: ACCOUNTS_FILE_VERSION, servers: [] };
+}

package/dist/assert/callback.d.ts

@@ -0,0 +1,76 @@
+import type { PropertyScopes } from '../project/properties.js';
+import type { CaptureSource } from './capture-source.js';
+import type { AssertionResult, CallbackAssertion, StepAssertion } from './model.js';
+/** The clock a wait polls by. */
+export interface CallbackClock {
+    /** Milliseconds on a monotonic clock. */
+    now(): number;
+    /** Resolves after `ms`, or at once when `signal` aborts. */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+export declare const realCallbackClock: CallbackClock;
+/** What a run reports while a step waits (the desktop's run panel, the CLI on a terminal). */
+export interface CallbackWaiting {
+    readonly label: string;
+    readonly catchUrl: string;
+    readonly withinMs: number;
+}
+export type PendingCallback = {
+    readonly kind: 'ready';
+    readonly assertion: CallbackAssertion;
+    readonly hookId: string;
+    readonly cursor: string | null;
+} | {
+    readonly kind: 'errored';
+    readonly assertion: CallbackAssertion;
+    readonly message: string;
+};
+/** The engine's own wording; the desktop and the CLI hand over a source with their own (§2.4). */
+export declare const NO_CAPTURE_SOURCE_MESSAGE = "no Wirebench Server is configured to check callbacks";
+export declare function isCallbackAssertion(assertion: StepAssertion): assertion is CallbackAssertion;
+/**
+ * `${…}` expanded in the assertion's values: every `equals` and `matches` in `match` and `expect`
+ * (§2.1). Names, paths and the method stay as written. Values expand like every other assertion's,
+ * so an expanded value (a `${#System#…}` one included) can show in a failure message.
+ */
+export declare function expandCallback(assertion: CallbackAssertion, scopes: PropertyScopes): CallbackAssertion;
+/**
+ * Before the send (§2.3 step 1): resolves each catch URL and takes its cursor. A missing source, an
+ * unknown name or a source error makes that assertion errored without stopping the send.
+ */
+export declare function prepareCallbacks(assertions: readonly CallbackAssertion[], captures: CaptureSource | undefined): Promise<PendingCallback[]>;
+/** What is about to be waited for: the ready ones. */
+export declare function waitingOf(pending: readonly PendingCallback[]): CallbackWaiting[];
+/** `30` for whole seconds, `1.5` otherwise: how a callback's wait reads in messages. */
+export declare function seconds(ms: number): string;
+export interface AwaitCallbacksOptions {
+    readonly captures: CaptureSource | undefined;
+    /** `clock.now()` when the send finished: `withinMs` counts from here. */
+    readonly sentAt: number;
+    readonly clock?: CallbackClock;
+    /** `CALLBACK_LIMITS.pollIntervalMs` unless a test says otherwise. */
+    readonly pollIntervalMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** After the send (§2.3 steps 2–4): every pending callback waits at once; the longest sets the total. */
+export declare function awaitCallbacks(pending: readonly PendingCallback[], options: AwaitCallbacksOptions): Promise<AssertionResult[]>;
+/** How a run waits for callbacks; the same for a selected request and a sequence step. */
+export interface CallbackWiring {
+    readonly captures?: CaptureSource;
+    readonly clock?: CallbackClock;
+    /** `CALLBACK_LIMITS.pollIntervalMs` unless a test says otherwise. */
+    readonly pollIntervalMs?: number;
+    readonly signal?: AbortSignal;
+    /** Called after the send, before the wait, when there is something to wait for. */
+    readonly onWaiting?: (waiting: readonly CallbackWaiting[]) => void;
+}
+/**
+ * The prepare → send → await wiring of §2.3, shared by `runRequests` and a sequence run so the
+ * cursor is always taken before the send. `scopes` is asked only when `assertions` hold a callback
+ * assertion, so a request without one does no extra work. `send` may throw; a throw before or in it
+ * abandons the wait. The callers evaluate their other assertions from `sent`, then merge `callbacks`.
+ */
+export declare function sendAwaitingCallbacks<T>(assertions: readonly StepAssertion[], scopes: () => PropertyScopes, send: () => Promise<T>, wiring: CallbackWiring): Promise<{
+    readonly sent: T;
+    readonly callbacks: AssertionResult[];
+}>;

package/dist/assert/callback.js

@@ -0,0 +1,320 @@
+/**
+ * Callback assertions (callback-assertion spec §2.3, §2.4). A run calls three steps in order:
+ * `expandCallback` and `prepareCallbacks` before the send, so the cursor predates anything the send
+ * can cause, then `awaitCallbacks` after the send and the step's other assertions. Time comes from a
+ * `CallbackClock`, so tests wait for nothing.
+ *
+ * `match` picks and `expect` checks. The first capture after the cursor that fits every part of
+ * `match` is the one checked; a method or path that differs is decided from the summary alone, so
+ * no detail is read for it. Nothing from a capture flows to later steps.
+ */
+import { expand } from '../project/properties.js';
+import { parseXml } from '../xml/parse.js';
+import { evaluateWithTimeout, matchRegexWithTimeout } from '../xpath/evaluate-async.js';
+import { firstHeaderValue } from './header.js';
+import { firstText } from './match.js';
+import { CALLBACK_LIMITS, callbackLabel } from './model.js';
+export const realCallbackClock = {
+    now: () => performance.now(),
+    sleep: (ms, signal) => new Promise((resolve) => {
+        if (signal?.aborted === true) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener('abort', finish, { once: true });
+        function finish() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', finish);
+            resolve();
+        }
+    }),
+};
+/** The engine's own wording; the desktop and the CLI hand over a source with their own (§2.4). */
+export const NO_CAPTURE_SOURCE_MESSAGE = 'no Wirebench Server is configured to check callbacks';
+export function isCallbackAssertion(assertion) {
+    return assertion.type === 'callback';
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function expandCheck(check, text) {
+    return {
+        ...check,
+        ...(check.equals !== undefined ? { equals: text(check.equals) } : {}),
+        ...(check.matches !== undefined ? { matches: text(check.matches) } : {}),
+    };
+}
+/**
+ * `${…}` expanded in the assertion's values: every `equals` and `matches` in `match` and `expect`
+ * (§2.1). Names, paths and the method stay as written. Values expand like every other assertion's,
+ * so an expanded value (a `${#System#…}` one included) can show in a failure message.
+ */
+export function expandCallback(assertion, scopes) {
+    const text = (value) => expand(value, scopes).text;
+    const { match } = assertion;
+    return {
+        ...assertion,
+        match: {
+            ...match,
+            ...(match.headers !== undefined ? { headers: match.headers.map((header) => expandCheck(header, text)) } : {}),
+            ...(match.body !== undefined ? { body: expandCheck(match.body, text) } : {}),
+        },
+        expect: assertion.expect.map((check) => 'body' in check
+            ? { body: expandCheck(check.body, text) }
+            : 'header' in check
+                ? { header: expandCheck(check.header, text) }
+                : check),
+    };
+}
+/**
+ * Before the send (§2.3 step 1): resolves each catch URL and takes its cursor. A missing source, an
+ * unknown name or a source error makes that assertion errored without stopping the send.
+ */
+export function prepareCallbacks(assertions, captures) {
+    return Promise.all(assertions.map(async (assertion) => {
+        if (captures === undefined) {
+            return { kind: 'errored', assertion, message: NO_CAPTURE_SOURCE_MESSAGE };
+        }
+        try {
+            const found = await captures.resolve(assertion.catchUrl);
+            if (found === undefined) {
+                return {
+                    kind: 'errored',
+                    assertion,
+                    message: `no catch URL named "${assertion.catchUrl}" in the server workspace`,
+                };
+            }
+            return { kind: 'ready', assertion, hookId: found.hookId, cursor: await captures.cursor(found.hookId) };
+        }
+        catch (error) {
+            return { kind: 'errored', assertion, message: messageOf(error) };
+        }
+    }));
+}
+/** What is about to be waited for: the ready ones. */
+export function waitingOf(pending) {
+    return pending.flatMap((p) => p.kind === 'ready'
+        ? [{ label: callbackLabel(p.assertion), catchUrl: p.assertion.catchUrl, withinMs: p.assertion.withinMs }]
+        : []);
+}
+const HELD = { ok: true };
+/** Long enough to read, short enough that a report stays a report. */
+const MAX_ACTUAL_CHARS = 200;
+const quoted = (text) => JSON.stringify(text.length > MAX_ACTUAL_CHARS ? `${text.slice(0, MAX_ACTUAL_CHARS)}…` : text);
+async function compare(label, check, actual, missing) {
+    const expected = check.matches !== undefined ? `/${check.matches}/` : quoted(check.equals ?? '');
+    if (actual === undefined) {
+        return { ok: false, reason: `${label}: expected ${expected}, got ${missing}` };
+    }
+    if (check.matches !== undefined) {
+        // On the worker: the pattern comes from a file, and a backtracking one must not block this thread.
+        const matched = await matchRegexWithTimeout(check.matches, actual);
+        if (matched.kind === 'error')
+            return { ok: false, reason: `${label}: ${matched.message}` };
+        return matched.matched ? HELD : { ok: false, reason: `${label}: expected ${expected}, got ${quoted(actual)}` };
+    }
+    return actual === check.equals
+        ? HELD
+        : { ok: false, reason: `${label}: expected ${expected}, got ${quoted(actual)}` };
+}
+function headerHolds(check, headers) {
+    const label = `header ${check.name}`;
+    const actual = firstHeaderValue(headers, check.name);
+    if (check.exists !== undefined) {
+        const found = actual !== undefined;
+        return found === check.exists
+            ? HELD
+            : {
+                ok: false,
+                reason: `${label}: expected ${check.exists ? 'present' : 'absent'}, got ${found ? 'present' : 'absent'}`,
+            };
+    }
+    return compare(label, check, actual, 'absent');
+}
+function notParsed(language, bodyText) {
+    if (language === 'jsonpath') {
+        try {
+            JSON.parse(bodyText);
+            return undefined;
+        }
+        catch {
+            return 'body is not JSON';
+        }
+    }
+    try {
+        // xmldom reports text with no root element as a document without one, not always as a fatal error.
+        return parseXml(bodyText).documentElement === null ? 'body is not XML' : undefined;
+    }
+    catch {
+        return 'body is not XML';
+    }
+}
+async function bodyHolds(check, bodyText) {
+    const label = check.path;
+    const refused = notParsed(check.language, bodyText);
+    if (refused !== undefined)
+        return { ok: false, reason: `${label}: ${refused}` };
+    const result = await evaluateWithTimeout(bodyText, check.path, { language: check.language }, { kind: check.language === 'jsonpath' ? 'json' : 'xml' });
+    if (result.kind === 'error')
+        return { ok: false, reason: `${label}: ${result.message}` };
+    const found = result.kind !== 'empty';
+    if (check.exists !== undefined) {
+        return found === check.exists
+            ? HELD
+            : {
+                ok: false,
+                reason: `${label}: expected ${check.exists ? 'a result' : 'no result'}, got ${found ? 'a result' : 'none'}`,
+            };
+    }
+    return compare(label, check, found ? (firstText(result) ?? '') : undefined, 'nothing');
+}
+function signatureHolds(capture) {
+    const signature = capture.signature;
+    if (signature?.verdict === 'verified')
+        return HELD;
+    const got = signature === null ? 'not checked' : `failed${signature.reason !== undefined ? ` (${signature.reason})` : ''}`;
+    return { ok: false, reason: `signature: expected verified, got ${got}` };
+}
+async function fit(match, summary, detail) {
+    const parts = [];
+    if (match.method !== undefined && match.method.toUpperCase() !== summary.method.toUpperCase())
+        parts.push('method');
+    if (match.path !== undefined && match.path !== summary.path)
+        parts.push('path');
+    if (match.pathMatches !== undefined) {
+        const matched = await matchRegexWithTimeout(match.pathMatches, summary.path);
+        if (matched.kind === 'error' || !matched.matched)
+            parts.push('path');
+    }
+    // §2.3: a method or path that differs is skipped before its detail is read.
+    if (parts.length > 0)
+        return { kind: 'differs', stage: 'summary', parts };
+    const full = await detail();
+    for (const header of match.headers ?? []) {
+        if (!(await headerHolds(header, full.headers)).ok)
+            parts.push(`header ${header.name}`);
+    }
+    if (match.body !== undefined && !(await bodyHolds(match.body, full.bodyText)).ok) {
+        parts.push(`body ${match.body.path}`);
+    }
+    return parts.length === 0 ? { kind: 'fits', detail: full } : { kind: 'differs', stage: 'detail', parts };
+}
+/**
+ * Whether a miss is closer than the closest so far. A header or body miss (its method and path fit)
+ * beats any method or path miss, whose headers and body were never read; within a stage the fewest
+ * parts win. Captures come oldest first, so `<=` gives a tie to the newer one (§2.4).
+ */
+function closerThan(miss, closest) {
+    if (closest === undefined)
+        return true;
+    if (miss.stage !== closest.stage)
+        return miss.stage === 'detail';
+    return miss.parts.length <= closest.parts.length;
+}
+/** `30` for whole seconds, `1.5` otherwise: how a callback's wait reads in messages. */
+export function seconds(ms) {
+    const value = ms / 1000;
+    return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+async function checked(base, assertion, hookId, detail, afterMs) {
+    const failures = [];
+    for (const check of assertion.expect) {
+        const held = 'body' in check
+            ? await bodyHolds(check.body, detail.bodyText)
+            : 'header' in check
+                ? await headerHolds(check.header, detail.headers)
+                : signatureHolds(detail);
+        if (!held.ok)
+            failures.push(held.reason);
+    }
+    const capture = { hookId, captureId: detail.id };
+    return failures.length === 0
+        ? {
+            ...base,
+            outcome: 'passed',
+            message: `matched capture ${detail.id} after ${(afterMs / 1000).toFixed(1)} s`,
+            capture,
+        }
+        : { ...base, outcome: 'failed', message: `matched ${detail.id}, but ${failures.join('; ')}`, capture };
+}
+async function awaitOne(pending, options) {
+    const { assertion } = pending;
+    const base = { type: 'callback', label: callbackLabel(assertion) };
+    if (pending.kind === 'errored')
+        return { ...base, outcome: 'errored', message: pending.message };
+    const captures = options.captures;
+    if (captures === undefined)
+        return { ...base, outcome: 'errored', message: NO_CAPTURE_SOURCE_MESSAGE };
+    const clock = options.clock ?? realCallbackClock;
+    const interval = options.pollIntervalMs ?? CALLBACK_LIMITS.pollIntervalMs;
+    const deadline = options.sentAt + assertion.withinMs;
+    let cursor = pending.cursor;
+    let arrived = 0;
+    let closest;
+    try {
+        for (;;) {
+            if (options.signal?.aborted === true) {
+                return { ...base, outcome: 'errored', message: `cancelled while waiting for ${assertion.catchUrl}` };
+            }
+            for (const summary of await captures.after(pending.hookId, cursor)) {
+                // The cursor passes every capture seen, so none is evaluated twice (§2.3).
+                cursor = summary.id;
+                arrived += 1;
+                const found = await fit(assertion.match, summary, () => captures.detail(pending.hookId, summary.id));
+                if (found.kind === 'fits') {
+                    return await checked(base, assertion, pending.hookId, found.detail, clock.now() - options.sentAt);
+                }
+                if (closerThan(found, closest))
+                    closest = { ...found, summary };
+            }
+            const now = clock.now();
+            if (now >= deadline)
+                break;
+            await clock.sleep(Math.min(interval, deadline - now), options.signal);
+        }
+    }
+    catch (error) {
+        // The source's own message; a source never puts its credential in one.
+        return { ...base, outcome: 'errored', message: messageOf(error) };
+    }
+    const within = seconds(assertion.withinMs);
+    return {
+        ...base,
+        outcome: 'failed',
+        message: closest === undefined
+            ? `no capture arrived at ${assertion.catchUrl} within ${within} s`
+            : `no capture matched within ${within} s — ${String(arrived)} arrived; closest: ${closest.summary.method} ${closest.summary.path} (${closest.parts[0] ?? 'match'} differs)`,
+    };
+}
+/** After the send (§2.3 steps 2–4): every pending callback waits at once; the longest sets the total. */
+export function awaitCallbacks(pending, options) {
+    return Promise.all(pending.map((one) => awaitOne(one, options)));
+}
+/**
+ * The prepare → send → await wiring of §2.3, shared by `runRequests` and a sequence run so the
+ * cursor is always taken before the send. `scopes` is asked only when `assertions` hold a callback
+ * assertion, so a request without one does no extra work. `send` may throw; a throw before or in it
+ * abandons the wait. The callers evaluate their other assertions from `sent`, then merge `callbacks`.
+ */
+export async function sendAwaitingCallbacks(assertions, scopes, send, wiring) {
+    const own = assertions.filter(isCallbackAssertion);
+    if (own.length === 0)
+        return { sent: await send(), callbacks: [] };
+    const clock = wiring.clock ?? realCallbackClock;
+    const resolved = scopes();
+    const pending = await prepareCallbacks(own.map((assertion) => expandCallback(assertion, resolved)), wiring.captures);
+    const sent = await send();
+    const sentAt = clock.now();
+    const waiting = waitingOf(pending);
+    if (waiting.length > 0)
+        wiring.onWaiting?.(waiting);
+    const callbacks = await awaitCallbacks(pending, {
+        captures: wiring.captures,
+        sentAt,
+        clock,
+        ...(wiring.pollIntervalMs !== undefined ? { pollIntervalMs: wiring.pollIntervalMs } : {}),
+        ...(wiring.signal !== undefined ? { signal: wiring.signal } : {}),
+    });
+    return { sent, callbacks };
+}

package/dist/assert/capture-source.d.ts

@@ -0,0 +1,50 @@
+import type { Capture, CaptureSummary, CatchUrl } from '../server-api/hooks.js';
+export interface CaptureSummaryView {
+    /** A ULID: sorts by arrival. */
+    readonly id: string;
+    readonly receivedAt: string;
+    readonly method: string;
+    /** The decoded subpath: `/` when the sender posted to the catch URL itself. */
+    readonly path: string;
+    readonly signature: {
+        readonly verdict: 'verified' | 'failed';
+        readonly reason?: string;
+    } | null;
+}
+export interface CaptureDetailView extends CaptureSummaryView {
+    readonly headers: readonly (readonly [string, string])[];
+    /** UTF-8 decoded; a truncated capture carries what was kept. */
+    readonly bodyText: string;
+    readonly truncated: boolean;
+}
+export interface CaptureSource {
+    /** Resolves a catch URL name; `undefined` when the workspace has none by that name. */
+    resolve(catchUrl: string): Promise<{
+        readonly hookId: string;
+    } | undefined>;
+    /** The newest capture's id now, or `null` when there is none. Taken before the send. */
+    cursor(hookId: string): Promise<string | null>;
+    /** Captures after the cursor, oldest first. */
+    after(hookId: string, cursor: string | null): Promise<readonly CaptureSummaryView[]>;
+    detail(hookId: string, captureId: string): Promise<CaptureDetailView>;
+}
+/** The manage API reads a host performs for one workspace, with its own credentials. */
+export interface CaptureServerReads {
+    /** `GET …/hooks`. */
+    hooks(): Promise<readonly Pick<CatchUrl, 'id' | 'name'>[]>;
+    /** `GET …/hooks/:hookId/captures?after=&limit=`: newest first, as the server answers. */
+    captures(hookId: string, page: {
+        readonly after?: string;
+        readonly limit: number;
+    }): Promise<readonly CaptureSummary[]>;
+    /** `GET …/hooks/:hookId/captures/:captureId`. */
+    capture(hookId: string, captureId: string): Promise<Capture>;
+}
+/** Below every ULID: `after` from here reads a hook's captures from its first. */
+export declare const FIRST_CAPTURE_CURSOR = "00000000000000000000000000";
+export declare function captureSummaryView(summary: CaptureSummary): CaptureSummaryView;
+export declare function captureDetailView(capture: Capture): CaptureDetailView;
+/** A `CaptureSource` over the manage API. The hook list is read once per source, which is once per run. */
+export declare function captureSourceOver(reads: CaptureServerReads): CaptureSource;
+/** A source for a host that cannot read captures: every callback assertion errors with `message`. */
+export declare function unavailableCaptureSource(message: string): CaptureSource;