@wirebench/engine 2.2.1 → 3.1.0

package/dist/sequence/file.js

@@ -0,0 +1,237 @@
+/**
+ * `sequences/<slug>.sequence.yaml`: parsing, validation and serialisation of one sequence file.
+ *
+ * The file may come from a teammate or a branch just pulled, so it is untrusted input: its size is
+ * checked before it is parsed, it is parsed with the project's YAML parser (core schema, aliases capped
+ * by the library), and every count is bounded by {@link SEQUENCE_LIMITS}. It names requests only by id,
+ * so nothing in it can name a path on disk.
+ *
+ * Like every project schema, objects are `looseObject`: an unknown key is ignored and not written back.
+ * That is only safe because a file whose `version` is newer than {@link SEQUENCE_VERSION} is refused
+ * whole rather than read in part, and a refused file is never deleted by a save (`save.ts`).
+ */
+import { z } from 'zod';
+import { stepAssertionsSchema, toCallbackAssertion } from '../assert/schema.js';
+import { ProjectError } from '../errors.js';
+import { compact, parseYaml, stringifyYaml } from '../project/yaml.js';
+import { SEQUENCE_LIMITS, SEQUENCE_VERSION, TRANSFER_NAME_PATTERN } from './model.js';
+/** Directory holding every sequence file, beside `interfaces/` and `apis/`. */
+export const SEQUENCES_DIR = 'sequences';
+/** Suffix identifying a sequence file. */
+export const SEQUENCE_SUFFIX = '.sequence.yaml';
+const nonEmpty = z.string().min(1);
+const transferBase = {
+    name: z.string().regex(TRANSFER_NAME_PATTERN, 'a transfer name is a letter or _, then letters, digits, _ . or -'),
+    secret: z.boolean().optional(),
+    optional: z.boolean().optional(),
+};
+const transferSchema = z.discriminatedUnion('from', [
+    z.looseObject({
+        ...transferBase,
+        from: z.literal('body'),
+        language: z.enum(['xpath', 'xquery', 'jsonpath']),
+        expression: nonEmpty,
+        namespaces: z.record(z.string(), z.string()).optional(),
+    }),
+    z.looseObject({ ...transferBase, from: z.literal('header'), header: nonEmpty }),
+    z.looseObject({ ...transferBase, from: z.literal('status') }),
+    z.looseObject({ ...transferBase, from: z.literal('cookie'), cookie: nonEmpty }),
+]);
+const stepSchema = z.looseObject({
+    id: nonEmpty,
+    name: z.string().optional(),
+    request: nonEmpty,
+    enabled: z.boolean().default(true),
+    requestAssertions: z.boolean().default(true),
+    transfers: z.array(transferSchema).max(SEQUENCE_LIMITS.transfersPerStep).default([]),
+    assertions: stepAssertionsSchema.max(SEQUENCE_LIMITS.assertionsPerStep).default([]),
+});
+/** One sequence file, after its `kind` and `version` have been checked. */
+export const sequenceFileSchema = z.looseObject({
+    kind: z.literal('sequence'),
+    version: z.literal(SEQUENCE_VERSION),
+    id: nonEmpty,
+    name: z.string(),
+    order: z.number().int(),
+    description: z.string().optional(),
+    settings: z
+        .looseObject({
+        stopOnFailure: z.boolean().default(true),
+        stepTimeoutMs: z.number().int().positive().optional(),
+    })
+        .default({ stopOnFailure: true }),
+    steps: z.array(stepSchema).max(SEQUENCE_LIMITS.steps).default([]),
+});
+/** The relative path of a sequence's file. */
+export function sequenceFilePath(slug) {
+    return `${SEQUENCES_DIR}/${slug}${SEQUENCE_SUFFIX}`;
+}
+/** The slug a sequence file's name gives it, or `undefined` for a name that is not a sequence file. */
+export function sequenceSlugOf(fileName) {
+    return fileName.endsWith(SEQUENCE_SUFFIX) && fileName.length > SEQUENCE_SUFFIX.length
+        ? fileName.slice(0, -SEQUENCE_SUFFIX.length)
+        : undefined;
+}
+function refuse(code, message, file, issues) {
+    throw new ProjectError(code, message, { details: { file, ...(issues !== undefined ? { issues } : {}) } });
+}
+/**
+ * Parses one sequence file.
+ *
+ * @throws ProjectError `sequence-file-invalid` (too large, malformed YAML, not a sequence, or failing the
+ * schema or a limit), `sequence-version-too-new` (a `version` above {@link SEQUENCE_VERSION})
+ */
+export function parseSequenceFile(bytes, file, slug) {
+    const size = typeof bytes === 'string' ? Buffer.byteLength(bytes, 'utf8') : bytes.byteLength;
+    if (size > SEQUENCE_LIMITS.fileBytes) {
+        refuse('sequence-file-invalid', `${file} is larger than ${SEQUENCE_LIMITS.fileBytes} bytes`, file);
+    }
+    const text = typeof bytes === 'string' ? bytes : Buffer.from(bytes).toString('utf8');
+    let document;
+    try {
+        document = parseYaml(text, file);
+    }
+    catch (error) {
+        refuse('sequence-file-invalid', `Malformed YAML in ${file}`, file, [
+            { path: '', message: error instanceof Error ? error.message : String(error) },
+        ]);
+    }
+    if (typeof document !== 'object' || document === null || Array.isArray(document)) {
+        refuse('sequence-file-invalid', `${file} is not a sequence`, file);
+    }
+    const header = document;
+    if (header['kind'] !== 'sequence') {
+        refuse('sequence-file-invalid', `${file} is not a sequence (kind: ${String(header['kind'])})`, file);
+    }
+    const version = header['version'];
+    if (typeof version === 'number' && Number.isInteger(version) && version > SEQUENCE_VERSION) {
+        refuse('sequence-version-too-new', `${file} was written by a newer version of Wirebench (sequence version ${version}); it was left as it is`, file);
+    }
+    const result = sequenceFileSchema.safeParse(document);
+    if (!result.success) {
+        refuse('sequence-file-invalid', `Invalid sequence file ${file}`, file, result.error.issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message })));
+    }
+    const parsed = result.data;
+    return {
+        id: parsed.id,
+        name: parsed.name,
+        slug,
+        order: parsed.order,
+        ...(parsed.description !== undefined ? { description: parsed.description } : {}),
+        settings: {
+            stopOnFailure: parsed.settings.stopOnFailure,
+            ...(parsed.settings.stepTimeoutMs !== undefined ? { stepTimeoutMs: parsed.settings.stepTimeoutMs } : {}),
+        },
+        steps: parsed.steps.map((step) => ({
+            id: step.id,
+            ...(step.name !== undefined ? { name: step.name } : {}),
+            requestId: step.request,
+            enabled: step.enabled,
+            requestAssertions: step.requestAssertions,
+            transfers: step.transfers.map(toTransfer),
+            assertions: step.assertions.map(knownAssertionFields),
+        })),
+    };
+}
+/**
+ * Only the fields an assertion of its type defines. `looseObject` keeps unknown keys on the parsed value;
+ * dropping them here is what keeps them from being written back.
+ */
+function knownAssertionFields(raw) {
+    const name = raw.name !== undefined ? { name: raw.name } : {};
+    switch (raw.type) {
+        case 'status':
+            return { type: 'status', equals: raw.equals, ...name };
+        case 'soap-fault':
+            return { type: 'soap-fault', expect: raw.expect, ...name };
+        case 'schema':
+            return { type: 'schema', ...name };
+        case 'sla':
+            return { type: 'sla', maxMs: raw.maxMs, ...name };
+        case 'match':
+            return {
+                type: 'match',
+                language: raw.language,
+                expression: raw.expression,
+                ...(raw.namespaces !== undefined ? { namespaces: raw.namespaces } : {}),
+                ...(raw.equals !== undefined ? { equals: raw.equals } : {}),
+                ...(raw.matches !== undefined ? { matches: raw.matches } : {}),
+                ...(raw.exists !== undefined ? { exists: raw.exists } : {}),
+                ...name,
+            };
+        case 'callback':
+            return toCallbackAssertion(raw);
+        case 'header':
+            return {
+                type: 'header',
+                header: raw.header,
+                ...(raw.equals !== undefined ? { equals: raw.equals } : {}),
+                ...(raw.matches !== undefined ? { matches: raw.matches } : {}),
+                ...(raw.exists !== undefined ? { exists: raw.exists } : {}),
+                ...name,
+            };
+    }
+}
+function toTransfer(raw) {
+    const base = {
+        name: raw.name,
+        ...(raw.secret === true ? { secret: true } : {}),
+        ...(raw.optional === true ? { optional: true } : {}),
+    };
+    switch (raw.from) {
+        case 'body':
+            return {
+                ...base,
+                from: 'body',
+                language: raw.language,
+                expression: raw.expression,
+                ...(raw.namespaces !== undefined ? { namespaces: raw.namespaces } : {}),
+            };
+        case 'header':
+            return { ...base, from: 'header', header: raw.header };
+        case 'status':
+            return { ...base, from: 'status' };
+        case 'cookie':
+            return { ...base, from: 'cookie', cookie: raw.cookie };
+    }
+}
+/** Only the fields a transfer or assertion defines, in a stable shape; defaults are left out. */
+function transferDocument(transfer) {
+    return compact({
+        name: transfer.name,
+        from: transfer.from,
+        language: transfer.from === 'body' ? transfer.language : undefined,
+        expression: transfer.from === 'body' ? transfer.expression : undefined,
+        namespaces: transfer.from === 'body' ? transfer.namespaces : undefined,
+        header: transfer.from === 'header' ? transfer.header : undefined,
+        cookie: transfer.from === 'cookie' ? transfer.cookie : undefined,
+        secret: transfer.secret === true ? true : undefined,
+        optional: transfer.optional === true ? true : undefined,
+    });
+}
+/** Serialises a sequence as its file's content: keys sorted, defaults omitted, steps in order. */
+export function sequenceDocument(sequence) {
+    return stringifyYaml(compact({
+        kind: 'sequence',
+        version: SEQUENCE_VERSION,
+        id: sequence.id,
+        name: sequence.name,
+        order: sequence.order,
+        description: sequence.description,
+        settings: compact({
+            stopOnFailure: sequence.settings.stopOnFailure,
+            stepTimeoutMs: sequence.settings.stepTimeoutMs,
+        }),
+        steps: sequence.steps.map((step) => compact({
+            id: step.id,
+            name: step.name,
+            request: step.requestId,
+            enabled: step.enabled ? undefined : false,
+            requestAssertions: step.requestAssertions ? undefined : false,
+            transfers: step.transfers.length > 0 ? step.transfers.map(transferDocument) : undefined,
+            assertions: step.assertions.length > 0
+                ? step.assertions.map((a) => compact({ ...knownAssertionFields(a) }))
+                : undefined,
+        })),
+    }));
+}

