niceeval 0.11.1 → 0.11.3

package/src/results/copy.ts

@@ -1,4 +1,4 @@
-// copySnapshots:把选中快照按格式感知地复制到另一个目录(定稿见 docs/feature/results/library.md「复制与瘦身」)。
+// copySnapshots:把选中快照按格式感知地复制到另一个目录(定稿见 docs/feature/record/library.md「复制与瘦身」)。
 //
 // 发布场景的原语:只带指定 artifact、只带选中快照的全部 attempt,布局知识不外泄。
 // artifact 复制忠实于源(原字节,不重新序列化、不改写);snapshot.json / result.json
@@ -20,7 +20,7 @@ import type { ArtifactKind, AttemptHandle, Scope, Snapshot, SnapshotMeta } from
 
 /** 缺省携带的 artifact:commands / events / trace / o11y / agentSetup / sources;diff 不截断、
  *  可达百 MB,缺省不带。commands 缺省带的理由单独交代:失败命令证据是 errored attempt 的主要
- *  下钻面,不能默认发布拷贝时静默删掉(见 docs/feature/results/library.md「复制与瘦身」)。 */
+ *  下钻面,不能默认发布拷贝时静默删掉(见 docs/feature/record/library.md「复制与瘦身」)。 */
 const DEFAULT_PUBLISH_ARTIFACTS: ArtifactKind[] = ["commands", "events", "trace", "o11y", "agentSetup", "sources"];
 const VALID_ARTIFACTS: ArtifactKind[] = ["commands", "events", "trace", "o11y", "agentSetup", "diff", "sources"];
 
@@ -234,7 +234,7 @@ async function findArtifactFiles(
           break;
         }
       } catch {
-        // 缺文件跳过:某类数据为空本来就不生成对应 JSON(docs/feature/results/architecture.md)。
+        // 缺文件跳过:某类数据为空本来就不生成对应 JSON(docs/feature/record/architecture.md)。
       }
     }
   }

package/src/results/format.ts

@@ -1,6 +1,6 @@
-// Results Format 的布局与版本知识,规则见 docs/feature/results/architecture.md。
+// Results Format 的布局与版本知识,规则见 docs/feature/record/architecture.md。
 //
-// 按 docs/feature/results/library.md,这份知识只住在本库:写入面(writer.ts / copy.ts)与
+// 按 docs/feature/record/library.md,这份知识只住在本库:写入面(writer.ts / copy.ts)与
 // 读取面(open.ts)共用这里的目录规则与版本判定;src/runner/reporters/artifacts.ts
 // 是 writer 的薄壳,view(src/view/data.ts)经 openResults 消费,不自带布局知识。
 
@@ -57,7 +57,7 @@ export type SnapshotClassification =
   | { kind: "not-a-report" };
 
 /**
- * 版本判定与最小形状校验(docs/feature/results/architecture.md「版本不匹配时的读取行为」):
+ * 版本判定与最小形状校验(docs/feature/record/architecture.md「版本不匹配时的读取行为」):
  * - 带 format 信封:format 不是 niceeval.results → 无关 JSON;schemaVersion 非数字 → malformed;
  *   schemaVersion 与当前不同 → 不兼容(不解析、不迁移、不降级),带 schemaVersion 与完整 producer;
  *   schemaVersion 相同时校验 experimentId / agent / startedAt 均为 string,不满足 → malformed。

package/src/results/host-equivalence.test.ts

@@ -1,6 +1,6 @@
-// cases: docs/engineering/testing/unit/results.md
-// show / view 两宿主的 Scope 选择等价契约(docs/feature/results/architecture.md「Selection 是计算入口」;
-// docs/feature/results/library.md「选择快照」)。
+// cases: docs/engineering/testing/unit/record.md
+// show / view 两宿主的 Scope 选择等价契约(docs/feature/record/architecture.md「Selection 是计算入口」;
+// docs/feature/record/library.md「选择快照」)。
 //
 // 守护的不变量:同一结果根、同一组范围参数下,两扇门(niceeval show 的 text 面、niceeval view 的
 // web 面)传给 selectCurrentResults(results, scope) 同形的 scope({ experiment, patterns }),必须
@@ -12,7 +12,7 @@
 // docs/engineering/testing/e2e/report.md 的读面 CLI 行为(§4)与渲染面(§5)验收。
 //
 // fixture 直接写新布局(<expDir>/<snapDir>/snapshot.json + <evalId>/a<n>/result.json),
-// 依据 docs/feature/results/architecture.md 的稳定磁盘契约(与 show.test.ts / view/data.test.ts 同一写法)。
+// 依据 docs/feature/record/architecture.md 的稳定磁盘契约(与 show.test.ts / view/data.test.ts 同一写法)。
 
 import { afterEach, describe, expect, it } from "vitest";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
@@ -42,7 +42,7 @@ function res(id: string, verdict: Verdict, extra: Partial<AttemptFixture> = {}):
   return { id, verdict, attempt: 0, durationMs: 1000, assertions: [], ...extra };
 }
 
-/** 实验目录名清洗:与 docs/feature/results/architecture.md 一致(/ 与非 [\w.@-] 换成 _)。 */
+/** 实验目录名清洗:与 docs/feature/record/architecture.md 一致(/ 与非 [\w.@-] 换成 _)。 */
 function cleanDirName(id: string): string {
   return id.replace(/[^\w.@-]/g, "_");
 }
