@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.0

package/vendor/dynamic-workflow/engine/engine-holes.js

@@ -0,0 +1,142 @@
+/**
+ * 留白（docs/execution-engine.md「Holes」）：脚本向主代理要一段代码，run 停在那一处等它。
+ *
+ * 与 escalation 不同——那个活在 driver 执行一次 ask 的内部，引擎核心看不见——留白是 Boundary A
+ * 的调用：脚本自己在等它，所以引擎像拥有一次 ask 那样拥有它，少一个 driver。与 ask 又有一处
+ * 根本不同：**没有 journal 行**。留白不是会自己结算出一个结果的节点，补全产出的东西已经以
+ * 有效脚本的身份写在 run 行上（`updateRunScript`），resume 重放有效脚本时体内联执行、shim 不过
+ * 线、`hole-reached` 不再出现。
+ *
+ * 本模块持有引擎的留白状态（停驻表 + 本世已补全的代码表），方法体是自由函数，经
+ * {@link EngineState} 接缝读写引擎的其余私有状态；WorkflowEngine 上只留薄委托（拆分原因：
+ * engine.ts 顶到 oxlint max-lines 上限 400 行）。
+ */
+/**
+ * `hole-reached` 与通知上 prompt 的上限（字符）：与 escalation 通知的 question / context 同一
+ * 把尺（docs/dynamic-workflow/transcript-and-notifications.md）。超出的截断并以 `…` 收尾。
+ */
+export const HOLE_PROMPT_MAX_CHARS = 4000;
+/** 截断标记：占最后一个字符的位置，截后总长恰为上限。 */
+const ELLIPSIS = "…";
+/** 引擎的留白状态：按站点的停驻表与本世的补全记忆。纯内存、随引擎实例而生，resume 从空表起。 */
+export class HoleRegistry {
+    now;
+    /** 站点 → 停在它下面的分支（一个站点可以同时停着好几个序号）。 */
+    parked = new Map();
+    /** 站点 → 本世记住的补全（后到的 `hole` 直接作答、不停驻）。 */
+    filled = new Map();
+    constructor(now) {
+        this.now = now;
+    }
+    /** 站点已补全时返回记住的代码，否则 undefined。 */
+    remembered(siteId) {
+        return this.filled.get(siteId)?.code;
+    }
+    /** 把一个分支停在站点下，返回它的 promise。 */
+    park(instance, name) {
+        return new Promise((resolve, reject) => {
+            const list = this.parked.get(instance.siteId) ?? [];
+            list.push({ instance, name, since: this.now(), resolve, reject });
+            this.parked.set(instance.siteId, list);
+        });
+    }
+    /** 这个站点是否有停驻的分支或已记住的补全（`fillHole` 的 not_waiting 判据的反面）。 */
+    isWaitingOrFilled(siteId) {
+        return (this.parked.get(siteId)?.length ?? 0) > 0 || this.filled.has(siteId);
+    }
+    /** 现在的时刻（epoch 毫秒）：`hole-filled` 的 `filledAt` 与记忆里的同一个瞬间。 */
+    clock() {
+        return this.now();
+    }
+    /** 记住补全并放行站点下的每一个分支。 */
+    release(siteId, code, filledAt, filledBy) {
+        this.filled.set(siteId, { code, filledAt, ...(filledBy === undefined ? {} : { filledBy }) });
+        const list = this.parked.get(siteId) ?? [];
+        this.parked.delete(siteId);
+        for (const entry of list)
+            entry.resolve({ code });
+    }
+    /** run 结算：停驻的分支一律以结算错误拒绝（与 ask 的取消同姿态）；补全记忆保留。 */
+    rejectAll(error) {
+        const lists = [...this.parked.values()];
+        this.parked.clear();
+        for (const list of lists)
+            for (const entry of list)
+                entry.reject(error);
+    }
+    open() {
+        const out = [];
+        for (const list of this.parked.values()) {
+            for (const entry of list) {
+                out.push({
+                    siteId: entry.instance.siteId,
+                    ordinal: entry.instance.ordinal,
+                    name: entry.name,
+                    since: entry.since,
+                });
+            }
+        }
+        return out;
+    }
+    filledList() {
+        return [...this.filled.entries()].map(([siteId, fill]) => ({
+            siteId,
+            filledAt: fill.filledAt,
+            ...(fill.filledBy === undefined ? {} : { filledBy: fill.filledBy }),
+        }));
+    }
+}
+/** 记录前把 prompt 截到上限（超出的以 `…` 收尾，截后总长恰为上限）。 */
+export function boundHolePrompt(prompt) {
+    if (prompt.length <= HOLE_PROMPT_MAX_CHARS)
+        return prompt;
+    return prompt.slice(0, HOLE_PROMPT_MAX_CHARS - ELLIPSIS.length) + ELLIPSIS;
+}
+/**
+ * Boundary A 的 `hole`：铸序号（`nextOrdinal` 同时盖出生阶段）、停驻、记 `hole-reached`。
+ * **先停驻再记事件**：事件经 driver.emit 同步扇出，一个在 emit 里同步补全的监听者必须能命中
+ * 停驻表，否则它拿到的是 `not_waiting`。已补全的站点以记住的代码立刻作答，不停驻、不记事件
+ * ——resume 重放有效脚本时 shim 本就不过线，这里只是引擎侧的同一条规则。
+ */
+export function reachHole(state, holes, siteId, name, prompt) {
+    if (state.isRunSettled())
+        return Promise.reject(state.runError());
+    const ordinal = state.nextOrdinal(siteId);
+    const remembered = holes.remembered(siteId);
+    if (remembered !== undefined)
+        return Promise.resolve({ code: remembered });
+    const instance = { siteId, ordinal };
+    const promise = holes.park(instance, name);
+    state.record({
+        type: "hole-reached",
+        instance,
+        name,
+        ...(prompt === undefined ? {} : { prompt: boundHolePrompt(prompt) }),
+    });
+    return promise;
+}
+/**
+ * `fillHole` 的方法体（docs/execution-engine.md「The engine's part」）：一个同步步骤里——换规格表
+ * 与阶段表（调用方负责，见 `swapTables`）、写有效脚本、记 `hole-filled`、记住代码、放行停驻的
+ * 每一个分支。两条 no-op 不写不发。
+ */
+export function fillHole(state, holes, fill, swapTables) {
+    if (state.isRunSettled())
+        return { ok: false, reason: "settled" };
+    if (!holes.isWaitingOrFilled(fill.siteId))
+        return { ok: false, reason: "not_waiting" };
+    swapTables(fill.askSpecs, fill.sitePhases);
+    state.journal.updateRunScript(state.runId, fill.script.text, fill.script.hash);
+    const filledAt = holes.clock();
+    state.record({
+        type: "hole-filled",
+        siteId: fill.siteId,
+        filledAt,
+        ...(fill.filledBy === undefined ? {} : { filledBy: fill.filledBy }),
+        phaseNames: fill.phaseNames,
+        ...(fill.holes === undefined ? {} : { holes: fill.holes }),
+        ...(fill.scriptPath === undefined ? {} : { scriptPath: fill.scriptPath }),
+    });
+    holes.release(fill.siteId, fill.code, filledAt, fill.filledBy);
+    return { ok: true };
+}

