niceeval 0.9.0 → 0.10.0

package/src/report/runtime/host.test.ts

@@ -0,0 +1,44 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 「外壳、页面与 Tabs」——宿主装载分流(文件 vs 内建)。
+// 装载规范化(content/pages/extends、page id、input/navigation、标题回退、icon)全部是
+// `defineReport` 自己的产物,由 src/report/runtime/dual-render.test.tsx 直接对着真实实现测试;
+// 这里只测 host facade 仍然私有的编排:内建报告分流与 LocalizedText 回退。
+
+import { describe, expect, it } from "vitest";
+import { HostReportError, loadHostReport, localizeText } from "./host.ts";
+// dist-sourced:裸宿主装载的就是这份预编译产物的默认导出(show 与 view 同一条路),
+// raw-src import 会是另一份模块实例,引用等同断言必须对着 dist。
+import distBuiltInReport from "../../../dist/report/built-in/index.js";
+
+describe("裸宿主装载内建报告", () => {
+  it("缺省(无 --report)装载 niceeval/report/built-in 的默认导出:同引用,页与其 content 同引用", async () => {
+    const host = await loadHostReport(process.cwd(), undefined);
+    const builtIn = distBuiltInReport as { pages: readonly { id: string; content: unknown }[] };
+    expect(host).toBe(distBuiltInReport);
+    expect(host.pages.map((p: { id: string }) => p.id)).toEqual(builtIn.pages.map((p) => p.id));
+    for (let i = 0; i < host.pages.length; i++) {
+      expect(host.pages[i]!.content).toBe(builtIn.pages[i]!.content);
+    }
+  });
+
+  it("--report <文件> 走文件装载;找不到文件时是 HostReportError 同族的可预期错误", async () => {
+    // loadHostReport 对文件路径委托 dist 里的 loadReportFile;这里只验证分流本身发生
+    // (文件装载错误的具体文案由 src/report/runtime/load.ts 自己的测试覆盖)。
+    await expect(loadHostReport(process.cwd(), "does/not/exist.tsx")).rejects.toThrow();
+  });
+});
+
+describe("LocalizedText 回退:locale → en → 键字典序第一个非空值", () => {
+  it("三级回退各自命中;undefined 输入原样返回 undefined", () => {
+    expect(localizeText({ "zh-CN": "中", en: "E" }, "zh-CN")).toBe("中");
+    expect(localizeText({ "zh-CN": "中", en: "E" }, "fr")).toBe("E");
+    expect(localizeText({ "zh-TW": "繁", ja: "日" }, "en")).toBe("日"); // ja < zh-TW 字典序
+    expect(localizeText("plain", "en")).toBe("plain");
+    expect(localizeText({}, "en")).toBeUndefined();
+    expect(localizeText(undefined, "en")).toBeUndefined();
+  });
+});
+
+it("HostReportError 是可预期用户错误(与 ReportLoadError 同待遇,不是内部异常)", () => {
+  expect(new HostReportError("x")).toBeInstanceOf(Error);
+});

package/src/report/runtime/host.ts

