niceeval 0.6.2 → 0.7.1

package/src/report/components.tsx

@@ -1,61 +1,79 @@
 // 官方双面组件的装配点:web 面(./react/ 的纯 React 组件)+ text 面(./text/faces.ts)
-// + 挂在组件上的 data 计算函数。faces 两键必填 —— 配对是结构义务,不是配对表;
-// MetricBars.data 就是 MetricMatrix.data(同一份矩阵数据的另一种摆法),别名显式化。
+// + resolve 解析面(spec 形态由管线代调配套 *Data 函数)。faces 两键必填 —— 配对是结构
+// 义务;MetricBars 与 MetricMatrix 消费同一份矩阵数据(同一个 metricMatrixData)。
+//
+// props 双形态以 `data` 判别(docs/feature/reports/library/metric-views.md):
+//   spec 形态 = 计算选项平铺 + 可选 `input`(默认宿主注入的 Scope),管线在 resolve 阶段
+//   代调同名 *Data,与手工计算严格等价;data 形态接收算好的可序列化数据,跳过取数。
+//   同一组件同时给出 `data` 与 spec 字段按完整用户反馈报错,不静默取一边。
+// 组件消费 `data` 时校验结构,不符合当前形状按完整用户反馈报错并提示可能的版本漂移。
 //
 // 官方组件在宿主里自动接上证据室:web 面的 attemptHref 缺省取 ctx.attemptHref
-// (宿主注入的证据室深链);显式传 prop 可覆盖(嵌进自己应用时自定去处)。三个实体列表
-// (ExperimentList / EvalList / AttemptList)没有这个覆盖口子——它们的 locator 徽标恒经
-// ctx.attemptHref / ctx.attemptCommand,不接受 attemptHref/attemptCommand prop(docs/feature/reports/library.md
-// 「嵌入自己的 React 页面」的函数签名没有这个参数),证据室深链在这三个组件上不是可选行为。
+// (宿主注入的证据室深链);显式传 prop 可覆盖(嵌进自己应用时自定去处)。
 
-import { defineComponent, isHostWebContextActive } from "./tree.ts";
-import type { ReportComponent } from "./tree.ts";
+import type { ReactNode } from "react";
+import {
+  defineComponent,
+  isHostWebContextActive,
+  memoFetchOf,
+  type ReportComponent,
+  type ResolveContext,
+  type TextContext,
+  type WebContext,
+} from "./tree.ts";
 import type { ReportLocale } from "./locale.ts";
 import type { AttemptLocator } from "../results/locator.ts";
-import type { Selection } from "../results/types.ts";
 import type {
   AttemptListItem,
   DeltaData,
+  EntityListDataOptions,
   EvalListItem,
+  ExperimentComparisonData,
   ExperimentListItem,
-  GroupSummaryData,
   LineData,
   MatrixData,
-  OverviewData,
+  ReportInput,
   ScatterData,
+  ScopeSummaryData,
   ScoreboardData,
   TableData,
 } from "./types.ts";
 import {
   attemptListData,
-  deltaData,
+  deltaTableData,
   evalListData,
+  experimentComparisonData,
   experimentListData,
-  groupSummaryData,
-  lineData,
-  matrixData,
-  overviewData,
-  scatterData,
+  metricLineData,
+  metricMatrixData,
+  metricScatterData,
+  metricTableData,
+  scopeSummaryData,
   scoreboardData,
-  tableData,
+  type DeltaTableOptions,
+  type MetricLineOptions,
+  type MetricMatrixOptions,
+  type MetricScatterOptions,
+  type MetricTableOptions,
+  type ScoreboardOptions,
 } from "./compute.ts";
-import type { ScatterDataOptions } from "./compute.ts";
+import { collectItems, locatorOf, resolveInput } from "./aggregate.ts";
 import {
   attemptListText,
-  barsText,
   deltaText,
   evalListText,
+  experimentComparisonText,
   experimentListText,
-  groupSummaryText,
+  barsText,
   lineText,
   matrixText,
-  overviewText,
   scatterText,
   scoreboardText,
+  scopeSummaryText,
   tableText,
 } from "./text/faces.ts";
-import { RunOverview as RunOverviewWeb } from "./react/RunOverview.tsx";
-import { GroupSummary as GroupSummaryWeb } from "./react/GroupSummary.tsx";
+import { ScopeSummary as ScopeSummaryWeb } from "./react/ScopeSummary.tsx";
+import { ExperimentComparisonView } from "./react/ExperimentComparison.tsx";
 import { ExperimentList as ExperimentListWeb } from "./react/ExperimentList.tsx";
 import { EvalList as EvalListWeb } from "./react/EvalList.tsx";
 import { AttemptList as AttemptListWeb } from "./react/AttemptList.tsx";
@@ -67,305 +85,627 @@ import { MetricScatter as MetricScatterWeb } from "./react/MetricScatter.tsx";
 import { MetricLine as MetricLineWeb } from "./react/MetricLine.tsx";
 import { DeltaTable as DeltaTableWeb } from "./react/DeltaTable.tsx";
 
-// ───────────────────────── props ─────────────────────────
+// ───────────────────────── DataProps 组合规则 ─────────────────────────
 
