@dommaker/harness 1.3.0 → 1.5.0

package/src/utils/__tests__/jsonl-skip-disposition.test.ts

@@ -0,0 +1,175 @@
+/**
+ * skip 读点的「计数去向」守护（harness#100）
+ *
+ * 契约原则（正本见 `src/monitoring/CONTEXT.md` 与 `src/cli/commands/CONTEXT.md`「约定」段）：
+ * **凡以 `skip` 策略读 JSONL，坏行计数必须到达该消费面的用户可见输出，或在该调用点
+ * 显式记名豁免并写明理由。** 静默吞掉「数据不全」不是一种可选项。
+ *
+ * 本文件把这句原则变成机器可检面，三道闸：
+ * 1. 每个 `readJsonl` 调用点都判得出坏行策略——判不出（策略走变量、参数形状超出识别窗口）
+ *    即形状逃逸，失败并交人裁决，不给静默漏判留口子
+ * 2. skip 读点集合冻结（`EXPECTED_SKIP_READ_SITES`）：新增读点即失败；
+ *    读点消失却不删条目也失败（豁免不烂成化石，与 #95 同一手法）
+ * 3. 每个读点上方 6 行内必须有 `计数去向：` 声明（透传到哪儿 / 为何豁免），且声明与本读点
+ *    之间不得夹着另一个读点——邻居的声明不顶替，缺失即失败
+ *
+ * `throw` 策略不产计数，故不要求去向声明；但新增 throw 调用点必须在下文那条断言里逐个点名
+ * 裁决——否则「改成 throw 就免掉告知」成了原则的绕行通道。`src/utils/jsonl.ts` 本身是策略
+ * 定义处，排除。
+ * `readJsonlEnds`（首尾读取）同样是 skip 读点，纳入同一识别正则——否则它成为本契约的
+ * 绕行通道（harness#114）。
+ * `countJsonlLines` 的纯行数站点（如 `check` 的提示计数）不 parse、不产坏行计数，也不在本表内
+ * ——它把损坏行算进条数的问题属口径变更，#100 明确不做。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const SRC_ROOT = path.join(__dirname, '..', '..');
+
+/** 读点上方声明计数去向的标记（写在坏行策略注释里，与调用点同一处） */
+const DISPOSITION_MARKER = /计数去向[:：]/;
+
+/** 声明与读点的最大距离（行数）：只认紧贴读点的那段注释 */
+const DECLARATION_LOOKBACK_LINES = 6;
+
+/** 判定策略时从读点行向下拼几行（覆盖参数换行的调用形状） */
+const POLICY_WINDOW_LINES = 6;
+
+/**
+ * 冻结的 skip 读点集合：文件（仓库相对路径）→ 读点数。
+ * 每个读点的去向理由在调用点注释里，此表只钉「有哪些点、各几处」。
+ */
+const EXPECTED_SKIP_READ_SITES: Record<string, number> = {
+  'src/cli/commands/status.ts': 1,
+  'src/cli/session-mining/transcript.ts': 1,
+  'src/context/session-manager.ts': 2,
+  'src/core/constraints/context-builder.ts': 2,
+  'src/core/constraints/usage-report.ts': 1,
+  'src/failure/recorder.ts': 1,
+  'src/knowledge/reference-tracker.ts': 1,
+  'src/monitoring/context-tracker.ts': 1,
+  'src/monitoring/traces.ts': 2,
+};
+
+function listTsFiles(dir: string): string[] {
+  const found: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__') continue;
+      found.push(...listTsFiles(full));
+    } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+      found.push(full);
+    }
+  }
+  return found.sort();
+}
+
+/** 仓库相对路径（跨机器稳定） */
+function repoPath(abs: string): string {
+  return path.relative(path.join(SRC_ROOT, '..'), abs).split(path.sep).join('/');
+}
+
+interface CallSite {
+  /** 1-based 行号 */
+  line: number;
+  snippet: string;
+  /** 策略判不出 = unknown（形状超出本守卫的识别能力，必须由人裁决而非静默漏判） */
+  policy: 'skip' | 'throw' | 'unknown';
+}
+
+/**
+ * 找出一个文件里所有 readJsonl 调用点并判出坏行策略。
+ * 调用参数可能换行，故从 `readJsonl` 起拼若干行再判：先遇到 `'skip'` 记 skip、
+ * 先遇到 `'throw'` 记 throw，两者都不出现记 unknown。
+ */
+function callSites(file: string): CallSite[] {
+  const raw = fs.readFileSync(file, 'utf-8').split('\n');
+  const sites: CallSite[] = [];
+
+  for (let i = 0; i < raw.length; i++) {
+    const trimmed = raw[i].trim();
+    if (!/readJsonl(?:Ends)?\s*[<(]/.test(trimmed)) continue;
+    // 注释行里的示例不是站点（策略定义处 src/utils/jsonl.ts 已整体排除）
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+
+    const joined = raw.slice(i, i + POLICY_WINDOW_LINES).join(' ');
+    const skipIdx = joined.indexOf("'skip'");
+    const throwIdx = joined.indexOf("'throw'");
+    const policy: CallSite['policy'] =
+      skipIdx === -1 && throwIdx === -1
+        ? 'unknown'
+        : throwIdx !== -1 && (skipIdx === -1 || throwIdx < skipIdx)
+          ? 'throw'
+          : 'skip';
+
+    sites.push({ line: i + 1, snippet: trimmed, policy });
+  }
+  return sites;
+}
+
+describe('skip 读点的计数去向契约（harness#100）', () => {
+  const sourceFiles = listTsFiles(SRC_ROOT).filter(
+    f => repoPath(f) !== 'src/utils/jsonl.ts'
+  );
+  const sitesByFile = new Map<string, CallSite[]>();
+  for (const file of sourceFiles) {
+    const sites = callSites(file);
+    if (sites.length > 0) sitesByFile.set(repoPath(file), sites);
+  }
+
+  it('每个 readJsonl 调用点都判得出策略（判不出即形状逃逸，需人来补识别规则）', () => {
+    const unknown = [...sitesByFile.entries()].flatMap(([rel, sites]) =>
+      sites.filter(s => s.policy === 'unknown').map(s => `${rel}:${s.line}  ${s.snippet}`)
+    );
+
+    expect(unknown).toEqual([]);
+  });
+
+  it('skip 读点集合 = 冻结表（新增即失败；站点消失却不删条目也失败）', () => {
+    const expected = Object.entries(EXPECTED_SKIP_READ_SITES)
+      .filter(([, count]) => count > 0)
+      .sort(([a], [b]) => a.localeCompare(b));
+    const observed = [...sitesByFile.entries()]
+      .map(([rel, sites]) => [rel, sites.filter(s => s.policy === 'skip').length] as [string, number])
+      .filter(([, count]) => count > 0)
+      .sort(([a], [b]) => a.localeCompare(b));
+
+    expect(observed).toEqual(expected);
+  });
+
+  it('每个 skip 读点都记名声明计数去向（透传目标或豁免理由）', () => {
+    const undeclared: string[] = [];
+
+    for (const [rel, sites] of sitesByFile) {
+      const raw = fs.readFileSync(path.join(SRC_ROOT, '..', rel), 'utf-8').split('\n');
+      for (const site of sites.filter(s => s.policy === 'skip')) {
+        const windowStart = Math.max(0, site.line - 1 - DECLARATION_LOOKBACK_LINES);
+        // 邻居读点的声明不得顶替：声明之后到本读点之间不能再有其它 readJsonl 调用点
+        const prevSiteLine = sites
+          .filter(s => s.line < site.line)
+          .map(s => s.line)
+          .reduce((max, line) => Math.max(max, line), 0);
+        const searchFrom = Math.max(windowStart, prevSiteLine);
+        const above = raw.slice(searchFrom, site.line - 1).join('\n');
+
+        if (!DISPOSITION_MARKER.test(above)) {
+          undeclared.push(`${rel}:${site.line}  ${site.snippet}`);
+        }
+      }
+    }
+
+    expect(undeclared).toEqual([]);
+  });
+
+  it('策略为 throw 的调用点不产计数，目前为零（出现即需逐个裁决）', () => {
+    const throwSites = [...sitesByFile.entries()].flatMap(([rel, sites]) =>
+      sites.filter(s => s.policy === 'throw').map(s => `${rel}:${s.line}`)
+    );
+
+    // 'throw' 是 #82 裁决 1 保留的显式选项，但全仓当前无调用点；
+    // 新增时必须在此逐个点名裁决，不允许悄悄多出一条「不需要告知」的策略
+    expect(throwSites).toEqual([]);
+  });
+});

package/src/utils/__tests__/jsonl.test.ts

@@ -0,0 +1,187 @@
+/**
+ * JSONL 读写正本测试（harness#82）
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { readJsonl, countJsonlLines, readJsonlEnds, appendJsonl } from '../jsonl';
+
+interface Row {
+  n: number;
+}
+
+const CORRUPT = '{"n":2,"broken';
+
+describe('readJsonl', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  function write(name: string, lines: string[]): string {
+    const filePath = path.join(dir, name);
+    fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
+    return filePath;
+  }
+
+  it('按文件顺序解析全部合法行', () => {
+    const filePath = write('ok.jsonl', ['{"n":1}', '{"n":2}', '{"n":3}']);
+    const { records, skippedLines } = readJsonl<Row>(filePath, 'skip');
+    expect(records.map(r => r.n)).toEqual([1, 2, 3]);
+    expect(skippedLines).toBe(0);
+  });
+
+  it('缺文件返回空结果，不抛', () => {
+    expect(readJsonl<Row>(path.join(dir, 'missing.jsonl'), 'skip')).toEqual({
+      records: [],
+      skippedLines: 0,
+    });
+  });
+
+  it('空文件与纯空白行返回空结果', () => {
+    const empty = write('empty.jsonl', []);
+    const blank = write('blank.jsonl', ['', '   ', '\t']);
+    expect(readJsonl<Row>(empty, 'skip').records).toEqual([]);
+    expect(readJsonl<Row>(blank, 'skip').records).toEqual([]);
+  });
+
+  it("policy 'skip'：坏行计数、合法行照常返回", () => {
+    const filePath = write('dirty.jsonl', ['{"n":1}', CORRUPT, '', '{"n":3}']);
+    const { records, skippedLines } = readJsonl<Row>(filePath, 'skip');
+    expect(records.map(r => r.n)).toEqual([1, 3]);
+    expect(skippedLines).toBe(1);
+  });
+
+  it("policy 'throw'：坏行上抛", () => {
+    const filePath = write('dirty.jsonl', ['{"n":1}', CORRUPT]);
+    expect(() => readJsonl<Row>(filePath, 'throw')).toThrow(SyntaxError);
+  });
+
+  it('读入口无策略缺省值：不传 policy 编译期即失败（裁决 1，@ts-expect-error 固定）', () => {
+    // @ts-expect-error policy 为显式必填参数，缺省必须在编译期失败
+    const result = readJsonl<Row>(path.join(dir, 'unused.jsonl'));
+    expect(result.records).toEqual([]);
+  });
+
+  it('tail：只解析最后 N 个非空行', () => {
+    const filePath = write('tail.jsonl', ['{"n":1}', '{"n":2}', CORRUPT, '{"n":4}']);
+    const { records, skippedLines } = readJsonl<Row>(filePath, 'skip', { tail: 2 });
+    expect(records.map(r => r.n)).toEqual([4]);
+    expect(skippedLines).toBe(1);
+  });
+
+  it('head：只解析前 N 个非空行', () => {
+    const filePath = write('head.jsonl', ['{"n":1}', CORRUPT, '{"n":3}', '{"n":4}']);
+    const { records, skippedLines } = readJsonl<Row>(filePath, 'skip', { head: 2 });
+    expect(records.map(r => r.n)).toEqual([1]);
+    expect(skippedLines).toBe(1);
+  });
+
+  it('tail/head 超过总行数时取全部', () => {
+    const filePath = write('small.jsonl', ['{"n":1}']);
+    expect(readJsonl<Row>(filePath, 'skip', { tail: 10 }).records).toHaveLength(1);
+    expect(readJsonl<Row>(filePath, 'skip', { head: 10 }).records).toHaveLength(1);
+  });
+});
+
+describe('countJsonlLines', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('计非空行数（含坏行），缺文件为 0', () => {
+    const filePath = path.join(dir, 'c.jsonl');
+    fs.writeFileSync(filePath, ['{"n":1}', CORRUPT, '', '  '].join('\n') + '\n', 'utf-8');
+    expect(countJsonlLines(filePath)).toBe(2);
+    expect(countJsonlLines(path.join(dir, 'missing.jsonl'))).toBe(0);
+  });
+});
+
+describe('readJsonlEnds', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  function write(name: string, lines: string[]): string {
+    const filePath = path.join(dir, name);
+    fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
+    return filePath;
+  }
+
+  it('取首/末条合法记录 + 原始行数（含坏行）', () => {
+    const filePath = write('ends.jsonl', ['{"n":1}', CORRUPT, '{"n":3}']);
+    expect(readJsonlEnds<Row>(filePath, 'skip')).toEqual({
+      totalLines: 3,
+      first: { n: 1 },
+      last: { n: 3 },
+    });
+  });
+
+  it('首/末行坏时跳过坏行取最近的合法记录', () => {
+    const filePath = write('dirty-ends.jsonl', [CORRUPT, '{"n":2}', '{"n":3}', CORRUPT]);
+    const result = readJsonlEnds<Row>(filePath, 'skip');
+    expect(result.first).toEqual({ n: 2 });
+    expect(result.last).toEqual({ n: 3 });
+    expect(result.totalLines).toBe(4);
+  });
+
+  it("policy 'throw'：首端遇坏行上抛", () => {
+    const filePath = write('throw.jsonl', [CORRUPT, '{"n":2}']);
+    expect(() => readJsonlEnds<Row>(filePath, 'throw')).toThrow();
+  });
+
+  it('缺文件 / 全坏行返回无首末记录', () => {
+    expect(readJsonlEnds<Row>(path.join(dir, 'missing.jsonl'), 'skip')).toEqual({ totalLines: 0 });
+
+    const filePath = write('all-bad.jsonl', [CORRUPT, CORRUPT]);
+    expect(readJsonlEnds<Row>(filePath, 'skip')).toEqual({ totalLines: 2 });
+  });
+});
+
+describe('appendJsonl', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('目录不存在时递归创建并追加单行 JSON', () => {
+    const filePath = path.join(dir, 'a', 'b', 'log.jsonl');
+    appendJsonl(filePath, { n: 1 });
+    appendJsonl(filePath, { n: 2 });
+
+    expect(countJsonlLines(filePath)).toBe(2);
+    const lines = fs.readFileSync(filePath, 'utf-8').split('\n');
+    expect(lines[0]).toBe('{"n":1}');
+    expect(lines[1]).toBe('{"n":2}');
+    expect(lines[2]).toBe('');
+  });
+
+  it('与 readJsonl 构成读写闭环', () => {
+    const filePath = path.join(dir, 'roundtrip.jsonl');
+    appendJsonl(filePath, { n: 7 });
+    expect(readJsonl<Row>(filePath, 'skip').records).toEqual([{ n: 7 }]);
+  });
+});

package/src/utils/__tests__/package-version.test.ts

@@ -0,0 +1,97 @@
+/**
+ * getHarnessPackageVersion 正本测试（#102，架构评审 A3）
+ *
+ * 钉住三件事：
+ * 1. 读的是 harness 包自身的 package.json（与真实版本一致）
+ * 2. cwd 兜底已删除：cwd 是装着 harness 的消费者项目时，绝不误读消费者版本
+ * 3. 仓内不再有第二份「harness 自身 package.json」版本读取（防回潮扫描）
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getHarnessPackageVersion } from '../package-version';
+
+const REAL_VERSION = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', '..', '..', 'package.json'), 'utf-8')
+).version as string;
+
+describe('getHarnessPackageVersion', () => {
+  it('返回 harness 包真实版本（与包根 package.json 一致）', () => {
+    expect(getHarnessPackageVersion()).toBe(REAL_VERSION);
+  });
+
+  it('cwd 是消费者项目时仍读 harness 版本，不误读消费者 package.json', () => {
+    const consumerDir = path.join(process.cwd(), 'temp-test-pkg-version-consumer');
+    fs.mkdirSync(consumerDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(consumerDir, 'package.json'),
+      JSON.stringify({ name: 'consumer-app', version: '9.9.9' })
+    );
+    const prevCwd = process.cwd();
+    try {
+      process.chdir(consumerDir);
+      expect(getHarnessPackageVersion()).toBe(REAL_VERSION);
+    } finally {
+      process.chdir(prevCwd);
+      fs.rmSync(consumerDir, { recursive: true, force: true });
+    }
+  });
+
+  it('package.json 读取失败（缺失/损坏）时返回 unknown', () => {
+    jest.isolateModules(() => {
+      jest.doMock('fs', () => ({
+        ...jest.requireActual('fs'),
+        readFileSync: () => { throw new Error('ENOENT'); },
+      }));
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const fresh = require('../package-version') as typeof import('../package-version');
+      expect(fresh.getHarnessPackageVersion()).toBe('unknown');
+      jest.dontMock('fs');
+    });
+  });
+
+  it('package.json 无 version 字段时返回 unknown', () => {
+    jest.isolateModules(() => {
+      jest.doMock('fs', () => ({
+        ...jest.requireActual('fs'),
+        readFileSync: () => JSON.stringify({ name: '@dommaker/harness' }),
+      }));
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const fresh = require('../package-version') as typeof import('../package-version');
+      expect(fresh.getHarnessPackageVersion()).toBe('unknown');
+      jest.dontMock('fs');
+    });
+  });
+});
+
+describe('版本读取正本收口（防回潮扫描）', () => {
+  function collectTsFiles(dir: string): string[] {
+    const out: string[] = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === '__tests__') continue;
+        out.push(...collectTsFiles(full));
+      } else if (entry.name.endsWith('.ts')) {
+        out.push(full);
+      }
+    }
+    return out;
+  }
+
+  it('src/ 内只有 utils/package-version.ts 读取 harness 自身 package.json', () => {
+    const srcRoot = path.join(__dirname, '..', '..');
+    const canonical = path.join(srcRoot, 'utils', 'package-version.ts');
+    // harness 自身清单的三类历史读法：__dirname 相对 / require / cwd 兜底
+    const selfPkgReadRe = /(__dirname[^\n]*package\.json|require\(['"][^'"]*package\.json['"]\)|process\.cwd\(\)[^\n]*package\.json)/;
+    const offenders: string[] = [];
+    for (const file of collectTsFiles(srcRoot)) {
+      if (file === canonical) continue;
+      const hits = fs.readFileSync(file, 'utf-8')
+        .split('\n')
+        .filter(line => selfPkgReadRe.test(line));
+      if (hits.length > 0) offenders.push(`${file}: ${hits.join(' | ')}`);
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/utils/exec.ts

@@ -53,6 +53,21 @@ export function normalizeTriggers<T>(
   return Array.isArray(value) ? value : [value];
 }
 
+/**
+ * 判断约束是否匹配当前操作集合（#105：trigger 匹配语义单一来源）
+ *
+ * 语义 = normalizeTriggers（undefined → [] 不匹配任何操作）+ 交集判定，
+ * 任一 operation 命中任一 trigger 即匹配。checker 与 prompt 渲染共用本函数，
+ * 禁止就地重写。
+ */
+export function matchesTrigger<T>(
+  constraint: { trigger: T | T[] | undefined },
+  operations: T[]
+): boolean {
+  const triggers = normalizeTriggers(constraint.trigger);
+  return operations.some(op => triggers.includes(op));
+}
+
 /**
  * 异步延迟
  */

package/src/utils/file-walk.ts

@@ -50,12 +50,21 @@ export function walkFiles(root: string, options: FileWalkOptions = {}): string[]
   return results;
 }
 
