@hoplogic/hopjit 0.1.0

package/dist/doc-ref.d.ts

@@ -0,0 +1,41 @@
+import type { DocRef, DocRefFragment } from './ast-types.js';
+import type { SandboxConfig } from './provider-types.js';
+/**
+ * 从文本提取 doc-ref。排除 #^ 前缀（那是 [[doc#^anc-*]] 段落锚点反链，非章节引用）。
+ * 同一 (doc, section) 去重。// @a: anc-rule-doc-ref-extract
+ */
+export declare function extractDocRefs(text: string): DocRef[];
+/** 章节切片结果：命中标题、章节正文、匹配级别（精确/归一化/子串/未命中）及歧义标记。见 [[doc-ref#^anc-exec-doc-ref-resolve]] */
+export interface SliceResult {
+    heading: string;
+    content: string;
+    matched: 'exact' | 'normalized' | 'fuzzy' | 'none';
+    ambiguous?: boolean;
+}
+/**
+ * 在 markdown 文本中定位 section 标题并切出其章节正文（含子标题，到下一个同级/更高级标题止）。
+ * 三级匹配：精确 → 归一化序号 → 子串包含。// @a: anc-exec-doc-ref-resolve
+ */
+export declare function sliceSection(lines: string[], section: string): SliceResult;
+/** doc-ref 解析期文件未找到/章节无匹配/沙箱拒读时抛出，携带原始 DocRef，供 engine failStep 消费。见 [[doc-ref#^anc-exec-doc-ref-resolve]] */
+export declare class DocRefError extends Error {
+    readonly ref: DocRef;
+    constructor(message: string, ref: DocRef);
+}
+/**
+ * 静态存在性校验（P15 用）：文件存在 + 章节可匹配。返回 null 表示通过，否则返回错误说明。
+ * 不抛异常（validator 收集错误而非中断）。// @a: anc-rule-p15
+ */
+export declare function checkDocRefExists(workspaceDir: string, sandbox: SandboxConfig, ref: DocRef): string | null;
+/**
+ * 运行期解析一组 doc-ref 为章节内容片段。同文件只读一次（按 path 缓存）。
+ * 大节超 DEFLATE_THRESHOLD 时写 workZone/docref/ 并返 file_path 指针；
+ * workZone 空串（独立模式）时不卸载、内联全文。
+ * 文件/章节找不到 → 抛 DocRefError（dispatcher 据此 failStep）。// @a: anc-exec-doc-ref-resolve
+ */
+export declare function resolveDocRefs(refs: DocRef[], workspaceDir: string, sandbox: SandboxConfig, workZone: string): DocRefFragment[];
+/**
+ * 把解析出的 fragment 渲染为 L2d doc_ref_context 文本块。
+ * 大节（有 file_path）只放 $file 指针提示；小节内联全文。// @a: anc-exec-doc-ref-injection
+ */
+export declare function formatDocRefContext(fragments: DocRefFragment[]): string;

package/dist/doc-ref.js

