@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.0

package/vendor/dynamic-workflow/analysis/causality-order-calls.js

@@ -0,0 +1,266 @@
+import ts from "typescript";
+import { callbackSemanticsOf, DEFAULT_CALLBACK_SEMANTICS } from "./callbacks.js";
+import { functionName, resolveCallDeclaration, } from "./causality-order-functions.js";
+import { applicationsAt, innermost, issue, issuesSince, jump, locOf, openRegion, } from "./causality-order-state.js";
+import { barrier, settlesAt } from "./causality-order-settle.js";
+import { closeStrand, isAsyncFunction, openStrand, } from "./causality-order-strands.js";
+// causality-order.ts 顶到 oxlint max-lines 上限（400 行），把调用这一组（调用表达式
+// 的访问器、通用调用规则 applyAt、函数体内联 inlineBody）拆到本文件；公开面仍从
+// causality-order.ts 导出。递归回 walk 一律经 `state.walk`，本文件不 import walk 模块。
+export function walkCall(state, node, chain) {
+    const { walk } = state;
+    // Receiver and arguments first, then the call itself — JavaScript's own order. (A
+    // function-like argument is deferred by `walk` itself: its body runs when applied.)
+    const receiverMark = state.events.length;
+    walk(node.expression, chain);
+    const receiverIssues = issuesSince(state, receiverMark);
+    for (const argument of node.arguments)
+        walk(argument, chain);
+    // A per-element callback call: the body runs once per element, inside a `fanout`.
+    const handled = new Set();
+    const cand = state.candByCall.get(node);
+    if (cand !== undefined) {
+        // An `async` literal callback makes the FAN-OUT the strand: every element's activation
+        // runs alongside the main line, and only a later await of the mapped array joins them.
+        // A named callback (`xs.map(review)`) inlines as a `call` inside the fan-out, and that
+        // `call` is the strand when `review` is async — {@link inlineBody} decides it there.
+        const strand = cand.callback !== undefined && isAsyncFunction(cand.callback);
+        const id = openRegion(state, "fanout", innermost(state, chain), {
+            entered: false,
+            label: cand.method,
+            loc: cand.loc,
+            ...(strand ? { strand: true } : {}),
+        });
+        const inside = [...chain, id];
+        if (cand.callback !== undefined) {
+            const record = strand ? openStrand(state, id) : undefined;
+            // A `return` in the literal ends THIS element's iteration: it targets the fanout.
+            state.returnTargets.push(id);
+            walk(cand.body, inside);
+            state.returnTargets.pop();
+            if (record !== undefined)
+                closeStrand(state, record);
+        }
+        else {
+            // A named / held callback: the oracle's argument applications, each an inlined call.
+            for (const fn of applicationsAt(state, node, "argument")) {
+                handled.add(fn);
+                inlineBody(state, fn, inside, node);
+            }
+        }
+    }
+    const ask = state.askByCall.get(node);
+    if (ask !== undefined) {
+        issue(state, ask, chain);
+        return;
+    }
+    const hole = state.holeByCall.get(node);
+    if (hole !== undefined) {
+        walkHole(state, node, hole, chain);
+        return;
+    }
+    const read = state.readByCall.get(node);
+    if (read !== undefined) {
+        issue(state, read, chain);
+        return;
+    }
+    const actor = state.actorByCall.get(node);
+    if (actor !== undefined) {
+        state.events.push({ actor, at: "actor", phase: state.currentPhase, regions: chain });
+        return;
+    }
+    applyAt(state, node, chain, handled, receiverIssues);
+}
+/**
+ * THE GENERIC CALL RULE: apply what the oracle recorded at this node.
+ *
+ *  - Callee applications inline the body as a `call` region (the helper's boundary, a
+ *    `return` target). Several candidates (an indirect dispatch that may reach any of
+ *    them) become the arms of one exhaustive `choice`: exactly one runs, we cannot say
+ *    which. With no oracle record the checker's resolved declaration is the fallback — a
+ *    value the interpreter could not track still has a syntactic answer.
+ *  - Argument applications are callbacks a library may invoke, per the registry: `once`
+ *    (the default) inlines the body as a `call`; when the library does not provably invoke
+ *    it (`.then`, an unknown callee) the call sits in a one-arm skippable `choice` — the
+ *    exact shape of an `if` without `else`, so certainty and the control-flow picture read
+ *    "may not run" through the vocabulary they already have. `each` callbacks are handled
+ *    by {@link walkCall} (their fanout) and arrive here in `handled`.
+ *  - A DEFERRED callback (`.then` / `.catch` / `.finally`, a timer) runs after its receiver
+ *    settles, so it is a STRAND whose PROLOGUE is an ordinary barrier over the receiver:
+ *    the steps issued while evaluating the receiver (`receiverIssues`, the syntactic half)
+ *    plus the oracle's claim keyed by the member-name token (see calls.ts), split by the
+ *    settle-certainty rule like any other await. It needs no special certainty any more:
+ *    the barrier runs inside the strand's own frame, so it orders the continuation's body
+ *    without asserting anything about steps the MAIN LINE issues afterwards, and without
+ *    robbing the main line's later `await` of its own certain settle. That scoping is what
+ *    `settleLocally`'s may-claim used to approximate.
+ */
+export function applyAt(state, node, chain, handled = new Set(), receiverIssues = []) {
+    const { checker, program, scriptFile } = state;
+    const callees = applicationsAt(state, node, "callee").filter((fn) => !handled.has(fn));
+    if (callees.length === 0 && ts.isCallExpression(node)) {
+        const decl = resolveCallDeclaration(node, checker, scriptFile);
+        if (decl !== undefined)
+            callees.push(decl);
+    }
+    if (callees.length === 1) {
+        inlineBody(state, callees[0], chain, node);
+    }
+    else if (callees.length > 1) {
+        const choice = openRegion(state, "choice", innermost(state, chain), {
+            entered: true,
+            exhaustive: true,
+            loc: locOf(state, node),
+        });
+        for (const fn of callees) {
+            const arm = openRegion(state, "branch", choice, { entered: false, loc: locOf(state, fn) });
+            inlineBody(state, fn, [...chain, choice, arm], node);
+        }
+    }
+    const callbacks = applicationsAt(state, node, "argument").filter((fn) => !handled.has(fn));
+    if (callbacks.length === 0)
+        return;
+    const semantics = ts.isTaggedTemplateExpression(node)
+        ? undefined
+        : callbackSemanticsOf(node, checker, program);
+    const entered = semantics?.entered ?? DEFAULT_CALLBACK_SEMANTICS.entered;
+    const access = semantics?.deferred === true &&
+        ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression)
+        ? node.expression
+        : undefined;
+    const prologue = access === undefined
+        ? undefined
+        : (inside) => {
+            const claim = settlesAt(state, node, access.name.getStart(scriptFile));
+            barrier(state, [...receiverIssues, ...claim.certain], claim.maybe, inside);
+        };
+    const options = {
+        label: semantics?.label,
+        prologue,
+        ...(semantics?.deferred === true ? { strand: true } : {}),
+    };
+    for (const fn of callbacks) {
+        if (entered) {
+            inlineBody(state, fn, chain, node, options);
+            continue;
+        }
+        const choice = openRegion(state, "choice", innermost(state, chain), {
+            entered: true,
+            loc: locOf(state, node),
+        });
+        const arm = openRegion(state, "branch", choice, { entered: false, loc: locOf(state, fn) });
+        inlineBody(state, fn, [...chain, choice, arm], node, options);
+    }
+}
+/**
+ * 留白在时序走查里的样子（docs/analysis.md「Sites」的 Hole sites 段）。
+ *
+ * **开放的留白是一步，也是一个阶段。** 一步：`issue` 一次，落在它**所站的**阶段里（当前阶段），
+ * 于是 await 屏障、settle、控制依赖对它与对 ask 一视同仁。一个阶段：id 就是站点 id、名字是
+ * 字面量，**没有成员**——它只是一个站，轨道要在 run 之前就画出来。为了让它出现在控制流投影
+ * 的阶段表上并接上前后的边，走查在 issue 之后发一条 `mark`：先 issue 再 mark，于是商图里
+ * 是「所站阶段 → 留白 → 下一阶段」而不是一次回到所站阶段的往返。
+ *
+ * **已补全的留白不是一步，只是一个阶段。** 它的阶段认领函数体里第一个标记之前的站点；体内
+ * 的标记是站在它之后的阶段，各自带 `fill` 指回这个留白；留白自己的阶段带的 `fill` 是**包着
+ * 它的**留白（顶层没有）——嵌套关系只记在这里，id 里没有（hole-id.ts）。
+ *
+ * 它的阶段还有一个 mark 节点，与开放的留白一样。修复原因：2026-09-28 之前已补全的留白没有
+ * mark，函数体以 `phase()` 开头时留白自己的阶段没有成员，控制流投影就把它丢了——接龙的每一步
+ * 名字因此从阶段表、侧栏与 run 的 `phaseNames` 里消失，只剩时间轴的头还叫得出它。
+ *
+ * 函数体像 `future` 的一样是一个进入过的、once 的、不延迟的回调——taint 解释器把它记成调用点
+ * 上的 `argument` 应用，这里照神谕内联；它是 async 的，所以是一条 strand，外面的 `await` 在
+ * 屏障处 join 它。
+ */
+function walkHole(state, node, site, chain) {
+    const name = site.name ?? site.id;
+    const enclosing = state.fillStack[state.fillStack.length - 1];
+    if (site.body === undefined) {
+        issue(state, site.id, chain);
+        mintHolePhase(state, site, name, enclosing);
+        state.events.push({ at: "mark", phase: site.id, regions: chain });
+        return;
+    }
+    mintHolePhase(state, site, name, enclosing);
+    state.events.push({ at: "mark", phase: site.id, regions: chain });
+    const outer = state.currentPhase;
+    state.currentPhase = site.id;
+    state.fillStack.push(site.id);
+    for (const fn of applicationsAt(state, node, "argument")) {
+        inlineBody(state, fn, chain, node, { label: name });
+    }
+    state.fillStack.pop();
+    state.currentPhase = outer;
+}
+/** 留白的阶段按首次到达铸一次（helper 里的留白每次调用都到达，阶段只有一个）。 */
+function mintHolePhase(state, site, name, fill) {
+    if (state.holePhases.has(site.id))
+        return;
+    state.holePhases.add(site.id);
+    state.phases.push({ id: site.id, loc: site.loc, name, ...(fill === undefined ? {} : { fill }) });
+}
+/**
+ * Inline one function body at a site: the `call` region (positioned at the SITE — it is
+ * this occurrence, not the declaration), inside a `loop` region when the function is
+ * recursive, with re-entry cut to a `recur` jump.
+ *
+ * The body is a STRAND when the applied function is `async` or the caller forces it (a
+ * deferred callback): it then gets a frame of its own, so the `await`s inside it suspend
+ * this activation and settle nothing for the spawner — which is the JavaScript semantics
+ * the single global settled set used to flatten.
+ */
+function inlineBody(state, decl, chain, site, options = {}) {
+    const { fnStack, sccLoopByDecl } = state;
+    const { label, prologue } = options;
+    if (fnStack.includes(decl)) {
+        // Recursion: the enclosing `loop` region carries it; the re-entrant call itself is a
+        // back edge to that loop for the control-flow projection.
+        const loop = sccLoopByDecl.get(decl);
+        if (loop !== undefined)
+            jump(state, "recur", loop, chain);
+        return;
+    }
+    const name = functionName(decl) ?? label;
+    const strand = options.strand === true || isAsyncFunction(decl);
+    let inside = chain;
+    let sccLoop;
+    if (state.recursive.has(decl)) {
+        // A call-graph SCC containing a step is a `loop` region, never unrolled.
+        sccLoop = openRegion(state, "loop", innermost(state, chain), {
+            entered: true,
+            loc: locOf(state, decl),
+            recursive: true,
+            ...(name === undefined ? {} : { label: name }),
+        });
+        inside = [...inside, sccLoop];
+    }
+    // The inlined body is a `call` region: the helper's boundary, which a `return` inside
+    // it targets.
+    const call = openRegion(state, "call", innermost(state, inside), {
+        entered: true,
+        loc: locOf(state, site),
+        ...(name === undefined ? {} : { label: name }),
+        ...(strand ? { strand: true } : {}),
+    });
+    inside = [...inside, call];
+    const record = strand ? openStrand(state, call) : undefined;
+    if (prologue !== undefined)
+        prologue(inside);
+    fnStack.push(decl);
+    state.walkedFns.add(decl);
+    const outerSccLoop = sccLoopByDecl.get(decl);
+    if (sccLoop !== undefined)
+        sccLoopByDecl.set(decl, sccLoop);
+    state.returnTargets.push(call);
+    state.walk(decl.body, inside);
+    state.returnTargets.pop();
+    if (outerSccLoop === undefined)
+        sccLoopByDecl.delete(decl);
+    else
+        sccLoopByDecl.set(decl, outerSccLoop);
+    fnStack.pop();
+    if (record !== undefined)
+        closeStrand(state, record);
+}

