niceeval 0.6.1 → 0.6.2

package/src/o11y/tool-names.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
 // 工具名归一的回归锁:canonical ToolName 是跨 agent 断言(calledTool("file_read"))
 // 的命中基础。这里逐 agent 锁死关键映射,防止基表 / per-agent 差异表重构时悄悄漂移
 // (曾发生:Claude Code 的裸名 Read/Write/Edit 在一次表合并中归一成了 "unknown")。

package/src/o11y/types.ts

@@ -53,11 +53,22 @@ export interface InputRequest {
   readonly options?: readonly { id: string; label?: string }[];
 }
 
+/**
+ * 落盘截断的结构化标记(见 docs/feature/results/architecture.md「大值截断」):
+ * `path` 是被截断的位置(事件里是字段名,如 "output";span 里是 attribute key,如 "output.value"),
+ * `originalBytes` 是截断前的 UTF-8 字节数。view 显示「输出过大,已截断」靠它,不正则匹配 marker。
+ */
+export interface Truncation {
+  path: string;
+  originalBytes: number;
+}
+
 /**
  * 标准事件流的词汇(对标 docs/feature/adapters/architecture/events.md)。adapter 唯一的硬活就是把
  * 各 agent 五花八门的原始 transcript 映射成 StreamEvent[];映射完,整套断言免费。
+ * `truncated` 只由 results writer 在落盘时刻写入(运行时全量,落盘截断);adapter 不产出它。
  */
