@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.2

package/vendor/dynamic-workflow/lowering/lower.d.ts

@@ -0,0 +1,82 @@
+import { type CompileDiagnostic, type WorkflowProgram } from "../compiler/compile.js";
+import { type SiteTable } from "../analysis/sites.js";
+/**
+ * Lowering（instrumentation emit step）：把已 typecheck + analyze 干净的 workflow 脚本降级为沙箱可跑的
+ * **JavaScript**。两件事：
+ *
+ *   1. 剥离类型——程序已经 typecheck 过，这里是对同一份源码做 transpile 级别的类型擦除。
+ *   2. 用站点表里的**静态 site id** 给每个 facade 调用打桩，改写成 Boundary A 的 `__host.*`：
+ *        agent(name, persona)        -> __host.createActor("actor#2", name, persona)
+ *        planner.ask<Plan>(text)     -> __host.ask("ask#3", planner, text)
+ *        maybe?.ask<Plan>(text)      -> maybe === null || maybe === undefined
+ *                                         ? undefined : __host.ask("ask#3", maybe, text)
+ *                                       （可选链的短路保留：receiver 为 nullish 时跳过 ask、
+ *                                        实参不求值；非标识符 receiver 经临时变量求值一次）
+ *        files.glob(p) / files.read(p)
+ *                                    -> __host.worldRead("world-read#1", "glob", [p])
+ *                                       __host.worldRead("world-read#2", "read", [p])
+ *        report(x)                   -> __host.report("report#1", x)
+ *        report(x, "perf")           -> __host.report("report#1", x, "perf")
+ *        artifact.file(id, p, o)     -> __host.publishArtifact("artifact#1", "file", [id, p, o])
+ *        artifact.chart(id, spec)    -> __host.declareArtifact("artifact#2", "chart", [id, spec])
+ *        log(msg)                    -> __host.log(msg)
+ *        phase("gate")               -> __host.enterPhase("gate")（无站点；引擎只发一条事件）
+ *        model("GLM-5.3-Flash")      -> "GLM-5.3-Flash"（无站点、无 host 调用：ModelRef 运行期即名字）
+ *        channel<T>("facts")         -> __host.channel("facts")（无站点；队列在 cell 内构造）
+ *        future(async () => {...})   -> __host.future(async () => {...})（无站点；cell 立即调用）
+ *        hole<T>(n, p?, body?)       -> __host.hole("hole#1", n, p ?? void 0, (__src) => eval(__src), body?)
+ *                                       （lower-hole.ts；已补全的函数体另以文本形式进 holeBodies）
+ *      Join（Promise.all）与 fan-out 是沙箱内的普通 promise 机制，不是 host 调用，原样保留。
+ *
+ * ————————————————————————————————————————————————————————————————
+ * 输出契约（harness 契约，沙箱负责 wrap）：
+ * ————————————————————————————————————————————————————————————————
+ * {@link LoweredWorkflow.code} 是 lowered 脚本的 **async 函数体**：顶层 `await` 与末尾
+ * `return <artifact>` 都合法，因为 harness 会把它包进一个 async 函数里执行，形如
+ *
+ *     const __run = async (__host) => { <code> };
+ *
+ * 也就是说 code 里唯一的自由标识符是 `__host`（见 {@link HOST_BINDING}）——facade 的
+ * `agent` / `log` / `files` / `phase` 都已改写掉，沙箱 vm 的 globals
+ * 只需提供 ES intrinsics 加一个 `__host` 即可。
+ * schema 从不跨沙箱边界：引擎按 site id 从编译产物里查 schema，code 里不含任何 schema。
+ *
+ * {@link LoweredWorkflow.siteIds} 是被打桩的全部 facade site id，按源码顺序排列（asks /
+ * actors / world-reads / reports / artifacts；`log`/`phase` 不占 site id，故不在其中）——供
+ * harness 与测试断言"每个 site id 恰好出现一次"。
+ *
+ * 确定性：printer + transpile 都是纯函数，同一份输入 → 逐字节相同的输出。
+ */
+/** harness 必须为 lowered code 绑定的自由标识符（Boundary A 的 host 句柄）。 */
+export declare const HOST_BINDING = "__host";
+/** lowering 的产物：sandbox 输入的 JS 体 + 打桩到的 site id 清单。 */
+export interface LoweredWorkflow {
+    /** lowered 脚本的 async 函数体（顶层 await / 末尾 return 合法；自由标识符仅 `__host`）。 */
+    code: string;
+    /** 被打桩的 facade site id，按源码顺序（不含 log，它无 site id；留白与其函数体内的站点在内）。 */
+    siteIds: string[];
+    /**
+     * 每个**已补全**留白的函数体文本 `(async () => {\n…\n})`，按站点 id：与主体同一趟 transform
+     * 打印、同一套参数擦除（execution-engine.md「The text that runs」）。开放的留白不在其中。
+     */
+    holeBodies: Record<string, string>;
+}
+/** {@link lowerWorkflowScript} 的结果：与 analyze 同构——脏脚本不降级，`lowered` 仅在 `ok` 时给出。 */
+export interface LowerResult {
+    diagnostics: CompileDiagnostic[];
+    ok: boolean;
+    lowered?: LoweredWorkflow;
+}
+/**
+ * 便捷入口：编译 + facade-siting 校验 + 收集站点表 + 降级，与 `analyzeWorkflowScript` 同构。
+ * 脏脚本（typecheck 或 facade-siting 报错）不降级——降级只在干净程序上运行。
+ */
+export declare function lowerWorkflowScript(scriptText: string): LowerResult;
+/**
+ * 核心：把一个已分析干净的 workflow 降级为 {@link LoweredWorkflow}。
+ * 站点调用（ask/actor/world-read）一律按 **ts.Node 身份**（站点表持有的 raw call 引用）匹配，
+ * 绝不按名字/形状重新识别——那会制造第二份真相。`log` 不入站点表，按 checker 的
+ * 签名解析（解析进 facade .d.ts，与 sites.ts 同一机制）识别，属于身份判定而非名字启发。
+ */
+export declare function lowerWorkflow(workflow: WorkflowProgram, table: SiteTable): LoweredWorkflow;
+//# sourceMappingURL=lower.d.ts.map

