@dommaker/harness 1.3.0 → 1.4.0

package/src/knowledge/store.ts

@@ -8,7 +8,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { splitFrontmatter, joinFrontmatter } from '../utils/frontmatter';
 import type { KnowledgeEntry, IndexEntry, QueryFilter } from './types';
 
 const DEFAULT_DIR = '.harness/knowledge';
@@ -30,6 +30,11 @@ export interface KnowledgeStore {
   get(id: string): KnowledgeEntry | undefined;
   list(filter?: QueryFilter): KnowledgeEntry[];
   save(entry: KnowledgeEntry): void;
+  /**
+   * 批量保存（harness#107）：循环内只更新内存索引，结束一次 writeIndex，
+   * 消除逐条 save 的 O(K·N) 全量索引重写。空批为零读写 no-op。
+   */
+  saveAll(entries: KnowledgeEntry[]): void;
   delete(id: string): boolean;
   update(id: string, partial: Partial<KnowledgeEntry>): KnowledgeEntry | undefined;
   rebuildIndex(): void;
@@ -47,6 +52,14 @@ export interface KnowledgeStore {
  */
 export class FileKnowledgeStore implements KnowledgeStore {
   private baseDir: string;
+  /**
+   * index.json 解析结果的实例级缓存（harness#106）
+   *
+   * mtimeMs+size 指纹（先例：project-config-loader.ts rawConfigCache）：
+   * 文件未变则复用解析结果，消除 list() 一次调用内 N+1 次全量重读；
+   * 文件变更（含外部进程改写、删除）自动失效。
+   */
+  private indexCache: { mtimeMs: number; size: number; entries: IndexEntry[] } | undefined;
 
   constructor(config?: Partial<StoreConfig>) {
     this.baseDir = config?.baseDir || DEFAULT_CONFIG.baseDir;
@@ -78,12 +91,31 @@ export class FileKnowledgeStore implements KnowledgeStore {
 
   save(entry: KnowledgeEntry): void {
     const filePath = this.entryPath(entry);
-    const frontmatter = this.toFrontmatter(entry);
-    const content = `---\n${frontmatter}---\n\n${entry.content}`;
+    const content = joinFrontmatter(this.toFrontmatter(entry), entry.content);
     fs.writeFileSync(filePath, content, 'utf-8');
     this.updateIndexEntry(entry);
   }
 
+  saveAll(entries: KnowledgeEntry[]): void {
+    if (entries.length === 0) return;
+    const index = this.readIndex();
+    const position = new Map(index.map((e, i) => [e.id, i]));
+    for (const entry of entries) {
+      const filePath = this.entryPath(entry);
+      const content = joinFrontmatter(this.toFrontmatter(entry), entry.content);
+      fs.writeFileSync(filePath, content, 'utf-8');
+      const indexEntry = this.toIndexEntry(entry);
+      const idx = position.get(entry.id);
+      if (idx !== undefined) {
+        index[idx] = indexEntry;
+      } else {
+        position.set(entry.id, index.length);
+        index.push(indexEntry);
+      }
+    }
+    this.writeIndex(index);
+  }
+
   delete(id: string): boolean {
     const filePath = this.findFile(id);
     if (!filePath) return false;
@@ -179,11 +211,16 @@ export class FileKnowledgeStore implements KnowledgeStore {
   }
 
   private parseFile(raw: string, filePath: string): KnowledgeEntry | undefined {
-    const match = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
-    if (!match) return undefined;
+    const fm = splitFrontmatter(raw);
+    if (fm.state === 'malformed') {
+      // 统一口径（harness#89）：损坏的 frontmatter 必须显式上报，不再静默丢条目
+      console.error(`[harness] 知识条目 frontmatter ${fm.reason}（${fm.detail}），已跳过 ${filePath}`);
+      return undefined;
+    }
+    if (fm.state === 'absent') return undefined;
 
-    const meta = yaml.load(match[1]) as Record<string, unknown>;
-    const content = match[2];
+    const meta = fm.meta;
+    const content = fm.body;
 
     return {
       id: meta.id as string || path.basename(filePath, '.md'),
@@ -209,7 +246,8 @@ export class FileKnowledgeStore implements KnowledgeStore {
     };
   }
 
-  private toFrontmatter(entry: KnowledgeEntry): string {
+  /** canonical 字段序是 store 的私有策略（harness#89 裁决 3），包裹格式交给 joinFrontmatter */
+  private toFrontmatter(entry: KnowledgeEntry): Record<string, unknown> {
     const meta: Record<string, unknown> = {
       id: entry.id,
       type: entry.type,
@@ -231,7 +269,7 @@ export class FileKnowledgeStore implements KnowledgeStore {
     if (entry.decayAt) meta.decayAt = entry.decayAt;
     if (entry.fullContentPath) meta.fullContentPath = entry.fullContentPath;
     if (entry.skillId) meta.skillId = entry.skillId;
-    return yaml.dump(meta, { lineWidth: 120 });
+    return meta;
   }
 
   private toIndexEntry(entry: KnowledgeEntry): IndexEntry {
@@ -348,10 +386,25 @@ export class FileKnowledgeStore implements KnowledgeStore {
 
   readIndex(): IndexEntry[] {
     const indexPath = path.join(this.baseDir, INDEX_FILE);
-    if (!fs.existsSync(indexPath)) return [];
+    let stat: fs.Stats | undefined;
+    try {
+      stat = fs.statSync(indexPath);
+    } catch {
+      stat = undefined;
+    }
+    if (!stat) {
+      this.indexCache = undefined;
+      return [];
+    }
+    const cached = this.indexCache;
+    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+      return cached.entries;
+    }
     try {
       const raw = fs.readFileSync(indexPath, 'utf-8');
-      return JSON.parse(raw) as IndexEntry[];
+      const entries = JSON.parse(raw) as IndexEntry[];
+      this.indexCache = { mtimeMs: stat.mtimeMs, size: stat.size, entries };
+      return entries;
     } catch {
       return [];
     }

package/src/monitoring/CONTEXT.md

@@ -4,19 +4,24 @@
 运行时监控：Execution Trace（收集/分析）+ 上下文使用追踪。
 
 ## 核心导出
-- `TraceCollector` — 执行追踪收集（append-only JSONL，`.harness/logs/traces.log`）
-- `TraceAnalyzer` — 追踪统计分析 + 异常检测（共用 analyzer-base 纯函数）
+- `TraceCollector` — 执行追踪收集（append-only JSONL，`.harness/logs/traces.log`）。读入口两个：`readReport(filter?)` 报告入口（返回 `{ traces, skippedLines }`，harness#100）与 `read()/readRecent()/readByConstraint()` 兼容包装（#82 裁决 4 冻结的签名，丢计数）
+- `TraceAnalyzer` — 追踪统计分析 + 异常检测（共用 analyzer-base 纯函数）。`analyzeRecentReport(hours)` 带坏行数，`analyzeRecent()/analyzeConstraint()` 仍返回 `TraceSummary[]`
 - `ContextTracker` — LLM 调用上下文使用快照记录
 
 ## 依赖关系
 - 依赖 `src/types/trace` ExecutionTrace 类型
-- 被 `src/core/constraints/checker`（惰性接线 getTraceCollector，ADR-0003）与 `src/cli/` 命令消费
+- 消费者：`src/cli/commands/{check,report}` 与 `src/hooks/bootstrap`——组合根经 `getTraceCollector()` 把收集器注入 `ConstraintChecker` 构造参数（harness#88）；`status` 另按 projectPath 自建收集器/分析器
+- core 不再依赖本模块（方向由 eslint no-restricted-imports 锁死，`src/__tests__/layering.test.ts` 守卫）
 
 ## 约定
 - Trace 文件存储在 .harness/ 目录（不提交）
 - 追加写入，单行 JSON，自动滚动
 - 零 Token 成本：不调用 LLM
+- **凡以 `skip` 策略读 JSONL，坏行计数必须到达该消费面的用户可见输出，或在该调用点显式记名豁免并写明理由（harness#100）**——静默吞掉「数据不全」不是一种可选项。承载方式纯增量：新报告入口带计数，旧入口退化为丢计数的薄包装（#82 裁决 4 的兼容约束继续成立），不另立第二份计数概念、不把 `JsonlReadResult` 提升进包根（ADR-0003）
+  - 机器可检：`src/utils/__tests__/jsonl-skip-disposition.test.ts` 三道闸——每个 `readJsonl` 调用点必须判得出策略（判不出即形状逃逸，失败）、skip 读点集合冻结（新增未声明即失败，站点消失却不删条目也失败）、每个读点上方 6 行内有 `计数去向：` 声明且邻居声明不得顶替
+  - 三类去向（逐条对得上代码）：**报告体内部的降级位**随报告体走 stdout——`constraints report` 的坏行提示紧挨既有的 `traceFileExists` 说明；**不挤动既有输出的诊断告知**走 stderr——`status`（`logError`，stdout 的 `记录数` 口径与字节不变）、`failure list`（#96 定稿的 `console.error`）、`constraints retire`（交互与 `--yes` 直达两条路径各自告知）；**结构化面用字段**——`constraints report --json` 的 `skippedLines`、`--export` markdown 的警示行、studio 端点响应体（配套票 studio#451）
 
 ## 注意事项
 - 追踪数据供 `harness constraints report` 统计与退役候选诊断消费（观测用途，不做自动降级）
+- **坏行计数是文件级口径**：`tail`/`head` 截断与时间窗过滤都发生在 parse 之前/之上，坏行既没有 timestamp 也没有 constraintId 可归窗，因此 `readReport()`/`analyzeRecentReport()` 返回的 `skippedLines` 不受过滤影响。消费方**无法**用「原始行数 − 统计条数」反推（两者分不开被窗过滤掉的合法行与损坏行），必须读 harness 透传的计数（#100 写死这条）
 - ADR-0003 起移除 recordBypass 链（绕过观测后续单独立项）与断链的诊断/性能/知识医生文件

package/src/monitoring/__tests__/skipped-lines-report.test.ts

@@ -0,0 +1,178 @@
+/**
+ * 坏行计数跨层透传（harness#100，承接 #82 裁决 4 的范围外项）
+ *
+ * #82 统一了 JSONL 读协议并让读「不抛 + 返回部分结果」，但计数在 TraceCollector
+ * 这一层被 `read()` 的兼容签名吞掉：studio 端点拿到部分结果却零提示。
+ * 本套件钉住收口后的形状——
+ * - 新报告入口 `readReport()` / `analyzeRecentReport()` 把计数带到消费面
+ * - 旧入口 `read()` / `readRecent()` / `readByConstraint()` / `getStats()` /
+ *   `analyzeRecent()` / `analyzeConstraint()` 的签名与返回类型逐条不变（编译期断言）
+ * - 跨层对账：module 计数 == collector 报告入口计数 == analyzer 报告入口计数
+ * - 时间窗只过滤合法行（坏行无 timestamp 可归窗），计数始终是文件级口径
+ */
+
+import * as path from 'path';
+import { createProjectFixture } from '../../test-setup/project-fixture';
+import { readJsonl } from '../../utils/jsonl';
+import { TraceCollector } from '../traces';
+import { TraceAnalyzer } from '../trace-analyzer';
+import type { ExecutionTrace, TraceSummary } from '../../types/trace';
+
+const BAD_LINE_1 = '{"constraintId":"broken"';
+const BAD_LINE_2 = 'not json at all';
+const BAD_LINE_3 = '{"constraintId":"half"';
+
+const NOW = 1700000000000;
+/** 覆盖全部 fixture 时间戳的窗口（100 年），语义 = "不按时间过滤" */
+const ALL_HOURS = 24 * 365 * 100;
+
+function validLine(constraintId: string, timestamp: number, result: ExecutionTrace['result'] = 'pass'): string {
+  return JSON.stringify({ constraintId, level: 'iron_law', timestamp, result });
+}
+
+/** 落一个只有 traces.log 的临时工程根 */
+function fixtureWith(lines: string[], name: string): string {
+  return createProjectFixture({
+    name,
+    files: { [path.join('.harness', 'logs', 'traces.log')]: lines.join('\n') + '\n' },
+  });
+}
+
+function collectorFor(root: string): TraceCollector {
+  return new TraceCollector({ traceFile: path.join(root, '.harness', 'logs', 'traces.log') });
+}
+
+describe('TraceCollector.readReport / TraceAnalyzer.analyzeRecentReport（harness#100）', () => {
+  describe.each([
+    { badCount: 1, badLines: [BAD_LINE_1] },
+    { badCount: 3, badLines: [BAD_LINE_1, BAD_LINE_2, BAD_LINE_3] },
+  ])('fixture 塞 $badCount 行坏数据', ({ badLines }) => {
+    const lines = [
+      validLine('alpha', NOW),
+      badLines[0],
+      validLine('beta', NOW + 1000, 'fail'),
+      ...(badLines.length > 1 ? [badLines[1], badLines[2]] : []),
+      validLine('alpha', NOW + 2000),
+    ];
+    const expectedSkipped = badLines.length;
+
+    it('跨层对账：module 计数 == collector 报告入口计数 == analyzer 报告入口计数', () => {
+      const root = fixtureWith(lines, 'skiplines-cross-layer');
+      const collector = collectorFor(root);
+      const analyzer = new TraceAnalyzer(collector);
+      const traceFile = path.join(root, '.harness', 'logs', 'traces.log');
+
+      const moduleResult = readJsonl<ExecutionTrace>(traceFile, 'skip');
+      const collectorReport = collector.readReport();
+      const analyzerReport = analyzer.analyzeRecentReport(ALL_HOURS);
+
+      expect(moduleResult.skippedLines).toBe(expectedSkipped);
+      expect(collectorReport.skippedLines).toBe(moduleResult.skippedLines);
+      expect(analyzerReport.skippedLines).toBe(moduleResult.skippedLines);
+      // 计数只有一份正本：合法记录集合在三层完全一致
+      expect(collectorReport.traces).toEqual(moduleResult.records);
+      expect(collectorReport.traces.map(t => t.constraintId)).toEqual(['alpha', 'beta', 'alpha']);
+    });
+
+    it('报告入口带过滤条件时，计数不受过滤影响（坏行无法归窗）', () => {
+      const root = fixtureWith(lines, 'skiplines-filtered');
+
+      const filtered = collectorFor(root).readReport({ constraintId: 'beta' });
+
+      expect(filtered.traces.map(t => t.constraintId)).toEqual(['beta']);
+      expect(filtered.skippedLines).toBe(expectedSkipped);
+    });
+
+    it('旧入口逐条不变：read()/readRecent()/readByConstraint() 仍只返回合法记录', () => {
+      const root = fixtureWith(lines, 'skiplines-compat');
+      const collector = collectorFor(root);
+
+      expect(collector.read().map(t => t.constraintId)).toEqual(['alpha', 'beta', 'alpha']);
+      expect(collector.readByConstraint('alpha')).toHaveLength(2);
+      expect(collector.readRecent(ALL_HOURS)).toHaveLength(3);
+    });
+
+    it('getStats().totalLines 保持原始行数口径（合法 + 坏行），与改动前一致', () => {
+      const root = fixtureWith(lines, 'skiplines-stats');
+
+      expect(collectorFor(root).getStats().totalLines).toBe(lines.length);
+    });
+  });
+
+  it('无损坏时报告入口计数为 0（零噪声前提）', () => {
+    const root = fixtureWith([validLine('alpha', NOW), validLine('beta', NOW + 1)], 'skiplines-clean');
+    const collector = collectorFor(root);
+
+    expect(collector.readReport()).toEqual({ traces: collector.read(), skippedLines: 0 });
+    expect(new TraceAnalyzer(collector).analyzeRecentReport(1).skippedLines).toBe(0);
+  });
+
+  it('缺 trace 文件时报告入口返回空记录 + 0，不抛', () => {
+    const collector = collectorFor(createProjectFixture({ name: 'skiplines-missing-file' }));
+
+    expect(collector.readReport()).toEqual({ traces: [], skippedLines: 0 });
+  });
+
+  it('时间窗内被丢掉的合法行不减计数：文件级口径（studio 无法自算的根因）', () => {
+    const lines = [
+      validLine('old', NOW - 10 * 3600 * 1000),
+      BAD_LINE_1,
+      BAD_LINE_2,
+      validLine('new', Date.now()),
+    ];
+    const root = fixtureWith(lines, 'skiplines-window');
+    const analyzer = new TraceAnalyzer(collectorFor(root));
+
+    const report = analyzer.analyzeRecentReport(1);
+
+    // 1 小时窗只剩 1 条合法 trace，但两条坏行仍要告知
+    expect(report.summaries.map(s => s.constraintId)).toEqual(['new']);
+    expect(report.summaries.reduce((n, s) => n + s.totalChecks, 0)).toBe(1);
+    expect(report.skippedLines).toBe(2);
+  });
+
+  describe('签名与返回类型冻结（#82 裁决 4 兼容约束，编译期固定）', () => {
+    it('旧入口返回类型逐条不变，新入口就地返回形状', () => {
+      const root = fixtureWith([validLine('alpha', NOW), BAD_LINE_1], 'skiplines-signature');
+      const collector = collectorFor(root);
+      const analyzer = new TraceAnalyzer(collector);
+
+      // 旧入口：返回类型逐条不变
+      const traces: ExecutionTrace[] = collector.read();
+      const recent: ExecutionTrace[] = collector.readRecent(ALL_HOURS);
+      const byConstraint: ExecutionTrace[] = collector.readByConstraint('alpha');
+      const stats: {
+        fileExists: boolean;
+        fileSize: number;
+        totalLines: number;
+        oldestTrace?: number;
+        newestTrace?: number;
+      } = collector.getStats();
+      const summaries: TraceSummary[] = analyzer.analyzeRecent(ALL_HOURS);
+      const constraintSummaries: TraceSummary[] = analyzer.analyzeConstraint('alpha');
+      expect(traces).toHaveLength(1);
+      expect(recent).toHaveLength(1);
+      expect(byConstraint).toHaveLength(1);
+      expect(stats.totalLines).toBe(2);
+      expect(summaries).toHaveLength(1);
+      expect(constraintSummaries).toHaveLength(1);
+
+      // 新入口：就地返回形状（不另立第二份计数概念，也不经包根导出的类型）
+      const collectorReport: { traces: ExecutionTrace[]; skippedLines: number } = collector.readReport();
+      const analyzerReport: { summaries: TraceSummary[]; skippedLines: number } = analyzer.analyzeRecentReport(
+        ALL_HOURS
+      );
+      expect(collectorReport.traces).toHaveLength(1);
+      expect(analyzerReport.summaries).toHaveLength(1);
+
+      // 兼容签名不会漂成报告对象：赋给报告类型是编译期错误（@ts-expect-error 消化），
+      // 运行期返回的仍是数组
+      // @ts-expect-error read() 仍返回 ExecutionTrace[]，不含坏行数
+      const readNoCount: { skippedLines: number } = collector.read();
+      // @ts-expect-error analyzeRecent() 仍返回 TraceSummary[]，不含坏行数
+      const analyzeNoCount: { skippedLines: number } = analyzer.analyzeRecent(ALL_HOURS);
+      expect(Array.isArray(readNoCount)).toBe(true);
+      expect(Array.isArray(analyzeNoCount)).toBe(true);
+    });
+  });
+});

package/src/monitoring/__tests__/traces.test.ts

@@ -3,6 +3,7 @@
  */
 
 import { TraceCollector, getTraceCollector, configureTraceCollector } from '../traces';
+import type { ExecutionTrace, TraceFilter } from '../../types/trace';
 import * as fs from 'fs';
 
 // Mock fs
@@ -161,6 +162,62 @@ describe('TraceCollector', () => {
       expect(stats.fileExists).toBe(true);
     });
   });
+
+  describe('坏行容错（harness#82 裁决 4：原「抛」改 skip，签名与返回类型不变）', () => {
+    it('read() 单行损坏只丢该行，合法 trace 照常返回', () => {
+      mockFs.readFileSync.mockReturnValueOnce(
+        '{"constraintId":"a","level":"iron_law","timestamp":100,"result":"pass"}\n' +
+        '{"constraintId":"b","broken"\n' +
+        '{"constraintId":"c","level":"guideline","timestamp":200,"result":"fail"}\n'
+      );
+      const traces = collector.read();
+      expect(traces.map(t => t.constraintId)).toEqual(['a', 'c']);
+    });
+
+    it('read() 坏行不阻断过滤', () => {
+      mockFs.readFileSync.mockReturnValueOnce(
+        '{"constraintId":"a","level":"iron_law","timestamp":100,"result":"pass"}\n' +
+        'not-json\n' +
+        '{"constraintId":"a","level":"iron_law","timestamp":200,"result":"fail"}\n'
+      );
+      const traces = collector.read({ constraintId: 'a' });
+      expect(traces).toHaveLength(2);
+    });
+
+    it('getStats() 首末行坏时不抛：totalLines 保持原始行数，时间戳取合法记录', () => {
+      mockFs.readFileSync.mockReturnValueOnce(
+        'not-json\n' +
+        '{"constraintId":"a","level":"iron_law","timestamp":100,"result":"pass"}\n' +
+        '{"constraintId":"b","level":"guideline","timestamp":200,"result":"fail"}\n' +
+        'also-bad\n'
+      );
+      mockFs.statSync.mockReturnValueOnce({ size: 2048 } as any);
+      const stats = collector.getStats();
+      expect(stats.fileExists).toBe(true);
+      expect(stats.totalLines).toBe(4);
+      expect(stats.oldestTrace).toBe(100);
+      expect(stats.newestTrace).toBe(200);
+    });
+
+    it('四个读方法签名与返回类型编译期固定（studio analyzeRecent 消费面零改动证据）', () => {
+      const read: (filter?: TraceFilter) => ExecutionTrace[] = collector.read.bind(collector);
+      const readRecent: (hours: number) => ExecutionTrace[] = collector.readRecent.bind(collector);
+      const readByConstraint: (constraintId: string) => ExecutionTrace[] =
+        collector.readByConstraint.bind(collector);
+      const getStats: () => {
+        fileExists: boolean;
+        fileSize: number;
+        totalLines: number;
+        oldestTrace?: number;
+        newestTrace?: number;
+      } = collector.getStats.bind(collector);
+
+      expect(read).toBeDefined();
+      expect(readRecent).toBeDefined();
+      expect(readByConstraint).toBeDefined();
+      expect(getStats).toBeDefined();
+    });
+  });
 });
 
 describe('getTraceCollector()', () => {

package/src/monitoring/context-tracker.ts

@@ -7,6 +7,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { readJsonl, appendJsonl } from '../utils/jsonl';
 import type { ContextUsageSnapshot } from '../context/types';
 
 export interface ContextAverages {
@@ -28,13 +29,7 @@ export class ContextTracker {
    * 记录上下文使用快照
    */
   record(snapshot: ContextUsageSnapshot): void {
-    const dir = path.dirname(this.logPath);
-
     try {
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-      }
-
       // 检查文件大小，超过限制时轮转
       if (fs.existsSync(this.logPath)) {
         const stat = fs.statSync(this.logPath);
@@ -43,8 +38,8 @@ export class ContextTracker {
         }
       }
 
-      const line = JSON.stringify(snapshot) + '\n';
-      fs.appendFileSync(this.logPath, line, 'utf-8');
+      // 写链收口：ensureDir + append（harness#82）
+      appendJsonl(this.logPath, snapshot);
     } catch {
       // 静默失败，不影响主流程
     }
@@ -55,21 +50,14 @@ export class ContextTracker {
    */
   getRecent(n: number): ContextUsageSnapshot[] {
     try {
-      if (!fs.existsSync(this.logPath)) {
-        return [];
-      }
-
-      const content = fs.readFileSync(this.logPath, 'utf-8');
-      const lines = content.trim().split('\n').filter(Boolean);
-      const recent = lines.slice(-n);
-
-      return recent.map(line => {
-        try {
-          return JSON.parse(line) as ContextUsageSnapshot;
-        } catch {
-          return null;
-        }
-      }).filter((s): s is ContextUsageSnapshot => s !== null);
+      // 坏行策略：skip（原逐行 null-filter 语义不变）；只 parse 最近 n 行；
+      // !== null 沿用原过滤口径：parse 成功但为 null 的记录不返回
+      // 计数去向：豁免（harness#100）——尾部快照读取（tail 在 parse 前截断，坏行占尾部槽位），
+      // 坏行只让返回条数少于 n；消费方是同模块 getAverages()/generateReport()（无 CLI 接线），
+      // 给它们加计数行属新能力，不在本票
+      return readJsonl<ContextUsageSnapshot>(this.logPath, 'skip', { tail: n })
+        .records
+        .filter((s): s is ContextUsageSnapshot => s !== null);
     } catch {
       return [];
     }

package/src/monitoring/index.ts

@@ -9,7 +9,7 @@
  * - ContextTracker：LLM 调用上下文快照记录
  */
 
-export { TraceCollector, getTraceCollector, configureTraceCollector, DEFAULT_TRACE_FILE } from './traces';
+export { TraceCollector, getTraceCollector, configureTraceCollector } from './traces';
 export { TraceAnalyzer, createAnalyzer } from './trace-analyzer';
 export { ContextTracker } from './context-tracker';
 export type { ContextAverages } from './context-tracker';

package/src/monitoring/trace-analyzer.ts

@@ -109,16 +109,35 @@ export class TraceAnalyzer {
     return summaries;
   }
 
+  /**
+   * 分析最近 N 小时的 traces，并带出坏行计数（harness#100 报告入口）
+   *
+   * `skippedLines` 是**文件级口径**：坏行没有 timestamp 归不进时间窗，
+   * 既不能按窗丢弃、也无法由消费方从 summaries 反推（客户端分不开
+   * 「被窗过滤掉的合法行」与「损坏行」）。
+   */
+  analyzeRecentReport(hours: number): { summaries: TraceSummary[]; skippedLines: number } {
+    const start = Date.now() - hours * 3600 * 1000;
+    const { traces, skippedLines } = this.collector.readReport({
+      timeRange: { start, end: Date.now() },
+    });
+
+    return { summaries: this.summarize(traces), skippedLines };
+  }
+
   /**
    * 分析最近 N 小时的 traces
+   *
+   * 兼容签名（#82 裁决 4 冻结）：丢坏行计数，要计数用 `analyzeRecentReport()`。
    */
   analyzeRecent(hours: number): TraceSummary[] {
-    const traces = this.collector.readRecent(hours);
-    return this.summarize(traces);
+    return this.analyzeRecentReport(hours).summaries;
   }
 
   /**
    * 分析特定约束
+   *
+   * 兼容签名同上：坏行计数由 `collector.readReport({ constraintId })` 承载。
    */
   analyzeConstraint(constraintId: string): TraceSummary[] {
     const traces = this.collector.readByConstraint(constraintId);

package/src/monitoring/traces.ts

@@ -11,6 +11,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { readJsonl, readJsonlEnds, appendJsonl } from '../utils/jsonl';
 import {
   DEFAULT_TRACE_FILE,
   type ExecutionTrace,
@@ -18,9 +19,6 @@ import {
   type TraceCollectorConfig,
 } from '../types/trace';
 
-// 路径常量再导出，保持既有从 monitoring/traces 导入的用法不破
-export { DEFAULT_TRACE_FILE };
-
 /**
  * 默认配置
  */
@@ -78,9 +76,8 @@ export class TraceCollector {
     // 检查文件大小，必要时滚动
     this.checkFileSize();
 
-    // 追加写入
-    const line = JSON.stringify(trace);
-    fs.appendFileSync(this.traceFile, line + '\n', 'utf-8');
+    // 追加写入（写链收口：ensureDir + append，harness#82）
+    appendJsonl(this.traceFile, trace);
   }
 
   /**
@@ -117,6 +114,24 @@ export class TraceCollector {
     });
   }
 
+  /**
+   * 批量读取 traces 并带出坏行计数（harness#100 报告入口）
+   *
+   * 支持过滤条件（同 `read()`）：时间范围 / 约束 ID / 结果类型 / 项目路径 / 会话 ID。
+   *
+   * **计数是文件级口径**：过滤只作用于合法记录——坏行没有 timestamp/约束 ID 可归窗，
+   * 丢不得。这正是消费方（studio 端点）无法自己算出坏行数的原因。
+   */
+  readReport(filter?: TraceFilter): { traces: ExecutionTrace[]; skippedLines: number } {
+    // 坏行策略：skip（harness#82 裁决 4：原裸 parse「抛」改 skip）；
+    // 计数去向：透传——skippedLines 随本方法返回，消费面是 TraceAnalyzer.analyzeRecentReport()
+    // （结构化）与包外调用方（studio 端点经配套票 #451 读它，见 studio#451）；
+    // `harness status` 另按 projectPath 直读 jsonl 正本，不经过本类
+    const { records, skippedLines } = readJsonl<ExecutionTrace>(this.traceFile, 'skip');
+
+    return { traces: filter ? this.applyFilter(records, filter) : records, skippedLines };
+  }
+
   /**
    * 批量读取 traces
    *
@@ -124,27 +139,19 @@ export class TraceCollector {
  * - 时间范围
  * - 约束 ID
    * - 结果类型
+   *
+   * 兼容签名（#82 裁决 4 冻结）：只返回记录数组、丢掉了坏行计数。
+   * 需要告知用户「数据不全」的消费方走 `readReport()`。
    */
   read(filter?: TraceFilter): ExecutionTrace[] {
-    if (!fs.existsSync(this.traceFile)) {
-      return [];
-    }
-
-    const content = fs.readFileSync(this.traceFile, 'utf-8');
-    const lines = content.split('\n').filter(l => l.trim());
-
-    let traces = lines.map(line => JSON.parse(line) as ExecutionTrace);
-
-    // 应用过滤条件
-    if (filter) {
-      traces = this.applyFilter(traces, filter);
-    }
-
-    return traces;
+    return this.readReport(filter).traces;
   }
 
   /**
    * 读取最近 N 小时的 traces
+   *
+   * 经 `read()` 的兼容包装，丢计数；要带计数用 `readReport({ timeRange })`
+   * 或 `TraceAnalyzer.analyzeRecentReport()`。
    */
   readRecent(hours: number): ExecutionTrace[] {
     const start = Date.now() - hours * 3600 * 1000;
@@ -153,6 +160,8 @@ export class TraceCollector {
 
   /**
    * 读取特定约束的 traces
+   *
+   * 同 `readRecent()`：兼容包装，计数走 `readReport({ constraintId })`。
    */
   readByConstraint(constraintId: string): ExecutionTrace[] {
     return this.read({ constraintId });
@@ -277,25 +286,19 @@ export class TraceCollector {
     }
 
     const stats = fs.statSync(this.traceFile);
-    const content = fs.readFileSync(this.traceFile, 'utf-8');
-    const lines = content.split('\n').filter(l => l.trim());
-
-    let oldest: number | undefined;
-    let newest: number | undefined;
-
-    if (lines.length > 0) {
-      const firstTrace = JSON.parse(lines[0]) as ExecutionTrace;
-      const lastTrace = JSON.parse(lines[lines.length - 1]) as ExecutionTrace;
-      oldest = firstTrace.timestamp;
-      newest = lastTrace.timestamp;
-    }
+    // 坏行策略：skip（同 read，裁决 4）；首/末时间戳取首/末条合法记录；
+    // totalLines 保持原始非空行数口径（合法 + 坏行）
+    // 计数去向：并进 totalLines 的原始行数口径（裁决 4 冻结，改口径属行为变更）；
+    // 本方法只出统计不出告警，要单列坏行数的消费方走 readReport()
+    // 实现经 readJsonlEnds 只 parse 两端（harness#114）：签名与口径逐字节不变
+    const { totalLines, first, last } = readJsonlEnds<ExecutionTrace>(this.traceFile, 'skip');
 
     return {
       fileExists: true,
       fileSize: stats.size,
-      totalLines: lines.length,
-      oldestTrace: oldest,
-      newestTrace: newest,
+      totalLines,
+      oldestTrace: first?.timestamp,
+      newestTrace: last?.timestamp,
     };
   }
 }

package/src/release/CONTEXT.md

@@ -4,6 +4,7 @@
 发布物完整性自检：harness 自己声明并校验自己发布了什么。关键发布物清单的单一来源，替代外部（studio publishPackage）与本仓 release 命令各自的 dist 文件硬编码（harness#77，#75 N4 收编）。
 
 ## 核心导出
+下列符号都由 `integrity.ts` 就地导出；`index.ts` barrel 只再导出标「公开 API」的那一组，其余属模块内部 seam——仓内消费方直接 `from './integrity'`，导出面由 `__tests__/barrel.test.ts` 守卫（harness#92）。
 - `deriveCriticalArtifacts(manifest)`（`integrity.ts`）——从包声明面（package.json `main`/`exports`/`bin`）推导脚本入口清单（.js/.cjs/.mjs/.d.ts，去 `./` 前缀、剔除非脚本叶子、去重排序）；纯函数
 - `EXTRA_CRITICAL_ARTIFACTS`——声明面推导之外的运行时关键发布物（bin/harness.js 引导期 require 的命令/门禁定义表、`dist/tools/definitions` 数据目录）；与其描述的文件同仓同评审，删改须同步
 - `resolvePackageRoot(fromDir?)`——从模块位置向上按包名解析本包根（源码仓与 node_modules 安装态均可达）