package/vendor/dynamic-workflow/analysis/causality-order-functions.d.ts

@@ -0,0 +1,26 @@
+import ts from "typescript";
+import type { ApplicationVia } from "./state.js";
+export type ScriptFunction = ts.SignatureDeclaration & {
+    body: ts.Node;
+};
+/** Identifiers a binding name introduces (an identifier, or every leaf of a pattern). */
+export declare function boundIdentifiers(name: ts.BindingName): ts.Identifier[];
+export declare function asScriptFunction(node: ts.Node, scriptFile: ts.SourceFile): ScriptFunction | undefined;
+/** The function-like ancestors of a node, innermost first. */
+export declare function enclosingFunctions(node: ts.Node): ScriptFunction[];
+export declare function functionName(decl: ts.Node): string | undefined;
+/**
+ * The script-local function a call resolves to. `getResolvedSignature` handles the
+ * hard shapes (methods, overloads, aliased consts) in one hop; anything outside the
+ * authored file (the facade, the stdlib) is not inlinable.
+ */
+export declare function resolveCallDeclaration(call: ts.CallExpression, checker: ts.TypeChecker, scriptFile: ts.SourceFile): ScriptFunction | undefined;
+/**
+ * Script-local functions that can reach themselves in the call graph — the SCCs the analysis turns into `loop` regions instead of unrolling. Callees are the union of the
+ * checker's resolved declarations and the call oracle's applications (both vias: a
+ * function handed to a library that hands it back is a cycle too). Nested function bodies
+ * count as their owner's callees, which over-approximates cycles; over-approximating here
+ * only costs a `loop` region, while under-approximating would unroll forever.
+ */
+export declare function collectRecursiveFunctions(scriptFile: ts.SourceFile, checker: ts.TypeChecker, applications: ReadonlyMap<ts.Node, ReadonlyMap<ts.Node, ApplicationVia>>): Set<ts.Node>;
+//# sourceMappingURL=causality-order-functions.d.ts.map

