@glubean/sdk 0.7.0 → 0.8.0

package/dist/load/runner.d.ts

@@ -0,0 +1,201 @@
+/**
+ * loadRunner(): the pressure model + report model over a loadScenario.
+ *
+ * `loadRunner()` is the runnable: it references one `loadScenario()` (or a
+ * traffic mix of several) and says how much pressure to apply. Discovery
+ * (M2) surfaces only `loadRunner()` exports as runnable; the referenced
+ * scenarios are workloads, not independently scheduled.
+ *
+ * M1 is the static authoring surface: `loadRunner()` returns a `LoadPlan`
+ * holding the resolved config. Actual execution lives in @glubean/runner.
+ */
+import type { LoadBuilder } from "./builder.js";
+import type { FeederBinding } from "./feeder.js";
+import type { LoadProjection } from "./projection.js";
+import type { LoadScenario } from "./scenario.js";
+import type { LoadAssertionFailureMode } from "./step.js";
+/** A duration as milliseconds (number) or a human string like `"60s"` / `"2m"`. */
+export type LoadDuration = number | string;
+export interface LoadProducerSlotInfo {
+    id: string;
+    index: number;
+}
+export interface LoadIterationInfo {
+    id: string;
+    index: number;
+}
+/**
+ * Arguments passed to a function-form `input`. `TRow` is the `loadRunner.each()`
+ * row type that produced this plan (typed and present for each variants);
+ * `undefined` for non-each plans.
+ */
+export interface LoadInputArgs<TRow = undefined> {
+    row: TRow;
+    /** Feeder-allocated rows for this iteration, keyed by feeder name. */
+    feed: Record<string, any>;
+    producerSlot: LoadProducerSlotInfo;
+    iteration: LoadIterationInfo;
+}
+/**
+ * Per-iteration scenario input. Object form is a static input (same for every
+ * iteration); function form is the canonical form when feeders / producer-slot /
+ * iteration / `.each()` row participate. There is no hidden merge.
+ */
+export type LoadInputOption<TInput, TRow = undefined> = TInput | ((args: LoadInputArgs<TRow>) => TInput);
+/** Safety valve for `ctx.report.primaryComplete(... releaseProducerSlot: true)`. */
+export interface LoadContinuationConfig {
+    maxOutstanding?: number;
+    maxConcurrent?: number;
+    minPollInterval?: LoadDuration;
+    drainTimeout?: LoadDuration;
+    onBacklogFull?: "block-producer" | "fail-iteration";
+}
+/** Optional pacing / think-time (MVP may leave unimplemented → back-to-back). */
+export interface LoadPacingConfig {
+    thinkTime?: LoadDuration | {
+        min: LoadDuration;
+        max: LoadDuration;
+    };
+}
+/** Threshold expressions for one scope (e.g. `errorRate: "<1%"`, `p95: "<800ms"`). */
+export interface LoadThresholdScope {
+    errorRate?: string;
+    p50?: string;
+    p90?: string;
+    p95?: string;
+    p99?: string;
+    throughputPerSec?: string;
+    backlog?: string;
+    backpressureMs?: string;
+}
+/** Structured thresholds. `endpoints` / `steps` are keyed by routeKey / stepId. */
+export interface LoadThresholds {
+    transaction?: LoadThresholdScope;
+    primary?: LoadThresholdScope;
+    endToEnd?: LoadThresholdScope;
+    continuation?: LoadThresholdScope;
+    endpoints?: Record<string, LoadThresholdScope>;
+    steps?: Record<string, LoadThresholdScope>;
+}
+/** Bounded report sampling caps. */
+export interface LoadReportConfig {
+    failureTraces?: number;
+    slowTransactionSummaries?: number;
+}
+/** A scenario reference: a built `LoadScenario` or an un-built `LoadBuilder`. */
+export type LoadScenarioRef<Input = unknown> = LoadScenario<Input, any> | LoadBuilder<Input, any>;
+type Feeders = Record<string, FeederBinding>;
+interface LoadRunnerCommon {
+    concurrency: number;
+    duration?: LoadDuration;
+    iterations?: number;
+    rampUp?: LoadDuration;
+    pacing?: LoadPacingConfig;
+    continuation?: LoadContinuationConfig;
+    assertions?: {
+        onFailure?: LoadAssertionFailureMode;
+    };
+    thresholds?: LoadThresholds;
+    report?: LoadReportConfig;
+    /** How a run-level abort (stop / duration deadline / SIGINT) reaches in-flight
+     *  requests.
+     *  - `"precise"` (default): cancel in-flight HTTP at once. Uses a leak-free
+     *    per-iteration abort bridge — no per-request listener accumulation.
+     *  - `"coarse"`: don't wire the abort signal into each request; stop between steps
+     *    instead. A few % more throughput for high-RPS runs where requests are short,
+     *    at the cost of letting an already-sent request finish before the run stops. */
+    abort?: "precise" | "coarse";
+}
+/** Single-scenario load runner config. `TRow` is the `.each()` row, if any. */
+export interface LoadRunnerConfig<Input = unknown, TRow = undefined> extends LoadRunnerCommon {
+    scenario: LoadScenarioRef<Input>;
+    feeders?: Feeders;
+    input?: LoadInputOption<Input, TRow>;
+}
+/** One entry in a traffic mix. */
+export interface LoadMixEntry<Input = unknown, TRow = undefined> {
+    id: string;
+    scenario: LoadScenarioRef<Input>;
+    weight: number;
+    feeders?: Feeders;
+    input?: LoadInputOption<Input, TRow>;
+}
+/** Multi-scenario (traffic mix) config. Each entry may have its own input/feeders. */
+export interface LoadMixConfig<TRow = undefined> extends LoadRunnerCommon {
+    scenarios: LoadMixEntry<any, TRow>[];
+    /** Shared feeders (no Input coupling). Per-entry feeders override these. */
+    feeders?: Feeders;
+}
+export type AnyLoadRunnerConfig = LoadRunnerConfig<any, any> | LoadMixConfig<any>;
+/** A runnable load plan (output of `loadRunner()`). */
+export interface LoadPlan {
+    readonly __glubean_type: "load-runner";
+    id: string;
+    config: AnyLoadRunnerConfig;
+    /**
+     * For `loadRunner.each()` variants: the table row that produced this plan.
+     * The load runtime surfaces it to function-form `input` as `args.row`.
+     * Absent for non-each plans.
+     */
+    row?: Record<string, unknown>;
+    /**
+     * Plain-data projection of this plan (runnerId / scenarios / steps /
+     * normalized durations / threshold scopes), exposed as a lazily-recomputed
+     * getter so it always reflects the current config / scenario builders — no
+     * stale snapshot if a scenario gains steps after `loadRunner()`. Discovery
+     * (scanner / CLI) reads it by duck-typing the exported value: no SDK import
+     * and no global registry needed.
+     */
+    readonly projection: LoadProjection;
+}
+interface LoadRunnerFn {
+    /** Single-scenario load plan. */
+    <Input, TRow = undefined>(id: string, config: LoadRunnerConfig<Input, TRow>): LoadPlan;
+    /** Traffic-mix load plan. */
+    (id: string, config: LoadMixConfig): LoadPlan;
+    /**
+     * Scenario-level inventory expansion: one load plan per row (e.g. by plan,
+     * region, tenant). Each variant has its own id / thresholds / report, and the
+     * factory may return a single scenario or a traffic mix. Function-form `input`
+     * receives the producing row as a typed `args.row`.
+     */
+    each<TRow extends object>(table: readonly TRow[]): <Input>(idTemplate: string, factory: (row: TRow, index: number) => LoadRunnerConfig<Input, TRow> | LoadMixConfig<TRow>) => LoadPlan[];
+}
+/**
+ * Define a pressure plan over one or more load scenarios.
+ *
+ * @example single scenario
+ * ```ts
+ * export const checkoutLoad = loadRunner("checkout-300", {
+ *   scenario: checkoutScenario,
+ *   concurrency: 300,
+ *   duration: "60s",
+ *   input: ({ feed, producerSlot, iteration }) => ({
+ *     user: feed.user,
+ *     clientRequestId: `${producerSlot.id}-${iteration.id}`,
+ *   }),
+ *   thresholds: { transaction: { errorRate: "<1%", p95: "<2000ms" } },
+ * });
+ * ```
+ */
+export declare const loadRunner: LoadRunnerFn;
+/**
+ * Type-safe constructor for a traffic-mix entry: it binds `input` to the
+ * scenario's `Input`, so a mismatched input shape is rejected at author time.
+ *
+ * Use it inside `scenarios: [...]`. A bare object literal in the array is only
+ * checked against `LoadMixEntry<any>` (TypeScript can't infer a distinct `Input`
+ * per array element), so wrap each entry with `loadMixEntry()` for per-entry
+ * type checking of heterogeneous typed scenarios.
+ *
+ * @example
+ * ```ts
+ * scenarios: [
+ *   loadMixEntry({ id: "checkout", scenario: checkout, weight: 70, input: () => ({ sku: "s" }) }),
+ *   loadMixEntry({ id: "refund", scenario: refund, weight: 30, input: () => ({ orderId: "o" }) }),
+ * ]
+ * ```
+ */
+export declare function loadMixEntry<Input, TRow = undefined>(entry: LoadMixEntry<Input, TRow>): LoadMixEntry<any, TRow>;
+export {};
+//# sourceMappingURL=runner.d.ts.map

