niceeval 0.6.1 → 0.6.2

package/src/scoring/types.ts

@@ -2,12 +2,25 @@
 
 import type { Severity, SourceLoc } from "../shared/types.ts";
 import type { DerivedFacts, StreamEvent, Usage } from "../o11y/types.ts";
+import type { ResolvedCoverage } from "./coverage.ts";
 
-/** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值。 */
+// 覆盖代数(解析 / 降级 / 聚合)住在 coverage.ts;类型经这里进聚合 facade(src/types.ts)。
+export type {
+  CoverageChannel,
+  ResolvedCoverage,
+  ResolvedCoverageChannel,
+  ResolvedCoverageStatus,
+} from "./coverage.ts";
+
+/** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值 / optional。 */
 export interface ValueAssertion {
   readonly name: string;
   readonly severity: Severity;
   readonly threshold?: number;
+  /** `.optional()` 链过的标记:评不了只记 unavailable,不把 attempt 拖成 errored。 */
+  readonly isOptional?: boolean;
+  /** 期望条件的有界文本描述(如 `contains "Brooklyn"`),失败时进 AssertionResult.expected。 */
+  readonly expected?: string;
   score(value: unknown): number | Promise<number>;
   /** 转成硬门槛断言:未达阈值(省略 threshold 则按 score > 0 判定)整条 eval 判为 failed。返回新实例,不改原对象。 */
   gate(threshold?: number): ValueAssertion;
@@ -16,37 +29,82 @@ export interface ValueAssertion {
    * `--strict` 运行下,软阈值失败也会把整条 eval 的 verdict 计为 failed。返回新实例,不改原对象。
    */
   atLeast(threshold: number): ValueAssertion;
+  /**
+   * 允许这条断言证据缺席:评不了时只记录 `outcome: "unavailable"`,不影响判定。
+   * 与 severity 正交(severity 说影不影响质量判定,optional 说证据允不允许缺席)。返回新实例,不改原对象。
+   */
+  optional(): ValueAssertion;
 }
 
-/** 收集到 collector 里的一条断言记录(评估前)。 */
-export interface AssertionSpec {
+/**
+ * 断言记录的公共字段(见 docs/feature/scoring/architecture.md「断言记录」——字段契约的单点定义)。
+ */
+export interface AssertionBase {
+  /** 断言标题:t.group 内是该断言自己的摘要,组外是 matcher 摘要或 judge 问题;show/view 失败行的标题。 */
   name: string;
+  /** 所属分组路径:外层在前的 t.group 标题数组;无分组省略。纯报告用,不影响判定。 */
+  groupPath?: string[];
   severity: Severity;
-  threshold?: number;
-  /** 延迟评估:final 时拿到完整运行结果再算分。 */
-  evaluate(ctx: ScoringContext): Promise<number> | number;
+  /** 作者用 .optional() 显式允许该断言缺席;只改变 unavailable 的折叠方式(见 Severity 与 Verdict),不改变 severity 语义。 */
+  optional?: true;
+  /** matcher / judge 摘要,如 `equals(4)`、`closedQA("…")`;与 name 分开,供 show/view 同时展示分组标题与检查方式。 */
+  detail?: string;
+  /** 断言在 eval 源码中的调用点,`--eval` 把结果标回源码行的锚。 */
+  loc?: SourceLoc;
 }
 
-/** 断言评估完的结果(进判定 / 报告)。 */
-export interface AssertionResult {
-  name: string;
+/**
+ * 断言评估完的结果(进判定 / 报告)。判别键是 `outcome`——`unavailable` 是没有分数的独立态,
+ * 普通聚合代码按 `outcome` 分支就不可能把证据缺口算成零分。判定只消费
+ * `severity` / `outcome` / `optional` / `score` / `threshold`。
+ */
+export type AssertionResult =
+  | (AssertionBase & {
+      outcome: "passed" | "failed";
+      /** 归一化得分:值断言 0/1,judge 等打分断言 0..1。 */
+      score: number;
+      /** soft 断言的 .atLeast(x) 阈值;没有设阈值则省略。 */
+      threshold?: number;
+      /** 失败证据摘要:期望值的有界文本预览,供 show/view 直接展示。 */
+      expected?: string;
+      /** 失败证据摘要:实际值的有界文本预览。 */
+      received?: string;
+      /** 这条分数看着什么材料算出(judge 输入或被检查值预览);view 展开排查用,默认不展示。 */
+      evidence?: string;
+    })
+  | (AssertionBase & {
+      outcome: "unavailable";
+      /** 机器可读原因,如 "judge-model-unresolved"、"coverage:actions=partial"。 */
+      reason: string;
+    });
+
+/**
+ * 摘要面从完整 `AssertionResult[]` 选出的一条主失败断言。它只负责展示，不参与 verdict；
+ * `show @locator` / view Attempt 详情仍读取完整断言数组。字段保持结构化，使 CI 不必解析
+ * Human 的 `gate: …` 文案。
+ */
+export interface PrimaryAssertionSummary {
   severity: Severity;
+  /** `groupPath.join(" > ")`，无 group 时回退到断言 name。 */
+  assertion: string;
+  /** `detail ?? name`；与 assertion 相同时省略，避免重复。 */
+  matcher?: string;
+  expected?: string;
+  received?: string;
+  score?: number;
   threshold?: number;
-  score: number;
-  passed: boolean;
-  detail?: string;
-  /** 这条分数是看着什么材料算出来的(judge 收到的输入,或 t.check 失败时实际被检查的值)。view 展开排查「为什么是这个分」,默认不展示。 */
-  evidence?: string;
-  /** 所属分组(t.group 标题)。纯报告用,不影响 passed/score。 */
-  group?: string;
-  /** 断言在 eval 源码里的调用点(栈回溯抠出);view 把判定叠回这一行。 */
-  loc?: SourceLoc;
+  /** unavailable 断言的结构化原因。 */
+  reason?: string;
+  /** 同类因果失败中除主失败外的条数。 */
+  additionalFailures: number;
 }
 
 /** eval 作者拿到的可链式句柄(t.judge.autoevals.closedQA(...).atLeast(0.7))。 */
 export interface AssertionHandle {
   atLeast(threshold: number): AssertionHandle;
   gate(threshold?: number): AssertionHandle;
+  /** 允许这条断言证据缺席:unavailable 只保留在记录里,不影响判定(见 Severity 与 Verdict)。 */
+  optional(): AssertionHandle;
 }
 
 /** scoped / judge 断言在 final 评估时拿到的运行结果。 */
@@ -57,6 +115,8 @@ export interface ScoringContext {
   readonly scripts: Record<string, ScriptResult>;
   readonly usage: Usage;
   readonly status: "completed" | "failed" | "waiting";
+  /** 当前作用域(turn / session / attempt)解析后的证据覆盖;断言按它做三值折叠(见 scoped.ts)。 */
+  readonly coverage: ResolvedCoverage;
   /** 读沙箱里某文件的最终内容(judge / file 断言用)。 */
   readFile(path: string): Promise<string | undefined>;
 }
@@ -66,9 +126,46 @@ export interface ScriptResult {
   output: string;
 }
 
+// ── agent 归因增量(见 docs/feature/results/architecture.md「diff.json」与
+//    docs/feature/sandbox/architecture.md「变更归因:send 窗口与分类账」)──
+
+/** diff.json 的落盘形状:按时序的窗口数组(逐窗口 delta 序列,不做跨窗口压缩)。 */
+export type DiffArtifact = DiffWindow[];
+
+export interface DiffWindow {
+  /** send 窗口标签,与时间树 turn 节点、--execution 轮次同源(如 "s1/t2")。 */
+  window: string;
+  /** 该窗口内 agent 改动的文件;窗口内没有 workspace 变化时窗口仍落一条、changes 为空对象。 */
+  changes: Record<string, WindowChange>;
+}
+
+export interface WindowChange {
+  status: "added" | "modified" | "deleted";
+  /** 窗口开始时的内容;added 无此字段。 */
+  before?: string;
+  /** 窗口结束时的内容;deleted 无此字段。 */
+  after?: string;
+  /** 二进制文件不内联内容,只记字节数。 */
+  binary?: { beforeBytes?: number; afterBytes?: number };
+}
+
+/** 读取面在窗口序列之上派生的文件级视图(派生物可随时重算,不落盘)。 */
+export interface DiffFileSummary {
+  /** 净效果:首个触及窗口的起点 vs 最后触及窗口的终点;"none" = 动过但净无变化(创建又删除、改回原样)。 */
+  net: "added" | "modified" | "deleted" | "none";
+  /** 触及该文件的窗口标签,按时序。 */
+  windows: string[];
+  binary?: true;
+}
+
+/** agent 归因 diff 的消费视图:窗口序列(落盘事实)+ 派生的文件级摘要与终态读取。 */
 export interface DiffData {
-  generatedFiles: Record<string, string>;
-  deletedFiles: string[];
+  /** 落盘事实,原样。 */
+  windows: DiffWindow[];
+  /** 派生:每个被 agent 触及的文件一条。 */
+  files: Record<string, DiffFileSummary>;
+  /** 该文件最后一个触及窗口结束时的内容;净删除或从未触及返回 undefined。t.sandbox.diff.get 同一语义。 */
+  get(path: string): string | undefined;
 }
 
 export type Verdict = "passed" | "failed" | "errored" | "skipped";

package/src/scoring/verdict.ts

@@ -1,17 +1,29 @@
-// 判定:把执行结果 + 断言 + 跳过原因折叠成一个 Verdict(见 docs/feature/scoring/README.md)。
+// 判定:把执行结果 + 断言 + 跳过原因折叠成一个 Verdict
+// (见 docs/feature/scoring/architecture/severity-and-verdict.md)。固定优先级取第一个成立项:
+//   执行异常 / 任一非 optional 断言 unavailable → errored
+//   任一 gate 不通过,或 strict 下 soft 低于阈值 → failed
+//   显式 t.skip(reason)                         → skipped
+//   否则                                        → passed
+// errored 压过一切(执行证据已不可信);failed 压过 skipped(t.skip 不掩盖已记录的硬失败)。
 
-import type { AssertionResult, Verdict } from "../types.ts";
+import type { AssertionResult, AttemptError, Verdict } from "../types.ts";
 
 export function computeVerdict(input: {
-  error?: string;
+  error?: AttemptError;
   assertions: readonly AssertionResult[];
   skipReason?: string;
   strict?: boolean;
 }): Verdict {
   if (input.error !== undefined) return "errored";
 
+  // 作者写下的每条断言默认都要求可评估:非 optional 的 unavailable 使 attempt errored,
+  // 不分 gate / soft——「soft 全部评不了但 attempt 还绿着」是没有测量的绿,不允许出现。
   for (const a of input.assertions) {
-    if (a.passed) continue;
+    if (a.outcome === "unavailable" && !a.optional) return "errored";
+  }
+
+  for (const a of input.assertions) {
+    if (a.outcome !== "failed") continue;
     if (a.severity === "gate" || input.strict) return "failed";
   }
 

package/src/shared/aggregate.ts

@@ -1,4 +1,4 @@
-// CLI 表格(runner/reporters/table.ts)与 view 榜单(view/aggregate.ts)共用的聚合小工具。
+// report 聚合(report/aggregate.ts)与 view 榜单(view/app/lib/rows.ts)共用的聚合小工具。
 // 实验标签推导、token/成本求和、verdict 排序各只有一份 —— 否则同一个实验在终端和网页上
 // 会显示成两个名字 / 两组数。保持环境无关(纯函数,只 type import)。
 
@@ -56,11 +56,12 @@ export function evalPrefixPredicate(evals?: string | string[]): (id: string) =>
 
 /** 无 experimentId 时的兜底标签。 */
 export function fallbackExperimentLabel(result: {
+  experimentId?: string;
   experiment?: ExperimentRunInfo;
   agent: string;
   model?: string;
 }): string {
-  if (result.experiment?.id) return displayExperimentName(result.experiment.id) ?? result.experiment.id;
+  if (result.experimentId) return displayExperimentName(result.experimentId) ?? result.experimentId;
   if (result.model) return `${result.agent}/${result.model}`;
   return result.agent || "ad hoc run";
 }

package/src/shared/types.ts

@@ -33,6 +33,37 @@ export interface SourceArtifact {
 /** 通用清理闭包(setup 返回值 / teardown 的形状),异步同步皆可,统一在 finally 里执行。 */
 export type Cleanup = () => Promise<void> | void;
 
+/** `ScopedFeedback.progress` 的入参:此刻正在做什么(短命状态,可被后续更新覆盖)。 */
+export interface ProgressUpdate {
+  message: string;
+  current?: number;
+  total?: number;
+}
+
+/** `ScopedFeedback.diagnostic` 的入参:运行结束后仍应保留的问题(永久事件)。 */
+export interface DiagnosticInput {
+  code: string;
+  level: "warning" | "error";
+  message: string;
+  data?: Readonly<Record<string, JsonValue>>;
+  /** 并发 attempt 产生同一问题时的去重键;相同 key 折叠成一条并累计次数。 */
+  dedupeKey?: string;
+}
+
+/**
+ * 作用域反馈 API(见 docs/feature/experiments/library.md「生命周期代码怎样向这次运行反馈」):
+ * sandbox provider、sandbox hook、eval 与 Agent Adapter 从 runner 注入的上下文获得同一套入口。
+ * - `progress` 是短命状态:Human profile 更新 active 行,Agent/CI 不逐条打印,不进最终结果;
+ * - `diagnostic` 是永久事件:进 Human/Agent/CI 的永久输出流并落进 attempt 的 diagnostics;
+ *   即使 level 为 "error" 也不自动改变 verdict(要 errored 抛异常,要 failed 用断言)。
+ * 两个方法都不接受 phase / scope / 颜色 / 输出流——runner 知道当前回调属于哪个生命周期阶段,
+ * 调用方不能冒充其它阶段。
+ */
+export interface ScopedFeedback {
+  progress(update: ProgressUpdate): void;
+  diagnostic(input: DiagnosticInput): void;
+}
+
 /**
  * 可本地化文案:纯字符串,或按 locale 代码(如 "en"、"zh-CN")映射多语言。
  * view 按当前界面语言挑一条,挑不到回退到 en / 第一条。

package/src/show/compose.ts

@@ -58,14 +58,14 @@ export function evalHistory(exp: Experiment, evalId: string): EvalHistoryRow[] {
       if (c !== null) cost = (cost ?? 0) + c;
     }
     const latest = fresh[fresh.length - 1];
-    const failed = latest.result.assertions.find((a) => !a.passed);
+    const failed = latest.result.assertions.find((a) => a.outcome !== "passed");
     rows.push({
       startedAt: snapshot.startedAt,
       verdict: foldEvalVerdict(fresh.map((a) => a.result)),
       attempts: fresh.length,
       costUSD: cost,
       ...(failed ? { failedAssertion: `${failed.severity} ${failed.name}` } : {}),
-      ...(latest.result.error !== undefined ? { error: latest.result.error } : {}),
+      ...(latest.result.error !== undefined ? { error: latest.result.error.message } : {}),
     });
   }
   return rows.reverse();

package/src/show/index.ts

@@ -50,6 +50,7 @@ import {
   evalSourceText,
   executionText,
   experimentHistoryText,
+  timingText,
   pickDetailAttempt,
   skippedRunsText,
   verdictReasonLine,
@@ -60,6 +61,8 @@ export interface ShowFlags {
   eval?: boolean;
   /** 该 attempt 的标准执行事件流 + OTel enrichment(证据切面)。 */
   execution?: boolean;
+  /** --timing:默认有界诊断投影；full 逐节点展开。boolean 仅供库调用兼容，等价 summary。 */
+  timing?: boolean | "summary" | "full";
   /** --diff(文件级摘要)。 */
   diff?: boolean;
   /** --diff=<路径>(单个文件的完整改动;路径必须 = 连写,位置参数永远留给 eval id 前缀)。 */
@@ -120,7 +123,12 @@ async function show(
   flags: ShowFlags,
   io: { out: (s: string) => void; err: (s: string) => void; width: number; now: number },
 ): Promise<void> {
-  const evidence = flags.eval === true || flags.execution === true || flags.diff === true || flags.diffPath !== undefined;
+  const evidence =
+    flags.eval === true ||
+    flags.execution === true ||
+    (flags.timing !== undefined && flags.timing !== false) ||
+    flags.diff === true ||
+    flags.diffPath !== undefined;
 
   // 组合语义矩阵(docs/feature/reports/show.md「选择结果范围」):--history 与 --report 互斥,先于任何 IO 报出来。
   if (flags.history && flags.report !== undefined) {
@@ -165,6 +173,12 @@ async function show(
       const blocks: string[] = [];
       if (flags.eval) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
       if (flags.execution) blocks.push(executionText(attemptEvidence, { header, artifactPath, width: io.width }));
+      if (flags.timing) blocks.push(timingText(attemptEvidence, {
+        header,
+        artifactPath,
+        width: io.width,
+        mode: flags.timing === "full" ? "full" : "summary",
+      }));
       if (flags.diff || flags.diffPath !== undefined) {
         blocks.push(diffText({ header, diff: attemptEvidence.diff, artifactPath, file: flags.diffPath }));
       }
@@ -228,6 +242,12 @@ async function show(
     const blocks: string[] = [];
     if (flags.eval) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
     if (flags.execution) blocks.push(executionText(attemptEvidence, { header, artifactPath, width: io.width }));
+    if (flags.timing) blocks.push(timingText(attemptEvidence, {
+      header,
+      artifactPath,
+      width: io.width,
+      mode: flags.timing === "full" ? "full" : "summary",
+    }));
     if (flags.diff || flags.diffPath !== undefined) {
       blocks.push(diffText({ header, diff: attemptEvidence.diff, artifactPath, file: flags.diffPath }));
     }