taskmeld 0.1.1

package/dist/src/pipeline/tool-activity.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolActivityLogger = void 0;
+const SESSION_AGENT_PATTERN = /^agent:([^:]+):/i;
+const MAX_SEEN_KEYS = 500;
+const findStringByKeys = (value, keys, depth = 0) => {
+    if (depth > 5 || value === null || value === undefined)
+        return null;
+    if (typeof value === "string")
+        return value.trim() || null;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = findStringByKeys(item, keys, depth + 1);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (typeof value !== "object")
+        return null;
+    const record = value;
+    for (const key of keys) {
+        const raw = record[key];
+        if (typeof raw === "string" && raw.trim())
+            return raw.trim();
+    }
+    for (const item of Object.values(record)) {
+        const found = findStringByKeys(item, keys, depth + 1);
+        if (found)
+            return found;
+    }
+    return null;
+};
+const createToolActivityLogger = (deps) => {
+    const seenOrder = [];
+    const seenSet = new Set();
+    const markSeen = (key) => {
+        if (seenSet.has(key))
+            return false;
+        seenSet.add(key);
+        seenOrder.push(key);
+        if (seenOrder.length > MAX_SEEN_KEYS) {
+            const oldest = seenOrder.shift();
+            if (oldest)
+                seenSet.delete(oldest);
+        }
+        return true;
+    };
+    const inferAgentId = (sessionKey) => {
+        if (!sessionKey)
+            return null;
+        const mapped = deps.resolveAgentBySessionId(sessionKey);
+        if (mapped && mapped.trim())
+            return mapped.trim();
+        const match = sessionKey.match(SESSION_AGENT_PATTERN);
+        return match?.[1] ?? null;
+    };
+    const handleFrame = (frame) => {
+        if (frame.type !== "event")
+            return;
+        if (frame.event !== "agent" && frame.event !== "session.tool")
+            return;
+        const payload = frame.payload;
+        if (!payload)
+            return;
+        if (payload.stream !== "tool")
+            return;
+        const data = (payload.data ?? {});
+        const phase = typeof data.phase === "string" ? data.phase.trim() : "";
+        const toolName = typeof data.name === "string" && data.name.trim() ? data.name.trim() : "unknown_tool";
+        const toolCallId = typeof data.toolCallId === "string" ? data.toolCallId.trim() : "";
+        const runId = typeof payload.runId === "string" && payload.runId.trim() ? payload.runId.trim() : "unknown";
+        const seq = typeof payload.seq === "number" ? String(payload.seq) : "n/a";
+        const sessionKey = findStringByKeys(payload, ["sessionKey", "sessionId", "key", "session"]);
+        const agentId = inferAgentId(sessionKey) ?? "unknown";
+        const dedupeKey = `${runId}|${toolCallId || toolName}|${phase}|${seq}`;
+        if (!markSeen(dedupeKey))
+            return;
+        if (phase === "start") {
+            deps.pushTimeline(`Agent ${agentId} 工具开始: ${toolName} (run:${runId})`);
+            return;
+        }
+        if (phase === "result" || phase === "end") {
+            const isError = data.isError === true;
+            deps.pushTimeline(`Agent ${agentId} 工具结束: ${toolName} (run:${runId}${isError ? ", error" : ""})`, isError ? "warn" : "info");
+            return;
+        }
+        deps.pushTimeline(`Agent ${agentId} 工具事件: ${toolName}/${phase || "unknown"} (run:${runId})`);
+    };
+    return {
+        handleFrame,
+    };
+};
+exports.createToolActivityLogger = createToolActivityLogger;

package/dist/src/pipeline/types/pipeline-link.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidLinkId = exports.buildJobId = void 0;
+const buildJobId = (linkId, outputId) => `job:${linkId}:${outputId}`;
+exports.buildJobId = buildJobId;
+const isValidLinkId = (id) => /^link:[a-zA-Z0-9._-]+$/.test(id);
+exports.isValidLinkId = isValidLinkId;