package/vendor/dynamic-workflow/analysis/causality-order-functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causality-order-functions.d.ts","sourceRoot":"","sources":["../../src/analysis/causality-order-functions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjD,MAAM,MAAM,cAAc,GAAG,EAAE,CAAC,oBAAoB,GAAG;IAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAA;CAAE,CAAC;AAEzE,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,GAAG,EAAE,CAAC,UAAU,EAAE,CAQtE;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,UAAU,EAAE,EAAE,CAAC,UAAU,GACxB,cAAc,GAAG,SAAS,CAK5B;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,cAAc,EAAE,CAQlE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,GAAG,SAAS,CAa9D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,EAAE,CAAC,cAAc,EACvB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,UAAU,EAAE,EAAE,CAAC,UAAU,GACxB,cAAc,GAAG,SAAS,CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,YAAY,EAAE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,GACvE,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAiDd"}

package/vendor/dynamic-workflow/analysis/causality-order-functions.js

@@ -0,0 +1,116 @@
+import ts from "typescript";
+import { isFunctionLike } from "./sites.js";
+/** Identifiers a binding name introduces (an identifier, or every leaf of a pattern). */
+export function boundIdentifiers(name) {
+    if (ts.isIdentifier(name))
+        return [name];
+    const out = [];
+    for (const element of name.elements) {
+        if (ts.isOmittedExpression(element))
+            continue;
+        out.push(...boundIdentifiers(element.name));
+    }
+    return out;
+}
+export function asScriptFunction(node, scriptFile) {
+    if (!isFunctionLike(node))
+        return undefined;
+    if (node.getSourceFile() !== scriptFile)
+        return undefined;
+    const body = node.body;
+    return body === undefined ? undefined : node;
+}
+/** The function-like ancestors of a node, innermost first. */
+export function enclosingFunctions(node) {
+    const scriptFile = node.getSourceFile();
+    const out = [];
+    for (let current = node.parent; current !== undefined; current = current.parent) {
+        const fn = asScriptFunction(current, scriptFile);
+        if (fn !== undefined)
+            out.push(fn);
+    }
+    return out;
+}
+export function functionName(decl) {
+    // A constructor is named by its class: `new Judge()` inlines as a call labelled "Judge".
+    if (ts.isConstructorDeclaration(decl)) {
+        const cls = decl.parent;
+        return ts.isClassLike(cls) && cls.name !== undefined ? cls.name.text : undefined;
+    }
+    const named = decl;
+    if (named.name !== undefined && ts.isIdentifier(named.name))
+        return named.name.text;
+    const parent = decl.parent;
+    if (parent !== undefined && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+        return parent.name.text;
+    }
+    return undefined;
+}
+/**
+ * The script-local function a call resolves to. `getResolvedSignature` handles the
+ * hard shapes (methods, overloads, aliased consts) in one hop; anything outside the
+ * authored file (the facade, the stdlib) is not inlinable.
+ */
+export function resolveCallDeclaration(call, checker, scriptFile) {
+    const declaration = checker.getResolvedSignature(call)?.declaration;
+    if (declaration === undefined)
+        return undefined;
+    return asScriptFunction(declaration, scriptFile);
+}
+/**
+ * Script-local functions that can reach themselves in the call graph — the SCCs the analysis turns into `loop` regions instead of unrolling. Callees are the union of the
+ * checker's resolved declarations and the call oracle's applications (both vias: a
+ * function handed to a library that hands it back is a cycle too). Nested function bodies
+ * count as their owner's callees, which over-approximates cycles; over-approximating here
+ * only costs a `loop` region, while under-approximating would unroll forever.
+ */
+export function collectRecursiveFunctions(scriptFile, checker, applications) {
+    const functions = [];
+    const collect = (node) => {
+        const fn = asScriptFunction(node, scriptFile);
+        if (fn !== undefined)
+            functions.push(fn);
+        ts.forEachChild(node, collect);
+    };
+    collect(scriptFile);
+    const callees = new Map();
+    for (const fn of functions) {
+        const set = new Set();
+        const scan = (node) => {
+            if (ts.isCallExpression(node)) {
+                const target = resolveCallDeclaration(node, checker, scriptFile);
+                if (target !== undefined)
+                    set.add(target);
+            }
+            if (ts.isCallExpression(node) ||
+                ts.isNewExpression(node) ||
+                ts.isTaggedTemplateExpression(node)) {
+                for (const applied of applications.get(node)?.keys() ?? []) {
+                    const target = asScriptFunction(applied, scriptFile);
+                    if (target !== undefined)
+                        set.add(target);
+                }
+            }
+            ts.forEachChild(node, scan);
+        };
+        scan(fn.body);
+        callees.set(fn, set);
+    }
+    const recursive = new Set();
+    for (const fn of functions) {
+        const seen = new Set();
+        const stack = [...(callees.get(fn) ?? [])];
+        while (stack.length > 0) {
+            const next = stack.pop();
+            if (next === fn) {
+                recursive.add(fn);
+                break;
+            }
+            if (seen.has(next))
+                continue;
+            seen.add(next);
+            stack.push(...(callees.get(next) ?? []));
+        }
+    }
+    return recursive;
+}