-export interface RunOverviewProps {
-  data: OverviewData;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
-}
-
-export interface GroupSummaryProps {
-  data: GroupSummaryData;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
-}
+type Never<T> = { [K in keyof T]?: never };
 
 /**
- * 三个实体列表都只收算好的 `items`(`.data(selection)` 的产物,报告作者先 `.filter()`/
- * `.slice()` 再传入)——没有 selection-form,组件不提供另一套过滤 DSL
- * (docs/feature/reports/library.md「实体列表」)。
+ * 官方数据组件的统一 props 组合(docs/feature/reports/library/metric-views.md):
+ * data 形态(接收配套 *Data 的产物)或 spec 形态(Options 平铺 + 可选 input)。
  */
-export interface ExperimentListProps {
-  items: ExperimentListItem[];
-  /** web 面在比较表前显示实验过滤框；text 面忽略。 */
-  filter?: boolean;
-  /**
-   * 可选父路径:两面的行标签去掉与它相同的前缀,只显示 experiment id 末段,避免在已经以组为
-   * 标题的上下文里重复文件夹名(默认 `ExperimentComparison` 给每组传组键)。完整 id 仍是排序 /
-   * 着色 / 过滤 / 折叠的键;不传或它不是前缀(如根目录单例组)时显示完整 id。
-   */
-  relativeTo?: string;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
-}
+export type DataProps<Data, Options, Presentation> =
+  | ({ data: Data; input?: never } & Never<Options> & Presentation)
+  | ({ data?: never; input?: ReportInput } & Options & Presentation);
 
-export interface EvalListProps {
-  items: EvalListItem[];
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
-}
+// ───────────────────────── data 结构校验(版本漂移防线)─────────────────────────
 