package/dist/src/pipeline/types/pipeline-output.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOutputId = void 0;
+const node_crypto_1 = require("node:crypto");
+/** 用去重键计算短哈希，稳定去重且长度可控。 */
+const buildOutputId = (pipelineId, runId, batchRunId, itemKey, outputNodeId, artifactId, hash) => {
+    const key = `${pipelineId}|${runId}|${batchRunId ?? ""}|${itemKey ?? ""}|${outputNodeId}|${artifactId}|${hash}`;
+    const digest = (0, node_crypto_1.createHash)("sha256").update(key).digest("hex").slice(0, 16);
+    return `output:${digest}`;
+};
+exports.buildOutputId = buildOutputId;

package/dist/src/pipeline/types/workflow.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/pipeline/workflow/branch-rules.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * 支线判定纯规则函数。
+ * 无外部依赖，只接受数据参数，供 workflow/validate 和 execution/dependency-check 共同使用。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBranchScope = exports.isCrossBranchEdgeByScope = exports.computeNodeScopes = void 0;
+// ====== Phase 2: 基于显式 branchScopeId 的支线规则 ======
+/**
+ * 从 workflow 的 route 边推导每个节点的 branch scope。
+ * scope 标识 = routerNodeId:routeValue，如 "router:a"。
+ * 主线节点 scope 为 null。
+ */
+const computeNodeScopes = (nodes, edges, explicitScopes) => {
+    const scopes = new Map();
+    // 初始化：有显式 scope 的用显式，否则为 null
+    for (const node of nodes) {
+        scopes.set(node.id, explicitScopes?.get(node.id) ?? null);
+    }
+    // 从 route 边推导 scope：路由边 from 的 scope 已知时，to 的 scope = fromScope != null ? fromScope : "from:when"
+    for (const edge of edges) {
+        if (edge.when === null)
+            continue;
+        const fromScope = scopes.get(edge.from);
+        const targetScope = fromScope != null ? fromScope : `${edge.from}:${edge.when}`;
+        const existing = scopes.get(edge.to);
+        if (existing == null) {
+            scopes.set(edge.to, targetScope);
+        }
+    }
+    // 传播 scope 沿普通依赖边：BFS 确保同一分支内的下游节点继承上游 scope。
+    // 多条路径到达节点时，若 scope 一致则合并；若冲突则保留首次设置的 scope。
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const edge of edges) {
+            if (edge.when !== null)
+                continue; // 只传播普通依赖边
+            const fromScope = scopes.get(edge.from);
+            if (fromScope == null)
+                continue; // 上游无 scope 则不传播
+            const toScope = scopes.get(edge.to);
+            if (toScope == null) {
+                scopes.set(edge.to, fromScope);
+                changed = true;
+            }
+        }
+    }
+    return scopes;
+};
+exports.computeNodeScopes = computeNodeScopes;
+/**
+ * 基于 scope 判断边是否为跨支线普通边。
+ * 跨支线：when 为 null 且 from 和 to 在不同的 scope 中。
+ */
+const isCrossBranchEdgeByScope = (edge, nodeScopes) => {
+    if (edge.when !== null)
+        return false;
+    const fromScope = nodeScopes.get(edge.from) ?? null;
+    const toScope = nodeScopes.get(edge.to) ?? null;
+    // 同 scope → 同一分支内，允许
+    if (fromScope === toScope)
+        return false;
+    // from 有 scope，to 无 scope → 支线结点向主线传播，不阻断（scope 沿依赖边继承）
+    if (fromScope != null && toScope == null)
+        return false;
+    // from 无 scope（主线），to 有 scope（支线）→ 禁止：主线不能无条件依赖支线内部节点
+    // from 和 to 都有 scope 但不同 → 禁止：不同支线之间的跨分支依赖
+    return fromScope !== toScope;
+};
+exports.isCrossBranchEdgeByScope = isCrossBranchEdgeByScope;
+/** 基于 scope 获取节点的支线身份。null scope = 主线。 */
+const getBranchScope = (nodeId, nodeScopes) => nodeScopes.get(nodeId) ?? null;
+exports.getBranchScope = getBranchScope;

