@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.2

package/vendor/dynamic-workflow/analysis/actor-graph.d.ts

@@ -0,0 +1,47 @@
+import type { SiteGraph, SiteLoc } from "./types.js";
+/**
+ * The actor graph: a derived, presentation-level view of a {@link SiteGraph} with
+ * **actors as nodes and messages as edges**. It is a PURE projection of an
+ * already-built site graph (no program/table access); the site graph stays canonical
+ * (journal, ordinals, and runtime marks all key off sites) and this view is recovered
+ * on demand, the same category as SCC loop-box recovery. An agent-relevance filter
+ * keeps the view about collaboration: an edge must touch at least one actor, so
+ * endpoint-to-endpoint plumbing is dropped and endpoints left dangling are pruned.
+ * Aggregated actor edges also carry the deduped producer artifact types of their
+ * contributing site edges as `types` — the message types flowing between the lanes.
+ */
+/** A node: an actor lane, or one of the virtual endpoints `source` / `sink` / `workspace`. */
+export interface ActorNode {
+    /**
+     * An actor-site id (`actor#1`); `"source"` / `"sink"` — the orchestrator's enter
+     * and exit roles, kept unmerged so the graph reads as a pipeline; or `"workspace"`.
+     */
+    id: string;
+    name?: string;
+    loc?: SiteLoc;
+    /** Enclosing promoted fan-out id when the actor site is a lane family (×N). */
+    family?: string;
+}
+/** A message edge: aggregated site data-flow between two actor lanes. */
+export interface ActorEdge {
+    from: string;
+    to: string;
+    /** OR over the contributing site edges' exactness (a may-projection forces false). */
+    exact: boolean;
+    /** How many site data-edges collapsed into this actor edge. */
+    count: number;
+    /**
+     * The producer artifact types carried by the contributing site edges — the message
+     * types on this actor edge (provenance: values of these types flow `from` -> `to`).
+     * Deduped, in contribution order (site-edge iteration order). Present iff non-empty;
+     * contributing edges with no type (e.g. `source` edges) add nothing.
+     */
+    types?: string[];
+}
+export interface ActorGraph {
+    nodes: ActorNode[];
+    edges: ActorEdge[];
+}
+/** Project a site graph to its derived actor graph (pure). */
+export declare function toActorGraph(graph: SiteGraph): ActorGraph;
+//# sourceMappingURL=actor-graph.d.ts.map

package/vendor/dynamic-workflow/analysis/actor-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-graph.d.ts","sourceRoot":"","sources":["../../src/analysis/actor-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAY,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;GAUG;AAEH,8FAA8F;AAC9F,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,KAAK,EAAE,OAAO,CAAC;IACf,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAMD,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAwFzD"}

package/vendor/dynamic-workflow/analysis/actor-graph.js