package/vendor/dynamic-workflow/lowering/lower.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lower.d.ts","sourceRoot":"","sources":["../../src/lowering/lower.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,YAAY,WAAW,CAAC;AASrC,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAcD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAenE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,GAAG,eAAe,CAsL1F"}

package/vendor/dynamic-workflow/lowering/lower.js

@@ -0,0 +1,333 @@
+import ts from "typescript";
+import { collectDiagnostics, createWorkflowProgram, WORKFLOW_FUNCTION_NAME, } from "../compiler/compile.js";
+import { FACADE_FILE_NAME } from "../facade/dts.js";
+import { isArtifactPresetOp } from "../facade/registry.js";
+import { collectFacadeMisuse } from "../analysis/facade-misuse.js";
+import { collectSites, isFacadeDeclared, resolveSymbol, } from "../analysis/sites.js";
+import { collectHoleDiagnostics } from "../analysis/hole-sites.js";
+import { lowerHoleCall, printHoleBodies, TRANSPILE_OPTIONS } from "./lower-hole.js";
+/**
+ * Lowering（instrumentation emit step）：把已 typecheck + analyze 干净的 workflow 脚本降级为沙箱可跑的
+ * **JavaScript**。两件事：
+ *
+ *   1. 剥离类型——程序已经 typecheck 过，这里是对同一份源码做 transpile 级别的类型擦除。
+ *   2. 用站点表里的**静态 site id** 给每个 facade 调用打桩，改写成 Boundary A 的 `__host.*`：
+ *        agent(name, persona)        -> __host.createActor("actor#2", name, persona)
+ *        planner.ask<Plan>(text)     -> __host.ask("ask#3", planner, text)
+ *        maybe?.ask<Plan>(text)      -> maybe === null || maybe === undefined
+ *                                         ? undefined : __host.ask("ask#3", maybe, text)
+ *                                       （可选链的短路保留：receiver 为 nullish 时跳过 ask、
+ *                                        实参不求值；非标识符 receiver 经临时变量求值一次）
+ *        files.glob(p) / files.read(p)
+ *                                    -> __host.worldRead("world-read#1", "glob", [p])
+ *                                       __host.worldRead("world-read#2", "read", [p])
+ *        report(x)                   -> __host.report("report#1", x)
+ *        report(x, "perf")           -> __host.report("report#1", x, "perf")
+ *        artifact.file(id, p, o)     -> __host.publishArtifact("artifact#1", "file", [id, p, o])
+ *        artifact.chart(id, spec)    -> __host.declareArtifact("artifact#2", "chart", [id, spec])
+ *        log(msg)                    -> __host.log(msg)
+ *        phase("gate")               -> __host.enterPhase("gate")（无站点；引擎只发一条事件）
+ *        model("GLM-5.3-Flash")      -> "GLM-5.3-Flash"（无站点、无 host 调用：ModelRef 运行期即名字）
+ *        channel<T>("facts")         -> __host.channel("facts")（无站点；队列在 cell 内构造）
+ *        future(async () => {...})   -> __host.future(async () => {...})（无站点；cell 立即调用）
+ *        hole<T>(n, p?, body?)       -> __host.hole("hole#1", n, p ?? void 0, (__src) => eval(__src), body?)
+ *                                       （lower-hole.ts；已补全的函数体另以文本形式进 holeBodies）
+ *      Join（Promise.all）与 fan-out 是沙箱内的普通 promise 机制，不是 host 调用，原样保留。
+ *
+ * ————————————————————————————————————————————————————————————————
+ * 输出契约（harness 契约，沙箱负责 wrap）：
+ * ————————————————————————————————————————————————————————————————
+ * {@link LoweredWorkflow.code} 是 lowered 脚本的 **async 函数体**：顶层 `await` 与末尾
+ * `return <artifact>` 都合法，因为 harness 会把它包进一个 async 函数里执行，形如
+ *
+ *     const __run = async (__host) => { <code> };
+ *
+ * 也就是说 code 里唯一的自由标识符是 `__host`（见 {@link HOST_BINDING}）——facade 的
+ * `agent` / `log` / `files` / `phase` 都已改写掉，沙箱 vm 的 globals
+ * 只需提供 ES intrinsics 加一个 `__host` 即可。
+ * schema 从不跨沙箱边界：引擎按 site id 从编译产物里查 schema，code 里不含任何 schema。
+ *
+ * {@link LoweredWorkflow.siteIds} 是被打桩的全部 facade site id，按源码顺序排列（asks /
+ * actors / world-reads / reports / artifacts；`log`/`phase` 不占 site id，故不在其中）——供
+ * harness 与测试断言"每个 site id 恰好出现一次"。
+ *
+ * 确定性：printer + transpile 都是纯函数，同一份输入 → 逐字节相同的输出。
+ */
+/** harness 必须为 lowered code 绑定的自由标识符（Boundary A 的 host 句柄）。 */
+export const HOST_BINDING = "__host";
+/**
+ * 无站点、按名字原样透传到 `__host.<name>(...)` 的顶层 facade 函数：`log`（进度叙事）、
+ * `channel` / `future`（沙箱内的流水线原语，docs/dynamic-workflow/authoring.md「Streams」）。
+ * 它们都没有 journal 键，所以不进站点表；身份仍按 checker 解析到 facade 声明判定。
+ */
+const HOST_PASSTHROUGH_FUNCTIONS = new Set(["log", "channel", "future"]);
+/**
+ * 便捷入口：编译 + facade-siting 校验 + 收集站点表 + 降级，与 `analyzeWorkflowScript` 同构。
+ * 脏脚本（typecheck 或 facade-siting 报错）不降级——降级只在干净程序上运行。
+ */
+export function lowerWorkflowScript(scriptText) {
+    const workflow = createWorkflowProgram(scriptText);
+    const diagnostics = collectDiagnostics(workflow.program);
+    if (diagnostics.length > 0)
+        return { diagnostics, ok: false };
+    const table = collectSites(workflow);
+    // 留白规则（9012）与 facade-siting 同席：一个没等值、或落在 fan-out 里的留白降级出去就是
+    // 运行期的错，与 analyzeWorkflowScript 同一道门。
+    const misuse = [
+        ...collectFacadeMisuse(workflow, table),
+        ...collectHoleDiagnostics(workflow, table),
+    ];
+    if (misuse.length > 0)
+        return { diagnostics: misuse, ok: false };
+    return { diagnostics, lowered: lowerWorkflow(workflow, table), ok: true };
+}
+/**
+ * 核心：把一个已分析干净的 workflow 降级为 {@link LoweredWorkflow}。
+ * 站点调用（ask/actor/world-read）一律按 **ts.Node 身份**（站点表持有的 raw call 引用）匹配，
+ * 绝不按名字/形状重新识别——那会制造第二份真相。`log` 不入站点表，按 checker 的
+ * 签名解析（解析进 facade .d.ts，与 sites.ts 同一机制）识别，属于身份判定而非名字启发。
+ */
+export function lowerWorkflow(workflow, table) {
+    const checker = workflow.program.getTypeChecker();
+    const siteMap = buildSiteMap(table);
+    // 已补全留白的函数体（改写后的节点），transform 结束后打印成 holeBodies。
+    const holeBodyNodes = new Map();
+    // 第一趟：instrumentation。在同一份 scriptFile（站点表引用的正是它的节点）上做 transform，
+    // 从而能按节点身份命中站点表；此时类型尚未擦除。
+    const transformer = (context) => {
+        const { factory } = context;
+        const hostMember = (name) => factory.createPropertyAccessExpression(factory.createIdentifier(HOST_BINDING), name);
+        const siteArg = (id) => factory.createStringLiteral(id);
+        const visit = (node) => {
+            // `args` 是 facade 里唯一一个**值**而不是可调用物，所以它是唯一走标识符级改写的
+            // 符号：读它不是一个等待点，没有站点、不进因果图。判定按 checker 解析结果（与站点
+            // 身份同一机制），所以脚本自己声明的局部 `args` 解析到脚本文件的符号，原样保留。
+            //
+            // 刻意**不**改用「在包装函数体里注入 `const args = ...`」：用户脚本里再声明一个
+            // `args` 会变成重复声明的运行期 SyntaxError，而编译期完全看不出来。
+            if (ts.isIdentifier(node) && node.text === "args" && isFacadeArgsRead(node, checker)) {
+                return hostMember("args");
+            }
+            if (ts.isCallExpression(node)) {
+                const emit = siteMap.get(node);
+                if (emit !== undefined)
+                    return lowerSited(node, emit);
+                // 非站点的 facade 调用：log、channel、future（agent/ask/glob/read 必定成站点、已在 siteMap）。
+                // 三者同规：按 checker 解析到 facade 声明的名字识别，改写成同名的 `__host.*`，丢弃类型
+                // 实参（`channel<Fact>(...)`），实参原样递进。channel / future 是沙箱内的纯 promise 机制
+                // （docs/dynamic-workflow/authoring.md「Streams」），不过线、无 journal 行，所以不需要站点 id。
+                const name = facadeCalleeName(node, checker);
+                // model("x") -> "x"：`ModelRef` 只活在类型系统里，运行期它就是名字字符串本身
+                // （docs/dynamic-workflow/authoring.md「Choosing a model per subagent」），宿主按这个
+                // 字符串查 launch 时解析好的绑定表。无站点、不过 host；实参缺席（9010 先挡）退回 `void 0`。
+                if (name === "model") {
+                    const arg = node.arguments[0];
+                    return arg === undefined ? factory.createVoidZero() : visitExpr(arg);
+                }
+                if (name !== undefined && HOST_PASSTHROUGH_FUNCTIONS.has(name)) {
+                    return factory.createCallExpression(hostMember(name), undefined, node.arguments.map(visitExpr));
+                }
+            }
+            return ts.visitEachChild(node, visit, context);
+        };
+        const visitExpr = (expr) => ts.visitNode(expr, visit);
+        const lowerSited = (call, emit) => {
+            if (emit.kind === "phase") {
+                // phase("gate") -> __host.enterPhase("gate")。标记仍然**无站点、无 journal 行**——它不是一步工作；但控制流经过
+                // 它这件事要让引擎看见（一条 `phase-entered` 事件），否则一个没有节点的阶段在时间线
+                // 上永远是空圈。名字去两端空白，与分析器铸造阶段 id 的键同一；名字缺席（非字面量，
+                // 9004 诊断本该先拦下）退回 `void 0`——沙箱里绝不能残留自由标识符 `phase`。
+                const name = emit.name?.trim();
+                if (name === undefined || name.length === 0)
+                    return factory.createVoidZero();
+                return factory.createCallExpression(hostMember("enterPhase"), undefined, [
+                    factory.createStringLiteral(name),
+                ]);
+            }
+            if (emit.kind === "hole") {
+                return lowerHoleCall(call, emit.site, factory, hostMember, siteArg, visitExpr, holeBodyNodes);
+            }
+            if (emit.kind === "actor") {
+                // agent(name?, persona?) -> __host.createActor(siteId, name?, persona?)
+                return factory.createCallExpression(hostMember("createActor"), undefined, [
+                    siteArg(emit.siteId),
+                    ...call.arguments.map(visitExpr),
+                ]);
+            }
+            if (emit.kind === "ask") {
+                // receiver.ask<T>(instr) -> __host.ask(siteId, receiver, instr)（丢弃类型实参 <T>）。
+                // facade-siting 保证 ask 一定是 `receiver.ask(...)` 直接调用，故 callee 必为属性访问。
+                const access = call.expression;
+                const receiver = visitExpr(access.expression);
+                const loweredAsk = (recv) => factory.createCallExpression(hostMember("ask"), undefined, [
+                    siteArg(emit.siteId),
+                    recv,
+                    ...call.arguments.map(visitExpr),
+                ]);
+                if (!ts.isOptionalChain(call))
+                    return loweredAsk(receiver);
+                // 可选链上的 ask（`p?.ask(x)`、`wrap?.p.ask(x)`）不能被无条件改写成
+                // `__host.ask(siteId, <receiver>, x)`——`?.` 的短路被丢弃。receiver 为 nullish 时
+                // 作者程序的语义是「跳过这次 ask，整条链结果 undefined」，而降级产物带着 undefined
+                // 调进引擎，被判 UnknownActor **失败整个 run**——且只在可选分支真为空时发作，
+                // 可能烧掉一整段长跑之后才炸。改写为 nullish 守卫三目：守卫命中时实参不求值，
+                // 与可选链原语义一致；标识符 receiver 直接复读（无副作用），其余表达式经 hoisted
+                // 临时变量恰好求值一次——与 tsc 自身降级可选链的做法同构。
+                const once = ts.isIdentifier(receiver)
+                    ? receiver
+                    : factory.createTempVariable(context.hoistVariableDeclaration);
+                const evaluated = once === receiver ? receiver : factory.createAssignment(once, receiver);
+                const isNullish = factory.createBinaryExpression(factory.createBinaryExpression(evaluated, factory.createToken(ts.SyntaxKind.EqualsEqualsEqualsToken), factory.createNull()), factory.createToken(ts.SyntaxKind.BarBarToken), factory.createBinaryExpression(once, factory.createToken(ts.SyntaxKind.EqualsEqualsEqualsToken), factory.createIdentifier("undefined")));
+                return factory.createConditionalExpression(isNullish, factory.createToken(ts.SyntaxKind.QuestionToken), factory.createIdentifier("undefined"), factory.createToken(ts.SyntaxKind.ColonToken), loweredAsk(once));
+            }
+            if (emit.kind === "artifact") {
+                // artifact.file(id, path, opts)  -> __host.publishArtifact(siteId, "file", [id, path, opts])
+                // artifact.chart(id, spec)       -> __host.declareArtifact(siteId, "chart", [id, spec])
+                // 两族**同形不同名**：名字不同是因为两条路的返回类型不同（promise vs void），而
+                // 引擎按方法名而不是按 op 分派——一个把声明当成效应去 await 的脚本，应该在类型层
+                // 就被挡住，而不是在运行期拿到一个 undefined。实参与 world-read 同规：原样按位置
+                // 打包进数组，lowering 不看 op、不校验元数（校验归引擎与 driver）。
+                const member = isArtifactPresetOp(emit.op) ? "declareArtifact" : "publishArtifact";
+                return factory.createCallExpression(hostMember(member), undefined, [
+                    siteArg(emit.siteId),
+                    factory.createStringLiteral(emit.op),
+                    factory.createArrayLiteralExpression(call.arguments.map(visitExpr)),
+                ]);
+            }
+            if (emit.kind === "report") {
+                // report(item, artifactId?) -> __host.report(siteId, item, artifactId?)
+                // report 走**站点映射**而不是下面那条按 checker 名字识别的 log 路径：它是
+                // 有站点的（journal 按 site × ordinal 去重 replay），而站点身份只在站点表里。
+                return factory.createCallExpression(hostMember("report"), undefined, [
+                    siteArg(emit.siteId),
+                    ...call.arguments.map(visitExpr),
+                ]);
+            }
+            // files.glob(arg)/files.read(arg) -> __host.worldRead(siteId, op, [arg])
+            // 实参**原样按位置**打包进数组字面量：lowering 不看 op、不看元数、不做任何校验。每个 op 的元数与实参校验归 driver，
+            // 所以加一个 world-read 原语在这一趟里是零改动。
+            return factory.createCallExpression(hostMember("worldRead"), undefined, [
+                siteArg(emit.siteId),
+                factory.createStringLiteral(emit.op),
+                factory.createArrayLiteralExpression(call.arguments.map(visitExpr)),
+            ]);
+        };
+        return (sourceFile) => ts.visitNode(sourceFile, visit);
+    };
+    const result = ts.transform(workflow.scriptFile, [transformer]);
+    const transformed = result.transformed[0];
+    if (transformed === undefined)
+        throw new Error("lowering: transform produced no source file");
+    // 只取 __workflowScript__ 的函数体语句（wrapper/facade/export 都不进 lowered code）。
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed, removeComments: false });
+    const instrumented = workflowBody(transformed)
+        .map((statement) => printer.printNode(ts.EmitHint.Unspecified, statement, transformed))
+        .join("\n");
+    const holeBodies = printHoleBodies(holeBodyNodes, printer, transformed);
+    result.dispose();
+    // 第二趟：类型擦除。此时打桩已完成、不再需要节点身份，故对文本做 transpile-级擦除即可。
+    const code = ts.transpileModule(instrumented, {
+        compilerOptions: TRANSPILE_OPTIONS,
+        reportDiagnostics: false,
+    }).outputText;
+    return { code, holeBodies, siteIds: sourceOrderSiteIds(table) };
+}
+/**
+ * 站点表的四类站点调用 + phase 标记，建成 `ts.CallExpression -> SiteEmit` 映射
+ * （按节点身份匹配）。phase 走这张表是为了拿到节点身份与名字——它没有 site id，因此
+ * 也不进 {@link sourceOrderSiteIds}。
+ */
+function buildSiteMap(table) {
+    const map = new Map();
+    for (const site of table.actors)
+        map.set(site.call, { kind: "actor", siteId: site.id });
+    for (const site of table.artifacts) {
+        map.set(site.call, { kind: "artifact", op: site.op, siteId: site.id });
+    }
+    for (const site of table.asks)
+        map.set(site.call, { kind: "ask", siteId: site.id });
+    for (const site of table.holes)
+        map.set(site.call, { kind: "hole", site });
+    for (const marker of table.phases)
+        map.set(marker.call, { kind: "phase", name: marker.name });
+    for (const site of table.reports)
+        map.set(site.call, { kind: "report", siteId: site.id });
+    for (const site of table.worldReads) {
+        map.set(site.call, { kind: "world-read", op: site.op, siteId: site.id });
+    }
+    return map;
+}
+/** 被打桩的 site id，按源码顺序（站点表的全局 `order` 发现序）。 */
+function sourceOrderSiteIds(table) {
+    const sited = [
+        ...table.actors,
+        ...table.artifacts,
+        ...table.asks,
+        ...table.holes,
+        ...table.reports,
+        ...table.worldReads,
+    ];
+    return sited.sort((a, b) => a.order - b.order).map((site) => site.id);
+}
+/** 定位 transform 后的 __workflowScript__ 函数体语句（与 sites.ts 的 findWorkflowBody 同形）。 */
+function workflowBody(sourceFile) {
+    for (const statement of sourceFile.statements) {
+        if (ts.isFunctionDeclaration(statement) &&
+            statement.name?.text === WORKFLOW_FUNCTION_NAME &&
+            statement.body !== undefined) {
+            return statement.body.statements;
+        }
+    }
+    throw new Error(`lowering: ${WORKFLOW_FUNCTION_NAME} not found in transformed source`);
+}
+/**
+ * 调用解析到的 facade callable 名字（走 resolved signature 的声明，落在 facade .d.ts 内），
+ * 否则 undefined。与 sites.ts 的私有 facadeCalleeName 同一思路——按签名声明的身份判定，
+ * 而非 callee 表达式的拼写，故计算成员访问（`files["read"](x)`）也能解析到 facade 方法。
+ * 本模块只用它认 log：站点类 facade 调用已先在 siteMap 命中并返回，不会走到这里。
+ */
+/**
+ * True iff this `args` identifier is a READ of the facade global (not a shadowing local,
+ * not a property name, not a declaration site).
+ *
+ * Identity comes from the checker, exactly as facade call sites do: a script that writes
+ * its own `const args = ...` resolves to a symbol declared in the script file, so it is
+ * left alone and keeps shadowing benignly. The syntactic guards below are for positions
+ * where an identifier is not a value read at all — `x.args`, `{ args: 1 }`, and the name
+ * in `const args = ...` — where rewriting would produce nonsense like `{ __host.args: 1 }`.
+ */
+function isFacadeArgsRead(node, checker) {
+    const parent = node.parent;
+    if (parent !== undefined) {
+        if (ts.isPropertyAccessExpression(parent) && parent.name === node)
+            return false;
+        if (ts.isQualifiedName(parent) && parent.right === node)
+            return false;
+        if ((ts.isPropertyAssignment(parent) || ts.isPropertySignature(parent)) &&
+            parent.name === node) {
+            return false;
+        }
+        if (ts.isShorthandPropertyAssignment(parent) && parent.name === node)
+            return false;
+        if (ts.isBindingElement(parent) && parent.propertyName === node)
+            return false;
+        // 声明位（`const args = ...`、参数名、import 名）：那是在**建**一个绑定，不是读 facade。
+        if ((ts.isVariableDeclaration(parent) ||
+            ts.isParameter(parent) ||
+            ts.isBindingElement(parent) ||
+            ts.isFunctionDeclaration(parent) ||
+            ts.isClassDeclaration(parent)) &&
+            parent.name === node) {
+            return false;
+        }
+    }
+    return isFacadeDeclared(resolveSymbol(node, checker));
+}
+function facadeCalleeName(call, checker) {
+    const declaration = checker.getResolvedSignature(call)?.declaration;
+    if (declaration === undefined || declaration.getSourceFile().fileName !== FACADE_FILE_NAME) {
+        return undefined;
+    }
+    const name = declaration.name;
+    return name !== undefined && ts.isIdentifier(name) ? name.text : undefined;
+}