package/dist/sequence/index.d.ts

@@ -0,0 +1,7 @@
+/** Sequences: saved requests chained with property transfers and declared assertions (#62). */
+export * from './model.js';
+export { SEQUENCES_DIR, SEQUENCE_SUFFIX, parseSequenceFile, sequenceDocument, sequenceFilePath, sequenceFileSchema, sequenceSlugOf, } from './file.js';
+export { extractTransfer } from './transfer.js';
+export type { ExtractedValue } from './transfer.js';
+export { runSequence } from './run.js';
+export type { CallbackStep, ResolvedStep, RunSequenceOptions, SequenceOutcome, SequenceRunResult, SequenceStepNotSent, SequenceStepResult, SequenceStepSender, SequenceStepSent, TransferResult, } from './run.js';

package/dist/sequence/index.js

@@ -0,0 +1,5 @@
+/** Sequences: saved requests chained with property transfers and declared assertions (#62). */
+export * from './model.js';
+export { SEQUENCES_DIR, SEQUENCE_SUFFIX, parseSequenceFile, sequenceDocument, sequenceFilePath, sequenceFileSchema, sequenceSlugOf, } from './file.js';
+export { extractTransfer } from './transfer.js';
+export { runSequence } from './run.js';

package/dist/sequence/load.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reads every file under `sequences/`, for loading a project and for deciding what a save may delete.
+ *
+ * The two questions share one answer on purpose. A save deletes the managed files the project no
+ * longer has; if "managed" meant every `*.sequence.yaml`, a file this build refused to load (written by
+ * a newer build, malformed mid-merge, or a copy with a duplicate id) would vanish on the next save
+ * without the user ever seeing it. So a file is managed only when this build loaded it.
+ */
+import type { FsLike } from '../project/fs.js';
+import type { SequenceDef } from './model.js';
+/** A sequence file that did not load, and why. */
+export interface SequenceFileProblem {
+    readonly code: 'sequence-file-invalid' | 'sequence-version-too-new' | 'sequence-duplicate-id';
+    readonly message: string;
+    /** Path relative to the project root. */
+    readonly file: string;
+}
+/** What {@link readSequences} found. */
+export interface SequenceFiles {
+    /** Sequences that loaded, each with the file it came from. */
+    readonly loaded: readonly {
+        readonly file: string;
+        readonly sequence: SequenceDef;
+    }[];
+    readonly problems: readonly SequenceFileProblem[];
+}
+/**
+ * Reads and parses every `sequences/*.sequence.yaml`. Never throws for a bad file: each becomes a
+ * problem and is left out. When two files share an id, the first by file name loads and the others are
+ * `sequence-duplicate-id` problems, so which one wins does not depend on the order the OS lists them.
+ */
+export declare function readSequences(fs: FsLike, root: string): Promise<SequenceFiles>;