package/vendor/dynamic-workflow/engine/engine-launch.d.ts

@@ -0,0 +1,34 @@
+import type { RunEvent } from "./types.js";
+/**
+ * 发起 run 那一轮随 `run-launched` 同车的宿主元数据（EngineConfig.launch）：锚点 `inputId`、
+ * 脚本声明的阶段表 `phaseNames`、与之按位置对齐的 `phaseAlongside`、本 run 子代理的选型
+ * `subagentModel` 与权限模式 `subagentPermissionMode`、脚本点名的模型绑定表 `modelBindings`、脚本来自
+ * 哪个文件 `scriptPath`，以及留白下标表 `holes`。八者引擎都不读——字段语义见 types.ts 里
+ * `run-launched` 的注释。
+ */
+export interface RunLaunchConfig {
+    inputId: string;
+    phaseNames?: string[];
+    subagentModel?: string;
+    /** 脚本点名的模型名（逐字）→ 规范串（docs/dynamic-workflow/launch.md「Models the script names」）。 */
+    modelBindings?: Record<string, string>;
+    /**
+     * 本 run 子代理的权限模式（docs/dynamic-workflow/launch.md「Permissions inside a run」）：
+     * 发起会话的权限模式名。引擎不读，按不透明串记下；宿主读回时校验。
+     */
+    subagentPermissionMode?: string;
+    /** 本 run 脚本文件的绝对路径（docs/dynamic-workflow/launch.md「Script files」）。 */
+    scriptPath?: string;
+    phaseAlongside?: number[][];
+    /** `phaseNames` 里未补全留白的下标（docs/execution-engine.md「Holes」），同车同规。 */
+    holes?: number[];
+}
+/**
+ * 把 launch 元数据转录成 `run-launched`。未设的键**缺席**而不是落成 undefined 值：读侧
+ * （AmendWorkflow 的三态、投影）把「没设」与「设了个空」当两件事。
+ */
+export declare function runLaunchedEvent(launch: RunLaunchConfig, origin: {
+    toolCallId?: string | undefined;
+    parentSessionId?: string | undefined;
+}): RunEvent;
+//# sourceMappingURL=engine-launch.d.ts.map

