@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.0

package/vendor/dynamic-workflow/engine/scheduler-types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * scheduler.ts 顶到 oxlint max-lines 上限（400 行），把调度器的内部类型（Deferred /
+ * AskNode / Actor）与引擎注入的依赖面 SchedulerHost 拆到本文件；公开面仍从 scheduler.ts 导出
+ * （SchedulerHost 在那里原地再导出，engine.ts 的导入路径不变）。
+ *
+ * 单独成文件的理由不只是行数：scheduler-submit.ts 里的自由函数也要拿到 AskNode / SchedulerHost，
+ * 从这里导入，两侧都不必反向 import 调度器本体。
+ */
+import type { ImportedActorState } from "./imported-cache.js";
+import type { ActorId, ActorRef, AskSpec, AskStats, Caps, InstanceRef, PersonaSpec, RunEvent, SessionRef, ValidateFn, WorkflowDriver, WorkflowError } from "./types.js";
+/** 一个可外部结算的 promise。 */
+export interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason: unknown) => void;
+}
+export declare function defer<T>(): Deferred<T>;
+/** 引擎注入给调度器的依赖面。 */
+export interface SchedulerHost {
+    readonly runId: string;
+    /**
+     * 本 run 的并发上界。**每次派发前现读**，不是构造时抄下的一份：`setMaxConcurrency` 会整份
+     * 换掉引擎持有的 caps（docs/dynamic-workflow/concurrency.md「Two bounds on a run」），
+     * 而调度器的派发判据必须看见新值。引擎侧因此以 getter 实现这个属性。
+     */
+    readonly caps: Caps;
+    readonly driver: WorkflowDriver;
+    readonly validate: ValidateFn;
+    /** 分配某站点的下一个执行序号（与 world-read/actor 共用一套计数器）。 */
+    nextOrdinal(siteId: string): number;
+    /**
+     * 受 replay 结算次序约束地释放一次命中（docs/execution-engine.md「Replaying the settle order」）。
+     * 非 resume、或次序表里没有这个实例时立即执行 `release`。
+     */
+    holdForReplay(instance: InstanceRef, release: () => void): void;
+    /** 事件既落 journal 又扇出（Boundary C）。 */
+    record(event: RunEvent): void;
+    isRunSettled(): boolean;
+    /** run 已结算时用于 reject 的错误。 */
+    runError(): WorkflowError;
+    /** run 级失败。 */
+    failRun(error: WorkflowError): void;
+    /**
+     * 导入缓存是否已关闭（amend-resume）。关门由引擎自己做
+     * （driver 上报 askMutating、或 live 的 world-run），调度器只读这个位——一个 ask 转 live 本身
+     * **不**关门：它还什么都没改。
+     */
+    importCacheClosed(): boolean;
+    /** 该记录行在崩溃前是否 live 跑过（resume 时引擎从事件恢复；非 resume 恒 false）。 */
+    wasLiveBeforeResume(instance: InstanceRef): boolean;
+    /**
+     * 该记录行的准入是否发生在导入缓存关闭**之前**（按事件次序恢复，见 engine-world.ts 的
+     * recoverImportClosure）。续跑前驱在飞 ask 的判定要它才能在 resume 时精确复原；非 resume 恒 false。
+     */
+    wasQueuedBeforeImportClose(instance: InstanceRef): boolean;
+}
+/** 一个 live（需真正派发执行）的 ask 节点。 */
+export interface AskNode {
+    instance: InstanceRef;
+    actor: Actor;
+    actorSeq: number;
+    instructions: string;
+    hash: string;
+    spec: AskSpec;
+    deferred: Deferred<unknown>;
+    repairsRemaining: number;
+    nudgesRemaining: number;
+    settled: boolean;
+    dispatched: boolean;
+    lastStats?: AskStats;
+    /**
+     * 准入时算好的指令开头（{@link AskNode.instructions} 的前 N 字符）。存在节点上而不是两处
+     * 各算一次：`node-queued` 与 `node-dispatched` 必须带**同一个**串（派发重复出生事实，
+     * 见 types.ts 的 `node-dispatched`），存下来这件事就由构造保证，不靠两处调用保持同步。
+     */
+    instructionsHead?: string;
+}
+/** 调度器维护的 actor 运行态。 */
+export interface Actor {
+    ref: ActorRef;
+    id: ActorId;
+    persona: PersonaSpec;
+    name?: string;
+    /** journal 中该 actor 已记录的 ask 节点数——replay 时 live 节点须等其全部准入后才放行。 */
+    recordedCount: number;
+    /** 下一个待准入的 actorSeq。 */
+    nextAdmitSeq: number;
+    /** 已到达但未准入的记录节点释放动作，按 actorSeq 挂起（hold 规则）。 */
+    pendingRecorded: Map<number, () => void>;
+    /** 已到达但在等记录节点排空的 live 节点释放动作，按到达顺序。 */
+    pendingLive: Array<() => void>;
+    /** 已准入待派发的 live 节点（FIFO = 准入顺序）。 */
+    liveQueue: AskNode[];
+    /** 正在执行的 live 节点（actor 串行，至多一个）。 */
+    current?: AskNode;
+    /** 会话惰性创建，缓存其 promise（每 actor 一次）。 */
+    sessionPromise?: Promise<SessionRef>;
+    session?: SessionRef;
+    /**
+     * amend-resume 的导入消费态（引擎在 createActor 里按名 + persona 匹配后挂上，见
+     * imported-cache.ts 的 `matchImportedActor`）。缺席即该 actor 全新重跑。
+     */
+    imported?: ImportedActorState;
+}
+//# sourceMappingURL=scheduler-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-types.d.ts","sourceRoot":"","sources":["../../src/engine/scheduler-types.ts"],"names":[],"mappings":"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"}