package/dist/load/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/load/runner.ts"],"names":[],"mappings":"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"}

package/dist/load/runner.js

@@ -0,0 +1,78 @@
+import { projectLoadPlan } from "./projection.js";
+/** Interpolate `$index` and `$field` placeholders in an `.each()` id template. */
+function interpolateId(template, row, index) {
+    // Token-aware: match a whole `$identifier` placeholder, so a field name that
+    // prefixes another (possibly missing) longer placeholder can't corrupt it
+    // (e.g. `$plan` must not eat the `$plan` inside a missing `$planId`).
+    return template.replace(/\$(\w+)/g, (match, name) => {
+        if (name === "index")
+            return String(index);
+        if (Object.prototype.hasOwnProperty.call(row, name))
+            return String(row[name]);
+        return match; // unknown placeholder — leave intact rather than silently corrupt
+    });
+}
+/**
+ * Build a LoadPlan whose `projection` is a lazily-recomputed getter, so it
+ * always reflects the current config / scenario builders (no stale snapshot if
+ * a scenario gains steps after `loadRunner()` is called).
+ */
+function makeLoadPlan(id, config, row) {
+    const plan = {
+        __glubean_type: "load-runner",
+        id,
+        config,
+        ...(row !== undefined ? { row } : {}),
+    };
+    Object.defineProperty(plan, "projection", {
+        get: () => projectLoadPlan(plan),
+        enumerable: true,
+    });
+    return plan;
+}
+const loadRunnerImpl = (id, config) => makeLoadPlan(id, config);
+loadRunnerImpl.each = (table) => {
+    return (idTemplate, factory) => table.map((row, index) => {
+        const rowRecord = row;
+        return makeLoadPlan(interpolateId(idTemplate, rowRecord, index), factory(row, index), rowRecord);
+    });
+};
+/**
+ * Define a pressure plan over one or more load scenarios.
+ *
+ * @example single scenario
+ * ```ts
+ * export const checkoutLoad = loadRunner("checkout-300", {
+ *   scenario: checkoutScenario,
+ *   concurrency: 300,
+ *   duration: "60s",
+ *   input: ({ feed, producerSlot, iteration }) => ({
+ *     user: feed.user,
+ *     clientRequestId: `${producerSlot.id}-${iteration.id}`,
+ *   }),
+ *   thresholds: { transaction: { errorRate: "<1%", p95: "<2000ms" } },
+ * });
+ * ```
+ */
+export const loadRunner = loadRunnerImpl;
+/**
+ * Type-safe constructor for a traffic-mix entry: it binds `input` to the
+ * scenario's `Input`, so a mismatched input shape is rejected at author time.
+ *
+ * Use it inside `scenarios: [...]`. A bare object literal in the array is only
+ * checked against `LoadMixEntry<any>` (TypeScript can't infer a distinct `Input`
+ * per array element), so wrap each entry with `loadMixEntry()` for per-entry
+ * type checking of heterogeneous typed scenarios.
+ *
+ * @example
+ * ```ts
+ * scenarios: [
+ *   loadMixEntry({ id: "checkout", scenario: checkout, weight: 70, input: () => ({ sku: "s" }) }),
+ *   loadMixEntry({ id: "refund", scenario: refund, weight: 30, input: () => ({ orderId: "o" }) }),
+ * ]
+ * ```
+ */
+export function loadMixEntry(entry) {
+    return entry;
+}
+//# sourceMappingURL=runner.js.map