package/vendor/dynamic-workflow/analysis/causality-order-loops.d.ts

@@ -0,0 +1,5 @@
+import ts from "typescript";
+import { type TraceState } from "./causality-order-state.js";
+/** The loop cases of the visitor. Returns false when `node` is not a loop statement. */
+export declare function walkLoop(state: TraceState, node: ts.Node, chain: readonly string[]): boolean;
+//# sourceMappingURL=causality-order-loops.d.ts.map

package/vendor/dynamic-workflow/analysis/causality-order-loops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causality-order-loops.d.ts","sourceRoot":"","sources":["../../src/analysis/causality-order-loops.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,4BAA4B,CAAC;AAqBpC,wFAAwF;AACxF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAkE5F"}

package/vendor/dynamic-workflow/analysis/causality-order-loops.js

@@ -0,0 +1,148 @@
+import ts from "typescript";
+import { innermost, issuesSince, locOf, openRegion, } from "./causality-order-state.js";
+import { barrier, recordControl, settlesAt } from "./causality-order-settle.js";
+import { strandMark } from "./causality-order-strands.js";
+// causality-order.ts 顶到 oxlint max-lines 上限（400 行），把循环语句的访问器
+// （for / for-of / for-in / while / do…while）连同 `for` 字面量轮数的推导拆到本文件；公开面
+// 仍从 causality-order.ts 导出。{@link walkLoop} 在 walk 的 if 链里占原来四个分支的位置，
+// 判定顺序与原文件逐字一致。
+/** Walk a loop body with its statement registered as a jump target for the duration. */
+function walkLoopBody(state, statement, body, chain) {
+    state.regionByStatement.set(statement, innermost(state, chain));
+    state.walk(body, chain);
+    state.regionByStatement.delete(statement);
+}
+/** The loop cases of the visitor. Returns false when `node` is not a loop statement. */
+export function walkLoop(state, node, chain) {
+    const { walk } = state;
+    if (ts.isForStatement(node)) {
+        const { bound, entered } = literalForBound(node);
+        if (node.initializer !== undefined)
+            walk(node.initializer, chain);
+        if (node.condition !== undefined)
+            walk(node.condition, chain);
+        if (node.incrementor !== undefined)
+            walk(node.incrementor, chain);
+        const id = openRegion(state, "loop", innermost(state, chain), {
+            entered,
+            loc: locOf(state, node),
+            ...(bound === undefined ? {} : { bound }),
+        });
+        if (node.condition !== undefined)
+            recordControl(state, node.condition, id);
+        walkLoopBody(state, node, node.statement, [...chain, id]);
+        return true;
+    }
+    if (ts.isForOfStatement(node) || ts.isForInStatement(node)) {
+        const mark = state.events.length;
+        const spawned = strandMark(state);
+        walk(node.expression, chain);
+        const id = openRegion(state, "loop", innermost(state, chain), {
+            entered: false,
+            loc: locOf(state, node),
+        });
+        const inside = [...chain, id];
+        // `for await (… of …)` awaits every element, so each iteration opens with a
+        // barrier over whatever the iterated expression issued — plus, from the oracle,
+        // whatever labels that expression's VALUE carries (an array of pending promises
+        // issues nothing at this point, which is the whole reason the oracle exists).
+        if (ts.isForOfStatement(node) && node.awaitModifier !== undefined) {
+            const claim = settlesAt(state, node.expression, node.expression.getStart(state.scriptFile));
+            barrier(state, [...issuesSince(state, mark), ...claim.certain], claim.maybe, inside, {
+                mark: spawned,
+                operand: node.expression,
+            });
+        }
+        walk(node.initializer, inside);
+        walkLoopBody(state, node, node.statement, inside);
+        return true;
+    }
+    if (ts.isWhileStatement(node)) {
+        walk(node.expression, chain);
+        const id = openRegion(state, "loop", innermost(state, chain), {
+            entered: false,
+            loc: locOf(state, node),
+        });
+        recordControl(state, node.expression, id);
+        walkLoopBody(state, node, node.statement, [...chain, id]);
+        return true;
+    }
+    if (ts.isDoStatement(node)) {
+        // A `do…while` body is unconditional on first entry, so it is `entered` and its
+        // condition is NOT a guard.
+        const id = openRegion(state, "loop", innermost(state, chain), {
+            entered: true,
+            loc: locOf(state, node),
+        });
+        walkLoopBody(state, node, node.statement, [...chain, id]);
+        walk(node.expression, [...chain, id]);
+        return true;
+    }
+    return false;
+}
+/**
+ * A `for` loop's provable entry and round count: `for (let i = <a>; i < <b>; i++)`
+ * with numeric literals and `a < b` runs `b - a` times. `entered` needs only the
+ * literal comparison; `bound` additionally needs a unit increment, or the count would
+ * be a guess.
+ */
+function literalForBound(node) {
+    const initializer = node.initializer;
+    const condition = node.condition;
+    if (initializer === undefined || !ts.isVariableDeclarationList(initializer)) {
+        return { entered: false };
+    }
+    const decl = initializer.declarations[0];
+    if (decl === undefined || !ts.isIdentifier(decl.name) || decl.initializer === undefined) {
+        return { entered: false };
+    }
+    const start = numericValue(decl.initializer);
+    if (start === undefined || condition === undefined || !ts.isBinaryExpression(condition)) {
+        return { entered: false };
+    }
+    if (!ts.isIdentifier(condition.left) || condition.left.text !== decl.name.text) {
+        return { entered: false };
+    }
+    const limit = numericValue(condition.right);
+    if (limit === undefined)
+        return { entered: false };
+    const operator = condition.operatorToken.kind;
+    const rounds = operator === ts.SyntaxKind.LessThanToken && start < limit
+        ? limit - start
+        : operator === ts.SyntaxKind.LessThanEqualsToken && start <= limit
+            ? limit - start + 1
+            : undefined;
+    if (rounds === undefined)
+        return { entered: false };
+    return isUnitIncrement(node.incrementor, decl.name.text)
+        ? { bound: rounds, entered: true }
+        : { entered: true };
+}
+function numericValue(expr) {
+    if (ts.isNumericLiteral(expr))
+        return Number(expr.text);
+    if (ts.isPrefixUnaryExpression(expr) && expr.operator === ts.SyntaxKind.MinusToken) {
+        const inner = numericValue(expr.operand);
+        return inner === undefined ? undefined : -inner;
+    }
+    return undefined;
+}
+function isUnitIncrement(incrementor, name) {
+    if (incrementor === undefined)
+        return false;
+    if (ts.isPostfixUnaryExpression(incrementor) &&
+        incrementor.operator === ts.SyntaxKind.PlusPlusToken) {
+        return ts.isIdentifier(incrementor.operand) && incrementor.operand.text === name;
+    }
+    if (ts.isPrefixUnaryExpression(incrementor) &&
+        incrementor.operator === ts.SyntaxKind.PlusPlusToken) {
+        return ts.isIdentifier(incrementor.operand) && incrementor.operand.text === name;
+    }
+    if (ts.isBinaryExpression(incrementor) &&
+        incrementor.operatorToken.kind === ts.SyntaxKind.PlusEqualsToken &&
+        ts.isIdentifier(incrementor.left) &&
+        incrementor.left.text === name) {
+        return numericValue(incrementor.right) === 1;
+    }
+    return false;
+}

