@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.0

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

@@ -0,0 +1,367 @@
+/**
+ * engine.ts 顶到 oxlint max-lines 上限（400 行），把**用户面产物**（`artifact.*`）的
+ * 发布 / 声明 / 准入 / 结算 / resume 恢复拆到本文件；公开面仍从 engine.ts 导出。
+ *
+ * ⚠ 术语：以下一律指**用户面产物**（脚本发布给用户看的产出），不是 RunSettlement.artifact。
+ * 自由函数经 {@link EngineState} 接缝读写引擎状态；WorkflowEngine 上的同名方法只是薄委托。
+ */
+import { canonicalJson, inputHash } from "./hash.js";
+import { ARTIFACT_CAPS } from "../facade/artifact-caps.js";
+import { isArtifactPresetOp, } from "../facade/registry.js";
+import { heldResolution } from "./replay-order.js";
+import { primaryArtifactId, primaryConflict, primaryConflictMessage, } from "./engine-artifacts-primary.js";
+import { validateArtifactSpec } from "./artifact-spec.js";
+import { hashMismatch } from "./hash-mismatch.js";
+import { refToString, WorkflowError } from "./types.js";
+/**
+ * 发布一个**内容产物**（`artifact.file` / `artifact.markdown`）。效应族：经 driver 拷字节进
+ * store，成功兑现 {@link ArtifactRef}，失败**可 catch 地拒绝**——脚本的门控习语是
+ * `try { await artifact.file(...) } catch { …让子代理补写… }`。
+ *
+ * 顺序：
+ * 1. `nextOrdinal` → journal 命中？命中即短路：比 inputHash，成功记录返回它的 ArtifactRef，
+ *    **失败记录按记录重新拒绝**（resume 是崩溃恢复，不是复验：一次失败的发布在恢复后仍然
+ *    是那次失败，重跑它会让脚本的 catch 分支走两次不同的路）。命中一律**不重发事件**（同 report）。
+ * 2. 未命中：种类归属 → id 数上限 → 版本数上限，三条都是节点级拒绝（有 promise 可拒）。
+ * 3. 版本号在 dispatch **之前**算好并传给 driver（store 的 toolCallId 里要带它，每版一份字节）。
+ * 4. `putNode(running)` → driver → 成功 `putNode(completed)` + `artifact-published`；
+ *    失败 `putNode(failed)` + `artifact-failed` → reject。
+ *
+ * 两条路都**不发任何节点生命周期事件**（node-queued / dispatched / settled）：产物站点在两张
+ * 图里都不是节点，一条 node-settled 落在这样的站点上会被投影归约进 `nodes[]`，在 run 面板里
+ * 变成一个无从解释的未知节点。
+ */
+export function publishContentArtifact(state, siteId, op, args) {
+    if (state.isRunSettled())
+        return Promise.reject(state.runError());
+    const ordinal = state.nextOrdinal(siteId);
+    const instance = { siteId, ordinal };
+    const id = args[0];
+    const payload = args[1];
+    // 实参形状的运行期护栏（编译期的字面量 id 诊断与 facade 类型是正门）：走到这里的非字符串
+    // 只可能是有东西绕过了编译。用 DriverError 而不是某个 Artifact* 码——让那些码只表示它们
+    // 各自的那件事（同 probeReportItem 对「item 不是 JSON」的取码论证）。
+    //
+    // 这两条**不落 journal 行、不发事件**，与下面所有失败路径不同。理由是它们是**确定性**的：
+    // 结论只由 args 决定，没有 driver 往返，resume 重跑同一个调用必然得到同一个拒绝，所以
+    // 不需要一行记录把它钉住（「settled failure 落库」那条要求针对的是 driver 执行过的、
+    // 下次未必再失败的那种）。何况这里根本没有 id 可写进 `artifact_id` 或事件——编一个出来
+    // 只会让读者以为真有那么一个产物。
+    if (typeof id !== "string" || id === "") {
+        return Promise.reject(new WorkflowError("DriverError", `artifact.${op}: id must be a non-empty string (at ${refToString(instance)}).`));
+    }
+    if (typeof payload !== "string") {
+        return Promise.reject(new WorkflowError("DriverError", op === "file"
+            ? `artifact.file: path must be a string (at ${refToString(instance)}).`
+            : `artifact.markdown: content must be a string (at ${refToString(instance)}).`));
+    }
+    // `opts.primary` 由**引擎**读：driver 对不认识的
+    // opts 键一律放行，而「全 run 至多一个 primary」是 run 级事实，只有引擎知道。非布尔值与上面
+    // 两条同属确定性护栏——不落行、不发事件。
+    const primaryOption = args[2]?.primary;
+    if (primaryOption !== undefined && typeof primaryOption !== "boolean") {
+        return Promise.reject(new WorkflowError("DriverError", `artifact.${op}: opts.primary must be a boolean (at ${refToString(instance)}).`));
+    }
+    const hash = inputHash({ args, id, op });
+    const recorded = state.journal.getNode(state.runId, siteId, ordinal);
+    if (recorded !== undefined) {
+        if (recorded.inputHash !== hash) {
+            const err = hashMismatch(instance, recorded.inputHash, hash);
+            state.failRun(err);
+            return Promise.reject(err);
+        }
+        // 与 ask / world 命中同规：释放点过 replay 次序闸（docs/execution-engine.md
+        // 「Replaying the settle order」）。发布是效应、脚本要 await 它，所以它也是一个能决定
+        // 后续续体次序的释放点；预置声明是同步 void，从不走这条路，也就从不占闸。
+        if (recorded.status === "completed") {
+            const record = recorded.result;
+            return heldResolution(state.holdForReplay, instance, () => ({
+                id: record.id,
+                version: record.version,
+            }));
+        }
+        if (recorded.status === "failed") {
+            return heldResolution(state.holdForReplay, instance, () => {
+                throw WorkflowError.fromJSON(recorded.error);
+            });
+        }
+        // status === "running"：崩溃于执行中，落到下面重新 live 执行（字节的拷贝是幂等的，
+        // 而版本号从**已 completed 的行数**派生，所以重跑不会跳号）。
+    }
+    // 粘着：这个 id 已经是 primary，则这一版也是，不管本次有没有再写 `primary`。
+    const idState = state.artifacts.get(id);
+    const primary = primaryOption === true || idState?.primary === true;
+    const admission = admitArtifact(state, id, op, primary);
+    if (admission !== undefined) {
+        return Promise.reject(settleArtifactFailure(state, instance, hash, { id, op }, admission));
+    }
+    const version = (idState?.versions ?? 0) + 1;
+    const publish = state.driver.executeArtifactPublish;
+    if (publish === undefined) {
+        // 装配没有 driver 侧的发布能力（纯 replay / 没接 store 的 fake）。**大声的一条命名失败**，
+        // 不是静默降级成「发布了一个空产物」——脚本看得见、节点以 failed 落库。
+        return Promise.reject(settleArtifactFailure(state, instance, hash, { id, op }, new WorkflowError("ArtifactStoreUnavailable", `Cannot publish "${id}": this host has no artifact store (at ${refToString(instance)}).`)));
+    }
+    state.journal.putNode({
+        runId: state.runId,
+        siteId,
+        ordinal,
+        kind: "artifact",
+        inputHash: hash,
+        status: "running",
+        artifactId: id,
+    });
+    const request = {
+        runId: state.runId,
+        siteId,
+        ordinal,
+        op,
+        id,
+        version,
+        ...(op === "file" ? { path: payload } : { content: payload }),
+        ...(args[2] === undefined ? {} : { opts: args[2] }),
+    };
+    return publish.call(state.driver, request).then((record) => settleArtifactPublish(state, instance, hash, { id, op, version, primary }, record), (cause) => {
+        const err = cause instanceof WorkflowError
+            ? cause
+            : new WorkflowError("DriverError", `Artifact publish failed: ${op} "${id}".`, {
+                cause,
+            });
+        throw settleArtifactFailure(state, instance, hash, { id, op }, err);
+    });
+}
+/**
+ * 声明一个**预置产物**（`artifact.chart` / `table` / `metrics` / `board`）。声明族：同步、
+ * 无返回值、**不经 driver**——一个声明没有可等的东西。
+ *
+ * 顺序：`nextOrdinal` → 命中即返回 → spec 形状校验
+ * → 同 id 既有声明？相同 canonical ⇒ 幂等 no-op（不落新行、不发事件）；不同 ⇒ failRun
+ * → 上限 → `putNode(completed)` + `artifact-published`。
+ *
+ * 三种失败（spec 非法 / 同 id 异 spec / 超上限）全是 failRun 而不是拒绝：void 返回没有拒绝
+ * 通道，与 `report` 的两个上限同一条论证。
+ */
+export function declarePresetArtifact(state, siteId, op, args) {
+    if (state.isRunSettled())
+        return; // 与 report / log 同
+    const ordinal = state.nextOrdinal(siteId);
+    const instance = { siteId, ordinal };
+    const id = args[0];
+    if (typeof id !== "string" || id === "") {
+        state.failRun(new WorkflowError("DriverError", `artifact.${op}: id must be a non-empty string (at ${refToString(instance)}).`));
+        return;
+    }
+    const spec = args[1];
+    const hash = inputHash({ args, id, op });
+    const recorded = state.journal.getNode(state.runId, siteId, ordinal);
+    if (recorded !== undefined) {
+        if (recorded.inputHash !== hash) {
+            state.failRun(hashMismatch(instance, recorded.inputHash, hash));
+            return;
+        }
+        return; // replay 去重：静默跳过（同 report）
+    }
+    const problem = validateArtifactSpec(op, spec);
+    if (problem !== undefined) {
+        state.failRun(new WorkflowError("ArtifactSpecInvalid", `Artifact "${id}" has an invalid spec (at ${refToString(instance)}): ${problem}`));
+        return;
+    }
+    const canonical = canonicalJson(spec);
+    const idState = state.artifacts.get(id);
+    if (idState !== undefined) {
+        if (idState.kind !== op) {
+            state.failRun(new WorkflowError("ArtifactKindMismatch", `Artifact id "${id}" is already a ${idState.kind} and cannot be declared as a ${op} ` +
+                `(at ${refToString(instance)}). An id belongs to one artifact kind for the whole run; ` +
+                `use a different id.`));
+            return;
+        }
+        if (idState.spec === canonical)
+            return; // 幂等 no-op：不落新行、不发事件
+        state.failRun(new WorkflowError("ArtifactRedeclared", `Artifact "${id}" was already declared with a different spec (at ${refToString(instance)}). ` +
+            `The spec for one id must stay identical (an identical re-declaration is a no-op); ` +
+            `declare it once at the top of the script.`));
+        return;
+    }
+    // `primary` 进 canonical spec，所以同 id 改旗子是 ArtifactRedeclared（上面已经拒了）；这里只剩
+    // **新** id 想当 primary 而别的 id 已经是——预置族没有拒绝通道，failRun。
+    const wantsPrimary = spec.primary === true;
+    const holder = wantsPrimary ? primaryArtifactId(state) : undefined;
+    if (holder !== undefined && holder !== id) {
+        state.failRun(new WorkflowError("ArtifactPrimaryConflict", primaryConflictMessage(id, holder, `declare "${id}" without primary`, instance)));
+        return;
+    }
+    if (state.artifacts.size >= ARTIFACT_CAPS.maxArtifactsPerRun) {
+        state.failRun(new WorkflowError("ArtifactCapExceeded", `Cannot declare "${id}": this run already has ${ARTIFACT_CAPS.maxArtifactsPerRun} artifact ` +
+            `ids, the maximum. Reuse an existing id or publish fewer artifacts.`));
+        return;
+    }
+    // 声明是**一次写**（同 report）：准入与结算之间没有 driver 调用，没有什么能在中间失败。
+    const record = presetRecord(id, op, spec);
+    state.artifacts.set(id, {
+        kind: op,
+        spec: canonical,
+        versions: 1,
+        ...(wantsPrimary ? { primary: true } : {}),
+    });
+    state.journal.putNode({
+        runId: state.runId,
+        siteId,
+        ordinal,
+        kind: "artifact",
+        inputHash: hash,
+        status: "completed",
+        result: record,
+        artifactId: id,
+    });
+    state.record({ type: "artifact-published", instance, artifact: record });
+}
+/**
+ * 内容产物的准入：种类归属 → id 数上限 → 版本数上限。返回拒绝理由，`undefined` 即放行。
+ *
+ * 三条全是**节点级**拒绝（内容成员有 promise 可拒），与预置族里同名的三条形成对照——
+ * 那一族只能 failRun。同一个事实、两个通道，差别在返回类型而不是严重程度。
+ */
+function admitArtifact(state, id, op, primary) {
+    const idState = state.artifacts.get(id);
+    if (idState !== undefined && idState.kind !== op) {
+        return new WorkflowError("ArtifactKindMismatch", `Artifact id "${id}" is already a ${idState.kind} and cannot be published as a ${op}. An id ` +
+            `belongs to one artifact kind for the whole run (publishing the same id again creates a ` +
+            `new version, and a version cannot change what it is); use a different id.`);
+    }
+    // primary 冲突排在上限之前：一个想当交付物的 id 被拒，理由该是「已经有交付物了」，不是「满了」。
+    const holder = primaryConflict(state, id, primary);
+    if (holder !== undefined) {
+        return new WorkflowError("ArtifactPrimaryConflict", primaryConflictMessage(id, holder, `publish "${id}" without primary`, undefined));
+    }
+    if (idState === undefined && state.artifacts.size >= ARTIFACT_CAPS.maxArtifactsPerRun) {
+        return new WorkflowError("ArtifactCapExceeded", `Cannot publish "${id}": this run already has ${ARTIFACT_CAPS.maxArtifactsPerRun} artifact ` +
+            `ids, the maximum. Publish a new version of an existing id instead.`);
+    }
+    if (idState !== undefined && idState.versions >= ARTIFACT_CAPS.maxVersionsPerArtifact) {
+        return new WorkflowError("ArtifactVersionCapExceeded", `Artifact "${id}" already has ${idState.versions} versions, the maximum of ` +
+            `${ARTIFACT_CAPS.maxVersionsPerArtifact}. Publish the final content in fewer versions.`);
+    }
+    return undefined;
+}
+/**
+ * 内容产物发布成功：落 completed 行 + 记账 + 发 `artifact-published`，返回脚本要的 ref。
+ *
+ * 身份（id / 种类 / 版本号）一律取**引擎自己算的那份**（`issued`），而不是 driver 回来的
+ * 记录里的同名字段：版本号是引擎按 journal 派生并下发的，让它绕 driver 走一圈再读回来，
+ * 只会多出一个可以不一致的地方。driver 的记录负责它真正拥有的东西——uri / bytes /
+ * contentType / sourcePath——那些整条原样落 journal。
+ */
+function settleArtifactPublish(state, instance, hash, issued, record) {
+    if (state.isRunSettled())
+        throw state.runError();
+    // 准入与结算之间隔着一次 driver 往返：两个并发的 primary 发布都能过准入。结算时再查一次，
+    // 输的那个走失败路径——failed 行不认领旗子，所以 journal 里永远不会有两个 completed 的 primary。
+    const holder = primaryConflict(state, issued.id, issued.primary);
+    if (holder !== undefined) {
+        throw settleArtifactFailure(state, instance, hash, issued, new WorkflowError("ArtifactPrimaryConflict", primaryConflictMessage(issued.id, holder, `publish "${issued.id}" without primary`, instance)));
+    }
+    // 旗子由引擎盖章：driver 的记录只负责它真正拥有的东西（uri / bytes / contentType / sourcePath）。
+    const stored = issued.primary ? { ...record, primary: true } : record;
+    state.journal.putNode({
+        runId: state.runId,
+        siteId: instance.siteId,
+        ordinal: instance.ordinal,
+        kind: "artifact",
+        inputHash: hash,
+        status: "completed",
+        result: stored,
+        artifactId: issued.id,
+    });
+    state.artifacts.set(issued.id, {
+        kind: issued.op,
+        versions: issued.version,
+        ...(issued.primary ? { primary: true } : {}),
+    });
+    state.record({ type: "artifact-published", instance, artifact: stored });
+    return { id: issued.id, version: issued.version };
+}
+/**
+ * 内容产物发布失败：落 failed 行 + 发 `artifact-failed`，返回要抛出的错误。
+ *
+ * 落库是重放健全性的既有要求（settled failure 必须在 journal 里），否则 resume 会把一次
+ * 已经被脚本 catch 过的失败重跑一遍——那正是「resume 是崩溃恢复不是复验」要防的。
+ *
+ * node-settled 的读者
+ * 会把它归约进 `nodes[]` 并按 site id 去图里找对应节点，而产物站点不进任何图——那会在 run
+ * 面板上变成一个无从解释的未知节点。`artifact-failed` 带着渲染一张失败卡需要的东西
+ * （id / 种类 / 结构化错误），不冒充一步工作。成功那侧同理只发 `artifact-published`。
+ */
+function settleArtifactFailure(state, instance, hash, issued, error) {
+    const json = error.toJSON();
+    state.journal.putNode({
+        runId: state.runId,
+        siteId: instance.siteId,
+        ordinal: instance.ordinal,
+        kind: "artifact",
+        inputHash: hash,
+        status: "failed",
+        error: json,
+        artifactId: issued.id,
+    });
+    state.record({
+        type: "artifact-failed",
+        instance,
+        id: issued.id,
+        op: issued.op,
+        error: json,
+    });
+    return error;
+}
+/**
+ * resume 恢复：把 journal 里一行**已完成**的产物记录并进内存状态。
+ *
+ * **只有 completed 行才认领 id**：失败的发布不占 id、不占种类、不占版本。这不只是图简洁——
+ * 失败行的 `result` 是空的，种类无从恢复，若让 live 那一侧认领而 resume 那一侧认领不了，
+ * 同一个脚本在崩溃前后就会得到两套上限账。种类冲突另有编译期诊断把守，运行期这条
+ * （`ArtifactKindMismatch`）管的是真正发布成功过的那些 id。
+ */
+export function rememberArtifactRow(state, id, result) {
+    if (id === undefined || id === "")
+        return;
+    const record = (result ?? undefined);
+    if (record?.kind === undefined)
+        return;
+    const existing = state.artifacts.get(id);
+    const spec = record.spec === undefined ? existing?.spec : canonicalJson(record.spec);
+    const primary = record.primary === true || existing?.primary === true;
+    state.artifacts.set(id, {
+        kind: record.kind,
+        ...(spec === undefined ? {} : { spec }),
+        versions: (existing?.versions ?? 0) + 1,
+        ...(primary ? { primary: true } : {}),
+    });
+}
+/** 该 id 是否已被声明为**预置**产物（`report` 标签的合法目标）。 */
+export function isDeclaredPreset(state, id) {
+    const idState = state.artifacts.get(id);
+    return idState !== undefined && isArtifactPresetOp(idState.kind);
+}
+/** 已声明的预置 id（字典序）——只用于把 `ArtifactUndeclared` 的消息写得能照做。 */
+export function declaredPresetIds(state) {
+    return [...state.artifacts.entries()]
+        .filter(([, idState]) => isArtifactPresetOp(idState.kind))
+        .map(([id]) => id)
+        .sort();
+}
+/**
+ * 预置声明的落库记录。`title` / `description` 从 spec 里**提上来**：卡片的读者（run 侧板、
+ * 通知、中枢）只拿到这条记录，不该为了显示一个标题去解 spec；spec 仍原样保留，渲染器要
+ * 完整形状。版本恒为 1——声明没有版本，它只有一次。
+ */
+function presetRecord(id, op, spec) {
+    const options = (spec ?? {});
+    return {
+        id,
+        kind: op,
+        version: 1,
+        ...(typeof options.title === "string" ? { title: options.title } : {}),
+        ...(typeof options.description === "string" ? { description: options.description } : {}),
+        spec,
+        ...(options.primary === true ? { primary: true } : {}),
+    };
+}

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

