@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.0

package/vendor/dynamic-workflow/analysis/site-phases.d.ts

@@ -0,0 +1,32 @@
+import type { AnalysisCore } from "./core.js";
+import type { ControlFlowGraph } from "./flow-graph.js";
+/**
+ * 站点 → 出生阶段**名**的编译期表（docs/analysis.md「Phases」；引擎侧见 execution-engine.md
+ * 「Identity: sites, ordinals, phases」）。
+ *
+ * 引擎给实例打的出生阶段戳原本只看「脚本最近经过的标记」——单线叙事下没错，但两个 future
+ * 各自以自己的标记开头并发跑起来后，一个生产者在首次 await 之后发出的第二个 ask，会被戳成
+ * 最后一个跑过的标记，也就是消费者那一段。所以戳改成**词法优先**：分析器的时序 walk 早就按
+ * 内联语义（helper 内联到调用点、回调放在注册处、future 体放在调用处）给每个 issue 记了当时的
+ * 阶段；一个站点的所有 issue（actor 站点则是所有 spawn）都落在**同一个有名阶段**时，那就是它
+ * 的出生阶段，与确认窗画给用户的图一致。落在两个阶段（被两处调用的 helper）或只落在 unphased
+ * 的站点不进表，引擎对它退回动态当前阶段。
+ *
+ * 以 trace 而不是投影图为源：投影会给跨阶段的步做 phase copy，而这里要的恰是「是否唯一」。
+ * 名字（不是 phase id）进表，因为引擎的戳与 `phase-entered` 事件都用作者的原词。
+ */
+/**
+ * run 的声明阶段表（execution-engine.md「run-launched」的 `phaseNames` / `holes`）：控制流投影
+ * 阶段表里**有名**的阶段按序取名——留白按名字站在它的位置上——外加与之对齐的下标表 `holes`，
+ * 指出其中哪些是**开放的留白**，侧栏迷你轨道据此把那些站画成虚线。无阶段词汇表时两张表都是
+ * 空数组（提交方据此让字段整个缺席）。
+ *
+ * 与 `createWorkflowPhaseNames`（contracts）同一份来源（控制流投影的阶段表，含只有标记的阶段），
+ * 所以补全后重算的表与 launch 时的表按同一条规则对齐。
+ */
+export declare function collectPhaseNames(flow: Pick<ControlFlowGraph, "phases" | "holes"> | undefined): {
+    phaseNames: string[];
+    holes: number[];
+};
+export declare function collectSitePhases(core: AnalysisCore): ReadonlyMap<string, string>;
+//# sourceMappingURL=site-phases.d.ts.map

package/vendor/dynamic-workflow/analysis/site-phases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-phases.d.ts","sourceRoot":"","sources":["../../src/analysis/site-phases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,SAAS,GAAG;IAC/F,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAUA;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBjF"}

package/vendor/dynamic-workflow/analysis/site-phases.js