package/dist/load/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/load/runner.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAmKlD,kFAAkF;AAClF,SAAS,aAAa,CACpB,QAAgB,EAChB,GAA4B,EAC5B,KAAa;IAEb,6EAA6E;IAC7E,0EAA0E;IAC1E,sEAAsE;IACtE,OAAO,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;QAC1D,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9E,OAAO,KAAK,CAAC,CAAC,kEAAkE;IAClF,CAAC,CAAC,CAAC;AACL,CAAC;AAwBD;;;;GAIG;AACH,SAAS,YAAY,CACnB,EAAU,EACV,MAA2B,EAC3B,GAA6B;IAE7B,MAAM,IAAI,GAAG;QACX,cAAc,EAAE,aAAsB;QACtC,EAAE;QACF,MAAM;QACN,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE;QACxC,GAAG,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC;QAChC,UAAU,EAAE,IAAI;KACjB,CAAC,CAAC;IACH,OAAO,IAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,cAAc,GAAG,CAAC,EAAU,EAAE,MAA2B,EAAY,EAAE,CAC3E,YAAY,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAE3B,cAAc,CAAC,IAAI,GAAG,CAAsB,KAAsB,EAAE,EAAE;IACpE,OAAO,CACL,UAAkB,EAClB,OAGwD,EAC5C,EAAE,CACd,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACvB,MAAM,SAAS,GAAG,GAA8B,CAAC;QACjD,OAAO,YAAY,CACjB,aAAa,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,EAC3C,OAAO,CAAC,GAAG,EAAE,KAAK,CAAwB,EAC1C,SAAS,CACV,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,cAA8B,CAAC;AAEzD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAgC;IAEhC,OAAO,KAAgC,CAAC;AAC1C,CAAC"}