-export type StreamEvent =
+export type StreamEvent = { truncated?: Truncation[] } & (
   /** 一条文本消息(assistant 回复或 user 输入);`loc` 是可选的源码位置,用于把消息叠回 eval 源码。 */
   | { type: "message"; role: "assistant" | "user"; text: string; loc?: SourceLoc }
   /** 发起一次工具/动作调用;`tool` 是归一化后的规范工具名,原始名保留在 DerivedFacts.ToolCall.originalName。 */
@@ -85,7 +96,8 @@ export type StreamEvent =
   /** 上下文被压缩/摘要(如超长会话截断历史);`reason` 是可选的压缩原因说明。 */
   | { type: "compaction"; reason?: string }
   /** 运行中出现的错误。 */
-  | { type: "error"; message: string };
+  | { type: "error"; message: string }
+);
 
 /** core 从事件流折叠出的结构化事实(deriveRunFacts)。 */
 export interface ToolCall {
@@ -145,6 +157,8 @@ export interface TraceSpan {
   kind?: SpanKind;
   /** OTLP span 属性(gen_ai.* / tool 名 / token 等),按 key 摊平。raw 属性始终保留供下钻。 */
   attributes?: Record<string, JsonValue>;
+  /** 落盘截断标记(只由 results writer 在序列化时写入,运行时全量;见 Truncation)。 */
+  truncated?: Truncation[];
 }
 
 /** 给人 / 给 EVAL.ts 看的 o11y 摘要(注入沙箱 __niceeval__/results.json)。 */

package/src/report/aggregate.ts

@@ -9,6 +9,8 @@ import type { AttemptHandle, Selection, SelectionWarning, Snapshot } from "../re
 import { encodeAttemptLocator, type AttemptLocator } from "../results/locator.ts";
 import type {
   Aggregator,
+  AxisInput,
+  ConfigRef,
   DimensionInput,
   Metric,
   MetricCell,
@@ -115,29 +117,56 @@ function isFlagRef(dimension: DimensionInput): dimension is FlagRef {
   return typeof dimension === "object" && "kind" in dimension && dimension.kind === "flag";
 }
 
+function isConfigRef(dimension: DimensionInput): dimension is ConfigRef {
+  return typeof dimension === "object" && "kind" in dimension && dimension.kind === "config";
+}
+
 /** experiment 声明的 flags(经 runner 原样透传进持久化字段 ExperimentRunInfo.flags)。 */
 function flagsOf(attempt: AttemptHandle): Record<string, unknown> | undefined {
   return attempt.result.experiment?.flags;
 }
 
+/**
+ * config() 的取值:读快照的 `ExperimentRunInfo` 投影(快照优先;第三方落盘只把投影拼在
+ * 条目上时回退 result.experiment),外加桥接到快照顶层权威字段的 `model` / `agent` 两个键
+ * (与 "model" / "agent" 内置维度同一读法,不另造第二套口径)。未投影 → undefined。
+ */
+function configValueOf(ref: ConfigRef, item: Item): unknown {
+  if (ref.name === "model") return item.attempt.result.model ?? item.snapshot.model;
+  if (ref.name === "agent") return item.attempt.result.agent || item.snapshot.agent;
+  const info = item.snapshot.experiment ?? item.attempt.result.experiment;
+  // ExperimentRunInfo 是穷尽可序列化投影;按字段名取值,新增投影字段无需改这里
+  return (info as Record<string, unknown> | undefined)?.[ref.name];
+}
+
 /** flag 声明值 → 组标签:label 函数优先,其余 String();未声明 → FLAG_UNSET。 */
 export function flagGroupKey(ref: FlagRef, item: Item): string {
-  const value = flagsOf(item.attempt)?.[ref.name];
+  return refGroupKey(ref, flagsOf(item.attempt)?.[ref.name]);
+}
+
+/** config 投影值 → 组标签,规则与 flagGroupKey 一致;未投影 → FLAG_UNSET。 */
+export function configGroupKey(ref: ConfigRef, item: Item): string {
+  return refGroupKey(ref, configValueOf(ref, item));
+}
+
+function refGroupKey(ref: FlagRef | ConfigRef, value: unknown): string {
   if (value === undefined) return FLAG_UNSET;
-  // 持久化字段是 Record<string, unknown>;声明侧的合法值就是这三种标量
+  // 声明侧的合法标量就是这三种;非标量投影(sandbox / selectedEvalIds…)如实 JSON 化,不猜
   if (typeof ref.label === "function") return ref.label(value as string | number | boolean);
+  if (typeof value === "object" && value !== null) return JSON.stringify(value);
   return String(value);
 }
 
-/** flag 作轴:要求数值;未声明或非数值 → null(点不画,注脚报数)。 */
-export function flagAxisValue(ref: FlagRef, item: Item): number | null {
-  const value = flagsOf(item.attempt)?.[ref.name];
+/** flag / config 作轴:要求数值;未声明、未投影或非数值 → null(点不画,注脚报数)。 */
+export function axisValue(ref: AxisInput, item: Item): number | null {
+  const value = ref.kind === "flag" ? flagsOf(item.attempt)?.[ref.name] : configValueOf(ref, item);
   return typeof value === "number" ? value : null;
 }
 
 export function dimensionKey(dimension: DimensionInput, item: Item): string {
   if (typeof dimension !== "string") {
     if (isFlagRef(dimension)) return flagGroupKey(dimension, item);
+    if (isConfigRef(dimension)) return configGroupKey(dimension, item);
     return dimension.of(item.attempt);
   }
   const result = item.attempt.result;

package/src/report/built-in-user-parity.test.tsx

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
 // Phase 4 验收:证明内置报告 ExperimentComparison 与一份普通用户 --report 文件走的是
 // 完全同一套机制 —— 不是长得像,而是同一条 build → resolveReportTree → validate → render 管线。
 //
@@ -9,17 +10,17 @@
 //   3. 两份分别过 renderReportToText / renderReportToStaticHtml,比较事实(散点键 / 表格行 /
 //      attempt 深链),不做 HTML 字面 snapshot。
 //   4. 覆盖 plan 的 9 个必测场景。
-//   5. 架构不变量:renderer 源码零 "ExperimentComparison" / "built-ins" 分支。
-//   6. show / view 只在「无 --report」分支选内置报告,--report 只换 definition,不碰
-//      Selection / resolve / validate / render。
+//   5. 架构不变量:renderer 模块的 import 依赖图不含 built-ins。
+// (show / view 的宿主选择与装载边界等价由 src/show/show.test.ts、src/view/view-report.test.ts 覆盖。)
 
 import { readFileSync } from "node:fs";
 import { renderToStaticMarkup } from "react-dom/server";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 
 import type { EvalResult, Verdict } from "../types.ts";
 import type { AttemptHandle, Results, Selection, Snapshot } from "../results/index.ts";
 import type { ExperimentListItem, ScatterData } from "./types.ts";
+import type { ExperimentComparisonData } from "./built-ins/index.ts";
 import { encodeAttemptLocator } from "../results/locator.ts";
 import { Col, ExperimentList, defineReport } from "./index.ts";
 import { ExperimentComparison } from "./built-ins/index.ts";
@@ -34,7 +35,6 @@ import {
   validateReportTree,
   type ReportNode,
 } from "./tree.ts";
-import * as compute from "./compute.ts";
 
 // ───────────────────────── fake Selection / Snapshot(按 results 读取契约造)─────────────────────────
 
@@ -139,7 +139,10 @@ function richContext() {
         agent: "codex",
         model: "gpt-codex",
         results: [
-          res("algebra/x", "errored", { error: "adapter crashed", estimatedCostUSD: 0.3 }),
+          res("algebra/x", "errored", {
+            error: { code: "unexpected-error", message: "adapter crashed", phase: "eval.run" },
+            estimatedCostUSD: 0.3,
+          }),
           res("algebra/y", "skipped"),
           res("algebra/z", "passed", { usage: { inputTokens: 1, outputTokens: 1, costUSD: 0.15 } }),
         ],
@@ -251,6 +254,12 @@ function experimentListOf(tree: ReportNode): ExperimentListItem[] | undefined {
   return collect(tree).find((c) => c.label === "ExperimentList")?.props.items as ExperimentListItem[] | undefined;
 }
 
+function comparisonDataOf(tree: ReportNode): ExperimentComparisonData | undefined {
+  return collect(tree).find((c) => c.label === "ExperimentComparison")?.props.data as
+    | ExperimentComparisonData
+    | undefined;
+}
+
 /** HTML 里所有 attempt 深链,排序后便于集合比较。 */
 function hrefsOf(html: string): string[] {
   return [...html.matchAll(/href="(#\/attempt\/[^"]+)"/g)].map((m) => m[1]).sort();
@@ -289,17 +298,16 @@ describe("resolved 树结构化等价(built-in ≡ 包外 public-copy)", () => {
       const builtIn = await resolvedTreeOf(ExperimentComparison, c);
       const user = await resolvedTreeOf(publicCopy, ctx()); // 各用一份等价 ctx,证明不依赖共享状态
 
-      // 组件类型与顺序:<Col> 包 [MetricScatter, ExperimentList],别无它物。
+      // build 面只把预计算分组数据交给公开组合件，没有 renderer 私有节点。
       const labels = collect(builtIn).map((n) => n.label);
-      expect(labels).toEqual(["Col", "MetricScatter", "ExperimentList"]);
+      expect(labels).toEqual(["ExperimentComparison"]);
       expect(collect(user).map((n) => n.label)).toEqual(labels);
 
       // 逐节点结构化相等:组件类型、顺序、resolved data、props keys(pointHref/filter/…)全一致。
       expect(factify(user)).toEqual(factify(builtIn));
 
       // resolved data 本身也逐字段相等(不只是树同构)。
-      expect(scatterOf(user)).toEqual(scatterOf(builtIn));
-      expect(experimentListOf(user)).toEqual(experimentListOf(builtIn));
+      expect(comparisonDataOf(user)).toEqual(comparisonDataOf(builtIn));
     });
   }
 });
@@ -309,15 +317,19 @@ describe("resolved 树结构化等价(built-in ≡ 包外 public-copy)", () => {
 describe("必测场景:resolved data 事实", () => {
   it("场景 1+2:多 experiment/agent,成本与通过率都有值;缺成本的点如实 x=null,实验列表仍出项", async () => {
     const tree = await resolvedTreeOf(ExperimentComparison, richContext());
-    const scatter = scatterOf(tree)!;
-    const experiments = experimentListOf(tree)!;
-
-    // 散点:points=experiment、series=agent、x=cost、y=pass-rate
+    const data = comparisonDataOf(tree)!;
+    expect(data.groups.map((group) => group.key)).toEqual(["compare", "solo"]);
+    const compare = data.groups[0]!;
+    const soloGroup = data.groups[1]!;
+    const scatter = compare.scatter;
+    const experiments = [...compare.experiments, ...soloGroup.experiments];
+
+    // 散点:points=experiment、series=agent、x=cost、y=end-to-end-pass-rate
     expect(scatter.points).toBe("experiment");
     expect(scatter.series).toBe("agent");
     expect(scatter.x.key).toBe("cost");
-    expect(scatter.y.key).toBe("pass-rate");
-    expect(scatter.rows.map((r) => r.key).sort()).toEqual(["compare/bub-low", "compare/codex-mid", "solo/no-cost"]);
+    expect(scatter.y.key).toBe("end-to-end-pass-rate");
+    expect(scatter.rows.map((r) => r.key).sort()).toEqual(["compare/bub-low", "compare/codex-mid"]);
 
     const bub = scatter.rows.find((r) => r.key === "compare/bub-low")!;
     expect(bub.series).toBe("bub");
@@ -327,10 +339,11 @@ describe("必测场景:resolved data 事实", () => {
     const codex = scatter.rows.find((r) => r.key === "compare/codex-mid")!;
     expect(codex.series).toBe("codex");
     expect(codex.x.value).toBeCloseTo(0.225, 10); // errored 0.3 与 passed 0.15,skipped 不计
+    // endToEndPassRate:errored → 0,skipped → null,algebra/z passed → 1,跨题均值 0.5
     expect(codex.y.value).toBeCloseTo(0.5, 10);
 
     // 场景 2:solo/no-cost 缺成本 → x 为 null(点在,不可画),y 仍有值
-    const solo = scatter.rows.find((r) => r.key === "solo/no-cost")!;
+    const solo = soloGroup.scatter.rows.find((r) => r.key === "solo/no-cost")!;
     expect(solo.x.value).toBeNull();
     expect(solo.y.value).toBeCloseTo(0.5, 10);
     // ≥2 可画点
@@ -341,52 +354,32 @@ describe("必测场景:resolved data 事实", () => {
     expect(experiments.find((e) => e.experimentId === "solo/no-cost")!.cost.value).toBeNull();
   });
 
-  it("场景 3:恰好一个可画点(另一实验缺成本)", async () => {
-    const tree = await resolvedTreeOf(ExperimentComparison, oneDrawableContext());
-    const scatter = scatterOf(tree)!;
-    const drawable = scatter.rows.filter((r) => r.x.value !== null && r.y.value !== null);
-    expect(drawable).toHaveLength(1);
-    expect(drawable[0].key).toBe("only/priced");
-  });
-
-  it("场景 4:空 Selection —— 散点无 rows、实验列表为空数组", async () => {
+  it("场景 4:空 Selection —— 没有可比组", async () => {
     const tree = await resolvedTreeOf(ExperimentComparison, emptyContext());
-    expect(scatterOf(tree)!.rows).toEqual([]);
-    expect(experimentListOf(tree)).toEqual([]);
+    expect(comparisonDataOf(tree)!.groups).toEqual([]);
   });
 
   it("场景 4 变体:全 skipped —— 每个点 x/y 都不可测,0 可画点", async () => {
     const tree = await resolvedTreeOf(ExperimentComparison, allSkippedContext());
-    const scatter = scatterOf(tree)!;
+    const scatter = comparisonDataOf(tree)!.groups[0]!.scatter;
     expect(scatter.rows.every((r) => r.x.value === null && r.y.value === null)).toBe(true);
     expect(scatter.rows.filter((r) => r.x.value !== null && r.y.value !== null)).toHaveLength(0);
   });
 
   it("场景 5:failed/errored/skipped 混合 —— ExperimentList 展开区结果摘要正确(eval 级折叠计票)", async () => {
     const tree = await resolvedTreeOf(ExperimentComparison, richContext());
-    const codex = experimentListOf(tree)!.find((e) => e.experimentId === "compare/codex-mid")!;
+    const codex = comparisonDataOf(tree)!.groups
+      .find((group) => group.key === "compare")!
+      .experiments.find((e) => e.experimentId === "compare/codex-mid")!;
     // algebra/x errored、algebra/y skipped、algebra/z passed → eval 级折叠 {passed:1, errored:1, skipped:1}
     expect(codex.verdicts).toEqual({ passed: 1, failed: 0, errored: 1, skipped: 1 });
     const errored = codex.evalRows.find((e) => e.evalId === "algebra/x")!;
     expect(errored.verdict).toBe("errored");
-    expect(errored.reason).toBe("adapter crashed");
+    expect(errored).not.toHaveProperty("reason");
+    expect(errored.attempts[0]!.error?.message).toBe("adapter crashed");
     expect(codex.evalRows.find((e) => e.evalId === "algebra/y")!.verdict).toBe("skipped");
   });
 
-  it("场景 6:同 experiment 多 eval、多 attempts —— 展开层与 attempt locator 正确", async () => {
-    const tree = await resolvedTreeOf(ExperimentComparison, richContext());
-    const bub = experimentListOf(tree)!.find((e) => e.experimentId === "compare/bub-low")!;
-    expect(bub.evalRows.map((e) => e.evalId).sort()).toEqual(["algebra/x", "algebra/y"]);
-    const multi = bub.evalRows.find((e) => e.evalId === "algebra/x")!;
-    // 多轮 attempt 折成 passed(任一轮通过),两次 attempt 都在展开区的 attempts 里
-    expect(multi.verdict).toBe("passed");
-    expect(multi.attempts.map((a) => a.attempt)).toEqual([0, 1]);
-    expect(multi.attempts.map((a) => a.verdict)).toEqual(["failed", "passed"]);
-    // attempt locator 唯一、格式正确 —— 回到证据的引用不丢
-    const locators = multi.attempts.map((a) => a.locator);
-    expect(new Set(locators).size).toBe(2);
-    for (const locator of locators) expect(locator).toMatch(/^@1[0-9a-z]{7}$/);
-  });
 });
 
 // ═════════════════════════ 3. text / web 渲染的事实相同 ═════════════════════════
@@ -435,33 +428,15 @@ describe("built-in 与 public-copy 渲染出的事实相同", () => {
 
 // ═════════════════════════ 4. 散点空 / 单点 / 多点行为(text + web 同一事实)═════════════════════════
 
-describe("散点空态 / 单点 / 多点行为", () => {
-  it("0 可画点(空 Selection):text 说 No data、web 走 nre-scatter-empty nre-missing", async () => {
+describe("分组空态 / 单点 / 多点行为", () => {
+  it("空 Selection:text / web 都显示没有实验组，不伪造空 scatter", async () => {
     const text = await renderReportToText(ExperimentComparison, emptyContext(), { width: 100 });
-    expect(text).toContain("No data to plot");
-    expect(text).not.toContain("better → upper right");
+    expect(text).toContain("No experiment groups");
     const html = await renderReportToStaticHtml(ExperimentComparison, emptyContext());
-    expect(html).toContain("nre-scatter-empty");
-    expect(html).toContain("nre-missing");
-  });
-
-  it("恰好 1 可画点:text/web 都正常画单点", async () => {
-    const text = await renderReportToText(ExperimentComparison, oneDrawableContext(), { width: 100 });
-    expect(text).toContain("better → upper right");
-    const html = await renderReportToStaticHtml(ExperimentComparison, oneDrawableContext());
-    expect(html).toContain("nre-scatter-point");
-    expect(html).not.toContain("nre-scatter-empty");
-    expect(html).not.toContain("nre-scatter-empty nre-missing");
-    expect(html).toContain("<svg");
+    expect(html).toContain("nre-experiment-groups-empty");
+    expect(html).not.toContain("nre-metric-scatter");
   });
 
-  it("≥2 可画点:正常绘图(text 有 better → upper right,web 有 svg)", async () => {
-    const text = await renderReportToText(ExperimentComparison, richContext(), { width: 100 });
-    expect(text).toContain("better → upper right");
-    const html = await renderReportToStaticHtml(ExperimentComparison, richContext());
-    expect(html).toContain("<svg");
-    expect(html).not.toContain("nre-scatter-empty");
-  });
 });
 
 // ═════════════════════════ 5. 场景 7:数据只 resolve 一次,locale 只改 chrome ═════════════════════════
@@ -474,8 +449,9 @@ describe("场景 7:en / zh-CN 数据 resolve 一次、chrome 分别本地化", (
     validateReportTree(resolved);
 
     // 同一棵 resolved 树 → data 只算了一次(下方 spy 版另证调用次数)。
-    const scatter = scatterOf(resolved)!;
-    const experiments = experimentListOf(resolved)!;
+    const comparison = comparisonDataOf(resolved)!;
+    const scatterRows = comparison.groups.flatMap((group) => group.scatter.rows);
+    const experiments = comparison.groups.flatMap((group) => group.experiments);
 
     const enText = renderNodeToText(resolved, createTextContext({ width: 100, locale: "en" }));
     const zhText = renderNodeToText(resolved, createTextContext({ width: 100, locale: "zh-CN" }));
@@ -489,55 +465,61 @@ describe("场景 7:en / zh-CN 数据 resolve 一次、chrome 分别本地化", (
     );
 
     // chrome 分语言
-    expect(enText).toContain("Pass rate");
-    expect(zhText).toContain("成功率");
-    expect(enHtml).toContain("Pass rate");
-    expect(zhHtml).toContain("成功率");
+    expect(enText).toContain("End-to-end pass rate");
+    expect(zhText).toContain("端到端成功率");
+    expect(enHtml).toContain("End-to-end pass rate");
+    expect(zhHtml).toContain("端到端成功率");
     expect(enText).not.toEqual(zhText);
 
     // 但两语言下的事实(散点键 / x / y、attempt 深链)完全相同 —— 数据没被重算成不同结果。
     expect(scatterKeysOf(zhHtml)).toEqual(scatterKeysOf(enHtml));
     expect(hrefsOf(zhHtml)).toEqual(hrefsOf(enHtml));
     // 从同一棵 resolved 树取的 data,en/zh 渲染不改变它
-    expect(scatter.rows.map((r) => r.key)).toEqual(["compare/bub-low", "compare/codex-mid", "solo/no-cost"]);
-    const [bub, codex, solo] = scatter.rows;
+    expect(scatterRows.map((r) => r.key)).toEqual(["compare/bub-low", "compare/codex-mid", "solo/no-cost"]);
+    const [bub, codex, solo] = scatterRows;
     expect(bub.x.value).toBeCloseTo(0.1, 10);
     expect(bub.y.value).toBeCloseTo(0.75, 10);
     expect(codex.x.value).toBeCloseTo(0.225, 10);
-    expect(codex.y.value).toBeCloseTo(0.5, 10);
+    expect(codex.y.value).toBeCloseTo(0.5, 10); // endToEndPassRate:errored=0,skipped=null,passed=1
     expect(solo.x.value).toBeNull();
     expect(solo.y.value).toBeCloseTo(0.5, 10);
+    // ExperimentList 按 endToEndPassRate 从高到低:bub-low(0.75)> codex-mid(0.5)=solo(0.5),同分按 id。
     expect(experiments.map((e) => e.experimentId)).toEqual(["compare/bub-low", "compare/codex-mid", "solo/no-cost"]);
   });
 
-  it("spy 佐证:build() 里各计算函数恰好调用一次,随后两 locale 渲染不再重算", async () => {
-    const scatterSpy = vi.spyOn(compute, "scatterData");
-    // 注意:spy 挂在 ExperimentList.data 本身,不是 compute.experimentListData —— components.tsx
-    // 用 `Object.assign(component, { data: experimentListData })` 把函数值复制成一个普通属性,
-    // 那份拷贝在 components.tsx 求值时(模块加载期)就定死了,晚于此的 vi.spyOn(compute, …) патch
-    // 不到已经复制走的引用。直接调用方(built-ins/experiment-comparison.tsx)读的是
-    // `ExperimentList.data` 这个属性,所以要在这个属性上打桩。MetricScatter 不受影响:它的
-    // resolve() 住在 components.tsx 里,调用的是 scatterData 这个 import 绑定本身(ESM 实时绑定),
-    // vi.spyOn(compute, "scatterData") 打得中。
-    const experimentListSpy = vi.spyOn(ExperimentList, "data");
-    try {
-      // ExperimentList 没有 resolve 面,.data() 直接在 build() 里 await——计算发生在 build,
-      // 不是 resolveReportTree;MetricScatter 仍是 selection-form,resolve 阶段才调它的 .data()。
-      const node = (await ExperimentComparison.build(richContext())) as ReportNode;
-      expect(experimentListSpy).toHaveBeenCalledTimes(1);
-      const resolved = await resolveReportTree(node);
-      expect(scatterSpy).toHaveBeenCalledTimes(1);
-      expect(experimentListSpy).toHaveBeenCalledTimes(1);
-
-      // 渲染面纯同步、零 IO:两 locale 渲染同一棵 resolved 树,不再触发任何计算。
-      renderNodeToText(resolved, createTextContext({ locale: "en" }));
-      renderNodeToText(resolved, createTextContext({ locale: "zh-CN" }));
-      expect(scatterSpy).toHaveBeenCalledTimes(1);
-      expect(experimentListSpy).toHaveBeenCalledTimes(1);
-    } finally {
-      scatterSpy.mockRestore();
-      experimentListSpy.mockRestore();
+  it("公共边界佐证:build + resolve 后,两 locale 渲染不再读取 Selection(不重算)", async () => {
+    // 观察面是公共的 Selection 契约:所有计算都必须经由 selection.snapshots 取数,
+    // filter 产物共享同一计数器,渲染阶段任何形式的重算都会让读数增长。
+    const counter = { reads: 0 };
+    function countingSelection(snapshots: Snapshot[]): Selection {
+      const self = {
+        warnings: [] as Selection["warnings"],
+        get snapshots() {
+          counter.reads += 1;
+          return snapshots;
+        },
+        filter: (predicate: (s: Snapshot) => boolean) => countingSelection(snapshots.filter(predicate)),
+      };
+      return self as unknown as Selection;
     }
+    const counting = countingSelection(richContext().selection.snapshots);
+
+    const node = (await ExperimentComparison.build({ selection: counting, results: {} as Results })) as ReportNode;
+    const resolved = await resolveReportTree(node);
+    // 计算阶段确实经由这个公共边界取过数 —— 计数器没有空转。
+    expect(counter.reads).toBeGreaterThan(0);
+    const readsAfterResolve = counter.reads;
+
+    // 渲染面纯同步、零 IO:两 locale、两宿主渲染同一棵 resolved 树,不再触发任何计算。
+    renderNodeToText(resolved, createTextContext({ locale: "en" }));
+    renderNodeToText(resolved, createTextContext({ locale: "zh-CN" }));
+    runWithWebContext({ attemptHref: (locator) => `#/attempt/${locator}`, locale: "en" }, () =>
+      renderToStaticMarkup(resolved as never),
+    );
+    runWithWebContext({ attemptHref: (locator) => `#/attempt/${locator}`, locale: "zh-CN" }, () =>
+      renderToStaticMarkup(resolved as never),
+    );
+    expect(counter.reads).toBe(readsAfterResolve);
   });
 });
 
@@ -560,19 +542,6 @@ describe("场景 9:最小用户报告只放 <ExperimentList> —— 不计算散
     expect(experimentListOf(tree)).toBeDefined();
   });
 
-  it("spy 佐证:scatterData 从未被调用,experimentListData 调一次", async () => {
-    const scatterSpy = vi.spyOn(compute, "scatterData");
-    // 见上一个 describe 块的注释:直接调用方读的是 ExperimentList.data 属性,打桩要打在这上面。
-    const experimentListSpy = vi.spyOn(ExperimentList, "data");
-    try {
-      await resolvedTreeOf(minimal, richContext());
-      expect(scatterSpy).not.toHaveBeenCalled();
-      expect(experimentListSpy).toHaveBeenCalledTimes(1);
-    } finally {
-      scatterSpy.mockRestore();
-      experimentListSpy.mockRestore();
-    }
-  });
 
   it("用户换指标/维度无需框架新增分支:改 points/series 只改 resolved data,不改机制", async () => {
     // 一份「用户自定义」报告:同一 MetricScatter 组件,换成 model 维度 + 只画一个指标轴组合。
@@ -595,46 +564,34 @@ describe("场景 9:最小用户报告只放 <ExperimentList> —— 不计算散
   });
 });
 
-// ═════════════════════════ 7. 架构不变量:renderer 无 built-in 分支 ═════════════════════════
+// ═════════════════════════ 7. 架构不变量:renderer 不依赖 built-in(import 依赖图)═════════════════════════
 
 describe("架构不变量:renderer 不认识 built-in", () => {
   const RENDERER_FILES = ["./report.ts", "./web.ts", "./tree.ts"];
+
+  /** 只解析 import / export…from / 动态 import() 语句的模块 specifier,不 grep 实现文本。 */
+  function importSpecifiersOf(rel: string): string[] {
+    const src = readFileSync(new URL(rel, import.meta.url), "utf8");
+    const specifiers: string[] = [];
+    const patterns = [
+      /(?:^|\n)\s*import\s+[^"'()]*?from\s*["']([^"']+)["']/g, // import x from "…"
+      /(?:^|\n)\s*import\s*["']([^"']+)["']/g, // import "…"(副作用导入)
+      /(?:^|\n)\s*export\s+[^"'()]*?from\s*["']([^"']+)["']/g, // export … from "…"
+      /import\(\s*["']([^"']+)["']\s*\)/g, // 动态 import("…")
+    ];
+    for (const re of patterns) {
+      for (const m of src.matchAll(re)) specifiers.push(m[1]);
+    }
+    return specifiers;
+  }
+
   for (const rel of RENDERER_FILES) {
-    it(`${rel} 源码里没有 "ExperimentComparison" / "built-ins" 分支`, () => {
-      const src = readFileSync(new URL(rel, import.meta.url), "utf8");
-      expect(src).not.toContain("ExperimentComparison");
-      expect(src).not.toContain("built-ins");
+    it(`${rel} 的 import 依赖图不含 built-ins 模块`, () => {
+      const specifiers = importSpecifiersOf(rel);
+      expect(specifiers.length).toBeGreaterThan(0); // 解析确实取到了依赖,守护没有空转
+      for (const spec of specifiers) {
+        expect(spec).not.toMatch(/built-ins/);
+      }
     });
   }
 });
-
-// ═════════════════════════ 8. 宿主选择:show / view 共用默认 definition ═════════════════════════
-
-describe("宿主选择:裸 show / view 共用 ExperimentComparison,--report 替换 definition", () => {
-  it("show / view 源码:Selection 先合成,随后选择内置或用户 definition", () => {
-    const showSrc = readFileSync(new URL("../show/index.ts", import.meta.url), "utf8");
-    expect(showSrc).toMatch(/import \{ ExperimentComparison \} from "\.\.\/\.\.\/dist\/report\/built-ins\/index\.js"/);
-    expect(showSrc).toMatch(/flags\.report === undefined \? ExperimentComparison : await loadReportFile\(cwd, flags\.report\)/);
-    expect(showSrc).not.toContain("showIndexText(selection");
-    // Selection 在报告槽之前、与 report 无关地由 selectCurrentResults 合成。
-    expect(showSrc).toMatch(/selectCurrentResults\(results, \{ experiment: flags\.experiment, patterns \}\)/);
-
-    const viewSrc = readFileSync(new URL("../view/data.ts", import.meta.url), "utf8");
-    // view 的报告槽:report 有值走 loadReportFile,否则 ExperimentComparison;Selection 同样先于报告槽合成。
-    expect(viewSrc).toMatch(/report\s*\?[\s\S]*loadReportFile[\s\S]*:\s*\(await import\([^)]*built-ins[^)]*\)\)\.ExperimentComparison/);
-    expect(viewSrc).toMatch(/selectCurrentResults\(results, \{ experiment: opts\.experiment, patterns \}\)/);
-  });
-
-  it("ExperimentComparison 与 public-copy 作为显式报告时事实完全相同", async () => {
-    for (const { ctx } of SCENARIOS) {
-      const bareText = await renderReportToText(ExperimentComparison, ctx(), { width: 100 });
-      const reportText = await renderReportToText(publicCopy, ctx(), { width: 100 });
-      expect(reportText).toBe(bareText);
-
-      const bareHtml = await renderReportToStaticHtml(ExperimentComparison, ctx());
-      const reportHtml = await renderReportToStaticHtml(publicCopy, ctx());
-      expect(scatterKeysOf(reportHtml)).toEqual(scatterKeysOf(bareHtml));
-      expect(hrefsOf(reportHtml)).toEqual(hrefsOf(bareHtml));
-    }
-  });
-});