niceeval 0.6.1 → 0.7.0

package/dist/report/types.js

@@ -1,4 +1,5 @@
-// niceeval/report 的公开类型:指标(Metric)、维度(Dimension / flag())与计算函数
-// 产物(即组件的 data props)。数据契约照 docs/feature/reports/library.md「数据计算与缓存边界」;
-// 这些不是持久化格式,没有 format / schemaVersion 信封,兼容性跟随 npm 版本。
+// niceeval/report 的公开类型:指标(Metric)、维度(Dimension / flag() / runConfig())与
+// 计算函数产物(即组件的 data)。数据契约照 docs/feature/reports/library/ 各分篇;
+// 这些不是持久化格式,没有 format / schemaVersion 信封,兼容性跟随 npm 版本
+// (组件消费 data 时校验结构,不符按完整用户反馈报错并提示版本漂移)。
 export {};

package/dist/report/web.d.ts

@@ -1,15 +1,31 @@
 import type { AttemptLocator } from "../results/locator.ts";
+import type { Scope } from "../results/types.ts";
 import { type ReportLocale } from "./locale.ts";
-import type { ReportContext, ReportDefinition } from "./report.ts";
+import { type ReportDefinition, type ReportHostContext } from "./report.ts";
 export interface StaticHtmlOptions {
+    /** 渲染哪一页;缺省第一页。未命中抛 ReportPageNotFoundError。 */
+    pageId?: string;
     /** 证据室深链;缺省用 view 的 attempt 路由 `#/attempt/@<locator>`(单段、不透明)。 */
     attemptHref?: (locator: AttemptLocator) => string;
     /** 官方组件 chrome 文案的 locale;默认 "en"。 */
     locale?: ReportLocale;
 }
 /**
- * build → 渲染前解析数据组件(唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染
- * web 面;Selection 有挑选警告时在报告顶部前置一块警告 HTML；报告树里的 RunOverview
- * 已经渲染同一条时不重复。
+ * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
+ * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
  */
-export declare function renderReportToStaticHtml(definition: ReportDefinition, ctx: ReportContext, options?: StaticHtmlOptions): Promise<string>;
+export declare function renderReportToStaticHtml(definition: ReportDefinition, ctx: ReportHostContext, options?: StaticHtmlOptions): Promise<string>;
+/**
+ * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
+ * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
+ * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ */
+export declare function renderReportTreeToStaticHtml(tree: import("./tree.ts").ReportNode, ctx: {
+    scope: Scope;
+    results: import("../results/types.ts").Results;
+    report: import("./report.ts").ReportMeta;
+}, options?: {
+    attemptHref?: (locator: AttemptLocator) => string;
+    locale?: ReportLocale;
+}): Promise<string>;

package/dist/report/web.js

@@ -3,35 +3,61 @@
 // 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
 import * as React from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-import { resolveReportTree, runWithWebContext, validateReportTree } from "./tree.js";
+import { resolveReportTree, runWithWebContext, validateReportTree, ResolveMemo, } from "./tree.js";
 import { DEFAULT_REPORT_LOCALE } from "./locale.js";
+import { buildReportMeta, pickReportPage } from "./report.js";
 /**
- * 挑选警告的 HTML 形态:宿主级前置块,与 RunOverview 里的警告用同一套结构和类名
- * (`.nre nre-report-warnings` 外壳内一个 `ul.nre-warnings` + `li.nre-warning[data-kind]`,
- * 复用 styles.css 已有的 `.nre .nre-warnings` 样式)。经 renderToStaticMarkup 走 React,
- * message 文本自动转义,不裸拼 HTML。裸跑 / --report 都在报告顶上如实报残缺,不静默。
+ * 挑选警告的 HTML 形态:宿主级前置块(`.nre nre-report-warnings` 外壳内一个
+ * `ul.nre-warnings` + `li.nre-warning[data-kind]`,复用 styles.css 已有样式)。
+ * 带 `command` 的警告把命令渲染为可复制块(`.nre-warning-command`);无 command 的
+ * 只显示 message,不硬造动作。经 renderToStaticMarkup 走 React,文本自动转义。
  */