@@ -0,0 +1,69 @@
+import { UNPHASED_ID } from "./constants.js";
+/**
+ * 站点 → 出生阶段**名**的编译期表（docs/analysis.md「Phases」；引擎侧见 execution-engine.md
+ * 「Identity: sites, ordinals, phases」）。
+ *
+ * 引擎给实例打的出生阶段戳原本只看「脚本最近经过的标记」——单线叙事下没错，但两个 future
+ * 各自以自己的标记开头并发跑起来后，一个生产者在首次 await 之后发出的第二个 ask，会被戳成
+ * 最后一个跑过的标记，也就是消费者那一段。所以戳改成**词法优先**：分析器的时序 walk 早就按
+ * 内联语义（helper 内联到调用点、回调放在注册处、future 体放在调用处）给每个 issue 记了当时的
+ * 阶段；一个站点的所有 issue（actor 站点则是所有 spawn）都落在**同一个有名阶段**时，那就是它
+ * 的出生阶段，与确认窗画给用户的图一致。落在两个阶段（被两处调用的 helper）或只落在 unphased
+ * 的站点不进表，引擎对它退回动态当前阶段。
+ *
+ * 以 trace 而不是投影图为源：投影会给跨阶段的步做 phase copy，而这里要的恰是「是否唯一」。
+ * 名字（不是 phase id）进表，因为引擎的戳与 `phase-entered` 事件都用作者的原词。
+ */
+/**
+ * run 的声明阶段表（execution-engine.md「run-launched」的 `phaseNames` / `holes`）：控制流投影
+ * 阶段表里**有名**的阶段按序取名——留白按名字站在它的位置上——外加与之对齐的下标表 `holes`，
+ * 指出其中哪些是**开放的留白**，侧栏迷你轨道据此把那些站画成虚线。无阶段词汇表时两张表都是
+ * 空数组（提交方据此让字段整个缺席）。
+ *
+ * 与 `createWorkflowPhaseNames`（contracts）同一份来源（控制流投影的阶段表，含只有标记的阶段），
+ * 所以补全后重算的表与 launch 时的表按同一条规则对齐。
+ */
+export function collectPhaseNames(flow) {
+    const phaseNames = [];
+    const holes = [];
+    const open = new Set((flow?.holes ?? []).map((hole) => hole.siteId));
+    for (const phase of flow?.phases ?? []) {
+        if (phase.name === undefined)
+            continue;
+        if (open.has(phase.id))
+            holes.push(phaseNames.length);
+        phaseNames.push(phase.name);
+    }
+    return { holes, phaseNames };
+}
+export function collectSitePhases(core) {
+    const nameOf = new Map();
+    for (const phase of core.trace.phases)
+        nameOf.set(phase.id, phase.name);
+    const claims = new Map();
+    const claim = (site, phase) => {
+        const set = claims.get(site);
+        if (set === undefined)
+            claims.set(site, new Set([phase]));
+        else
+            set.add(phase);
+    };
+    for (const event of core.trace.events) {
+        if (event.at === "issue")
+            claim(event.step, event.phase);
+        else if (event.at === "actor")
+            claim(event.actor, event.phase);
+    }
+    const table = new Map();
+    for (const [site, phases] of claims) {
+        if (phases.size !== 1)
+            continue;
+        const [phase] = phases;
+        if (phase === undefined || phase === UNPHASED_ID)
+            continue;
+        const name = nameOf.get(phase);
+        if (name !== undefined)
+            table.set(site, name);
+    }
+    return table;
+}

package/vendor/dynamic-workflow/analysis/sites-labels.d.ts

