niceeval 0.6.2 → 0.7.0

package/dist/report/types.d.ts

@@ -1,21 +1,23 @@
-import type { AttemptHandle, SelectionWarning } from "../results/types.ts";
+import type { AttemptHandle, Scope, ScopeWarning, Snapshot } from "../results/types.ts";
 import type { AttemptLocator } from "../results/locator.ts";
-import type { AssertionResult, AttemptError, DiagnosticRecord, Verdict } from "../types.ts";
-import type { LocalizedLabel, ReportLocale } from "./locale.ts";
-export type { SelectionWarning };
+import type { ExperimentRunInfo, JsonValue, Verdict } from "../types.ts";
+import type { LocalizedText, ReportLocale } from "./locale.ts";
+export type { ScopeWarning };
 export type { AttemptLocator };
-export type { LocalizedLabel, ReportLocale };
+export type { LocalizedText, ReportLocale };
+/** 所有官方计算函数的第一参:Scope(warnings 随行)或手工挑的快照数组(没有挑选过程,自然无警告)。 */
+export type ReportInput = Scope | readonly Snapshot[];
 /** 两级聚合里单级的折叠方式。 */
-export type Aggregator = "mean" | "sum" | "min" | "max" | ((values: number[]) => number);
+export type Aggregator = "mean" | "sum" | "min" | "max" | ((values: readonly number[]) => number);
 /**
  * 两级聚合:「每格 attempt 数相等」是幻觉(earlyExit 让失败的题天然比通过的题样本多),
  * 平铺求均值会让分数和重试策略纠缠;所以先题内折叠、再跨题折叠,默认宏平均。
  */
 export interface MetricAggregate {
-    /** 第一级:同一 (eval × 快照) 的多 attempt → 一个题级值;默认 "mean"。 */
+    /** 第一级:同一 experiment × eval 的多个 attempt 先折成题级值;默认 "mean"。 */
     perEval?: Aggregator;
-    /** 第二级:分组内的题级值 → 格子终值;默认 "mean"。 */
-    across?: Aggregator;
+    /** 第二级:题级值再跨 experiment × eval 折成终值;默认 "mean"。 */
+    acrossEvals?: Aggregator;
 }
 /**
  * 指标:纯函数,吃一个 AttemptHandle 吐一个值(null = 此 attempt 测不了这个指标,
@@ -26,16 +28,13 @@ export interface MetricAggregate {
 export interface Metric<Name extends string = string> {
     /** MetricColumn.key 与列头的来源;同一次计算里重名是错误。 */
     name: Name;
-    /**
-     * 列头;省略时用 name。可以给按 locale 的字典({ en, "zh-CN" }),
-     * 渲染面按宿主 locale 解析,缺项回退 en(display 是 format 产物,不本地化)。
-     */
-    label?: LocalizedLabel;
-    description?: string;
-    /** 渲染提示:越高越好还是越低越好(排序方向、轴向、涨跌配色用)。 */
-    better?: "higher" | "lower";
+    /** 列头;省略时用 name。渲染面按 locale 解析,缺项走 LocalizedText 回退规则。 */
+    label?: LocalizedText;
+    description?: LocalizedText;
     /** 驱动内置格式化:"%" → 87%、"ms" → 1.2s、"$" → $0.31、其余 → 1.2k 缩写。 */
     unit?: string;
+    /** 渲染提示:越高越好还是越低越好(排序方向、轴向、涨跌配色用)。 */
+    better?: "higher" | "lower";
     /**
      * 声明式前置:不满足 → null,语义等价于在 value 开头 return null。
      * 单独设字段是因为这一步最容易忘(忘了它,code-golf 会奖励「写得短的坏代码」)。
@@ -43,51 +42,58 @@ export interface Metric<Name extends string = string> {
     where?: (attempt: AttemptHandle) => boolean;
     value(attempt: AttemptHandle): number | null | Promise<number | null>;
     aggregate?: MetricAggregate;
-    /** 覆盖 unit 驱动的内置格式化。 */
-    display?: (value: number) => string;
+    /** 覆盖 unit 驱动的内置格式化;只格式化同一个终值,不按 locale 分裂计算口径。 */
+    display?: (value: number, locale: ReportLocale) => string;
 }
 /**
- * 维度:attempt 分到哪一组。内置维度就是结果已有的身份字段;自定义维度是一个函数。
- * - "evalGroup" = eval id 的第一段:"algebra/quadratic" → "algebra"(考试里的「科目」)
- * - "snapshot"  = "<experimentId> @ <startedAt>",把两次快照并排成行,与 view 的 Compare 同口径
+ * 内置维度就是结果已有的身份字段。
+ * - "evalGroup" = eval id 的完整父路径("a/b/c" → "a/b";无 "/" 取完整 id,与可比组同一条派生规则)
+ * - "snapshot"  = "<experimentId> @ <startedAt>",把两次快照并排成行
  */