-function renderSelectionWarningsHtml(warnings) {
-    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)))));
+function renderScopeWarningsHtml(scope) {
+    return renderToStaticMarkup(React.createElement("div", { className: "nre nre-report-warnings" }, React.createElement("ul", { className: "nre-warnings" }, scope.warnings.map((w, i) => React.createElement("li", { key: i, className: "nre-warning", "data-kind": w.kind }, w.message, "command" in w && w.command
+        ? React.createElement("code", { className: "nre-warning-command", "data-nre-copy": w.command }, w.command)
+        : null)))));
 }
 /**
- * build → 渲染前解析数据组件(唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染
- * web 面;Selection 有挑选警告时在报告顶部前置一块警告 HTML；报告树里的 RunOverview
- * 已经渲染同一条时不重复。
+ * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
+ * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
  */
 export async function renderReportToStaticHtml(definition, ctx, options) {
-    const node = await definition.build(ctx);
-    const resolved = await resolveReportTree(node);
+    const page = pickReportPage(definition, options?.pageId);
+    const meta = buildReportMeta(definition, ctx.scope, page.id);
+    const resolved = await resolveReportTree(page.content, {
+        scope: ctx.scope,
+        results: ctx.results,
+        report: meta,
+        memo: new ResolveMemo(),
+    });
     validateReportTree(resolved);
     const webCtx = {
         attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
         locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
     };
     const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
-    const missingWarnings = ctx.selection.warnings.filter((warning) => {
-        const escapedMessage = renderToStaticMarkup(React.createElement(React.Fragment, null, warning.message));
-        return !body.includes(escapedMessage);
+    const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
+    return warnings + body;
+}
+/**
+ * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
+ * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
+ * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ */
+export async function renderReportTreeToStaticHtml(tree, ctx, options) {
+    const resolved = await resolveReportTree(tree, {
+        scope: ctx.scope,
+        results: ctx.results,
+        report: ctx.report,
+        memo: new ResolveMemo(),
     });
-    const warnings = missingWarnings.length > 0 ? renderSelectionWarningsHtml(missingWarnings) : "";
+    validateReportTree(resolved);
+    const webCtx = {
+        attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
+        locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
+    };
+    const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
+    const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
     return warnings + body;
 }

package/dist/results/select.d.ts

@@ -1,37 +1,59 @@
-import type { AttemptHandle, DedupeWarning, Experiment, Results, Selection, SelectionWarning, Snapshot } from "./types.ts";
+import type { AttemptHandle, DedupeWarning, Experiment, Results, Scope, ScopeWarning, Snapshot } from "./types.ts";
+import type { ExperimentRunInfo, JsonValue } from "../types.ts";
 /** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
 export declare function selectLatest(experiments: Experiment[], opts?: {
     experiments?: string | string[];
-}): Selection;
+}): Scope;
 /** selectCurrentResults 的范围输入:experiment id 前缀与 eval id 前缀,都可缺省。 */
 export interface ResultScope {
     /** experiment id 前缀(--experiment),分段匹配语义同 filterExperiments。 */
-    experiment?: string;
-    /** eval id 前缀(位置参数),收窄 Selection 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
+    experiment?: string | string[];
+    /** eval id 前缀(位置参数),收窄 Scope 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
     patterns?: string[];
 }
 /**
- * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取时间上最新的那份
- * 判定,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出
- * 残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的全部历史快照上逐 eval
- * 向更早的 run 补齐,再把合成好的 Selection 交给宿主注入报告槽——内置默认报告与 --report 吃
- * 同一份。
+ * current() 跨快照拼接的可比性前提所比较的字段集(docs/feature/results/library.md
+ * 「官方现刻水位」):会改变单题被测行为或判定的字段。runs / earlyExit / maxConcurrency /
+ * selectedEvalIds / evalFilterFingerprint / description 是编排与选题字段,不参与比较。
+ */
+export interface ComparabilityConfig {
+    agent: string;
+    model?: string;
+    reasoningEffort?: string;
+    flags?: Record<string, JsonValue>;
+    budget?: number;
+    timeoutMs?: number;
+    sandbox?: ExperimentRunInfo["sandbox"];
+}
+/** 一个快照的可比性配置投影;pairsByFlag 与 experimentListData 复用同一字段集。 */
+export declare function comparabilityConfigOf(snapshot: Snapshot): ComparabilityConfig;
+/** 可序列化值的深相等(对象键序无关;undefined 字段与缺席字段等价)。 */
+export declare function deepEqualJson(a: unknown, b: unknown): boolean;
+/**
+ * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取「包含该 eval 的
+ * 最新快照」里的全部 attempt,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval
+ * 前缀的局部重跑会产出残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的
+ * 历史快照上逐 eval 向更早的 run 补齐,再把合成好的 Scope 交给宿主注入报告槽。
+ *
+ * **可比性前提**:每个 experiment 以最新快照的可比性配置(agent / model / reasoningEffort /
+ * flags / budget / timeoutMs / sandbox)为基准,只有配置与基准深相等的历史快照才参与补齐;
+ * 改过配置后只补跑部分 eval 时,旧配置快照覆盖的其余题不冒充新配置的水位,按 partial-coverage
+ * 如实告警。这保证 current() 产出的每个 experiment 只对应一套配置。
  *
  * 同一 eval 的全部 attempts 必须整批取自包含它的最新快照,不把历史快照的 attempts 平铺后
  * 按 eval 聚合——否则会把不同运行的重试混成一次虚构运行。合成快照的 dir/元数据只服务报告
  * 分组与来源展示,证据身份一律来自 attempt 自己的 ref。
- * 警告随 Selection 重算:partial-coverage 的分母 = 已知并集 ∩ 范围(范围收窄时分母同步收窄,
- * 不让范围外的缺口刷屏);stale / unfinished 与 results.latest() 同口径。
  */
-export declare function selectCurrentResults(results: Results, scope?: ResultScope): Selection;
+export declare function selectCurrentResults(results: Results, scope?: ResultScope): Scope;
 /**
- * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
- * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ * Scope 构造:attempts 按口径物化(快照 attempts 的平铺);filter 只删不换 —— 快照删减,
+ * attempts 随之同步修剪,warnings 修剪规则是「experimentId 不在幸存快照中的丢弃,
+ * 非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
  */
-export declare function makeSelection(snapshots: Snapshot[], warnings: SelectionWarning[]): Selection;
+export declare function makeScope(mode: Scope["mode"], snapshots: Snapshot[], warnings: ScopeWarning[]): Scope;
 /**
  * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
- * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 携带合入会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
  * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
  * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
  */

package/dist/results/select.js

@@ -1,15 +1,15 @@
-// 快照 Selection 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「身份键与去重」)。
+// 快照 Scope 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「官方现刻水位」「身份键与去重」)。
 //
-// 选择器只有一个(latest),长在集合上;它不是 DSL,只是最常用的那次筛选。
-// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Selection 走 ——
-// 渲染与否在消费方(message 是渲染好的英文句子),但缺口不静默。
+// 选择器长在集合上(results.latest() / results.current()),不是 DSL,只是最常用的两种口径。
+// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Scope 走 ——
+// 渲染与否在消费方(message 是渲染好的英文句子,以下一步收尾),但缺口不静默。
 import { evalPrefixPredicate } from "../shared/aggregate.js";
 /** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
 export function selectLatest(experiments, opts) {
     const selected = filterExperiments(experiments, opts?.experiments);
     const snapshots = selected.map((exp) => exp.latest);
     const warnings = [];
-    // stale 的基准:Selection 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
+    // stale 的基准:Scope 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
     let latestStartedAt = "";
     for (const snapshot of snapshots) {
         if (snapshot.startedAt > latestStartedAt)
@@ -28,6 +28,7 @@ export function selectLatest(experiments, opts) {
                 covered,
                 total,
                 message: `snapshot covers ${covered} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+                command: `niceeval exp ${exp.id}`,
             });
         }
         if (snapshot.startedAt < latestStartedAt) {
@@ -36,7 +37,8 @@ export function selectLatest(experiments, opts) {
                 experimentId: exp.id,
                 startedAt: snapshot.startedAt,
                 latestStartedAt,
-                message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this selection by ${humanizeGap(snapshot.startedAt, latestStartedAt)}`,
+                message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this scope by ${humanizeGap(snapshot.startedAt, latestStartedAt)}; re-run \`niceeval exp ${exp.id}\` to align, or ignore if evals, agent and model are unchanged between the runs`,
+                command: `niceeval exp ${exp.id}`,
             });
         }
         if (!snapshot.completedAt) {
@@ -45,24 +47,58 @@ export function selectLatest(experiments, opts) {
                 experimentId: exp.id,
                 startedAt: snapshot.startedAt,
                 dir: snapshot.dir,
-                message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; results may be incomplete`,
+                message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; re-run \`niceeval exp ${exp.id}\` for a complete snapshot`,
+                command: `niceeval exp ${exp.id}`,
             });
         }
     }
-    return makeSelection(snapshots, warnings);
+    return makeScope("latest-snapshots", snapshots, warnings);
+}
+/** 一个快照的可比性配置投影;pairsByFlag 与 experimentListData 复用同一字段集。 */
+export function comparabilityConfigOf(snapshot) {
+    const info = snapshot.experiment;
+    return {
+        agent: snapshot.agent,
+        ...(snapshot.model !== undefined ? { model: snapshot.model } : {}),
+        ...(info?.reasoningEffort !== undefined ? { reasoningEffort: info.reasoningEffort } : {}),
+        ...(info?.flags !== undefined ? { flags: info.flags } : {}),
+        ...(info?.budget !== undefined ? { budget: info.budget } : {}),
+        ...(info?.timeoutMs !== undefined ? { timeoutMs: info.timeoutMs } : {}),
+        ...(info?.sandbox !== undefined ? { sandbox: info.sandbox } : {}),
+    };
+}
+/** 可序列化值的深相等(对象键序无关;undefined 字段与缺席字段等价)。 */
+export function deepEqualJson(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqualJson(item, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
+        const keysA = Object.keys(a).filter((k) => a[k] !== undefined);
+        const keysB = Object.keys(b).filter((k) => b[k] !== undefined);
+        if (keysA.length !== keysB.length)
+            return false;
+        return keysA.every((k) => deepEqualJson(a[k], b[k]));
+    }
+    return false;
 }
 /**
- * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取时间上最新的那份
- * 判定,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出
- * 残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的全部历史快照上逐 eval
- * 向更早的 run 补齐,再把合成好的 Selection 交给宿主注入报告槽——内置默认报告与 --report 吃
- * 同一份。
+ * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取「包含该 eval 的
+ * 最新快照」里的全部 attempt,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval
+ * 前缀的局部重跑会产出残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的
+ * 历史快照上逐 eval 向更早的 run 补齐,再把合成好的 Scope 交给宿主注入报告槽。
+ *
+ * **可比性前提**:每个 experiment 以最新快照的可比性配置(agent / model / reasoningEffort /
+ * flags / budget / timeoutMs / sandbox)为基准,只有配置与基准深相等的历史快照才参与补齐;
+ * 改过配置后只补跑部分 eval 时,旧配置快照覆盖的其余题不冒充新配置的水位,按 partial-coverage
+ * 如实告警。这保证 current() 产出的每个 experiment 只对应一套配置。
  *
  * 同一 eval 的全部 attempts 必须整批取自包含它的最新快照,不把历史快照的 attempts 平铺后
  * 按 eval 聚合——否则会把不同运行的重试混成一次虚构运行。合成快照的 dir/元数据只服务报告
  * 分组与来源展示,证据身份一律来自 attempt 自己的 ref。
- * 警告随 Selection 重算:partial-coverage 的分母 = 已知并集 ∩ 范围(范围收窄时分母同步收窄,
- * 不让范围外的缺口刷屏);stale / unfinished 与 results.latest() 同口径。
  */
 export function selectCurrentResults(results, scope = {}) {
     const match = scope.patterns && scope.patterns.length > 0 ? evalPrefixPredicate(scope.patterns) : () => true;
@@ -70,9 +106,13 @@ export function selectCurrentResults(results, scope = {}) {
     const snapshots = [];
     const warnings = [];
     for (const exp of experiments) {
+        // 可比性基准 = 该实验最新快照的可比性配置;不一致的旧快照整份跳过,不贡献 attempt。
+        const baseline = comparabilityConfigOf(exp.latest);
         // 逐题取最新:快照按最新在前,首个出现即最新判定
         const taken = new Map();
         for (const snapshot of exp.snapshots) {
+            if (!deepEqualJson(comparabilityConfigOf(snapshot), baseline))
+                continue;
             for (const ev of snapshot.evals) {
                 if (!match(ev.id) || taken.has(ev.id))
                     continue;
@@ -97,6 +137,8 @@ export function selectCurrentResults(results, scope = {}) {
             startedAt,
             agent: base.agent,
             ...(base.model !== undefined ? { model: base.model } : {}),
+            ...(base.experiment !== undefined ? { experiment: base.experiment } : {}),
+            ...(base.name !== undefined ? { name: base.name } : {}),
             producer: base.producer,
             schemaVersion: base.schemaVersion,
             evals,
@@ -105,8 +147,8 @@ export function selectCurrentResults(results, scope = {}) {
             ...(newest.completedAt !== undefined ? { completedAt: newest.completedAt } : {}),
             ...(base.knownEvalIds ? { knownEvalIds: [...base.knownEvalIds] } : {}),
         });
-        // 残缺检测:跨快照补齐后仍缺,只可能是历史上见过(或 knownEvalIds 声明过)
-        // 却从未在可读落盘里出现的题 —— 分母收窄到范围内,不让范围外的缺口刷屏。
+        // 残缺检测:跨快照补齐后仍缺,来自「历史上见过却从未在可比配置的可读落盘里出现」的题
+        // (含改配置后未补跑的题)—— 分母收窄到范围内,不让范围外的缺口刷屏。
         const total = exp.evalIds.filter(match).length;
         if (evals.length < total) {
             warnings.push({
@@ -115,6 +157,7 @@ export function selectCurrentResults(results, scope = {}) {
                 covered: evals.length,
                 total,
                 message: `verdicts cover ${evals.length} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+                command: `niceeval exp ${exp.id}`,
             });
         }
     }
@@ -130,7 +173,8 @@ export function selectCurrentResults(results, scope = {}) {
                 experimentId: snapshot.experimentId,
                 startedAt: snapshot.startedAt,
                 latestStartedAt,
-                message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, before the latest run in this selection (${latestStartedAt})`,
+                message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, ${humanizeGap(snapshot.startedAt, latestStartedAt)} before the latest run in this scope; re-run \`niceeval exp ${snapshot.experimentId}\` to align, or ignore if evals, agent and model are unchanged between the runs`,
+                command: `niceeval exp ${snapshot.experimentId}`,
             });
         }
         if (snapshot.completedAt === undefined) {
@@ -139,19 +183,23 @@ export function selectCurrentResults(results, scope = {}) {
                 experimentId: snapshot.experimentId,
                 startedAt: snapshot.startedAt,
                 dir: snapshot.dir,
-                message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete`,
+                message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete — re-run \`niceeval exp ${snapshot.experimentId}\` for a complete snapshot`,
+                command: `niceeval exp ${snapshot.experimentId}`,
             });
         }
     }
-    return makeSelection(snapshots, warnings);
+    return makeScope("current-evals", snapshots, warnings);
 }
 /**
- * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
- * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ * Scope 构造:attempts 按口径物化(快照 attempts 的平铺);filter 只删不换 —— 快照删减,
+ * attempts 随之同步修剪,warnings 修剪规则是「experimentId 不在幸存快照中的丢弃,
+ * 非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
  */
-export function makeSelection(snapshots, warnings) {
+export function makeScope(mode, snapshots, warnings) {
     return {
+        mode,
         snapshots,
+        attempts: snapshots.flatMap((s) => s.attempts),
         warnings,
         filter(predicate) {
             const kept = snapshots.filter(predicate);
@@ -160,13 +208,13 @@ export function makeSelection(snapshots, warnings) {
                 const scope = w.experimentId;
                 return typeof scope !== "string" || survivors.has(scope);
             });
-            return makeSelection(kept, keptWarnings);
+            return makeScope(mode, kept, keptWarnings);
         },
     };
 }
 /**
  * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
- * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 携带合入会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
  * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
  * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
  */

package/dist/results/types.d.ts

@@ -33,6 +33,13 @@ export interface SnapshotMeta {
     completedAt?: string;
     /** 写入时刻该实验已知的 eval 并集 —— 残缺检测的分母随数据走(copySnapshots 自动补记,writer 可声明)。 */
     knownEvalIds?: string[];
+    /**
+     * 发布拷贝的自描述标记:copySnapshots 补记,消毒函数 → "applied"、redact: false → "none";
+     * 本地事实根没有此字段。只声明流程,不证明无秘密;view --out 据此分级防呆。
+     */
+    publish?: {
+        redaction: "applied" | "none";
+    };
     /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
     name?: LocalizedText;
 }
@@ -110,6 +117,10 @@ export interface Snapshot {
     dir: string;
     /** 写入时刻该实验已知的 eval 并集(可选);copySnapshots 自动补记,writer.snapshot() 也可声明。 */
     knownEvalIds?: string[];
+    /** 发布拷贝的自描述标记(见 SnapshotMeta.publish);本地事实根没有此字段。 */
+    publish?: {
+        redaction: "applied" | "none";
+    };
 }
 /** 一个实验的全部历史:同一 experiment id 的历次快照归在一起。 */
 export interface Experiment {
@@ -146,46 +157,68 @@ export interface Results {
     experiments: Experiment[];
     skipped: SkippedDir[];
     /**
-     * 每个实验取最新一次快照,返回 Selection(快照与挑选警告绑在一起走)。
+     * 每个实验取最新一次快照,返回 Scope(快照与挑选警告绑在一起走)。
      * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
      */
     latest(opts?: {
         experiments?: string | string[];
-    }): Selection;
+    }): Scope;
+    /**
+     * 官方现刻水位:每个 experiment × eval 取「包含该 eval 的最新快照」里的全部 attempt,
+     * 跨历史拼出当前判定水位。可比性前提:每个 experiment 以最新快照的可比性配置
+     * (agent / model / reasoningEffort / flags / budget / timeoutMs / sandbox)为基准,
+     * 配置不一致的旧快照不贡献 attempt,缺口走 partial-coverage
+     * (见 docs/feature/results/library.md「官方现刻水位」)。
+     */
+    current(opts?: {
+        experiments?: string | string[];
+    }): Scope;
 }
 /**
- * Selection:选出的快照 + 挑选过程算出的警告。渲染与否在消费方,但缺口永远被算出来。
- * 下游(Reports 计算函数、copySnapshots)收 `Selection | Snapshot[]`;
- * 手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
+ * Scope(范围):选出的快照 + 口径 + 已按口径物化的 attempt 全集 + 挑选警告。
+ * 渲染与否在消费方,但缺口永远被算出来。下游(Reports 计算函数、copySnapshots)收
+ * `Scope | readonly Snapshot[]`;手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
  */
-export interface Selection {
+export interface Scope {
+    /** 这份 Scope 的口径,字面写在数据上。 */
+    mode: "latest-snapshots" | "current-evals";
     snapshots: Snapshot[];
-    warnings: SelectionWarning[];
     /**
-     * 只删不换:返回新 Selection,快照删减,warnings 按规则修剪 ——
-     * experimentId 不在幸存快照中的丢弃,非实验作用域的保留。
+     * 按口径物化的 attempt 全集:消费 attempts 就自动正确,不需要自己 flatten snapshots,
+     * 也就不可能算错口径。官方计算函数同样只消费它。
+     */
+    attempts: AttemptHandle[];
+    warnings: ScopeWarning[];
+    /**
+     * 只删不换:返回新 Scope,快照删减,attempts 与 warnings 随之同步修剪 ——
+     * experimentId 不在幸存快照中的警告丢弃,非实验作用域的警告保留。
      * 「换成上一个完整快照」这类替换式重挑不给方法,回 exp.snapshots 自己挑。
      */
-    filter(predicate: (snapshot: Snapshot) => boolean): Selection;
+    filter(predicate: (snapshot: Snapshot) => boolean): Scope;
 }
 /**
- * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;
- * kind 是契约的一部分,全集与触发条件见 docs/feature/results/library.md「警告 kind 全集」。
+ * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;能用一条命令直接推进的
+ * kind 同时带 `command`(已替换真实 id,复制即跑)。kind 是契约的一部分,全集与触发条件见
+ * docs/feature/results/library.md「警告 kind 全集」。
  */
-export type SelectionWarning = {
+export type ScopeWarning = {
     /** 选中快照的覆盖 < 该实验已知 eval 并集(本地历史 ∪ knownEvalIds)。 */
     kind: "partial-coverage";
     experimentId: string;
     covered: number;
     total: number;
     message: string;
+    /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+    command: string;
 } | {
-    /** 该实验选中的快照早于 Selection 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
+    /** 该实验选中的快照早于 Scope 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
     kind: "stale-snapshot";
     experimentId: string;
     startedAt: string;
     latestStartedAt: string;
     message: string;
+    /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+    command: string;
 } | {
     /** 选中快照缺 completedAt(进程中断,未收尾);已落盘 attempt 照常读出,警告提示集合可能不完整。 */
     kind: "unfinished-snapshot";
@@ -194,6 +227,8 @@ export type SelectionWarning = {
     /** 该快照目录的绝对路径。 */
     dir: string;
     message: string;
+    /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+    command: string;
 };
 /** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */
 export interface DedupeWarning {

package/dist/runner/feedback/sink.d.ts

@@ -0,0 +1,110 @@
+import type { AttemptLifecycleEvent, AttemptRef, FailureDetail } from "../types.ts";
+import type { Verdict } from "../../scoring/types.ts";
+import type { JsonValue } from "../../shared/types.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+/** `sink.diagnostic()` 的输入 —— 与 `DurableFeedbackEvent` 的 "diagnostic" 变体字段一致,
+ *  只是省略 `type`/`at`(由 coordinator 补上)。 */
+export interface DiagnosticInput {
+    /** 稳定去重 key —— 同一种 warning/error 用同一个 key(见 cli.md「同一 dedupeKey 并发出现时
+     *  只留一条并显示次数」),不要把可变的实例细节(如具体 sandbox id)编进 key 本身,
+     *  那些细节放 `data`。 */
+    key: string;
+    severity: "warning" | "error";
+    /** 一句话人类可读摘要;renderer 的 appendDurable 直接展示,不需要再解析。 */
+    message: string;
+    identity?: AttemptRef;
+    data?: Readonly<Record<string, JsonValue>>;
+}
+/** `sink.failure()` 的输入 —— 与 `DurableFeedbackEvent` 的 "failure" 变体字段一致,只省略
+ *  `type`/`at`(由 coordinator 补上)。`locator` 只有在 attempt 挂靠 experiment 时才存在
+ *  (见 `results/locator.ts` 的 `encodeAttemptLocator`);调用方(run.ts)只在拿到 locator 之后
+ *  才应该调用这个函数——没有 locator 的裸 run 不产出这类永久失败通知。 */
+export type FailureInput = FailureDetail;
+/** `sink.budgetExhausted()` 的输入 —— 与 `DurableFeedbackEvent` 的 "budget-exhausted" 变体字段
+ *  一致,只省略 `type`/`at`。调用方(run.ts)对每一个因预算到顶而不派发的 attempt 各调一次
+ *  (与 `AttemptLifecycleEvent` 的 "attempt:early-exit" 同构);`unstarted` 是调用方自己维护的、
+ *  发出这条时的累计未派发数,不是 reducer 能推导的值(见 reducer.ts 对应事件的注释)。 */
+export interface BudgetExhaustedInput {
+    experimentId: string;
+    spent: number;
+    unstarted: number;
+}
+/** `sink.kept()` 的输入 —— 与 `DurableFeedbackEvent` 的 "kept" 变体字段一致,省略 type/at。 */
+export interface KeptInput {
+    locator: AttemptLocator;
+    identity: AttemptRef;
+    who: string;
+    verdict: Verdict;
+    provider: string;
+    sandboxId: string;
+    enter?: string;
+}
+/** `sink.ts` façade 函数实际转发到的最小接口 —— `FeedbackCoordinator`(coordinator.ts)实现它。
+ *  定义在这里(而不是从 coordinator.ts 导入)是为了让 sink.ts 不必在运行时依赖 coordinator.ts,
+ *  避免两个模块互相 import 造成的循环依赖 —— coordinator.ts 反过来 `import type` 这个接口。 */
+export interface FeedbackSink {
+    activity(text: string): void;
+    diagnostic(input: DiagnosticInput): void;
+    interrupted(): void;
+    reporterError(input: {
+        reporter: string;
+        required: boolean;
+        message: string;
+    }): void;
+    /** 一次失败/errored attempt 的永久通知(见 `FailureInput`)。 */
+    failure(input: FailureInput): void;
+    /** 一个因预算到顶而未被派发的 attempt(见 `BudgetExhaustedInput`)。 */
+    budgetExhausted(input: BudgetExhaustedInput): void;
+    /** 一次留存授予(--keep-sandbox);见 `KeptInput` 与 docs/feature/sandbox/cli.md。 */
+    kept(input: KeptInput): void;
+    /** attempt 生命周期事件(queued/start/phase/progress/complete/early-exit),见
+     *  `AttemptLifecycleEvent`。只驱动 human dashboard 的 active slot,不落 RunSummary/结果文件,
+     *  所以没有活跃 coordinator 时(见 `reportAttemptLifecycle`)静默丢弃是安全的 —— 这类信息
+     *  本身就只服务「正在画着的 dashboard」,不是必须留痕的诊断。 */
+    lifecycle(event: AttemptLifecycleEvent): void;
+}
+/**
+ * coordinator 进入「活跃」阶段时调用一次(见 coordinator.ts 的 start()),把自己注册为当前
+ * reportXxx() 调用的目的地。返回的函数用于退出活跃状态(见 coordinator.ts 的 finish())——
+ * 调用一次即失效,重复调用是安全的 no-op。
+ */
+export declare function activateFeedbackSink(sink: FeedbackSink): () => void;
+/** 仅供测试:断言没有遗留未退出的活跃 coordinator(避免一个测试忘记 finish() 污染下一个)。 */
+export declare function activeFeedbackSinkCount(): number;
+/** 不需要去重、不进入 RunFeedbackState 的瞬时活动文本(docker 镜像拉取进度、vercel session
+ *  rotate 成功通知……)。没有活跃 coordinator 时退回一行 stderr,与迁移前的裸写视觉效果一致。 */
+export declare function reportActivity(text: string): void;
+/** 需要去重、要出现在三种 profile 永久事件流里的一条 warning/error。 */
+export declare function reportDiagnostic(input: DiagnosticInput): void;
+/** 一次失败/errored attempt 的永久通知(见 `FailureInput`)。与 `reportDiagnostic` 同级别的
+ *  「必须留痕」信号 —— 没有活跃 coordinator 时退回一行 stderr,不像 `reportAttemptLifecycle`
+ *  那样静默丢弃(定位一次真实失败不该因为没接 coordinator 就彻底没有出口)。 */
+export declare function reportFailure(input: FailureInput): void;
+/** 一个因预算到顶而未被派发的 attempt(见 `BudgetExhaustedInput`)。没有活跃 coordinator 时的
+ *  兜底文案与 coordinator.ts 的 `fallbackTextFor` 对 "budget-exhausted" 事件的格式化保持一致。 */
+/** 一次留存授予的永久通知(--keep-sandbox);没有活跃 coordinator 时退回一行 stderr。 */
+export declare function reportKept(input: KeptInput): void;
+export declare function reportBudgetExhausted(input: BudgetExhaustedInput): void;
+/** 用户中断(Ctrl+C)。没有活跃 coordinator 时的兜底文案与迁移前的 `runner.interrupted` 完全
+ *  相同 —— 调用方(run.ts)不再需要自己持有这段 i18n 文案。 */
+export declare function reportInterrupted(): void;
+/**
+ * runner 自己驱动的 attempt 生命周期投影(见 docs/feature/experiments/cli.md「Attempt 阶段」)——
+ * `src/runner/attempt.ts`(phase/progress)与 `src/runner/run.ts`(start/complete/early-exit)是
+ * 目前仅有的两个调用方。没有活跃 coordinator 时(今天:CLI 还没接入 --output)静默 no-op ——
+ * 与其它 reportXxx() 不同,这里不退回 `writeStderrLine` 兜底:这类事件只服务尚不存在的
+ * dashboard,不是需要留痕的诊断,现有可观察行为(直到 CLI 接入真正的 coordinator 之前)因此
+ * 完全不变。
+ */
+export declare function reportAttemptLifecycle(event: AttemptLifecycleEvent): void;
+/** 一个 reporter 的某次回调抛错(见 `runner/report.ts` 的 `runReporter`)。`reporter`/`required`
+ *  来自调用方注册这个 reporter 时的 `ReporterRegistration`(见其字段注释)——默认 artifacts、
+ *  显式 `--json`/`--junit` 传 `required: true`,用户 `config.reporters`/`EvalDef.reporters`
+ *  传 `required: false`。coordinator 把它折进 `RunFeedbackState.diagnostics`(reducer 按
+ *  `reporter-error:<reporter>` 去重),调用方(`cli.ts` 的 `assembleRunCompletion`)据此把
+ *  `required` 为真的失败折进 `RunCompletion.reporterErrors`,让 completion/CI 退出码判红。 */
+export declare function reportReporterError(input: {
+    reporter: string;
+    required: boolean;
+    message: string;
+}): void;