@glubean/runner 0.3.2 → 0.4.1

package/dist/harness.js

@@ -12,6 +12,7 @@ import { bootstrap } from "./bootstrap.js";
 import { loadProjectOverlays } from "@glubean/scanner";
 import { setRuntime, setExplicitInput, setBootstrapInput, setForceStandalone, } from "@glubean/sdk/internal";
 import ky from "ky";
+import { isTestBranchStep, isTestPollStep } from "@glubean/sdk";
 import { Expectation } from "@glubean/sdk/expect";
 // Global error handlers for async errors that escape try/catch
 process.on("uncaughtException", (error) => {
@@ -590,6 +591,10 @@ const ctx = {
             passed: false,
             message,
         });
+        // Also bump the step-failed-assertion counter (like ctx.assert) so the
+        // failure is recorded even if the FailError is caught — e.g. inside a branch
+        // predicate that swallows it; the step/branch must still fail.
+        incrAssertions(false);
         throw new FailError(message);
     },
     /**
@@ -1509,6 +1514,14 @@ async function executeNewTest(test) {
                 else {
                     let state = undefined;
                     let stepFailed = false;
+                    // First branch-decision failure message (predicate/lens threw or failed
+                    // an assertion). A branch decision has no `step_end`, so result
+                    // renderers that surface step/status errors would otherwise lose it;
+                    // we promote it into the final status error below.
+                    let branchDecisionError;
+                    // Set when a step calls ctx.skip(): skips the remaining steps and
+                    // marks the whole test as skipped (not failed) after teardown runs.
+                    let skipRequest;
                     try {
                         if (test.setup) {
                             emitEvent({
@@ -1518,22 +1531,267 @@ async function executeNewTest(test) {
                             state = await test.setup(effectiveCtx);
                         }
                         if (test.steps) {
-                            for (let i = 0; i < test.steps.length; i++) {
-                                const step = test.steps[i];
-                                // If a previous step failed, skip remaining steps
-                                if (stepFailed) {
+                            // Monotonic step index across the (possibly branching) execution.
+                            // For a branchless test this counts 0,1,2,… == array position, so
+                            // non-branch behavior is identical to before. Counts ONLY leaf steps
+                            // (step_start/step_end), NOT branch decisions — so these indices line
+                            // up 1:1 with the leaves-only registry metadata, and consumers can
+                            // join runtime step events to discovered steps by index.
+                            let stepSeq = 0;
+                            // Separate ordinal for branch decision events (kept out of the leaf
+                            // step-index space so it can't desync leaf indices from metadata).
+                            let branchSeq = 0;
+                            // "step N of TOTAL" denominator: every LEAF step in the whole tree
+                            // (branch decisions are not steps). A leaf emits exactly once on any
+                            // path, so `stepSeq` indices are 0..leafTotal-1 and `index < total`
+                            // always holds. Branchless → test.steps.length (unchanged).
+                            const leafTotal = (list) => {
+                                let n = 0;
+                                for (const s of list) {
+                                    if (isTestBranchStep(s)) {
+                                        for (const c of s.branch.cases)
+                                            n += leafTotal(c.steps);
+                                        n += leafTotal(s.branch.default);
+                                    }
+                                    else {
+                                        n += 1;
+                                    }
+                                }
+                                return n;
+                            };
+                            const stepTotal = leafTotal(test.steps);
+                            // Emit a skipped step_end for every leaf step in a list, recursing
+                            // into branch sub-steps. Used by the skip-cascade and for the
+                            // non-taken cases/default of a branch.
+                            const emitSkippedTree = (list) => {
+                                for (const s of list) {
+                                    if (isTestBranchStep(s)) {
+                                        for (const c of s.branch.cases)
+                                            emitSkippedTree(c.steps);
+                                        emitSkippedTree(s.branch.default);
+                                    }
+                                    else {
+                                        emitEvent({
+                                            type: "step_end",
+                                            index: stepSeq++,
+                                            name: s.meta.name,
+                                            status: "skipped",
+                                            durationMs: 0,
+                                            assertions: 0,
+                                            failedAssertions: 0,
+                                        });
+                                    }
+                                }
+                            };
+                            // Recursive step-list runner. Branch sub-steps run through the same
+                            // path (first-class steps, incremental state commit), mirroring the
+                            // flow-side `runSteps` so teardown always sees the last committed state.
+                            const runStepList = async (list) => {
+                                for (const step of list) {
+                                    // If a previous step failed (or a step called ctx.skip()),
+                                    // skip the remaining steps (and all their branch descendants).
+                                    if (stepFailed || skipRequest) {
+                                        emitSkippedTree([step]);
+                                        continue;
+                                    }
+                                    // Branch step (condition / switchOn / switchCond): evaluate the
+                                    // decision, run the taken case's sub-steps, skip the rest.
+                                    if (isTestBranchStep(step)) {
+                                        await runBranchStep(step);
+                                        continue;
+                                    }
+                                    // Poll step (test().poll): bounded retry of the attempt fn until
+                                    // the exit predicate holds (or a bound exhausts → the step fails).
+                                    if (isTestPollStep(step)) {
+                                        await runPollStep(step);
+                                        continue;
+                                    }
+                                    const i = stepSeq++;
+                                    // Reset per-step assertion counters and set step scope
+                                    {
+                                        const trc = currentTestCtx();
+                                        trc.stepFailedAssertions = 0;
+                                        trc.stepAssertionTotal = 0;
+                                        trc.currentStepIndex = i;
+                                    }
+                                    const stepStart = performance.now();
+                                    emitEvent({
+                                        type: "step_start",
+                                        index: i,
+                                        name: step.meta.name,
+                                        total: stepTotal,
+                                    });
+                                    let stepError;
+                                    let stepReturnState = undefined;
+                                    const retries = step.meta.retries;
+                                    const configuredRetries = typeof retries === "number" && Number.isFinite(retries)
+                                        ? Math.max(0, Math.floor(retries))
+                                        : 0;
+                                    const retryDelayMs = typeof step.meta.retryDelay === "number" && Number.isFinite(step.meta.retryDelay)
+                                        ? Math.max(0, step.meta.retryDelay)
+                                        : (configuredRetries > 0 ? 1000 : 0);
+                                    const backoffMultiplier = typeof step.meta.backoff === "number" && Number.isFinite(step.meta.backoff)
+                                        ? Math.max(1, step.meta.backoff)
+                                        : 1;
+                                    const stepTimeout = step.meta.timeout;
+                                    const configuredStepTimeout = typeof stepTimeout === "number" && Number.isFinite(stepTimeout)
+                                        ? Math.floor(stepTimeout)
+                                        : 0;
+                                    const stepTimeoutMs = configuredStepTimeout > 0 ? configuredStepTimeout : undefined;
+                                    const maxAttempts = configuredRetries + 1;
+                                    let attemptsUsed = 0;
+                                    let lastFailedAssertions = 0;
+                                    let lastAssertions = 0;
+                                    let timeoutFailure = false;
+                                    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+                                        attemptsUsed = attempt;
+                                        stepError = undefined;
+                                        stepReturnState = undefined;
+                                        {
+                                            const trc = currentTestCtx();
+                                            trc.stepFailedAssertions = 0;
+                                            trc.stepAssertionTotal = 0;
+                                        }
+                                        timeoutFailure = false;
+                                        let stepTimeoutId;
+                                        try {
+                                            const stepResult = step.fn(effectiveCtx, state);
+                                            // Note: timed-out step bodies cannot be force-cancelled in JS.
+                                            // We treat timeout as terminal (no further retries) to avoid
+                                            // overlapping attempts mutating shared step context.
+                                            const result = stepTimeoutMs === undefined ? await stepResult : await Promise.race([
+                                                stepResult,
+                                                new Promise((_, reject) => {
+                                                    stepTimeoutId = setTimeout(() => {
+                                                        reject(new StepTimeoutError(step.meta.name, stepTimeoutMs));
+                                                    }, stepTimeoutMs);
+                                                }),
+                                            ]);
+                                            if (result !== undefined) {
+                                                state = result;
+                                                stepReturnState = result;
+                                            }
+                                        }
+                                        catch (err) {
+                                            if (err instanceof SkipError) {
+                                                // ctx.skip() inside a step skips the WHOLE test. It is
+                                                // not a step failure and must not be retried.
+                                                skipRequest = err;
+                                            }
+                                            else {
+                                                stepError = err instanceof Error ? err.message : String(err);
+                                                timeoutFailure = err instanceof StepTimeoutError;
+                                            }
+                                        }
+                                        finally {
+                                            if (stepTimeoutId !== undefined) {
+                                                clearTimeout(stepTimeoutId);
+                                            }
+                                        }
+                                        lastFailedAssertions = getStepFailedAssertions();
+                                        lastAssertions = getStepAssertionTotal();
+                                        // Skip is terminal — stop attempting, never retry a skip.
+                                        if (skipRequest) {
+                                            break;
+                                        }
+                                        const attemptFailed = !!stepError || getStepFailedAssertions() > 0;
+                                        if (!attemptFailed) {
+                                            break;
+                                        }
+                                        // Timeouts are terminal to avoid overlapping attempts from
+                                        // dangling async operations in the timed-out step body.
+                                        if (timeoutFailure) {
+                                            break;
+                                        }
+                                        if (attempt < maxAttempts) {
+                                            const delay = Math.min(retryDelayMs * backoffMultiplier ** (attempt - 1), 30_000);
+                                            const reason = stepError ? stepError : `${getStepFailedAssertions()} failed assertion(s)`;
+                                            emitEvent({
+                                                type: "log",
+                                                stepIndex: i,
+                                                message: `Retrying step "${step.meta.name}" (${attempt + 1}/${maxAttempts}) after failure: ${reason}${delay > 0 ? ` (waiting ${delay}ms)` : ""}`,
+                                            });
+                                            if (delay > 0) {
+                                                await new Promise((r) => setTimeout(r, delay));
+                                            }
+                                        }
+                                    }
+                                    // ctx.skip() called in this step. If the step already recorded a
+                                    // failed assertion BEFORE skipping, the failure wins — a skip must
+                                    // not mask a real failure (consistent with simple-mode tests,
+                                    // where generateSummary fails on a failed assertion regardless of
+                                    // a later skip). Otherwise emit a skipped step_end and stop running
+                                    // steps; the test is reported as skipped after teardown via the
+                                    // throw below the loop.
+                                    if (skipRequest && lastFailedAssertions === 0) {
+                                        emitEvent({
+                                            type: "step_end",
+                                            index: i,
+                                            name: step.meta.name,
+                                            status: "skipped",
+                                            durationMs: Math.round(performance.now() - stepStart),
+                                            assertions: lastAssertions,
+                                            failedAssertions: 0,
+                                            attempts: attemptsUsed,
+                                            retriesUsed: Math.max(0, attemptsUsed - 1),
+                                        });
+                                        currentTestCtx().currentStepIndex = null;
+                                        continue;
+                                    }
+                                    // Prior failure overrides the skip — fall through and report this
+                                    // step (and the test) as failed.
+                                    skipRequest = undefined;
+                                    const durationMs = Math.round(performance.now() - stepStart);
+                                    const failed = !!stepError || lastFailedAssertions > 0;
+                                    // Serialize return state with size guard (max 4 KB)
+                                    let returnStatePayload = undefined;
+                                    if (stepReturnState !== undefined) {
+                                        try {
+                                            const serialized = JSON.stringify(stepReturnState);
+                                            if (serialized.length <= 4096) {
+                                                returnStatePayload = stepReturnState;
+                                            }
+                                            else {
+                                                returnStatePayload = `[truncated: ${serialized.length} bytes]`;
+                                            }
+                                        }
+                                        catch {
+                                            returnStatePayload = "[non-serializable]";
+                                        }
+                                    }
                                     emitEvent({
                                         type: "step_end",
                                         index: i,
                                         name: step.meta.name,
-                                        status: "skipped",
-                                        durationMs: 0,
-                                        assertions: 0,
-                                        failedAssertions: 0,
+                                        status: failed ? "failed" : "passed",
+                                        durationMs,
+                                        assertions: lastAssertions,
+                                        failedAssertions: lastFailedAssertions,
+                                        attempts: attemptsUsed,
+                                        retriesUsed: Math.max(0, attemptsUsed - 1),
+                                        ...(stepError && { error: stepError }),
+                                        ...(returnStatePayload !== undefined && {
+                                            returnState: returnStatePayload,
+                                        }),
                                     });
-                                    continue;
+                                    currentTestCtx().currentStepIndex = null;
+                                    if (failed) {
+                                        stepFailed = true;
+                                        // Don't throw here — let the loop continue to emit skip events
+                                    }
                                 }
-                                // Reset per-step assertion counters and set step scope
+                            };
+                            // Execute a poll step (test().poll): a first-class leaf step whose
+                            // body is a bounded retry of `fn` until `until` holds (or a bound
+                            // exhausts → the step fails). Each attempt is RACED against its
+                            // budget (best-effort: arbitrary user `fn`/`until` can't be force-
+                            // cancelled, but the step never waits past the budget). Emits a
+                            // `poll` timeline event (attempts/elapsed/satisfied/exhausted) plus
+                            // the normal step_start/step_end. fn/until run against the live ctx
+                            // (test-side, like ctx.pollUntil — assertions count).
+                            const runPollStep = async (step) => {
+                                const poll = step.poll;
+                                const i = stepSeq++;
                                 {
                                     const trc = currentTestCtx();
                                     trc.stepFailedAssertions = 0;
@@ -1541,135 +1799,326 @@ async function executeNewTest(test) {
                                     trc.currentStepIndex = i;
                                 }
                                 const stepStart = performance.now();
-                                emitEvent({
-                                    type: "step_start",
-                                    index: i,
-                                    name: step.meta.name,
-                                    total: test.steps.length,
-                                });
-                                let stepError;
-                                let stepReturnState = undefined;
-                                const retries = step.meta.retries;
-                                const configuredRetries = typeof retries === "number" && Number.isFinite(retries)
-                                    ? Math.max(0, Math.floor(retries))
-                                    : 0;
-                                const retryDelayMs = typeof step.meta.retryDelay === "number" && Number.isFinite(step.meta.retryDelay)
-                                    ? Math.max(0, step.meta.retryDelay)
-                                    : (configuredRetries > 0 ? 1000 : 0);
-                                const backoffMultiplier = typeof step.meta.backoff === "number" && Number.isFinite(step.meta.backoff)
-                                    ? Math.max(1, step.meta.backoff)
-                                    : 1;
-                                const stepTimeout = step.meta.timeout;
-                                const configuredStepTimeout = typeof stepTimeout === "number" && Number.isFinite(stepTimeout)
-                                    ? Math.floor(stepTimeout)
-                                    : 0;
-                                const stepTimeoutMs = configuredStepTimeout > 0 ? configuredStepTimeout : undefined;
-                                const maxAttempts = configuredRetries + 1;
-                                let attemptsUsed = 0;
-                                let lastFailedAssertions = 0;
-                                let lastAssertions = 0;
-                                let timeoutFailure = false;
-                                for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-                                    attemptsUsed = attempt;
-                                    stepError = undefined;
-                                    stepReturnState = undefined;
-                                    {
-                                        const trc = currentTestCtx();
-                                        trc.stepFailedAssertions = 0;
-                                        trc.stepAssertionTotal = 0;
+                                emitEvent({ type: "step_start", index: i, name: step.meta.name, total: stepTotal });
+                                // Local budget sentinel so a budget timeout is distinguishable from
+                                // a genuine fn/until error or a SkipError.
+                                class PollBudgetTimeout extends Error {
+                                }
+                                const raceBudget = (p, budgetMs) => {
+                                    if (!Number.isFinite(budgetMs))
+                                        return p;
+                                    return new Promise((resolve, reject) => {
+                                        const t = setTimeout(() => reject(new PollBudgetTimeout()), Math.max(0, budgetMs));
+                                        p.then((v) => { clearTimeout(t); resolve(v); }, (e) => { clearTimeout(t); reject(e); });
+                                    });
+                                };
+                                const everyMs = poll.every ?? 1000;
+                                const backoff = poll.backoff ?? 1;
+                                const perAttempt = poll.perAttemptTimeout ?? Infinity;
+                                const start = performance.now();
+                                const deadline = poll.timeout !== undefined ? start + poll.timeout : Infinity;
+                                let attempt = 0;
+                                let delay = everyMs;
+                                let satisfied = false;
+                                let exhausted = false;
+                                let pollError;
+                                let lastRes;
+                                // A poll-phase throw (fn / until / out-mapper) must surface a
+                                // non-empty message: pollError is tested for truthiness below to
+                                // decide failure AND whether to emit an `error`, so an empty
+                                // message (`throw new Error("")` / `throw ""`) would otherwise be
+                                // silently treated as a pass.
+                                const pollErrMsg = (e) => {
+                                    const m = e instanceof Error ? e.message : String(e);
+                                    return m || `poll "${step.meta.name}" threw an empty error`;
+                                };
+                                for (;;) {
+                                    attempt += 1;
+                                    const remainingTotal = deadline - performance.now();
+                                    if (remainingTotal <= 0) {
+                                        exhausted = true;
+                                        break;
                                     }
-                                    timeoutFailure = false;
-                                    let stepTimeoutId;
+                                    const attemptBudget = Math.min(perAttempt, remainingTotal);
+                                    const attemptStart = performance.now();
+                                    // Attempt fn (best-effort raced).
                                     try {
-                                        const stepResult = step.fn(effectiveCtx, state);
-                                        // Note: timed-out step bodies cannot be force-cancelled in JS.
-                                        // We treat timeout as terminal (no further retries) to avoid
-                                        // overlapping attempts mutating shared step context.
-                                        const result = stepTimeoutMs === undefined ? await stepResult : await Promise.race([
-                                            stepResult,
-                                            new Promise((_, reject) => {
-                                                stepTimeoutId = setTimeout(() => {
-                                                    reject(new StepTimeoutError(step.meta.name, stepTimeoutMs));
-                                                }, stepTimeoutMs);
-                                            }),
-                                        ]);
-                                        if (result !== undefined) {
-                                            state = result;
-                                            stepReturnState = result;
-                                        }
+                                        lastRes = await raceBudget(Promise.resolve(poll.fn(effectiveCtx, state)), attemptBudget);
                                     }
                                     catch (err) {
-                                        stepError = err instanceof Error ? err.message : String(err);
-                                        timeoutFailure = err instanceof StepTimeoutError;
-                                    }
-                                    finally {
-                                        if (stepTimeoutId !== undefined) {
-                                            clearTimeout(stepTimeoutId);
+                                        if (err instanceof SkipError) {
+                                            skipRequest = err;
+                                            break;
                                         }
-                                    }
-                                    lastFailedAssertions = getStepFailedAssertions();
-                                    lastAssertions = getStepAssertionTotal();
-                                    const attemptFailed = !!stepError || getStepFailedAssertions() > 0;
-                                    if (!attemptFailed) {
+                                        if (err instanceof PollBudgetTimeout) {
+                                            exhausted = true;
+                                            break;
+                                        }
+                                        pollError = pollErrMsg(err);
                                         break;
                                     }
-                                    // Timeouts are terminal to avoid overlapping attempts from
-                                    // dangling async operations in the timed-out step body.
-                                    if (timeoutFailure) {
+                                    if (performance.now() > deadline || performance.now() - attemptStart > perAttempt) {
+                                        exhausted = true;
                                         break;
                                     }
-                                    if (attempt < maxAttempts) {
-                                        const delay = Math.min(retryDelayMs * backoffMultiplier ** (attempt - 1), 30_000);
-                                        const reason = stepError ? stepError : `${getStepFailedAssertions()} failed assertion(s)`;
-                                        emitEvent({
-                                            type: "log",
-                                            stepIndex: i,
-                                            message: `Retrying step "${step.meta.name}" (${attempt + 1}/${maxAttempts}) after failure: ${reason}${delay > 0 ? ` (waiting ${delay}ms)` : ""}`,
-                                        });
-                                        if (delay > 0) {
-                                            await new Promise((r) => setTimeout(r, delay));
+                                    // Exit predicate (raced to the remaining attempt budget).
+                                    let done;
+                                    try {
+                                        const predBudget = Math.min(deadline - performance.now(), perAttempt - (performance.now() - attemptStart));
+                                        const out = await raceBudget(Promise.resolve(poll.until(effectiveCtx, lastRes, state)), Math.max(0, predBudget));
+                                        if (typeof out !== "boolean") {
+                                            pollError = `poll "${step.meta.name}": until must return a boolean; got ${out === null ? "null" : typeof out}`;
+                                            break;
                                         }
+                                        done = out;
                                     }
-                                }
-                                const durationMs = Math.round(performance.now() - stepStart);
-                                const failed = !!stepError || lastFailedAssertions > 0;
-                                // Serialize return state with size guard (max 4 KB)
-                                let returnStatePayload = undefined;
-                                if (stepReturnState !== undefined) {
-                                    try {
-                                        const serialized = JSON.stringify(stepReturnState);
-                                        if (serialized.length <= 4096) {
-                                            returnStatePayload = stepReturnState;
+                                    catch (err) {
+                                        if (err instanceof SkipError) {
+                                            skipRequest = err;
+                                            break;
                                         }
-                                        else {
-                                            returnStatePayload = `[truncated: ${serialized.length} bytes]`;
+                                        if (err instanceof PollBudgetTimeout) {
+                                            exhausted = true;
+                                            break;
+                                        }
+                                        pollError = pollErrMsg(err);
+                                        break;
+                                    }
+                                    if (done) {
+                                        satisfied = true;
+                                        if (poll.out) {
+                                            // A throwing out-mapper must fail the poll through the normal
+                                            // path (poll event + step_end + ctx reset below), not escape
+                                            // and leave a dangling started step — like fn/until errors.
+                                            try {
+                                                const next = poll.out(state, lastRes);
+                                                if (next !== undefined)
+                                                    state = next;
+                                            }
+                                            catch (err) {
+                                                pollError = pollErrMsg(err);
+                                            }
                                         }
+                                        break;
+                                    }
+                                    // Not satisfied → check bounds, then wait.
+                                    if (poll.maxAttempts && attempt >= poll.maxAttempts) {
+                                        exhausted = true;
+                                        break;
                                     }
-                                    catch {
-                                        returnStatePayload = "[non-serializable]";
+                                    if (Number.isFinite(deadline) && performance.now() + delay >= deadline) {
+                                        exhausted = true;
+                                        break;
                                     }
+                                    await new Promise((r) => setTimeout(r, delay));
+                                    delay = Math.min(delay * backoff, 30_000);
+                                }
+                                const durationMs = Math.round(performance.now() - stepStart);
+                                const failedAssertions = getStepFailedAssertions();
+                                const assertions = getStepAssertionTotal();
+                                // ctx.skip() in fn/until skips the whole test (unless a failure was
+                                // already recorded — failure wins, mirroring the normal step path).
+                                if (skipRequest && failedAssertions === 0 && !pollError && !exhausted) {
+                                    emitEvent({
+                                        type: "step_end",
+                                        index: i,
+                                        name: step.meta.name,
+                                        status: "skipped",
+                                        durationMs,
+                                        assertions,
+                                        failedAssertions: 0,
+                                        attempts: attempt,
+                                    });
+                                    currentTestCtx().currentStepIndex = null;
+                                    return;
+                                }
+                                skipRequest = undefined;
+                                if (exhausted && !pollError) {
+                                    pollError = `poll "${step.meta.name}" exhausted: condition not met after ${attempt} attempt(s)`;
                                 }
+                                const failed = !!pollError || failedAssertions > 0 || !satisfied;
+                                emitEvent({
+                                    type: "poll",
+                                    index: i,
+                                    name: step.meta.name,
+                                    attempts: attempt,
+                                    elapsedMs: Math.round(performance.now() - start),
+                                    satisfied,
+                                    exhausted,
+                                    ...(pollError && { error: pollError }),
+                                });
                                 emitEvent({
                                     type: "step_end",
                                     index: i,
                                     name: step.meta.name,
                                     status: failed ? "failed" : "passed",
                                     durationMs,
-                                    assertions: lastAssertions,
-                                    failedAssertions: lastFailedAssertions,
-                                    attempts: attemptsUsed,
-                                    retriesUsed: Math.max(0, attemptsUsed - 1),
-                                    ...(stepError && { error: stepError }),
-                                    ...(returnStatePayload !== undefined && {
-                                        returnState: returnStatePayload,
-                                    }),
+                                    assertions,
+                                    failedAssertions,
+                                    attempts: attempt,
+                                    ...(pollError && { error: pollError }),
                                 });
                                 currentTestCtx().currentStepIndex = null;
-                                if (failed) {
+                                if (failed)
                                     stepFailed = true;
-                                    // Don't throw here — let the loop continue to emit skip events
+                            };
+                            // Execute a branch step: evaluate the decision (value-switch subject
+                            // once, or first-match predicate), emit a `branch` decision event,
+                            // run the taken case's sub-steps as first-class steps, and emit
+                            // skipped for every non-taken case + (if a case matched) the default.
+                            const runBranchStep = async (step) => {
+                                const branch = step.branch;
+                                const ctxNow = currentTestCtx();
+                                if (ctxNow) {
+                                    ctxNow.currentStepIndex = null;
+                                    // Reset the assertion counters so we can detect ctx.assert /
+                                    // ctx.validate failures made DURING the decision (predicates get
+                                    // the full ctx) and fail the branch instead of silently deciding.
+                                    ctxNow.stepFailedAssertions = 0;
+                                    ctxNow.stepAssertionTotal = 0;
                                 }
-                            }
+                                let takenIndex = "default";
+                                let takenValue;
+                                try {
+                                    if (branch.mode === "value") {
+                                        // Subject lens evaluated EXACTLY ONCE (test lenses may be impure).
+                                        // `await` so an async lens resolves to its scalar before
+                                        // matching (and a rejection is caught below as a decision
+                                        // failure) — a bare Promise would never === a case value.
+                                        const subject = branch.subject
+                                            ? await branch.subject(effectiveCtx, state)
+                                            : undefined;
+                                        for (let ci = 0; ci < branch.cases.length; ci++) {
+                                            if (subject === branch.cases[ci].value) {
+                                                takenIndex = ci;
+                                                takenValue = branch.cases[ci].value;
+                                                break;
+                                            }
+                                        }
+                                    }
+                                    else {
+                                        for (let ci = 0; ci < branch.cases.length; ci++) {
+                                            const pred = branch.cases[ci].predicate;
+                                            if (!pred)
+                                                continue;
+                                            const result = await pred(effectiveCtx, state);
+                                            // Predicate contract is boolean. A JS / `as any` caller could
+                                            // return a truthy non-boolean ("false", an object); fail fast
+                                            // instead of coercing (mirrors the flow-side guarantee).
+                                            if (typeof result !== "boolean") {
+                                                throw new Error(`condition / switchCond predicate must return a boolean; ` +
+                                                    `got ${result === null ? "null" : typeof result}`);
+                                            }
+                                            if (result) {
+                                                takenIndex = ci;
+                                                break;
+                                            }
+                                        }
+                                    }
+                                }
+                                catch (err) {
+                                    // ctx.skip() inside a predicate/lens skips the WHOLE test (like
+                                    // inside a step) — UNLESS a failed assertion was already recorded
+                                    // during the decision, in which case the failure wins over the
+                                    // skip (mirrors the step loop's d675fc9 semantics: a skip must
+                                    // not mask a real failure).
+                                    if (err instanceof SkipError && getStepFailedAssertions() === 0) {
+                                        skipRequest = err;
+                                        emitEvent({
+                                            type: "branch",
+                                            index: branchSeq++,
+                                            name: step.meta.name,
+                                            takenIndex: "default",
+                                            ...(branch.message ? { message: branch.message } : {}),
+                                            total: branch.cases.length,
+                                        });
+                                        for (const c of branch.cases)
+                                            emitSkippedTree(c.steps);
+                                        emitSkippedTree(branch.default);
+                                        return;
+                                    }
+                                    // Branch decision failure (§7.4): the test fails; do not silently
+                                    // take a branch. Emit a failed branch event + skip all sub-steps.
+                                    // A skip that reaches here was preceded by a failed assertion.
+                                    const failedDuring = getStepFailedAssertions();
+                                    const errMessage = err instanceof SkipError
+                                        ? `${failedDuring} failed assertion(s) before ctx.skip() in branch decision`
+                                        : err instanceof Error
+                                            ? err.message
+                                            : String(err);
+                                    emitEvent({
+                                        type: "branch",
+                                        index: branchSeq++,
+                                        name: step.meta.name,
+                                        takenIndex: "default",
+                                        ...(branch.message ? { message: branch.message } : {}),
+                                        total: branch.cases.length,
+                                        error: errMessage,
+                                    });
+                                    stepFailed = true;
+                                    if (branchDecisionError === undefined) {
+                                        branchDecisionError = `branch "${step.meta.name}": ${errMessage}`;
+                                    }
+                                    for (const c of branch.cases)
+                                        emitSkippedTree(c.steps);
+                                    emitSkippedTree(branch.default);
+                                    return;
+                                }
+                                // A ctx.assert(false) / ctx.validate(...) failure recorded while
+                                // evaluating the decision fails the branch (the assertion event is
+                                // outside any step, so step-authoritative success would miss it).
+                                const decisionFailedAssertions = getStepFailedAssertions();
+                                if (decisionFailedAssertions > 0) {
+                                    const assertErr = `${decisionFailedAssertions} failed assertion(s) during branch decision`;
+                                    emitEvent({
+                                        type: "branch",
+                                        index: branchSeq++,
+                                        name: step.meta.name,
+                                        takenIndex: "default",
+                                        ...(branch.message ? { message: branch.message } : {}),
+                                        total: branch.cases.length,
+                                        error: assertErr,
+                                    });
+                                    stepFailed = true;
+                                    if (branchDecisionError === undefined) {
+                                        branchDecisionError = `branch "${step.meta.name}": ${assertErr}`;
+                                    }
+                                    for (const c of branch.cases)
+                                        emitSkippedTree(c.steps);
+                                    emitSkippedTree(branch.default);
+                                    return;
+                                }
+                                emitEvent({
+                                    type: "branch",
+                                    index: branchSeq++,
+                                    name: step.meta.name,
+                                    takenIndex,
+                                    ...(takenValue !== undefined ? { takenValue } : {}),
+                                    ...(branch.message ? { message: branch.message } : {}),
+                                    total: branch.cases.length,
+                                });
+                                // Emit/run leaves in REGISTRY (source) order — cases 0..N then
+                                // default — running the taken one as first-class steps and
+                                // skipping the rest IN PLACE. This keeps the monotonic leaf
+                                // `stepSeq` aligned with `flattenStepsForRegistry` order, so
+                                // consumers join runtime events to discovered steps by index even
+                                // when a later case (or the default) is taken.
+                                for (let ci = 0; ci < branch.cases.length; ci++) {
+                                    if (ci === takenIndex) {
+                                        await runStepList(branch.cases[ci].steps);
+                                    }
+                                    else {
+                                        emitSkippedTree(branch.cases[ci].steps);
+                                    }
+                                }
+                                if (takenIndex === "default") {
+                                    await runStepList(branch.default);
+                                }
+                                else {
+                                    emitSkippedTree(branch.default);
+                                }
+                            };
+                            await runStepList(test.steps);
                         }
                     }
                     finally {
@@ -1689,9 +2138,14 @@ async function executeNewTest(test) {
                             }
                         }
                     }
+                    // A step called ctx.skip() → propagate so the test is reported as
+                    // skipped (teardown has already run in the finally above).
+                    if (skipRequest) {
+                        throw skipRequest;
+                    }
                     // If any step failed (assertion or throw), mark overall test as failed
                     if (stepFailed) {
-                        throw new Error("One or more steps failed");
+                        throw new Error(branchDecisionError ?? "One or more steps failed");
                     }
                 }
             };