package/vendor/dynamic-workflow/engine/scheduler-types.js

@@ -0,0 +1,17 @@
+/**
+ * scheduler.ts 顶到 oxlint max-lines 上限（400 行），把调度器的内部类型（Deferred /
+ * AskNode / Actor）与引擎注入的依赖面 SchedulerHost 拆到本文件；公开面仍从 scheduler.ts 导出
+ * （SchedulerHost 在那里原地再导出，engine.ts 的导入路径不变）。
+ *
+ * 单独成文件的理由不只是行数：scheduler-submit.ts 里的自由函数也要拿到 AskNode / SchedulerHost，
+ * 从这里导入，两侧都不必反向 import 调度器本体。
+ */
+export function defer() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}

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

@@ -0,0 +1,113 @@
+/**
+ * ask 调度器：把"每 actor FIFO + hold 规则 + 并发上限派发 + ask 结算"从引擎主体拆出，
+ * 使两个文件都聚焦、可读（并满足单文件行数上限）。引擎通过 {@link SchedulerHost} 注入其
+ * 依赖（driver、caps、序号分配、run 级失败），调度器只负责 ask 生命周期，不管 run 生命周期。
+ *
+ * 关键规则见 engine.ts 顶部说明：命中短路、actorSeq 准入顺序、replay 的 hold 规则、串行 actor。
+ *
+ * 内部类型与 SchedulerHost 在 scheduler-types.ts；submit / turn 的向上回报处理在 scheduler-submit.ts
+ * （拆分原因：oxlint max-lines 上限 400 行）。SchedulerHost 在此原地再导出，导入路径不变。
+ * replay 命中的哈希不一致错误 {@link hashMismatch} 在 hash-mismatch.ts（同一个理由）。
+ */
+import { type ImportedActorState } from "./imported-cache.js";
+import { type Actor, type SchedulerHost } from "./scheduler-types.js";
+import type { ActorId, ActorRef, AskSpec, AskStats, InstanceRef, NodeRecord, PersonaSpec } from "./types.js";
+import { WorkflowError } from "./types.js";
+export type { SchedulerHost } from "./scheduler-types.js";
+export declare class AskScheduler {
+    private readonly host;
+    private readonly actors;
+    private readonly actorOrder;
+    private readonly liveNodes;
+    /**
+     * 「转录早于本次派发」的 ask 实例（`siteId@ordinal`）：续跑前驱在飞 ask 的，以及 resume 时
+     * 据 running 行重新派发的。它们落 journal 的 stats 要抹掉 `worldToolCalls`，见 {@link journaledStats}。
+     * 结算后不清理——迟到的 stats 回填还要查它。
+     */
+    private readonly priorTranscriptAsks;
+    /**
+     * 每个 actor 在 journal 里已记录的 ask 行数（`siteId@ordinal` → 行数），由引擎的 resume 分支用它
+     * 已经读好的 ask 行一次建好（{@link seedRecordedAsks}）。修复原因：registerActor 原先每建一个
+     * actor 就把整张节点表读一遍再过滤——宽扇出下是 O(actor × 行) 次解码，而且解的是每条 ask 的回答
+     * 与每条 report item。一次建表是对的：actor 总在它的第一次 ask 之前注册，所以注册那一刻 journal
+     * 里属于它的 ask 行只可能来自前几世；全新 run 的表为空。
+     */
+    private readonly recordedAsks;
+    private activeAsks;
+    /** scheduler-submit.ts 的自由函数经它查 live 节点、按结果结算（见 {@link SubmitSeam}）。 */
+    private readonly submitSeam;
+    constructor(host: SchedulerHost);
+    private get journal();
+    /** resume 时喂入本 run 已落库的 ask 行（可不带结果），建好 {@link recordedAsks}。 */
+    seedRecordedAsks(askRows: readonly NodeRecord[]): void;
+    hasActor(id: ActorId): boolean;
+    /**
+     * 注册一个 actor（创建站点 × 序号）。`imported` 是 amend-resume 的导入候选：引擎已在
+     * createActor 里按有效名 + 规范化 persona 匹配过，调度器只负责消费它。
+     */
+    registerActor(ref: ActorRef, id: ActorId, name: string | undefined, persona: PersonaSpec, imported?: ImportedActorState): Actor;
+    /** 受理一次 ask：完结命中短路（走 hold 规则），running 命中或未命中则 live 派发。 */
+    admitAsk(siteId: string, actorId: ActorId, instructions: string, spec: AskSpec): Promise<unknown>;
+    /**
+     * 把一个 ask 作为 live 节点准入：建节点、准入即落 running 记录、入队并记事件。
+     *
+     * `priorTranscript` 为真表示这一条不是从空转录开跑的（续跑前驱在飞 ask，或 resume 据 running
+     * 行重新派发）——它只影响 stats 怎么落库，见 {@link journaledStats}。
+     */
+    private admitLive;
+    /**
+     * fresh ask 准入时问一次导入缓存（amend-resume）。命中即 **cached settle** 并返回 true
+     * （调用方不再 live）；判定与分歧记账全在 {@link ImportedActorState}。
+     *
+     * 命中写一行**真** dwf_node，只发 `node-settled cached:true`——与 replay 命中的
+     * {@link releaseCachedAsk} 同一副姿态：不发 node-queued / node-dispatched，
+     * 不入 liveQueue，不建会话，不占 `actor.current`。那条结算因此就是出生事件，重发出生事实，
+     * 并点名前驱里持有这段交换的会话（{@link cachedAskFacts}）。
+     */
+    private tryImportedSettle;
+    /** submit_result 到达：方法体在 scheduler-submit.ts 的 handleSubmitAttempted。 */
+    submitAttempted(instance: InstanceRef, payload: unknown): void;
+    /** turn 结束（无 submit）：方法体在 scheduler-submit.ts 的 handleTurnEnded。 */
+    turnEnded(instance: InstanceRef, finalText: string): void;
+    noteStats(instance: InstanceRef, stats: AskStats): void;
+    /**
+     * 落 journal 的 stats：**转录早于本次派发**的 ask 抹掉 `worldToolCalls`。
+     *
+     * 根因：driver 的工具计数器是内存态、每次 ask 起跑时清零，所以接着一段既有转录跑的 ask 只数
+     * 得到自己这几轮，转录里原有的工具调用一个也数不到。少报的后果不是账目不准（那是 tokens 的
+     * 事），而是**纯度判据被污染**：一个报 0 的 ask 会被后来的修订当成纯条目，在关门之后仍从缓存
+     * 结算——而它其实碰过工作区。缺席这个键本就表示「碰过」（保守读法），所以抹掉才是诚实记录。
+     * tokens / toolCalls / turns 照记：它们是用量，不是纯度声明。
+     */
+    private journaledStats;
+    failed(instance: InstanceRef, error: WorkflowError): void;
+    /** 该实例是否仍是在飞（已准入、未结算）的 live ask——限流观察事件只对这样的节点有意义。 */
+    isLive(instance: InstanceRef): boolean;
+    /** 在飞 ask 所属子代理的有效名（关门事件里点名用）；不在飞即 undefined。 */
+    liveActorName(instance: InstanceRef): string | undefined;
+    /** 中止所有在飞 ask：run 取消/失败时用。emitCancelled 为真时补发 node-settled(cancelled)。 */
+    abortInFlight(error: WorkflowError, emitCancelled: boolean): void;
+    private drainAdmission;
+    /**
+     * 命中记录的 ask：按 journal 记下的**结算次序**释放（docs/execution-engine.md
+     * 「Replaying the settle order」）。hold 规则定的是同一个 actor 内的准入次序，跨 actor 的
+     * 完成次序要这一道闸才回得来——扇出分支在 await 之后的每一次 journal 调用都按它编号。
+     */
+    private releaseCachedAsk;
+    private settleCachedAsk;
+    /**
+     * 重扫每个 actor 的待派发队列。公开面**只为一个调用方**：引擎在抬高本 run 的并发上界之后
+     * 调它（docs/dynamic-workflow/concurrency.md「Two bounds on a run」）。上界本身是
+     * {@link pumpActor} 每次派发前现读的，但没有任何别的事件会触发一次重扫——排队的 ask
+     * 否则要一直等到下一次结算才动，而「抬高之后立刻多跑几个」正是这条命令买的东西。
+     */
+    pumpAll(): void;
+    private pumpActor;
+    private dispatch;
+    private ensureSession;
+    private settleOk;
+    private settleFailed;
+    private finishLiveNode;
+    private nodeRecordFor;
+}
+//# sourceMappingURL=scheduler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/engine/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAS,KAAK,KAAK,EAA+B,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1G,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAER,OAAO,EACP,QAAQ,EACR,WAAW,EAEX,UAAU,EACV,WAAW,EAEZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAIL,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,qBAAa,YAAY;IAuBX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAtBjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,UAAU,CAAK;IAEvB,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;gBAEX,IAAI,EAAE,aAAa;IAShD,OAAO,KAAK,OAAO,GAElB;IAED,iEAAiE;IACjE,gBAAgB,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI;IAUtD,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO;IAI9B;;;OAGG;IACH,aAAa,CACX,GAAG,EAAE,QAAQ,EACb,EAAE,EAAE,OAAO,EACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,kBAAkB,GAC5B,KAAK;IA0BR,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAwDjG;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IA0DjB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAyBzB,yEAAyE;IACzE,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAI9D,oEAAoE;IACpE,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIzD,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI;IAevD;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAMtB,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI;IAMzD,sDAAsD;IACtD,MAAM,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO;IAKtC,iDAAiD;IACjD,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS;IAKxD,0EAA0E;IAC1E,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,OAAO,GAAG,IAAI;IAgBjE,OAAO,CAAC,cAAc;IAqBtB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,eAAe;IAWvB;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,SAAS;YAWH,QAAQ;IA6CtB,OAAO,CAAC,aAAa;IAgCrB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,aAAa;CAqBtB"}