package/vendor/dynamic-workflow/engine/engine-launch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-launch.d.ts","sourceRoot":"","sources":["../../src/engine/engine-launch.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IAC5B,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAChF,QAAQ,CAwBV"}

package/vendor/dynamic-workflow/engine/engine-launch.js

@@ -0,0 +1,26 @@
+// ============================================================
+// run-launched：发起 run 那一轮的宿主元数据 → 事件
+// ============================================================
+// 引擎不读这些元数据（锚点、阶段表、并行表、子代理选型），只在建 run 那一世紧跟首条
+// `run-started` 逐字转录一次（engine.ts）。构造独立成模块，engine.ts 与 types.ts 才都留在
+// 400 行的 lint 上限之内——它们是两侧同时增长的文件。
+/**
+ * 把 launch 元数据转录成 `run-launched`。未设的键**缺席**而不是落成 undefined 值：读侧
+ * （AmendWorkflow 的三态、投影）把「没设」与「设了个空」当两件事。
+ */
+export function runLaunchedEvent(launch, origin) {
+    const { inputId, phaseNames, subagentModel, subagentPermissionMode, modelBindings, scriptPath, phaseAlongside, holes, } = launch;
+    return {
+        type: "run-launched",
+        inputId,
+        ...(origin.toolCallId === undefined ? {} : { toolCallId: origin.toolCallId }),
+        ...(origin.parentSessionId === undefined ? {} : { parentSessionId: origin.parentSessionId }),
+        ...(phaseNames === undefined ? {} : { phaseNames }),
+        ...(subagentModel === undefined ? {} : { subagentModel }),
+        ...(subagentPermissionMode === undefined ? {} : { subagentPermissionMode }),
+        ...(modelBindings === undefined ? {} : { modelBindings }),
+        ...(scriptPath === undefined ? {} : { scriptPath }),
+        ...(phaseAlongside === undefined ? {} : { phaseAlongside }),
+        ...(holes === undefined ? {} : { holes }),
+    };
+}

package/vendor/dynamic-workflow/engine/engine-phase-stamp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 出生阶段坐标的两个打戳函数（docs/dynamic-workflow/presentation.md 追记 2026-09-09）。
+ *
+ * 拆分原因：engine.ts 顶到 oxlint max-lines 上限（400 行）。选中这两个而不是别的，是因为它们
+ * 高度同族——同一张 `instancePhases` 表（实例 `siteId@ordinal` → 它**出生时**的阶段名）的仅有
+ * 两个读者，一个给事件打戳、一个给 `ProviderStop` 明细补阶段，且都是纯函数：表由调用方（引擎）
+ * 拥有并在铸造点写入，这里只读。公开面仍只有 engine.ts 在用。
+ */
+import type { RunEvent } from "./types.js";
+import { WorkflowError } from "./types.js";
+/** 实例键（`siteId@ordinal`）→ 它出生时的阶段名。引擎的 `instancePhases` 的只读视图。 */
+export type InstancePhases = ReadonlyMap<string, string>;
+/**
+ * 给**出生事件**补上出生阶段：actor 的 `actor-created` 按 actor 查表，节点的 `node-queued`
+ * 按 instance 查表，命中缓存的 `node-settled { cached: true }` 同样按 instance——命中的节点
+ * 没有 queued，那条 settle 就是它的出生事件。其余事件**原样返回**：调度器的其余发射点零改动，
+ * reducer 沿用 `actorSiteId` 的先例向前携带。
+ *
+ * ask 的 `node-dispatched` 是唯一的例外，它重复自己的出生事实（types.ts 的同名事件），于是
+ * 两个阶段名在这里一并补上：`phaseName` 按 instance、`actorPhaseName` 按它的 actor，两次都查
+ * 同一张出生表，所以与该实例的 `node-queued`、该 actor 的 `actor-created` 逐字相同。带 `actor`
+ * 才补——world-read 的派发不带子代理，保持裸的。
+ *
+ * 它不是「发出这条事件时的当前阶段」：node-queued 可能被 hold 规则推迟到下一个标记之后才发出，
+ * 而出生时刻在上一个阶段；派发更是可能卡在并发上界后面，等到脚本已走过好几个标记。
+ */
+export declare function stampBirthPhase(event: RunEvent, instancePhases: InstancePhases): RunEvent;
+/**
+ * 给 `ProviderStop` 补上触发停止的子代理的**出生阶段**（docs/execution-engine.md
+ * 「通知文案」的 `phase=`）：driver 只知道 actor ref，阶段只有引擎知道（与事件流上 `phaseName`
+ * 的同一张表）。没有 providerStop、没有 subagent、已带阶段、或该 ref 出生在任何 `phase()`
+ * 标记之前 → 原样返回。
+ */
+export declare function enrichProviderStopPhase(error: WorkflowError, instancePhases: InstancePhases): WorkflowError;
+//# sourceMappingURL=engine-phase-stamp.d.ts.map

