@glubean/scanner 0.5.2 → 0.7.0

package/dist/extractor-ast.js

@@ -14,12 +14,15 @@
  */
 import { parseSource, forEachExportedConst, unwrapExpression, stringFromExpression, objectFromExpression, objectProperty, stringProperty, propertyNameText, findPropertyCall, walk, lineOf, } from "./ast.js";
 import { resolveDataPath } from "./data-path.js";
-const BASE_FNS = new Set(["test", "task"]);
+// `workflow` is the vNext graph authoring factory (@glubean/sdk workflow());
+// its build() wraps the graph in a simple Test, so a `workflow("id")...` export
+// is a runnable test for discovery purposes (S2.5).
+const BASE_FNS = new Set(["test", "task", "workflow"]);
 /** Whether a factory identifier name is a recognized test/task function. */
 function isTestFnName(name, customFns) {
     if (customFns)
         return customFns.has(name);
-    // Convention fallback: test | task | *Test | *Task (capitalized suffix).
+    // Convention fallback: test | task | workflow | *Test | *Task (capitalized suffix).
     return BASE_FNS.has(name) || /(?:Test|Task)$/.test(name);
 }
 /** Parse `{ id, name, tags, timeout, requires, defaultRun }` from a TestMeta object literal. */
@@ -31,6 +34,12 @@ function parseMetaObject(obj) {
     const name = stringProperty(obj, "name");
     if (name !== undefined)
         out.name = name;
+    // WorkflowMeta.skip is a string reason (TestMeta.skip is boolean — a string
+    // here only ever comes from a workflow). Carried as `deferred` so the
+    // upload gate can exclude skipped workflows (codex S2.6 R13 P2).
+    const skipReason = stringProperty(obj, "skip");
+    if (skipReason !== undefined)
+        out.deferred = skipReason;
     const tagsProp = objectProperty(obj, "tags");
     if (tagsProp) {
         const value = unwrapExpression(tagsProp.value);
@@ -64,6 +73,16 @@ function parseMetaObject(obj) {
         out.defaultRun = defaultRun;
     return out;
 }
+/** `parallel: true` from a meta OBJECT — read only for data-driven (.each/
+ * .pick) declarations; a plain test() meta must not gain a parallel group
+ * (codex S2.12 R5 P2). */
+function parseMetaParallel(obj) {
+    const parallelProp = objectProperty(obj, "parallel");
+    if (!parallelProp)
+        return false;
+    const value = unwrapExpression(parallelProp.value);
+    return value?.type === "BooleanLiteral" && value.value === true;
+}
 /** Builder `.meta({...})` fields (name/tags/timeout/requires/defaultRun) from the chain. */
 function builderMeta(init) {
     const metaCall = findPropertyCall(init, "meta");
@@ -110,7 +129,611 @@ function chainHead(init) {
     }
     return node;
 }
-function parseTestDeclaration(decl, statement, customFns) {
+/** Like `walk`, but does NOT descend into nested function scopes (arrow /
+ * function expressions / declarations). The factory's graph calls live at its
+ * top level — branch sides etc. are flagged by the outer `.branch(` on the
+ * chain — while runtime callbacks may declare shadowing locals (`const wf =
+ * ...` inside an action) that must not leak into the scan (codex S2.12 R4). */
+function walkSameScope(node, cb, onNestedFn) {
+    cb(node);
+    for (const key of Object.keys(node)) {
+        const value = node[key];
+        const visit = (v) => {
+            if (!v || typeof v !== "object")
+                return;
+            const child = v;
+            if (typeof child.type !== "string")
+                return;
+            if (child.type === "ArrowFunctionExpression" ||
+                child.type === "FunctionExpression" ||
+                child.type === "FunctionDeclaration") {
+                onNestedFn?.(child); // nested scope — the caller decides what to do
+                return;
+            }
+            walkSameScope(child, cb, onNestedFn);
+        };
+        if (Array.isArray(value))
+            value.forEach(visit);
+        else
+            visit(value);
+    }
+}
+/** Babel emits Optional* variants for `?.` — every call/member check must
+ * accept both or optional chaining bypasses the gate (codex S2.13 R9 P2). */
+function isCallNode(n) {
+    return n?.type === "CallExpression" || n?.type === "OptionalCallExpression";
+}
+function isMemberNode(n) {
+    return n?.type === "MemberExpression" || n?.type === "OptionalMemberExpression";
+}
+/** The branch-family + poll method names the Cloud-render gate flags. */
+const BRANCH_FAMILY_METHODS = new Set(["branch", "poll", "pollAction", "switch", "route"]);
+/** The full builder chain surface — used to decide whether a member call on
+ * a live name is the builder's OWN chain call (callbacks handled by the
+ * shadow-aware recursion) or an unknown method on a live CONTAINER
+ * (`h.makeFlow(() => b)`) whose function args must be deep-checked
+ * (codex S2.13 R17 P2). */
+const KNOWN_BUILDER_METHODS = new Set([
+    "setup",
+    "teardown",
+    "meta",
+    "call",
+    "action",
+    "check",
+    "compute",
+    "branch",
+    "switch",
+    "route",
+    "poll",
+    "pollAction",
+    "use",
+    "group",
+    "build",
+]);
+/** The delegated callback of a use/group call: the FIRST function-shaped
+ * argument (use carries it at 0, group at 1 behind the id). None found →
+ * undefined → the caller fails closed. */
+function delegatedCallbackOf(args) {
+    for (const arg of args ?? []) {
+        const u = unwrapExpression(arg);
+        if (u?.type === "ArrowFunctionExpression" || u?.type === "FunctionExpression")
+            return u;
+    }
+    return undefined;
+}
+/** Chain methods that DELEGATE part of the graph to a callback argument —
+ * the callback is scanned like an each-factory; references fail closed.
+ * "use" (S2.13) and "group" (S2.14) — phase4 §4's shared rule. */
+const DELEGATING_CHAIN_METHODS = new Set(["use", "group"]);
+/** Descend a receiver/initializer expression to its root identifier —
+ * through call chains AND member access (`h.b.branch(...)` roots at `h`:
+ * a container holding a live builder is itself suspect — codex S2.13 R7). */
+function chainRootOf(expr) {
+    let root = expr ? unwrapExpression(expr) : undefined;
+    for (;;) {
+        if (!root)
+            return root;
+        if (isCallNode(root)) {
+            const innerCallee = unwrapExpression(root.callee);
+            if (isMemberNode(innerCallee)) {
+                root = unwrapExpression(innerCallee.object);
+                continue;
+            }
+            return root;
+        }
+        if (isMemberNode(root)) {
+            // computed or not — for ROOT tracking, descending the object is the
+            // fail-closed direction (`h["b"].branch(...)` roots at h — codex R8).
+            root = unwrapExpression(root.object);
+            continue;
+        }
+        return root;
+    }
+}
+/** Does the expression subtree REFERENCE any live builder name? Same-scope
+ * only (nested functions are handled by the scanner's own recursion), and
+ * non-computed member/property KEY identifiers are skipped — `client.b` is a
+ * property name, not a reference (codex S2.13 R7). */
+function containsLiveIdentifier(expr, live, opts) {
+    if (!expr || typeof expr !== "object")
+        return false;
+    let found = false;
+    const visit = (node) => {
+        if (found || !node || typeof node.type !== "string")
+            return;
+        // TYPE-ONLY subtrees never hold runtime references — a type argument
+        // named like the builder (`makeClient<b>()`) must not taint anything
+        // (codex S2.13 R15 P2). But TS EXPRESSION wrappers (`b as any`, `b!`)
+        // carry a real runtime expression — descend into it (codex R16 P2).
+        if (node.type.startsWith("TS")) {
+            const inner = node.expression;
+            if (inner && typeof inner.type === "string")
+                visit(inner);
+            return;
+        }
+        if (!opts?.intoFunctions &&
+            (node.type === "ArrowFunctionExpression" ||
+                node.type === "FunctionExpression" ||
+                node.type === "FunctionDeclaration")) {
+            return; // nested scope — the scanner recurses there separately
+        }
+        if (node.type === "Identifier") {
+            if (live.has(node.name))
+                found = true;
+            return;
+        }
+        for (const key of Object.keys(node)) {
+            // skip NAME positions: a non-computed member's property and a
+            // non-computed object-property key are labels, not references.
+            if (key === "typeParameters" ||
+                key === "typeAnnotation" ||
+                key === "returnType" ||
+                key === "superTypeParameters" ||
+                (isMemberNode(node) && node.computed !== true && key === "property") ||
+                ((node.type === "ObjectProperty" ||
+                    node.type === "Property" ||
+                    // `{ b() {} }` — a method NAME is a label too (codex S2.13 R11 P2)
+                    node.type === "ObjectMethod" ||
+                    node.type === "ClassMethod") &&
+                    node.computed !== true &&
+                    key === "key")) {
+                continue;
+            }
+            const value = node[key];
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    if (v && typeof v.type === "string")
+                        visit(v);
+                }
+            }
+            else if (value && typeof value.type === "string") {
+                visit(value);
+            }
+            if (found)
+                return;
+        }
+    };
+    visit(unwrapExpression(expr) ?? expr);
+    return found;
+}
+/**
+ * The ONE shared rule (phase4 §4): any construct handing graph authorship to
+ * a callback — each/pick factories, `.use(` fragments, (S2.14) `.group(`
+ * bodies — is scanned with the binding-aware live/everLive dataflow
+ * (codex S2.12 R2/R4/R10/R12/R13/R14/R15/R18) when INLINE.
+ *
+ * Returns `true` (branch-family call rooted at the builder found), `false`
+ * (inline and clean), or `undefined` (not an inspectable inline function —
+ * the caller fails CLOSED).
+ */
+function scanCallbackForBranchFamily(fn) {
+    if (!fn ||
+        (fn.type !== "ArrowFunctionExpression" && fn.type !== "FunctionExpression")) {
+        return undefined;
+    }
+    // TS `this` parameters are erased at runtime but occupy params[0] in the
+    // AST (`function (this: void, b) {...}`) — skip them or the scan tracks
+    // "this" instead of the builder (codex S2.13 R21 P2).
+    const params = (fn.params ?? []).filter((p) => !(p.type === "Identifier" && p.name === "this"));
+    const builderParam = params[0]?.type === "Identifier" ? params[0].name : undefined;
+    if (!builderParam)
+        return undefined; // destructured/absent — cannot root the dataflow
+    // A default-parameter INITIALIZER can author the delegated chain before the
+    // body (`(b, r = b.branch(...)) => r`) — the body-only scan would miss it
+    // (codex S2.13 R5 P2). Only initializers can EXECUTE code, so fail closed
+    // exactly on AssignmentPattern (incl. nested inside destructuring); a plain
+    // destructured row param (`(wf, { region }) => ...`) is pure binding and
+    // stays scannable (codex S2.13 R6 P2).
+    for (const param of (params ?? []).slice(1)) {
+        let hasInitializer = false;
+        walk(param, (n) => {
+            if (n.type === "AssignmentPattern")
+                hasInitializer = true;
+        });
+        if (hasInitializer)
+            return undefined;
+    }
+    let found = false;
+    // Per-scope dataflow: every scope folds its own bindings into the inherited
+    // builder-name set in SOURCE ORDER, detects calls against the live set, then
+    // recurses into nested functions with the everLive snapshot (closures
+    // capture bindings — see the S2.12 R14/R15 commit messages for the cases).
+    const scanScope = (scopeBody, inherited, inheritedDirect) => {
+        const live = new Set(inherited);
+        const everLive = new Set(inherited);
+        // DIRECT builder aliases (the chain itself) vs tainted CONTAINERS — the
+        // own-chain callback exemption may only apply to direct aliases: a
+        // container can carry a foreign function under a builder-method name
+        // (`{ b, compute: makeFlow }` — codex S2.13 R18 P2).
+        const liveDirect = new Set(inheritedDirect);
+        const everDirect = new Set(inheritedDirect);
+        // All names BOUND by a target — an Identifier, or every binding inside a
+        // destructuring pattern (`const { b: x } = h` binds x — codex S2.13 R10).
+        const boundNames = (target) => {
+            if (!target)
+                return [];
+            if (target.type === "Identifier")
+                return [target.name];
+            const names = [];
+            const visit = (node) => {
+                if (!node || typeof node.type !== "string")
+                    return;
+                if (node.type === "Identifier") {
+                    names.push(node.name);
+                    return;
+                }
+                if (node.type === "ObjectPattern") {
+                    for (const propNode of node.properties ?? []) {
+                        if (propNode.type === "ObjectProperty" || propNode.type === "Property") {
+                            visit(propNode.value); // the BINDING side, never the key
+                        }
+                        else if (propNode.type === "RestElement") {
+                            visit(propNode.argument);
+                        }
+                    }
+                    return;
+                }
+                if (node.type === "ArrayPattern") {
+                    for (const el of node.elements ?? []) {
+                        if (el)
+                            visit(el);
+                    }
+                    return;
+                }
+                if (node.type === "RestElement")
+                    visit(node.argument);
+                if (node.type === "AssignmentPattern")
+                    visit(node.left);
+            };
+            visit(target);
+            return names;
+        };
+        const bind = (nameNode, valueExpr, isDeclaration) => {
+            const names = boundNames(nameNode);
+            if (names.length === 0)
+                return;
+            // A PATTERN-INTERNAL default can smuggle the builder into a binding
+            // even when the RHS is clean: `const { x = b } = {}` (codex S2.13 R13).
+            let patternDefaultIsLive = false;
+            if (nameNode && nameNode.type !== "Identifier") {
+                walk(nameNode, (n) => {
+                    if (n.type === "AssignmentPattern" &&
+                        containsLiveIdentifier(n.right, live)) {
+                        patternDefaultIsLive = true;
+                    }
+                });
+            }
+            // A value that CONTAINS a live builder reference (chain root, or a
+            // wrapper like `{ b }` — codex S2.13 R7) makes every bound name
+            // suspect: alias them all (fail-closed; destructuring from a live
+            // container — codex S2.13 R10).
+            if (patternDefaultIsLive || containsLiveIdentifier(valueExpr, live)) {
+                // A plain Identifier bound to a chain rooted at a DIRECT alias is
+                // itself direct (`const c = b.compute(...)`); anything else (wrapper
+                // objects, destructured pulls, pattern defaults) is tainted-only.
+                const valueRoot = chainRootOf(valueExpr);
+                const isDirectChain = nameNode?.type === "Identifier" &&
+                    valueRoot?.type === "Identifier" &&
+                    liveDirect.has(valueRoot.name);
+                for (const name of names) {
+                    live.add(name);
+                    everLive.add(name);
+                    if (isDirectChain) {
+                        liveDirect.add(name);
+                        everDirect.add(name);
+                    }
+                }
+            }
+            else if (valueExpr !== undefined) {
+                for (const name of names) {
+                    live.delete(name);
+                    liveDirect.delete(name);
+                    if (isDeclaration) {
+                        everLive.delete(name);
+                        everDirect.delete(name);
+                    }
+                }
+            }
+        };
+        const deferredFns = [];
+        // Block-aware traversal (codex S2.13 R9 P2): a block-scoped shadow
+        // (`{ const b = client; }`) must not delete the outer builder for the
+        // REST of the function. On block exit the pre-block names are UNIONED
+        // back in: block-local deletions are undone, block-born aliases leak
+        // outward (fail-closed direction; a block-local `b = client` assignment
+        // being undone is the same conservative trade).
+        const handleNode = (n) => {
+            if (n.type === "VariableDeclarator") {
+                bind(n.id, n.init, true);
+                return;
+            }
+            if (n.type === "AssignmentExpression" &&
+                (n.operator === "=" ||
+                    // logical assignments MAY assign at runtime — taint like plain
+                    // `=` on the live side; never delete on the foreign side (the
+                    // old value may survive) — codex S2.13 R16 P2.
+                    n.operator === "??=" ||
+                    n.operator === "||=" ||
+                    n.operator === "&&=")) {
+                const conditional = n.operator !== "=";
+                const left = unwrapExpression(n.left);
+                // A MEMBER write storing a live builder taints the container:
+                // `h.b = b; h.b.branch(...)` (codex S2.13 R14 P2).
+                if (left && isMemberNode(left)) {
+                    if (containsLiveIdentifier(n.right, live)) {
+                        const root = chainRootOf(left);
+                        if (root?.type === "Identifier") {
+                            live.add(root.name);
+                            everLive.add(root.name);
+                        }
+                    }
+                    return;
+                }
+                if (conditional) {
+                    // taint-only path: add aliases when the RHS is live, never delete
+                    // (and never as DIRECT — the assignment may not happen)
+                    if (left?.type === "Identifier" && containsLiveIdentifier(n.right, live)) {
+                        live.add(left.name);
+                        everLive.add(left.name);
+                    }
+                    return;
+                }
+                bind(left, n.right, false);
+                return;
+            }
+            if (found)
+                return;
+            // CONSTRUCTOR delegation: `new Fragment(b)` / `new X(() => b)` hands
+            // the builder (or a capturing closure) to uninspectable code — same
+            // fail-closed rule as call arguments (codex S2.13 R17 P2).
+            if (n.type === "NewExpression") {
+                for (const arg of n.arguments ?? []) {
+                    const u = unwrapExpression(arg) ?? arg;
+                    const isFnArg = u.type === "ArrowFunctionExpression" || u.type === "FunctionExpression";
+                    if (containsLiveIdentifier(arg, live, { intoFunctions: isFnArg })) {
+                        found = true;
+                        return;
+                    }
+                }
+                return;
+            }
+            if (!isCallNode(n))
+                return;
+            const callee = unwrapExpression(n.callee);
+            // An EXTRACTED method alias (`const branch = b.branch; branch(...)`)
+            // calls a live alias directly — no member access to inspect; fail
+            // closed (codex S2.13 R13 P2).
+            if (callee?.type === "Identifier" && live.has(callee.name)) {
+                found = true;
+                return;
+            }
+            let methodName;
+            if (callee && isMemberNode(callee)) {
+                const prop = unwrapExpression(callee.property);
+                if (callee.computed !== true && prop?.type === "Identifier") {
+                    methodName = prop.name;
+                }
+                else if (callee.computed === true && prop?.type === "StringLiteral") {
+                    // bracket syntax with a literal name resolves statically
+                    methodName = prop.value;
+                }
+                else if (callee.computed === true &&
+                    containsLiveIdentifier(callee.object, live)) {
+                    // a DYNAMIC method on a live builder cannot be resolved — fail
+                    // closed (codex S2.13 R8 P2).
+                    found = true;
+                    return;
+                }
+            }
+            // Nested delegation (`b.use(innerFragment)`): recurse into inline
+            // callbacks; references fail closed — BEFORE the generic
+            // argument-delegation check so an inline-and-clean fragment doesn't
+            // false-positive on its own builder argument.
+            if (methodName !== undefined &&
+                DELEGATING_CHAIN_METHODS.has(methodName) &&
+                (() => {
+                    const root = chainRootOf(callee.object);
+                    // DIRECT aliases only — `h.use(cb)` on a tainted container is a
+                    // foreign method wearing the name (codex S2.13 R19 P2); it falls
+                    // through to the foreign-call deep checks below.
+                    return root?.type === "Identifier" && liveDirect.has(root.name);
+                })()) {
+                const cb = delegatedCallbackOf(n.arguments);
+                const verdict = scanCallbackForBranchFamily(cb);
+                if (verdict !== false)
+                    found = true;
+                return;
+            }
+            // DELEGATION fails closed (codex S2.12 R18 P2): passing a live
+            // builder to any call — bare (`makeFlow(wf)`) or WRAPPED
+            // (`makeFlow({ wf })`, codex S2.13 R7) — hands the graph to code
+            // this scan cannot see. Nested-function arguments are exempt (the
+            // scanner recurses into them itself).
+            // Whose call is this? A live builder's OWN chain call (`b.action("x",
+            // cb)`) hands its callbacks to the runtime — the recursion scans them
+            // shadow-aware. A FOREIGN call's function argument capturing the
+            // builder (`makeFlow(() => b)`) hands authoring capability to code we
+            // can't see — deep-check those (codex S2.13 R15 P2; shadow-unaware by
+            // design, fail-closed).
+            const calleeRootForArgs = callee && isMemberNode(callee)
+                ? chainRootOf(callee.object)
+                : undefined;
+            // The exemption holds only for the builder's OWN chain surface — an
+            // unknown method on a live CONTAINER (`h.makeFlow(() => b)`) is a
+            // foreign call wearing a live root (codex S2.13 R17 P2).
+            const calleeIsLiveChain = calleeRootForArgs?.type === "Identifier" &&
+                liveDirect.has(calleeRootForArgs.name) &&
+                methodName !== undefined &&
+                KNOWN_BUILDER_METHODS.has(methodName);
+            for (const arg of n.arguments ?? []) {
+                const unwrappedArg = unwrapExpression(arg) ?? arg;
+                const isFnArg = unwrappedArg.type === "ArrowFunctionExpression" ||
+                    unwrappedArg.type === "FunctionExpression";
+                if (containsLiveIdentifier(arg, live, {
+                    intoFunctions: isFnArg && !calleeIsLiveChain,
+                })) {
+                    found = true;
+                    return;
+                }
+            }
+            // A member call on a LIVE root that is NOT the builder's own chain
+            // surface hands the receiver — and the builder inside it — to foreign
+            // code as `this` (`h.use(cb)` reaching b via this.b — codex S2.13 R19
+            // P2). Fail closed.
+            if (calleeRootForArgs?.type === "Identifier" &&
+                live.has(calleeRootForArgs.name) &&
+                !calleeIsLiveChain) {
+                found = true;
+                return;
+            }
+            if (methodName === undefined || !BRANCH_FAMILY_METHODS.has(methodName))
+                return;
+            const root = chainRootOf(callee.object);
+            if (root?.type === "Identifier") {
+                if (live.has(root.name))
+                    found = true;
+                return;
+            }
+            // The receiver didn't root at an identifier — a conditional/sequence
+            // or other expression (`(cond ? b : other).branch(...)`). If it
+            // CONTAINS a live builder anywhere, fail closed (codex S2.13 R14 P2).
+            if (containsLiveIdentifier(callee.object, live)) {
+                found = true;
+            }
+        };
+        const visitTree = (node) => {
+            if (node.type === "ArrowFunctionExpression" ||
+                node.type === "FunctionExpression" ||
+                node.type === "FunctionDeclaration") {
+                deferredFns.push({ fn: node, excluded: new Set() });
+                return;
+            }
+            const isBlock = node.type === "BlockStatement" && node !== scopeBody;
+            const liveSnap = isBlock ? new Set(live) : undefined;
+            const everSnap = isBlock ? new Set(everLive) : undefined;
+            const directSnap = isBlock ? new Set(liveDirect) : undefined;
+            const everDirectSnap = isBlock ? new Set(everDirect) : undefined;
+            const deferredStart = isBlock ? deferredFns.length : 0;
+            handleNode(node);
+            for (const key of Object.keys(node)) {
+                const value = node[key];
+                const visitChild = (v) => {
+                    if (!v || typeof v !== "object")
+                        return;
+                    const child = v;
+                    if (typeof child.type !== "string")
+                        return;
+                    visitTree(child);
+                };
+                if (Array.isArray(value))
+                    value.forEach(visitChild);
+                else
+                    visitChild(value);
+            }
+            if (isBlock) {
+                // Names a block-local DECLARATION shadowed (present before, deleted
+                // by a declaration inside): closures defined IN this block captured
+                // the shadow binding, not the outer builder — scanning them against
+                // the restored outer names would false-positive a linear workflow
+                // (codex S2.13 R20 P2). Record exclusions before the union restore.
+                // Late-ASSIGNED aliases (R15) are unaffected: assignments never
+                // delete from everLive, so they don't appear here.
+                for (const name of everSnap) {
+                    if (!everLive.has(name)) {
+                        for (let i = deferredStart; i < deferredFns.length; i++) {
+                            deferredFns[i].excluded.add(name);
+                        }
+                    }
+                }
+                for (const n of liveSnap)
+                    live.add(n);
+                for (const n of everSnap)
+                    everLive.add(n);
+                for (const n of directSnap)
+                    liveDirect.add(n);
+                for (const n of everDirectSnap)
+                    everDirect.add(n);
+            }
+        };
+        visitTree(scopeBody);
+        const fnQueue = [...deferredFns];
+        while (fnQueue.length > 0) {
+            if (found)
+                return;
+            const { fn: fnNode, excluded } = fnQueue.shift();
+            const childInherited = new Set(everLive);
+            const childDirect = new Set(everDirect);
+            for (const name of excluded) {
+                childInherited.delete(name);
+                childDirect.delete(name);
+            }
+            for (const param of fnNode.params ?? []) {
+                // A default-parameter INITIALIZER referencing a live builder executes
+                // at call time with the closure's bindings (`const make = (x =
+                // b.branch(...)) => x`) — the body-only recursion never sees it, and
+                // the param may BECOME the builder (`(x = b) => x.branch()`).
+                // Initializers can hide ANYWHERE in a destructuring pattern
+                // (`({ x = b.branch(...) } = {}) => x` — codex S2.13 R11 P2), so the
+                // WHOLE param subtree is searched. Fail closed on the reference.
+                // A CLOSURE inside an initializer (`(x = () => b.branch(...)) =>`)
+                // is invisible to containsLiveIdentifier (it skips nested fns) —
+                // queue it for the same recursive scan as any other nested function
+                // (codex S2.13 R12 P2).
+                let liveInitializer = false;
+                walk(param, (n) => {
+                    if (n.type === "AssignmentPattern" &&
+                        containsLiveIdentifier(n.right, everLive)) {
+                        liveInitializer = true;
+                    }
+                    if (n.type === "ArrowFunctionExpression" || n.type === "FunctionExpression") {
+                        fnQueue.push({ fn: n, excluded: new Set(excluded) });
+                    }
+                });
+                if (liveInitializer) {
+                    found = true;
+                    return;
+                }
+                for (const name of boundNames(param)) {
+                    childInherited.delete(name);
+                    childDirect.delete(name);
+                }
+            }
+            scanScope(fnNode.body, childInherited, childDirect);
+        }
+    };
+    scanScope(fn.body, new Set([builderParam]), new Set([builderParam]));
+    return found;
+}
+/**
+ * Local names bound to the SDK's `workflow` factory via named-import aliases
+ * (`import { workflow as journeyTest } ...`). The literal `workflow` is always
+ * included. Without this, an alias that happens to satisfy the `*Test`/`*Task`
+ * convention (or customFns) would be classified as a plain test and bypass the
+ * workflow marker + the --upload branch/poll gate (codex S2.6 R12 P2).
+ */
+function collectWorkflowAliases(source) {
+    const aliases = new Set(["workflow"]);
+    const body = source.program.body ?? [];
+    for (const stmt of body) {
+        if (stmt.type !== "ImportDeclaration")
+            continue;
+        const specifiers = stmt.specifiers ?? [];
+        for (const spec of specifiers) {
+            if (spec.type !== "ImportSpecifier")
+                continue;
+            const imported = spec.imported;
+            const importedName = imported?.type === "Identifier"
+                ? imported.name
+                : imported?.value; // string import names
+            const local = spec.local;
+            if (importedName === "workflow" && local?.type === "Identifier") {
+                aliases.add(local.name);
+            }
+        }
+    }
+    return aliases;
+}
+function parseTestDeclaration(decl, statement, customFns, workflowAliases) {
     const exportName = decl.id?.name;
     if (!exportName)
         return undefined;
@@ -152,8 +775,13 @@ function parseTestDeclaration(decl, statement, customFns) {
     else {
         return undefined;
     }
-    if (!factoryName || !isTestFnName(factoryName, customFns))
+    // A workflow import alias is always accepted (even when it matches no
+    // test-name convention) and always classified as a workflow — the marker
+    // must not depend on what the alias happens to look like (codex S2.6 R12).
+    const isWorkflowFactory = workflowAliases?.has(factoryName) ?? factoryName === "workflow";
+    if (!factoryName || (!isTestFnName(factoryName, customFns) && !isWorkflowFactory)) {
         return undefined;
+    }
     // Resolve id + inline meta from the first argument (string id or TestMeta obj).
     let fields = {};
     const metaObj = objectFromExpression(metaArg);
@@ -177,10 +805,15 @@ function parseTestDeclaration(decl, statement, customFns) {
         fields.requires = bMeta.requires;
     if (fields.defaultRun === undefined && bMeta.defaultRun !== undefined)
         fields.defaultRun = bMeta.defaultRun;
+    if (fields.deferred === undefined && bMeta.deferred !== undefined)
+        fields.deferred = bMeta.deferred;
     if (fields.id === undefined)
         return undefined;
     // `.each(data, { parallel: true })`.
-    let parallel = false;
+    // meta-object `parallel` counts only for data-driven declarations
+    // (workflow.each puts it there); legacy each-args form parsed below.
+    const metaObjForParallel = (variant === "each" || variant === "pick") && metaArg ? objectFromExpression(metaArg) : undefined;
+    let parallel = metaObjForParallel ? parseMetaParallel(metaObjForParallel) : false;
     if (variant === "each" && eachArgs && eachArgs.length > 1) {
         const optsObj = objectFromExpression(eachArgs[1]);
         const parallelProp = optsObj ? objectProperty(optsObj, "parallel") : undefined;
@@ -211,6 +844,20 @@ function parseTestDeclaration(decl, statement, customFns) {
         result.steps = steps;
     if (parallel)
         result.parallel = true;
+    // vNext workflow exports get a static marker so downstream consumers can
+    // classify them as graph orchestrators ("flow"-kind runnables) without
+    // importing the file, plus an AST-level branch/poll flag so the --upload
+    // gate fails closed for .test.ts workflows the runtime extractor can never
+    // safely inspect (codex S2.6 R10 P2).
+    if (isWorkflowFactory) {
+        result.workflow = true;
+        // WorkflowMeta.skip (string reason) — surfaced so the upload gate can
+        // exclude skipped workflows like deferred flows (codex S2.6 R13 P2).
+        // Only emitted for workflows: TestMeta.skip is boolean, so a string skip
+        // never legitimately appears on a plain test.
+        if (fields.deferred !== undefined)
+            result.deferred = fields.deferred;
+    }
     return result;
 }
 /**
@@ -229,9 +876,10 @@ export function extractFromSource(content, customFns) {
         return [];
     }
     const fns = customFns && customFns.length > 0 ? new Set([...BASE_FNS, ...customFns]) : undefined;
+    const workflowAliases = collectWorkflowAliases(source);
     const results = [];
     forEachExportedConst(source, (statement, declaration) => {
-        const meta = parseTestDeclaration(declaration, statement, fns);
+        const meta = parseTestDeclaration(declaration, statement, fns, workflowAliases);
         if (meta)
             results.push(meta);
     });
@@ -320,15 +968,35 @@ function readCases(casesObj) {
         const key = propertyNameText(property);
         if (key === undefined)
             continue;
-        const body = objectFromExpression(property.value);
+        // `evt: inboundCase({...})` (I2 authoring helper) — unwrap to the spec
+        // argument so description etc. stay readable, and mark the direction so
+        // static-fallback discovery never advertises a non-runnable case.
+        const rawValue = unwrapExpression(property.value);
+        let inbound = false;
+        let bodySource = rawValue;
+        if (rawValue?.type === "CallExpression") {
+            const callee = unwrapExpression(rawValue.callee);
+            if (callee?.type === "Identifier" && callee.name === "inboundCase") {
+                inbound = true;
+                bodySource = rawValue.arguments?.[0];
+            }
+        }
+        const body = objectFromExpression(bodySource);
         if (!body) {
             // Reference / shorthand case value (`cases: { ok }` or `ok: sharedCase`):
             // the case body isn't an inline object, so per-case fields can't be read,
             // but the KEY is still a real case — preserve it (VSCode discovery needs it).
-            out.push({ key, line: lineOf(property.key ?? property.value) });
+            out.push({
+                key,
+                line: lineOf(property.key ?? property.value),
+                ...(inbound ? { direction: "inbound" } : {}),
+            });
             continue;
         }
         const meta = { key, line: lineOf(property.value) };
+        if (inbound || stringProperty(body, "direction") === "inbound") {
+            meta.direction = "inbound";
+        }
         const description = stringProperty(body, "description");
         if (description !== undefined)
             meta.description = description;
@@ -412,85 +1080,6 @@ export function extractContractCases(content, opts) {
     });
     return results;
 }
-/**
- * Structural (marker-free) flow extraction: every `export const X = <fn>.flow("id")…`
- * → `FlowStaticMeta`. Replaces vscode's `// @flow`-gated extractMarkedFlows — AST
- * recognizes the `.flow("id")` call shape directly, so no magic comment is needed
- * (aligns vscode discovery with the CLI, which never required markers). Returns []
- * on parse error.
- */
-export function extractFlows(content) {
-    let source;
-    try {
-        source = parseSource(content);
-    }
-    catch {
-        return [];
-    }
-    const results = [];
-    forEachExportedConst(source, (statement, declaration) => {
-        const exportName = declaration.id?.name;
-        const init = declaration.init;
-        if (!exportName || !init)
-            return;
-        const flowCall = findFlowCall(init);
-        if (!flowCall)
-            return;
-        // `flow(idOrMeta: string | FlowMeta)` — string id or `{ id, ... }`. Runtime
-        // honors the object's `id`; its `skip` is IGNORED at runtime (skip is only
-        // applied from a chained `.meta({ skip })`), so we read skip only from there.
-        const flowArg = flowCall.arguments?.[0];
-        const flowMetaObj = objectFromExpression(flowArg);
-        const flowId = stringFromExpression(flowArg) ?? (flowMetaObj && stringProperty(flowMetaObj, "id"));
-        if (!flowId)
-            return;
-        const metaCall = findPropertyCall(init, "meta");
-        const metaObj = metaCall
-            ? objectFromExpression(metaCall.arguments?.[0])
-            : undefined;
-        const skip = metaObj ? stringProperty(metaObj, "skip") : undefined;
-        const meta = { exportName, line: lineOf(statement), flowId };
-        if (skip !== undefined)
-            meta.skip = skip;
-        results.push(meta);
-    });
-    return results;
-}
-/**
- * Find the Glubean flow call in a chain: `contract.flow(...)` — a `.flow` member
- * on the `contract` namespace. Does NOT match an arbitrary `.flow(...)` on some
- * other object (`otherLib.flow(...)`) nor a bare `flow(...)`, which the runtime
- * would not recognize as a flow.
- *
- * Like `findContractCall` / the former regex, this keys off the literal name
- * `contract` and does not resolve `import { contract as x }` aliases — a known,
- * consistent limitation across the contract + flow static extractors (real code
- * uses `contract.flow(...)`).
- */
-function findFlowCall(init) {
-    let node = unwrapExpression(init);
-    while (node && node.type === "CallExpression") {
-        const callee = unwrapExpression(node.callee);
-        if (!callee)
-            break;
-        if (callee.type === "MemberExpression" && callee.computed !== true) {
-            const object = callee.object;
-            const property = callee.property;
-            if (property.type === "Identifier" && property.name === "flow" &&
-                object.type === "Identifier" && object.name === "contract") {
-                return node; // contract.flow("id")
-            }
-            node = unwrapExpression(object);
-        }
-        else if (callee.type === "CallExpression") {
-            node = callee;
-        }
-        else {
-            break;
-        }
-    }
-    return undefined;
-}
 /** Classify a data-loader call (`fromDir(...)`, `fromYaml.map(...)`, …) → {type, raw path}. */
 function classifyLoader(call) {
     const callee = unwrapExpression(call.callee);