niceeval 0.4.5 → 0.5.0

package/src/report/tree.ts

@@ -0,0 +1,220 @@
+// 报告的元素树与双面组件基座(docs/reports.md「元素树与两个宿主」「双面组件」)。
+//
+// 报告函数返回的树不是「React 树」,只是 { type, props } 节点 —— 标准 react
+// jsx-runtime 产的元素恰好就是这个形状。本文件是基础实现:零 react 运行时依赖
+// (只有类型层的 `import type`,编译后擦除);text 宿主遍历渲染不需要 react-dom,
+// web 宿主(web.ts)才真正 import react。渲染面是纯同步函数:零 IO、零 await ——
+// 计算全部发生在报告函数体里,可达百 MB 的工件永远不进渲染路径。
+
+import type { ReactNode } from "react";
+import type { AttemptRef } from "../results/index.ts";
+
+// ───────────────────────── 节点形状 ─────────────────────────
+
+/** 标准 jsx-runtime 元素形状;text 宿主只认 type / props,不管 $$typeof。 */
+export interface ReportElement {
+  type: unknown;
+  props: Record<string, unknown>;
+  key?: unknown;
+}
+
+/** 报告树节点:元素、文本、数组 / Fragment 的儿子们,或渲染为空的空值。 */
+export type ReportNode = ReportElement | string | number | boolean | null | undefined | ReportNode[];
+
+// react/jsx-runtime 的 Fragment 是注册符号,跨 react 版本稳定;不 import react 也认得它
+const REACT_FRAGMENT = Symbol.for("react.fragment");
+
+function isReportElement(node: unknown): node is ReportElement {
+  return (
+    typeof node === "object" &&
+    node !== null &&
+    !Array.isArray(node) &&
+    "type" in node &&
+    "props" in node &&
+    typeof (node as ReportElement).props === "object"
+  );
+}
+
+// ───────────────────────── 双面组件 ─────────────────────────
+
+/** 挂 faces 的私有键:text 宿主与树校验靠它识别双面组件。 */
+export const COMPONENT_FACES: unique symbol = Symbol.for("niceeval.report.faces");
+
+export interface TextContext {
+  /** 可用列宽;Row 分栏后变窄。 */
+  width: number;
+  /** 容器组件渲染 children 用,宽度显式传递。 */
+  render(node: ReportNode, width?: number): string;
+  /** 下钻命令,通证据室。 */
+  attemptCommand(ref: AttemptRef): string;
+}
+
+export interface WebContext {
+  /** 证据室深链,同 view 的 attempt 路由。 */
+  attemptHref(ref: AttemptRef): string;
+}
+
+export interface ComponentFaces<P> {
+  /** 真 React JSX 在这个面里;返回静态可渲染的 ReactNode。 */
+  web(props: P, ctx: WebContext): ReactNode;
+  text(props: P, ctx: TextContext): string;
+}
+
+/**
+ * 双面组件的产物:可直接用于 JSX(React 把它当函数组件调用,走 web 面),
+ * text 宿主经 COMPONENT_FACES 调 text 面。
+ */
+export type ReportComponent<P> = ((props: P) => ReactNode) & {
+  [COMPONENT_FACES]: ComponentFaces<P>;
+  displayName?: string;
+};
+
+// web 面的环境上下文:web 宿主渲染前设好;宿主之外(组件直接嵌进用户 React 应用)
+// 用默认值 —— attemptHref 默认 view 的 attempt 路由格式(自定义组件显式调 ctx.attemptHref
+// 时总有去处);官方组件的「宿主里自动接证据室」只在宿主上下文激活时发生,
+// 宿主外不传 attemptHref 就是纯展示,不发明断链。
+const DEFAULT_WEB_CONTEXT: WebContext = {
+  attemptHref: (ref) => `#/attempt/${ref.run}/${ref.result}`,
+};
+let activeWebContext: WebContext | null = null;
+
+/** web 宿主用:在给定 WebContext 下同步渲染(React 静态渲染本身是同步的)。 */
+export function runWithWebContext<T>(ctx: WebContext, fn: () => T): T {
+  const prev = activeWebContext;
+  activeWebContext = ctx;
+  try {
+    return fn();
+  } finally {
+    activeWebContext = prev;
+  }
+}
+
+/** 官方组件的装配用:宿主上下文激活时才把 ctx.attemptHref 当默认下钻。 */
+export function isHostWebContextActive(): boolean {
+  return activeWebContext !== null;
+}
+
+/**
+ * 定义一个双面组件:faces 两键必填 —— 少实现一个面编译不过,配对是结构义务。
+ * 基础实现不 import react;产物以可调用组件的形状兼容 React 渲染。
+ */
+export function defineComponent<P>(faces: ComponentFaces<P>): ReportComponent<P> {
+  if (typeof faces?.web !== "function" || typeof faces?.text !== "function") {
+    throw new Error(
+      "defineComponent requires both faces: { web(props, ctx), text(props, ctx) }. " +
+        "Every report component must render in both hosts (niceeval view and niceeval show).",
+    );
+  }
+  const component = ((props: P) => faces.web(props, activeWebContext ?? DEFAULT_WEB_CONTEXT)) as ReportComponent<P>;
+  component[COMPONENT_FACES] = faces;
+  return component;
+}
+
+export function facesOf(type: unknown): ComponentFaces<unknown> | undefined {
+  if (typeof type !== "function") return undefined;
+  return (type as Partial<ReportComponent<unknown>>)[COMPONENT_FACES] as ComponentFaces<unknown> | undefined;
+}
+
+// ───────────────────────── 树校验 ─────────────────────────
+
+function componentLabel(type: unknown): string {
+  if (typeof type === "string") return `<${type}>`;
+  if (typeof type === "function") {
+    const name = (type as { displayName?: string; name?: string }).displayName || (type as { name?: string }).name;
+    return name ? `<${name}>` : "<anonymous component>";
+  }
+  if (type === REACT_FRAGMENT) return "<>";
+  return `<${String(type)}>`;
+}
+
+/**
+ * 渲染前树校验:页面树里只放双面组件、排版原语与普通组合函数,字符串 intrinsic
+ * (<div>)报错、指名组件路径。这是运行时校验而非编译期(标准 JSX 下 TS 把一切
+ * JSX 表达式统一成 JSX.Element);两个宿主渲染前跑同一遍 —— 不做单侧宽容,否则
+ * 对着 view 写的页面到 show 才炸。校验只下钻 children(children 就是报告树);
+ * 普通函数组件调用展开(渲染面纯同步,重复调用无副作用)。
+ */
+export function validateReportTree(node: ReportNode, path: string[] = []): void {
+  if (node === null || node === undefined || typeof node === "boolean") return;
+  if (typeof node === "string" || typeof node === "number") return;
+  if (Array.isArray(node)) {
+    for (const child of node) validateReportTree(child, path);
+    return;
+  }
+  if (!isReportElement(node)) return;
+  const { type, props } = node;
+  if (typeof type === "string") {
+    const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+    throw new Error(
+      `Raw HTML <${type}> has no terminal face; use <Text>, layout primitives, or a defineComponent component.${where}`,
+    );
+  }
+  if (type === REACT_FRAGMENT) {
+    validateReportTree(props.children as ReportNode, path);
+    return;
+  }
+  const label = componentLabel(type);
+  if (facesOf(type)) {
+    // 双面组件是校验的信任边界之内的叶子,但 children 仍是报告树的一部分
+    validateReportTree(props.children as ReportNode, [...path, label]);
+    return;
+  }
+  if (typeof type === "function") {
+    // 普通函数组件 = 用户拿函数组合页面片段:调用展开继续校验
+    const expanded = (type as (p: unknown) => ReportNode)(props);
+    validateReportTree(expanded, [...path, label]);
+    return;
+  }
+  const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+  throw new Error(`Unsupported node type ${label} in report tree.${where}`);
+}
+
+// ───────────────────────── text 渲染 ─────────────────────────
+
+export interface TextRenderOptions {
+  /** 终端可用列宽;默认 80。 */
+  width?: number;
+  /** 下钻命令的生成;宿主注入,默认指向 view 的 attempt 路由。 */
+  attemptCommand?: (ref: AttemptRef) => string;
+}
+
+export function createTextContext(options?: TextRenderOptions): TextContext {
+  const width = Math.max(20, options?.width ?? 80);
+  const attemptCommand =
+    options?.attemptCommand ?? ((ref: AttemptRef) => `niceeval view "#/attempt/${ref.run}/${ref.result}"`);
+  const make = (w: number): TextContext => ({
+    width: w,
+    attemptCommand,
+    render(node, childWidth) {
+      return renderNodeToText(node, childWidth === undefined ? this : make(Math.max(10, childWidth)));
+    },
+  });
+  return make(width);
+}
+
+/** text 宿主的遍历渲染:双面组件走 text 面,普通函数调用展开,块之间以换行相接。 */
+export function renderNodeToText(node: ReportNode, ctx: TextContext): string {
+  if (node === null || node === undefined || typeof node === "boolean") return "";
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) {
+    return node
+      .map((child) => renderNodeToText(child, ctx))
+      .filter((text) => text.length > 0)
+      .join("\n");
+  }
+  if (!isReportElement(node)) return "";
+  const { type, props } = node;
+  if (typeof type === "string") {
+    // 校验先行会拦住;这里兜底同一条错误,渲染路径自身也不宽容
+    throw new Error(
+      `Raw HTML <${type}> has no terminal face; use <Text>, layout primitives, or a defineComponent component.`,
+    );
+  }
+  if (type === REACT_FRAGMENT) return renderNodeToText(props.children as ReportNode, ctx);
+  const faces = facesOf(type);
+  if (faces) return faces.text(props, ctx);
+  if (typeof type === "function") {
+    return renderNodeToText((type as (p: unknown) => ReportNode)(props), ctx);
+  }
+  return "";
+}

