@usejourney/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,696 @@
+import { z, ZodType } from 'zod';
+export { infer as ZodInfer, ZodType, ZodTypeAny, z } from 'zod';
+
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+declare const EndpointResponseBrand: unique symbol;
+interface EndpointRef<TResponse> {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly operationId?: string;
+    readonly [EndpointResponseBrand]?: TResponse;
+}
+interface EndpointDescriptor {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly baseUrl?: string;
+}
+type Endpoint<TResponse = unknown> = EndpointRef<TResponse> | EndpointDescriptor;
+type ResponseOf<E> = E extends EndpointRef<infer R> ? R : unknown;
+declare function isEndpointRef(e: Endpoint): e is EndpointRef<unknown>;
+
+declare const JourneyConfigSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    spec: z.ZodDefault<z.ZodString>;
+    generatedDir: z.ZodDefault<z.ZodString>;
+    journeysDir: z.ZodDefault<z.ZodString>;
+    environmentsDir: z.ZodDefault<z.ZodString>;
+    defaultEnvironment: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    runHistoryKeepCount: z.ZodDefault<z.ZodNumber>;
+    tlsRejectUnauthorized: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    spec: string;
+    generatedDir: string;
+    journeysDir: string;
+    environmentsDir: string;
+    runHistoryKeepCount: number;
+    tlsRejectUnauthorized: boolean;
+    name?: string | undefined;
+    defaultEnvironment?: string | undefined;
+    baseUrl?: string | undefined;
+}, {
+    name?: string | undefined;
+    spec?: string | undefined;
+    generatedDir?: string | undefined;
+    journeysDir?: string | undefined;
+    environmentsDir?: string | undefined;
+    defaultEnvironment?: string | undefined;
+    baseUrl?: string | undefined;
+    runHistoryKeepCount?: number | undefined;
+    tlsRejectUnauthorized?: boolean | undefined;
+}>;
+type JourneyConfig = z.infer<typeof JourneyConfigSchema>;
+interface LoadedConfig {
+    readonly config: JourneyConfig;
+    readonly projectDir: string;
+    readonly configPath: string;
+}
+/**
+ * Effective base URL for runtime requests. `config.baseUrl` wins when set;
+ * otherwise the active environment's `BASE_URL` is used. Returns `undefined`
+ * if neither source supplies one — descriptor endpoints can still carry their
+ * own per-step baseUrl in that case.
+ */
+declare function resolveBaseUrl(config: JourneyConfig): string | undefined;
+declare function resolveConfigPaths(loaded: LoadedConfig): {
+    specPath: string;
+    generatedDir: string;
+    journeysDir: string;
+    environmentsDir: string;
+};
+declare function loadConfig(projectDir: string): Promise<LoadedConfig>;
+
+type EnvValues = Record<string, string>;
+declare function setActiveEnvironment(name: string, values: EnvValues): void;
+declare function clearActiveEnvironment(): void;
+declare function env(key: string): string;
+declare function tryEnv(key: string): string | undefined;
+declare function loadEnvironment(environmentsDir: string, name: string): Promise<EnvValues>;
+declare function listEnvironments(environmentsDir: string): Promise<string[]>;
+
+declare class AssertionError extends Error {
+    constructor(message: string);
+}
+interface Expectation<T> {
+    toBe(expected: T): void;
+    toEqual(expected: unknown): void;
+    toBeDefined(): void;
+    toContain(expected: unknown): void;
+    toMatch(expected: RegExp | string): void;
+    toBeGreaterThan(n: number): void;
+    toBeGreaterThanOrEqual(n: number): void;
+    toBeLessThan(n: number): void;
+    toBeLessThanOrEqual(n: number): void;
+    toHaveLength(n: number): void;
+}
+declare function expect<T>(value: T): Expectation<T>;
+
+/**
+ * Output cache for sub-journey invocations. When an `invokeJourney(...)` call
+ * supplies a `cacheKey`, the resolved key + child journey name identify a
+ * cache slot; a hit short-circuits the child run and replays the stored
+ * output. See the M7 RFC (#86) for the lifetime model.
+ */
+/** Cache lifetime selected via `--cache`. */
+type CacheMode = "off" | "run" | "process" | "disk";
+interface CacheEntry {
+    value: unknown;
+    /** Epoch ms after which the entry is stale; absent → no expiry. */
+    expiresAt?: number;
+}
+/**
+ * Storage backend for sub-journey outputs. `get`/`set` may be sync (memory) or
+ * async (disk); callers `await` the result either way.
+ */
+interface SubJourneyCache {
+    get(key: string): CacheEntry | undefined | Promise<CacheEntry | undefined>;
+    set(key: string, value: unknown, ttlMs?: number): void | Promise<void>;
+}
+/** Composite cache key — `${childJourneyName}:${resolvedKey}`. */
+declare function subJourneyCacheKey(journeyName: string, resolvedKey: string): string;
+/**
+ * In-memory cache. Lives as long as the holding process keeps the instance —
+ * the CLI reuses one instance for `--cache=process` (persists across runs of
+ * `journey serve`) and a fresh one per run for `--cache=run`.
+ */
+declare class MemorySubJourneyCache implements SubJourneyCache {
+    private readonly store;
+    get(key: string): CacheEntry | undefined;
+    set(key: string, value: unknown, ttlMs?: number): void;
+    clear(): void;
+}
+/**
+ * Disk-backed cache: one JSON file per key under `dir`, named by the SHA-256
+ * of the composite key. Survives process restarts (`--cache=disk`).
+ *
+ * Values must be JSON-serializable — a sub-journey `output(...)` is normally a
+ * plain object, so this holds in practice. Non-JSON values (Date, undefined,
+ * functions) are silently lost in the round-trip.
+ */
+declare class DiskSubJourneyCache implements SubJourneyCache {
+    private readonly dir;
+    constructor(dir: string);
+    private pathFor;
+    get(key: string): Promise<CacheEntry | undefined>;
+    set(key: string, value: unknown, ttlMs?: number): Promise<void>;
+}
+/**
+ * Builds the cache backend for a `CacheMode`. `off` → no cache. `run` and
+ * `process` → a fresh `MemorySubJourneyCache` (the caller controls reuse, and
+ * so the lifetime). `disk` → a `DiskSubJourneyCache` under `diskDir`.
+ */
+declare function createSubJourneyCache(mode: CacheMode, opts: {
+    diskDir: string;
+}): SubJourneyCache | undefined;
+
+/**
+ * Pluggable request/response logger. The runtime calls into a logger attached
+ * to the HttpContext (if any); CLI/GUI surfaces wire one up when --debug or
+ * DEBUG=journey is set.
+ */
+interface RequestLog {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+interface ResponseLog {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+    durationMs: number;
+}
+/**
+ * Fired at the top of a run before any step executes. The runtime allocates a
+ * runId if the caller didn't pass one in, so subscribers can correlate later
+ * events back to the run.
+ */
+interface RunStartEvent {
+    runId: string;
+    journeyNames: string[];
+}
+/** Fired once per run after every journey has either completed or halted. */
+interface RunEndEvent {
+    runId: string;
+    ok: boolean;
+    durationMs: number;
+    results: ReadonlyArray<{
+        name: string;
+        ok: boolean;
+    }>;
+}
+/**
+ * Fired once per journey, right after `runJourney` has finished collecting the
+ * step list (a single execution of `def.body()`) and before any `onStepStart`.
+ * The full ordered step list is known at this point — subscribers can use it to
+ * pre-render a timeline without waiting for each `step:start` to arrive.
+ *
+ * Particularly useful for journeys whose bodies inject steps via helpers (e.g.
+ * `registerAuthStep()` calling `step()` from inside the body): a static parse
+ * of the source can't see those, but `onPlanned` does.
+ *
+ * `stepIdxOffset` is the absolute index of the first step in this journey
+ * within the surrounding `runAllRegistered` call; consumers can use it to map
+ * positions in `steps` back to the monotonic `stepIdx` values that subsequent
+ * `step:start` / `step:end` events will carry.
+ */
+/**
+ * One entry in a planned pipeline. `kind` is `"step"` for an HTTP step
+ * (carries method/path from the endpoint) and `"sub"` for an
+ * `invokeJourney(...)` node (carries the child journey's display name;
+ * method/path are unset).
+ *
+ * A `"sub"` node carries `children` — the best-effort plan of the child
+ * pipeline, discovered by evaluating the reusable journey body at plan time
+ * (recursively, so nested sub-journeys are included). `incomplete` is set
+ * when that discovery could not run — e.g. the body threw, or the recursion
+ * cap was hit — in which case `children` is absent and subscribers fall back
+ * to the live `onGroupStart` / step events once the sub-journey executes.
+ *
+ * Plan-time discovery is best-effort: conditional `step()` calls and a
+ * sub-journey that turns out to be a cache hit can make the planned tree
+ * differ from what actually runs. The live group/step events are always
+ * authoritative.
+ */
+interface PlannedNode {
+    kind?: "step" | "sub";
+    name: string;
+    method?: string;
+    path?: string;
+    /** Sub-journey only — best-effort plan of the child pipeline. */
+    children?: PlannedNode[];
+    /** Sub-journey only — true when the child pipeline could not be discovered. */
+    incomplete?: boolean;
+}
+interface RunPlannedEvent {
+    runId: string;
+    journeyIdx: number;
+    journeyName: string;
+    stepIdxOffset: number;
+    /**
+     * Resolved pipeline entries, in order. A `"sub"` entry nests its child
+     * pipeline under `children` (see `PlannedNode`) so subscribers can
+     * pre-render the full tree — including nested sub-journeys — without
+     * waiting for the run to enter each group.
+     */
+    steps: ReadonlyArray<PlannedNode>;
+}
+/**
+ * Fired at the moment a sub-journey node (an `invokeJourney(handle, ...)`
+ * call) begins executing — before any of the child's steps run. The `stepIdx`
+ * is the slot consumed by the sub-journey itself in the parent run's
+ * monotonic counter; child step events that follow carry `firstChildStepIdx`
+ * and beyond.
+ */
+interface GroupStartEvent {
+    runId: string;
+    journeyIdx: number;
+    /** Display name for the timeline (override on the call site, else handle.name). */
+    name: string;
+    /** Child journey's authored name (i.e. handle.name). Distinct from `name` only when overridden. */
+    childJourneyName: string;
+    /** Slot consumed by the sub-journey node itself. */
+    stepIdx: number;
+    /** First child stepIdx that will fire inside this group (== `stepIdx + 1`). */
+    firstChildStepIdx: number;
+    /** "miss" / "hit". Until #90 lands the cache store, this is always "miss". */
+    cacheStatus: "miss" | "hit";
+    /** Resolved cache key if the caller supplied a `cacheKey` opt. Omitted otherwise. */
+    resolvedKey?: string;
+}
+/** Fired once the sub-journey node finishes (success, failure, or cache hit short-circuit). */
+interface GroupEndEvent {
+    runId: string;
+    journeyIdx: number;
+    name: string;
+    childJourneyName: string;
+    stepIdx: number;
+    /** Last child stepIdx that fired inside this group. Equal to `stepIdx` when the child had no steps (or hit cache). */
+    lastChildStepIdx: number;
+    ok: boolean;
+    durationMs: number;
+    error?: string;
+}
+/**
+ * Fired when a step starts executing, before any lazy-resolved headers/query/
+ * body are materialized and before `onRequest`. `stepIdx` is monotonic across
+ * the whole run, not just within a journey — this way consumers don't need to
+ * track journey boundaries to correlate events.
+ */
+interface StepStartEvent {
+    runId: string;
+    journeyIdx: number;
+    journeyName: string;
+    stepIdx: number;
+    name: string;
+}
+/** Fired when a step finishes, after `onResponse`/`onError`. */
+interface StepEndEvent {
+    runId: string;
+    journeyIdx: number;
+    stepIdx: number;
+    ok: boolean;
+    durationMs: number;
+    error?: string;
+}
+/**
+ * Fired for `console.log` / `console.warn` / `console.error` calls made from
+ * inside step hooks (e.g. `after(res) { console.log(res.body.id); }`). The
+ * subscriber attaches its own `stepIdx`; core carries only the raw level + text.
+ */
+interface LogEvent {
+    level: "info" | "warn" | "error";
+    text: string;
+}
+interface JourneyLogger {
+    onRunStart?(event: RunStartEvent): void;
+    onRunEnd?(event: RunEndEvent): void;
+    onPlanned?(event: RunPlannedEvent): void;
+    onStepStart?(event: StepStartEvent): void;
+    onStepEnd?(event: StepEndEvent): void;
+    onRequest?(req: RequestLog): void;
+    onResponse?(req: RequestLog, res: ResponseLog): void;
+    onError?(req: RequestLog, error: unknown, durationMs: number): void;
+    /** Fired when a sub-journey node begins executing, before any child step events. */
+    onGroupStart?(event: GroupStartEvent): void;
+    /** Fired when a sub-journey node finishes; carries the child step range and the group outcome. */
+    onGroupEnd?(event: GroupEndEvent): void;
+    /**
+     * Fired for user-code `console.*` calls captured during a run. The runner
+     * installs a shim that forwards each call here and to the original console
+     * so terminal output stays intact.
+     */
+    onLog?(event: LogEvent): void;
+    info?(message: string): void;
+}
+/** Header names that get redacted before logging by default. */
+declare const SECRET_HEADERS: ReadonlyArray<string>;
+/**
+ * Walks `err.cause` up to `depth` links and joins each message with ` ← `.
+ * Surfaces the real reason behind `fetch failed` (Node's fetch wraps undici
+ * errors, e.g. `ECONNREFUSED`, `ENOTFOUND`, OpenSSL cert errors). Includes
+ * the error `code` in parentheses when present.
+ */
+declare function describeError(err: unknown, depth?: number): string;
+declare function maskHeaders(headers: Record<string, string>, masks?: ReadonlyArray<string>): Record<string, string>;
+interface ConsoleLoggerOptions {
+    /** Where to write each line. Defaults to console.error so stdout stays clean. */
+    write?: (line: string) => void;
+    /** Mask secret-looking headers (default true). */
+    mask?: boolean;
+    /** Truncate logged response/request bodies past this many chars (default 1024). */
+    maxBodyChars?: number;
+}
+declare function createConsoleLogger(opts?: ConsoleLoggerOptions): JourneyLogger;
+/**
+ * Returns a console logger when DEBUG env var includes "journey" (or "*"),
+ * otherwise undefined. Useful for CLI bins that want to opt in via env var.
+ */
+declare function loggerFromEnv(env?: NodeJS.ProcessEnv): JourneyLogger | undefined;
+
+interface HttpResponse<T = unknown> {
+    status: number;
+    headers: Record<string, string>;
+    body: T;
+}
+interface HttpContext {
+    /** Fallback base URL when the endpoint doesn't carry its own. */
+    baseUrl?: string;
+    /** Global default headers applied before per-step headers. */
+    defaultHeaders?: Record<string, string>;
+    /** Injectable fetch — default is global fetch. Tests override this. */
+    fetchImpl?: typeof fetch;
+    /** Optional logger called before/after each request. */
+    logger?: JourneyLogger;
+    /**
+     * Optional undici `Dispatcher` (typed as `unknown` so core stays
+     * dependency-free). When set, it is forwarded to `fetch` as `init.dispatcher`
+     * so callers can disable TLS verification, route through a proxy, or pin a
+     * client cert. The CLI's `--insecure` flag uses this.
+     */
+    dispatcher?: unknown;
+    /**
+     * Optional run-scoped AbortSignal. When set, every `fetch` issued through
+     * `execute` (and through the instrumented `@usejourney/core` `fetch` helper)
+     * receives it, and `runJourney` stops iterating steps as soon as it fires.
+     * Used by the dev server's `POST /api/runs/:id/abort` route to cancel an
+     * in-flight run.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional sub-journey output cache. When set, an `invokeJourney(...)` call
+     * that supplies a `cacheKey` (and isn't `cache: "off"`) replays a stored
+     * output instead of re-running the child. Absent → caching disabled
+     * (`--cache=off`). Wired by the CLI from the `--cache` flag.
+     */
+    subJourneyCache?: SubJourneyCache;
+    /** Default TTL (ms) for sub-journey cache writes; per-call `cacheTtlMs` overrides. */
+    subJourneyCacheTtlMs?: number;
+}
+interface RequestSpec {
+    method: HttpMethod;
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    timeoutMs?: number;
+}
+interface BuildRequestOptions {
+    endpoint: Endpoint;
+    params?: Record<string, string | number>;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeoutMs?: number;
+}
+declare function resolveUrl(endpoint: Endpoint, ctx: HttpContext, params: Record<string, string | number> | undefined, query: Record<string, string | number | boolean | undefined> | undefined): string;
+declare function buildRequest(opts: BuildRequestOptions, ctx: HttpContext): RequestSpec;
+declare function execute(req: RequestSpec, ctx: HttpContext): Promise<HttpResponse>;
+
+/** Caller-supplied run metadata. runId is forwarded to every lifecycle event. */
+interface RunMeta {
+    runId?: string;
+    /**
+     * Absolute (monotonic across journey boundaries) stepIdx to stop after. The
+     * run still emits `run:end` cleanly; journeys/steps past this index are not
+     * collected or executed. Use for "run only up to this step" in the GUI.
+     */
+    upToStepIdx?: number;
+}
+type Lazy<T> = T | (() => T | Promise<T>);
+interface StepOptions<E extends Endpoint> {
+    endpoint: E;
+    params?: Lazy<Record<string, string | number>>;
+    query?: Lazy<Record<string, string | number | boolean | undefined>>;
+    headers?: Lazy<Record<string, string>>;
+    body?: Lazy<unknown>;
+    timeoutMs?: number;
+    assert?: (res: HttpResponse<ResponseOf<E>>) => void | Promise<void>;
+    after?: (res: HttpResponse<ResponseOf<E>>) => void | Promise<void>;
+}
+interface StepDef {
+    name: string;
+    options: StepOptions<Endpoint>;
+}
+/**
+ * Recorded call to a reusable journey, captured in the parent's pipeline at
+ * registration time. The `handle` carries the child def and its input/output
+ * schemas; everything else is per-call configuration. See `invokeJourney`.
+ */
+interface SubJourneyCallDef {
+    handle: JourneyHandle<unknown, unknown>;
+    /** Display label for the timeline; defaults to `handle.name`. */
+    name?: string;
+    /** Lazy or eager input. Validated against `handle.inputs` (if set) before child body runs. */
+    inputs?: Lazy<unknown>;
+    /** Cache opts — plumbed through `onGroupStart`. Store lookup lands in #90. */
+    cacheKey?: string | ((input: unknown) => string);
+    cacheTtlMs?: number;
+    cache?: "off" | "inherit";
+    assert?: (out: unknown) => void | Promise<void>;
+    after?: (out: unknown) => void | Promise<void>;
+}
+/**
+ * One ordered entry in the resolved pipeline of a journey. Both kinds consume
+ * exactly one `stepIdx` slot in the run's monotonic counter; child steps
+ * inside a `sub` node consume their own slots in the same counter.
+ */
+type PipelineNode = {
+    kind: "step";
+    def: StepDef;
+} | {
+    kind: "sub";
+    def: SubJourneyCallDef;
+};
+/**
+ * Typed reference to a reusable journey. Returned by `journey(name, { reusable: true, ... }, body)`.
+ * Pass it to `invokeJourney(handle, ...)`; the phantom `I`/`O` parameters drive
+ * type inference at the call site.
+ */
+interface JourneyHandle<I = unknown, O = unknown> {
+    readonly name: string;
+    readonly inputs?: ZodType<I>;
+    readonly outputs?: ZodType<O>;
+    /** Internal: the def the runtime invokes. Treat as opaque. */
+    readonly __def: JourneyDef;
+    /** Phantom — never assigned at runtime, only present in the type. */
+    readonly __input?: I;
+    readonly __output?: O;
+}
+/**
+ * k6 `export const options` shape for an exported journey. Strict named fields
+ * cover the common load profiles (vus + duration, iterations, stages); the
+ * index signature passes everything else through so adding a k6 knob (e.g.
+ * thresholds, scenarios, ext) does not require a core release.
+ */
+interface K6JourneyOptions {
+    vus?: number;
+    duration?: string;
+    iterations?: number;
+    stages?: Array<{
+        duration: string;
+        target: number;
+    }>;
+    [extra: string]: unknown;
+}
+/**
+ * Per-call configuration accepted by the 3-arg `journey()` overloads. The
+ * field set is split by mode:
+ *
+ * - Entry journeys (default — registered for `runAllRegistered`): `tags`, `k6`.
+ * - Reusable journeys (`reusable: true`, no auto-run, returns a handle):
+ *   `inputs`, `outputs`.
+ *
+ * The two sets are disjoint in the public overloads. Mixing is an `as any`
+ * escape from the type-level split; the footgun guard in `runAllRegistered`
+ * catches it at run start.
+ */
+interface JourneyOptions {
+    /** Entry-only — drives `journey export k6 --tag` filtering. */
+    tags?: string[];
+    /** Entry-only — baked into the emitted k6 script's `export const options`. */
+    k6?: K6JourneyOptions;
+    /** Switches to reusable mode when true. */
+    reusable?: boolean;
+    /** Reusable-only — child input schema. Validated before the child body runs. */
+    inputs?: ZodType;
+    /** Reusable-only — child output schema. Validated when the child completes. */
+    outputs?: ZodType;
+}
+interface JourneyDef {
+    name: string;
+    /** Bodies for entries take no argument; reusable bodies take the validated input. */
+    body: (input?: unknown) => void | Promise<void>;
+    options?: JourneyOptions;
+}
+interface StepResult {
+    name: string;
+    ok: boolean;
+    request?: {
+        method: string;
+        url: string;
+    };
+    response?: HttpResponse;
+    error?: string;
+    durationMs: number;
+    /** Set on sub-journey nodes; the flat list of child step results in execution order. */
+    children?: StepResult[];
+    /** Set on sub-journey nodes — distinguishes a group entry from a regular step. */
+    kind?: "step" | "sub";
+    /** Set on sub-journey nodes — whether the output cache was hit or missed. */
+    cacheStatus?: "hit" | "miss";
+}
+interface JourneyResult {
+    name: string;
+    ok: boolean;
+    steps: StepResult[];
+    durationMs: number;
+}
+/**
+ * Returns the HttpContext bound to the currently-executing journey, or
+ * undefined when called outside a run. Consumed by the instrumented `fetch`
+ * helper so that ad-hoc HTTP calls made from inside step hooks land on the
+ * same logger as the steps themselves.
+ */
+declare function getCurrentCtx(): HttpContext | undefined;
+/** Type for the journey body when no `inputs` schema is set. */
+type EntryBody = () => void | Promise<void>;
+/** Type for a reusable journey body — receives the validated input. */
+type ReusableBody<I> = (input: I) => void | Promise<void>;
+/** Strict reusable options — discriminated by literal `reusable: true`. */
+interface ReusableJourneyOptions<I, O> {
+    reusable: true;
+    inputs?: ZodType<I>;
+    outputs?: ZodType<O>;
+}
+/** Strict entry options — `reusable` must be absent or false. */
+interface EntryJourneyOptions {
+    reusable?: false;
+    tags?: string[];
+    k6?: K6JourneyOptions;
+}
+declare function journey<I, O>(name: string, options: ReusableJourneyOptions<I, O>, body: ReusableBody<I>): JourneyHandle<I, O>;
+declare function journey(name: string, options: EntryJourneyOptions, body: EntryBody): void;
+declare function journey(name: string, body: EntryBody): void;
+declare function step<E extends Endpoint>(name: string, options: StepOptions<E>): void;
+/** Options accepted at an `invokeJourney(handle, opts)` call site. */
+interface InvokeJourneyOptions<I, O> {
+    inputs?: I | (() => I | Promise<I>);
+    /** Override the timeline display label; defaults to `handle.name`. */
+    name?: string;
+    cacheKey?: string | ((input: I) => string);
+    cacheTtlMs?: number;
+    cache?: "off" | "inherit";
+    assert?: (out: O) => void | Promise<void>;
+    after?: (out: O) => void | Promise<void>;
+}
+/**
+ * Pipeline-level primitive: registers a sub-journey call as a node in the
+ * surrounding journey's pipeline. Like `step()`, this is called during the
+ * registration phase (the journey body), not at execution time — the child
+ * runs inline when the runtime reaches the node.
+ */
+declare function invokeJourney<I, O>(handle: JourneyHandle<I, O>, opts?: InvokeJourneyOptions<I, O>): void;
+/**
+ * Terminal helper for reusable journeys: records the value returned to the
+ * parent's `invokeJourney({ after })`. Called from inside any step's `after`
+ * hook within the child body. Multiple calls: last wins (with a warn log).
+ * Called outside a reusable journey context: warn and no-op.
+ */
+declare function output(value: unknown): void;
+declare function getRegisteredJourneys(): ReadonlyArray<JourneyDef>;
+declare function clearRegistry(): void;
+/** Walks a journey body and returns every pipeline node (step + sub) in order. */
+declare function collectPipeline(def: JourneyDef): Promise<ReadonlyArray<PipelineNode>>;
+/**
+ * Collects the child pipeline of a sub-journey call, resolving the call's
+ * `inputs` and passing them to the reusable body so `input.*` references in
+ * the child resolve. Lets an exporter (#92) walk a journey into a nested
+ * tree without running it. Best-effort: input resolution failures fall back
+ * to `undefined`, mirroring `discoverChildNodes`.
+ */
+declare function collectSubPipeline(call: SubJourneyCallDef): Promise<ReadonlyArray<PipelineNode>>;
+/**
+ * Resolves a journey's plan tree without executing it — the same nested
+ * `PlannedNode[]` that `onPlanned` broadcasts at run start. Evaluates the
+ * journey body (and, best-effort, each sub-journey body) to discover steps;
+ * performs no HTTP. Lets a surface pre-render a timeline before the run.
+ *
+ * `env()` references in the body are resolved against the active environment,
+ * so callers should `setActiveEnvironment(...)` first, exactly as they would
+ * before a run.
+ */
+declare function planJourney(def: JourneyDef): Promise<PlannedNode[]>;
+/**
+ * Runs a single entry journey. Emits `onStepStart` / `onStepEnd` (and
+ * `onGroupStart` / `onGroupEnd` for any sub-journey nodes) through
+ * `ctx.logger`; run-level lifecycle events (`onRunStart` / `onRunEnd`) are
+ * the caller's responsibility — use `runAllRegistered` to get the full set.
+ *
+ * Pass `opts.journeyIdx` (and `opts.runId`) so step events carry the same
+ * correlation identifiers as surrounding `runAllRegistered` invocations would
+ * use; otherwise a fresh runId is minted and journeyIdx defaults to 0.
+ */
+declare function runJourney(def: JourneyDef, ctx: HttpContext, opts?: {
+    runId?: string;
+    journeyIdx?: number;
+    stepIdxOffset?: number;
+    upToStepIdx?: number;
+}): Promise<JourneyResult>;
+/**
+ * Runs every currently-registered entry journey, clearing the registry first.
+ * Emits `onRunStart` / `onRunEnd` bookends around the set, with each journey's
+ * steps in between sharing the same runId. stepIdx is monotonic across the
+ * whole run so a subscriber can key network/log streams by stepIdx without
+ * caring about journey boundaries.
+ */
+declare function runAllRegistered(ctx: HttpContext, opts?: RunMeta): Promise<JourneyResult[]>;
+
+interface RunRecord {
+    id: string;
+    timestamp: string;
+    results: JourneyResult[];
+}
+interface RunSummary {
+    id: string;
+    timestamp: string;
+    journeyNames: string[];
+    ok: boolean;
+    /** Sum of durationMs across all journeys in the run. */
+    durationMs: number;
+    /** Total step count across all journeys. */
+    stepCount: number;
+}
+declare function writeRun(cacheDir: string, results: JourneyResult[]): Promise<RunRecord>;
+declare function listRuns(cacheDir: string): Promise<RunSummary[]>;
+declare function readRun(cacheDir: string, id: string): Promise<RunRecord | undefined>;
+declare function pruneRuns(cacheDir: string, keep: number): Promise<number>;
+
+type FetchInput = Parameters<typeof globalThis.fetch>[0];
+type FetchInit = Parameters<typeof globalThis.fetch>[1];
+type FetchResponse = Awaited<ReturnType<typeof globalThis.fetch>>;
+/**
+ * Drop-in replacement for `globalThis.fetch` that routes through the
+ * currently-executing journey's logger when called from inside a step hook.
+ *
+ * Outside a run context (no active `runJourney`) it delegates to the platform
+ * `fetch` with no behaviour change — the same helper module is therefore
+ * safe to import from ad-hoc scripts or top-level setup code.
+ *
+ * Intended use: auth-helper steps that mint a token from a separate service
+ * inside an `after` hook. Raw `globalThis.fetch` works but is invisible to
+ * the Debug Console and run history; this wrapper makes those calls
+ * observable without forcing helpers to thread the HttpContext through.
+ */
+declare function fetch$1(input: FetchInput, init?: FetchInit): Promise<FetchResponse>;
+
+export { AssertionError, type BuildRequestOptions, type CacheEntry, type CacheMode, type ConsoleLoggerOptions, DiskSubJourneyCache, type Endpoint, type EndpointDescriptor, type EndpointRef, type EntryJourneyOptions, type EnvValues, type Expectation, type GroupEndEvent, type GroupStartEvent, type HttpContext, type HttpMethod, type HttpResponse, type InvokeJourneyOptions, type JourneyConfig, JourneyConfigSchema, type JourneyDef, type JourneyHandle, type JourneyLogger, type JourneyOptions, type JourneyResult, type K6JourneyOptions, type LoadedConfig, type LogEvent, MemorySubJourneyCache, type PipelineNode, type PlannedNode, type RequestLog, type RequestSpec, type ResponseLog, type ResponseOf, type ReusableJourneyOptions, type RunEndEvent, type RunMeta, type RunPlannedEvent, type RunRecord, type RunStartEvent, type RunSummary, SECRET_HEADERS, type StepDef, type StepEndEvent, type StepOptions, type StepResult, type StepStartEvent, type SubJourneyCache, type SubJourneyCallDef, buildRequest, clearActiveEnvironment, clearRegistry, collectPipeline, collectSubPipeline, createConsoleLogger, createSubJourneyCache, describeError, env, execute, expect, fetch$1 as fetch, getCurrentCtx, getRegisteredJourneys, invokeJourney, isEndpointRef, journey, listEnvironments, listRuns, loadConfig, loadEnvironment, loggerFromEnv, maskHeaders, output, planJourney, pruneRuns, readRun, resolveBaseUrl, resolveConfigPaths, resolveUrl, runAllRegistered, runJourney, setActiveEnvironment, step, subJourneyCacheKey, tryEnv, writeRun };