@@ -0,0 +1,71 @@
+import ts from "typescript";
+import type { WorldReadOp } from "../facade/registry.js";
+import type { ScriptLoc } from "../compiler/compile.js";
+import type { NamePattern } from "./types.js";
+import type { CallbackSemantics } from "./callbacks.js";
+import type { IterationCandidate } from "./sites.js";
+/** Resolve a node's symbol, following one alias hop (imports never occur here). */
+export declare function resolveSymbol(node: ts.Node, checker: ts.TypeChecker): ts.Symbol | undefined;
+/** True iff any of the symbol's declarations lives in the facade `.d.ts`. */
+export declare function isFacadeDeclared(symbol: ts.Symbol | undefined): boolean;
+/**
+ * 一个实参**无洞字符串字面量**的文本，其余（标识符、带洞模板、任意表达式）一律 undefined。
+ *
+ * 三处共用一条判定：phase 的名字、产物的 id、report 的标签。三者的规矩完全相同——只有编译期
+ * 就闭合的字面量才算数，看不穿的一律留给各自的诊断趟按原表达式定位，**绝不在这里猜一个值
+ * 出来**（猜出来的名字会让一条本该被教改写的调用静默通过）。`ts.isStringLiteralLike` 覆盖
+ * 无插值的反引号串。
+ */
+export declare function literalText(expr: ts.Expression | undefined): string | undefined;
+/**
+ * 一套 per-kind 站点计数器（`ask#N` / `actor#N` / …），外加 id 前缀。
+ *
+ * 前缀是留白的事（docs/analysis.md「Sites」的 Hole sites 段）：走查进入一个留白的函数体时
+ * **开一套全新的计数器**，体内铸出的每个 id 都带 `<holeId>/`（`hole#a91f3c07/ask#1`），外层
+ * 计数器从不看见体内的站点。于是补全一个留白（在脚本中间插入代码）不改动任何已有的 `ask#N` /
+ * `actor#N` / …——这是站点 id 稳定性规则从「加标记」到「加函数体」的延伸；活 run 的 journal
+ * 键、ask spec、站点阶段表都靠它在补全后幸存。前缀只有**一层**：留白自己的 id 是名字键
+ * （hole-id.ts），不带外层前缀，体内再留的留白因此不会让 id 随深度增长；`holeId` 记着
+ * 这套计数器属于哪个留白，让体内的留白站点把包着它的留白写进 `fill`。
+ * 全局 `order` 不在这里：它是文本输出的归并键，穿过函数体连续计数。
+ */
+export declare class SiteCounters {
+    private readonly prefix;
+    /** 这套计数器所在的留白函数体（顶层没有）。 */
+    readonly holeId?: string | undefined;
+    private readonly counts;
+    constructor(prefix?: string, 
+    /** 这套计数器所在的留白函数体（顶层没有）。 */
+    holeId?: string | undefined);
+    /** 铸下一个 `<prefix><kind>#<n>`。 */
+    next(kind: string): string;
+    /** 进入留白 `holeId` 的函数体：全新一套计数器，前缀就是这个留白的 id（不叠加外层的）。 */
+    child(holeId: string): SiteCounters;
+}
+/**
+ * ask label: an inline `agent("name", …)` receiver contributes its literal name;
+ * a plain identifier receiver contributes its text; otherwise `"ask"`.
+ */
+export declare function askLabel(receiver: ts.Expression, checker: ts.TypeChecker): string;
+/**
+ * ask label pattern: only for an inline `` agent(`研究员${i}`) `` receiver — the one shape
+ * `askLabel` answers `"ask"` for despite the script having said something. A named or
+ * identifier receiver already produced a real label, so there is nothing to reconstruct.
+ */
+export declare function askLabelPattern(receiver: ts.Expression, checker: ts.TypeChecker): NamePattern | undefined;
+/**
+ * actor name: a string-literal first argument, else the binding name when the call
+ * directly initializes a variable declaration, else undefined.
+ */
+export declare function actorName(call: ts.CallExpression): string | undefined;
+/**
+ * actor name pattern: the static shape of a first argument that is a template literal
+ * with holes. Only consulted when `actorName` came back undefined — a literal name and a
+ * binding name are both real names, and a pattern must never displace one.
+ */
+export declare function actorNamePattern(call: ts.CallExpression): NamePattern | undefined;
+/** world-read label: the op name, plus a string-literal first argument when present. */
+export declare function worldReadLabel(op: WorldReadOp, arg: ts.Expression | undefined): string;
+export declare function eachCandidate(call: ts.CallExpression, semantics: CallbackSemantics, order: number, loc: ScriptLoc): IterationCandidate | undefined;
+export declare function forOfCandidate(statement: ts.ForOfStatement, order: number, loc: ScriptLoc): IterationCandidate;
+//# sourceMappingURL=sites-labels.d.ts.map

package/vendor/dynamic-workflow/analysis/sites-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites-labels.d.ts","sourceRoot":"","sources":["../../src/analysis/sites-labels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAOrD,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,GAAG,EAAE,CAAC,MAAM,GAAG,SAAS,CAM3F;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,GAAG,SAAS,GAAG,OAAO,CAMvE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE/E;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IAIrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAL1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;gBAGjC,MAAM,SAAK;IAC5B,2BAA2B;IAClB,MAAM,CAAC,EAAE,MAAM,YAAA;IAG1B,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAM1B,uDAAuD;IACvD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;CAGpC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,GAAG,MAAM,CAOjF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,EAAE,CAAC,UAAU,EACvB,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,WAAW,GAAG,SAAS,CAGzB;AAQD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,GAAG,MAAM,GAAG,SAAS,CAYrE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,GAAG,WAAW,GAAG,SAAS,CAEjF;AAkCD,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,GAAG,MAAM,CAGtF;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,EAAE,CAAC,cAAc,EACvB,SAAS,EAAE,iBAAiB,EAC5B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,SAAS,GACb,kBAAkB,GAAG,SAAS,CAkBhC;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,EAAE,CAAC,cAAc,EAC5B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,SAAS,GACb,kBAAkB,CAapB"}

package/vendor/dynamic-workflow/analysis/sites-labels.js

