niceeval 0.11.1 → 0.11.3

package/src/results/select.test.ts

@@ -0,0 +1,438 @@
+// cases: docs/engineering/testing/unit/sample.md
+// 选择层(niceeval/sample)的单测:在临时目录里构造最小落盘树,直接调选择器,
+// 覆盖定稿契约(docs/feature/sample/library.md):两个选择口径、覆盖缺口(coverage)、
+// 时效与 fresh、Sample 的删减语义与四面同步重算、身份键去重、警告 kind 全集。
+// fixture 的目录名/artifact 路径手写(不 import 库的路径函数),让测试独立于实现充当口径基准。
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import {
+  RESULTS_FORMAT,
+  RESULTS_SCHEMA_VERSION,
+  copySnapshots,
+  createResultsWriter,
+  dedupeAttempts,
+  openResults,
+  resolveLocator,
+  loadAnnotatedEvalSource,
+  LocatorNotFoundError,
+  MalformedLocatorError,
+  LocatorCollisionError,
+  encodeAttemptLocator,
+  type AttemptHandle,
+  type EvalResult,
+  type ResultsWriter,
+  type Results,
+  type Snapshot,
+  type SnapshotMeta,
+} from "./index.ts";
+
+// ───────────────────────── fixture 工具 ─────────────────────────
+
+const roots: string[] = [];
+async function makeRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "niceeval-results-"));
+  roots.push(root);
+  return root;
+}
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((r) => rm(r, { recursive: true, force: true })));
+});
+
+/** 测试便利:封口一个 writer 已声明的全部 Snapshot(finish() 现在是 SnapshotWriter 的方法,
+ *  每个 Snapshot 各自只能封一次;多数测试不关心逐个 Snapshot 分别封口,只要「全部封完」)。 */
+async function finishAll(writer: ResultsWriter): Promise<void> {
+  const snapshots = await writer.snapshotWriters();
+  await Promise.all(snapshots.map(({ writer: snap }) => snap.finish()));
+}
+
+function meta(over: { experimentId: string; agent: string; startedAt: string } & Partial<SnapshotMeta>): SnapshotMeta {
+  return {
+    format: RESULTS_FORMAT,
+    schemaVersion: RESULTS_SCHEMA_VERSION,
+    producer: { name: "niceeval", version: "0.3.0" },
+    ...over,
+  };
+}
+
+function record(over: { id: string; attempt: number } & Record<string, unknown>): EvalResult {
+  return { verdict: "passed", durationMs: 1000, assertions: [], ...over } as unknown as EvalResult;
+}
+
+async function writeSnapshot(root: string, expDir: string, snapDirName: string, m: SnapshotMeta): Promise<string> {
+  const dir = join(root, expDir, snapDirName);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "snapshot.json"), JSON.stringify(m, null, 2), "utf-8");
+  return dir;
+}
+
+async function writeResultFile(snapDir: string, relAttemptDir: string, r: unknown): Promise<string> {
+  const dir = join(snapDir, relAttemptDir);
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, "result.json");
+  await writeFile(path, JSON.stringify(r, null, 2), "utf-8");
+  return path;
+}
+
+async function writeArtifactFile(snapDir: string, relAttemptDir: string, file: string, data: unknown): Promise<string> {
+  const dir = join(snapDir, relAttemptDir);
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, file);
+  await writeFile(path, JSON.stringify(data), "utf-8");
+  return path;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ───────────────────────── 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",
+    producer: { name: "niceeval" },
+    schemaVersion: RESULTS_SCHEMA_VERSION,
+    evals: [],
+    attempts: [],
+    ...over,
+  };
+}
+
+function fakeAttempt(snapshot: Snapshot, result: EvalResult): AttemptHandle {
+  return {
+    evalId: result.id,
+    experimentId: snapshot.experimentId,
+    result,
+    ref: { snapshot: "x/y", attempt: `${result.id}/a${result.attempt}` },
+    snapshot,
+    carried: Boolean(result.artifactBase),
+    commands: async () => null,
+    events: async () => null,
+    trace: async () => null,
+    o11y: async () => null,
+    agentSetup: async () => null,
+    diff: async () => null,
+    sources: async () => null,
+  };
+}
+
+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");
+  });
+});