@@ -0,0 +1,90 @@
+/**
+ * 引擎构造配置（{@link EngineConfig}）。定义从 engine.ts 迁到本文件：那个文件顶到 oxlint
+ * max-lines 上限（400 行），而这份配置是纯类型、只被构造函数读一遍。公开面不变——engine.ts
+ * 原地再导出它，src/index.ts 与 harness 的引用路径逐字不动。
+ */
+import type { RunLaunchConfig } from "./engine-launch.js";
+import type { AskSpec, Caps, ImportedRunCache, ValidateFn, WorkflowDriver } from "./types.js";
+/** 引擎构造配置。 */
+export interface EngineConfig {
+    runId: string;
+    driver: WorkflowDriver;
+    caps: Caps;
+    /**
+     * 每 ask 站点的静态规格（typed + schema）。**必须覆盖脚本里的每一个 ask 站点**——
+     * 站点表与 schema 合成来自同一次编译，因此缺席只可能是接线错误，引擎按硬错误处理
+     * （MissingAskSpec）。untyped 站点要显式记为 `{ typed: false }`。
+     */
+    askSpecs: ReadonlyMap<string, AskSpec>;
+    /** 注入的 schema 校验器（核心不 import schema 实现）。 */
+    validate: ValidateFn;
+    /**
+     * 站点 → 出生阶段名的编译期表（`collectSitePhases`，docs/execution-engine.md「Identity: sites,
+     * ordinals, phases」）。铸造实例时**词法优先**：站点在表里就戳表里的阶段，不在表里（被两处调用的
+     * helper、首个标记之前的调用、老编译产物）才退回脚本最近经过的标记。缺席等于空表。
+     */
+    sitePhases?: ReadonlyMap<string, string>;
+    /** run 元数据（落 dwf_run，仅在本次 createRun 时写入；resume 时不覆写记录）。 */
+    scriptText?: string;
+    /**
+     * run 的展示名（`CreateWorkflow` 的可选 `input.name`）。引擎不读它，只在建 run 时随
+     * `scriptText` 一起落库——宿主的枚举面据它给 run 起标签。见 {@link RunRecord.name}。
+     */
+    name?: string;
+    /**
+     * 脚本文本的哈希。resume 时与 journal 记录里的值比对：两侧都有且不同即拒绝本次 resume
+     * （V1 的 resume 只对逐字节相同的脚本有效）。
+     */
+    scriptHash?: string;
+    /**
+     * 本次 run 的实参（已校验回填）。引擎不读它，只在建 run 时随 `scriptText` 一起落库；
+     * 沙箱侧的注入走 harness 的 spawn payload，不经引擎。见 {@link RunRecord.args}。
+     */
+    args?: Record<string, unknown>;
+    parentSessionId?: string;
+    cwd?: string;
+    /**
+     * 发起 run 的 CreateWorkflow 工具调用 id（见 {@link RunRecord.toolCallId}）。
+     * 引擎不读它，只随其余元数据在 createRun 时落库。
+     */
+    toolCallId?: string;
+    /**
+     * 本次 run 修订自哪个前驱 run（见 {@link RunRecord.resumedFrom}）。引擎不读它，
+     * 只随其余元数据在 createRun 时落库——导入缓存的构建在 run service，不在核心。
+     */
+    resumedFrom?: string;
+    /**
+     * 发起 run 那一轮的锚点。引擎不读它，只在建 run 那一世
+     * 紧跟首条 `run-started` 记一条 `run-launched`；resume 命中既有行时不再记（锚点跨生命周期唯一）。
+     * `phaseNames` 随锚点同车：脚本声明的阶段表，引擎同样不读，只落 journal。`phaseAlongside`
+     * 与它按位置对齐（下标指向同一张表），同车同规。
+     * `subagentModel` 也同车：本 run 子代理的选型（规范 picker 串），引擎同样不读——模型面整个
+     * 在宿主侧（bootstrap 的 workflow-actor-model.ts），宿主从这条事件读回它，零 SQL。
+     * `scriptPath` 同车同规：本 run 的脚本来自哪个文件（绝对路径），引擎不读，宿主从这条事件
+     * 读回它交给模型面。
+     */
+    launch?: RunLaunchConfig;
+    /**
+     * 建 run 时的用量起点：前驱 run 的 `spentTokens`。amend 路径给出，全新 submit 缺席（= 从零起账），
+     * resume 路径给了也无用——命中既有行时用量从行里恢复。
+     *
+     * 语义是「本 run 报的是整条 lineage 的花费」：每个前驱的数字本身已是累计值，所以链式修订
+     * 按构造求和，没人需要走 `resumed_from` 链。命中缓存不再加钱（那笔账就在这个继承值里），
+     * 只有本次现跑的 live turn 往上加。
+     */
+    inheritedTokens?: number;
+    /**
+     * amend-resume 的导入缓存（{@link ImportedRunCache}）。**纯数据注入**——核心因此仍是
+     * 零 I/O 的确定性状态机：读前驱 journal、走 `resumed_from` 链、解析转录源，全部发生在
+     * run service，引擎只拿到一张构建好的表并按运行期身份（actor 名 + persona、
+     * `{op,args}` 内容 + 出现序）比对。缺席即本次不是修订续跑。
+     */
+    importedCache?: ImportedRunCache;
+    /**
+     * 时钟注入。核心本身不读时钟；唯一的读者是留白（docs/execution-engine.md「Holes」）——停驻时刻
+     * `since` 与补全时刻 `filledAt` 是给读者算「等了多久」用的观察值，不进任何决策、不进
+     * inputHash、replay 不比对它。缺省 `Date.now`；测试注入定值。
+     */
+    now?: () => number;
+}
+//# sourceMappingURL=engine-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine-config.d.ts","sourceRoot":"","sources":["../../src/engine/engine-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9F,cAAc;AACd,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,IAAI,CAAC;IACX;;;;OAIG;IACH,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,EAAE,UAAU,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB"}

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