package/vendor/dynamic-workflow/engine/engine-phase-stamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-phase-stamp.d.ts","sourceRoot":"","sources":["../../src/engine/engine-phase-stamp.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAe,aAAa,EAAE,MAAM,YAAY,CAAC;AAExD,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,GAAG,QAAQ,CA8BzF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,aAAa,EACpB,cAAc,EAAE,cAAc,GAC7B,aAAa,CAWf"}

package/vendor/dynamic-workflow/engine/engine-phase-stamp.js

@@ -0,0 +1,74 @@
+/**
+ * 出生阶段坐标的两个打戳函数（docs/dynamic-workflow/presentation.md 追记 2026-09-09）。
+ *
+ * 拆分原因：engine.ts 顶到 oxlint max-lines 上限（400 行）。选中这两个而不是别的，是因为它们
+ * 高度同族——同一张 `instancePhases` 表（实例 `siteId@ordinal` → 它**出生时**的阶段名）的仅有
+ * 两个读者，一个给事件打戳、一个给 `ProviderStop` 明细补阶段，且都是纯函数：表由调用方（引擎）
+ * 拥有并在铸造点写入，这里只读。公开面仍只有 engine.ts 在用。
+ */
+import { refToString, WorkflowError } from "./types.js";
+/**
+ * 给**出生事件**补上出生阶段：actor 的 `actor-created` 按 actor 查表，节点的 `node-queued`
+ * 按 instance 查表，命中缓存的 `node-settled { cached: true }` 同样按 instance——命中的节点
+ * 没有 queued，那条 settle 就是它的出生事件。其余事件**原样返回**：调度器的其余发射点零改动，
+ * reducer 沿用 `actorSiteId` 的先例向前携带。
+ *
+ * ask 的 `node-dispatched` 是唯一的例外，它重复自己的出生事实（types.ts 的同名事件），于是
+ * 两个阶段名在这里一并补上：`phaseName` 按 instance、`actorPhaseName` 按它的 actor，两次都查
+ * 同一张出生表，所以与该实例的 `node-queued`、该 actor 的 `actor-created` 逐字相同。带 `actor`
+ * 才补——world-read 的派发不带子代理，保持裸的。
+ *
+ * 它不是「发出这条事件时的当前阶段」：node-queued 可能被 hold 规则推迟到下一个标记之后才发出，
+ * 而出生时刻在上一个阶段；派发更是可能卡在并发上界后面，等到脚本已走过好几个标记。
+ */
+export function stampBirthPhase(event, instancePhases) {
+    if (event.type === "actor-created") {
+        const phaseName = instancePhases.get(refToString(event.actor));
+        return phaseName === undefined ? event : { ...event, phaseName };
+    }
+    if (event.type === "node-queued") {
+        const phaseName = instancePhases.get(refToString(event.instance));
+        return phaseName === undefined ? event : { ...event, phaseName };
+    }
+    if (event.type === "node-dispatched" && event.actor !== undefined) {
+        const phaseName = instancePhases.get(refToString(event.instance));
+        const actorPhaseName = instancePhases.get(refToString(event.actor));
+        if (phaseName === undefined && actorPhaseName === undefined)
+            return event;
+        return {
+            ...event,
+            ...(phaseName === undefined ? {} : { phaseName }),
+            ...(actorPhaseName === undefined ? {} : { actorPhaseName }),
+        };
+    }
+    if (event.type === "node-settled" && event.cached === true) {
+        const phaseName = instancePhases.get(refToString(event.instance));
+        return phaseName === undefined ? event : { ...event, phaseName };
+    }
+    // 留白的到达也是一次出生（docs/execution-engine.md「Holes」）：序号与节点同族铸造，出生
+    // 阶段同一张表——没有行，事件是它唯一的坐标。
+    if (event.type === "hole-reached") {
+        const phaseName = instancePhases.get(refToString(event.instance));
+        return phaseName === undefined ? event : { ...event, phaseName };
+    }
+    return event;
+}
+/**
+ * 给 `ProviderStop` 补上触发停止的子代理的**出生阶段**（docs/execution-engine.md
+ * 「通知文案」的 `phase=`）：driver 只知道 actor ref，阶段只有引擎知道（与事件流上 `phaseName`
+ * 的同一张表）。没有 providerStop、没有 subagent、已带阶段、或该 ref 出生在任何 `phase()`
+ * 标记之前 → 原样返回。
+ */
+export function enrichProviderStopPhase(error, instancePhases) {
+    const details = error.providerStop;
+    if (details === undefined || details.subagent === undefined || details.phase !== undefined) {
+        return error;
+    }
+    const phase = instancePhases.get(details.subagent);
+    if (phase === undefined)
+        return error;
+    return new WorkflowError(error.code, error.message, {
+        providerStop: { ...details, phase },
+        cause: error.cause,
+    });
+}