package/src/results/select.ts

@@ -1,4 +1,4 @@
-// 快照 Scope 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「官方现刻水位」「身份键与去重」)。
+// 快照 Scope 与 attempt 去重(定稿见 docs/feature/record/library.md「选择快照」「官方现刻水位」「身份键与去重」)。
 //
 // 选择器长在集合上(results.latest() / results.current()),不是 DSL,只是最常用的两种口径。
 // 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Scope 走 ——
@@ -42,7 +42,7 @@ export function selectLatest(
     // fresh: true 只保留新执行的 attempt——在 latest() 口径下,选中集合永远只有这一份
     // 快照,「所属快照早于该实验在 Scope 中最新快照」这条历史出身天生不成立(只有它自己),
     // 唯一的历史出身是携带条目(attempt.carried)。只过滤显式物化的 attempts 集,不克隆/
-    // 改写来源 Snapshot 的 evals(见 docs/feature/results/library.md「选择快照」)。
+    // 改写来源 Snapshot 的 evals(见 docs/feature/record/library.md「选择快照」)。
     const picked = fresh ? raw.attempts.filter((a) => !a.carried) : raw.attempts;
     attempts.push(...picked);
 
@@ -85,7 +85,7 @@ export interface ResultScope {
 // ───────────────────────── 可比性配置 ─────────────────────────
 
 /**
- * current() 跨快照拼接的可比性前提所比较的字段集(docs/feature/results/library.md
+ * current() 跨快照拼接的可比性前提所比较的字段集(docs/feature/record/library.md
  * 「官方现刻水位」):会改变单题被测行为或判定的字段。runs / earlyExit / maxConcurrency /
  * selectedEvalIds / evalFilterFingerprint / description 是编排与选题字段,不参与比较。
  */
@@ -134,7 +134,7 @@ export function deepEqualJson(a: unknown, b: unknown): boolean {
 /**
  * 一个快照实际选中的 eval id 全集:优先读落盘的 `experiment.selectedEvalIds`(niceeval 自己的
  * 写入面必有此字段);第三方 harness 未实现该字段时退化为该快照实际写出的 `evals`,不把整份
- * 来源排除在外(见 docs/feature/results/architecture.md「selectedEvalIds」)。
+ * 来源排除在外(见 docs/feature/record/architecture.md「selectedEvalIds」)。
  */
 export function selectedEvalIdsOf(snapshot: Snapshot): readonly string[] {
   return snapshot.experiment?.selectedEvalIds ?? snapshot.evals.map((ev) => ev.id);
@@ -146,7 +146,7 @@ export function selectedEvalIdsOf(snapshot: Snapshot): readonly string[] {
  * 快照」,带 eval 前缀的局部重跑会产出残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,
  * 所以在实验的历史快照上逐 eval 向更早的 run 补齐——但补齐只发生在 `Scope.attempts` 这份
  * 物化选择上,真正贡献过至少一道题的来源 Snapshot 原样进 `Scope.snapshots`,不重建、不
- * 合并成报告专用对象(见 docs/feature/results/library.md「官方现刻水位」)。
+ * 合并成报告专用对象(见 docs/feature/record/library.md「官方现刻水位」)。
  *
  * **可比性前提**:每个 experiment 以最新快照的可比性配置(agent / model / reasoningEffort /
  * flags / budget / timeoutMs / sandbox)为基准,只有配置与基准深相等的历史快照才参与补齐;
@@ -419,7 +419,7 @@ export function filterExperiments(experiments: Experiment[], filter?: string | s
 /**
  * 时效标注(`↩` + 人话时距)的粒度选择:选粒度最大的单位,四舍五入。结构化形态是单源——
  * entity-lists 渲染面的紧凑时距("3d")与曾经的 stale-snapshot message 用同一套阈值,
- * 阈值不写两份(docs/feature/reports/library/entity-lists.md「时效标注」)。
+ * 阈值不写两份(docs/feature/reports/components/entity-lists/README.md「时效标注」)。
  */
 export function gapParts(fromIso: string, toIso: string): { n: number; unit: "second" | "minute" | "hour" | "day" } {
   const ms = Math.max(0, Date.parse(toIso) - Date.parse(fromIso));

package/src/results/skipped-notice.ts

@@ -16,7 +16,7 @@ export interface SkippedVersionGroup {
 /**
  * 把 `skipped` 拆成「可按版本分组给出统一 npx 建议的」与「其余原样列出的」两部分。
  * 只有 reason 为 `incompatible-version` 且 `producer.name === "niceeval"`、`producer.version`
- * 存在时才分组——第三方 harness 如实报名字版本、不拼 npx(docs/feature/results/library.md 的裁决);
+ * 存在时才分组——第三方 harness 如实报名字版本、不拼 npx(docs/feature/record/library.md 的裁决);
  * 版本信息缺失时也没有可执行的统一建议,归入 `rest`。分组键是 `(producer.version, schemaVersion)`,
  * 因为同一 producer.version 理论上 schemaVersion 恒定,但落盘可能来自更旧的 patch 版本,
  * 拆开更保守。

package/src/results/truncate.ts

@@ -1,4 +1,4 @@
-// 落盘大值截断(见 docs/feature/results/architecture.md「大值截断」)。
+// 落盘大值截断(见 docs/feature/record/architecture.md「大值截断」)。
 // 运行时全量,落盘截断:落点唯一在 snap.writeAttempt(writer.ts)——不在 adapter、不在 OTLP
 // 解析、不在事件归一化里做。适用范围:events.json 的事件字段与 trace.json 的 span 属性里的
 // 任意字符串值。没有 flag、没有配置项;截断永远不影响判决(落盘是证据,不是评分输入)。
@@ -90,7 +90,7 @@ export function truncateSpans(spans: readonly TraceSpan[]): TraceSpan[] {
 }
 
 /** commands.json 落盘前的截断:每条证据的 stdout / stderr 逐值截断,`truncated[].path` 固定
- *  是 "stdout" 或 "stderr"(见 docs/feature/results/architecture.md「commandsjson」）。 */
+ *  是 "stdout" 或 "stderr"(见 docs/feature/record/architecture.md「commandsjson」）。 */
 export function truncateCommands(commands: readonly FailedCommandEvidence[]): FailedCommandEvidence[] {
   return commands.map((cmd) => {
     const out: Truncation[] = [];

package/src/results/types.ts

@@ -1,4 +1,4 @@
-// results 域类型:openResults 的分层读取契约与 Selection(定稿见 docs/feature/results/library.md、docs/feature/results/architecture.md)。
+// results 域类型:openResults 的分层读取契约与 Selection(定稿见 docs/feature/record/library.md、docs/feature/record/architecture.md)。
 //
 // 结果数据类型(EvalResult / ExperimentRunInfo / StreamEvent / …)仍住在各自的域文件里,
 // 这里只 import,不搬家 —— 「类型的家」迁移(facade 反向 re-export)是下一波,不在本次范围。
@@ -11,7 +11,7 @@ import type { FailedCommandEvidence, O11ySummary, StreamEvent, TraceSpan } from
 import type { AgentSetupManifest, DiffData, SourceArtifact } from "../types.ts";
 import type { AttemptLocator } from "./locator.ts";
 
-/** attempt 级 artifact 的种类;文件名见 format.ts 的 artifactFileOf,布局见 docs/feature/results/architecture.md。 */
+/** attempt 级 artifact 的种类;文件名见 format.ts 的 artifactFileOf,布局见 docs/feature/record/architecture.md。 */
 export const ARTIFACT_KINDS = ["commands", "events", "trace", "o11y", "agentSetup", "diff", "sources"] as const;
 export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
 
@@ -25,7 +25,7 @@ export interface Producer {
 /**
  * `snapshot.json` 的持久化契约:快照元数据 —— 身份、快照级字段与版本元数据,
  * 不含任何逐 attempt 数据。快照开始时写入;收尾时补写 `completedAt`。
- * 字段规则与版本判定见 docs/feature/results/architecture.md「snapshot.json」「版本与升级设计」。
+ * 字段规则与版本判定见 docs/feature/record/architecture.md「snapshot.json」「版本与升级设计」。
  */
 export interface SnapshotMeta {
   /** 恒为 "niceeval.results";和 schemaVersion、producer 一起构成持久化契约,永不移动或改名。 */
@@ -50,7 +50,7 @@ export interface SnapshotMeta {
   diagnostics?: DiagnosticRecord[];
   /**
    * experiment 作用域生命周期代码经 `ctx.fact()` 上报的运行事实;与 completedAt 同批在快照
-   * 封口补写。字段契约见 result.json 的 facts 小节(docs/feature/results/architecture.md#facts运行事实)。
+   * 封口补写。字段契约见 result.json 的 facts 小节(docs/feature/record/architecture.md#facts运行事实)。
    */
   facts?: Record<string, string | number | boolean>;
   /** 写入时刻该实验已知的 eval 并集 —— 残缺检测的分母随数据走(copySnapshots 自动补记,writer 可声明)。 */
@@ -98,7 +98,7 @@ export interface AttemptHandle {
   /**
    * 携带条目投影:true = fingerprint 未变、上一轮终态结果合入本快照(`result.artifactBase`
    * 有值);false = 本快照那次运行真实执行。`startedAt` 为原执行时刻,不因携带而改写
-   * (时效语义见 docs/feature/results/library.md「时效:新执行与历史执行」)。
+   * (时效语义见 docs/feature/sample/library.md「时效:新执行与历史执行」)。
    */
   carried: boolean;
   /** 非零 Sandbox 命令的 stdout/stderr 证据(`commands.json`);没有失败命令时 null。 */
@@ -196,7 +196,7 @@ export interface Results {
    * 每个实验取最新一次快照,返回 Scope(快照与挑选警告绑在一起走)。
    * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
    * `fresh: true` 只保留新执行的 attempt(排除携带条目),被排除的题按覆盖事实进入
-   * `coverage.missingEvalIds`(见 docs/feature/results/library.md「时效:新执行与历史执行」)。
+   * `coverage.missingEvalIds`(见 docs/feature/sample/library.md「时效:新执行与历史执行」)。
    */
   latest(opts?: { experiments?: string | string[]; fresh?: boolean }): Scope;
   /**
@@ -204,7 +204,7 @@ export interface Results {
    * 跨历史拼出当前判定水位。可比性前提:每个 experiment 以最新快照的可比性配置
    * (agent / model / reasoningEffort / flags / budget / timeoutMs / sandbox)为基准,
    * 配置不一致的旧快照不贡献 attempt,缺口进 `coverage.missingEvalIds`
-   * (见 docs/feature/results/library.md「官方现刻水位」)。`fresh: true` 同 `latest()`。
+   * (见 docs/feature/record/library.md「官方现刻水位」)。`fresh: true` 同 `latest()`。
    */
   current(opts?: { experiments?: string | string[]; fresh?: boolean }): Scope;
 }
@@ -212,7 +212,7 @@ export interface Results {
 /**
  * 一个实验的覆盖事实:已知 eval 并集(分母)与当前口径下没有任何 attempt 的题。
  * `missingEvalIds` 永远被算出来,不静默——渲染面把它转成榜单占位行
- * (见 docs/feature/results/library.md「选择快照」「时效:新执行与历史执行」)。
+ * (见 docs/feature/sample/library.md「选择快照」「时效:新执行与历史执行」)。
  */
 export interface ScopeCoverage {
   experimentId: string;
@@ -250,7 +250,7 @@ export interface Scope {
 /**
  * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;能用一条命令直接推进的
  * kind 同时带 `command`(已替换真实 id,复制即跑)。kind 是契约的一部分,全集与触发条件见
- * docs/feature/results/library.md「警告 kind 全集」——三种都是**定位不到任何一行**的完整性
+ * docs/feature/record/library.md「警告 kind 全集」——三种都是**定位不到任何一行**的完整性
  * 事实:覆盖缺口(行级事实,见 `ScopeCoverage`)与时效(`AttemptHandle.carried` 投影的行级
  * 属性)不在这个联合里。
  */

package/src/results/writer.ts

@@ -1,4 +1,4 @@
-// createResultsWriter:Results Format 的写入面(定稿见 docs/feature/results/library.md「写:createResultsWriter」)。
+// createResultsWriter:Results Format 的写入面(定稿见 docs/feature/record/library.md「写:createResultsWriter」)。
 //
 // writer 与 reader 是同一组类型的两半,而且是字面的两半:reader 的 attempt.result 由
 // 「snapshot() 声明的快照级字段(experimentId / agent / model / startedAt / experiment)+
@@ -83,7 +83,7 @@ export interface AttemptArtifacts {
   agentSetup?: AgentSetupManifest;
   diff?: DiffArtifact;
   sources?: SourceArtifact[];
-  /** 非零 Sandbox 命令的 stdout/stderr 证据(见 docs/feature/results/architecture.md「commandsjson」)。 */
+  /** 非零 Sandbox 命令的 stdout/stderr 证据(见 docs/feature/record/architecture.md「commandsjson」)。 */
   commands?: FailedCommandEvidence[];
 }
 
@@ -351,7 +351,7 @@ async function writeAttemptFiles(
   // 大值截断只发生在这里(序列化的那一刻):events 的事件字段、trace 的 span 属性与 commands
   // 的 stdout/stderr 里的任意字符串值按 ARTIFACT_VALUE_MAX_BYTES 截断并留结构化 truncated
   // 标记;运行时(断言 / o11y 派生)看到的始终是完整值。sources 与 diff 不截断(见
-  // docs/feature/results/architecture.md)。
+  // docs/feature/record/architecture.md)。
   if (hasCommands)
     writes.push(
       writeFile(join(attemptDir, artifactFileOf("commands")), JSON.stringify(truncateCommands(artifacts!.commands!)), "utf-8"),
@@ -456,7 +456,7 @@ async function createSnapshotDir(root: string, experimentId: string): Promise<st
 
 
 
-/** 快照目录名的时间戳段:Date#toISOString 把 : 与 . 换成 -(与 docs/feature/results/architecture.md 一致)。 */
+/** 快照目录名的时间戳段:Date#toISOString 把 : 与 . 换成 -(与 docs/feature/record/architecture.md 一致)。 */
 function safeTimestamp(d: Date): string {
   return d.toISOString().replace(/[:.]/g, "-");
 }

package/src/runner/attempt.test.ts

@@ -3,11 +3,11 @@
 // ctx.fact() 的作用域归属单测在本文件末尾单独一个 describe 块:sandbox hook / eval.setup /
 // agent setup·send·teardown 上报的 fact 是否真的落进同一个 attempt 的 EvalResult.facts、
 // 同 key 后写覆盖先写、非法 key / 非标量 value 是否完整报错(见
-// docs/feature/results/architecture.md#facts运行事实)。
+// docs/feature/record/architecture.md#facts运行事实)。
 //
 // 路径提升单测:agent.setup 写进沙箱 `__niceeval__/agent-setup.json` 的安装 manifest,
 // runAttemptEffect 在 setup 之后把它读出来、原样挂到 EvalResult.agentSetup(见
-// docs/feature/results/architecture.md「agent-setup.json」、src/agents/manifest.ts 的注释)。
+// docs/feature/record/architecture.md「agent-setup.json」、src/agents/manifest.ts 的注释)。
 // 沙箱是内存 fake(记文件,不起容器)——这里要验的是运行器自己「何时读、读到什么、读不到
 // 怎么办」这段编排逻辑,不是 adapter 侧的 manifest 构造规则(那部分已在 agents/skills.test.ts
 // 覆盖)。