@@ -0,0 +1,95 @@
+const SOURCE = "source";
+const SINK = "sink";
+const WORKSPACE = "workspace";
+/** Project a site graph to its derived actor graph (pure). */
+export function toActorGraph(graph) {
+    const kindOf = new Map(graph.nodes.map((node) => [node.id, node.kind]));
+    const actorsOf = new Map(graph.nodes.filter((node) => node.kind === "ask").map((node) => [node.id, node.actors ?? []]));
+    // The lane(s) a site projects onto. The virtual source/sink pass through UNMERGED
+    // (two roles of the orchestrator, kept apart so the graph reads as a pipeline
+    // rather than a hub with back-edges into its start); world-reads -> the single
+    // workspace node; asks -> their actor set (empty when unresolved); join/fan-out
+    // relays -> nothing (dropped: additive relay labels guarantee a direct
+    // producer -> consumer edge already exists, so no transitive composition is lost).
+    const project = (id) => {
+        if (id === SOURCE || id === SINK)
+            return [id];
+        const kind = kindOf.get(id);
+        if (kind === "world-read")
+            return [WORKSPACE];
+        if (kind === "ask")
+            return actorsOf.get(id) ?? [];
+        return [];
+    };
+    // Aggregate contributed edges by (from, to): count them, OR their exactness, and
+    // collect the deduped producer types in contribution order.
+    const agg = new Map();
+    const contribute = (from, to, exact, type) => {
+        const key = `${from}|${to}`;
+        const existing = agg.get(key);
+        if (existing === undefined) {
+            agg.set(key, { count: 1, exact, from, to, ...(type === undefined ? {} : { types: [type] }) });
+            return;
+        }
+        existing.count += 1;
+        existing.exact = existing.exact || exact;
+        if (type !== undefined) {
+            const types = (existing.types ??= []);
+            if (!types.includes(type))
+                types.push(type);
+        }
+    };
+    for (const edge of graph.edges) {
+        if (edge.kind !== "data")
+            continue; // context edges dissolve (same actor = same node)
+        // source -> world-read drops: the workspace is itself an origin, not fed by source.
+        if (edge.from === SOURCE && kindOf.get(edge.to) === "world-read")
+            continue;
+        const fromNodes = project(edge.from);
+        const toNodes = project(edge.to);
+        if (fromNodes.length === 0 || toNodes.length === 0)
+            continue; // a relay endpoint: drop
+        // A non-singleton (may) projection on either side forces every contributed edge
+        // inexact — the ask might run in any of its candidate lanes.
+        const exact = edge.exact && fromNodes.length === 1 && toNodes.length === 1;
+        for (const from of fromNodes)
+            for (const to of toNodes)
+                contribute(from, to, exact, edge.type);
+    }
+    // Agent-relevance filter: an actor edge must touch at least one actor, so
+    // endpoint-to-endpoint plumbing (e.g. `workspace -> sink`, a world read flowing
+    // untouched into the result) is dropped — honest in the site graph, noise in a
+    // collaboration view. We filter the aggregated set (one pass) rather than skipping
+    // at contribution, so the rule sits in one place next to the pruning it feeds.
+    const isEndpoint = (id) => id === SOURCE || id === SINK || id === WORKSPACE;
+    const kept = [...agg.values()].filter((edge) => !(isEndpoint(edge.from) && isEndpoint(edge.to)));
+    // Prune any endpoint node the filter (or the projection) leaves with no incident
+    // edge — a dangling source/workspace/sink bubble is as noisy as the edge was. Actor
+    // nodes always render, even edge-less.
+    const incident = new Set();
+    for (const edge of kept) {
+        incident.add(edge.from);
+        incident.add(edge.to);
+    }
+    // Node order: source first, workspace second, actors in site order (graph.actors is
+    // already source-ordered), sink LAST — so `flowchart LR` reads as a pipeline.
+    const nodes = [];
+    if (incident.has(SOURCE))
+        nodes.push({ id: SOURCE });
+    if (incident.has(WORKSPACE))
+        nodes.push({ id: WORKSPACE });
+    for (const actor of graph.actors) {
+        nodes.push({
+            id: actor.id,
+            loc: actor.loc,
+            ...(actor.name === undefined ? {} : { name: actor.name }),
+            ...(actor.within === undefined ? {} : { family: actor.within }),
+        });
+    }
+    if (incident.has(SINK))
+        nodes.push({ id: SINK });
+    const position = new Map(nodes.map((node, index) => [node.id, index]));
+    const rank = (id) => position.get(id) ?? Number.MAX_SAFE_INTEGER;
+    const edges = kept.sort((a, b) => rank(a.from) - rank(b.from) || rank(a.to) - rank(b.to));
+    return { edges, nodes };
+}

