@glubean/runner 0.7.0 → 0.8.1

package/dist/load/continuation-pool.js

@@ -0,0 +1,154 @@
+/**
+ * Bounded continuation backlog for producer release (M6).
+ *
+ * When a load iteration calls `ctx.report.primaryComplete(..., { releaseProducerSlot:
+ * true })`, its producer slot is freed to start a NEW primary iteration while the
+ * rest of that iteration (the continuation — typically a poll-for-result loop) runs
+ * in the background. This pool bounds how many continuations may be in flight at
+ * once (`maxOutstanding`): when full, the producer is either back-pressured
+ * (`block-producer` — `admit()` waits for a free slot, so the primary ingress rate
+ * self-throttles to the continuation drain rate) or the iteration fails
+ * (`fail-iteration` — `admit()` throws). An unset `maxOutstanding` is unbounded
+ * (release frees the slot with no backlog cap).
+ *
+ * A parked `admit()` is bounded by `drainTimeoutMs` (from when it parks), if set, so
+ * a backlog that never frees (a hung continuation) can't hang the run — even before
+ * its bound is reached, when EVERY slot is parked and none can advance. The run's
+ * wall-clock (duration) deadline additionally `closeImmediate()`s the pool, cancelling
+ * parked producers at once.
+ *
+ * Single-process / single-threaded: all bookkeeping is synchronous between awaits,
+ * so the counters never race. `maxConcurrent` is recorded in the config but
+ * coincides with `maxOutstanding` here (every in-flight continuation is an actively
+ * scheduled async flow), so this pool enforces the one bound.
+ */
+/** Thrown by `admit()` under `fail-iteration` when the backlog is full. */
+export class ContinuationBacklogFullError extends Error {
+    constructor() {
+        super("continuation backlog is full");
+        this.name = "ContinuationBacklogFullError";
+    }
+}
+/** Thrown by a parked `admit()` when its drain bound expires or the run's wall-clock
+ *  deadline closes the pool. Carries how long the producer was stalled and why. */
+export class AdmissionCancelledError extends Error {
+    waitMs;
+    reason;
+    constructor(waitMs, reason) {
+        super(`continuation admission cancelled (${reason})`);
+        this.waitMs = waitMs;
+        this.reason = reason;
+        this.name = "AdmissionCancelledError";
+    }
+}
+export class ContinuationPool {
+    maxOutstanding;
+    onBacklogFull;
+    drainTimeoutMs;
+    now;
+    inFlight = 0;
+    peak = 0;
+    closed = false; // the run's wall-clock deadline — reject new parks at once
+    waiters = [];
+    constructor(maxOutstanding, onBacklogFull, drainTimeoutMs, now) {
+        this.maxOutstanding = maxOutstanding;
+        this.onBacklogFull = onBacklogFull;
+        this.drainTimeoutMs = drainTimeoutMs;
+        this.now = now;
+    }
+    /** Continuations currently in flight (admitted, not yet released). */
+    get outstanding() {
+        return this.inFlight;
+    }
+    /** Highest concurrent in-flight count reached (for the backlog report). */
+    get peakOutstanding() {
+        return this.peak;
+    }
+    /** Whether the backlog is at capacity right now (the next admit would block/fail). */
+    get atCapacity() {
+        return this.maxOutstanding !== undefined && this.inFlight >= this.maxOutstanding;
+    }
+    /**
+     * Reserve a continuation slot. Returns the back-pressure wait in ms (0 if a slot
+     * was immediately free). Throws `ContinuationBacklogFullError` under
+     * `fail-iteration` when full, or `AdmissionCancelledError` when a parked wait is
+     * cut short by its drain bound or the run's wall-clock deadline.
+     */
+    async admit() {
+        // The run's wall-clock deadline closes the pool and takes precedence over EVERYTHING
+        // below — capacity AND backlog policy. Once it fires, every later release is
+        // released-for-drain (runDeadlineReached): admitting a fresh continuation as a normal
+        // `producer:released` (free capacity) would misaccount post-deadline work, and
+        // failing it (fail-iteration) would spuriously fail a primary the run simply outran.
+        // The tail still drains either way; this is purely correct deadline accounting.
+        if (this.closed) {
+            throw new AdmissionCancelledError(0, "runDeadlineReached"); // wall-clock up: never admit anew
+        }
+        if (!this.atCapacity) {
+            this.acquire();
+            return 0;
+        }
+        if (this.onBacklogFull === "fail-iteration") {
+            throw new ContinuationBacklogFullError();
+        }
+        // block-producer: park until a releasing continuation hands its slot over, the
+        // drain timeout expires, or the run's wall-clock deadline closes the pool.
+        const start = this.now();
+        const waiter = { resolve: () => { } };
+        const granted = await new Promise((resolve) => {
+            waiter.resolve = resolve;
+            this.waiters.push(waiter);
+            if (this.drainTimeoutMs !== undefined) {
+                waiter.timer = setTimeout(() => this.cancel(waiter, "drainTimeout"), this.drainTimeoutMs);
+            }
+        });
+        const waited = Math.max(0, this.now() - start);
+        if (!granted)
+            throw new AdmissionCancelledError(waited, waiter.reason ?? "runDeadlineReached");
+        return waited;
+    }
+    /**
+     * Free a continuation slot. If a producer is parked, hand the slot DIRECTLY to it
+     * (in-flight count unchanged — capacity transfers) so no third producer can slip
+     * in between; otherwise decrement.
+     */
+    release() {
+        const next = this.waiters.shift();
+        if (next) {
+            if (next.timer !== undefined)
+                clearTimeout(next.timer);
+            next.resolve(true); // grant the slot
+            return;
+        }
+        this.inFlight = Math.max(0, this.inFlight - 1);
+    }
+    /**
+     * The run's wall-clock (duration) deadline: cancel every parked producer at once
+     * and reject any later park immediately, so a slot blocked on a release can't
+     * outrun the bound (its tail still drains, bounded by the run's drain phase).
+     */
+    closeImmediate() {
+        this.closed = true;
+        for (const w of [...this.waiters])
+            this.cancel(w, "runDeadlineReached");
+    }
+    /** Remove a parked producer and cancel its wait, recording WHY (its per-park drain
+     *  bound expired, or the run's wall-clock deadline closed the pool) so `admit()`
+     *  can throw the right cause. */
+    cancel(waiter, reason) {
+        const i = this.waiters.indexOf(waiter);
+        if (i < 0)
+            return; // already granted / cancelled
+        this.waiters.splice(i, 1);
+        if (waiter.timer !== undefined)
+            clearTimeout(waiter.timer);
+        waiter.reason = reason;
+        waiter.resolve(false);
+    }
+    acquire() {
+        this.inFlight += 1;
+        if (this.inFlight > this.peak)
+            this.peak = this.inFlight;
+    }
+}
+//# sourceMappingURL=continuation-pool.js.map

