@hoplogic/hopjit 0.1.0

package/dist/ast-helpers.d.ts

@@ -0,0 +1,26 @@
+import type { StepType, StepNode, SubtaskStep, ParallelStep, LoopStep, BranchStep, CaseStep } from './ast-types.js';
+/** 7 种可执行步骤类型集合（reason/act/check/confirm/ask/commit/call），供 parser/validator/engine 判类。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export declare const EXECUTABLE_STEP_TYPES: ReadonlySet<StepType>;
+/** 8 种结构/控制流步骤类型集合（subtask/parallel/loop/branch/case/break/continue/exit），由引擎内部展开而非交 LLM 执行。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export declare const STRUCTURAL_STEP_TYPES: ReadonlySet<StepType>;
+/** 持有 children 的容器步骤类型集合（subtask/parallel/loop/branch/case），isContainerStep 据此判定。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export declare const CONTAINER_STEP_TYPES: ReadonlySet<StepType>;
+/** 全部 15 种步骤类型集合（7 可执行 ∪ 8 结构/控制流），全类型判类的并集。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export declare const ALL_STEP_TYPES: ReadonlySet<StepType>;
+export declare const DEFLATE_THRESHOLD = 4096;
+export declare const HUMAN_PREVIEW_THRESHOLD = 5000;
+export declare function isContainerStep(step: StepNode): step is SubtaskStep | ParallelStep | LoopStep | BranchStep | CaseStep;
+/** 判定步骤是否实际持有 children 数组的类型守卫（结构存在性检查，收窄为容器步骤类型）。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export declare function hasChildren(step: StepNode): step is SubtaskStep | ParallelStep | LoopStep | BranchStep | CaseStep;
+/** 取步骤的子步骤列表，非容器或无 children 时返回空数组。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export declare function getChildren(step: StepNode): StepNode[];
+export declare function getParentStepId(stepId: string): string | null;
+/** 判某输出名是否为该步的"更新模式"输出——步骤同时 `← outName` 且 `+ → outName`（读入即输出，
+ * 在既有变量基础上更新而非新产出）。三处共用同一判据：engine failStep 跳过 null 化 / check 失败
+ * 写回 / validator V3 放行遮蔽。抽此消除重复、保判据一致。见 ^anc-exec-failstep-skip-update / ^anc-rule-v3。
+ * @a: anc-exec-failstep-skip-update */
+export declare function isUpdateModeOutput(step: {
+    inputs?: {
+        source: string;
+    }[];
+}, outName: string): boolean;

package/dist/ast-helpers.js