package/dist/load/scenario.d.ts

@@ -0,0 +1,130 @@
+/**
+ * loadScenario definition shape + branch/poll runtime data.
+ *
+ * These mirror the test() step / branch / poll runtime structures, but bind to
+ * `LoadContext` and carry a load-specific per-step assertion policy. The load
+ * orchestrator (later milestones) executes these. They are intentionally
+ * independent of `Test` / `TestEvent` structures so load's bounded-aggregation
+ * model never inherits ordinary test timeline semantics.
+ */
+import type { StepJsonScalar, StepMeta, StepNoExtraKeys } from "../types.js";
+import type { LoadContext } from "./context.js";
+import type { LoadAssertionFailureMode, LoadStepOptions } from "./step.js";
+/** Step metadata for a load scenario step: StepMeta plus a load assertion policy. */
+export interface LoadStepMeta extends StepMeta {
+    assertions?: {
+        onFailure?: LoadAssertionFailureMode;
+    };
+}
+/**
+ * A scenario step's runtime structure. A normal step has a callable `fn`; a
+ * branch step (condition/switch) additionally carries `branch`, and a poll step
+ * carries `poll` — for both, `fn` is a throwing stub and the orchestrator
+ * dispatches on the extra field.
+ */
+export interface LoadStepDefinition<Input = unknown, S = unknown> {
+    meta: LoadStepMeta;
+    fn: (ctx: LoadContext<Input>, state: S) => Promise<S | void>;
+    branch?: LoadBranchData<Input, S>;
+    poll?: LoadPollData<Input, S>;
+}
+/** Runtime branch data (condition / switchOn / switchCond) bound to LoadContext. */
+export interface LoadBranchData<Input = unknown, S = unknown> {
+    mode: "predicate" | "value";
+    message?: string;
+    /** value-mode only: subject lens evaluated once against committed state. */
+    subject?: (ctx: LoadContext<Input>, state: S) => unknown;
+    cases: Array<{
+        predicate?: (ctx: LoadContext<Input>, state: S) => boolean | Promise<boolean>;
+        value?: StepJsonScalar;
+        message?: string;
+        steps: LoadStepDefinition<Input, S>[];
+    }>;
+    default: LoadStepDefinition<Input, S>[];
+}
+/** Runtime poll data (bounded poll-until) bound to LoadContext. */
+export interface LoadPollData<Input = unknown, S = unknown> {
+    fn: (ctx: LoadContext<Input>, state: S) => Promise<unknown>;
+    until: (ctx: LoadContext<Input>, res: unknown, state: S) => boolean | Promise<boolean>;
+    out?: (state: S, res: unknown) => unknown;
+    every?: number;
+    backoff?: number;
+    timeout?: number;
+    perAttemptTimeout?: number;
+    maxAttempts?: number;
+}
+/** Narrow a LoadStepDefinition to a branch step. */
+export declare function isLoadBranchStep<Input, S>(step: LoadStepDefinition<Input, S>): step is LoadStepDefinition<Input, S> & {
+    branch: LoadBranchData<Input, S>;
+};
+/** Narrow a LoadStepDefinition to a poll step. */
+export declare function isLoadPollStep<Input, S>(step: LoadStepDefinition<Input, S>): step is LoadStepDefinition<Input, S> & {
+    poll: LoadPollData<Input, S>;
+};
+/** `loadScenario().condition` spec — arbitrary runtime predicate. */
+export interface LoadConditionSpec<Input = unknown, S = unknown> {
+    predicate: (ctx: LoadContext<Input>, state: S) => boolean | Promise<boolean>;
+    message?: string;
+}
+/** `loadScenario().poll` options. `Res` is inferred from the attempt `fn`'s return. */
+export interface LoadPollOpts<Input, S, Res, NewS> {
+    until: (ctx: LoadContext<Input>, res: Res, state: S) => boolean | Promise<boolean>;
+    every?: number;
+    backoff?: number;
+    timeout?: number;
+    perAttemptTimeout?: number;
+    maxAttempts?: number;
+    out?: (state: S, res: Res) => NewS;
+}
+/** Module-private phantom brand making LoadFragmentBuilder invariant in State. */
+declare const LOAD_FRAGMENT_STATE: unique symbol;
+/**
+ * Restricted builder for a `loadScenario()` branch body (condition then/else,
+ * switch case/default). Exposes step / use / condition / switchOn / switchCond /
+ * poll and accumulates them into the branch node; it deliberately does NOT
+ * expose setup / teardown / meta / build. Invariant in `State` via the phantom
+ * brand (same convergence guarantee as TestFragmentBuilder).
+ */
+export interface LoadFragmentBuilder<Input = unknown, S = unknown> {
+    readonly [LOAD_FRAGMENT_STATE]: (s: S) => S;
+    step(name: string, fn: (ctx: LoadContext<Input>, state: S) => Promise<void>): LoadFragmentBuilder<Input, S>;
+    step<NewS>(name: string, fn: (ctx: LoadContext<Input>, state: S) => Promise<NewS>): LoadFragmentBuilder<Input, NewS>;
+    step(name: string, options: LoadStepOptions, fn: (ctx: LoadContext<Input>, state: S) => Promise<void>): LoadFragmentBuilder<Input, S>;
+    step<NewS>(name: string, options: LoadStepOptions, fn: (ctx: LoadContext<Input>, state: S) => Promise<NewS>): LoadFragmentBuilder<Input, NewS>;
+    use<NewS>(fn: (b: LoadFragmentBuilder<Input, S>) => LoadFragmentBuilder<Input, NewS>): LoadFragmentBuilder<Input, NewS>;
+    condition<R extends S = S>(spec: LoadConditionSpec<Input, S>, thenBranch: (b: LoadFragmentBuilder<Input, S>) => LoadFragmentBuilder<Input, R & StepNoExtraKeys<R, S>>): LoadFragmentBuilder<Input, S>;
+    condition<T>(spec: LoadConditionSpec<Input, S>, thenBranch: (b: LoadFragmentBuilder<Input, S>) => LoadFragmentBuilder<Input, T>, elseBranch: (b: LoadFragmentBuilder<Input, S>) => LoadFragmentBuilder<Input, NoInfer<T>>): LoadFragmentBuilder<Input, T>;
+    switchOn<V>(lens: (ctx: LoadContext<Input>, state: S) => V): <T>(cases: ReadonlyArray<{
+        value: [Exclude<Awaited<V>, undefined>] extends [StepJsonScalar] ? Exclude<Awaited<V>, undefined> : never;
+        then: (b: LoadFragmentBuilder<Input, S>) => LoadFragmentBuilder<Input, NoInfer<T>>;
+    }>, deflt: (b: LoadFragmentBuilder<Input, S>) => LoadFragmentBuilder<Input, T>) => LoadFragmentBuilder<Input, T>;
+    switchCond<T>(cases: ReadonlyArray<{
+        when: (ctx: LoadContext<Input>, state: S) => boolean | Promise<boolean>;
+        then: (b: LoadFragmentBuilder<Input, S>) => LoadFragmentBuilder<Input, NoInfer<T>>;
+    }>, deflt: (b: LoadFragmentBuilder<Input, S>) => LoadFragmentBuilder<Input, T>): LoadFragmentBuilder<Input, T>;
+    poll<Res, NewS = S>(name: string, fn: (ctx: LoadContext<Input>, state: S) => Promise<Res>, opts: LoadPollOpts<Input, S, Res, NewS>): LoadFragmentBuilder<Input, NewS>;
+}
+/** Scenario-level metadata. */
+export interface LoadScenarioMeta {
+    id: string;
+    description?: string;
+    /** Scenario-level default for guard/assertion failures. */
+    assertions?: {
+        onFailure?: LoadAssertionFailureMode;
+    };
+}
+/**
+ * A complete loadScenario definition (output of `LoadBuilder.build()`).
+ *
+ * This is the performance-transaction workload that a `loadRunner()` executes.
+ * It is NOT independently runnable — only `loadRunner()` exports are scheduled.
+ */
+export interface LoadScenario<Input = unknown, S = unknown> {
+    readonly __glubean_type: "load-scenario";
+    meta: LoadScenarioMeta;
+    setup?: (ctx: LoadContext<Input>) => Promise<unknown>;
+    steps: LoadStepDefinition<Input, unknown>[];
+    teardown?: (ctx: LoadContext<Input>, state: S) => Promise<void>;
+}
+export {};
+//# sourceMappingURL=scenario.d.ts.map

