@glubean/sdk 0.3.2 → 0.5.0

package/dist/contract-core.js

@@ -19,6 +19,8 @@
  *   - `internal/40-discovery/proposals/contract-flow.md` v9
  */
 import { registerTest } from "./internal.js";
+import { selectBranchSteps, extractBranchStep, predicateScope, assertSelectorSource, assertSwitchCaseValues, assertL2Predicate, } from "./contract-flow-condition.js";
+import { quarantinedCtx, raceBudget, evalPollExit, extractPollStep, validatePollBounds, PollExhaustedError, BACKOFF_CAP_MS, DEFAULT_EVERY_MS, } from "./contract-flow-poll.js";
 import { getBootstrap, registerBootstrap } from "./bootstrap-registry.js";
 import { getExplicitInput, getBootstrapInput, isForceStandalone, } from "./runner-input-channel.js";
 /**
@@ -570,6 +572,236 @@ export const contract = {
 /**
  * Protocol-agnostic flow builder. See contract-flow.md v9 §4.1.
  */
+// =============================================================================
+// Branch desugar helpers (condition / switchOn / switchCond → one "branch" step)
+//
+// Shared by both FlowBuilder (top-level steps) and FlowFragmentBuilder (branch
+// sub-steps). Each `then`/`else`/`default`/case callback is run against a fresh
+// step sink whose accumulated RuntimeFlowStep[] becomes that branch's steps.
+// =============================================================================
+/** Build a contract-call runtime step (adapter lookup + flow-safety validation). */
+function buildContractCallStep(flowId, ref, bindings) {
+    const adapter = _adapters.get(ref.protocol);
+    if (!adapter) {
+        throw new Error(`contract.flow(${JSON.stringify(flowId)}).step: unknown protocol "${ref.protocol}". ` +
+            `Did you forget to import a contract plugin package (e.g. "@glubean/grpc")?`);
+    }
+    if (!adapter.executeCaseInFlow) {
+        throw new Error(`contract.flow(${JSON.stringify(flowId)}).step: adapter for "${ref.protocol}" ` +
+            `does not implement executeCaseInFlow — this protocol cannot appear in a flow.`);
+    }
+    // v10: flow-safety validation fires at step-declaration time (not .case()).
+    const contractRef = ref.contract;
+    adapter.validateCaseForFlow?.(contractRef._spec, ref.caseKey, ref.contractId);
+    return {
+        kind: "contract-call",
+        name: bindings?.name,
+        ref,
+        caseKey: ref.caseKey,
+        contract: ref.contract,
+        bindings: bindings
+            ? {
+                in: bindings.in,
+                out: bindings.out,
+                ...(bindings.accept ? { accept: bindings.accept } : {}),
+            }
+            : undefined,
+    };
+}
+/** Module-private key holding a fragment sink's accumulated step list. */
+const FRAGMENT_STEPS = Symbol("glubean.fragment-steps");
+/**
+ * Run a branch-body callback and return the steps of the fragment it RETURNS
+ * (not a closure-shared array). Because the sink is persistent/immutable (each
+ * method returns a NEW sink carrying `[...prev, step]`), the executed steps are
+ * exactly the chain that produced the returned, type-checked fragment. A block
+ * body that mutates then returns an earlier sink — e.g.
+ * `(b) => { b.compute(reshape); return b; }` — yields that earlier sink's
+ * (shorter) step list, so runtime matches what the type system saw. This keeps
+ * the `NoExtraKeys` / invariant convergence guarantees honest.
+ */
+function collectFragmentSteps(flowId, fn) {
+    const result = fn(makeStepSink(flowId, []));
+    const out = result?.[FRAGMENT_STEPS];
+    if (!Array.isArray(out)) {
+        throw new Error(`flow "${flowId}": a branch body must return the fragment builder ` +
+            `(e.g. \`(b) => b.compute(...)\` or \`(b) => b\`); it returned a non-builder value`);
+    }
+    return out;
+}
+/**
+ * A persistent (immutable) FlowFragmentBuilder over a steps array. Every method
+ * returns a NEW sink carrying `[...steps, newStep]` — it never mutates `steps`.
+ * The accumulated list is read back (by `collectFragmentSteps`) via the
+ * module-private `FRAGMENT_STEPS` key, so only the RETURNED fragment's steps
+ * run. The phantom invariant brand exists only in the type.
+ */
+function makeStepSink(flowId, steps) {
+    const extend = (step) => makeStepSink(flowId, [...steps, step]);
+    // Typed `any` so methods can return sinks; the public type is the cast below.
+    const sink = {
+        step(ref, bindings) {
+            return extend(buildContractCallStep(flowId, ref, bindings));
+        },
+        compute(fn) {
+            return extend({ kind: "compute", fn });
+        },
+        condition(spec, thenB, elseB) {
+            return extend(buildConditionStep(flowId, "L2", spec, thenB, elseB));
+        },
+        conditionFn(spec, thenB, elseB) {
+            return extend(buildConditionStep(flowId, "L1", spec, thenB, elseB));
+        },
+        conditionAsync(spec, thenB, elseB) {
+            return extend(buildConditionStep(flowId, "L0", spec, thenB, elseB));
+        },
+        switchOn(lens) {
+            return (cases, deflt) => extend(buildSwitchOnStep(flowId, lens, cases, deflt));
+        },
+        switchCond(cases, deflt) {
+            return extend(buildSwitchCondStep(flowId, cases, deflt));
+        },
+        poll(ref, opts) {
+            return extend(buildPollStep(flowId, "L2", ref, opts));
+        },
+        pollFn(ref, opts) {
+            return extend(buildPollStep(flowId, "L1", ref, opts));
+        },
+        pollAsync(ref, opts) {
+            return extend(buildPollStep(flowId, "L0", ref, opts));
+        },
+    };
+    // Non-enumerable, frozen step list snapshot for this sink.
+    Object.defineProperty(sink, FRAGMENT_STEPS, {
+        value: Object.freeze(steps),
+        enumerable: false,
+    });
+    return sink;
+}
+/**
+ * condition / conditionFn / conditionAsync → predicate-mode branch (1 case +
+ * default). L2 builds a declarative `BranchPredicate` via `predicateScope`;
+ * L1/L0 wrap the opaque fn and REQUIRE a message (type-level + this runtime
+ * guard, so `as any` / JS callers can't produce an unlabeled opaque gate).
+ */
+function buildConditionStep(flowId, tier, spec, thenB, elseB) {
+    const thenSteps = collectFragmentSteps(flowId, thenB);
+    const elseSteps = elseB ? collectFragmentSteps(flowId, elseB) : [];
+    let predicate;
+    let message;
+    if (tier === "L2") {
+        predicate = spec.predicate(predicateScope());
+        assertL2Predicate(predicate, "condition"); // runtime brand: reject forged/opaque/non-JSON trees
+        message = spec.message;
+    }
+    else {
+        if (typeof spec.message !== "string" || spec.message.length === 0) {
+            throw new LensPurityError(tier === "L1" ? "conditionFn" : "conditionAsync", `opaque (${tier}) predicate requires a non-empty \`message\` — the projection marks ` +
+                `this branch as an opaque/dynamic gate and the message is its only human-facing label`);
+        }
+        message = spec.message;
+        predicate = { kind: "opaque", sync: tier === "L1", fn: spec.predicate };
+    }
+    return {
+        kind: "branch",
+        mode: "predicate",
+        cases: [{ ...(message ? { message } : {}), predicate, steps: thenSteps }],
+        default: elseSteps,
+    };
+}
+/** switchCond → predicate-mode branch (N cases + default), each case a declarative predicate. */
+function buildSwitchCondStep(flowId, cases, deflt) {
+    return {
+        kind: "branch",
+        mode: "predicate",
+        cases: cases.map((c) => {
+            const predicate = c.when(predicateScope());
+            assertL2Predicate(predicate, "switchCond"); // switch is always L2 — reject forged/opaque trees
+            return { predicate, steps: collectFragmentSteps(flowId, c.then) };
+        }),
+        default: collectFragmentSteps(flowId, deflt),
+    };
+}
+/**
+ * switchOn → value-mode branch. The subject lens runs the same P0 source gate +
+ * strict-Proxy path extraction as `w.when` (so the decision-table projection
+ * can't lie), values must be unique + finite, and the lens is normalized to
+ * `(ctx, s)` for uniform runtime evaluation (it is evaluated exactly once).
+ */
+function buildSwitchOnStep(flowId, lens, cases, deflt) {
+    void flowId;
+    assertSelectorSource(lens);
+    const path = extractSelectorPath(lens);
+    assertSwitchCaseValues(cases.map((c) => c.value));
+    return {
+        kind: "branch",
+        mode: "value",
+        subject: { lens: (_ctx, s) => lens(s), path },
+        cases: cases.map((c) => ({ value: c.value, steps: collectFragmentSteps(flowId, c.then) })),
+        default: collectFragmentSteps(flowId, deflt),
+    };
+}
+/**
+ * poll / pollFn / pollAsync → a bounded poll-until step. Validates flow-safety
+ * (like a contract-call step) + bounds (validatePollBounds), builds the exit
+ * predicate (L2 declarative over the response via predicateScope + brand gate;
+ * L1/L0 opaque, message REQUIRED), and applies the every/backoff defaults.
+ */
+function buildPollStep(flowId, tier, ref, opts) {
+    const adapter = _adapters.get(ref.protocol);
+    if (!adapter) {
+        throw new Error(`contract.flow(${JSON.stringify(flowId)}).poll: unknown protocol "${ref.protocol}". ` +
+            `Did you forget to import a contract plugin package?`);
+    }
+    if (!adapter.executeCaseInFlow) {
+        throw new Error(`contract.flow(${JSON.stringify(flowId)}).poll: adapter for "${ref.protocol}" ` +
+            `does not implement executeCaseInFlow — this protocol cannot appear in a flow.`);
+    }
+    const contractRef = ref.contract;
+    adapter.validateCaseForFlow?.(contractRef._spec, ref.caseKey, ref.contractId);
+    const stepLabel = opts.name ?? `${ref.contractId}#${ref.caseKey}`;
+    validatePollBounds({
+        timeout: opts.timeout,
+        maxAttempts: opts.maxAttempts,
+        perAttemptTimeout: opts.perAttemptTimeout,
+        every: opts.every,
+        backoff: opts.backoff,
+    }, stepLabel);
+    let until;
+    let message;
+    if (tier === "L2") {
+        until = opts.until(predicateScope());
+        assertL2Predicate(until, "poll"); // runtime brand: reject forged/opaque/non-JSON exit predicates
+        message = opts.message;
+    }
+    else {
+        if (typeof opts.message !== "string" || opts.message.length === 0) {
+            throw new LensPurityError(tier === "L1" ? "pollFn" : "pollAsync", `opaque (${tier}) poll exit predicate requires a non-empty \`message\` — the projection marks ` +
+                `this poll as an opaque/dynamic gate and the message is its only human-facing label`);
+        }
+        message = opts.message;
+        until = { kind: "opaque", sync: tier === "L1", fn: opts.until };
+    }
+    return {
+        kind: "poll",
+        name: opts.name,
+        ref,
+        caseKey: ref.caseKey,
+        contract: ref.contract,
+        bindings: {
+            in: opts.in,
+            out: opts.out,
+            ...(opts.accept ? { accept: opts.accept } : {}),
+        },
+        until,
+        ...(message ? { message } : {}),
+        every: opts.every ?? DEFAULT_EVERY_MS,
+        backoff: opts.backoff ?? 1,
+        ...(opts.timeout !== undefined ? { timeoutMs: opts.timeout } : {}),
+        ...(opts.perAttemptTimeout !== undefined ? { perAttemptTimeoutMs: opts.perAttemptTimeout } : {}),
+        ...(opts.maxAttempts !== undefined ? { maxAttempts: opts.maxAttempts } : {}),
+    };
+}
 export function flow(idOrMeta) {
     const meta = typeof idOrMeta === "string"
         ? { id: idOrMeta }
@@ -594,34 +826,7 @@ export function flow(idOrMeta) {
             return builder;
         },
         step(ref, bindings) {
-            const adapter = _adapters.get(ref.protocol);
-            if (!adapter) {
-                throw new Error(`contract.flow(${JSON.stringify(meta.id)}).step: unknown protocol "${ref.protocol}". ` +
-                    `Did you forget to import a contract plugin package (e.g. "@glubean/grpc")?`);
-            }
-            if (!adapter.executeCaseInFlow) {
-                throw new Error(`contract.flow(${JSON.stringify(meta.id)}).step: adapter for "${ref.protocol}" ` +
-                    `does not implement executeCaseInFlow — this protocol cannot appear in a flow.`);
-            }
-            // v10: flow-safety validation fires here (at step-declaration time),
-            // not at .case() time. The ref itself is pure; only when it enters a
-            // flow do we enforce adapter-specific rules like HTTP's "function-
-            // valued body/params/headers can't resolve in flow mode". This lets
-            // contract.bootstrap(ref) attach to the same ref (where function-
-            // valued fields legitimately receive resolvedInput).
-            const contractRef = ref.contract;
-            adapter.validateCaseForFlow?.(contractRef._spec, ref.caseKey, ref.contractId);
-            const step = {
-                kind: "contract-call",
-                name: bindings?.name,
-                ref,
-                caseKey: ref.caseKey,
-                contract: ref.contract,
-                bindings: bindings
-                    ? { in: bindings.in, out: bindings.out }
-                    : undefined,
-            };
-            steps.push(step);
+            steps.push(buildContractCallStep(meta.id, ref, bindings));
             return builder;
         },
         compute(fn) {
@@ -632,6 +837,40 @@ export function flow(idOrMeta) {
             steps.push(step);
             return builder;
         },
+        condition(spec, thenB, elseB) {
+            steps.push(buildConditionStep(meta.id, "L2", spec, thenB, elseB));
+            return builder;
+        },
+        conditionFn(spec, thenB, elseB) {
+            steps.push(buildConditionStep(meta.id, "L1", spec, thenB, elseB));
+            return builder;
+        },
+        conditionAsync(spec, thenB, elseB) {
+            steps.push(buildConditionStep(meta.id, "L0", spec, thenB, elseB));
+            return builder;
+        },
+        switchOn(lens) {
+            return (cases, deflt) => {
+                steps.push(buildSwitchOnStep(meta.id, lens, cases, deflt));
+                return builder;
+            };
+        },
+        switchCond(cases, deflt) {
+            steps.push(buildSwitchCondStep(meta.id, cases, deflt));
+            return builder;
+        },
+        poll(ref, opts) {
+            steps.push(buildPollStep(meta.id, "L2", ref, opts));
+            return builder;
+        },
+        pollFn(ref, opts) {
+            steps.push(buildPollStep(meta.id, "L1", ref, opts));
+            return builder;
+        },
+        pollAsync(ref, opts) {
+            steps.push(buildPollStep(meta.id, "L0", ref, opts));
+            return builder;
+        },
         build() {
             return finalize();
         },
@@ -720,6 +959,52 @@ function stepProjectionToRegistry(step) {
             writes: step.writes,
         };
     }
+    if (step.kind === "branch") {
+        if (step.mode === "value") {
+            return {
+                kind: "branch",
+                mode: "value",
+                name: step.name,
+                subjectPath: step.subjectPath,
+                cases: step.cases.map((c) => ({
+                    value: c.value,
+                    steps: c.steps.map(stepProjectionToRegistry),
+                })),
+                default: step.default.map(stepProjectionToRegistry),
+            };
+        }
+        return {
+            kind: "branch",
+            mode: "predicate",
+            name: step.name,
+            cases: step.cases.map((c) => ({
+                message: c.message,
+                predicate: c.predicate,
+                steps: c.steps.map(stepProjectionToRegistry),
+            })),
+            default: step.default.map(stepProjectionToRegistry),
+        };
+    }
+    if (step.kind === "poll") {
+        return {
+            kind: "poll",
+            name: step.name,
+            contractId: step.contractId,
+            caseKey: step.caseKey,
+            protocol: step.protocol,
+            target: step.target,
+            inputs: step.inputs,
+            outputs: step.outputs,
+            ...(step.accept ? { accept: step.accept } : {}),
+            ...(step.until !== undefined ? { until: step.until } : {}),
+            ...(step.message !== undefined ? { message: step.message } : {}),
+            every: step.every,
+            backoff: step.backoff,
+            ...(step.timeoutMs !== undefined ? { timeoutMs: step.timeoutMs } : {}),
+            ...(step.perAttemptTimeoutMs !== undefined ? { perAttemptTimeoutMs: step.perAttemptTimeoutMs } : {}),
+            ...(step.maxAttempts !== undefined ? { maxAttempts: step.maxAttempts } : {}),
+        };
+    }
     return {
         kind: "contract-call",
         name: step.name,
@@ -729,12 +1014,172 @@ function stepProjectionToRegistry(step) {
         target: step.target,
         inputs: step.inputs,
         outputs: step.outputs,
+        ...(step.accept ? { accept: step.accept } : {}),
     };
 }
 /**
  * Core flow execution helper. Implements the Rule 1 / Rule 2 teardown
  * semantics from contract-flow.md §7.
  */
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Execute ONE contract-call against its adapter (shared by the contract-call
+ * step and each poll attempt). Resolves `in`, enforces `needs` at the flow
+ * boundary, and calls `adapter.executeCaseInFlow`. Returns the raw response;
+ * the caller applies `out`. `opts.signal` is threaded to honoring adapters.
+ */
+async function executeContractCaseInFlow(step, state, ctx, runtimeId, opts) {
+    const adapter = _adapters.get(step.ref.protocol);
+    if (!adapter) {
+        throw new Error(`flow "${runtimeId}" step "${step.name ?? step.caseKey}": ` +
+            `no registered adapter for protocol "${step.ref.protocol}". ` +
+            `Did you forget to import a contract plugin package?`);
+    }
+    if (!adapter.executeCaseInFlow) {
+        throw new Error(`flow "${runtimeId}" step "${step.name ?? step.caseKey}": ` +
+            `adapter for "${step.ref.protocol}" does not implement executeCaseInFlow`);
+    }
+    // Enforce `needs` at the flow boundary (the conditional-tuple step() signature
+    // catches authoring shape, this catches `as any` / JS bypass + Zod transforms).
+    const contractSpec = step.contract._spec;
+    const caseSpec = contractSpec?.cases?.[step.caseKey];
+    const needsSchema = caseSpec?.needs;
+    const hasIn = typeof step.bindings?.in === "function";
+    if (needsSchema && !hasIn) {
+        throw new Error(`flow "${runtimeId}" step "${step.name ?? step.caseKey}": ` +
+            `case "${step.ref.contractId}.${step.caseKey}" declares \`needs\` ` +
+            `but the step has no \`bindings.in\`. Provide an ` +
+            `\`in: (state) => <logical input>\` binding or remove the \`needs\` schema.`);
+    }
+    let resolvedInputs = step.bindings?.in?.(state);
+    if (needsSchema) {
+        resolvedInputs = validateNeedsOutput(needsSchema, resolvedInputs, { testId: `${step.ref.contractId}.${step.caseKey}`, source: "flow" });
+    }
+    return adapter.executeCaseInFlow({
+        ctx,
+        contract: step.contract,
+        caseKey: step.caseKey,
+        resolvedInputs,
+        ...(step.bindings?.accept ? { accept: step.bindings.accept } : {}),
+        ...(opts?.signal ? { signal: opts.signal } : {}),
+    });
+}
+/**
+ * Bounded-retry execution of a poll step. Repeats the case until `until` holds
+ * (→ apply `out`, return next state) or a bound is exhausted (→ throw
+ * PollExhaustedError, failing the flow). Each attempt's request + exit predicate
+ * are budget-raced (so the loop is bounded regardless of whether the adapter
+ * honors `signal`) and run in quarantined contexts (probe noise / timed-out
+ * orphans discarded; the satisfying attempt's validation + in-budget predicate
+ * effects flushed). See contract-flow-poll.md §4.2.
+ */
+async function runPollStep(step, state, ctx, runtimeId) {
+    const label = step.name ?? `${step.contract._projection.id}#${step.caseKey}`;
+    // Runtime bound guard — the builder validates at construction, but `as any` /
+    // JS callers can reach runFlow with an unbounded poll step. Re-validate so a
+    // missing stop condition / per-attempt budget fails fast instead of looping
+    // forever (mirrors the runtime `needs` guard for contract-call steps).
+    validatePollBounds({
+        timeout: step.timeoutMs,
+        maxAttempts: step.maxAttempts,
+        perAttemptTimeout: step.perAttemptTimeoutMs,
+        every: step.every,
+        backoff: step.backoff,
+    }, label);
+    // Default interval/backoff — validatePollBounds permits them to be omitted, but
+    // the loop must not read `undefined` (sleep(undefined) hot-loops; delay*undefined
+    // is NaN). The builder applies the same defaults; this covers as-any/JS callers.
+    const everyMs = step.every ?? DEFAULT_EVERY_MS;
+    const backoff = step.backoff ?? 1;
+    const now = () => performance.now();
+    const start = now();
+    const deadline = step.timeoutMs !== undefined ? start + step.timeoutMs : Infinity;
+    const perAttempt = step.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 + abort signal; budget-raced so a non-honoring
+        // adapter can't block past the budget.
+        const ac = new AbortController();
+        let budgetAborted = false;
+        const budgetTimer = Number.isFinite(attemptBudget)
+            ? setTimeout(() => {
+                budgetAborted = true;
+                ac.abort();
+            }, Math.max(0, attemptBudget))
+            : undefined;
+        const reqCtx = quarantinedCtx(ctx);
+        const exhausted = () => new PollExhaustedError(label, attempt, `attempt budget ${Math.round(attemptBudget)}ms exceeded`);
+        try {
+            lastRes = await raceBudget(executeContractCaseInFlow(step, state, reqCtx, runtimeId, { signal: ac.signal }), attemptBudget, exhausted);
+        }
+        catch (err) {
+            // A signal-honoring adapter (HTTP) rejects with AbortError when OUR budget
+            // timer fired — convert it to the poll exhaustion error (with the attempt
+            // count) rather than leaking a raw AbortError.
+            if (budgetAborted && err instanceof Error && err.name === "AbortError") {
+                throw exhausted();
+            }
+            // A budget timeout discards this attempt's ctx (orphan); a genuine request
+            // error (incl. fatal validation / ctx.fail in the adapter) is in-budget —
+            // flush its buffered effects (the failure assertion lands) then fail the poll.
+            if (!(err instanceof PollExhaustedError))
+                reqCtx.flushTo(ctx);
+            throw 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");
+        // Exit predicate — quarantined ctx, budget-raced, flushed only on in-budget completion.
+        const predBudget = Math.min(deadline - now(), perAttempt - (now() - attemptStart));
+        const predCtx = quarantinedCtx(ctx);
+        let done;
+        try {
+            done = await raceBudget(evalPollExit(step.until, 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(ctx);
+            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(ctx); // in-budget: user's deliberate skip/fail/assert count
+        if (done) {
+            reqCtx.flushTo(ctx); // satisfying attempt: final-response validation failures surface (P1)
+            return step.bindings?.out ? step.bindings.out(state, lastRes) : state;
+        }
+        // probe (not satisfied): reqCtx discarded (pending validation noise).
+        if (step.maxAttempts && attempt >= step.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 * backoff, BACKOFF_CAP_MS);
+    }
+}
 export async function runFlow(flowContract, ctx) {
     const runtime = flowContract._flow;
     // If flow.setup throws → flow.teardown does NOT run (Rule 2).
@@ -742,81 +1187,50 @@ export async function runFlow(flowContract, ctx) {
         ? await runtime.setup(ctx)
         : undefined;
     try {
-        for (const step of runtime.steps) {
-            if (step.kind === "compute") {
-                // Compute: synchronous pure function. Enforce both syntactic and
-                // value-level async rejection.
-                if (step.fn.constructor?.name === "AsyncFunction") {
-                    throw new Error(`flow "${runtime.id}" compute step "${step.name ?? "<unnamed>"}": ` +
-                        `async functions are not allowed — compute must be synchronous and I/O-free`);
+        // Recursive step executor. `state` is the closure-level committed cell —
+        // branch sub-steps read and write the same `state`, so a taken branch can
+        // observe and mutate flow state exactly like a top-level step. Non-taken
+        // branches never run (and so never touch state). Branches nest via recursion.
+        const runSteps = async (steps) => {
+            for (const step of steps) {
+                if (step.kind === "branch") {
+                    // Evaluate selector/predicates against the current committed state,
+                    // then execute only the matched case's sub-steps (or default).
+                    const taken = await selectBranchSteps(step, state, ctx);
+                    await runSteps(taken);
+                    continue;
                 }
-                const result = step.fn(state);
-                if (result && typeof result.then === "function") {
-                    throw new Error(`flow "${runtime.id}" compute step "${step.name ?? "<unnamed>"}": ` +
-                        `returned a thenable (Promise or Promise-like) — compute must not return async values. ` +
-                        `If you need async initialization, use flow.setup() instead.`);
+                if (step.kind === "compute") {
+                    // Compute: synchronous pure function. Enforce both syntactic and
+                    // value-level async rejection.
+                    if (step.fn.constructor?.name === "AsyncFunction") {
+                        throw new Error(`flow "${runtime.id}" compute step "${step.name ?? "<unnamed>"}": ` +
+                            `async functions are not allowed — compute must be synchronous and I/O-free`);
+                    }
+                    const result = step.fn(state);
+                    if (result && typeof result.then === "function") {
+                        throw new Error(`flow "${runtime.id}" compute step "${step.name ?? "<unnamed>"}": ` +
+                            `returned a thenable (Promise or Promise-like) — compute must not return async values. ` +
+                            `If you need async initialization, use flow.setup() instead.`);
+                    }
+                    state = result;
+                    continue;
+                }
+                // poll branch — bounded retry of ONE case until the exit predicate holds
+                // (or a bound is exhausted → the poll step fails). Shares the committed
+                // `state` cell like every other step.
+                if (step.kind === "poll") {
+                    state = (await runPollStep(step, state, ctx, runtime.id));
+                    continue;
+                }
+                // contract-call branch
+                const response = await executeContractCaseInFlow(step, state, ctx, runtime.id);
+                if (step.bindings?.out) {
+                    state = step.bindings.out(state, response);
                 }
-                state = result;
-                continue;
-            }
-            // contract-call branch
-            const adapter = _adapters.get(step.ref.protocol);
-            if (!adapter) {
-                throw new Error(`flow "${runtime.id}" step "${step.name ?? step.caseKey}": ` +
-                    `no registered adapter for protocol "${step.ref.protocol}". ` +
-                    `Did you forget to import a contract plugin package?`);
-            }
-            if (!adapter.executeCaseInFlow) {
-                throw new Error(`flow "${runtime.id}" step "${step.name ?? step.caseKey}": ` +
-                    `adapter for "${step.ref.protocol}" does not implement executeCaseInFlow`);
-            }
-            // v10 Phase 2d Step 2+3 follow-up (RFR v2 / v2.1 P1): enforce `needs`
-            // schema at flow boundary, not just standalone. The conditional-tuple
-            // `step()` signature catches TS authoring shape mismatches, but runtime
-            // validation is the only line of defense against:
-            //   - `as any` / JS callers that bypass the TS check
-            //   - Zod parse / coerce / default semantics (schema can transform
-            //     the value, not just validate it)
-            //   - State drift producing invalid values at runtime despite valid
-            //     authoring types
-            // Standalone overlay path already validates via the same helper in
-            // `dispatchContract`'s test.fn closure; flow mirrors that to keep
-            // `needs` a true contract semantic rather than a TS-only boundary.
-            //
-            // Two-branch guard:
-            //   needs present + bindings.in missing  → throw (contract requires input)
-            //   needs present + bindings.in present  → validate unconditionally
-            //   needs absent                          → no guard
-            const contractSpec = step.contract._spec;
-            const caseSpec = contractSpec?.cases?.[step.caseKey];
-            const needsSchema = caseSpec?.needs;
-            const hasIn = typeof step.bindings?.in === "function";
-            if (needsSchema && !hasIn) {
-                throw new Error(`flow "${runtime.id}" step "${step.name ?? step.caseKey}": ` +
-                    `case "${step.ref.contractId}.${step.caseKey}" declares \`needs\` ` +
-                    `but the step has no \`bindings.in\`. The TypeScript conditional ` +
-                    `tuple on FlowBuilder.step() usually prevents this at compile time; ` +
-                    `this runtime check catches \`as any\` / JS bypass. Provide an ` +
-                    `\`in: (state) => <logical input>\` binding or remove the \`needs\` ` +
-                    `schema from the case.`);
-            }
-            let resolvedInputs = step.bindings?.in?.(state);
-            if (needsSchema) {
-                resolvedInputs = validateNeedsOutput(needsSchema, resolvedInputs, {
-                    testId: `${step.ref.contractId}.${step.caseKey}`,
-                    source: "flow",
-                });
-            }
-            const response = await adapter.executeCaseInFlow({
-                ctx,
-                contract: step.contract,
-                caseKey: step.caseKey,
-                resolvedInputs,
-            });
-            if (step.bindings?.out) {
-                state = step.bindings.out(state, response);
             }
-        }
+        };
+        await runSteps(runtime.steps);
     }
     finally {
         if (runtime.teardown) {
@@ -843,6 +1257,101 @@ export async function runFlow(flowContract, ctx) {
  * with step context so the author sees which step needs fixing.
  */
 export function normalizeFlow(runtime) {
+    // Recursive single-step normalizer. Branch sub-steps (cases + default) are
+    // normalized through the same helper, so nested branches and any lens-purity
+    // diagnostics inside them are handled identically at every depth.
+    const normalizeStep = (s, idx) => {
+        const stepLabel = s.name ??
+            (s.kind === "contract-call" || s.kind === "poll"
+                ? `${s.contract._projection.id}#${s.caseKey}`
+                : `step-${idx + 1}`);
+        if (s.kind === "branch") {
+            // Recurse over each case/default sub-step list. We re-index from 0 within
+            // the branch for labeling; the branch name (if any) carries outer context.
+            return extractBranchStep(s, (steps) => steps.map((sub, i) => normalizeStep(sub, i)));
+        }
+        if (s.kind === "poll") {
+            // Same Proxy dry-run as a contract-call step → the poll node carries
+            // input/output data-flow edges; the bounded-retry + exit predicate are
+            // carried by extractPollStep.
+            return extractPollStep(s, (ps) => {
+                let pInputs;
+                if (ps.bindings?.in) {
+                    try {
+                        pInputs = extractMappings(ps.bindings.in);
+                    }
+                    catch (err) {
+                        if (err instanceof LensPurityError) {
+                            throw new Error(`flow "${runtime.id}" step ${idx + 1} "${stepLabel}" (poll in lens): ${err.message}`);
+                        }
+                        throw err;
+                    }
+                }
+                let pOutputs;
+                if (ps.bindings?.out) {
+                    try {
+                        pOutputs = extractMappingsOut(ps.bindings.out);
+                    }
+                    catch (err) {
+                        if (err instanceof LensPurityError) {
+                            throw new Error(`flow "${runtime.id}" step ${idx + 1} "${stepLabel}" (poll out lens): ${err.message}`);
+                        }
+                        throw err;
+                    }
+                }
+                return { inputs: pInputs, outputs: pOutputs };
+            });
+        }
+        if (s.kind === "compute") {
+            try {
+                const { reads, writes } = traceComputeFn(s.fn);
+                return { kind: "compute", name: s.name, reads, writes };
+            }
+            catch (err) {
+                // Wrap compute-tracer failures with the same step-context format
+                // used for lens errors, so authoring mistakes are equally easy
+                // to localize regardless of which tracer caught them.
+                throw new Error(`flow "${runtime.id}" step ${idx + 1} "${stepLabel}" (compute): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        let inputs;
+        if (s.bindings?.in) {
+            try {
+                inputs = extractMappings(s.bindings.in);
+            }
+            catch (err) {
+                if (err instanceof LensPurityError) {
+                    throw new Error(`flow "${runtime.id}" step ${idx + 1} "${stepLabel}" (in lens): ${err.message}`);
+                }
+                throw err;
+            }
+        }
+        let outputs;
+        if (s.bindings?.out) {
+            try {
+                outputs = extractMappingsOut(s.bindings.out);
+            }
+            catch (err) {
+                if (err instanceof LensPurityError) {
+                    throw new Error(`flow "${runtime.id}" step ${idx + 1} "${stepLabel}" (out lens): ${err.message}`);
+                }
+                throw err;
+            }
+        }
+        return {
+            kind: "contract-call",
+            name: s.name,
+            contractId: s.contract._projection.id,
+            caseKey: s.caseKey,
+            protocol: s.ref.protocol,
+            target: s.ref.target,
+            inputs,
+            outputs,
+            ...(s.bindings?.accept
+                ? { accept: [...s.bindings.accept] }
+                : {}),
+        };
+    };
     return {
         id: runtime.id,
         protocol: "flow",
@@ -852,56 +1361,7 @@ export function normalizeFlow(runtime) {
         ...(runtime.skip !== undefined ? { skip: runtime.skip } : {}),
         ...(runtime.only !== undefined ? { only: runtime.only } : {}),
         setupDynamic: runtime.setup ? true : undefined,
-        steps: runtime.steps.map((s, idx) => {
-            const stepLabel = s.name ??
-                (s.kind === "contract-call" ? `${s.contract._projection.id}#${s.caseKey}` : `step-${idx + 1}`);
-            if (s.kind === "compute") {
-                try {
-                    const { reads, writes } = traceComputeFn(s.fn);
-                    return { kind: "compute", name: s.name, reads, writes };
-                }
-                catch (err) {
-                    // Wrap compute-tracer failures with the same step-context format
-                    // used for lens errors, so authoring mistakes are equally easy
-                    // to localize regardless of which tracer caught them.
-                    throw new Error(`flow "${runtime.id}" step ${idx + 1} "${stepLabel}" (compute): ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-            let inputs;
-            if (s.bindings?.in) {
-                try {
-                    inputs = extractMappings(s.bindings.in);
-                }
-                catch (err) {
-                    if (err instanceof LensPurityError) {
-                        throw new Error(`flow "${runtime.id}" step ${idx + 1} "${stepLabel}" (in lens): ${err.message}`);
-                    }
-                    throw err;
-                }
-            }
-            let outputs;
-            if (s.bindings?.out) {
-                try {
-                    outputs = extractMappingsOut(s.bindings.out);
-                }
-                catch (err) {
-                    if (err instanceof LensPurityError) {
-                        throw new Error(`flow "${runtime.id}" step ${idx + 1} "${stepLabel}" (out lens): ${err.message}`);
-                    }
-                    throw err;
-                }
-            }
-            return {
-                kind: "contract-call",
-                name: s.name,
-                contractId: s.contract._projection.id,
-                caseKey: s.caseKey,
-                protocol: s.ref.protocol,
-                target: s.ref.target,
-                inputs,
-                outputs,
-            };
-        }),
+        steps: runtime.steps.map(normalizeStep),
     };
 }
 /**
@@ -919,6 +1379,28 @@ export function extractMappings(fn) {
     const result = fn(proxy);
     return collectMappings(result, []);
 }
+/**
+ * Run a single-selector lens `fn: (state) => state.a.b.c` through the strict
+ * tracing Proxy and return the read path (root segment dropped), e.g.
+ * `s => s.lookup.status` → `["lookup", "status"]`.
+ *
+ * Used by the condition/switch predicate builders (contract-flow-condition.ts)
+ * to capture a predicate's read path at construction time. The strict Proxy
+ * enforces purity (method calls / `new` / arithmetic-via-coercion throw
+ * `LensPurityError`); callers add a source-level single-selector gate on top
+ * to also reject ternaries / free-variable reads the Proxy can't see.
+ *
+ * Throws `LensPurityError` if the lens does not resolve to a single traced
+ * value (e.g. returns an object literal, a constant, or `undefined`).
+ */
+export function extractSelectorPath(fn) {
+    const result = fn(makeLensProxy("state"));
+    if (!isTracedValue(result)) {
+        throw new LensPurityError("state", "selector must read a single state path (e.g. s => s.a.b), not compute or repack a value");
+    }
+    const full = result[TRACE_MARKER]; // "state.lookup.status"
+    return full.split(".").slice(1); // drop "state" root
+}
 /**
  * Extract FieldMappings from `out: (state, response) => newState`.
  * Same purity contract as `extractMappings`.