@@ -0,0 +1,58 @@
+// @module: spec-ast ^anc-struct-spec-ast
+// AST 谓词函数 + 跨模块常量——非类型的运行时逻辑（从原 types.ts 剥离，回归 types 纯类型契约）。
+// 见 design/spec-ast.md ^anc-struct-spec-ast（拆分动机：类型文件不应混逻辑）。
+/** 7 种可执行步骤类型集合（reason/act/check/confirm/ask/commit/call），供 parser/validator/engine 判类。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export const EXECUTABLE_STEP_TYPES = new Set([
+    'reason', 'act', 'check', 'confirm', 'ask', 'commit', 'call',
+]);
+/** 8 种结构/控制流步骤类型集合（subtask/parallel/loop/branch/case/break/continue/exit），由引擎内部展开而非交 LLM 执行。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export const STRUCTURAL_STEP_TYPES = new Set([
+    'subtask', 'parallel', 'loop', 'branch', 'case', 'break', 'continue', 'exit',
+]);
+/** 持有 children 的容器步骤类型集合（subtask/parallel/loop/branch/case），isContainerStep 据此判定。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export const CONTAINER_STEP_TYPES = new Set([
+    'subtask', 'parallel', 'loop', 'branch', 'case',
+]);
+/** 全部 15 种步骤类型集合（7 可执行 ∪ 8 结构/控制流），全类型判类的并集。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export const ALL_STEP_TYPES = new Set([
+    ...EXECUTABLE_STEP_TYPES, ...STRUCTURAL_STEP_TYPES,
+]);
+// 大内容阈值(agent 通道):NextResponse 中 inputs/outputs/params_for_child 等
+// record 的单个值 JSON.stringify().length 超此阈值时,引擎自动写入 work_zone/vars/<key>.json,
+// 响应中替换为 {$file: abs_path} 指针。driver/LLM 遇 $file 时 Read 取真实值。
+// 见 design/shared-types.md ^anc-exec-deflate。// @a: anc-exec-deflate
+export const DEFLATE_THRESHOLD = 4096;
+// 人通道预览阈值:paused.presented_data.context(给 user 看的)单值超此字符数时,
+// 引擎返 {$file, preview} 复合格式:preview = 头 5K 字符 + "...[完整内容见文件]",
+// driver 完整 dump preview 给 user 看,$file 让 user 知完整在哪。
+// 见 design/shared-types.md ^anc-exec-deflate / 概念 ^anc-exec-audience-routing。
+// @a: anc-exec-deflate, anc-exec-audience-routing
+export const HUMAN_PREVIEW_THRESHOLD = 5000;
+// ===== Type guards =====
+export function isContainerStep(step) {
+    return CONTAINER_STEP_TYPES.has(step.step_type);
+}
+/** 判定步骤是否实际持有 children 数组的类型守卫（结构存在性检查，收窄为容器步骤类型）。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export function hasChildren(step) {
+    return 'children' in step && Array.isArray(step.children);
+}
+/** 取步骤的子步骤列表，非容器或无 children 时返回空数组。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export function getChildren(step) {
+    if (hasChildren(step))
+        return step.children;
+    return [];
+}
+// ===== step_id 寻址 =====
+// 取父 step_id：纯字符串操作（"1.2.3" → "1.2"，"1" → null）。
+// 无状态 AST 寻址，非执行调度职责——归 spec-ast（从 engine-traverse 迁入）。
+export function getParentStepId(stepId) {
+    const lastDot = stepId.lastIndexOf('.');
+    return lastDot >= 0 ? stepId.slice(0, lastDot) : null;
+}
+/** 判某输出名是否为该步的"更新模式"输出——步骤同时 `← outName` 且 `+ → outName`（读入即输出，
+ * 在既有变量基础上更新而非新产出）。三处共用同一判据：engine failStep 跳过 null 化 / check 失败
+ * 写回 / validator V3 放行遮蔽。抽此消除重复、保判据一致。见 ^anc-exec-failstep-skip-update / ^anc-rule-v3。
+ * @a: anc-exec-failstep-skip-update */
+export function isUpdateModeOutput(step, outName) {
+    return step.inputs?.some(b => b.source === outName) ?? false;
+}

package/dist/ast-runtime.d.ts

@@ -0,0 +1,49 @@
+import type { OutputDecl, SpecAST, StepNode } from './ast-types.js';
+export type StepStatus = 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+/** 步骤是否处于终态（done/failed/skipped）。单点定义终态集合——engine/engine-traverse 多处判据复用，
+ * 新增终态只改这里。undefined（从未 set 状态的 pending 步骤）返回 false。 */
+export declare function isTerminalStatus(st: StepStatus | undefined): boolean;
+/** 树状变量作用域节点：持有本层变量表并链向父作用域，read 沿链上溯实现遮蔽/继承。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export interface VariableScope {
+    id: string;
+    parent: VariableScope | null;
+    variables: Map<string, unknown>;
+}
+/** 树状作用域变量存储：按 scope_id 管理变量的读写/作用域创建/序列化，供 engine 与 prompt 消费（从 engine-vars 迁入语言运行时层）。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export declare class VariableStore {
+    private root;
+    private scopes;
+    constructor(inputs?: Record<string, unknown>);
+    createScope(scopeId: string, parentId: string): VariableScope;
+    /** scope 是否已存在（供 ensureScope 显式判 loop 重进/resume 已恢复，避免用 createScope 抛错做控制流）。 */
+    hasScope(scopeId: string): boolean;
+    findScope(stepId: string): VariableScope;
+    read(name: string, scopeId: string): unknown;
+    write(name: string, value: unknown, scopeId: string): void;
+    writeToRoot(name: string, value: unknown): void;
+    writeOutputs(outputs: Record<string, unknown>, scopeId: string): void;
+    setOutputsToNull(outputDecls: OutputDecl[], scopeId: string): void;
+    getAllVariables(): Record<string, unknown>;
+    getPendingOutputs(declaredOutputs: OutputDecl[]): string[];
+    clearScope(scopeId: string): void;
+    deleteVar(name: string, scopeId: string): void;
+    deleteScope(scopeId: string): void;
+    /** 序列化完整 scope 树（vars.json format_version=2）：每个 scope 记 parent id + 本层变量。
+     * 见 [[exec-engine#^anc-exec-vars-scope-persist]]。不再拍平——拍平会丢兄弟 scope 同名变量。 */
+    toJSON(): Record<string, {
+        parent: string | null;
+        variables: Record<string, unknown>;
+    }>;
+    /** 从 scope 树重建（v2）：三遍——① 建所有空 scope ② 连 parent 指针 ③ 灌变量，
+     * 保证连指针/灌变量前所有节点已在 map。见 [[exec-engine#^anc-exec-vars-scope-persist]]。 */
+    static fromScopes(scopes: Record<string, {
+        parent: string | null;
+        variables: Record<string, unknown>;
+    }>): VariableStore;
+    /** v1 legacy：扁平变量字典全塞 root（向后兼容旧 vars.json）。 */
+    static fromJSON(data: Record<string, unknown>): VariableStore;
+}
+export declare const SCOPE_CREATING_TYPES: Set<string>;
+export declare function buildStepMap(spec: SpecAST): Map<string, StepNode>;
+export declare function getWriteScope(stepId: string, spec: SpecAST): string;
+export declare function isTruthy(value: unknown): boolean;