package/dist/load/scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../../src/load/scenario.ts"],"names":[],"mappings":"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"}

package/dist/load/scenario.js

@@ -0,0 +1,9 @@
+/** Narrow a LoadStepDefinition to a branch step. */
+export function isLoadBranchStep(step) {
+    return step.branch !== undefined;
+}
+/** Narrow a LoadStepDefinition to a poll step. */
+export function isLoadPollStep(step) {
+    return step.poll !== undefined;
+}
+//# sourceMappingURL=scenario.js.map

package/dist/load/scenario.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.js","sourceRoot":"","sources":["../../src/load/scenario.ts"],"names":[],"mappings":"AA4DA,oDAAoD;AACpD,MAAM,UAAU,gBAAgB,CAC9B,IAAkC;IAElC,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;AACnC,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,cAAc,CAC5B,IAAkC;IAElC,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC;AACjC,CAAC"}

package/dist/load/step.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Load scenario step authoring types.
+ *
+ * These mirror the `test().builder()` step model (return-state threading:
+ * a step returns the next state, or `void`/`undefined` to keep the current
+ * state) but bind to `LoadContext` and add a load-specific assertion policy.
+ */
+import type { StepMeta } from "../types.js";
+import type { LoadContext } from "./context.js";
+/**
+ * What happens when a guard/assertion fails inside a load step.
+ *
+ * Resolution order (most specific wins):
+ *   per-assertion `.orFail()` / thrown error
+ *     > step-level `assertions.onFailure`
+ *     > scenario-level `assertions.onFailure`
+ *     > loadRunner `assertions.onFailure`
+ *     > default `"continue"`
+ */
+export type LoadAssertionFailureMode = 
+/** Default: record + count the failure, keep running the scenario. */
+"continue"
+/** Current step completes; remaining steps are skipped. */
+ | "skipRemainingSteps"
+/** Fail-fast the current iteration. */
+ | "abortIteration";
+/** Per-step options for `loadScenario` steps (`StepMeta` minus `name`, plus load policy). */
+export type LoadStepOptions = Omit<StepMeta, "name"> & {
+    assertions?: {
+        onFailure?: LoadAssertionFailureMode;
+    };
+};
+/** A scenario `setup` producing the initial state from the context. */
+export type LoadSetupFunction<Input, NewState> = (ctx: LoadContext<Input>) => Promise<NewState>;
+/**
+ * A scenario step. Returns the next state, or `void`/`undefined` to keep the
+ * current state (matching `test().builder()` semantics).
+ */
+export type LoadStepFunction<Input, State, NewState = State> = (ctx: LoadContext<Input>, state: State) => Promise<NewState | void>;
+/** A scenario `teardown`, always run with the last committed state. */
+export type LoadTeardownFunction<Input, State> = (ctx: LoadContext<Input>, state: State) => Promise<void>;
+//# sourceMappingURL=step.d.ts.map

