niceeval 0.6.1 → 0.7.0

package/src/results/copy.ts

@@ -7,20 +7,38 @@
 // knownEvalIds(复制时刻该实验已知的 eval 并集),发布目录上重新 openResults().latest(),
 // 残缺警告被同一套机制重新算出来,不靠发布者转述。
 
-import { copyFile, mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import type { EvalResult } from "../types.ts";
+import type { EvalResult, StreamEvent, TraceSpan } 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 { 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";
+import {
+  PUBLISH_FILE_MAX_BYTES,
+  redactEvents,
+  redactExperimentInfo,
+  redactJsonValue,
+  redactResultRecord,
+  redactSpans,
+  type Redactor,
+} from "./publish.ts";
+import type { ArtifactKind, AttemptHandle, Scope, Snapshot, SnapshotMeta } from "./types.ts";
+
+/** 缺省携带的 artifact:events / trace / o11y / agentSetup / sources;diff 不截断、可达百 MB,缺省不带。 */
+const DEFAULT_PUBLISH_ARTIFACTS: ArtifactKind[] = ["events", "trace", "o11y", "agentSetup", "sources"];
+const VALID_ARTIFACTS: ArtifactKind[] = ["events", "trace", "o11y", "agentSetup", "diff", "sources"];
 
 export interface CopySnapshotsOptions {
-  /** 要带上的 artifact 种类;省略 = 全部六类。diff 可达百 MB,发布时常见地不带;o11y 只有几 KB,报告用 turns 这类 artifact 档指标(见 docs/feature/reports/library.md「内置指标」)时记得带上。 */
+  /** 要带上的 artifact 种类;缺省带 events / trace / o11y / agentSetup / sources,不带 diff。 */
   artifacts?: ArtifactKind[];
+  /**
+   * 发布消毒(必填,没有隐式默认):传函数逐值消毒自由文本字段,或显式传 `false` 声明
+   * 「这批数据可以原文发布」——「不消毒」必须是写在代码里的选择,不是忘了传参数的副作用。
+   * 结构字段(格式、判定、身份、路径、哈希)永不经过 redactor。
+   */
+  redact: Redactor | false;
 }
 
 export interface CopySnapshotsResult {
@@ -32,25 +50,31 @@ export interface CopySnapshotsResult {
 
 /**
  * 把选中快照复制成 `destDir` 下的一个标准结果根目录(`<experiment-dir>/<源快照目录名>/`,
- * 快照目录名原样保留,身份不变)。输入收 Selection 或手工挑的 Snapshot[]
+ * 快照目录名原样保留,身份不变)。输入收 Scope 或手工挑的 Snapshot[]
  * (与 Reports 计算函数同一输入约定)。目标目录非空即报错,不静默覆盖、不合并。
  */
 export async function copySnapshots(
-  selection: Selection | Snapshot[],
+  scope: Scope | readonly Snapshot[],
   destDir: string,
-  opts?: CopySnapshotsOptions,
+  opts: CopySnapshotsOptions,
 ): Promise<CopySnapshotsResult> {
-  const selected = Array.isArray(selection) ? selection : selection.snapshots;
+  const selected = Array.isArray(scope) ? (scope as readonly Snapshot[]) : (scope as Scope).snapshots;
   if (selected.length === 0) {
     throw new Error(
       "copySnapshots got no snapshots to copy. Check the experiments filter, or pass snapshots from openResults().latest().",
     );
   }
-  const kinds = opts?.artifacts ?? [...ARTIFACT_KINDS];
+  if (opts?.redact === undefined) {
+    throw new Error(
+      'copySnapshots requires an explicit "redact" option: pass a (text) => string sanitizer, or the literal false to declare this data safe to publish verbatim.',
+    );
+  }
+  const redactor: Redactor | undefined = opts.redact === false ? undefined : opts.redact;
+  const kinds = opts.artifacts ?? [...DEFAULT_PUBLISH_ARTIFACTS];
   for (const kind of kinds) {
-    if (!ARTIFACT_KINDS.includes(kind)) {
+    if (!VALID_ARTIFACTS.includes(kind)) {
       throw new Error(
-        `Unknown artifact kind "${String(kind)}" in copySnapshots options. Valid kinds: ${ARTIFACT_KINDS.join(", ")}.`,
+        `Unknown artifact kind "${String(kind)}" in copySnapshots options. Valid kinds: ${VALID_ARTIFACTS.join(", ")}.`,
       );
     }
   }
@@ -68,101 +92,167 @@ export async function copySnapshots(
       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.`,
+      `warning: multiple snapshots selected for experiment "${snapshot.experimentId}"; kept the newest one, dropped the rest. Dedupe with Scope.filter() or pick a single snapshot per experiment before copySnapshots to avoid this.`,
     );
     if (isNewerSnapshot(snapshot, existing)) byExperiment.set(snapshot.experimentId, snapshot);
   }
 
-  await mkdir(dest, { recursive: true });
+  // 发布前整文件预检:先规划并序列化全部目标文件(消毒发生在序列化后、写盘前),任一文件
+  // 超过 PUBLISH_FILE_MAX_BYTES 就整体失败,不留半成品目标目录。
+  const planned: PlannedFile[] = [];
   for (const snapshot of byExperiment.values()) {
-    await copyOneSnapshot(snapshot, selected, dest, kinds);
+    planned.push(...(await planOneSnapshot(snapshot, [...selected], dest, kinds, redactor)));
+  }
+  const oversized = planned.filter((f) => f.bytes.byteLength > PUBLISH_FILE_MAX_BYTES);
+  if (oversized.length > 0) {
+    const lines = oversized.map(
+      (f) =>
+        `  ${f.source ?? f.path}: ${f.bytes.byteLength} bytes (limit ${PUBLISH_FILE_MAX_BYTES}). Exclude that artifact kind from "artifacts", or regenerate the history with the current writer.`,
+    );
+    throw new Error(`copySnapshots publish precheck failed; ${oversized.length} file(s) exceed the 50 MiB publish budget:\n${lines.join("\n")}`);
+  }
+
+  await mkdir(dest, { recursive: true });
+  for (const file of planned) {
+    await mkdir(dirname(file.path), { recursive: true });
+    await writeFile(file.path, file.bytes);
   }
 
   return { dir: dest, warnings };
 }
 
-async function copyOneSnapshot(snapshot: Snapshot, selected: Snapshot[], destRoot: string, kinds: ArtifactKind[]): Promise<void> {
+interface PlannedFile {
+  /** 目标绝对路径。 */
+  path: string;
+  /** 序列化(且已消毒)后的字节。 */
+  bytes: Buffer;
+  /** 源文件路径(预检报错定位用);重建的 json 没有单一源。 */
+  source?: string;
+}
+
+async function planOneSnapshot(
+  snapshot: Snapshot,
+  selected: Snapshot[],
+  destRoot: string,
+  kinds: ArtifactKind[],
+  redactor: Redactor | undefined,
+): Promise<PlannedFile[]> {
   const destSnapDir = join(destRoot, experimentDirOf(snapshot.experimentId), basename(snapshot.dir));
-  await mkdir(destSnapDir, { recursive: true });
+  const planned: PlannedFile[] = [];
 
   // sources 的去重仓库(sources/<sha256>.json)是快照级的:同一份源码被多个 attempt 引用时,
-  // 复制到目的地也只应该有一份——这个 Set 记录本快照已经落过盘的 hash,整快照的 attempt 共享。
-  const copiedSourceHashes = new Set<string>();
+  // 复制到目的地也只应该有一份——这个 Set 记录本快照已经规划过的 hash,整快照的 attempt 共享。
+  const plannedSourceHashes = new Set<string>();
   for (const attempt of snapshot.attempts) {
-    await copyOneAttempt(attempt, destSnapDir, kinds, copiedSourceHashes);
+    planned.push(...(await planOneAttempt(attempt, destSnapDir, kinds, plannedSourceHashes, redactor)));
   }
 
   const knownEvalIds = experimentOfSnapshot(snapshot)?.evalIds ?? fallbackUnion(selected, snapshot.experimentId);
+  const experiment =
+    snapshot.experiment !== undefined && redactor
+      ? (redactExperimentInfo(snapshot.experiment as unknown as Record<string, unknown>, redactor) as unknown as SnapshotMeta["experiment"])
+      : snapshot.experiment;
   const meta: SnapshotMeta = {
     format: RESULTS_FORMAT,
     schemaVersion: snapshot.schemaVersion,
     producer: snapshot.producer,
     experimentId: snapshot.experimentId,
-    ...(snapshot.experiment !== undefined ? { experiment: snapshot.experiment } : {}),
+    ...(experiment !== undefined ? { 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 } : {}),
+    ...(snapshot.name !== undefined
+      ? { name: redactor && typeof snapshot.name === "string" ? redactor(snapshot.name) : snapshot.name }
+      : {}),
+    // 发布根标记只声明流程,不证明结果:applied = 消毒函数对全部自由文本字段跑过;
+    // none = 作者显式的原文发布声明。view --out 的防呆据此分级。
+    publish: { redaction: redactor ? "applied" : "none" },
   };
-  await writeFile(join(destSnapDir, SNAPSHOT_FILE), JSON.stringify(meta, null, 2), "utf-8");
+  planned.push({ path: join(destSnapDir, SNAPSHOT_FILE), bytes: Buffer.from(JSON.stringify(meta, null, 2), "utf-8") });
+  return planned;
 }
 
-async function copyOneAttempt(
+async function planOneAttempt(
   attempt: AttemptHandle,
   destSnapDir: string,
   kinds: ArtifactKind[],
-  copiedSourceHashes: Set<string>,
-): Promise<void> {
+  plannedSourceHashes: Set<string>,
+  redactor: Redactor | undefined,
+): Promise<PlannedFile[]> {
   const destAttemptDir = join(destSnapDir, attempt.ref.attempt);
-  await mkdir(destAttemptDir, { recursive: true });
+  const planned: PlannedFile[] = [];
 
   // sources 是唯一「两层」的 artifact(attempt 级引用 + 快照级去重仓库),不能像其它四类那样
-  // 单文件 copyFile 原字节完事——原字节只是引用,不带内容。走读取面已经会解引用+回退的
-  // attempt.sources() 拿到完整内容,再在目的地按内容哈希重新去重落盘,天然吸收 artifactBase
-  // 回退链(携带条目复制后,原快照可能不在目的地里,必须此刻把内容落到自己脚下)。
+  // 单文件原字节完事——原字节只是引用,不带内容。走读取面已经会解引用+回退的 attempt.sources()
+  // 拿到完整内容,消毒后按(消毒后)内容哈希重新去重落盘——发布根里引用与内容永远一致。
   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));
+  for (const { kind, source } of files) {
+    const raw = await readFile(source);
+    const bytes = redactor ? redactArtifactBytes(kind, raw, redactor) : raw;
+    planned.push({ path: join(destAttemptDir, artifactFileOf(kind)), bytes, source });
+  }
 
   if (kinds.includes("sources")) {
-    const wroteSources = await copySources(attempt, destSnapDir, destAttemptDir, copiedSourceHashes);
-    if (wroteSources) copied.add("sources");
+    const sources = await attempt.sources();
+    if (sources && sources.length > 0) {
+      copied.add("sources");
+      const destStoreDir = join(destSnapDir, "sources");
+      const refs: { path: string; sha256: string }[] = [];
+      for (const src of sources) {
+        const content = redactor ? redactor(src.content) : src.content;
+        const sha256 = hashEvalSource(normalizeEvalSource(content));
+        refs.push({ path: src.path, sha256 });
+        if (!plannedSourceHashes.has(sha256)) {
+          planned.push({
+            path: join(destStoreDir, `${sha256}.json`),
+            bytes: Buffer.from(JSON.stringify({ content }), "utf-8"),
+          });
+          plannedSourceHashes.add(sha256);
+        }
+      }
+      planned.push({
+        path: join(destAttemptDir, artifactFileOf("sources")),
+        bytes: Buffer.from(JSON.stringify(refs), "utf-8"),
+      });
+    }
   }
 
-  const record = slimForCopy(attempt.result, copied);
-  await writeFile(join(destAttemptDir, RESULT_FILE), JSON.stringify(record, null, 2), "utf-8");
+  let record = slimForCopy(attempt.result, copied);
+  if (redactor) record = redactResultRecord(record, redactor);
+  planned.push({ path: join(destAttemptDir, RESULT_FILE), bytes: Buffer.from(JSON.stringify(record, null, 2), "utf-8") });
+  return planned;
 }
 
-/**
- * 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);
+/** 单个 artifact 文件的消毒:按种类解析 JSON、走各自的自由文本标注,重新序列化。 */
+function redactArtifactBytes(kind: ArtifactKind, raw: Buffer, redactor: Redactor): Buffer {
+  try {
+    const parsed = JSON.parse(raw.toString("utf-8")) as unknown;
+    let next: unknown;
+    switch (kind) {
+      case "events":
+        next = redactEvents(parsed as StreamEvent[], redactor);
+        break;
+      case "trace":
+        next = redactSpans(parsed as TraceSpan[], redactor);
+        break;
+      // diff 的 before/after/内容与 o11y 的命令 / 错误 / URL 都是自由文本;路径键为结构字段。
+      case "diff":
+      case "o11y":
+      case "agentSetup":
+        next = redactJsonValue(parsed, redactor);
+        break;
+      default:
+        next = parsed;
     }
+    return Buffer.from(JSON.stringify(next), "utf-8");
+  } catch {
+    // 解析不了的按原字节透传(malformed 数据不该在发布路径上被静默改写)。
+    return raw;
   }
-  await writeFile(join(destAttemptDir, artifactFileOf("sources")), JSON.stringify(refs), "utf-8");
-  return true;
 }
 
 /** 目标目录非空即报错:盘上不该出现「我没写的东西被动过」的惊讶;发布脚本要幂等就自己先清目录。 */

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

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/results/cases.md
 // show / view 宿主等价契约(设计契约:plan/show-view-equivalence.md 完成定义;
 // docs/feature/reports/architecture.md「Selection 是计算入口」;docs/feature/results/library.md「选择快照」)。
 //
@@ -23,7 +24,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { openResults } from "./index.ts";
-import type { Selection, SelectionWarning } from "./index.ts";
+import type { Scope, ScopeWarning } from "./index.ts";
 import { selectCurrentResults, type ResultScope } from "./select.ts";
 import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type Verdict } from "../types.ts";
 import { runShow, type ShowFlags } from "../show/index.ts";
@@ -131,7 +132,7 @@ interface NormSelection {
   experiments: NormExperiment[];
 }
 
-function normalizeWarning(w: SelectionWarning): NormWarning {
+function normalizeWarning(w: ScopeWarning): NormWarning {
   switch (w.kind) {
     case "partial-coverage":
       return { kind: w.kind, experimentId: w.experimentId, covered: w.covered, total: w.total };
@@ -143,7 +144,7 @@ function normalizeWarning(w: SelectionWarning): NormWarning {
   }
 }
 
-function normalizeSelection(selection: Selection): NormSelection {
+function normalizeSelection(selection: Scope): NormSelection {
   return {
     warnings: selection.warnings.map(normalizeWarning),
     experiments: selection.snapshots.map((snapshot) => ({
@@ -166,7 +167,7 @@ function normalizeSelection(selection: Selection): NormSelection {
 async function showText(root: string, patterns: string[], flags: ShowFlags = {}): Promise<string> {
   let out = "";
   let err = "";
-  const code = await runShow(root, patterns, { run: root, ...flags }, {
+  const code = await runShow(root, patterns, { results: root, ...flags }, {
     out: (s) => (out += s),
     err: (s) => (err += s),
     width: 120,
@@ -178,8 +179,8 @@ async function showText(root: string, patterns: string[], flags: ShowFlags = {})
 
 /** view 的 web 面:loadViewScan → 报告槽 HTML(en)。 */
 async function viewHtml(root: string, opts: ViewScanOptions = {}): Promise<string> {
-  const { reportHtml } = await loadViewScan(root, opts);
-  return reportHtml.en;
+  const { reportPages } = await loadViewScan(root, opts);
+  return reportPages.map((page) => page.html.en).join("\n");
 }
 
 /** 两个宿主构造给选择器的 scope 完全同形:验证读源无误,避免"我以为它们一样"。 */
@@ -339,7 +340,7 @@ describe("selectCurrentResults · 现刻水位结构化身份", () => {
     const rootA = await makeRoot();
     const rootB = await makeRoot();
     // 失败 eval 让 id 现于两面(通过 eval 只进折叠子行,不便断言);qa / qb 各根独有。
-    const boom = { assertions: [{ name: "succeeded()", severity: "gate" as const, score: 0, passed: false, detail: "boom" }] };
+    const boom = { assertions: [{ name: "succeeded()", severity: "gate" as const, score: 0, outcome: "failed" as const, detail: "boom" }] };
     await writeSnapshot(rootA, "2026-07-01T08-00-00-000Z", { experimentId: "onlyA/bub", startedAt: "2026-07-01T08:00:00.000Z" }, [res("qa", "failed", boom)]);
     await writeSnapshot(rootB, "2026-07-02T08-00-00-000Z", { experimentId: "onlyB/bub", startedAt: "2026-07-02T08:00:00.000Z" }, [res("qb", "failed", boom)]);
     const normB = normalizeSelection(selectCurrentResults(await openResults(rootB)));
@@ -389,7 +390,7 @@ async function seedPartialRerun(): Promise<string> {
   const root = await makeRoot();
   await writeSnapshot(root, "2026-07-01T08-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-01T08:00:00.000Z" }, [
     res("q1", "passed"),
-    res("q2", "failed", { assertions: [{ name: 'fileChanged("q2.tsx")', severity: "gate", score: 0, passed: false, detail: "file was not modified" }] }),
+    res("q2", "failed", { assertions: [{ name: 'fileChanged("q2.tsx")', severity: "gate", score: 0, outcome: "failed" as const, detail: "file was not modified" }] }),
   ]);
   await writeSnapshot(root, "2026-07-02T08-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-02T08:00:00.000Z" }, [
     res("q1", "passed"),
@@ -404,7 +405,7 @@ async function seedPartialCoverage(): Promise<string> {
     root,
     "2026-07-01T08-00-00-000Z",
     { experimentId: "compare/bub", startedAt: "2026-07-01T08:00:00.000Z", knownEvalIds: ["q1", "q2"] },
-    [res("q1", "failed", { assertions: [{ name: "succeeded()", severity: "gate", score: 0, passed: false, detail: "boom" }] })],
+    [res("q1", "failed", { assertions: [{ name: "succeeded()", severity: "gate", score: 0, outcome: "failed" as const, detail: "boom" }] })],
   );
   return root;
 }
@@ -415,9 +416,10 @@ describe("宿主接线 · show text 面与 view web 面反映同一批事实", (
     const text = await showText(root, []);
     const html = await viewHtml(root);
     for (const face of [text, html]) {
-      expect(face).toContain("compare/bub");
       expect(face).toContain("q2"); // 周一补齐的失败 eval,若宿主回退 results.latest() 就会消失
     }
+    expect(text).toMatch(/\bbub\s+default\s+bub\s+1s\s+50%/);
+    expect(html).toContain('data-sort-value="compare/bub"');
     expect(text).toContain("1 passed / 1 failed");
     expect(html).toContain("50%");
     // 现刻水位覆盖齐全 → 两面都不出 partial-coverage(text: "verdicts cover"; html: data-kind)。
@@ -431,7 +433,7 @@ describe("宿主接线 · show text 面与 view web 面反映同一批事实", (
   it("位置前缀收窄:两扇门都只见范围内的 eval,范围外一致排除", async () => {
     const root = await makeRoot();
     await writeSnapshot(root, "2026-07-01T08-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-01T08:00:00.000Z" }, [
-      res("weather/brooklyn", "failed", { assertions: [{ name: "succeeded()", severity: "gate", score: 0, passed: false, detail: "boom" }] }),
+      res("weather/brooklyn", "failed", { assertions: [{ name: "succeeded()", severity: "gate", score: 0, outcome: "failed" as const, detail: "boom" }] }),
       res("weather/queens", "passed"),
       res("algebra/quadratic", "passed"),
     ]);
@@ -451,20 +453,32 @@ describe("宿主接线 · show text 面与 view web 面反映同一批事实", (
     await writeFile(
       reportPath,
       [
+        "// 手搭新 defineReport 产物(kind + brand + 规范化页列表);组合组件从 ctx.scope 读注入范围。",
         'const FACES = Symbol.for("niceeval.report.faces");',
-        "const Echo = (props) => Echo[FACES].web(props);",
-        "Echo[FACES] = {",
+        'const COMPOSE = Symbol.for("niceeval.report.compose");',
+        "const Leaf = (props) => Leaf[FACES].web(props);",
+        "Leaf[FACES] = {",
         '  web: (props) => "EVALS[" + props.ids + "]",',
         '  text: (props) => "EVALS[" + props.ids + "]",',
         "};",
+        "const Echo = () => { throw new Error(\"compose only\"); };",
+        "Echo[COMPOSE] = (_props, ctx) => ({",
+        '  $$typeof: Symbol.for("react.transitional.element"),',
+        "  type: Leaf,",
+        '  props: { ids: ctx.scope.snapshots.flatMap((s) => s.evals.map((e) => e.id)).sort().join(",") },',
+        "  key: null,",
+        "});",
         "export default {",
+        '  kind: "report",',
         '  [Symbol.for("niceeval.report.definition")]: true,',
-        "  build: (ctx) => ({",
-        '    $$typeof: Symbol.for("react.transitional.element"),',
-        "    type: Echo,",
-        '    props: { ids: ctx.selection.snapshots.flatMap((s) => s.evals.map((e) => e.id)).sort().join(",") },',
-        "    key: null,",
-        "  }),",
+        "  links: [],",
+        "  scripts: [],",
+        "  styles: [],",
+        "  pages: [{",
+        '    id: "report",',
+        '    title: "Report",',
+        '    content: { $$typeof: Symbol.for("react.transitional.element"), type: Echo, props: {}, key: null },',
+        "  }],",
         "};",
         "",
       ].join("\n"),
@@ -497,7 +511,7 @@ function hasPartialCoverageHtml(html: string): boolean {
   it("通过计数一致:同一 fixture 两面反映 3 过 1 败", async () => {
     const root = await makeRoot();
     await writeSnapshot(root, "2026-07-01T08-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-01T08:00:00.000Z" }, [
-      res("q1", "failed", { durationMs: 40_000, estimatedCostUSD: 0.04, assertions: [{ name: "succeeded()", severity: "gate", score: 0, passed: false, detail: "boom" }] }),
+      res("q1", "failed", { durationMs: 40_000, estimatedCostUSD: 0.04, assertions: [{ name: "succeeded()", severity: "gate", score: 0, outcome: "failed" as const, detail: "boom" }] }),
       res("q2", "passed", { durationMs: 2_000, estimatedCostUSD: 0.02 }),
       res("q3", "passed", { durationMs: 2_000, estimatedCostUSD: 0.02 }),
       res("q4", "passed", { durationMs: 2_000, estimatedCostUSD: 0.02 }),

package/src/results/index.ts

@@ -1,6 +1,6 @@
 // niceeval/results —— 实验结果数据的读写库(定稿见 docs/feature/results/library.md、docs/feature/results/architecture.md)。
 //
-// 读:openResults(实验 → 快照 → eval → attempt 分层、skipped、latest() Selection);
+// 读:openResults(实验 → 快照 → eval → attempt 分层、skipped、latest() / current() Scope);
 // 写:createResultsWriter(快照声明 + attempt 增量落盘 + finish 补 completedAt);
 // 发布:copySnapshots(格式感知复制 + knownEvalIds 补记);
 // 身份:dedupeAttempts(跨快照聚合前按 (experimentId, evalId, attempt, startedAt) 去重)、isNewerSnapshot。
@@ -29,9 +29,11 @@ export {
 } from "./locator.ts";
 export {
   buildAnnotatedEvalSource,
+  deriveSendAnnotations,
   type AnnotatedEvalSource,
   type AnnotatedEvalSourceSummary,
   type AnnotatedSourceLine,
+  type SendAnnotation,
 } from "./annotated-source.ts";
 export { loadAnnotatedEvalSource } from "./attempt-source.ts";
 export {
@@ -42,7 +44,13 @@ export {
 } from "./attempt-evidence.ts";
 export { hashEvalSource, normalizeEvalSource } from "./source-hash.ts";
 export { groupIncompatibleVersionSkips, type SkippedVersionGroup } from "./skipped-notice.ts";
-export { dedupeAttempts, isNewerSnapshot } from "./select.ts";
+export {
+  comparabilityConfigOf,
+  dedupeAttempts,
+  deepEqualJson,
+  isNewerSnapshot,
+  type ComparabilityConfig,
+} from "./select.ts";
 export { copySnapshots, type CopySnapshotsOptions, type CopySnapshotsResult } from "./copy.ts";
 export {
   createResultsWriter,
@@ -71,8 +79,8 @@ export {
   type Eval,
   type Experiment,
   type Results,
-  type Selection,
-  type SelectionWarning,
+  type Scope,
+  type ScopeWarning,
   type SkippedDir,
   type Snapshot,
   type SnapshotMeta,

package/src/results/locator.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/results/cases.md
 // AttemptLocator 单测(定稿见 docs/feature/results/library.md「按 locator 寻址一个 attempt」、docs/concepts.md「Attempt 定位符」):
 // 确定性编码、字段敏感(任一身份字段变化都换 locator)、@ 前缀与定长 base36 格式、decode 的语法
 // 校验分支、大批量下的实际无撞车、buildLocatorIndex 的撞车检测(用可注入的 encode 强制制造撞车,
@@ -79,10 +80,6 @@ describe("encodeAttemptLocator · 确定性与格式", () => {
 });
 
 describe("decodeAttemptLocator · 语法校验", () => {
-  it("接受一个真实编码出来的 locator", () => {
-    expect(decodeAttemptLocator(encodeAttemptLocator(id()))).toEqual({ valid: true, scheme: 1 });
-  });
-
   it.each([
     ["", "空字符串"],
     ["7k2m9qz", "缺 @ 前缀"],
@@ -149,24 +146,6 @@ describe("buildLocatorIndex", () => {
     expect(err.message).toContain("collision");
   });
 
-  it("撞车中若第三个身份与已记录身份相同,不重复抛错(只有真正不同的身份对才算撞车)", () => {
-    const sameEncode = (() => {
-      let calls = 0;
-      return (_identity: AttemptIdentity) => {
-        calls++;
-        return `@1samesame` as ReturnType<typeof encodeAttemptLocator>;
-      };
-    })();
-    const identity = id();
-    const index = buildLocatorIndex(
-      [
-        { identity, handle: "first" },
-        { identity, handle: "second" },
-      ],
-      sameEncode,
-    );
-    expect(index.size).toBe(1);
-  });
 });
 
 describe("resolveAttemptLocator", () => {

package/src/results/open.ts

@@ -11,8 +11,9 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import type { EvalResult } from "../types.ts";
 import type { O11ySummary, StreamEvent, TraceSpan } from "../types.ts";
 import type { AgentSetupManifest, DiffData, SourceArtifact } from "../types.ts";
+import { deriveDiffData } from "../scoring/diff.ts";
 import { RESULT_FILE, SNAPSHOT_FILE, artifactFileOf, classifySnapshot } from "./format.ts";
-import { isNewerSnapshot, selectLatest } from "./select.ts";
+import { isNewerSnapshot, selectCurrentResults, selectLatest } from "./select.ts";
 import {
   encodeAttemptLocator,
   resolveAttemptLocator,
@@ -26,7 +27,7 @@ import type {
   Eval,
   Experiment,
   Results,
-  Selection,
+  Scope,
   SkippedDir,
   Snapshot,
   SnapshotMeta,
@@ -170,13 +171,17 @@ export async function openResults(dir: string): Promise<Results> {
 }
 
 function makeResults(experiments: Experiment[], skipped: SkippedDir[]): Results {
-  return {
+  const results: Results = {
     experiments,
     skipped,
-    latest(opts?: { experiments?: string | string[] }): Selection {
+    latest(opts?: { experiments?: string | string[] }): Scope {
       return selectLatest(experiments, opts);
     },
+    current(opts?: { experiments?: string | string[] }): Scope {
+      return selectCurrentResults(results, { experiment: opts?.experiments });
+    },
   };
+  return results;
 }
 
 // ───────────────────────── 目录扫描 ─────────────────────────
@@ -360,7 +365,12 @@ function makeAttempt(snapshot: Snapshot, snapshotDir: string, attemptDir: string
     trace: lazyArtifact<TraceSpan[]>(candidates, "trace", record.trace),
     o11y: lazyArtifact<O11ySummary>(candidates, "o11y", record.o11y),
     agentSetup: lazyArtifact<AgentSetupManifest>(candidates, "agentSetup", record.agentSetup),
-    diff: lazyArtifact<DiffData>(candidates, "diff", record.diff),
+    diff: (() => {
+      // diff.json 落盘的是逐窗口 delta 序列(DiffArtifact);文件级视图在读取面派生。
+      const raw = lazyArtifact<import("../types.ts").DiffArtifact>(candidates, "diff", record.diff);
+      let memo: Promise<DiffData | null> | undefined;
+      return () => (memo ??= raw().then((windows) => (windows === null ? null : deriveDiffData(windows))));
+    })(),
     sources: lazySources(candidates, candidateSnapshotRoots, record.sources),
   };
 }