-export interface AttemptListProps {
-  items: AttemptListItem[];
-  /** items 被 slice 时如实显示剩余数量;省略即 items.length(未截断)。 */
-  total?: number;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-export interface MetricTableProps {
-  data: TableData;
-  /** 传了,格子可点、下钻去处你定;不传,宿主里走证据室深链,宿主外纯展示。 */
-  attemptHref?: (locator: AttemptLocator) => string;
-  /**
-   * web 面在表格前渲染一个过滤输入框(`<input class="nre-filter" data-nre-filter>`),
-   * 由渐进增强 runtime(enhance.js)接管:输入过滤行 textContent。无 JS 时输入框
-   * 静默无功能,表格内容依旧完整可读。默认 false;text 面不受影响。
-   */
-  filter?: boolean;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
+function isCell(value: unknown): boolean {
+  return (
+    isObject(value) &&
+    "value" in value &&
+    "display" in value &&
+    typeof value.samples === "number" &&
+    typeof value.total === "number" &&
+    Array.isArray(value.refs)
+  );
 }
 
-export interface MetricMatrixProps {
-  data: MatrixData;
-  attemptHref?: (locator: AttemptLocator) => string;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
+function isTally(value: unknown): boolean {
+  return (
+    isObject(value) &&
+    typeof value.passed === "number" &&
+    typeof value.failed === "number" &&
+    typeof value.errored === "number" &&
+    typeof value.skipped === "number"
+  );
 }
 
-export interface ScoreboardProps {
-  data: ScoreboardData;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
+type Validator = (data: unknown) => string | null;
+
+function dataShapeError(component: string, dataFnName: string, shape: string, problem: string): Error {
+  return new Error(
+    `<${component}> received data that does not match the current ${shape} shape: ${problem}. ` +
+      `It may have been computed by a different niceeval version (component data carries no schemaVersion; the support window is same-version write and read). ` +
+      `Recompute it with ${dataFnName}() from this niceeval version, then re-render.`,
+  );
 }
 
-/** MetricScatter 两臂共享的纯渲染选项(不含数据来源)。 */
-interface MetricScatterRenderProps {
-  /** 点一个点 → 该配置的下钻页。 */
-  pointHref?: (row: ScatterData["rows"][number]) => string;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
+const validateTableData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (typeof data.rowDimension !== "string") return 'missing "rowDimension" (string)';
+  if (!Array.isArray(data.columns)) return 'missing "columns" (array)';
+  if (!Array.isArray(data.rows)) return 'missing "rows" (array)';
+  for (const row of data.rows as unknown[]) {
+    if (!isObject(row) || typeof row.key !== "string" || !isObject(row.cells)) {
+      return 'each row needs { key, cells }';
+    }
+  }
+  return null;
+};
+
+const validateMatrixData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (typeof data.rowDimension !== "string" || typeof data.columnDimension !== "string") {
+    return 'missing "rowDimension" / "columnDimension" (string)';
+  }
+  if (!isObject(data.metric)) return 'missing "metric" (MetricColumn)';
+  if (!Array.isArray(data.cells)) return 'missing "cells" (array)';
+  return null;
+};
+
+const validateScatterData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (typeof data.pointDimension !== "string") return 'missing "pointDimension" (string)';
+  if (!isObject(data.x) || !isObject(data.y)) return 'missing "x" / "y" (MetricColumn)';
+  if (!Array.isArray(data.rows)) return 'missing "rows" (array)';
+  for (const row of data.rows as unknown[]) {
+    if (!isObject(row) || typeof row.key !== "string" || !isCell(row.x) || !isCell(row.y)) {
+      return "each row needs { key, x: MetricCell, y: MetricCell }";
+    }
+  }
+  return null;
+};
+
+const validateLineData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (!isObject(data.x) || typeof (data.x as Record<string, unknown>).key !== "string") return 'missing "x" axis descriptor';
+  if (!isObject(data.y)) return 'missing "y" (MetricColumn)';
+  if (!Array.isArray(data.rows)) return 'missing "rows" (array)';
+  return null;
+};
+
+const validateScoreboardData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (typeof data.rowDimension !== "string") return 'missing "rowDimension" (string)';
+  if (!Array.isArray(data.questions)) return 'missing "questions" (array)';
+  if (typeof data.fullMarks !== "number") return 'missing "fullMarks" (number)';
+  if (typeof data.ignoredEvals !== "number") return 'missing "ignoredEvals" (number)';
+  if (!Array.isArray(data.rows)) return 'missing "rows" (array)';
+  for (const row of data.rows as unknown[]) {
+    if (!isObject(row) || !isObject(row.total) || typeof (row.total as Record<string, unknown>).notRun !== "number") {
+      return 'each row needs { key, total: { value, display, notRun, unscorable, refs }, subjects }';
+    }
+  }
+  return null;
+};
+
+const validateDeltaData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (typeof data.byDimension !== "string") return 'missing "byDimension" (string)';
+  if (!Array.isArray(data.columns) || !Array.isArray(data.rows)) return 'missing "columns" / "rows" (array)';
+  for (const row of data.rows as unknown[]) {
+    if (!isObject(row) || row.label === undefined || !isObject(row.a) || !isObject(row.b)) {
+      return "each row needs { key, label, a, b, cells }";
+    }
+  }
+  return null;
+};
+
+const validateScopeSummaryData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (!isObject(data.range)) return 'missing "range" ({ earliestStartedAt, latestStartedAt })';
+  if (!isTally(data.evalVerdicts) || !isTally(data.attemptVerdicts)) {
+    return 'missing "evalVerdicts" / "attemptVerdicts" tallies';
+  }
+  if (!isCell(data.endToEndPassRate) || !isCell(data.totalCostUSD)) {
+    return 'missing "endToEndPassRate" / "totalCostUSD" (MetricCell)';
+  }
+  return null;
+};
+
+const validateComparisonData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (!Array.isArray(data.groups)) return 'missing "groups" (array)';
+  for (const group of data.groups as unknown[]) {
+    if (!isObject(group) || typeof group.key !== "string" || validateScopeSummaryData(group.summary) !== null) {
+      return "each group needs { key, summary, scatter, experiments }";
+    }
+  }
+  return null;
+};
+
+const validateExperimentListData: Validator = (data) => {
+  if (!Array.isArray(data)) return "expected an array of ExperimentListItem";
+  for (const item of data as unknown[]) {
+    if (!isObject(item) || typeof item.experimentId !== "string" || !isTally(item.evalVerdicts) || !isCell(item.endToEndPassRate)) {
+      return "each item needs { experimentId, evalVerdicts, endToEndPassRate, costUSD, durationMs, tokens, evalRows, … }";
+    }
+  }
+  return null;
+};
+
+const validateEvalListData: Validator = (data) => {
+  if (!Array.isArray(data)) return "expected an array of EvalListItem";
+  for (const item of data as unknown[]) {
+    if (!isObject(item) || typeof item.evalId !== "string" || !isCell(item.examScore) || !Array.isArray(item.attempts)) {
+      return "each item needs { experimentId, evalId, verdict, examScore, durationMs, costUSD, attempts }";
+    }
+  }
+  return null;
+};
+
+const validateAttemptListData: Validator = (data) => {
+  if (!Array.isArray(data)) return "expected an array of AttemptListItem";
+  for (const item of data as unknown[]) {
+    if (!isObject(item) || typeof item.evalId !== "string" || !("failureSummary" in item) || !("costUSD" in item)) {
+      return "each item needs { experimentId, evalId, verdict, failureSummary, moreFailures, examScore, durationMs, costUSD, locator }";
+    }
+  }
+  return null;
+};
+
+// ───────────────────────── spec / data 双形态的通用装配 ─────────────────────────
+
+interface DataComponentDef<Data, Options, Presentation> {
+  name: string;
+  dataFnName: string;
+  shapeName: string;
+  dataFn: (input: ReportInput, options: Options) => Promise<Data>;
+  /** spec 形态的计算选项 prop 名(不含 input);未列出的 props 视为呈现选项原样保留。 */
+  specKeys: readonly string[];
+  validate: Validator;
+  web(props: { data: Data } & Presentation, ctx: WebContext): ReactNode;
+  text(props: { data: Data } & Presentation, ctx: TextContext): string;
 }
 
