@glubean/sdk 0.5.1 → 0.8.0

package/dist/contract-core.js

@@ -6,9 +6,6 @@
  *   - `contract.register(protocol, adapter)` — plugin extension point
  *   - `contract[protocol](id, spec)` dispatcher — validates 1:1 case keys,
  *     invokes adapter.execute per case, registers tests + ContractRegistryMeta
- *   - `contract.flow(id)` — protocol-agnostic FlowBuilder
- *   - `runFlow(flow, ctx)` — core flow execution helper (Rule 1/2 teardown)
- *   - `normalizeFlow(runtime)` — Runtime → ExtractedFlowProjection
  *   - Permissive Proxy tracer for `compute` nodes (best-effort reads/writes)
  *
  * HTTP is NOT handled here — it registers itself in `./contract-http/`.
@@ -19,8 +16,6 @@
  *   - `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";
 /**
@@ -58,7 +53,7 @@ async function runCleanupsLifo(cleanups, testId) {
         }
     }
 }
-function validateNeedsOutput(needsSchema, value, ctx) {
+export function validateNeedsOutput(needsSchema, value, ctx) {
     const sp = needsSchema.safeParse;
     if (typeof sp === "function") {
         const result = sp(value);
@@ -68,7 +63,8 @@ function validateNeedsOutput(needsSchema, value, ctx) {
         const sourceLabel = ctx.source === "bootstrap" ? "Bootstrap output"
             : ctx.source === "explicit" ? "Explicit input"
                 : ctx.source === "bootstrap-params" ? "Bootstrap params"
-                    : "Flow `in` output";
+                    : ctx.source === "workflow" ? "Workflow `in` output"
+                        : "Flow `in` output";
         const schemaLabel = ctx.source === "bootstrap-params" ? "params schema" : "needs schema";
         throw new Error(`${sourceLabel} for case "${ctx.testId}" does not satisfy ${schemaLabel}:\n${lines.join("\n")}`);
     }
@@ -191,10 +187,15 @@ function dispatchContract(protocol, adapter, id, spec) {
             ? [contractTagsRaw]
             : [];
     const projCaseMap = new Map(projection.cases.map((c) => [c.key, c]));
-    const tests = Object.entries(cases).map(([caseKey, caseSpec]) => {
+    const tests = Object.entries(cases).flatMap(([caseKey, caseSpec]) => {
         const testId = `${id}.${caseKey}`;
         const testName = `${id} — ${caseKey}`;
         const projCase = projCaseMap.get(caseKey);
+        // Non-runnable cases (adapter sets `runnable: false`, e.g. inbound
+        // cases — inbound-contract-design §9.5): no Test, no runnable-inventory
+        // entry. The case exists in projection/_extracted only.
+        if (projCase.runnable === false)
+            return [];
         const caseTags = caseSpec.tags ?? [];
         const allTags = [...contractTags, ...caseTags];
         // Projection lifecycle/severity are authoritative
@@ -476,7 +477,13 @@ function dispatchContract(protocol, adapter, id, spec) {
             defaultRun,
             contract: registryMeta,
         });
-        return testDef;
+        // Keep contract cases on the LEGACY harness under the runner-on-engine cutover
+        // (engineSupports excludes marked tests). Outbound cases are common HTTP the
+        // engine could drive, but inbound (node:http webhook + node:crypto signing) is
+        // node-only, and the runner golden suite can't validate the engine path for
+        // contracts — so conservatively all contract cases stay legacy (plan 0005 §scope).
+        testDef.__glubean_kind = "contract";
+        return [testDef];
     });
     // Core injects id into both _projection and _spec carrier
     const enrichedProjection = { ...projection, id };
@@ -498,7 +505,7 @@ function dispatchContract(protocol, adapter, id, spec) {
             // ref used via contract.bootstrap(overlay) legitimately uses
             // function-valued fields with `resolvedInput` — v9's
             // validateCaseForFlow incorrectly rejected that at .case() time.
-            return makeContractCaseRef(protocol, id, projection.target, key, contractObj, spec);
+            return makeContractCaseRef(protocol, id, projection.target, key, contractObj, spec, projCaseMap.get(key)?.direction);
         },
     });
     return contractObj;
@@ -536,7 +543,7 @@ function validateCaseKeys(protocol, specCases, projectionCases) {
  * should enforce it in their own `.case()` wrapper if needed. For
  * built-in HTTP adapter, see `./contract-http/adapter.ts`.
  */
-function makeContractCaseRef(protocol, contractId, target, caseKey, contract, spec) {
+function makeContractCaseRef(protocol, contractId, target, caseKey, contract, spec, direction) {
     const caseSpec = spec.cases?.[caseKey];
     return {
         __glubean_type: "contract-case-ref",
@@ -546,6 +553,7 @@ function makeContractCaseRef(protocol, contractId, target, caseKey, contract, sp
         target,
         contract,
         ...(caseSpec?.runnability ? { runnability: caseSpec.runnability } : {}),
+        ...(direction ? { direction } : {}),
     };
 }
 /**
@@ -559,818 +567,24 @@ function makeContractCaseRef(protocol, contractId, target, caseKey, contract, sp
  * compatible Needs, masking real type errors (Spike 0 Finding 1).
  */
 export function bootstrap(ref, spec) {
+    if (ref.direction === "inbound") {
+        throw new Error(`contract.bootstrap: case "${ref.contractId}.${ref.caseKey}" is inbound — ` +
+            `it is awaited (workflow inbound poll), never executed, so a bootstrap ` +
+            `overlay has no meaning for it.`);
+    }
     return registerBootstrap(ref, spec);
 }
 export const contract = {
     register,
-    flow,
     bootstrap,
 };
-// =============================================================================
-// Flow: FlowBuilder + runFlow + normalizeFlow + tracePureFn
-// =============================================================================
-/**
- * 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 }
-        : idOrMeta;
-    const steps = [];
-    let setupFn;
-    let teardownFn;
-    let built = false;
-    let extraMeta = {};
-    const builder = {
-        __glubean_type: "flow-builder",
-        meta(m) {
-            extraMeta = { ...extraMeta, ...m };
-            return builder;
-        },
-        setup(fn) {
-            setupFn = fn;
-            return builder;
-        },
-        teardown(fn) {
-            teardownFn = fn;
-            return builder;
-        },
-        step(ref, bindings) {
-            steps.push(buildContractCallStep(meta.id, ref, bindings));
-            return builder;
-        },
-        compute(fn) {
-            const step = {
-                kind: "compute",
-                fn: fn,
-            };
-            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();
-        },
-    };
-    // Auto-finalize via microtask (mirrors TestBuilder pattern)
-    queueMicrotask(() => {
-        if (!built)
-            finalize();
-    });
-    function finalize() {
-        if (built)
-            return builtResult;
-        built = true;
-        const runtime = {
-            protocol: "flow",
-            description: extraMeta.description,
-            tags: extraMeta.tags,
-            extensions: extraMeta.extensions,
-            ...(extraMeta.skip !== undefined ? { skip: extraMeta.skip } : {}),
-            ...(extraMeta.only !== undefined ? { only: extraMeta.only } : {}),
-            setup: setupFn,
-            teardown: teardownFn,
-            steps,
-        };
-        // Build the single Test that runFlow orchestrates.
-        const flowTest = {
-            meta: {
-                id: meta.id,
-                name: extraMeta.name ?? meta.id,
-                tags: extraMeta.tags,
-                description: extraMeta.description,
-                // `FlowMeta.skip: string` (the reason) → `TestMeta.deferred: string`
-                // mirrors the ContractCase.deferred convention so downstream
-                // reporters render the skip reason consistently.
-                ...(extraMeta.skip !== undefined ? { deferred: extraMeta.skip } : {}),
-                ...(extraMeta.only !== undefined ? { only: extraMeta.only } : {}),
-            },
-            type: "simple",
-            fn: async (ctx) => {
-                // Belt-and-suspenders: runtime ctx.skip in case the runner didn't
-                // filter on meta.deferred (e.g. the user ran with an explicit
-                // target that bypasses skip filters).
-                if (extraMeta.skip)
-                    ctx.skip(extraMeta.skip);
-                await runFlow(resultHandle, ctx);
-            },
-        };
-        const arr = [flowTest];
-        const runtimeWithId = { ...runtime, id: meta.id };
-        // Pre-compute extracted projection so downstream consumers (scanner,
-        // CLI, MCP, Cloud) get full field mappings + compute reads/writes
-        // without having to import the SDK to call normalizeFlow themselves.
-        const extracted = normalizeFlow(runtimeWithId);
-        const resultHandle = Object.assign(arr, {
-            _flow: runtimeWithId,
-            _extracted: extracted,
-        });
-        // Register flow in the registry
-        const flowRegistryMeta = {
-            id: extracted.id,
-            description: extracted.description,
-            tags: extracted.tags,
-            steps: extracted.steps.map(stepProjectionToRegistry),
-            setupDynamic: extracted.setupDynamic,
-        };
-        registerTest({
-            id: meta.id,
-            name: extraMeta.name ?? meta.id,
-            type: "simple",
-            tags: extraMeta.tags,
-            description: extraMeta.description,
-            flow: flowRegistryMeta,
-        });
-        builtResult = resultHandle;
-        return resultHandle;
-    }
-    let builtResult;
-    return builder;
-}
-function stepProjectionToRegistry(step) {
-    if (step.kind === "compute") {
-        return {
-            kind: "compute",
-            name: step.name,
-            reads: step.reads,
-            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,
-        contractId: step.contractId,
-        caseKey: step.caseKey,
-        protocol: step.protocol,
-        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).
-    let state = runtime.setup
-        ? await runtime.setup(ctx)
-        : undefined;
-    try {
-        // 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;
-                }
-                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);
-                }
-            }
-        };
-        await runSteps(runtime.steps);
-    }
-    finally {
-        if (runtime.teardown) {
-            // flow.teardown runs in Rule 2 outer-finally. Its errors are logged
-            // but must not mask the primary exception.
-            try {
-                await runtime.teardown(ctx, state);
-            }
-            catch (teardownErr) {
-                ctx.log?.(`flow.teardown failed: ${String(teardownErr)}`);
-            }
-        }
-    }
-}
-// =============================================================================
-// normalizeFlow + permissive Proxy tracer
-// =============================================================================
-/**
- * Normalize a RuntimeFlowProjection to JSON-safe ExtractedFlowProjection.
- * Runs Proxy dry-run of lens functions to extract FieldMappings.
- *
- * Lens purity is enforced here: if a `step.bindings.in` or `.out` lens
- * violates purity (method call, `new`, etc.), `LensPurityError` is thrown
- * 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",
-        description: runtime.description,
-        tags: runtime.tags,
-        extensions: runtime.extensions,
-        ...(runtime.skip !== undefined ? { skip: runtime.skip } : {}),
-        ...(runtime.only !== undefined ? { only: runtime.only } : {}),
-        setupDynamic: runtime.setup ? true : undefined,
-        steps: runtime.steps.map(normalizeStep),
-    };
-}
 /**
  * Run a pure lens `fn: (state) => output` with a tracing Proxy, extracting
  * FieldMappings from state paths to output paths.
  *
  * Pure-lens enforcement: method calls, `new`, and coercion on the state
  * proxy raise `LensPurityError`. Errors are **not** swallowed — the caller
- * (typically `normalizeFlow`) wraps them with step context and re-throws,
+ * (legacy flow's normalizer used to) wraps them with step context and re-throws,
  * so authors see the failure at flow build time rather than silently
  * losing projection data.
  */
@@ -1466,7 +680,7 @@ function isTracedValue(v) {
 /**
  * Raised by the strict lens Proxy when a user lens fn attempts an operation
  * that breaks the "pure field access + repack" contract. Caught and re-
- * thrown with step context by `normalizeFlow`.
+ * thrown with step context by callers.
  */
 export class LensPurityError extends Error {
     path;