@hoplogic/hopjit 0.1.0

package/dist/parser.js

@@ -0,0 +1,802 @@
+// @module: spec-parser ^anc-struct-spec-parser
+// Hand-written line-by-line parser for HopSpec v3 markdown.
+// Remark was evaluated and rejected (nesting, +→ outputs, blockquotes all break).
+import { ALL_STEP_TYPES, CONTAINER_STEP_TYPES } from './ast-helpers.js';
+import { extractHopPythonFence, parseActBody } from './act-body-parser.js';
+import { extractDocRefs } from './doc-ref.js';
+const MAX_INPUT_SIZE = 100 * 1024;
+const MAX_NESTING_DEPTH = 10;
+// ===== Regex patterns =====
+const RE_HEADING = /^(#{1,6})\s+(.*\S)/;
+const RE_STEP = /^(\d+(?:\.\d+)*)\.\s*\[(\w+)(?:\s+([^\]]*))?\]\s*(.*)/;
+const RE_INPUT = /^-\s*←\s*(.+)/;
+const RE_OUTPUT = /^\+\s*→\s*(.+)/;
+const RE_INSTRUCTION = /^>\s?(.*)/;
+const RE_VAR_DECL = /^-\s*(\w+)\s*:\s*(\S+(?:\([^)]*\))?)\s*(?:#\s*(.*))?$/;
+const RE_LIST_ITEM = /^-\s+(.*)/;
+const RE_ID_LINE = /^Id\s*:\s*(\S+)/;
+const RE_FENCE = /^```/;
+const SECTION_KEYWORDS = {
+    goal: 'goal',
+    constraints: 'constraints',
+    types: 'types',
+    inputs: 'inputs',
+    outputs: 'outputs',
+    config: 'config',
+    steps: 'steps',
+};
+function identifySections(lines) {
+    const sections = [];
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (RE_FENCE.test(line.trim())) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const hm = line.match(RE_HEADING);
+        if (hm) {
+            const depth = hm[1].length;
+            const text = hm[2].trim();
+            if (depth === 1 && sections.length === 0) {
+                sections.push({ kind: 'title', startLine: i, endLine: i + 1 });
+            }
+            else if (depth === 2) {
+                const key = text.toLowerCase().replace(/\s+/g, '');
+                const kind = SECTION_KEYWORDS[key];
+                // 非关键字的 depth-2 标题（如标题风的 `## Task` 契约分区）静默忽略——不产生 section、
+                // 零解析影响。这是有意支持的 Obsidian 折叠分区惯例，非漏网 bug，勿加报错。
+                // 见 design ^anc-rule-surface-heading-flavor。// @a: anc-rule-surface-heading-flavor
+                if (kind)
+                    sections.push({ kind, startLine: i, endLine: i + 1 });
+            }
+            continue;
+        }
+        // Inline label format: "Goal: text", "Inputs:", etc.
+        if (sections.length > 0) {
+            const labelMatch = line.match(/^(\w+)\s*:/);
+            if (labelMatch) {
+                const key = labelMatch[1].toLowerCase();
+                const kind = SECTION_KEYWORDS[key];
+                if (kind && !sections.some(s => s.kind === kind)) {
+                    sections.push({ kind, startLine: i, endLine: i + 1 });
+                }
+            }
+        }
+        // Id: line (special case, not a section heading)
+        if (RE_ID_LINE.test(line) && !sections.some(s => s.kind === 'id')) {
+            sections.push({ kind: 'id', startLine: i, endLine: i + 1 });
+        }
+    }
+    // Set endLine for each section to next section's start (or EOF)
+    for (let i = 0; i < sections.length; i++) {
+        const next = sections[i + 1];
+        sections[i].endLine = next ? next.startLine : lines.length;
+    }
+    return sections;
+}
+// ===== Header parsing =====
+function parseHeaderSections(lines, sections, errors) {
+    const header = { title: '' };
+    const titleSec = sections.find(s => s.kind === 'title');
+    if (titleSec) {
+        const hm = lines[titleSec.startLine].match(RE_HEADING);
+        if (hm)
+            header.title = hm[2].trim();
+    }
+    else {
+        errors.push({ kind: 'parse', line: 1, message: 'Missing spec title (# heading)' });
+    }
+    const idSec = sections.find(s => s.kind === 'id');
+    if (idSec) {
+        const m = lines[idSec.startLine].match(RE_ID_LINE);
+        if (m)
+            header.id = m[1].trim();
+    }
+    const goalSec = sections.find(s => s.kind === 'goal');
+    if (goalSec)
+        header.goal = parsePlainTextSection(lines, goalSec);
+    const conSec = sections.find(s => s.kind === 'constraints');
+    if (conSec) {
+        header.constraints = parseListSection(lines, conSec);
+        const conDocRefs = extractDocRefs(header.constraints.join('\n')); // @a: anc-rule-doc-ref-extract
+        if (conDocRefs.length > 0)
+            header.doc_refs = conDocRefs;
+    }
+    const typesSec = sections.find(s => s.kind === 'types');
+    if (typesSec)
+        header.types = parseTypesSection(lines, typesSec, errors);
+    const inputsSec = sections.find(s => s.kind === 'inputs');
+    if (inputsSec)
+        header.inputs = parseVarDeclSection(lines, inputsSec);
+    const outputsSec = sections.find(s => s.kind === 'outputs');
+    if (outputsSec)
+        header.outputs = parseOutputDeclSection(lines, outputsSec);
+    const configSec = sections.find(s => s.kind === 'config');
+    if (configSec)
+        header.config = parseConfigSection(lines, configSec);
+    return header;
+}
+function sectionBodyLines(lines, sec) {
+    const start = sec.startLine;
+    const firstLine = lines[start];
+    // Skip the heading/label line itself; for inline label with content, handle separately
+    const isHeading = RE_HEADING.test(firstLine);
+    const bodyStart = isHeading ? start + 1 : start;
+    // For inline label format "Goal: text", the text after ":" is part of content
+    const result = [];
+    for (let i = bodyStart; i < sec.endLine; i++) {
+        const line = lines[i];
+        if (i === start && !isHeading) {
+            // Inline label: extract text after ":"
+            const colonIdx = line.indexOf(':');
+            if (colonIdx >= 0) {
+                const rest = line.slice(colonIdx + 1).trim();
+                if (rest)
+                    result.push(rest);
+                continue;
+            }
+        }
+        result.push(line);
+    }
+    return result;
+}
+function parsePlainTextSection(lines, sec) {
+    return sectionBodyLines(lines, sec)
+        .map(l => l.trim())
+        .filter(l => l.length > 0)
+        .join('\n');
+}
+function parseListSection(lines, sec) {
+    const items = [];
+    for (const line of sectionBodyLines(lines, sec)) {
+        const m = line.trim().match(RE_LIST_ITEM);
+        if (m)
+            items.push(m[1].trim());
+    }
+    return items;
+}
+function parseTypesSection(lines, sec, errors) {
+    const types = [];
+    const bodyLines = sectionBodyLines(lines, sec);
+    let current = null;
+    let typeIndent = -1;
+    for (let i = 0; i < bodyLines.length; i++) {
+        const raw = bodyLines[i];
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        // New type declaration: "- TypeName:" or "TypeName:"（容忍尾部 `# 注释`）
+        const typeMatch = trimmed.match(/^-?\s*(\w+)\s*:\s*(?:#.*)?$/);
+        if (typeMatch) {
+            if (current)
+                types.push(current);
+            current = { name: typeMatch[1], fields: {} };
+            typeIndent = raw.search(/\S/);
+            continue;
+        }
+        // Field line (indented under type): "fieldName: typeString"
+        if (current) {
+            const lineIndent = raw.search(/\S/);
+            if (lineIndent > typeIndent) {
+                // 容忍字段行首的 `- ` 列表前缀（`- id: line` 与 `id: line` 均可，与 TypeName 行 `-?` 一致）。
+                // 旧正则漏了 `-?\s*`，致 `- field: type` 写法的字段被整体丢弃、fields 空（C8 字段校验落空）。
+                const fieldMatch = trimmed.match(/^-?\s*(\w+)\s*:\s*(\S+(?:\([^)]*\))?)/);
+                if (fieldMatch) {
+                    current.fields[fieldMatch[1]] = fieldMatch[2];
+                }
+                continue;
+            }
+            // Not indented under type — finalize current TypeDecl
+            types.push(current);
+            current = null;
+        }
+    }
+    if (current)
+        types.push(current);
+    return types;
+}
+function parseVarDeclSection(lines, sec) {
+    const vars = [];
+    for (const line of sectionBodyLines(lines, sec)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const m = trimmed.match(RE_VAR_DECL);
+        if (m) {
+            vars.push({ name: m[1], type: m[2], description: m[3]?.trim() });
+        }
+    }
+    return vars;
+}
+function parseOutputDeclSection(lines, sec) {
+    const outputs = [];
+    for (const line of sectionBodyLines(lines, sec)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const m = trimmed.match(RE_VAR_DECL);
+        if (m) {
+            outputs.push({ name: m[1], type: m[2], description: m[3]?.trim() ?? '' });
+        }
+    }
+    return outputs;
+}
+function parseConfigSection(lines, sec) {
+    const config = {};
+    for (const line of sectionBodyLines(lines, sec)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const m = trimmed.match(/^-?\s*(\w+)\s*:\s*(.+)/);
+        if (m) {
+            const val = m[2].trim();
+            const num = Number(val);
+            config[m[1]] = Number.isFinite(num) ? num : val;
+        }
+    }
+    return config;
+}
+function parseStepSection(lines, sec, errors) {
+    const flatSteps = [];
+    let current = null;
+    let inFence = false;
+    // 标题风裸 fence 捕获态：进入裸 ```hop_python 且属 heading-flavor 步骤时置真，
+    // fence 开/闭行与 body 行捕获进 current.instruction（body 按开栏缩进 de-indent）。
+    // 见 design ^anc-rule-surface-heading-flavor。
+    let captureFence = false;
+    let fenceIndent = 0;
+    for (let i = sec.startLine + 1; i < sec.endLine; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (RE_FENCE.test(trimmed)) {
+            // heading-flavor 步骤的裸 fence：捕获而非丢弃。开栏进捕获态、记缩进；闭栏出捕获态。
+            // 开/闭行归一（无缩进）推入 instruction，供 extractHopPythonFence 提取。
+            if (!inFence && current?.headingFlavor && !captureFence) {
+                captureFence = true;
+                fenceIndent = line.length - line.trimStart().length;
+                current.instruction.push(trimmed);
+                continue;
+            }
+            if (captureFence) {
+                current.instruction.push(trimmed);
+                captureFence = false;
+                continue;
+            }
+            inFence = !inFence;
+            continue;
+        }
+        if (captureFence) {
+            // body 行：按开栏缩进 de-indent（act body 缩进敏感），不足则整体 trimStart 兜底。
+            current.instruction.push(line.length >= fenceIndent ? line.slice(fenceIndent) : line.trimStart());
+            continue;
+        }
+        if (inFence)
+            continue;
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith('%%'))
+            continue;
+        // Try step line。标题风：先剥行首 `#` 前缀（`### 1. [reason] …`），再匹配 RE_STEP。
+        // 剥掉过前缀 = heading-flavor 步骤，启用下方段落吸收。`#` 个数不参与树构建（树由 step ID
+        // 数字编码），故深过 h6 的 `#######` 照常解析。见 design ^anc-rule-surface-heading-flavor。
+        const stepBody = trimmed.replace(/^#+\s+/, '');
+        const isHeadingFlavor = stepBody !== trimmed;
+        const stepMatch = stepBody.match(RE_STEP);
+        if (stepMatch) {
+            if (current) {
+                current.source_location.line_end = i;
+                flatSteps.push(current);
+            }
+            const [, stepId, stepType, attrStr, summaryRaw] = stepMatch;
+            const attrs = attrStr ? parseStepAttrs(attrStr) : {};
+            if (!ALL_STEP_TYPES.has(stepType)) {
+                errors.push({ kind: 'parse', line: i + 1, message: `Unknown step type: ${stepType}` });
+            }
+            current = {
+                step_id: stepId,
+                step_type: stepType,
+                summary: summaryRaw.trim(),
+                attrs,
+                inputs: [],
+                outputs: [],
+                rawOutputs: [],
+                instruction: [],
+                ...(isHeadingFlavor ? { headingFlavor: true } : {}),
+                source_location: { line_start: i + 1, line_end: i + 1 },
+            };
+            continue;
+        }
+        if (!current)
+            continue;
+        // Input line: - ← var1, var2
+        const inputMatch = trimmed.match(RE_INPUT);
+        if (inputMatch) {
+            current.inputs.push(...parseInputExpr(inputMatch[1].trim()));
+            continue;
+        }
+        // Output line: + → ...
+        const outputMatch = trimmed.match(RE_OUTPUT);
+        if (outputMatch) {
+            const outBody = outputMatch[1].trim();
+            // 单行 for-each：`+ → <item> : for-each <list>`——左段=元素绑定输出(itemVar)，右段=遍历列表(listVar)。
+            // 必须先剥离 for-each 段再 parseOutputExpr，否则 `<item> : for-each` 会被单输出正则误读为 name:type。
+            const forEachInline = outBody.match(/^(.*?)\s*:\s*for-each\s+(\S+)\s*$/);
+            if (forEachInline) {
+                const itemDecl = parseOutputExpr(forEachInline[1].trim());
+                current.outputs.push(...itemDecl);
+                current.rawOutputs.push(forEachInline[1].trim());
+                // itemVar = 左段声明的输出名（元素绑定）；listVar = for-each 后的列表变量
+                current.forEach = { listVar: forEachInline[2], itemVar: itemDecl[0]?.name ?? forEachInline[1].trim() };
+                continue;
+            }
+            current.outputs.push(...parseOutputExpr(outBody));
+            current.rawOutputs.push(outBody);
+            continue;
+        }
+        // 旧两行式 for-each 已废弃（硬替换）：残留独立 `for-each X → Y` 行 → 友好报错，提示改单行式。
+        const staleForEach = trimmed.match(/^for-each\s+(\S+)\s*(?:→|->)\s*(\S+)$/);
+        if (staleForEach) {
+            errors.push({
+                kind: 'parse',
+                line: i + 1,
+                message: `for-each 已改为单行语法，请写 \`+ → ${staleForEach[2]} : for-each ${staleForEach[1]}\`（旧的独立 \`for-each X → Y\` 行已废弃）`,
+            });
+            continue;
+        }
+        // Instruction line: > text
+        const instrMatch = trimmed.match(RE_INSTRUCTION);
+        if (instrMatch) {
+            current.instruction.push(instrMatch[1]);
+            continue;
+        }
+        // 末尾兜底：标题风步骤的纯文本行（标题下自然段落）吸收进 instruction，等价内联风 `>` 指令。
+        // 内联风（非 heading-flavor）维持现状——未知行静默丢弃，零回归。
+        // 见 design ^anc-rule-surface-heading-flavor。// @a: anc-rule-surface-heading-flavor
+        if (current.headingFlavor) {
+            current.instruction.push(trimmed);
+            continue;
+        }
+    }
+    if (current) {
+        current.source_location.line_end = sec.endLine;
+        flatSteps.push(current);
+    }
+    return buildStepTree(flatSteps, errors);
+}
+function parseStepAttrs(attrStr) {
+    const attrs = {};
+    const parts = attrStr.trim().split(/\s+/);
+    for (const part of parts) {
+        const eqIdx = part.indexOf('=');
+        if (eqIdx >= 0) {
+            attrs[part.slice(0, eqIdx)] = part.slice(eqIdx + 1);
+        }
+        else {
+            attrs[part] = true;
+        }
+    }
+    return attrs;
+}
+function parseInputExpr(text) {
+    // 先剥行尾 `# 就近注释`（标题风建议输入加 # 说明，见 design ^anc-rule-surface-heading-flavor）——
+    // 手法对齐 parseOutputExpr 的 hashIdx，注释不剥会污染变量名/映射来源。// @a: anc-rule-surface-heading-flavor
+    const hashIdx = text.indexOf('#');
+    const body = hashIdx >= 0 ? text.slice(0, hashIdx) : text;
+    // 支持冒号映射 "target: source"（call 输入映射 子参数: 父变量）；无冒号则 name=source 同名
+    return body.split(',').map(s => s.trim()).filter(Boolean).map(item => {
+        const colonIdx = item.indexOf(':');
+        if (colonIdx > 0) {
+            const name = item.slice(0, colonIdx).trim();
+            const source = item.slice(colonIdx + 1).trim();
+            return { name, source };
+        }
+        return { name: item, source: item };
+    });
+}
+/** 解析 `= 初值` 字面量为运行时值：Null/None/null→null；[]→空数组；{}→空对象；true/false→bool；
+ * 数字→number；带引号或裸文本→字符串。按字面量形态解析，不依赖声明 type。见 exec-engine
+ * ^anc-exec-output-init。 // @a: anc-exec-output-init */
+function parseInitValue(raw) {
+    const s = raw.trim();
+    if (/^(null|none)$/i.test(s))
+        return null;
+    if (s === '[]')
+        return [];
+    if (s === '{}')
+        return {};
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(s))
+        return Number(s);
+    // 带引号字符串剥引号；裸文本原样作字符串
+    const q = s.match(/^["'](.*)["']$/);
+    return q ? q[1] : s;
+}
+function parseOutputExpr(text) {
+    if (text.toLowerCase() === 'none')
+        return [];
+    // Single output with type + optional init: "name: type = 初值  # description"
+    const singleMatch = text.match(/^(\w+)\s*:\s*(\S+(?:\([^)]*\))?)\s*(?:=\s*([^#]*?))?\s*(?:#\s*(.*))?$/);
+    if (singleMatch) {
+        const decl = {
+            name: singleMatch[1],
+            type: singleMatch[2],
+            description: singleMatch[4]?.trim() ?? '',
+        };
+        if (singleMatch[3] !== undefined && singleMatch[3].trim() !== '') {
+            decl.default = parseInitValue(singleMatch[3]);
+        }
+        return [decl];
+    }
+    // Comma-separated names (简写引用，无类型): "var1, var2  # 注释"
+    // 先剥离行尾 # 注释——更新模式 `+ → findings  # 更新...` 走此分支，注释不剥离会污染变量名
+    const hashIdx = text.indexOf('#');
+    const namesPart = hashIdx >= 0 ? text.slice(0, hashIdx) : text;
+    return namesPart.split(',').map(s => s.trim()).filter(Boolean).map(name => ({
+        name,
+        type: 'text',
+        description: '',
+    }));
+}
+// ===== Tree building =====
+function getParentId(stepId) {
+    const lastDot = stepId.lastIndexOf('.');
+    return lastDot >= 0 ? stepId.slice(0, lastDot) : null;
+}
+function buildStepTree(flatSteps, errors) {
+    const nodeMap = new Map();
+    const topLevel = [];
+    // First pass: create all nodes
+    for (const flat of flatSteps) {
+        const node = flatToStepNode(flat, errors);
+        nodeMap.set(flat.step_id, node);
+    }
+    // Second pass: establish parent-child relationships
+    for (const flat of flatSteps) {
+        const parentId = getParentId(flat.step_id);
+        if (!parentId) {
+            topLevel.push(nodeMap.get(flat.step_id));
+            continue;
+        }
+        const parent = nodeMap.get(parentId);
+        if (!parent) {
+            errors.push({
+                kind: 'parse',
+                line: flat.source_location.line_start,
+                message: `Step ${flat.step_id} references non-existent parent ${parentId}`,
+            });
+            topLevel.push(nodeMap.get(flat.step_id));
+            continue;
+        }
+        if (CONTAINER_STEP_TYPES.has(parent.step_type)) {
+            const container = parent;
+            if (!container.children)
+                container.children = [];
+            container.children.push(nodeMap.get(flat.step_id));
+        }
+        else {
+            errors.push({
+                kind: 'parse',
+                line: flat.source_location.line_start,
+                message: `Step ${flat.step_id} is nested under non-container step ${parentId} (type: ${parent.step_type})`,
+            });
+        }
+    }
+    return topLevel;
+}
+const MODEL_RE = /^@model\s+(\S+)$/;
+function extractModelAnnotation(lines) {
+    let model_override;
+    const filtered = [];
+    for (const line of lines) {
+        const m = MODEL_RE.exec(line.trim());
+        if (m) {
+            model_override = m[1];
+        }
+        else {
+            filtered.push(line);
+        }
+    }
+    return { instruction: filtered, model_override };
+}
+/** 取布尔修饰属性（true / 'true' 都算真）。adaptive/finally/require_human 共用，消 5 处复制。 */
+function boolAttr(attrs, key) {
+    const v = attrs[key];
+    return v === true || v === 'true';
+}
+/** 解析 subtask/case 共有的 retry/adaptive 修饰符（两分支原逐字复制）。 */
+function parseRetryAdaptive(attrs) {
+    return {
+        retry: attrs['retry'] ? Number(attrs['retry']) : undefined,
+        adaptive: boolAttr(attrs, 'adaptive'),
+    };
+}
+function flatToStepNode(flat, errors) {
+    const { instruction: rawInstruction, model_override } = extractModelAnnotation(flat.instruction);
+    const instructionText = rawInstruction.length > 0 ? rawInstruction.join('\n') : undefined;
+    const docRefs = instructionText ? extractDocRefs(instructionText) : []; // @a: anc-rule-doc-ref-extract
+    const base = {
+        step_id: flat.step_id,
+        step_type: flat.step_type,
+        summary: flat.summary,
+        inputs: flat.inputs.length > 0 ? flat.inputs : undefined,
+        outputs: flat.outputs.length > 0 ? flat.outputs : undefined,
+        instruction: instructionText,
+        ...(docRefs.length > 0 ? { doc_refs: docRefs } : {}),
+        ...(model_override ? { model_override } : {}),
+        source_location: flat.source_location,
+    };
+    switch (flat.step_type) {
+        case 'subtask': {
+            const { retry, adaptive } = parseRetryAdaptive(flat.attrs);
+            return { ...base, step_type: 'subtask', retry, adaptive, children: [] };
+        }
+        case 'parallel':
+            return { ...base, children: [], ...(flat.forEach ? { forEach: flat.forEach } : {}) };
+        case 'branch':
+            return { ...base, children: [] };
+        case 'loop': {
+            const maxIter = flat.attrs['max_iterations'] ? Number(flat.attrs['max_iterations']) : undefined;
+            return { ...base, step_type: 'loop', max_iterations: maxIter, children: [] };
+        }
+        case 'case': {
+            // case 条件解析(见 design/spec-parser.md ^anc-rule-case-condition):
+            // 仅行尾最后一对半角括号 (...) 内是机器求值的 condition;括号前文字为人读描述、丢弃;
+            // 无尾括号则整行作 condition(兼容 [case] severity == 'fatal' 纯条件写法);
+            // 结果为空或 default → 'default'(默认 case)。
+            // @a: anc-rule-case-condition
+            const condition = extractCaseCondition(flat.summary);
+            // case 就是 branch 下的 subtask：解析 retry/adaptive 修饰符，语义同 subtask
+            const { retry: caseRetry, adaptive: caseAdaptive } = parseRetryAdaptive(flat.attrs);
+            return { ...base, step_type: 'case', condition, retry: caseRetry, adaptive: caseAdaptive, children: [] };
+        }
+        case 'call': {
+            let callee_spec_id;
+            let summary = flat.summary;
+            const colonIdx = summary.indexOf(' : ');
+            if (colonIdx >= 0) {
+                callee_spec_id = summary.slice(0, colonIdx).trim();
+                summary = summary.slice(colonIdx + 3).trim();
+            }
+            const param_mapping = buildParamMapping(flat.inputs);
+            const output_mapping = buildOutputMapping(flat.rawOutputs);
+            // call 的 - ←/+ → 是双向映射，不是 VarBinding/OutputDecl——清除 base.inputs/outputs 避免 V4 把映射当类型校验
+            return { ...base, step_type: 'call', summary, inputs: undefined, outputs: undefined, callee_spec_id, param_mapping, output_mapping };
+        }
+        case 'act': {
+            const { body, instruction } = parseActBodyFromFlat(flat, errors);
+            return { ...base, step_type: 'act', instruction, ...(body ? { body } : {}) };
+        }
+        case 'commit': {
+            const { body, instruction } = parseActBodyFromFlat(flat, errors);
+            const irreversible_action = instruction || flat.summary;
+            return { ...base, step_type: 'commit', irreversible_action, instruction, ...(body ? { body } : {}) };
+        }
+        case 'check': {
+            const is_finally = boolAttr(flat.attrs, 'finally');
+            return { ...base, step_type: 'check', ...(is_finally ? { is_finally: true } : {}) };
+        }
+        case 'confirm': {
+            const require_human = boolAttr(flat.attrs, 'require_human');
+            return { ...base, step_type: 'confirm', ...(require_human ? { require_human: true } : {}) };
+        }
+        case 'ask': {
+            const require_human = boolAttr(flat.attrs, 'require_human');
+            // present_inputs: 逗号分隔的变量名列表,如 [ask present_inputs=raw_outline,other]。
+            // 见 design/spec-parser.md ^anc-rule-p14。// @a: anc-rule-p14
+            const piRaw = flat.attrs['present_inputs'];
+            const present_inputs = typeof piRaw === 'string' && piRaw.length > 0
+                ? piRaw.split(',').map(s => s.trim()).filter(Boolean)
+                : undefined;
+            return { ...base, step_type: 'ask',
+                ...(require_human ? { require_human: true } : {}),
+                ...(present_inputs ? { present_inputs } : {}),
+            };
+        }
+        case 'exit': {
+            return { ...base, step_type: 'exit' };
+        }
+        default:
+            return base;
+    }
+}
+// act/commit：从 instruction 行提取 ```hop_python 围栏 body，剩余自然语言行（去 @model）作 instruction。
+function parseActBodyFromFlat(flat, errors) {
+    const { bodyLines, bodyStartIndex, narrative } = extractHopPythonFence(flat.instruction);
+    const { instruction: narrativeNoModel } = extractModelAnnotation(narrative);
+    const instruction = narrativeNoModel.length > 0 ? narrativeNoModel.join('\n') : undefined;
+    if (!bodyLines)
+        return { instruction };
+    // 围栏行在原文的绝对行号：步骤起始 + body 在 instruction 中的偏移（近似，错误定位用）
+    const baseLine = (flat.source_location?.line_start ?? 0) + bodyStartIndex;
+    const body = parseActBody(bodyLines, baseLine, errors) ?? undefined;
+    return { body, instruction };
+}
+function buildParamMapping(inputs) {
+    if (inputs.length === 0)
+        return undefined;
+    // 输入映射：from=来源(父变量=source), to=目标(子 Input 名=name)
+    return inputs.map(b => ({ from: b.source, to: b.name }));
+}
+// case 条件提取（见 design/spec-parser.md ^anc-rule-case-condition）。
+// 仅行尾最后一对半角括号 (...) 内是机器求值的 condition；括号前文字为人读描述、丢弃。
+// 无尾括号则整行作 condition（兼容 `[case] severity == 'fatal'` 纯条件写法）。
+// 结果为空或 'default' → 'default'（默认 case，与 engine-traverse 的 isDefault 判定对齐）。
+// 取**最后一对**括号而非首个，避免描述里的括号（如全角「（含未知）」+ 半角条件）误截。
+// @a: anc-rule-case-condition
+function extractCaseCondition(summary) {
+    const s = (summary ?? '').trim();
+    if (!s)
+        return 'default';
+    // 尾部最后一对半角括号
+    const m = s.match(/\(([^()]*)\)\s*$/);
+    const raw = (m ? m[1] : s).trim();
+    if (!raw || raw.toLowerCase() === 'default')
+        return 'default';
+    return raw;
+}
+// call 输出映射：+ → parent_var: callee_output（目标父变量: 来源子输出）。同名省略。
+function buildOutputMapping(rawOutputs) {
+    const items = rawOutputs.flatMap(raw => raw.split(',').map(s => s.trim()).filter(Boolean));
+    if (items.length === 0)
+        return undefined;
+    if (items.length === 1 && items[0].toLowerCase() === 'none')
+        return undefined;
+    return items.map(item => {
+        // 去掉行尾 # 注释
+        const noComment = item.split('#')[0].trim();
+        const colonIdx = noComment.indexOf(':');
+        if (colonIdx > 0) {
+            const to = noComment.slice(0, colonIdx).trim(); // 父变量（目标）
+            const from = noComment.slice(colonIdx + 1).trim(); // 子输出（来源）
+            return { from, to };
+        }
+        return { from: noComment, to: noComment }; // 同名
+    });
+}
+// ===== Depth check =====
+function getMaxNesting(steps) {
+    let max = 0;
+    for (const step of steps) {
+        const depth = step.step_id.split('.').length;
+        if (depth > max)
+            max = depth;
+        if ('children' in step && Array.isArray(step.children)) {
+            const childMax = getMaxNesting(step.children);
+            if (childMax > max)
+                max = childMax;
+        }
+    }
+    return max;
+}
+// ===== Main export =====
+export function parseSpec(markdown) {
+    const errors = [];
+    if (new TextEncoder().encode(markdown).length > MAX_INPUT_SIZE) {
+        errors.push({ kind: 'parse', line: 0, message: `Input exceeds ${MAX_INPUT_SIZE / 1024}KB limit` });
+        return { ast: { header: { title: '' } }, errors };
+    }
+    const lines = markdown.split('\n');
+    const sections = identifySections(lines);
+    const header = parseHeaderSections(lines, sections, errors);
+    const stepsSec = sections.find(s => s.kind === 'steps');
+    let steps;
+    if (stepsSec) {
+        steps = parseStepSection(lines, stepsSec, errors);
+        const maxDepth = getMaxNesting(steps);
+        if (maxDepth > MAX_NESTING_DEPTH) {
+            errors.push({
+                kind: 'parse', line: stepsSec.startLine + 1,
+                message: `Step nesting depth ${maxDepth} exceeds limit of ${MAX_NESTING_DEPTH}`,
+            });
+        }
+    }
+    return { ast: { header, steps }, errors };
+}
+// ===== Serializer =====
+export function serializeSpec(ast) {
+    const lines = [];
+    lines.push(`# ${ast.header.title}`);
+    if (ast.header.id)
+        lines.push(`Id: ${ast.header.id}`);
+    lines.push('');
+    if (ast.header.goal) {
+        lines.push('## Goal');
+        lines.push(ast.header.goal);
+        lines.push('');
+    }
+    if (ast.header.constraints?.length) {
+        lines.push('## Constraints');
+        for (const c of ast.header.constraints)
+            lines.push(`- ${c}`);
+        lines.push('');
+    }
+    if (ast.header.types?.length) {
+        lines.push('## Types');
+        for (const t of ast.header.types) {
+            lines.push(`- ${t.name}:`);
+            for (const [field, type] of Object.entries(t.fields)) {
+                lines.push(`    ${field}: ${type}`);
+            }
+        }
+        lines.push('');
+    }
+    if (ast.header.inputs?.length) {
+        lines.push('## Inputs');
+        for (const v of ast.header.inputs) {
+            let line = `- ${v.name}: ${v.type}`;
+            if (v.description)
+                line += `  # ${v.description}`;
+            lines.push(line);
+        }
+        lines.push('');
+    }
+    if (ast.header.outputs?.length) {
+        lines.push('## Outputs');
+        for (const o of ast.header.outputs) {
+            let line = `- ${o.name}: ${o.type}`;
+            if (o.description)
+                line += `  # ${o.description}`;
+            lines.push(line);
+        }
+        lines.push('');
+    }
+    if (ast.header.config) {
+        lines.push('## Config');
+        for (const [key, val] of Object.entries(ast.header.config)) {
+            lines.push(`- ${key}: ${val}`);
+        }
+        lines.push('');
+    }
+    if (ast.steps?.length) {
+        lines.push('## Steps');
+        serializeSteps(ast.steps, lines);
+    }
+    return lines.join('\n') + '\n';
+}
+function serializeSteps(steps, lines) {
+    for (const step of steps) {
+        const depth = step.step_id.split('.').length - 1;
+        const indent = '  '.repeat(depth);
+        let stepLine = `${indent}${step.step_id}. [${step.step_type}`;
+        if (step.step_type === 'subtask') {
+            const st = step;
+            if (st.retry !== undefined)
+                stepLine += ` retry=${st.retry}`;
+            if (st.adaptive)
+                stepLine += ' adaptive';
+        }
+        if (step.step_type === 'loop') {
+            const lt = step;
+            if (lt.max_iterations !== undefined)
+                stepLine += ` max_iterations=${lt.max_iterations}`;
+        }
+        stepLine += `] ${step.summary}`;
+        lines.push(stepLine);
+        const bodyIndent = '  '.repeat(depth + 1);
+        if (step.inputs?.length) {
+            lines.push(`${bodyIndent}- ← ${step.inputs.map(i => i.name).join(', ')}`);
+        }
+        if (step.outputs?.length) {
+            for (const o of step.outputs) {
+                let outLine = `${bodyIndent}+ → ${o.name}: ${o.type}`;
+                if (o.description)
+                    outLine += `  # ${o.description}`;
+                lines.push(outLine);
+            }
+        }
+        if (step.instruction) {
+            for (const iline of step.instruction.split('\n')) {
+                lines.push(`${bodyIndent}> ${iline}`);
+            }
+        }
+        if ('children' in step && Array.isArray(step.children)) {
+            serializeSteps(step.children, lines);
+        }
+    }
+}