package/vendor/dynamic-workflow/analysis/actor-models.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 子代理模型的编译期规则（docs/dynamic-workflow/authoring.md「Choosing a model per subagent」；
+ * docs/analysis.md「Diagnostics」的 9010 行）。
+ *
+ * 规则只有一句：**一个脚本能交给子代理的模型名，在运行前就是一个封闭集合**。launch 工具据此在确认窗
+ * 之前把每个名字对着宿主的模型目录解析一遍（docs/dynamic-workflow/launch.md「Models the script
+ * names」），窗上显示的就是将要生效的模型，解不出来的名字作为 9011 退回、什么都不跑。
+ *
+ * 集合的两个来源：
+ *
+ * 1. `model("…")` 调用的实参——必须是非空的无洞字符串字面量（9010）。`ModelRef` 只能由它造出
+ *    （facade 里是私有构造器 + 私有成员的 class，`new` 与对象字面量都造不出来），所以任何类型为
+ *    `ModelRef` 的值都来自某一次 `model()`，名字已经在集合里。
+ * 2. 每个 `agent(name, persona)` 站点上 persona 的 `model` 属性的**类型**：必须是 `ModelRef`、
+ *    字符串字面量类型，或它们的联合（9010）。联合里的每个字面量成员都进集合。
+ *
+ * 为什么判**类型**而不是判语法上的字面量：`const FLASH = "…"`、`hard ? "a" : "b"`、`MODELS[k]`
+ * 这些写法运行期取哪个值不定，但取值集合 checker 已经算好了——按类型判，一条规则就同时覆盖
+ * 内联字面量、const 绑定和三目，而一个被拓宽成 `string` 的值（`let`、参数、带洞模板、先装进
+ * 变量的 persona 对象）恰好就是集合不封闭的那一类。
+ *
+ * 为什么内联的 persona 对象字面量要**按语法取 `model` 的初值表达式**再问它的类型，而不是问整个
+ * 对象的类型：对象字面量的属性类型在上下文类型不含字面量类型时会被拓宽（`{ model: "x" }` 在
+ * `AgentPersona` 的上下文里，属性类型是 `string`），按对象类型判会把最常见的写法误报掉。初值
+ * 表达式自己的类型不受这条拓宽影响。
+ *
+ * 与 actor-names.ts（9005/9006）不同，本诊断**没有运行期兜底**：下游没有第二处去查「一个子代理的
+ * model 可能是什么」。宿主在建会话时查不到绑定只会让那一次 ask 大声失败（只有类型断言能走到那
+ * 一步），而那已经是确认窗之后了。所以这里宁可多报，不可漏报。
+ *
+ * 顺带：`ModelRef` 在运行期不存在（lowering 把 `model("x")` 抹成 `"x"`，沙箱里没有这个 class），
+ * 所以脚本在**值位置**引用 `ModelRef`（`x instanceof ModelRef`）也在这里以 9010 报出，
+ * 而不是留成一个运行期 ReferenceError。
+ */
+import type { CompileDiagnostic, WorkflowProgram } from "../compiler/compile.js";
+import { type SiteTable } from "./sites.js";
+/** 模型名不封闭（persona 的 `model` 类型、`model()` 的实参、值位置的 `ModelRef`）。 */
+export declare const MODEL_REFERENCE_CODE = 9010;
+/**
+ * 脚本里的模型名在宿主的模型目录里解析不出来（没有、歧义、被停用、档位不对）。**不是**本包产出的
+ * 诊断——编译器不知道宿主配了哪些模型——而是 launch 工具（packages/core）在 `resolveInput` 之后
+ * 按 {@link ModelReference} 的位置报出来的；码放在这里，好让两处共用一个数、诊断表只有一份。
+ */
+export declare const MODEL_UNRESOLVED_CODE = 9011;
+/** 脚本能交给子代理的一个模型名，及它在脚本里出现的一处位置。 */
+export interface ModelReference {
+    /** 名字，**逐字**如脚本所写：运行期 persona 里带的就是这个串，launch 的绑定表以它为键。 */
+    name: string;
+    line: number;
+    column: number;
+}
+export interface ActorModels {
+    /** 每处出现一条，按发现顺序（`model()` 调用在前，其后是各 `agent()` 站点）。 */
+    references: ModelReference[];
+    /** 9010；非空即脚本不可提交。 */
+    diagnostics: CompileDiagnostic[];
+}
+/** 收集模型名集合与 9010 诊断。只在编译干净的程序上调用。 */
+export declare function collectActorModels(workflow: WorkflowProgram, table: SiteTable): ActorModels;
+//# sourceMappingURL=actor-models.d.ts.map

package/vendor/dynamic-workflow/analysis/actor-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-models.d.ts","sourceRoot":"","sources":["../../src/analysis/actor-models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAa,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE5F,OAAO,EAAmC,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE7E,kEAAkE;AAClE,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,sBAAsB;IACtB,WAAW,EAAE,iBAAiB,EAAE,CAAC;CAClC;AAmBD,qCAAqC;AACrC,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,GAAG,WAAW,CA4F3F"}

package/vendor/dynamic-workflow/analysis/actor-models.js