-/** resolve 之后 web / text 面看到的形态:数据已备好,零 IO。 */
-export interface MetricScatterResolvedProps extends MetricScatterRenderProps {
-  data: ScatterData;
+function makeDataComponent<Data, Options, Presentation>(
+  def: DataComponentDef<Data, Options, Presentation>,
+): ReportComponent<DataProps<Data, Options, Presentation>> {
+  type Props = Record<string, unknown>;
+  type Resolved = { data: Data } & Presentation;
+
+  const assertData = (data: unknown): Data => {
+    const problem = def.validate(data);
+    if (problem !== null) throw dataShapeError(def.name, def.dataFnName, def.shapeName, problem);
+    return data as Data;
+  };
+
+  const resolve = async (props: Props, ctx: ResolveContext): Promise<Resolved> => {
+    const givenSpec = def.specKeys.filter((key) => props[key] !== undefined);
+    if (props.data !== undefined) {
+      if (givenSpec.length > 0 || props.input !== undefined) {
+        const extras = [...givenSpec, ...(props.input !== undefined ? ["input"] : [])];
+        throw new Error(
+          `<${def.name}> got both \`data\` and spec field${extras.length > 1 ? "s" : ""} (${extras.join(", ")}) — the two data sources are exclusive and niceeval will not silently pick one. ` +
+            `Keep \`data\` (precomputed with ${def.dataFnName}()) and drop the spec fields, or drop \`data\` and let the pipeline compute from the spec.`,
+        );
+      }
+      assertData(props.data);
+      return props as unknown as Resolved;
+    }
+    const options: Record<string, unknown> = {};
+    for (const key of givenSpec) options[key] = props[key];
+    const input = (props.input as ReportInput | undefined) ?? ctx.input;
+    const data = await memoFetchOf(ctx)(def.dataFn, input, options, () =>
+      def.dataFn(input, options as Options),
+    );
+    const rest: Record<string, unknown> = { ...props };
+    delete rest.input;
+    for (const key of def.specKeys) delete rest[key];
+    return { ...rest, data } as unknown as Resolved;
+  };
+
+  const component = defineComponent<Props, Resolved>({
+    resolve,
+    web: (props, ctx) => {
+      assertData((props as { data?: unknown }).data);
+      return def.web(props, ctx);
+    },
+    text: (props, ctx) => {
+      assertData((props as { data?: unknown }).data);
+      return def.text(props, ctx);
+    },
+  }) as unknown as ReportComponent<DataProps<Data, Options, Presentation>>;
+  component.displayName = def.name;
+  return component;
 }
 
-/**
- * 互斥两臂:要么直接给算好的 `data`(用于用户自己的 React 页面 / 预计算 / 跨边界序列化),
- * 要么给 `selection` + 计算选项让宿主在渲染前解析(见 tree.ts 的 resolveReportTree)。
- * 同时传 `data` 与 `selection`、或两者都不传,都在 typecheck 阶段失败。计算选项复用
- * `ScatterDataOptions`,不手写会漂移的副本。
- */
-export type MetricScatterProps =
-  | (MetricScatterResolvedProps & {
-      selection?: never;
-      points?: never;
-      series?: never;
-      x?: never;
-      y?: never;
-    })
-  | ({ data?: never } & ScatterDataOptions & MetricScatterRenderProps & { selection: Selection });
-
-export interface MetricLineProps {
-  data: LineData;
-  pointHref?: (row: LineData["rows"][number]) => string;
-  /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
-  locale?: ReportLocale;
-  className?: string;
+/** 宿主内缺省接证据室,显式 prop 覆盖;宿主外不传 attemptHref 就是纯展示。 */
+function hrefOf(
+  props: { attemptHref?: (locator: AttemptLocator) => string },
+  ctx: WebContext,
+): ((locator: AttemptLocator) => string) | undefined {
+  return props.attemptHref ?? (isHostWebContextActive() ? ctx.attemptHref : undefined);
 }
 
-export interface DeltaTableProps {
-  data: DeltaData;
+// ───────────────────────── 呈现选项类型 ─────────────────────────
+
+interface ChromeProps {
   /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
   locale?: ReportLocale;
   className?: string;
 }
 
-// ───────────────────────── 装配 ─────────────────────────
+// ───────────────────────── 概览组件 ─────────────────────────
 
-const SCATTER_UNRESOLVED_MESSAGE =
-  "MetricScatter received unresolved (selection-form) props outside the report host pipeline. " +
-  "Render through defineReport + niceeval show/view (or renderReportToText/renderReportToStaticHtml), " +
-  "or precompute with `await MetricScatter.data(selection, options)` and pass the result as `data`.";
+export type ScopeSummaryProps = DataProps<
+  ScopeSummaryData,
+  Record<never, never>,
+  ChromeProps & {
+    /** 显示哪一级计票;默认 "eval"。data 恒携带两级,votes 只选择呈现。 */
+    votes?: "eval" | "attempt";
+  }
+>;
 
-/** 渲染面(web / text)只吃已解析的数据形态;selection 形态漏解析时直说,而不是画一张空组件。 */
-function requireScatterData(props: { data?: ScatterData }): ScatterData {
-  if (props.data === undefined) throw new Error(SCATTER_UNRESOLVED_MESSAGE);
-  return props.data;
-}
+/** 范围摘要卡:时间窗、数量、两级计票、端到端成功率与总成本。 */
+export const ScopeSummary = makeDataComponent<
+  ScopeSummaryData,
+  Record<never, never>,
+  ChromeProps & { votes?: "eval" | "attempt" }
+>({
+  name: "ScopeSummary",
+  dataFnName: "scopeSummaryData",
+  shapeName: "ScopeSummaryData",
+  dataFn: (input) => scopeSummaryData(input),
+  specKeys: [],
+  validate: validateScopeSummaryData,
+  web: (props, ctx) => <ScopeSummaryWeb {...props} locale={props.locale ?? ctx.locale} />,
+  text: (props, ctx) => scopeSummaryText(props.data, props.votes ?? "eval", ctx),
+}) as unknown as ReportComponent<ScopeSummaryProps>;
 
-/** 页头 KPI 条:何时跑的、几个配置、几道题、通过率、总成本;Selection 的警告随行显示在条内。 */
-export const RunOverview: ReportComponent<RunOverviewProps> & { data: typeof overviewData } = Object.assign(
-  defineComponent<RunOverviewProps>({
-    web: (props, ctx) => <RunOverviewWeb {...props} locale={props.locale ?? ctx.locale} />,
-    text: ({ data }, ctx) => overviewText(data, ctx),
-  }),
-  { data: overviewData },
-);
-RunOverview.displayName = "RunOverview";
+export type ExperimentComparisonProps = DataProps<ExperimentComparisonData, Record<never, never>, ChromeProps>;
 
 /**
- * 组摘要:一组 experiment(典型用法是同一 `<Section>` 内的全部 experiment)的紧凑统计——
- * 通过率(旧 GroupSelector 卡片口径)、experiment/eval/attempt 数、eval 级折叠计票、
- * 总成本、最后运行时间。
+ * 内建报告的默认组合件:先把 input 按可比组分区,再为每组分别计算 ScopeSummary、
+ * 成本 × 端到端成功率散点和 ExperimentList。web 面持有完整组索引并一次聚焦一组;
+ * text 面命中多个组时只显示组索引与可执行的单组查看命令,命中单组时才输出完整散点与列表。
  */
-export const GroupSummary: ReportComponent<GroupSummaryProps> & { data: typeof groupSummaryData } = Object.assign(
-  defineComponent<GroupSummaryProps>({
-    web: (props, ctx) => <GroupSummaryWeb {...props} locale={props.locale ?? ctx.locale} />,
-    text: ({ data }, ctx) => groupSummaryText(data, ctx),
-  }),
-  { data: groupSummaryData },
-);
-GroupSummary.displayName = "GroupSummary";
+export const ExperimentComparison = makeDataComponent<ExperimentComparisonData, Record<never, never>, ChromeProps>({
+  name: "ExperimentComparison",
+  dataFnName: "experimentComparisonData",
+  shapeName: "ExperimentComparisonData",
+  dataFn: (input) => experimentComparisonData(input),
+  specKeys: [],
+  validate: validateComparisonData,
+  web: (props, ctx) => (
+    <ExperimentComparisonView
+      data={props.data}
+      locale={props.locale ?? ctx.locale}
+      className={props.className}
+      attemptHref={isHostWebContextActive() ? ctx.attemptHref : undefined}
+    />
+  ),
+  text: (props, ctx) => experimentComparisonText(props.data, props.className, ctx),
+}) as unknown as ReportComponent<ExperimentComparisonProps>;
+
+// ───────────────────────── 实体列表 ─────────────────────────
+
+interface EntityListChrome extends ChromeProps {
+  attemptHref?: (locator: AttemptLocator) => string;
+}
+
+export type ExperimentListProps = DataProps<
+  readonly ExperimentListItem[],
+  EntityListDataOptions,
+  EntityListChrome & {
+    /** web 面在比较表前显示实验过滤框;text 面忽略。 */
+    filter?: boolean;
+    /**
+     * 可选父路径:两面的行标签去掉与它相同的前缀,只显示 experiment id 末段(默认
+     * `ExperimentComparison` 给每组传组键)。完整 id 仍是排序 / 着色 / 过滤 / 折叠的键。
+     */
+    relativeTo?: string;
+  }
+>;
+
+/** 实验列表:每项一个 experiment,固定八列比较表 + 展开到 Eval / Attempt。 */
+export const ExperimentList = makeDataComponent<
+  readonly ExperimentListItem[],
+  EntityListDataOptions,
+  EntityListChrome & { filter?: boolean; relativeTo?: string }
+>({
+  name: "ExperimentList",
+  dataFnName: "experimentListData",
+  shapeName: "ExperimentListItem[]",
+  dataFn: (input, options) => experimentListData(input, options),
+  specKeys: ["redact"],
+  validate: validateExperimentListData,
+  web: (props, ctx) => (
+    <ExperimentListWeb
+      data={props.data}
+      filter={props.filter}
+      relativeTo={props.relativeTo}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx) ?? ctx.attemptHref}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => experimentListText(props.data, ctx, props.relativeTo),
+}) as unknown as ReportComponent<ExperimentListProps>;
+
+export type EvalListProps = DataProps<readonly EvalListItem[], EntityListDataOptions, EntityListChrome>;
+
+/** Eval 列表:每项一个 experimentId + evalId,展开到这道题的 Attempt。 */
+export const EvalList = makeDataComponent<readonly EvalListItem[], EntityListDataOptions, EntityListChrome>({
+  name: "EvalList",
+  dataFnName: "evalListData",
+  shapeName: "EvalListItem[]",
+  dataFn: (input, options) => evalListData(input, options),
+  specKeys: ["redact"],
+  validate: validateEvalListData,
+  web: (props, ctx) => (
+    <EvalListWeb
+      data={props.data}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx) ?? ctx.attemptHref}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => evalListText(props.data, ctx),
+}) as unknown as ReportComponent<EvalListProps>;
+
+export type AttemptListProps = DataProps<
+  readonly AttemptListItem[],
+  EntityListDataOptions,
+  EntityListChrome & {
+    /** 过滤 / 截断前的总数;省略时等于 data 长度。 */
+    total?: number;
+  }
+>;
+
+/** Attempt 列表:实体列表的叶子层,每项一次 attempt 的判定、单行摘要与 locator。 */
+export const AttemptList = makeDataComponent<
+  readonly AttemptListItem[],
+  EntityListDataOptions,
+  EntityListChrome & { total?: number }
+>({
+  name: "AttemptList",
+  dataFnName: "attemptListData",
+  shapeName: "AttemptListItem[]",
+  dataFn: (input, options) => attemptListData(input, options),
+  specKeys: ["redact"],
+  validate: validateAttemptListData,
+  web: (props, ctx) => (
+    <AttemptListWeb
+      data={props.data}
+      total={props.total}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx) ?? ctx.attemptHref}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => attemptListText(props.data, props.total, ctx),
+}) as unknown as ReportComponent<AttemptListProps>;
+
+// ───────────────────────── FailureList(官方组合件)─────────────────────────
+
+export interface FailureListProps {
+  /** 显示的最大条数;默认 20。 */
+  limit?: number;
+  /** 默认宿主注入的 Scope。 */
+  input?: ReportInput;
+  redact?: (text: string) => string;
+  attemptHref?: (locator: AttemptLocator) => string;
+  locale?: ReportLocale;
+  className?: string;
+}
 
 /**
- * 实验列表:每项一个 experiment,固定展示身份、配置(flags)、Eval 判定构成和官方两级聚合
- * 汇总指标;展开到这个 experiment 的 Eval,每道题内联该题全部 Attempt 的 locator 徽标。
- * 没有 selection-form:`ExperimentList.data(selection)` 产出普通数组,过滤由报告作者对
- * 数组调用 `.filter()`。
+ * 「现在有哪些失败要处理」的成品组合件:内部就是 attemptListData → 过滤 → AttemptList
+ * data 形态,与手写组合严格等价、没有私有能力(docs/feature/reports/library/entity-lists.md)。
+ * verdict ∈ failed / errored,按 attempt 开始时间降序(同刻按 locator 字典序),
+ * 截断到 limit(默认 20),total 报告截断前总数。
  */