@@ -0,0 +1,138 @@
+// 报告装载与逐页渲染的中性宿主 facade:show 与 view 共用(docs/feature/reports/architecture.md
+// 「共享内核与两个宿主的代码边界」「单一 report runtime 身份」)。ReportDefinition / ReportPage /
+// ReportMeta 的类型体系,以及装载规范化、resolve、text/web render 全部住在 niceeval/report 的
+// 构建单元(src/report/**,经 `pnpm run build:report` 编译进 dist/report/**);这里只做两个
+// 宿主都需要、但只属于宿主编排的一件事——文件 vs 内建报告的装载分流、逐页渲染——不重复声明
+// 任何报告类型或规范化逻辑。终端专属的可复制命令拼装(`showCommand`)不在这里,只有 show 需要,
+// 住在 src/show/command.ts。
+//
+// 本文件物理上住在 src/report/runtime/(host facade 的架构归属),但**不**参与
+// tsconfig.report-build.json 的编译单元(见该文件的 exclude 注释):它是调用方经 tsx 直接执行的
+// raw TypeScript,内部一律动态 import 兄弟 dist/report/** 产物——不是所有 show / view 命令都
+// 渲染报告,静态 import 会让不需要报告的命令也背上 react / react-dom 依赖(web.ts 静态 import
+// react-dom/server);同一进程也不能混用 raw src/report/** 与 dist/report/** 的同一状态模块,
+// 所以值和类型都从同一批 dist 模块拿,不从本文件的兄弟源码拿。
+
+import type { Results, Scope } from "../../results/index.ts";
+import type { LocalizedText } from "../../types.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+import type { PageContext } from "../../../dist/report/definition/tree.js";
+import type {
+  ReportDefinition,
+  ReportMeta,
+  ReportPage,
+} from "../../../dist/report/definition/report.js";
+
+export type { PageContext } from "../../../dist/report/definition/tree.js";
+export type {
+  HeadTag,
+  ReportAsset,
+  ReportDefinition,
+  ReportMeta,
+  ReportMetaPage,
+  ReportPage,
+} from "../../../dist/report/definition/report.js";
+
+/** 可预期的装载用户错误(与 ReportLoadError 同待遇:打一句直说问题与下一步,不抛堆栈)。 */
+export class HostReportError extends Error {}
+
+// ───────────────────────── 装载 ─────────────────────────
+
+/**
+ * 装载宿主报告:`--report <file>` 走 dist 里的 `loadReportFile`;缺省(裸 show / 裸 view)
+ * 装载内建 `standard`。两条路的产物都已经是 `defineReport` 规范化后的 `ReportDefinition`——
+ * 没有第二个规范化步骤,`defineReport` 本身就是唯一规范化点。
+ */
+export async function loadHostReport(
+  cwd: string,
+  reportPath: string | undefined,
+  options?: { freshImport?: boolean },
+): Promise<ReportDefinition> {
+  if (reportPath !== undefined) {
+    const { loadReportFile } = await import("../../../dist/report/runtime/load.js");
+    return loadReportFile(cwd, reportPath, options) as Promise<ReportDefinition>;
+  }
+  const { standard } = await import("../../../dist/report/built-in/index.js");
+  return standard as ReportDefinition;
+}
+
+/** ctx.report 的构建(不携带当前页——那是 HostRenderContext.page 的事)。 */
+export async function buildHostReportMeta(definition: ReportDefinition, scope: Scope): Promise<ReportMeta> {
+  const { buildReportMeta } = await import("../../../dist/report/definition/report.js");
+  return buildReportMeta(definition, scope);
+}
+
+/**
+ * LocalizedText 的确定回退(shell.md「行为约束」):当前 locale → en → 按 locale 键字典序的
+ * 第一个非空值。undefined 输入原样返回 undefined——两个宿主用它给"可能没声明"的字段
+ * (页标题、外壳字段)取显示字符串。算法与 niceeval/report 的 resolveLocalizedText 是同一份
+ * shell.md 文档契约的两处实现(这里没有报告类型或规范化状态,纯字符串函数,不经 dist 边界)。
+ */
+export function localizeText(text: LocalizedText | undefined, locale: string): string | undefined {
+  if (text === undefined) return undefined;
+  if (typeof text === "string") return text || undefined;
+  const exact = text[locale];
+  if (exact) return exact;
+  if (text.en) return text.en;
+  for (const key of Object.keys(text).sort()) {
+    if (text[key]) return text[key];
+  }
+  return undefined;
+}
+
+// ───────────────────────── 索引命令上下文 ─────────────────────────
+
+/**
+ * 宿主索引命令的完整上下文(docs/feature/reports/show/reports.md「索引命令携带完整上下文」)。
+ * 只是数据形状;拼出实际可复制的 `niceeval show ...` 命令字符串是 show 自己的事
+ * (`src/show/command.ts` 的 `showCommand`)——view 走网页路由,不生成终端命令。
+ */
+export interface HostCommandContext {
+  patterns: string[];
+  results?: string;
+  experiment?: string;
+  report?: string;
+  page?: string;
+}
+
+// ───────────────────────── 逐页渲染 ─────────────────────────
+
+/** 逐页渲染的宿主上下文:官方口径的 Scope、结果根读取面、规范化声明与当前页判别。 */
+export interface HostRenderContext {
+  scope: Scope;
+  results: Results;
+  report: ReportMeta;
+  page: PageContext;
+}
+
+export interface HostTextRenderOptions {
+  width?: number;
+  locale?: string;
+  /** 索引命令的完整上下文(docs/feature/reports/show/reports.md);逐页渲染时透传。 */
+  commandContext?: HostCommandContext;
+}
+
+/** 渲染一页的 text 面。 */
+export async function renderHostPageText(
+  page: ReportPage,
+  ctx: HostRenderContext,
+  options: HostTextRenderOptions,
+): Promise<string> {
+  const { renderReportTreeToText } = await import("../../../dist/report/runtime/text.js");
+  return renderReportTreeToText(page.content, ctx, options);
+}
+
+/**
+ * 渲染一页的 web 面(静态 HTML)。attemptHref 缺省时报告有 attempt-input page 就用
+ * niceeval/report 的根相对默认值(`attempt/<encodeURIComponent(locator)>.html`,index.html
+ * 视角);从 attempt 页面自身内容渲染时(该 page 引用了其它 locator)view 显式传入同级
+ * 相对版本覆盖它——两种情形都不在这里判断,只透传。
+ */
+export async function renderHostPageHtml(
+  page: ReportPage,
+  ctx: HostRenderContext,
+  options: { locale: string; attemptHref?: (locator: AttemptLocator) => string },
+): Promise<string> {
+  const { renderReportTreeToStaticHtml } = await import("../../../dist/report/runtime/web.js");
+  return renderReportTreeToStaticHtml(page.content, ctx, options);
+}