@@ -0,0 +1,208 @@
+/**
+ * 子代理模型的编译期规则（docs/dynamic-workflow/authoring.md「Choosing a model per subagent」；
+ * docs/analysis.md「Diagnostics」的 9010 行）。
+ *
+ * 规则只有一句：**一个脚本能交给子代理的模型名，在运行前就是一个封闭集合**。launch 工具据此在确认窗
+ * 之前把每个名字对着宿主的模型目录解析一遍（docs/dynamic-workflow/launch.md「Models the script
+ * names」），窗上显示的就是将要生效的模型，解不出来的名字作为 9011 退回、什么都不跑。
+ *
+ * 集合的两个来源：
+ *
+ * 1. `model("…")` 调用的实参——必须是非空的无洞字符串字面量（9010）。`ModelRef` 只能由它造出
+ *    （facade 里是私有构造器 + 私有成员的 class，`new` 与对象字面量都造不出来），所以任何类型为
+ *    `ModelRef` 的值都来自某一次 `model()`，名字已经在集合里。
+ * 2. 每个 `agent(name, persona)` 站点上 persona 的 `model` 属性的**类型**：必须是 `ModelRef`、
+ *    字符串字面量类型，或它们的联合（9010）。联合里的每个字面量成员都进集合。
+ *
+ * 为什么判**类型**而不是判语法上的字面量：`const FLASH = "…"`、`hard ? "a" : "b"`、`MODELS[k]`
+ * 这些写法运行期取哪个值不定，但取值集合 checker 已经算好了——按类型判，一条规则就同时覆盖
+ * 内联字面量、const 绑定和三目，而一个被拓宽成 `string` 的值（`let`、参数、带洞模板、先装进
+ * 变量的 persona 对象）恰好就是集合不封闭的那一类。
+ *
+ * 为什么内联的 persona 对象字面量要**按语法取 `model` 的初值表达式**再问它的类型，而不是问整个
+ * 对象的类型：对象字面量的属性类型在上下文类型不含字面量类型时会被拓宽（`{ model: "x" }` 在
+ * `AgentPersona` 的上下文里，属性类型是 `string`），按对象类型判会把最常见的写法误报掉。初值
+ * 表达式自己的类型不受这条拓宽影响。
+ *
+ * 与 actor-names.ts（9005/9006）不同，本诊断**没有运行期兜底**：下游没有第二处去查「一个子代理的
+ * model 可能是什么」。宿主在建会话时查不到绑定只会让那一次 ask 大声失败（只有类型断言能走到那
+ * 一步），而那已经是确认窗之后了。所以这里宁可多报，不可漏报。
+ *
+ * 顺带：`ModelRef` 在运行期不存在（lowering 把 `model("x")` 抹成 `"x"`，沙箱里没有这个 class），
+ * 所以脚本在**值位置**引用 `ModelRef`（`x instanceof ModelRef`）也在这里以 9010 报出，
+ * 而不是留成一个运行期 ReferenceError。
+ */
+import ts from "typescript";
+import { facadeMemberOf, valueFunctionOfSymbol } from "../facade/registry.js";
+import { findWorkflowBody, resolveSymbol } from "./sites.js";
+/** 模型名不封闭（persona 的 `model` 类型、`model()` 的实参、值位置的 `ModelRef`）。 */
+export const MODEL_REFERENCE_CODE = 9010;
+/**
+ * 脚本里的模型名在宿主的模型目录里解析不出来（没有、歧义、被停用、档位不对）。**不是**本包产出的
+ * 诊断——编译器不知道宿主配了哪些模型——而是 launch 工具（packages/core）在 `resolveInput` 之后
+ * 按 {@link ModelReference} 的位置报出来的；码放在这里，好让两处共用一个数、诊断表只有一份。
+ */
+export const MODEL_UNRESOLVED_CODE = 9011;
+/** 被拒的 `model` 值的统一说明：给出三种改法，好让作者一次改对。 */
+const WIDENED_MODEL_MESSAGE = "A subagent's `model` must be known before the run starts: a string literal, a union of " +
+    'string literals, or a ModelRef from model("…"). This value\'s type is {type}, which could ' +
+    "be any model name. Write the name inline, add `as const` where it is declared, or declare " +
+    "the candidates with model() and choose among those ModelRefs at run time.";
+const MODEL_CALL_MESSAGE = "model() takes the model name as a non-empty string literal (a model id or " +
+    '"providerId/modelId", optionally with "$level"): every model a script can use is checked ' +
+    "against the configured models before the run starts. Put runtime choices in which ModelRef " +
+    "you pass, not in the name.";
+const MODEL_REF_VALUE_MESSAGE = "ModelRef exists only as a type: at run time a ModelRef is its model name. Use it in type " +
+    "positions only; compare ModelRefs directly or keep a table keyed by your own choice.";
+/** 收集模型名集合与 9010 诊断。只在编译干净的程序上调用。 */
+export function collectActorModels(workflow, table) {
+    const { program, scriptFile, toScriptLoc } = workflow;
+    const checker = program.getTypeChecker();
+    const references = [];
+    const diagnostics = [];
+    const locOf = (node) => toScriptLoc(node.getStart(scriptFile));
+    const report = (at, message) => {
+        const loc = locOf(at);
+        diagnostics.push({ code: MODEL_REFERENCE_CODE, column: loc.column, line: loc.line, message });
+    };
+    const collect = (name, at) => {
+        const loc = locOf(at);
+        references.push({ column: loc.column, line: loc.line, name });
+    };
+    // 1. model() 调用与值位置的 ModelRef：一趟走完整个脚本体（含嵌套函数——模型表常在顶层，
+    //    但写在 helper 里的 model() 同样在集合里）。
+    const walk = (node) => {
+        if (ts.isCallExpression(node)) {
+            if (valueFunctionOfSymbol(resolveSymbol(node.expression, checker)) === "model") {
+                const arg = node.arguments[0];
+                if (arg !== undefined && ts.isStringLiteralLike(arg) && arg.text.trim().length > 0) {
+                    collect(arg.text, arg);
+                }
+                else {
+                    report(arg ?? node, MODEL_CALL_MESSAGE);
+                }
+            }
+        }
+        else if (ts.isIdentifier(node) && isModelRefClass(resolveSymbol(node, checker))) {
+            if (!isTypePosition(node))
+                report(node, MODEL_REF_VALUE_MESSAGE);
+        }
+        ts.forEachChild(node, walk);
+    };
+    walk(findWorkflowBody(scriptFile));
+    // 2. 每个 agent() 站点上 persona 的 model。
+    const checkModelValue = (expr, type) => {
+        const members = type.isUnion() ? type.types : [type];
+        for (const member of members) {
+            // 可选属性带进来的 undefined = 「没选模型」，不是一个名字。
+            if ((member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0)
+                continue;
+            if (isModelRefType(member))
+                continue;
+            if (member.isStringLiteral()) {
+                if (member.value.trim().length > 0) {
+                    collect(member.value, expr);
+                    continue;
+                }
+            }
+            report(expr, WIDENED_MODEL_MESSAGE.replace("{type}", `'${checker.typeToString(type)}'`));
+            return;
+        }
+    };
+    const checkPersona = (persona) => {
+        if (ts.isParenthesizedExpression(persona)) {
+            checkPersona(persona.expression);
+            return;
+        }
+        if (ts.isConditionalExpression(persona)) {
+            checkPersona(persona.whenTrue);
+            checkPersona(persona.whenFalse);
+            return;
+        }
+        if (ts.isObjectLiteralExpression(persona)) {
+            const modelExpr = lastModelInitializer(persona);
+            if (modelExpr === "spread") {
+                checkPersonaType(persona);
+            }
+            else if (modelExpr !== undefined) {
+                checkModelValue(modelExpr, modelValueType(modelExpr, checker));
+            }
+            return;
+        }
+        checkPersonaType(persona);
+    };
+    // 不是内联对象字面量：按实参的类型取 model 属性。字符串 persona（= system prompt）没有 model。
+    const checkPersonaType = (persona) => {
+        const type = checker.getTypeAtLocation(persona);
+        const members = type.isUnion() ? type.types : [type];
+        for (const member of members) {
+            if ((member.flags & ts.TypeFlags.StringLike) !== 0)
+                continue;
+            const property = checker.getPropertyOfType(member, "model");
+            if (property === undefined)
+                continue;
+            checkModelValue(persona, checker.getTypeOfSymbolAtLocation(property, persona));
+        }
+    };
+    for (const site of table.actors) {
+        const persona = site.call.arguments[1];
+        if (persona !== undefined)
+            checkPersona(persona);
+    }
+    return { diagnostics, references };
+}
+/**
+ * 内联 persona 字面量里**最后一次**写下的 `model` 的初值表达式。它之后若还有展开，展开可能盖掉它，
+ * 回 `"spread"` 交给按类型的判定；从没写过 `model` 但有展开时同样回 `"spread"`；两者都没有即 undefined。
+ */
+function lastModelInitializer(literal) {
+    let found;
+    for (const property of literal.properties) {
+        if (ts.isSpreadAssignment(property)) {
+            found = "spread";
+        }
+        else if (ts.isPropertyAssignment(property) && propertyNameText(property.name) === "model") {
+            found = property.initializer;
+        }
+        else if (ts.isShorthandPropertyAssignment(property) && property.name.text === "model") {
+            found = property.name;
+        }
+    }
+    return found;
+}
+/** 初值表达式自己的类型（不经对象字面量的属性拓宽）；shorthand `{ model }` 取被引用绑定的类型。 */
+function modelValueType(expr, checker) {
+    const parent = expr.parent;
+    if (ts.isShorthandPropertyAssignment(parent) && parent.name === expr) {
+        const value = checker.getShorthandAssignmentValueSymbol(parent);
+        if (value !== undefined)
+            return checker.getTypeOfSymbolAtLocation(value, expr);
+    }
+    return checker.getTypeAtLocation(expr);
+}
+function propertyNameText(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteralLike(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return undefined;
+}
+/** facade 里的 `ModelRef` class 符号。 */
+function isModelRefClass(symbol) {
+    const member = facadeMemberOf(symbol);
+    return (member !== undefined &&
+        member.container === undefined &&
+        member.member === "ModelRef" &&
+        symbol !== undefined &&
+        (symbol.flags & ts.SymbolFlags.Class) !== 0);
+}
+/** 这个类型就是 facade 的 `ModelRef`（它的实例类型）。 */
+function isModelRefType(type) {
+    return isModelRefClass(type.getSymbol());
+}
+/** 标识符处在类型位置（`x: ModelRef`、`typeof ModelRef`、`A.ModelRef` 的限定名链上）。 */
+function isTypePosition(node) {
+    let parent = node.parent;
+    while (ts.isQualifiedName(parent))
+        parent = parent.parent;
+    return ts.isTypeReferenceNode(parent) || ts.isTypeQueryNode(parent);
+}

package/vendor/dynamic-workflow/analysis/actor-names.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 具名 actor 重名的编译期 courtesy 诊断。
+ *
+ * 规则本身是**运行期**的：引擎在 createActor 查非空有效名的重复，撞上即 run 级失败
+ * （`DuplicateActorName`）。理由是具名 actor 是修订续跑（amend-resume）缓存导入的身份键，
+ * 而任何 run 都是未来修订的潜在前驱——前驱里重名会让导入匹配歧义。
+ *
+ * 这里做**字面量能看穿的那一半**，两条子句：
+ *
+ * 1. **两处同名**：两个 `agent(...)` 站点的有效名是同一个字符串字面量时，在后一处报一条可
+ *    定位的诊断，让作者在便宜的那一侧改名，而不是跑到一半失败。任何动态成分
+ *    （`` `worker-${i}` ``、标识符、展开、shorthand 属性）一律跳过——那些只有运行期能查。
+ * 2. **fan-out 里的静态名**：一个 `agent("x")` 站点跑在 fan-out 体内时，每个元素都建一个新
+ *    actor 而它们共用同一个名字——一个站点，N 次重名，运行期必然大声失败。
+ *
+ * 子句 1 **只会漏报、不会误报**：跳过一个可能重名的站点没有代价（引擎兜底），而误伤一个
+ * 合法脚本会挡住提交。
+ *
+ * `.map` 的集合可能只有 ≤1 个
+ * 元素，那样的脚本在运行期其实合法，所以这条子句理论上会误报。接受它的理由是代价不对称——
+ * 修复是免费的（改成逐元素名 `` `x-${item}` `` 或匿名），而不报的代价是模型烧掉一整个 run
+ * 才学到这条规则。`paths.map((p) => agent("reviewer").ask(…))` 正是 fan-out 的教科书写法，
+ * 沉默地留给运行期是最坏的一档。
+ *
+ * fan-out 的判定**复用站点表的分类**（`analysis/sites.ts` 的 `IterationCandidate`：带内联
+ * 回调的数组方法 + `for...of`），不自己再造一套循环识别。代价是普通 `for` / `while` /
+ * `do` 循环不在那张分类里，因而不被本子句覆盖——它们回落到子句 1 的老姿态（看不见，归运行期）。
+ * 那正是漏报方向，与本模块的保守取向一致。
+ *
+ * `CreateWorkflow` 与
+ * `SaveWorkflow` 两个 handler 都先走 `analyzeScript`（本诊断在 `analyzeWorkflowScript` 的
+ * authoring 批次里），`!ok` 即带诊断早返回、**不 submit / 不落盘**，所以一条 9005/9006 确实
+ * 挡住提交与保存。但 run service 的 `compileOnce`（submit 与 resume 的重编译）只复验
+ * typecheck / schema / world.run 字面量三项，**不含**本诊断——所以它不是 submit 路径上的
+ * 强制门，别把它当承重结构：具名唯一性的权威始终是引擎 createActor 的运行期查重。
+ */
+import type { CompileDiagnostic, WorkflowProgram } from "../compiler/compile.js";
+import type { SiteTable } from "./sites.js";
+/** 两处字面量同名（子句 1）。9001 = facade-siting、9002 = schema、9003 = world-run、9004 = phase。 */
+export declare const DUPLICATE_ACTOR_NAME_CODE = 9005;
+/**
+ * fan-out 体内的静态名（子句 2），单独一个码而不是复用 9005。
+ *
+ * 两条子句是同一条规则，但**确定性不同**：9005 只在静态确定重名时出现，9006 是上面那条刻意
+ * 接受误报的子句。读端因此需要能区分它们——特别是分析侧的 fixture 语料：
+ * 那些脚本从不执行，只用来钉图形状，其中静态名 + fan-out 的组合恰恰是**分析器必须正确处理**
+ * 的形状（`ActorNode.family`、actor 标签），所以语料要豁免 9006 而对 9005 保持严格。
+ * 共用一个码就只能靠匹配 message 文本来区分，而按错误文本分流正是本仓库处处禁止的。
+ */
+export declare const FANOUT_ACTOR_NAME_CODE = 9006;
+/**
+ * 收集字面量重名诊断。非空即脚本不可提交（`analyzeWorkflowScript` 与 world.run / phase
+ * 的编译期规则同席）。
+ */
+export declare function collectDuplicateActorNames(workflow: WorkflowProgram, table: SiteTable): CompileDiagnostic[];
+//# sourceMappingURL=actor-names.d.ts.map

package/vendor/dynamic-workflow/analysis/actor-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-names.d.ts","sourceRoot":"","sources":["../../src/analysis/actor-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,SAAS,GACf,iBAAiB,EAAE,CAgDrB"}

package/vendor/dynamic-workflow/analysis/actor-names.js

@@ -0,0 +1,155 @@
+/**
+ * 具名 actor 重名的编译期 courtesy 诊断。
+ *
+ * 规则本身是**运行期**的：引擎在 createActor 查非空有效名的重复，撞上即 run 级失败
+ * （`DuplicateActorName`）。理由是具名 actor 是修订续跑（amend-resume）缓存导入的身份键，
+ * 而任何 run 都是未来修订的潜在前驱——前驱里重名会让导入匹配歧义。
+ *
+ * 这里做**字面量能看穿的那一半**，两条子句：
+ *
+ * 1. **两处同名**：两个 `agent(...)` 站点的有效名是同一个字符串字面量时，在后一处报一条可
+ *    定位的诊断，让作者在便宜的那一侧改名，而不是跑到一半失败。任何动态成分
+ *    （`` `worker-${i}` ``、标识符、展开、shorthand 属性）一律跳过——那些只有运行期能查。
+ * 2. **fan-out 里的静态名**：一个 `agent("x")` 站点跑在 fan-out 体内时，每个元素都建一个新
+ *    actor 而它们共用同一个名字——一个站点，N 次重名，运行期必然大声失败。
+ *
+ * 子句 1 **只会漏报、不会误报**：跳过一个可能重名的站点没有代价（引擎兜底），而误伤一个
+ * 合法脚本会挡住提交。
+ *
+ * `.map` 的集合可能只有 ≤1 个
+ * 元素，那样的脚本在运行期其实合法，所以这条子句理论上会误报。接受它的理由是代价不对称——
+ * 修复是免费的（改成逐元素名 `` `x-${item}` `` 或匿名），而不报的代价是模型烧掉一整个 run
+ * 才学到这条规则。`paths.map((p) => agent("reviewer").ask(…))` 正是 fan-out 的教科书写法，
+ * 沉默地留给运行期是最坏的一档。
+ *
+ * fan-out 的判定**复用站点表的分类**（`analysis/sites.ts` 的 `IterationCandidate`：带内联
+ * 回调的数组方法 + `for...of`），不自己再造一套循环识别。代价是普通 `for` / `while` /
+ * `do` 循环不在那张分类里，因而不被本子句覆盖——它们回落到子句 1 的老姿态（看不见，归运行期）。
+ * 那正是漏报方向，与本模块的保守取向一致。
+ *
+ * `CreateWorkflow` 与
+ * `SaveWorkflow` 两个 handler 都先走 `analyzeScript`（本诊断在 `analyzeWorkflowScript` 的
+ * authoring 批次里），`!ok` 即带诊断早返回、**不 submit / 不落盘**，所以一条 9005/9006 确实
+ * 挡住提交与保存。但 run service 的 `compileOnce`（submit 与 resume 的重编译）只复验
+ * typecheck / schema / world.run 字面量三项，**不含**本诊断——所以它不是 submit 路径上的
+ * 强制门，别把它当承重结构：具名唯一性的权威始终是引擎 createActor 的运行期查重。
+ */
+import ts from "typescript";
+/** 两处字面量同名（子句 1）。9001 = facade-siting、9002 = schema、9003 = world-run、9004 = phase。 */
+export const DUPLICATE_ACTOR_NAME_CODE = 9005;
+/**
+ * fan-out 体内的静态名（子句 2），单独一个码而不是复用 9005。
+ *
+ * 两条子句是同一条规则，但**确定性不同**：9005 只在静态确定重名时出现，9006 是上面那条刻意
+ * 接受误报的子句。读端因此需要能区分它们——特别是分析侧的 fixture 语料：
+ * 那些脚本从不执行，只用来钉图形状，其中静态名 + fan-out 的组合恰恰是**分析器必须正确处理**
+ * 的形状（`ActorNode.family`、actor 标签），所以语料要豁免 9006 而对 9005 保持严格。
+ * 共用一个码就只能靠匹配 message 文本来区分，而按错误文本分流正是本仓库处处禁止的。
+ */
+export const FANOUT_ACTOR_NAME_CODE = 9006;
+/**
+ * 收集字面量重名诊断。非空即脚本不可提交（`analyzeWorkflowScript` 与 world.run / phase
+ * 的编译期规则同席）。
+ */
+export function collectDuplicateActorNames(workflow, table) {
+    const diagnostics = [];
+    const claimed = new Map();
+    // fan-out 体的集合来自站点表的 IterationCandidate（数组方法的内联回调体 + for...of 的
+    // 循环体），与 `ActorNode.fanOutId` 判定「站点是否落在 fan-out 体内」用的是同一个概念。
+    const fanOutBodies = new Set(table.iterations.map((iteration) => iteration.body));
+    for (const site of table.actors) {
+        // 站点表的 `site.name` 在这里**用不得**：它会退回到绑定名（`const planner = agent()`
+        // 记作 "planner"），那是给图用的展示标签，不是运行期的有效名。这里要的是引擎会看见的
+        // 那个值，所以自己从实参读。
+        const name = staticEffectiveName(site.call);
+        if (name === undefined || name === "")
+            continue;
+        const first = claimed.get(name);
+        if (first === undefined)
+            claimed.set(name, site.call);
+        const loc = workflow.toScriptLoc(site.call.getStart(workflow.scriptFile));
+        // 一个站点最多报一条：fan-out 子句更具体（它连修法都不同——逐元素名而不是换个名字），
+        // 所以它优先。名字仍照常登记，后面同名的站点该报还报。
+        if (isInsideFanOut(site.call, fanOutBodies)) {
+            diagnostics.push({
+                code: FANOUT_ACTOR_NAME_CODE,
+                column: loc.column,
+                line: loc.line,
+                message: `this agent(...) runs once per element of a fan-out but its name "${name}" is a fixed ` +
+                    `string, so every element creates a different actor under the same name — the run ` +
+                    `fails with DuplicateActorName as soon as the collection holds more than one item. ` +
+                    `An actor name must be unique within a run: it is the identity key an amended re-run ` +
+                    `matches its imported cache against. Build a per-element name (\`${name}-\${item}\`), ` +
+                    `or drop the name — anonymous actors are legal (they just never reuse cached work).`,
+            });
+            continue;
+        }
+        if (first === undefined)
+            continue;
+        // 诊断落在**后一处**：先出现的那个名字是既有事实，要改的是后来的这一个。
+        const firstLoc = workflow.toScriptLoc(first.getStart(workflow.scriptFile));
+        diagnostics.push({
+            code: DUPLICATE_ACTOR_NAME_CODE,
+            column: loc.column,
+            line: loc.line,
+            message: `two actors are named "${name}" (the first is on line ${firstLoc.line}): an actor name ` +
+                `must be unique within a run. The name is the identity key an amended re-run matches ` +
+                `its imported cache against, and any run can become the predecessor of one, so a ` +
+                `repeated name makes that match ambiguous. Give this one its own name, or drop the ` +
+                `name entirely — anonymous actors are legal (they just never reuse cached work).`,
+        });
+    }
+    return diagnostics;
+}
+/**
+ * 该调用是否**词法上**落在某个 fan-out 体内。从调用本身起走父链（调用可以就是体本身：
+ * `paths.map((p) => agent("x"))` 的箭头简写体），命中任一候选体即是。
+ */
+function isInsideFanOut(call, fanOutBodies) {
+    for (let node = call; node !== undefined; node = node.parent) {
+        if (fanOutBodies.has(node))
+            return true;
+    }
+    return false;
+}
+/**
+ * 一个 `agent(...)` 调用静态可知的**有效名**，否则 undefined（= 跳过）。
+ *
+ * 与引擎的 `normalizePersona` 同一条规则：persona.name 压过 name 实参；字符串 persona 是
+ * system prompt、不带名字。任何一处看不穿就整体放弃——宁可漏报。
+ *
+ * facade 的 `AgentPersona` **今天不声明 name**，所以脚本写得出的 persona 从不带名字，有效名
+ * 一律落到 name 实参。persona 这一段因此现在从不触发；留着是为了与 normalizePersona 同步，
+ * 而不是为了今天生效——一旦 facade 长出 name 而这里还按 name 实参判定，一个被 persona 改过名
+ * 的 actor 就会被**误报**，而误报会挡住合法脚本（漏报没有代价：引擎运行期兜底）。
+ */
+function staticEffectiveName(call) {
+    const [nameArg, personaArg] = call.arguments;
+    if (personaArg !== undefined && !ts.isStringLiteralLike(personaArg)) {
+        if (!ts.isObjectLiteralExpression(personaArg))
+            return undefined; // 动态 persona：可能带 name
+        for (const property of personaArg.properties) {
+            // 展开可能带进一个 name，静态说不准。
+            if (ts.isSpreadAssignment(property))
+                return undefined;
+            // 计算键（`{ ["na" + "me"]: … }`）也说不准：它**可能就是** name。这里必须整体放弃而
+            // 不是 `continue`——continue 会落回 name 实参，等于断言 persona 没有改名，那是一次
+            // 猜测，而猜错的方向恰好是误报（挡住合法脚本）。
+            if (property.name !== undefined && ts.isComputedPropertyName(property.name))
+                return undefined;
+            if (property.name === undefined || !isNameKey(property.name))
+                continue;
+            if (!ts.isPropertyAssignment(property))
+                return undefined; // shorthand / 方法：动态
+            return ts.isStringLiteralLike(property.initializer)
+                ? property.initializer.text
+                : undefined;
+        }
+        // 对象字面量里没有 name，落回 name 实参。
+    }
+    return nameArg !== undefined && ts.isStringLiteralLike(nameArg) ? nameArg.text : undefined;
+}
+/** 属性键是否**静态确定**就是 `name`（计算键在调用点已整体放弃，不走这里）。 */
+function isNameKey(key) {
+    return (ts.isIdentifier(key) || ts.isStringLiteralLike(key)) && key.text === "name";
+}