niceeval 0.5.4 → 0.6.1

package/src/view/data.test.ts

@@ -1,15 +1,21 @@
-// view 数据层(data.ts)的单测:loader 收编到 openResults、统计收编到官方计算函数之后,
-// 守护三件事——skipped 三种原因如实进 viewData(producer 感知的 npx 提示)、榜单是
-// results.latest() 口径(不再跨历史合并)、跨快照去重让 Runs/Traces 不被 --resume 复印件灌票。
+// view 数据层(data.ts)的单测:loader 收编到 openResults、统计整体住进报告槽之后,
+// 守护三件事——skipped 三种原因如实进 viewData(producer 感知的 npx 提示)、报告槽是
+// 现刻水位口径(裸跑经 selectCurrentResults 跨快照合成每 experiment × eval 的最新判定,
+// 与 show 同一函数;en / zh-CN 双语渲染)、跨快照去重让 Runs/Traces 不被 --resume 复印件
+// 灌票。viewData 只携带证据室数据(快照明细 + skipped + 壳元信息),不再有 overview /
+// table / overall 统计产物。
 // 另含 loadLatestResultsPerEval 的续跑携带语义(从旧 loader.test.ts 移植,口径不变)。
+//
+// fixture 直接写新布局(<expDir>/<snapDir>/snapshot.json + <evalId>/a<n>/result.json),
+// 依据是 docs/feature/results/architecture.md 的稳定磁盘契约,不经 writer 运行时 API。
 
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { IncompatibleResultsError, ViewInputError, loadLatestResultsPerEval, loadViewScan } from "./data.ts";
-import { createRunWriter } from "../results/index.ts";
-import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type RunSummary } from "../types.ts";
+import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type Verdict } from "../types.ts";
+import { encodeAttemptLocator } from "../results/locator.ts";
 
 const roots: string[] = [];
 async function makeRoot(): Promise<string> {
@@ -21,52 +27,90 @@ afterEach(async () => {
   await Promise.all(roots.splice(0).map((r) => rm(r, { recursive: true, force: true })));
 });
 
-function res(over: Partial<EvalResult> & Pick<EvalResult, "id" | "agent">): EvalResult {
-  return { outcome: "passed", attempt: 0, durationMs: 1000, assertions: [], ...over };
+type AttemptFixture = Pick<EvalResult, "id" | "verdict"> &
+  Partial<Pick<EvalResult, "attempt" | "durationMs" | "assertions" | "fingerprint" | "startedAt" | "artifactBase" | "hasEvents">>;
+
+function res(id: string, verdict: Verdict, extra: Partial<AttemptFixture> = {}): AttemptFixture {
+  return { id, verdict, attempt: 0, durationMs: 1000, assertions: [], ...extra };
 }
 
-function summaryOf(results: EvalResult[], over: Partial<RunSummary> = {}): RunSummary {
-  const count = (o: EvalResult["outcome"]) => results.filter((r) => r.outcome === o).length;
-  return {
-    format: RESULTS_FORMAT,
-    schemaVersion: RESULTS_SCHEMA_VERSION,
-    producer: { name: "niceeval", version: "0.4.0" },
-    agent: results[0]?.agent ?? "agent",
-    startedAt: "2026-07-01T08:00:00.000Z",
-    completedAt: "2026-07-01T08:10:00.000Z",
-    passed: count("passed"),
-    failed: count("failed"),
-    skipped: count("skipped"),
-    errored: count("errored"),
-    durationMs: 60_000,
-    results,
-    ...over,
-  };
+/** 实验目录名的清洗:与 docs/feature/results/architecture.md 一致(/ 与非 [\w.@-] 换成 _)。 */
+function cleanDirName(id: string): string {
+  return id.replace(/[^\w.@-]/g, "_");
 }
 
-async function writeRun(root: string, dirName: string, summary: unknown): Promise<string> {
-  const dir = join(root, dirName);
+interface SnapshotOpts {
+  experimentId: string;
+  agent?: string;
+  model?: string;
+  startedAt: string;
+  completedAt?: string;
+  schemaVersion?: number;
+  producer?: { name: string; version?: string };
+}
+
+/** 写一份新布局快照:snapshot.json + 各 attempt 的 result.json。返回快照目录绝对路径。 */
+async function writeSnapshot(
+  root: string,
+  expDirName: string,
+  snapDirName: string,
+  opts: SnapshotOpts,
+  results: AttemptFixture[],
+): Promise<string> {
+  const dir = join(root, expDirName, snapDirName);
   await mkdir(dir, { recursive: true });
-  await writeFile(join(dir, "summary.json"), typeof summary === "string" ? summary : JSON.stringify(summary), "utf-8");
+  const meta = {
+    format: RESULTS_FORMAT,
+    schemaVersion: opts.schemaVersion ?? RESULTS_SCHEMA_VERSION,
+    producer: opts.producer ?? { name: "niceeval", version: "0.4.0" },
+    experimentId: opts.experimentId,
+    agent: opts.agent ?? "agent",
+    ...(opts.model !== undefined ? { model: opts.model } : {}),
+    startedAt: opts.startedAt,
+    ...(opts.completedAt !== undefined ? { completedAt: opts.completedAt } : {}),
+  };
+  await writeFile(join(dir, "snapshot.json"), JSON.stringify(meta, null, 2), "utf-8");
+  for (const r of results) {
+    const attemptDir = join(dir, r.id, `a${r.attempt ?? 0}`);
+    await mkdir(attemptDir, { recursive: true });
+    await writeFile(join(attemptDir, "result.json"), JSON.stringify(r, null, 2), "utf-8");
+  }
   return dir;
 }
 
 describe("loadViewScan · skipped 三种原因进 viewData", () => {
   it("incompatible-version / malformed / incomplete 都进 skippedRuns;niceeval 落盘拼 npx 命令,第三方如实报名字不拼", async () => {
     const root = await makeRoot();
-    // 正常 run,页面照常渲染。
-    await writeRun(root, "2026-07-01T08-00-00-000Z", summaryOf([res({ id: "q1", agent: "bub", experimentId: "exp/a", startedAt: "2026-07-01T08:01:00.000Z" })]));
+    // 正常快照,页面照常渲染。
+    await writeSnapshot(root, "exp_a", "2026-07-01T08-00-00-000Z", { experimentId: "exp/a", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z" }, [
+      res("q1", "passed"),
+    ]);
     // 版本不同:niceeval 写的。
-    await writeRun(root, "2026-07-02T08-00-00-000Z", summaryOf([], { schemaVersion: 999, producer: { name: "niceeval", version: "9.9.9" } }));
+    await writeSnapshot(
+      root,
+      "exp_b",
+      "2026-07-02T08-00-00-000Z",
+      { experimentId: "exp/b", startedAt: "2026-07-02T08:00:00.000Z", schemaVersion: 999, producer: { name: "niceeval", version: "9.9.9" } },
+      [],
+    );
     // 版本不同:第三方 harness 写的。
-    await writeRun(root, "2026-07-03T08-00-00-000Z", summaryOf([], { schemaVersion: 999, producer: { name: "otherharness", version: "1.2.3" } }));
+    await writeSnapshot(
+      root,
+      "exp_c",
+      "2026-07-03T08-00-00-000Z",
+      { experimentId: "exp/c", startedAt: "2026-07-03T08:00:00.000Z", schemaVersion: 999, producer: { name: "otherharness", version: "1.2.3" } },
+      [],
+    );
     // 坏 JSON。
-    await writeRun(root, "2026-07-04T08-00-00-000Z", "{not json");
-    // incomplete:有 attempt 工件、没有 summary(run 中途 crash)。
-    await mkdir(join(root, "2026-07-05T08-00-00-000Z", "q1", "bub", "default", "a0"), { recursive: true });
-    await writeFile(join(root, "2026-07-05T08-00-00-000Z", "q1", "bub", "default", "a0", "events.json"), "[]", "utf-8");
+    const malformedDir = join(root, "exp_d", "2026-07-04T08-00-00-000Z");
+    await mkdir(malformedDir, { recursive: true });
+    await writeFile(join(malformedDir, "snapshot.json"), "{not json", "utf-8");
+    // incomplete:有 attempt 落盘、没有 snapshot.json(快照目录建好、元数据没写完的极窄窗口)。
+    const incompleteDir = join(root, "exp_e", "2026-07-05T08-00-00-000Z");
+    await mkdir(join(incompleteDir, "q1", "a0"), { recursive: true });
+    await writeFile(join(incompleteDir, "q1", "a0", "events.json"), "[]", "utf-8");
 
-    const { viewData } = await loadViewScan(root);
+    const { viewData, reportHtml } = await loadViewScan(root);
     const byReason = new Map(viewData.skippedRuns!.map((s) => [s.dir, s]));
     expect(viewData.skippedRuns).toHaveLength(4);
 
@@ -85,171 +129,190 @@ describe("loadViewScan · skipped 三种原因进 viewData", () => {
     const incomplete = [...byReason.values()].find((s) => s.reason === "incomplete")!;
     expect(incomplete.dir).toContain("2026-07-05T08-00-00-000Z");
 
-    // 正常 run 照常进榜单,坏 run 不拖垮整页。
-    expect(viewData.table.rows.map((r) => r.key)).toEqual(["exp/a"]);
+    // 正常快照照常进报告槽(默认报告的榜单),坏快照不拖垮整页。
+    expect(reportHtml.en).toContain("exp/a");
+    expect(viewData.snapshots.map((s) => s.experimentId)).toEqual(["exp/a"]);
   });
 
   it("单文件模式指向版本不同的报告:抛 IncompatibleResultsError(CLI 打印提示退出)", async () => {
     const root = await makeRoot();
-    const dir = await writeRun(root, "2026-07-02T08-00-00-000Z", summaryOf([], { schemaVersion: 999, producer: { name: "niceeval", version: "9.9.9" } }));
-    await expect(loadViewScan(join(dir, "summary.json"))).rejects.toBeInstanceOf(IncompatibleResultsError);
+    const dir = await writeSnapshot(
+      root,
+      "exp_b",
+      "2026-07-02T08-00-00-000Z",
+      { experimentId: "exp/b", startedAt: "2026-07-02T08:00:00.000Z", schemaVersion: 999, producer: { name: "niceeval", version: "9.9.9" } },
+      [],
+    );
+    await expect(loadViewScan(join(dir, "snapshot.json"))).rejects.toBeInstanceOf(IncompatibleResultsError);
   });
 });
 
-describe("loadViewScan · 榜单是 latest 口径,不再跨历史合并", () => {
-  it("同一实验两次 run:榜单格子只反映最新快照;partial-coverage 警告经 overview.warnings 透传", async () => {
+describe("loadViewScan · 报告槽是现刻水位口径,裸跑与局部收窄合成规则一致", () => {
+  it("同一实验两次快照:报告槽跨快照补齐每 eval 的最新判定,不残缺;历史快照仍供证据室", async () => {
     const root = await makeRoot();
     // 周一全量:q1 失败、q2 通过。
-    await writeRun(root, "2026-07-01T08-00-00-000Z", summaryOf([
-      res({ id: "q1", agent: "bub", experimentId: "exp/a", outcome: "failed", startedAt: "2026-07-01T08:01:00.000Z" }),
-      res({ id: "q2", agent: "bub", experimentId: "exp/a", startedAt: "2026-07-01T08:02:00.000Z" }),
-    ], { startedAt: "2026-07-01T08:00:00.000Z" }));
-    // 周二只补跑 q1(通过):latest 快照只盖 1/2 道题。
-    await writeRun(root, "2026-07-02T08-00-00-000Z", summaryOf([
-      res({ id: "q1", agent: "bub", experimentId: "exp/a", startedAt: "2026-07-02T08:01:00.000Z" }),
-    ], { startedAt: "2026-07-02T08:00:00.000Z" }));
+    await writeSnapshot(root, "exp_a", "2026-07-01T08-00-00-000Z", { experimentId: "exp/a", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z" }, [
+      res("q1", "failed"),
+      res("q2", "passed"),
+    ]);
+    // 周二只补跑 q1(通过):latest 快照只盖 1/2 道题,但现刻水位从周一补齐 q2。
+    await writeSnapshot(root, "exp_a", "2026-07-02T08-00-00-000Z", { experimentId: "exp/a", agent: "bub", startedAt: "2026-07-02T08:00:00.000Z" }, [
+      res("q1", "passed"),
+    ]);
 
-    const { viewData } = await loadViewScan(root);
-    const row = viewData.table.rows.find((r) => r.key === "exp/a")!;
-    // 旧的 aggregateRows 会把两次 run 揉在一起(q1 一败一过);latest 口径只看周二快照:全过。
-    expect(row.cells["pass-rate"]!.value).toBe(1);
-    expect(row.cells["pass-rate"]!.refs.length).toBe(1);
+    const { viewData, reportHtml } = await loadViewScan(root);
+    // 现刻水位:q1 取周二(更新,通过),q2 取周一(仅此一次,通过)—— 两题全过(2/2 = 100%),
+    // 不是「只看周二快照的 1/1」。深链分别指向各自的贡献快照(AttemptLocator 由身份元组——
+    // 含快照 startedAt——确定性派生,两个不同快照的 q1/q2 编出两个不同的 locator)。
+    expect(reportHtml.en).toContain("100%");
+    const q1Locator = encodeAttemptLocator({
+      experimentId: "exp/a",
+      snapshotStartedAt: "2026-07-02T08:00:00.000Z",
+      evalId: "q1",
+      attempt: 0,
+    });
+    const q2Locator = encodeAttemptLocator({
+      experimentId: "exp/a",
+      snapshotStartedAt: "2026-07-01T08:00:00.000Z",
+      evalId: "q2",
+      attempt: 0,
+    });
+    expect(reportHtml.en).toContain(`#/attempt/${q1Locator}`); // q1 来自周二
+    expect(reportHtml.en).toContain(`#/attempt/${q2Locator}`); // q2 来自周一
+
+    // 两题都有真实判定,不是伪残缺:报告槽不再出 partial-coverage 警告。
+    expect(reportHtml.en).not.toContain('data-kind="partial-coverage"');
 
-    // 快照元信息:latest 标记 + 每行可标注判决时间。
+    // 证据室的 latest 标记仍按 results.latest() 口径(周二快照),与报告槽 Selection 无关。
     const latest = viewData.snapshots.filter((s) => s.latest);
     expect(latest).toHaveLength(1);
     expect(latest[0]!.startedAt).toBe("2026-07-02T08:00:00.000Z");
-    expect(viewData.composedRuns).toBe(1);
     expect(viewData.lastRunAt).toBe("2026-07-02T08:00:00.000Z");
-
-    // 挑选警告随 OverviewData 进前端,不静默。
-    const kinds = viewData.overview.warnings.map((w) => w.kind);
-    expect(kinds).toContain("partial-coverage");
-    const partial = viewData.overview.warnings.find((w) => w.kind === "partial-coverage")!;
-    expect(partial.message).toContain("1 of 2");
+    // 合成 Selection 的 attempts 来自周一、周二两个物理 run。
+    expect(viewData.composedRuns).toBe(2);
 
     // 历史快照仍在(Runs / Traces 吃全部),但不是 latest。
     const historical = viewData.snapshots.filter((s) => !s.latest);
     expect(historical).toHaveLength(1);
     expect(historical[0]!.results.map((r) => r.id).sort()).toEqual(["q1", "q2"]);
   });
-
-  it("缺 experimentId 的落盘:合成键快照 synthetic: true,synthetic-experiment-id 警告透传", async () => {
-    const root = await makeRoot();
-    await writeRun(root, "2026-07-01T08-00-00-000Z", summaryOf([
-      res({ id: "q1", agent: "bub", model: "gpt-5", startedAt: "2026-07-01T08:01:00.000Z" }),
-    ]));
-    const { viewData } = await loadViewScan(root);
-    expect(viewData.snapshots[0]!.synthetic).toBe(true);
-    expect(viewData.snapshots[0]!.experimentId).toBe("bub/gpt-5");
-    expect(viewData.overview.warnings.map((w) => w.kind)).toContain("synthetic-experiment-id");
-  });
 });
 
 describe("loadViewScan · 跨快照去重(--resume 携带的复印件只算一次)", () => {
-  it("同一 attempt 存在于两份落盘:只保留最新 run 里的那份,attemptRef 落在最新落盘,artifactBase 沿用原 run 工件", async () => {
+  it("同一 attempt 存在于两份落盘:只保留最新快照里的那份,locator 落在最新落盘,artifactBase 沿用原快照 artifact", async () => {
     const root = await makeRoot();
-    const original = res({
-      id: "q1",
-      agent: "bub",
-      experimentId: "exp/a",
-      startedAt: "2026-07-01T08:01:00.000Z",
-      artifactsDir: "artifacts/q1/bub/default/a0",
-      hasEvents: true,
-    });
-    const oldRun = await writeRun(root, "2026-07-01T08-00-00-000Z", summaryOf([original], { startedAt: "2026-07-01T08:00:00.000Z" }));
-    await mkdir(join(oldRun, "artifacts/q1/bub/default/a0"), { recursive: true });
-    await writeFile(join(oldRun, "artifacts/q1/bub/default/a0/events.json"), "[]", "utf-8");
-    // 携带条目:artifactsDir 清空,artifactBase 指向原 run 的工件目录(runner 的 carriedResults 形状)。
-    const carried = { ...original, artifactsDir: undefined, artifactBase: "2026-07-01T08-00-00-000Z/artifacts/q1/bub/default/a0" };
-    await writeRun(root, "2026-07-02T08-00-00-000Z", summaryOf([
-      carried,
-      res({ id: "q2", agent: "bub", experimentId: "exp/a", startedAt: "2026-07-02T08:02:00.000Z", artifactsDir: "artifacts/q2/bub/default/a0" }),
-    ], { startedAt: "2026-07-02T08:00:00.000Z" }));
+    const oldDir = await writeSnapshot(
+      root,
+      "exp_a",
+      "2026-07-01T08-00-00-000Z",
+      { experimentId: "exp/a", agent: "bub", startedAt: "2026-07-01T08:00:00.000Z" },
+      [res("q1", "passed", { hasEvents: true })],
+    );
+    await writeFile(join(oldDir, "q1", "a0", "events.json"), "[]", "utf-8");
+    // 携带条目:startedAt 锚定原快照, artifactBase 指向原快照的 attempt 目录(root 相对)。
+    await writeSnapshot(root, "exp_a", "2026-07-02T08-00-00-000Z", { experimentId: "exp/a", agent: "bub", startedAt: "2026-07-02T08:00:00.000Z" }, [
+      res("q1", "passed", {
+        hasEvents: true,
+        startedAt: "2026-07-01T08:00:00.000Z",
+        artifactBase: "exp_a/2026-07-01T08-00-00-000Z/q1/a0",
+      }),
+      res("q2", "passed"),
+    ]);
 
     const { viewData, artifactDirs } = await loadViewScan(root);
     // 全部快照(Runs/Traces 的数据面)里 q1 只出现一次:复印件不灌票。
     const allResults = viewData.snapshots.flatMap((s) => s.results);
     expect(allResults.filter((r) => r.id === "q1")).toHaveLength(1);
     const q1 = allResults.find((r) => r.id === "q1")!;
-    expect(q1.attemptRef).toEqual({ run: "2026-07-02T08-00-00-000Z", result: 0 }); // 证据身份跟着最新落盘走
-    expect(q1.artifactBase).toBe("2026-07-01T08-00-00-000Z/artifacts/q1/bub/default/a0"); // 工件仍指原 run
-    // 静态导出(--out)能把携带条目的工件一并带走。
-    expect(artifactDirs.get("2026-07-01T08-00-00-000Z/artifacts/q1/bub/default/a0")).toBe(join(oldRun, "artifacts/q1/bub/default/a0"));
+    // 证据身份(locator)跟着最新落盘走:身份元组里的 snapshotStartedAt 是新快照的 startedAt。
+    expect(q1.locator).toBe(
+      encodeAttemptLocator({ experimentId: "exp/a", snapshotStartedAt: "2026-07-02T08:00:00.000Z", evalId: "q1", attempt: 0 }),
+    );
+    expect(q1.artifactBase).toBe("exp_a/2026-07-01T08-00-00-000Z/q1/a0"); // artifact 仍指原快照
+    // 静态导出(--out)能把携带条目的 artifact 一并带走。
+    expect(artifactDirs.get("exp_a/2026-07-01T08-00-00-000Z/q1/a0")).toBe(join(oldDir, "q1", "a0"));
     // 条目全被吸走的旧快照不再出现。
     expect(viewData.snapshots.filter((s) => !s.latest)).toHaveLength(0);
   });
 });
 
-describe("loadViewScan · createRunWriter 写出的落盘直接可读(writer/reader 同一契约)", () => {
-  it("writer roundtrip:默认报告、快照与 attemptRef 都从写入面产物算出", async () => {
+describe("loadViewScan · 新布局落盘直接可读(写入面 / 读取面同一契约)", () => {
+  it("快照与 locator 都从落盘产物算出", async () => {
     const root = await makeRoot();
-    const writer = await createRunWriter(root, { producer: { name: "niceeval", version: "0.4.6" } });
-    const snap = writer.snapshot({
-      experiment: "compare/bub",
-      agent: "bub",
-      model: "gpt-5",
-      startedAt: "2026-07-03T08:00:00.000Z",
-    });
-    await snap.writeAttempt(
-      { id: "q1", outcome: "passed", attempt: 0, durationMs: 1200, assertions: [], estimatedCostUSD: 0.5 },
-      { events: [{ type: "run.started", t: 0 } as never] },
+    await writeSnapshot(
+      root,
+      "compare_bub",
+      "2026-07-03T08-00-00-000Z",
+      { experimentId: "compare/bub", agent: "bub", model: "gpt-5", startedAt: "2026-07-03T08:00:00.000Z" },
+      [
+        res("q1", "passed", { hasEvents: true }),
+        res("q2", "failed"),
+      ],
     );
-    await snap.writeAttempt({ id: "q2", outcome: "failed", attempt: 0, durationMs: 800, assertions: [] });
-    await writer.finish();
 
-    const { viewData } = await loadViewScan(root);
-    expect(viewData.table.rows.map((r) => r.key)).toEqual(["compare/bub"]);
-    expect(viewData.table.rows[0]!.cells["pass-rate"]!.value).toBe(0.5);
-    expect(viewData.overview.totals.evals).toBe(2);
+    const { viewData, reportHtml } = await loadViewScan(root);
+    // 报告槽(ExperimentComparison 的 web 面):Experiment 工作台行 + 官方通过率格子(1 过 1 败 = 50%)。
+    expect(reportHtml.en).toContain("compare/bub");
+    expect(reportHtml.en).toContain("50%");
     const snapshot = viewData.snapshots[0]!;
     expect(snapshot.latest).toBe(true);
     expect(snapshot.agent).toBe("bub");
-    expect(snapshot.results.every((r) => r.attemptRef?.run === snapshot.run)).toBe(true);
-    // 写入面拆出的工件,读取面拼回相对 view 根的 artifactBase。
+    expect(snapshot.run).toBe("compare_bub/2026-07-03T08-00-00-000Z");
+    // 每条结果的 locator 都能由身份元组(experimentId/快照 startedAt/evalId/attempt 下标)独立复算,
+    // 证明它不是随手塞的占位值,而是真从落盘产物(snapshot.json + result.json)算出来的。
+    expect(snapshot.results.every((r) => r.locator === encodeAttemptLocator({
+      experimentId: snapshot.experimentId,
+      snapshotStartedAt: snapshot.startedAt,
+      evalId: r.id,
+      attempt: r.attempt,
+    }))).toBe(true);
+    // 本快照跑出的条目落盘没有 artifactBase 字段:读取面按 `${ref.snapshot}/${ref.attempt}` 现算,
+    // ref.snapshot 恒等于 snapshot.run,ref.attempt 恒是 `${evalId}/a${attempt}`。
     const q1 = snapshot.results.find((r) => r.id === "q1")!;
     expect(q1.hasEvents).toBe(true);
-    expect(q1.artifactBase).toBe(`${snapshot.run}/${q1.artifactsDir}`);
+    expect(q1.artifactBase).toBe(`${snapshot.run}/q1/a0`);
   });
 });
 
 describe("loadLatestResultsPerEval(续跑携带基线,口径与旧 loader 一致)", () => {
-  it("部分补跑 run 只遮蔽它跑过的 eval,其它 eval 仍取自更早的全量 run", async () => {
+  it("部分补跑快照只遮蔽它跑过的 eval,其它 eval 仍取自更早的全量快照", async () => {
     const root = await makeRoot();
-    await writeRun(root, "2026-01-01T00-00-00", summaryOf([
-      res({ id: "e1", agent: "a", experimentId: "exp/a" }),
-      res({ id: "e2", agent: "a", experimentId: "exp/a", outcome: "errored" }),
-      res({ id: "e1", agent: "a", experimentId: "exp/b" }),
-    ], { startedAt: "2026-01-01T00:00:00.000Z" }));
+    await writeSnapshot(root, "exp_a", "2026-01-01T00-00-00-000Z", { experimentId: "exp/a", agent: "a", startedAt: "2026-01-01T00:00:00.000Z" }, [
+      res("e1", "passed"),
+      res("e2", "errored"),
+    ]);
+    await writeSnapshot(root, "exp_b", "2026-01-01T00-00-00-000Z", { experimentId: "exp/b", agent: "a", startedAt: "2026-01-01T00:00:00.000Z" }, [
+      res("e1", "passed"),
+    ]);
     // 部分补跑:只重跑了 exp/a 的 e2
-    await writeRun(root, "2026-01-02T00-00-00", summaryOf([
-      res({ id: "e2", agent: "a", experimentId: "exp/a" }),
-    ], { startedAt: "2026-01-02T00:00:00.000Z" }));
+    await writeSnapshot(root, "exp_a", "2026-01-02T00-00-00-000Z", { experimentId: "exp/a", agent: "a", startedAt: "2026-01-02T00:00:00.000Z" }, [
+      res("e2", "passed"),
+    ]);
 
     const results = await loadLatestResultsPerEval(root);
-    const byKey = new Map(results.map((r) => [`${r.experimentId}|${r.id}`, r.outcome]));
-    expect(byKey.get("exp/a|e1")).toBe("passed"); // 来自旧全量 run,没被部分 run 冲掉
-    expect(byKey.get("exp/a|e2")).toBe("passed"); // 来自补跑 run(最新)
+    const byKey = new Map(results.map((r) => [`${r.experimentId}|${r.id}`, r.verdict]));
+    expect(byKey.get("exp/a|e1")).toBe("passed"); // 来自旧全量快照,没被部分快照冲掉
+    expect(byKey.get("exp/a|e2")).toBe("passed"); // 来自补跑快照(最新)
     expect(byKey.get("exp/b|e1")).toBe("passed");
     expect(results).toHaveLength(3);
   });
 
-  it("同 (experiment, eval) 多 attempt 整批取自含它的最新 run,不跨 run 混装;artifactBase 已拼好", async () => {
+  it("同 (experiment, eval) 多 attempt 整批取自含它的最新快照,不跨快照混装;artifactBase 已拼好", async () => {
     const root = await makeRoot();
-    await writeRun(root, "2026-01-01T00-00-00", summaryOf([
-      res({ id: "e1", agent: "a", experimentId: "exp/a", fingerprint: "old" }),
-    ], { startedAt: "2026-01-01T00:00:00.000Z" }));
-    await writeRun(root, "2026-01-02T00-00-00", summaryOf([
-      res({ id: "e1", agent: "a", experimentId: "exp/a", outcome: "failed", fingerprint: "new", artifactsDir: "artifacts/e1/a0" }),
-      res({ id: "e1", agent: "a", experimentId: "exp/a", attempt: 1, fingerprint: "new" }),
-    ], { startedAt: "2026-01-02T00:00:00.000Z" }));
+    await writeSnapshot(root, "exp_a", "2026-01-01T00-00-00-000Z", { experimentId: "exp/a", agent: "a", startedAt: "2026-01-01T00:00:00.000Z" }, [
+      res("e1", "passed", { fingerprint: "old" }),
+    ]);
+    await writeSnapshot(root, "exp_a", "2026-01-02T00-00-00-000Z", { experimentId: "exp/a", agent: "a", startedAt: "2026-01-02T00:00:00.000Z" }, [
+      res("e1", "failed", { fingerprint: "new" }),
+      res("e1", "passed", { attempt: 1, fingerprint: "new" }),
+    ]);
 
     const results = await loadLatestResultsPerEval(root);
     expect(results).toHaveLength(2);
     expect(results.every((r) => r.fingerprint === "new")).toBe(true);
-    // runner 携带条目时依赖 artifactBase(相对结果根)可解析,view 才找得回工件。
-    const withArtifacts = results.find((r) => r.artifactsDir)!;
-    expect(withArtifacts.artifactBase).toBe("2026-01-02T00-00-00/artifacts/e1/a0");
+    // runner 携带条目时依赖 artifactBase(相对结果根)可解析,view 才找得回 artifact。
+    const withArtifact = results.find((r) => r.attempt === 0)!;
+    expect(withArtifact.artifactBase).toBe("exp_a/2026-01-02T00-00-00-000Z/e1/a0");
   });
 });
 
@@ -262,15 +325,23 @@ describe("loadViewScan · 零可读结果直说,不渲染空页面", () => {
 
   it("全被跳过:错误逐条列目录与原因,niceeval 落盘的 schemaVersion 场景给出可跑的 npx 命令", async () => {
     const root = await makeRoot();
-    await writeRun(root, "2026-07-02T08-00-00-000Z", summaryOf([], { schemaVersion: 999, producer: { name: "niceeval", version: "9.9.9" } }));
-    await writeRun(root, "2026-07-04T08-00-00-000Z", "{not json");
+    await writeSnapshot(
+      root,
+      "exp_b",
+      "2026-07-02T08-00-00-000Z",
+      { experimentId: "exp/b", startedAt: "2026-07-02T08:00:00.000Z", schemaVersion: 999, producer: { name: "niceeval", version: "9.9.9" } },
+      [],
+    );
+    const malformedDir = join(root, "exp_d", "2026-07-04T08-00-00-000Z");
+    await mkdir(malformedDir, { recursive: true });
+    await writeFile(join(malformedDir, "snapshot.json"), "{not json", "utf-8");
 
     const err = await loadViewScan(root).then(
       () => { throw new Error("expected ViewInputError"); },
       (e) => e as Error,
     );
     expect(err).toBeInstanceOf(ViewInputError);
-    expect(err.message).toContain("2 run directories were skipped");
+    expect(err.message).toContain("2 snapshot directories were skipped");
     expect(err.message).toContain("incompatible-version, schemaVersion 999");
     expect(err.message).toContain("npx niceeval@9.9.9 view ");
     expect(err.message).toContain("malformed");