package/src/report/{load.ts → runtime/load.ts}

@@ -7,7 +7,7 @@
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { isReportDefinition, type ReportDefinition } from "./report.ts";
+import { isReportDefinition, type ReportDefinition } from "../definition/report.ts";
 
 /** 可预期的装载错误:宿主打一句英文直说问题与下一步,不抛堆栈。 */
 export class ReportLoadError extends Error {}

package/src/report/runtime/text.ts

@@ -0,0 +1,192 @@
+// text 宿主(show)的渲染入口:装载好的 ReportDefinition/page → resolve(组合展开 + spec 取数)
+// → validate(两面资格)→ render(纯同步字符输出)。web 宿主的对应入口在 ./web.ts(那一侧才
+// import react-dom)。管线以页为单位执行;defineReport 本身与 ReportDefinition 的类型体系在
+// ../definition/report.ts,这里只做渲染编排与宿主联系面(页选择、索引命令拼装)。
+
+import type { Results, Scope } from "../../results/types.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+import {
+  createTextContext,
+  renderNodeToText,
+  resolveReportTree,
+  validateReportTree,
+  ResolveMemo,
+  type PageContext,
+  type ReportNode,
+  type TextRenderOptions,
+} from "../definition/tree.ts";
+import {
+  buildReportMeta,
+  resolveReportTitle,
+  type ReportDefinition,
+  type ReportMeta,
+  type ReportMetaPage,
+  type ReportPage,
+} from "../definition/report.ts";
+import { resolveLocalizedText, type ReportLocale } from "../model/locale.ts";
+
+/** 默认下钻命令:`niceeval show <locator>` 是 show 已实现的真实 CLI 语法,不需要反查 eval id 再拼近似命令。 */
+const DEFAULT_ATTEMPT_COMMAND = (locator: AttemptLocator): string => `niceeval show ${locator}`;
+
+// ───────────────────────── 页选择与 text 宿主入口 ─────────────────────────
+
+/** `--page` 未命中:宿主据此按用法错误退出并列出可用页 id(只列 navigation !== false 的)。 */
+export class ReportPageNotFoundError extends Error {
+  readonly pageId: string;
+  readonly available: string[];
+  constructor(pageId: string, available: string[]) {
+    super(`page "${pageId}" not found. Available pages: ${available.join(", ")}`);
+    this.pageId = pageId;
+    this.available = available;
+  }
+}
+
+/** 显式请求了 attempt-input page,但当前入口没有 locator 可注入 evidence。 */
+export class ReportPageNeedsLocatorError extends Error {
+  readonly pageId: string;
+  constructor(pageId: string) {
+    super(
+      `Page "${pageId}" is an attempt-input page and needs a locator — it cannot be opened with --page or #/page/<id> directly. ` +
+        "Use the host's locator addressing instead (niceeval show @<locator>, or the view attempt route), which resolves this page with the matching AttemptEvidence.",
+    );
+    this.pageId = pageId;
+  }
+}
+
+/**
+ * 挑选要渲染的 page:省略 pageId 时挑第一张 `navigation !== false` 的页(跳过参数化详情页,
+ * 它没有 locator 就不可打开);显式 pageId 命中 attempt-input page 时报
+ * ReportPageNeedsLocatorError——这个入口没有 locator,不能拿 Scope 强行 resolve。
+ */
+export function pickReportPage(definition: ReportDefinition, pageId?: string): ReportPage {
+  if (pageId === undefined) {
+    return definition.pages.find((p) => p.navigation !== false) ?? definition.pages[0];
+  }
+  const page = definition.pages.find((p) => p.id === pageId);
+  if (!page) {
+    throw new ReportPageNotFoundError(
+      pageId,
+      definition.pages.filter((p) => p.navigation !== false).map((p) => p.id),
+    );
+  }
+  if (page.input === "attempt") throw new ReportPageNeedsLocatorError(page.id);
+  return page;
+}
+
+/** 宿主注入的渲染上下文:官方口径挑好的 Scope 与结果根完整读取面。 */
+export interface ReportHostContext {
+  scope: Scope;
+  /** 组合组件 ctx.results 的来源;历史视图从这里自行挑 Snapshot[]。 */
+  results: Results;
+}
+
+export interface RenderReportTextOptions extends TextRenderOptions {
+  /** 渲染哪一页;缺省第一张可导航页。命中 attempt-input page 抛 ReportPageNeedsLocatorError,未命中抛 ReportPageNotFoundError。 */
+  pageId?: string;
+}
+
+/**
+ * text 宿主的装载语义:选页(只能是 scope-input page,见 pickReportPage)→ resolve(组合展开 +
+ * spec 取数,唯一的 await 边界)→ 树校验 → 遍历渲染 text 面。不需要 react-dom。宿主不在报告树外
+ * 另设警告通道——挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放
+ * 是作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
+ */
+export async function renderReportToText(
+  definition: ReportDefinition,
+  ctx: ReportHostContext,
+  options?: RenderReportTextOptions,
+): Promise<string> {
+  const page = pickReportPage(definition, options?.pageId);
+  const meta = buildReportMeta(definition, ctx.scope);
+  const hasAttemptPage = definition.pages.some((p) => p.input === "attempt");
+  const resolved = await resolveReportTree(page.content, {
+    scope: ctx.scope,
+    results: ctx.results,
+    report: meta,
+    page: { id: page.id, input: "scope" },
+    memo: new ResolveMemo(),
+  });
+  validateReportTree(resolved);
+  return renderNodeToText(
+    resolved,
+    createTextContext({
+      ...options,
+      attemptCommand: options?.attemptCommand ?? (hasAttemptPage ? DEFAULT_ATTEMPT_COMMAND : undefined),
+    }),
+  );
+}
+
+/** 页索引标题行(show 多页索引 / view 导航共用的解析结果):按 locale 解析的标题字符串。 */
+export function reportTitleText(definition: ReportDefinition, scope: Scope, locale: ReportLocale): string {
+  return resolveLocalizedText(resolveReportTitle(definition, scope), locale);
+}
+
+// ───────────────────────── 逐页(树)渲染入口:宿主联系面 ─────────────────────────
+
+/** 宿主索引命令的完整上下文(docs/feature/reports/show/reports.md「索引命令携带完整上下文」)。 */
+export interface HostCommandContext {
+  patterns: string[];
+  results?: string;
+  experiment?: string;
+  report?: string;
+  page?: string;
+}
+
+function quoteArg(value: string): string {
+  return /^[A-Za-z0-9._/@-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+/** 按上下文拼组索引的可复制命令:`niceeval show <patterns> --exp <id> [--results/--report/--page]`。 */
+function experimentCommandFor(ctx: HostCommandContext): (experimentIdPrefix: string) => string {
+  return (prefix) => {
+    const parts = ["niceeval show", ...ctx.patterns.map(quoteArg), `--exp ${quoteArg(prefix)}`];
+    if (ctx.results !== undefined) parts.push(`--results ${quoteArg(ctx.results)}`);
+    if (ctx.report !== undefined) parts.push(`--report ${quoteArg(ctx.report)}`);
+    if (ctx.page !== undefined) parts.push(`--page ${quoteArg(ctx.page)}`);
+    return parts.join(" ");
+  };
+}
+
+/** 逐页渲染的宿主上下文:官方口径的 Scope、结果根读取面、规范化声明(ctx.report)与当前页判别。 */
+export interface ReportTreeHostContext {
+  scope: Scope;
+  results: Results;
+  report: ReportMeta;
+  /** 当前渲染的页:scope 分支只有 id;attempt 分支带 locator + evidence(宿主已完成寻址与装配)。 */
+  page: PageContext;
+}
+
+export interface RenderTreeTextOptions extends TextRenderOptions {
+  /** 组索引命令的完整上下文;给了就按它拼命令,experimentCommand 显式注入时以后者为准。 */
+  commandContext?: HostCommandContext;
+}
+
+/**
+ * 渲染一页报告树的 text 面(宿主逐页调用;页选择归宿主):
+ * resolve(组合展开 + spec 取数)→ validate → render。宿主不在报告树外另设警告通道,
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现(内建报告每页都放它)。当前 definition 没有
+ * attempt-input page 时不注入默认下钻命令,调用方也没显式给,`ctx.attemptCommand` 就不存在。
+ */
+export async function renderReportTreeToText(
+  tree: ReportNode,
+  ctx: ReportTreeHostContext,
+  options?: RenderTreeTextOptions,
+): Promise<string> {
+  const resolved = await resolveReportTree(tree, {
+    scope: ctx.scope,
+    results: ctx.results,
+    report: ctx.report,
+    page: ctx.page,
+    memo: new ResolveMemo(),
+  });
+  validateReportTree(resolved);
+  const hasAttemptPage = ctx.report.pages.some((p) => p.input === "attempt");
+  const textCtx = createTextContext({
+    ...options,
+    attemptCommand: options?.attemptCommand ?? (hasAttemptPage ? DEFAULT_ATTEMPT_COMMAND : undefined),
+    ...(options?.experimentCommand === undefined && options?.commandContext !== undefined
+      ? { experimentCommand: experimentCommandFor(options.commandContext) }
+      : {}),
+  });
+  return renderNodeToText(resolved, textCtx);
+}

package/src/report/runtime/web.ts

@@ -0,0 +1,106 @@
+// web 宿主(view --report)的装载入口:同一棵树走 web 面,renderToStaticMarkup 吐静态
+// HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
+// 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
+
+import type { ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { AttemptLocator } from "../../results/locator.ts";
+import type { Scope } from "../../results/types.ts";
+import {
+  resolveReportTree,
+  runWithWebContext,
+  validateReportTree,
+  ResolveMemo,
+  type PageContext,
+  type WebContext,
+} from "../definition/tree.ts";
+import { DEFAULT_REPORT_LOCALE, type ReportLocale } from "../model/locale.ts";
+import { buildReportMeta, type ReportDefinition } from "../definition/report.ts";
+import { pickReportPage, type ReportHostContext } from "./text.ts";
+
+/**
+ * 默认证据室深链:view 静态站的 attempt 文档路径,根相对(与 index.html 同级 —— scope-input
+ * page 恒在文档树的根)。文件名是 URL 编码后的 locator(architecture.md「Attempt 详情是一张
+ * 参数化 page」);磁盘/清单键用未编码的原始 locator,两者的对应关系与拆分只住在 view 的站点
+ * 管线(site.ts),这里只产出 href 字符串。从 attempt 页面自身内容渲染时(极少见:自定义
+ * attempt-input page 里嵌了别的证据引用组件)view 显式传入同级相对版本覆盖这个默认值,
+ * 不依赖这里的根相对形态。
+ */
+const DEFAULT_ATTEMPT_HREF = (locator: AttemptLocator): string => `attempt/${encodeURIComponent(locator)}.html`;
+
+export interface StaticHtmlOptions {
+  /** 渲染哪一页;缺省第一张可导航页。命中 attempt-input page 抛 ReportPageNeedsLocatorError。 */
+  pageId?: string;
+  /** 证据室深链;当前 definition 没有 attempt-input page 时不注入默认值,除非显式传入。 */
+  attemptHref?: (locator: AttemptLocator) => string;
+  /** 官方组件 chrome 文案的 locale;默认 "en"。 */
+  locale?: ReportLocale;
+}
+
+/**
+ * web 宿主的装载语义:选页(只能是 scope-input page)→ resolve(组合展开 + spec 取数,
+ * 唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外
+ * 另设警告通道——挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告
+ * 放不放是作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
+ */
+export async function renderReportToStaticHtml(
+  definition: ReportDefinition,
+  ctx: ReportHostContext,
+  options?: StaticHtmlOptions,
+): Promise<string> {
+  const page = pickReportPage(definition, options?.pageId);
+  const meta = buildReportMeta(definition, ctx.scope);
+  const hasAttemptPage = definition.pages.some((p) => p.input === "attempt");
+  const resolved = await resolveReportTree(page.content, {
+    scope: ctx.scope,
+    results: ctx.results,
+    report: meta,
+    page: { id: page.id, input: "scope" },
+    memo: new ResolveMemo(),
+  });
+  validateReportTree(resolved);
+  const webCtx: WebContext = {
+    ...(options?.attemptHref !== undefined
+      ? { attemptHref: options.attemptHref }
+      : hasAttemptPage
+        ? { attemptHref: DEFAULT_ATTEMPT_HREF }
+        : {}),
+    locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
+  };
+  return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
+}
+
+/**
+ * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
+ * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
+ * ctx.report 是宿主规范化后的声明,ctx.page 是当前页判别(scope 或 attempt 分支)。
+ */
+export async function renderReportTreeToStaticHtml(
+  tree: import("../definition/tree.ts").ReportNode,
+  ctx: {
+    scope: Scope;
+    results: import("../../results/types.ts").Results;
+    report: import("../definition/report.ts").ReportMeta;
+    page: PageContext;
+  },
+  options?: { attemptHref?: (locator: AttemptLocator) => string; locale?: ReportLocale },
+): Promise<string> {
+  const resolved = await resolveReportTree(tree, {
+    scope: ctx.scope,
+    results: ctx.results,
+    report: ctx.report,
+    page: ctx.page,
+    memo: new ResolveMemo(),
+  });
+  validateReportTree(resolved);
+  const hasAttemptPage = ctx.report.pages.some((p) => p.input === "attempt");
+  const webCtx: WebContext = {
+    ...(options?.attemptHref !== undefined
+      ? { attemptHref: options.attemptHref }
+      : hasAttemptPage
+        ? { attemptHref: DEFAULT_ATTEMPT_HREF }
+        : {}),
+    locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
+  };
+  return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
+}

package/src/results/attempt-evidence.ts

@@ -33,7 +33,7 @@ import { type AttemptIdentity, type AttemptLocator, encodeAttemptLocator } from
 import { loadAnnotatedEvalSource } from "./attempt-source.ts";
 import { deriveSendAnnotations, type AnnotatedEvalSource } from "./annotated-source.ts";
 import { buildExecutionTree, type ExecutionTree } from "../o11y/execution-tree.ts";
-import type { DiffData, EvalResult } from "../types.ts";
+import type { DiffData, EvalResult, StreamEvent } from "../types.ts";
 
 /**
  * 一个 Attempt 的 artifact 落盘位置。单一目录足够:一个 attempt 的全部 artifact
@@ -79,6 +79,9 @@ export interface AttemptEvidence {
    * 的调用方直接读结构化字段(如按 experimentId 分组、按时间排序)。 */
   identity: AttemptIdentity;
   result: EvalResult;
+  /** 标准事件流(`--execution` 切面与 AttemptConversation 分轮的唯一事实来源);没有非空
+   * events() 就是 null。装配一次,`show` / `view` / 报告不再各自调用 `attempt.events()`。 */
+  events: readonly StreamEvent[] | null;
   /** 运行时保存的 Eval 源码标注(`--source` 切面);没有 sources() 就是 null,不伪造空文档。 */
   evalSource: AnnotatedEvalSource | null;
   /** 标准事件流 + OTel enrichment(`--execution` 切面);没有非空 events 就是 null,
@@ -138,6 +141,7 @@ export async function loadAttemptEvidence(attempt: AttemptHandle): Promise<Attem
     locator,
     identity,
     result: attempt.result,
+    events: hasEvents ? events : null,
     evalSource,
     execution,
     diff,

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

@@ -73,6 +73,8 @@ interface SnapshotOpts {
   /** 缺省 = 已收尾(completedAt = startedAt);置 true 则不写 completedAt,模拟中断快照。 */
   unfinished?: boolean;
   knownEvalIds?: string[];
+  /** 声明这份快照实际选中的 eval id 全集;省略 = 第三方 harness 未实现该字段。 */
+  selectedEvalIds?: string[];
 }
 
 /** 写一份新布局快照:snapshot.json + 各 attempt 的 result.json。返回快照目录绝对路径。 */
@@ -94,6 +96,9 @@ async function writeSnapshot(
     startedAt: opts.startedAt,
     ...(opts.unfinished ? {} : { completedAt: opts.startedAt }),
     ...(opts.knownEvalIds ? { knownEvalIds: opts.knownEvalIds } : {}),
+    ...(opts.selectedEvalIds !== undefined
+      ? { experiment: { runs: 1, earlyExit: true, selectedEvalIds: opts.selectedEvalIds } }
+      : {}),
   };
   await writeFile(join(dir, "snapshot.json"), JSON.stringify(meta, null, 2), "utf-8");
   for (const r of results) {
@@ -234,6 +239,51 @@ describe("selectCurrentResults · 现刻水位结构化身份", () => {
     expect(results.latest().warnings.some((w) => w.kind === "partial-coverage")).toBe(true);
   });
 
+  it("合成快照的 selectedEvalIds 重建为最终 picks(q1 新快照 + q2 旧快照补齐),不是照抄某一来源的局部选择", async () => {
+    const root = await makeRoot();
+    await writeSnapshot(
+      root,
+      "2026-07-01T08-00-00-000Z",
+      { experimentId: "compare/carry", startedAt: "2026-07-01T08:00:00.000Z", selectedEvalIds: ["q1", "q2"] },
+      [res("q1", "passed"), res("q2", "failed")],
+    );
+    await writeSnapshot(
+      root,
+      "2026-07-02T08-00-00-000Z",
+      { experimentId: "compare/carry", startedAt: "2026-07-02T08:00:00.000Z", selectedEvalIds: ["q1"] },
+      [res("q1", "passed")],
+    );
+    const results = await openResults(root);
+    const scope = selectCurrentResults(results);
+    expect(scope.snapshots[0]!.experiment!.selectedEvalIds).toEqual(["q1", "q2"]);
+  });
+
+  it("来源快照声明 selectedEvalIds:[q1] 却夹带 q2 的历史 attempt,合成结果不含该 q2", async () => {
+    const root = await makeRoot();
+    await writeSnapshot(
+      root,
+      "2026-07-01T08-00-00-000Z",
+      { experimentId: "compare/leaky", startedAt: "2026-07-01T08:00:00.000Z", selectedEvalIds: ["q1"] },
+      [res("q1", "passed"), res("q2", "passed")], // q2 落盘了,但没被这次实验选中
+    );
+    const results = await openResults(root);
+    const scope = selectCurrentResults(results);
+    expect(scope.snapshots[0]!.evals.map((ev) => ev.id)).toEqual(["q1"]);
+  });
+
+  it("第三方快照缺 experiment.selectedEvalIds 时按其实际 evals 退化,不整份排除;与本方快照混合时各自按自己口径收窄", async () => {
+    const root = await makeRoot();
+    await writeSnapshot(
+      root,
+      "2026-07-01T08-00-00-000Z",
+      { experimentId: "third-party/harness", startedAt: "2026-07-01T08:00:00.000Z" }, // 无 selectedEvalIds
+      [res("q1", "passed"), res("q2", "passed")],
+    );
+    const results = await openResults(root);
+    const scope = selectCurrentResults(results);
+    expect(scope.snapshots[0]!.evals.map((ev) => ev.id).sort()).toEqual(["q1", "q2"]);
+  });
+
   it("场景3 同一 eval 多 attempts:最新快照整批替换旧 attempts,不跨快照混装", async () => {
     const root = await makeRoot();
     await writeSnapshot(root, "2026-07-01T08-00-00-000Z", { experimentId: "retry/bub", startedAt: "2026-07-01T08:00:00.000Z" }, [
@@ -329,7 +379,7 @@ describe("selectCurrentResults · 现刻水位结构化身份", () => {
     expect(algebra.warnings).toEqual([]);
   });
 
-  it("场景8 --experiment 分段前缀过滤:只留匹配段,不误配同前缀实验", async () => {
+  it("场景8 --exp 分段前缀过滤:只留匹配段,不误配同前缀实验", async () => {
     const root = await makeRoot();
     await writeSnapshot(root, "2026-07-01T08-00-00-000Z", { experimentId: "compare/bub", startedAt: "2026-07-01T08:00:00.000Z" }, [res("q1", "passed")]);
     await writeSnapshot(root, "2026-07-01T09-00-00-000Z", { experimentId: "compare/codex", agent: "codex", startedAt: "2026-07-01T09:00:00.000Z" }, [res("q1", "passed")]);
@@ -424,7 +474,7 @@ describe("宿主接线 · show text 面与 view web 面反映同一批事实", (
     }
     expect(text).toMatch(/\bbub\s+default\s+bub\s+1s\s+50%/);
     expect(html).toContain('data-sort-value="compare/bub"');
-    expect(text).toContain("1 passed / 1 failed");
+    expect(text).toContain("1 passed · 1 failed");
     expect(html).toContain("50%");
     // 现刻水位覆盖齐全 → 两面都不出 partial-coverage(text: "verdicts cover"; html: data-kind)。
     expect(hasPartialCoverageText(text)).toBe(false);
@@ -476,6 +526,7 @@ describe("宿主接线 · show text 面与 view web 面反映同一批事实", (
         '  kind: "report",',
         '  [Symbol.for("niceeval.report.definition")]: true,',
         "  links: [],",
+        "  head: [],",
         "  scripts: [],",
         "  styles: [],",
         "  pages: [{",
@@ -522,7 +573,7 @@ function hasPartialCoverageHtml(html: string): boolean {
     ]);
     const text = await showText(root, []);
     const html = await viewHtml(root);
-    expect(text).toContain("3 passed / 1 failed");
+    expect(text).toContain("3 passed · 1 failed");
     expect(html).toContain("75%");
     for (const face of [text, html]) expect(face).toContain("compare/bub");
     // 无残缺:两面都不出 partial-coverage,布尔一致(某面偷偷补/漏警告即失配)。