package/dist/sequence/load.js

@@ -0,0 +1,56 @@
+/**
+ * Reads every file under `sequences/`, for loading a project and for deciding what a save may delete.
+ *
+ * The two questions share one answer on purpose. A save deletes the managed files the project no
+ * longer has; if "managed" meant every `*.sequence.yaml`, a file this build refused to load (written by
+ * a newer build, malformed mid-merge, or a copy with a duplicate id) would vanish on the next save
+ * without the user ever seeing it. So a file is managed only when this build loaded it.
+ */
+import { join } from 'node:path';
+import { isWirebenchError } from '../errors.js';
+import { readFileIfExists, readdirIfExists } from '../project/fs.js';
+import { SEQUENCES_DIR, parseSequenceFile, sequenceSlugOf } from './file.js';
+/**
+ * Reads and parses every `sequences/*.sequence.yaml`. Never throws for a bad file: each becomes a
+ * problem and is left out. When two files share an id, the first by file name loads and the others are
+ * `sequence-duplicate-id` problems, so which one wins does not depend on the order the OS lists them.
+ */
+export async function readSequences(fs, root) {
+    const entries = [...(await readdirIfExists(fs, join(root, SEQUENCES_DIR)))]
+        .filter((entry) => entry.isFile && sequenceSlugOf(entry.name) !== undefined)
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const loaded = [];
+    const problems = [];
+    const seen = new Map();
+    for (const entry of entries) {
+        const file = `${SEQUENCES_DIR}/${entry.name}`;
+        const bytes = await readFileIfExists(fs, join(root, SEQUENCES_DIR, entry.name));
+        if (bytes === undefined) {
+            continue;
+        }
+        let sequence;
+        try {
+            sequence = parseSequenceFile(bytes, file, sequenceSlugOf(entry.name) ?? entry.name);
+        }
+        catch (error) {
+            if (isWirebenchError(error) &&
+                (error.code === 'sequence-file-invalid' || error.code === 'sequence-version-too-new')) {
+                problems.push({ code: error.code, message: error.message, file });
+                continue;
+            }
+            throw error;
+        }
+        const first = seen.get(sequence.id);
+        if (first !== undefined) {
+            problems.push({
+                code: 'sequence-duplicate-id',
+                message: `${file} has the same id as ${first}; it was not loaded and is left as it is`,
+                file,
+            });
+            continue;
+        }
+        seen.set(sequence.id, file);
+        loaded.push({ file, sequence });
+    }
+    return { loaded, problems };
+}