package/src/report/types.ts

@@ -1,9 +1,10 @@
-// niceeval/report 的公开类型:指标(Metric)、维度(Dimension)与计算函数产物
-// (即 niceeval/report/react 组件的 props)。数据契约照抄 docs/reports.md
-// 「计算函数与数据契约」——这些不是持久化格式,没有 format / schemaVersion 信封;
-// 兼容性跟随 npm 版本。
+// niceeval/report 的公开类型:指标(Metric)、维度(Dimension / param())与计算函数
+// 产物(即组件的 data props)。数据契约照 docs/reports.md「计算函数与数据契约」;
+// 这些不是持久化格式,没有 format / schemaVersion 信封,兼容性跟随 npm 版本。
 
-import type { AttemptHandle } from "../results/types.ts";
+import type { AttemptHandle, AttemptRef, SelectionWarning } from "../results/index.ts";
+
+export type { AttemptRef, SelectionWarning };
 
 // ───────────────────────── 指标与聚合 ─────────────────────────
 
@@ -24,11 +25,12 @@ export interface MetricAggregate {
 /**
  * 指标:纯函数,吃一个 AttemptHandle 吐一个值(null = 此 attempt 测不了这个指标,
  * 不进聚合;0 = 测了结果是零,照常进),外加名字、两级聚合方式和渲染提示。
- * 内置指标与自定义指标是同一个类型,没有特权。
+ * 内置指标与自定义指标是同一个类型,没有特权。name 走字面量泛型:列键锚在指标
+ * 对象上(`row.cells[passRate.name]`),拼错列名编译不过。
  */
-export interface Metric {
+export interface Metric<Name extends string = string> {
   /** MetricColumn.key 与列头的来源;同一次计算里重名是错误。 */
-  name: string;
+  name: Name;
   /** 列头;省略时用 name。 */
   label?: string;
   description?: string;
@@ -47,8 +49,10 @@ export interface Metric {
   display?: (value: number) => string;
 }
 
+// ───────────────────────── 维度 ─────────────────────────
+
 /**
- * 维度:attempt 分到哪一组。内置维度就是 EvalResult 已有的身份字段;自定义维度是一个函数。
+ * 维度:attempt 分到哪一组。内置维度就是结果已有的身份字段;自定义维度是一个函数。
  * - "evalGroup" = eval id 的第一段:"algebra/quadratic" → "algebra"(考试里的「科目」)
  * - "snapshot"  = "<experimentId> @ <startedAt>",把两次快照并排成行,与 view 的 Compare 同口径
  */
@@ -61,7 +65,23 @@ export type Dimension =
   | "snapshot"
   | { name: string; of: (attempt: AttemptHandle) => string };
 
-// ───────────────────────── 计算产物(组件 props)─────────────────────────
+/**
+ * param() 的产物:把 experiment 声明的 params 当维度(series / rows / columns / points
+ * 槽,按声明值分组)或轴(MetricLine 的 x 槽,要求数值并驱动刻度)。
+ * 未声明该 param 的 experiment 不猜:分组如实归「(unset)」,作轴不画点、注脚报数。
+ */
+export interface ParamRef {
+  readonly kind: "param";
+  readonly name: string;
+  /** 组标签 / 轴标签;函数形态把声明值折成组名(如 `(v) => \`${v} agents\``)。 */
+  readonly label?: string | ((value: string | number | boolean) => string);
+  readonly unit?: string;
+}
+
+/** 维度槽的输入:内置/自定义维度,或 experiment 声明的 param。 */
+export type DimensionInput = Dimension | ParamRef;
+
+// ───────────────────────── 计算产物(组件 data props)─────────────────────────
 
 export interface MetricColumn {
   /** = metric.name,与 cells 的键对应。 */
@@ -81,20 +101,19 @@ export interface MetricCell {
   samples: number;
   /** 组内 attempt 总数;samples < total = 有 attempt 测不了这个指标。 */
   total: number;
-  /** 这个格子由哪些 attempt 算出 —— 回到证据的引用。 */
-  refs?: AttemptRef[];
+  /**
+   * 这个格子由哪些 attempt 算出 —— 回到证据的引用。必填(可空数组):
+   * 「每个数字点进去就是证据」是页面的核心承诺,可选字段会让深链静默缺失。
+   */
+  refs: AttemptRef[];
 }
 
-// AttemptRef 的家在 niceeval/results:Reports 的 refs、view 深链、copyRun 用同一个证据身份。
-// 这里 import + re-export,公共 API 入口不变。
-import type { AttemptRef } from "../results/types.ts";
-export type { AttemptRef };
-
-export interface TableData {
+/** 列键 K 来自 columns 元组的字面量 name:拼错列名编译不过,不是运行时 undefined。 */
+export interface TableData<K extends string = string> {
   /** 行维度名,如 "agent"。 */
   dimension: string;
   columns: MetricColumn[];
-  rows: { key: string; cells: Record<string, MetricCell> }[];
+  rows: { key: string; cells: Record<K, MetricCell> }[];
 }
 
 export interface MatrixData {
@@ -108,8 +127,12 @@ export interface MatrixData {
 }
 
 export interface ScoreboardData {
-  /** 被打分的维度名,如 "agent"。 */
-  of: string;
+  /**
+   * 被打分的维度名,如 "agent"。
+   * (计算函数的维度槽叫 rows,与 MetricTable.data 统一;数据形状上行数组已占用
+   * rows 一词,维度名沿用 TableData 的 dimension。)
+   */
+  dimension: string;
   fullMarks: number;
   /** 实际生效的权重表(按匹配顺序:最长前缀在前)—— 成绩单可审计。 */
   weights: { prefix: string; weight: number }[];
@@ -151,6 +174,31 @@ export interface ScatterData {
   }[];
 }
 
+/** MetricLine 的 x 轴:experiment 声明的 param,数值驱动刻度。 */
+export interface LineAxis {
+  /** param 名。 */
+  key: string;
+  label: string;
+  unit?: string;
+}
+
+export interface LineData {
+  x: LineAxis;
+  /** 系列维度名(param 或普通维度)。 */
+  series?: string;
+  y: MetricColumn;
+  rows: {
+    /** 点的键(experiment id):每个点 = 一个 experiment 的聚合。 */
+    key: string;
+    series?: string;
+    /** param 声明值;未声明或非数值 → null,点不画、注脚报数。 */
+    x: number | null;
+    /** 已格式化的 x("300 ms");x 为 null 时为空串。 */
+    xDisplay: string;
+    y: MetricCell;
+  }[];
+}
+
 export interface OverviewData {
   snapshots: { experimentId: string; agent: string; model?: string; startedAt: string }[];
   totals: {
@@ -164,27 +212,27 @@ export interface OverviewData {
     costUSD: number | null;
     durationMs: number;
   };
-  /** 选择器的警告透传进来,RunOverview 直接渲染 —— 诚实不靠使用者记得渲染。 */
-  warnings: string[];
+  /** 选集的警告随行(结构化,含渲染好的 message),RunOverview 直接渲染。 */
+  warnings: SelectionWarning[];
 }
 
-export interface DeltaData {
+export interface DeltaData<K extends string = string> {
   columns: MetricColumn[];
   rows: {
     /** pair 的 label,如 "bub"。 */
     key: string;
-    /** 基线侧。 */
+    /** 基线侧:experiment id 或快照键 "<experimentId> @ <startedAt>"。 */
     a: { experimentId: string };
     /** 对比侧。 */
     b: { experimentId: string };
     cells: Record<
-      string,
+      K,
       {
         a: MetricCell;
         b: MetricCell;
         /** b.value - a.value;任一侧 null → null,不硬算。 */
         delta: number | null;
-        /** 已带符号("+12%" / "-$0.80"),涨跌好坏由 better 判定。 */
+        /** 已带符号("+12%" / "-$0.80" / "±0"),涨跌好坏由 better 判定。 */
         display: string;
       }
     >;

package/src/report/web.ts

@@ -0,0 +1,40 @@
+// web 宿主(view --report)的装载入口:同一棵树走 web 面,renderToStaticMarkup 吐静态
+// HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
+// 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
+
+import * as React from "react";
+import type { ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+// tsx 按「tsconfig 所在目录」为界应用 jsx 配置:CLI 在用户项目 cwd 下跑时,包内
+// .tsx(primitives / react 组件的 web 面)落在用户 tsconfig 覆盖范围之外,esbuild
+// 退化成 classic JSX(编译产物引用全局 React)。这里补上全局 React,web 面在两种
+// 编译模式下都可渲染;只定义一次,不覆盖宿主已有的全局。
+const g = globalThis as { React?: unknown };
+if (g.React === undefined) g.React = React;
+import type { AttemptRef } from "../results/index.ts";
+import { runWithWebContext, validateReportTree, type WebContext } from "./tree.ts";
+import { prepareDefaultReportData, runWithDefaultReportData } from "./default-report.tsx";
+import type { ReportContext, ReportDefinition } from "./report.ts";
+
+export interface StaticHtmlOptions {
+  /** 证据室深链;缺省用 view 的 attempt 路由 `#/attempt/<run>/<result>`。 */
+  attemptHref?: (ref: AttemptRef) => string;
+}
+
+/** build → 渲染前树校验(与 text 宿主同一遍)→ 备好官方水位 → 静态渲染 web 面。 */
+export async function renderReportToStaticHtml(
+  definition: ReportDefinition,
+  ctx: ReportContext,
+  options?: StaticHtmlOptions,
+): Promise<string> {
+  const node = await definition.build(ctx);
+  validateReportTree(node);
+  const defaultData = await prepareDefaultReportData(ctx.selection);
+  const webCtx: WebContext = {
+    attemptHref: options?.attemptHref ?? ((ref) => `#/attempt/${ref.run}/${ref.result}`),
+  };
+  return runWithDefaultReportData(defaultData, () =>
+    runWithWebContext(webCtx, () => renderToStaticMarkup(node as ReactNode)),
+  );
+}

package/src/results/copy.ts

@@ -1,26 +1,28 @@
-// copyRun:把选中快照按格式感知地复制到另一个目录(设计见 docs/results-lib.md「复制与瘦身」)。
+// copySnapshots:把选中快照按格式感知地复制到另一个目录(定稿见 docs/results-lib.md「复制与瘦身」)。
 //
 // 发布场景的原语:只带指定工件、只带选中的 attempt,布局知识不外泄。
 // 工件复制忠实于源(copyFile 原字节,不重新序列化、不消毒);summary.json 按选中条目重建,
-// 版本元数据保留,榜单计数按选中条目重算 —— 产物是一个 openResults / `niceeval view`
-// 都能直接读的合法 run 目录。
+// 版本元数据保留,榜单计数按选中条目重算 —— 产物是一个标准 run 目录,openResults /
+// `niceeval view` 直接能读。唯一随行补记的是挑选时的覆盖事实:每个复制出的快照带上
+// knownEvalIds(复制时刻该实验已知的 eval 并集),发布目录上重新 openResults().latest(),
+// 残缺警告被同一套机制重新算出来,不靠发布者转述。
 
-import { copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import type { EvalResult, RunSummary } from "../runner/types.ts";
-import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../runner/types.ts";
-import type { Usage } from "../o11y/types.ts";
+import type { EvalResult, RunSummary, Usage } from "../types.ts";
+import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../types.ts";
 import { artifactFileOf, attemptDirOf } from "./format.ts";
-import { isNewerRun } from "./select.ts";
-import type { ArtifactKind, AttemptHandle, RunHandle, SnapshotHandle } from "./types.ts";
+import { experimentOfSnapshot } from "./open.ts";
+import { isNewerRunDir } from "./select.ts";
+import type { ArtifactKind, AttemptHandle, RunDir, Selection, Snapshot } from "./types.ts";
 import { ARTIFACT_KINDS } from "./types.ts";
 
-export interface CopyRunOptions {
+export interface CopySnapshotsOptions {
   /** 要带上的工件种类;省略 = 全部五类。diff 可达百 MB、o11y 查看器不读,发布时常见地不带。 */
   artifacts?: ArtifactKind[];
 }
 
-export interface CopiedRun {
+export interface CopySnapshotsResult {
   /** 目标 run 目录的绝对路径(summary.json 所在目录)。 */
   dir: string;
   /** 重建后的 summary(与写入磁盘的一致)。 */
@@ -30,30 +32,31 @@ export interface CopiedRun {
 }
 
 /**
- * 把 `snapshots` 里的全部 attempt 复制成 `destDir` 下的一个 run 目录。
- * 快照可以来自不同物理 run(latestPerExperiment 的典型输出);两个 attempt 落到同一
- * 工件目录时保留最新 run 的那份并出 warning —— 复制前先 dedupeAttempts 可避免。
+ * 把选中快照的全部 attempt 复制成 `destDir` 下的一个标准 run 目录。
+ * 输入收 Selection 或手工挑的 Snapshot[](与 Reports 计算函数同一输入约定);
+ * 快照可以来自不同物理 run(latest() 的典型输出)。目标目录非空即报错,不静默覆盖、不合并。
  */
-export async function copyRun(
-  snapshots: SnapshotHandle | SnapshotHandle[],
+export async function copySnapshots(
+  selection: Selection | Snapshot[],
   destDir: string,
-  opts?: CopyRunOptions,
-): Promise<CopiedRun> {
-  const selected = Array.isArray(snapshots) ? snapshots : [snapshots];
+  opts?: CopySnapshotsOptions,
+): Promise<CopySnapshotsResult> {
+  const selected = Array.isArray(selection) ? selection : selection.snapshots;
   if (selected.length === 0) {
     throw new Error(
-      "copyRun got no snapshots to copy. Check the experiments filter, or pass snapshots from openResults()/latestPerExperiment().",
+      "copySnapshots got no snapshots to copy. Check the experiments filter, or pass snapshots from openResults().latest().",
     );
   }
   const kinds = opts?.artifacts ?? [...ARTIFACT_KINDS];
-  const dest = resolve(destDir);
-
-  const sourceRuns = uniqueRuns(selected);
-  for (const run of sourceRuns) {
-    if (resolve(run.dir) === dest) {
-      throw new Error(`copyRun destination ${dest} is a source run directory. Pick a different destination.`);
+  for (const kind of kinds) {
+    if (!ARTIFACT_KINDS.includes(kind)) {
+      throw new Error(
+        `Unknown artifact kind "${String(kind)}" in copySnapshots options. Valid kinds: ${ARTIFACT_KINDS.join(", ")}.`,
+      );
     }
   }
+  const dest = resolve(destDir);
+  await assertEmptyDestination(dest);
 
   // 第一趟:按目标工件目录选出胜者(最新 run 的那份),顺序取首次出现处 —— 两趟避免
   // 「旧的先落盘、新的再去清理覆盖」的中间态。
@@ -70,9 +73,9 @@ export async function copyRun(
         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 copyRun to avoid this.`,
+        `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 (isNewerRun(attempt.run, existing.run)) winners.set(relDir, attempt);
+      if (isNewerRunDir(attempt.runDir, existing.runDir)) winners.set(relDir, attempt);
     }
   }
 
@@ -91,19 +94,37 @@ export async function copyRun(
     results.push(slimForCopy(attempt.result, relDir, copied));
   }
 
-  const summary = rebuildSummary(selected, sourceRuns, results, dest);
+  const summary = rebuildSummary(selected, results, dest);
   await writeFile(join(dest, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
   return { dir: dest, summary, warnings };
 }
 
+/** 目标目录非空即报错:盘上不该出现「我没写的东西被动过」的惊讶;发布脚本要幂等就自己先清目录。 */
+async function assertEmptyDestination(dest: string): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await readdir(dest);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException | null)?.code === "ENOENT") return;
+    throw new Error(
+      `Destination "${dest}" is not a usable directory (${e instanceof Error ? e.message : String(e)}). Pass a new or empty directory.`,
+    );
+  }
+  if (entries.length > 0) {
+    throw new Error(
+      `Destination directory "${dest}" is not empty. copySnapshots never overwrites or merges; delete the directory first if you want to replace it.`,
+    );
+  }
+}
+
 /** 源工件定位:与读取面同一候选顺序(本 run 的 artifactsDir 优先,artifactBase 回退)。 */
 async function findArtifactFiles(
   attempt: AttemptHandle,
   kinds: ArtifactKind[],
 ): Promise<{ kind: ArtifactKind; source: string }[]> {
   const candidates: string[] = [];
-  if (attempt.result.artifactsDir) candidates.push(join(attempt.run.dir, attempt.result.artifactsDir));
-  if (attempt.result.artifactBase) candidates.push(join(dirname(attempt.run.dir), attempt.result.artifactBase));
+  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 found: { kind: ArtifactKind; source: string }[] = [];
   for (const kind of kinds) {
@@ -142,15 +163,11 @@ function slimForCopy(r: EvalResult, relDir: string, copied: Set<ArtifactKind>):
   };
 }
 
-function rebuildSummary(
-  selected: SnapshotHandle[],
-  sourceRuns: RunHandle[],
-  results: EvalResult[],
-  dest: string,
-): RunSummary {
+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 (isNewerRun(run, newest)) newest = run;
+  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;
@@ -171,9 +188,46 @@ function rebuildSummary(
     ...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;
+}
+
+function fallbackUnion(selected: Snapshot[], experimentId: string): string[] {
+  const ids = new Set<string>();
+  for (const snapshot of selected) {
+    if (snapshot.experimentId !== experimentId) continue;
+    for (const ev of snapshot.evals) ids.add(ev.id);
+    for (const known of snapshot.knownEvalIds ?? []) ids.add(known);
+  }
+  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);
@@ -191,10 +245,10 @@ function usageAndCost(results: EvalResult[]): Pick<RunSummary, "usage" | "estima
   return { usage, estimatedCostUSD: cost || undefined };
 }
 
-function uniqueRuns(snapshots: SnapshotHandle[]): RunHandle[] {
-  const runs: RunHandle[] = [];
+function uniqueRuns(snapshots: Snapshot[]): RunDir[] {
+  const runs: RunDir[] = [];
   for (const snapshot of snapshots) {
-    if (!runs.includes(snapshot.run)) runs.push(snapshot.run);
+    if (!runs.includes(snapshot.runDir)) runs.push(snapshot.runDir);
   }
   return runs;
 }