package/dist/src/pipeline/workflow/defaults.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultWorkflowDefinition = exports.defaultTemplateNodes = void 0;
+const normalize_1 = require("./normalize");
+// ====== Default template nodes ======
+const defaultTemplateNodes = () => [];
+exports.defaultTemplateNodes = defaultTemplateNodes;
+const mapTemplateNodesToWorkflow = (nodes) => {
+    const workflowNodes = nodes.map((node) => ({
+        id: node.id,
+        name: node.title,
+        type: "task",
+        enabled: true,
+        isMainline: true,
+        lane: "main",
+        parallelGroupId: null,
+        executor: node.executor,
+        inputMode: "single",
+        outputMode: "single",
+        dependencyPolicy: "all",
+        routePolicy: null,
+        retryPolicy: {
+            maxAttempts: 2,
+            backoffMs: 0,
+        },
+        outputSpec: node.outputSpec,
+        instruction: node.instruction,
+        allowReject: node.allowReject,
+        maxRejectCount: node.maxRejectCount,
+    }));
+    const edges = [];
+    for (const node of nodes) {
+        for (const dep of node.dependsOn) {
+            edges.push({ from: dep, to: node.id, when: null });
+        }
+    }
+    return {
+        version: "3.0",
+        scheduler: (0, normalize_1.normalizeWorkflowScheduler)(undefined),
+        plugins: (0, normalize_1.normalizeWorkflowPlugins)(undefined),
+        output: { mode: "mainline_last", nodeId: null },
+        nodes: workflowNodes,
+        edges,
+        groups: [],
+    };
+};
+const defaultWorkflowDefinition = () => mapTemplateNodesToWorkflow((0, exports.defaultTemplateNodes)());
+exports.defaultWorkflowDefinition = defaultWorkflowDefinition;

package/dist/src/pipeline/workflow/io.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.savePipelineTemplateWithStorage = exports.savePipelineTemplate = exports.loadPipelineTemplateWithStorage = exports.loadPipelineTemplate = exports.saveWorkflowDefinitionWithStorage = exports.saveWorkflowDefinition = exports.loadWorkflowDefinitionWithStorage = exports.loadWorkflowDefinition = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const data_dir_1 = require("../../app/data-dir");
+const defaults_1 = require("./defaults");
+const template_mapper_1 = require("./template-mapper");
+const normalize_1 = require("./normalize");
+const validate_1 = require("./validate");
+const TEMPLATE_FILE = (0, data_dir_1.resolveTaskMeldDataPath)("pipeline-template.json");
+const loadWorkflowDefinition = () => {
+    return (0, exports.loadWorkflowDefinitionWithStorage)({});
+};
+exports.loadWorkflowDefinition = loadWorkflowDefinition;
+const loadWorkflowDefinitionWithStorage = (options) => {
+    const workflowFilePath = options.workflowFilePath ?? TEMPLATE_FILE;
+    if (!(0, node_fs_1.existsSync)(workflowFilePath)) {
+        return (0, defaults_1.defaultWorkflowDefinition)();
+    }
+    try {
+        const raw = (0, node_fs_1.readFileSync)(workflowFilePath, "utf8");
+        const parsed = JSON.parse(raw);
+        const readResult = (0, normalize_1.readWorkflowDefinitionFromRawDetailed)(parsed);
+        if (readResult.ok)
+            return readResult.workflow;
+        const error = new Error("invalid_persisted_workflow_definition");
+        error.detail = readResult.detail;
+        throw error;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "invalid_persisted_workflow_definition") {
+            throw error;
+        }
+        const wrapped = new Error("invalid_persisted_workflow_definition");
+        wrapped.detail = "workflow 文件解析失败，请检查 JSON 格式";
+        throw wrapped;
+    }
+};
+exports.loadWorkflowDefinitionWithStorage = loadWorkflowDefinitionWithStorage;
+const saveWorkflowDefinition = (workflow) => {
+    (0, exports.saveWorkflowDefinitionWithStorage)(workflow, {});
+};
+exports.saveWorkflowDefinition = saveWorkflowDefinition;
+const saveWorkflowDefinitionWithStorage = (workflow, options) => {
+    const validation = (0, validate_1.validateWorkflowDefinition)(workflow);
+    if (!validation.ok) {
+        const error = new Error(validation.error);
+        error.detail = validation.detail;
+        throw error;
+    }
+    const outputValidation = (0, validate_1.validateWorkflowOutputConfig)(workflow);
+    if (!outputValidation.ok) {
+        const error = new Error(outputValidation.error);
+        error.detail = outputValidation.detail;
+        throw error;
+    }
+    const workflowFilePath = options.workflowFilePath ?? TEMPLATE_FILE;
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(workflowFilePath), { recursive: true });
+    const persisted = {
+        ...workflow,
+        version: "3.0",
+        edges: workflow.edges.map((edge) => edge.when === null
+            ? { from: edge.from, to: edge.to, kind: "dependency" }
+            : { from: edge.from, to: edge.to, kind: "route", route: edge.when }),
+    };
+    (0, node_fs_1.writeFileSync)(workflowFilePath, JSON.stringify(persisted, null, 2), "utf8");
+};
+exports.saveWorkflowDefinitionWithStorage = saveWorkflowDefinitionWithStorage;
+const loadPipelineTemplate = () => {
+    return (0, exports.loadPipelineTemplateWithStorage)({});
+};
+exports.loadPipelineTemplate = loadPipelineTemplate;
+const loadPipelineTemplateWithStorage = (options) => {
+    const workflow = (0, exports.loadWorkflowDefinitionWithStorage)(options);
+    const legacy = (0, template_mapper_1.workflowToTemplateNodes)(workflow);
+    return legacy;
+};
+exports.loadPipelineTemplateWithStorage = loadPipelineTemplateWithStorage;
+const savePipelineTemplate = (nodes) => {
+    (0, exports.savePipelineTemplateWithStorage)(nodes, {});
+};
+exports.savePipelineTemplate = savePipelineTemplate;
+const savePipelineTemplateWithStorage = (nodes, options) => {
+    const current = (0, exports.loadWorkflowDefinitionWithStorage)(options);
+    const merged = (0, template_mapper_1.mergeTemplateNodesIntoWorkflow)(current, nodes);
+    (0, exports.saveWorkflowDefinitionWithStorage)(merged, options);
+};
+exports.savePipelineTemplateWithStorage = savePipelineTemplateWithStorage;