@@ -0,0 +1,214 @@
+// @module: doc-ref ^anc-struct-doc-ref
+// doc-ref [[文档#章节]] 确定性精确引用解析。
+// 概念: ../../HopSpec V3核心规范.md ^anc-exec-doc-ref
+// 设计: design/spec-parser.md ^anc-rule-doc-ref-extract（提取）
+//       design/step-dispatcher.md ^anc-exec-doc-ref-resolve（解析）
+//       design/prompt-assembler.md ^anc-exec-doc-ref-injection（注入/deflate）
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFLATE_THRESHOLD } from './ast-helpers.js';
+import { readSandboxedFile, resolveWorkspacePath } from './tools.js';
+// 捕获组1=文档路径，组2=章节名；(?:\|别名)? 吞掉 Obsidian 别名后缀。
+// 强制要求 #章节（无 # 的纯 [[doc]] 不匹配）。
+const RE_DOC_REF = /\[\[([^\]#|]+)#([^\]|]+?)(?:\|[^\]]+)?\]\]/g;
+const RE_HEADING = /^(#{1,6})\s+(.*\S)/;
+const RE_FENCE = /^```/;
+/**
+ * 从文本提取 doc-ref。排除 #^ 前缀（那是 [[doc#^anc-*]] 段落锚点反链，非章节引用）。
+ * 同一 (doc, section) 去重。// @a: anc-rule-doc-ref-extract
+ */
+export function extractDocRefs(text) {
+    if (!text)
+        return [];
+    const seen = new Set();
+    const refs = [];
+    RE_DOC_REF.lastIndex = 0;
+    let m;
+    while ((m = RE_DOC_REF.exec(text)) !== null) {
+        const doc = m[1].trim();
+        const section = m[2].trim();
+        if (section.startsWith('^'))
+            continue; // 段落锚点反链，非章节引用
+        if (!doc || !section)
+            continue;
+        const key = `${doc} ${section}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        refs.push({ doc, section });
+    }
+    return refs;
+}
+// 剥离章节名/标题的序号前缀做归一化匹配。四类前缀：
+//  ① 阿拉伯序号 `4` / `4.7`（分隔符可选）  ② 中文数字序号 `二、`（分隔符必需——
+//  避免 "十全大补" 的 "十" 被误剥）  ③ 全角括号序号 `（一）`  ④ 半角括号序号 `(1)`。
+// "第三方" 因 "第" 不在数字集、无分隔符，不会被剥。
+const RE_NUM_PREFIX = /^(?:\d+(?:\.\d+)*[.、\s]*|[一二三四五六七八九十百千零]+[、.\s]+|（[^）]*）\s*|\([^)]*\)\s*)/;
+function normalizeSection(s) {
+    return s.replace(RE_NUM_PREFIX, '').trim();
+}
+function scanHeadings(lines) {
+    const headings = [];
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (RE_FENCE.test(lines[i].trim())) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const hm = lines[i].match(RE_HEADING);
+        if (hm)
+            headings.push({ line: i, depth: hm[1].length, text: hm[2].trim() });
+    }
+    return headings;
+}
+/**
+ * 在 markdown 文本中定位 section 标题并切出其章节正文（含子标题，到下一个同级/更高级标题止）。
+ * 三级匹配：精确 → 归一化序号 → 子串包含。// @a: anc-exec-doc-ref-resolve
+ */
+export function sliceSection(lines, section) {
+    const headings = scanHeadings(lines);
+    const target = section.trim();
+    const normTarget = normalizeSection(target);
+    let hit;
+    let matched = 'none';
+    let ambiguous = false;
+    // a. 精确
+    hit = headings.find(h => h.text === target);
+    if (hit)
+        matched = 'exact';
+    // b. 归一化序号相等
+    if (!hit && normTarget) {
+        hit = headings.find(h => normalizeSection(h.text) === normTarget);
+        if (hit)
+            matched = 'normalized';
+    }
+    // c. 子串包含（兜底，多命中取首 + 标 ambiguous）
+    if (!hit) {
+        const cands = headings.filter(h => h.text.includes(target) || (normTarget && normalizeSection(h.text).includes(normTarget)));
+        if (cands.length > 0) {
+            hit = cands[0];
+            matched = 'fuzzy';
+            ambiguous = cands.length > 1;
+        }
+    }
+    if (!hit)
+        return { heading: '', content: '', matched: 'none' };
+    // 切区间 [命中行+1, 下一个 depth <= 命中 depth 的标题行)
+    let end = lines.length;
+    for (const h of headings) {
+        if (h.line > hit.line && h.depth <= hit.depth) {
+            end = h.line;
+            break;
+        }
+    }
+    const content = lines.slice(hit.line + 1, end).join('\n').trim();
+    return { heading: hit.text, content, matched, ambiguous };
+}
+/** doc-ref 解析期文件未找到/章节无匹配/沙箱拒读时抛出，携带原始 DocRef，供 engine failStep 消费。见 [[doc-ref#^anc-exec-doc-ref-resolve]] */
+export class DocRefError extends Error {
+    ref;
+    constructor(message, ref) {
+        super(message);
+        this.ref = ref;
+    }
+}
+// 候选路径：原名 + 补 .md 兜底（Obsidian 习惯省后缀）
+function candidatePaths(doc) {
+    return doc.endsWith('.md') ? [doc] : [doc, `${doc}.md`];
+}
+/** 定位 doc-ref 文件：遍历 candidatePaths（含 .md 兜底），命中 existsSync 即返回该 cand，全不命中返回 undefined。
+ * 不吞 resolveWorkspacePath 的抛错（path traversal 等）——由调用方按各自语义处理。checkDocRefExists / resolveDocRefs 共用。 */
+function resolveDocFile(workspaceDir, doc) {
+    for (const cand of candidatePaths(doc)) {
+        if (existsSync(resolveWorkspacePath(workspaceDir, cand)))
+            return cand;
+    }
+    return undefined;
+}
+/**
+ * 静态存在性校验（P15 用）：文件存在 + 章节可匹配。返回 null 表示通过，否则返回错误说明。
+ * 不抛异常（validator 收集错误而非中断）。// @a: anc-rule-p15
+ */
+export function checkDocRefExists(workspaceDir, sandbox, ref) {
+    let resolvedFile;
+    try {
+        resolvedFile = resolveDocFile(workspaceDir, ref.doc);
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+    if (!resolvedFile)
+        return `文件未找到: ${ref.doc}`;
+    let text;
+    try {
+        text = readSandboxedFile(workspaceDir, sandbox, resolvedFile);
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+    const slice = sliceSection(text.split('\n'), ref.section);
+    if (slice.matched === 'none')
+        return `章节未匹配: [[${ref.doc}#${ref.section}]]`;
+    return null;
+}
+/**
+ * 运行期解析一组 doc-ref 为章节内容片段。同文件只读一次（按 path 缓存）。
+ * 大节超 DEFLATE_THRESHOLD 时写 workZone/docref/ 并返 file_path 指针；
+ * workZone 空串（独立模式）时不卸载、内联全文。
+ * 文件/章节找不到 → 抛 DocRefError（dispatcher 据此 failStep）。// @a: anc-exec-doc-ref-resolve
+ */
+export function resolveDocRefs(refs, workspaceDir, sandbox, workZone) {
+    const fileCache = new Map();
+    const fragments = [];
+    for (const ref of refs) {
+        // 定位文件（含 .md 兜底）
+        const resolvedFile = resolveDocFile(workspaceDir, ref.doc);
+        if (!resolvedFile)
+            throw new DocRefError(`doc-ref 文件未找到: [[${ref.doc}#${ref.section}]]`, ref);
+        let lines = fileCache.get(resolvedFile);
+        if (!lines) {
+            lines = readSandboxedFile(workspaceDir, sandbox, resolvedFile).split('\n');
+            fileCache.set(resolvedFile, lines);
+        }
+        const slice = sliceSection(lines, ref.section);
+        if (slice.matched === 'none') {
+            throw new DocRefError(`doc-ref 章节未匹配: [[${ref.doc}#${ref.section}]]`, ref);
+        }
+        const frag = {
+            doc: ref.doc,
+            section: ref.section,
+            heading: slice.heading,
+            content: slice.content,
+            matched: slice.matched,
+        };
+        // deflate: 大节卸载到 work_zone 文件（独立模式 workZone 空串则内联）
+        if (workZone && Buffer.byteLength(slice.content, 'utf-8') > DEFLATE_THRESHOLD) {
+            const docrefDir = join(workZone, 'docref');
+            mkdirSync(docrefDir, { recursive: true, mode: 0o700 });
+            const safe = `${ref.doc}__${ref.section}`.replace(/[^\w一-龥.-]+/g, '_');
+            const filePath = join(docrefDir, `${safe}.md`);
+            writeFileSync(filePath, slice.content, { mode: 0o600 });
+            frag.file_path = filePath;
+        }
+        fragments.push(frag);
+    }
+    return fragments;
+}
+/**
+ * 把解析出的 fragment 渲染为 L2d doc_ref_context 文本块。
+ * 大节（有 file_path）只放 $file 指针提示；小节内联全文。// @a: anc-exec-doc-ref-injection
+ */
+export function formatDocRefContext(fragments) {
+    if (fragments.length === 0)
+        return '';
+    const blocks = fragments.map(f => {
+        const head = `[[${f.doc}#${f.section}]]（命中标题：${f.heading}）`;
+        if (f.file_path) {
+            return `### ${head}\n全文见 $file: ${f.file_path}（请 Read 获取完整章节）`;
+        }
+        return `### ${head}\n${f.content}`;
+    });
+    return `[L2d. 引用文档（作者指定，必读）]\n${blocks.join('\n\n---\n\n')}`;
+}

package/dist/engine-traverse.d.ts

@@ -0,0 +1,37 @@
+import type { SpecAST, StepNode, ExitStep } from './ast-types.js';
+import type { StepStatus, VariableStore } from './ast-runtime.js';
+export declare function subtreeContainsConfirm(node: StepNode): boolean;
+/** DFS 遍历共享状态——步骤状态映射、变量存储、loop 计数器及 newlyRunning/newlyDone 回收通道。见 [[exec-engine#^anc-exec-dfs-traversal]] */
+export interface TraversalState {
+    stepStates: Map<string, StepStatus>;
+    variables: VariableStore;
+    loopCounters: Map<string, number>;
+    newlyRunning?: StepNode[];
+    newlyDone?: {
+        node: StepNode;
+        failed: boolean;
+    }[];
+}
+/** DFS 遍历结果——executable（命中可执行步骤）/exit（触发提前退出）/retry（控制流后重新遍历）/none（无可执行节点）四态之一。见 [[exec-engine#^anc-exec-dfs-traversal]] */
+export type TraversalResult = {
+    kind: 'executable';
+    step: StepNode;
+} | {
+    kind: 'exit';
+    step: ExitStep;
+} | {
+    kind: 'retry';
+} | {
+    kind: 'none';
+};
+/** 深度优先前序遍历步骤树，定位下一个可执行节点：容器自动展开标 running、branch 内部评估条件、loop/控制流状态转移。见 [[exec-engine#^anc-exec-dfs-traversal]] */
+export declare function dfsNextStep(steps: StepNode[], state: TraversalState, spec: SpecAST): TraversalResult;
+export declare function collectParallelBatch(steps: StepNode[], state: TraversalState, spec: SpecAST, inParallelContext?: boolean): {
+    parallelStepId: string;
+    children: StepNode[];
+} | null;
+/** 完成级联：某步终态后递归向上检查父容器，全 children 终态则容器完成并按声明 +→ 提升聚合输出、loop 触发下轮迭代。见 [[exec-engine#^anc-exec-completion-cascade]] */
+export declare function propagateCompletion(stepId: string, state: TraversalState, spec: SpecAST): void;
+/** 求值 branch case 条件表达式：`{var}` 真值判定、`{var}==literal` / `{var}!=literal` 字符串比较，空条件恒真（default case）。见 [[exec-engine#^anc-exec-dfs-traversal]] */
+export declare function evaluateCondition(condition: string | undefined, variables: VariableStore, scopeId: string): boolean;
+export declare function collectDescendants(node: StepNode): StepNode[];

package/dist/engine-traverse.js

@@ -0,0 +1,385 @@
+import { EXECUTABLE_STEP_TYPES, CONTAINER_STEP_TYPES, hasChildren, getChildren, getParentStepId } from './ast-helpers.js';
+import { getWriteScope, buildStepMap, SCOPE_CREATING_TYPES, isTruthy, isTerminalStatus } from './ast-runtime.js';
+const DEFAULT_MAX_ITERATIONS = 100;
+// 静态判定 child 子树是否含 confirm——含则不可并行（多 worker 同时暂停 confirm 无法干净串行问人）。
+// DFS 遍历所有后代；call 步骤的 callee 无法静态展开，保守不视为含 confirm（留运行时，同 P8 哲学）。
+// 见 design/parallel-execution.md ^anc-exec-parallel-confirm-exclude。// @a: anc-exec-parallel-confirm-exclude
+export function subtreeContainsConfirm(node) {
+    if (node.step_type === 'confirm')
+        return true;
+    if (hasChildren(node)) {
+        for (const child of getChildren(node)) {
+            if (subtreeContainsConfirm(child))
+                return true;
+        }
+    }
+    return false;
+}
+/** 深度优先前序遍历步骤树，定位下一个可执行节点：容器自动展开标 running、branch 内部评估条件、loop/控制流状态转移。见 [[exec-engine#^anc-exec-dfs-traversal]] */
+export function dfsNextStep(steps, state, spec) {
+    for (const step of steps) {
+        const status = state.stepStates.get(step.step_id);
+        if (isTerminalStatus(status))
+            continue;
+        if (status === 'pending') {
+            if (step.step_type === 'break') {
+                handleBreak(step, state, spec);
+                return { kind: 'retry' };
+            }
+            if (step.step_type === 'continue') {
+                handleContinue(step, state, spec);
+                return { kind: 'retry' };
+            }
+            if (step.step_type === 'exit') {
+                handleExit(step, state, spec);
+                return { kind: 'exit', step: step };
+            }
+            if (EXECUTABLE_STEP_TYPES.has(step.step_type)) {
+                // 叶子 `+ → x = 初值` 每次执行前重置：写入 default 到叶子的 write scope（最近容器 scope）。
+                // loop 内每轮该步执行即每轮重置（Python `x=None` 语义）。仅带 default 的输出触发，opt-in。
+                // 见 ^anc-exec-output-init。// @a: anc-exec-output-init
+                if (step.outputs?.some(o => o.default !== undefined)) {
+                    const leafScope = getWriteScope(step.step_id, spec);
+                    for (const o of step.outputs) {
+                        if (o.default !== undefined)
+                            state.variables.write(o.name, o.default, leafScope);
+                    }
+                }
+                return { kind: 'executable', step };
+            }
+            if (CONTAINER_STEP_TYPES.has(step.step_type)) {
+                state.stepStates.set(step.step_id, 'running');
+                state.newlyRunning?.push(step);
+                ensureScope(step, state, spec);
+                if (step.step_type === 'branch') {
+                    const evalResult = handleBranchEntry(step, state, spec);
+                    if (evalResult === 'error')
+                        return { kind: 'none' };
+                }
+                if (step.step_type === 'loop') {
+                    const loop = step;
+                    const maxIter = loop.max_iterations ?? DEFAULT_MAX_ITERATIONS;
+                    if (maxIter === 0) {
+                        state.stepStates.set(step.step_id, 'done');
+                        skipAllChildren(step, state);
+                        continue;
+                    }
+                    state.loopCounters.set(step.step_id, 1);
+                }
+                // for-each parallel：不进入子树（模板 child 是展开模板，不直接执行），
+                // 交给 collectParallelBatch 动态展开。见 design/parallel-execution.md §9b
+                // @a: anc-exec-parallel-foreach
+                if (step.step_type === 'parallel' && step.forEach) {
+                    continue;
+                }
+                const children = getChildren(step);
+                if (children.length > 0) {
+                    const result = dfsNextStep(children, state, spec);
+                    if (result.kind !== 'none')
+                        return result;
+                }
+                continue;
+            }
+        }
+        if (status === 'running' && CONTAINER_STEP_TYPES.has(step.step_type)) {
+            const children = getChildren(step);
+            if (children.length > 0) {
+                const result = dfsNextStep(children, state, spec);
+                if (result.kind !== 'none')
+                    return result;
+            }
+            continue;
+        }
+    }
+    return { kind: 'none' };
+}
+// 复用模式真并行:找最外层 running/pending parallel,返回其 pending 直接 children(容器),供批量 fan-out。
+// "最外层"判定:DFS 下行携带 inParallelContext——遇 parallel 且 !inParallelContext 即最外层;进入其子树后
+// 置 true,内层再遇 parallel 不扇出(退化顺序模拟)。S12 保证 children 无依赖→串/并等价。
+// @a: anc-exec-parallel-batch, anc-exec-parallel-one-layer
+export function collectParallelBatch(steps, state, spec, inParallelContext = false) {
+    for (const step of steps) {
+        const status = state.stepStates.get(step.step_id);
+        if (isTerminalStatus(status))
+            continue;
+        // 最外层 parallel（pending 或 running，但前序 sibling 必须全部终态——否则前序步骤还没完成不能 fan-out）
+        if (step.step_type === 'parallel' && !inParallelContext) {
+            // 检查本层级中 parallel 之前的 sibling 是否都已终态
+            const siblings = steps;
+            const myIndex = siblings.indexOf(step);
+            const allPriorDone = siblings.slice(0, myIndex).every(s => isTerminalStatus(state.stepStates.get(s.step_id)));
+            if (!allPriorDone)
+                continue;
+            const children = getChildren(step);
+            const pendingChildren = children.filter(c => {
+                const s = state.stepStates.get(c.step_id);
+                return s === undefined || s === 'pending';
+            });
+            // 含 confirm 子树的 child 结构性排除出并行批次，保持 pending 留主循环串行推进。
+            // 见 design/parallel-execution.md ^anc-exec-parallel-confirm-exclude。// @a: anc-exec-parallel-confirm-exclude
+            const parallelizable = pendingChildren.filter(c => !subtreeContainsConfirm(c));
+            // 无可并行 child（全空 / 剩的全含 confirm）→ 此 parallel 无并行批次,交主循环串行 dfsNextStep
+            if (parallelizable.length === 0)
+                continue;
+            return { parallelStepId: step.step_id, children: parallelizable };
+        }
+        // 进入容器子树继续找(running 的容器才下钻;pending 的非 parallel 容器尚未进入,跳过交 dfsNextStep 处理)
+        if (CONTAINER_STEP_TYPES.has(step.step_type) && status === 'running') {
+            const nextInParallel = inParallelContext || step.step_type === 'parallel';
+            const found = collectParallelBatch(getChildren(step), state, spec, nextInParallel);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/** 完成级联：某步终态后递归向上检查父容器，全 children 终态则容器完成并按声明 +→ 提升聚合输出、loop 触发下轮迭代。见 [[exec-engine#^anc-exec-completion-cascade]] */
+export function propagateCompletion(stepId, state, spec) {
+    const parentId = getParentStepId(stepId);
+    if (!parentId)
+        return;
+    const stepMap = buildStepMap(spec);
+    const parent = stepMap.get(parentId);
+    if (!parent)
+        return;
+    if (!CONTAINER_STEP_TYPES.has(parent.step_type))
+        return;
+    const children = getChildren(parent);
+    const allTerminal = children.every(c => isTerminalStatus(state.stepStates.get(c.step_id)));
+    if (!allTerminal)
+        return;
+    if (parent.step_type === 'loop') {
+        const loop = parent;
+        const maxIter = loop.max_iterations ?? DEFAULT_MAX_ITERATIONS;
+        const currentIter = state.loopCounters.get(parent.step_id) ?? 1;
+        if (currentIter < maxIter) {
+            const allChildrenDoneOrSkipped = children.every(c => {
+                const s = state.stepStates.get(c.step_id);
+                return s === 'done' || s === 'skipped';
+            });
+            if (allChildrenDoneOrSkipped) {
+                state.loopCounters.set(parent.step_id, currentIter + 1);
+                resetChildrenToPending(children, state);
+                // Python 语义：变量跨迭代自然保留，引擎不清当轮变量。
+                // 需每轮重置的量由作者在子步骤显式 `+ → x = Null`（叶子每轮执行即重置）。
+                // 见 [[exec-engine]] 变量作用域规则 6 / 概念 ^anc-exec-loop-var-scope。// @a: anc-exec-loop-var-scope
+                return;
+            }
+        }
+    }
+    // Promote container declared outputs to parent scope
+    if (parent.outputs && parent.outputs.length > 0 && SCOPE_CREATING_TYPES.has(parent.step_type)) {
+        const containerScope = parentId;
+        const parentScope = getWriteScope(parentId, spec);
+        for (const decl of parent.outputs) {
+            const val = state.variables.read(decl.name, containerScope);
+            if (val !== undefined) {
+                state.variables.write(decl.name, val, parentScope);
+            }
+        }
+    }
+    // branch 完成判定：被选中的 case 失败即 branch 失败（concept: 被激活的 case 失败 → branch 失败）
+    // 其余 case 为 skipped，仅当选中的 case（非 skipped）为 failed 时 branch failed
+    if (parent.step_type === 'branch') {
+        const activeFailed = children.some(c => state.stepStates.get(c.step_id) === 'failed');
+        state.stepStates.set(parentId, activeFailed ? 'failed' : 'done');
+        state.newlyDone?.push({ node: parent, failed: activeFailed });
+        propagateCompletion(parentId, state, spec);
+        return;
+    }
+    state.stepStates.set(parentId, 'done');
+    // parallel 容器 done 由 joinParallel 直接记录,此通道排除 parallel(避免重复)。
+    // 见 design/spec-observability.md ^anc-obs-step-done-timing。
+    if (parent.step_type !== 'parallel') {
+        state.newlyDone?.push({ node: parent, failed: false });
+    }
+    propagateCompletion(parentId, state, spec);
+}
+/** 求值 branch case 条件表达式：`{var}` 真值判定、`{var}==literal` / `{var}!=literal` 字符串比较，空条件恒真（default case）。见 [[exec-engine#^anc-exec-dfs-traversal]] */
+export function evaluateCondition(condition, variables, scopeId) {
+    if (!condition || condition.trim() === '')
+        return true;
+    const trimmed = condition.trim();
+    const neqIdx = trimmed.indexOf('!=');
+    if (neqIdx >= 0) {
+        const varName = extractVarName(trimmed.slice(0, neqIdx).trim());
+        const literal = stripQuotes(trimmed.slice(neqIdx + 2).trim());
+        const value = variables.read(varName, scopeId);
+        return String(value) !== literal;
+    }
+    const eqIdx = trimmed.indexOf('==');
+    if (eqIdx >= 0) {
+        const varName = extractVarName(trimmed.slice(0, eqIdx).trim());
+        const literal = stripQuotes(trimmed.slice(eqIdx + 2).trim());
+        const value = variables.read(varName, scopeId);
+        return String(value) === literal;
+    }
+    const varName = extractVarName(trimmed);
+    const value = variables.read(varName, scopeId);
+    return isTruthy(value);
+}
+function extractVarName(expr) {
+    if (expr.startsWith('{') && expr.endsWith('}')) {
+        return expr.slice(1, -1).trim();
+    }
+    return expr.trim();
+}
+function stripQuotes(s) {
+    if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith('"') && s.endsWith('"'))) {
+        return s.slice(1, -1);
+    }
+    return s;
+}
+function handleBranchEntry(branch, state, spec) {
+    const scopeId = getWriteScope(branch.step_id, spec);
+    const cases = branch.children;
+    for (let i = 0; i < cases.length; i++) {
+        const caseStep = cases[i];
+        const isDefault = !caseStep.condition || caseStep.condition.trim() === '' || caseStep.condition.trim() === 'default';
+        const matches = isDefault || evaluateCondition(caseStep.condition, state.variables, scopeId);
+        if (matches) {
+            state.stepStates.set(caseStep.step_id, 'running');
+            ensureScope(caseStep, state, spec);
+            // 选中的 case 进 newlyRunning(branch 自身已被 dfsNextStep 加入),
+            // nextStep 据此为 case 容器记录 step_start 骨架。未选中走 skipCaseRecursive。
+            // 见 design/spec-observability.md ^anc-obs-step-start-timing。// @a: anc-obs-step-start-timing
+            state.newlyRunning?.push(caseStep);
+            for (let j = 0; j < cases.length; j++) {
+                if (j !== i) {
+                    skipCaseRecursive(cases[j], state);
+                }
+            }
+            return 'ok';
+        }
+    }
+    // No case matched — silent skip: mark branch done, all cases skipped, outputs None
+    for (const caseStep of cases) {
+        skipCaseRecursive(caseStep, state);
+    }
+    if (branch.outputs) {
+        const branchScope = getWriteScope(branch.step_id, spec);
+        for (const out of branch.outputs) {
+            state.variables.write(out.name, null, branchScope);
+        }
+    }
+    state.stepStates.set(branch.step_id, 'done');
+    return 'ok';
+}
+/** 从 stepId 向上找最近的 loop 祖先节点（break/continue 共用）。无则 null。 */
+function findNearestLoopAncestor(stepId, spec) {
+    const stepMap = buildStepMap(spec);
+    let ancestorId = getParentStepId(stepId);
+    while (ancestorId) {
+        const ancestor = stepMap.get(ancestorId);
+        if (ancestor && ancestor.step_type === 'loop')
+            return ancestor;
+        ancestorId = getParentStepId(ancestorId);
+    }
+    return null;
+}
+function handleBreak(step, state, spec) {
+    state.stepStates.set(step.step_id, 'done');
+    const loop = findNearestLoopAncestor(step.step_id, spec);
+    if (loop) {
+        state.stepStates.set(loop.step_id, 'done');
+        skipRemainingInContainer(loop, state);
+        propagateCompletion(loop.step_id, state, spec);
+    }
+}
+function handleContinue(step, state, spec) {
+    state.stepStates.set(step.step_id, 'done');
+    const loop = findNearestLoopAncestor(step.step_id, spec);
+    if (loop) {
+        skipRemainingInContainer(loop, state);
+        propagateCompletion(step.step_id, state, spec);
+    }
+}
+function handleExit(step, state, spec) {
+    state.stepStates.set(step.step_id, 'done');
+    if (step.exit_outputs) {
+        const scopeId = getWriteScope(step.step_id, spec);
+        for (const [k, v] of Object.entries(step.exit_outputs)) {
+            state.variables.write(k, v, scopeId);
+        }
+    }
+    for (const [id, status] of state.stepStates) {
+        if (status === 'pending' || status === 'running') {
+            if (id !== step.step_id) {
+                state.stepStates.set(id, 'skipped');
+            }
+        }
+    }
+}
+function ensureScope(step, state, spec) {
+    if (!SCOPE_CREATING_TYPES.has(step.step_type))
+        return;
+    // 显式判"已存在"（loop 重进 / resume 已恢复），不建、不重灌初值——避免用 createScope 抛错做控制流。
+    if (state.variables.hasScope(step.step_id))
+        return;
+    const parentScope = getWriteScope(step.step_id, spec);
+    // parent scope 未建则跳过——worker 子实例 executeSubtreeOnly 收窄执行到 child 子树、父容器 scope 不建，
+    // 此时 child 容器的 parent 缺失是合法的（旧实现靠 createScope 抛错被 catch 吞，现显式判）。
+    if (!state.variables.hasScope(parentScope))
+        return;
+    state.variables.createScope(step.step_id, parentScope);
+    // 容器节点 `+ → acc = 初值` 的 init-once：仅首次创建 scope 时写入（loop 每轮重进/resume 恢复都提前 return，
+    // 不重灌 → 累加器保值）。见 ^anc-exec-output-init。// @a: anc-exec-output-init
+    if (step.outputs) {
+        for (const o of step.outputs) {
+            if (o.default !== undefined)
+                state.variables.write(o.name, o.default, step.step_id);
+        }
+    }
+}
+function skipCaseRecursive(caseStep, state) {
+    state.stepStates.set(caseStep.step_id, 'skipped');
+    skipAllChildren(caseStep, state);
+}
+// 标记子孙：仅 pending → skipped（未执行的才算跳过）；已 done/failed/running/skipped 不动，
+// 保留其真实执行状态（break 路径上已执行的子步骤不该被误标 skipped）
+function skipAllChildren(step, state) {
+    if (!hasChildren(step))
+        return;
+    for (const child of getChildren(step)) {
+        if (state.stepStates.get(child.step_id) === 'pending') {
+            state.stepStates.set(child.step_id, 'skipped');
+        }
+        skipAllChildren(child, state);
+    }
+}
+// break/continue 收尾 loop 时调用：未执行的 pending → skipped；
+// 执行路径上的 running（如命中的 branch/case）→ done（它执行到了 break/continue，不是被跳过）；
+// 已 done/failed/skipped 的不动。避免把已执行步骤误标 skipped。
+function skipRemainingInContainer(container, state) {
+    if (!hasChildren(container))
+        return;
+    for (const child of getChildren(container)) {
+        const status = state.stepStates.get(child.step_id);
+        if (status === 'pending') {
+            state.stepStates.set(child.step_id, 'skipped');
+            skipAllChildren(child, state);
+        }
+        else if (status === 'running') {
+            state.stepStates.set(child.step_id, 'done');
+            skipAllChildren(child, state);
+        }
+    }
+}
+function resetChildrenToPending(children, state) {
+    for (const child of children) {
+        state.stepStates.set(child.step_id, 'pending');
+        if (hasChildren(child)) {
+            resetChildrenToPending(getChildren(child), state);
+        }
+    }
+}
+// 收集一个节点的所有后代（不含自身），用于 parallel child 子树输入解析、subtree 收窄等
+export function collectDescendants(node) {
+    if (!hasChildren(node))
+        return [];
+    const out = [];
+    for (const c of getChildren(node)) {
+        out.push(c, ...collectDescendants(c));
+    }
+    return out;
+}