package/dist/sequence/model.d.ts

@@ -0,0 +1,115 @@
+/**
+ * A sequence: saved requests run in order, each able to lift values out of its response for the steps
+ * after it (`${#Sequence#name}`) and to assert on it. One file per sequence under `sequences/`, with its
+ * own `version`, outside the project `formatVersion` (ADR-0003, update of 2026-09-28).
+ *
+ * The limits here bound what a file from someone else can make a run hold in memory; the security
+ * reasoning is in `docs/specs/2026-09-28-sequences-design.md` and ADR-0015.
+ */
+import type { AssertionLanguage, StepAssertion } from '../assert/model.js';
+import type { CreateOptions } from '../project/model.js';
+/** The version of the sequence file this build writes and the highest it reads. */
+export declare const SEQUENCE_VERSION = 1;
+/** Bounds on one sequence file and one run, whatever the file or the server says. */
+export declare const SEQUENCE_LIMITS: Readonly<{
+    /** A file larger than this is refused before it is parsed. */
+    fileBytes: number;
+    steps: 100;
+    transfersPerStep: 50;
+    assertionsPerStep: 50;
+    /** A transferred value larger than this errors the step (`sequence-value-too-large`). */
+    valueBytes: number;
+}>;
+/** A transfer's name, as `${#Sequence#name}` uses it. */
+export declare const TRANSFER_NAME_PATTERN: RegExp;
+interface TransferBase {
+    /** The name later steps use, as `${#Sequence#name}`. A later transfer of the same name replaces it. */
+    readonly name: string;
+    /** Masked everywhere from the moment it is extracted, and never shown or reported. */
+    readonly secret?: boolean;
+    /** Finding nothing leaves the name unset instead of failing the step. */
+    readonly optional?: boolean;
+}
+/** Lifts the first result of an expression over the response body. */
+export interface BodyTransfer extends TransferBase {
+    readonly from: 'body';
+    readonly language: AssertionLanguage;
+    readonly expression: string;
+    /** Prefix bindings for XPath/XQuery. Absent means the response's own prefixes. */
+    readonly namespaces?: Readonly<Record<string, string>>;
+}
+/** Lifts the first value of a response header (gRPC: metadata, then trailers). */
+export interface HeaderTransfer extends TransferBase {
+    readonly from: 'header';
+    readonly header: string;
+}
+/** Lifts the status: HTTP for SOAP and REST, the numeric gRPC status for gRPC. */
+export interface StatusTransfer extends TransferBase {
+    readonly from: 'status';
+}
+/**
+ * Lifts the value of one cookie the response set (`Set-Cookie`; the last one of that name wins).
+ *
+ * Wirebench keeps no shared cookie jar, on purpose (`rest/cookies.ts`), and a sequence does not add
+ * one: a step that needs a login's cookie says so, `Cookie: sid=${#Sequence#sid}`, where it can be
+ * read and where ADR-0015's guards apply.
+ */
+export interface CookieTransfer extends TransferBase {
+    readonly from: 'cookie';
+    readonly cookie: string;
+}
+/** One value lifted from a step's response. */
+export type Transfer = BodyTransfer | HeaderTransfer | StatusTransfer | CookieTransfer;
+/** One request in a sequence, and what to take from and check about its response. */
+export interface SequenceStep {
+    readonly id: string;
+    /** Defaults to the request's own name wherever it is shown. */
+    readonly name?: string;
+    /** A saved request's id: SOAP, REST or unary gRPC. Never a path, so a rename or a move keeps the step. */
+    readonly requestId: string;
+    /** A disabled step is reported as `skipped`. */
+    readonly enabled: boolean;
+    /** Whether the request's own `assertions:` run in this step, before the step's own. */
+    readonly requestAssertions: boolean;
+    readonly transfers: readonly Transfer[];
+    readonly assertions: readonly StepAssertion[];
+}
+/** How a sequence runs. */
+export interface SequenceSettings {
+    /** After a failed or errored step, the rest are `skipped`. */
+    readonly stopOnFailure: boolean;
+    /** Overrides each request's own timeout for every step. */
+    readonly stepTimeoutMs?: number;
+}
+/** A whole sequence, as loaded from (or saved to) `sequences/<slug>.sequence.yaml`. */
+export interface SequenceDef {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+    readonly description?: string;
+    readonly settings: SequenceSettings;
+    readonly steps: readonly SequenceStep[];
+}
+/** The settings a new sequence starts with. */
+export declare const DEFAULT_SEQUENCE_SETTINGS: SequenceSettings;
+/** Input to {@link createSequence} beyond the name. */
+export interface CreateSequenceInput extends CreateOptions {
+    readonly slug?: string;
+    readonly description?: string;
+    readonly settings?: SequenceSettings;
+    readonly steps?: readonly SequenceStep[];
+}
+/** Creates a sequence, empty unless `input.steps` says otherwise. */
+export declare function createSequence(name: string, input?: CreateSequenceInput): SequenceDef;
+/** Input to {@link createSequenceStep} beyond the request id. */
+export interface CreateSequenceStepInput extends Omit<CreateOptions, 'order'> {
+    readonly name?: string;
+    readonly enabled?: boolean;
+    readonly requestAssertions?: boolean;
+    readonly transfers?: readonly Transfer[];
+    readonly assertions?: readonly StepAssertion[];
+}
+/** Creates a step that sends `requestId`, enabled, with the request's own assertions on. */
+export declare function createSequenceStep(requestId: string, input?: CreateSequenceStepInput): SequenceStep;
+export {};