-export type Dimension = "agent" | "model" | "experiment" | "eval" | "evalGroup" | "snapshot" | {
+export type BuiltInDimension = "agent" | "model" | "experiment" | "eval" | "evalGroup" | "snapshot";
+/** 自定义维度:一个函数把 attempt 分到组。 */
+export interface CustomDimension {
     name: string;
-    of: (attempt: AttemptHandle) => string;
-};
-/**
- * flag() 的产物:把 experiment 声明的 flags 当维度(series / rows / columns / points
- * 槽,按声明值分组)或轴(MetricLine 的 x 槽,要求数值并驱动刻度)。
- * 未声明该 flag 的 experiment 不猜:分组如实归「(unset)」,作轴不画点、注脚报数。
- */
-export interface FlagRef {
-    readonly kind: "flag";
-    readonly name: string;
-    /** 组标签 / 轴标签;函数形态把声明值折成组名(如 `(v) => \`${v} agents\``)。 */
-    readonly label?: string | ((value: string | number | boolean) => string);
-    readonly unit?: string;
+    of(attempt: AttemptHandle): string;
 }
 /**
- * config() 的产物:把顶层运行配置(快照 `ExperimentRunInfo` 投影的字段全集,外加桥接到
- * 快照顶层权威字段的 `model` / `agent` 两个键)当维度或轴,槽位用法与 {@link FlagRef} 一致。
- * 未投影的值不猜:分组如实归「(unset)」,作轴不画点、注脚报数。
+ * flag() / runConfig() 的产物:把 experiment 声明的 flag 或顶层运行配置当分组维度。
+ * 读取的 JSON 值可能是任意形状,分组显示键按稳定 JSON 规则生成;缺失值显示内置文案
+ * `(missing)`,不同原始值撞出同一显示键时计算报错并要求改用 CustomDimension。
  */
-export interface ConfigRef {
-    readonly kind: "config";
+export interface DimensionRef {
+    readonly kind: "flag" | "runConfig";
     readonly name: string;
-    /** 组标签 / 轴标签;函数形态把投影值折成组名。 */
-    readonly label?: string | ((value: string | number | boolean) => string);
+    readonly label?: LocalizedText;
     readonly unit?: string;
 }
-/** MetricLine 的 x 轴输入:experiment 声明的 flag,或顶层运行配置(config())。 */
-export type AxisInput = FlagRef | ConfigRef;
-/** 维度槽的输入:内置/自定义维度、experiment 声明的 flag,或顶层运行配置(config())。 */
-export type DimensionInput = Dimension | FlagRef | ConfigRef;
+/** 维度槽的输入:内置维度、自定义维度,或 flag() / runConfig() 的产物。 */
+export type DimensionInput = BuiltInDimension | CustomDimension | DimensionRef;
+/** MetricLine 的 x 轴:必须是数值;字符串配置显式映射,组件不猜 low < medium < high。 */
+export interface NumericAxis {
+    name: string;
+    label?: LocalizedText;
+    unit?: string;
+    of(attempt: AttemptHandle): number | null;
+}
+export interface DimensionOptions {
+    label?: LocalizedText;
+    unit?: string;
+}
+export interface NumericAxisOptions extends DimensionOptions {
+}
+export interface NumericRunConfigAxisOptions extends NumericAxisOptions {
+    /** 字符串配置到数值轴的显式映射;数值配置不需要。 */
+    map?: Readonly<Record<string, number>>;
+}
+/** runConfig() 的可用键:ExperimentRunInfo 字段全集,外加桥接到快照顶层权威字段的 model / agent。 */
+export type RunConfigKey = keyof ExperimentRunInfo | "model" | "agent";
 export interface MetricColumn {
     /** = metric.name,与 cells 的键对应。 */
     key: string;
-    /** 数据层原样携带 metric.label(可本地化);渲染面用 resolveMetricLabel 按 locale 解析。 */
-    label: LocalizedLabel;
+    /** 数据层原样携带 metric.label(可本地化);渲染面按 locale 解析。 */
+    label: LocalizedText;
+    description?: LocalizedText;
     unit?: string;
     /** 渲染提示:排序方向、轴向、涨跌配色。 */
     better?: "higher" | "lower";
@@ -95,332 +101,271 @@ export interface MetricColumn {
 export interface MetricCell {
     /** 聚合后的值;null = 该组没有任何有效样本。 */
     value: number | null;
-    /** 已格式化("87%" / "1.2k lines" / "$0.31"),前端可直接渲染。 */
-    display: string;
-    /** 有效 attempt 数(值为 null 的不计入)。 */
+    /**
+     * 已格式化的显示值;计算函数为官方生成面覆盖的每个 locale(当前 en、zh-CN)生成,
+     * renderer 按 LocalizedText 回退规则选择,其它 locale 回退 en。
+     */
+    display: LocalizedText;
+    /** 有效 attempt 数(指标返回非 null 的 attempt)。 */
     samples: number;
-    /** 组内 attempt 总数;samples < total = 有 attempt 测不了这个指标。 */
+    /** 本格子覆盖的 attempt 总数,包含值为 null 的 attempt。 */
     total: number;
     /**
-     * 这个格子由哪些 attempt 算出 —— 回到证据的引用。必填(可空数组):
+     * 本格子覆盖的全部 attempt(包含指标值为 null 的证据)—— 回到证据的引用。必填(可空数组):
      * 「每个数字点进去就是证据」是页面的核心承诺,可选字段会让深链静默缺失。
      */
     refs: AttemptLocator[];
 }
 /**
- * 榜单行的元信息:rows: "experiment" 时随行(experiment 行天然有唯一的 agent/model 身份、
- * eval 级折叠计票与「这行覆盖了多少题/多少次尝试/最近何时跑的」);其它维度不携带。
- * web / text 面在 meta 在场时补 Model / Agent / Verdicts 列,`evals`/`attempts`/
- * `lastRunAt` 则渲染成行键下的一行紧凑摘要——与 view 原生榜单同一份信息密度。
- * `MetricTable` 只表达维度 × 指标,没有实体下钻——要展开到 experiment 的 Eval 或
- * Eval 的 Attempt,用 `ExperimentList` / `EvalList`,这里不再有 `subRows`。
+ * 数据形状的字段命名规则(docs/feature/reports/library/metric-views.md「共用数据形状」):
+ * 维度名字段 = 产生它的选项名 + `Dimension` 后缀,值是解析后的维度 name;
+ * 条目数组一律叫 `rows`(Matrix 的稀疏格子叫 `cells`);条目内的 key / series 是维度值,不带后缀。
  */
-export interface TableRowMeta<K extends string = string> {
-    agent?: string;
-    model?: string;
-    /** eval 级折叠计票(foldEvalVerdict 口径,与 view 榜单同一套):每题折成单一判定后计数。 */
-    verdicts?: {
-        passed: number;
-        failed: number;
-        errored: number;
-        skipped: number;
-    };
-    /**
-     * `rows: "experiment"` 专属:这一行覆盖的 eval 数(去重后,summarizeItems 口径,与
-     * `verdicts` 四项之和一致)。其它行维度(agent/eval/自定义…)没有「这一行是几道题」的
-     * 独立语义(题本身就是行),不携带这个字段。
-     */
-    evals?: number;
-    /**
-     * `rows: "experiment"` 专属:这一行覆盖的 attempt 总数(原始计数,含多轮重试)。
-     * 大于 `evals` 说明存在多轮重试(early-exit 复测 / flaky 重跑);等于 `evals` 说明
-     * 每题只跑了一轮。同上,只在 `rows: "experiment"` 时语义成立。
-     */
-    attempts?: number;
-    /**
-     * `rows: "experiment"` 专属:这一行覆盖范围内快照 `startedAt` 的最大值(最近一次运行
-     * 时间,ISO 8601,字符串比较即可比大小)。组内没有任何 item 时缺席。
-     */
-    lastRunAt?: string;
-}
-/** 列键 K 来自 columns 元组的字面量 name:拼错列名编译不过,不是运行时 undefined。 */
-export interface TableData<K extends string = string> {
-    /** 行维度名,如 "agent"。 */
-    dimension: string;
+export interface TableData {
+    rowDimension: string;
     columns: MetricColumn[];
-    rows: {
+    rows: Array<{
         key: string;
-        cells: Record<K, MetricCell>;
-        meta?: TableRowMeta<K>;
-    }[];
+        cells: Record<string, MetricCell>;
+    }>;
 }
 export interface MatrixData {
-    /** 行维度名,如 "eval"。 */
-    rows: string;
-    /** 列维度名,如 "agent"。 */
-    columns: string;
+    rowDimension: string;
+    columnDimension: string;
     metric: MetricColumn;
-    /** 稀疏:没有样本的格子不出现。 */
-    cells: {
+    /** 稀疏格子:没有 attempt 的组合不生成格子。 */
+    cells: Array<{
         row: string;
         column: string;
         cell: MetricCell;
-    }[];
-}
-export interface ScoreboardData {
-    /**
-     * 被打分的维度名,如 "agent"。
-     * (计算函数的维度槽叫 rows,与 MetricTable.data 统一;数据形状上行数组已占用
-     * rows 一词,维度名沿用 TableData 的 dimension。)
-     */
-    dimension: string;
-    fullMarks: number;
-    /** 实际生效的权重表(按匹配顺序:最长前缀在前)—— 成绩单可审计。 */
-    weights: {
-        prefix: string;
-        weight: number;
-    }[];
-    rows: {
-        key: string;
-        /** 已折算到 fullMarks。 */
-        total: {
-            value: number;
-            display: string;
-        };
-        subjects: {
-            /** 科目(subjects 维度的值)。 */
-            key: string;
-            /** 加权得分。 */
-            earned: number;
-            /** 科目分值合计。 */
-            possible: number;
-            /** 题数。 */
-            evals: number;
-            /** 无任何样本、按 0 计的题数 —— 固定分母的如实注脚。 */
-            missing: number;
-        }[];
-    }[];
+    }>;
 }
 export interface ScatterData {
-    /** 点维度名,如 "experiment"。 */
-    points: string;
-    /** 系列维度名,如 "agent"。 */
-    series?: string;
-    /** better: "lower" → 组件反向画轴,「好」的角落恒在右上。 */
+    pointDimension: string;
+    seriesDimension?: string;
+    /** 轴方向跟随 better:lower 反向渲染(值大在左/下),「更好」恒指向右上;刻度显示真实值。 */
     x: MetricColumn;
     y: MetricColumn;
-    rows: {
-        /** 点的键,如 "compare/bub-high"。 */
+    rows: Array<{
         key: string;
-        /** 所属系列,如 "bub"。 */
         series?: string;
         x: MetricCell;
         /** 任一为 null 的点组件不画,注脚如实报数(点仍留在 rows 里,可数)。 */
         y: MetricCell;
-    }[];
-}
-/** MetricLine 的 x 轴:experiment 声明的 flag,数值驱动刻度。 */
-export interface LineAxis {
-    /** flag 名。 */
-    key: string;
-    label: string;
-    unit?: string;
+    }>;
 }
 export interface LineData {
-    x: LineAxis;
-    /** 系列维度名(flag 或普通维度)。 */
-    series?: string;
+    x: {
+        key: string;
+        label: LocalizedText;
+        unit?: string;
+    };
+    seriesDimension?: string;
     y: MetricColumn;
-    rows: {
-        /** 点的键(experiment id):每个点 = 一个 experiment 的聚合。 */
+    rows: Array<{
+        /** 点身份 = (series, x):x 值的稳定十进制字符串,同一 series 内唯一。 */
         key: string;
         series?: string;
-        /** flag 声明值;未声明或非数值 → null,点不画、注脚报数。 */
         x: number | null;
-        /** 已格式化的 x("300 ms");x 为 null 时为空串。 */
-        xDisplay: string;
+        xDisplay: LocalizedText;
         y: MetricCell;
-    }[];
-}
-/**
- * 一组 experiment(如自定义报告里同一 `<Section>` 内的全部 experiment)的摘要:
- * experiment/eval/attempt 数量、eval 级折叠计票、通过率、总成本、最后运行时间——
- * 恢复旧 `GroupSelector` 卡片曾展示的信息密度,但通过率是官方 `MetricCell` 形态,
- * 不是裸数字,渲染面不用另外拼格式。
- */
-export interface GroupSummaryData {
-    /** 组内 experiment 数(去重后的 experimentId 个数)。 */
-    experiments: number;
-    /**
-     * 组内 eval 数,按完整身份键(experimentId + eval id)去重——多 experiment 的组里
-     * 两个 experiment 各自的同名 eval(如都叫 "algebra/a")算两道题,不会被误合并成一道。
-     */
-    evals: number;
-    /** 组内 attempt 总数(原始计数,一轮 attempt 一票,不折叠)。 */
-    attempts: number;
-    /**
-     * eval 级折叠计票:同一 eval 的多轮 attempt 先折成一个判定(`foldEvalVerdict`,任一轮
-     * 通过则通过,否则取最严重的),再计数——与 `TableRowMeta.verdicts`、view 榜单同一口径,
-     * 不是 attempt 原始票数的直接计票。
-     */
-    verdicts: {
-        passed: number;
-        failed: number;
-        errored: number;
-        skipped: number;
-    };
-    /**
-     * 组的通过率:eval 级折叠计票的 `passed / (passed + failed + errored)`(`skipped` 不进
-     * 分母)——这是旧 `GroupSelector` 卡片的口径,不是 `OverviewData.totals.passRate` 那种
-     * `computeCell` 两级聚合(两者服务不同问题:「这组题多少算过」vs「每次运行成功多少」)。
-     * 分母为 0(组内没有任何已跑的 eval)时 `value` 为 `null`,不编 0%。
-     */
-    passRate: MetricCell;
-    /** 组内可测成本(`attemptCostUSD`)求和;一次 attempt 都没报成本 = `null`,不编 `0`。 */
-    totalCostUSD: number | null;
-    /** 组内快照 `startedAt` 的最大值(字符串比较,ISO 8601 天然可比);组内没有任何 item 时缺席。 */
-    lastRunAt?: string;
+    }>;
 }
-export interface OverviewData {
-    snapshots: {
-        experimentId: string;
-        agent: string;
-        model?: string;
-        startedAt: string;
-    }[];
-    totals: {
-        evals: number;
-        attempts: number;
-        /**
-         * 四个 attempt 原始判定计票(一个 attempt 一票),独立于 `passRate`:驱动页头的
-         * 判定计数展示,不是通过率公式的输入——不要从这四个数现场重算百分比。
-         */
-        passed: number;
-        failed: number;
-        errored: number;
-        skipped: number;
-        /**
-         * 默认成功率的唯一官方口径:`computeCell(endToEndPassRate, items)`,与 `MetricTable.data(...,
-         * columns: [endToEndPassRate])` 同一台两级聚合引擎(题内折叠 perEval、跨题折叠 across,默认都是
-         * mean)——一道题内多个 attempt 部分通过,贡献的是小数份额而不是二元票。`samples`/`total`
-         * 是两级聚合口径下的 attempt 计数(`total` 含 skipped 与 errored——endToEndPassRate 对
-         * errored 记 0、只对 skipped 记 null,`samples` 因此只不含 skipped),不等于上面四个
-         * verdict 计票的任何一个之和。
-         */
-        passRate: MetricCell;
-        /** 任一 attempt 报了成本才有;全缺 = null,不编 0。 */
-        costUSD: number | null;
-        durationMs: number;
-    };
-    /** Selection 的警告随行(结构化,含渲染好的 message),RunOverview 直接渲染。 */
-    warnings: SelectionWarning[];
+export interface ScoreboardData {
+    rowDimension: string;
+    questions: string[];
+    fullMarks: number;
+    /** 实际生效的权重表(最长前缀在前)—— 成绩单可审计。 */
+    weights: Array<{
+        prefix: string;
+        weight: number;
+    }>;
+    /** Scope 中存在但不在题集内、被忽略的 eval 数(注脚显示)。 */
+    ignoredEvals: number;
+    rows: Array<{
+        key: string;
+        total: {
+            /** fullMarks × earned / possible。 */
+            value: number;
+            display: LocalizedText;
+            /** 题集中该行完全没有 attempt 的题数(按 0 计,分开计数)。 */
+            notRun: number;
+            /** 有 attempt 但指标为 null(测不了)的题数(按 0 计,分开计数)。 */
+            unscorable: number;
+            refs: AttemptLocator[];
+        };
+        subjects: Array<{
+            key: string;
+            /** 加权后的 [0, 1] 题目分数之和。 */
+            earned: number;
+            /** 本分科题目的权重之和。 */
+            possible: number;
+            questions: number;
+            notRun: number;
+            unscorable: number;
+            display: LocalizedText;
+            refs: AttemptLocator[];
+        }>;
+    }>;
 }
-export interface DeltaData<K extends string = string> {
+export interface DeltaData {
+    byDimension: string;
     columns: MetricColumn[];
-    rows: {
-        /** pair 的 label,如 "bub"。 */
+    /** FlagPairs 派生形态下的配对域实验数;字面 pairs 不携带(空态文案用)。 */
+    experiments?: number;
+    rows: Array<{
         key: string;
-        /** 基线侧:experiment id 或快照键 "<experimentId> @ <startedAt>"。 */
+        /** 作者在 DeltaPair 里声明(或派生规则生成)的 label,原样透传;renderer 据此显示行名。 */
+        label: LocalizedText;
         a: {
-            experimentId: string;
+            key: string;
         };
-        /** 对比侧。 */
         b: {
-            experimentId: string;
+            key: string;
         };
-        cells: Record<K, {
+        cells: Record<string, {
             a: MetricCell;
             b: MetricCell;
-            /** b.value - a.value;任一侧 null → null,不硬算。 */
+            /** b.value - a.value;任一侧缺失则为 null。 */
             delta: number | null;
-            /** 已带符号("+12%" / "-$0.80" / "±0"),涨跌好坏由 better 判定。 */
-            display: string;
+            display: LocalizedText;
+            outcome: "improved" | "regressed" | "unchanged" | "unavailable";
         }>;
-    }[];
+    }>;
+}
+export interface DeltaPair {
+    label: LocalizedText;
+    a: string;
+    b: string;
+}
+/** pairsByFlag() 的产物:按一个 flag 机械导出全部 A/B 对;只在 by 为 "experiment" 时成立。 */
+export interface FlagPairs {
+    readonly kind: "flagPairs";
+    readonly flag: string;
+    /** a 侧的 flag 取值;缺省表示「未声明该 flag」的实验作 a。 */
+    readonly baseline?: JsonValue;
+}
+export interface VerdictTally {
+    passed: number;
+    failed: number;
+    errored: number;
+    skipped: number;
+}
+/**
+ * 一个范围的摘要:快照时间窗、experiment / eval / attempt 数、两级判定计票、端到端成功率
+ * 和总成本。eval 的身份键是 experimentId + evalId;data 恒携带两级计票,渲染面显示哪一级
+ * 由呈现 prop `votes` 决定,不改变 data(docs/feature/reports/library/summaries.md)。
+ */
+export interface ScopeSummaryData {
+    /** 贡献当前数据的快照时间范围;空范围为 null,不编造当前时间。 */
+    range: {
+        earliestStartedAt: string | null;
+        latestStartedAt: string | null;
+    };
+    experiments: number;
+    /** experimentId + evalId 的去重计数,与 evalVerdicts 同分母。 */
+    evals: number;
+    attempts: number;
+    /** 每个 experimentId + evalId 先折成最终 verdict 后计票。 */
+    evalVerdicts: VerdictTally;
+    /** attempt 原始计票,不折叠。 */
+    attemptVerdicts: VerdictTally;
+    /** 官方两级 endToEndPassRate,不从任一计票重算。 */
+    endToEndPassRate: MetricCell;
+    /** costUSD 按 attempt 求和;缺失成本不伪造为 0。 */
+    totalCostUSD: MetricCell;
+}
+/** 一个可比组的数据;三个子块都只消费本组快照,不能含其它父目录的引用。 */
+export interface ExperimentComparisonGroupData {
+    /** experiment id 的完整父路径;根目录 experiment 使用完整 id。 */
+    key: string;
+    summary: ScopeSummaryData;
+    scatter: ScatterData;
+    experiments: ExperimentListItem[];
+}
+export interface ExperimentComparisonData {
+    groups: ExperimentComparisonGroupData[];
 }
 /**
- * `AttemptList` 一项 = 一个 Attempt:身份、判定、断言、结构化 error、diagnostics、耗时、
- * 成本和 locator。`ExperimentList` / `EvalList` 的下钻数组复用同一个类型,不是各自的精简版。
- * 渲染面只显示一条主失败断言摘要或 error 的一层摘要；完整 assertions、cause / stack 与
- * diagnostics 属于 locator 下钻详情,不塞进比较列表,但随数据携带 —— `AttemptList.data` 的 `redact`
- * 钩子覆盖它们的自由文本(见 docs/feature/reports/library.md「AttemptList」)。
+ * `AttemptList` 一项 = 一次 attempt:身份、判定、算好的单行结果摘要与证据引用。
+ * 完整 assertions、Judge evidence、diagnostics、cause 与 stack 不进列表 data;
+ * 需要完整结构时经 locator 回读取面(resolveLocator → AttemptHandle)。
  */
 export interface AttemptListItem {
-    evalId: string;
     experimentId: string;
+    evalId: string;
     attempt: number;
     agent: string;
     verdict: Verdict;
-    /** 结构化执行错误(与 `EvalResult.error` 同构):列表只显示 `message` 一层摘要。 */
-    error?: AttemptError;
-    /** 本 attempt 的有界诊断(teardown / cleanup 失败等,与 verdict 独立);属于下钻详情。 */
-    diagnostics?: DiagnosticRecord[];
-    assertions: AssertionResult[];
+    /**
+     * 该轮的单行结果摘要,已按 Scoring display 契约折好:failed 取主失败断言摘要,
+     * errored 取结构化 error 的一层摘要(phase · code · message),passed / skipped 为 null。
+     * 渲染面只做宽度截断,不重算摘要。
+     */
+    failureSummary: string | null;
+    /** 主失败之外还有几条失败断言("+N more failures" 的 N);无失败为 0。 */
+    moreFailures: number;
+    /** 当前 attempt 的 examScore 与证据引用。 */
+    examScore: MetricCell;
     durationMs: number;
-    costUSD?: number;
+    /** 缺失为 null(测不了),不伪造 0;attempt 级条目的缺失一律用 null,不用省略字段。 */
+    costUSD: number | null;
     locator: AttemptLocator;
 }
 /**
- * `ExperimentList` 一项里,一个 Eval 的展开行:折叠判定(`foldEvalVerdict`)、该 Eval 内
- * attempt 的平均耗时/成本(两级聚合引擎在单一 eval 上退化成组内均值),以及这道题的全部
- * Attempt(升序,供进一步展开到 `AttemptList`)。失败原因属于各 Attempt,不在父行挑一轮重复。
+ * `EvalList` 一项 = 一个 `experimentId + evalId`(同一个 Eval 跑在两个 experiment 上是
+ * 两条不同结果,不合并)。失败原因只存在于各 AttemptListItem,不在 Eval 父项重复一份。
  */
+export interface EvalListItem {
+    experimentId: string;
+    evalId: string;
+    /** 任一轮 passed 即 passed,否则 failed > errored > skipped。 */
+    verdict: Verdict;
+    examScore: MetricCell;
+    durationMs: MetricCell;
+    costUSD: MetricCell;
+    attempts: AttemptListItem[];
+}
+/** `ExperimentList` 一项里,一个 Eval 的展开行。 */
 export interface ExperimentListEvalRow {
     evalId: string;
-    /** 折叠判定(任一 attempt 通过则通过,否则取最严重的)。 */
     verdict: Verdict;
-    /** 这道题内 attempt 的平均耗时(`computeCell(durationMs, …)`,单一 eval 分组下即均值)。 */
-    duration: MetricCell;
-    /** 这道题内 attempt 的平均成本。 */
-    cost: MetricCell;
-    /** 这道题的全部 Attempt,按 attempt 序号升序。 */
+    durationMs: MetricCell;
+    costUSD: MetricCell;
     attempts: AttemptListItem[];
 }
 /**
- * `ExperimentList.data(selection)` 的一项 = 一个 experiment:身份(experimentId/agent/model)、
- * 声明的 flags、Eval 判定构成(`foldEvalVerdict` 计票,与 view 榜单同一口径)、官方两级聚合
- * 汇总指标(endToEndPassRate/cost/duration/tokens,直接来自 `computeCell`,不现场重算),以及展开到
- * 这个 experiment 每道 Eval 的 `evalRows`(按 eval id 升序)。
+ * `experimentListData` 的一项 = 一个 experiment:身份(experimentId/agent/model)、
+ * 声明的 flags、eval 级最终 verdict 计票、官方两级聚合汇总指标,以及展开到每道 Eval 的
+ * `evalRows`(按 eval id 升序)。一行只有一套 agent / model / flags 是输入约束:
+ * 同一 experiment 混入不一致可比性配置时计算按完整用户反馈失败。
  */
 export interface ExperimentListItem {
     experimentId: string;
     agent: string;
     model?: string;
-    flags?: Record<string, unknown>;
-    /** eval 级折叠计票(foldEvalVerdict 口径,与 `TableRowMeta.verdicts`、view 榜单同一套)。 */
-    verdicts: {
-        passed: number;
-        failed: number;
-        errored: number;
-        skipped: number;
-    };
-    /** 官方两级聚合口径(endToEndPassRate),与 `MetricTable.data(..., columns: [endToEndPassRate])` 同一台引擎。 */
-    passRate: MetricCell;
-    cost: MetricCell;
-    duration: MetricCell;
+    flags?: Record<string, JsonValue>;
+    /** eval 级最终 verdict 计票(Result 列的构成)。 */
+    evalVerdicts: VerdictTally;
+    endToEndPassRate: MetricCell;
+    costUSD: MetricCell;
+    durationMs: MetricCell;
     tokens: MetricCell;
-    /** 这个 experiment 覆盖的 eval 数(去重后,与 `verdicts` 四项之和一致)。 */
+    /** 这个 experiment 覆盖的 eval 数(去重后,与 evalVerdicts 四项之和一致)。 */
     evals: number;
     /** 这个 experiment 覆盖的 attempt 总数(原始计数,含多轮重试)。 */
     attempts: number;
     /** 所含快照中最近的 startedAt。 */
     lastRunAt: string;
-    /** 展开到这个 experiment 的 Eval,按 eval id 升序。 */
     evalRows: ExperimentListEvalRow[];
 }
-/**
- * `EvalList.data(selection)` 的一项 = 一个 `experimentId + evalId`(同一个 Eval 跑在两个
- * experiment 上是两条不同结果,不合并)。判定、分数(examScore 的两级聚合)、这道题内 attempt
- * 的平均耗时/成本,外加展开到这道题全部 Attempt 的 `attempts`(按 attempt 序号升序)。失败
- * 原因只存在于各 `AttemptListItem` 的 error / assertions,不会在 Eval 父项重复一份。
- */
-export interface EvalListItem {
-    evalId: string;
-    experimentId: string;
-    verdict: Verdict;
-    /** examScore 的两级聚合;单一 eval 分组下即这道题的题级分数。 */
-    score: MetricCell;
-    duration: MetricCell;
-    cost: MetricCell;
-    attempts: AttemptListItem[];
+/** 三个实体列表共用的计算选项。 */
+export interface EntityListDataOptions {
+    /**
+     * 展示层遮蔽:只改写这次组件数据中的自由文本——条目本身与任何嵌套 attempt 条目的
+     * `failureSummary`;身份与分类字段(experimentId、evalId、locator、数值指标)不经它。
+     * 只作用于这次计算产出的组件数据,不改盘上或任何导出目录里的 artifact;
+     * 发布 artifact 的脱敏用 copySnapshots({ redact })。
+     */
+    redact?: (text: string) => string;
 }