package/vendor/dynamic-workflow/projections.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 浏览器安全的纯投影桶：
+ * `@zcode/dynamic-workflow/projections`。
+ *
+ * 下游浏览器端消费者把 `AnalysisCore` 冻结成 core.json，在浏览器里解码后现场重算站点图 / 因果图 /
+ * CFG / 交接图 / actor 图，再用 `*ToMermaid` 或 display 契约画出来。那条链上不能有
+ * `typescript`——它是分析器铸造 core 时才需要的编译器，几 MB 大，也不该进前端包。
+ *
+ * 因此这里**只**再导出运行时不 import `typescript` 的模块：core 的类型与规范文本、JSON
+ * 编解码、五个投影、归约器、mermaid 与文本序列化器、图类型。`analyzeWorkflowScript`、
+ * 编译器、lowering、引擎一概不在——它们走根导出。
+ */
+export { isActorSite, serializeCore, type AnalysisCore, type CoreActorSite, type CoreAskSite, type CoreFacts, type CoreFanoutSite, type CoreHoleSite, type CoreSimpleSite, type CoreSites, type CoreTypes, } from "./analysis/core.js";
+export { decodeAnalysisCore, encodeAnalysisCore, type AnalysisCoreJson, type MapEntries, } from "./analysis/core-json.js";
+export type { ActorEvent, ControlFact, IssueEvent, JumpEvent, MarkEvent, OrderEvent, OrderRegion, OrderTrace, PhaseInfo, SettleEvent, } from "./analysis/causality-order.js";
+export { isStructuralRegionKind, UNPHASED_ID, type JumpKind, type RegionKind, type StructuralRegionKind, type TraceRegionKind, } from "./analysis/constants.js";
+export { projectSiteGraph } from "./analysis/graph.js";
+export { toActorGraph, type ActorEdge, type ActorGraph, type ActorNode } from "./analysis/actor-graph.js";
+export { MAIN_LANE, projectCausalityGraph, SINK_ID, UNKNOWN_LANE, WORKSPACE_LANE, type CausalityGraph, type Certainty, type Lane, type NamePattern, type OrderEdge, type OrderKind, type Phase, type Region, type Step, type StepKind, } from "./analysis/causality-graph.js";
+export { reduceOrdering, type ReducibleEdge } from "./analysis/causality-reduce.js";
+export { FLOW_ABORT, FLOW_ENTRY, FLOW_SINK, projectControlFlow, type ControlFlowGraph, type FlowEdge, type FlowEdgeKind, type FlowHole, type FlowNode, type FlowNodeKind, type FlowPhase, type FlowVia, } from "./analysis/flow-graph.js";
+export { FANOUT_EXPAND_CAP, projectHandoffGraph, UNPHASED, type Handoff, type HandoffGraph, type HandoffParticipant, } from "./analysis/handoff-graph.js";
+export { actorGraphToMermaid, causalityGraphToMermaid, controlFlowToMermaid, handoffGraphToMermaid, phaseFlowToMermaid, phaseGraphToMermaid, siteGraphToMermaid, } from "./analysis/mermaid.js";
+export { serializeActorGraph, serializeCausalityGraph, serializeControlFlow, serializeGraph, serializeHandoffGraph, } from "./analysis/serialize.js";
+export type { ActorSite, SiteEdge, SiteGraph, SiteKind, SiteLoc, SiteNode } from "./analysis/types.js";
+//# sourceMappingURL=projections.d.ts.map

