@hoplogic/hopjit 0.1.0

package/dist/hoplog.js

@@ -0,0 +1,501 @@
+// @module: hoplog ^anc-obs-hoplog
+import { mkdirSync, appendFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+const LEVEL_PRIORITY = {
+    debug: 0, info: 1, warn: 2,
+};
+// 审计性字段 key 集合——写入时无视日志级别
+const AUDIT_FIELDS = new Set(['tool', 'commit_audit', 'hitl', 'callee_spec_id']);
+// 流控轨迹字段——info 级写入
+const FLOW_FIELDS = new Set(['knowledge', 'doc_refs', 'retry', 'taken', 'condition', 'llm', 'tokens_used']);
+const _metaFieldsCovered = true;
+void _metaFieldsCovered;
+/**
+ * HopLog 执行轨迹日志——唯一信息源是 main.yaml 文件本身。
+ * 每个 record* 方法实时 appendFileSync，无内存镜像（查询已记录内容请读文件）。
+ */
+export class HopLog {
+    level;
+    runDir;
+    filePath;
+    // 已 start 的步骤集合——守卫孤儿字段（步骤未 start 时 done/meta/warn 不写入）
+    startedSteps = new Set();
+    // 延迟 resume marker：resume() 只暂存时间戳，由下一次写入按正确层级落盘（三出口之一：emitResumed
+    // 续未完成 step / recordStepStart 内联接新 step / flushTopLevelResume 顶层收尾）。
+    // 避免旧实现把裸注释砸进未闭合 prompt 块标量中间破坏 YAML。见 design ^anc-obs-hoplog-resume。
+    pendingResume = null;
+    // loop 多轮：hoplog 展示态轮次计数。同一 loop 子步 step-id 每轮重复（4.1 每轮同名），
+    // 嵌套后成同层重复 key（YAML 非法）——检测"已 done 过的 step 又 start"=新轮次、+1，
+    // hoplog key 写 `4.1#2`（#iter 仅展示 key，不碰 step-id 铁钉、depth 仍按点号算）。
+    // 与 startedSteps 同性质的展示态计数，不违反"无内存镜像"。见 design ^anc-obs-nested-tree。
+    iterCounts = new Map();
+    // 已 done 的 step（判 loop 新轮：已 done 又 start = 进入下一轮）。
+    doneSteps = new Set();
+    // 已写过 resumed_at 的 step——同一 step 只落一个 resumed_at（多次 resume 续同一未完成 step 会各触发
+    // emitResumed，重复写语义冗余）。首次恢复的 marker 足以标记"该 step 曾被恢复"，后续恢复不再重复写。
+    // resume 重建时从文件扫已有 resumed_at 行填入（跨进程去重）。顶层事件（close/replan）用空串 '' 记。
+    resumedWritten = new Set();
+    constructor(options) {
+        this.level = options.level ?? 'info';
+        const runId = generateRunId();
+        this.runDir = join(options.logDir, `${options.specId}-${runId}`); // @a: anc-obs-file-layout
+        mkdirSync(this.runDir, { recursive: true });
+        this.filePath = join(this.runDir, 'main.yaml');
+        // Header — written immediately。spec_id（用户在 spec 写的 Id:）/trace_id（调用方传入）走 toYaml 转义
+        // ——外部来源值含空格/冒号/特殊字符会破 YAML header；run_id（内部生成固定格式）/level（枚举）无需。
+        this.append(`spec_id: ${toYaml(options.specId)}\n`);
+        this.append(`run_id: ${runId}\n`);
+        this.append(`trace_id: ${toYaml(options.traceId ?? runId)}\n`); // @a: anc-obs-trace-inherit
+        this.append(`level: ${this.level}\n`);
+        this.append(`started_at: ${toYaml(timestamp())}\n`);
+        // title/goal 在 spec: 下的 2 空格层级；多行值走 block scalar，内容须比键更深缩进（indent=1 → 内容 4 空格 > 键 2 空格）。
+        // 不传 indent 时多行 goal 的 block scalar 内容仅 2 空格 = 键缩进 → YAML 非法（block 判空 + 内容行无冒号）。
+        this.append(`spec:\n  title: ${toYaml(options.title, 1)}\n  goal: ${toYaml(options.goal, 1)}\n`);
+        const filteredInputs = this.filterValues(options.inputs);
+        if (filteredInputs && Object.keys(filteredInputs).length > 0) {
+            this.append(`inputs:\n${toYaml(filteredInputs, 1)}\n`);
+        }
+        this.append(`execution:\n`);
+    }
+    static resume(runDir, level) {
+        const log = Object.create(HopLog.prototype);
+        log.runDir = runDir;
+        log.filePath = join(runDir, 'main.yaml');
+        // 从已有 main.yaml 头部读取 level（跨进程恢复时保持原 run 的日志级别）
+        if (!level && existsSync(log.filePath)) {
+            const head = readFileSync(log.filePath, 'utf-8').slice(0, 500);
+            const m = head.match(/^level:\s*(debug|info|warn)/m);
+            if (m)
+                level = m[1];
+        }
+        log.level = level ?? 'info';
+        // 从已有 main.yaml 重建 startedSteps——跨进程恢复时守卫不能丢已记录的步骤，
+        // 否则下一进程的 recordStepDone 会误判为孤儿。步骤记录格式：`  "<id>":` 或 `  <id>:`（二级缩进）
+        log.startedSteps = new Set();
+        log.iterCounts = new Map();
+        log.doneSteps = new Set();
+        log.resumedWritten = new Set();
+        if (existsSync(log.filePath)) {
+            const text = readFileSync(log.filePath, 'utf-8');
+            // 嵌套树后 step key 缩进为任意偶数（2/4/6…）、值为 step-id 形态（可带 #iter 后缀）、冒号后换行（块头无 inline 值）。
+            // id 形态约束（`[\d.]+` 可带 `#\d+`）+ 冒号后换行，避免误匹配 llm/inputs/outputs 等 body 字段键。
+            const re = /^ +(?:"([\d.]+(?:#\d+)?)"|([\d.]+(?:#\d+)?)):\s*$/gm;
+            let m;
+            while ((m = re.exec(text)) !== null) {
+                const key = m[1] ?? m[2];
+                const hash = key.indexOf('#');
+                if (hash >= 0) {
+                    // loop 多轮 key `4.1#2`：还原 step-id + 重建轮次计数（取最大 N）
+                    const base = key.slice(0, hash);
+                    const iter = Number(key.slice(hash + 1));
+                    log.startedSteps.add(base);
+                    if (Number.isFinite(iter))
+                        log.iterCounts.set(base, Math.max(log.iterCounts.get(base) ?? 1, iter));
+                }
+                else {
+                    log.startedSteps.add(key);
+                }
+            }
+            // 重建 doneSteps：loop 新轮的判据是"已 **done** 又 start"，**不是**"已 started 又 start"——
+            // resume 续一个**未完成**的 step（如 subtask 内某 act 中断、resume 重发其 step_ready 再走
+            // recordStepStart）不是新轮，误当新轮会生成错误的 #iter key（实测 v3：4.2 中断 resume → "4#2"/"4.2#2"）。
+            // 故 doneSteps 只收文件中**真正终态**的 step：栈式单遍——step key 入栈，遇 status: completed/failed
+            // 标记其归属 step（缩进比 status 浅 2 的最近 step key）为 done。
+            const lines = text.split('\n');
+            const stepStack = [];
+            for (const line of lines) {
+                if (line.trim() === '')
+                    continue;
+                const indent = line.length - line.trimStart().length;
+                const keyMatch = line.match(/^ +(?:"([\d.]+(?:#\d+)?)"|([\d.]+(?:#\d+)?)):\s*$/);
+                if (keyMatch) {
+                    const key = keyMatch[1] ?? keyMatch[2];
+                    const base = key.indexOf('#') >= 0 ? key.slice(0, key.indexOf('#')) : key;
+                    while (stepStack.length && stepStack[stepStack.length - 1].indent >= indent)
+                        stepStack.pop();
+                    stepStack.push({ id: base, indent });
+                    continue;
+                }
+                const sm = line.match(/^( +)status: (completed|failed)\s*$/);
+                if (sm) {
+                    const stInd = sm[1].length;
+                    // status 归属：缩进恰为 stInd-2 的最近 step（栈顶应是它）
+                    for (let i = stepStack.length - 1; i >= 0; i--) {
+                        if (stepStack[i].indent === stInd - 2) {
+                            log.doneSteps.add(stepStack[i].id);
+                            break;
+                        }
+                    }
+                }
+                // resumed_at 归属：填 resumedWritten 去重（跨进程——本进程 resume 续同 step 不再重写第二个 resumed_at）。
+                const rm = line.match(/^( *)resumed_at:/);
+                if (rm) {
+                    const rInd = rm[1].length;
+                    if (rInd === 0) {
+                        log.resumedWritten.add('');
+                    } // 顶层 resumed_at（close/replan）
+                    else
+                        for (let i = stepStack.length - 1; i >= 0; i--) {
+                            if (stepStack[i].indent === rInd - 2) {
+                                log.resumedWritten.add(stepStack[i].id);
+                                break;
+                            }
+                        }
+                }
+            }
+            // startedSteps 已含文件中所有写过骨架的 step（含未 done 的）——recordStepStart 幂等判据直接用它：
+            // startedSteps 有且未 done = resume 续/ recover 重发，跳过骨架只补 resumed_at（见 recordStepStart）。
+        }
+        mkdirSync(runDir, { recursive: true });
+        // resume marker 延迟写入：不在此 append（可能砸进上一步未闭合的 prompt 块标量中间破坏
+        // YAML），仅暂存时间戳，由下一次写入按正确层级落成结构化字段 resumed_at（三出口见 pendingResume 声明处）。
+        // 见 design ^anc-obs-hoplog-resume。
+        log.pendingResume = timestamp();
+        return log;
+    }
+    // resumed_at 的**顶层出口**（close/replan 场景）：resume 后未再写任何 step 就直接终态/重规划时，
+    // 把暂存的 marker 落成顶层字段（0 缩进，stepKey 用空串 '' 去重）。另两个出口按落点分工：
+    // ① emitResumed(stepId)——resume 续**未完成** step（recordStepStart 幂等分支）；
+    // ② recordStepStart 内联——resume 后首个**新** step，作该 step 块字段。
+    // 三出口对应三种真实落点语义，不合一（旧设计企图用单个 flushResume 从 stepId 反推缩进覆盖所有场景，
+    // 嵌套 resume/多次 flush 时归属错乱、resumed_at 落错层截断 YAML，实测崩——故按落点拆分）。
+    // pendingResume 非空且顶层未写过才落，写后清空——天然幂等，多次调用仅首次落、余次 no-op。
+    // 见 design ^anc-obs-hoplog-resume / ^anc-obs-nested-tree。// @a: anc-obs-hoplog-resume
+    flushTopLevelResume() {
+        if (this.pendingResume === null)
+            return;
+        // 顶层 resumed_at 已写过（stepKey=''）→ 不重复写；仍清 pendingResume 避免它漏到别处。
+        if (this.resumedWritten.has('')) {
+            this.pendingResume = null;
+            return;
+        }
+        this.append(`resumed_at: ${toYaml(this.pendingResume)}\n`);
+        this.resumedWritten.add('');
+        this.pendingResume = null;
+    }
+    // step-id 点号深度 = 树层级（顶层=1）。缩进纯函数：key 前导 2d、body 字段 2d+2、子块值基准 d+2
+    // （toYaml 的 indentLevel 单位是 2 空格，d+2 对应 2d+4 空格）。#iter 后缀不影响深度。见 design ^anc-obs-nested-tree。
+    stepDepth(stepId) {
+        const base = stepId.split('#')[0];
+        return base.split('.').length;
+    }
+    ind(spaces) { return ' '.repeat(spaces); }
+    // hoplog 展示 key：loop 多轮子步加 `#iter` 区分（iterCounts 记当前轮次）。首轮及非重复 step 无后缀。
+    hoplogKey(stepId) {
+        const iter = this.iterCounts.get(stepId);
+        return iter && iter > 1 ? `${stepId}#${iter}` : stepId;
+    }
+    // YAMLL 块头：写 `<2d>"<step-id>":`（缩进 = step 深度，供折叠）。每个 record 事件自成一块。
+    // 见 design/spec-observability.md ^anc-obs-nested-tree（v3 YAMLL）。// @a: anc-obs-nested-tree
+    blockHeader(stepId) {
+        this.append(`${this.ind(2 * this.stepDepth(stepId))}${toYaml(this.hoplogKey(stepId))}:\n`);
+    }
+    recordStepStart(stepId, type, summary, inputs, promptText) {
+        // loop 新轮：已 done 过的 step 又 start = 下一轮迭代 → 轮次 +1（hoplog key 加 #iter）。
+        if (this.doneSteps.has(stepId)) {
+            this.iterCounts.set(stepId, (this.iterCounts.get(stepId) ?? 1) + 1);
+            this.doneSteps.delete(stepId);
+        }
+        // resume 续未完成 / recover 重发（可能多次）：start 块已写过 → 不重写，只写一个 resumed 块（去重）。
+        // YAMLL 下这不是"避免重复 key"（块间本就允许重复 step-id），而是语义去重：一次恢复标一次。
+        if (this.startedSteps.has(stepId)) {
+            this.emitResumed(stepId);
+            return;
+        }
+        this.startedSteps.add(stepId);
+        const d = this.stepDepth(stepId);
+        const f = 2 * d + 2;
+        this.blockHeader(stepId); // 独立块：块头 `<2d>id:`
+        this.append(`${this.ind(f)}type: ${type}\n`);
+        this.append(`${this.ind(f)}summary: ${toYaml(summary)}\n`);
+        this.append(`${this.ind(f)}at: ${toYaml(timestamp())}\n`);
+        // resume 后首个新 step：进程在此恢复——resumed_at 作本块字段落盘（本块的 f，天然对齐），一次即清。
+        if (this.pendingResume !== null && !this.resumedWritten.has(stepId)) {
+            this.append(`${this.ind(f)}resumed_at: ${toYaml(this.pendingResume)}\n`);
+            this.resumedWritten.add(stepId);
+            this.pendingResume = null;
+        }
+        const filtered = this.filterValues(inputs);
+        if (filtered && Object.keys(filtered).length > 0) {
+            this.append(`${this.ind(f)}inputs:\n${toYaml(filtered, d + 2)}\n`);
+        }
+        // debug 级记录完整 prompt（给 LLM 的完整输入——6 层格式化文本）
+        if (promptText && this.level === 'debug') {
+            this.append(`${this.ind(f)}llm:\n`);
+            this.append(`${this.ind(f + 2)}prompt: ${toYaml(promptText, d + 2)}\n`);
+        }
+    }
+    // resume marker：自成一块 `<2d>id:` + `<2d+2>resumed_at:`。resume 时就知道续的是哪个 step
+    // （engine 从 state.json running 传入），块头即用它，缩进自算——不再延迟到"下一次调用"。
+    // 同 step 已写过 resumed 块则跳过（多次 resume 只标一次）。// @a: anc-obs-hoplog-resume
+    emitResumed(stepId) {
+        if (this.pendingResume === null)
+            return;
+        if (this.resumedWritten.has(stepId)) {
+            this.pendingResume = null;
+            return;
+        }
+        this.blockHeader(stepId);
+        this.append(`${this.ind(2 * this.stepDepth(stepId) + 2)}resumed_at: ${toYaml(this.pendingResume)}\n`);
+        this.resumedWritten.add(stepId);
+        this.pendingResume = null;
+    }
+    // 孤儿写入 = Engine 调用序列 bug 的信号——写入错误标记暴露问题，但不抛异常打断执行
+    guardOrphan(stepId, method) {
+        if (this.startedSteps.has(stepId))
+            return true;
+        this.append(`# ERROR: orphan ${method}("${stepId}") — step never started (caller sequence bug)\n`);
+        return false;
+    }
+    recordStepDone(stepId, outputs) {
+        if (!this.guardOrphan(stepId, 'recordStepDone'))
+            return;
+        const d = this.stepDepth(stepId);
+        const f = 2 * d + 2;
+        this.blockHeader(stepId); // YAMLL：done 自成一块（块头 `<2d>id:`，与 start 块同 step-id、独立）
+        const filtered = this.filterValues(outputs);
+        if (filtered && Object.keys(filtered).length > 0) {
+            if (this.level === 'debug') {
+                this.append(`${this.ind(f)}response:\n${toYaml(filtered, d + 2)}\n`);
+            }
+            this.append(`${this.ind(f)}outputs:\n${toYaml(filtered, d + 2)}\n`);
+        }
+        this.append(`${this.ind(f)}status: completed\n`);
+        this.append(`${this.ind(f)}completed_at: ${toYaml(timestamp())}\n`);
+        this.doneSteps.add(stepId); // 标记已 done（loop 再次 start 同 id → 新轮次）
+    }
+    recordStepFailed(stepId, reason, failKind = 'error') {
+        if (!this.guardOrphan(stepId, 'recordStepFailed'))
+            return;
+        const d = this.stepDepth(stepId);
+        const f = 2 * d + 2;
+        this.blockHeader(stepId); // YAMLL：failed 自成一块
+        this.append(`${this.ind(f)}status: failed\n`);
+        this.append(`${this.ind(f)}failed_at: ${toYaml(timestamp())}\n`);
+        this.append(`${this.ind(f)}fail_kind: ${toYaml(failKind)}\n`);
+        this.append(`${this.ind(f)}reason: ${toYaml(sanitize(reason))}\n`);
+        this.doneSteps.add(stepId); // 标记已终态（loop 再次 start 同 id → 新轮次）
+    }
+    /**
+     * 记录步骤特有字段。审计性字段（tool/commit_audit/hitl/callee_spec_id）
+     * 无视日志级别始终写入；流控轨迹字段（knowledge/retry/taken/condition/llm/tokens_used）info 级写入。
+     */
+    recordStepMeta(stepId, meta) {
+        if (!this.guardOrphan(stepId, 'recordStepMeta'))
+            return;
+        const d = this.stepDepth(stepId);
+        const f = 2 * d + 2;
+        // 先算出实际要写的字段（按级别过滤后），非空才写块头——避免空 meta 留一个孤块头。
+        const entries = Object.entries(meta).filter(([key, value]) => {
+            if (value === undefined)
+                return false;
+            const isAudit = AUDIT_FIELDS.has(key);
+            const isFlow = FLOW_FIELDS.has(key);
+            return isAudit || !isFlow || this.shouldRecord('info');
+        });
+        if (entries.length === 0)
+            return;
+        this.blockHeader(stepId); // YAMLL：meta 自成一块
+        for (const [key, value] of entries) {
+            const valStr = toYaml(value, d + 2);
+            if (typeof value === 'object' && value !== null) {
+                this.append(`${this.ind(f)}${key}:\n${valStr}\n`);
+            }
+            else {
+                this.append(`${this.ind(f)}${key}: ${valStr}\n`);
+            }
+        }
+    }
+    // stepId 非空 → step 级告警（warn 作该 step 块字段，过 guardOrphan 守卫）。
+    // stepId 为空 '' → 文档级告警（如"Output 声明了却从未赋值"，不归属任何 step）：
+    //   落顶层 `warn:` 独立块，不过 guardOrphan、不写 blockHeader（空 id 无 step 归属，
+    //   旧实现误让它走 guardOrphan 被当孤儿写成 `# ERROR: orphan` 而正文丢失）。
+    recordWarn(stepId, message) {
+        if (!this.shouldRecord('warn'))
+            return;
+        if (stepId === '') { // 文档级：顶层独立块
+            this.append(`warn: ${toYaml(sanitize(message))}\n`);
+            return;
+        }
+        if (!this.guardOrphan(stepId, 'recordWarn'))
+            return;
+        const f = 2 * this.stepDepth(stepId) + 2;
+        this.blockHeader(stepId); // YAMLL：warn 自成一块
+        this.append(`${this.ind(f)}warn: ${toYaml(sanitize(message))}\n`);
+    }
+    // parallel fan-out/join 审计:作为 parallel 步骤（parallelStepId）的 body 子字段写入，缩进按步骤深度
+    // （fanout:/join: 键在 2d+2，与 type/summary 并列；子内容更深）。始终写入（无视级别）。
+    // ⚠️ 曾误实现为顶格 0 缩进——在 execution 深缩进流中途 append 顶格键会提前闭合 execution mapping，
+    // 令其后步骤错位、YAML 不可解析。改为随步骤深度缩进后自然嵌在该 parallel 子树内。
+    // 见 design/spec-observability.md ^anc-obs-nested-tree。// @a: anc-exec-parallel-batch, anc-exec-parallel-join-merge, anc-obs-nested-tree
+    recordParallelFanout(parallelStepId, childIds, maxConcurrent) {
+        const f = 2 * this.stepDepth(parallelStepId) + 2;
+        this.blockHeader(parallelStepId); // YAMLL：fanout 自成一块（块头 = parallel step-id）
+        this.append(`${this.ind(f)}fanout:\n`);
+        // 字段序：max_concurrent（窗口容量，先看到）→ children（全集）→ started_at（开始持续派发的锚点）。
+        // fanout 不做二元起止——parallel 阶段"结束"由 join 的 ended_at 承载。见 design ^anc-obs-nested-tree。
+        this.append(`${this.ind(f + 2)}max_concurrent: ${maxConcurrent}\n`);
+        this.append(`${this.ind(f + 2)}children:\n${childIds.map(id => `${this.ind(f + 4)}- ${toYaml(id)}`).join('\n')}\n`);
+        this.append(`${this.ind(f + 2)}started_at: ${toYaml(timestamp())}\n`);
+    }
+    // 每派发一个 child 一次（fanout-plan/fanout-next 顾问进程在 toLaunch 循环内调）：流式 append 一条 dispatch 块。
+    // dispatched_at = 引擎决定派发的时刻（"引擎动作时刻"，如实反映滑动窗口的持续派发，非 fanout 一瞬塌缩）；
+    // log = 该 child 子日志目录（确定性算出）。顾问进程 load 后 HopLog.resume 重建父句柄故能 append。
+    // 见 design/spec-observability.md ^anc-obs-parallel-dispatch。// @a: anc-obs-parallel-dispatch
+    recordParallelDispatch(parallelStepId, childId, logDir) {
+        const f = 2 * this.stepDepth(parallelStepId) + 2;
+        this.blockHeader(parallelStepId); // YAMLL：dispatch 自成一块（块头 = parallel step-id，块间重复合法）
+        this.append(`${this.ind(f)}dispatch:\n`);
+        this.append(`${this.ind(f + 2)}child: ${toYaml(childId)}\n`);
+        this.append(`${this.ind(f + 2)}dispatched_at: ${toYaml(timestamp())}\n`);
+        this.append(`${this.ind(f + 2)}log: ${toYaml(logDir)}\n`);
+    }
+    // join 完成时记录。childResults 每项带 failed + 可选 log（子实例日志路径，join 时逐个读子实例顺手带出）。
+    // startedAt = engine 进入 join 的时刻（外部捕获传入）；ended_at = 本方法 merge 完的 timestamp()。
+    // 见 design/spec-observability.md ^anc-obs-nested-tree。// @a: anc-obs-parallel-dispatch
+    recordParallelJoin(parallelStepId, childResults, startedAt) {
+        const f = 2 * this.stepDepth(parallelStepId) + 2;
+        this.blockHeader(parallelStepId); // YAMLL：join 自成一块
+        this.append(`${this.ind(f)}join:\n`);
+        this.append(`${this.ind(f + 2)}children:\n`);
+        for (const [id, res] of Object.entries(childResults)) {
+            const status = res.failed ? 'failed' : 'completed';
+            // child 值写成 inline mapping：status + 可选 log（子日志定位线索）
+            const logPart = res.log ? `, log: ${toYaml(res.log)}` : '';
+            this.append(`${this.ind(f + 4)}${toYaml(id)}: {status: ${status}${logPart}}\n`);
+        }
+        if (startedAt)
+            this.append(`${this.ind(f + 2)}started_at: ${toYaml(startedAt)}\n`);
+        this.append(`${this.ind(f + 2)}ended_at: ${toYaml(timestamp())}\n`);
+    }
+    // replan 提报记录:降级阶梯第3/4档运行时生成的审计事件,供离线沉淀为预声明备用链路。
+    // 顶层事件、无视日志级别始终记录、不受 guardOrphan(replan 是 subtask 级跨进程事件,
+    // 不是叶子步 meta——subtask 容器本就不 recordStepStart,且跨进程 startedSteps 重置)。
+    // 见 design/spec-observability.md ^anc-obs-replan-audit。// @a: anc-obs-replan-audit
+    recordReplanAudit(audit) {
+        this.flushTopLevelResume(); // 顶层事件：resumed_at 落顶层（0 缩进）
+        this.append(`replan_audit:\n${toYaml(audit, 1)}\n`);
+    }
+    close(status) {
+        this.flushTopLevelResume(); // resume 后直接终态也不丢 marker——close 前落顶层 resumed_at（0 缩进）
+        this.append(`status: ${status}\n`);
+        this.append(`ended_at: ${toYaml(timestamp())}\n`);
+    }
+    getRunDir() {
+        return this.runDir;
+    }
+    getFilePath() {
+        return this.filePath;
+    }
+    flush() {
+        // All writes are immediate via appendFileSync — flush is a no-op
+    }
+    append(text) {
+        appendFileSync(this.filePath, text);
+    }
+    shouldRecord(level) {
+        return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.level];
+    }
+    filterValues(values) {
+        if (!values)
+            return undefined;
+        // warn: 不记录变量值（只看步骤骨架和警告）
+        if (this.level === 'warn')
+            return undefined;
+        // debug: 完整记录（仅脱敏 API key，不截断——debug 的核心价值是完整还原 LLM 输入）
+        // info: 脱敏 + 截断（摘要足够，控制文件大小）
+        return this.level === 'debug' ? sanitizeRecordFull(values) : sanitizeRecordTruncated(values);
+    }
+}
+/** 日志脱敏 helper：抹除 API key 类敏感 pattern 并截断超长文本，保证密钥不落 HopLog。见 [[spec-observability#^anc-obs-log-levels]] */
+export function sanitize(text) {
+    let s = text.replace(/\b(sk-|key-)[a-zA-Z0-9]{20,}/g, '$1***');
+    if (s.length > 200)
+        s = s.substring(0, 200) + ' [TRUNCATED]';
+    return s;
+}
+function sanitizeFull(text) {
+    return text.replace(/\b(sk-|key-)[a-zA-Z0-9]{20,}/g, '$1***');
+}
+/** 对 record 的字符串值逐个应用 fn（非字符串原样）。full/truncated 两个 sanitize 变体共用骨架。 */
+function mapStringValues(rec, fn) {
+    const result = {};
+    for (const [k, v] of Object.entries(rec)) {
+        result[k] = typeof v === 'string' ? fn(v) : v;
+    }
+    return result;
+}
+function sanitizeRecordFull(rec) {
+    return mapStringValues(rec, sanitizeFull);
+}
+function sanitizeRecordTruncated(rec) {
+    return mapStringValues(rec, sanitize);
+}
+function generateRunId() {
+    const now = new Date();
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+    const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    const hex = randomBytes(2).toString('hex');
+    return `${date}T${time}-${hex}`;
+}
+export function timestamp() {
+    const now = new Date();
+    const off = -now.getTimezoneOffset();
+    const sign = off >= 0 ? '+' : '-';
+    const h = String(Math.floor(Math.abs(off) / 60)).padStart(2, '0');
+    const m = String(Math.abs(off) % 60).padStart(2, '0');
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    // 毫秒级精度（.mmm 三位零填充）：亚秒事件可分辨——同批 dispatch 落同一秒、join 起止单进程内间隔<1s。
+    // 见 design ^anc-obs-timestamp / ^anc-obs-parallel-dispatch。
+    const ms = String(now.getMilliseconds()).padStart(3, '0');
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${ms}${sign}${h}:${m}`;
+}
+/** 把日志条目对象序列化为 block-style YAML 文本，供 record* 方法实时 appendFileSync 写入 main.yaml。见 [[spec-observability#^anc-obs-hoplog-flush]] */
+export function toYaml(obj, indent = 0) {
+    const prefix = '  '.repeat(indent);
+    if (obj === null || obj === undefined)
+        return 'null';
+    if (typeof obj === 'boolean')
+        return String(obj);
+    if (typeof obj === 'number')
+        return String(obj);
+    if (typeof obj === 'string') {
+        if (obj.includes('\n')) {
+            const lines = obj.split('\n');
+            return '|\n' + lines.map(l => prefix + '  ' + l).join('\n');
+        }
+        if (obj === '' || /[:{}\[\],&*?|>!'"%@`#]/.test(obj) || /^\s/.test(obj) || /\s$/.test(obj)
+            || /^-?\d+(\.\d+)?$/.test(obj) || obj === 'true' || obj === 'false' || obj === 'null') {
+            return JSON.stringify(obj);
+        }
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        if (obj.length === 0)
+            return '[]';
+        return obj.map(item => {
+            const val = toYaml(item, indent + 1);
+            if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+                return prefix + '- ' + val.trimStart();
+            }
+            return prefix + '- ' + val;
+        }).join('\n');
+    }
+    if (typeof obj === 'object') {
+        const entries = Object.entries(obj);
+        if (entries.length === 0)
+            return '{}';
+        return entries.map(([key, value]) => {
+            if (value === undefined)
+                return null;
+            const valStr = toYaml(value, indent + 1);
+            if (typeof value === 'object' && value !== null && (Array.isArray(value) ? value.length > 0 : Object.keys(value).length > 0)) {
+                return prefix + key + ':\n' + valStr;
+            }
+            return prefix + key + ': ' + valStr;
+        }).filter(Boolean).join('\n');
+    }
+    return String(obj);
+}

package/dist/parser.d.ts

@@ -0,0 +1,7 @@
+import type { SpecAST } from './ast-types.js';
+import type { ParseError } from './errors.js';
+export declare function parseSpec(markdown: string): {
+    ast: SpecAST;
+    errors: ParseError[];
+};
+export declare function serializeSpec(ast: SpecAST): string;