niceeval 0.6.1 → 0.6.2

package/dist/report/types.d.ts

@@ -1,6 +1,6 @@
 import type { AttemptHandle, SelectionWarning } from "../results/types.ts";
 import type { AttemptLocator } from "../results/locator.ts";
-import type { AssertionResult, Verdict } from "../types.ts";
+import type { AssertionResult, AttemptError, DiagnosticRecord, Verdict } from "../types.ts";
 import type { LocalizedLabel, ReportLocale } from "./locale.ts";
 export type { SelectionWarning };
 export type { AttemptLocator };
@@ -21,7 +21,7 @@ export interface MetricAggregate {
  * 指标:纯函数,吃一个 AttemptHandle 吐一个值(null = 此 attempt 测不了这个指标,
  * 不进聚合;0 = 测了结果是零,照常进),外加名字、两级聚合方式和渲染提示。
  * 内置指标与自定义指标是同一个类型,没有特权。name 走字面量泛型:列键锚在指标
- * 对象上(`row.cells[passRate.name]`),拼错列名编译不过。
+ * 对象上(`row.cells[taskPassRate.name]`),拼错列名编译不过。
  */
 export interface Metric<Name extends string = string> {
     /** MetricColumn.key 与列头的来源;同一次计算里重名是错误。 */
@@ -67,8 +67,22 @@ export interface FlagRef {
     readonly label?: string | ((value: string | number | boolean) => string);
     readonly unit?: string;
 }
-/** 维度槽的输入:内置/自定义维度,或 experiment 声明的 flag。 */
-export type DimensionInput = Dimension | FlagRef;
+/**
+ * config() 的产物:把顶层运行配置(快照 `ExperimentRunInfo` 投影的字段全集,外加桥接到
+ * 快照顶层权威字段的 `model` / `agent` 两个键)当维度或轴,槽位用法与 {@link FlagRef} 一致。
+ * 未投影的值不猜:分组如实归「(unset)」,作轴不画点、注脚报数。
+ */
+export interface ConfigRef {
+    readonly kind: "config";
+    readonly name: string;
+    /** 组标签 / 轴标签;函数形态把投影值折成组名。 */
+    readonly label?: string | ((value: string | number | boolean) => string);
+    readonly unit?: string;
+}
+/** MetricLine 的 x 轴输入:experiment 声明的 flag,或顶层运行配置(config())。 */
+export type AxisInput = FlagRef | ConfigRef;
+/** 维度槽的输入:内置/自定义维度、experiment 声明的 flag,或顶层运行配置(config())。 */
+export type DimensionInput = Dimension | FlagRef | ConfigRef;
 export interface MetricColumn {
     /** = metric.name,与 cells 的键对应。 */
     key: string;
@@ -258,7 +272,7 @@ export interface GroupSummaryData {
     /**
      * 组的通过率:eval 级折叠计票的 `passed / (passed + failed + errored)`(`skipped` 不进
      * 分母)——这是旧 `GroupSelector` 卡片的口径,不是 `OverviewData.totals.passRate` 那种
-     * `computeCell` 两级聚合(两者服务不同问题:「这组题多少算过」vs「整体质量几分」)。
+     * `computeCell` 两级聚合(两者服务不同问题:「这组题多少算过」vs「每次运行成功多少」)。
      * 分母为 0(组内没有任何已跑的 eval)时 `value` 为 `null`,不编 0%。
      */
     passRate: MetricCell;
@@ -286,10 +300,11 @@ export interface OverviewData {
         errored: number;
         skipped: number;
         /**
-         * 通过率的唯一官方口径:`computeCell(passRate, items)`,与 `MetricTable.data(...,
-         * columns: [passRate])` 同一台两级聚合引擎(题内折叠 perEval、跨题折叠 across,默认都是
+         * 默认成功率的唯一官方口径:`computeCell(endToEndPassRate, items)`,与 `MetricTable.data(...,
+         * columns: [endToEndPassRate])` 同一台两级聚合引擎(题内折叠 perEval、跨题折叠 across,默认都是
          * mean)——一道题内多个 attempt 部分通过,贡献的是小数份额而不是二元票。`samples`/`total`
-         * 是两级聚合口径下的 attempt 计数(`total` 含 skipped,`samples` 不含),不等于上面四个
+         * 是两级聚合口径下的 attempt 计数(`total` 含 skipped 与 errored——endToEndPassRate 对
+         * errored 记 0、只对 skipped 记 null,`samples` 因此只不含 skipped),不等于上面四个
          * verdict 计票的任何一个之和。
          */
         passRate: MetricCell;
@@ -324,8 +339,11 @@ export interface DeltaData<K extends string = string> {
     }[];
 }
 /**
- * `AttemptList` 一项 = 一个 Attempt:身份、判定、断言、error、耗时、成本和 locator。
- * `ExperimentList` / `EvalList` 的下钻数组复用同一个类型,不是各自的精简版。
+ * `AttemptList` 一项 = 一个 Attempt:身份、判定、断言、结构化 error、diagnostics、耗时、
+ * 成本和 locator。`ExperimentList` / `EvalList` 的下钻数组复用同一个类型,不是各自的精简版。
+ * 渲染面只显示一条主失败断言摘要或 error 的一层摘要；完整 assertions、cause / stack 与
+ * diagnostics 属于 locator 下钻详情,不塞进比较列表,但随数据携带 —— `AttemptList.data` 的 `redact`
+ * 钩子覆盖它们的自由文本(见 docs/feature/reports/library.md「AttemptList」)。
  */
 export interface AttemptListItem {
     evalId: string;
@@ -333,23 +351,24 @@ export interface AttemptListItem {
     attempt: number;
     agent: string;
     verdict: Verdict;
-    error?: string;
+    /** 结构化执行错误(与 `EvalResult.error` 同构):列表只显示 `message` 一层摘要。 */
+    error?: AttemptError;
+    /** 本 attempt 的有界诊断(teardown / cleanup 失败等,与 verdict 独立);属于下钻详情。 */
+    diagnostics?: DiagnosticRecord[];
     assertions: AssertionResult[];
     durationMs: number;
     costUSD?: number;
     locator: AttemptLocator;
 }
 /**
- * `ExperimentList` 一项里,一个 Eval 的展开行:折叠判定(`foldEvalVerdict`)、失败原因摘要
- * (`error` → `skipReason` → 未通过的 gate 断言,`reasonFor` 的口径,soft 断言永不进入)、
- * 该 Eval 内 attempt 的平均耗时/成本(两级聚合引擎在单一 eval 上退化成组内均值),以及这道题
- * 的全部 Attempt(升序,供进一步展开到 `AttemptList`)。
+ * `ExperimentList` 一项里,一个 Eval 的展开行:折叠判定(`foldEvalVerdict`)、该 Eval 内
+ * attempt 的平均耗时/成本(两级聚合引擎在单一 eval 上退化成组内均值),以及这道题的全部
+ * Attempt(升序,供进一步展开到 `AttemptList`)。失败原因属于各 Attempt,不在父行挑一轮重复。
  */
 export interface ExperimentListEvalRow {
     evalId: string;
     /** 折叠判定(任一 attempt 通过则通过,否则取最严重的)。 */
     verdict: Verdict;
-    reason?: string;
     /** 这道题内 attempt 的平均耗时(`computeCell(durationMs, …)`,单一 eval 分组下即均值)。 */
     duration: MetricCell;
     /** 这道题内 attempt 的平均成本。 */
@@ -360,7 +379,7 @@ export interface ExperimentListEvalRow {
 /**
  * `ExperimentList.data(selection)` 的一项 = 一个 experiment:身份(experimentId/agent/model)、
  * 声明的 flags、Eval 判定构成(`foldEvalVerdict` 计票,与 view 榜单同一口径)、官方两级聚合
- * 汇总指标(passRate/cost/duration/tokens,直接来自 `computeCell`,不现场重算),以及展开到
+ * 汇总指标(endToEndPassRate/cost/duration/tokens,直接来自 `computeCell`,不现场重算),以及展开到
  * 这个 experiment 每道 Eval 的 `evalRows`(按 eval id 升序)。
  */
 export interface ExperimentListItem {
@@ -375,7 +394,7 @@ export interface ExperimentListItem {
         errored: number;
         skipped: number;
     };
-    /** 官方两级聚合口径,与 `MetricTable.data(..., columns: [passRate])` 同一台引擎。 */
+    /** 官方两级聚合口径(endToEndPassRate),与 `MetricTable.data(..., columns: [endToEndPassRate])` 同一台引擎。 */
     passRate: MetricCell;
     cost: MetricCell;
     duration: MetricCell;
@@ -392,14 +411,13 @@ export interface ExperimentListItem {
 /**
  * `EvalList.data(selection)` 的一项 = 一个 `experimentId + evalId`(同一个 Eval 跑在两个
  * experiment 上是两条不同结果,不合并)。判定、分数(examScore 的两级聚合)、这道题内 attempt
- * 的平均耗时/成本,失败原因摘要(与 `ExperimentListEvalRow.reason` 同一口径),外加展开到这道题
- * 全部 Attempt 的 `attempts`(按 attempt 序号升序)。
+ * 的平均耗时/成本,外加展开到这道题全部 Attempt 的 `attempts`(按 attempt 序号升序)。失败
+ * 原因只存在于各 `AttemptListItem` 的 error / assertions,不会在 Eval 父项重复一份。
  */
 export interface EvalListItem {
     evalId: string;
     experimentId: string;
     verdict: Verdict;
-    reason?: string;
     /** examScore 的两级聚合;单一 eval 分组下即这道题的题级分数。 */
     score: MetricCell;
     duration: MetricCell;

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 {

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;