@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.2

package/vendor/dynamic-workflow/engine/imported-cache.js

@@ -0,0 +1,244 @@
+/**
+ * amend-resume 导入缓存的**消费态**。
+ *
+ * 注入的 {@link ImportedRunCache} 是调用方构建的只读数据——run service 读前驱 journal 得到它，
+ * 崩溃后 resume 用同一个纯函数重建同一张表。所以「消费到哪了」不能就地写回那张表，必须是引擎
+ * 自己的状态：本模块就是这份状态，以及围绕它的全部判定（命中 / 分歧 / 种子）。
+ *
+ * 从 scheduler.ts 与 engine.ts 拆出来，理由同当初 scheduler 从 engine 拆出来：三个文件各自
+ * 聚焦、可读，且满足单文件行数上限。
+ */
+import { canonicalJson } from "./hash.js";
+import { personaIdentity } from "./persona.js";
+/**
+ * 一个已附着候选的 actor 的导入消费态：消费游标 + 分歧标志。
+ *
+ * **分歧单调**：`diverged` 一旦为真永不回头查缓存，导入后缀弃置不可复活。
+ */
+export class ImportedActorState {
+    candidate;
+    /** 已消费的导入条目数 = 下一个可命中的 actorSeq（也是转录截断边界的下标 + 1）。 */
+    consumed = 0;
+    diverged = false;
+    /**
+     * 「续跑前驱在飞 ask」的那个 seq（没有续跑即缺席）。至多一个：续跑本身就是分歧，
+     * 分歧单调，所以第二次不会再有。
+     */
+    carriedSeq;
+    constructor(candidate) {
+        this.candidate = candidate;
+    }
+    /**
+     * fresh ask 在 seq 上问缓存：命中返回条目（并推进游标），否则置分歧并返回 undefined。
+     *
+     * 两种不命中同等处理：哈希不符（指令变了）与 `seq >= entries.length`（新脚本在此 actor 上
+     * 扩了新 ask）。分歧的**级联**是免费且动态的——上游 ask 转 live 拿到新结果，下游用它插值出的
+     * 指令哈希必变，于是下游自动分歧，不需要任何显式传播。
+     *
+     * 本方法只在导入缓存**开着**时被调用（关门后走 {@link takeIfPure}），所以未命中时可以谈续跑。
+     */
+    take(seq, hash) {
+        if (this.diverged)
+            return undefined;
+        const entry = this.candidate.entries[seq];
+        if (entry === undefined || entry.inputHash !== hash) {
+            this.diverge(seq, hash, true);
+            return undefined;
+        }
+        this.consumed = seq + 1;
+        return entry;
+    }
+    /**
+     * 缓存关闭后的问法：只有**纯**条目（前驱记下 `worldToolCalls === 0`）还能命中。纯 ask 只依赖指令与
+     * 转录前缀——两者都在哈希链里——与工作区无关，所以关门不影响它的答案。碰过外部世界的条目即便同哈希
+     * 也不给：它读过的工作区可能已被改写；这个 ask 转 live，actor 从此分歧（转录不再与前驱一致，
+     * 后缀条目不可复活）。没有 stats、或 stats 里没有这个键的老条目按「碰过」处理（保守）。
+     *
+     * 关门后同样不续跑在飞 ask：那半场转录里全是前驱对**旧工作区**的观察，与带工具的条目同理。
+     */
+    takeIfPure(seq, hash) {
+        if (this.diverged)
+            return undefined;
+        const entry = this.candidate.entries[seq];
+        if (entry === undefined || entry.inputHash !== hash || entry.stats?.worldToolCalls !== 0) {
+            this.diverge(seq, hash, false);
+            return undefined;
+        }
+        this.consumed = seq + 1;
+        return entry;
+    }
+    /**
+     * 该 seq 的 ask 的答案是否**读自前驱的转录**：是则返回持有它的会话，否则 undefined。
+     *
+     * 成立当且仅当此刻仍未分歧、且游标已越过该 seq——分歧单调、准入按 seq 升序，所以这恰好是
+     * 「这一条被导入消费了」。两条路径各在判定之后立刻问：fresh ask 在 {@link take} 命中之后，
+     * 修订 run 的 resume 在 {@link reconcileRecorded} 之后（结算次序闸可能把事件推迟到同一个
+     * actor 更后的行已经置了分歧的时候，那时再问就会把一条导入行说成本 run 自己跑的）。
+     */
+    sourceSessionAt(seq) {
+        return !this.diverged && seq < this.consumed
+            ? this.candidate.transcriptSourceSessionId
+            : undefined;
+    }
+    /** 该 seq 的 ask 是否续跑了前驱的在飞 ask（调度器据此决定 stats 记不记 worldToolCalls）。 */
+    carriedAt(seq) {
+        return this.carriedSeq === seq;
+    }
+    /**
+     * 据一行**已记录**的 ask 重推分歧状态（修订 run 崩溃后 resume 时用）。
+     *
+     * 分歧状态不落库，而修订 run 的 resume 会把导入缓存整表重建。若不据 journal 行重推分歧点，
+     * 一个在原次执行中已于 seq k 分歧的 actor，其 seq k+n 的 fresh ask 可能恰好撞上导入条目的
+     * 哈希而被**错误导入**——那等于把一段与本 run 实际转录无关的历史塞回来。逐 seq 拿记录行的
+     * inputHash 与导入条目比对，恰好重建了原次执行当时的判定（准入按 seq 升序，hold 规则保证
+     * 这一点），因此这个重推是精确的，不是保守近似。`wasLive` 补上哈希看不见的那一种 live
+     * （缓存关闭后带工具的 ask，见 scheduler 的 tryImportedSettle）。
+     *
+     * `queuedBeforeClose` 是续跑判定的那一半事实：续跑与该 ask 的 `node-queued` 在准入的同一个
+     * 同步片里发生，所以「当时门开着」等价于「这条 node-queued 早于第一条 import-cache-closed」
+     * （见 engine-world.ts 的 recoverImportClosure）。必须精确——错判成续跑会让 seedActorTranscript
+     * 往一个**已经分歧**的会话里多抄一段前驱消息（driver 的幂等判据只看目标够不够长）。
+     */
+    reconcileRecorded(seq, recordedHash, wasLive, queuedBeforeClose) {
+        if (this.diverged)
+            return;
+        // 缓存关闭之后，一个带工具 actor 的 ask 即便与导入
+        // 条目同哈希也是 live 跑的——按哈希算成「已消费」会让种子边界取自前驱条目，而本会话的
+        // 真实转录在那个位置根本不是那些消息。live 与否是事件里的事实（node-queued），不是哈希
+        // 能推出来的。
+        if (wasLive) {
+            this.diverge(seq, recordedHash, queuedBeforeClose);
+            return;
+        }
+        const entry = this.candidate.entries[seq];
+        if (entry === undefined || entry.inputHash !== recordedHash) {
+            // 没 live 过的行不可能是续跑（续跑的 ask 一定被派发过，一定有 node-queued）。
+            this.diverged = true;
+            return;
+        }
+        this.consumed = Math.max(this.consumed, seq + 1);
+    }
+    /**
+     * 分歧 actor 的会话种子：源会话 + 复制多少条消息 + 承袭的模型 pin。
+     *
+     * 边界取**最后一条被消费**的导入条目的记账值：在 seq k 分歧意味着 0..k-1 的问答都已按缓存
+     * 结算，新会话要接着的正是那 k 次完整交换之后的位置（含它们的 repair / nudge 轮）。
+     * 一条也没消费就没有种子——全新会话、全新模型解析、不带 pin：pin 是为「转录接续下不静默
+     * 换模型」存在的，没有接续就没有它的用武之地。
+     *
+     * **续跑是例外**：边界改取 `inFlight.messageBoundary`（前驱整个会话），因此一条都没消费也有
+     * 种子——那正是「扇出第一轮在飞时被修订」的形状。
+     */
+    seed() {
+        const inFlight = this.candidate.inFlight;
+        if (this.carriedSeq !== undefined && inFlight !== undefined) {
+            return this.seedAt(inFlight.messageBoundary);
+        }
+        if (this.consumed === 0)
+            return undefined;
+        const last = this.candidate.entries[this.consumed - 1];
+        if (last === undefined)
+            return undefined;
+        return this.seedAt(last.messageBoundary);
+    }
+    /**
+     * 置分歧，并在此顺带判定这次未命中是不是**续跑前驱的在飞 ask**。
+     *
+     * 续跑的四个条件缺一不可：此前未分歧（否则本 actor 的转录早已不是前驱那条）、`seq` 恰在
+     * 前缀之后（在飞 ask 的位置）、整个前缀都已消费、指令哈希与在飞 ask 相符。`cacheOpen`
+     * 是第五个：关门之后那半场转录只是对旧工作区的观察，不比缓存的 world 读取更可信。
+     */
+    diverge(seq, hash, cacheOpen) {
+        const inFlight = this.candidate.inFlight;
+        if (cacheOpen &&
+            inFlight !== undefined &&
+            seq === this.candidate.entries.length &&
+            this.consumed === seq &&
+            inFlight.inputHash === hash) {
+            this.carriedSeq = seq;
+        }
+        this.diverged = true;
+    }
+    seedAt(messageCount) {
+        const seed = {
+            sourceSessionId: this.candidate.transcriptSourceSessionId,
+            messageCount,
+        };
+        if (this.candidate.resolvedModel !== undefined)
+            seed.resolvedModel = this.candidate.resolvedModel;
+        return seed;
+    }
+}
+/**
+ * world 节点的导入队列消费态：每个内容哈希一个游标（第 n 次出现对第 n 条记录）。
+ * 与 {@link ImportedActorState} 同理，游标是引擎的状态，注入的队列保持只读。
+ */
+export class ImportedWorldQueue {
+    world;
+    cursors = new Map();
+    constructor(world) {
+        this.world = world;
+    }
+    /** 取该内容哈希的下一条记录，耗尽或从未记录即 undefined（调用方转 live）。 */
+    take(hash) {
+        const queue = this.world.get(hash);
+        if (queue === undefined)
+            return undefined;
+        const cursor = this.cursors.get(hash) ?? 0;
+        const entry = queue[cursor];
+        if (entry === undefined)
+            return undefined;
+        this.cursors.set(hash, cursor + 1);
+        return entry;
+    }
+}
+/**
+ * 为一个刚建出的 actor 找导入候选：按**有效名**查表，规范化 persona 一致才收。
+ *
+ * persona 比对用 `canonicalJson`——它跳过 undefined 成员、对象键排序，恰好就是要的规范化
+ * （`{name:"a"}` 与 `{name:"a", system: undefined}` 同值）。不一致即**弃整个候选**，该 actor
+ * 全新重跑：全保真转录下这是双重正确的——旧 system prompt 产的转录接新 persona 是身份错乱，
+ * 而「我把 persona 修好了」这个意图本来就是要重跑。
+ *
+ * 匿名 actor 永不附着：名字是缓存身份键，没有名字就没有可比对的坐标（代价已裁决）。
+ * 比对之所以在**运行期**而不是提交时静态比对两份脚本：名字与 persona 都是运行期值
+ * （`agent()` 的实参可以是动态表达式），静态比对是第二份真相，恰是本包处处要防的。
+ */
+export function matchImportedActor(cache, spec) {
+    if (cache === undefined)
+        return undefined;
+    const name = spec.name;
+    if (name === undefined || name === "")
+        return undefined;
+    const candidate = cache.actors.get(name);
+    if (candidate === undefined)
+        return undefined;
+    if (canonicalJson(personaIdentity(spec)) !== canonicalJson(personaIdentity(candidate.persona))) {
+        return undefined;
+    }
+    return new ImportedActorState(candidate);
+}
+/**
+ * 一次 ask 缓存命中要落的**真** dwf_node 行（新 siteId、拷贝 result / stats / 边界）。
+ *
+ * 边界值必须一起拷过去，否则**这个** run 自己就不能再被修订——链式修订靠的正是 count offset
+ * 跨前缀复制不变。
+ */
+export function importedAskRecord(runId, instance, actor, seq, hash, entry) {
+    const record = {
+        runId,
+        siteId: instance.siteId,
+        ordinal: instance.ordinal,
+        kind: "ask",
+        actorSiteId: actor.siteId,
+        actorOrdinal: actor.ordinal,
+        actorSeq: seq,
+        inputHash: hash,
+        status: "completed",
+        result: entry.result,
+        messageBoundary: entry.messageBoundary,
+    };
+    if (entry.stats !== undefined)
+        record.stats = entry.stats;
+    return record;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * @zcode/dynamic-workflow 执行引擎核心的模块导出。
+ */
+export { WorkflowEngine, type EngineConfig, type RunSettlement } from "./engine.js";
+export { InMemoryJournalStore } from "./journal-memory.js";
+export { HOLE_PROMPT_MAX_CHARS, type FilledHole, type FillHoleResult, type HoleFill, type OpenHole, } from "./engine-holes.js";
+export { ALL_EVENTS, NODE_KINDS, NON_REPORT_NODE_KINDS, type GetNodeOptions, type ListActorsOptions, type ListNodesOptions, type RunEventType, } from "./journal-read-types.js";
+export { ConcurrencyController, CONCURRENCY_DECREASE_FACTOR, CONCURRENCY_FLOOR, CONCURRENCY_IDLE_RESET_MS, CONCURRENCY_INCREASE_AFTER_SUCCESSES, CONCURRENCY_INCREASE_STEP, type ConcurrencyControllerSnapshot, type ConcurrencyThrottleReason, } from "./concurrency.js";
+export { canonicalJson, fnv1a, inputHash } from "./hash.js";
+export { WorkflowError, INSTRUCTIONS_HEAD_MAX_CHARS, LAST_TOOL_NAME_MAX_CHARS, LAST_TOOL_TARGET_MAX_CHARS, NUDGE_ATTEMPTS, REPAIR_ATTEMPTS, refToString, type ActorId, type ActorRecord, type ActorRef, type ActorSessionSeed, type ArtifactPublishRequest, type ArtifactRef, type ArtifactVersionRecord, type AskMessage, type AskLastTool, type AskProgress, type AskSpec, type AskStats, type AskWaitInfo, type ConcurrencyChange, type ConcurrencyChangeReason, type Caps, type InstanceRef, type JournalStorePort, type ImportedActorCandidate, type ImportedAskEntry, type ImportedInFlightAsk, type ImportedRunCache, type ImportedWorldEntry, type ListEventsOptions, type NodeKind, type NodeOutcome, type NodeRecord, type NodeRecordStatus, type WorldReadInput, WORLD_READ_INPUT_MAX_BYTES, type PersonaSpec, type RunEvent, type RunRecord, type RunSettlementRecord, type RunStallInfo, type RunStatus, type RunStopReason, type SessionRef, type StoredEvent, type SubmitVerdict, type ValidateFn, type WorkflowDriver, type WorkflowErrorCode, type WorkflowErrorJson, type ProviderStopDetails, type WorkflowErrorMismatch, type WorkflowHostApi, type WorkflowReportSink, type WorldReadOp, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACL,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,QAAQ,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,EACjB,yBAAyB,EACzB,oCAAoC,EACpC,yBAAyB,EACzB,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EACL,aAAa,EACb,2BAA2B,EAC3B,wBAAwB,EACxB,0BAA0B,EAC1B,cAAc,EACd,eAAe,EACf,WAAW,EACX,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,0BAA0B,EAC1B,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * @zcode/dynamic-workflow 执行引擎核心的模块导出。
+ */
+export { WorkflowEngine } from "./engine.js";
+export { InMemoryJournalStore } from "./journal-memory.js";
+export { HOLE_PROMPT_MAX_CHARS, } from "./engine-holes.js";
+export { ALL_EVENTS, NODE_KINDS, NON_REPORT_NODE_KINDS, } from "./journal-read-types.js";
+export { ConcurrencyController, CONCURRENCY_DECREASE_FACTOR, CONCURRENCY_FLOOR, CONCURRENCY_IDLE_RESET_MS, CONCURRENCY_INCREASE_AFTER_SUCCESSES, CONCURRENCY_INCREASE_STEP, } from "./concurrency.js";
+export { canonicalJson, fnv1a, inputHash } from "./hash.js";
+export { WorkflowError, INSTRUCTIONS_HEAD_MAX_CHARS, LAST_TOOL_NAME_MAX_CHARS, LAST_TOOL_TARGET_MAX_CHARS, NUDGE_ATTEMPTS, REPAIR_ATTEMPTS, refToString, WORLD_READ_INPUT_MAX_BYTES, } from "./types.js";

package/vendor/dynamic-workflow/engine/journal-memory.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 内存版 {@link JournalStorePort}：阶段一用于 fake-driver 测试与 replay/resume。
+ * 纯内存、同步；深拷贝进出以杜绝调用方持有的引用被后续写入意外改动（模拟存储边界）。
+ * 生产实现落在 zcode session store 的 node:sqlite（DatabaseSync，同步）之上，共用 JournalStorePort；
+ * 事务性不在端口面上，由 driver 组合 journal+session 写入。
+ */
+import type { ActorRecord, Caps, GetNodeOptions, JournalStorePort, ListActorsOptions, ListEventsOptions, ListNodesOptions, NodeKind, NodeRecord, RunEvent, RunRecord, RunSettlementRecord, RunStatus, StoredEvent } from "./types.js";
+export declare class InMemoryJournalStore implements JournalStorePort {
+    private readonly runs;
+    private readonly actors;
+    private readonly nodes;
+    private readonly events;
+    createRun(record: RunRecord): void;
+    getRun(runId: string): RunRecord | undefined;
+    updateRunStatus(runId: string, status: RunStatus, settlement?: RunSettlementRecord): void;
+    updateRunUsage(runId: string, spentTokens: number): void;
+    updateRunCaps(runId: string, caps: Caps): void;
+    updateRunScript(runId: string, scriptText: string, scriptHash: string): void;
+    putActor(record: ActorRecord): void;
+    getActor(runId: string, siteId: string, ordinal: number): ActorRecord | undefined;
+    listActors(runId: string, opts: ListActorsOptions): ActorRecord[];
+    putNode(record: NodeRecord): void;
+    getNode(runId: string, siteId: string, ordinal: number, opts?: GetNodeOptions): NodeRecord | undefined;
+    listNodes(runId: string, opts: ListNodesOptions): NodeRecord[];
+    countNodes(runId: string, kind: NodeKind): number;
+    sumResultBytes(runId: string, kind: NodeKind): number;
+    appendEvent(runId: string, event: RunEvent): StoredEvent;
+    listEvents(runId: string, opts: ListEventsOptions): StoredEvent[];
+    private requireActorBucket;
+    private requireNodeBucket;
+}
+//# sourceMappingURL=journal-memory.d.ts.map

package/vendor/dynamic-workflow/engine/journal-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-memory.d.ts","sourceRoot":"","sources":["../../src/engine/journal-memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,IAAI,EACJ,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,mBAAmB,EACnB,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AAmBpB,qBAAa,oBAAqB,YAAW,gBAAgB;IAE3D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+C;IACtE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAE3D,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAUlC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAK5C,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,mBAAmB,GAAG,IAAI;IA6BzF,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAMxD,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI;IAQ9C,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAQ5E,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAKnC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAKjF,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,WAAW,EAAE;IAajE,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAKjC,OAAO,CACL,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,cAAc,GACpB,UAAU,GAAG,SAAS;IAKzB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,UAAU,EAAE;IAe9D,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM;IAQjD,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM;IAQrD,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,WAAW;IAgBxD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,WAAW,EAAE;IAkCjE,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,iBAAiB;CAK1B"}

package/vendor/dynamic-workflow/engine/journal-memory.js

@@ -0,0 +1,243 @@
+/**
+ * 内存版 {@link JournalStorePort}：阶段一用于 fake-driver 测试与 replay/resume。
+ * 纯内存、同步；深拷贝进出以杜绝调用方持有的引用被后续写入意外改动（模拟存储边界）。
+ * 生产实现落在 zcode session store 的 node:sqlite（DatabaseSync，同步）之上，共用 JournalStorePort；
+ * 事务性不在端口面上，由 driver 组合 journal+session 写入。
+ */
+/** 结构化深拷贝：隔离存储边界两侧的引用。值均为 JSON 兼容或 PersonaSpec 等纯数据。 */
+function clone(value) {
+    return structuredClone(value);
+}
+/** 节点行的出库副本；`withResult: false` 与 SQLite 侧不 select `result_json` 同语义（键缺席）。 */
+function nodeCopy(node, withResult) {
+    const copy = clone(node);
+    if (!withResult)
+        delete copy.result;
+    return copy;
+}
+/** actor / node 的复合键。 */
+function key(siteId, ordinal) {
+    return `${siteId}@${ordinal}`;
+}
+export class InMemoryJournalStore {
+    // 以 runId 分桶，贴合"一个 store 可承载多个 run"的存储语义。
+    runs = new Map();
+    actors = new Map();
+    nodes = new Map();
+    events = new Map();
+    createRun(record) {
+        if (this.runs.has(record.runId)) {
+            throw new Error(`journal: run ${record.runId} already exists`);
+        }
+        this.runs.set(record.runId, clone(record));
+        this.actors.set(record.runId, new Map());
+        this.nodes.set(record.runId, new Map());
+        this.events.set(record.runId, []);
+    }
+    getRun(runId) {
+        const r = this.runs.get(runId);
+        return r === undefined ? undefined : clone(r);
+    }
+    updateRunStatus(runId, status, settlement) {
+        const r = this.runs.get(runId);
+        if (r === undefined)
+            throw new Error(`journal: unknown run ${runId}`);
+        r.status = status;
+        if (status === "pending" || status === "running") {
+            // 非终态 = 无 settlement：resume 把 run 翻回 running 时必须清掉上一世的残留，否则
+            // 孤儿收敛写下的 failure_json 会与 running 并存（journal 快照读面同时报「在跑」与
+            // 「已失败」）。矛盾的结算袋（非终态却携带 failure/result）同样按清空处理。
+            delete r.failure;
+            delete r.result;
+            delete r.stopReason;
+            delete r.supersededBy;
+            return;
+        }
+        // 失败三件套（failure / stopReason / supersededBy）**整体改写**：结算袋是这一刻失败的
+        // 全部真相，缺席即没有失败。旧的「缺席 = 不触碰」语义下，外部写入的 failed + Interrupted
+        // 会在随后的 completed 结算里幸存，行同时说「完成了」和「被打断了」
+        // （SQLite 侧是同一条 coalesce，两实现同语义）。
+        if (settlement?.stopReason === undefined)
+            delete r.stopReason;
+        else
+            r.stopReason = settlement.stopReason;
+        if (settlement?.supersededBy === undefined)
+            delete r.supersededBy;
+        else
+            r.supersededBy = settlement.supersededBy;
+        if (settlement?.failure === undefined)
+            delete r.failure;
+        else
+            r.failure = clone(settlement.failure);
+        // 产物相反：缺席的键表示「不触碰」，一次不带产物的重复结算不会抹掉已结算的产物。
+        // `result: null` 是合法产物，只有 undefined 才算缺席。
+        if (settlement?.result !== undefined)
+            r.result = clone(settlement.result);
+    }
+    updateRunUsage(runId, spentTokens) {
+        const r = this.runs.get(runId);
+        if (r === undefined)
+            throw new Error(`journal: unknown run ${runId}`);
+        r.spentTokens = spentTokens;
+    }
+    updateRunCaps(runId, caps) {
+        const r = this.runs.get(runId);
+        if (r === undefined)
+            throw new Error(`journal: unknown run ${runId}`);
+        // 深拷贝与其余写入同规（存储边界两侧不共享引用）：调用方手里的那份 caps 随后被换掉，
+        // 不该顺手改动已落库的行。
+        r.caps = clone(caps);
+    }
+    updateRunScript(runId, scriptText, scriptHash) {
+        const r = this.runs.get(runId);
+        if (r === undefined)
+            throw new Error(`journal: unknown run ${runId}`);
+        // 两列同一笔写（resume 拿哈希对文本），行上其余一切不碰（与 updateRunUsage 同族）。
+        r.scriptText = scriptText;
+        r.scriptHash = scriptHash;
+    }
+    putActor(record) {
+        const bucket = this.requireActorBucket(record.runId);
+        bucket.set(key(record.siteId, record.ordinal), clone(record));
+    }
+    getActor(runId, siteId, ordinal) {
+        const a = this.actors.get(runId)?.get(key(siteId, ordinal));
+        return a === undefined ? undefined : clone(a);
+    }
+    listActors(runId, opts) {
+        const bucket = this.actors.get(runId);
+        if (bucket === undefined)
+            return [];
+        const matched = [...bucket.values()].filter((actor) => opts.name === undefined || actor.name === opts.name);
+        return matched.map((actor) => {
+            const copy = clone(actor);
+            if (!opts.withPersona)
+                delete copy.persona;
+            return copy;
+        });
+    }
+    putNode(record) {
+        const bucket = this.requireNodeBucket(record.runId);
+        bucket.set(key(record.siteId, record.ordinal), clone(record));
+    }
+    getNode(runId, siteId, ordinal, opts) {
+        const n = this.nodes.get(runId)?.get(key(siteId, ordinal));
+        return n === undefined ? undefined : nodeCopy(n, opts?.withResult ?? true);
+    }
+    listNodes(runId, opts) {
+        const bucket = this.nodes.get(runId);
+        if (bucket === undefined)
+            return [];
+        // Map 的迭代序 = 首次插入序，与 SQLite 侧的 `order by id` 同语义（upsert 不改 id，也不改
+        // Map 里的位置）。
+        const kinds = opts.kinds;
+        const matched = [...bucket.values()].filter((node) => kinds === "all" || kinds.includes(node.kind));
+        const limited = opts.limit === undefined ? matched : matched.slice(0, Math.max(0, opts.limit));
+        const budgeted = opts.maxResultBytes === undefined ? limited : withinBytes(limited, opts.maxResultBytes);
+        return budgeted.map((node) => nodeCopy(node, opts.withResult));
+    }
+    countNodes(runId, kind) {
+        const bucket = this.nodes.get(runId);
+        if (bucket === undefined)
+            return 0;
+        let count = 0;
+        for (const node of bucket.values())
+            if (node.kind === kind)
+                count += 1;
+        return count;
+    }
+    sumResultBytes(runId, kind) {
+        const bucket = this.nodes.get(runId);
+        if (bucket === undefined)
+            return 0;
+        let bytes = 0;
+        for (const node of bucket.values())
+            if (node.kind === kind)
+                bytes += resultBytes(node);
+        return bytes;
+    }
+    appendEvent(runId, event) {
+        // 孤儿事件（run 尚未 createRun）与 putActor/putNode 一样是契约破坏：静默建桶
+        // 会写出一批永远归属不到任何 run 的事件；SQLite 侧有 FK 兜底，内存侧靠这句。
+        const list = this.events.get(runId);
+        if (list === undefined)
+            throw new Error(`journal: unknown run ${runId}`);
+        // 追加时刻与 SQLite 侧的 `dwf_event.time_created` 同语义（两实现共用一份契约测）：事件日志里
+        // 一切「多久以前」只能从它算，让读者现取 Date.now() 会把冷重放的整段历史全标成「刚刚」。
+        const stored = {
+            sequence: list.length,
+            event: clone(event),
+            timeCreated: Date.now(),
+        };
+        list.push(stored);
+        return clone(stored);
+    }
+    listEvents(runId, opts) {
+        const list = this.events.get(runId);
+        if (list === undefined)
+            return [];
+        // report 的排名按**全 run** 计（与 types / cursor / limit 无关），所以先在未过滤的序列上
+        // 给每条 report 事件定名次，再过滤——SQLite 侧的 row_number() 也开在过滤之前。
+        const reportLimit = opts.reportItems === "all" ? undefined : opts.reportItems.limit;
+        const stripped = new Set();
+        if (reportLimit !== undefined) {
+            let rank = 0;
+            for (const stored of list) {
+                if (stored.event.type !== "report")
+                    continue;
+                rank += 1;
+                if (rank > reportLimit)
+                    stripped.add(stored.sequence);
+            }
+        }
+        // sequence 与数组下标在内存实现里恒等（appendEvent 用 list.length 分配），但这里仍按
+        // sequence 比较而不是按下标偏移：cursor 的语义是"严格大于该 sequence"，SQLite 侧也是
+        // `where sequence > ?`。两侧共用同一份契约测，语义必须逐字相同。
+        const types = opts.types;
+        const after = opts.afterSequence;
+        const filtered = list.filter((e) => (types === "all" || types.includes(e.event.type)) &&
+            (after === undefined || e.sequence > after));
+        const limited = opts.limit === undefined ? filtered : filtered.slice(0, Math.max(0, opts.limit));
+        return limited.map((stored) => {
+            const copy = clone(stored);
+            if (stripped.has(stored.sequence))
+                delete copy.event.item;
+            return copy;
+        });
+    }
+    requireActorBucket(runId) {
+        const bucket = this.actors.get(runId);
+        if (bucket === undefined)
+            throw new Error(`journal: unknown run ${runId}`);
+        return bucket;
+    }
+    requireNodeBucket(runId) {
+        const bucket = this.nodes.get(runId);
+        if (bucket === undefined)
+            throw new Error(`journal: unknown run ${runId}`);
+        return bucket;
+    }
+}
+/**
+ * 一行 `result` 的 UTF-8 序列化字节数，与 SQLite 侧 `octet_length(result_json)` 同一把尺
+ * （`result_json` 就是 `JSON.stringify(result)`）。无结果的行计 0。
+ */
+function resultBytes(node) {
+    if (node.result === undefined)
+        return 0;
+    const text = JSON.stringify(node.result);
+    return text === undefined ? 0 : new TextEncoder().encode(text).length;
+}
+/** `maxResultBytes` 的前缀规则：再加一行就超界时收尾，第一行总是带上（同 SQLite 侧）。 */
+function withinBytes(nodes, maxResultBytes) {
+    const kept = [];
+    let total = 0;
+    for (const node of nodes) {
+        const bytes = resultBytes(node);
+        if (kept.length > 0 && total + bytes > maxResultBytes)
+            break;
+        kept.push(node);
+        total += bytes;
+    }
+    return kept;
+}

package/vendor/dynamic-workflow/engine/journal-read-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * journal 读面的选项词汇表（docs/execution-engine.md「Reading the journal」）。
+ *
+ * 一条 run 的表随它做过的一切增长：每次调用一行节点，ask 的回答与 world read 的结果在
+ * `result_json`，每条 report item 更是存了两份（节点行 + `report` 事件的载荷）。所以没有读者
+ * 可以「整表读进内存再过滤」：每次读都说清自己要什么，过滤、计数、分组都在存储层做。
+ *
+ * 选项是**必填**的而不是带缺省：一次整表读必须在调用点写出 `"all"`，于是它在代码评审与
+ * grep 里都看得见，不会借一个缺省参数悄悄回来。
+ *
+ * 独立成模块：types.ts 顶在 oxlint max-lines 上限（400 行）。
+ */
+import type { NodeKind, RunEvent } from "./types.js";
+/** 事件类型词（`dwf_event.type` 列）。 */
+export type RunEventType = RunEvent["type"];
+export declare const NODE_KINDS: readonly NodeKind[];
+/** 除 `report` 之外的全部 kind：读「这条 run 做过的事」而不碰报告条目的读者用它。 */
+export declare const NON_REPORT_NODE_KINDS: readonly NodeKind[];
+/** 节点列表读。行按 `id`（插入顺序）升序，`limit` 作用在过滤之后。 */
+export interface ListNodesOptions {
+    /** 只返回这些 kind 的行（`kind in (…)`）；`"all"` = 不过滤。空数组得到空列表。 */
+    kinds: readonly NodeKind[] | "all";
+    /** false = 不读 `result_json`，返回的行上 `result` 缺席（其余列照常）。 */
+    withResult: boolean;
+    /** 最多返回的行数；缺省不限。 */
+    limit?: number;
+    /**
+     * 结果字节的上界：按行序取行，再加一行就会让已取各行 `result` 的序列化字节数之和超过它时
+     * 收尾；第一行总是带上。只在 `withResult: true` 时有意义。终态快照用它把「前 256 条报告」
+     * 同时限在 8 MiB 之内——条数上界单独管不住字节。
+     */
+    maxResultBytes?: number;
+}
+/** 单行节点读。缺省读整行：点查不是整表读，只有只比对哈希的读者才需要省掉结果。 */
+export interface GetNodeOptions {
+    /** false = 不读 `result_json`，返回的行上 `result` 缺席。 */
+    withResult: boolean;
+}
+/** 子代理列表读。行按 `id`（插入顺序）升序。 */
+export interface ListActorsOptions {
+    /** 只返回这个名字的行（`name = ?`）；缺省不过滤。 */
+    name?: string;
+    /** false = 不读 `persona_json`，返回的行上 `persona` 缺席。 */
+    withPersona: boolean;
+}
+/**
+ * 事件列表读（cursor = journal sequence）。事件按 sequence 升序；`types` 过滤先于 cursor 与
+ * `limit` 生效，于是分页在过滤后的序列上进行。
+ */
+export interface ListEventsOptions {
+    /** 只返回这些类型的事件（`type in (…)`）；`"all"` = 不过滤。空数组得到空列表。 */
+    types: readonly RunEventType[] | "all";
+    /**
+     * `report` 事件的 `item` 读到哪里为止。`{limit: N}`：本 run 按 sequence 的**第 N 条之后**的
+     * 每条 `report` 事件照样返回，但不带 `item`——实例、`artifactId`、出生阶段字段与时间都保留。
+     * 剥离发生在存储层（SQLite 的 `json_remove`），被剥掉的 item 从不进入 JS 堆。`item` 缺席只
+     * 可能是被剥掉的：`report(undefined)` 在引擎里就被拒绝了。
+     *
+     * 排名按**本 run 全部 report 事件**的 sequence 计，与 `types` / cursor / `limit` 无关——
+     * 「第几条报告」是 run 的事实，不随一页从哪里开始而变。
+     */
+    reportItems: "all" | {
+        limit: number;
+    };
+    /** 只返回 sequence **严格大于**该值的事件。cursor 是"已读到的最后一个 sequence"，不是偏移量。 */
+    afterSequence?: number;
+    /** 单页最多返回的条数；缺省不限。 */
+    limit?: number;
+}
+/** 整条事件日志、report item 不剥：只给真要逐字节重放全部事件的读者（与测试）。 */
+export declare const ALL_EVENTS: ListEventsOptions;
+//# sourceMappingURL=journal-read-types.d.ts.map

package/vendor/dynamic-workflow/engine/journal-read-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-read-types.d.ts","sourceRoot":"","sources":["../../src/engine/journal-read-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErD,iCAAiC;AACjC,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;AAc5C,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAA6C,CAAC;AAExF,wDAAwD;AACxD,eAAO,MAAM,qBAAqB,EAAE,SAAS,QAAQ,EAEpD,CAAC;AAEF,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,KAAK,CAAC;IACnC,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAC;IACpB,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,8BAA8B;AAC9B,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,KAAK,CAAC;IACvC;;;;;;;;OAQG;IACH,WAAW,EAAE,KAAK,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mDAAmD;AACnD,eAAO,MAAM,UAAU,EAAE,iBAAwD,CAAC"}

package/vendor/dynamic-workflow/engine/journal-read-types.js

@@ -0,0 +1,28 @@
+/**
+ * journal 读面的选项词汇表（docs/execution-engine.md「Reading the journal」）。
+ *
+ * 一条 run 的表随它做过的一切增长：每次调用一行节点，ask 的回答与 world read 的结果在
+ * `result_json`，每条 report item 更是存了两份（节点行 + `report` 事件的载荷）。所以没有读者
+ * 可以「整表读进内存再过滤」：每次读都说清自己要什么，过滤、计数、分组都在存储层做。
+ *
+ * 选项是**必填**的而不是带缺省：一次整表读必须在调用点写出 `"all"`，于是它在代码评审与
+ * grep 里都看得见，不会借一个缺省参数悄悄回来。
+ *
+ * 独立成模块：types.ts 顶在 oxlint max-lines 上限（400 行）。
+ */
+/**
+ * 全部节点 kind。`Record<NodeKind, true>` 让新增的 kind 在这里编译失败，而不是被一份手写
+ * 列表悄悄漏掉——{@link NON_REPORT_NODE_KINDS} 这类「除了某种之外」的集合都从它派生。
+ */
+const NODE_KIND_SET = {
+    ask: true,
+    "world-read": true,
+    "world-run": true,
+    report: true,
+    artifact: true,
+};
+export const NODE_KINDS = Object.keys(NODE_KIND_SET);
+/** 除 `report` 之外的全部 kind：读「这条 run 做过的事」而不碰报告条目的读者用它。 */
+export const NON_REPORT_NODE_KINDS = NODE_KINDS.filter((kind) => kind !== "report");
+/** 整条事件日志、report item 不剥：只给真要逐字节重放全部事件的读者（与测试）。 */
+export const ALL_EVENTS = { types: "all", reportItems: "all" };