@@ -150,7 +150,7 @@ function normalizeWarning(w: ScopeWarning): NormWarning {
 /**
  * Selection 的「按 experiment × eval」视图现在从 `selection.attempts` 分组重建,不再读
  * `snapshot.evals`——真实 Snapshot 各自持有完整(未按现刻水位收窄的)evals,只有物化的
- * `Scope.attempts` 才是这次选择的真正结果(docs/feature/results/library.md「官方现刻水位」)。
+ * `Scope.attempts` 才是这次选择的真正结果(docs/feature/record/library.md「官方现刻水位」)。
  */
 function normalizeSelection(selection: Scope): NormSelection {
   const byExperiment = new Map<string, Map<string, NormAttempt[]>>();

package/src/results/index.ts

@@ -1,4 +1,4 @@
-// niceeval/results —— 实验结果数据的读写库(定稿见 docs/feature/results/library.md、docs/feature/results/architecture.md)。
+// niceeval/results —— 实验结果数据的读写库(定稿见 docs/feature/record/library.md、docs/feature/record/architecture.md)。
 //
 // 读:openResults(实验 → 快照 → eval → attempt 分层、skipped、latest() / current() Scope);
 // 写:createResultsWriter(快照声明 + attempt 增量落盘 + finish 补 completedAt);

package/src/results/locator.test.ts

@@ -1,5 +1,5 @@
-// cases: docs/engineering/testing/unit/results.md
-// AttemptLocator 单测(定稿见 docs/feature/results/library.md「按 locator 寻址一个 attempt」、docs/concepts.md「Attempt 定位符」):
+// cases: docs/engineering/testing/unit/record.md
+// AttemptLocator 单测(定稿见 docs/feature/record/library.md「按 locator 寻址一个 attempt」、docs/concepts.md「Attempt 定位符」):
 // 确定性编码、字段敏感(任一身份字段变化都换 locator)、@ 前缀与定长 base36 格式、decode 的语法
 // 校验分支、大批量下的实际无撞车、buildLocatorIndex 的撞车检测(用可注入的 encode 强制制造撞车,
 // 不依赖真实哈希小概率碰撞)与「相同身份重复出现不算撞车」(--resume 携带条目跨快照复现同一身份的场景)、

package/src/results/locator.ts

@@ -1,4 +1,4 @@
-// AttemptLocator:Attempt 的不透明、可复制、可发布的短标识(定稿见 docs/feature/results/library.md
+// AttemptLocator:Attempt 的不透明、可复制、可发布的短标识(定稿见 docs/feature/record/library.md
 // 「按 locator 寻址一个 attempt」、docs/concepts.md「Attempt 定位符」、docs/feature/reports/view.md 的 `#/attempt/@<locator>` 路由)。
 //
 // locator 由不可变身份元组 {experimentId, 快照 startedAt, evalId, attempt 下标(0-indexed)}

package/src/results/open.ts

@@ -1,5 +1,5 @@
 // openResults:扫描结果目录,返回「实验 → 快照 → eval → attempt」的类型化层次
-// (定稿见 docs/feature/results/library.md「读:openResults」、docs/feature/results/architecture.md「读取规则」)。
+// (定稿见 docs/feature/record/library.md「读:openResults」、docs/feature/record/architecture.md「读取规则」)。
 //
 // 三条铁律:
 // - 忠实磁盘:快照与实验归组只切片,不合并、不聚合、不去重;合并/聚合永远发生在消费方。
@@ -476,7 +476,7 @@ function makeAttempt(snapshot: Snapshot, snapshotDir: string, attemptDir: string
     snapshot,
     locator: record.locator as AttemptLocator,
     // 携带条目投影:artifactBase 有值就是本快照 `--resume` 合入的上一轮终态结果
-    // (docs/feature/results/library.md「时效:新执行与历史执行」)。
+    // (docs/feature/sample/library.md「时效:新执行与历史执行」)。
     carried: Boolean(record.artifactBase),
     commands: lazyArtifact<FailedCommandEvidence[]>(candidates, "commands", record.commands),
     events: lazyArtifact<StreamEvent[]>(candidates, "events", record.events),

package/src/results/publish.ts

@@ -1,4 +1,4 @@
-// 发布预算(见 docs/feature/results/library.md「复制与瘦身:copySnapshots」)。
+// 发布预算(见 docs/feature/record/library.md「复制与瘦身:copySnapshots」)。
 // 结果数据分两类:.niceeval/ 是本地事实根,不是默认可提交目录;任何要离开本机的拷贝是
 // 发布拷贝,经 copySnapshots 这一条管线产出。管线只做选择、归拢与整文件大小预检,
 // 不改写内容——保密边界由格式在采集侧划定(env 值与命令 stdout/stderr 不进结果文件)。

package/src/results/results.test.ts

@@ -1,8 +1,7 @@
-// cases: docs/engineering/testing/unit/results.md
+// cases: docs/engineering/testing/unit/record.md
 // niceeval/results 的单测:临时目录里构造最小 snapshot.json / result.json / artifact fixture,
-// 覆盖定稿契约(docs/feature/results/library.md、docs/feature/results/architecture.md):分层读取(含快照级字段注入)、
-// 懒加载与 artifactBase 回退、skipped 三种原因、unfinished-snapshot、latest() 三种警告、
-// Selection.filter 修剪、dedupeAttempts 身份键、writer(独占目录、并发快照互不干扰、
+// 覆盖定稿契约(docs/feature/record/library.md、docs/feature/record/architecture.md):分层读取(含快照级字段注入)、
+// 懒加载与 artifactBase 回退、skipped 三种原因、writer(独占目录、并发快照互不干扰、
 // snapshot.json 键形状、writeAttempt/writeAttemptFor、finish 幂等)、copySnapshots(布局、
 // knownEvalIds 补记、artifacts 词干列表重算)。
 // 读取面 fixture 的目录名/artifact 路径手写(不 import 库的路径函数),让测试独立于实现充当格式基准。
@@ -304,296 +303,6 @@ describe("openResults · skipped", () => {
   });
 });
 
-// ───────────────────────── latest() Selection 与警告 ─────────────────────────
-
-describe("results.latest() · Selection", () => {
-  it("每个实验取最新快照;experiments 前缀过滤同 CLI 语义(尾斜杠等价)", async () => {
-    const root = await makeRoot();
-    await writeSnapshot(root, "mid_a", "s1", meta({ experimentId: "mid/a", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeSnapshot(root, "mid_b", "s1", meta({ experimentId: "mid/b", agent: "codex", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    const tuesday = await writeSnapshot(root, "mid_b", "s2", meta({ experimentId: "mid/b", agent: "codex", startedAt: "2026-07-02T08:00:00.000Z", completedAt: "2026-07-02T08:10:00.000Z" }));
-
-    const results = await openResults(root);
-    const latest = results.latest();
-    expect(latest.snapshots.map((s) => s.experimentId)).toEqual(["mid/a", "mid/b"]);
-    expect(latest.snapshots[1].dir).toBe(tuesday);
-
-    expect(results.latest({ experiments: "mid/a" }).snapshots).toHaveLength(1);
-    expect(results.latest({ experiments: "mid/" }).snapshots).toHaveLength(2);
-    expect(results.latest({ experiments: ["mid/a", "mid/b"] }).snapshots).toHaveLength(2);
-    expect(results.latest({ experiments: "other" }).snapshots).toHaveLength(0);
-    expect(results.latest({ experiments: "mid/a" }).snapshots[0].experimentId).toBe("mid/a"); // 不误配 "mid/ab"
-  });
-
-  it("coverage:最新快照覆盖 < 已知并集时,missingEvalIds 列出缺的题;分母是 knownEvalIds", async () => {
-    const root = await makeRoot();
-    const mondayDir = await writeSnapshot(root, "midterm", "2026-07-01T08-00-00-000Z", meta({ experimentId: "midterm/bub-gpt-5.4", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeResultFile(mondayDir, "algebra/q1/a1", record({ id: "algebra/q1", attempt: 1 }));
-    await writeResultFile(mondayDir, "algebra/q2/a1", record({ id: "algebra/q2", attempt: 1 }));
-    await writeResultFile(mondayDir, "algebra/q3/a1", record({ id: "algebra/q3", attempt: 1 }));
-
-    const fridayDir = await writeSnapshot(root, "midterm", "2026-07-05T08-00-00-000Z", meta({ experimentId: "midterm/bub-gpt-5.4", agent: "bub", startedAt: "2026-07-05T08:00:00.000Z", completedAt: "2026-07-05T08:10:00.000Z" }));
-    await writeResultFile(fridayDir, "algebra/q1/a1", record({ id: "algebra/q1", attempt: 1 }));
-
-    const latest = (await openResults(root)).latest();
-    expect(latest.snapshots).toHaveLength(1);
-    // partial-coverage / stale-snapshot 不再是 warnings —— 覆盖缺口是行级事实,物化在 coverage 上。
-    expect(latest.warnings.filter((w) => w.kind !== "unreadable-snapshot")).toHaveLength(0);
-    const coverage = latest.coverage.find((c) => c.experimentId === "midterm/bub-gpt-5.4")!;
-    expect(coverage.knownEvalIds).toEqual(["algebra/q1", "algebra/q2", "algebra/q3"]);
-    expect(coverage.missingEvalIds).toEqual(["algebra/q2", "algebra/q3"]);
-  });
-
-  it("unfinished-snapshot:选中快照缺 completedAt", async () => {
-    const root = await makeRoot();
-    const dir = await writeSnapshot(root, "e", "2026-07-01T08-00-00-000Z", meta({ experimentId: "e", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z" }));
-
-    const latest = (await openResults(root)).latest();
-    const warn = latest.warnings.find((w) => w.kind === "unfinished-snapshot")!;
-    expect(warn).toMatchObject({ experimentId: "e", startedAt: "2026-07-01T08:00:00.000Z", dir });
-    expect(warn.message).toContain("has no completedAt");
-  });
-
-  it("Selection.filter 只删不换:快照删减,幸存实验的 coverage / 警告保留、其余丢弃", async () => {
-    const root = await makeRoot();
-    const aDir = await writeSnapshot(root, "mid_a", "s1", meta({ experimentId: "mid/a", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeResultFile(aDir, "q1/a1", record({ id: "q1", attempt: 1 }));
-    await writeResultFile(aDir, "q2/a1", record({ id: "q2", attempt: 1 }));
-    const bDir = await writeSnapshot(root, "mid_b", "s1", meta({ experimentId: "mid/b", agent: "codex", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeResultFile(bDir, "q1/a1", record({ id: "q1", attempt: 1 }));
-    await writeResultFile(bDir, "q2/a1", record({ id: "q2", attempt: 1 }));
-
-    // 两个实验的最新快照都只重跑了 q1(残缺,进 coverage.missingEvalIds)且都未收尾(进 warnings)。
-    const aDir2 = await writeSnapshot(root, "mid_a", "s2", meta({ experimentId: "mid/a", agent: "bub", startedAt: "2026-07-02T08:00:00.000Z" }));
-    await writeResultFile(aDir2, "q1/a1", record({ id: "q1", attempt: 1 }));
-    const bDir2 = await writeSnapshot(root, "mid_b", "s2", meta({ experimentId: "mid/b", agent: "codex", startedAt: "2026-07-02T08:00:00.000Z" }));
-    await writeResultFile(bDir2, "q1/a1", record({ id: "q1", attempt: 1 }));
-
-    const latest = (await openResults(root)).latest();
-    expect(latest.coverage.map((c) => c.experimentId).sort()).toEqual(["mid/a", "mid/b"]);
-    expect(latest.coverage.find((c) => c.experimentId === "mid/a")!.missingEvalIds).toEqual(["q2"]);
-    expect(latest.warnings.filter((w) => w.kind === "unfinished-snapshot")).toHaveLength(2);
-
-    const filtered = latest.filter((s) => s.experimentId !== "mid/b");
-    expect(filtered.snapshots.map((s) => s.experimentId)).toEqual(["mid/a"]);
-    expect(filtered.coverage.map((c) => c.experimentId)).toEqual(["mid/a"]);
-    expect(filtered.warnings.map((w) => ("experimentId" in w ? w.experimentId : undefined))).toEqual(["mid/a"]);
-    // 原 Selection 不被改动。
-    expect(latest.snapshots).toHaveLength(2);
-    expect(latest.coverage).toHaveLength(2);
-    expect(latest.warnings).toHaveLength(2);
-  });
-
-  it("current() 下同一 experiment 有两个贡献 Snapshot 时,filter 删除其中一个只删该来源的水位,不整实验全留或全删", async () => {
-    const root = await makeRoot();
-    // 周一:q1、q2 真实执行。
-    const mondayDir = await writeSnapshot(root, "multi_e", "2026-07-01T08-00-00-000Z", meta({ experimentId: "multi/e", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeResultFile(mondayDir, "q1/a1", record({ id: "q1", attempt: 1 }));
-    await writeResultFile(mondayDir, "q2/a1", record({ id: "q2", attempt: 1 }));
-    // 周二:只重跑 q1;current() 从周一补齐 q2,两个真实快照都进 Scope.snapshots。
-    const tuesdayDir = await writeSnapshot(root, "multi_e", "2026-07-02T08-00-00-000Z", meta({ experimentId: "multi/e", agent: "bub", startedAt: "2026-07-02T08:00:00.000Z", completedAt: "2026-07-02T08:10:00.000Z" }));
-    await writeResultFile(tuesdayDir, "q1/a1", record({ id: "q1", attempt: 1 }));
-
-    const current = (await openResults(root)).current();
-    expect(current.snapshots.map((s) => s.startedAt).sort()).toEqual(["2026-07-01T08:00:00.000Z", "2026-07-02T08:00:00.000Z"]);
-    expect(current.attempts.map((a) => a.evalId).sort()).toEqual(["q1", "q2"]);
-    expect(current.coverage.find((c) => c.experimentId === "multi/e")!.missingEvalIds).toEqual([]);
-
-    // 删掉周一(q2 唯一来源),周二(q1 来源)保留:不是整实验全留或全删。
-    const filtered = current.filter((s) => s.startedAt !== "2026-07-01T08:00:00.000Z");
-    expect(filtered.snapshots.map((s) => s.startedAt)).toEqual(["2026-07-02T08:00:00.000Z"]);
-    expect(filtered.attempts.map((a) => a.evalId)).toEqual(["q1"]);
-    // knownEvalIds(分母)不变,只有被删来源独占贡献的 q2 转入 missingEvalIds。
-    const filteredCoverage = filtered.coverage.find((c) => c.experimentId === "multi/e")!;
-    expect(filteredCoverage.knownEvalIds).toEqual(["q1", "q2"]);
-    expect(filteredCoverage.missingEvalIds).toEqual(["q2"]);
-    // 原 Scope 不被改动。
-    expect(current.snapshots).toHaveLength(2);
-    expect(current.attempts).toHaveLength(2);
-
-    // 反过来删掉周二(q1 唯一来源),周一(q2 来源)保留。
-    const otherWay = current.filter((s) => s.startedAt !== "2026-07-02T08:00:00.000Z");
-    expect(otherWay.snapshots.map((s) => s.startedAt)).toEqual(["2026-07-01T08:00:00.000Z"]);
-    expect(otherWay.attempts.map((a) => a.evalId)).toEqual(["q2"]);
-    expect(otherWay.coverage.find((c) => c.experimentId === "multi/e")!.missingEvalIds).toEqual(["q1"]);
-
-    // attempt.snapshot 原样指回真实来源(不是过滤时重建的新对象)。
-    for (const attempt of filtered.attempts) {
-      expect(filtered.snapshots).toContain(attempt.snapshot);
-    }
-  });
-});
-
-// ───────────────────────── unreadable-snapshot 警告 ─────────────────────────
-
-describe("results.latest() / results.current() · unreadable-snapshot", () => {
-  it("malformed 快照产生 warning 且其余快照照常计入;无关 JSON 不产生 warning", async () => {
-    const root = await makeRoot();
-    const okDir = await writeSnapshot(root, "ok-exp", "2026-07-04T08-00-00-000Z-oooo", meta({ experimentId: "ok", agent: "bub", startedAt: "2026-07-04T08:00:00.000Z", completedAt: "2026-07-04T08:10:00.000Z" }));
-    await writeResultFile(okDir, "q1/a1", record({ id: "q1", attempt: 1 }));
-
-    const badDir = join(root, "bad-exp", "2026-07-02T08-00-00-000Z-zzzz");
-    await mkdir(badDir, { recursive: true });
-    await writeFile(join(badDir, "snapshot.json"), "not json {", "utf-8");
-
-    const alienDir = join(root, "alien-exp", "2026-07-06T08-00-00-000Z-alien");
-    await mkdir(alienDir, { recursive: true });
-    await writeFile(join(alienDir, "summary.json"), JSON.stringify({ hello: 1 }), "utf-8");
-
-    const results = await openResults(root);
-    const latest = results.latest();
-    // 其余快照照常计入,不被坏落盘拖垮。
-    expect(latest.snapshots.map((s) => s.experimentId)).toEqual(["ok"]);
-
-    const unreadable = latest.warnings.filter((w) => w.kind === "unreadable-snapshot");
-    expect(unreadable).toHaveLength(1); // 无关 JSON(alien)不产生 warning
-    expect(unreadable[0]).toMatchObject({ kind: "unreadable-snapshot", dir: badDir, reason: "malformed" });
-    expect(unreadable[0].message).toContain(badDir);
-    expect(unreadable[0].message).toMatch(/inspect .*snapshot\.json/);
-    expect((unreadable[0] as { command?: string }).command).toBeUndefined();
-
-    // results.current() 同一份事实(show / view 报告槽走的是它)。
-    const current = results.current();
-    expect(current.warnings.filter((w) => w.kind === "unreadable-snapshot")).toHaveLength(1);
-  });
-
-  it("incompatible(schemaVersion 不兼容,niceeval producer)的 warning 带版本化 command", async () => {
-    const root = await makeRoot();
-    const oldDir = join(root, "old-exp", "2026-06-01T08-00-00-000Z");
-    await mkdir(oldDir, { recursive: true });
-    await writeFile(
-      join(oldDir, "snapshot.json"),
-      JSON.stringify({
-        format: RESULTS_FORMAT,
-        schemaVersion: RESULTS_SCHEMA_VERSION - 1,
-        producer: { name: "niceeval", version: "0.4.6" },
-        experimentId: "old",
-        agent: "bub",
-        startedAt: "2026-06-01T08:00:00.000Z",
-      }),
-      "utf-8",
-    );
-
-    const latest = (await openResults(root)).latest();
-    const warn = latest.warnings.find((w) => w.kind === "unreadable-snapshot")!;
-    expect(warn).toMatchObject({ kind: "unreadable-snapshot", dir: oldDir, reason: "incompatible-version" });
-    expect((warn as { command?: string }).command).toBe(`npx niceeval@0.4.6 show --results ${root}`);
-    expect(warn.message).toContain("npx niceeval@0.4.6 show --results");
-  });
-
-  it("非实验作用域:Selection.filter 收窄后 unreadable-snapshot warning 仍在", async () => {
-    const root = await makeRoot();
-    const aDir = await writeSnapshot(root, "mid_a", "s1", meta({ experimentId: "mid/a", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeResultFile(aDir, "q1/a1", record({ id: "q1", attempt: 1 }));
-
-    const badDir = join(root, "bad-exp", "2026-07-02T08-00-00-000Z-zzzz");
-    await mkdir(badDir, { recursive: true });
-    await writeFile(join(badDir, "snapshot.json"), "not json {", "utf-8");
-
-    const latest = (await openResults(root)).latest();
-    expect(latest.warnings.filter((w) => w.kind === "unreadable-snapshot")).toHaveLength(1);
-
-    // filter 只删快照,不删非实验作用域的警告 —— 即便过滤条件与该 warning 无关的实验都不复存在。
-    const filtered = latest.filter((s) => s.experimentId === "mid/a");
-    expect(filtered.snapshots).toHaveLength(1);
-    expect(filtered.warnings.filter((w) => w.kind === "unreadable-snapshot")).toHaveLength(1);
-  });
-});
-
-// ───────────────────────── ScopeWarning 联合成员恰为三种(回归锁死) ─────────────────────────
-
-// 类型契约(编译期,随 pnpm typecheck):ScopeWarning 联合成员恰为三种——多一个 kind 而没同步
-// 改这里,default 分支的 never 赋值编译不过;少一个则对应 case 编译不过。kind 全集不是运行时
-// 行为,没有运行时断言可写(docs/engineering/testing/unit/README.md「类型契约」)。
-function assertScopeWarningKindExhaustive(kind: import("./types.ts").ScopeWarning["kind"]): void {
-  switch (kind) {
-    case "unfinished-snapshot":
-    case "missing-startedAt":
-    case "unreadable-snapshot":
-      return;
-    default: {
-      const exhausted: never = kind;
-      void exhausted;
-    }
-  }
-}
-void assertScopeWarningKindExhaustive;
-
-// ───────────────────────── 时效:attempt.carried 与 fresh 口径 ─────────────────────────
-
-describe("时效:carried 投影与 fresh 口径", () => {
-  it("latest({ fresh: true }):排除携带条目,被排除的题进 coverage.missingEvalIds", async () => {
-    const root = await makeRoot();
-    const monday = await writeSnapshot(root, "e", "2026-07-01T08-00-00-000Z", meta({ experimentId: "e", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeResultFile(monday, "q1/a1", record({ id: "q1", attempt: 1 }));
-
-    // 周二:q1 携带合入(artifactBase 指回周一),q2 真实执行。
-    const tuesday = await writeSnapshot(root, "e", "2026-07-02T08-00-00-000Z", meta({ experimentId: "e", agent: "bub", startedAt: "2026-07-02T08:00:00.000Z", completedAt: "2026-07-02T08:10:00.000Z" }));
-    await writeResultFile(tuesday, "q1/a1", record({ id: "q1", attempt: 1, startedAt: "2026-07-01T08:00:00.000Z", artifactBase: "e/2026-07-01T08-00-00-000Z/q1/a1" }));
-    await writeResultFile(tuesday, "q2/a1", record({ id: "q2", attempt: 1 }));
-
-    const results = await openResults(root);
-    const notFresh = results.latest();
-    expect(notFresh.snapshots[0]!.evals.map((e) => e.id).sort()).toEqual(["q1", "q2"]);
-    expect(notFresh.coverage.find((c) => c.experimentId === "e")!.missingEvalIds).toEqual([]);
-
-    const fresh = results.latest({ fresh: true });
-    expect(fresh.attempts.map((a) => a.evalId)).toEqual(["q2"]); // q1 是携带条目,被排除
-    expect(fresh.coverage.find((c) => c.experimentId === "e")!.missingEvalIds).toEqual(["q1"]);
-    // 真实 Snapshot 原样保留:q1 仍在它自己的 evals 里,fresh 没有克隆/裁剪来源对象。
-    expect(fresh.snapshots[0]!.evals.map((e) => e.id).sort()).toEqual(["q1", "q2"]);
-  });
-
-  it("current({ fresh: true }):同时排除携带条目与跨快照拼入的历史执行,区分力 fixture ——「只排携带 / 只排旧快照 / 两者都排」三种候选算法各给出不同答案", async () => {
-    const root = await makeRoot();
-    // 周一:q1、q2 真实执行。
-    const monday = await writeSnapshot(root, "e", "2026-07-01T08-00-00-000Z", meta({ experimentId: "e", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeResultFile(monday, "q1/a1", record({ id: "q1", attempt: 1 }));
-    await writeResultFile(monday, "q2/a1", record({ id: "q2", attempt: 1 }));
-
-    // 周二:q1 携带合入(仍是这次快照里"最新"的一份,但 carried=true);q3 真实执行;q2 本次没有
-    // 任何 attempt —— current() 从周一补齐它,补齐来的 q2 attempt 所属快照早于本实验在 Scope 中
-    // 最新快照(周二),是「跨快照拼入」的历史执行,即使它自己不是携带条目。
-    const tuesday = await writeSnapshot(root, "e", "2026-07-02T08-00-00-000Z", meta({ experimentId: "e", agent: "bub", startedAt: "2026-07-02T08:00:00.000Z", completedAt: "2026-07-02T08:10:00.000Z" }));
-    await writeResultFile(tuesday, "q1/a1", record({ id: "q1", attempt: 1, startedAt: "2026-07-01T08:00:00.000Z", artifactBase: "e/2026-07-01T08-00-00-000Z/q1/a1" }));
-    await writeResultFile(tuesday, "q3/a1", record({ id: "q3", attempt: 1 }));
-
-    const results = await openResults(root);
-    const notFresh = results.current();
-    expect(notFresh.attempts.map((a) => a.evalId).sort()).toEqual(["q1", "q2", "q3"]);
-    expect(notFresh.coverage.find((c) => c.experimentId === "e")!.missingEvalIds).toEqual([]);
-    // 两个真实来源都在场:q2 唯一来自周一,q1/q3 来自周二——不是一个合并对象。
-    expect(notFresh.snapshots.map((s) => s.startedAt).sort()).toEqual(["2026-07-01T08:00:00.000Z", "2026-07-02T08:00:00.000Z"]);
-
-    const fresh = results.current({ fresh: true });
-    // 只有 q3(本次快照真实执行、非携带)是新执行;q1(携带)与 q2(跨快照拼入)都被排除。
-    expect(fresh.attempts.map((a) => a.evalId)).toEqual(["q3"]);
-    expect(fresh.coverage.find((c) => c.experimentId === "e")!.missingEvalIds.sort()).toEqual(["q1", "q2"]);
-    // 周一(q2 唯一来源)不再贡献任何 fresh attempt,退出 snapshots;周二仍在,即便它自己的
-    // evals 里仍然原样带着被排除的 q1(真实 Snapshot 不被裁剪)。
-    expect(fresh.snapshots.map((s) => s.startedAt)).toEqual(["2026-07-02T08:00:00.000Z"]);
-    expect(fresh.snapshots[0]!.evals.map((e) => e.id).sort()).toEqual(["q1", "q3"]);
-  });
-
-  it("fresh 清空全部 attempt 后 Scope 只剩 coverage 事实;filter 不拿 snapshots 当 coverage 的存续代理", async () => {
-    const root = await makeRoot();
-    const monday = await writeSnapshot(root, "e", "2026-07-01T08-00-00-000Z", meta({ experimentId: "e", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z", completedAt: "2026-07-01T08:10:00.000Z" }));
-    await writeResultFile(monday, "q1/a1", record({ id: "q1", attempt: 1 }));
-    // 周二唯一的条目是携带复印件:fresh 把它排除后,这个实验没有任何新执行。
-    const tuesday = await writeSnapshot(root, "e", "2026-07-02T08-00-00-000Z", meta({ experimentId: "e", agent: "bub", startedAt: "2026-07-02T08:00:00.000Z", completedAt: "2026-07-02T08:10:00.000Z" }));
-    await writeResultFile(tuesday, "q1/a1", record({ id: "q1", attempt: 1, startedAt: "2026-07-01T08:00:00.000Z", artifactBase: "e/2026-07-01T08-00-00-000Z/q1/a1" }));
-
-    const fresh = (await openResults(root)).current({ fresh: true });
-    expect(fresh.attempts).toEqual([]);
-    const coverage = fresh.coverage.find((c) => c.experimentId === "e")!;
-    expect(coverage.missingEvalIds).toEqual(["q1"]);
-    // coverage-only 实验(零 snapshot 贡献)经 filter 后覆盖缺口不静默消失——榜单占位行的上游事实。
-    expect(fresh.filter(() => true).coverage).toEqual(fresh.coverage);
-  });
-});
-
-// ───────────────────────── 身份键去重 ─────────────────────────
-
 function fakeSnapshot(over: { experimentId: string; startedAt: string; dir: string }): Snapshot {
   return {
     agent: "bub",
@@ -623,32 +332,6 @@ function fakeAttempt(snapshot: Snapshot, result: EvalResult): AttemptHandle {
   };
 }
 
-describe("dedupeAttempts", () => {
-  it("按 (experimentId, evalId, attempt, startedAt) 去重,保留最新快照里的那份;缺 startedAt 不去重并出 missing-startedAt", () => {
-    const monday = fakeSnapshot({ experimentId: "e", startedAt: "2026-07-01T08:00:00.000Z", dir: "/tmp/e/monday" });
-    const tuesday = fakeSnapshot({ experimentId: "e", startedAt: "2026-07-02T08:00:00.000Z", dir: "/tmp/e/tuesday" });
-
-    const a1 = fakeAttempt(monday, record({ id: "q1", attempt: 1, startedAt: "2026-07-01T08:01:00.000Z" }));
-    const a1Resumed = fakeAttempt(tuesday, record({ id: "q1", attempt: 1, startedAt: "2026-07-01T08:01:00.000Z" })); // resume 原样合入
-    const a2Mon = fakeAttempt(monday, record({ id: "q2", attempt: 1, startedAt: "2026-07-01T08:02:00.000Z" }));
-    const a2Tue = fakeAttempt(tuesday, record({ id: "q2", attempt: 1, startedAt: "2026-07-02T08:02:00.000Z" })); // 重跑,新 startedAt
-    const a3Mon = fakeAttempt(monday, record({ id: "q3", attempt: 1 })); // 缺 startedAt(携带条目缺锚的极端情况)
-    const a3Tue = fakeAttempt(tuesday, record({ id: "q3", attempt: 1 }));
-
-    const { attempts, warnings } = dedupeAttempts([a1, a2Mon, a3Mon, a1Resumed, a2Tue, a3Tue]);
-    expect(attempts).toHaveLength(5);
-    const q1 = attempts.filter((a) => a.evalId === "q1");
-    expect(q1).toHaveLength(1);
-    expect(q1[0].snapshot).toBe(tuesday); // 保留最新快照
-    expect(attempts.filter((a) => a.evalId === "q2")).toHaveLength(2);
-    expect(attempts.filter((a) => a.evalId === "q3")).toHaveLength(2);
-
-    expect(warnings).toHaveLength(2);
-    expect(warnings[0]).toMatchObject({ kind: "missing-startedAt", experimentId: "e", evalId: "q3" });
-    expect(warnings[0].message).toContain("has no startedAt");
-  });
-});
-
 // ───────────────────────── writer ─────────────────────────
 
 describe("createResultsWriter", () => {
@@ -769,7 +452,7 @@ describe("createResultsWriter", () => {
     expect(JSON.parse(await readFile(copied, "utf-8"))).toEqual(manifest);
   });
 
-  // cases: docs/engineering/testing/unit/results.md「Usage、facts 与失败命令证据落盘」
+  // cases: docs/engineering/testing/unit/record.md「Usage、facts 与失败命令证据落盘」
   it("commands:落成 commands.json(不内联进 result.json),artifacts 含 commands;懒加载读回原样往返;没有非零命令的 attempt 恒 null;copySnapshots 缺省携带", async () => {
     const root = await makeRoot();
     const writer = createResultsWriter(root, { producer: { name: "niceeval", version: "0.12.0" } });
@@ -836,7 +519,7 @@ describe("createResultsWriter", () => {
   });
 
   it("每个 Snapshot 各自独立封口:两个 Experiment 各自不同的 completedAt 与 diagnostics 不串味,空 diagnostics 省略字段", async () => {
-    // cases: docs/engineering/testing/unit/results.md「落盘格式」——snap.finish() 唯一一次补
+    // cases: docs/engineering/testing/unit/record.md「落盘格式」——snap.finish() 唯一一次补
     // completedAt 与快照级 diagnostics。
     const root = await makeRoot();
     const writer = createResultsWriter(root, { producer: { name: "niceeval", version: "1.0.0" } });
@@ -882,7 +565,7 @@ describe("createResultsWriter", () => {
   });
 
   it("facts:attempt 级随 writeAttempt 落进 result.json、experiment 级随 finish() 落进 snapshot.json,两级原样读回不合并,空 facts 省略字段", async () => {
-    // cases: docs/engineering/testing/unit/results.md「Usage、facts 与失败命令证据落盘」——
+    // cases: docs/engineering/testing/unit/record.md「Usage、facts 与失败命令证据落盘」——
     // 两级 facts 各自独立落盘与读回,读取面不把 attempt facts 与 snapshot facts 混在一起。
     const root = await makeRoot();
     const writer = createResultsWriter(root, { producer: { name: "niceeval", version: "1.0.0" } });