-export const ExperimentList: ReportComponent<ExperimentListProps> & { data: typeof experimentListData } =
-  Object.assign(
-    defineComponent<ExperimentListProps>({
-      web: (props, ctx) => <ExperimentListWeb {...props} locale={props.locale ?? ctx.locale} attemptHref={ctx.attemptHref} />,
-      text: ({ items, relativeTo }, ctx) => experimentListText(items, ctx, relativeTo),
-    }),
-    { data: experimentListData },
+export const FailureList = defineComponent<FailureListProps>(async (props, ctx) => {
+  const input = props.input ?? ctx.scope;
+  const all = await attemptListData(input, props.redact !== undefined ? { redact: props.redact } : undefined);
+  // attempt 开始时间不在列表条目里(它不是列表展示字段);从同一 input 的读取面按 locator 对回。
+  const startedAtByLocator = new Map<string, string>();
+  for (const item of collectItems(resolveInput(input).snapshots)) {
+    startedAtByLocator.set(locatorOf(item), item.attempt.result.startedAt ?? "");
+  }
+  const failures = all
+    .filter((item) => item.verdict === "failed" || item.verdict === "errored")
+    .sort((a, b) => {
+      const ta = startedAtByLocator.get(a.locator) ?? "";
+      const tb = startedAtByLocator.get(b.locator) ?? "";
+      if (ta !== tb) return ta < tb ? 1 : -1; // 最近的失败在前
+      return a.locator < b.locator ? -1 : a.locator > b.locator ? 1 : 0;
+    });
+  const limit = props.limit ?? 20;
+  return (
+    <AttemptList
+      data={failures.slice(0, limit)}
+      total={failures.length}
+      attemptHref={props.attemptHref}
+      locale={props.locale}
+      className={props.className}
+    />
   );
-ExperimentList.displayName = "ExperimentList";
+});
+FailureList.displayName = "FailureList";
 
-/**
- * Eval 列表:每项一个 `experimentId + evalId`,固定展示判定、Attempt 数、分数、成本、耗时
- * 与失败原因;展开到这道题的 Attempt(与 AttemptList 同一份 AttemptListItem)。
- */
-export const EvalList: ReportComponent<EvalListProps> & { data: typeof evalListData } = Object.assign(
-  defineComponent<EvalListProps>({
-    web: (props, ctx) => <EvalListWeb {...props} locale={props.locale ?? ctx.locale} attemptHref={ctx.attemptHref} />,
-    text: ({ items }, ctx) => evalListText(items, ctx),
-  }),
-  { data: evalListData },
-);
-EvalList.displayName = "EvalList";
+// ───────────────────────── 指标组件 ─────────────────────────
 
-/**
- * Attempt 列表:实体列表的叶子层,每项一个 Attempt,固定展示判定、一条主失败断言摘要或
- * error 一层摘要与证据引用(locator)。完整 assertions / evidence 经 locator 下钻。它不预设只看失败;
- * 报告作者过滤 `AttemptListItem[]`、用 `.slice()` 限量,`total` 让渲染面如实报告剩余数量。
- */
-export const AttemptList: ReportComponent<AttemptListProps> & { data: typeof attemptListData } = Object.assign(
-  defineComponent<AttemptListProps>({
-    web: (props, ctx) => <AttemptListWeb {...props} locale={props.locale ?? ctx.locale} attemptHref={ctx.attemptHref} />,
-    text: ({ items, total }, ctx) => attemptListText(items, total, ctx),
-  }),
-  { data: attemptListData },
-);
-AttemptList.displayName = "AttemptList";
+export type MetricTableProps = DataProps<
+  TableData,
+  MetricTableOptions,
+  ChromeProps & {
+    /** web 面在表格前渲染过滤输入框(enhance.js 接管);无 JS 时表格内容依旧完整。 */
+    filter?: boolean;
+    attemptHref?: (locator: AttemptLocator) => string;
+  }
+>;
 
 /** 榜单:一行一个维度值、一列一个指标,回答「谁整体更好」。 */
-export const MetricTable: ReportComponent<MetricTableProps> & { data: typeof tableData } = Object.assign(
-  defineComponent<MetricTableProps>({
-    web: (props, ctx) => (
-      <MetricTableWeb
-        {...props}
-        locale={props.locale ?? ctx.locale}
-        attemptHref={props.attemptHref ?? (isHostWebContextActive() ? ctx.attemptHref : undefined)}
-      />
-    ),
-    text: ({ data }, ctx) => tableText(data, ctx),
-  }),
-  { data: tableData },
-);
-MetricTable.displayName = "MetricTable";
+export const MetricTable = makeDataComponent<
+  TableData,
+  MetricTableOptions,
+  ChromeProps & { filter?: boolean; attemptHref?: (locator: AttemptLocator) => string }
+>({
+  name: "MetricTable",
+  dataFnName: "metricTableData",
+  shapeName: "TableData",
+  dataFn: metricTableData,
+  specKeys: ["rows", "columns", "sort", "evals"],
+  validate: validateTableData,
+  web: (props, ctx) => (
+    <MetricTableWeb
+      data={props.data}
+      filter={props.filter}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx)}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => tableText(props.data, ctx),
+}) as unknown as ReportComponent<MetricTableProps>;
+
+export type MetricMatrixProps = DataProps<
+  MatrixData,
+  MetricMatrixOptions,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>;
+export type MetricBarsProps = MetricMatrixProps;
 
 /** 逐题格子:行 × 列两个维度、格子里一个指标,回答「哪道题谁挂了」。 */