package/dist/ast-runtime.js

@@ -0,0 +1,224 @@
+import { getParentStepId, hasChildren, getChildren } from './ast-helpers.js';
+/** 步骤是否处于终态（done/failed/skipped）。单点定义终态集合——engine/engine-traverse 多处判据复用，
+ * 新增终态只改这里。undefined（从未 set 状态的 pending 步骤）返回 false。 */
+export function isTerminalStatus(st) {
+    return st === 'done' || st === 'failed' || st === 'skipped';
+}
+/** 树状作用域变量存储：按 scope_id 管理变量的读写/作用域创建/序列化，供 engine 与 prompt 消费（从 engine-vars 迁入语言运行时层）。见 [[spec-ast#^anc-struct-spec-ast-exports]]。 */
+export class VariableStore {
+    root;
+    scopes = new Map();
+    constructor(inputs) {
+        this.root = { id: 'root', parent: null, variables: new Map() };
+        this.scopes.set('root', this.root);
+        if (inputs) {
+            for (const [k, v] of Object.entries(inputs)) {
+                this.root.variables.set(k, v);
+            }
+        }
+    }
+    createScope(scopeId, parentId) {
+        const parent = this.scopes.get(parentId);
+        if (!parent)
+            throw new Error(`Parent scope '${parentId}' not found`);
+        const scope = { id: scopeId, parent, variables: new Map() };
+        this.scopes.set(scopeId, scope);
+        return scope;
+    }
+    /** scope 是否已存在（供 ensureScope 显式判 loop 重进/resume 已恢复，避免用 createScope 抛错做控制流）。 */
+    hasScope(scopeId) {
+        return this.scopes.has(scopeId);
+    }
+    findScope(stepId) {
+        return this.scopes.get(stepId) ?? this.root;
+    }
+    read(name, scopeId) {
+        // 整名优先：先按 name 原样向上查找（兼容真有 "a.b" 此名的扁平变量）。
+        let scope = this.scopes.get(scopeId) ?? this.root;
+        while (scope) {
+            if (scope.variables.has(name))
+                return scope.variables.get(name);
+            scope = scope.parent;
+        }
+        // 未命中且含路径分隔 → dotted path 成员访问：首段为根变量，逐段下钻。
+        // 类似 JSON 路径：对象字段按 key 取，数组按数字下标取（`arr.0` 或 `arr[0]` 皆可）。
+        // 用于 for-each 元素按字段/下标分流（如 branch 条件 {point.type}、{items.0.name}）。
+        // 见 design ^anc-exec-dfs-traversal 条件求值。中途某段无法下钻（非对象/数组、越界、字段缺失）→ undefined。
+        if (name.includes('.') || name.includes('[')) {
+            // 归一化 `a[0].b` → `a.0.b`，再按 `.` 分段
+            const segs = name.replace(/\[(\w+)\]/g, '.$1').split('.').filter(s => s !== '');
+            let cur = this.scopes.get(scopeId) ?? this.root;
+            while (cur) {
+                if (cur.variables.has(segs[0])) {
+                    let val = cur.variables.get(segs[0]);
+                    for (let i = 1; i < segs.length; i++) {
+                        if (val === null || typeof val !== 'object')
+                            return undefined;
+                        if (Array.isArray(val)) {
+                            const idx = Number(segs[i]);
+                            if (!Number.isInteger(idx))
+                                return undefined; // 数组只接受整数下标
+                            val = val[idx];
+                        }
+                        else {
+                            val = val[segs[i]];
+                        }
+                    }
+                    return val;
+                }
+                cur = cur.parent;
+            }
+        }
+        return undefined;
+    }
+    write(name, value, scopeId) {
+        const scope = this.scopes.get(scopeId) ?? this.root;
+        scope.variables.set(name, value);
+    }
+    writeToRoot(name, value) {
+        this.root.variables.set(name, value);
+    }
+    writeOutputs(outputs, scopeId) {
+        for (const [k, v] of Object.entries(outputs)) {
+            this.write(k, v, scopeId);
+        }
+    }
+    setOutputsToNull(outputDecls, scopeId) {
+        for (const decl of outputDecls) {
+            this.write(decl.name, null, scopeId);
+        }
+    }
+    getAllVariables() {
+        const result = {};
+        const collectScope = (scope) => {
+            for (const [k, v] of scope.variables) {
+                if (!(k in result))
+                    result[k] = v;
+            }
+        };
+        for (const scope of this.scopes.values()) {
+            collectScope(scope);
+        }
+        return result;
+    }
+    getPendingOutputs(declaredOutputs) {
+        const allVars = this.getAllVariables();
+        return declaredOutputs
+            .filter(o => !(o.name in allVars) || allVars[o.name] === undefined)
+            .map(o => o.name);
+    }
+    clearScope(scopeId) {
+        const scope = this.scopes.get(scopeId);
+        if (scope)
+            scope.variables.clear();
+    }
+    // 从指定 scope 删除单个变量（删后 read 沿链上溯，本 scope 无则返回祖先值或 undefined）。
+    // 注：Python 语义改造后引擎不再每轮清变量（^anc-exec-loop-var-scope），此方法为通用工具、无引擎内部调用者。
+    deleteVar(name, scopeId) {
+        const scope = this.scopes.get(scopeId);
+        if (scope)
+            scope.variables.delete(name);
+    }
+    deleteScope(scopeId) {
+        this.scopes.delete(scopeId);
+    }
+    /** 序列化完整 scope 树（vars.json format_version=2）：每个 scope 记 parent id + 本层变量。
+     * 见 [[exec-engine#^anc-exec-vars-scope-persist]]。不再拍平——拍平会丢兄弟 scope 同名变量。 */
+    // @a: anc-exec-vars-scope-persist
+    toJSON() {
+        const result = {};
+        for (const [scopeId, scope] of this.scopes) {
+            result[scopeId] = {
+                parent: scope.parent?.id ?? null,
+                variables: Object.fromEntries(scope.variables),
+            };
+        }
+        return result;
+    }
+    /** 从 scope 树重建（v2）：三遍——① 建所有空 scope ② 连 parent 指针 ③ 灌变量，
+     * 保证连指针/灌变量前所有节点已在 map。见 [[exec-engine#^anc-exec-vars-scope-persist]]。 */
+    // @a: anc-exec-vars-scope-persist
+    static fromScopes(scopes) {
+        const store = new VariableStore();
+        // 第 1 遍：建所有 scope 节点（root 已由构造函数建好，复用之）
+        for (const scopeId of Object.keys(scopes)) {
+            if (scopeId === 'root')
+                continue;
+            store.scopes.set(scopeId, { id: scopeId, parent: null, variables: new Map() });
+        }
+        // 第 2 遍：连 parent 指针。孤儿 parent（数据里不存在该 parent id）响亮失败——vars.json v2 应含
+        // 完整 scope 树，parent 缺失是数据损坏，静默挂 root 会掩盖它。
+        for (const [scopeId, data] of Object.entries(scopes)) {
+            if (scopeId === 'root')
+                continue;
+            const scope = store.scopes.get(scopeId);
+            if (data.parent === null) {
+                scope.parent = store.root;
+                continue;
+            }
+            const parent = store.scopes.get(data.parent);
+            if (!parent)
+                throw new Error(`CORRUPT_STATE_FILE: vars.json scope '${scopeId}' 的 parent '${data.parent}' 不存在（scope 树损坏）`);
+            scope.parent = parent;
+        }
+        // 第 3 遍：灌变量（含 root）
+        for (const [scopeId, data] of Object.entries(scopes)) {
+            const scope = store.scopes.get(scopeId) ?? store.root;
+            for (const [k, v] of Object.entries(data.variables))
+                scope.variables.set(k, v);
+        }
+        return store;
+    }
+    /** v1 legacy：扁平变量字典全塞 root（向后兼容旧 vars.json）。 */
+    static fromJSON(data) {
+        return new VariableStore(data);
+    }
+}
+// ===== step_id 寻址 + 作用域定位（从 engine-traverse 迁入）=====
+// 开作用域的容器类型:branch 声明聚合输出(统一接口名),各 case 同名填充。
+// branch + case 都开作用域。见 design/exec-engine.md 变量作用域规则 5b / ^anc-exec-container-output
+export const SCOPE_CREATING_TYPES = new Set(['subtask', 'parallel', 'loop', 'branch', 'case']);
+let _stepMapCache = null;
+// 建 step_id → StepNode 反查表（带 spec 身份缓存）。作用域定位/父节点寻址的公共底座。
+export function buildStepMap(spec) {
+    if (_stepMapCache && _stepMapCache.spec === spec)
+        return _stepMapCache.map;
+    const map = new Map();
+    const walk = (steps) => {
+        for (const step of steps) {
+            map.set(step.step_id, step);
+            if (hasChildren(step))
+                walk(getChildren(step));
+        }
+    };
+    walk(spec.steps ?? []);
+    _stepMapCache = { spec, map };
+    return map;
+}
+// 给定 step_id,向上找最近的作用域容器 scope_id（写变量的归属作用域）。顶层→'root'。
+export function getWriteScope(stepId, spec) {
+    const stepMap = buildStepMap(spec);
+    let current = getParentStepId(stepId);
+    while (current) {
+        const step = stepMap.get(current);
+        if (step && SCOPE_CREATING_TYPES.has(step.step_type)) {
+            return current;
+        }
+        current = getParentStepId(current);
+    }
+    return 'root';
+}
+// ===== 条件真值语义（从 engine-traverse 迁入）=====
+// HopSpec 条件真值判断（branch/case 条件求值、None 传播共用）。
+// null/undefined/false/''/0 为 falsy,其余 truthy。
+export function isTruthy(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (value === false)
+        return false;
+    if (value === '')
+        return false;
+    if (value === 0)
+        return false;
+    return true;
+}