package/vendor/dynamic-workflow/projections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projections.d.ts","sourceRoot":"","sources":["../src/projections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,WAAW,EACX,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,SAAS,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,UAAU,GAChB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,WAAW,EACX,UAAU,EACV,SAAS,EACT,WAAW,GACZ,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,sBAAsB,EACtB,WAAW,EACX,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC1G,OAAO,EACL,SAAS,EACT,qBAAqB,EACrB,OAAO,EACP,YAAY,EACZ,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,IAAI,EACT,KAAK,QAAQ,GACd,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpF,OAAO,EACL,UAAU,EACV,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,OAAO,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,QAAQ,EACR,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,cAAc,EACd,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}

package/vendor/dynamic-workflow/projections.js

@@ -0,0 +1,23 @@
+/**
+ * 浏览器安全的纯投影桶：
+ * `@zcode/dynamic-workflow/projections`。
+ *
+ * 下游浏览器端消费者把 `AnalysisCore` 冻结成 core.json，在浏览器里解码后现场重算站点图 / 因果图 /
+ * CFG / 交接图 / actor 图，再用 `*ToMermaid` 或 display 契约画出来。那条链上不能有
+ * `typescript`——它是分析器铸造 core 时才需要的编译器，几 MB 大，也不该进前端包。
+ *
+ * 因此这里**只**再导出运行时不 import `typescript` 的模块：core 的类型与规范文本、JSON
+ * 编解码、五个投影、归约器、mermaid 与文本序列化器、图类型。`analyzeWorkflowScript`、
+ * 编译器、lowering、引擎一概不在——它们走根导出。
+ */
+export { isActorSite, serializeCore, } from "./analysis/core.js";
+export { decodeAnalysisCore, encodeAnalysisCore, } from "./analysis/core-json.js";
+export { isStructuralRegionKind, UNPHASED_ID, } from "./analysis/constants.js";
+export { projectSiteGraph } from "./analysis/graph.js";
+export { toActorGraph } from "./analysis/actor-graph.js";
+export { MAIN_LANE, projectCausalityGraph, SINK_ID, UNKNOWN_LANE, WORKSPACE_LANE, } from "./analysis/causality-graph.js";
+export { reduceOrdering } from "./analysis/causality-reduce.js";
+export { FLOW_ABORT, FLOW_ENTRY, FLOW_SINK, projectControlFlow, } from "./analysis/flow-graph.js";
+export { FANOUT_EXPAND_CAP, projectHandoffGraph, UNPHASED, } from "./analysis/handoff-graph.js";
+export { actorGraphToMermaid, causalityGraphToMermaid, controlFlowToMermaid, handoffGraphToMermaid, phaseFlowToMermaid, phaseGraphToMermaid, siteGraphToMermaid, } from "./analysis/mermaid.js";
+export { serializeActorGraph, serializeCausalityGraph, serializeControlFlow, serializeGraph, serializeHandoffGraph, } from "./analysis/serialize.js";

