niceeval 0.5.4 → 0.6.1

package/src/results/copy.ts

@@ -1,40 +1,39 @@
-// copySnapshots:把选中快照按格式感知地复制到另一个目录(定稿见 docs/results-lib.md「复制与瘦身」)。
+// copySnapshots:把选中快照按格式感知地复制到另一个目录(定稿见 docs/feature/results/library.md「复制与瘦身」)。
 //
-// 发布场景的原语:只带指定工件、只带选中的 attempt,布局知识不外泄。
-// 工件复制忠实于源(copyFile 原字节,不重新序列化、不消毒);summary.json 按选中条目重建,
-// 版本元数据保留,榜单计数按选中条目重算 —— 产物是一个标准 run 目录,openResults /
+// 发布场景的原语:只带指定 artifact、只带选中快照的全部 attempt,布局知识不外泄。
+// artifact 复制忠实于源(copyFile 原字节,不重新序列化、不消毒);snapshot.json / result.json
+// 按选中条目重建,版本元数据保留。产物是一个标准结果根目录(同布局),openResults /
 // `niceeval view` 直接能读。唯一随行补记的是挑选时的覆盖事实:每个复制出的快照带上
 // knownEvalIds(复制时刻该实验已知的 eval 并集),发布目录上重新 openResults().latest(),
 // 残缺警告被同一套机制重新算出来,不靠发布者转述。
 
 import { copyFile, mkdir, readdir, stat, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-import type { EvalResult, RunSummary, Usage } from "../types.ts";
-import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../types.ts";
-import { artifactFileOf, attemptDirOf } from "./format.ts";
+import { basename, dirname, join, resolve } from "node:path";
+import type { EvalResult } from "../types.ts";
+import { RESULTS_FORMAT } from "../types.ts";
+import { RESULT_FILE, SNAPSHOT_FILE, artifactFileOf, experimentDirOf } from "./format.ts";
 import { experimentOfSnapshot } from "./open.ts";
-import { isNewerRunDir } from "./select.ts";
-import type { ArtifactKind, AttemptHandle, RunDir, Selection, Snapshot } from "./types.ts";
+import { isNewerSnapshot } from "./select.ts";
+import { hashEvalSource, normalizeEvalSource } from "./source-hash.ts";
+import type { ArtifactKind, AttemptHandle, Selection, Snapshot, SnapshotMeta } from "./types.ts";
 import { ARTIFACT_KINDS } from "./types.ts";
 
 export interface CopySnapshotsOptions {
-  /** 要带上的工件种类;省略 = 全部五类。diff 可达百 MB、o11y 查看器不读,发布时常见地不带。 */
+  /** 要带上的 artifact 种类;省略 = 全部六类。diff 可达百 MB,发布时常见地不带;o11y 只有几 KB,报告用 turns 这类 artifact 档指标(见 docs/feature/reports/library.md「内置指标」)时记得带上。 */
   artifacts?: ArtifactKind[];
 }
 
 export interface CopySnapshotsResult {
-  /** 目标 run 目录的绝对路径(summary.json 所在目录)。 */
+  /** 目标结果根目录的绝对路径。 */
   dir: string;
-  /** 重建后的 summary(与写入磁盘的一致)。 */
-  summary: RunSummary;
-  /** 复制过程中的警告(如多个 attempt 落到同一目录);不静默。 */
+  /** 复制过程中的警告(如同一实验选中多个快照);不静默。 */
   warnings: string[];
 }
 
 /**
- * 把选中快照的全部 attempt 复制成 `destDir` 下的一个标准 run 目录。
- * 输入收 Selection 或手工挑的 Snapshot[](与 Reports 计算函数同一输入约定);
- * 快照可以来自不同物理 run(latest() 的典型输出)。目标目录非空即报错,不静默覆盖、不合并。
+ * 把选中快照复制成 `destDir` 下的一个标准结果根目录(`<experiment-dir>/<源快照目录名>/`,
+ * 快照目录名原样保留,身份不变)。输入收 Selection 或手工挑的 Snapshot[]
+ * (与 Reports 计算函数同一输入约定)。目标目录非空即报错,不静默覆盖、不合并。
  */
 export async function copySnapshots(
   selection: Selection | Snapshot[],
@@ -58,45 +57,112 @@ export async function copySnapshots(
   const dest = resolve(destDir);
   await assertEmptyDestination(dest);
 
-  // 第一趟:按目标工件目录选出胜者(最新 run 的那份),顺序取首次出现处 —— 两趟避免
-  // 「旧的先落盘、新的再去清理覆盖」的中间态。
-  const winners = new Map<string, AttemptHandle>();
-  const order: string[] = [];
+  // 同一 experiment 选中多个快照 → 只带最新的那个,记 warning(无胜者逻辑:一旦落到单快照,
+  // 快照内 evalId+attempt 天然唯一)。
+  const byExperiment = new Map<string, Snapshot>();
   const warnings: string[] = [];
   for (const snapshot of selected) {
-    for (const attempt of snapshot.attempts) {
-      const relDir = attemptDirOf(attempt.result);
-      const existing = winners.get(relDir);
-      if (!existing) {
-        winners.set(relDir, attempt);
-        order.push(relDir);
-        continue;
-      }
-      warnings.push(
-        `warning: multiple attempts map to "${relDir}" in the copied run; kept the one from the newest run. Dedupe attempts or re-select snapshots before copySnapshots to avoid this.`,
-      );
-      if (isNewerRunDir(attempt.runDir, existing.runDir)) winners.set(relDir, attempt);
+    const existing = byExperiment.get(snapshot.experimentId);
+    if (!existing) {
+      byExperiment.set(snapshot.experimentId, snapshot);
+      continue;
     }
+    warnings.push(
+      `warning: multiple snapshots selected for experiment "${snapshot.experimentId}"; kept the newest one, dropped the rest. Dedupe with Selection.filter() or pick a single snapshot per experiment before copySnapshots to avoid this.`,
+    );
+    if (isNewerSnapshot(snapshot, existing)) byExperiment.set(snapshot.experimentId, snapshot);
   }
 
-  // 第二趟:复制工件 + 生成瘦身条目(has* 按目标目录里真的有什么重算)。
   await mkdir(dest, { recursive: true });
-  const results: EvalResult[] = [];
-  for (const relDir of order) {
-    const attempt = winners.get(relDir)!;
-    const files = await findArtifactFiles(attempt, kinds);
-    if (files.length > 0) {
-      const attemptDest = join(dest, relDir);
-      await mkdir(attemptDest, { recursive: true });
-      await Promise.all(files.map(({ kind, source }) => copyFile(source, join(attemptDest, artifactFileOf(kind)))));
-    }
-    const copied = new Set(files.map((f) => f.kind));
-    results.push(slimForCopy(attempt.result, relDir, copied));
+  for (const snapshot of byExperiment.values()) {
+    await copyOneSnapshot(snapshot, selected, dest, kinds);
+  }
+
+  return { dir: dest, warnings };
+}
+
+async function copyOneSnapshot(snapshot: Snapshot, selected: Snapshot[], destRoot: string, kinds: ArtifactKind[]): Promise<void> {
+  const destSnapDir = join(destRoot, experimentDirOf(snapshot.experimentId), basename(snapshot.dir));
+  await mkdir(destSnapDir, { recursive: true });
+
+  // sources 的去重仓库(sources/<sha256>.json)是快照级的:同一份源码被多个 attempt 引用时,
+  // 复制到目的地也只应该有一份——这个 Set 记录本快照已经落过盘的 hash,整快照的 attempt 共享。
+  const copiedSourceHashes = new Set<string>();
+  for (const attempt of snapshot.attempts) {
+    await copyOneAttempt(attempt, destSnapDir, kinds, copiedSourceHashes);
   }
 
-  const summary = rebuildSummary(selected, results, dest);
-  await writeFile(join(dest, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
-  return { dir: dest, summary, warnings };
+  const knownEvalIds = experimentOfSnapshot(snapshot)?.evalIds ?? fallbackUnion(selected, snapshot.experimentId);
+  const meta: SnapshotMeta = {
+    format: RESULTS_FORMAT,
+    schemaVersion: snapshot.schemaVersion,
+    producer: snapshot.producer,
+    experimentId: snapshot.experimentId,
+    ...(snapshot.experiment !== undefined ? { experiment: snapshot.experiment } : {}),
+    agent: snapshot.agent,
+    ...(snapshot.model !== undefined ? { model: snapshot.model } : {}),
+    startedAt: snapshot.startedAt,
+    ...(snapshot.completedAt !== undefined ? { completedAt: snapshot.completedAt } : {}),
+    ...(knownEvalIds.length ? { knownEvalIds } : {}),
+    ...(snapshot.name !== undefined ? { name: snapshot.name } : {}),
+  };
+  await writeFile(join(destSnapDir, SNAPSHOT_FILE), JSON.stringify(meta, null, 2), "utf-8");
+}
+
+async function copyOneAttempt(
+  attempt: AttemptHandle,
+  destSnapDir: string,
+  kinds: ArtifactKind[],
+  copiedSourceHashes: Set<string>,
+): Promise<void> {
+  const destAttemptDir = join(destSnapDir, attempt.ref.attempt);
+  await mkdir(destAttemptDir, { recursive: true });
+
+  // sources 是唯一「两层」的 artifact(attempt 级引用 + 快照级去重仓库),不能像其它四类那样
+  // 单文件 copyFile 原字节完事——原字节只是引用,不带内容。走读取面已经会解引用+回退的
+  // attempt.sources() 拿到完整内容,再在目的地按内容哈希重新去重落盘,天然吸收 artifactBase
+  // 回退链(携带条目复制后,原快照可能不在目的地里,必须此刻把内容落到自己脚下)。
+  const genericKinds = kinds.filter((k) => k !== "sources");
+  const files = await findArtifactFiles(attempt, genericKinds);
+  await Promise.all(files.map(({ kind, source }) => copyFile(source, join(destAttemptDir, artifactFileOf(kind)))));
+  const copied = new Set(files.map((f) => f.kind));
+
+  if (kinds.includes("sources")) {
+    const wroteSources = await copySources(attempt, destSnapDir, destAttemptDir, copiedSourceHashes);
+    if (wroteSources) copied.add("sources");
+  }
+
+  const record = slimForCopy(attempt.result, copied);
+  await writeFile(join(destAttemptDir, RESULT_FILE), JSON.stringify(record, null, 2), "utf-8");
+}
+
+/**
+ * sources 的复制:经 attempt.sources() 拿到已解引用的完整内容(null / 空数组 = 没有,不写任何
+ * 文件,与其它 artifact「空数据不落文件」的约定一致),按内容 sha256 写进目的快照的
+ * `sources/<sha256>.json`(同一快照内已经写过的 hash 不重写),attempt 目录下落一份引用。
+ */
+async function copySources(
+  attempt: AttemptHandle,
+  destSnapDir: string,
+  destAttemptDir: string,
+  copiedSourceHashes: Set<string>,
+): Promise<boolean> {
+  const sources = await attempt.sources();
+  if (!sources || sources.length === 0) return false;
+
+  const destStoreDir = join(destSnapDir, "sources");
+  const refs: { path: string; sha256: string }[] = [];
+  for (const src of sources) {
+    const sha256 = hashEvalSource(normalizeEvalSource(src.content));
+    refs.push({ path: src.path, sha256 });
+    if (!copiedSourceHashes.has(sha256)) {
+      await mkdir(destStoreDir, { recursive: true });
+      await writeFile(join(destStoreDir, `${sha256}.json`), JSON.stringify({ content: src.content }), "utf-8");
+      copiedSourceHashes.add(sha256);
+    }
+  }
+  await writeFile(join(destAttemptDir, artifactFileOf("sources")), JSON.stringify(refs), "utf-8");
+  return true;
 }
 
 /** 目标目录非空即报错:盘上不该出现「我没写的东西被动过」的惊讶;发布脚本要幂等就自己先清目录。 */
@@ -117,14 +183,15 @@ async function assertEmptyDestination(dest: string): Promise<void> {
   }
 }
 
-/** 源工件定位:与读取面同一候选顺序(本 run 的 artifactsDir 优先,artifactBase 回退)。 */
+/** 源 artifact 定位:与读取面同一候选顺序(本 attempt 目录优先,artifactBase 回退)。 */
 async function findArtifactFiles(
   attempt: AttemptHandle,
   kinds: ArtifactKind[],
 ): Promise<{ kind: ArtifactKind; source: string }[]> {
-  const candidates: string[] = [];
-  if (attempt.result.artifactsDir) candidates.push(join(attempt.runDir.dir, attempt.result.artifactsDir));
-  if (attempt.result.artifactBase) candidates.push(join(dirname(attempt.runDir.dir), attempt.result.artifactBase));
+  const candidates: string[] = [join(attempt.snapshot.dir, attempt.ref.attempt)];
+  if (attempt.result.artifactBase) {
+    candidates.push(resolve(dirname(dirname(attempt.snapshot.dir)), attempt.result.artifactBase));
+  }
 
   const found: { kind: ArtifactKind; source: string }[] = [];
   for (const kind of kinds) {
@@ -136,88 +203,61 @@ async function findArtifactFiles(
           break;
         }
       } catch {
-        // 缺文件跳过:某类数据为空本来就不生成对应 JSON(docs/results-format.md)。
+        // 缺文件跳过:某类数据为空本来就不生成对应 JSON(docs/feature/results/architecture.md)。
       }
     }
   }
   return found;
 }
 
-/** 瘦身条目:去掉内联大字段与 view 注入的路径字段,artifactsDir / has* 按目标目录重算。 */
-function slimForCopy(r: EvalResult, relDir: string, copied: Set<ArtifactKind>): EvalResult {
-  const { events, sources, o11y, trace, diff, rawTranscript, artifactBase, artifactAbsBase, ...rest } = r;
+/**
+ * 重建 attempt 记录:去掉快照级字段(agent/model/experimentId/experiment,目标 snapshot.json
+ * 已经带了)与 artifactBase(artifact 已本地化,不再需要回退指针);has* 按目标目录实际复制到的
+ * 种类重算。startedAt 是 attempt 级事实(身份键与「何时跑的」都靠它),原样保留。
+ */
+function slimForCopy(r: EvalResult, copied: Set<ArtifactKind>): Record<string, unknown> {
+  const {
+    agent,
+    model,
+    experimentId,
+    experiment,
+    events,
+    sources,
+    o11y,
+    trace,
+    agentSetup,
+    diff,
+    rawTranscript,
+    artifactBase,
+    hasTrace,
+    hasEvents,
+    hasSources,
+    ...rest
+  } = r;
+  void agent;
+  void model;
+  void experimentId;
+  void experiment;
   void events;
   void sources;
   void o11y;
   void trace;
+  void agentSetup;
   void diff;
   void rawTranscript;
   void artifactBase;
-  void artifactAbsBase;
+  void hasTrace;
+  void hasEvents;
+  void hasSources;
   return {
     ...rest,
-    artifactsDir: relDir,
     hasEvents: copied.has("events"),
     hasTrace: copied.has("trace"),
     hasSources: copied.has("sources"),
   };
 }
 
-function rebuildSummary(selected: Snapshot[], results: EvalResult[], dest: string): RunSummary {
-  // 版本元数据与 run 级元数据取最新源 run 的(producer 缺失的 legacy 源保持缺失,不冒充)。
-  const sourceRuns = uniqueRuns(selected);
-  let newest = sourceRuns[0];
-  for (const run of sourceRuns) if (isNewerRunDir(run, newest)) newest = run;
-
-  const counts = { passed: 0, failed: 0, skipped: 0, errored: 0 };
-  for (const r of results) counts[r.outcome] += 1;
-
-  return {
-    format: RESULTS_FORMAT,
-    schemaVersion: RESULTS_SCHEMA_VERSION,
-    ...(newest.summary.producer ? { producer: newest.summary.producer } : {}),
-    ...(newest.summary.name !== undefined ? { name: newest.summary.name } : {}),
-    // 顶层 agent/model 沿用 runner 的「第一个配置」姿势;快照各自的 agent 在条目里。
-    agent: selected[0].agent,
-    ...(selected[0].model !== undefined ? { model: selected[0].model } : {}),
-    startedAt: newest.summary.startedAt,
-    completedAt: newest.summary.completedAt,
-    ...counts,
-    // 跨 run 拼装无法还原墙钟时长,这里是选中 attempt 的耗时合计。
-    durationMs: results.reduce((total, r) => total + (r.durationMs ?? 0), 0),
-    ...usageAndCost(results),
-    results,
-    outputDir: dest,
-    snapshots: snapshotsMeta(selected, newest.summary.startedAt),
-  };
-}
-
-/**
- * 快照级元数据补记:startedAt 保留各快照自己的时刻(它们可能来自不同源 run),
- * knownEvalIds = 复制时刻该实验已知的 eval 并集(openResults 产出的快照从所属实验取,
- * 手工构造的快照退回「同 id 输入快照的覆盖 ∪ 携带值」)—— 残缺检测的分母随数据走。
- */
-function snapshotsMeta(selected: Snapshot[], summaryStartedAt: string): NonNullable<RunSummary["snapshots"]> {
-  // 同一 experiment 被选了多个快照(未 dedupe)时取最新的那个,与工件胜者规则一致。
-  const bySnapshotId = new Map<string, Snapshot>();
-  for (const snapshot of selected) {
-    const existing = bySnapshotId.get(snapshot.experimentId);
-    if (!existing || isNewerRunDir(snapshot.runDir, existing.runDir)) {
-      bySnapshotId.set(snapshot.experimentId, snapshot);
-    }
-  }
-
-  const meta: NonNullable<RunSummary["snapshots"]> = {};
-  for (const [experimentId, snapshot] of bySnapshotId) {
-    const union = experimentOfSnapshot(snapshot)?.evalIds ?? fallbackUnion(selected, experimentId);
-    meta[experimentId] = {
-      ...(snapshot.startedAt !== summaryStartedAt ? { startedAt: snapshot.startedAt } : {}),
-      knownEvalIds: union,
-    };
-  }
-  return meta;
-}
-
+/** experimentOfSnapshot 查不到归属(手工构造的 Snapshot[])时的兜底:同 id 输入快照的覆盖 ∪ 携带值。 */
 function fallbackUnion(selected: Snapshot[], experimentId: string): string[] {
   const ids = new Set<string>();
   for (const snapshot of selected) {
@@ -227,28 +267,3 @@ function fallbackUnion(selected: Snapshot[], experimentId: string): string[] {
   }
   return [...ids].sort();
 }
-
-/** usage / 成本按选中条目重算;口径同 runner 的 summarize(没有任何 usage 就不写)。 */
-function usageAndCost(results: EvalResult[]): Pick<RunSummary, "usage" | "estimatedCostUSD"> {
-  const usages = results.map((r) => r.usage).filter((u): u is Usage => u !== undefined);
-  const cost = results.reduce((total, r) => total + (r.estimatedCostUSD ?? 0), 0);
-  if (usages.length === 0) return { estimatedCostUSD: cost || undefined };
-  const usage: Usage = { inputTokens: 0, outputTokens: 0 };
-  for (const u of usages) {
-    usage.inputTokens += u.inputTokens;
-    usage.outputTokens += u.outputTokens;
-    for (const key of ["cacheReadTokens", "cacheWriteTokens", "requests", "costUSD"] as const) {
-      const value = u[key];
-      if (value !== undefined) usage[key] = (usage[key] ?? 0) + value;
-    }
-  }
-  return { usage, estimatedCostUSD: cost || undefined };
-}
-
-function uniqueRuns(snapshots: Snapshot[]): RunDir[] {
-  const runs: RunDir[] = [];
-  for (const snapshot of snapshots) {
-    if (!runs.includes(snapshot.runDir)) runs.push(snapshot.runDir);
-  }
-  return runs;
-}

package/src/results/format.ts

@@ -1,76 +1,83 @@
-// Results Format 的布局与版本知识,规则见 docs/results-format.md。
+// Results Format 的布局与版本知识,规则见 docs/feature/results/architecture.md。
 //
-// 按 docs/results-lib.md,这份知识只住在本库:写入面(writer.ts / copy.ts)与
+// 按 docs/feature/results/library.md,这份知识只住在本库:写入面(writer.ts / copy.ts)与
 // 读取面(open.ts)共用这里的目录规则与版本判定;src/runner/reporters/artifacts.ts
 // 是 writer 的薄壳,view(src/view/data.ts)经 openResults 消费,不自带布局知识。
 
-import type { EvalResult, RunSummary } from "../types.ts";
+import type { EvalResult } from "../types.ts";
 import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../types.ts";
-import type { ArtifactKind } from "./types.ts";
+import type { ArtifactKind, SnapshotMeta } from "./types.ts";
 
-/** attempt 工件子目录(相对 run 根):<evalId>/<agent>/<model>[/<experimentId>]/a<attempt>。 */
-export function attemptDirOf(r: Pick<EvalResult, "id" | "agent" | "model" | "attempt" | "experimentId">): string {
-  const safe = (s: string) => s.replace(/[^\w.@-]/g, "_");
-  // evalId 里的 / 保留作目录层级,其余危险字符替换。
+/** attempt 目录名:结果记录文件恒为 result.json,attempt 级判决权威落点。 */
+export const RESULT_FILE = "result.json";
+/** 快照元数据文件名。 */
+export const SNAPSHOT_FILE = "snapshot.json";
+
+/** attempt 目录(相对快照根):`<evalId>/a<attempt>`;evalId 里的 / 保留作目录层级,其余危险字符替换。 */
+export function attemptDirOf(r: Pick<EvalResult, "id" | "attempt">): string {
   const id = r.id.replace(/[^\w./@-]/g, "_");
-  // experiment 段:两个实验可以同 agent 同 model、只差实验参数,少这一段它们的工件会互相
-  // 覆盖;experimentId 里的 / 不作层级(整段压成 _),整个实验一格。
-  const exp = r.experimentId ? `/${safe(r.experimentId)}` : "";
-  return `${id}/${safe(r.agent)}/${safe(r.model ?? "default")}${exp}/a${r.attempt}`;
+  return `${id}/a${r.attempt}`;
+}
+
+/** 实验目录名:experimentId 里的 / 与其它非 [\w.@-] 字符替换成 _。 */
+export function experimentDirOf(experimentId: string): string {
+  return experimentId.replace(/[^\w.@-]/g, "_");
 }
 
-/** 工件文件名:种类即文件名。 */
+/**
+ * artifact 文件名。种类名是 TS 侧的驼峰(`agentSetup`),文件名是磁盘侧的 kebab
+ * (`agent-setup.json`)——两边各自守自己的惯例,映射表是唯一的翻译点。
+ */
+const ARTIFACT_FILES: Record<ArtifactKind, string> = {
+  events: "events.json",
+  trace: "trace.json",
+  o11y: "o11y.json",
+  agentSetup: "agent-setup.json",
+  diff: "diff.json",
+  sources: "sources.json",
+};
+
 export function artifactFileOf(kind: ArtifactKind): string {
-  return `${kind}.json`;
+  return ARTIFACT_FILES[kind];
 }
 
-/** summary.json 的版本判定结果;openResults 按它分流 ok / skipped / 静默忽略。 */
-export type SummaryClassification =
-  | { kind: "ok"; summary: RunSummary }
-  | { kind: "incompatible"; schemaVersion: number; producer?: RunSummary["producer"] }
+/** snapshot.json 的版本判定结果;openResults 按它分流 ok / skipped / 静默忽略。 */
+export type SnapshotClassification =
+  | { kind: "ok"; meta: SnapshotMeta }
+  | { kind: "incompatible"; schemaVersion: number; producer?: SnapshotMeta["producer"] }
   | { kind: "malformed"; detail: string }
   | { kind: "not-a-report" };
 
 /**
- * 版本判定与最小形状校验(docs/results-format.md「版本不匹配时的读取行为」):
- * - 带 format 信封:format 不是 niceeval.results → 无关 JSON;schemaVersion 与当前不同 →
- *   不兼容(不解析、不迁移、不降级),缺 schemaVersion 的早期信封按 1 处理。
- * - 无信封:results[] 与 startedAt 同时具备才按 legacy 照读(未知字段忽略);
- *   只沾到一个键的多半是别家工具的 summary.json,按规范当无关 JSON 忽略,不进 skipped 制造噪音。
+ * 版本判定与最小形状校验(docs/feature/results/architecture.md「版本不匹配时的读取行为」):
+ * - 带 format 信封:format 不是 niceeval.results → 无关 JSON;schemaVersion 非数字 → malformed;
+ *   schemaVersion 与当前不同 → 不兼容(不解析、不迁移、不降级),带 schemaVersion 与完整 producer;
+ *   schemaVersion 相同时校验 experimentId / agent / startedAt 均为 string,不满足 → malformed。
+ * - 无信封:v1 的 run 级 summary.json(results[] 是数组且 startedAt 是 string)按 incompatible
+ *   (schemaVersion 1)处理 —— 这是版本识别,不是迁移;不满足启发式的当无关 JSON 忽略。
+ * - v2/v3 的 summary.json 带 format + schemaVersion(≠ 4),自然落进 incompatible 档。
  */
-export function classifySummary(raw: unknown): SummaryClassification {
+export function classifySnapshot(raw: unknown): SnapshotClassification {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     return { kind: "malformed", detail: "not a JSON object" };
   }
-  const data = raw as Partial<RunSummary>;
+  const data = raw as Partial<SnapshotMeta> & { results?: unknown };
   if (data.format !== undefined && data.format !== RESULTS_FORMAT) return { kind: "not-a-report" };
   if (data.format === RESULTS_FORMAT) {
-    const version = data.schemaVersion ?? 1;
-    if (typeof version !== "number") return { kind: "malformed", detail: "schemaVersion is not a number" };
-    if (version !== RESULTS_SCHEMA_VERSION) {
+    if (typeof data.schemaVersion !== "number") return { kind: "malformed", detail: "schemaVersion is not a number" };
+    if (data.schemaVersion !== RESULTS_SCHEMA_VERSION) {
       // skipped 必须带完整 producer(name + version):npx 提示只对 name === "niceeval" 成立,
       // 第三方 harness 的落盘只给裸版本号的话,消费方连做对这个分支的信息都没有。
-      return { kind: "incompatible", schemaVersion: version, producer: data.producer };
+      return { kind: "incompatible", schemaVersion: data.schemaVersion, producer: data.producer };
     }
-    if (!Array.isArray(data.results) || typeof data.startedAt !== "string") {
-      return { kind: "malformed", detail: "missing results[] or startedAt" };
+    if (typeof data.experimentId !== "string" || typeof data.agent !== "string" || typeof data.startedAt !== "string") {
+      return { kind: "malformed", detail: "missing experimentId, agent or startedAt" };
     }
-    return { kind: "ok", summary: data as RunSummary };
+    return { kind: "ok", meta: data as SnapshotMeta };
   }
-  if (!Array.isArray(data.results) || typeof data.startedAt !== "string") {
-    return { kind: "not-a-report" };
+  // 无信封:引入版本信封之前的存量报告(v1 run 级 summary.json)。
+  if (Array.isArray(data.results) && typeof (data as { startedAt?: unknown }).startedAt === "string") {
+    return { kind: "incompatible", schemaVersion: 1 };
   }
-  return { kind: "ok", summary: data as RunSummary };
-}
-
-/**
- * 快照/去重共用的 experiment 身份键:experimentId 缺失时以 "<agent>/<model>" 合成
- * (无 model 用 "default",与工件目录命名同一口径),synthesized 供调用方决定要不要出 warning。
- */
-export function experimentKeyOf(r: Pick<EvalResult, "experimentId" | "agent" | "model">): {
-  id: string;
-  synthesized: boolean;
-} {
-  if (r.experimentId) return { id: r.experimentId, synthesized: false };
-  return { id: `${r.agent}/${r.model ?? "default"}`, synthesized: true };
+  return { kind: "not-a-report" };
 }