package/vendor/dynamic-workflow/engine/engine-report.d.ts

@@ -0,0 +1,27 @@
+/**
+ * engine.ts 顶到 oxlint max-lines 上限（400 行），把 `report()` 的发布路径（序列化探针、
+ * replay 去重、标签校验、两个上限、一次写）拆到本文件；公开面仍从 engine.ts 导出。
+ *
+ * 自由函数经 {@link EngineState} 接缝读写引擎状态；WorkflowEngine.report 只是薄委托。
+ */
+import type { EngineState } from "./engine-state.js";
+/**
+ * 发布一条中间结果（Boundary A 的 `report`）。同步、无返回值、无 driver 往返：
+ * 落一行 journal + 发一个事件就结束。
+ *
+ * 四件事，顺序是有讲究的：
+ *
+ * 1. **序列化探针先行**。用 `JSON.stringify` 一次拿到两样东西：item 到底能不能被 JSON
+ *    表示，以及它的字节数（上限的度量）。必须在 canonicalJson 之前——带环的 item 会让
+ *    canonicalJson 递归爆栈，那是一次崩溃而不是一次可读的失败。
+ * 2. **replay 命中即跳过**：不发事件、不重写记录。跳过之前先比对 inputHash，不一致按
+ *    纯度违约让 run 大声失败。这条比对是**防御性的**（一条报告派生自 journal 已经钉住的
+ *    值），但它是免费的，而这里的偏移意味着整个 replay 不可靠——Results 面板的读者绝不
+ *    应该在不知情的情况下看到那种东西。
+ * 3. **上限先于落库**：单条字节数、条数、run 级字节总数任一超出即 `ReportCapExceeded`
+ *    失败整个 run。
+ *    run 级而非 node 级，因为 `report` 返回 `void`，没有可拒绝进去的地方。
+ * 4. **一次写**：`completed`、无 actor 字段。
+ */
+export declare function publishReport(state: EngineState, siteId: string, item: unknown, artifactId?: string): void;
+//# sourceMappingURL=engine-report.d.ts.map

package/vendor/dynamic-workflow/engine/engine-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-report.d.ts","sourceRoot":"","sources":["../../src/engine/engine-report.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CA2DN"}

package/vendor/dynamic-workflow/engine/engine-report.js