package/vendor/dynamic-workflow/schema/actor-submit-profiles.d.ts

@@ -0,0 +1,49 @@
+import type { SiteGraph } from "../analysis/types.js";
+import type { SiteTable } from "../analysis/sites.js";
+import type { WorkflowProgram } from "../compiler/compile.js";
+import type { AskSpec } from "../engine/types.js";
+import type { JsonSchema } from "./types.js";
+/**
+ * 每个 actor 站点的 **submit profile**：决定该 actor 的子代理会话拿到哪一种 `submit_result` 工具。
+ *
+ * - `untyped`：能落到这个 actor 的 ask 全是 untyped（或它根本没有 ask）→ 不注册 submit_result。
+ * - `mono`：能落到这个 actor 的 typed ask 的 schema **全部相同**（规范 JSON 相等；untyped ask 可以
+ *   混在其中）→ 工具声明就是 `{ result: schema }`，对该 actor 冻结、跨 ask 不变，因此缓存中性。
+ * - `generic`：typed ask 的 schema 不止一种 → 今天的通用工具 + 每个 ask 的 schema 尾注。
+ *
+ * 为什么是编译期而不是运行期：工具块渲染在 prompt 最前面，一旦按 ask 换 schema 就打掉该 actor
+ * 的整个缓存前缀。只有「整个 actor 生命周期里 schema 不变」这件事
+ * 在编译期可判定时，typed 工具才是免费的；判定不了就退回 generic，行为逐字节保持等价。
+ */
+export type ActorSubmitProfile = {
+    kind: "untyped";
+} | {
+    kind: "mono";
+    schema: JsonSchema;
+} | {
+    kind: "generic";
+};
+/** 缺席 / 无法判定时的 profile：今天的行为。 */
+export declare const GENERIC_SUBMIT_PROFILE: ActorSubmitProfile;
+/**
+ * 由站点图与 ask 规格推导每个 actor 站点的 submit profile。纯函数。
+ *
+ * **可靠性规则**：ask→actor 的绑定取站点图上的 may-set（`SiteNode.actors`）。只要有**任何一个**
+ * ask 站点的 actor 集为空（receiver 没解析出来），分析就说不出那个 ask 会落到谁头上——于是
+ * **所有** actor 都记 `generic`。这是有意的保守：一个 typed ask 若落到一个 `untyped` 子代理上，
+ * 它没有工具可提交，只能耗尽 nudge 失败；宁可少省一点缓存，也不能凭一个不完整的图把工具拿掉。
+ * 同理，一个 ask 的 actor 集有多个成员（条件分支上的 receiver）时，它的 schema 计入每一个成员。
+ *
+ * askSpecs 缺少某个 ask 站点时同样整体退回 generic：站点表与规格出自同一次编译，缺席只可能是
+ * 接线错误，此处不猜（引擎侧对此以 MissingAskSpec 硬失败，这里只需不放大它）。
+ *
+ * 返回表覆盖 `graph.actors` 里的每一个 actor 站点。
+ */
+export declare function deriveActorSubmitProfiles(graph: SiteGraph, askSpecs: ReadonlyMap<string, AskSpec>): Map<string, ActorSubmitProfile>;
+/**
+ * 「编译一次」的便捷入口：在构建站点表与合成 schema 的**同一个** {@link WorkflowProgram} 上做解释
+ * 与站点图投影（analyzeWorkflowScript 跑的正是这两步），然后推导 profile。供 run 提交路径调用，
+ * 不必自己拼装 interpret + projectSiteGraph（两者不在包的公开面上）。
+ */
+export declare function deriveActorSubmitProfilesFor(workflow: WorkflowProgram, table: SiteTable, askSpecs: ReadonlyMap<string, AskSpec>): Map<string, ActorSubmitProfile>;
+//# sourceMappingURL=actor-submit-profiles.d.ts.map

