niceeval 0.5.4 → 0.6.1

package/src/report/types.ts

@@ -1,10 +1,15 @@
 // niceeval/report 的公开类型:指标(Metric)、维度(Dimension / flag())与计算函数
-// 产物(即组件的 data props)。数据契约照 docs/reports.md「计算函数与数据契约」;
+// 产物(即组件的 data props)。数据契约照 docs/feature/reports/library.md「数据计算与缓存边界」;
 // 这些不是持久化格式,没有 format / schemaVersion 信封,兼容性跟随 npm 版本。
 
-import type { AttemptHandle, AttemptRef, SelectionWarning } from "../results/index.ts";
+import type { AttemptHandle, SelectionWarning } from "../results/types.ts";
+import type { AttemptLocator } from "../results/locator.ts";
+import type { AssertionResult, Verdict } from "../types.ts";
+import type { LocalizedLabel, ReportLocale } from "./locale.ts";
 
-export type { AttemptRef, SelectionWarning };
+export type { SelectionWarning };
+export type { AttemptLocator };
+export type { LocalizedLabel, ReportLocale };
 
 // ───────────────────────── 指标与聚合 ─────────────────────────
 
@@ -31,8 +36,11 @@ export interface MetricAggregate {
 export interface Metric<Name extends string = string> {
   /** MetricColumn.key 与列头的来源;同一次计算里重名是错误。 */
   name: Name;
-  /** 列头;省略时用 name。 */
-  label?: string;
+  /**
+   * 列头;省略时用 name。可以给按 locale 的字典({ en, "zh-CN" }),
+   * 渲染面按宿主 locale 解析,缺项回退 en(display 是 format 产物,不本地化)。
+   */
+  label?: LocalizedLabel;
   description?: string;
   /** 渲染提示:越高越好还是越低越好(排序方向、轴向、涨跌配色用)。 */
   better?: "higher" | "lower";
@@ -86,7 +94,8 @@ export type DimensionInput = Dimension | FlagRef;
 export interface MetricColumn {
   /** = metric.name,与 cells 的键对应。 */
   key: string;
-  label: string;
+  /** 数据层原样携带 metric.label(可本地化);渲染面用 resolveMetricLabel 按 locale 解析。 */
+  label: LocalizedLabel;
   unit?: string;
   /** 渲染提示:排序方向、轴向、涨跌配色。 */
   better?: "higher" | "lower";
@@ -105,7 +114,39 @@ export interface MetricCell {
    * 这个格子由哪些 attempt 算出 —— 回到证据的引用。必填(可空数组):
    * 「每个数字点进去就是证据」是页面的核心承诺,可选字段会让深链静默缺失。
    */
-  refs: AttemptRef[];
+  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`。
+ */
+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。 */
@@ -113,7 +154,7 @@ export interface TableData<K extends string = string> {
   /** 行维度名,如 "agent"。 */
   dimension: string;
   columns: MetricColumn[];
-  rows: { key: string; cells: Record<K, MetricCell> }[];
+  rows: { key: string; cells: Record<K, MetricCell>; meta?: TableRowMeta<K> }[];
 }
 
 export interface MatrixData {
@@ -199,20 +240,67 @@ export interface LineData {
   }[];
 }
 
+/**
+ * 一组 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(passRate, items)`,与 `MetricTable.data(...,
+     * columns: [passRate])` 同一台两级聚合引擎(题内折叠 perEval、跨题折叠 across,默认都是
+     * mean)——一道题内多个 attempt 部分通过,贡献的是小数份额而不是二元票。`samples`/`total`
+     * 是两级聚合口径下的 attempt 计数(`total` 含 skipped,`samples` 不含),不等于上面四个
+     * verdict 计票的任何一个之和。
+     */
+    passRate: MetricCell;
     /** 任一 attempt 报了成本才有;全缺 = null,不编 0。 */
     costUSD: number | null;
     durationMs: number;
   };
-  /** 选集的警告随行(结构化,含渲染好的 message),RunOverview 直接渲染。 */
+  /** Selection 的警告随行(结构化,含渲染好的 message),RunOverview 直接渲染。 */
   warnings: SelectionWarning[];
 }
 
@@ -239,20 +327,91 @@ export interface DeltaData<K extends string = string> {
   }[];
 }
 
-export interface CaseListData {
-  rows: {
-    eval: string;
-    experimentId: string;
-    agent: string;
-    outcome: "failed" | "errored";
-    /** errored 的错误摘要(已过 redact)。 */
-    error?: string;
-    failedAssertions: { name: string; score: number; detail?: string; evidence?: string }[];
-    durationMs: number;
-    costUSD?: number;
-    /** 每条案例都能回到证据。 */
-    ref: AttemptRef;
-  }[];
-  /** limit 之外还有几条,如实报,不静默截断。 */
-  truncated: number;
+// ───────────────────────── 实体列表(ExperimentList / EvalList / AttemptList)─────────────────────────
+//
+// 三个组件按「experiment → experimentId × eval → attempt」逐级下钻,固定展示实体事实,
+// 没有列配置(docs/feature/reports/library.md「实体列表」)。每一级都以下一级的 `AttemptListItem[]`
+// 收尾——同一个类型既是 `AttemptList` 自己的 items,也是 `ExperimentListEvalRow.attempts` /
+// `EvalListItem.attempts` 的元素,报告作者可以直接把这些嵌套数组喂给 `<AttemptList items={...} />`。
+
+/**
+ * `AttemptList` 一项 = 一个 Attempt:身份、判定、断言、error、耗时、成本和 locator。
+ * `ExperimentList` / `EvalList` 的下钻数组复用同一个类型,不是各自的精简版。
+ */
+export interface AttemptListItem {
+  evalId: string;
+  experimentId: string;
+  attempt: number;
+  agent: string;
+  verdict: Verdict;
+  error?: string;
+  assertions: AssertionResult[];
+  durationMs: number;
+  costUSD?: number;
+  locator: AttemptLocator;
+}
+
+/**
+ * `ExperimentList` 一项里,一个 Eval 的展开行:折叠判定(`foldEvalVerdict`)、失败原因摘要
+ * (`error` → `skipReason` → 未通过的 gate 断言,`reasonFor` 的口径,soft 断言永不进入)、
+ * 该 Eval 内 attempt 的平均耗时/成本(两级聚合引擎在单一 eval 上退化成组内均值),以及这道题
+ * 的全部 Attempt(升序,供进一步展开到 `AttemptList`)。
+ */
+export interface ExperimentListEvalRow {
+  evalId: string;
+  /** 折叠判定(任一 attempt 通过则通过,否则取最严重的)。 */
+  verdict: Verdict;
+  reason?: string;
+  /** 这道题内 attempt 的平均耗时(`computeCell(durationMs, …)`,单一 eval 分组下即均值)。 */
+  duration: MetricCell;
+  /** 这道题内 attempt 的平均成本。 */
+  cost: MetricCell;
+  /** 这道题的全部 Attempt,按 attempt 序号升序。 */
+  attempts: AttemptListItem[];
+}
+
+/**
+ * `ExperimentList.data(selection)` 的一项 = 一个 experiment:身份(experimentId/agent/model)、
+ * 声明的 flags、Eval 判定构成(`foldEvalVerdict` 计票,与 view 榜单同一口径)、官方两级聚合
+ * 汇总指标(passRate/cost/duration/tokens,直接来自 `computeCell`,不现场重算),以及展开到
+ * 这个 experiment 每道 Eval 的 `evalRows`(按 eval id 升序)。
+ */
+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 };
+  /** 官方两级聚合口径,与 `MetricTable.data(..., columns: [passRate])` 同一台引擎。 */
+  passRate: MetricCell;
+  cost: MetricCell;
+  duration: MetricCell;
+  tokens: MetricCell;
+  /** 这个 experiment 覆盖的 eval 数(去重后,与 `verdicts` 四项之和一致)。 */
+  evals: number;
+  /** 这个 experiment 覆盖的 attempt 总数(原始计数,含多轮重试)。 */
+  attempts: number;
+  /** 所含快照中最近的 startedAt。 */
+  lastRunAt: string;
+  /** 展开到这个 experiment 的 Eval,按 eval id 升序。 */
+  evalRows: ExperimentListEvalRow[];
+}
+
+/**
+ * `EvalList.data(selection)` 的一项 = 一个 `experimentId + evalId`(同一个 Eval 跑在两个
+ * experiment 上是两条不同结果,不合并)。判定、分数(examScore 的两级聚合)、这道题内 attempt
+ * 的平均耗时/成本,失败原因摘要(与 `ExperimentListEvalRow.reason` 同一口径),外加展开到这道题
+ * 全部 Attempt 的 `attempts`(按 attempt 序号升序)。
+ */
+export interface EvalListItem {
+  evalId: string;
+  experimentId: string;
+  verdict: Verdict;
+  reason?: string;
+  /** examScore 的两级聚合;单一 eval 分组下即这道题的题级分数。 */
+  score: MetricCell;
+  duration: MetricCell;
+  cost: MetricCell;
+  attempts: AttemptListItem[];
 }