package/dist/ast-types.d.ts

@@ -0,0 +1,260 @@
+export interface SpecAST {
+    header: SpecHeader;
+    steps?: StepNode[];
+}
+/** SpecHeader：Spec 头部字段结构——title/id/goal/constraints/types/inputs/outputs/config/doc_refs。见 [[spec-ast#^anc-ast-spec-header]] */
+export interface SpecHeader {
+    title: string;
+    id?: string;
+    goal?: string;
+    constraints?: string[];
+    types?: TypeDecl[];
+    inputs?: VarDecl[];
+    outputs?: OutputDecl[];
+    config?: SpecConfig;
+    doc_refs?: DocRef[];
+}
+/** TypeDecl：Types 段复用结构体（名称+字段字典），v1 仅校验字段名存在性。见 [[spec-ast#^anc-type-type-decl]] */
+export interface TypeDecl {
+    name: string;
+    fields: Record<string, string>;
+}
+/** VarDecl：变量声明（Inputs 段等），含名称、类型、描述与默认值。见 [[spec-ast#^anc-ast-spec-header]] */
+export interface VarDecl {
+    name: string;
+    type: ValueTypeString | string;
+    description?: string;
+    default?: unknown;
+}
+/** SpecConfig：Config 段配置项——max_depth/max_retries/Spec 级默认 model，允许扩展键。见 [[spec-ast#^anc-ast-spec-header]] */
+export interface SpecConfig {
+    max_depth?: number;
+    max_retries?: number;
+    model?: string;
+    [key: string]: unknown;
+}
+export type ExecutableStepType = 'reason' | 'act' | 'check' | 'confirm' | 'ask' | 'commit' | 'call';
+/** StructuralStepType：8 种结构/控制流步骤类型字面量——由 ExecutionEngine 内部展开，不直接交 LLM。见 [[spec-ast#^anc-ast-step-type]] */
+export type StructuralStepType = 'subtask' | 'parallel' | 'loop' | 'branch' | 'case' | 'break' | 'continue' | 'exit';
+/** StepType：全部 14 种步骤类型联合（可执行 ∪ 结构），BaseStep.step_type 的判别基座。见 [[spec-ast#^anc-ast-step-type]] */
+export type StepType = ExecutableStepType | StructuralStepType;
+/** VarBinding：← 输入绑定（变量名与引用来源，二者同值）。见 [[spec-ast#^anc-ast-base-step]] */
+export interface VarBinding {
+    name: string;
+    source: string;
+}
+/** SourceLocation：markdown 原文行位置（错误报告与定位用）。见 [[spec-ast#^anc-ast-base-step]] */
+export interface SourceLocation {
+    line_start: number;
+    line_end: number;
+}
+/** ParamMapping：call 步骤的父子变量搬运映射（from=来源变量名, to=目标变量名），v1 不做类型匹配。见 [[spec-ast#^anc-step-call]] */
+export interface ParamMapping {
+    from: string;
+    to: string;
+}
+/** BaseStep：所有步骤共享的公共字段基座（step_id/step_type/summary/inputs/outputs/instruction 等）。见 [[spec-ast#^anc-ast-base-step]] */
+export interface BaseStep {
+    step_id: string;
+    step_type: StepType;
+    summary: string;
+    inputs?: VarBinding[];
+    outputs?: OutputDecl[];
+    instruction?: string;
+    model_override?: string;
+    doc_refs?: DocRef[];
+    source_location?: SourceLocation;
+}
+export interface DocRef {
+    doc: string;
+    section: string;
+}
+/** DocRefFragment：engine 运行期解析出的 doc-ref 章节内容（命中标题/正文/匹配级别），注入前的中间形态。见 [[spec-ast#^anc-type-doc-ref]] */
+export interface DocRefFragment {
+    doc: string;
+    section: string;
+    heading: string;
+    content: string;
+    matched: 'exact' | 'normalized' | 'fuzzy';
+    file_path?: string;
+}
+export interface ReasonStep extends BaseStep {
+    step_type: 'reason';
+}
+/** ActStep：act 步骤 AST 节点——执行可逆副作用（限 SandboxConfig 沙箱内），可选 ActBody 结构化 body。见 [[spec-ast#^anc-step-act]] */
+export interface ActStep extends BaseStep {
+    step_type: 'act';
+    body?: ActBody;
+}
+/** CheckStep：check 步骤 AST 节点——验证判定（is_finally 为 Constraints 可执行化身），固定 bool+text 输出签名。见 [[spec-ast#^anc-step-check]] */
+export interface CheckStep extends BaseStep {
+    step_type: 'check';
+    is_finally?: boolean;
+}
+/** ConfirmStep：confirm 步骤 AST 节点——纯审批闸门（+→ 仅 bool），可配 require_human 与 response_options。见 [[spec-ast#^anc-step-confirm]] */
+export interface ConfirmStep extends BaseStep {
+    step_type: 'confirm';
+    require_human?: boolean;
+    response_options?: ResponseOption[];
+}
+/** AskStep：ask 步骤 AST 节点——CITL 数据收集（answer 落到 +→ 变量），present_inputs 声明必须完整展示的输入子集。见 [[spec-ast#^anc-step-ask]] */
+export interface AskStep extends BaseStep {
+    step_type: 'ask';
+    require_human?: boolean;
+    present_inputs?: string[];
+}
+/** CommitStep：commit 步骤 AST 节点——不可逆动作（irreversible_action），与 act 同源复用 ActBody，requires_commit 放行且不可重试。见 [[spec-ast#^anc-step-commit]] */
+export interface CommitStep extends BaseStep {
+    step_type: 'commit';
+    irreversible_action: string;
+    body?: ActBody;
+}
+/** CallStep：call 步骤 AST 节点——调用子 Spec（callee_spec_id），param_mapping/output_mapping 搬运父子变量。见 [[spec-ast#^anc-step-call]] */
+export interface CallStep extends BaseStep {
+    step_type: 'call';
+    callee_spec_id?: string;
+    param_mapping?: ParamMapping[];
+    output_mapping?: ParamMapping[];
+}
+export interface BranchStep extends BaseStep {
+    step_type: 'branch';
+    children: CaseStep[];
+}
+/** SubtaskStep：subtask 结构步骤 AST 节点——容器（children），支持 retry 与 adaptive replan。见 [[spec-ast#^anc-step-subtask]] */
+export interface SubtaskStep extends BaseStep {
+    step_type: 'subtask';
+    retry?: number;
+    adaptive?: boolean;
+    children: StepNode[];
+}
+/** ParallelStep：parallel 结构步骤 AST 节点——并行容器（children），forEach 表达动态 for-each 展开。见 [[spec-ast#^anc-step-parallel]] */
+export interface ParallelStep extends BaseStep {
+    step_type: 'parallel';
+    children: StepNode[];
+    forEach?: {
+        listVar: string;
+        itemVar: string;
+    };
+}
+/** LoopStep：loop 结构步骤 AST 节点——循环容器（children），max_iterations 限迭代，靠 break/continue/exit 终止。见 [[spec-ast#^anc-step-loop]] */
+export interface LoopStep extends BaseStep {
+    step_type: 'loop';
+    max_iterations?: number;
+    children: StepNode[];
+}
+/** CaseStep：case 结构步骤 AST 节点——branch 下的分支子任务（condition 条件，空为 default），继承 subtask 重试语义。见 [[spec-ast#^anc-step-case]] */
+export interface CaseStep extends BaseStep {
+    step_type: 'case';
+    condition?: string;
+    retry?: number;
+    adaptive?: boolean;
+    children: StepNode[];
+}
+/** BreakStep：break 控制流步骤 AST 节点——仅 loop 内合法，Engine 检测后终止循环。见 [[spec-ast#^anc-step-break]] */
+export interface BreakStep extends BaseStep {
+    step_type: 'break';
+}
+/** ContinueStep：continue 控制流步骤 AST 节点——仅 loop 内合法，Engine 检测后跳过当前迭代。见 [[spec-ast#^anc-step-continue]] */
+export interface ContinueStep extends BaseStep {
+    step_type: 'continue';
+}
+/** ExitStep：exit 控制流步骤 AST 节点——任意位置合法，Engine 检测后终止整个 Spec，exit_outputs 为提前退出的输出值。见 [[spec-ast#^anc-step-exit]] */
+export interface ExitStep extends BaseStep {
+    step_type: 'exit';
+    exit_outputs?: Record<string, unknown>;
+}
+/** StepNode：14 个步骤接口的判别联合（按 step_type 编译期收窄），AST steps 树的节点类型。见 [[spec-ast#^anc-ast-step-type]] */
+export type StepNode = ReasonStep | ActStep | CheckStep | ConfirmStep | AskStep | CommitStep | CallStep | BranchStep | SubtaskStep | ParallelStep | LoopStep | CaseStep | BreakStep | ContinueStep | ExitStep;
+/** ValueTypeString：HopSpec 内置值类型字符串字面量集合（text/bool/number/enum(...)/列表/元组等）。见 [[spec-ast#^anc-ast-spec-header]] */
+export type ValueTypeString = 'text' | 'bool' | 'line' | 'number' | 'int' | 'float' | 'markdown' | 'yaml' | 'prompt' | 'HopSpec' | '[line]' | `[${string}]` | `(${string})` | `enum(${string})`;
+/** OutputDecl：+→ 输出声明（名称、类型、描述、可选初值），用于 SpecHeader.outputs 与 BaseStep.outputs。见 [[spec-ast#^anc-type-output-decl]] */
+export interface OutputDecl {
+    name: string;
+    type: ValueTypeString | string;
+    description: string;
+    default?: unknown;
+}
+export interface ActBody {
+    statements: ActStatement[];
+    source_location?: SourceLocation;
+}
+/** ActStatement：act body 语句联合——赋值/调用/if 分支（禁循环）。见 [[spec-ast#^anc-ast-act-body]] */
+export type ActStatement = AssignStmt | CallStmt | IfStmt;
+/** AssignStmt：act body 赋值语句——target（body 局部或 +→ 输出名）= value 表达式。见 [[spec-ast#^anc-ast-act-body]] */
+export interface AssignStmt {
+    type: 'assign';
+    target: string;
+    value: ActExpr;
+    line?: number;
+}
+/** CallStmt：act body 调用语句——把工具/内置调用作为独立副作用语句（如 write）。见 [[spec-ast#^anc-ast-act-body]] */
+export interface CallStmt {
+    type: 'call';
+    call: CallExpr;
+    line?: number;
+}
+/** IfStmt：act body 无推理分支语句——condition 须确定性可求值，elif 展开为 else_body 嵌套。见 [[spec-ast#^anc-ast-act-body]] */
+export interface IfStmt {
+    type: 'if';
+    condition: ActExpr;
+    then_body: ActStatement[];
+    else_body?: ActStatement[];
+    line?: number;
+}
+/** ActExpr：act body 表达式联合——字面量/变量引用/字段访问/二元/一元/调用。见 [[spec-ast#^anc-ast-act-body]] */
+export type ActExpr = LiteralExpr | VarRefExpr | FieldAccessExpr | BinaryExpr | UnaryExpr | CallExpr;
+/** LiteralExpr：act body 字面量表达式——string/number/bool 值及其 literal_kind。见 [[spec-ast#^anc-ast-act-body]] */
+export interface LiteralExpr {
+    type: 'literal';
+    value: string | number | boolean;
+    literal_kind: 'string' | 'number' | 'bool';
+}
+/** VarRefExpr：act body 变量引用表达式（← 输入 / body 局部 / 上文赋值）。见 [[spec-ast#^anc-ast-act-body]] */
+export interface VarRefExpr {
+    type: 'var';
+    name: string;
+}
+/** FieldAccessExpr：act body 字段访问表达式——object.field，可链式 a.b.c。见 [[spec-ast#^anc-ast-act-body]] */
+export interface FieldAccessExpr {
+    type: 'field';
+    object: ActExpr;
+    field: string;
+}
+/** BinaryOp：act body 二元运算符集合——算术/比较/逻辑（+ 按操作数分派数加或串接）。见 [[spec-ast#^anc-ast-act-body]] */
+export type BinaryOp = '+' | '-' | '*' | '/' | '==' | '!=' | '<' | '>' | '<=' | '>=' | 'and' | 'or';
+/** BinaryExpr：act body 二元表达式——op 及左右操作数。见 [[spec-ast#^anc-ast-act-body]] */
+export interface BinaryExpr {
+    type: 'binary';
+    op: BinaryOp;
+    left: ActExpr;
+    right: ActExpr;
+}
+/** UnaryExpr：act body 一元表达式——not/取负 作用于 operand。见 [[spec-ast#^anc-ast-act-body]] */
+export interface UnaryExpr {
+    type: 'unary';
+    op: 'not' | '-';
+    operand: ActExpr;
+}
+/** CallExpr：act body 调用表达式——callee 必须 ∈ 白名单（内置函数 ∪ ToolProvider 工具名），args 参数列表。见 [[spec-ast#^anc-ast-act-body]] */
+export interface CallExpr {
+    type: 'call';
+    callee: string;
+    args: CallArg[];
+}
+/** CallArg：act body 调用实参——工具调用用命名参数（name 必填），内置函数用位置参数（name 省略）。见 [[spec-ast#^anc-ast-act-body]] */
+export interface CallArg {
+    name?: string;
+    value: ActExpr;
+}
+/** StepSummary：步骤精简摘要（step_id/step_type/summary/输出名列表），供 replan 等场景引用。见 [[spec-ast]] */
+export interface StepSummary {
+    step_id: string;
+    step_type: StepType;
+    summary: string;
+    outputs: string[];
+}
+export interface ResponseOption {
+    value: string;
+    label: string;
+    description?: string;
+}

package/dist/ast-types.js

@@ -0,0 +1,4 @@
+// @module: spec-ast ^anc-struct-spec-ast
+// AST 类型契约——最稳的契约层（语言身份）。SpecAST/14 步骤类型/ActBody 表达式/DocRef + 共享辅助类型。
+// 拆自原 types.ts（按稳定性，见 design/spec-ast.md ^anc-struct-spec-ast）；types.ts 保留为 barrel re-export。
+export {};