@@ -0,0 +1,151 @@
+/**
+ * engine.ts 顶到 oxlint max-lines 上限（400 行），把 `report()` 的发布路径（序列化探针、
+ * replay 去重、标签校验、两个上限、一次写）拆到本文件；公开面仍从 engine.ts 导出。
+ *
+ * 自由函数经 {@link EngineState} 接缝读写引擎状态；WorkflowEngine.report 只是薄委托。
+ */
+import { inputHash } from "./hash.js";
+import { REPORT_CAPS } from "../facade/report-caps.js";
+import { declaredPresetIds, isDeclaredPreset } from "./engine-artifacts.js";
+import { hashMismatch } from "./hash-mismatch.js";
+import { refToString, WorkflowError } from "./types.js";
+/**
+ * 发布一条中间结果（Boundary A 的 `report`）。同步、无返回值、无 driver 往返：
+ * 落一行 journal + 发一个事件就结束。
+ *
+ * 四件事，顺序是有讲究的：
+ *
+ * 1. **序列化探针先行**。用 `JSON.stringify` 一次拿到两样东西：item 到底能不能被 JSON
+ *    表示，以及它的字节数（上限的度量）。必须在 canonicalJson 之前——带环的 item 会让
+ *    canonicalJson 递归爆栈，那是一次崩溃而不是一次可读的失败。
+ * 2. **replay 命中即跳过**：不发事件、不重写记录。跳过之前先比对 inputHash，不一致按
+ *    纯度违约让 run 大声失败。这条比对是**防御性的**（一条报告派生自 journal 已经钉住的
+ *    值），但它是免费的，而这里的偏移意味着整个 replay 不可靠——Results 面板的读者绝不
+ *    应该在不知情的情况下看到那种东西。
+ * 3. **上限先于落库**：单条字节数、条数、run 级字节总数任一超出即 `ReportCapExceeded`
+ *    失败整个 run。
+ *    run 级而非 node 级，因为 `report` 返回 `void`，没有可拒绝进去的地方。
+ * 4. **一次写**：`completed`、无 actor 字段。
+ */
+export function publishReport(state, siteId, item, artifactId) {
+    if (state.isRunSettled())
+        return; // 与 log 同：结算之后不再受理
+    const ordinal = state.nextOrdinal(siteId);
+    const instance = { siteId, ordinal };
+    const serialized = probeReportItem(state, instance, item);
+    if (serialized === undefined)
+        return; // 探针已 failRun
+    // inputHash 刻意**只覆盖 item**，标签不进哈希：标签是站点上的编译期字面量，而 resume
+    // 要求脚本逐字节相同（script_hash），所以同一 (siteId, ordinal) 的标签不可能变。把它加进
+    // 哈希输入的唯一效果，是让**每一条**既有 journal 里的无标签 report 在 resume 时
+    // InputHashMismatch——一次没有任何收益的破坏性载荷形变。
+    const hash = inputHash(item);
+    // 只比对哈希，不读 item（docs/execution-engine.md「Reading the journal」）：resume 重放一个
+    // 报了 65,536 条的脚本时，每一次命中都去解一条 ≤1 MiB 的 item 再扔掉，是按总字节数付的钱。
+    const recorded = state.journal.getNode(state.runId, siteId, ordinal, { withResult: false });
+    if (recorded !== undefined) {
+        if (recorded.inputHash !== hash) {
+            state.failRun(hashMismatch(instance, recorded.inputHash, hash));
+            return;
+        }
+        return; // replay 去重：静默跳过（无事件、不重复 append）
+    }
+    // 标签在场：它必须已经被声明为**预置**产物。查在上限之前——一个指向不存在看板的标签
+    // 是脚本写错了，不是容量事件，两者混在一起会让错误码骗人。
+    // failRun 而不是拒绝，理由与 report 的两个上限完全相同：void 返回没有拒绝通道。
+    if (artifactId !== undefined && !isDeclaredPreset(state, artifactId)) {
+        state.failRun(new WorkflowError("ArtifactUndeclared", `report() tag "${artifactId}" is not a declared preset artifact ` +
+            `(at ${refToString(instance)}). Declare it once at the top of the script, e.g. ` +
+            `artifact.chart("${artifactId}", …), before tagging reports with it. Declared presets: ` +
+            `${declaredPresetIds(state).join(", ") || "(none)"}.`));
+        return;
+    }
+    if (!reserveReport(state, instance, serialized))
+        return;
+    state.journal.putNode({
+        runId: state.runId,
+        siteId,
+        ordinal,
+        kind: "report",
+        inputHash: hash,
+        status: "completed",
+        result: item,
+        // 打了标签的 report 行是「看板 = journal 的投影」这条不变式的落点：一个看板的每个点
+        // 就是一行 kind = report ∧ artifact_id = 该 id。
+        ...(artifactId === undefined ? {} : { artifactId }),
+    });
+    state.record({
+        type: "report",
+        instance,
+        item,
+        ...(artifactId === undefined ? {} : { artifactId }),
+    });
+}
+/**
+ * report 的**运行期 JSON 护栏**（编译期的可序列化诊断是 suspenders，这里是 belt）。
+ * 返回 item 的序列化文本；不可表示时 failRun 并返回 undefined。
+ *
+ * 为什么用 `JSON.stringify` 而不是 `canonicalJson`：canonicalJson 是**全函数**的（把
+ * undefined/函数静默折成 `"null"`，遇到环则递归爆栈），这正是它作为哈希输入该有的样子，
+ * 但作为护栏它会把一个残缺的 item 悄悄落进 journal。`JSON.stringify` 相反：环与 bigint
+ * 抛错、undefined/函数/symbol 返回 undefined——两种情形都能被抓成一次大声的失败。
+ *
+ * 错误码选 `DriverError` 而不是 `ReportCapExceeded`：这不是一个上限（上限是数量），而是
+ * 「item 不是 JSON」这条契约被破坏，而那条契约的正门是编译期诊断。走到这里说明有东西
+ * 绕过了正门（典型是经 `any` 造出的环），所以它是一次契约破裂而不是一次容量事件——
+ * 让 `ReportCapExceeded` 只表示上限，读者才能据码行动。
+ */
+function probeReportItem(state, instance, item) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(item);
+    }
+    catch (cause) {
+        state.failRun(new WorkflowError("DriverError", `report() item cannot be serialized to JSON (a cycle or a bigint) at ` +
+            `${refToString(instance)}. Report a plain JSON value.`, { cause }));
+        return undefined;
+    }
+    if (serialized === undefined) {
+        // JSON.stringify 对 undefined / 函数 / symbol 返回 undefined。
+        state.failRun(new WorkflowError("DriverError", `report() item is not a JSON value (undefined, a function or a symbol) at ` +
+            `${refToString(instance)}. Report a plain JSON value.`));
+        return undefined;
+    }
+    return serialized;
+}
+/**
+ * report 的三个上限（单条字节数、条数、run 级字节总数）。任一超出即 failRun 并返回 false。
+ *
+ * 顺序按「错在哪一条」：单条过大是这一条 item 的问题，与 run 攒了多少无关，所以先判；两个
+ * run 级上限在后，且都在计数之前——被拒的那条不进计数，失败信息里的数字才是真的。
+ */
+function reserveReport(state, instance, serialized) {
+    const bytes = utf8ByteLength(serialized);
+    if (bytes > REPORT_CAPS.maxItemSerializedBytes) {
+        state.failRun(new WorkflowError("ReportCapExceeded", `report() item at ${refToString(instance)} is ${bytes} bytes, over the ` +
+            `${REPORT_CAPS.maxItemSerializedBytes}-byte limit. Report a summary instead.`));
+        return false;
+    }
+    const tally = state.reportTally();
+    if (tally.count >= REPORT_CAPS.maxItemsPerRun) {
+        state.failRun(new WorkflowError("ReportCapExceeded", `This run already reported ${REPORT_CAPS.maxItemsPerRun} items, the maximum. ` +
+            `Report findings, not chatter.`));
+        return false;
+    }
+    if (tally.bytes + bytes > REPORT_CAPS.maxBytesPerRun) {
+        state.failRun(new WorkflowError("ReportCapExceeded", `report() item at ${refToString(instance)} would take this run's reports to ` +
+            `${tally.bytes + bytes} bytes, over the ${REPORT_CAPS.maxBytesPerRun}-byte limit per run. ` +
+            `Report summaries, and publish large results with artifact.file.`));
+        return false;
+    }
+    state.countReport(bytes);
+    return true;
+}
+/**
+ * 一个字符串的 UTF-8 字节数（report 单条上限的度量）。用 `TextEncoder`（ECMAScript/WHATWG
+ * 标准全局）而不是 `Buffer.byteLength`：本包保持零 node 内建依赖。上限论的是**字节**而非
+ * 字符——一份中文 findings 的字符数只有字节数的三分之一，按字符计会让上限形同虚设。
+ */
+function utf8ByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}

