@glubean/sdk 0.5.1 → 0.7.0

package/dist/workflow/builder.js

@@ -0,0 +1,1150 @@
+import { predicateScope, assertL2Predicate, selectorPath } from "../predicates.js";
+import { validatePollBounds, DEFAULT_EVERY_MS } from "../poll-primitives.js";
+import { registerTest } from "../internal.js";
+import { traceComputeFn } from "../contract-core.js";
+import { interpolateTemplate, normalizeEachTable } from "../test/utils.js";
+import { validateRetryMeta } from "./retry.js";
+import { projectWorkflow } from "./project.js";
+/**
+ * Validate a per-node timeout (§17 #4) at build time. Only the ASYNC node
+ * kinds accept one; `compute` is synchronous by contract and `poll`/the branch
+ * family own their own bounds/decision semantics — a timeout there would be
+ * dead config pretending to protect something.
+ */
+function validateNodeTimeout(meta, kind) {
+    if (meta.timeout === undefined)
+        return;
+    if (kind !== "call" && kind !== "action" && kind !== "check") {
+        throw new Error(`workflow.${kind}() "${meta.id}": \`timeout\` is not supported on ${kind} nodes — ` +
+            (kind === "poll"
+                ? "a poll owns its own bounds (timeout/perAttemptTimeout/maxAttempts)"
+                : kind === "compute"
+                    ? "compute is synchronous by contract"
+                    : kind === "group"
+                        ? "a group is a display-only bracket; members carry their own timeouts"
+                        : "the branch family's decision has no timeout semantics"));
+    }
+    if (typeof meta.timeout !== "number" || !Number.isFinite(meta.timeout) || meta.timeout <= 0) {
+        throw new Error(`workflow.${kind}() "${meta.id}": \`timeout\` must be a finite number > 0 (ms); got ${String(meta.timeout)}`);
+    }
+}
+/**
+ * Normalize a step's first argument into a `NodeMeta`. A string is shorthand for
+ * the node `id` (mirrors `workflow(id)`); an object is spread as-is. `id` falls
+ * back to `name` then to a positional `${idPrefix}node-${index}`; `name` defaults
+ * to `id`. `idPrefix` keeps anonymous-fallback ids unique inside branch sides
+ * (each side collects with its own positional counter — codex S2.4a R7).
+ */
+function normalizeNodeMeta(input, index, idPrefix = "") {
+    const m = typeof input === "string" ? { id: input } : { ...input };
+    const id = m.id ?? m.name ?? `${idPrefix}node-${index}`;
+    return { ...m, id, name: m.name ?? id };
+}
+class WorkflowBuilderImpl {
+    _idPrefix;
+    _isChild;
+    /** Discovery marker — the runner's resolver auto-builds exported builders. */
+    __glubean_type = "workflow-builder";
+    _meta;
+    _setup;
+    _setupTimeoutMs;
+    _setupNote;
+    _teardown;
+    _teardownTimeoutMs;
+    _teardownNote;
+    _nodes = [];
+    _built;
+    /** The first authoring error, if any — a poisoned builder never finalizes. */
+    _poisoned;
+    /** Set by `.route()` — the tree is terminal; only teardown/build may follow. */
+    _terminated;
+    /** workflow.each: registration is deferred until EVERY row passes the
+     * one-structure validation — set by the engine, never by users. */
+    _suppressRegistration = false;
+    constructor(meta, _idPrefix = "", 
+    /** Child builders (branch/poll sub-graphs) never finalize/register. */
+    _isChild = false) {
+        this._idPrefix = _idPrefix;
+        this._isChild = _isChild;
+        this._meta = meta;
+        // Auto-finalize via microtask (mirrors contract.flow()/TestBuilder): an
+        // exported, never-built workflow still registers for discovery. A poisoned
+        // builder (a chained call threw) must NOT auto-build — registering the
+        // partial graph would leak a phantom workflow into discovery when the
+        // author caught the error (codex S2.5 R3 P2).
+        if (!_isChild) {
+            queueMicrotask(() => {
+                if (this._built || this._poisoned !== undefined)
+                    return;
+                try {
+                    this.build();
+                }
+                catch (e) {
+                    // Auto-build is fire-and-forget on a microtask — a build-time
+                    // validation error (e.g. duplicate node ids) must not become an
+                    // unhandled exception (codex S2.13 R1 P1). The builder is poisoned
+                    // (build() did that) so it never registers; surface the cause
+                    // loudly enough to find.
+                    console.error(`[glubean] workflow "${this._meta.id}" failed to auto-build and will not be registered: ` +
+                        (e instanceof Error ? e.message : String(e)));
+                }
+            });
+        }
+    }
+    // The CHAINED brand is purely type-level — at runtime every chain call
+    // returns this same instance; the cast just re-labels it.
+    chained() {
+        return this;
+    }
+    // Wraps every authoring mutator: a throw from validation (invalid poll
+    // bounds, sub-builder build(), …) leaves the graph half-authored, so it
+    // poisons the builder — build()/auto-build then refuse instead of
+    // registering the partial graph (codex S2.5 R3 P2). A post-build mutation
+    // throw does NOT poison: the registered graph is complete and stays valid.
+    authoring(fn) {
+        try {
+            return fn();
+        }
+        catch (e) {
+            if (!this._built)
+                this._poisoned ??= e;
+            throw e;
+        }
+    }
+    meta(meta) {
+        return this.authoring(() => {
+            this.assertNotBuilt("meta");
+            // ENGINE-OWNED fields are locked (codex S2.12 R21 P2): a factory
+            // overwriting them would desync discovery from execution. The Omit
+            // above blocks the type level; this reapply blocks `as any`.
+            this._meta = {
+                ...this._meta,
+                ...meta,
+                id: this._meta.id,
+                templateId: this._meta.templateId,
+                groupId: this._meta.groupId,
+                parallel: this._meta.parallel,
+            };
+            return this.chained();
+        });
+    }
+    /** A blank hint is noise pretending to be signal (phase4 §6.1). */
+    static validateLifecycleNote(phase, note) {
+        if (note === undefined)
+            return;
+        if (typeof note !== "string" || note.trim().length === 0) {
+            throw new Error(`workflow.${phase}(): \`note\` must be a non-empty string — omit it instead of leaving it blank`);
+        }
+    }
+    static validateLifecycleTimeout(phase, timeout) {
+        if (timeout === undefined)
+            return;
+        if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+            throw new Error(`workflow.${phase}(): \`timeout\` must be a finite number > 0 (ms); got ${String(timeout)}`);
+        }
+    }
+    setup(fn, opts) {
+        return this.authoring(() => {
+            this.assertNotBuilt("setup");
+            // setup runs first at execution, so authoring it after a node OR after
+            // teardown would make the advertised state type dishonest (codex slice-1 P2).
+            if (this._nodes.length > 0 || this._teardown) {
+                throw new Error("workflow.setup() must be called before any step (call/action/check/compute) or teardown");
+            }
+            // Lifecycle belongs to the WORKFLOW AUTHOR: a fragment silently
+            // replacing the host's setup (and reshaping runtime state invisibly to
+            // the tip guard, which only tracks nodes) is exactly the stale-handle
+            // hazard again (codex S2.13 R5 P2). meta() stays allowed — display
+            // annotation, not behavior.
+            if (this._fragmentDepth > 0) {
+                throw new Error(`workflow "${this._meta.id}": a .use() fragment cannot declare setup — ` +
+                    `lifecycle belongs to the workflow author`);
+            }
+            WorkflowBuilderImpl.validateLifecycleTimeout("setup", opts?.timeout);
+            WorkflowBuilderImpl.validateLifecycleNote("setup", opts?.note);
+            this._setup = fn;
+            this._setupTimeoutMs = opts?.timeout;
+            this._setupNote = opts?.note;
+            return this;
+        });
+    }
+    teardown(fn, opts) {
+        return this.authoring(() => {
+            this.assertNotBuilt("teardown");
+            if (this._fragmentDepth > 0) {
+                throw new Error(`workflow "${this._meta.id}": a .use() fragment cannot declare teardown — ` +
+                    `lifecycle belongs to the workflow author`);
+            }
+            WorkflowBuilderImpl.validateLifecycleTimeout("teardown", opts?.timeout);
+            WorkflowBuilderImpl.validateLifecycleNote("teardown", opts?.note);
+            this._teardown = fn;
+            this._teardownTimeoutMs = opts?.timeout;
+            this._teardownNote = opts?.note;
+            return this.chained();
+        });
+    }
+    // A finalized workflow is immutable — its Test/registry entry already
+    // captured the graph; a later mutation would be silently dropped.
+    assertNotBuilt(method) {
+        if (this._built) {
+            throw new Error(`workflow.${method}() called after build() — the workflow is already finalized`);
+        }
+    }
+    // teardown receives the FINAL state, so no step may follow it (else its
+    // callback is authored against a stale state type) (codex slice-1 P2).
+    // A `.route()` terminal tree likewise allows no further graph nodes (§9 #5).
+    assertNoTeardown(method) {
+        this.assertNotBuilt(method);
+        if (this._terminated) {
+            throw new Error(`workflow.${method}() cannot follow ${this._terminated} — a route is terminal; ` +
+                `only .teardown()/.build() may come after`);
+        }
+        if (this._teardown) {
+            throw new Error(`workflow.${method}() cannot be added after .teardown() — teardown must be the last step`);
+        }
+    }
+    // Impl uses a broad `...rest` + `any` return so it satisfies the interface's
+    // generic conditional-tuple signature; call-site type-checking uses the precise
+    // interface signature, not this one.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    call(idOrMeta, ref, ...rest) {
+        return this.authoring(() => {
+            this.assertNoTeardown("call");
+            const meta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(meta, "call");
+            if (ref?.direction === "inbound") {
+                throw new Error(`workflow.call() "${meta.id}": case "${ref.contractId}.${ref.caseKey}" is ` +
+                    `inbound — the counterparty calls us, so there is nothing to call. ` +
+                    `Await it with an inbound poll instead.`);
+            }
+            const bindings = rest[0];
+            if (bindings?.retry)
+                validateRetryMeta(bindings.retry, meta.id);
+            const node = {
+                kind: "contract-call",
+                meta,
+                ref,
+                in: bindings?.in,
+                out: bindings?.out,
+                accept: bindings?.accept,
+                retry: bindings?.retry,
+            };
+            this._nodes.push(node);
+            return this;
+        });
+    }
+    // Broad impl satisfies both action overloads; call sites use the interface.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    action(idOrMeta, fn, opts) {
+        return this.authoring(() => {
+            this.assertNoTeardown("action");
+            const meta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(meta, "action");
+            if (opts?.retry)
+                validateRetryMeta(opts.retry, meta.id);
+            const node = {
+                kind: "action",
+                meta,
+                fn: fn,
+                project: opts?.project,
+                retry: opts?.retry,
+            };
+            this._nodes.push(node);
+            return this;
+        });
+    }
+    // Broad impl satisfies both check overloads; call sites use the interface.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    check(idOrMeta, fnOrOpts, opts) {
+        return this.authoring(() => {
+            this.assertNoTeardown("check");
+            const checkMeta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(checkMeta, "check");
+            // Declarative form: { expect: (w) => [...] } (phase4 §7)
+            if (fnOrOpts !== null &&
+                typeof fnOrOpts === "object" &&
+                typeof fnOrOpts.expect === "function") {
+                const expectFn = fnOrOpts.expect;
+                const items = expectFn(predicateScope());
+                if (!Array.isArray(items) || items.length === 0) {
+                    throw new Error(`workflow.check() "${checkMeta.id}": \`expect\` must return a non-empty array of predicates`);
+                }
+                for (const item of items) {
+                    // every item must be L2 declarative — an opaque predicate here is a
+                    // contradiction in terms; use the inline form for opaque logic.
+                    assertL2Predicate(item, `check "${checkMeta.id}" expect`);
+                }
+                const node = {
+                    kind: "check",
+                    meta: checkMeta,
+                    expects: Object.freeze([...items]),
+                };
+                this._nodes.push(node);
+                return this.chained();
+            }
+            if (typeof fnOrOpts !== "function") {
+                throw new Error(`workflow.check() "${checkMeta.id}" requires a check function or { expect: (w) => [...] }`);
+            }
+            const node = {
+                kind: "check",
+                meta: checkMeta,
+                fn: fnOrOpts,
+                project: opts?.project,
+            };
+            this._nodes.push(node);
+            return this.chained();
+        });
+    }
+    // Broad impl returns `any` to satisfy the interface's conditional return type.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    compute(idOrMeta, fn) {
+        return this.authoring(() => {
+            this.assertNoTeardown("compute");
+            // Catch the common async case here (compute is modeled/projected as a
+            // synchronous `full` transform; an async fn would store a Promise-returning
+            // fn — codex slice-1 P2). A sync fn that still RETURNS a promise
+            // (`() => Promise.resolve(x)`) can't be caught at build time (the fn isn't
+            // invoked here); TODO(executor): thenable-check the compute result at run
+            // time and fail the node.
+            if (fn?.constructor?.name === "AsyncFunction") {
+                throw new Error("workflow.compute() must be synchronous — use .action() for async work");
+            }
+            const computeMeta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(computeMeta, "compute");
+            // S2.18 lens-purity: trace the dataflow at BUILD time (proxy dry-run —
+            // the same tracer flow's normalizer runs). Transform LOGIC stays
+            // undeclarable, which is why compute grades `partial` at best.
+            //
+            // DESIGN STANCE (codex S2.18 R3, defended): yes, this executes the fn
+            // once at authoring/scan time. That is the established vNext mechanism
+            // for EVERY declared function — predicate lenses, selector lenses,
+            // via/correlate lenses all dry-run through a proxy at build — and the
+            // public contract of compute is "pure synchronous transform": a body
+            // with closure mutation/side effects (`++n`) violates that contract,
+            // and the dry run makes the violation observable instead of latent.
+            // No published users exist (pre-0.6 window); a static-analysis
+            // alternative is the regex bottomless pit S2.15 already disproved.
+            //
+            // A throw during the dry run is NOT an authoring error: the proxy
+            // feeds dummy values ("", 0) and a value-sensitive helper
+            // (`new URL(state.url)`, schema validators) may legitimately reject
+            // them — degrade to untraced (grade `opaque`) instead of failing a
+            // build the runtime would have passed (codex S2.18 R1 P2).
+            let traced;
+            try {
+                traced = traceComputeFn(fn);
+            }
+            catch {
+                traced = undefined;
+            }
+            const node = {
+                kind: "compute",
+                meta: computeMeta,
+                fn: fn,
+                ...(traced ? { reads: traced.reads, writes: traced.writes } : {}),
+            };
+            this._nodes.push(node);
+            return this;
+        });
+    }
+    /** DEPTH of currently-executing `.use()` fragments (nested fragments
+     * compose — a boolean would be cleared by the inner finally, reopening the
+     * premature-build hole; codex S2.13 R3 P2). A fragment finalizing the
+     * workflow (`b.build()` via JS/as-any) would register it BEFORE use() can
+     * reject the handle, and the set `_built` would defeat poisoning. */
+    _fragmentDepth = 0;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    use(fragment) {
+        return this.authoring(() => {
+            this.assertNotBuilt("use");
+            if (typeof fragment !== "function") {
+                throw new Error(`workflow.use() on "${this._meta.id}": a fragment function is required`);
+            }
+            // The fragment gets a TIP-GUARDED FACADE, not the raw builder — the
+            // same stale-handle hazard branch sides have exists on the trunk: a
+            // block-body fragment could chain off a pre-reshape handle and run a
+            // check against state that no longer exists (codex S2.13 R3 P2).
+            const { facade, tipOf } = WorkflowBuilderImpl.makeTipGuardedFacade(this, `fragment in "${this._meta.id}"`);
+            let result;
+            this._fragmentDepth += 1;
+            try {
+                result = fragment(facade);
+            }
+            finally {
+                this._fragmentDepth -= 1;
+            }
+            // An async fragment would add nodes after the chain moved on — same
+            // hazard as an async branch side (codex S2.4a R5). Consume the promise
+            // first: its later rejection would otherwise surface as unhandled even
+            // when the caller catches this throw (codex S2.13 R2 P2).
+            if (result && typeof result.then === "function") {
+                result.then(() => { }, () => { });
+                throw new Error(`workflow.use() on "${this._meta.id}": the fragment must be synchronous — an ` +
+                    `async fragment loses any steps added after an await`);
+            }
+            // The CHAINED brand is type-only — a fragment returning a chain built
+            // from a DIFFERENT workflow() satisfies the type while redirecting
+            // every subsequent trunk call to that other builder and leaving this
+            // one half-authored (codex phase4 design-R1). The returned handle must
+            // be THIS use()'s facade chain AND its tip (a stale prefix means steps
+            // were appended after it — same belt-and-suspenders as branch sides).
+            const returnedTip = tipOf(result);
+            if (returnedTip === undefined) {
+                throw new Error(`workflow.use() on "${this._meta.id}": the fragment must return the chain built ` +
+                    `from the builder it was given — it returned ${result === undefined ? "undefined" : "a different builder/value"}`);
+            }
+            if (returnedTip !== this._nodes.length) {
+                throw new Error(`workflow.use() on "${this._meta.id}": the fragment returned a stale chain handle — ` +
+                    `return the value of the LAST chain call`);
+            }
+            return this.chained();
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    group(idOrMeta, body) {
+        return this.authoring(() => {
+            this.assertNoTeardown("group");
+            const meta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(meta, "group");
+            if (typeof body !== "function") {
+                throw new Error(`workflow.group() "${meta.id}" requires a body function`);
+            }
+            const node = {
+                kind: "group",
+                meta,
+                nodes: this.collectSubNodes(body, `${meta.id}.`),
+            };
+            this._nodes.push(node);
+            return this.chained();
+        });
+    }
+    branch(idOrMeta, opts) {
+        return this.authoring(() => {
+            this.assertNoTeardown("branch");
+            const meta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(meta, "branch");
+            // 2-way sugar over the branch-family IR (addendum §9): one predicate case
+            // (then) + default (else). Prefix each side's anonymous-fallback ids with
+            // the branch id + side so flat outcome/projection ids stay unique (S2.4a R7).
+            const node = {
+                kind: "branch",
+                meta,
+                mode: "predicate",
+                message: opts.message,
+                cases: [
+                    {
+                        when: this.buildBranchPredicate(opts),
+                        label: "then",
+                        nodes: this.collectSubNodes(opts.then, `${meta.id}.then.`),
+                    },
+                ],
+                default: opts.else ? this.collectSubNodes(opts.else, `${meta.id}.else.`) : undefined,
+            };
+            this._nodes.push(node);
+            return this.chained();
+        });
+    }
+    // Broad impls satisfy the interface signatures; call sites type-check against
+    // the precise interface, not these.
+    switch(idOrMeta, opts) {
+        return this.authoring(() => {
+            this.assertNoTeardown("switch");
+            const meta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(meta, "switch");
+            const node = {
+                kind: "branch",
+                meta,
+                ...this.buildFamilyDecision("switch", meta.id, opts),
+                default: opts.default
+                    ? this.collectSubNodes(opts.default, `${meta.id}.default.`)
+                    : undefined, // optional = identity pass-through (addendum §9 #4)
+            };
+            this._nodes.push(node);
+            return this.chained();
+        });
+    }
+    route(idOrMeta, opts) {
+        return this.authoring(() => {
+            this.assertNoTeardown("route");
+            const meta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(meta, "route");
+            // route's default is REQUIRED (a no-match must be defined — §9 #5); the
+            // types enforce it, but `as any`/JS callers can omit it.
+            if (typeof opts.default !== "function") {
+                throw new Error(`workflow.route() "${meta.id}" requires a \`default\` case — a no-match path must be defined`);
+            }
+            const node = {
+                kind: "branch",
+                meta,
+                ...this.buildFamilyDecision("route", meta.id, opts),
+                default: this.collectSubNodes(opts.default, `${meta.id}.default.`),
+                terminal: true,
+            };
+            this._nodes.push(node);
+            // The tree is terminal: only teardown/build may follow (§9 #5).
+            this._terminated = `route "${meta.id}"`;
+            return this;
+        });
+    }
+    // Shared switch/route decision lowering: value mode (on lens + literal table,
+    // === match) XOR predicate mode (ordered L2, first-match). Case sub-graphs
+    // collect under `<id>.<label>.` prefixes; labels derive from explicit label →
+    // String(value) → positional case-N.
+    buildFamilyDecision(method, nodeId, opts) {
+        if (!Array.isArray(opts.cases) || opts.cases.length === 0) {
+            throw new Error(`workflow.${method}() "${nodeId}" requires at least one case`);
+        }
+        const valueMode = typeof opts.on === "function";
+        const cases = opts.cases.map((c, i) => {
+            const raw = c;
+            if (valueMode) {
+                const v = raw.value;
+                if (v !== null && typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean") {
+                    throw new Error(`workflow.${method}() "${nodeId}" case ${i}: value mode requires a JSON-scalar \`value\` ` +
+                        `(string | number | boolean | null); got ${typeof v}`);
+                }
+                // NaN never matches under === and non-finite numbers serialize as null
+                // in JSON metadata — reject before they poison the case table (codex
+                // S2.8 R1 P2).
+                if (typeof v === "number" && !Number.isFinite(v)) {
+                    throw new Error(`workflow.${method}() "${nodeId}" case ${i}: \`value\` must be a finite number — ` +
+                        `${String(v)} never matches (===) and is not JSON-safe`);
+                }
+                const label = raw.label ?? String(v);
+                return { value: v, label, nodes: this.collectSubNodes(raw.then, `${nodeId}.${label}.`) };
+            }
+            if (typeof raw.when !== "function") {
+                throw new Error(`workflow.${method}() "${nodeId}" case ${i}: predicate mode requires a declarative \`when\``);
+            }
+            const pred = raw.when(predicateScope());
+            // switch/route case predicates are L2-only — a clean decision table
+            // (addendum §9 #4); an opaque N-way gate is a nested branch+whenRuntime.
+            assertL2Predicate(pred, method);
+            const label = raw.label ?? `case-${i}`;
+            return { when: pred, label, nodes: this.collectSubNodes(raw.then, `${nodeId}.${label}.`) };
+        });
+        // Duplicate value-mode literals would make later cases unreachable — fail
+        // fast (mirrors the unreachable-case spirit of a real switch).
+        if (valueMode) {
+            const seen = new Set();
+            for (const c of cases) {
+                const key = `${typeof c.value}:${String(c.value)}`;
+                if (seen.has(key)) {
+                    throw new Error(`workflow.${method}() "${nodeId}": duplicate case value ${JSON.stringify(c.value)} — later case is unreachable`);
+                }
+                seen.add(key);
+            }
+        }
+        // Labels must be unique: they prefix anonymous child ids and identify the
+        // taken case in branch_decision events — `value: 1` vs `value: "1"` both
+        // stringify to "1", and explicit labels can collide too (codex S2.8 R1 P2).
+        const seenLabels = new Set();
+        for (const c of cases) {
+            // "default" is reserved: the fallback side collects under the same
+            // `${nodeId}.default.` prefix, so a case labeled "default" (e.g.
+            // `value: "default"`) would collide with it (codex S2.8 R2 P2).
+            if (c.label === "default") {
+                throw new Error(`workflow.${method}() "${nodeId}": case label "default" is reserved for the ` +
+                    `fallback side — give the case an explicit different \`label\``);
+            }
+            if (seenLabels.has(c.label)) {
+                throw new Error(`workflow.${method}() "${nodeId}": duplicate case label "${c.label}" — ` +
+                    `labels prefix child node ids and identify the taken case; give the ` +
+                    `colliding case an explicit distinct \`label\``);
+            }
+            seenLabels.add(c.label);
+        }
+        if (valueMode) {
+            // S2.18 lens-purity: `on` passes the same P0 selector gate as every
+            // predicate lens, and only its EXTRACTED path is kept — the runtime
+            // dispatches via safe path resolution over onPath, so projection and
+            // execution share one truth. A classification expression (ternary,
+            // comparison, call) is rejected here: make it explicit — `.compute()`
+            // a discriminant field first, or use predicate mode.
+            const onPath = selectorPath(opts.on);
+            return { mode: "value", onPath, cases };
+        }
+        return { mode: "predicate", cases };
+    }
+    // Broad impl satisfies the interface's conditional-tuple signature; call sites
+    // type-check against the precise interface signature, not this one.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    poll(idOrMeta, ref, ...rest) {
+        return this.authoring(() => {
+            this.assertNoTeardown("poll");
+            const meta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(meta, "poll");
+            if (ref?.direction === "inbound") {
+                return this.inboundPoll(meta, ref, rest[0]);
+            }
+            const opts = rest[0];
+            // Inbound-only vocabulary on an outbound poll = a direction mixup —
+            // reject loudly instead of silently ignoring the receiver lens.
+            const stray = opts;
+            if (stray && (stray.via !== undefined || stray.correlate !== undefined)) {
+                throw new Error(`workflow.poll() "${meta.id}": \`via\`/\`correlate\` are inbound-poll options, ` +
+                    `but case "${ref?.contractId}.${ref?.caseKey}" is outbound — did you mean an ` +
+                    `inboundCase (direction: "inbound")?`);
+            }
+            // The type system requires opts (until XOR untilRuntime), but JS / `as any`
+            // callers can omit it — an exit-predicate-less poll would loop to exhaustion
+            // for nothing, so fail fast here.
+            if (!opts || (typeof opts.until !== "function" && typeof opts.untilRuntime !== "function")) {
+                throw new Error(`workflow.poll() "${meta.id}" requires an exit predicate — \`until\` (declarative) or \`untilRuntime\``);
+            }
+            validatePollBounds({
+                timeout: opts.timeout,
+                maxAttempts: opts.maxAttempts,
+                perAttemptTimeout: opts.perAttemptTimeout,
+                every: opts.every,
+                backoff: opts.backoff,
+            }, meta.id);
+            const node = {
+                kind: "poll",
+                meta,
+                ref,
+                in: opts.in,
+                out: opts.out,
+                accept: opts.accept,
+                until: this.buildPollUntil(opts),
+                message: opts.message,
+                every: opts.every ?? DEFAULT_EVERY_MS,
+                backoff: opts.backoff ?? 1,
+                timeoutMs: opts.timeout,
+                perAttemptTimeoutMs: opts.perAttemptTimeout,
+                maxAttempts: opts.maxAttempts,
+            };
+            this._nodes.push(node);
+            return this;
+        });
+    }
+    /**
+     * Inbound await (inbound-contract-design §9.3, slice I3): the counterparty
+     * calls US — one attempt scans `via(state).deliveries()` through the
+     * adapter matcher; matched IS the exit (no `until`), nothing is sent (no
+     * `in`/`accept`). `timeout` defaults from the case's `expect.within`
+     * (evidence + default bound, not an independent failure condition —
+     * §9.4a #5). All lenses pass the selector-source gate at build time.
+     */
+    inboundPoll(meta, ref, rawOpts) {
+        const opts = (rawOpts ?? {});
+        const where = `workflow.poll() "${meta.id}" (inbound "${ref.contractId}.${ref.caseKey}")`;
+        // Outbound-only vocabulary is rejected loudly — silent acceptance would
+        // read as "this knob works" when nothing is ever sent or predicated.
+        const rejected = [
+            ["until", "matched IS the exit — an inbound poll has no response to predicate over"],
+            ["untilRuntime", "matched IS the exit"],
+            ["in", "nothing is sent — an inbound case has no logical input"],
+            ["accept", "alternate outcome keys are outbound response vocabulary"],
+            ["message", "no opaque predicate exists to label"],
+        ];
+        for (const [key, why] of rejected) {
+            if (opts[key] !== undefined) {
+                throw new Error(`${where}: \`${key}\` is not allowed on an inbound poll — ${why}.`);
+            }
+        }
+        if (typeof opts.via !== "function") {
+            throw new Error(`${where}: \`via\` is required — a pure lens selecting the ReceiverHandle ` +
+                `from workflow state, e.g. \`via: (s) => s.inbox\` (design §9.3).`);
+        }
+        const viaPath = selectorPath(opts.via);
+        let correlate;
+        if (opts.correlate !== undefined) {
+            const { event, state: stateLens } = opts.correlate;
+            // §9.3: correlation is an === compare — BOTH lenses must be defined or
+            // the comparison degenerates to undefined === x.
+            if (typeof event !== "function" || typeof stateLens !== "function") {
+                throw new Error(`${where}: \`correlate\` needs BOTH lenses — { event: (e) => ..., state: (s) => ... } (design §9.3).`);
+            }
+            correlate = {
+                event,
+                eventPath: selectorPath(event),
+                state: stateLens,
+                statePath: selectorPath(stateLens),
+            };
+        }
+        // `expect.within` (duck-read; the adapter owns the case shape) is the
+        // poll's default total timeout.
+        const within = (ref.contract._spec
+            ?.cases?.[ref.caseKey]?.expect?.within);
+        const timeout = opts.timeout ?? within;
+        validatePollBounds({
+            timeout,
+            maxAttempts: opts.maxAttempts,
+            perAttemptTimeout: opts.perAttemptTimeout,
+            every: opts.every,
+            backoff: opts.backoff,
+        }, meta.id);
+        const node = {
+            kind: "poll",
+            meta,
+            ref,
+            inbound: {
+                via: opts.via,
+                viaPath,
+                ...(correlate ? { correlate } : {}),
+                ...(within !== undefined ? { withinMs: within } : {}),
+            },
+            out: opts.out,
+            every: opts.every ?? DEFAULT_EVERY_MS,
+            backoff: opts.backoff ?? 1,
+            timeoutMs: timeout,
+            perAttemptTimeoutMs: opts.perAttemptTimeout,
+            maxAttempts: opts.maxAttempts,
+        };
+        this._nodes.push(node);
+        return this;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    pollAction(idOrMeta, fn, ...rest) {
+        return this.authoring(() => {
+            this.assertNoTeardown("pollAction");
+            const meta = normalizeNodeMeta(idOrMeta, this._nodes.length, this._idPrefix);
+            validateNodeTimeout(meta, "poll");
+            const opts = rest[0];
+            if (typeof fn !== "function") {
+                throw new Error(`workflow.pollAction() "${meta.id}" requires an attempt function`);
+            }
+            if (!opts || (typeof opts.until !== "function" && typeof opts.untilRuntime !== "function")) {
+                throw new Error(`workflow.pollAction() "${meta.id}" requires an exit predicate — \`until\` (declarative) or \`untilRuntime\``);
+            }
+            validatePollBounds({
+                timeout: opts.timeout,
+                maxAttempts: opts.maxAttempts,
+                perAttemptTimeout: opts.perAttemptTimeout,
+                every: opts.every,
+                backoff: opts.backoff,
+            }, meta.id);
+            const node = {
+                kind: "poll",
+                meta,
+                attemptFn: fn,
+                project: opts.project,
+                out: opts.out,
+                until: this.buildPollUntil(opts),
+                message: opts.message,
+                every: opts.every ?? DEFAULT_EVERY_MS,
+                backoff: opts.backoff ?? 1,
+                timeoutMs: opts.timeout,
+                perAttemptTimeoutMs: opts.perAttemptTimeout,
+                maxAttempts: opts.maxAttempts,
+            };
+            this._nodes.push(node);
+            return this;
+        });
+    }
+    // Build the poll exit predicate: an L2 declarative tree over the RESPONSE
+    // (validated + projectable) or an opaque wrapper. Mirrors buildBranchPredicate,
+    // including the conservative `sync: false` (we cannot statically prove an
+    // untilRuntime fn is synchronous — codex S2.4a P2 applies identically here).
+    buildPollUntil(opts) {
+        if (opts.until) {
+            const pred = opts.until(predicateScope());
+            assertL2Predicate(pred, "poll");
+            return pred;
+        }
+        if (typeof opts.message !== "string" || opts.message.length === 0) {
+            throw new Error("workflow.poll() with untilRuntime requires a non-empty `message`");
+        }
+        return {
+            kind: "opaque",
+            sync: false,
+            fn: opts.untilRuntime,
+        };
+    }
+    // Build the branch predicate: an L2 declarative tree (validated + projectable) or
+    // an L1/L0 opaque wrapper. Reuses the flow condition model (no second predicate
+    // engine). `whenRuntime` requires a `message` (projection/diagnostics).
+    buildBranchPredicate(opts) {
+        if (opts.when) {
+            const pred = opts.when(predicateScope());
+            assertL2Predicate(pred, "branch");
+            return pred;
+        }
+        const wr = opts.whenRuntime;
+        if (typeof opts.message !== "string" || opts.message.length === 0) {
+            throw new Error("workflow.branch() with whenRuntime requires a non-empty `message`");
+        }
+        return {
+            kind: "opaque",
+            // whenRuntime's return type allows `Promise<boolean>`, so we CANNOT statically
+            // prove it's synchronous — inferring sync from the constructor name is dishonest
+            // for `() => Promise.resolve(x)`. Project conservatively as L0 / may-do-async-IO
+            // (codex S2.4a P2). A future split (whenRuntime L1 vs whenRuntimeAsync L0) could
+            // recover the L1 distinction; the runtime awaits either way.
+            sync: false,
+            fn: wr,
+        };
+    }
+    // Collect a then/else sub-graph by running its callback on a fresh child builder.
+    // A branch side may NOT declare setup/teardown (those are workflow-scoped).
+    /**
+     * Tip-guarded facade over a builder (codex S2.8 R3 / S2.13 R3): the CHAINED
+     * brand catches `return b`, but a FORKED chain needs a runtime guard — e.g.
+     * `b.compute(reshape); return b.check(noop)` compiles (the second chain is
+     * S→S) while the discarded reshaping chain still lands in the node list.
+     * Every facade remembers the chain length at its creation; a node call from
+     * a handle whose tip is no longer the chain's end IS the fork — throw at
+     * authoring time. Sequential chains (incl. `const c = b.x(); return c`)
+     * pass untouched. Shared by branch-family sides (collectSubNodes) AND
+     * `.use()` fragments — the same stale-handle hazard exists on the trunk.
+     */
+    static makeTipGuardedFacade(target, label) {
+        const tips = new WeakMap();
+        const make = (tip) => {
+            const proxy = new Proxy(target, {
+                get: (t, prop) => {
+                    const v = Reflect.get(t, prop, t);
+                    if (typeof v !== "function")
+                        return v;
+                    return (...args) => {
+                        if (target._nodes.length !== tip) {
+                            throw new Error(`workflow ${label} forked its chain — continue from the ` +
+                                `latest chain return value; don't call off an earlier handle`);
+                        }
+                        const out = v.apply(t, args);
+                        // A node call advanced the chain → hand back a fresh tip handle.
+                        if (target._nodes.length !== tip)
+                            return make(target._nodes.length);
+                        // A NON-advancing chain call (meta/setup/teardown) returns the
+                        // raw builder — re-wrap at the same tip so the chain never
+                        // escapes the facade, else the final return-value validation
+                        // would reject a perfectly valid fragment that starts with
+                        // metadata (codex S2.13 R4 P2). Non-builder results (e.g. a
+                        // guard's return) pass through untouched.
+                        return out === t ? make(tip) : out;
+                    };
+                },
+            });
+            tips.set(proxy, tip);
+            return proxy;
+        };
+        // The facade starts at the CURRENT chain end — a trunk facade (.use) is
+        // created mid-chain, so tip 0 would instantly false-positive the fork
+        // guard on the first call; a child builder starts empty so this is 0.
+        return {
+            facade: make(target._nodes.length),
+            tipOf: (v) => (typeof v === "object" && v !== null ? tips.get(v) : undefined),
+        };
+    }
+    collectSubNodes(fn, idPrefix) {
+        const child = new WorkflowBuilderImpl({ id: this._meta.id }, idPrefix, true);
+        const { facade, tipOf } = WorkflowBuilderImpl.makeTipGuardedFacade(child, `side under "${idPrefix}"`);
+        const result = fn(facade);
+        // An async then/else callback would snapshot child._nodes BEFORE its post-await
+        // steps are added — silently dropping them. Reject thenables (codex S2.4a R5).
+        if (result && typeof result.then === "function") {
+            throw new Error("workflow.branch() then/else callback must be synchronous — an async callback " +
+                "loses any steps added after an await");
+        }
+        // The callback MUST return its own facade chain (codex S2.14 R2 P2): a
+        // body closing over a DIFFERENT builder (`group("g", () => other.compute(
+        // ...))`) type-checks when shapes match, but the sub-graph would be EMPTY
+        // while the other builder mutates — silently dropping every member. And a
+        // returned handle that is not the chain's tip means steps were added
+        // after it (stale prefix — codex S2.8 R3).
+        const returnedTip = tipOf(result);
+        if (returnedTip === undefined) {
+            throw new Error(`workflow sub-graph under "${idPrefix}": the callback must return the chain built ` +
+                `from the builder it was given — it returned ` +
+                `${result === undefined ? "undefined" : "a different builder/value"}`);
+        }
+        if (returnedTip !== child._nodes.length) {
+            throw new Error(`workflow side under "${idPrefix}" returned a stale chain handle — ` +
+                `return the value of the LAST chain call`);
+        }
+        if (child._setup || child._teardown) {
+            throw new Error("a workflow sub-graph callback (branch side / group body) cannot declare setup/teardown");
+        }
+        // A poisoned child holds a half-authored side (the callback caught an
+        // authoring error on it) — accepting its nodes would smuggle the partial
+        // graph past the parent's poison protection (codex S2.5 R4 P2). This throw
+        // runs inside the parent's authoring() wrapper, so the parent poisons too.
+        if (child._poisoned !== undefined) {
+            const causeMsg = child._poisoned instanceof Error ? child._poisoned.message : String(child._poisoned);
+            throw new Error(`workflow sub-graph (branch side / group body) is half-authored — a sub-builder call failed: ${causeMsg}`);
+        }
+        return child._nodes.slice();
+    }
+    /**
+     * Node ids must be UNIQUE across the whole graph (S2.13 / phase4 §1.3):
+     * evidence addressing (§17 #9), summary folding (per-nodeId last-wins) and
+     * Cloud rendering all assume it, and a fragment used twice (.use) would
+     * silently collide. Walks the trunk plus branch-family cases/default and
+     * group children; throws naming both occurrences.
+     */
+    static assertUniqueNodeIds(nodes, wfId) {
+        const seen = new Map();
+        const visit = (node, path) => {
+            const where = path ? `${path} > ${node.meta.id}` : node.meta.id;
+            const prior = seen.get(node.meta.id);
+            if (prior !== undefined) {
+                throw new Error(`workflow "${wfId}": duplicate node id "${node.meta.id}" (first at ${prior}, ` +
+                    `again at ${where}) — node ids address evidence and must be unique; a reused ` +
+                    `fragment should parameterize its ids (e.g. makeLogin(prefix))`);
+            }
+            seen.set(node.meta.id, where);
+            if (node.kind === "branch") {
+                for (const c of node.cases)
+                    for (const n of c.nodes)
+                        visit(n, where);
+                for (const n of node.default ?? [])
+                    visit(n, where);
+            }
+            else if (node.kind === "group") {
+                for (const n of node.nodes)
+                    visit(n, where);
+            }
+        };
+        for (const n of nodes)
+            visit(n, "");
+    }
+    build() {
+        // A branch/poll sub-builder is not an independent workflow: building one
+        // would register a bogus top-level entry under the parent id carrying only
+        // the side's nodes (codex S2.5 R2 P2). The sub-graph belongs to its parent.
+        if (this._isChild) {
+            throw new Error("workflow.build() cannot be called on a branch/poll sub-builder — " +
+                "return the builder chain from the callback instead");
+        }
+        // A fragment finalizing its host would register the workflow before
+        // use() can validate the return — and `_built` would then defeat the
+        // poison path (codex S2.13 R2 P2).
+        if (this._fragmentDepth > 0) {
+            throw new Error(`workflow "${this._meta.id}": build() cannot be called inside a .use() fragment — ` +
+                `return the chain; the workflow's author builds it`);
+        }
+        if (this._built)
+            return this._built; // idempotent — one Test, one registration
+        // A poisoned builder holds a half-authored graph (a chained call threw and
+        // the author caught it) — registering/executing it would be a phantom
+        // workflow (codex S2.5 R3 P2).
+        if (this._poisoned !== undefined) {
+            const causeMsg = this._poisoned instanceof Error ? this._poisoned.message : String(this._poisoned);
+            throw new Error(`workflow "${this._meta.id}" cannot build — an earlier authoring call failed: ${causeMsg}`);
+        }
+        try {
+            WorkflowBuilderImpl.assertUniqueNodeIds(this._nodes, this._meta.id);
+        }
+        catch (e) {
+            // Build-time validation failure must POISON the builder: the queued
+            // auto-build would otherwise call build() again on the next microtask
+            // and throw UNHANDLED even though the caller caught this one
+            // (codex S2.13 R1 P1).
+            this._poisoned ??= e;
+            throw e;
+        }
+        const meta = this._meta;
+        // The single simple-shaped Test that REPRESENTS the graph (mirrors the flow's
+        // wrapping, contract-core.ts:1236). Invocation inversion (plan 0007): the wrapper
+        // is a first-class workflow DEF — it carries the Workflow IR but does NOT execute
+        // itself. The host run-loop detects `__glubean_kind === "workflow"`, reads the IR
+        // off `__glubean_workflow`, and drives it through the (host-owned) workflow
+        // executor — exactly like RunnerCore.run() dispatches simple vs steps. The SDK
+        // stays authoring-only: it defines the workflow's SHAPE; the host runs it. The
+        // verdict (skipped → ctx.skip(reason); failed → rethrow the cause) is applied by
+        // the host, not here.
+        const wfTest = {
+            meta: {
+                id: meta.id,
+                name: meta.name ?? meta.id,
+                ...(meta.tags ? { tags: meta.tags } : {}),
+                ...(meta.description ? { description: meta.description } : {}),
+                // `WorkflowMeta.skip: string` (the reason) → `TestMeta.deferred: string`
+                // mirrors the flow convention so reporters render the reason consistently.
+                ...(meta.skip !== undefined ? { deferred: meta.skip } : {}),
+                ...(meta.only !== undefined ? { only: meta.only } : {}),
+            },
+            type: "simple",
+            // No `fn`: a built workflow is a DEF the host run-loop owns, not a self-
+            // executing test (plan 0007 invocation inversion). The IR is attached below.
+        };
+        // Mark the wrapper so the host routes it to the workflow executor (and the
+        // runner-on-engine gate `engineSupports` keeps it OFF the browser-safe engine:
+        // workflow stays node-only / cloud — plan 0005 §scope; codex Phase-3 P2).
+        wfTest.__glubean_kind = "workflow";
+        // The handle IS both the Workflow IR (runWorkflow/projectWorkflow consume it
+        // directly) and a one-element Test[] (the runner's array resolution discovers
+        // it) — the same dual shape as contract.flow()'s FlowContract.
+        const handle = Object.assign([wfTest], {
+            __glubean_type: "workflow",
+            meta,
+            setup: this._setup,
+            ...(this._setupTimeoutMs !== undefined ? { setupTimeoutMs: this._setupTimeoutMs } : {}),
+            ...(this._setupNote !== undefined ? { setupNote: this._setupNote } : {}),
+            teardown: this._teardown,
+            ...(this._teardownTimeoutMs !== undefined
+                ? { teardownTimeoutMs: this._teardownTimeoutMs }
+                : {}),
+            ...(this._teardownNote !== undefined ? { teardownNote: this._teardownNote } : {}),
+            nodes: this._nodes.slice(),
+        });
+        // Invocation inversion (plan 0007): attach the Workflow IR to the wrapper so the
+        // host run-loop can drive `runWorkflow(handle, ctx)` itself (the handle IS a
+        // `Workflow`). Non-enumerable so the wrapper still serializes/spreads as a plain
+        // simple Test — and so the wfTest↔handle cycle (handle[0] === wfTest) never leaks
+        // into JSON. Slice 1 of moving the executor out of the SDK (plan 0007).
+        Object.defineProperty(wfTest, "__glubean_workflow", {
+            value: handle,
+            enumerable: false,
+            configurable: true,
+        });
+        // Pre-compute the graded projection ONCE; the registry entry and the
+        // handle's `_projection` (the scanner's dep-free read, mirroring
+        // FlowContract._extracted — S2.6) share the same object. A data-driven
+        // member carries its template id (addendum §3: rows share ONE structure).
+        // templateId/groupId/parallel ride projectWorkflow itself (from meta) so
+        // every projection path agrees, not just this cached one (codex R5 P2).
+        const projection = projectWorkflow(handle);
+        Object.assign(handle, { _projection: projection });
+        // Register for scanner discovery with the full graded projection (§7) —
+        // scanner/Cloud/agents read grades + call identity without executing.
+        // workflow.each defers this until every row validates (codex S2.12 R3 P2:
+        // a rejected matrix must not leave half its members in the registry).
+        const register = () => registerTest({
+            id: meta.id,
+            name: meta.name ?? meta.id,
+            type: "simple",
+            ...(meta.tags ? { tags: meta.tags } : {}),
+            ...(meta.description ? { description: meta.description } : {}),
+            ...(meta.groupId ? { groupId: meta.groupId } : {}),
+            ...(meta.parallel ? { parallel: true } : {}),
+            workflow: projection,
+        });
+        if (this._suppressRegistration) {
+            Object.assign(handle, { _pendingRegistration: register });
+        }
+        else {
+            register();
+        }
+        this._built = handle;
+        return handle;
+    }
+}
+function workflowFn(idOrMeta) {
+    const meta = typeof idOrMeta === "string" ? { id: idOrMeta } : { ...idOrMeta };
+    if (typeof meta.id !== "string" || meta.id.length === 0) {
+        throw new Error("workflow(): a non-empty string id is required");
+    }
+    // Engine-owned data-driven fields can only be minted by workflow.each/pick.
+    delete meta.templateId;
+    delete meta.groupId;
+    delete meta.parallel;
+    return new WorkflowBuilderImpl(meta);
+}
+function buildEachMembers(rows, meta, factory) {
+    {
+        if (typeof meta?.id !== "string" || meta.id.length === 0) {
+            throw new Error("workflow.each(): a non-empty template id is required");
+        }
+        if (typeof factory !== "function") {
+            throw new Error(`workflow.each() "${meta.id}": a (wf, row) factory is required`);
+        }
+        const filtered = meta.filter
+            ? rows.filter((row, index) => meta.filter(row, index))
+            : rows;
+        const tagFieldNames = typeof meta.tagFields === "string" ? [meta.tagFields] : [...(meta.tagFields ?? [])];
+        const staticTags = meta.tags ?? [];
+        // Grouping is parallel-only: an object-table each has _pick on its rows
+        // (the map key) but stays deterministic and ungrouped (codex S2.12 R11).
+        const hasGroup = meta.parallel === true;
+        // Addendum §3 binding rule 2 made executable: row data enters state ONLY
+        // via setup (or closure literals), so every row must project to ONE
+        // structure — identical canonicalHash, one version × N runs. A factory
+        // that shapes the GRAPH from the row (conditional nodes) breaks that
+        // contract and is rejected here, not silently shipped as N blobs.
+        let canonicalStructure;
+        let canonicalRowId;
+        // Row-INVARIANT top-level meta participates too: a factory varying e.g.
+        // `skip` per row via wf.meta() would let pick's collapsed template entry
+        // inherit the first member's deferral and skip runnable examples
+        // (codex S2.12 R14 P2). name/tags are engine-owned (templated per row)
+        // and excluded.
+        // Lifecycle PRESENCE and timeouts are structure too: one row declaring
+        // setup while another doesn't is a different workflow shape even though
+        // projected nodes match (codex S2.12 R15 P2). The setup fn itself may
+        // freely close over row data — only presence/bounds are compared.
+        const structureOf = (handle) => JSON.stringify({
+            nodes: handle._projection.nodes,
+            gradeSummary: handle._projection.gradeSummary,
+            description: handle.meta.description ?? null,
+            skip: handle.meta.skip ?? null,
+            only: handle.meta.only ?? null,
+            extensions: handle.meta.extensions ?? null,
+            setup: handle.setup
+                ? { timeoutMs: handle.setupTimeoutMs ?? null, note: handle.setupNote ?? null }
+                : null,
+            teardown: handle.teardown
+                ? { timeoutMs: handle.teardownTimeoutMs ?? null, note: handle.teardownNote ?? null }
+                : null,
+        });
+        return filtered.map((row, index) => {
+            const id = interpolateTemplate(meta.id, row, index);
+            const name = meta.name ? interpolateTemplate(meta.name, row, index) : id;
+            const dynamicTags = tagFieldNames
+                .map((field) => {
+                const value = row[field];
+                return value != null ? `${field}:${String(value)}` : null;
+            })
+                .filter((t) => t !== null);
+            const allTags = [...staticTags, ...dynamicTags];
+            const builder = new WorkflowBuilderImpl({
+                ...meta,
+                id,
+                name,
+                tags: allTags.length > 0 ? allTags : undefined,
+                templateId: meta.id, // every member carries the shared-structure marker
+                groupId: hasGroup ? meta.id : undefined,
+                parallel: meta.parallel === true ? true : undefined,
+            });
+            builder._suppressRegistration = true; // registered only after ALL rows validate
+            const result = factory(builder, row);
+            // An async factory would add nodes after we build — same hazard as an
+            // async branch side (codex S2.4a R5): reject thenables. Consume the
+            // promise first: its continuation will reject later (the builder is
+            // finalized by then), and an unhandled rejection would bury this
+            // actionable diagnostic (codex S2.12 R4 P3).
+            if (result && typeof result.then === "function") {
+                result.then(() => { }, () => { });
+                throw new Error(`workflow.each() "${meta.id}": the factory must be synchronous — an async ` +
+                    `factory loses any steps added after an await`);
+            }
+            const handle = builder.build();
+            const structure = structureOf(handle);
+            if (canonicalStructure === undefined) {
+                canonicalStructure = structure;
+                canonicalRowId = id;
+            }
+            else if (structure !== canonicalStructure) {
+                throw new Error(`workflow.each() "${meta.id}": row ${index} ("${id}") projects a DIFFERENT ` +
+                    `structure than "${canonicalRowId}" — all rows must share one projected shape ` +
+                    `(addendum §3: row data enters state via setup only; don't shape the graph ` +
+                    `from the row — use filter, or split into separate workflows)`);
+            }
+            return handle;
+        });
+    }
+}
+function workflowEach(table) {
+    const rows = normalizeEachTable(table);
+    return (meta, factory) => {
+        const members = buildEachMembers(rows, meta, factory);
+        // Every row validated against the canonical structure — register now
+        // (a rejected matrix never reaches the registry; codex S2.12 R3 P2).
+        for (const m of members) {
+            m._pendingRegistration?.();
+        }
+        return members;
+    };
+}
+/** Create a workflow builder. `id` is required (string or `WorkflowMeta`).
+ * `workflow.each(table)(metaTemplate, factory)` authors data-driven matrices
+ * (addendum §3). There is deliberately NO `workflow.pick`: random selection
+ * is a test-layer idea — a workflow's declaration inventory must be
+ * deterministic (canonicalHash, one version × N runs), and "hand-run one
+ * member" is already covered because every each member is an addressable
+ * test (`glubean run -t checkout-us`). Owner decision 2026-06-12. */
+export const workflow = Object.assign(workflowFn, {
+    each: workflowEach,
+});
+//# sourceMappingURL=builder.js.map