@@ -0,0 +1,6 @@
+/**
+ * 引擎构造配置（{@link EngineConfig}）。定义从 engine.ts 迁到本文件：那个文件顶到 oxlint
+ * max-lines 上限（400 行），而这份配置是纯类型、只被构造函数读一遍。公开面不变——engine.ts
+ * 原地再导出它，src/index.ts 与 harness 的引用路径逐字不动。
+ */
+export {};

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

@@ -0,0 +1,116 @@
+/**
+ * 留白（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 行）。
+ */
+import type { EngineState } from "./engine-state.js";
+import type { AskSpec, InstanceRef, WorkflowError } from "./types.js";
+/**
+ * `hole-reached` 与通知上 prompt 的上限（字符）：与 escalation 通知的 question / context 同一
+ * 把尺（docs/dynamic-workflow/transcript-and-notifications.md）。超出的截断并以 `…` 收尾。
+ */
+export declare const HOLE_PROMPT_MAX_CHARS = 4000;
+/**
+ * 一次补全（docs/execution-engine.md「The engine's part」）。`code` 不是主代理写的、也不是
+ * harness 拼的：它是**有效脚本**自己 lowering 出的 `holeBodies[siteId]`，与脚本其余部分走同样
+ * 的两遍（按节点身份改写站点、再 transpile），所以现补与日后重放执行的是逐字节相同的文本。
+ * 规格表与阶段表是有效脚本的：原表的超集，新站点都是这次补全写下的（run service 已校验）。
+ * 引擎不解析站点 id：留白 id 是名字键，对引擎只是一个串。
+ */
+export interface HoleFill {
+    siteId: string;
+    /** 有效脚本的 `holeBodies[siteId]`：`(async () => { … })` 的文本。 */
+    code: string;
+    /** 有效脚本（两列同一笔写回 run 行）。 */
+    script: {
+        text: string;
+        hash: string;
+    };
+    /** 有效脚本的 ask 规格表（原表的超集）。 */
+    askSpecs: ReadonlyMap<string, AskSpec>;
+    /** 有效脚本的站点 → 词法出生阶段表。 */
+    sitePhases: ReadonlyMap<string, string>;
+    /** 有效脚本的阶段表，留白按名字占位（`hole-filled` 原样携带）。 */
+    phaseNames: string[];
+    /** `phaseNames` 里仍未补全的留白下标。 */
+    holes?: number[];
+    /** 补全它的会话。 */
+    filledBy?: string;
+    /** 这次补全为没有草稿的 run 铸下的草稿路径（原样进 `hole-filled`，见事件字段注释）。 */
+    scriptPath?: string;
+}
+/**
+ * `fillHole` 的结果。两条 no-op 都**不写不发**：`not_waiting`——这个站点没有停驻的分支、本世也
+ * 没记住过它的代码；`settled`——run 已结算。
+ */
+export type FillHoleResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "not_waiting" | "settled";
+};
+/** 一处仍在等的留白（快照投影用，docs/execution-engine.md「The run snapshot」）。 */
+export interface OpenHole {
+    siteId: string;
+    ordinal: number;
+    name: string;
+    /** 停驻时刻（epoch 毫秒），读者据它算「等了多久」。 */
+    since: number;
+}
+/** 一处本世已补全的留白。 */
+export interface FilledHole {
+    siteId: string;
+    filledAt: number;
+    filledBy?: string;
+}
+/** 引擎的留白状态：按站点的停驻表与本世的补全记忆。纯内存、随引擎实例而生，resume 从空表起。 */
+export declare class HoleRegistry {
+    private readonly now;
+    /** 站点 → 停在它下面的分支（一个站点可以同时停着好几个序号）。 */
+    private readonly parked;
+    /** 站点 → 本世记住的补全（后到的 `hole` 直接作答、不停驻）。 */
+    private readonly filled;
+    constructor(now: () => number);
+    /** 站点已补全时返回记住的代码，否则 undefined。 */
+    remembered(siteId: string): string | undefined;
+    /** 把一个分支停在站点下，返回它的 promise。 */
+    park(instance: InstanceRef, name: string): Promise<{
+        code: string;
+    }>;
+    /** 这个站点是否有停驻的分支或已记住的补全（`fillHole` 的 not_waiting 判据的反面）。 */
+    isWaitingOrFilled(siteId: string): boolean;
+    /** 现在的时刻（epoch 毫秒）：`hole-filled` 的 `filledAt` 与记忆里的同一个瞬间。 */
+    clock(): number;
+    /** 记住补全并放行站点下的每一个分支。 */
+    release(siteId: string, code: string, filledAt: number, filledBy: string | undefined): void;
+    /** run 结算：停驻的分支一律以结算错误拒绝（与 ask 的取消同姿态）；补全记忆保留。 */
+    rejectAll(error: WorkflowError): void;
+    open(): OpenHole[];
+    filledList(): FilledHole[];
+}
+/** 记录前把 prompt 截到上限（超出的以 `…` 收尾，截后总长恰为上限）。 */
+export declare function boundHolePrompt(prompt: string): string;
+/**
+ * Boundary A 的 `hole`：铸序号（`nextOrdinal` 同时盖出生阶段）、停驻、记 `hole-reached`。
+ * **先停驻再记事件**：事件经 driver.emit 同步扇出，一个在 emit 里同步补全的监听者必须能命中
+ * 停驻表，否则它拿到的是 `not_waiting`。已补全的站点以记住的代码立刻作答，不停驻、不记事件
+ * ——resume 重放有效脚本时 shim 本就不过线，这里只是引擎侧的同一条规则。
+ */
+export declare function reachHole(state: EngineState, holes: HoleRegistry, siteId: string, name: string, prompt: string | undefined): Promise<{
+    code: string;
+}>;
+/**
+ * `fillHole` 的方法体（docs/execution-engine.md「The engine's part」）：一个同步步骤里——换规格表
+ * 与阶段表（调用方负责，见 `swapTables`）、写有效脚本、记 `hole-filled`、记住代码、放行停驻的
+ * 每一个分支。两条 no-op 不写不发。
+ */
+export declare function fillHole(state: EngineState, holes: HoleRegistry, fill: HoleFill, swapTables: (askSpecs: ReadonlyMap<string, AskSpec>, sitePhases: ReadonlyMap<string, string>) => void): FillHoleResult;
+//# sourceMappingURL=engine-holes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine-holes.d.ts","sourceRoot":"","sources":["../../src/engine/engine-holes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAK1C;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,4BAA4B;IAC5B,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,yBAAyB;IACzB,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,4CAA4C;IAC5C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAA;CAAE,CAAC;AAE7F,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kBAAkB;AAClB,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgBD,uDAAuD;AACvD,qBAAa,YAAY;IAMX,OAAO,CAAC,QAAQ,CAAC,GAAG;IALhC,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;gBAE/B,GAAG,EAAE,MAAM,MAAM;IAE9C,kCAAkC;IAClC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI9C,+BAA+B;IAC/B,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAQpE,2DAA2D;IAC3D,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI1C,6DAA6D;IAC7D,KAAK,IAAI,MAAM;IAIf,wBAAwB;IACxB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAO3F,kDAAkD;IAClD,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAMrC,IAAI,IAAI,QAAQ,EAAE;IAelB,UAAU,IAAI,UAAU,EAAE;CAO3B;AAED,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAc3B;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE,CACV,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KACpC,IAAI,GACR,cAAc,CAiBhB"}