package/dist/load/continuation-pool.js.map

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

package/dist/load/execute-iteration.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Single load-iteration executor — runs ONE scenario iteration through the shared
+ * engine `RunnerCore`, reusing the exact test() execution surface (ctx.http /
+ * session / vars / steps / branch / poll / setup / teardown) via the engine's
+ * generic `ctxExtensions` seam.
+ *
+ * A `LoadScenario` is compiled ONCE (`compileLoadScenario`) into engine steps:
+ * `LoadStepDefinition` mirrors the SDK's step/branch/poll runtime shape, which the
+ * engine detects structurally — so the conversion is a re-label, not a re-built
+ * run-loop. Compilation also resolves each step's `LoadAssertionFailureMode` into
+ * the engine's neutral `continueOnAssertionFailure` hint (the load `continue`
+ * default keeps a transaction running after a soft assertion failure) and carries
+ * `meta.group` through for report attribution. Load-only ctx members (`input` /
+ * `producerSlot` / `iteration` / `now` / `report`) ride in on `ctxExtensions`.
+ *
+ * The executor owns the iteration lifecycle: it brackets the run with
+ * `iteration:start` / `iteration:end` on the sink and threads a per-iteration
+ * `report` whose checkpoints emit through the same sink. Concurrency, pacing,
+ * feeder allocation, and the producer-release boundary live in the orchestrator
+ * (M3-f) and the phase split (M5/M6) — this function runs exactly one iteration.
+ */
+import type { RunnerCore, StepDef, TestDef, TestFn, TestResult } from "@glubean/engine";
+import type { LoadAssertionFailureMode, LoadErrorKind, LoadIteration, LoadProducerSlot, LoadScenario } from "@glubean/sdk/load";
+import { type ContinuationPool } from "./continuation-pool.js";
+import type { LoadIterationEnvelope, LoadSink } from "./sink.js";
+/** Phantom-typed Input so a compiled scenario stays coupled to its input type. */
+declare const COMPILED_INPUT: unique symbol;
+/**
+ * A `LoadScenario` lowered to engine-ready steps, computed once and reused across
+ * every iteration of the run (only the per-iteration `meta.id` differs). The
+ * `steps` already carry the resolved `continueOnAssertionFailure` hint + group.
+ */
+export interface CompiledLoadScenario<Input = unknown> {
+    /** @internal phantom — preserves the Input type through compilation. */
+    readonly [COMPILED_INPUT]?: (input: Input) => void;
+    scenarioId: string;
+    name: string;
+    setup?: TestFn;
+    steps: StepDef[];
+    teardown?: TestFn;
+}
+/** Options for resolving a scenario's assertion-failure policy chain. */
+export interface CompileLoadScenarioOptions {
+    /**
+     * The `loadRunner`-level default `onFailure` (the lowest-precedence rung of the
+     * resolution chain). Omitted → the documented default `"continue"`.
+     */
+    defaultOnFailure?: LoadAssertionFailureMode;
+}
+/** Compile a `LoadScenario` to reusable engine steps (do this ONCE per scenario). */
+export declare function compileLoadScenario<Input>(scenario: LoadScenario<Input, any>, opts?: CompileLoadScenarioOptions): CompiledLoadScenario<Input>;
+/** Re-label a compiled scenario as an engine `TestDef` for one iteration run. */
+export declare function loadScenarioToTestDef(compiled: CompiledLoadScenario<any>, iterationId: string): TestDef;
+/** Inputs for one iteration run. */
+export interface RunLoadIterationArgs<Input = unknown> {
+    core: RunnerCore;
+    sink: LoadSink;
+    /** The compiled scenario (compile once with `compileLoadScenario`, reuse). */
+    scenario: CompiledLoadScenario<Input>;
+    envelope: LoadIterationEnvelope;
+    /** Per-iteration input produced by `loadRunner().input` (becomes `ctx.input`). */
+    input: Input;
+    producerSlot: LoadProducerSlot;
+    iteration: LoadIteration;
+    /** Per-iteration session overlay (copy-on-write isolation lands in M3-f). */
+    session?: Record<string, unknown>;
+    /** Attribution for `iteration:start` (feeder allocation lands in M3-f). */
+    inputKey?: string;
+    feederKeys?: Record<string, string>;
+    /** Monotonic clock for the iteration duration; defaults to `performance.now`. */
+    now?: () => number;
+    /** Producer-release wiring (M6). When present, `ctx.report.primaryComplete(...,
+     *  { releaseProducerSlot: true })` reserves a continuation slot from this pool
+     *  (back-pressure / fail-iteration) and frees the producer slot at the boundary;
+     *  absent → the M5 closed model (release is a no-op phase split). */
+    continuation?: {
+        pool: ContinuationPool;
+    };
+    /** Run-level abort signal. Threaded to the engine so the run can truly cancel this
+     *  iteration's in-flight HTTP / poll tail — the orchestrator fires it at finalization
+     *  to kill continuation tails the drain phase abandons (instead of leaving them to run
+     *  to completion in the background). */
+    signal?: AbortSignal;
+}
+/**
+ * Handle to a started iteration whose producer slot may be released mid-run (M6).
+ * `primaryDone` lets the orchestrator free the slot at the right moment;
+ * `completed` is the whole iteration (continuation included) for drain + counting.
+ */
+export interface LoadIterationHandle {
+    /** Resolves when the PRODUCER SLOT is free to start the next primary: at the
+     *  release boundary (`released: true`) or, with no release, at full completion. */
+    primaryDone: Promise<{
+        released: boolean;
+    }>;
+    /** Resolves when the whole iteration (incl. any continuation) settles. */
+    completed: Promise<RunLoadIterationResult>;
+}
+/** Outcome of one iteration run (the engine `TestResult` plus the load verdict). */
+export interface RunLoadIterationResult {
+    ok: boolean;
+    durationMs: number;
+    errorKind?: LoadErrorKind;
+    /** The scenario called `ctx.skip()` — the iteration opted out (not a failure).
+     *  Distinct skip accounting in the artifact is future work; for now a skipped
+     *  iteration is reported `ok` so it never pollutes failure/assertion stats. */
+    skipped?: boolean;
+    /** The engine result, or null if the core itself threw (infra error). */
+    result: TestResult | null;
+}
+/**
+ * Start one scenario iteration through the engine core, bracketing it with
+ * `iteration:start` / `iteration:end`. Returns a handle: `primaryDone` resolves
+ * when the producer slot is free (release boundary, or full completion when no
+ * release), and `completed` resolves when the whole iteration settles. Never
+ * rejects: an infra-level throw from the core is recorded as a failed iteration.
+ */
+export declare function startLoadIteration<Input>(args: RunLoadIterationArgs<Input>): LoadIterationHandle;
+/**
+ * Run one scenario iteration to completion (closed model). The M5/M3 entry: it
+ * awaits the WHOLE iteration. The orchestrator uses `startLoadIteration` directly
+ * for M6 producer-release scheduling.
+ */
+export declare function runLoadIteration<Input>(args: RunLoadIterationArgs<Input>): Promise<RunLoadIterationResult>;
+export {};
+//# sourceMappingURL=execute-iteration.d.ts.map

