@glubean/engine 0.7.0

package/dist/engine.js

@@ -0,0 +1,1391 @@
+/**
+ * RunnerCore — the environment-agnostic run-loop (Stage 1 spike).
+ *
+ * Everything per-run lives in an explicit ExecutionScope; the engine touches NO
+ * module-level mutable state. Per-run isolation is delegated entirely to the
+ * injected Carrier port: run() wraps the run-loop in runWithRuntime(scope.runtime),
+ * so SDK getRuntime() consumers (configure() / session / configured-http) resolve
+ * to the active scope. node installs an ALS carrier (true cross-await isolation);
+ * the negative-control test installs the globalThis single-slot carrier and the
+ * SAME interleaving test must then leak — proving the gate is sensitive.
+ *
+ * HTTP (Decision B): each run gets a REAL ky instance built with the host-injected
+ * fetch + scope-bound trace hooks (keyed by Request, not ky NormalizedOptions —
+ * codex P1-2). ky owns the http facade; we only alias the SDK's public `prefixUrl`
+ * to ky 2's `prefix` at the boundary (codex P2-5). Narrow run-loop only: simple +
+ * linear steps. No branch / poll / retry / timeout / workflow (Stage 2).
+ */
+import ky from "ky";
+import { captureRequestBody, inferJsonSchema, truncateBody, truncateDeep } from "./http-trace.js";
+import { Expectation } from "@glubean/sdk";
+import { installCarrier, runWithRuntime } from "@glubean/sdk/internal";
+const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head"]);
+/** URL pathname, or the raw url if it doesn't parse (node parity: trace target). */
+function pathnameOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url;
+    }
+}
+/** URL pathname, or undefined if it doesn't parse (node parity: the http_duration_ms
+ *  metric drops the `path` tag when the url is unparseable, harness.ts:1116-1127). */
+function tryPathname(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Layer per-run overrides over a host env object WITHOUT a destructive spread, so
+ * a fallback-Proxy provider (node: .env → process.env) keeps its fallback for keys
+ * the run never overrides. An empty-string override is treated as "unset" (node
+ * parity: empty = missing → defer to the provider). (codex P2 / plan 0005 §E)
+ */
+/**
+ * Mirror the node harness's validator semantics for ctx.vars/secrets.require's
+ * optional validator callback (codex P2): true / undefined / null = valid; a string
+ * = custom error message; anything else (false) = generic validation failure.
+ */
+function runEngineValidator(result, key, kind) {
+    if (result === true || result === undefined || result === null)
+        return;
+    if (typeof result === "string")
+        throw new Error(`Invalid ${kind} "${key}": ${result}`);
+    throw new Error(`Invalid ${kind} "${key}": validation failed`);
+}
+function branchOf(step) {
+    const b = step.branch;
+    return b && typeof b === "object" && Array.isArray(b.cases) ? b : null;
+}
+function pollOf(step) {
+    const p = step.poll;
+    return p && typeof p === "object" && typeof p.fn === "function" && typeof p.until === "function" ? p : null;
+}
+/** Count LEAF steps (node parity: leafTotal) — branch cases + default recurse;
+ *  used for the `total` on step_start. A linear list counts as its length. */
+function countLeafSteps(steps) {
+    let n = 0;
+    for (const s of steps) {
+        const br = branchOf(s);
+        if (br) {
+            for (const c of br.cases)
+                n += countLeafSteps(c.steps);
+            n += countLeafSteps(br.default ?? []);
+        }
+        else {
+            n += 1;
+        }
+    }
+    return n;
+}
+/** Per-step timeout error — same message/name as the node harness (harness.ts:446)
+ *  so step_end.error + classifyErrorReason match. */
+class StepTimeoutError extends Error {
+    constructor(stepName, timeoutMs) {
+        super(`Step "${stepName}" timed out after ${timeoutMs}ms`);
+        this.name = "StepTimeoutError";
+    }
+}
+/**
+ * ctx.skip() sentinel (node parity: harness.ts SkipError). Caught in the run-loop
+ * and turned into a `skipped` verdict — never leaves the engine (the host re-raises
+ * its OWN SkipError from the result so the dispatcher's skip status matches). The
+ * name matches the node harness so any classifier agrees.
+ */
+class SkipError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason ? `Test skipped: ${reason}` : "Test skipped");
+        this.reason = reason;
+        this.name = "SkipError";
+    }
+}
+/**
+ * ctx.fail() sentinel (node parity: harness.ts FailError). ctx.fail emits a failed
+ * assertion THEN throws this; in a simple test it propagates as a throw (→ host
+ * re-raises → failed), in a step/branch leg it is caught as the step error message.
+ */
+class FailError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = "FailError";
+    }
+}
+/**
+ * Core schema validation (node parity: harness.ts:runSchemaValidation). Duck-types
+ * `safeParse` (preferred) / `parse` so it stays browser-safe — no zod import. Always
+ * emits a schema_validation event (via the injected emitter), then routes a FAILURE
+ * by severity through the injected assert/warn (so it shares the run-loop's assertion
+ * counters + stepIndex). `fatal` emits a failed assertion then throws to abort. Shared
+ * by ctx.validate and (Phase 4f) the HTTP schema hooks.
+ */
+function runSchemaValidation(data, schema, label, severity, deps) {
+    let success = false;
+    let parsed;
+    let issues = [];
+    if (typeof schema.safeParse === "function") {
+        const result = schema.safeParse(data);
+        if (result.success) {
+            success = true;
+            parsed = result.data;
+        }
+        else {
+            issues = (result.error?.issues ?? []).map((i) => ({ message: i.message, ...(i.path ? { path: i.path } : {}) }));
+        }
+    }
+    else if (typeof schema.parse === "function") {
+        try {
+            parsed = schema.parse(data);
+            success = true;
+        }
+        catch (err) {
+            const errObj = err;
+            if (errObj?.issues && Array.isArray(errObj.issues)) {
+                issues = errObj.issues.map((i) => ({ message: i.message ?? String(i), ...(i.path ? { path: i.path } : {}) }));
+            }
+            else {
+                issues = [{ message: err instanceof Error ? err.message : String(err) }];
+            }
+        }
+    }
+    else {
+        issues = [{ message: "Schema has neither safeParse nor parse method" }];
+    }
+    deps.emitSchemaValidation({ label, success, severity, ...(issues.length > 0 ? { issues } : {}) });
+    if (!success) {
+        const issuesSummary = issues
+            .map((i) => (i.path ? i.path.join(".") + ": " : "") + i.message)
+            .join("; ");
+        const msg = `Schema validation failed: ${label} — ${issuesSummary}`;
+        switch (severity) {
+            case "error":
+                deps.assert(false, msg);
+                break;
+            case "warn":
+                deps.warn(false, msg);
+                break;
+            case "fatal":
+                deps.assert(false, msg);
+                throw new FailError(msg);
+        }
+        return { success: false, issues };
+    }
+    return { success: true, data: parsed };
+}
+/**
+ * Serialize a step's return state for the step_end event with the node harness's
+ * 4 KB guard: keep the value if it serializes ≤ 4096 bytes, else a truncated marker;
+ * a non-serializable value becomes a marker (codex parity).
+ */
+function serializeReturnState(value) {
+    try {
+        const s = JSON.stringify(value);
+        if (typeof s !== "string")
+            return "[non-serializable]";
+        return s.length <= 4096 ? value : `[truncated: ${s.length} bytes]`;
+    }
+    catch {
+        return "[non-serializable]";
+    }
+}
+function layerEnv(provider, overlay) {
+    if (!overlay || Object.keys(overlay).length === 0)
+        return provider;
+    return new Proxy(provider, {
+        get(target, prop) {
+            const o = overlay[prop];
+            return o !== undefined && o !== "" ? o : target[prop];
+        },
+        has(target, prop) {
+            // Empty overlay value = unset → defer to the provider (so ctx.vars.require,
+            // which checks `k in vars`, still throws for a genuinely-missing key). (codex P2)
+            const o = overlay[prop];
+            if (o !== undefined && o !== "")
+                return true;
+            return prop in target;
+        },
+    });
+}
+export class RunnerCore {
+    services;
+    constructor(services) {
+        this.services = services;
+        // Install the host carrier as the SDK's global carrier so getRuntime()
+        // (configure/session/configured-http) resolves through it.
+        installCarrier(services.carrier);
+    }
+    /**
+     * Run one test in an isolated scope. The whole run-loop — including every async
+     * continuation in user code — executes inside runWithRuntime(scope.runtime).
+     */
+    run(def, input = {}) {
+        // Honor an explicitly skipped test: never execute it (no side effects) —
+        // node-harness parity (codex B4 P2).
+        if (def.meta.skip) {
+            // No status EVENT — status emission is host policy (the runner emits the
+            // skipped status at dispatch; the browser derives it from this result).
+            return Promise.resolve({
+                id: def.meta.id,
+                name: def.meta.name ?? def.meta.id,
+                status: "skipped",
+                assertions: { total: 0, passed: 0 },
+            });
+        }
+        const scope = this.createScope(def, input);
+        return runWithRuntime(scope.runtime, () => this.runLoop(def, scope));
+    }
+    /**
+     * Runtime-authoritative resolution of a module namespace into runnable TestDefs
+     * (SoT §3.2: the static scanner is UI-only; this is the权威 resolver). Handles
+     * plain Test, Test[], TestBuilder, and EachBuilder — each `test.each` row
+     * becomes its own def. Narrow Stage-1 surface (no workflow/contract expansion).
+     */
+    resolve(namespace) {
+        const defs = [];
+        for (const value of Object.values(namespace ?? {}))
+            collectDefs(value, defs);
+        return defs;
+    }
+    createScope(def, input) {
+        const { env, events } = this.services;
+        // Layer per-run input OVER the host EnvProvider WITHOUT a destructive spread,
+        // so a host whose vars()/secrets() is a fallback Proxy (node: .env → process.env)
+        // keeps that fallback for keys the run never overrides (codex P2 / plan 0005 §E).
+        const vars = layerEnv(env.vars(), input.vars);
+        const secrets = layerEnv(env.secrets(), input.secrets);
+        const session = { ...(input.session ?? {}) };
+        // Raw snapshot for ctx.vars.all() (node parity: {...rawVars}). Use the host's RAW
+        // map (varsAll) so empty/overlay vars aren't lost to the fallback Proxy; layer the
+        // per-run input on top. Falls back to spreading vars() for hosts without varsAll
+        // (e.g. a browser host whose vars() is already a plain map). (codex Phase-8 P2)
+        const varsAll = { ...(env.varsAll ? env.varsAll() : env.vars()), ...(input.vars ?? {}) };
+        const scope = {
+            runtime: undefined,
+            testMeta: { id: def.meta.id, tags: def.meta.tags ?? [] },
+            stepIndex: 0,
+            currentStepIndex: null,
+            retryCount: input.retryCount ?? 0,
+            assertions: { total: 0, passed: 0 },
+            // assigned just below once the scope exists (the ky trace hook reads the live
+            // scope.currentStepIndex so HTTP traces inside a step carry stepIndex).
+            http: undefined,
+            session,
+            varsAll,
+        };
+        const http = this.createScopedKy(scope);
+        scope.http = http;
+        // Fresh runtime object per run (configure().http WeakMap-caches per identity).
+        scope.runtime = {
+            vars,
+            secrets,
+            session, // same ref as scope.session, so ctx.session.set is visible to session.get
+            http: http,
+            get test() {
+                return scope.testMeta;
+            },
+            log: (message, data) => events.emit({ type: "log", id: def.meta.id, message, data }),
+            // configure() plugins resolve trace/action/event from the CARRIER runtime, not
+            // the ctx object (configure/plugin.ts: `runtime.trace ?? noop`). The legacy
+            // harness wires these via setRuntime (`trace: ctx.trace`, …); forward them here
+            // too so an engine-routed plugin test keeps its trace/action/event evidence —
+            // else plugins (e.g. @glubean/grpc) silently no-op (codex 4c-e P2). Delegated to
+            // scope.ctxRef (back-filled before any user code resolves a plugin) so they
+            // carry the run's stepIndex, exactly like ctx.trace/action/event.
+            trace: (t) => scope.ctxRef?.trace(t),
+            action: (a) => scope.ctxRef?.action(a),
+            event: (ev) => scope.ctxRef?.event(ev),
+        };
+        return scope;
+    }
+    /**
+     * Build a per-run ky instance: host fetch + scope-bound trace hooks. Per-request
+     * state is keyed by ky 2's stable `options.context` object (NOT the Request, which
+     * a hook may replace when an auth helper rebuilds it — codex ky2 P2 / plan 0005 §D).
+     * throwHttpErrors:false matches the node harness default so 4xx/5xx surface as
+     * responses, not throws. The auto-trace routes through scope.ctxRef.trace (→ trace
+     * event + derived action) + ctx.metric("http_duration_ms"), so it shares the run's
+     * stepIndex attribution (node parity: harness.ts:1010-1133).
+     */
+    createScopedKy(scope) {
+        const { fetch: hostFetch, scheduler } = this.services;
+        const emitFullTrace = this.services.http?.emitFullTrace ?? false;
+        const inferSchema = this.services.http?.inferSchema ?? false;
+        const truncateArrays = this.services.http?.truncateArrays ?? false;
+        // Per-request state keyed by ky 2's stable options.context (not the Request).
+        const reqState = new WeakMap();
+        const instance = ky.create({
+            fetch: hostFetch,
+            throwHttpErrors: false,
+            // Match the node harness default: no implicit retries (authors opt in
+            // per-request). ky 2 retries GET/HEAD by default, which would mask
+            // transient failures and emit extra requests/traces. (codex engine P2)
+            retry: 0,
+            hooks: {
+                beforeRequest: [
+                    async ({ request, options }) => {
+                        reqState.set(options.context, {
+                            startTime: scheduler.now(),
+                            // Capture the request body (ky 2 hides options.json) for full-trace.
+                            body: emitFullTrace ? await captureRequestBody(request) : undefined,
+                        });
+                    },
+                ],
+                afterResponse: [
+                    async ({ request, options, response }) => {
+                        const ctx = scope.ctxRef;
+                        // No ctx yet (a request before makeCtx) should never happen during a run;
+                        // bail rather than emit an un-attributed trace.
+                        if (!ctx)
+                            return response;
+                        const state = reqState.get(options.context);
+                        const durationMs = Math.round(scheduler.now() - (state?.startTime ?? scheduler.now()));
+                        // `request` is the final (possibly hook-replaced) request — correct target.
+                        const pathname = pathnameOf(request.url);
+                        const trace = {
+                            protocol: "http",
+                            target: `${request.method} ${pathname}`,
+                            status: response.status,
+                            durationMs,
+                            ok: response.status < 400,
+                            // Deprecated HTTP back-compat fields (node parity: harness.ts:1043).
+                            method: request.method,
+                            url: request.url,
+                            duration: durationMs,
+                        };
+                        // Operation name from the GraphQL client (X-Glubean-Op header).
+                        const glubeanOp = request.headers.get("x-glubean-op");
+                        if (glubeanOp)
+                            trace.name = glubeanOp;
+                        // Full-trace capture (node parity: harness.ts:1062-1106), gated by
+                        // emitFullTrace. Reads a CLONE so the user's res.json()/text() still works.
+                        if (emitFullTrace) {
+                            trace.requestHeaders = Object.fromEntries(request.headers.entries());
+                            if (state?.body !== undefined)
+                                trace.requestBody = truncateBody(state.body);
+                            trace.responseHeaders = Object.fromEntries(response.headers.entries());
+                            try {
+                                const cloned = response.clone();
+                                const contentType = response.headers.get("content-type") || "";
+                                let parsedBody;
+                                if (contentType.includes("json"))
+                                    parsedBody = await cloned.json();
+                                else if (contentType.includes("text") || contentType.includes("xml"))
+                                    parsedBody = await cloned.text();
+                                if (parsedBody !== undefined) {
+                                    // Schema inference runs on the FULL body before any truncation.
+                                    if (inferSchema && typeof parsedBody === "object" && parsedBody !== null) {
+                                        trace.responseSchema = inferJsonSchema(parsedBody);
+                                    }
+                                    trace.responseBody = truncateArrays ? truncateDeep(parsedBody) : truncateBody(parsedBody);
+                                }
+                                // Binary content types are intentionally skipped.
+                            }
+                            catch {
+                                // Ignore clone/parse errors — trace still emits without the body.
+                            }
+                        }
+                        // ctx.trace emits the trace event + the derived `http:request` action.
+                        ctx.trace(trace);
+                        // Auto-metric for response time (node parity: harness.ts:1116).
+                        const urlPath = tryPathname(request.url);
+                        ctx.metric("http_duration_ms", durationMs, {
+                            unit: "ms",
+                            tags: urlPath !== undefined ? { method: request.method, path: urlPath } : { method: request.method },
+                        });
+                        return response;
+                    },
+                ],
+            },
+        });
+        return wrapScopedKy(instance, scope);
+    }
+    async runLoop(def, scope) {
+        const { events, scheduler } = this.services;
+        events.emit({
+            type: "start",
+            id: scope.testMeta.id,
+            name: def.meta.name ?? def.meta.id,
+            tags: scope.testMeta.tags,
+            ...(scope.retryCount > 0 ? { retryCount: scope.retryCount } : {}),
+        });
+        const ctx = this.makeCtx(scope);
+        // Back-fill so the scope-bound ky hooks (built in createScope, before makeCtx)
+        // can route the HTTP auto-trace through ctx.trace / ctx.metric at request time.
+        scope.ctxRef = ctx;
+        let threw = false;
+        let thrownError;
+        let thrownStack;
+        let thrownName;
+        // A step that throws is CAUGHT + recorded as a failed step (node parity: the
+        // run still "completes"); it must still make the test's verdict error.
+        let stepFailed = false;
+        let stepFailMsg;
+        // First branch-decision failure → the test-level failure message (node parity:
+        // the post-loop throw prefers it over "One or more steps failed").
+        let branchDecisionError;
+        // ctx.skip() reached us: in a steps run a step/branch-predicate skip sets this
+        // (no throw — skips remaining steps + skips the whole test after teardown, node
+        // parity). A simple-test / setup skip propagates as a throw to the catch below.
+        let skipRequest;
+        let skipped = false;
+        let skipReason;
+        try {
+            if (def.type === "simple") {
+                if (!def.fn)
+                    throw new Error(`test "${def.meta.id}": missing fn`);
+                await def.fn(ctx);
+            }
+            else {
+                let state;
+                const stepTotal = countLeafSteps(def.steps ?? []);
+                let stepSeq = 0; // monotonic LEAF step index (continues across branches)
+                let branchSeq = 0; // separate index for branch decision events
+                // Recursive skipped-step emission (node parity: emitSkippedTree) — a skipped
+                // step_end per leaf (no attempts/retriesUsed); branch cases recurse.
+                const emitSkippedTree = (steps) => {
+                    for (const s of steps) {
+                        const br = branchOf(s);
+                        if (br) {
+                            for (const c of br.cases)
+                                emitSkippedTree(c.steps);
+                            emitSkippedTree((br.default ?? []));
+                        }
+                        else {
+                            events.emit({
+                                type: "step_end",
+                                id: scope.testMeta.id,
+                                index: stepSeq++,
+                                name: s.meta.name,
+                                status: "skipped",
+                                durationMs: 0,
+                                assertions: 0,
+                                failedAssertions: 0,
+                            });
+                        }
+                    }
+                };
+                // Run one normal (non-branch) step with retry/timeout (node parity).
+                const runNormalStep = async (step) => {
+                    const idx = stepSeq++;
+                    scope.currentStepIndex = idx;
+                    const startedAt = scheduler.now();
+                    events.emit({ type: "step_start", id: scope.testMeta.id, index: idx, name: step.meta.name, total: stepTotal });
+                    const sm = step.meta ?? {};
+                    const configuredRetries = Number.isFinite(sm.retries) ? Math.max(0, Math.floor(sm.retries)) : 0;
+                    const retryDelayMs = Number.isFinite(sm.retryDelay) ? Math.max(0, sm.retryDelay) : configuredRetries > 0 ? 1000 : 0;
+                    const backoff = Number.isFinite(sm.backoff) ? Math.max(1, sm.backoff) : 1;
+                    const stepTimeoutMs = Number.isFinite(sm.timeout) && sm.timeout > 0 ? Math.floor(sm.timeout) : undefined;
+                    const maxAttempts = configuredRetries + 1;
+                    let stepError;
+                    let stepReturnState;
+                    let attemptsUsed = 0;
+                    let lastAssertions = 0;
+                    let lastFailedAssertions = 0;
+                    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+                        attemptsUsed = attempt;
+                        stepError = undefined;
+                        stepReturnState = undefined;
+                        const aBefore = scope.assertions.total;
+                        const fBefore = scope.assertions.total - scope.assertions.passed;
+                        let timedOut = false;
+                        try {
+                            const call = step.fn(ctx, state);
+                            if (stepTimeoutMs === undefined) {
+                                const next = await call;
+                                if (next !== undefined) {
+                                    state = next;
+                                    stepReturnState = next;
+                                }
+                            }
+                            else {
+                                let timer;
+                                try {
+                                    const next = await Promise.race([
+                                        call,
+                                        new Promise((_, reject) => {
+                                            timer = setTimeout(() => reject(new StepTimeoutError(step.meta.name, stepTimeoutMs)), stepTimeoutMs);
+                                        }),
+                                    ]);
+                                    if (next !== undefined) {
+                                        state = next;
+                                        stepReturnState = next;
+                                    }
+                                }
+                                finally {
+                                    if (timer !== undefined)
+                                        clearTimeout(timer);
+                                }
+                            }
+                        }
+                        catch (e) {
+                            if (e instanceof SkipError) {
+                                // ctx.skip() inside a step skips the WHOLE test — not a step failure,
+                                // and never retried (node parity: harness.ts:2219).
+                                skipRequest = e;
+                            }
+                            else {
+                                // A thrown step is caught + recorded as a failed step (node parity:
+                                // the run still "completes"; the test fails via stepsFailed).
+                                stepError = e instanceof Error ? e.message : String(e);
+                                timedOut = e instanceof StepTimeoutError;
+                            }
+                        }
+                        lastAssertions = scope.assertions.total - aBefore;
+                        lastFailedAssertions = scope.assertions.total - scope.assertions.passed - fBefore;
+                        if (skipRequest)
+                            break; // skip is terminal — never retry a skip
+                        const attemptFailed = !!stepError || lastFailedAssertions > 0;
+                        if (!attemptFailed || timedOut)
+                            break; // success, or a timeout (terminal — no retry)
+                        if (attempt < maxAttempts) {
+                            const delay = Math.min(retryDelayMs * backoff ** (attempt - 1), 30_000);
+                            const reason = stepError ? stepError : `${lastFailedAssertions} failed assertion(s)`;
+                            events.emit({
+                                type: "log",
+                                id: scope.testMeta.id,
+                                stepIndex: idx,
+                                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() in this step skips the whole test — UNLESS a failed assertion
+                    // was already recorded before the skip, in which case the failure wins (a
+                    // skip must not mask a real failure; node parity: harness.ts:2275). On a
+                    // clean skip: emit a skipped step_end (with attempts/retriesUsed) and return;
+                    // runStepList sees skipRequest set and skips the remaining steps.
+                    if (skipRequest && lastFailedAssertions === 0) {
+                        events.emit({
+                            type: "step_end",
+                            id: scope.testMeta.id,
+                            index: idx,
+                            name: step.meta.name,
+                            status: "skipped",
+                            durationMs: scheduler.now() - startedAt,
+                            assertions: lastAssertions,
+                            failedAssertions: 0,
+                            attempts: attemptsUsed,
+                            retriesUsed: Math.max(0, attemptsUsed - 1),
+                        });
+                        scope.currentStepIndex = null;
+                        return;
+                    }
+                    // A prior failure overrides the skip — report this step (+ the test) failed.
+                    skipRequest = undefined;
+                    const failed = !!stepError || lastFailedAssertions > 0;
+                    events.emit({
+                        type: "step_end",
+                        id: scope.testMeta.id,
+                        index: idx,
+                        name: step.meta.name,
+                        status: failed ? "failed" : "passed",
+                        durationMs: scheduler.now() - startedAt,
+                        assertions: lastAssertions,
+                        failedAssertions: lastFailedAssertions,
+                        attempts: attemptsUsed,
+                        retriesUsed: Math.max(0, attemptsUsed - 1),
+                        ...(stepError ? { error: stepError } : {}),
+                        ...(stepReturnState !== undefined ? { returnState: serializeReturnState(stepReturnState) } : {}),
+                    });
+                    scope.currentStepIndex = null;
+                    if (failed) {
+                        stepFailed = true;
+                        if (stepError && stepFailMsg === undefined)
+                            stepFailMsg = stepError;
+                    }
+                };
+                // Recursive step-list runner (node parity: runStepList). A prior failure
+                // skips the rest (skipped step_end tree). branch handling lands in Phase 2.
+                // Branch step (test().condition / .switchOn / .switchCond): make the decision
+                // ONCE, emit a `branch` event, run the taken case's sub-steps as first-class
+                // steps, and skip every non-taken case + (if a case matched) the default —
+                // in registry order so stepSeq stays aligned (node parity: runBranchStep).
+                const runBranchStep = async (step, branch) => {
+                    scope.currentStepIndex = null;
+                    const failedBefore = scope.assertions.total - scope.assertions.passed;
+                    let takenIndex = "default";
+                    let takenValue;
+                    const total = branch.cases.length;
+                    const baseEvent = { id: scope.testMeta.id, name: step.meta.name, ...(branch.message ? { message: branch.message } : {}) };
+                    const failDecision = (errMessage) => {
+                        events.emit({ type: "branch", ...baseEvent, index: branchSeq++, takenIndex: "default", total, 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 ?? []);
+                    };
+                    try {
+                        if (branch.mode === "value") {
+                            // Subject lens evaluated EXACTLY ONCE (lenses may be impure); await so
+                            // an async lens resolves to its scalar before matching.
+                            const subject = branch.subject ? await branch.subject(ctx, 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(ctx, state);
+                                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 (e) {
+                        const decisionFailed = scope.assertions.total - scope.assertions.passed - failedBefore;
+                        if (e instanceof SkipError && decisionFailed === 0) {
+                            // ctx.skip() in a predicate/lens skips the WHOLE test (node parity:
+                            // harness.ts:2573) — emit a default-taken branch with NO error + skip
+                            // every sub-step; runStepList then skips the remaining steps.
+                            skipRequest = e;
+                            events.emit({ type: "branch", ...baseEvent, index: branchSeq++, takenIndex: "default", total });
+                            for (const c of branch.cases)
+                                emitSkippedTree(c.steps);
+                            emitSkippedTree(branch.default ?? []);
+                            return;
+                        }
+                        // Decision failure (§7.4): the test fails; never silently take a branch. A
+                        // skip preceded by a failed assertion reports that failure (failure wins).
+                        failDecision(e instanceof SkipError
+                            ? `${decisionFailed} failed assertion(s) before ctx.skip() in branch decision`
+                            : e instanceof Error
+                                ? e.message
+                                : String(e));
+                        return;
+                    }
+                    // A ctx.assert(false) failure recorded WHILE deciding fails the branch (the
+                    // assertion event is outside any step, so step-authority would miss it).
+                    const decisionFailed = scope.assertions.total - scope.assertions.passed - failedBefore;
+                    if (decisionFailed > 0) {
+                        failDecision(`${decisionFailed} failed assertion(s) during branch decision`);
+                        return;
+                    }
+                    events.emit({
+                        type: "branch",
+                        ...baseEvent,
+                        index: branchSeq++,
+                        takenIndex,
+                        ...(takenValue !== undefined ? { takenValue } : {}),
+                        total,
+                    });
+                    // Leaves in registry order: cases 0..N then default — run the taken one,
+                    // skip the rest IN PLACE (keeps stepSeq aligned with discovery order).
+                    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 ?? []);
+                };
+                // 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 → it 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` event (attempts/elapsed/satisfied/exhausted) + the normal step_start/
+                // step_end. Assertions accumulate across attempts (node parity: harness.ts:2345).
+                const runPollStep = async (step, poll) => {
+                    const idx = stepSeq++;
+                    scope.currentStepIndex = idx;
+                    const aBefore = scope.assertions.total;
+                    const fBefore = scope.assertions.total - scope.assertions.passed;
+                    const stepStart = scheduler.now();
+                    events.emit({ type: "step_start", id: scope.testMeta.id, index: idx, 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 = scheduler.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 must surface a non-empty message: pollError is tested for
+                    // truthiness below to decide failure, so an empty message would be a silent 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 - scheduler.now();
+                        if (remainingTotal <= 0) {
+                            exhausted = true;
+                            break;
+                        }
+                        const attemptBudget = Math.min(perAttempt, remainingTotal);
+                        const attemptStart = scheduler.now();
+                        // Attempt fn (best-effort raced).
+                        try {
+                            lastRes = await raceBudget(Promise.resolve(poll.fn(ctx, state)), attemptBudget);
+                        }
+                        catch (err) {
+                            if (err instanceof SkipError) {
+                                skipRequest = err;
+                                break;
+                            }
+                            if (err instanceof PollBudgetTimeout) {
+                                exhausted = true;
+                                break;
+                            }
+                            pollError = pollErrMsg(err);
+                            break;
+                        }
+                        if (scheduler.now() > deadline || scheduler.now() - attemptStart > perAttempt) {
+                            exhausted = true;
+                            break;
+                        }
+                        // Exit predicate (raced to the remaining attempt budget).
+                        let done;
+                        try {
+                            const predBudget = Math.min(deadline - scheduler.now(), perAttempt - (scheduler.now() - attemptStart));
+                            const out = await raceBudget(Promise.resolve(poll.until(ctx, 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;
+                        }
+                        catch (err) {
+                            if (err instanceof SkipError) {
+                                skipRequest = err;
+                                break;
+                            }
+                            if (err instanceof PollBudgetTimeout) {
+                                exhausted = true;
+                                break;
+                            }
+                            pollError = pollErrMsg(err);
+                            break;
+                        }
+                        if (done) {
+                            satisfied = true;
+                            if (poll.out) {
+                                // A throwing out-mapper fails the poll through the normal path (poll
+                                // event + step_end below), not by escaping.
+                                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;
+                        }
+                        if (Number.isFinite(deadline) && scheduler.now() + delay >= deadline) {
+                            exhausted = true;
+                            break;
+                        }
+                        await new Promise((r) => setTimeout(r, delay));
+                        delay = Math.min(delay * backoff, 30_000);
+                    }
+                    const durationMs = scheduler.now() - stepStart;
+                    const failedAssertions = scope.assertions.total - scope.assertions.passed - fBefore;
+                    const assertions = scope.assertions.total - aBefore;
+                    // ctx.skip() in fn/until skips the whole test (unless a failure/exhaustion was
+                    // already recorded — failure wins, node parity: harness.ts:2464).
+                    if (skipRequest && failedAssertions === 0 && !pollError && !exhausted) {
+                        events.emit({
+                            type: "step_end",
+                            id: scope.testMeta.id,
+                            index: idx,
+                            name: step.meta.name,
+                            status: "skipped",
+                            durationMs,
+                            assertions,
+                            failedAssertions: 0,
+                            attempts: attempt,
+                        });
+                        scope.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;
+                    events.emit({
+                        type: "poll",
+                        id: scope.testMeta.id,
+                        index: idx,
+                        name: step.meta.name,
+                        attempts: attempt,
+                        elapsedMs: Math.round(scheduler.now() - start),
+                        satisfied,
+                        exhausted,
+                        ...(pollError ? { error: pollError } : {}),
+                    });
+                    events.emit({
+                        type: "step_end",
+                        id: scope.testMeta.id,
+                        index: idx,
+                        name: step.meta.name,
+                        status: failed ? "failed" : "passed",
+                        durationMs,
+                        assertions,
+                        failedAssertions,
+                        attempts: attempt,
+                        ...(pollError ? { error: pollError } : {}),
+                    });
+                    scope.currentStepIndex = null;
+                    if (failed) {
+                        stepFailed = true;
+                        if (pollError && stepFailMsg === undefined)
+                            stepFailMsg = pollError;
+                    }
+                };
+                // Recursive step-list runner (node parity: runStepList). A prior failure
+                // skips the rest (skipped step_end tree); branch steps make a decision + recurse.
+                const runStepList = async (steps) => {
+                    for (const step of steps) {
+                        if (stepFailed || skipRequest) {
+                            emitSkippedTree([step]);
+                            continue;
+                        }
+                        const branch = branchOf(step);
+                        if (branch) {
+                            await runBranchStep(step, branch);
+                            continue;
+                        }
+                        const poll = pollOf(step);
+                        if (poll) {
+                            await runPollStep(step, poll);
+                            continue;
+                        }
+                        await runNormalStep(step);
+                    }
+                };
+                try {
+                    if (def.setup) {
+                        events.emit({ type: "log", id: scope.testMeta.id, message: "Running setup..." });
+                        state = await def.setup(ctx);
+                    }
+                    await runStepList((def.steps ?? []));
+                }
+                finally {
+                    // teardown runs even when setup/a step throws (builder contract); its
+                    // own errors never fail the run (parity with the node harness). (codex P2)
+                    if (def.teardown) {
+                        events.emit({ type: "log", id: scope.testMeta.id, message: "Running teardown..." });
+                        try {
+                            await def.teardown(ctx, state);
+                        }
+                        catch (e) {
+                            events.emit({
+                                type: "log",
+                                id: scope.testMeta.id,
+                                message: `Teardown error: ${e instanceof Error ? e.message : String(e)}`,
+                            });
+                        }
+                    }
+                }
+                // A step / branch-predicate called ctx.skip() (recorded without a throw):
+                // after teardown the whole test is skipped (node parity: harness.ts:2692).
+                if (skipRequest) {
+                    skipped = true;
+                    skipReason = skipRequest.reason;
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof SkipError) {
+                // ctx.skip() from a simple test (or setup) propagates as a throw → skipped.
+                skipped = true;
+                skipReason = e.reason;
+            }
+            else {
+                threw = true;
+                thrownError = e instanceof Error ? e.message : String(e);
+                thrownStack = e instanceof Error ? e.stack : undefined;
+                thrownName = e instanceof Error ? e.name : undefined;
+            }
+        }
+        // ctx.skip() wins over any partial assertion bookkeeping: a skipped test has no
+        // verdict (the host re-raises its own SkipError(reason) so the dispatcher emits
+        // the same skipped status as legacy). assertions are carried for completeness.
+        if (skipped) {
+            return {
+                id: scope.testMeta.id,
+                name: def.meta.name ?? def.meta.id,
+                status: "skipped",
+                ...(skipReason !== undefined ? { skipReason } : {}),
+                assertions: { ...scope.assertions },
+            };
+        }
+        // The engine does NOT emit a status EVENT — status emission is host policy:
+        // the runner emits "completed" at dispatch (and re-raises a throw so its own
+        // dispatcher reports "failed" + exit 1), the browser derives status from the
+        // RESULT. Emitting here would force one shape on both hosts and double the
+        // runner's status event (plan 0005 / codex P2).
+        const assertionsFailed = scope.assertions.total > scope.assertions.passed;
+        // Steps tests fail via stepFailed (the LAST attempt of each step) — NOT the
+        // cumulative assertion count, so a step that fails then RETRIES to success does
+        // not fail the run. Simple tests use the cumulative count (soft-fail).
+        const verdict = threw || (def.type === "steps" ? stepFailed : assertionsFailed) ? "error" : "ok";
+        return {
+            id: scope.testMeta.id,
+            name: def.meta.name ?? def.meta.id,
+            status: verdict,
+            threw,
+            // A branch decision failure promotes its message over "One or more steps failed"
+            // (node parity: harness throws `branchDecisionError ?? "One or more steps failed"`).
+            ...(stepFailed ? { stepsFailed: true, stepsFailMessage: branchDecisionError ?? "One or more steps failed" } : {}),
+            error: verdict === "ok" ? undefined : threw ? thrownError : (stepFailMsg ?? "assertion failed"),
+            // Preserve the user's original throw stack + name so a host can re-raise with
+            // them (stack diagnostics + failure classification parity — codex P2).
+            ...(threw && thrownStack ? { errorStack: thrownStack } : {}),
+            ...(threw && thrownName ? { errorName: thrownName } : {}),
+            assertions: { ...scope.assertions },
+        };
+    }
+    makeCtx(scope) {
+        const emit = (e) => this.services.events.emit(e);
+        // Aggressive array/string truncation of a PASSING assertion's actual/expected,
+        // to save tokens (node parity: harness.ts:718 — only on pass, full kept on fail).
+        const truncateArrays = this.services.http?.truncateArrays ?? false;
+        // Events emitted DURING a step carry its 0-based index (node parity); outside a
+        // step (simple tests / setup / teardown) they carry none.
+        const emitStep = (e) => emit((scope.currentStepIndex !== null ? { ...e, stepIndex: scope.currentStepIndex } : e));
+        // Extracted so ctx.validate's failure routing reuses the SAME assert/warn paths
+        // as ctx.assert / ctx.warn (node parity: harness's runSchemaValidation calls
+        // ctx.assert / ctx.warn) — same counters, same stepIndex attribution.
+        const assertFn = (condition, message, details) => {
+            const result = condition && typeof condition === "object" && "passed" in condition
+                ? condition
+                : { passed: !!condition };
+            const d = (details ?? {});
+            // `in` not `??` so an intentional null actual/expected keeps its
+            // diagnostic value (codex B4 P3).
+            const actual = "actual" in result ? result.actual : d.actual;
+            const expected = "expected" in result ? result.expected : d.expected;
+            scope.assertions.total += 1;
+            if (result.passed)
+                scope.assertions.passed += 1;
+            emitStep({
+                type: "assertion",
+                id: scope.testMeta.id,
+                passed: result.passed,
+                // Truncate on PASS to save tokens; keep full on FAIL for debugging (node parity).
+                actual: result.passed && truncateArrays ? truncateDeep(actual) : actual,
+                expected: result.passed && truncateArrays ? truncateDeep(expected) : expected,
+                // Parity with the node harness default (gap C).
+                message: message ?? (result.passed ? "Assertion passed" : "Assertion failed"),
+            });
+        };
+        const warnFn = (condition, message) => 
+        // First-class warning event (node parity) — NOT a log. condition=true means OK.
+        emitStep({ type: "warning", id: scope.testMeta.id, condition: !!condition, message: message ?? "" });
+        // Extracted so ctx.trace's derived action reuses the SAME action path as ctx.action.
+        const actionFn = (a) => emitStep({ type: "action", id: scope.testMeta.id, data: a });
+        return {
+            http: scope.http,
+            // Route through assertFn (like the node harness routes expect → ctx.assert,
+            // harness.ts:725-737) so the counters, default message, and truncate-on-pass
+            // behave identically — one assertion implementation.
+            expect: (actual) => new Expectation(actual, (r) => assertFn({ passed: r.passed, actual: r.actual, expected: r.expected }, r.message)),
+            assert: assertFn,
+            warn: warnFn,
+            validate: (data, schema, label, options) => {
+                const r = runSchemaValidation(data, schema, label ?? "data", options?.severity ?? "error", {
+                    emitSchemaValidation: (p) => emitStep({ type: "schema_validation", id: scope.testMeta.id, ...p }),
+                    assert: (passed, msg) => assertFn(passed, msg),
+                    warn: (cond, msg) => warnFn(cond, msg),
+                });
+                return r.success ? r.data : undefined;
+            },
+            vars: {
+                get: (k) => scope.runtime.vars[k],
+                require: (k, validate) => {
+                    // Empty = missing (node parity: a "" .env value with no fallback is unset).
+                    // Check the VALUE, not `k in vars`, since a fallback Proxy may report an
+                    // empty key as present (codex). Message matches the node harness.
+                    const v = scope.runtime.vars[k];
+                    if (v === undefined || v === "")
+                        throw new Error(`Missing required var: ${k}`);
+                    if (validate)
+                        runEngineValidator(validate(v), k, "var");
+                    return v;
+                },
+                // A copy of all vars (node parity: harness ctx.vars.all → {...rawVars}). Returns
+                // the RAW snapshot (host raw map + input overlay), NOT a spread of the fallback
+                // Proxy — so empty / overlay-only vars survive identically (codex Phase-8 P2).
+                all: () => ({ ...scope.varsAll }),
+            },
+            secrets: {
+                get: (k) => scope.runtime.secrets[k],
+                require: (k, validate) => {
+                    const v = scope.runtime.secrets[k];
+                    if (v === undefined || v === "")
+                        throw new Error(`Missing required secret: ${k}`);
+                    if (validate)
+                        runEngineValidator(validate(v), k, "secret");
+                    return v;
+                },
+            },
+            session: {
+                get: (k) => scope.session[k],
+                // node parity: harness.ts:652 — throws with the exact same message.
+                require: (k) => {
+                    const v = scope.session[k];
+                    if (v === undefined) {
+                        throw new Error(`Session key '${k}' is required but not set. Check your session.ts setup.`);
+                    }
+                    return v;
+                },
+                set: (k, v) => {
+                    scope.session[k] = v;
+                    // Surface the update so a host can propagate it (node: forward to sibling
+                    // tests; browser: update its store). Without this it'd be lost (codex P2).
+                    emit({ type: "session_set", id: scope.testMeta.id, key: k, value: v });
+                },
+                entries: () => ({ ...scope.session }),
+            },
+            log: (message, data) => emitStep({ type: "log", id: scope.testMeta.id, message, data }),
+            // ctx.metric — numeric perf metric. unit/tags are emitted as-is (undefined keys
+            // drop on the wire) to match the node harness exactly (harness.ts:818).
+            metric: (name, value, options) => emitStep({ type: "metric", id: scope.testMeta.id, name, value, unit: options?.unit, tags: options?.tags }),
+            // ctx.action — typed interaction record (node parity: harness.ts:790).
+            action: actionFn,
+            // ctx.trace — protocol trace event + a derived `{protocol}:request` action
+            // (node parity: harness.ts:767-787). The HTTP auto-trace routes through here.
+            trace: (request) => {
+                emitStep({ type: "trace", id: scope.testMeta.id, data: request });
+                const protocol = request.protocol ?? "http";
+                const actionTarget = request.target ??
+                    (request.method && request.url ? `${request.method} ${pathnameOf(request.url)}` : "unknown");
+                const actionDuration = request.durationMs ?? request.duration ?? 0;
+                const actionOk = request.ok ?? (typeof request.status === "number" && request.status < 400);
+                actionFn({
+                    category: `${protocol}:request`,
+                    target: actionTarget,
+                    duration: actionDuration,
+                    status: actionOk ? "ok" : "error",
+                    detail: { status: request.status },
+                });
+            },
+            // ctx.event — generic structured event. The workflow first-class unwrap is
+            // workflow-only → node-legacy (workflow is never engine-routed), so the engine
+            // always emits the generic shape (node parity: harness.ts:804 fall-through).
+            event: (ev) => emitStep({ type: "event", id: scope.testMeta.id, data: ev }),
+            // ctx.setTimeout(ms) — a CONTROL event (not step-scoped): the parent re-arms its
+            // SIGTERM deadline (node parity: harness.ts:898). No stepIndex, like legacy.
+            setTimeout: (ms) => emit({ type: "timeout_update", id: scope.testMeta.id, timeout: ms }),
+            // ctx.pollUntil — poll fn until truthy or timeout; on timeout call onTimeout
+            // (silent) or throw (node parity: harness.ts:860). Emits no events itself (fn's
+            // assertions emit as usual). Uses the injected clock + setTimeout for the wait.
+            pollUntil: async (options, fn) => {
+                const { timeoutMs, intervalMs = 1000, onTimeout } = options;
+                const deadline = this.services.scheduler.now() + timeoutMs;
+                let lastError;
+                while (this.services.scheduler.now() < deadline) {
+                    try {
+                        if (await fn())
+                            return; // truthy → done
+                    }
+                    catch (err) {
+                        lastError = err instanceof Error ? err : new Error(String(err));
+                    }
+                    const remaining = deadline - this.services.scheduler.now();
+                    if (remaining <= 0)
+                        break;
+                    await new Promise((r) => setTimeout(r, Math.min(intervalMs, remaining)));
+                }
+                if (onTimeout) {
+                    onTimeout(lastError);
+                    return;
+                }
+                throw new Error(`pollUntil timed out after ${timeoutMs}ms${lastError ? `: ${lastError.message}` : ""}`);
+            },
+            // ctx.skip(reason?) — throws; the run-loop turns it into a `skipped` verdict.
+            skip: (reason) => {
+                throw new SkipError(reason);
+            },
+            // ctx.fail(message) — emit a failed assertion THEN throw. The assertion is
+            // emitted WITHOUT a stepIndex even inside a step (node parity: harness ctx.fail
+            // uses the bare emit, not the step-scoped one), but it still bumps the assertion
+            // counter so a step/branch leg records the failure even if the throw is caught.
+            fail: (message) => {
+                scope.assertions.total += 1;
+                emit({ type: "assertion", id: scope.testMeta.id, passed: false, message });
+                throw new FailError(message);
+            },
+            retryCount: scope.retryCount,
+            // node parity: harness ctx.getMemoryUsage → process.memoryUsage(). Reached via
+            // globalThis (NOT a node:* import) so the engine stays browser-safe — null where
+            // process.memoryUsage is unavailable (browser).
+            getMemoryUsage: () => {
+                const proc = globalThis.process;
+                return typeof proc?.memoryUsage === "function" ? proc.memoryUsage() : null;
+            },
+        };
+    }
+}
+/** Resolve a SchemaEntry to {schema, severity} — a bare schema defaults to "error"
+ *  (node parity: harness resolveSchemaEntry). */
+function resolveSchemaEntry(entry) {
+    if (entry && typeof entry === "object" && "schema" in entry && entry.schema != null) {
+        const obj = entry;
+        return { schema: obj.schema, severity: obj.severity ?? "error" };
+    }
+    return { schema: entry, severity: "error" };
+}
+/** Normalize a HeadersInit (Headers / plain object / tuple array) → Record<string,
+ *  string> for schema validation (node parity: harness normalizeHeadersForValidation). */
+function normalizeHeadersForValidation(headers) {
+    if (headers == null)
+        return {};
+    if (typeof Headers !== "undefined" && headers instanceof Headers)
+        return Object.fromEntries(headers.entries());
+    if (Array.isArray(headers)) {
+        return Object.fromEntries(headers.filter((p) => Array.isArray(p) && p.length === 2));
+    }
+    if (typeof headers === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(headers))
+            if (v != null)
+                out[k] = String(v);
+        return out;
+    }
+    return {};
+}
+/** Strip a leading '/' from a relative path so ky's `prefix` join works (node parity:
+ *  harness normalizeUrl). A protocol-relative '//host' is left intact. */
+function normalizeUrl(input) {
+    if (typeof input === "string" && input.startsWith("/") && !input.startsWith("//"))
+        return input.slice(1);
+    return input;
+}
+/**
+ * Wrap a per-run ky instance into the public ctx.http facade. A Proxy preserves the
+ * full KyInstance surface and adds, on calls + `.extend()`:
+ *  - prefixUrl → ky 2 `prefix` + empty-searchParams removal (node parity: harness
+ *    normalizeOptions / normalizeUrl).
+ *  - automatic schema validation: request body / query / request headers BEFORE the
+ *    request, response headers via an injected afterResponse hook, and response body
+ *    by monkey-patching the response promise's `.json()` — all routed through the
+ *    run's ctx.validate (→ schema_validation event + severity routing), node parity:
+ *    harness wrapKy / runPreRequestSchemaValidation / wrapResponseWithSchema.
+ */
+function wrapScopedKy(instance, scope) {
+    // prefixUrl → ky 2 `prefix`, and drop an empty searchParams (no bare '?'). `schema`
+    // is RETAINED here (callWithSchema reads it, then strips it before handing to ky).
+    const normalizeKyOptions = (opts) => {
+        if (!opts || typeof opts !== "object")
+            return opts;
+        const n = { ...opts };
+        if ("prefixUrl" in n) {
+            n.prefix = n.prefixUrl;
+            delete n.prefixUrl;
+        }
+        const sp = n.searchParams;
+        if (sp != null) {
+            const empty = (typeof URLSearchParams !== "undefined" && sp instanceof URLSearchParams && sp.toString() === "") ||
+                (typeof sp === "string" && sp === "") ||
+                (typeof sp === "object" && !(sp instanceof URLSearchParams) && !Array.isArray(sp) && Object.keys(sp).length === 0);
+            if (empty)
+                delete n.searchParams;
+        }
+        return n;
+    };
+    // Route a schema validation through the run's ctx (→ schema_validation event +
+    // severity routing). A request before makeCtx never happens during a run, so the
+    // optional-chain is just defensive.
+    const validate = (data, entry, label) => {
+        const { schema, severity } = resolveSchemaEntry(entry);
+        scope.ctxRef?.validate(data, schema, label, { severity });
+    };
+    const preRequest = (opts) => {
+        const schemaOpts = opts?.schema;
+        if (!schemaOpts)
+            return;
+        if (schemaOpts.query && opts?.searchParams != null)
+            validate(opts.searchParams, schemaOpts.query, "query params");
+        if (schemaOpts.request && opts?.json !== undefined)
+            validate(opts.json, schemaOpts.request, "request body");
+        if (schemaOpts.requestHeaders && opts?.headers != null) {
+            validate(normalizeHeadersForValidation(opts.headers), schemaOpts.requestHeaders, "request headers");
+        }
+    };
+    // Strip the non-ky `schema` option, injecting a response-headers afterResponse hook
+    // when a responseHeaders schema is present (fires once per final response).
+    const toKyOptions = (opts) => {
+        if (!opts)
+            return opts;
+        const schemaOpts = opts.schema;
+        const { schema: _schema, ...rest } = opts;
+        let kyOptions = rest;
+        if (schemaOpts?.responseHeaders) {
+            const entry = schemaOpts.responseHeaders;
+            const hook = ({ response }) => validate(normalizeHeadersForValidation(response.headers), entry, "response headers");
+            const hooks = (kyOptions.hooks ?? {});
+            kyOptions = { ...kyOptions, hooks: { ...hooks, afterResponse: [...(hooks.afterResponse ?? []), hook] } };
+        }
+        return kyOptions;
+    };
+    // Monkey-patch the ky ResponsePromise's `.json()` shortcut to validate the parsed
+    // body. EXACT node-harness parity (harness.ts:1249-1268): only the promise shortcut
+    // (`http.get(url, {schema}).json()`) is patched, NOT the resolved Response — so an
+    // `await`-first-then-`res.json()` flow bypasses response-schema validation on BOTH
+    // legs identically (codex 4f P2). This is a shared legacy limitation, not an engine
+    // divergence; "fixing" it engine-only would break byte-parity. Any real fix must
+    // land in both legs (post-cutover), so the engine intentionally mirrors legacy here.
+    const wrapResponse = (promise, opts) => {
+        const schemaOpts = opts?.schema;
+        if (!schemaOpts?.response)
+            return promise;
+        const entry = schemaOpts.response;
+        const originalJson = promise.json.bind(promise);
+        promise.json = async () => {
+            const body = await originalJson();
+            validate(body, entry, "response body");
+            return body;
+        };
+        return promise;
+    };
+    const callWithSchema = (kyCall, input, opts) => {
+        const normalized = normalizeKyOptions(opts);
+        preRequest(normalized);
+        const promise = kyCall(normalizeUrl(input), toKyOptions(normalized));
+        return wrapResponse(promise, normalized);
+    };
+    return new Proxy(instance, {
+        apply: (target, _thisArg, args) => callWithSchema((u, o) => target(u, o), args[0], args[1]),
+        get: (target, prop, recv) => {
+            if (prop === "extend") {
+                return (opts) => wrapScopedKy(target.extend(typeof opts === "function"
+                    ? ((parent) => normalizeKyOptions(opts(parent)))
+                    : normalizeKyOptions(opts)), scope);
+            }
+            const value = Reflect.get(target, prop, recv);
+            if (typeof value === "function" && typeof prop === "string" && HTTP_METHODS.has(prop)) {
+                return (url, opts) => callWithSchema((u, o) => value.call(target, u, o), url, opts);
+            }
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+// Only the Stage-1 supported markers — a `workflow-builder` also has __glubean_type
+// + build(), but the narrow engine has no workflow ctx, so building it would yield
+// a def that fails at runtime. Leave workflows unresolved until Stage 2. (codex B4 P2)
+function isBuilder(v) {
+    const marker = v?.__glubean_type;
+    return (!!v &&
+        typeof v === "object" &&
+        typeof v.build === "function" &&
+        (marker === "builder" || marker === "each-builder"));
+}
+function isSdkTest(v) {
+    return (!!v &&
+        typeof v === "object" &&
+        "meta" in v &&
+        "type" in v &&
+        (v.type === "simple" || v.type === "steps"));
+}
+// TestBuilder → Test, EachBuilder → Test[]. Otherwise pass through (workflow
+// builders are NOT built — see isBuilder).
+function autoResolveDef(v) {
+    return isBuilder(v) ? v.build() : v;
+}
+// A built workflow handle is an array tagged __glubean_type "workflow" (builder.ts).
+// Workflows are Stage 2 (no workflow ctx here), so exclude them entirely. (codex B4 P2)
+function isWorkflowHandle(v) {
+    return !!v && typeof v === "object" && v.__glubean_type === "workflow";
+}
+// test.extend() tests carry a non-empty `fixtures` map. Fixtures are Stage 2;
+// excluding keeps us from running an extended test without its fixtures. (codex B4 P2)
+function hasFixtures(v) {
+    const f = v?.fixtures;
+    return !!f && typeof f === "object" && Object.keys(f).length > 0;
+}
+// A resolved value the narrow Stage-1 engine can actually run.
+function pushIfRunnable(v, out) {
+    if (isWorkflowHandle(v) || !isSdkTest(v) || hasFixtures(v))
+        return;
+    out.push(toTestDef(v));
+}
+function collectDefs(value, out) {
+    if (isWorkflowHandle(value))
+        return;
+    const resolved = autoResolveDef(value);
+    if (isWorkflowHandle(resolved))
+        return;
+    if (isSdkTest(resolved)) {
+        pushIfRunnable(resolved, out);
+        return;
+    }
+    if (Array.isArray(resolved)) {
+        for (const item of resolved) {
+            if (isWorkflowHandle(item))
+                continue;
+            const r = autoResolveDef(item);
+            if (isWorkflowHandle(r))
+                continue;
+            if (Array.isArray(r)) {
+                for (const inner of r)
+                    pushIfRunnable(inner, out);
+            }
+            else {
+                pushIfRunnable(r, out);
+            }
+        }
+    }
+}
+export function toTestDef(t) {
+    const tags = Array.isArray(t.meta.tags) ? t.meta.tags : typeof t.meta.tags === "string" ? [t.meta.tags] : undefined;
+    // SDK step fns take the SDK TestContext; the engine provides the narrow subset
+    // at runtime, so the cast is sound for the Stage-1 surface.
+    return {
+        meta: { id: t.meta.id, name: t.meta.name, tags, skip: t.meta.skip, only: t.meta.only },
+        type: t.type,
+        fn: t.fn,
+        setup: t.setup,
+        steps: t.steps,
+        teardown: t.teardown,
+    };
+}
+//# sourceMappingURL=engine.js.map