package/src/report/web.ts

@@ -5,36 +5,63 @@
 import * as React from "react";
 import type { ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-
-// tsx 按「tsconfig 所在目录」为界应用 jsx 配置:CLI 在用户项目 cwd 下跑时,包内
-// .tsx(primitives / react 组件的 web 面)落在用户 tsconfig 覆盖范围之外,esbuild
-// 退化成 classic JSX(编译产物引用全局 React)。这里补上全局 React,web 面在两种
-// 编译模式下都可渲染;只定义一次,不覆盖宿主已有的全局。
-const g = globalThis as { React?: unknown };
-if (g.React === undefined) g.React = React;
-import type { AttemptRef } from "../results/index.ts";
-import { runWithWebContext, validateReportTree, type WebContext } from "./tree.ts";
-import { prepareDefaultReportData, runWithDefaultReportData } from "./default-report.tsx";
+import type { AttemptLocator } from "../results/locator.ts";
+import type { SelectionWarning } from "../results/types.ts";
+import { resolveReportTree, runWithWebContext, validateReportTree, type WebContext } from "./tree.ts";
+import { DEFAULT_REPORT_LOCALE, type ReportLocale } from "./locale.ts";
 import type { ReportContext, ReportDefinition } from "./report.ts";
 
 export interface StaticHtmlOptions {
-  /** 证据室深链;缺省用 view 的 attempt 路由 `#/attempt/<run>/<result>`。 */
-  attemptHref?: (ref: AttemptRef) => string;
+  /** 证据室深链;缺省用 view 的 attempt 路由 `#/attempt/@<locator>`(单段、不透明)。 */
+  attemptHref?: (locator: AttemptLocator) => string;
+  /** 官方组件 chrome 文案的 locale;默认 "en"。 */
+  locale?: ReportLocale;
 }
 
-/** build → 渲染前树校验(与 text 宿主同一遍)→ 备好官方水位 → 静态渲染 web 面。 */
+/**
+ * 挑选警告的 HTML 形态:宿主级前置块,与 RunOverview 里的警告用同一套结构和类名
+ * (`.nre nre-report-warnings` 外壳内一个 `ul.nre-warnings` + `li.nre-warning[data-kind]`,
+ * 复用 styles.css 已有的 `.nre .nre-warnings` 样式)。经 renderToStaticMarkup 走 React,
+ * message 文本自动转义,不裸拼 HTML。裸跑 / --report 都在报告顶上如实报残缺,不静默。
+ */
+function renderSelectionWarningsHtml(warnings: SelectionWarning[]): string {
+  return renderToStaticMarkup(
+    React.createElement(
+      "div",
+      { className: "nre nre-report-warnings" },
+      React.createElement(
+        "ul",
+        { className: "nre-warnings" },
+        warnings.map((w, i) =>
+          React.createElement("li", { key: i, className: "nre-warning", "data-kind": w.kind }, w.message),
+        ),
+      ),
+    ),
+  );
+}
+
+/**
+ * build → 渲染前解析数据组件(唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染
+ * web 面;Selection 有挑选警告时在报告顶部前置一块警告 HTML；报告树里的 RunOverview
+ * 已经渲染同一条时不重复。
+ */
 export async function renderReportToStaticHtml(
   definition: ReportDefinition,
   ctx: ReportContext,
   options?: StaticHtmlOptions,
 ): Promise<string> {
   const node = await definition.build(ctx);
-  validateReportTree(node);
-  const defaultData = await prepareDefaultReportData(ctx.selection);
+  const resolved = await resolveReportTree(node);
+  validateReportTree(resolved);
   const webCtx: WebContext = {
-    attemptHref: options?.attemptHref ?? ((ref) => `#/attempt/${ref.run}/${ref.result}`),
+    attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
+    locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
   };
-  return runWithDefaultReportData(defaultData, () =>
-    runWithWebContext(webCtx, () => renderToStaticMarkup(node as ReactNode)),
-  );
+  const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
+  const missingWarnings = ctx.selection.warnings.filter((warning) => {
+    const escapedMessage = renderToStaticMarkup(React.createElement(React.Fragment, null, warning.message));
+    return !body.includes(escapedMessage);
+  });
+  const warnings = missingWarnings.length > 0 ? renderSelectionWarningsHtml(missingWarnings) : "";
+  return warnings + body;
 }

package/src/results/annotated-source.test.ts

@@ -0,0 +1,146 @@
+// buildAnnotatedEvalSource 的单测(定稿见 docs/concepts.md「标注 Eval 源码」)。
+// 覆盖:同一行多条断言、无 loc 断言进 unmapped、loc 指向别的文件/越界行也进 unmapped
+// (never silently dropped 的边界情况)、空断言数组、summary 计数、哈希与归一化行为。
+
+import { describe, expect, it } from "vitest";
+import type { AssertionResult } from "../types.ts";
+import { buildAnnotatedEvalSource } from "./annotated-source.ts";
+import { hashEvalSource, normalizeEvalSource } from "./source-hash.ts";
+
+const SOURCE_PATH = "evals/weather.eval.ts";
+
+function assertion(over: Partial<AssertionResult> & Pick<AssertionResult, "name">): AssertionResult {
+  return {
+    severity: "soft",
+    score: 1,
+    passed: true,
+    ...over,
+  };
+}
+
+describe("buildAnnotatedEvalSource", () => {
+  it("maps multiple assertions on the same line, preserving input order", () => {
+    const content = "line 1\nline 2\nline 3\n";
+    const a1 = assertion({ name: "first", loc: { file: SOURCE_PATH, line: 2 } });
+    const a2 = assertion({ name: "second", loc: { file: SOURCE_PATH, line: 2 } });
+    const a3 = assertion({ name: "third", loc: { file: SOURCE_PATH, line: 1 } });
+
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content }, [a1, a2, a3]);
+
+    expect(model.lines).toHaveLength(3);
+    expect(model.lines[0]!.assertions.map((a) => a.name)).toEqual(["third"]);
+    expect(model.lines[1]!.assertions.map((a) => a.name)).toEqual(["first", "second"]);
+    expect(model.lines[2]!.assertions).toEqual([]);
+    expect(model.unmapped).toEqual([]);
+    expect(model.summary.mappedAssertions).toBe(3);
+    expect(model.summary.unmappedAssertions).toBe(0);
+  });
+
+  it("buckets an assertion with no SourceLoc into unmapped, never dropping it", () => {
+    const content = "only line\n";
+    const withLoc = assertion({ name: "has-loc", loc: { file: SOURCE_PATH, line: 1 } });
+    const withoutLoc = assertion({ name: "no-loc" });
+
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content }, [withLoc, withoutLoc]);
+
+    expect(model.lines[0]!.assertions.map((a) => a.name)).toEqual(["has-loc"]);
+    expect(model.unmapped.map((a) => a.name)).toEqual(["no-loc"]);
+    expect(model.summary.totalAssertions).toBe(2);
+    expect(model.summary.mappedAssertions).toBe(1);
+    expect(model.summary.unmappedAssertions).toBe(1);
+  });
+
+  it("buckets an assertion whose loc points at a different file into unmapped", () => {
+    const content = "a\nb\n";
+    const elsewhere = assertion({ name: "elsewhere", loc: { file: "evals/other.eval.ts", line: 1 } });
+
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content }, [elsewhere]);
+
+    expect(model.lines.every((l) => l.assertions.length === 0)).toBe(true);
+    expect(model.unmapped).toEqual([elsewhere]);
+  });
+
+  it("buckets an assertion whose loc.line is out of range into unmapped", () => {
+    const content = "a\nb\n"; // 2 lines
+    const tooHigh = assertion({ name: "too-high", loc: { file: SOURCE_PATH, line: 3 } });
+    const tooLow = assertion({ name: "too-low", loc: { file: SOURCE_PATH, line: 0 } });
+
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content }, [tooHigh, tooLow]);
+
+    expect(model.lines.every((l) => l.assertions.length === 0)).toBe(true);
+    expect(model.unmapped.map((a) => a.name).sort()).toEqual(["too-high", "too-low"]);
+  });
+
+  it("handles an empty assertions array: lines are still built, everything else is zeroed", () => {
+    const content = "a\nb\nc\n";
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content }, []);
+
+    expect(model.lines).toHaveLength(3);
+    expect(model.lines.every((l) => l.assertions.length === 0)).toBe(true);
+    expect(model.unmapped).toEqual([]);
+    expect(model.summary).toEqual({
+      totalAssertions: 0,
+      mappedAssertions: 0,
+      unmappedAssertions: 0,
+      passed: 0,
+      failed: 0,
+      gate: 0,
+      soft: 0,
+      totalLines: 3,
+      annotatedLines: 0,
+    });
+  });
+
+  it("computes summary counts across passed/failed and gate/soft, mapped and unmapped alike", () => {
+    const content = "line 1\nline 2\n";
+    const assertions = [
+      assertion({ name: "a", severity: "gate", passed: true, loc: { file: SOURCE_PATH, line: 1 } }),
+      assertion({ name: "b", severity: "gate", passed: false, loc: { file: SOURCE_PATH, line: 1 } }),
+      assertion({ name: "c", severity: "soft", passed: true, loc: { file: SOURCE_PATH, line: 2 } }),
+      assertion({ name: "d", severity: "soft", passed: false }), // unmapped
+    ];
+
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content }, assertions);
+
+    expect(model.summary).toEqual({
+      totalAssertions: 4,
+      mappedAssertions: 3,
+      unmappedAssertions: 1,
+      passed: 2,
+      failed: 2,
+      gate: 2,
+      soft: 2,
+      totalLines: 2,
+      annotatedLines: 2,
+    });
+  });
+
+  it("does not produce a phantom trailing blank line for source text ending in a newline", () => {
+    const content = "a\nb\n";
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content }, []);
+    expect(model.lines.map((l) => l.text)).toEqual(["a", "b"]);
+  });
+
+  it("keeps a real trailing blank line when the source has one (double newline)", () => {
+    const content = "a\nb\n\n";
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content }, []);
+    expect(model.lines.map((l) => l.text)).toEqual(["a", "b", ""]);
+  });
+
+  it("treats an empty source file as a single empty line", () => {
+    const model = buildAnnotatedEvalSource({ path: SOURCE_PATH, content: "" }, []);
+    expect(model.lines).toEqual([{ line: 1, text: "", assertions: [] }]);
+  });
+
+  it("sourceSha256 matches hashEvalSource(normalizeEvalSource(content)) and is stable across CRLF/LF", () => {
+    const lf = "a\nb\nc\n";
+    const crlf = "a\r\nb\r\nc\r\n";
+
+    const modelLf = buildAnnotatedEvalSource({ path: SOURCE_PATH, content: lf }, []);
+    const modelCrlf = buildAnnotatedEvalSource({ path: SOURCE_PATH, content: crlf }, []);
+
+    expect(modelLf.sourceSha256).toBe(hashEvalSource(normalizeEvalSource(lf)));
+    expect(modelLf.sourceSha256).toBe(modelCrlf.sourceSha256);
+    expect(modelLf.lines.map((l) => l.text)).toEqual(modelCrlf.lines.map((l) => l.text));
+  });
+});

