@hoplogic/hopjit 0.1.0

package/dist/validator.js

@@ -0,0 +1,959 @@
+// @module: spec-parser ^anc-struct-spec-parser
+// 37-rule validator for SpecAST (from design/spec-parser.md appendix).
+// S1-S12 structure, C1-C7 control flow, V1-V7 variables, P1-P15 special steps.
+import { ALL_STEP_TYPES, CONTAINER_STEP_TYPES, EXECUTABLE_STEP_TYPES, hasChildren, getChildren, isUpdateModeOutput } from './ast-helpers.js';
+import { ACT_BUILTINS, ACT_BUILTIN_NAMES } from './act-builtins.js';
+import { checkDocRefExists } from './doc-ref.js';
+// branch 声明聚合输出（统一接口名），各 case 同名填充（同一个东西）。
+// branch + case 都开作用域。见 ^anc-exec-container-output
+const SCOPE_CREATING_CONTAINERS = new Set(['subtask', 'parallel', 'loop', 'branch', 'case']);
+/** Leaf step types — cannot have children */
+const LEAF_STEP_TYPES = new Set([
+    'reason', 'act', 'check', 'confirm', 'ask', 'commit', 'call', 'break', 'continue', 'exit',
+]);
+/** Spec 校验入口——对 SpecAST 执行结构/控制流/变量/特殊步骤共 37 条规则，返回违规列表（放行前闸门）。见 [[spec-parser#^anc-rule-all]]。 */
+export function validateSpec(ast, docRefCtx) {
+    const errors = [];
+    structuralRuleS10(ast, errors);
+    structuralRules(ast, errors);
+    controlFlowRules(ast, errors);
+    variableRules(ast, errors);
+    specialStepRules(ast, errors);
+    if (docRefCtx)
+        docRefRuleP15(ast, errors, docRefCtx); // 仅当有 workspace 访问能力时校验
+    return errors;
+}
+// P15: doc-ref [[doc#章节]] 静态存在性校验 // @a: anc-rule-p15
+function docRefRuleP15(ast, errors, ctx) {
+    const check = (refs, step_id, line) => {
+        for (const ref of refs ?? []) {
+            const err = checkDocRefExists(ctx.workspace_dir, ctx.sandbox, ref);
+            if (err)
+                errors.push(ve('P15', 'error', `doc-ref [[${ref.doc}#${ref.section}]] 校验失败: ${err}`, step_id, line));
+        }
+    };
+    check(ast.header.doc_refs); // spec 级（Constraints）
+    for (const step of ast.steps ? flattenSteps(ast.steps) : []) {
+        check(step.doc_refs, step.step_id, step.source_location?.line_start);
+    }
+}
+// ===== Helpers =====
+function ve(rule, severity, message, step_id, line) {
+    return { kind: 'validate', rule, severity, message, step_id, line };
+}
+function flattenSteps(steps) {
+    const result = [];
+    function walk(nodes) {
+        for (const n of nodes) {
+            result.push(n);
+            for (const c of getChildren(n))
+                walk([c]);
+        }
+    }
+    walk(steps);
+    return result;
+}
+function findAncestor(stepId, allSteps, predicate) {
+    let id = stepId;
+    while (id.includes('.')) {
+        id = id.slice(0, id.lastIndexOf('.'));
+        const parent = allSteps.get(id);
+        if (parent && predicate(parent))
+            return parent;
+    }
+    return undefined;
+}
+// ===== S1-S9: Structural rules =====
+function structuralRules(ast, errors) {
+    // S1: title non-empty // @a: anc-rule-s1
+    if (!ast.header.title?.trim()) {
+        errors.push(ve('S1', 'error', 'Spec must have a non-empty title'));
+    }
+    // S8: goal non-empty // @a: anc-rule-s8
+    if (!ast.header.goal?.trim()) {
+        errors.push(ve('S8', 'error', 'Spec must have a non-empty goal'));
+    }
+    if (!ast.steps)
+        return;
+    const allFlat = flattenSteps(ast.steps);
+    const idSet = new Set();
+    for (const step of allFlat) {
+        const loc = step.source_location?.line_start;
+        // S2: step_id format // @a: anc-rule-s2
+        if (!/^\d+(\.\d+)*$/.test(step.step_id) || step.step_id.split('.').some(n => Number(n) < 1)) {
+            errors.push(ve('S2', 'error', `Invalid step_id format: "${step.step_id}"`, step.step_id, loc));
+        }
+        // S3: step_id uniqueness // @a: anc-rule-s3
+        if (idSet.has(step.step_id)) {
+            errors.push(ve('S3', 'error', `Duplicate step_id: "${step.step_id}"`, step.step_id, loc));
+        }
+        idSet.add(step.step_id);
+        // S4: valid step_type // @a: anc-rule-s4
+        if (!ALL_STEP_TYPES.has(step.step_type)) {
+            errors.push(ve('S4', 'error', `Invalid step_type: "${step.step_type}"`, step.step_id, loc));
+        }
+        // S5: container steps must have ≥1 child（含 case≡subtask）// @a: anc-rule-s5
+        if (CONTAINER_STEP_TYPES.has(step.step_type)) {
+            const children = getChildren(step);
+            if (children.length === 0) {
+                errors.push(ve('S5', 'error', `Container step "${step.step_id}" (${step.step_type}) has no children`, step.step_id, loc));
+            }
+        }
+        // S9: container with outputs referenced downstream must declare them // @a: anc-rule-s9
+        // branch 声明聚合输出（统一接口名），case 同名填充（同一个东西），都受 S9 约束
+        if (CONTAINER_STEP_TYPES.has(step.step_type)) {
+            if (!step.outputs || step.outputs.length === 0) {
+                const prefix = step.step_id + '.';
+                const isReferenced = allFlat.some(other => other.inputs?.some(b => b.source.includes(prefix)));
+                if (isReferenced) {
+                    errors.push(ve('S9', 'error', `Container step "${step.step_id}" (${step.step_type}) outputs are referenced but not declared`, step.step_id, loc));
+                }
+            }
+        }
+        // S6: child step_id must inherit parent step_id as prefix // @a: anc-rule-s6
+        const children = getChildren(step);
+        for (const child of children) {
+            if (!child.step_id.startsWith(step.step_id + '.')) {
+                errors.push(ve('S6', 'error', `Child step_id "${child.step_id}" does not start with parent "${step.step_id}."`, child.step_id, child.source_location?.line_start));
+            }
+        }
+    }
+    // S7: top-level step IDs must be single numbers // @a: anc-rule-s7
+    for (const step of ast.steps) {
+        if (step.step_id.includes('.')) {
+            errors.push(ve('S7', 'error', `Top-level step_id "${step.step_id}" must be a single number`, step.step_id, step.source_location?.line_start));
+        }
+    }
+    // S11: leaf steps cannot have children // @a: anc-rule-s11
+    for (const step of allFlat) {
+        if (LEAF_STEP_TYPES.has(step.step_type) && 'children' in step) {
+            const children = step.children;
+            if (Array.isArray(children) && children.length > 0) {
+                const loc = step.source_location?.line_start;
+                errors.push(ve('S11', 'error', `叶子步骤 "${step.step_id}" (${step.step_type}) 不能有 children`, step.step_id, loc));
+            }
+        }
+    }
+    // S12: parallel children must not have inter-sibling data flow dependencies // @a: anc-rule-s12
+    // 注：parallel 嵌套 parallel 不报错——v2 真并行只扇出最外层，内层在 worker 子实例内退化顺序模拟
+    // （决策3 一层并行）。S12 的无依赖约束保证串/并等价，故嵌套退化语义安全。见 design/exec-engine.md ^anc-exec-parallel-batch
+    for (const step of allFlat) {
+        if (step.step_type === 'parallel' && hasChildren(step)) {
+            const pStep = step;
+            // Collect output names declared by each child (top-level only)
+            const childOutputSets = new Map();
+            for (const child of pStep.children) {
+                const outputs = new Set();
+                if (child.outputs) {
+                    for (const o of child.outputs)
+                        outputs.add(o.name);
+                }
+                // Also collect outputs from all descendants of this child
+                const descendants = flattenSteps([child]);
+                for (const d of descendants) {
+                    if (d.outputs) {
+                        for (const o of d.outputs)
+                            outputs.add(o.name);
+                    }
+                }
+                childOutputSets.set(child.step_id, outputs);
+            }
+            // Check if any child references outputs from a sibling
+            for (const child of pStep.children) {
+                const allChildSteps = flattenSteps([child]);
+                for (const descendant of allChildSteps) {
+                    if (!descendant.inputs)
+                        continue;
+                    for (const binding of descendant.inputs) {
+                        // Check if binding.source matches any sibling's output
+                        childOutputSets.forEach((siblingOutputs, siblingId) => {
+                            if (siblingId === child.step_id)
+                                return; // same child tree, skip
+                            if (siblingOutputs.has(binding.source)) {
+                                const loc2 = descendant.source_location?.line_start;
+                                errors.push(ve('S12', 'error', `parallel 内步骤 "${descendant.step_id}" 引用了同级子步骤 "${siblingId}" 的输出 "${binding.source}"`, descendant.step_id, loc2));
+                            }
+                        });
+                    }
+                }
+            }
+        }
+    }
+}
+// S10: spec with steps must have ≥1 step; spec without steps must have goal+outputs // @a: anc-rule-s10
+function structuralRuleS10(ast, errors) {
+    if (ast.steps !== undefined) {
+        // Has Steps section — must contain at least one step
+        if (ast.steps.length === 0) {
+            errors.push(ve('S10', 'error', '有 Steps 的 Spec 至少包含一个步骤'));
+        }
+    }
+    else {
+        // No Steps — capability declaration must have Goal and Outputs
+        if (!ast.header.goal?.trim()) {
+            errors.push(ve('S10', 'error', '无 Steps 的 Spec（能力声明）必须有 Goal'));
+        }
+        if (!ast.header.outputs || ast.header.outputs.length === 0) {
+            errors.push(ve('S10', 'error', '无 Steps 的 Spec（能力声明）必须有 Outputs'));
+        }
+    }
+}
+// ===== C1-C6: Control flow rules =====
+function controlFlowRules(ast, errors) {
+    if (!ast.steps)
+        return;
+    const allFlat = flattenSteps(ast.steps);
+    const stepMap = new Map(allFlat.map(s => [s.step_id, s]));
+    for (const step of allFlat) {
+        const loc = step.source_location?.line_start;
+        // C1: case only as direct child of branch // @a: anc-rule-c1
+        if (step.step_type === 'case') {
+            const parentId = step.step_id.includes('.') ? step.step_id.slice(0, step.step_id.lastIndexOf('.')) : null;
+            const parent = parentId ? stepMap.get(parentId) : undefined;
+            if (!parent || parent.step_type !== 'branch') {
+                errors.push(ve('C1', 'error', `Case step "${step.step_id}" is not a direct child of a branch`, step.step_id, loc));
+            }
+        }
+        // C2: branch children must all be case, ≥1 (single case = if-then) // @a: anc-rule-c2
+        if (step.step_type === 'branch') {
+            const children = getChildren(step);
+            const nonCaseChildren = children.filter(c => c.step_type !== 'case');
+            if (nonCaseChildren.length > 0) {
+                errors.push(ve('C2', 'error', `Branch "${step.step_id}" children must all be case steps`, step.step_id, loc));
+            }
+            if (children.length < 1) {
+                errors.push(ve('C2', 'error', `Branch "${step.step_id}" must have at least 1 case child`, step.step_id, loc));
+            }
+        }
+        // C3: break/continue only inside loop // @a: anc-rule-c3
+        if (step.step_type === 'break' || step.step_type === 'continue') {
+            const loopAncestor = findAncestor(step.step_id, stepMap, s => s.step_type === 'loop');
+            if (!loopAncestor) {
+                errors.push(ve('C3', 'error', `${step.step_type} step "${step.step_id}" is not inside a loop`, step.step_id, loc));
+            }
+        }
+        // C6: check must be inside subtask or case // @a: anc-rule-c6
+        if (step.step_type === 'check') {
+            const containerAncestor = findAncestor(step.step_id, stepMap, s => s.step_type === 'subtask' || s.step_type === 'case');
+            if (!containerAncestor) {
+                errors.push(ve('C6', 'error', `Check step "${step.step_id}" must be inside a subtask or case`, step.step_id, loc));
+            }
+        }
+        // P11: check fixed signature — exactly one bool slot + one text slot // @a: anc-rule-p11
+        // check 是内置验证算子，固定输出签名（封闭）：恰好 bool（判定槽）+ text（说明槽），
+        // 引擎按类型定位（[[exec-engine#^anc-exec-check-verdict]]）。不能多/少/换类型。
+        if (step.step_type === 'check') {
+            const outs = step.outputs ?? [];
+            const boolCount = outs.filter(o => o.type === 'bool').length;
+            const textCount = outs.filter(o => o.type === 'text').length;
+            if (!(outs.length === 2 && boolCount === 1 && textCount === 1)) {
+                errors.push(ve('P11', 'error', `Check step "${step.step_id}" must declare exactly two outputs: one bool (verdict) + one text (explanation), got [${outs.map(o => o.type).join(', ') || 'none'}]`, step.step_id, loc));
+            }
+        }
+        // C5: loop must have reachable termination path // @a: anc-rule-c5
+        if (step.step_type === 'loop') {
+            if (!hasTerminationPath(step)) {
+                errors.push(ve('C5', 'warn', `Loop "${step.step_id}" has no reachable termination path (break/exit)`, step.step_id, loc));
+            }
+        }
+    }
+    // C4: warn about unreachable steps after exit/break // @a: anc-rule-c4
+    checkUnreachableAfterExit(ast.steps, errors);
+    // C7: check finally must be inside subtask and at the end of children // @a: anc-rule-c7
+    for (const step of allFlat) {
+        if (step.step_type === 'check' && step.is_finally) {
+            const loc = step.source_location?.line_start;
+            // Must be inside a subtask
+            const subtaskAncestor = findAncestor(step.step_id, stepMap, s => s.step_type === 'subtask');
+            if (!subtaskAncestor) {
+                errors.push(ve('C7', 'error', `Check finally step "${step.step_id}" must be inside a subtask`, step.step_id, loc));
+                continue;
+            }
+            // Must be at the end of immediate parent's children
+            const parentId = step.step_id.includes('.') ? step.step_id.slice(0, step.step_id.lastIndexOf('.')) : null;
+            const parent = parentId ? stepMap.get(parentId) : undefined;
+            if (parent && CONTAINER_STEP_TYPES.has(parent.step_type)) {
+                const siblings = getChildren(parent);
+                // Find index of this step among siblings
+                const idx = siblings.findIndex(s => s.step_id === step.step_id);
+                // Check that all steps after this one are also check finally
+                for (let i = idx + 1; i < siblings.length; i++) {
+                    const sib = siblings[i];
+                    if (sib.step_type !== 'check' || !sib.is_finally) {
+                        errors.push(ve('C7', 'error', `Check finally step "${step.step_id}" must be at the end of its container's children (non-finally step "${sib.step_id}" follows)`, step.step_id, loc));
+                        break;
+                    }
+                }
+                // Check that all steps before this one that are not check-finally don't follow a check-finally
+                for (let i = 0; i < idx; i++) {
+                    const sib = siblings[i];
+                    if (sib.step_type === 'check' && sib.is_finally) {
+                        // A check-finally before this one, check there's no non-finally between them
+                        for (let j = i + 1; j < idx; j++) {
+                            const between = siblings[j];
+                            if (between.step_type !== 'check' || !between.is_finally) {
+                                errors.push(ve('C7', 'error', `Check finally steps must be contiguous at the end of container — non-finally step "${between.step_id}" interrupts the sequence`, between.step_id, between.source_location?.line_start));
+                                break;
+                            }
+                        }
+                        break;
+                    }
+                }
+            }
+        }
+    }
+}
+function checkUnreachableAfterExit(steps, errors) {
+    scanSiblingList(steps, errors);
+    for (const step of steps) {
+        const children = getChildren(step);
+        if (children.length > 0) {
+            if (step.step_type === 'branch') {
+                for (const c of children) {
+                    checkUnreachableAfterExit(getChildren(c), errors);
+                }
+            }
+            else {
+                checkUnreachableAfterExit(children, errors);
+            }
+        }
+    }
+}
+function scanSiblingList(siblings, errors) {
+    for (let i = 0; i < siblings.length - 1; i++) {
+        const step = siblings[i];
+        if (step.step_type === 'exit' || step.step_type === 'break') {
+            const next = siblings[i + 1];
+            const loc = next.source_location?.line_start;
+            errors.push(ve('C4', 'warn', `Step "${next.step_id}" is unreachable after ${step.step_type} step "${step.step_id}"`, next.step_id, loc));
+            break;
+        }
+    }
+}
+function hasTerminationPath(loop) {
+    function scan(nodes) {
+        if (!nodes)
+            return false;
+        for (const n of nodes) {
+            if (n.step_type === 'break' || n.step_type === 'exit')
+                return true;
+            if (n.step_type === 'loop')
+                continue; // nested loop's break doesn't terminate outer
+            const children = getChildren(n);
+            if (children.length > 0 && scan(children))
+                return true;
+        }
+        return false;
+    }
+    return loop.max_iterations !== undefined || scan(loop.children);
+}
+function variableRules(ast, errors) {
+    // V5: input names unique (header-level, no steps needed) // @a: anc-rule-v5
+    if (ast.header.inputs) {
+        const seen = new Set();
+        for (const v of ast.header.inputs) {
+            if (seen.has(v.name)) {
+                errors.push(ve('V5', 'error', `Duplicate input variable: "${v.name}"`));
+            }
+            seen.add(v.name);
+        }
+    }
+    // V7: input variable types must be valid (ValueTypeString or declared TypeDecl) // @a: anc-rule-v7
+    if (ast.header.inputs) {
+        const declaredTypes = new Set();
+        if (ast.header.types) {
+            for (const t of ast.header.types)
+                declaredTypes.add(t.name);
+        }
+        for (const v of ast.header.inputs) {
+            if (!isValidTypeWithDecls(v.type, declaredTypes)) {
+                errors.push(ve('V7', 'error', `Inputs 段变量 "${v.name}" 的类型 "${v.type}" 无效（须为 ValueTypeString 或已声明 TypeDecl）`));
+            }
+        }
+    }
+    if (!ast.steps)
+        return;
+    const rootScope = { declared: new Map() };
+    if (ast.header.inputs) {
+        for (const v of ast.header.inputs)
+            rootScope.declared.set(v.name, v.type);
+    }
+    const declaredTypes = new Set();
+    const typeDecls = new Map(); // C8 dotted 下钻用（带 fields）
+    if (ast.header.types) {
+        for (const t of ast.header.types) {
+            declaredTypes.add(t.name);
+            typeDecls.set(t.name, t);
+        }
+    }
+    walkVariableScope(ast.steps, rootScope, errors, declaredTypes, typeDecls);
+}
+function walkVariableScope(steps, parentScope, errors, declaredTypes, typeDecls) {
+    const scope = { declared: new Map(parentScope.declared), parent: parentScope };
+    for (const step of steps) {
+        const loc = step.source_location?.line_start;
+        // V1: input bindings reference existing variables // @a: anc-rule-v1
+        if (step.inputs) {
+            for (const binding of step.inputs) {
+                if (!isVarVisible(binding.source, scope)) {
+                    errors.push(ve('V1', 'error', `Step "${step.step_id}" references undefined variable "${binding.source}"`, step.step_id, loc));
+                }
+            }
+        }
+        // V4: output type validity // @a: anc-rule-v4
+        if (step.outputs) {
+            for (const out of step.outputs) {
+                if (!isValidTypeWithDecls(out.type, declaredTypes)) {
+                    errors.push(ve('V4', 'error', `Step "${step.step_id}" output "${out.name}" has invalid type: "${out.type}"`, step.step_id, loc));
+                }
+            }
+        }
+        // Register this step's outputs into scope (for subsequent sibling visibility)
+        if (step.outputs) {
+            for (const out of step.outputs) {
+                // V2: no duplicate output names in same scope // @a: anc-rule-v2
+                if (scope.declared.has(out.name) && !parentScope.declared.has(out.name)) {
+                    errors.push(ve('V2', 'error', `Duplicate output variable "${out.name}" in same scope (step "${step.step_id}")`, step.step_id, loc));
+                }
+                // V3: no shadowing ancestor scope // @a: anc-rule-v3
+                // 例外（放行）：① 更新模式——step 同时 ← out.name（读入即输出）是"在祖先变量基础上
+                // 更新"（典型为 loop 内更新累加器）；② 显式初值/重置——step `+ → X = 初值`（带 default）
+                // 是对已有变量的显式重置（Python X=None 语义），非新建遮蔽。见
+                // [[HopSpec V3核心规范#^anc-exec-loop-var-scope]] / exec-engine ^anc-exec-output-init
+                // ① 更新模式（← X 且 → X，共享 isUpdateModeOutput 判据）② `= 初值` 显式重置（out.default）。// @a: anc-exec-output-init
+                const isUpdate = isUpdateModeOutput(step, out.name) || out.default !== undefined;
+                if (!isUpdate && isVarInAncestorScope(out.name, parentScope)) {
+                    errors.push(ve('V3', 'error', `Output "${out.name}" in step "${step.step_id}" shadows ancestor scope variable`, step.step_id, loc));
+                }
+                scope.declared.set(out.name, out.type);
+            }
+        }
+        // V8: for-each parallel 的 listVar 声明类型必须是列表 [T]（error）——非列表会让引擎把整个值
+        // 当单元素、只展开 1 个 child。见 design ^anc-rule-v8 / exec-engine ^anc-exec-parallel-foreach。// @a: anc-rule-v8
+        if (step.step_type === 'parallel' && step.forEach) {
+            const listVar = step.forEach.listVar;
+            const declType = scope.declared.get(listVar); // 此刻 scope 已含前序 + 本步 outputs
+            if (declType !== undefined && !/^\[.+\]$/.test(declType.trim())) {
+                errors.push(ve('V8', 'error', `for-each parallel "${step.step_id}" 的 listVar "${listVar}" 声明类型为 "${declType}"，必须是列表 [T]（否则引擎把整值当单元素、只展开 1 个 child）`, step.step_id, loc));
+            }
+        }
+        // C8: branch case 条件引用的变量路径必须合法（error）。见 design ^anc-rule-c8。// @a: anc-rule-c8
+        if (step.step_type === 'branch') {
+            for (const caseStep of getChildren(step)) {
+                const cond = caseStep.condition;
+                checkCaseCondition(cond, caseStep, scope, typeDecls, errors);
+            }
+        }
+        // call 步骤通过 output_mapping 产出父变量（call 的 outputs 为 undefined，+→ 解析为
+        // output_mapping，见 parser）。其 to（父变量）是 call 的实际产出，注册进 scope 供后续
+        // 步骤 ← 引用——否则下游引用 call 输出会被 V1 误判未定义。// @a: anc-rule-v1, anc-step-call
+        if (step.step_type === 'call') {
+            for (const om of step.output_mapping ?? []) {
+                if (om.to)
+                    scope.declared.set(om.to, ''); // call 输出类型未在 mapping 声明，记空
+            }
+        }
+        // act/commit body 校验（B 系列规则）：仅当 step 有 body。// @a: anc-rule-b-all
+        if ((step.step_type === 'act' || step.step_type === 'commit') && step.body) {
+            const visible = new Set(scope.declared.keys()); // body 校验只需变量名集合
+            for (const b of step.inputs ?? [])
+                visible.add(b.name); // body 用 ← 输入的 name 引用
+            checkActBodyScope(step.body, visible, step, errors);
+        }
+        // Recurse into container children with new child scope
+        if (CONTAINER_STEP_TYPES.has(step.step_type)) {
+            const children = getChildren(step);
+            if (children.length > 0) {
+                if (SCOPE_CREATING_CONTAINERS.has(step.step_type) && step.outputs) {
+                    const childParent = { declared: new Map(scope.declared), parent: parentScope };
+                    // subtask/parallel/branch/case 输出对子步骤不可见（子步骤产出后才聚合）→ 从子作用域删除。
+                    // loop 例外：loop 节点输出是累加器，loop 内子步骤需以更新模式（← X + → X）读取并更新它，
+                    // 故保留可见（见 [[../../HopSpec V3核心规范#^anc-exec-loop-var-scope]]）
+                    if (step.step_type !== 'loop') {
+                        for (const out of step.outputs)
+                            childParent.declared.delete(out.name);
+                    }
+                    // for-each parallel：itemVar 注册为 child 可见变量（在 output 删除之后，确保不被误删） // @a: anc-exec-parallel-foreach
+                    // itemVar 元素类型 = listVar 声明类型 [T] 剥括号（供 case 条件 C8 dotted 下钻）。
+                    if (step.step_type === 'parallel' && step.forEach) {
+                        const fe = step.forEach;
+                        const listType = scope.declared.get(fe.listVar) ?? '';
+                        const elemType = /^\[(.+)\]$/.exec(listType.trim())?.[1] ?? ''; // [CheckPoint] → CheckPoint
+                        childParent.declared.set(fe.itemVar, elemType);
+                    }
+                    // branch 特殊处理：互斥 case 各走独立 scope 副本递归（case 声明与 branch 同名输出不碰撞，
+                    // "同名=同一个东西"原则——V2 不误杀）。branch 自己的输出已注册到外层 scope（L484），
+                    // 后续步骤通过 branch 的输出名引用，不需要 case 输出 union。
+                    if (step.step_type === 'branch') {
+                        for (const child of children) {
+                            const caseScopeCopy = { declared: new Map(childParent.declared), parent: childParent.parent };
+                            walkVariableScope([child], caseScopeCopy, errors, declaredTypes, typeDecls);
+                        }
+                    }
+                    else {
+                        walkVariableScope(children, childParent, errors, declaredTypes, typeDecls);
+                    }
+                }
+                else {
+                    walkVariableScope(children, scope, errors, declaredTypes, typeDecls);
+                }
+            }
+        }
+    }
+}
+function isVarVisible(name, scope) {
+    return scope.declared.has(name);
+}
+// C8: 校验 branch case 条件引用的变量路径合法。// @a: anc-rule-c8
+// cond 形态：`{var} == literal` / `var != literal` / 裸 `var`（truthy）；var 可含 dotted path。
+// 只校验 == / != 左侧或裸条件的变量路径，不校验右侧 literal。default（空/`default`）跳过。
+function checkCaseCondition(cond, caseStep, scope, typeDecls, errors) {
+    if (cond === undefined)
+        return;
+    const t = cond.trim();
+    if (t === '' || t === 'default')
+        return; // default case
+    // 取比较左侧（或裸条件）作变量表达式：切在首个 == / != 前
+    const neq = t.indexOf('!='), eq = t.indexOf('==');
+    const cut = [neq, eq].filter(i => i >= 0).sort((a, b) => a - b)[0];
+    let varExpr = (cut === undefined ? t : t.slice(0, cut)).trim();
+    if (varExpr.startsWith('{') && varExpr.endsWith('}'))
+        varExpr = varExpr.slice(1, -1).trim();
+    if (varExpr === '')
+        return;
+    const loc = caseStep.source_location?.line_start;
+    // 归一化 a[0].b → a.0.b，逐段
+    const segs = varExpr.replace(/\[(\w+)\]/g, '.$1').split('.').filter(s => s !== '');
+    const root = segs[0];
+    // ① 根变量必须可见
+    if (!scope.declared.has(root)) {
+        errors.push(ve('C8', 'error', `Case "${caseStep.step_id}" 条件引用未定义变量 "${root}"（条件: ${t}）`, caseStep.step_id, loc));
+        return;
+    }
+    // ② 逐段顺类型下钻（根类型未知 '' → 无法下钻，止于根、放行——避免误报无类型信息的变量）
+    let curType = (scope.declared.get(root) ?? '').trim();
+    for (let i = 1; i < segs.length; i++) {
+        if (curType === '')
+            return; // 类型信息缺失，不再下钻（不误报）
+        const arrM = /^\[(.+)\]$/.exec(curType);
+        if (arrM) {
+            // 数组段：要求 segs[i] 是整数下标，下钻到元素类型
+            if (!/^\d+$/.test(segs[i])) {
+                errors.push(ve('C8', 'error', `Case "${caseStep.step_id}" 条件路径 "${varExpr}" 段 "${segs[i]}" 对列表类型 "${curType}" 非法（列表须数字下标）`, caseStep.step_id, loc));
+                return;
+            }
+            curType = arrM[1].trim();
+            continue;
+        }
+        const decl = typeDecls.get(curType);
+        if (!decl)
+            return; // 非 TypeDecl（如 line/text 标量）无字段可下钻——类型信息不足，放行不误报
+        if (!(segs[i] in decl.fields)) {
+            errors.push(ve('C8', 'error', `Case "${caseStep.step_id}" 条件路径 "${varExpr}" 中 "${segs[i]}" 不是类型 "${curType}" 的字段（合法字段: ${Object.keys(decl.fields).join(', ')}）`, caseStep.step_id, loc));
+            return;
+        }
+        curType = decl.fields[segs[i]].trim();
+    }
+}
+// ===== B 系列：act/commit body 校验（hop_python）===== // @a: anc-rule-b-all
+// visible：进入 body 时可见的变量集（步骤 ← 输入名 ∪ 当前 scope 已声明）。
+// 顺序遍历语句：赋值 target 加入 visible；if 分支各拷贝 visible（分支局部不泄漏）。
+function checkActBodyScope(body, visible, step, errors) {
+    const loc = step.source_location?.line_start;
+    const writtenOutputs = new Set();
+    walkActStatements(body.statements, visible, step, errors, writtenOutputs);
+    // B5：声明的 +→ 输出，body 应有对应赋值；缺则 warn // @a: anc-rule-b5
+    for (const out of step.outputs ?? []) {
+        if (!writtenOutputs.has(out.name)) {
+            errors.push(ve('B5', 'warn', `act body 声明输出 "${out.name}" 但 body 中无对应赋值（step "${step.step_id}"）`, step.step_id, loc));
+        }
+    }
+}
+function walkActStatements(stmts, visible, step, errors, writtenOutputs) {
+    const loc = step.source_location?.line_start;
+    const declaredOutputs = new Set((step.outputs ?? []).map(o => o.name));
+    for (const stmt of stmts) {
+        if (stmt.type === 'assign') {
+            checkActExpr(stmt.value, visible, step, errors);
+            const target = stmt.target;
+            visible.add(target); // 赋值后该名可见
+            if (declaredOutputs.has(target))
+                writtenOutputs.add(target);
+        }
+        else if (stmt.type === 'call') {
+            checkActExpr(stmt.call, visible, step, errors);
+        }
+        else if (stmt.type === 'if') {
+            const ifs = stmt;
+            checkActExpr(ifs.condition, visible, step, errors);
+            // 分支各拷贝可见集校验；分支内新赋值的变量默认不泄漏到分支外。
+            // 例外——汇合赋值：若某变量在 then 与 else 两分支都被赋值，分支后必然有值，提升到外层可见
+            // （Python/TS 同样行为；否则 if/else 双分支赋值同名变量、分支后引用会被误判未定义）。
+            const thenVis = new Set(visible);
+            walkActStatements(ifs.then_body, thenVis, step, errors, writtenOutputs);
+            if (ifs.else_body) {
+                const elseVis = new Set(visible);
+                walkActStatements(ifs.else_body, elseVis, step, errors, writtenOutputs);
+                for (const v of thenVis) {
+                    if (!visible.has(v) && elseVis.has(v))
+                        visible.add(v); // then ∩ else 新增 → 提升
+                }
+            }
+        }
+        else {
+            // B1 兜底：理论上 parser 已拒循环，AST 不应出现其他语句类型 // @a: anc-rule-b1
+            errors.push(ve('B1', 'error', `act body 含非法语句类型（step "${step.step_id}"）`, step.step_id, loc));
+        }
+    }
+}
+function checkActExpr(expr, visible, step, errors) {
+    const loc = step.source_location?.line_start;
+    switch (expr.type) {
+        case 'literal': return;
+        case 'var':
+            // B4：变量引用须可见 // @a: anc-rule-b4
+            if (!visible.has(expr.name)) {
+                errors.push(ve('B4', 'error', `act body 引用未定义变量 "${expr.name}"（step "${step.step_id}"）`, step.step_id, loc));
+            }
+            return;
+        case 'field':
+            checkActExpr(expr.object, visible, step, errors);
+            return;
+        case 'binary':
+            checkActExpr(expr.left, visible, step, errors);
+            checkActExpr(expr.right, visible, step, errors);
+            return;
+        case 'unary':
+            checkActExpr(expr.operand, visible, step, errors);
+            return;
+        case 'call': {
+            // B2：callee 须 ∈ 内置白名单 ∪ ToolProvider 工具（运行期）。内置则校验 arity，非内置 warn。 // @a: anc-rule-b2
+            const call = expr;
+            if (ACT_BUILTIN_NAMES.has(call.callee)) {
+                const def = ACT_BUILTINS.get(call.callee);
+                const n = call.args.length;
+                if (n < def.arity.min || n > def.arity.max) {
+                    const range = def.arity.max === Infinity ? `≥${def.arity.min}` : `${def.arity.min}-${def.arity.max}`;
+                    errors.push(ve('B2', 'error', `act body 内置函数 "${call.callee}" 参数个数 ${n} 不符（期望 ${range}）（step "${step.step_id}"）`, step.step_id, loc));
+                }
+            }
+            else {
+                errors.push(ve('B2', 'warn', `act body 调用 "${call.callee}" 非内置函数——视为工具，运行期对照 ToolProvider 清单确认（step "${step.step_id}"）`, step.step_id, loc));
+            }
+            for (const arg of call.args)
+                checkActExpr(arg.value, visible, step, errors);
+            return;
+        }
+    }
+}
+function isVarInAncestorScope(name, scope) {
+    let s = scope;
+    while (s) {
+        if (s.declared.has(name))
+            return true;
+        s = s.parent;
+    }
+    return false;
+}
+const BUILTIN_TYPES = new Set([
+    'text', 'bool', 'line', 'number', 'int', 'float', 'markdown', 'yaml', 'prompt', 'HopSpec', '[line]',
+]);
+/** Strict type check: valid only if builtin, enum, list, tuple, or explicitly declared TypeDecl */
+function isValidTypeWithDecls(type, declaredTypes) {
+    if (BUILTIN_TYPES.has(type))
+        return true;
+    if (/^enum\(.+\)$/.test(type))
+        return true;
+    if (/^\[.+\]$/.test(type))
+        return true; // [TypeName] list syntax
+    if (/^\(.+\)$/.test(type))
+        return true; // (Type, Type) tuple syntax
+    if (declaredTypes.has(type))
+        return true;
+    return false;
+}
+// ===== P1-P7: Special step rules =====
+function specialStepRules(ast, errors) {
+    if (!ast.steps)
+        return;
+    const allFlat = flattenSteps(ast.steps);
+    for (const step of allFlat) {
+        const loc = step.source_location?.line_start;
+        // P1: call must have callee_spec_id // @a: anc-rule-p1
+        if (step.step_type === 'call') {
+            const cs = step;
+            if (!cs.callee_spec_id?.trim()) {
+                errors.push(ve('P1', 'error', `Call step "${step.step_id}" is missing callee_spec_id`, step.step_id, loc));
+            }
+        }
+        // P2【已废除】：旧 commit 语义（commit 自带审批/输出 approval）残留。新概念下授权前置到
+        // confirm，commit 不自带审批，不再要求声明 approval。规则不再生效，编号位保留不重编。
+        // 见 design/spec-parser.md ^anc-rule-p2 废除说明、概念 ^anc-step-commit。
+        // P3: confirm response_options must have ≥1 if specified // @a: anc-rule-p3
+        if (step.step_type === 'confirm') {
+            const cs = step;
+            if (cs.response_options && cs.response_options.length === 0) {
+                errors.push(ve('P3', 'warn', `Confirm step "${step.step_id}" has empty response_options`, step.step_id, loc));
+            }
+            // P12: confirm 纯审批闸门——+→ 仅允许 bool（数据收集用 ask）// @a: anc-rule-p12, anc-step-confirm
+            for (const out of step.outputs ?? []) {
+                if (out.type !== 'bool') {
+                    errors.push(ve('P12', 'error', `Confirm step "${step.step_id}" output "${out.name}" must be bool (confirm 是纯审批闸门，数据收集用 ask 步骤)`, step.step_id, loc));
+                }
+            }
+        }
+        // P13: ask 步骤须声明 +→ 输出（数据收集的目标变量）// @a: anc-rule-p13, anc-step-ask
+        if (step.step_type === 'ask') {
+            if (!step.outputs || step.outputs.length === 0) {
+                errors.push(ve('P13', 'error', `Ask step "${step.step_id}" must declare at least one +→ output (要 caller 提供的数据)`, step.step_id, loc));
+            }
+            // P14: ask present_inputs 必须是 ← inputs 的子集 // @a: anc-rule-p14, anc-step-ask
+            const askStep = step;
+            if (askStep.present_inputs && askStep.present_inputs.length > 0) {
+                const inputNames = new Set((askStep.inputs ?? []).map(b => b.name));
+                for (const name of askStep.present_inputs) {
+                    if (!inputNames.has(name)) {
+                        errors.push(ve('P14', 'error', `Ask step "${step.step_id}" present_inputs="${name}" not declared in ← inputs (present_inputs 必须是 ← inputs 子集,driver 无值可呈现)`, step.step_id, loc));
+                    }
+                }
+            }
+        }
+        // P4: exit exit_outputs keys must exactly match header.outputs // @a: anc-rule-p4
+        if (step.step_type === 'exit') {
+            const es = step;
+            if (es.exit_outputs && ast.header.outputs) {
+                const headerOutputNames = new Set(ast.header.outputs.map(o => o.name));
+                const exitKeys = new Set(Object.keys(es.exit_outputs));
+                for (const key of exitKeys) {
+                    if (!headerOutputNames.has(key)) {
+                        errors.push(ve('P4', 'error', `Exit step "${step.step_id}" output "${key}" is not in header outputs`, step.step_id, loc));
+                    }
+                }
+                for (const name of headerOutputNames) {
+                    if (!exitKeys.has(name)) {
+                        errors.push(ve('P4', 'error', `Exit step "${step.step_id}" is missing required output "${name}"`, step.step_id, loc));
+                    }
+                }
+            }
+        }
+        // P5: commit must have non-empty irreversible_action // @a: anc-rule-p5
+        if (step.step_type === 'commit') {
+            const cs = step;
+            if (!cs.irreversible_action?.trim()) {
+                errors.push(ve('P5', 'error', `Commit step "${step.step_id}" is missing irreversible_action description`, step.step_id, loc));
+            }
+        }
+        // P6: subtask.retry ≥ 1, loop.max_iterations ≥ 1 // @a: anc-rule-p6
+        if (step.step_type === 'subtask') {
+            const st = step;
+            if (st.retry !== undefined && st.retry < 1) {
+                errors.push(ve('P6', 'warn', `Subtask "${step.step_id}" retry=${st.retry} should be ≥ 1`, step.step_id, loc));
+            }
+        }
+        if (step.step_type === 'loop') {
+            const lt = step;
+            if (lt.max_iterations !== undefined && lt.max_iterations < 1) {
+                errors.push(ve('P6', 'warn', `Loop "${step.step_id}" max_iterations=${lt.max_iterations} should be ≥ 1`, step.step_id, loc));
+            }
+        }
+        // P7: ResponseOption values and labels non-empty // @a: anc-rule-p7
+        if (step.step_type === 'confirm') {
+            const cs = step;
+            if (cs.response_options) {
+                for (const opt of cs.response_options) {
+                    if (!opt.value?.trim() || !opt.label?.trim()) {
+                        errors.push(ve('P7', 'warn', `Confirm step "${step.step_id}" has response_option with empty value or label`, step.step_id, loc));
+                    }
+                }
+            }
+        }
+        // P9: retry and adaptive only allowed on subtask and case steps // @a: anc-rule-p9
+        // case 就是 branch 下的 subtask，继承 retry/adaptive 语义（见 anc-step-case）
+        if (step.step_type !== 'subtask' && step.step_type !== 'case') {
+            const anyStep = step;
+            if (anyStep.retry !== undefined) {
+                errors.push(ve('P9', 'error', `retry 属性仅适用于 subtask/case 步骤，当前步骤 "${step.step_id}" 类型为 ${step.step_type}`, step.step_id, loc));
+            }
+            if (anyStep.adaptive !== undefined) {
+                errors.push(ve('P9', 'error', `adaptive 属性仅适用于 subtask/case 步骤，当前步骤 "${step.step_id}" 类型为 ${step.step_type}`, step.step_id, loc));
+            }
+        }
+        // @model annotation only valid on executable steps
+        if (step.model_override && !EXECUTABLE_STEP_TYPES.has(step.step_type)) {
+            errors.push(ve('P9', 'warn', `@model annotation on non-executable step "${step.step_id}" (type: ${step.step_type}) has no effect`, step.step_id, loc));
+        }
+        // P8: commit in retry/adaptive subtask requires confirm guard // @a: anc-rule-p8
+        if (step.step_type === 'subtask') {
+            const st = step;
+            if ((st.retry !== undefined && st.retry > 0) || st.adaptive === true) {
+                const descendants = flattenSteps(st.children);
+                const hasCommit = descendants.some(d => d.step_type === 'commit');
+                const hasConfirm = descendants.some(d => d.step_type === 'confirm');
+                if (hasCommit && !hasConfirm) {
+                    errors.push(ve('P8', 'error', `Subtask "${step.step_id}" has retry/adaptive but contains commit without confirm guard`, step.step_id, loc));
+                }
+                const hasCall = descendants.some(d => d.step_type === 'call');
+                if (hasCall && !hasConfirm) {
+                    errors.push(ve('P8', 'warn', `Subtask "${step.step_id}" has retry/adaptive and contains call — cannot verify callee has no unguarded commit (v2+ runtime check)`, step.step_id, loc));
+                }
+            }
+        }
+    }
+    // V6: call param_mapping + output_mapping validity (placed here with special step rules) // @a: anc-rule-v6
+    for (const step of allFlat) {
+        if (step.step_type !== 'call')
+            continue;
+        const cs = step;
+        const loc = step.source_location?.line_start;
+        for (const pm of cs.param_mapping ?? []) {
+            if (!pm.from?.trim()) {
+                errors.push(ve('V6', 'error', `Call step "${step.step_id}" param_mapping has empty 'from'`, step.step_id, loc));
+            }
+            if (!pm.to?.trim()) {
+                errors.push(ve('V6', 'error', `Call step "${step.step_id}" param_mapping has empty 'to'`, step.step_id, loc));
+            }
+        }
+        for (const om of cs.output_mapping ?? []) {
+            if (!om.from?.trim()) {
+                errors.push(ve('V6', 'error', `Call step "${step.step_id}" output_mapping has empty 'from'`, step.step_id, loc));
+            }
+            if (!om.to?.trim()) {
+                errors.push(ve('V6', 'error', `Call step "${step.step_id}" output_mapping has empty 'to'`, step.step_id, loc));
+            }
+        }
+    }
+    // P10: declared output should have a producer (static reachability) // @a: anc-rule-p10
+    // 递归遍历子树，返回该子树产出的变量名集合（+→ 输出 + exit 交付）。
+    // 顺带就地检查容器：scope-creating 容器声明的 +→ 须由其子树产出，否则 warn。
+    function collectProduced(node) {
+        const produced = new Set();
+        if (node.step_type === 'exit') {
+            for (const k of Object.keys(node.exit_outputs ?? {}))
+                produced.add(k);
+        }
+        if (hasChildren(node)) {
+            const childProduced = new Set();
+            for (const child of getChildren(node)) {
+                for (const name of collectProduced(child))
+                    childProduced.add(name);
+            }
+            // 容器自身的 +→ 须由子树产出（否则可能漏写产出步骤）
+            if (SCOPE_CREATING_CONTAINERS.has(node.step_type)) {
+                // for-each parallel 的 itemVar 是引擎运行时注入的元素绑定，非子树产出 → 豁免 // @a: anc-exec-parallel-foreach
+                const forEachItemVar = node.step_type === 'parallel' ? node.forEach?.itemVar : undefined;
+                for (const out of node.outputs ?? []) {
+                    if (out.name === forEachItemVar)
+                        continue;
+                    if (!childProduced.has(out.name)) {
+                        errors.push(ve('P10', 'warn', `Container "${node.step_id}" declares output "${out.name}" but no descendant step produces it`, node.step_id, node.source_location?.line_start));
+                    }
+                }
+            }
+            for (const name of childProduced)
+                produced.add(name);
+        }
+        // 叶子/自身的 +→ 也是产出
+        for (const o of node.outputs ?? [])
+            produced.add(o.name);
+        return produced;
+    }
+    const allProduced = new Set();
+    for (const top of ast.steps) {
+        for (const name of collectProduced(top))
+            allProduced.add(name);
+    }
+    // Spec Outputs：声明的交付物若无任何步骤产出 → warn（可能漏写产出步骤，也可能是合法 impl）
+    for (const out of ast.header.outputs ?? []) {
+        if (!allProduced.has(out.name)) {
+            errors.push(ve('P10', 'warn', `Declared output "${out.name}" has no producing step (no '+→' or exit produces it)`, undefined, undefined));
+        }
+    }
+}
+const VALUE_TRUNC = 60;
+function truncateValue(v) {
+    let s;
+    try {
+        s = typeof v === 'string' ? v : JSON.stringify(v);
+    }
+    catch {
+        s = String(v);
+    }
+    if (s === undefined)
+        s = String(v);
+    return s.length > VALUE_TRUNC ? s.slice(0, VALUE_TRUNC) + '…' : s;
+}
+/** 校验单个值是否匹配声明类型（v1 策略）。匹配返回 null，不匹配返回原因字符串。 */
+function checkValue(type, value) {
+    // 宽松字符串类型：接受任意（含可序列化为字符串的）值，不强约束
+    if (['text', 'line', 'markdown', 'yaml', 'prompt', 'HopSpec'].includes(type)) {
+        return null;
+    }
+    if (type === 'bool') {
+        if (typeof value === 'boolean')
+            return null;
+        if (typeof value === 'string' && /^(true|false)$/i.test(value.trim()))
+            return null;
+        return '期望 bool（true/false），实际非布尔值';
+    }
+    if (type === 'number' || type === 'int' || type === 'float') {
+        if (typeof value === 'number' && !Number.isNaN(value))
+            return null;
+        if (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value)))
+            return null;
+        return `期望 ${type}（可转为数字），实际无法转为数字`;
+    }
+    // enum(a,b,c)：值须在列举内
+    const enumMatch = /^enum\((.+)\)$/.exec(type);
+    if (enumMatch) {
+        const allowed = enumMatch[1].split(',').map(s => s.trim());
+        if (allowed.includes(String(value).trim()))
+            return null;
+        return `期望 enum 之一 [${allowed.join(', ')}]，实际不在列举内`;
+    }
+    // [Type] 列表：严格要求数组，字符串一律拒绝（列表语义=数组，字符串=类型谎报）。
+    // 曾"宽松接受非空字符串"是静默容错：谎报值（如 @file 指针字符串）漂过校验、污染下游，
+    // 到 for-each join 才 Array.isArray 失败、聚合全空、故障漂离源头两步。契约违反须当场炸——
+    // SCHEMA_MISMATCH 触发带反馈重试，driver 自然改出真数组。见 design ^anc-exec-output-schema-check。
+    if (/^\[.+\]$/.test(type)) {
+        if (Array.isArray(value))
+            return null;
+        return '期望列表 [Type]，实际非数组';
+    }
+    // 自定义 TypeDecl / 元组 / 其他：v1 仅做存在性（非空），不递归类型匹配
+    if (value === null || value === undefined) {
+        return `期望 ${type}，实际为空`;
+    }
+    return null;
+}
+/**
+ * 校验一组输出值是否匹配步骤的 +→ 声明（OutputDecl[]）。
+ * 返回不匹配项列表（空数组 = 全部通过）。
+ * @a: anc-exec-output-schema-check
+ */
+export function validateOutputValues(decls, outputs) {
+    if (!decls || decls.length === 0)
+        return [];
+    const mismatches = [];
+    for (const decl of decls) {
+        // 声明的字段缺失（未产出）
+        if (!(decl.name in outputs)) {
+            mismatches.push({
+                field: decl.name, declared_type: decl.type,
+                actual: '(缺失)', reason: '声明的输出未产出',
+            });
+            continue;
+        }
+        const reason = checkValue(decl.type, outputs[decl.name]);
+        if (reason) {
+            mismatches.push({
+                field: decl.name, declared_type: decl.type,
+                actual: truncateValue(outputs[decl.name]), reason,
+            });
+        }
+    }
+    return mismatches;
+}
+/** 把不匹配项格式化为 SCHEMA_MISMATCH 的 message（供算子级重试构造反馈）。 */
+export function formatSchemaMismatch(mismatches) {
+    return 'SCHEMA_MISMATCH: ' + mismatches.map(m => `字段 "${m.field}"（声明 ${m.declared_type}）：${m.reason}（实际：${m.actual}）`).join('；');
+}