package/dist/load/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/load/step.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,MAAM,wBAAwB;AAClC,sEAAsE;AACpE,UAAU;AACZ,2DAA2D;GACzD,oBAAoB;AACtB,uCAAuC;GACrC,gBAAgB,CAAC;AAErB,6FAA6F;AAC7F,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG;IACrD,UAAU,CAAC,EAAE;QACX,SAAS,CAAC,EAAE,wBAAwB,CAAC;KACtC,CAAC;CACH,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,CAAC,KAAK,EAAE,QAAQ,IAAI,CAC/C,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,KACpB,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,IAAI,CAC7D,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,EACvB,KAAK,EAAE,KAAK,KACT,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;AAE9B,uEAAuE;AACvE,MAAM,MAAM,oBAAoB,CAAC,KAAK,EAAE,KAAK,IAAI,CAC/C,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,EACvB,KAAK,EAAE,KAAK,KACT,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/load/step.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=step.js.map

package/dist/load/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/load/step.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -1332,6 +1332,16 @@ export interface HttpRequestOptions {
      * ```
      */
     schema?: HttpSchemaOptions;
+    /**
+     * Per-request context — a non-wire object shared across this request's hooks (never
+     * sent to the server). The runtime reads `context.glubeanRoute` (an exact route
+     * template like `"GET /runs/:runId"`) to attribute the load runner's endpoint stats
+     * exactly instead of heuristically normalizing the URL; a `contract.http()` client
+     * sets it automatically. A custom `HttpClient` may ignore this option.
+     */
+    context?: {
+        glubeanRoute?: string;
+    } & Record<string, unknown>;
 }
 /**
  * Hooks for intercepting HTTP request/response lifecycle.
@@ -1713,6 +1723,12 @@ export interface Trace {
     name?: string;
     /** Optional detailed description */
     description?: string;
+    /** Optional EXACT route template, e.g. "GET /runs/:runId". Carried via the request's
+     *  non-wire `context.glubeanRoute` option (set by a `contract.http()` client from its
+     *  `endpoint`, or by a caller) — NEVER a request header, so it can't leak to the server.
+     *  The load runner uses it for an exact endpoint routeKey instead of the heuristic
+     *  URL-normalization fallback. Absent → fall back. */
+    routeKey?: string;
     /** @deprecated Use `target` and `metadata` instead. HTTP method. */
     method?: string;
     /** @deprecated Use `target` and `metadata` instead. Request URL. */