@glubean/runner 0.4.1 → 0.7.0

package/dist/workflow/execute.js

@@ -0,0 +1,1475 @@
+/**
+ * @module workflow/execute
+ *
+ * vNext `workflow` EXECUTOR — the per-node runtime harness.
+ *
+ * GOVERNING PRINCIPLE (2026-06-09): no backward compatibility. Where `runFlow`
+ * (`contract-core.ts`) and the `test()` harness (`packages/runner`) diverge, this
+ * executor picks the ONE rule decided in the proposal §17 self-consistency corpus
+ * and every node obeys it. See `internal/40-discovery/proposals/contract-workflow-vnext.md`.
+ *
+ * This slice (S2.0) builds the foundation every later node type stands on:
+ *   - a per-node derived child ctx (`makeNodeScope`) that attributes evidence to
+ *     the node, tracks its pass/fail + structured-evidence emission, and — after
+ *     the node settles — QUARANTINES any late evidence the body still emits (§17 #12);
+ *   - `runNode`: brackets the node with `workflow:node_start` / `:node_end`
+ *     events, runs the body under a per-node `AbortController`, and enforces a
+ *     TERMINAL per-node timeout (no retry; §17 #4) that aborts the node (§17 #12).
+ *
+ * On top of it: `runWorkflow` walks setup → nodes → teardown (S2.1); `runBranch`
+ * runs only the taken side (S2.4a, §17 #6); `runPollNode` is the bounded
+ * poll-until with per-attempt quarantine (S2.4b, §17 #3). Control-flow nodes
+ * (branch/poll) own their bracket/bounds and are dispatched by `runNodeList`,
+ * not `runNode`; remaining reserved kinds throw "not implemented yet".
+ */
+// The workflow executor lives in @glubean/runner (node-only) as of plan 0007. It is
+// execution semantics, not authoring DSL, and it legitimately uses node:async_hooks
+// (the runner is node-only). Its SDK dependencies are split: authoring/projection
+// types + GlubeanSkipError + Expectation come from the public surface; the shared
+// runtime primitives (contract adapters, predicate eval, poll primitives, static
+// grading, retry validation) come through the @glubean/sdk/internal bridge.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { GlubeanSkipError } from "@glubean/sdk";
+import { Expectation } from "@glubean/sdk/expect";
+import { getAdapter, validateNeedsOutput, evalPredicate, extractPredicate, resolvePath, quarantinedCtx, raceBudget, validatePollBounds, PollExhaustedError, BACKOFF_CAP_MS, DEFAULT_EVERY_MS, staticGradeOf, validateRetryMeta, } from "@glubean/sdk/internal";
+/**
+ * Human-readable label for a declarative expect item (phase4 §7.2) — derived
+ * from the extracted predicate, never authored, so it cannot drift from what
+ * actually evaluates. Used for assertion-event messages.
+ */
+export function predicateLabel(p) {
+    switch (p.kind) {
+        case "compare": {
+            const OPS = { eq: "==", ne: "!=", gt: ">", gte: ">=", lt: "<", lte: "<=" };
+            const lhs = p.path.join(".") || "<state>";
+            const rhs = p.rhsPath !== undefined ? p.rhsPath.join(".") : JSON.stringify(p.value);
+            return `${lhs} ${OPS[p.op] ?? p.op} ${rhs}`;
+        }
+        case "in":
+            return `${p.path.join(".")} in ${JSON.stringify(p.values)}`;
+        case "presence":
+            return `${p.path.join(".")} ${p.op}`;
+        case "matches":
+            return `${p.path.join(".")} matches /${p.pattern}/${p.flags ?? ""}`;
+        case "and":
+            return p.clauses.map(predicateLabel).join(" && ");
+        case "or":
+            return `(${p.clauses.map(predicateLabel).join(" || ")})`;
+        case "not":
+            return `not(${predicateLabel(p.clause)})`;
+        case "opaque":
+            return "<opaque predicate>";
+    }
+}
+// =============================================================================
+// Active-node context channel (§17 #9/#12 — the ctx.http rebind, S2.10)
+// =============================================================================
+/**
+ * The per-node child ctx of the CURRENTLY EXECUTING workflow node body.
+ *
+ * The host harness pre-binds `ctx.http`'s auto-trace/metric hooks to the
+ * test-level ctx at construction, so inline HTTP inside a workflow node used
+ * to bypass the node scope entirely — no attribution (an opaque HTTP action
+ * never promoted to `trace`, §17 #10) and no late-evidence quarantine
+ * (§17 #12). The executor now runs every node body inside this
+ * AsyncLocalStorage scope; the harness's hooks ask for the active node ctx
+ * FIRST and fall back to their own closure ctx (non-workflow tests see no
+ * behavior change).
+ */
+const activeNodeCtx = new AsyncLocalStorage();
+/**
+ * Host integration point (used by @glubean/runner's http hooks): the ctx that
+ * observability emitted DURING a workflow node body should be attributed to,
+ * or undefined outside any workflow node.
+ */
+export function __activeWorkflowNodeCtx() {
+    return activeNodeCtx.getStore();
+}
+/** Run a node body (or attempt/decision) attributed to `ctx`. */
+function withActiveNodeCtx(ctx, fn) {
+    return activeNodeCtx.run(ctx, fn);
+}
+// =============================================================================
+// Per-node evidence events (§17 #9)
+// =============================================================================
+/**
+ * Per-node boundary events ride the generic `ctx.event` channel for this slice
+ * (zero runner-package change — they reach the timeline as namespaced
+ * `GlubeanEvent`s). S2.5 decides whether to promote them to first-class
+ * `node_start` / `node_end` event kinds for richer Cloud rendering.
+ */
+export const NODE_START_EVENT = "workflow:node_start";
+export const NODE_END_EVENT = "workflow:node_end";
+// =============================================================================
+// Timeout (§17 #4 — terminal, never retried) + abort (§17 #12)
+// =============================================================================
+/** A node exceeded its `timeout`. TERMINAL — the node is not retried (§17 #4). */
+export class NodeTimeoutError extends Error {
+    nodeId;
+    timeoutMs;
+    constructor(nodeId, timeoutMs) {
+        super(`workflow node "${nodeId}" timed out after ${timeoutMs}ms`);
+        this.name = "NodeTimeoutError";
+        this.nodeId = nodeId;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * A workflow phase (setup, or a node) FAILED via soft assertions/validation —
+ * nothing was thrown, so `runNode` has no `error` to report. The executor
+ * synthesizes this as the run's `cause` so teardown + the result carry a
+ * non-empty failure even for the pure soft-failure path (codex S2.1 P2).
+ */
+export class WorkflowPhaseFailedError extends Error {
+    workflowId;
+    phase;
+    constructor(workflowId, phase) {
+        super(`workflow "${workflowId}" ${phase} failed (soft assertion/validation)`);
+        this.name = "WorkflowPhaseFailedError";
+        this.workflowId = workflowId;
+        this.phase = phase;
+    }
+}
+/**
+ * A `compute` node returned a thenable — an async fn, or (the case the builder
+ * can't catch) a sync fn that returns a Promise. compute MUST be synchronous and
+ * I/O-free; the executor FAILS the node rather than committing the Promise as
+ * state, so async/I/O can't masquerade as a `full` pure transform (§17 #11).
+ */
+export class ComputeAsyncError extends Error {
+    nodeId;
+    constructor(nodeId) {
+        super(`workflow compute "${nodeId}" returned a thenable — compute must be ` +
+            `synchronous and I/O-free; use .action() for async work`);
+        this.name = "ComputeAsyncError";
+        this.nodeId = nodeId;
+    }
+}
+export function makeNodeScope(base, signal) {
+    let live = true;
+    let failed = false;
+    let structured = false;
+    // Single gate for every emit: while live, record flags + forward to the real
+    // ctx; once sealed, do NOTHING (drop the late emission, leave flags untouched —
+    // the node's verdict is already fixed). `run` returns its value so accessors
+    // that must yield a sound result to the (now-abandoned) body still can.
+    const onEvidence = (flags, forward) => {
+        if (!live)
+            return;
+        if (flags.failed)
+            failed = true;
+        if (flags.structured)
+            structured = true;
+        forward();
+    };
+    // `Object.create(base)` (not a spread) so prototype-inherited APIs survive — a
+    // fixture-augmented ctx (test.extend) carries vars/http/log/etc. on its
+    // prototype chain. Only the APIs below are overridden; everything else resolves
+    // through `base`.
+    //
+    // `ctx.http` rebind (closes the S2.0 known limitation): the host's ky hooks
+    // are pre-bound to the test-level ctx, so the executor runs every node body
+    // inside the activeNodeCtx ALS scope and the harness's hooks route their
+    // auto-trace/metric through `__activeWorkflowNodeCtx()` first — inline HTTP
+    // inside a node now attributes to THIS scope (opaque HTTP actions promote to
+    // `trace`, §17 #10) and is quarantined after seal (§17 #12).
+    const ctx = Object.assign(Object.create(base), {
+        signal,
+        assert: (a, message, details) => {
+            const passed = typeof a === "boolean" ? a : a.passed;
+            onEvidence({ failed: !passed, structured: true }, () => base.assert(a, message, details));
+        },
+        expect: (actual) => new Expectation(actual, (result) => {
+            onEvidence({ failed: !result.passed, structured: true }, () => base.assert({ passed: result.passed, actual: result.actual, expected: result.expected }, result.message));
+        }),
+        validate: (data, schema, label, options) => {
+            // Run the schema NOW regardless of liveness — the body consumes the return
+            // value (mirrors `quarantinedCtx.validate`). Supports both safeParse and
+            // parse-only SchemaLikes. Only the EMIT + failure flag + fatal-throw are
+            // gated on liveness.
+            const s = schema;
+            let ok = true;
+            let value;
+            if (typeof s.safeParse === "function") {
+                const r = s.safeParse(data);
+                ok = r.success;
+                value = r.success ? r.data : undefined;
+            }
+            else if (typeof s.parse === "function") {
+                try {
+                    value = s.parse(data);
+                }
+                catch {
+                    ok = false;
+                }
+            }
+            else {
+                // Neither safeParse nor parse — an unusable schema. The delegated
+                // base.validate still records a failed validation, so this scope must
+                // count it as a failure too, else runNode would report `passed` despite
+                // failed validation evidence (codex S2.0 R2 P2).
+                ok = false;
+            }
+            const severity = options?.severity ?? "error";
+            onEvidence({ failed: !ok && severity !== "warn", structured: true }, () => base.validate(data, schema, label, options));
+            // `severity: "fatal"` aborts the body at the validation point — preserve
+            // that control flow, but only while live (a sealed node is already done).
+            if (live && !ok && severity === "fatal") {
+                throw new Error(`fatal validation failed: ${label ?? "data"}`);
+            }
+            return value;
+        },
+        // `fail` emits a failed assertion AND aborts the body. It must NOT delegate to
+        // `base.fail` (that would mutate the real ctx even from a sealed/abandoned
+        // node). Emit (gated) + throw (always — the throw is control flow, not leaked
+        // evidence).
+        fail: (message) => {
+            onEvidence({ failed: true, structured: true }, () => base.assert({ passed: false }, message));
+            throw new Error(message);
+        },
+        // `skip` is pure control flow (emits nothing). OVERRIDE it (don't inherit
+        // base.skip) so a node skip throws the SDK `GlubeanSkipError` REGARDLESS of
+        // what the host ctx's skip throws — the real runner's `ctx.skip` throws its
+        // own private `SkipError` (harness.ts:692), which `runNode`'s instanceof check
+        // would miss. Overriding makes the skip shape the executor's own, not the
+        // host's (codex S2.0 R2 P1; no-compat — workflow owns its skip semantics).
+        skip: (reason) => {
+            throw new GlubeanSkipError(reason);
+        },
+        warn: (condition, message) => onEvidence({}, () => base.warn(condition, message)),
+        // Structured observability that DOES count toward opaque→trace (§17 #10).
+        trace: (request) => onEvidence({ structured: true }, () => base.trace(request)),
+        metric: (name, value, options) => onEvidence({ structured: true }, () => base.metric(name, value, options)),
+        // Non-structured channels: forwarded while live, never promote the grade.
+        action: (a) => onEvidence({}, () => base.action(a)),
+        event: (ev) => onEvidence({}, () => base.event(ev)),
+        log: (message, data) => onEvidence({}, () => base.log(message, data)),
+    });
+    return {
+        ctx,
+        hasFailure: () => failed,
+        emittedStructuredEvidence: () => structured,
+        seal: () => {
+            live = false;
+        },
+    };
+}
+// =============================================================================
+// Grade promotion (§17 #10)
+// =============================================================================
+/**
+ * Runtime grade = the static floor, promoted from `opaque` → `trace` iff the node
+ * emitted structured evidence at run time (§17 #10). `full` / `partial` are never
+ * promoted (they are already as good as or better than `trace`).
+ */
+export function promoteGrade(staticGrade, scope) {
+    return staticGrade === "opaque" && scope.emittedStructuredEvidence()
+        ? "trace"
+        : staticGrade;
+}
+function emitNodeStart(base, node, attempt) {
+    const data = {
+        nodeId: node.meta.id,
+        kind: node.kind,
+        name: node.meta.name ?? node.meta.id,
+    };
+    if (attempt) {
+        data.attempt = attempt.n;
+        data.attempts = attempt.of;
+    }
+    base.event({ type: NODE_START_EVENT, data });
+}
+function emitNodeEnd(base, node, status, grade, durationMs, error, attempt) {
+    const data = {
+        nodeId: node.meta.id,
+        kind: node.kind,
+        name: node.meta.name ?? node.meta.id,
+        status,
+        grade,
+        durationMs,
+    };
+    if (error !== undefined)
+        data.error = error instanceof Error ? error.message : String(error);
+    if (attempt) {
+        data.attempt = attempt.n;
+        data.attempts = attempt.of;
+    }
+    base.event({ type: NODE_END_EVENT, data });
+}
+// `validateRetryMeta` (§17 #7 retry validation) moved to the SDK (`workflow/retry.ts`)
+// when the executor relocated here (plan 0007): it is shared with the authoring-side
+// builder. Imported from @glubean/sdk/internal above; still called by the executor
+// before looping (an `as any`/JS caller could smuggle an invalid retry past the types).
+/** True for a Promise or any Promise-like (`.then` is a function). */
+function isThenable(v) {
+    return v != null && typeof v.then === "function";
+}
+/**
+ * Execute ONE in-graph contract-case invocation (§17 #8). Independent of the flow
+ * engine (which gets deleted — plan fork a): dispatch through the PUBLIC adapter
+ * registry and call the protocol-neutral `executeCaseInFlow`. Covers the adapter
+ * lookup, the third-party `validateCaseForFlow` veto (mirrors contract-core.ts:818),
+ * the `needs` validation at the call boundary (contract-core.ts:1402-1427 parity;
+ * codex S2.1 R4 P2), and the `in` lens (PURE SYNCHRONOUS — thenables rejected,
+ * codex S2.1 R7). Shared by `.call` (one shot, node signal) and `.poll` (one
+ * invocation per attempt, per-attempt budget signal + quarantined ctx).
+ */
+async function executeCallAttempt(kind, node, ctx, state, signal) {
+    const label = `workflow ${kind} "${node.meta.id}"`;
+    const adapter = getAdapter(node.ref.protocol);
+    if (!adapter?.executeCaseInFlow) {
+        throw new Error(`${label}: protocol "${node.ref.protocol}" ` +
+            (adapter
+                ? "does not implement executeCaseInFlow — it cannot be called in a workflow"
+                : "has no registered adapter (did you import its contract plugin package?)"));
+    }
+    // Third-party adapter veto: a protocol can reject specific cases from in-graph use
+    // (§17 #8, the validateCaseForFlow half — a third-party slot; built-in adapters
+    // don't implement it).
+    adapter.validateCaseForFlow?.(node.ref.contract._spec, node.ref.caseKey, node.ref.contractId);
+    const contractSpec = node.ref.contract._spec;
+    const needsSchema = contractSpec?.cases?.[node.ref.caseKey]?.needs;
+    const caseId = `${node.ref.contractId}.${node.ref.caseKey}`;
+    if (needsSchema && typeof node.in !== "function") {
+        throw new Error(`${label}: case "${caseId}" declares \`needs\` but the ` +
+            `${kind} has no \`in\` binding. Provide \`in: (state) => <logical input>\`.`);
+    }
+    let resolvedInputs = node.in ? node.in(state) : undefined;
+    if (isThenable(resolvedInputs)) {
+        throw new Error(`${label}: \`in\` returned a thenable — in must be a ` +
+            `pure synchronous lens (state) => input; do async work in .action()`);
+    }
+    if (needsSchema) {
+        resolvedInputs = validateNeedsOutput(needsSchema, resolvedInputs, { testId: caseId, source: "workflow" });
+    }
+    return adapter.executeCaseInFlow({
+        ctx,
+        // The adapter owns the contract's concrete spec type; the ref carries the live
+        // instance. Cast at this protocol-neutral seam (mirrors contract-core.ts:1431).
+        contract: node.ref.contract,
+        caseKey: node.ref.caseKey,
+        resolvedInputs,
+        ...(node.accept ? { accept: node.accept } : {}),
+        ...(signal ? { signal } : {}),
+    });
+}
+/**
+ * Invoke a contract case IN-GRAPH for a `.call` node: one `executeCallAttempt`
+ * under the node's ctx + signal, then the `out` lens. `in` maps state → the
+ * case's logical input; `out` folds the raw response back into state (no `out`
+ * → response discarded, state preserved, like runFlow contract-core.ts:1625-1628).
+ */
+async function runContractCall(node, ctx, state, scope) {
+    const res = await executeCallAttempt("call", node, ctx, state, ctx.signal);
+    // If the adapter already recorded a soft failure (scoped expect/validate on a
+    // failing case), STOP before `out`: an out lens that assumes the validated success
+    // shape would throw and become the cause, masking the real validation failure.
+    // runNode then fails the node on hasFailure() with a synthesized cause (codex S2.1 R7).
+    if (scope.hasFailure()) {
+        return state; // preserve; the node fails on the recorded failure, not via `out`
+    }
+    // `out` REPLACES state; absent `out` returns undefined → §17 #2 preserves it.
+    // `out` is a PURE SYNCHRONOUS lens — reject a thenable result so async/I/O can't
+    // hide inside a `full`-graded call lens (mirrors compute, §17 #11; codex S2.1 R6).
+    const next = node.out ? node.out(state, res) : undefined;
+    if (isThenable(next)) {
+        throw new Error(`workflow call "${node.meta.id}": \`out\` returned a thenable — out must be a ` +
+            `pure synchronous lens (state, res) => state; do async work in .action()`);
+    }
+    return next;
+}
+/** Dispatch a node's body to its kind-specific executor. */
+function runBody(node, ctx, state, scope) {
+    switch (node.kind) {
+        case "action":
+            return Promise.resolve(node.fn(ctx, state));
+        case "check": {
+            const check = node;
+            // DECLARATIVE form (phase4 §7): pure evaluation, one assertion event
+            // per item, soft semantics (§17 #5) — the node fails iff any item
+            // failed, via the scope's existing hasFailure aggregation. No user
+            // code runs.
+            if (check.expects !== undefined) {
+                for (const item of check.expects) {
+                    const extracted = extractPredicate(item);
+                    ctx.assert(evalPredicate(item, state), predicateLabel(extracted));
+                }
+                return Promise.resolve(undefined);
+            }
+            // `as any`/JS construction can hand a check with NEITHER form — the
+            // type is an XOR union, but fail fast for bypassers (codex S2.17 R2).
+            if (typeof check.fn !== "function") {
+                throw new Error(`workflow check "${node.meta.id}": needs an inline fn or { expect: [...] }`);
+            }
+            // A check returns void → it never changes state (resolve to `undefined` so
+            // the caller's §17 #2 "void preserves" rule keeps the prior state).
+            return Promise.resolve(check.fn(ctx, state)).then(() => undefined);
+        }
+        case "compute": {
+            // Pure synchronous transform; the return REPLACES state (§17 #2/#13). The
+            // builder rejects `async` compute syntactically; here we also catch a sync fn
+            // that RETURNS a thenable (JS / cast bypass) — fail the node, never commit the
+            // Promise as state (§17 #11).
+            const result = node.fn(state);
+            if (isThenable(result)) {
+                throw new ComputeAsyncError(node.meta.id);
+            }
+            return Promise.resolve(result);
+        }
+        case "contract-call":
+            return runContractCall(node, ctx, state, scope);
+        case "branch":
+        case "poll":
+            // Control-flow nodes own their bracket/bounds — runNodeList dispatches them
+            // to runBranch / runPollNode directly, never through runNode.
+            throw new Error(`runNode: "${node.kind}" nodes run via the node-list dispatcher, not runNode`);
+        default:
+            throw new Error(`runNode: node kind "${node.kind}" is not implemented yet (lands in a later slice)`);
+    }
+}
+/**
+ * Run ONE node: bracket it with node_start/node_end, execute its body under a
+ * per-node child ctx + `AbortController`, enforce a TERMINAL timeout (§17 #4),
+ * and quarantine any late evidence after the node settles (§17 #12). Returns the
+ * verdict + the state to carry forward (commit-on-success, §17 #13).
+ */
+export async function runNode(base, node, state, opts) {
+    const ac = new AbortController();
+    const scope = makeNodeScope(base, ac.signal);
+    const started = Date.now();
+    // One grade per settle path, shared by the node_end event AND the result so
+    // they always agree; `adjustGrade` lets the retry wrapper tie promotion to
+    // host-visible evidence (codex S2.5 R5 P2). Called only after settle().
+    const finalGrade = (status, error) => {
+        const computed = promoteGrade(opts.staticGrade, scope);
+        return opts.adjustGrade
+            ? opts.adjustGrade(computed, {
+                structured: scope.emittedStructuredEvidence(),
+                status,
+                error,
+            })
+            : computed;
+    };
+    emitNodeStart(base, node, opts.attempt);
+    let timer;
+    const hasTimeout = opts.timeoutMs != null && Number.isFinite(opts.timeoutMs);
+    const settle = () => {
+        // Order matters: seal BEFORE clearing the timer so a body that races the
+        // timer can't slip an emission through the gap.
+        scope.seal();
+        if (timer !== undefined)
+            clearTimeout(timer);
+    };
+    try {
+        const body = withActiveNodeCtx(scope.ctx, () => runBody(node, scope.ctx, state, scope));
+        const raced = hasTimeout
+            ? Promise.race([
+                body,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        // Seal BEFORE aborting: `ac.abort()` runs abort listeners
+                        // synchronously, and a listener that emits evidence must be
+                        // quarantined too — sealing first stops it leaking past the timeout
+                        // boundary or promoting the grade (codex S2.0 R3 P2).
+                        scope.seal();
+                        ac.abort();
+                        reject(new NodeTimeoutError(node.meta.id, opts.timeoutMs));
+                    }, opts.timeoutMs);
+                }),
+            ])
+            : body;
+        const returned = await raced;
+        settle();
+        if (scope.hasFailure()) {
+            // Body resolved but a soft assertion failed → node fails, no commit (§17 #13).
+            // Abort the signal too (as timeout/throw do) so any cooperative work the node
+            // started observes the failure and stops — the WorkflowContext signal contract.
+            if (!ac.signal.aborted)
+                ac.abort();
+            const grade = finalGrade("failed");
+            opts.beforeNodeEnd?.("failed", undefined);
+            emitNodeEnd(base, node, "failed", grade, Date.now() - started, undefined, opts.attempt);
+            return { status: "failed", state, grade };
+        }
+        // Success: return REPLACES state; void/undefined PRESERVES it (§17 #2 / #13).
+        const nextState = returned === undefined ? state : returned;
+        const grade = finalGrade("passed");
+        opts.beforeNodeEnd?.("passed", undefined);
+        emitNodeEnd(base, node, "passed", grade, Date.now() - started, undefined, opts.attempt);
+        return { status: "passed", state: nextState, grade };
+    }
+    catch (err) {
+        settle();
+        // Ensure the body's signal fires even on a thrown (non-timeout) failure, so a
+        // dangling async leg observes the abort.
+        if (!ac.signal.aborted)
+            ac.abort();
+        // `ctx.skip()` is control flow, not a failure: a node that deliberately skips
+        // (and had no earlier failed assertion) settles `skipped`, NOT `failed` — a
+        // failed assertion before the skip still wins (mirrors harness.ts:2297). The
+        // skip is preserved on `err` so the caller (runWorkflow, S2.1) can decide its
+        // graph-level meaning (skip the rest vs. continue); runNode only classifies.
+        if (err instanceof GlubeanSkipError && !scope.hasFailure()) {
+            const grade = finalGrade("skipped", err);
+            opts.beforeNodeEnd?.("skipped", err);
+            emitNodeEnd(base, node, "skipped", grade, Date.now() - started, undefined, opts.attempt);
+            return { status: "skipped", state, grade, error: err };
+        }
+        // A skip thrown AFTER a soft failure is NOT the cause — the prior failure is.
+        // Drop the skip so runWorkflow synthesizes a proper phase-failure cause; a real
+        // thrown error / timeout stays as the cause (codex S2.1 R4 P3).
+        const failError = err instanceof GlubeanSkipError ? undefined : err;
+        const grade = finalGrade("failed", failError);
+        opts.beforeNodeEnd?.("failed", failError);
+        emitNodeEnd(base, node, "failed", grade, Date.now() - started, failError, opts.attempt);
+        return { status: "failed", state, grade, error: failError };
+    }
+}
+/**
+ * Derive a lifecycle (setup/teardown) child ctx + its `AbortController` — same
+ * per-node attribution + late-evidence quarantine as a graph node, AND the same
+ * failure-abort guarantee: the caller aborts the signal when the phase fails, so
+ * signal-aware async work the body started gets cancelled (codex S2.1 R2). No
+ * per-node timeout for this slice (§17 #4 timeout on setup/teardown lands later).
+ */
+function deriveLifecycleScope(base) {
+    const ac = new AbortController();
+    return { scope: makeNodeScope(base, ac.signal), ac };
+}
+/**
+ * Record nodes in `list` from `startIndex` onward as `skipped` (emit end-only — they
+ * never started). Indexed by POSITION, not `meta.id`, so two nodes that accidentally
+ * share an id both still get an outcome (the builder doesn't reject dup ids — codex
+ * S2.1 R3 P3). A skipped branch node is recorded as one `skipped` node (its sides are
+ * not expanded — they never ran).
+ */
+function emitNodesSkipped(baseCtx, list, outcomes, startIndex) {
+    for (let i = startIndex; i < list.length; i++) {
+        const node = list[i];
+        const grade = staticGradeOf(node);
+        emitNodeEnd(baseCtx, node, "skipped", grade, 0);
+        outcomes.push({ id: node.meta.id, status: "skipped", grade });
+        // RECURSIVE (phase4 §2.4 / design-R2): summary and Cloud count nodes from
+        // per-child node_end events. A skipped GROUP's members are a definite
+        // execution list — they must each report. A skipped BRANCH's case
+        // sub-graphs get the same treatment for consistency with the executed
+        // branch path, which emits skipped node_ends for every non-taken case.
+        if (node.kind === "group") {
+            emitNodesSkipped(baseCtx, node.nodes, outcomes, 0);
+        }
+        else if (node.kind === "branch") {
+            const b = node;
+            for (const c of b.cases)
+                emitNodesSkipped(baseCtx, c.nodes, outcomes, 0);
+            if (b.default)
+                emitNodesSkipped(baseCtx, b.default, outcomes, 0);
+        }
+    }
+}
+/** Is this `when` an L1/L0 opaque predicate (vs an L2 declarative `BranchPredicate`)? */
+function isOpaquePredicate(when) {
+    return when.kind === "opaque";
+}
+/**
+ * Decide the taken case of a branch-family node (addendum §9).
+ *
+ * - value mode: run the `on` lens (pure + synchronous — thenables rejected,
+ *   mirrors call's `in`), === match against the literal case table.
+ * - predicate mode: ordered first-match. L2 declarative → pure synchronous
+ *   `evalPredicate`; an opaque fn (branch's whenRuntime) runs under the node's
+ *   child ctx (may read ctx + emit evidence; async awaited). A non-boolean
+ *   opaque result is rejected, not coerced (codex S2.4a P2).
+ *
+ * No match → "default" (which the caller maps to the `default` nodes, or — for
+ * switch with no default — the identity pass-through).
+ */
+async function selectBranchCase(node, state, ctx) {
+    if (node.mode === "value") {
+        // S2.18 lens-purity: the runtime dispatches via SAFE PATH RESOLUTION over
+        // the extracted onPath — the projection and the execution share one truth
+        // (the live lens is not kept on the node). A missing path yields
+        // `undefined`, which `===`-matches no JSON-scalar case → default/identity
+        // (the missing-operand rule). `as any`/JS callers without an onPath get
+        // the same no-match behavior rather than a crash.
+        const discriminant = node.onPath !== undefined ? resolvePath(state, node.onPath) : undefined;
+        // A thenable at the path (an unawaited request stored into state by an
+        // earlier action) must FAIL, not silently fall through to default —
+        // taking the wrong branch on a pending value is misrouting, not a
+        // no-match (codex S2.18 R1 P2; preserves the pre-onPath guard).
+        if (isThenable(discriminant)) {
+            throw new Error(`workflow ${node.meta.id}: the value at \`on\` path ` +
+                `"${(node.onPath ?? []).join(".")}" is a thenable — state must hold ` +
+                `settled values; await async work in .action() before switching on it`);
+        }
+        const idx = node.cases.findIndex((c) => c.value === discriminant);
+        return idx >= 0
+            ? { takenIndex: idx, takenLabel: node.cases[idx].label }
+            : { takenIndex: "default" };
+    }
+    for (let i = 0; i < node.cases.length; i++) {
+        const when = node.cases[i].when;
+        if (when === undefined)
+            continue; // defensive: a case without a predicate never matches
+        let hit;
+        if (isOpaquePredicate(when)) {
+            const result = await when.fn(ctx, state);
+            if (typeof result !== "boolean") {
+                // The public type promises boolean; reject non-booleans rather than coercing
+                // (a `'false'` string or a forgotten return would silently take the case).
+                throw new Error(`workflow branch "${node.meta.id}": whenRuntime must return a boolean, got ${typeof result}`);
+            }
+            hit = result;
+        }
+        else {
+            hit = evalPredicate(when, state);
+        }
+        if (hit)
+            return { takenIndex: i, takenLabel: node.cases[i].label };
+    }
+    return { takenIndex: "default" };
+}
+/**
+ * Run a single leaf (non-control-flow) node: runNode + push outcome + cause
+ * synthesis. Explicit-intent retry (§17 #7) lives HERE: each attempt is a FULL
+ * runNode bracket (fresh scope + abort + attempt-stamped node_start/node_end).
+ *
+ * Attempt-evidence policy (§17 #7, codex S2.4c R1 P2): the run's pass/fail
+ * counters belong to the FINAL attempt only — a retried-and-passed node must
+ * not leave failed assertion/validation counts on the host ctx (the shipped
+ * step retry resets per-attempt counters the same way; otherwise a host
+ * summary computed from assertion events contradicts the node verdict). So a
+ * retrying node buffers each attempt's pass/fail evidence (`quarantinedCtx`)
+ * and flushes ONLY the attempt that decides the verdict: the passing/skipping
+ * attempt, the terminal-timeout attempt, or the last exhausted attempt. A
+ * non-final failed attempt stays VISIBLE — its attempt-stamped node_end
+ * (failed, with the error), its traces/logs/metrics, and a retry log line all
+ * pass through; only its buffered assert/validate COUNTS are dropped.
+ *
+ * Each attempt re-reads the same last-committed state (a failed attempt
+ * commits nothing, §17 #13). Never retried: a passed/skipped attempt (skip is
+ * control flow), and a timeout (TERMINAL, §17 #4). check/compute cannot carry
+ * retry — a check failure must never replay a prior action.
+ */
+async function runLeafNode(baseCtx, workflowId, node, state, outcomes) {
+    const grade = staticGradeOf(node);
+    const retry = node.kind === "contract-call" || node.kind === "action"
+        ? node.retry
+        : undefined;
+    // Re-validate at run time: an `as any`/JS caller could smuggle e.g.
+    // `attempts: Infinity` past the builder — fail the node fast, don't loop.
+    let r;
+    if (retry) {
+        try {
+            validateRetryMeta(retry, node.meta.id);
+        }
+        catch (err) {
+            outcomes.push({ id: node.meta.id, status: "failed", grade });
+            emitNodeEnd(baseCtx, node, "failed", grade, 0, err);
+            return { state, status: "failed", cause: err };
+        }
+    }
+    const maxAttempts = retry?.attempts ?? 1;
+    const timeoutOpt = node.meta.timeout !== undefined ? { timeoutMs: node.meta.timeout } : {};
+    if (!retry) {
+        r = await runNode(baseCtx, node, state, { staticGrade: grade, ...timeoutOpt });
+    }
+    else {
+        // A failed attempt is terminal when it cannot/must not be replayed: a
+        // passed/skipped verdict (skip is control flow), a timeout (TERMINAL,
+        // §17 #4), or attempt exhaustion.
+        const isTerminal = (attempt, status, error) => status !== "failed" || error instanceof NodeTimeoutError || attempt >= maxAttempts;
+        // Replaying a buffered FATAL validation onto the real host ctx throws again
+        // (the host's validate aborts on fatal). That control flow is already spent —
+        // it failed the attempt at the original throw — so the replay's throw must
+        // not escape runNode/runWorkflow (codex S2.4c R3 P2). Evidence before the
+        // fatal entry has already replayed; nothing follows it (the attempt body
+        // stopped at the throw).
+        const safeFlush = (attemptCtx) => {
+            try {
+                attemptCtx.flushTo(baseCtx);
+            }
+            catch {
+                /* replayed fatal validation — already accounted in the attempt verdict */
+            }
+        };
+        // Promotion aggregates across attempts, but ONLY from evidence that actually
+        // reached the host (codex S2.4c R3+R4 P2): pass-through trace/metric on ANY
+        // attempt counts (it is on the host timeline even when the attempt's buffered
+        // counts are dropped); buffered assert/validate counts only when FLUSHED —
+        // i.e. on the terminal attempt. The adjustment is applied INSIDE runNode (via
+        // adjustGrade) so each attempt's node_end event and the final outcome carry
+        // the same host-visible grade — a discarded attempt's assert-only "trace"
+        // must not show anywhere, and an earlier attempt's pass-through promotion
+        // must survive into the terminal bracket (codex S2.5 R5 P2).
+        let promoted = false;
+        for (let attempt = 1;; attempt++) {
+            // Buffer this attempt's pass/fail evidence; observability (traces, logs,
+            // node_start/node_end events) passes straight through to the host — via a
+            // probe that records whether any pass-through STRUCTURED evidence landed.
+            let passthroughStructured = false;
+            const probe = Object.assign(Object.create(baseCtx), {
+                trace: (t) => {
+                    passthroughStructured = true;
+                    baseCtx.trace(t);
+                },
+                metric: (name, value, options) => {
+                    passthroughStructured = true;
+                    baseCtx.metric(name, value, options);
+                },
+            });
+            const attemptCtx = quarantinedCtx(probe);
+            let flushed = false;
+            r = await runNode(attemptCtx, node, state, {
+                staticGrade: grade,
+                ...timeoutOpt, // §17 #4: a timed-out attempt is TERMINAL — never retried
+                attempt: { n: attempt, of: maxAttempts },
+                // Flush the verdict-deciding attempt's evidence BEFORE its node_end is
+                // emitted, so the assertions land INSIDE the attempt bracket on the
+                // host timeline (codex S2.4c R2 P2).
+                beforeNodeEnd: (status, error) => {
+                    if (isTerminal(attempt, status, error)) {
+                        flushed = true; // set first — a throwing replay still counts as flushed
+                        safeFlush(attemptCtx);
+                    }
+                },
+                adjustGrade: (computed, info) => {
+                    if (grade !== "opaque")
+                        return computed; // only opaque→trace exists (§17 #10)
+                    const terminal = isTerminal(attempt, info.status, info.error);
+                    // Host-visible structured evidence: a pass-through trace/metric (this
+                    // or any earlier attempt), or — only when this attempt's buffers flush
+                    // (terminal) — its scope-recorded assert/validate evidence.
+                    const hostVisible = promoted || passthroughStructured || (terminal && info.structured);
+                    return hostVisible ? "trace" : "opaque";
+                },
+            });
+            if (passthroughStructured)
+                promoted = true;
+            if (isTerminal(attempt, r.status, r.error)) {
+                // beforeNodeEnd already flushed on every runNode settle path; this is a
+                // safety net for a future runNode path that misses the hook (flushTo
+                // replays the buffer, so it must run at most once).
+                if (!flushed)
+                    safeFlush(attemptCtx);
+                break;
+            }
+            // Non-final failed attempt: drop its buffered counts, log the retry
+            // (mirrors the shipped step-retry log line), wait, go again.
+            baseCtx.log?.(`retrying workflow node "${node.meta.id}" (${attempt + 1}/${maxAttempts}) ` +
+                `after failure — ${retry.reason}`);
+            if (retry.delay)
+                await sleep(retry.delay);
+        }
+        // r.grade already carries the cross-attempt host-visible promotion (adjustGrade).
+    }
+    outcomes.push({ id: node.meta.id, status: r.status, grade: r.grade });
+    if (r.status === "passed")
+        return { state: r.state, status: "passed" };
+    if (r.status === "failed") {
+        return {
+            state,
+            status: "failed",
+            cause: r.error ?? new WorkflowPhaseFailedError(workflowId, `node "${node.meta.id}"`),
+        };
+    }
+    // node ctx.skip() — preserve the authored reason (codex S2.5 R6).
+    return {
+        state,
+        status: "skipped",
+        skipReason: r.error instanceof GlubeanSkipError ? r.error.reason : undefined,
+    };
+}
+/** Branch-family decision event (§17 #9 "branch decision") — rides the generic
+ * ctx.event channel like node_start/node_end; the runner unwraps it into a
+ * first-class `branch_decision` timeline event. */
+export const BRANCH_DECISION_EVENT = "workflow:branch_decision";
+/**
+ * Run a branch-family node (§17 #6, addendum §9): decide the taken case (under
+ * a child ctx so an opaque predicate's evidence is attributed + quarantined),
+ * then run ONLY the taken case's nodes via runNodeList; every non-taken case
+ * (and the un-taken default) is emitted `skipped`. A decision that throws or
+ * soft-fails fails the node (all cases skipped). switch with no default and no
+ * match = identity pass-through. A terminal route's outcome carries
+ * `terminal: true` so runNodeList stops the trunk after it.
+ */
+async function runBranch(baseCtx, workflowId, node, state, outcomes) {
+    const grade = staticGradeOf(node);
+    const started = Date.now();
+    emitNodeStart(baseCtx, node);
+    // The family node's own outcome precedes its children (tree order); the final
+    // status is set once the taken case settles.
+    const outcomeIndex = outcomes.length;
+    outcomes.push({ id: node.meta.id, status: "passed", grade });
+    const ac = new AbortController();
+    const scope = makeNodeScope(baseCtx, ac.signal);
+    // Emit ALL children (every case in authored order, then default) as skipped.
+    // `exceptIndex` skips the taken case's slot (its children get real outcomes).
+    const emitChildrenSkipped = (exceptIndex) => {
+        node.cases.forEach((c, i) => {
+            if (exceptIndex !== i)
+                emitNodesSkipped(baseCtx, c.nodes, outcomes, 0);
+        });
+        if (node.default && exceptIndex !== "default") {
+            emitNodesSkipped(baseCtx, node.default, outcomes, 0);
+        }
+    };
+    const failAll = (cause, error) => {
+        ac.abort();
+        emitChildrenSkipped();
+        const g = promoteGrade(grade, scope); // a soft-failed predicate may have emitted evidence (§17 #10)
+        outcomes[outcomeIndex] = { id: node.meta.id, status: "failed", grade: g };
+        emitNodeEnd(baseCtx, node, "failed", g, Date.now() - started, error);
+        return { state, status: "failed", cause };
+    };
+    let decision;
+    try {
+        decision = await withActiveNodeCtx(scope.ctx, () => selectBranchCase(node, state, scope.ctx));
+    }
+    catch (err) {
+        scope.seal();
+        if (err instanceof GlubeanSkipError && !scope.hasFailure()) {
+            // decision ctx.skip() with no prior failure → skip the node (→ whole
+            // workflow, like a node skip), NOT a failure (codex S2.4a R5).
+            ac.abort();
+            emitChildrenSkipped();
+            const g = promoteGrade(grade, scope);
+            outcomes[outcomeIndex] = { id: node.meta.id, status: "skipped", grade: g };
+            emitNodeEnd(baseCtx, node, "skipped", g, Date.now() - started);
+            return { state, status: "skipped", skipReason: err.reason };
+        }
+        // a real throw, OR a soft-failure-then-skip → fail. A skip is never the cause;
+        // synthesize a phase failure (mirrors runNode/setup, codex S2.4a R6).
+        if (err instanceof GlubeanSkipError) {
+            return failAll(new WorkflowPhaseFailedError(workflowId, `branch "${node.meta.id}" decision`));
+        }
+        return failAll(err, err);
+    }
+    if (scope.hasFailure()) {
+        // opaque predicate soft-failed (scoped assert/validate) — fail the node.
+        scope.seal();
+        return failAll(new WorkflowPhaseFailedError(workflowId, `branch "${node.meta.id}" decision`));
+    }
+    // The decision is observability (§17 #9) — emit through the scope while live.
+    const decisionData = {
+        nodeId: node.meta.id,
+        mode: node.mode,
+        takenIndex: decision.takenIndex,
+        ...(decision.takenLabel !== undefined ? { takenLabel: decision.takenLabel } : {}),
+    };
+    scope.ctx.event({ type: BRANCH_DECISION_EVENT, data: decisionData });
+    scope.seal();
+    // Run the taken case; emit every other case's children skipped — in AUTHORED
+    // order, so outcomes/events align with the projected tree (codex S2.4a P2):
+    // cases before the taken one first, then the taken sub-run, then the rest.
+    let r;
+    if (decision.takenIndex === "default") {
+        emitChildrenSkipped("default");
+        r = node.default
+            ? await runNodeList(baseCtx, workflowId, node.default, state, outcomes)
+            : { state, status: "passed" }; // switch with no default: identity pass-through (§9 #4)
+    }
+    else {
+        const takenIdx = decision.takenIndex;
+        node.cases.forEach((c, i) => {
+            if (i < takenIdx)
+                emitNodesSkipped(baseCtx, c.nodes, outcomes, 0);
+        });
+        r = await runNodeList(baseCtx, workflowId, node.cases[takenIdx].nodes, state, outcomes);
+        node.cases.forEach((c, i) => {
+            if (i > takenIdx)
+                emitNodesSkipped(baseCtx, c.nodes, outcomes, 0);
+        });
+        if (node.default)
+            emitNodesSkipped(baseCtx, node.default, outcomes, 0);
+    }
+    // promote opaque→trace if the decision emitted structured evidence, same as
+    // runNode (§17 #10; codex S2.4a P2).
+    const runtimeGrade = promoteGrade(grade, scope);
+    outcomes[outcomeIndex] = { id: node.meta.id, status: r.status, grade: runtimeGrade };
+    emitNodeEnd(baseCtx, node, r.status, runtimeGrade, Date.now() - started);
+    // A terminal route that completed (passed OR skipped) ends the trunk; a
+    // failed one already fail-stops the list the normal way.
+    if (node.terminal && r.status === "passed") {
+        return { ...r, terminal: true };
+    }
+    return r;
+}
+// =============================================================================
+// runPollNode — bounded poll-until with per-attempt quarantine (§17 #3, §6.7)
+// =============================================================================
+/** Per-attempt timeline event (§17 #9 "poll attempt timeline"). Rides the generic
+ * `ctx.event` channel like node_start/node_end; emitted through the NODE scope, so
+ * it is observability (never promotes the grade) and is quarantined after seal. */
+export const POLL_ATTEMPT_EVENT = "workflow:poll_attempt";
+function emitPollAttempt(ctx, node, attempt, outcome, durationMs, inboundDetail) {
+    const data = {
+        nodeId: node.meta.id,
+        attempt,
+        outcome,
+        durationMs: Math.round(durationMs),
+        ...(inboundDetail ? inboundDetail : {}),
+    };
+    ctx.event({ type: POLL_ATTEMPT_EVENT, data });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * A fail-class inbound classification (inbound-contract-design §9.4 rows 1–3):
+ * a property of the delivery CHANNEL (forgery / replay / non-JSON), never
+ * noise — it fails the poll node even when a later delivery in the same
+ * snapshot would have matched (§9.4a #4, first terminal wins).
+ */
+export class InboundDeliveryFailError extends Error {
+    classification;
+    constructor(classification, nodeId, detail) {
+        super(`workflow poll "${nodeId}": inbound delivery classified ${classification}` +
+            `${detail ? ` (${detail})` : ""} — authentication/channel failures are ` +
+            `never noise (inbound-contract-design §9.4).`);
+        this.classification = classification;
+        this.name = "InboundDeliveryFailError";
+    }
+}
+/**
+ * ONE inbound attempt (design §9.3): walk the receiver's unclaimed snapshot
+ * in receiver order (oldest first) through the adapter matcher; the FIRST
+ * terminal classification wins — matched claims and exits, a fail class
+ * throws (§9.4a #4). Pre-existing deliveries are allowed evidence
+ * (§9.4a #3) — eligibility is "unclaimed", not "received after poll start".
+ */
+function runInboundAttempt(node, state, ctx) {
+    const inbound = node.inbound;
+    const ref = node.ref;
+    const label = node.meta.id;
+    const adapter = getAdapter(ref.protocol);
+    if (!adapter?.matchInboundCase) {
+        throw new Error(`workflow poll "${label}": adapter for protocol "${ref.protocol}" does ` +
+            `not implement matchInboundCase — it cannot await inbound deliveries.`);
+    }
+    const handle = inbound.via(state);
+    if (!handle ||
+        typeof handle.deliveries !== "function" ||
+        typeof handle.claim !== "function") {
+        throw new Error(`workflow poll "${label}": \`via\` did not resolve to a ReceiverHandle ` +
+            `(needs deliveries() and claim()) — put the live handle in state ` +
+            `during setup and select it with a pure lens.`);
+    }
+    const caseSpec = ref.contract._spec
+        ?.cases?.[ref.caseKey];
+    if (!caseSpec) {
+        throw new Error(`workflow poll "${label}": case "${ref.caseKey}" not found in contract "${ref.contractId}"`);
+    }
+    // Delivery-less preflight (§9.4 row P): an EMPTY inbox must not let an
+    // unknown scheme / missing secret exhaust as a timeout — the matcher's own
+    // preflight only runs when a delivery exists (codex I3 R3 P2).
+    adapter.preflightInboundCase?.({ caseSpec, secrets: ctx.secrets });
+    // Both correlate sides resolve via EXTRACTED paths (safe traversal) — a
+    // lens call (`s => s.a.b`) throws on a missing intermediate. Event side:
+    // missing path = type-mismatch probe (the matcher walks it). State side:
+    // state is OURS and deterministic, so a missing/undefined correlation
+    // value is an authoring bug — fail fast with a named error instead of
+    // letting `undefined === undefined` match someone else's event or probing
+    // silently to exhaustion (the missing-operand rule, same as eqPath).
+    let correlate;
+    if (inbound.correlate) {
+        const stateValue = resolvePath(state, inbound.correlate.statePath);
+        if (stateValue === undefined) {
+            throw new Error(`workflow poll "${label}": correlate.state resolved \`undefined\` at ` +
+                `path "${inbound.correlate.statePath.join(".")}" — the value to ` +
+                `correlate on must be in state before the poll starts.`);
+        }
+        correlate = { eventPath: inbound.correlate.eventPath, stateValue };
+    }
+    let last = { matched: false, classification: "no-delivery" };
+    for (const delivery of handle.deliveries()) {
+        const result = adapter.matchInboundCase({
+            caseSpec,
+            delivery: delivery,
+            secrets: ctx.secrets,
+            correlate,
+        });
+        if (result.kind === "matched") {
+            handle.claim(delivery.id);
+            return {
+                matched: true,
+                parsed: result.parsed,
+                classification: "matched",
+                receivedAt: delivery.receivedAt,
+            };
+        }
+        if (result.kind === "signature-invalid" ||
+            result.kind === "stale" ||
+            result.kind === "unparseable") {
+            throw new InboundDeliveryFailError(result.kind, label, result.detail);
+        }
+        last = { matched: false, classification: result.kind };
+    }
+    return last;
+}
+/**
+ * Evaluate the poll exit predicate. L2 declarative reads the RESPONSE (shared
+ * `evalPredicate`, subject = response — the single predicate engine, same as
+ * branch). An opaque `untilRuntime` gets `(ctx, res, state)` and is awaited; a
+ * non-boolean result is rejected (same rule + wording as branch `whenRuntime`).
+ * Deliberately NOT the flow's `evalPollExit`: that helper's error text names the
+ * legacy `pollFn`/`pollAsync` API, which is deleted before release (no-compat).
+ */
+async function evalUntil(node, response, ctx, state) {
+    const until = node.until;
+    if (until.kind === "opaque") {
+        // The quarantined predicate ctx prototype-chains to the node scope's ctx, so
+        // `signal` and observability resolve through it — the WorkflowContext cast is
+        // sound at runtime (same seam as the branch predicate).
+        const result = await until.fn(ctx, response, state);
+        if (typeof result !== "boolean") {
+            throw new Error(`workflow poll "${node.meta.id}": untilRuntime must return a boolean, got ${typeof result}`);
+        }
+        return result;
+    }
+    return evalPredicate(until, response);
+}
+/**
+ * The bounded attempt loop — a port of the flow's `runPollStep`
+ * (contract-core.ts:1449-1569) onto the workflow node scope. Each attempt runs
+ * request + exit predicate in their own quarantined ctxs over `scope.ctx`
+ * (§17 #3):
+ *   - satisfy (until=true)    → flush reqCtx, return the response (caller applies `out`);
+ *   - probe (until=false)     → DISCARD reqCtx (pending validation noise);
+ *   - in-budget fail/throw    → flush the throwing ctx (the deliberate failure lands), rethrow;
+ *   - orphan (budget timeout) → DISCARD that ctx (a timed-out attempt cannot corrupt the run);
+ *   - exhaust (any bound)     → throw PollExhaustedError (the node fails).
+ * The predicate ctx is flushed after EVERY in-budget evaluation — its traces and
+ * deliberate asserts are observability/intent, not probe noise (§17 #3). Both the
+ * request and the predicate are budget-raced, so the loop is bounded even when
+ * the adapter ignores `signal`.
+ */
+async function pollLoop(node, state, scope) {
+    const label = node.meta.id;
+    // `as any`/JS callers can hand a poll node with neither attempt source —
+    // executeCallAttempt would crash on an undefined ref; fail fast instead.
+    if (!node.ref && !node.attemptFn) {
+        throw new Error(`workflow poll "${label}": needs a contract ref (.poll) or an attempt fn (.pollAction)`);
+    }
+    // Inbound polls have no exit predicate — matched IS the exit (§9.4a); every
+    // other poll requires one (an exit-predicate-less poll loops for nothing).
+    if (!node.inbound && !node.until) {
+        throw new Error(`workflow poll "${label}": needs an exit predicate — \`until\` (declarative) or \`untilRuntime\``);
+    }
+    // Epoch anchor for `within` evidence (receivedAt is epoch ms; §9.4a #3 —
+    // the delta may be negative for deliveries that beat the poll start).
+    const pollStartEpochMs = Date.now();
+    // Runtime bound guard — the builder validates at construction, but `as any` /
+    // JS callers can hand the executor an unbounded poll node. Fail fast instead of
+    // looping forever (mirrors runPollStep's guard).
+    validatePollBounds({
+        timeout: node.timeoutMs,
+        maxAttempts: node.maxAttempts,
+        perAttemptTimeout: node.perAttemptTimeoutMs,
+        every: node.every,
+        backoff: node.backoff,
+    }, label);
+    // Defaults for as-any/JS callers — the builder already applies them (a missing
+    // `every` would hot-loop; `delay * undefined` is NaN).
+    const everyMs = node.every ?? DEFAULT_EVERY_MS;
+    const backoffFactor = node.backoff ?? 1;
+    const now = () => performance.now();
+    const start = now();
+    const deadline = node.timeoutMs !== undefined ? start + node.timeoutMs : Infinity;
+    const perAttempt = node.perAttemptTimeoutMs ?? Infinity;
+    let attempt = 0;
+    let delay = everyMs;
+    let lastRes;
+    for (;;) {
+        attempt += 1;
+        const remainingTotal = deadline - now();
+        if (remainingTotal <= 0) {
+            throw new PollExhaustedError(label, attempt - 1, "total timeout reached before next attempt");
+        }
+        const attemptBudget = Math.min(perAttempt, remainingTotal); // build-time validation ⇒ finite
+        const attemptStart = now();
+        // Request: quarantined ctx + per-attempt abort signal; budget-raced so a
+        // non-honoring adapter can't block past the budget.
+        const attemptAc = new AbortController();
+        let budgetAborted = false;
+        const budgetTimer = Number.isFinite(attemptBudget)
+            ? setTimeout(() => {
+                budgetAborted = true;
+                attemptAc.abort();
+            }, Math.max(0, attemptBudget))
+            : undefined;
+        // The attempt ctx: quarantined over the node scope, with `signal` =
+        // THIS attempt's budget abort (an attemptFn reads ctx.signal; a contract
+        // attempt gets the same signal explicitly).
+        const reqCtx = Object.assign(quarantinedCtx(scope.ctx), { signal: attemptAc.signal });
+        const exhausted = () => new PollExhaustedError(label, attempt, `attempt budget ${Math.round(attemptBudget)}ms exceeded`);
+        try {
+            // Attempt source: inbound await (design §9.3 — scan the receiver
+            // snapshot through the adapter matcher), pollAction probe (addendum
+            // §4), or a contract-call attempt. Same quarantine, same budget race.
+            const attemptRun = node.inbound
+                ? Promise.resolve(runInboundAttempt(node, state, reqCtx))
+                : node.attemptFn
+                    ? Promise.resolve(node.attemptFn(reqCtx, state))
+                    : executeCallAttempt("poll", node, reqCtx, state, attemptAc.signal);
+            lastRes = await raceBudget(attemptRun, attemptBudget, exhausted);
+        }
+        catch (err) {
+            // Once OUR budget timer fired, the attempt is over budget no matter HOW
+            // the cancelled body rejects — an AbortError from a signal-honoring
+            // adapter, or (pollAction takes arbitrary fns — codex S2.11 R1 P2) a
+            // plain Error thrown from an abort handler. Either way the rejection is
+            // the cancellation's echo, not an in-budget verdict: normalize to poll
+            // exhaustion and DISCARD the orphan's buffered evidence.
+            const isBudgetAbort = budgetAborted && !(err instanceof PollExhaustedError);
+            // A genuine IN-BUDGET request error (incl. fatal validation / ctx.fail)
+            // flushes its buffered effects (the failure assertion lands) then fails
+            // the poll; budget overruns discard the orphan ctx.
+            if (!isBudgetAbort && !(err instanceof PollExhaustedError))
+                reqCtx.flushTo(scope.ctx);
+            emitPollAttempt(scope.ctx, node, attempt, "failed", now() - attemptStart, err instanceof InboundDeliveryFailError
+                ? { classification: err.classification }
+                : undefined);
+            throw isBudgetAbort ? exhausted() : err;
+        }
+        finally {
+            if (budgetTimer)
+                clearTimeout(budgetTimer);
+        }
+        // A sync-heavy request the timer couldn't preempt may have overrun — re-check.
+        if (now() > deadline)
+            throw new PollExhaustedError(label, attempt, "total timeout reached");
+        if (now() - attemptStart > perAttempt)
+            throw new PollExhaustedError(label, attempt, "attempt budget exceeded");
+        let done;
+        let inboundDetail;
+        if (node.inbound) {
+            // Inbound: matched IS the exit (§9.4a) — no predicate, no predCtx.
+            const res = lastRes;
+            done = res.matched;
+            inboundDetail = {
+                classification: res.classification,
+                ...(res.matched && res.receivedAt !== undefined
+                    ? { withinDeltaMs: res.receivedAt - pollStartEpochMs }
+                    : {}),
+            };
+        }
+        else {
+            // Exit predicate — quarantined ctx, budget-raced, flushed only on in-budget completion.
+            const predBudget = Math.min(deadline - now(), perAttempt - (now() - attemptStart));
+            const predCtx = quarantinedCtx(scope.ctx);
+            try {
+                done = await raceBudget(evalUntil(node, lastRes, predCtx, state), Math.max(0, predBudget), () => new PollExhaustedError(label, attempt, "exit-predicate budget exceeded"));
+            }
+            catch (err) {
+                // Timed-out predicate orphan → discard predCtx. An in-budget predicate that
+                // threw (ctx.fail / ctx.skip / a thrown error) → flush its buffered effects
+                // (the failure assertion lands) then propagate (the poll fails / skips).
+                if (!(err instanceof PollExhaustedError))
+                    predCtx.flushTo(scope.ctx);
+                emitPollAttempt(scope.ctx, node, attempt, "failed", now() - attemptStart);
+                throw err;
+            }
+            if (now() > deadline)
+                throw new PollExhaustedError(label, attempt, "total timeout reached");
+            if (now() - attemptStart > perAttempt)
+                throw new PollExhaustedError(label, attempt, "attempt budget exceeded");
+            predCtx.flushTo(scope.ctx); // in-budget: the user's deliberate skip/fail/assert count (§17 #3)
+        }
+        if (done) {
+            reqCtx.flushTo(scope.ctx); // satisfying attempt: final-response validation failures surface
+            emitPollAttempt(scope.ctx, node, attempt, "satisfied", now() - attemptStart, inboundDetail);
+            // The satisfying inbound result hands `out` the PARSED, schema-validated
+            // body (§9.4a) — the wrapper is loop machinery, not user data.
+            return node.inbound ? lastRes.parsed : lastRes;
+        }
+        // probe (not satisfied): reqCtx discarded (pending validation noise).
+        emitPollAttempt(scope.ctx, node, attempt, "probe", now() - attemptStart, inboundDetail);
+        if (node.maxAttempts && attempt >= node.maxAttempts) {
+            throw new PollExhaustedError(label, attempt, "maxAttempts reached");
+        }
+        // A wait that would cross the deadline is pointless — fail now, don't sleep.
+        if (Number.isFinite(deadline) && now() + delay >= deadline) {
+            throw new PollExhaustedError(label, attempt, "next wait would exceed timeout");
+        }
+        await sleep(delay);
+        delay = Math.min(delay * backoffFactor, BACKOFF_CAP_MS);
+    }
+}
+/**
+ * Run a poll node (§17 #3): a leaf with its OWN bounds (it does not take the
+ * generic per-node timeout, §17 #4) — so like branch it owns its bracket instead
+ * of going through runNode. The loop runs under the node scope; quarantine policy
+ * is layered: per-attempt buffered ctxs (flush/discard, §17 #3) over the node
+ * scope (late-evidence seal, §17 #12). On satisfy the `out` lens folds the
+ * response into state (commit-on-success, §17 #13); on exhaustion / a deliberate
+ * in-budget failure the node fails; a predicate/adapter `ctx.skip()` with no
+ * prior failure skips the node (→ whole workflow, same as every other node).
+ */
+async function runPollNode(baseCtx, workflowId, node, state, outcomes) {
+    const staticGrade = staticGradeOf(node);
+    const started = Date.now();
+    emitNodeStart(baseCtx, node);
+    const ac = new AbortController();
+    const scope = makeNodeScope(baseCtx, ac.signal);
+    let status;
+    let nextState = state;
+    let cause;
+    let errForEvent;
+    let skipReason;
+    try {
+        const res = await withActiveNodeCtx(scope.ctx, () => pollLoop(node, state, scope));
+        if (scope.hasFailure()) {
+            // The satisfying attempt's flushed evidence (or an earlier in-budget
+            // predicate assert) recorded a soft failure → the node fails and `out` is
+            // NOT applied (an out lens assumes the validated success shape — same rule
+            // as runContractCall, codex S2.1 R7).
+            status = "failed";
+            cause = new WorkflowPhaseFailedError(workflowId, `poll "${node.meta.id}"`);
+        }
+        else {
+            // `out` REPLACES state; absent/void `out` preserves it (§17 #2). Reject a
+            // thenable so async/I/O can't hide inside the lens (§17 #11; mirrors call).
+            const next = node.out ? node.out(state, res) : undefined;
+            if (isThenable(next)) {
+                throw new Error(`workflow poll "${node.meta.id}": \`out\` returned a thenable — out must be a ` +
+                    `pure synchronous lens (state, res) => state; do async work in .action()`);
+            }
+            nextState = next === undefined ? state : next;
+            status = "passed";
+        }
+    }
+    catch (err) {
+        if (err instanceof GlubeanSkipError && !scope.hasFailure()) {
+            // deliberate ctx.skip() (predicate or adapter, in-budget, no prior failure)
+            // → skip the poll (→ whole workflow), NOT a failure.
+            status = "skipped";
+            skipReason = err.reason;
+        }
+        else if (err instanceof GlubeanSkipError) {
+            // skip AFTER a soft failure → the failure wins; never surface the skip.
+            status = "failed";
+            cause = new WorkflowPhaseFailedError(workflowId, `poll "${node.meta.id}"`);
+        }
+        else {
+            status = "failed";
+            cause = err;
+            errForEvent = err;
+        }
+    }
+    // Seal BEFORE aborting (abort listeners that emit must be quarantined too —
+    // same ordering as runNode's timeout path). Abort on any non-success so
+    // signal-aware work the node started observes it; a passed poll's attempts are
+    // already settled (per-attempt signals own in-flight aborts).
+    scope.seal();
+    if (status !== "passed" && !ac.signal.aborted)
+        ac.abort();
+    const grade = promoteGrade(staticGrade, scope);
+    outcomes.push({ id: node.meta.id, status, grade });
+    emitNodeEnd(baseCtx, node, status, grade, Date.now() - started, errForEvent);
+    if (status === "passed")
+        return { state: nextState, status };
+    if (status === "failed")
+        return { state, status, cause };
+    return { state, status, skipReason };
+}
+/**
+ * Run a node LIST with fail-stop / skip-stop + commit-on-success state threading
+ * (§17 #5/#13). Shared by the top-level graph and each branch side (recursion). A
+ * non-passed node stops the list; the rest are emitted `skipped`.
+ */
+async function runNodeList(baseCtx, workflowId, list, state, outcomes) {
+    for (let i = 0; i < list.length; i++) {
+        const node = list[i];
+        const r = node.kind === "branch"
+            ? await runBranch(baseCtx, workflowId, node, state, outcomes)
+            : node.kind === "poll"
+                ? await runPollNode(baseCtx, workflowId, node, state, outcomes)
+                : node.kind === "group"
+                    ? await runGroup(baseCtx, workflowId, node, state, outcomes)
+                    : await runLeafNode(baseCtx, workflowId, node, state, outcomes);
+        state = r.state;
+        if (r.status === "passed") {
+            // A terminal route completed: the trunk ends here (§9 #5). Anything
+            // smuggled after it (the builder forbids it; `as any` can't) is reported
+            // skipped, never executed.
+            if (r.terminal) {
+                emitNodesSkipped(baseCtx, list, outcomes, i + 1);
+                return r;
+            }
+            continue;
+        }
+        emitNodesSkipped(baseCtx, list, outcomes, i + 1); // rest of THIS list → skipped
+        return r;
+    }
+    return { state, status: "passed" };
+}
+/**
+ * Run a `.group()` node — a DISPLAY-ONLY container (phase4 §2, owner-decided):
+ * members execute sequentially on the trunk's state exactly as if the group
+ * wrapper were absent; deleting the group changes nothing about execution.
+ * The group adds ONLY a node_start/node_end bracket so CLI/Cloud can render a
+ * collapsible section. Aggregate status precedence: failed > skipped > passed
+ * (design-R2 — a member ctx.skip() must not render a "passed" bracket).
+ * Grade = worst member RUNTIME grade (promotions included). Summary counts
+ * MEMBERS, not the bracket (kind:"group" on node_end is the discriminator).
+ * No own lifecycle, no timeout, no retry — those were rejected at build time.
+ */
+async function runGroup(baseCtx, workflowId, node, state, outcomes) {
+    const started = Date.now();
+    emitNodeStart(baseCtx, node);
+    const before = outcomes.length;
+    const r = await runNodeList(baseCtx, workflowId, node.nodes, state, outcomes);
+    // Worst DIRECT-member grade — same scope as staticGradeOf(group), which
+    // folds direct children only (a branch member contributes its DECISION
+    // grade; its case sub-graphs are tallied independently, S2.4a R4). Folding
+    // descendants here would let a skipped opaque side DOWNGRADE the bracket
+    // below its static floor (codex S2.14 R1 P2) — runtime may only promote.
+    const directIds = new Set(node.nodes.map((n) => n.meta.id));
+    const RANK = { full: 0, partial: 1, trace: 2, opaque: 3 };
+    let grade = "full";
+    for (let i = before; i < outcomes.length; i++) {
+        const o = outcomes[i];
+        if (directIds.has(o.id) && RANK[o.grade] > RANK[grade])
+            grade = o.grade;
+    }
+    if (node.nodes.length === 0)
+        grade = staticGradeOf(node);
+    outcomes.push({ id: node.meta.id, status: r.status, grade });
+    emitNodeEnd(baseCtx, node, r.status, grade, Date.now() - started);
+    return r;
+}
+/**
+ * Execute a built `Workflow` against a host `TestContext`. setup runs INSIDE the
+ * protected region so teardown ALWAYS runs — even when setup throws (§17 #1, the
+ * opposite of runFlow). Nodes run in authored order with fail-stop: a non-passed
+ * node stops the rest (emitted `skipped`). A node `ctx.skip()` skips the whole
+ * workflow (mirrors the runner's whole-test skip); `meta.skip` opts the workflow
+ * out entirely (discoverable, never executed). teardown sees the last committed
+ * state + the failing cause; a teardown that throws is logged and never masks it.
+ */
+export async function runWorkflow(wf, baseCtx) {
+    const nodes = [];
+    // --- workflow-level skip: discoverable but NEVER executed — no setup, no nodes,
+    // --- no teardown; every node reported skipped (codex S2.1 R2). ---
+    if (wf.meta.skip !== undefined) {
+        emitNodesSkipped(baseCtx, wf.nodes, nodes, 0);
+        return {
+            status: "skipped",
+            state: undefined,
+            nodes,
+            error: undefined,
+            skipReason: wf.meta.skip,
+        };
+    }
+    let state;
+    let cause;
+    let failed = false;
+    let skipped = false; // setup or a node called ctx.skip() → the whole workflow is skipped
+    let skipReason; // the authored ctx.skip(reason) (codex S2.5 R6)
+    try {
+        // --- setup: an async lifecycle node, SELF-CONTAINED — its throw / ctx.skip() /
+        // --- soft-failure is classified here (no outer catch); on any non-success the
+        // --- graph is skipped and we stop before the node loop. ---
+        let proceed = true;
+        if (wf.setup) {
+            const { scope, ac } = deriveLifecycleScope(baseCtx);
+            let setupResult;
+            let setupError;
+            let threw = false;
+            try {
+                // setup is an async lifecycle node — its terminal timeout (§17 #4)
+                // budget-races the body; on expiry the run fails with the timeout as
+                // the cause and the seal (below) quarantines any late evidence.
+                const setupRun = Promise.resolve(withActiveNodeCtx(scope.ctx, () => wf.setup(scope.ctx)));
+                setupResult =
+                    wf.setupTimeoutMs !== undefined
+                        ? await raceBudget(setupRun, wf.setupTimeoutMs, () => new NodeTimeoutError("setup", wf.setupTimeoutMs))
+                        : await setupRun;
+            }
+            catch (e) {
+                threw = true;
+                setupError = e;
+            }
+            finally {
+                scope.seal();
+            }
+            const softFailed = scope.hasFailure();
+            if (threw || softFailed) {
+                ac.abort(); // failure/skip → cancel signal-aware work setup started (codex S2.1 R2)
+                proceed = false;
+                emitNodesSkipped(baseCtx, wf.nodes, nodes, 0);
+                if (threw && setupError instanceof GlubeanSkipError && !softFailed) {
+                    // deliberate setup ctx.skip() with no prior failure → whole workflow
+                    // skipped, like a node skip (codex S2.1 R3 P2).
+                    skipped = true;
+                    skipReason = setupError.reason;
+                }
+                else {
+                    // a thrown error, or a soft failure (possibly then a skip) → run fails.
+                    // A skip after a soft failure is NOT the cause (failure wins, mirroring the
+                    // node path); use the real thrown error, else synthesize a phase failure —
+                    // never surface the skip as the cause (codex S2.1 R5 P2).
+                    failed = true;
+                    cause =
+                        setupError && !(setupError instanceof GlubeanSkipError)
+                            ? setupError
+                            : new WorkflowPhaseFailedError(wf.meta.id, "setup");
+                }
+            }
+            else {
+                state = setupResult; // commit-on-success (§17 #13)
+            }
+        }
+        // --- walk nodes in authored order; fail-stop / skip-stop (§17 #5 basic). The
+        // --- graph + each branch side share runNodeList (commit-on-success threading,
+        // --- §17 #13; node ctx.skip() → whole-workflow skip, mirrors harness.ts:1944). ---
+        if (proceed) {
+            const r = await runNodeList(baseCtx, wf.meta.id, wf.nodes, state, nodes);
+            state = r.state;
+            if (r.status === "failed") {
+                failed = true;
+                cause = r.cause;
+            }
+            else if (r.status === "skipped") {
+                skipped = true;
+                skipReason = r.skipReason;
+            }
+        }
+    }
+    finally {
+        // --- teardown: ALWAYS runs (§17 #1), sees the last committed state + cause ---
+        if (wf.teardown) {
+            const { scope, ac } = deriveLifecycleScope(baseCtx);
+            let teardownThrew = false;
+            try {
+                const teardownRun = Promise.resolve(withActiveNodeCtx(scope.ctx, () => wf.teardown(scope.ctx, state, cause)));
+                // teardown's terminal timeout (§17 #4): logged like any teardown
+                // failure — it NEVER masks the primary cause (§17 #1).
+                if (wf.teardownTimeoutMs !== undefined) {
+                    await raceBudget(teardownRun, wf.teardownTimeoutMs, () => new NodeTimeoutError("teardown", wf.teardownTimeoutMs));
+                }
+                else {
+                    await teardownRun;
+                }
+            }
+            catch (teardownErr) {
+                teardownThrew = true;
+                // Logged, NEVER masks the primary cause (§17 #1).
+                baseCtx.log?.(`workflow "${wf.meta.id}" teardown failed: ${String(teardownErr)}`);
+            }
+            finally {
+                scope.seal();
+                // Abort on failure so signal-aware cleanup work is cancelled, mirroring the
+                // node/setup failure path (codex S2.1 R2).
+                if (teardownThrew || scope.hasFailure())
+                    ac.abort();
+            }
+        }
+    }
+    return {
+        status: failed ? "failed" : skipped ? "skipped" : "passed",
+        state,
+        nodes,
+        error: cause,
+        ...(skipped && skipReason !== undefined ? { skipReason } : {}),
+    };
+}
+//# sourceMappingURL=execute.js.map