package/dist/sequence/model.js

@@ -0,0 +1,53 @@
+/**
+ * A sequence: saved requests run in order, each able to lift values out of its response for the steps
+ * after it (`${#Sequence#name}`) and to assert on it. One file per sequence under `sequences/`, with its
+ * own `version`, outside the project `formatVersion` (ADR-0003, update of 2026-09-28).
+ *
+ * The limits here bound what a file from someone else can make a run hold in memory; the security
+ * reasoning is in `docs/specs/2026-09-28-sequences-design.md` and ADR-0015.
+ */
+import { generateId } from '../project/model.js';
+import { slugify } from '../project/paths.js';
+/** The version of the sequence file this build writes and the highest it reads. */
+export const SEQUENCE_VERSION = 1;
+/** Bounds on one sequence file and one run, whatever the file or the server says. */
+export const SEQUENCE_LIMITS = Object.freeze({
+    /** A file larger than this is refused before it is parsed. */
+    fileBytes: 256 * 1024,
+    steps: 100,
+    transfersPerStep: 50,
+    assertionsPerStep: 50,
+    /** A transferred value larger than this errors the step (`sequence-value-too-large`). */
+    valueBytes: 64 * 1024,
+});
+/** A transfer's name, as `${#Sequence#name}` uses it. */
+export const TRANSFER_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
+/** The settings a new sequence starts with. */
+export const DEFAULT_SEQUENCE_SETTINGS = Object.freeze({ stopOnFailure: true });
+function idOf(options) {
+    return options?.id ?? (options?.newId ?? generateId)();
+}
+/** Creates a sequence, empty unless `input.steps` says otherwise. */
+export function createSequence(name, input = {}) {
+    return {
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        settings: input.settings ?? DEFAULT_SEQUENCE_SETTINGS,
+        steps: input.steps ?? [],
+    };
+}
+/** Creates a step that sends `requestId`, enabled, with the request's own assertions on. */
+export function createSequenceStep(requestId, input = {}) {
+    return {
+        id: idOf(input),
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        requestId,
+        enabled: input.enabled ?? true,
+        requestAssertions: input.requestAssertions ?? true,
+        transfers: input.transfers ?? [],
+        assertions: input.assertions ?? [],
+    };
+}