package/vendor/dynamic-workflow/schema/actor-submit-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-submit-profiles.d.ts","sourceRoot":"","sources":["../../src/schema/actor-submit-profiles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,iCAAiC;AACjC,eAAO,MAAM,sBAAsB,EAAE,kBAAwC,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAsCjC;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAEjC"}

package/vendor/dynamic-workflow/schema/actor-submit-profiles.js

@@ -0,0 +1,69 @@
+import { interpret } from "../analysis/interpret.js";
+import { projectSiteGraph } from "../analysis/graph.js";
+import { canonicalJson } from "../engine/hash.js";
+/** 缺席 / 无法判定时的 profile：今天的行为。 */
+export const GENERIC_SUBMIT_PROFILE = { kind: "generic" };
+/**
+ * 由站点图与 ask 规格推导每个 actor 站点的 submit profile。纯函数。
+ *
+ * **可靠性规则**：ask→actor 的绑定取站点图上的 may-set（`SiteNode.actors`）。只要有**任何一个**
+ * ask 站点的 actor 集为空（receiver 没解析出来），分析就说不出那个 ask 会落到谁头上——于是
+ * **所有** actor 都记 `generic`。这是有意的保守：一个 typed ask 若落到一个 `untyped` 子代理上，
+ * 它没有工具可提交，只能耗尽 nudge 失败；宁可少省一点缓存，也不能凭一个不完整的图把工具拿掉。
+ * 同理，一个 ask 的 actor 集有多个成员（条件分支上的 receiver）时，它的 schema 计入每一个成员。
+ *
+ * askSpecs 缺少某个 ask 站点时同样整体退回 generic：站点表与规格出自同一次编译，缺席只可能是
+ * 接线错误，此处不猜（引擎侧对此以 MissingAskSpec 硬失败，这里只需不放大它）。
+ *
+ * 返回表覆盖 `graph.actors` 里的每一个 actor 站点。
+ */
+export function deriveActorSubmitProfiles(graph, askSpecs) {
+    const profiles = new Map();
+    const actorIds = graph.actors.map((actor) => actor.id);
+    // 每个 actor 收集到的 typed schema，按规范 JSON 去重（同一份 schema 对象在不同 ask 站点上各合成
+    // 一次，引用不同但内容相同，必须按内容比较）。
+    const schemasByActor = new Map();
+    for (const id of actorIds)
+        schemasByActor.set(id, new Map());
+    for (const node of graph.nodes) {
+        if (node.kind !== "ask")
+            continue;
+        const actors = node.actors ?? [];
+        const spec = askSpecs.get(node.id);
+        if (actors.length === 0 || spec === undefined) {
+            for (const id of actorIds)
+                profiles.set(id, GENERIC_SUBMIT_PROFILE);
+            return profiles;
+        }
+        if (!spec.typed)
+            continue;
+        const schema = spec.schema;
+        const key = canonicalJson(schema);
+        for (const actorId of actors) {
+            // 站点图里的 actor id 必然在 graph.actors 内；防御性地补一个桶，而不是静默跳过。
+            let bucket = schemasByActor.get(actorId);
+            if (bucket === undefined) {
+                bucket = new Map();
+                schemasByActor.set(actorId, bucket);
+            }
+            bucket.set(key, schema);
+        }
+    }
+    for (const [actorId, bucket] of schemasByActor) {
+        if (bucket.size === 0)
+            profiles.set(actorId, { kind: "untyped" });
+        else if (bucket.size === 1)
+            profiles.set(actorId, { kind: "mono", schema: [...bucket.values()][0] });
+        else
+            profiles.set(actorId, GENERIC_SUBMIT_PROFILE);
+    }
+    return profiles;
+}
+/**
+ * 「编译一次」的便捷入口：在构建站点表与合成 schema 的**同一个** {@link WorkflowProgram} 上做解释
+ * 与站点图投影（analyzeWorkflowScript 跑的正是这两步），然后推导 profile。供 run 提交路径调用，
+ * 不必自己拼装 interpret + projectSiteGraph（两者不在包的公开面上）。
+ */
+export function deriveActorSubmitProfilesFor(workflow, table, askSpecs) {
+    return deriveActorSubmitProfiles(projectSiteGraph(interpret(workflow, table)), askSpecs);
+}