package/vendor/dynamic-workflow/engine/engine-resume.d.ts

@@ -0,0 +1,18 @@
+/**
+ * resume 分支从 journal 恢复的 run 级状态（docs/execution-engine.md「Resume by replay」与
+ * 「Reading the journal」）：结算次序闸、每个 actor 的已记录 ask 数、报告计数、产物状态。
+ *
+ * 拆出原因：engine.ts 顶到 oxlint max-lines 上限（400 行）。
+ *
+ * 节点行只读一次、只读要的列：工作行不带结果（次序闸与 ask 计数只看 kind / status / 坐标），
+ * 产物行带结果（成员族与版本记录在 `result` 上，且有界），报告行只数条数与字节、不读——一个
+ * run 可以有 65,536 条、1 GiB 的 item，恢复它们的计数不需要把任何一条读进内存。
+ */
+import type { EngineState, ReportTally } from "./engine-state.js";
+import { type ReplaySettleOrder } from "./replay-order.js";
+import type { AskScheduler } from "./scheduler.js";
+export declare function restoreFromJournal(state: EngineState, scheduler: AskScheduler): {
+    replaySettleOrder: ReplaySettleOrder;
+    reportTally: ReportTally;
+};
+//# sourceMappingURL=engine-resume.d.ts.map

package/vendor/dynamic-workflow/engine/engine-resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-resume.d.ts","sourceRoot":"","sources":["../../src/engine/engine-resume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAsC,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,YAAY,GACtB;IAAE,iBAAiB,EAAE,iBAAiB,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,CAwBpE"}

package/vendor/dynamic-workflow/engine/engine-resume.js