@@ -0,0 +1,189 @@
+import ts from "typescript";
+import { FACADE_FILE_NAME } from "../facade/dts.js";
+// sites.ts 顶到 oxlint max-lines 上限（400 行），把名字 / 标签辅助（ask 标签与模板
+// 形状、actor 名与模板形状、world-read 标签、字面量文本、迭代候选的构造、计数器）与它们依赖的
+// 符号解析（resolveSymbol / isFacadeDeclared）拆到本文件；公开面仍从 sites.ts 导出（后两者
+// 在那里原样再导出，其余本就不公开）。站点类型留在 sites.ts，这里只按类型导入。
+/** Resolve a node's symbol, following one alias hop (imports never occur here). */
+export function resolveSymbol(node, checker) {
+    const symbol = checker.getSymbolAtLocation(node);
+    if (symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0) {
+        return checker.getAliasedSymbol(symbol);
+    }
+    return symbol;
+}
+/** True iff any of the symbol's declarations lives in the facade `.d.ts`. */
+export function isFacadeDeclared(symbol) {
+    return (symbol?.declarations?.some((declaration) => declaration.getSourceFile().fileName === FACADE_FILE_NAME) ?? false);
+}
+/**
+ * 一个实参**无洞字符串字面量**的文本，其余（标识符、带洞模板、任意表达式）一律 undefined。
+ *
+ * 三处共用一条判定：phase 的名字、产物的 id、report 的标签。三者的规矩完全相同——只有编译期
+ * 就闭合的字面量才算数，看不穿的一律留给各自的诊断趟按原表达式定位，**绝不在这里猜一个值
+ * 出来**（猜出来的名字会让一条本该被教改写的调用静默通过）。`ts.isStringLiteralLike` 覆盖
+ * 无插值的反引号串。
+ */
+export function literalText(expr) {
+    return expr !== undefined && ts.isStringLiteralLike(expr) ? expr.text : undefined;
+}
+/**
+ * 一套 per-kind 站点计数器（`ask#N` / `actor#N` / …），外加 id 前缀。
+ *
+ * 前缀是留白的事（docs/analysis.md「Sites」的 Hole sites 段）：走查进入一个留白的函数体时
+ * **开一套全新的计数器**，体内铸出的每个 id 都带 `<holeId>/`（`hole#a91f3c07/ask#1`），外层
+ * 计数器从不看见体内的站点。于是补全一个留白（在脚本中间插入代码）不改动任何已有的 `ask#N` /
+ * `actor#N` / …——这是站点 id 稳定性规则从「加标记」到「加函数体」的延伸；活 run 的 journal
+ * 键、ask spec、站点阶段表都靠它在补全后幸存。前缀只有**一层**：留白自己的 id 是名字键
+ * （hole-id.ts），不带外层前缀，体内再留的留白因此不会让 id 随深度增长；`holeId` 记着
+ * 这套计数器属于哪个留白，让体内的留白站点把包着它的留白写进 `fill`。
+ * 全局 `order` 不在这里：它是文本输出的归并键，穿过函数体连续计数。
+ */
+export class SiteCounters {
+    prefix;
+    holeId;
+    counts = new Map();
+    constructor(prefix = "", 
+    /** 这套计数器所在的留白函数体（顶层没有）。 */
+    holeId) {
+        this.prefix = prefix;
+        this.holeId = holeId;
+    }
+    /** 铸下一个 `<prefix><kind>#<n>`。 */
+    next(kind) {
+        const n = (this.counts.get(kind) ?? 0) + 1;
+        this.counts.set(kind, n);
+        return `${this.prefix}${kind}#${n}`;
+    }
+    /** 进入留白 `holeId` 的函数体：全新一套计数器，前缀就是这个留白的 id（不叠加外层的）。 */
+    child(holeId) {
+        return new SiteCounters(`${holeId}/`, holeId);
+    }
+}
+/**
+ * ask label: an inline `agent("name", …)` receiver contributes its literal name;
+ * a plain identifier receiver contributes its text; otherwise `"ask"`.
+ */
+export function askLabel(receiver, checker) {
+    if (ts.isCallExpression(receiver) && isActorCall(receiver, checker)) {
+        const first = receiver.arguments[0];
+        if (first !== undefined && ts.isStringLiteralLike(first))
+            return first.text;
+    }
+    if (ts.isIdentifier(receiver))
+        return receiver.text;
+    return "ask";
+}
+/**
+ * ask label pattern: only for an inline `` agent(`研究员${i}`) `` receiver — the one shape
+ * `askLabel` answers `"ask"` for despite the script having said something. A named or
+ * identifier receiver already produced a real label, so there is nothing to reconstruct.
+ */
+export function askLabelPattern(receiver, checker) {
+    if (!ts.isCallExpression(receiver) || !isActorCall(receiver, checker))
+        return undefined;
+    return templateAffixes(receiver.arguments[0]);
+}
+function isActorCall(call, checker) {
+    if (ts.isPropertyAccessExpression(call.expression))
+        return false;
+    const symbol = resolveSymbol(call.expression, checker);
+    return isFacadeDeclared(symbol) && symbol?.name === "agent";
+}
+/**
+ * actor name: a string-literal first argument, else the binding name when the call
+ * directly initializes a variable declaration, else undefined.
+ */
+export function actorName(call) {
+    const first = call.arguments[0];
+    if (first !== undefined && ts.isStringLiteralLike(first))
+        return first.text;
+    const parent = call.parent;
+    if (ts.isVariableDeclaration(parent) &&
+        parent.initializer === call &&
+        ts.isIdentifier(parent.name)) {
+        return parent.name.text;
+    }
+    return undefined;
+}
+/**
+ * actor name pattern: the static shape of a first argument that is a template literal
+ * with holes. Only consulted when `actorName` came back undefined — a literal name and a
+ * binding name are both real names, and a pattern must never displace one.
+ */
+export function actorNamePattern(call) {
+    return templateAffixes(call.arguments[0]);
+}
+/**
+ * 模板字符串两端的字面量：第一个洞之前（`head`）与最后一个洞之后（`tail`）。
+ *
+ * `ts.isStringLiteralLike` 已经覆盖了无插值的反引号串（那是字面量，走 `name` 那条路），
+ * 所以这里只处理真正带洞的 `ts.TemplateExpression`。
+ *
+ * **中间的字面量刻意丢弃**：`` `a${x}b${y}c` `` 给出 `a` 与 `c`，不是 `a…b…c`。名字是一行
+ * 上的标签，不是产生它的那个表达式的渲染。
+ */
+function templateAffixes(arg) {
+    if (arg === undefined || !ts.isTemplateExpression(arg))
+        return undefined;
+    const head = meaningfulAffix(arg.head.text);
+    const tail = meaningfulAffix(arg.templateSpans.at(-1)?.literal.text);
+    if (head === undefined && tail === undefined)
+        return undefined;
+    return {
+        ...(head === undefined ? {} : { head }),
+        ...(tail === undefined ? {} : { tail }),
+    };
+}
+/**
+ * 一个 affix 值不值得显示：trim 后必须至少含一个字母或数字。
+ *
+ * 为什么要这道门：`` agent(`${x}-`) `` 的 tail 是 `-`，渲染出来是 `…-`——那比「未命名智能体」
+ * 更差，读者既得不到名字，还多了一串标点。`\p{L}` 覆盖 CJK，所以「研究员」照常通过。
+ */
+function meaningfulAffix(text) {
+    const trimmed = text?.trim();
+    if (trimmed === undefined || trimmed === "")
+        return undefined;
+    return /[\p{L}\p{N}]/u.test(trimmed) ? trimmed : undefined;
+}
+/** world-read label: the op name, plus a string-literal first argument when present. */
+export function worldReadLabel(op, arg) {
+    if (arg !== undefined && ts.isStringLiteralLike(arg))
+        return `${op} ${arg.text}`;
+    return op;
+}
+export function eachCandidate(call, semantics, order, loc) {
+    const index = semantics.callbacks[0];
+    const argument = index === undefined ? undefined : call.arguments[index];
+    const iterated = semantics.iterated;
+    if (argument === undefined || iterated === undefined)
+        return undefined;
+    const literal = ts.isArrowFunction(argument) || ts.isFunctionExpression(argument);
+    return {
+        body: literal ? argument.body : argument,
+        ...(literal ? { callback: argument } : { callbackExpr: argument }),
+        call,
+        element: literal ? argument.parameters[semantics.elementParams?.[0] ?? 0]?.name : undefined,
+        form: "array-method",
+        iterated,
+        loc,
+        method: semantics.label,
+        order,
+        semantics,
+    };
+}
+export function forOfCandidate(statement, order, loc) {
+    let element;
+    if (ts.isVariableDeclarationList(statement.initializer)) {
+        element = statement.initializer.declarations[0]?.name;
+    }
+    return {
+        body: statement.statement,
+        element,
+        form: "for-of",
+        iterated: statement.expression,
+        loc,
+        order,
+    };
+}