package/dist/load/execute-iteration.d.ts.map

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

package/dist/load/execute-iteration.js

@@ -0,0 +1,367 @@
+import { isLoadBranchStep } from "@glubean/sdk/load";
+import { AdmissionCancelledError, ContinuationBacklogFullError } from "./continuation-pool.js";
+/**
+ * Resolve a step's effective `onFailure` (most specific wins):
+ *   step `assertions.onFailure` > scenario `assertions.onFailure`
+ *     > loadRunner default > `"continue"`.
+ */
+function resolveOnFailure(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+step, scenarioMode, runnerDefault) {
+    return (step.meta.assertions?.onFailure ?? scenarioMode ?? runnerDefault ?? "continue");
+}
+/** Lower one load step (recursing into branch sub-steps) to an engine StepDef.
+ *  `inheritedGroup` is the group of an enclosing `.group()`-wrapped branch — only
+ *  branch LEAVES emit `step_start`, so the branch node's group must flow down. */
+function compileStep(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+step, scenarioMode, runnerDefault, inheritedGroup) {
+    const onFailure = resolveOnFailure(step, scenarioMode, runnerDefault);
+    // A step's own group wins; otherwise it inherits the enclosing branch's group.
+    const effectiveGroup = step.meta.group ?? inheritedGroup;
+    // Preserve the WHOLE step meta (name / group / timeout / retries / retryDelay /
+    // backoff — all read by the engine) and only ADD the resolved policy hint + the
+    // effective group. Only `continue` keeps the transaction running after a soft
+    // assertion failure; `skipRemainingSteps` / `abortIteration` both halt (the
+    // engine treats them the same — the iteration is marked failed and the rest
+    // skipped either way). The load-only `assertions` field rides along inertly; the
+    // engine never reads it.
+    const meta = {
+        ...step.meta,
+        ...(effectiveGroup !== undefined ? { group: effectiveGroup } : {}),
+        continueOnAssertionFailure: onFailure === "continue",
+    };
+    // Branch/poll are detected structurally by the engine via these fields; carry
+    // them through, recursing so nested case/default steps inherit the policy chain
+    // AND the enclosing group.
+    if (isLoadBranchStep(step)) {
+        const branch = step.branch;
+        return {
+            meta,
+            fn: step.fn,
+            branch: {
+                ...branch,
+                cases: branch.cases.map((c) => ({
+                    ...c,
+                    steps: c.steps.map((s) => compileStep(s, scenarioMode, runnerDefault, effectiveGroup)),
+                })),
+                default: branch.default.map((s) => compileStep(s, scenarioMode, runnerDefault, effectiveGroup)),
+            },
+        };
+    }
+    // Normal or poll step (poll carries its own `.poll` data the engine reads).
+    return { meta, fn: step.fn, ...("poll" in step ? { poll: step.poll } : {}) };
+}
+/** Compile a `LoadScenario` to reusable engine steps (do this ONCE per scenario). */
+export function compileLoadScenario(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+scenario, opts = {}) {
+    const scenarioMode = scenario.meta.assertions?.onFailure;
+    return {
+        scenarioId: scenario.meta.id,
+        name: scenario.meta.id,
+        setup: scenario.setup,
+        steps: scenario.steps.map((s) => compileStep(s, scenarioMode, opts.defaultOnFailure)),
+        teardown: scenario.teardown,
+    };
+}
+/** Re-label a compiled scenario as an engine `TestDef` for one iteration run. */
+export function loadScenarioToTestDef(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+compiled, iterationId) {
+    return {
+        meta: { id: iterationId, name: compiled.name },
+        type: "steps",
+        setup: compiled.setup,
+        steps: compiled.steps,
+        teardown: compiled.teardown,
+    };
+}
+/**
+ * Map an engine `TestResult` to a load `errorKind`.
+ *
+ * A load scenario is always lowered to a STEPS `TestDef`, and the engine catches
+ * step/poll/teardown throws — so a top-level throw (`result.threw`) means the
+ * scenario `setup` failed: classify it as `setupError`. For caught step/poll
+ * failures the engine surfaces the error NAME in `stepErrorName`, so a request
+ * timeout (`TimeoutError`), step timeout (`StepTimeoutError`), or HTTP error
+ * (`HTTPError`) still classifies correctly; a soft assertion failure leaves no
+ * thrown error and the generic "assertion failed" text.
+ *
+ * NOTE: with the engine's default `throwHttpErrors: false` a non-2xx response does
+ * NOT throw — it surfaces as the endpoint's `ok:false` / status in
+ * `request:observed` (endpoint error rate), not as an iteration `errorKind`; only
+ * an explicit HTTP throw yields `"http"` here.
+ */
+function classifyIterationError(result, runAborted) {
+    // A run-level abort (the orchestrator's `signal`) — distinct from a user failure. Only
+    // when the orchestrator actually aborted THIS iteration: the engine surfaces it as a
+    // top-level "AbortError" throw (a simple/setup body awaiting an aborted request), a
+    // caught step/poll "AbortError", or the post-loop "run aborted" verdict (an opaque,
+    // non-cancellable await that outran the abort). A scenario that aborts its OWN request
+    // raises the same AbortError, so gate on `runAborted` — else an ordinary user
+    // cancellation would be mislabelled and real setup/step errors under-reported.
+    if (runAborted && (result.errorName === "AbortError" || result.stepErrorName === "AbortError" || result.error === "run aborted")) {
+        return "aborted";
+    }
+    if (result.threw)
+        return "setupError";
+    const name = result.stepErrorName;
+    const msg = result.error ?? "";
+    if (name === "TimeoutError" || name === "StepTimeoutError" || /timed out/i.test(msg))
+        return "timeout";
+    if (name === "HTTPError")
+        return "http";
+    // A backlog-full release rejection (fail-iteration policy) failed the iteration.
+    if (name === "ContinuationBacklogFullError")
+        return "continuationBacklogFull";
+    if (name !== undefined)
+        return "stepError";
+    if (msg === "" || msg === "assertion failed")
+        return "assertion";
+    return "stepError";
+}
+/**
+ * A per-iteration `report` whose signals emit through the sink with attribution.
+ *
+ * `primaryComplete` records the measurement boundary (M5): the FIRST call stamps
+ * `primaryDurationMs` (iteration start → now), emits `producer:primaryCompleted`,
+ * and flips the sink into this iteration's continuation phase; later calls are
+ * duplicates. With `releaseProducerSlot: true` AND a `release` coordinator (M6) it
+ * also frees the producer slot via the continuation pool (back-pressure /
+ * fail-iteration); without a coordinator release is a no-op phase split.
+ */
+function makeIterationReport(sink, env, start, now, release, rejectDuplicateRelease) {
+    let primaryCompleted = false;
+    return {
+        checkpoint(id, data) {
+            sink.emitCheckpoint(env, id, data);
+        },
+        async primaryComplete(id, data) {
+            if (primaryCompleted) {
+                // A second boundary in the same iteration is ignored (one boundary per
+                // logical iteration); report it as a duplicate for diagnostics. A duplicate
+                // that re-requested release is recorded as a rejected duplicate signal.
+                if (data?.releaseProducerSlot === true)
+                    rejectDuplicateRelease?.(id);
+                return { measuredPrimaryComplete: false, releasedProducerSlot: false, duplicate: true, backpressureMs: 0 };
+            }
+            primaryCompleted = true;
+            // `releaseProducerSlot` only requests a release when a coordinator is wired (M6).
+            // Without one (the M5-only phase split), it's a documented no-op — so report
+            // releaseRequested:false, else the reducer would treat this boundary as a producer
+            // parked on backlog and surface spurious blockedOnBacklog / a continuation summary.
+            const releaseRequested = data?.releaseProducerSlot === true && release !== undefined;
+            const primaryDurationMs = Math.max(0, now() - start);
+            sink.emitPrimaryCompleted(env, { primaryId: id, primaryDurationMs, releaseRequested });
+            if (releaseRequested && release) {
+                // Release the producer slot (may back-pressure, or throw under
+                // fail-iteration → the iteration fails). Returns the full receipt.
+                return release({ primaryId: id, primaryDurationMs });
+            }
+            return { measuredPrimaryComplete: true, releasedProducerSlot: false, duplicate: false, backpressureMs: 0 };
+        },
+    };
+}
+/**
+ * Start one scenario iteration through the engine core, bracketing it with
+ * `iteration:start` / `iteration:end`. Returns a handle: `primaryDone` resolves
+ * when the producer slot is free (release boundary, or full completion when no
+ * release), and `completed` resolves when the whole iteration settles. Never
+ * rejects: an infra-level throw from the core is recorded as a failed iteration.
+ */
+export function startLoadIteration(args) {
+    const { core, sink, scenario, envelope, input, producerSlot, iteration, session } = args;
+    const pool = args.continuation?.pool;
+    const now = args.now ?? (() => performance.now());
+    sink.beginIteration(envelope);
+    sink.emitIterationStart(envelope, {
+        ...(args.inputKey !== undefined ? { inputKey: args.inputKey } : {}),
+        ...(args.feederKeys !== undefined ? { feederKeys: args.feederKeys } : {}),
+    });
+    // Stamp the iteration start BEFORE building the report so `primaryComplete` can
+    // measure `primaryDurationMs` from it; `start` is also the end-to-end baseline.
+    const start = now();
+    // The producer-slot lifecycle (see SlotDisposition). Starts "held"; the release
+    // coordinator moves it to "released" / "releasedForDrain" at most once. The `as`
+    // widens past the "held" literal so reads in `completed` see the full union — the
+    // coordinator's writes are in an async closure CFA can't fold back into the narrowing.
+    let slot = "held";
+    // The iteration couldn't honor the continuation backlog bound — a `fail-iteration`
+    // release hit a full backlog, or a `block-producer` release parked past its drain
+    // bound — so it MUST fail, regardless of step retries or a tail that later settles.
+    let failedBacklogBound = false;
+    // The iteration has fully ended (its `completed` finalizer ran). Guards a release
+    // still parked on back-pressure so it hands its slot back instead of leaking.
+    let iterationSettled = false;
+    let resolvePrimaryDone;
+    const primaryDone = new Promise((r) => { resolvePrimaryDone = r; });
+    // M6 release coordinator (only wired when a continuation pool is provided).
+    const release = pool
+        ? async ({ primaryId, primaryDurationMs }) => {
+            try {
+                const backpressureMs = await pool.admit(); // back-pressure, or throw under fail-iteration
+                if (iterationSettled) {
+                    // The iteration already ended (e.g. a step timeout) while this release
+                    // was parked on back-pressure. Hand the just-acquired slot straight back
+                    // and do NOT release the producer slot or emit a late producer:released —
+                    // otherwise the slot would leak at capacity and deadlock future releases.
+                    pool.release();
+                    return { measuredPrimaryComplete: true, releasedProducerSlot: false, duplicate: false, backpressureMs };
+                }
+                slot = "released";
+                sink.emitProducerReleased(envelope, {
+                    releaseId: primaryId,
+                    primaryDurationMs,
+                    continuationBacklog: pool.outstanding,
+                    backpressureMs,
+                });
+                resolvePrimaryDone({ released: true }); // free the producer slot NOW
+                return { measuredPrimaryComplete: true, releasedProducerSlot: true, duplicate: false, backpressureMs };
+            }
+            catch (e) {
+                if (e instanceof AdmissionCancelledError) {
+                    if (iterationSettled) {
+                        // The iteration already ended (e.g. a step timeout) before the cancel
+                        // hit this parked admit. It's no longer tracked — don't emit a
+                        // rejection or resolve primaryDone (already done), just return.
+                        return { measuredPrimaryComplete: true, releasedProducerSlot: false, duplicate: false, backpressureMs: e.waitMs };
+                    }
+                    // Either the run's wall-clock deadline closed the pool, or this release's
+                    // own drain bound expired (the backlog never freed). Both free the producer
+                    // for liveness and leave the continuation tail to be drained at run-end
+                    // (no pool slot acquired), but they're DIFFERENT outcomes:
+                    //  - runDeadlineReached: the run is ending; the primary was already complete
+                    //    and is released-for-drain — NOT an iteration failure.
+                    //  - drainTimeout: the backlog stayed full past the drain bound mid-run — the
+                    //    same terminal outcome as fail-iteration, so the iteration MUST fail (else
+                    //    the slot would silently run over the configured backlog bound).
+                    sink.emitProducerReleaseRejected(envelope, {
+                        releaseId: primaryId,
+                        reason: e.reason,
+                        waitMs: e.waitMs,
+                        continuationBacklog: pool.outstanding,
+                    });
+                    slot = "releasedForDrain"; // freed at the boundary, no pool slot to pair with release()
+                    if (e.reason === "drainTimeout")
+                        failedBacklogBound = true;
+                    resolvePrimaryDone({ released: true }); // free the slot + track the tail
+                    return { measuredPrimaryComplete: true, releasedProducerSlot: false, duplicate: false, backpressureMs: e.waitMs };
+                }
+                if (e instanceof ContinuationBacklogFullError) {
+                    sink.emitProducerReleaseRejected(envelope, {
+                        releaseId: primaryId,
+                        reason: "continuationBacklogFull",
+                        waitMs: 0,
+                        continuationBacklog: pool.outstanding,
+                    });
+                    // fail-iteration: the iteration MUST fail. Throw the TYPED error so a
+                    // non-retried step classifies as "continuationBacklogFull"; also latch the
+                    // flag so that if the step has `retries`, the retry's duplicate
+                    // primaryComplete (which returns success) can't let the iteration pass. The
+                    // slot stays "held" — the throw propagates and the finalizer frees it.
+                    failedBacklogBound = true;
+                }
+                throw e;
+            }
+        }
+        : undefined;
+    // Record a duplicate release request (a second primaryComplete that re-asks for
+    // release) so the continuation summary's duplicateReleaseSignals reflects it.
+    const rejectDuplicateRelease = pool
+        ? (id) => sink.emitProducerReleaseRejected(envelope, {
+            releaseId: id,
+            reason: "duplicateRelease",
+            waitMs: 0,
+            continuationBacklog: pool.outstanding,
+        })
+        : undefined;
+    const scope = {
+        ...(session !== undefined ? { session } : {}),
+        ...(args.signal !== undefined ? { signal: args.signal } : {}),
+        ctxExtensions: {
+            input,
+            producerSlot,
+            iteration,
+            now,
+            report: makeIterationReport(sink, envelope, start, now, release, rejectDuplicateRelease),
+        },
+    };
+    const completed = (async () => {
+        let result = null;
+        let ok = false;
+        let skipped = false;
+        let errorKind;
+        try {
+            result = await core.run(loadScenarioToTestDef(scenario, envelope.iterationId), scope);
+            if (result.status === "skipped") {
+                // `ctx.skip()` opted this iteration out — not a success and not a failure.
+                ok = true;
+                skipped = true;
+            }
+            else {
+                ok = result.status === "ok";
+                // Only treat an AbortError as a cancellation when the orchestrator's run signal
+                // actually aborted this iteration (a scenario aborting its own request is a real
+                // user failure, not an orchestrator cancellation).
+                errorKind = ok ? undefined : classifyIterationError(result, args.signal?.aborted === true);
+            }
+        }
+        catch {
+            // The engine resolves user errors into a TestResult; reaching here means the
+            // core itself threw (infra). Record it as a runner-crash-flavoured failure.
+            ok = false;
+            errorKind = "runnerCrash";
+        }
+        // A backlog-bound failure is terminal regardless of step retries / a tail that
+        // later settles: the iteration couldn't honor the backlog bound, so it fails. This
+        // covers both fail-iteration (full → throw immediately) and block-producer
+        // drain-timeout (parked past the drain bound → give up) — a retry's duplicate
+        // primaryComplete returns success and could otherwise let the iteration (and a
+        // re-run primary side effect) pass.
+        if (failedBacklogBound) {
+            ok = false;
+            errorKind = "continuationBacklogFull";
+        }
+        const durationMs = now() - start;
+        // Mark the iteration done BEFORE finalizing, so a release still parked on
+        // back-pressure (its step having timed out) returns its slot instead of leaking.
+        iterationSettled = true;
+        try {
+            sink.emitIterationEnd(envelope, { ok, durationMs, ...(errorKind !== undefined ? { errorKind } : {}) });
+            sink.endIteration(envelope.iterationId);
+        }
+        catch {
+            // Finalization is best-effort — a sink hiccup must neither reject this
+            // promise nor (via the finally below) hang the producer slot.
+        }
+        finally {
+            // Settle the slot per its end-state (see SlotDisposition). This MUST run so the
+            // slot loop's `await primaryDone` never hangs.
+            //  - "released":        pair the acquired pool slot with a release now the tail settled.
+            //  - "held":            no release happened — free the producer slot it held to the end.
+            //  - "releasedForDrain": primaryDone already resolved at the boundary, no pool slot held.
+            if (slot === "released")
+                pool?.release();
+            else if (slot === "held")
+                resolvePrimaryDone({ released: false });
+        }
+        return {
+            ok,
+            durationMs,
+            ...(errorKind !== undefined ? { errorKind } : {}),
+            ...(skipped ? { skipped: true } : {}),
+            result,
+        };
+    })();
+    return { primaryDone, completed };
+}
+/**
+ * Run one scenario iteration to completion (closed model). The M5/M3 entry: it
+ * awaits the WHOLE iteration. The orchestrator uses `startLoadIteration` directly
+ * for M6 producer-release scheduling.
+ */
+export async function runLoadIteration(args) {
+    return startLoadIteration(args).completed;
+}
+//# sourceMappingURL=execute-iteration.js.map