package/vendor/dynamic-workflow/analysis/causality-order-settle.d.ts

@@ -0,0 +1,39 @@
+import ts from "typescript";
+import type { TraceState } from "./causality-order-state.js";
+import { type AwaitedOperand } from "./causality-order-strands.js";
+/** An oracle lookup split by the settle-certainty rule. Readonly because {@link NO_CLAIM}
+ * is a shared singleton — an in-place edit of an empty result would leak everywhere. */
+interface OracleClaim {
+    certain: readonly string[];
+    maybe: readonly string[];
+}
+export declare function settlesAt(state: TraceState, node: ts.Node, at: number): OracleClaim;
+/**
+ * An `await` barrier over the union of what the two halves resolved, plus the summaries of
+ * the STRANDS it joins: `certain` settles as a certainty, `maybe` as a may-claim (a step
+ * claimed by both counts as certain). Steps already settled IN A VISIBLE FRAME drop out,
+ * and a claim that has entirely settled already is a no-op. Widening is reached only when
+ * the claim and every joined summary were empty to begin with.
+ *
+ * The already-settled no-op is not new; what changed is that it became REACHABLE. Before
+ * the settle oracle, an indirect await (`await held`, `await p` in a helper, a second await of
+ * one promise) resolved to the empty set, so every such await fell through to widening and
+ * manufactured `seq maybe` claims over unrelated steps still in flight. The oracle makes
+ * the claim non-empty, so the no-op catches it and those spurious barriers disappear —
+ * which is why several async-promise-* snapshots got STRONGER certainties once the oracle
+ * landed rather than gaining edges.
+ *
+ * Two frame rules carry the strand model:
+ * freshness is judged against EVERY frame on the stack, because a step the spawner
+ * already awaited is settled for the strands it spawns; fresh steps are recorded in the
+ * CURRENT frame alone, because this activation's await tells the spawner nothing.
+ * `awaited` is the operand this barrier stands over, which {@link joinStrands} scans for
+ * the promises it names; a barrier with no operand (a deferred callback's receiver
+ * prologue) can still LIFT a strand out of its own claim.
+ */
+export declare function barrier(state: TraceState, certain: readonly string[], maybe: readonly string[], chain: readonly string[], awaited?: AwaitedOperand): void;
+export declare function bindSteps(state: TraceState, name: ts.BindingName, steps: readonly string[]): void;
+/** Record a guard's control dependence against a region, when it has any. */
+export declare function recordControl(state: TraceState, guard: ts.Expression, region: string): void;
+export {};
+//# sourceMappingURL=causality-order-settle.d.ts.map

package/vendor/dynamic-workflow/analysis/causality-order-settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causality-order-settle.d.ts","sourceRoot":"","sources":["../../src/analysis/causality-order-settle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAI5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAOtC;wFACwF;AACxF,UAAU,WAAW;IACnB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAqHD,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAEnF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,IAAI,CA4DN;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CASjG;AAwCD,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAK3F"}