package/vendor/dynamic-workflow/analysis/sites.d.ts

@@ -0,0 +1,267 @@
+import ts from "typescript";
+import { type ArtifactOp, type WorldReadOp } from "../facade/registry.js";
+import { type ScriptLoc, type WorkflowProgram } from "../compiler/compile.js";
+import type { NamePattern } from "./types.js";
+import { type CallbackSemantics } from "./callbacks.js";
+export { isFacadeDeclared, resolveSymbol } from "./sites-labels.js";
+/**
+ * The site table: the raw substrate the taint pass builds on. One walk over the
+ * wrapped script body collects every facade call site (resolved via the checker,
+ * never by name), keeps their `ts.Node` references, and records iteration
+ * candidates and top-level returns. This module owns the table type; it is
+ * deliberately NOT re-exported from the package index — only `analyzeWorkflowScript`
+ * and the graph types are public.
+ *
+ * Ordinal ids are per-kind source-order counters (`ask#1`, `join#2`, …); `order`
+ * is a single global discovery sequence used to merge the per-kind lists back into
+ * source order for serialization. Source order = pre-order AST traversal, which is
+ * `ts.forEachChild` order.
+ */
+export interface AskSite {
+    id: string;
+    order: number;
+    label: string;
+    /** `label` 落到兜底串时，内联 `agent()` receiver 的模板形状；见 `askLabelPattern`。 */
+    labelPattern?: NamePattern;
+    loc: ScriptLoc;
+    /** The `x.ask(...)` call. */
+    call: ts.CallExpression;
+    /** The receiver of `.ask` (the actor expression). Read for actor/context labels. */
+    receiver: ts.Expression;
+    /** The instruction argument, if present. The taint pass reads it as a sink. */
+    instructions: ts.Expression | undefined;
+}
+export interface ActorSite {
+    id: string;
+    order: number;
+    name: string | undefined;
+    /** `name` 缺席而首参是模板字符串时的静态形状；见 `actorNamePattern`。 */
+    namePattern?: NamePattern;
+    loc: ScriptLoc;
+    /** The `agent(...)` call. */
+    call: ts.CallExpression;
+}
+/**
+ * A `report(...)` call site. A site that becomes **no node in either graph**: lowering
+ * needs an id, the journal keys report nodes by site × ordinal for replay dedupe, and
+ * the facade-siting rule needs something to point at — but a report emits progress, not
+ * order, and nothing can wait for it, so there is nothing for an edge to mean. Its
+ * argument is likewise **not a taint sink**.
+ *
+ * `report#N` is its own per-kind counter, so every existing `ask#N` / `actor#N` /
+ * `world-read#N` id stays bit-for-bit unchanged — the invariant the site-id stability
+ * rule actually protects. Report sites DO consume the global `order` discovery sequence,
+ * which shifts serialization interleaving in text snapshots and nothing else: `order` is
+ * a merge key for output, per-kind counters are journal keys.
+ */
+export interface ReportSite {
+    id: string;
+    order: number;
+    loc: ScriptLoc;
+    /** The `report(...)` call. */
+    call: ts.CallExpression;
+    /**
+     * The reported item expression, if present. Read by the compile-side serializability
+     * check (schema/synthesize.ts) — NOT by the taint pass.
+     */
+    item: ts.Expression | undefined;
+    /**
+     * The artifact tag (`report(item, "perf")`), set only when the second argument is a
+     * string literal without holes. It routes the item to a preset artifact. Absent means
+     * either "no tag" or "a tag the compiler could not read"; {@link artifactIdExpr} tells
+     * those apart, and the artifacts pass rejects the second case.
+     */
+    artifactId?: string;
+    /**
+     * The tag argument, if present. Kept raw so the diagnostics pass can position a
+     * rejection on the offending expression rather than on the call (same reason
+     * {@link PhaseMarkerSite.nameExpr} is kept).
+     */
+    artifactIdExpr: ts.Expression | undefined;
+}
+/**
+ * An `artifact.*(...)` call site: one publish (`file` / `markdown`) or one preset
+ * declaration (`chart` / `table` / `metrics` / `board`).
+ *
+ * ⚠ 术语：这里的 artifact 是**用户面产物**（脚本发布给用户看的产出），不是同名的引擎内部
+ * 概念（顶层返回值 / 站点的类型化输出值，见 `analysis/artifact-types.ts`）。
+ *
+ * Like {@link ReportSite} it is **sited but drawn in neither graph**: a publish is a
+ * deliverable, not a step other steps can wait for, so there is nothing an edge could
+ * mean; and its arguments are **not taint sinks** for the same reason `report`'s are not.
+ * What it does need an id for is the journal (`artifact#N` × ordinal keys the replay
+ * dedupe) and the facade-siting rule.
+ *
+ * `artifact#N` is its own per-kind counter, so every existing `ask#N` / `actor#N` /
+ * `report#N` / `world-read#N` id stays bit-for-bit unchanged. It DOES consume the global
+ * `order` discovery sequence, exactly as report sites do.
+ */
+export interface ArtifactSite {
+    id: string;
+    order: number;
+    /** The registry op (`file`, `chart`, …), resolved by DECLARING CONTAINER, never by name. */
+    op: ArtifactOp;
+    loc: ScriptLoc;
+    /** The `artifact.file(...)` / `artifact.chart(...)` call. */
+    call: ts.CallExpression;
+    /** The artifact id — set only when the first argument is a string literal without holes. */
+    artifactId?: string;
+    /**
+     * The id argument, if present. Kept raw so the diagnostics pass can position a rejection
+     * on the offending expression.
+     */
+    artifactIdExpr: ts.Expression | undefined;
+}
+/**
+ * A `phase("…")` marker call. The one collected facade call that is **not a site**: no id,
+ * no journal row — lowering rewrites it to `__host.enterPhase(name)`, which only makes the
+ * engine emit a `phase-entered` event.
+ * It is collected so the ordering walk can read the author's grouping, the diagnostics pass
+ * can point at a malformed marker, and lowering can find the call by node identity.
+ *
+ * It therefore consumes **neither the global `order` sequence nor any per-kind counter**:
+ * adding markers to a script must not move a single `ask#N` / `report#N` id, nor the
+ * serialization interleaving. That is stronger than what `report` needed (which shifts
+ * `order` only) and it costs nothing here, because a marker has no id to order.
+ */
+export interface PhaseMarkerSite {
+    /** The phase name — set only when the argument is a string literal without holes. */
+    name?: string;
+    loc: ScriptLoc;
+    /** The `phase(...)` call. */
+    call: ts.CallExpression;
+    /**
+     * The name argument, if present. Kept raw so the diagnostics pass can position a
+     * rejection on the offending expression rather than on the call.
+     */
+    nameExpr: ts.Expression | undefined;
+}
+export interface WorldReadSite {
+    id: string;
+    order: number;
+    /**
+     * Boundary A's op, resolved from the world-read registry by the DECLARING CONTAINER
+     * (`files`×`glob` → `"glob"`), never from the bare member name. Not the member name:
+     * `git.log` maps to `"git-log"`.
+     */
+    op: WorldReadOp;
+    label: string;
+    loc: ScriptLoc;
+    /** The `files.glob(...)` / `files.read(...)` call. */
+    call: ts.CallExpression;
+    /**
+     * The call's arguments in source order (`files.glob(p)` → `[p]`). Positional, and
+     * plural because ops differ in arity (`files.grep(pattern, glob?)`, `git.status()`);
+     * the taint pass treats every one as a sink.
+     */
+    args: readonly ts.Expression[];
+}
+export interface JoinSite {
+    id: string;
+    order: number;
+    method: "all" | "allSettled";
+    label: string;
+    loc: ScriptLoc;
+    /** The `Promise.all(...)` / `Promise.allSettled(...)` call. */
+    call: ts.CallExpression;
+    /** The single argument expression (the iterable); ports come from array literals. */
+    arg: ts.Expression | undefined;
+}
+/**
+ * A fan-out candidate — NOT a graph node yet. The taint pass promotes one to a
+ * `fan-out` node iff its body reaches a facade site. Two shapes: a per-element callback
+ * call per the callback registry (`xs.map(fn)`, `Array.from(xs, fn)`, … — the callback may
+ * be an inline literal OR any expression holding a script function), or a `for...of`.
+ */
+export interface IterationCandidate {
+    order: number;
+    form: "array-method" | "for-of";
+    loc: ScriptLoc;
+    /** Registry label (`map`, `reduce`, `from`, …); undefined for `for...of`. */
+    method?: string;
+    /** The call (array-method form only) — the key both listeners look the candidate up by. */
+    call?: ts.CallExpression;
+    /** The registry entry that made this call a candidate (array-method form only). */
+    semantics?: CallbackSemantics;
+    /** The inline callback literal (array-method form, when the argument is one). */
+    callback?: ts.FunctionExpression | ts.ArrowFunction;
+    /**
+     * The callback argument when it is NOT a literal (`xs.map(review)`, `xs.map(this.f)`):
+     * the taint pass applies whatever script functions its value holds, per element.
+     */
+    callbackExpr?: ts.Expression;
+    /** The body values flow through: the callback body or the `for...of` statement body.
+     * For a non-literal callback this is the argument expression itself (no lexical body). */
+    body: ts.Node;
+    /** The element binding (array method: first callback parameter; `for...of`: the loop variable). */
+    element: ts.BindingName | undefined;
+    /** The iterated expression: the array-method receiver, or the `for...of` right-hand side. */
+    iterated: ts.Expression;
+}
+/**
+ * A `hole<T>(name, prompt?, body?)` call site: a typed gap the main agent fills with code
+ * while the run waits at it (docs/dynamic-workflow/authoring.md「Holes」, docs/analysis.md
+ * 「Sites」). Its id is the key of its NAME (`hole#<hash>`, hole-id.ts), the same at any
+ * nesting depth, so every existing id stays unchanged when a fill inserts code; it consumes
+ * the global `order` like every other site. A hole whose name is not a literal (9012) falls
+ * back to a positional `hole#N`, which never reaches a run.
+ *
+ * 留白的函数体（`body`）在收集时以**全新的一套 per-kind 计数器**走查，体内铸出的 id 一律带
+ * `<holeId>/` 前缀（见 {@link SiteCounters}）；体内的 `return` 不是顶层 return——它从留白
+ * 返回。补全前后，体外的每个 id 逐字不变，这是活 run 能被补全的全部理由。
+ */
+export interface HoleSite {
+    id: string;
+    /** 包着这个留白的那个（已补全的）留白的 id；顶层留白没有。嵌套关系只记在这里，不在 id 里。 */
+    fill?: string;
+    order: number;
+    /** 留白名（也是它的阶段名）——只在首参是无洞字面量时设置。 */
+    name?: string;
+    /** 名字实参原样保留：9012 的诊断按它定位。 */
+    nameExpr: ts.Expression | undefined;
+    /** 显式类型实参的源码文本（`hole<Plan>` 的 `Plan`）；缺席即 9012。 */
+    typeText?: string;
+    typeArg?: ts.TypeNode;
+    /** 给主代理的提示（第二实参，非函数体时）；taint 趟把它当 sink。 */
+    prompt?: ts.Expression;
+    /** 已补全的留白的函数体（最后一个实参的内联函数字面量）；开放的留白没有。 */
+    body?: ts.ArrowFunction | ts.FunctionExpression;
+    loc: ScriptLoc;
+    /** The `hole(...)` call. */
+    call: ts.CallExpression;
+    /** 调用是顶层 `return` 的（await 过的）操作数：脚本的结尾开着，run 的结果就是补全的返回值。 */
+    tail: boolean;
+}
+/** A `return` in the top-level script body (not inside a nested function). */
+export interface TopLevelReturn {
+    loc: ScriptLoc;
+    /** The returned expression, if any (`return;` has none). Read as the sink. */
+    expression: ts.Expression | undefined;
+}
+export interface SiteTable {
+    asks: AskSite[];
+    actors: ActorSite[];
+    worldReads: WorldReadSite[];
+    /** `report(...)` sites — sited but drawn in neither graph (see {@link ReportSite}). */
+    reports: ReportSite[];
+    /** `artifact.*(...)` sites — sited but drawn in neither graph (see {@link ArtifactSite}). */
+    artifacts: ArtifactSite[];
+    /** `phase("…")` markers — collected but NOT sited (see {@link PhaseMarkerSite}). */
+    phases: PhaseMarkerSite[];
+    joins: JoinSite[];
+    /** `hole<T>(...)` sites — open and filled, body sites included with prefixed ids (see {@link HoleSite}). */
+    holes: HoleSite[];
+    iterations: IterationCandidate[];
+    topLevelReturns: TopLevelReturn[];
+}
+/** Collect the site table by walking the wrapped script's `__workflowScript__` body. */
+export declare function collectSites(workflow: WorkflowProgram): SiteTable;
+/**
+ * The authored script body: the wrapper function's block. Exported for the causality
+ * pass, which walks the same body in evaluation order. Read-only — it collects nothing
+ * into the site table, so site ids stay bit-for-bit identical.
+ */
+export declare function findWorkflowBody(scriptFile: ts.SourceFile): ts.Block;
+/** True iff the node introduces its own function scope (a body that runs only when called). */
+export declare function isFunctionLike(node: ts.Node): boolean;
+//# sourceMappingURL=sites.d.ts.map

package/vendor/dynamic-workflow/analysis/sites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites.d.ts","sourceRoot":"","sources":["../../src/analysis/sites.ts"],"names":[],"mappings":"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"}