package/dist/src/pipeline/workflow/normalize.js

@@ -0,0 +1,347 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWorkflowDefinitionFromRawDetailed = exports.readWorkflowDefinitionFromRaw = exports.normalizeWorkflowOutputConfig = exports.normalizeWorkflowGroup = exports.normalizeWorkflowEdge = exports.normalizeWorkflowNode = exports.normalizeTemplateNode = exports.normalizeWorkflowPlugins = exports.normalizeWorkflowScheduler = exports.isRecord = void 0;
+const validate_1 = require("./validate");
+const routes_1 = require("./routes");
+// ====== Internal constants / helpers ======
+const DEFAULT_REMOTE_BATCH_URL = String(process.env.OPENCLAW_PIPELINE_POOL_URL ?? "").trim();
+const guards_1 = require("../../utils/guards");
+Object.defineProperty(exports, "isRecord", { enumerable: true, get: function () { return guards_1.isRecord; } });
+const isExecutorRole = (value) => value === "planner" || value === "coder" || value === "tester" || value === "reviewer" || value === "operator";
+const normalizeNonEmptyString = (value) => {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed || null;
+};
+const normalizeStringArray = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== "string")
+            continue;
+        const trimmed = item.trim();
+        if (!trimmed)
+            continue;
+        out.push(trimmed);
+    }
+    return out;
+};
+const normalizeIntegerInRange = (value, fallback, min, max) => {
+    const num = Number(value);
+    if (!Number.isFinite(num))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.trunc(num)));
+};
+const normalizeWorkflowScheduler = (value) => {
+    const record = (0, guards_1.isRecord)(value) ? value : {};
+    const loopGuard = (0, guards_1.isRecord)(record.loopGuard) ? record.loopGuard : {};
+    const mode = record.mode === "manual" ? "manual" : "auto";
+    const dispatchBy = record.dispatchBy === "node" ? "node" : "item";
+    return {
+        enabled: record.enabled !== false,
+        mode,
+        dispatchBy,
+        maxConcurrency: normalizeIntegerInRange(record.maxConcurrency, 3, 1, 20),
+        loopGuard: {
+            maxGlobalIterations: normalizeIntegerInRange(loopGuard.maxGlobalIterations, 200, 10, 100_000),
+            maxPerItemLoop: normalizeIntegerInRange(loopGuard.maxPerItemLoop, 8, 1, 100),
+        },
+    };
+};
+exports.normalizeWorkflowScheduler = normalizeWorkflowScheduler;
+const normalizeRemoteBatchPlugin = (value) => {
+    const record = (0, guards_1.isRecord)(value) ? value : {};
+    return {
+        enabled: record.enabled === true,
+        url: normalizeNonEmptyString(record.url) ?? DEFAULT_REMOTE_BATCH_URL,
+        startBatch: normalizeIntegerInRange(record.startBatch, 1, 1, 1_000_000),
+        // 批大小与取数来源都属于低频配置，统一并入插件配置，避免主面板堆叠过多参数。
+        batchSize: normalizeIntegerInRange(record.batchSize, 5, 1, 1_000),
+        sourceField: normalizeNonEmptyString(record.sourceField) ?? "list30",
+    };
+};
+const normalizeSchedulerPlugin = (value) => {
+    const record = (0, guards_1.isRecord)(value) ? value : {};
+    return {
+        // 调度器历史上默认对所有流水线开启；插件化后继续保持默认开启，避免升级后界面和行为突然消失。
+        enabled: record.enabled !== false,
+    };
+};
+const normalizeWorkflowPlugins = (value) => {
+    const record = (0, guards_1.isRecord)(value) ? value : {};
+    return {
+        // 插件能力对所有流水线一致，这里只记录每条流水线自己的启用与参数配置。
+        remoteBatch: normalizeRemoteBatchPlugin(record.remoteBatch),
+        scheduler: normalizeSchedulerPlugin(record.scheduler),
+    };
+};
+exports.normalizeWorkflowPlugins = normalizeWorkflowPlugins;
+const normalizeRoutePolicy = (value) => {
+    if (!(0, guards_1.isRecord)(value))
+        return null;
+    const allowed = (0, routes_1.normalizeRouteListWithDefaults)(normalizeStringArray(value.allowed));
+    if (allowed.length < 2 || allowed.length > 5)
+        return null;
+    return { allowed };
+};
+const normalizeRetryPolicy = (value) => {
+    const record = (0, guards_1.isRecord)(value) ? value : {};
+    return {
+        maxAttempts: normalizeIntegerInRange(record.maxAttempts, 2, 1, 10),
+        backoffMs: normalizeIntegerInRange(record.backoffMs, 0, 0, 600_000),
+    };
+};
+const normalizeExecutor = (value) => {
+    if (!(0, guards_1.isRecord)(value))
+        return null;
+    const role = value.role;
+    if (!isExecutorRole(role))
+        return null;
+    const agentId = normalizeNonEmptyString(value.agentId);
+    if (!agentId)
+        return null;
+    const fallbackAgentId = normalizeNonEmptyString(value.fallbackAgentId);
+    const sessionId = normalizeNonEmptyString(value.sessionId);
+    return {
+        agentId,
+        role,
+        fallbackAgentId,
+        sessionId,
+    };
+};
+const normalizeOutputSpec = (value) => {
+    if (!(0, guards_1.isRecord)(value))
+        return null;
+    const type = normalizeNonEmptyString(value.type);
+    if (!type)
+        return null;
+    const schemaVersion = normalizeIntegerInRange(value.schemaVersion, 0, 1, Number.MAX_SAFE_INTEGER);
+    if (schemaVersion <= 0)
+        return null;
+    return { type, schemaVersion };
+};
+const normalizeTemplateNode = (value) => {
+    if (!(0, guards_1.isRecord)(value))
+        return null;
+    const id = normalizeNonEmptyString(value.id);
+    const title = normalizeNonEmptyString(value.title);
+    if (!id || !title)
+        return null;
+    const executor = normalizeExecutor(value.executor);
+    if (!executor)
+        return null;
+    const outputSpec = normalizeOutputSpec(value.outputSpec);
+    if (!outputSpec)
+        return null;
+    const instruction = typeof value.instruction === "string" ? value.instruction.trim() : "";
+    const dependsOn = normalizeStringArray(value.dependsOn);
+    const allowReject = value.allowReject === true;
+    const maxRejectCount = normalizeIntegerInRange(value.maxRejectCount, 3, 0, 10);
+    return {
+        id,
+        title,
+        dependsOn,
+        executor,
+        instruction,
+        outputSpec,
+        allowReject,
+        maxRejectCount,
+    };
+};
+exports.normalizeTemplateNode = normalizeTemplateNode;
+const normalizeWorkflowNode = (value) => {
+    if (!(0, guards_1.isRecord)(value))
+        return null;
+    const id = normalizeNonEmptyString(value.id);
+    const name = normalizeNonEmptyString(value.name);
+    if (!id || !name)
+        return null;
+    const executor = normalizeExecutor(value.executor);
+    if (!executor)
+        return null;
+    const outputSpec = normalizeOutputSpec(value.outputSpec);
+    if (!outputSpec)
+        return null;
+    const lane = value.lane === "branch" ? "branch" : "main";
+    const inputMode = value.inputMode === "batch" ? "batch" : "single";
+    const outputMode = value.outputMode === "array" ? "array" : "single";
+    const routePolicy = value.routePolicy === null ? null : normalizeRoutePolicy(value.routePolicy);
+    if (value.routePolicy !== undefined && value.routePolicy !== null && !routePolicy)
+        return null;
+    const dependencyPolicy = value.dependencyPolicy === "any" ? "any" : "all";
+    const branchScopeId = normalizeNonEmptyString(value.branchScopeId);
+    const routeSourceNodeId = normalizeNonEmptyString(value.routeSourceNodeId);
+    const routeValue = normalizeNonEmptyString(value.routeValue);
+    const node = {
+        id,
+        name,
+        type: normalizeNonEmptyString(value.type) ?? "task",
+        enabled: value.enabled !== false,
+        isMainline: value.isMainline !== false,
+        lane,
+        parallelGroupId: normalizeNonEmptyString(value.parallelGroupId),
+        executor,
+        inputMode,
+        outputMode,
+        dependencyPolicy,
+        routePolicy,
+        retryPolicy: normalizeRetryPolicy(value.retryPolicy),
+        outputSpec,
+        instruction: typeof value.instruction === "string" ? value.instruction.trim() : "",
+        allowReject: value.allowReject === true,
+        maxRejectCount: normalizeIntegerInRange(value.maxRejectCount, 3, 0, 10),
+    };
+    // 仅在显式提供时写入 branch scope 字段，避免 null 值污染 JSON 输出
+    if (branchScopeId)
+        node.branchScopeId = branchScopeId;
+    if (routeSourceNodeId)
+        node.routeSourceNodeId = routeSourceNodeId;
+    if (routeValue)
+        node.routeValue = routeValue;
+    return node;
+};
+exports.normalizeWorkflowNode = normalizeWorkflowNode;
+const normalizeWorkflowEdge = (value) => {
+    if (!(0, guards_1.isRecord)(value))
+        return null;
+    const from = normalizeNonEmptyString(value.from);
+    const to = normalizeNonEmptyString(value.to);
+    if (!from || !to)
+        return null;
+    return {
+        from,
+        to,
+        when: normalizeNonEmptyString(value.when),
+    };
+};
+exports.normalizeWorkflowEdge = normalizeWorkflowEdge;
+const normalizeWorkflowEdgeV3 = (value) => {
+    if (!(0, guards_1.isRecord)(value))
+        return null;
+    const from = normalizeNonEmptyString(value.from);
+    const to = normalizeNonEmptyString(value.to);
+    if (!from || !to)
+        return null;
+    // v3 API 闭环要求：读取接口返回运行时 when 形状时，写回 /workflow 也必须可直接接受。
+    // 这里仅在 version=3.0 契约下做"同版本双形状"归一化，不允许 version=2.0 旁路写入。
+    if ("when" in value) {
+        return {
+            from,
+            to,
+            when: normalizeNonEmptyString(value.when),
+        };
+    }
+    const kind = value.kind;
+    if (kind === "dependency") {
+        return { from, to, when: null };
+    }
+    if (kind === "route") {
+        const route = normalizeNonEmptyString(value.route);
+        if (!route)
+            return null;
+        return { from, to, when: route };
+    }
+    return null;
+};
+const normalizeWorkflowGroup = (value) => {
+    if (!(0, guards_1.isRecord)(value))
+        return null;
+    const id = normalizeNonEmptyString(value.id);
+    if (!id)
+        return null;
+    const members = [...new Set(normalizeStringArray(value.members))];
+    if (members.length < 2)
+        return null;
+    const type = value.type === "parallel" ? "parallel" : null;
+    if (!type)
+        return null;
+    const joinPolicy = "all";
+    // 历史 any/quorum 降级：运行时仅支持 all，读取历史数据时静默降级为 all。
+    // 保存新 workflow 时 validate 会显式拒绝 any/quorum。
+    if (value.joinPolicy === "any" || value.joinPolicy === "quorum") {
+        // 静默降级 — 历史数据兼容，新保存会被 validate 拦截
+    }
+    return {
+        id,
+        type,
+        members,
+        joinPolicy,
+    };
+};
+exports.normalizeWorkflowGroup = normalizeWorkflowGroup;
+const normalizeWorkflowOutputConfig = (value) => {
+    const record = (0, guards_1.isRecord)(value) ? value : {};
+    const mode = record.mode === "explicit" ? "explicit" : "mainline_last";
+    const nodeId = mode === "explicit" ? normalizeNonEmptyString(record.nodeId) : null;
+    return { mode, nodeId };
+};
+exports.normalizeWorkflowOutputConfig = normalizeWorkflowOutputConfig;
+// ====== Read raw / parse ======
+const readWorkflowDefinitionFromRaw = (value) => {
+    const parsed = (0, exports.readWorkflowDefinitionFromRawDetailed)(value);
+    return parsed.ok ? parsed.workflow : null;
+};
+exports.readWorkflowDefinitionFromRaw = readWorkflowDefinitionFromRaw;
+const readWorkflowDefinitionFromRawDetailed = (value) => {
+    if (!(0, guards_1.isRecord)(value)) {
+        return { ok: false, error: "invalid_workflow_definition", detail: "workflow 根对象格式非法" };
+    }
+    if (value.version === "2.0") {
+        return {
+            ok: false,
+            error: "workflow_migration_required",
+            detail: "检测到 workflow v2.0，请先执行迁移脚本再写入",
+        };
+    }
+    if (value.version !== "3.0") {
+        return { ok: false, error: "invalid_workflow_definition", detail: `workflow.version 非法: ${String(value.version ?? "")}` };
+    }
+    if (!Array.isArray(value.nodes) || !Array.isArray(value.edges) || !Array.isArray(value.groups)) {
+        return { ok: false, error: "invalid_workflow_definition", detail: "workflow.nodes/edges/groups 必须为数组" };
+    }
+    const nodes = [];
+    for (const item of value.nodes) {
+        const normalized = (0, exports.normalizeWorkflowNode)(item);
+        if (!normalized)
+            return { ok: false, error: "invalid_workflow_definition", detail: "workflow.nodes 存在非法节点结构" };
+        nodes.push(normalized);
+    }
+    const edges = [];
+    for (const item of value.edges) {
+        const normalized = normalizeWorkflowEdgeV3(item);
+        if (!normalized)
+            return { ok: false, error: "invalid_workflow_definition", detail: "workflow.edges 存在非法边结构" };
+        edges.push(normalized);
+    }
+    const groups = [];
+    for (const item of value.groups) {
+        // 预检：在 normalize 静默降级之前显式拒绝不支持的 joinPolicy
+        if ((0, guards_1.isRecord)(item) && (item.joinPolicy === "any" || item.joinPolicy === "quorum")) {
+            return {
+                ok: false,
+                error: "join_policy_not_supported",
+                detail: `并行组 "${String(item.id ?? "?")}" 的 joinPolicy "${String(item.joinPolicy)}" 未支持，当前仅支持 "all"`,
+            };
+        }
+        const normalized = (0, exports.normalizeWorkflowGroup)(item);
+        if (!normalized)
+            return { ok: false, error: "invalid_workflow_definition", detail: "workflow.groups 存在非法并行组结构" };
+        groups.push(normalized);
+    }
+    const workflow = {
+        version: "3.0",
+        scheduler: (0, exports.normalizeWorkflowScheduler)(value.scheduler),
+        plugins: (0, exports.normalizeWorkflowPlugins)(value.plugins),
+        output: (0, exports.normalizeWorkflowOutputConfig)(value.output),
+        nodes,
+        edges,
+        groups,
+    };
+    const validation = (0, validate_1.validateWorkflowGraph)(workflow);
+    if (!validation.ok)
+        return { ok: false, error: validation.error, detail: validation.detail };
+    return { ok: true, workflow };
+};
+exports.readWorkflowDefinitionFromRawDetailed = readWorkflowDefinitionFromRawDetailed;