-export const MetricMatrix: ReportComponent<MetricMatrixProps> & { data: typeof matrixData } = Object.assign(
-  defineComponent<MetricMatrixProps>({
-    web: (props, ctx) => (
-      <MetricMatrixWeb
-        {...props}
-        locale={props.locale ?? ctx.locale}
-        attemptHref={props.attemptHref ?? (isHostWebContextActive() ? ctx.attemptHref : undefined)}
-      />
-    ),
-    text: ({ data }, ctx) => matrixText(data, ctx),
-  }),
-  { data: matrixData },
-);
-MetricMatrix.displayName = "MetricMatrix";
-
-/** 分组条形:同一份矩阵数据的另一种摆法;MetricBars.data 就是 MetricMatrix.data 的别名。 */
-export const MetricBars: ReportComponent<MetricMatrixProps> & { data: typeof matrixData } = Object.assign(
-  defineComponent<MetricMatrixProps>({
-    web: (props, ctx) => (
-      <MetricBarsWeb
-        {...props}
-        locale={props.locale ?? ctx.locale}
-        attemptHref={props.attemptHref ?? (isHostWebContextActive() ? ctx.attemptHref : undefined)}
-      />
-    ),
-    text: ({ data }) => barsText(data),
-  }),
-  { data: matrixData },
-);
-MetricBars.displayName = "MetricBars";
-
-/** 考试成绩单:总分 + 分科小计,固定分母、missing 如实报。 */
-export const Scoreboard: ReportComponent<ScoreboardProps> & { data: typeof scoreboardData } = Object.assign(
-  defineComponent<ScoreboardProps>({
-    web: (props, ctx) => <ScoreboardWeb {...props} locale={props.locale ?? ctx.locale} />,
-    text: ({ data }, ctx) => scoreboardText(data, ctx),
-  }),
-  { data: scoreboardData },
-);
-Scoreboard.displayName = "Scoreboard";
-
-/** 质量 × 成本 frontier:每个点一个配置、两个指标各占一轴,「好」的角落恒在右上。 */
-export const MetricScatter: ReportComponent<MetricScatterProps> & { data: typeof scatterData } = Object.assign(
-  defineComponent<MetricScatterProps, MetricScatterResolvedProps>({
-    resolve: async (props) => {
-      if ("data" in props && props.data !== undefined) return props;
-      const { selection, points, series, x, y, ...rest } = props;
-      return { ...rest, data: await scatterData(selection, { points, series, x, y }) };
-    },
-    web: (props, ctx) => {
-      requireScatterData(props);
-      return <MetricScatterWeb {...props} locale={props.locale ?? ctx.locale} />;
-    },
-    text: (props, ctx) => scatterText(requireScatterData(props), ctx),
-  }),
-  { data: scatterData },
-);
-MetricScatter.displayName = "MetricScatter";
-
-/** 趋势线:x 是 experiment 声明的 flag(flag()),同系列按 x 排序连线。 */
-export const MetricLine: ReportComponent<MetricLineProps> & { data: typeof lineData } = Object.assign(
-  defineComponent<MetricLineProps>({
-    web: (props, ctx) => <MetricLineWeb {...props} locale={props.locale ?? ctx.locale} />,
-    text: ({ data }, ctx) => lineText(data, ctx),
-  }),
-  { data: lineData },
-);
-MetricLine.displayName = "MetricLine";
-
-/** 成对对比:每行一对配置、格子里 A、B、Δ 三个值,涨跌好坏由 better 判定。 */
-export const DeltaTable: ReportComponent<DeltaTableProps> & { data: typeof deltaData } = Object.assign(
-  defineComponent<DeltaTableProps>({
-    web: (props, ctx) => <DeltaTableWeb {...props} locale={props.locale ?? ctx.locale} />,
-    text: ({ data }, ctx) => deltaText(data, ctx),
-  }),
-  { data: deltaData },
-);
-DeltaTable.displayName = "DeltaTable";
+export const MetricMatrix = makeDataComponent<
+  MatrixData,
+  MetricMatrixOptions,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>({
+  name: "MetricMatrix",
+  dataFnName: "metricMatrixData",
+  shapeName: "MatrixData",
+  dataFn: metricMatrixData,
+  specKeys: ["rows", "columns", "cell", "evals"],
+  validate: validateMatrixData,
+  web: (props, ctx) => (
+    <MetricMatrixWeb data={props.data} locale={props.locale ?? ctx.locale} attemptHref={hrefOf(props, ctx)} className={props.className} />
+  ),
+  text: (props, ctx) => matrixText(props.data, ctx),
+}) as unknown as ReportComponent<MetricMatrixProps>;
+
+/** 分组条形:同一份矩阵数据的另一种摆法;与 MetricMatrix 写同一份 spec 时只计算一次。 */
+export const MetricBars = makeDataComponent<
+  MatrixData,
+  MetricMatrixOptions,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>({
+  name: "MetricBars",
+  dataFnName: "metricMatrixData",
+  shapeName: "MatrixData",
+  dataFn: metricMatrixData,
+  specKeys: ["rows", "columns", "cell", "evals"],
+  validate: validateMatrixData,
+  web: (props, ctx) => (
+    <MetricBarsWeb data={props.data} locale={props.locale ?? ctx.locale} attemptHref={hrefOf(props, ctx)} className={props.className} />
+  ),
+  text: (props, ctx) => barsText(props.data, ctx),
+}) as unknown as ReportComponent<MetricBarsProps>;
+
+export type ScoreboardProps = DataProps<
+  ScoreboardData,
+  ScoreboardOptions,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>;
+
+/** 考试成绩单:总分 + 分科小计,固定分母、notRun / unscorable 分开如实报。 */
+export const Scoreboard = makeDataComponent<
+  ScoreboardData,
+  ScoreboardOptions,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>({
+  name: "Scoreboard",
+  dataFnName: "scoreboardData",
+  shapeName: "ScoreboardData",
+  dataFn: scoreboardData,
+  specKeys: ["rows", "questions", "subject", "weights", "fullMarks", "score"],
+  validate: validateScoreboardData,
+  web: (props, ctx) => <ScoreboardWeb data={props.data} locale={props.locale ?? ctx.locale} className={props.className} />,
+  text: (props, ctx) => scoreboardText(props.data, ctx),
+}) as unknown as ReportComponent<ScoreboardProps>;
+
+export type MetricScatterProps = DataProps<
+  ScatterData,
+  MetricScatterOptions,
+  ChromeProps & { pointHref?: (row: ScatterData["rows"][number]) => string }
+>;
+
+/** 两个指标之间的取舍:每个点一个维度值,x / y 各一个指标,series 只决定颜色和分组。 */
+export const MetricScatter = makeDataComponent<
+  ScatterData,
+  MetricScatterOptions,
+  ChromeProps & { pointHref?: (row: ScatterData["rows"][number]) => string }
+>({
+  name: "MetricScatter",
+  dataFnName: "metricScatterData",
+  shapeName: "ScatterData",
+  dataFn: metricScatterData,
+  specKeys: ["points", "series", "x", "y", "evals"],
+  validate: validateScatterData,
+  web: (props, ctx) => (
+    <MetricScatterWeb data={props.data} pointHref={props.pointHref} locale={props.locale ?? ctx.locale} className={props.className} />
+  ),
+  text: (props, ctx) => scatterText(props.data, ctx),
+}) as unknown as ReportComponent<MetricScatterProps>;
+
+export type MetricLineProps = DataProps<
+  LineData,
+  MetricLineOptions,
+  ChromeProps & { pointHref?: (row: LineData["rows"][number]) => string }
+>;
+
+/** 趋势线:x 是 NumericAxis(参数轴),点身份 = (series, x)。 */
+export const MetricLine = makeDataComponent<
+  LineData,
+  MetricLineOptions,
+  ChromeProps & { pointHref?: (row: LineData["rows"][number]) => string }
+>({
+  name: "MetricLine",
+  dataFnName: "metricLineData",
+  shapeName: "LineData",
+  dataFn: metricLineData,
+  specKeys: ["x", "series", "y", "evals"],
+  validate: validateLineData,
+  web: (props, ctx) => (
+    <MetricLineWeb data={props.data} pointHref={props.pointHref} locale={props.locale ?? ctx.locale} className={props.className} />
+  ),
+  text: (props, ctx) => lineText(props.data, ctx),
+}) as unknown as ReportComponent<MetricLineProps>;
+
+export type DeltaTableProps = DataProps<
+  DeltaData,
+  DeltaTableOptions,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>;
+
+/** 成对对比:每行一对(字面声明或 pairsByFlag 派生),格子里 A、B、Δ 三个值。 */
+export const DeltaTable = makeDataComponent<
+  DeltaData,
+  DeltaTableOptions,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>({
+  name: "DeltaTable",
+  dataFnName: "deltaTableData",
+  shapeName: "DeltaData",
+  dataFn: deltaTableData,
+  specKeys: ["by", "pairs", "metrics", "evals"],
+  validate: validateDeltaData,
+  web: (props, ctx) => <DeltaTableWeb data={props.data} locale={props.locale ?? ctx.locale} className={props.className} />,
+  text: (props, ctx) => deltaText(props.data, ctx),
+}) as unknown as ReportComponent<DeltaTableProps>;