+/**
+ * 目录遍历默认跳过名单：依赖 / 旁测目录 / 构建产物。
+ *
+ * 遍历跳过口径的正本——chain 式判断（sync-docs 的 readdir 循环）与
+ * findTsSourceFiles 的 skipDirs 默认值同源，禁止再各处手抄三段 `===`。
+ * 各调用方自有的更广名单（如 AGENTS.md 目录表跳过 build/out/coverage）不并入。
+ */
+export const DEFAULT_SKIP_DIRS = ['node_modules', '__tests__', 'dist'];
+
 export interface TsSourceWalkOptions {
   /** 是否跳过 barrel 文件 index.ts，默认 false */
   skipIndex?: boolean;
   /** 是否同时收集 .tsx 文件，默认 false（只收集 .ts） */
   includeTsx?: boolean;
-  /** 跳过的目录名，默认 node_modules/__tests__/dist */
+  /** 跳过的目录名，默认 DEFAULT_SKIP_DIRS */
   skipDirs?: string[];
   /** 是否跳过 `.` 开头的条目，默认 false */
   skipHidden?: boolean;
@@ -86,7 +95,7 @@ export function findTsSourceFiles(root: string, options: TsSourceWalkOptions = {
   const {
     skipIndex = false,
     includeTsx = false,
-    skipDirs = ['node_modules', '__tests__', 'dist'],
+    skipDirs = DEFAULT_SKIP_DIRS,
     skipHidden = false,
   } = options;
 

package/src/utils/frontmatter.ts

@@ -0,0 +1,121 @@
+/**
+ * markdown frontmatter 解析/序列化正本（harness#89，架构评审 2026-09-02 候选10）
+ *
+ * `---\n<yaml>\n---\n<body>` 这一种语法此前在 knowledge 域 5 个文件里手写了 7 遍，
+ * 失败语义三派并存（store 静默丢条目 / migration 记 errors / index-generator 走
+ * best-effort / sdd 不要求闭合行完整 / ingest 只 strip 会把正文 `---` 误吞）。
+ * 语法与失败走法在此一处定义，仓内不允许存在第二份副本。
+ *
+ * 语法（唯一解释）：
+ * - 开界：偏移 0 处必须正好是一行 `---`（前面有空白行则不算 frontmatter）
+ * - 闭界：其后第一个**独立成行**的 `---`（`---x`、`----`、缩进 `---` 均不作闭合）
+ * - body：闭合行之后全部内容，紧随的一个空行被吃掉（与 join 的 `---\n\n` 包裹严格对称，
+ *   保证已落盘条目 load→save 字节稳定）
+ * - meta：闭合前的行经 YAML 解析，必须是 mapping
+ * - CRLF 文件不按 frontmatter 处理（与收口前各消费方一致，本 module 不新增解释）
+ *
+ * 三种畸形输入的走法（裁决 2，用例固定在 utils/__tests__/frontmatter.test.ts）：
+ * - 缺 frontmatter（无开界）→ 'absent'
+ * - 空 meta（闭合前只有空白，含零宽块）→ 'absent'——零宽元数据块不承载信息，
+ *   与「没有 frontmatter」同走一支，消费方按无元数据路径处理（store 视为非条目、
+ *   index-generator 走 best-effort），无需上报
+ * - 未闭合（有开无闭 / 闭合行不完整）→ 'malformed' + reason 'unterminated'
+ * - meta 不是合法 YAML mapping（语法错、显式 null、标量或数组）→ 'malformed' + reason 'invalid-yaml'
+ *
+ * 消费方统一口径（裁决 2：不允许两派并存）：'malformed' 两支必须**显式上报**，
+ * 禁止静默丢数据；恢复动作按消费方语义选择并在代码里写明——
+ * 有结构化报告面的写报告（migration → result.errors），
+ * 纯扫描型的打一行 stderr（前缀 `[harness]`，与 failure/recorder.ts 的坏行告警同构）
+ * 后跳过或走 best-effort。'absent' 是合法输入，不上报。
+ *
+ * 序列化（裁决 3：收格式不收字段排序策略）：join 只负责包裹与 YAML dump 参数
+ * （lineWidth 120，与收口前 store/migration 逐字一致）；canonical 字段序是 store 的
+ * 私有策略，留在 store.toFrontmatter。
+ *
+ * 机械核查（期望命中数，均已实测）：
+ *   grep -rnE '/\^---' src --include='*.ts' | grep -v __tests__
+ *     → 期望 0 处：手写开界正则归零
+ *   grep -rn "'---'" src --include='*.ts' | grep -v __tests__
+ *     → 期望 1 处：本文件 DELIMITER
+ *   grep -rn "yaml.load(metaText)\|yaml.dump(meta," src --include='*.ts' | grep -v __tests__
+ *     → 期望 2 处：本文件 split 的 load + join 的 dump
+ * 豁免清单（不属 frontmatter，不改）：markdown 生成物里的 `---` 分隔线与表格分隔行
+ *   （init / sync-docs / report / constraints-report 模板）、doc-freshness 的章节定位正则
+ *   （`\n---` 是章节边界）、config.yml 与 checkpoint/tasks/progress 的 yaml.dump（单 YAML/JSON 文档）。
+ */
+
+import * as yaml from 'js-yaml';
+
+/** frontmatter 界符（整行） */
+const DELIMITER = '---';
+
+/** 与收口前 store/migration 逐字一致的 YAML dump 行宽 */
+const DUMP_LINE_WIDTH = 120;
+
+/** 'malformed' 的两支：消费方必须逐支显式处理（口径见文件头） */
+export type FrontmatterMalformedReason = 'unterminated' | 'invalid-yaml';
+
+/** frontmatter 元数据（已由 split 保证是 YAML mapping） */
+export type FrontmatterMeta = Record<string, unknown>;
+
+export type FrontmatterSplit =
+  | { state: 'ok'; meta: FrontmatterMeta; body: string }
+  | { state: 'absent' }
+  | { state: 'malformed'; reason: FrontmatterMalformedReason; detail: string };
+
+/**
+ * 解析 markdown 的 YAML frontmatter。
+ *
+ * 不抛：三种畸形输入与 YAML 非法都体现在返回值 state/reason 上，由消费方按口径处置。
+ */
+export function splitFrontmatter(raw: string): FrontmatterSplit {
+  const lines = raw.split('\n');
+  if (lines[0] !== DELIMITER) return { state: 'absent' };
+
+  const closeIndex = lines.indexOf(DELIMITER, 1);
+  if (closeIndex === -1) {
+    return {
+      state: 'malformed',
+      reason: 'unterminated',
+      detail: `开界之后缺少独立成行的 ${DELIMITER} 闭合行`,
+    };
+  }
+
+  const metaLines = lines.slice(1, closeIndex);
+  if (metaLines.every(line => line.trim().length === 0)) return { state: 'absent' };
+
+  const metaText = metaLines.join('\n');
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(metaText);
+  } catch (error) {
+    return {
+      state: 'malformed',
+      reason: 'invalid-yaml',
+      // js-yaml 的 message 带多行代码片段，detail 只取首行描述——消费方要嵌进单行报告/stderr
+      detail: (error instanceof Error ? error.message : String(error)).split('\n')[0],
+    };
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      state: 'malformed',
+      reason: 'invalid-yaml',
+      detail: `frontmatter 必须是 YAML mapping，实际是 ${Array.isArray(parsed) ? 'array' : typeof parsed}`,
+    };
+  }
+
+  let bodyStart = closeIndex + 1;
+  if (lines[bodyStart] === '') bodyStart++;
+
+  return { state: 'ok', meta: parsed as FrontmatterMeta, body: lines.slice(bodyStart).join('\n') };
+}
+
+/**
+ * 序列化为 `---\n<yaml>---\n\n<body>`（包裹格式与收口前 store/migration 逐字一致）。
+ *
+ * meta 的键序由调用方决定（store 保 canonical 序）；本函数只做包裹与 dump 参数。
+ */
+export function joinFrontmatter(meta: FrontmatterMeta, body: string): string {
+  return `${DELIMITER}\n${yaml.dump(meta, { lineWidth: DUMP_LINE_WIDTH })}${DELIMITER}\n\n${body}`;
+}