@lingxiao-office/sdk 1.0.0

package/dist/core/DaemonManager.js

@@ -0,0 +1,429 @@
+/**
+ * DaemonManager — Daemon 进程管理
+ *
+ * 管理凌霄后台常驻服务 (daemon) 的生命周期。
+ * Daemon 是一个 detached 子进程，在父进程退出后继续运行。
+ * 状态通过 ~/.lingxiao/daemon.json 持久化。
+ *
+ * v2 新增：
+ *   - startDaemonWithSupervisor(): 启动 daemon + 自动守护（崩溃自愈）
+ *   - 内嵌 EternalSupervisor，指数退避重启
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync, closeSync, } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { CONFIG_DIR } from '../config.js';
+import { EternalSupervisor } from './EternalSupervisor.js';
+import { alertManager } from './AlertManager.js';
+import { isDaemonActiveStatus } from './StateSemantics.js';
+import { killProcess, processExists } from '../utils/platform.js';
+import { sleep } from '../utils/sleep.js';
+const DAEMON_FILE = join(CONFIG_DIR, 'daemon.json');
+const TOKEN_FILE = join(CONFIG_DIR, 'server-token');
+const DAEMON_DB_PATH = join(CONFIG_DIR, 'daemon', 'daemon.db');
+const STARTUP_HEALTH_TIMEOUT_MS = 30_000;
+const STARTUP_HEALTH_POLL_MS = 500;
+function isAlive(pid) {
+    return processExists(pid);
+}
+function readDaemonFile() {
+    try {
+        if (!existsSync(DAEMON_FILE))
+            return null;
+        const raw = readFileSync(DAEMON_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch { /* expected: file missing or malformed JSON */
+        return null;
+    }
+}
+function writeDaemonFile(info) {
+    if (!existsSync(CONFIG_DIR))
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(DAEMON_FILE, JSON.stringify(info, null, 2), 'utf-8');
+}
+function removeDaemonFile() {
+    try {
+        if (existsSync(DAEMON_FILE))
+            unlinkSync(DAEMON_FILE);
+    }
+    catch { /* expected: file already removed */ }
+}
+function readServerToken() {
+    try {
+        if (existsSync(TOKEN_FILE))
+            return readFileSync(TOKEN_FILE, 'utf-8').trim() || undefined;
+    }
+    catch { /* expected: file missing or unreadable */ }
+    return undefined;
+}
+export async function waitForDaemonHealthy(input) {
+    const timeoutMs = input.timeoutMs ?? STARTUP_HEALTH_TIMEOUT_MS;
+    const pollMs = input.pollMs ?? STARTUP_HEALTH_POLL_MS;
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const isAliveImpl = input.isAliveImpl ?? isAlive;
+    const now = input.now ?? Date.now;
+    const startedAt = now();
+    let lastError = '';
+    while (now() - startedAt < timeoutMs) {
+        if (!isAliveImpl(input.pid)) {
+            return {
+                ok: false,
+                checkedAt: now(),
+                error: 'daemon process exited before passing health check',
+            };
+        }
+        try {
+            const response = await fetchImpl(`${input.url}/health`);
+            if (response.ok) {
+                return {
+                    ok: true,
+                    checkedAt: now(),
+                };
+            }
+            lastError = `health endpoint returned HTTP ${response.status}`;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await sleep(pollMs);
+    }
+    return {
+        ok: false,
+        checkedAt: now(),
+        error: lastError || `health check timed out after ${timeoutMs}ms`,
+    };
+}
+export const DaemonManager = {
+    /**
+     * 获取当前 daemon 状态
+     */
+    getStatus() {
+        const info = readDaemonFile();
+        if (!info)
+            return { status: 'stopped' };
+        if (!isAlive(info.pid)) {
+            removeDaemonFile();
+            return { status: 'stopped' };
+        }
+        return {
+            status: 'running',
+            pid: info.pid,
+            port: info.port,
+            host: info.host,
+            url: info.url,
+            token: info.token || readServerToken(),
+            startedAt: info.startedAt,
+            uptime: Math.floor((Date.now() - info.startedAt) / 1000),
+            lastStartReason: info.lastStartReason,
+            restartCount: info.restartCount,
+            lastHealthCheckAt: info.lastHealthCheckAt,
+            lastHealthCheckOk: info.lastHealthCheckOk,
+            lastError: info.lastError,
+        };
+    },
+    /**
+     * 启动 daemon（幂等：已有运行中的 daemon 直接返回）
+     * 文件锁防止并发启动
+     */
+    async startDaemon(port = 0, host = '127.0.0.1', reason = 'manual_start', sessionId) {
+        // 幂等检查：已有运行中的 daemon 直接返回
+        const existing = DaemonManager.getStatus();
+        if (isDaemonActiveStatus(existing.status)) {
+            return existing;
+        }
+        // 文件锁：防止并发启动
+        const lockFile = join(CONFIG_DIR, 'daemon.lock');
+        const lockFd = (() => {
+            try {
+                // O_CREAT | O_EXCL — 原子创建，已存在则抛异常
+                const fd = openSync(lockFile, 'wx');
+                writeFileSync(lockFile, String(process.pid), 'utf-8');
+                return fd;
+            }
+            catch { /* expected: lock file exists — check if holder is alive */
+                // 锁文件存在，检查持有者是否还活着
+                try {
+                    const lockPid = parseInt(readFileSync(lockFile, 'utf-8').trim(), 10);
+                    if (lockPid && isAlive(lockPid)) {
+                        // 另一个进程正在启动 daemon，等待它完成
+                        return -1;
+                    }
+                    // 持有者已死，清理残留锁
+                    unlinkSync(lockFile);
+                    const fd = openSync(lockFile, 'wx');
+                    writeFileSync(lockFile, String(process.pid), 'utf-8');
+                    return fd;
+                }
+                catch { /* expected: concurrent lock contention */
+                    return -1;
+                }
+            }
+        })();
+        if (lockFd === -1) {
+            // 等待其他进程完成启动
+            for (let i = 0; i < 60; i++) {
+                await sleep(500);
+                const s = DaemonManager.getStatus();
+                if (isDaemonActiveStatus(s.status))
+                    return s;
+            }
+            // 超时，清理锁文件重试
+            try {
+                unlinkSync(lockFile);
+            }
+            catch { /* expected: already removed */ }
+            return DaemonManager.startDaemon(port, host, reason);
+        }
+        const releaseLock = () => {
+            try {
+                closeSync(lockFd);
+            }
+            catch { /* expected: fd may already be closed */ }
+            try {
+                unlinkSync(lockFile);
+            }
+            catch { /* expected: file may already be removed */ }
+        };
+        const previousInfo = readDaemonFile();
+        // Find the CLI entry point
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = dirname(__filename);
+        // The CLI script is at dist/cli.js (relative to this compiled file in dist/core/)
+        const cliPath = join(__dirname, '..', 'cli.js');
+        return new Promise((resolve, reject) => {
+            const child = spawn(process.execPath, [cliPath, 'start', '--daemon-mode'], {
+                detached: true,
+                stdio: 'ignore',
+                env: {
+                    ...process.env,
+                    LINGXIAO_WEB_PORT: String(port),
+                    LINGXIAO_WEB_HOST: host,
+                    LINGXIAO_DAEMON_MODE: '1',
+                    LINGXIAO_DAEMON_DB_PATH: DAEMON_DB_PATH,
+                    ...(sessionId ? { LINGXIAO_DAEMON_SESSION_ID: sessionId } : {}),
+                },
+            });
+            child.on('error', (err) => { releaseLock(); reject(err); });
+            child.unref();
+            // 释放文件锁（子进程已启动）
+            releaseLock();
+            // Write daemon file optimistically — the child will overwrite with real PID/port
+            const pid = child.pid;
+            const startedAt = Date.now();
+            const url = `http://${host}:${port}`;
+            const token = readServerToken();
+            const info = {
+                pid,
+                port,
+                host,
+                url,
+                startedAt,
+                token,
+                lastStartReason: reason,
+                restartCount: (previousInfo?.restartCount || 0) + (reason === 'manual_restart' || reason === 'auto_recover' ? 1 : 0),
+                lastHealthCheckAt: startedAt,
+                lastHealthCheckOk: false,
+            };
+            writeDaemonFile(info);
+            void (async () => {
+                try {
+                    // 健康检查：轮询 daemon.json 获取真实 URL
+                    // daemon 启动后会通过 updateDaemonPid 写入真实端口到 daemon.json
+                    // 随机端口（port=0）时初始 URL 是占位的，必须等 updateDaemonPid 覆盖；
+                    // 固定端口（port≠0）时初始 URL 已有效，可直接用于健康检查。
+                    const initialUrl = url;
+                    let healthUrl = (port !== 0) ? initialUrl : '';
+                    const deadline = Date.now() + STARTUP_HEALTH_TIMEOUT_MS;
+                    while (Date.now() < deadline) {
+                        if (!isAlive(pid)) {
+                            removeDaemonFile();
+                            reject(new Error('Daemon process exited before passing health check'));
+                            return;
+                        }
+                        // 每次循环都从 daemon.json 读取最新 URL
+                        // updateDaemonPid 会覆盖初始占位 URL
+                        const latestInfo = readDaemonFile();
+                        const latestUrl = latestInfo?.url || '';
+                        // 只有当 URL 被 updateDaemonPid 更新过（不同于初始占位 URL）才尝试健康检查
+                        if (latestUrl && latestUrl !== initialUrl) {
+                            healthUrl = latestUrl;
+                        }
+                        if (!healthUrl) {
+                            await sleep(STARTUP_HEALTH_POLL_MS);
+                            continue;
+                        }
+                        try {
+                            const resp = await fetch(`${healthUrl}/health`);
+                            if (resp.ok) {
+                                const finalInfo = readDaemonFile() || info;
+                                writeDaemonFile({
+                                    ...finalInfo,
+                                    lastHealthCheckAt: Date.now(),
+                                    lastHealthCheckOk: true,
+                                    lastError: '',
+                                });
+                                resolve(DaemonManager.getStatus());
+                                return;
+                            }
+                        }
+                        catch { /* expected: health check may fail during startup */ }
+                        await sleep(STARTUP_HEALTH_POLL_MS);
+                    }
+                    try {
+                        await killProcess(pid, 'SIGTERM', { tree: true });
+                    }
+                    catch { /* expected: process may already be dead */ }
+                    removeDaemonFile();
+                    reject(new Error(`Daemon failed health check: timed out after ${STARTUP_HEALTH_TIMEOUT_MS}ms`));
+                }
+                catch (error) {
+                    try {
+                        await killProcess(pid, 'SIGTERM', { tree: true });
+                    }
+                    catch { /* expected: process may already be dead */ }
+                    removeDaemonFile();
+                    reject(error);
+                }
+            })();
+        });
+    },
+    /**
+     * 停止 daemon
+     */
+    async stopDaemon() {
+        const info = readDaemonFile();
+        if (!info)
+            return { success: true };
+        if (!isAlive(info.pid)) {
+            removeDaemonFile();
+            return { success: true };
+        }
+        try {
+            await killProcess(info.pid, 'SIGTERM', { tree: true });
+            // Wait for process to exit
+            await new Promise((resolve) => {
+                let attempts = 0;
+                const check = setInterval(() => {
+                    attempts++;
+                    if (!isAlive(info.pid) || attempts > 30) {
+                        clearInterval(check);
+                        resolve();
+                    }
+                }, 200);
+            });
+            // Force kill if still alive
+            if (isAlive(info.pid)) {
+                await killProcess(info.pid, 'SIGKILL', { tree: true });
+            }
+            removeDaemonFile();
+            return { success: true };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    },
+    /**
+     * 重启 daemon
+     */
+    async restartDaemon(port, host) {
+        const existing = readDaemonFile();
+        const targetPort = port || existing?.port || 0;
+        const targetHost = host || existing?.host || '127.0.0.1';
+        await DaemonManager.stopDaemon();
+        await new Promise(r => setTimeout(r, 500));
+        return DaemonManager.startDaemon(targetPort, targetHost, 'manual_restart');
+    },
+    /**
+     * 由 daemon 进程本身调用，更新 PID 文件记录真实 PID
+     */
+    updateDaemonPid(pid, port, host) {
+        const existing = readDaemonFile();
+        const startedAt = existing?.startedAt || Date.now();
+        const url = `http://${host}:${port}`;
+        writeDaemonFile({
+            pid,
+            port,
+            host,
+            url,
+            startedAt,
+            token: existing?.token || readServerToken(),
+            lastStartReason: existing?.lastStartReason,
+            restartCount: existing?.restartCount,
+            lastHealthCheckAt: existing?.lastHealthCheckAt,
+            lastHealthCheckOk: existing?.lastHealthCheckOk,
+            lastError: existing?.lastError,
+        });
+    },
+    // ─── Supervisor (v2: 进程级自愈) ───
+    /** 内部 EternalSupervisor 实例引用 */
+    _supervisor: undefined,
+    /**
+     * 启动 daemon + 自动守护（崩溃自愈）。
+     *
+     * 与 startDaemon() 的区别：启动后启动 EternalSupervisor 后台监控，
+     * daemon 进程崩溃时自动重启（指数退避，最多 5 次）。
+     *
+     * 适合「无人值守」场景 — 调用一次即进入永久守护模式。
+     */
+    async startDaemonWithSupervisor(port = 0, host = '127.0.0.1', supervisorOptions, sessionId) {
+        // 先启动 daemon
+        const status = await DaemonManager.startDaemon(port, host, 'auto_recover', sessionId);
+        // 如果已有 supervisor 在跑，先停掉
+        DaemonManager._supervisor?.stop();
+        const info = readDaemonFile();
+        if (!info)
+            throw new Error('Daemon started but daemon.json not found');
+        const supervisor = new EternalSupervisor({
+            healthUrl: info.url,
+            pid: info.pid,
+            maxRestarts: supervisorOptions?.maxRestarts ?? 5,
+            healthCheckIntervalMs: supervisorOptions?.healthCheckIntervalMs ?? 15_000,
+            onRestart: async () => {
+                // 重启 daemon（先停再起，复用已有端口/主机）
+                const current = readDaemonFile();
+                const p = current?.port ?? port;
+                const h = current?.host ?? host;
+                await DaemonManager.stopDaemon();
+                await sleep(500);
+                await DaemonManager.startDaemon(p, h, 'auto_recover');
+                const newInfo = readDaemonFile();
+                if (!newInfo)
+                    throw new Error('Restart failed: no daemon.json');
+                return { pid: newInfo.pid, healthUrl: newInfo.url };
+            },
+            onGiveUp: (reason) => {
+                alertManager.emit({
+                    type: 'supervisor_give_up',
+                    severity: 'critical',
+                    message: reason,
+                    source: 'DaemonManager',
+                });
+            },
+            onAlert: (alert) => {
+                alertManager.emit({
+                    type: `supervisor_${alert.type}`,
+                    severity: alert.type === 'give_up' ? 'critical' : 'warning',
+                    message: alert.message,
+                    source: 'DaemonManager',
+                    metadata: { attempt: alert.attempt, maxRestarts: alert.maxRestarts },
+                });
+            },
+        });
+        supervisor.start();
+        DaemonManager._supervisor = supervisor;
+        return status;
+    },
+    /** 停止 supervisor 守护循环 */
+    stopSupervisor() {
+        DaemonManager._supervisor?.stop();
+        DaemonManager._supervisor = undefined;
+    },
+    /** 获取 supervisor 状态 */
+    getSupervisorStatus() {
+        return DaemonManager._supervisor?.getState() ?? null;
+    },
+};
+//# sourceMappingURL=DaemonManager.js.map

package/dist/core/DaemonManager.js.map

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

package/dist/core/DagScheduler.d.ts

@@ -0,0 +1,73 @@
+/**
+ * DagScheduler — 通用 DAG 调度纯函数(无 IO,确定性,零启发式)。
+ *
+ * 单一图算法真相源,服务凌霄原本各写一遍的多套依赖解锁:
+ *  - bughunt 调查 DAG(`BughuntDagScheduler` 薄封装复用本模块)
+ *  - 通用任务 DAG(`TaskBoard` 的环检测 / ready 判定复用本模块)
+ *  - 黑板 intent 依赖(`BlackboardGraph.getDispatchableIntents` 复用本模块)
+ *  - 项目蓝图子系统依赖(`ProjectBlueprint.getReadySubsystems` 复用本模块)
+ *
+ * 设计:领域语义(status 字面值 / 契约门 / evidence gate / 「依赖缺失是否视为已解决」)
+ * 全部外提成 `DagSchedulerDeps` 回调,引擎只懂 `{ id, blocked_by }` 的纯图运算。
+ * 同一套 Kahn 拓扑 + 三道门就绪判定 + DFS 环检测,各领域注入各自 deps,语义各自保留:
+ *   - bughunt: 依赖须 completed;候选态 planned;evidence gate
+ *   - TaskBoard: 依赖须 terminal+completed;候选态 dispatchable 且无 blocked_reason;契约门
+ *   - 黑板: 依赖缺失视为已解决(与上两者相反);候选态 open;无额外门
+ *
+ * 零运行时依赖(泛型自带,无 import),便于单测与跨入口复用。
+ */
+/** 通用 DAG 节点:只要有稳定 id 与依赖边即可。status / gate 等领域字段由 deps 回调解释。 */
+export interface DagNodeLike {
+    readonly id: string;
+    /** 依赖边:本节点被这些 id 阻塞,直到它们都被判定为「已满足」。 */
+    readonly blocked_by: readonly string[];
+}
+/** 领域语义注入回调,把「依赖满足 / 候选态 / 额外门」外提,引擎不耦合具体 status 字面值。 */
+export interface DagSchedulerDeps<TNode extends DagNodeLike> {
+    /**
+     * 依赖是否已满足。接收依赖节点(可能 undefined —— 依赖 id 不在图里)。
+     * 各领域语义:
+     *  - bughunt / TaskBoard: undefined → 未满足(算 blocker);
+     *  - 黑板: undefined → 视为已解决(不算 blocker)。
+     */
+    isDependencySatisfied: (dep: TNode | undefined) => boolean;
+    /** 节点是否处于「可派发候选态」(bughunt: planned;Task: dispatchable 且无 blocked_reason;黑板: open)。 */
+    isCandidate: (node: TNode) => boolean;
+    /** 额外就绪门(契约 / evidence gate),返回缺口数组,空 = 通过;缺省视为无门。 */
+    evaluateExtraGate?: (node: TNode) => string[];
+}
+export interface DagTopoResult<TNode extends DagNodeLike> {
+    readonly order: readonly TNode[];
+}
+export interface DagCycleResult {
+    readonly cycle: readonly string[];
+}
+export interface DagNodeReadiness {
+    readonly ready: boolean;
+    readonly reason?: string;
+}
+/**
+ * Kahn 拓扑排序。存在环时返回 { cycle }(fail-closed,避免调度死锁)。
+ * 依赖边引用了图中不存在的 id 时,该边忽略(当作无依赖),与各领域既有行为一致。
+ */
+export declare function topologicalOrder<TNode extends DagNodeLike>(dag: readonly TNode[]): DagTopoResult<TNode> | DagCycleResult;
+/**
+ * 假设给 `nodeId` 追加 `newBlockedBy` 依赖,是否会形成环。
+ * 从每个 newBlockedBy 出发,沿现有 blocked_by 反向回溯,看能否回到 nodeId。
+ * 泛型自 TaskBoard.wouldCreateDependencyCycle 的 DFS。不修改 dag(纯查询)。
+ */
+export declare function wouldCreateCycle<TNode extends DagNodeLike>(dag: readonly TNode[], nodeId: string, newBlockedBy: readonly string[]): boolean;
+/**
+ * 节点是否就绪可派发,依次过三道门:
+ *  1. 候选态(isCandidate —— 非终态/非在跑/无外部阻塞);
+ *  2. blocked_by 全部已满足(isDependencySatisfied);
+ *  3. 额外门通过(evaluateExtraGate,如契约就绪 / evidence gate)。
+ * 任一不满足返回 { ready: false, reason }。reason 含语义标签供各领域测试匹配。
+ */
+export declare function isNodeReady<TNode extends DagNodeLike>(node: TNode, byId: ReadonlyMap<string, TNode>, deps: DagSchedulerDeps<TNode>): DagNodeReadiness;
+/**
+ * 就绪候选集:遍历 dag 过滤 ready 节点。**只返回候选,不自动 dispatch** ——
+ * dispatch 决策权保留给 Leader(凌霄铁律:DAG ready-node 仅作候选提示注入上下文)。
+ */
+export declare function getReadyNodes<TNode extends DagNodeLike>(dag: readonly TNode[], deps: DagSchedulerDeps<TNode>): TNode[];
+//# sourceMappingURL=DagScheduler.d.ts.map

package/dist/core/DagScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DagScheduler.d.ts","sourceRoot":"","sources":["../../src/core/DagScheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB,CAAC,KAAK,SAAS,WAAW;IACzD;;;;;OAKG;IACH,qBAAqB,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,SAAS,KAAK,OAAO,CAAC;IAC3D,sFAAsF;IACtF,WAAW,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC;IACtC,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,EAAE,CAAC;CAC/C;AAED,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,WAAW;IACtD,QAAQ,CAAC,KAAK,EAAE,SAAS,KAAK,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,WAAW,EACxD,GAAG,EAAE,SAAS,KAAK,EAAE,GACpB,aAAa,CAAC,KAAK,CAAC,GAAG,cAAc,CAiCvC;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,WAAW,EACxD,GAAG,EAAE,SAAS,KAAK,EAAE,EACrB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAYT;AAID;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,SAAS,WAAW,EACnD,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,EAChC,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAC5B,gBAAgB,CAalB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,SAAS,WAAW,EACrD,GAAG,EAAE,SAAS,KAAK,EAAE,EACrB,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAC5B,KAAK,EAAE,CAGT"}

package/dist/core/DagScheduler.js

@@ -0,0 +1,111 @@
+/**
+ * DagScheduler — 通用 DAG 调度纯函数(无 IO,确定性,零启发式)。
+ *
+ * 单一图算法真相源,服务凌霄原本各写一遍的多套依赖解锁:
+ *  - bughunt 调查 DAG(`BughuntDagScheduler` 薄封装复用本模块)
+ *  - 通用任务 DAG(`TaskBoard` 的环检测 / ready 判定复用本模块)
+ *  - 黑板 intent 依赖(`BlackboardGraph.getDispatchableIntents` 复用本模块)
+ *  - 项目蓝图子系统依赖(`ProjectBlueprint.getReadySubsystems` 复用本模块)
+ *
+ * 设计:领域语义(status 字面值 / 契约门 / evidence gate / 「依赖缺失是否视为已解决」)
+ * 全部外提成 `DagSchedulerDeps` 回调,引擎只懂 `{ id, blocked_by }` 的纯图运算。
+ * 同一套 Kahn 拓扑 + 三道门就绪判定 + DFS 环检测,各领域注入各自 deps,语义各自保留:
+ *   - bughunt: 依赖须 completed;候选态 planned;evidence gate
+ *   - TaskBoard: 依赖须 terminal+completed;候选态 dispatchable 且无 blocked_reason;契约门
+ *   - 黑板: 依赖缺失视为已解决(与上两者相反);候选态 open;无额外门
+ *
+ * 零运行时依赖(泛型自带,无 import),便于单测与跨入口复用。
+ */
+// ─── 拓扑排序(Kahn + 环检测,fail-closed)─────────────────────────────────────
+/**
+ * Kahn 拓扑排序。存在环时返回 { cycle }(fail-closed,避免调度死锁)。
+ * 依赖边引用了图中不存在的 id 时,该边忽略(当作无依赖),与各领域既有行为一致。
+ */
+export function topologicalOrder(dag) {
+    const ids = new Set(dag.map((n) => n.id));
+    const indeg = new Map();
+    const adj = new Map();
+    for (const n of dag) {
+        indeg.set(n.id, 0);
+        adj.set(n.id, []);
+    }
+    for (const n of dag) {
+        for (const b of n.blocked_by) {
+            if (ids.has(b)) {
+                adj.get(b).push(n.id);
+                indeg.set(n.id, (indeg.get(n.id) ?? 0) + 1);
+            }
+        }
+    }
+    const queue = [...dag]
+        .filter((n) => (indeg.get(n.id) ?? 0) === 0)
+        .map((n) => n.id);
+    const ordered = [];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        ordered.push(id);
+        for (const next of adj.get(id) ?? []) {
+            indeg.set(next, (indeg.get(next) ?? 0) - 1);
+            if ((indeg.get(next) ?? 0) === 0)
+                queue.push(next);
+        }
+    }
+    if (ordered.length < dag.length) {
+        const cyclic = dag.filter((n) => !ordered.includes(n.id)).map((n) => n.id);
+        return { cycle: cyclic };
+    }
+    return { order: ordered.map((id) => dag.find((n) => n.id === id)) };
+}
+// ─── 环检测(增量,模拟「给 nodeId 加这些依赖是否成环」)──────────────────────
+/**
+ * 假设给 `nodeId` 追加 `newBlockedBy` 依赖,是否会形成环。
+ * 从每个 newBlockedBy 出发,沿现有 blocked_by 反向回溯,看能否回到 nodeId。
+ * 泛型自 TaskBoard.wouldCreateDependencyCycle 的 DFS。不修改 dag(纯查询)。
+ */
+export function wouldCreateCycle(dag, nodeId, newBlockedBy) {
+    const byId = new Map(dag.map((n) => [n.id, n]));
+    const visit = (currentId, seen) => {
+        if (currentId === nodeId)
+            return true;
+        if (seen.has(currentId))
+            return false;
+        const nextSeen = new Set(seen);
+        nextSeen.add(currentId);
+        const current = byId.get(currentId);
+        if (!current)
+            return false;
+        return current.blocked_by.some((depId) => visit(depId, nextSeen));
+    };
+    return newBlockedBy.some((depId) => visit(depId, new Set()));
+}
+// ─── 就绪判定(三道门)+ 候选集 ───────────────────────────────────────────────
+/**
+ * 节点是否就绪可派发,依次过三道门:
+ *  1. 候选态(isCandidate —— 非终态/非在跑/无外部阻塞);
+ *  2. blocked_by 全部已满足(isDependencySatisfied);
+ *  3. 额外门通过(evaluateExtraGate,如契约就绪 / evidence gate)。
+ * 任一不满足返回 { ready: false, reason }。reason 含语义标签供各领域测试匹配。
+ */
+export function isNodeReady(node, byId, deps) {
+    if (!deps.isCandidate(node)) {
+        return { ready: false, reason: 'not a dispatch candidate' };
+    }
+    const blockers = node.blocked_by.filter((id) => !deps.isDependencySatisfied(byId.get(id)));
+    if (blockers.length > 0) {
+        return { ready: false, reason: `blocked_by=${blockers.join(',')}` };
+    }
+    const gaps = deps.evaluateExtraGate ? deps.evaluateExtraGate(node) : [];
+    if (gaps.length > 0) {
+        return { ready: false, reason: gaps.join('; ') };
+    }
+    return { ready: true };
+}
+/**
+ * 就绪候选集:遍历 dag 过滤 ready 节点。**只返回候选,不自动 dispatch** ——
+ * dispatch 决策权保留给 Leader(凌霄铁律:DAG ready-node 仅作候选提示注入上下文)。
+ */
+export function getReadyNodes(dag, deps) {
+    const byId = new Map(dag.map((n) => [n.id, n]));
+    return dag.filter((node) => isNodeReady(node, byId, deps).ready);
+}
+//# sourceMappingURL=DagScheduler.js.map

package/dist/core/DagScheduler.js.map

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