package/dist/sequence/run.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Running a sequence: the loop, the transfers and the assertions, with the same semantics wherever it
+ * runs. Sending stays with the host (the CLI through `createRunSender`, the desktop through its own send
+ * paths and History), because the two send with different secrets, auth flows and cookie jars.
+ *
+ * Values lifted from responses reach the next step only through the `sequence` scope the host passes to
+ * its expanders, where ADR-0015's rules apply: literal, explicit, escaped, never the origin.
+ */
+import type { CallbackClock, CallbackWaiting } from '../assert/callback.js';
+import type { CaptureSource } from '../assert/capture-source.js';
+import type { AssertionResult, AssertionSubject } from '../assert/model.js';
+import type { PropertyMap, Project } from '../project/model.js';
+import type { PropertyScopes } from '../project/properties.js';
+import type { ProtocolRegistry } from '../protocol/registry.js';
+import type { SelectedRequest } from '../run/select.js';
+import type { SequenceDef, SequenceStep } from './model.js';
+import { type SentScripts } from '../run/script-support.js';
+/** How one step, or a run, ended. The runner's own outcomes, with `skipped` for a step never sent. */
+export type SequenceOutcome = 'passed' | 'failed' | 'errored' | 'skipped';
+/** What the host needs to send one step. */
+export interface ResolvedStep {
+    readonly index: number;
+    readonly step: SequenceStep;
+    readonly selected: SelectedRequest;
+    /** The sequence's `stepTimeoutMs`, when set: it overrides the request's own timeout. */
+    readonly timeoutMs?: number;
+}
+/** A step the host sent: the response as assertions see it, and where it went. */
+export interface SequenceStepSent {
+    readonly subject: AssertionSubject;
+    /** The origin the request went to, for the run panel and the reports. */
+    readonly origin?: string;
+    /** What the step request's scripts produced (#63): tests, values for later steps, a log. */
+    readonly script?: SentScripts;
+    /** True when the step's request has scripts and they are switched off. */
+    readonly scriptsOff?: boolean;
+}
+/** A step the host could not send. */
+export interface SequenceStepNotSent {
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/**
+ * Sends one step's request with `sequenceScope` as the `${#Sequence#…}` values, and describes the
+ * response. May throw; a throw becomes an errored step.
+ */
+export type SequenceStepSender = (step: ResolvedStep, sequenceScope: PropertyMap, signal: AbortSignal) => Promise<SequenceStepSent | SequenceStepNotSent>;
+/** What one transfer did. A secret value is never carried here, so it cannot reach a report or the UI. */
+export interface TransferResult {
+    readonly name: string;
+    readonly outcome: 'set' | 'missing' | 'errored';
+    readonly secret: boolean;
+    readonly value?: string;
+    readonly message?: string;
+}
+/** One step's result. */
+export interface SequenceStepResult {
+    readonly index: number;
+    readonly stepId: string;
+    readonly requestId: string;
+    readonly name: string;
+    readonly protocol?: SelectedRequest['kind'];
+    readonly outcome: SequenceOutcome;
+    readonly status?: number;
+    readonly durationMs?: number;
+    readonly origin?: string;
+    readonly assertions: readonly AssertionResult[];
+    readonly transfers: readonly TransferResult[];
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    /** Why a `skipped` step was not sent. */
+    readonly skipped?: 'disabled' | 'after-failure' | 'cancelled';
+    /** What the step request's scripts logged. NOT yet redacted. */
+    readonly scriptLog?: readonly string[];
+    /** True when the step's request has scripts and they are switched off. */
+    readonly scriptsOff?: boolean;
+}
+/** A whole run's result. */
+export interface SequenceRunResult {
+    readonly sequenceId: string;
+    readonly name: string;
+    readonly startedAt: string;
+    readonly outcome: SequenceOutcome;
+    readonly steps: readonly SequenceStepResult[];
+}
+/** Which step waits: for the run panel's waiting row and the CLI's waiting line. */
+export interface CallbackStep {
+    readonly index: number;
+    readonly stepId: string;
+    readonly name: string;
+}
+/** Options for {@link runSequence}. */
+export interface RunSequenceOptions {
+    readonly signal?: AbortSignal;
+    /** Called as each step ends, in order, skipped steps included. */
+    readonly onStepDone?: (result: SequenceStepResult) => void;
+    /** Called with every value that is to be masked from here on, as soon as it is extracted. */
+    readonly onSecretValue?: (value: string) => void;
+    /** Whether `value` contains a credential the host already knows; such a value is treated as secret. */
+    readonly containsKnownSecret?: (value: string) => boolean;
+    /** Injectable clock for `startedAt`. */
+    readonly now?: () => Date;
+    /** Where callback assertions read captures (callback-assertion §2.2). */
+    readonly captures?: CaptureSource;
+    /** The clock callback waits poll by; a test seam. */
+    readonly callbackClock?: CallbackClock;
+    /** A test seam; `CALLBACK_LIMITS.pollIntervalMs` by default. */
+    readonly callbackPollMs?: number;
+    /**
+     * The scopes a step's callback values expand against: the host's own for that request, with
+     * `sequence` set. Absent: the Sequence values alone.
+     */
+    readonly callbackScopes?: (step: ResolvedStep, sequenceScope: PropertyMap) => PropertyScopes;
+    /** Called after a step's send when it has callbacks to wait for. */
+    readonly onCallbackWaiting?: (step: CallbackStep, waiting: readonly CallbackWaiting[]) => void;
+    /**
+     * The protocol modules a step's request is looked up in. Absent: the built-in ones. A host that
+     * sends with `createRunSender` passes the registry of its `RunContext` here too.
+     */
+    readonly registry?: ProtocolRegistry;
+}
+/**
+ * Runs `sequence` against `project`, sending each step through `send`. Never throws: every failure,
+ * a throwing sender included, is an errored step. A step after an abort, after a failure under
+ * `stopOnFailure`, or disabled, is `skipped` and never sent.
+ */
+export declare function runSequence(sequence: SequenceDef, project: Project, send: SequenceStepSender, options?: RunSequenceOptions): Promise<SequenceRunResult>;