package/src/results/annotated-source.ts

@@ -0,0 +1,128 @@
+// AnnotatedEvalSource:标注 Eval 源码(定稿见 docs/concepts.md「结果数据与报告」、
+// docs/concepts.md「Attempt 证据」)。把一份 eval 源码文本与该次运行产出的
+// AssertionResult[] 叠在一起 —— 每条断言按 SourceLoc 标回源码行,没有(或够不上)行映射的
+// 断言进 `unmapped` 桶,不静默丢弃。这是共享 model:未来的网页 CodeView 与
+// `show --eval` 文本 renderer 只消费这同一份数据,不各自重新分桶。
+//
+// 泛化自 src/view/app/lib/transcript-data.tsx 的 indexAsserts()(Map<string, Assertion[]>
+// + noloc 兜底桶的先例)——同一套"按 loc 分桶、没有 loc 进兜底"的思路,换成源码行数组
+// (不是 Map)存放,外加 sourceSha256 / summary 计数。indexTurns() 那部分(events → 轮次)
+// 是 ExecutionTree 的地盘,不在这个模型里。
+//
+// 本模块不 import react/jsx,纯数据 + 纯函数,可以在任何 Node 语境(CLI 的 show、
+// view 的 server 端数据准备)调用。
+
+import type { AssertionResult } from "../types.ts";
+import { hashEvalSource, normalizeEvalSource } from "./source-hash.ts";
+
+/** 一行源码 + 映射到这一行的全部断言(保持原始顺序;可以是空数组)。 */
+export interface AnnotatedSourceLine {
+  /** 1-indexed 行号,与 SourceLoc.line 同一坐标系。 */
+  line: number;
+  /** 这一行的原始文本(已按 normalizeEvalSource 归一化,不含行尾换行符)。 */
+  text: string;
+  /**
+   * 映射到这一行的断言,按输入顺序(通常即执行顺序)排列。每条断言自带 severity / score /
+   * passed / detail / evidence —— 这就是"状态 / 严重度 / 分数 / detail / evidence"标回源码行
+   * 的完整信息,不需要额外的行级折叠字段:折叠成单一显示态是 renderer 的展示决定,不是这份
+   * 领域 model 的职责(与 indexAsserts() 的先例一致,它同样只分桶、不折叠)。
+   */
+  assertions: AssertionResult[];
+}
+
+export interface AnnotatedEvalSourceSummary {
+  /** 参与统计的断言总数 = mappedAssertions + unmappedAssertions。 */
+  totalAssertions: number;
+  /** 成功映射到某一行源码的断言数。 */
+  mappedAssertions: number;
+  /** 落进 unmapped 桶的断言数。 */
+  unmappedAssertions: number;
+  /** 按 passed 计票(映射与未映射的断言都计入)。 */
+  passed: number;
+  failed: number;
+  /** 按 severity 计票(映射与未映射的断言都计入)。 */
+  gate: number;
+  soft: number;
+  /** 源码总行数,等于 lines.length。 */
+  totalLines: number;
+  /** 至少挂了一条断言的行数。 */
+  annotatedLines: number;
+}
+
+export interface AnnotatedEvalSource {
+  /** 项目相对路径,与 SourceArtifact.path / SourceLoc.file 同一约定。 */
+  sourcePath: string;
+  /** 归一化后源码文本的 SHA-256(与 captureEvalSource() 的算法一致,见 source-hash.ts)。 */
+  sourceSha256: string;
+  lines: AnnotatedSourceLine[];
+  /**
+   * 没有落到 lines 里任何一行的断言,原始顺序保留,永不丢弃。三种情况都进这里:
+   * 没有 SourceLoc(如 skip 前就出错的 eval、或调用方尚未收集到位置)、SourceLoc 指向
+   * 另一个文件(loc.file !== sourcePath —— 罕见,如断言写在共享 helper 里)、
+   * SourceLoc 的行号落在这份源码的行范围之外(源码与断言记录不同步的边界情况)。
+   * 后两种不是文档明确要求的场景,但"never silently dropped"的契约对它们同样成立 ——
+   * 这份 model 是分桶断言的唯一出口,不属于任何一行就必须出现在这里。
+   */
+  unmapped: AssertionResult[];
+  summary: AnnotatedEvalSourceSummary;
+}
+
+/**
+ * 纯函数:给定一份源码文本(未归一化也可以,内部会 normalizeEvalSource)与一批断言,
+ * 产出标注好的 AnnotatedEvalSource。幂等 / 无 IO —— 可以在渲染路径上安全调用。
+ *
+ * 断言 → 源码行的映射规则:`a.loc` 存在、`a.loc.file === source.path`、且
+ * `1 <= a.loc.line <= lines.length` 三者同时成立才落到对应行;否则进 `unmapped`。
+ */
+export function buildAnnotatedEvalSource(
+  source: { path: string; content: string },
+  assertions: readonly AssertionResult[],
+): AnnotatedEvalSource {
+  const normalized = normalizeEvalSource(source.content);
+  // 末尾的单个换行符不产出幻影空行(源码文件几乎总以换行符收尾);中间的空行原样保留为一行。
+  const body = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
+  const rawLines = body.length === 0 && normalized.length === 0 ? [""] : body.split("\n");
+
+  const lines: AnnotatedSourceLine[] = rawLines.map((text, i) => ({ line: i + 1, text, assertions: [] }));
+
+  const unmapped: AssertionResult[] = [];
+  let mappedAssertions = 0;
+  let passed = 0;
+  let failed = 0;
+  let gate = 0;
+  let soft = 0;
+
+  for (const assertion of assertions) {
+    if (assertion.passed) passed++;
+    else failed++;
+    if (assertion.severity === "gate") gate++;
+    else soft++;
+
+    const loc = assertion.loc;
+    const target = loc && loc.file === source.path && loc.line >= 1 && loc.line <= lines.length ? lines[loc.line - 1] : undefined;
+    if (target) {
+      target.assertions.push(assertion);
+      mappedAssertions++;
+    } else {
+      unmapped.push(assertion);
+    }
+  }
+
+  return {
+    sourcePath: source.path,
+    sourceSha256: hashEvalSource(normalized),
+    lines,
+    unmapped,
+    summary: {
+      totalAssertions: assertions.length,
+      mappedAssertions,
+      unmappedAssertions: unmapped.length,
+      passed,
+      failed,
+      gate,
+      soft,
+      totalLines: lines.length,
+      annotatedLines: lines.reduce((n, l) => n + (l.assertions.length > 0 ? 1 : 0), 0),
+    },
+  };
+}