@@ -0,0 +1,38 @@
+/**
+ * resume 分支从 journal 恢复的 run 级状态（docs/execution-engine.md「Resume by replay」与
+ * 「Reading the journal」）：结算次序闸、每个 actor 的已记录 ask 数、报告计数、产物状态。
+ *
+ * 拆出原因：engine.ts 顶到 oxlint max-lines 上限（400 行）。
+ *
+ * 节点行只读一次、只读要的列：工作行不带结果（次序闸与 ask 计数只看 kind / status / 坐标），
+ * 产物行带结果（成员族与版本记录在 `result` 上，且有界），报告行只数条数与字节、不读——一个
+ * run 可以有 65,536 条、1 GiB 的 item，恢复它们的计数不需要把任何一条读进内存。
+ */
+import { rememberArtifactRow } from "./engine-artifacts.js";
+import { readReplayRows, recoverSettleOrder } from "./replay-order.js";
+export function restoreFromJournal(state, scheduler) {
+    const { workRows, artifactRows } = readReplayRows(state.journal, state.runId);
+    // 结算次序按本 run 自己的事件恢复（本闸是 replay 正确性的一部分，不是观察面：站点序号依
+    // 调用到达顺序，而扇出的到达顺序只有首生的结算次序能复现）。
+    const replaySettleOrder = recoverSettleOrder(state.journal, state.runId, [
+        ...workRows,
+        ...artifactRows,
+    ]);
+    scheduler.seedRecordedAsks(workRows);
+    // 产物状态与报告计数同席恢复：id 归属（种类、预置 spec）与已成功版本数全部由 journal 行派生，
+    // 所以崩溃恢复后第 3 版仍然是第 3 版，而不是从 1 重新数起。
+    for (const node of artifactRows) {
+        if (node.status !== "completed")
+            continue;
+        rememberArtifactRow(state, node.artifactId, node.result);
+    }
+    // 报告计数按 kind:"report" 的行恢复：上限是 run 级的，跨 resume 必须连续。条数是 count(*)，
+    // 字节数是 result_json 的字节和——SQLite 从行头读长度，一条 item 都不读出来。
+    return {
+        replaySettleOrder,
+        reportTally: {
+            count: state.journal.countNodes(state.runId, "report"),
+            bytes: state.journal.sumResultBytes(state.runId, "report"),
+        },
+    };
+}

package/vendor/dynamic-workflow/engine/engine-settlement.d.ts

@@ -0,0 +1,30 @@
+/**
+ * engine.ts 顶到 oxlint max-lines 上限（400 行），把 run 的三条终态路径
+ * （completed / stopped / errored）与它们共用的 finishRun
+ * 拆到本文件；公开面仍从 engine.ts 导出。
+ *
+ * 自由函数经 {@link EngineState} 接缝读写引擎状态；WorkflowEngine 的 complete / stop /
+ * failRun 只是薄委托。first-wins 由 `isRunSettled()` 守在每条路径的第一行。
+ */
+import type { EngineState } from "./engine-state.js";
+import type { RunStopReason } from "./types.js";
+import { WorkflowError } from "./types.js";
+/**
+ * 沙箱脚本成功返回顶层 artifact，结算为 completed。
+ *
+ * 脚本返回时仍可能有在飞 ask（`Promise.race` 的输家、没有 `await` 的 ask）。它们与 cancel
+ * 路径同款中止：driver 侧 cancelAsk、deferred 以 Cancelled reject、补发 node-settled(cancelled)。
+ * 不中止的后果是三重的：scheduler 的 liveNodes 永远握着节点、driver 侧 turn 继续烧 token、
+ * 事件日志里一个 node-dispatched 永远等不到它的 node-settled。
+ */
+export declare function settleCompleted(state: EngineState, artifact: unknown): void;
+/**
+ * 外部停止：中止在飞 ask（deferred 以 Cancelled reject、补发 node-settled(cancelled)），run
+ * 结算 `stopped(reason)`；已完结的 journal 条目保留（可 resume）。四个 reason 走同一条路：
+ * `user` / `model`（cancel 入口传进来的 initiator）、`interrupted`（harness 的沙箱故障）、
+ * `provider`（driver 经 `stopRun` 报上来的确定性模型侧错误）。`error` 只对后两者在场。
+ */
+export declare function settleStopped(state: EngineState, reason: RunStopReason, error?: WorkflowError, supersededBy?: string): void;
+/** run 级失败（脚本之错）：中止在飞 ask（以 run 错误 reject），run 结算 errored。 */
+export declare function settleFailed(state: EngineState, error: WorkflowError): void;
+//# sourceMappingURL=engine-settlement.d.ts.map

package/vendor/dynamic-workflow/engine/engine-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-settlement.d.ts","sourceRoot":"","sources":["../../src/engine/engine-settlement.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAkC,aAAa,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAW3E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,aAAa,EACrB,KAAK,CAAC,EAAE,aAAa,EACrB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAiBN;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAM3E"}