niceeval 0.6.0 → 0.6.2

package/src/scoring/coverage.ts

@@ -0,0 +1,95 @@
+// 证据覆盖的解析与折叠:Agent 级默认 + Turn 级降级 → attempt 级聚合
+// (见 docs/feature/adapters/architecture/evidence.md「覆盖声明」)。
+// 消费规则(正/负断言的三值折叠)在 scoped.ts;这里只管状态代数:
+// unknown/unavailable < partial < complete,Turn 只能降级、聚合取最差。
+
+import type { CoverageDeclaration, CoverageStatus, EvidenceCoverage } from "../agents/types.ts";
+
+/** 证据通道全集(EvidenceCoverage 的键)。 */
+export const COVERAGE_CHANNELS = ["events", "actions", "messages", "usage", "status", "data"] as const;
+export type CoverageChannel = (typeof COVERAGE_CHANNELS)[number];
+
+/**
+ * 解析后的通道状态:未声明按 "unknown" 落地(不是 complete)。unknown 与 unavailable 在
+ * 消费侧同样保守;区别只在展示(unknown =「Adapter 没说」,unavailable =「Adapter 说了拿不到」)。
+ */
+export type ResolvedCoverageStatus = CoverageStatus | "unknown";
+
+/** 解析后的单通道声明。 */
+export interface ResolvedCoverageChannel {
+  status: ResolvedCoverageStatus;
+  reason?: string;
+}
+
+/** 全通道解析后的覆盖:每个通道必有一个状态(缺省 unknown)。 */
+export type ResolvedCoverage = Readonly<Record<CoverageChannel, ResolvedCoverageChannel>>;
+
+/**
+ * 官方 SDK 适配器用的「全通道 complete」常量:完整事件流、完整 steps/output、经过生命周期
+ * fixture 验证的 transcript 才可以声明它(见 docs/feature/adapters/architecture/evidence.md)。
+ */
+export const completeCoverage: EvidenceCoverage = Object.freeze<EvidenceCoverage>({
+  events: { status: "complete" },
+  actions: { status: "complete" },
+  messages: { status: "complete" },
+  usage: { status: "complete" },
+  status: { status: "complete" },
+  data: { status: "complete" },
+});
+
+// 状态序:折叠一律取最差。unknown 与 unavailable 保守程度相同,并列最差;
+// 并列时取「有声明的那一个」(unavailable 带 reason,信息量更大)。
+const RANK: Record<ResolvedCoverageStatus, number> = {
+  complete: 3,
+  partial: 2,
+  unavailable: 1,
+  unknown: 1,
+};
+
+function worseOf(a: ResolvedCoverageChannel, b: ResolvedCoverageChannel): ResolvedCoverageChannel {
+  const ra = RANK[a.status];
+  const rb = RANK[b.status];
+  if (ra < rb) return a;
+  if (rb < ra) return b;
+  // 并列:优先「Adapter 说了拿不到」(unavailable / 带 reason)而不是「没说」。
+  if (a.status === "unknown" && b.status !== "unknown") return b;
+  if (b.status === "unknown" && a.status !== "unknown") return a;
+  return a.reason !== undefined ? a : b;
+}
+
+/** Agent 级声明 → 全通道解析(未声明通道 = unknown)。 */
+export function resolveAgentCoverage(declared: EvidenceCoverage | undefined): ResolvedCoverage {
+  const out = {} as Record<CoverageChannel, ResolvedCoverageChannel>;
+  for (const ch of COVERAGE_CHANNELS) {
+    const d: CoverageDeclaration | undefined = declared?.[ch];
+    out[ch] = d ? { status: d.status, ...(d.reason !== undefined ? { reason: d.reason } : {}) } : { status: "unknown" };
+  }
+  return out;
+}
+
+/**
+ * Turn 级降级:相对 base(Agent 默认)只能变差,不能升格——Turn 声明比 base 更好的状态
+ * 直接被 base 压住(min 语义天然满足「不能把 Agent 未声明的通道升格成 complete」)。
+ */
+export function downgradeCoverage(base: ResolvedCoverage, turn: EvidenceCoverage | undefined): ResolvedCoverage {
+  if (!turn) return base;
+  const out = {} as Record<CoverageChannel, ResolvedCoverageChannel>;
+  for (const ch of COVERAGE_CHANNELS) {
+    const d = turn[ch];
+    out[ch] = d ? worseOf(base[ch], { status: d.status, ...(d.reason !== undefined ? { reason: d.reason } : {}) }) : base[ch];
+  }
+  return out;
+}
+
+/** attempt / session 级聚合:各 turn 的最差值(unknown/unavailable < partial < complete)。 */
+export function worstCoverage(list: readonly ResolvedCoverage[]): ResolvedCoverage {
+  if (list.length === 0) return resolveAgentCoverage(undefined);
+  let acc = list[0]!;
+  for (let i = 1; i < list.length; i++) {
+    const next = list[i]!;
+    const out = {} as Record<CoverageChannel, ResolvedCoverageChannel>;
+    for (const ch of COVERAGE_CHANNELS) out[ch] = worseOf(acc[ch], next[ch]);
+    acc = out;
+  }
+  return acc;
+}

package/src/scoring/diff.ts

@@ -0,0 +1,81 @@
+// agent 归因 diff 的派生视图:从落盘事实(DiffWindow[])派生文件级摘要与终态读取。
+// 派生物可随时重算、不落盘——符合「聚合在消费方」铁律(docs/feature/results/architecture.md「diff.json」)。
+
+import type { DiffArtifact, DiffData, DiffFileSummary, DiffWindow, WindowChange } from "./types.ts";
+
+/** 从窗口序列派生 DiffData:files 摘要(net / 触及窗口)+ get(最后触及窗口的终态)。 */
+export function deriveDiffData(windows: DiffArtifact): DiffData {
+  const touched = new Map<string, { first: WindowChange; last: WindowChange; windows: string[]; binary: boolean }>();
+  for (const window of windows) {
+    for (const [path, change] of Object.entries(window.changes)) {
+      const entry = touched.get(path);
+      if (entry) {
+        entry.last = change;
+        entry.windows.push(window.window);
+        if (change.binary) entry.binary = true;
+      } else {
+        touched.set(path, { first: change, last: change, windows: [window.window], binary: change.binary !== undefined });
+      }
+    }
+  }
+
+  const files: Record<string, DiffFileSummary> = {};
+  for (const [path, entry] of touched) {
+    files[path] = {
+      net: computeNet(entry.first, entry.last),
+      windows: entry.windows,
+      ...(entry.binary ? { binary: true as const } : {}),
+    };
+  }
+
+  return {
+    windows,
+    files,
+    get(path: string): string | undefined {
+      const entry = touched.get(path);
+      if (!entry) return undefined;
+      if (entry.last.status === "deleted") return undefined;
+      return entry.last.after;
+    },
+  };
+}
+
+/** 净效果:首个触及窗口的起点 vs 最后触及窗口的终点。 */
+function computeNet(first: WindowChange, last: WindowChange): DiffFileSummary["net"] {
+  const existedBefore = first.status !== "added";
+  const existsAfter = last.status !== "deleted";
+  if (!existedBefore && !existsAfter) return "none"; // 创建又删除
+  if (!existedBefore && existsAfter) return "added";
+  if (existedBefore && !existsAfter) return "deleted";
+  // 改回原样 = none;比较首窗口起点与末窗口终点的内容(二进制按字节数近似)。
+  const beforeContent = first.before ?? first.binary?.beforeBytes;
+  const afterContent = last.after ?? last.binary?.afterBytes;
+  if (beforeContent !== undefined && afterContent !== undefined && beforeContent === afterContent) return "none";
+  return "modified";
+}
+
+/** DiffArtifact 里是否有任何窗口触及过任何文件。 */
+export function diffIsEmpty(diff: DiffData): boolean {
+  return Object.keys(diff.files).length === 0;
+}
+
+/** 正则是否命中任何被触及的路径或任何窗口的 before/after 内容。 */
+export function diffMatches(diff: DiffData, re: RegExp): boolean {
+  for (const path of Object.keys(diff.files)) {
+    if (re.test(path)) return true;
+  }
+  for (const window of diff.windows) {
+    for (const change of Object.values(window.changes)) {
+      if (change.after !== undefined && re.test(change.after)) return true;
+      if (change.before !== undefined && re.test(change.before)) return true;
+    }
+  }
+  return false;
+}
+
+/** 空 diff(remote / skipped attempt)。 */
+export function emptyDiffData(): DiffData {
+  return deriveDiffData([]);
+}
+
+export type { DiffArtifact, DiffData, DiffWindow, WindowChange } from "./types.ts";

package/src/scoring/display.test.ts

@@ -0,0 +1,121 @@
+// cases: docs/engineering/unit-tests/scoring/cases.md
+import { describe, expect, it } from "vitest";
+import type { AssertionResult } from "./types.ts";
+import {
+  assertionSummaryLines,
+  compactAssertionSummary,
+  fitCompactAssertionSummary,
+  primaryAssertionSummary,
+} from "./display.ts";
+
+describe("primaryAssertionSummary", () => {
+  it("选择第一条失败 gate，保留领域 group、matcher 与 expected/received，并只计数其余 gate", () => {
+    const assertions: AssertionResult[] = [
+      { name: "style", severity: "soft", outcome: "failed", score: 0.2, threshold: 0.8 },
+      {
+        name: "equals(4)",
+        groupPath: ["Issue 15193: selected proposal matches the accepted proposal"],
+        severity: "gate",
+        outcome: "failed",
+        score: 0,
+        expected: "4",
+        received: "3",
+      },
+      { name: "matches(schema)", severity: "gate", outcome: "failed", score: 0 },
+    ];
+
+    const summary = primaryAssertionSummary(assertions, "failed");
+    expect(summary).toEqual({
+      severity: "gate",
+      assertion: "Issue 15193: selected proposal matches the accepted proposal",
+      matcher: "equals(4)",
+      expected: "4",
+      received: "3",
+      additionalFailures: 1,
+    });
+    expect(assertionSummaryLines(summary!)).toEqual([
+      "gate: Issue 15193: selected proposal matches the accepted proposal",
+      "equals(4) · expected 4 · received 3 · +1 more failures",
+    ]);
+    expect(compactAssertionSummary(summary!)).toBe(
+      "gate: Issue 15193: selected proposal matches the accepted proposal · equals(4) · expected 4 · received 3 · +1 more failures",
+    );
+  });
+
+  it("无 group 时不重复 matcher；failed verdict 没有 gate 才选择 soft", () => {
+    const summary = primaryAssertionSummary(
+      [{ name: "similarity", severity: "soft", outcome: "failed", score: 0.71, threshold: 0.9 }],
+      "failed",
+    );
+    expect(compactAssertionSummary(summary!)).toBe("similarity · score 0.71 · threshold 0.9");
+  });
+
+  it("errored 可由首条非 optional unavailable 解释，passed 不产生摘要", () => {
+    const assertions: AssertionResult[] = [
+      { name: "failed gate is not the errored root cause", severity: "gate", outcome: "failed", score: 0 },
+      { name: "optional judge", severity: "soft", optional: true, outcome: "unavailable", reason: "no-key" },
+      { name: "required judge", severity: "gate", outcome: "unavailable", reason: "judge-model-unresolved" },
+    ];
+    expect(primaryAssertionSummary(assertions, "errored")).toMatchObject({
+      assertion: "required judge",
+      reason: "judge-model-unresolved",
+    });
+    expect(primaryAssertionSummary(assertions, "passed")).toBeUndefined();
+  });
+
+  it("摘要把多行大值压成单行有界预览，完整断言证据不在这里展开", () => {
+    const assertions: AssertionResult[] = [{
+      name: "includes(/updateTag/)",
+      severity: "gate",
+      outcome: "failed",
+      score: 0,
+      expected: "matches /updateTag/",
+      received: `// app/actions/posts.ts\n'use server';\n${"const source = 1;\n".repeat(80)}`,
+    }];
+
+    const summary = primaryAssertionSummary(assertions, "failed")!;
+    expect(summary.received).not.toContain("\n");
+    expect(summary.received!.length).toBeLessThanOrEqual(240);
+    expect(summary.received).toMatch(/…$/);
+    const lines = assertionSummaryLines(summary);
+    expect(lines).toHaveLength(2);
+    expect(lines.every((line) => !line.includes("\n"))).toBe(true);
+  });
+});
+
+describe("fitCompactAssertionSummary", () => {
+  const summary = primaryAssertionSummary(
+    [{
+      name: "includes(/['\"]use cache['\"];?/)",
+      groupPath: ["Catalog reads use use-cache directive and products cache tag"],
+      severity: "gate",
+      outcome: "failed",
+      score: 0,
+      expected: "matches /['\"]use cache['\"];?/",
+      received: `// next.config.ts\n${"import type { NextConfig } from 'next';\n".repeat(20)}`,
+    }],
+    "failed",
+  )!;
+
+  it("预算充足时与 compactAssertionSummary 完全一致", () => {
+    const full = compactAssertionSummary(summary);
+    expect(fitCompactAssertionSummary(summary, full.length)).toBe(full);
+  });
+
+  it("空间不足先截语义标题,received 保留最大份额", () => {
+    const full = compactAssertionSummary(summary);
+    const fitted = fitCompactAssertionSummary(summary, full.length - 20);
+    expect(fitted.length).toBeLessThanOrEqual(full.length - 20);
+    // 标题被截(带 …),matcher 与 received 前缀仍在
+    expect(fitted).not.toContain("Catalog reads use use-cache directive and products cache tag");
+    expect(fitted).toContain("…");
+    expect(fitted).toContain("includes(");
+    expect(fitted).toContain("received");
+  });
+
+  it("预算再小也收得住:整串不超预算且以 … 收口", () => {
+    const fitted = fitCompactAssertionSummary(summary, 80);
+    expect(fitted.length).toBeLessThanOrEqual(80);
+    expect(fitted).toMatch(/…/);
+  });
+});

package/src/scoring/display.ts

@@ -0,0 +1,133 @@
+// scoring 结果的摘要投影。这里仅决定「摘要面显示哪一条、显示哪些事实」；完整诊断面继续
+// 消费 AssertionResult[]，不复用这个有损投影。
+
+import type { AssertionResult, PrimaryAssertionSummary, Verdict } from "./types.ts";
+
+/**
+ * Human/Agent 摘要是一条终端事实行，不是完整证据面。压成单行并设字符上限，避免 received
+ * 恰好是源码/工具输出时把多页内容灌进 scrollback；完整 AssertionResult 仍原样留给 show/view。
+ */
+const SUMMARY_TEXT_MAX_CHARS = 240;
+
+/** 摘要面的单值收口:折单行 + 240 字符上限。任何把断言事实放进「行」里的面共用这一条。 */
+export function summaryText(value: string): string {
+  const singleLine = value.replace(/\s+/g, " ").trim();
+  return singleLine.length <= SUMMARY_TEXT_MAX_CHARS
+    ? singleLine
+    : `${singleLine.slice(0, SUMMARY_TEXT_MAX_CHARS - 1)}…`;
+}
+
+/**
+ * 按公开展示契约选择主失败断言：failed gate 优先；只有 soft 促成 failed verdict 时才取 soft；
+ * errored 且没有结构化 error 时可由第一条非 optional unavailable 解释。
+ */
+export function primaryAssertionSummary(
+  assertions: readonly AssertionResult[],
+  verdict: Verdict,
+): PrimaryAssertionSummary | undefined {
+  if (verdict === "failed") {
+    const failedGates = assertions.filter(
+      (assertion) => assertion.outcome === "failed" && assertion.severity === "gate",
+    );
+    if (failedGates.length > 0) return summaryOf(failedGates[0]!, failedGates.length - 1);
+
+    const failedSoft = assertions.filter(
+      (assertion) => assertion.outcome === "failed" && assertion.severity === "soft",
+    );
+    if (failedSoft.length > 0) return summaryOf(failedSoft[0]!, failedSoft.length - 1);
+  }
+
+  if (verdict === "errored") {
+    const unavailable = assertions.filter(
+      (assertion) => assertion.outcome === "unavailable" && assertion.optional !== true,
+    );
+    if (unavailable.length > 0) return summaryOf(unavailable[0]!, unavailable.length - 1);
+  }
+
+  return undefined;
+}
+
+function summaryOf(assertion: AssertionResult, additionalFailures: number): PrimaryAssertionSummary {
+  const rawTitle = assertion.groupPath?.length ? assertion.groupPath.join(" > ") : assertion.name;
+  const rawMatcher = assertion.detail ?? assertion.name;
+  const title = summaryText(rawTitle);
+  return {
+    severity: assertion.severity,
+    assertion: title,
+    ...(rawMatcher !== rawTitle ? { matcher: summaryText(rawMatcher) } : {}),
+    ...(assertion.outcome === "unavailable"
+      ? { reason: summaryText(assertion.reason) }
+      : {
+          ...(assertion.expected !== undefined ? { expected: summaryText(assertion.expected) } : {}),
+          ...(assertion.received !== undefined ? { received: summaryText(assertion.received) } : {}),
+          ...(assertion.severity === "soft" || assertion.threshold !== undefined ? { score: assertion.score } : {}),
+          ...(assertion.threshold !== undefined ? { threshold: assertion.threshold } : {}),
+        }),
+    additionalFailures,
+  };
+}
+
+/** 摘要的事实层；Human/Agent 用作第二行，表格可把它接在标题后。 */
+export function assertionSummaryDetail(summary: PrimaryAssertionSummary): string | undefined {
+  const parts: string[] = [];
+  if (summary.matcher !== undefined) parts.push(summary.matcher);
+  if (summary.expected !== undefined) parts.push(`expected ${summary.expected}`);
+  if (summary.received !== undefined) parts.push(`received ${summary.received}`);
+  if (summary.score !== undefined) parts.push(`score ${summary.score}`);
+  if (summary.threshold !== undefined) parts.push(`threshold ${summary.threshold}`);
+  if (summary.reason !== undefined) parts.push(`reason ${summary.reason}`);
+  if (summary.additionalFailures > 0) parts.push(`+${summary.additionalFailures} more failures`);
+  return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+
+/** Human/Agent 的至多两层文本。 */
+export function assertionSummaryLines(summary: PrimaryAssertionSummary): [string] | [string, string] {
+  const head = `${summary.severity}: ${summary.assertion}`;
+  const detail = assertionSummaryDetail(summary);
+  return detail === undefined ? [head] : [head, detail];
+}
+
+/** 比较列表的单元格投影；无 group 时不重复 `gate:` 前缀。 */
+export function compactAssertionSummary(summary: PrimaryAssertionSummary): string {
+  const hasDistinctTitle = summary.matcher !== undefined;
+  const head = hasDistinctTitle ? `${summary.severity}: ${summary.assertion}` : summary.assertion;
+  const detail = assertionSummaryDetail(summary);
+  return detail === undefined ? head : `${head} · ${detail}`;
+}
+
+/** 收口用的截断:目标长度容不下时截到 target-1 并补 `…`。 */
+function shrinkTo(text: string, target: number): string {
+  return text.length <= target ? text : `${text.slice(0, Math.max(0, target - 1))}…`;
+}
+
+/**
+ * 单元格投影的宽度收口。空间不足时按解释力从低到高让位:先截语义标题、再截 matcher,
+ * `expected / received` 与 `+N more failures` 最后截——它们直接解释为什么红。
+ * maxChars 由渲染面按可用宽度给(如两行单元格 = 2 × 列宽);字符数口径与
+ * SUMMARY_TEXT_MAX_CHARS 一致,显示宽度的精确裁剪仍归渲染面。
+ */
+export function fitCompactAssertionSummary(summary: PrimaryAssertionSummary, maxChars: number): string {
+  const budget = Math.max(24, Math.floor(maxChars));
+  let full = compactAssertionSummary(summary);
+  if (full.length <= budget) return full;
+
+  const TITLE_FLOOR = 24;
+  let fitted: PrimaryAssertionSummary = {
+    ...summary,
+    assertion: shrinkTo(summary.assertion, Math.max(TITLE_FLOOR, summary.assertion.length - (full.length - budget))),
+  };
+  full = compactAssertionSummary(fitted);
+  if (full.length <= budget) return full;
+
+  const MATCHER_FLOOR = 16;
+  if (fitted.matcher !== undefined) {
+    fitted = {
+      ...fitted,
+      matcher: shrinkTo(fitted.matcher, Math.max(MATCHER_FLOOR, fitted.matcher.length - (full.length - budget))),
+    };
+    full = compactAssertionSummary(fitted);
+    if (full.length <= budget) return full;
+  }
+
+  return shrinkTo(full, budget);
+}

package/src/scoring/evidence.test.ts

@@ -0,0 +1,189 @@
+// cases: docs/engineering/unit-tests/scoring/cases.md
+// 证据完整性模型的单测:覆盖代数(resolve/downgrade/worst)、作用域断言的三值折叠、
+// 判定折叠(非 optional unavailable → errored)、judge 未解析 → unavailable。
+// 契约见 docs/feature/scoring/architecture/{severity-and-verdict,evidence}.md 与
+// docs/feature/adapters/architecture/evidence.md。
+
+import { describe, expect, it } from "vitest";
+import { completeCoverage, downgradeCoverage, resolveAgentCoverage, worstCoverage } from "./coverage.ts";
+import { emptyDiffData } from "./diff.ts";
+import { computeVerdict } from "./verdict.ts";
+import { AssertionCollector } from "./collector.ts";
+import * as Scoped from "./scoped.ts";
+import { buildJudge } from "./judge.ts";
+import { deriveRunFacts } from "../o11y/derive.ts";
+import type { AssertionResult, ScoringContext, StreamEvent } from "../types.ts";
+
+function ctxWith(over: Partial<ScoringContext> = {}): ScoringContext {
+  const events = (over.events ?? []) as StreamEvent[];
+  return {
+    events,
+    facts: deriveRunFacts(events),
+    diff: emptyDiffData(),
+    scripts: {},
+    usage: { inputTokens: 0, outputTokens: 0 },
+    status: "completed",
+    coverage: resolveAgentCoverage(completeCoverage),
+    readFile: async () => undefined,
+    ...over,
+  };
+}
+
+const UNKNOWN = resolveAgentCoverage(undefined);
+
+describe("coverage 代数", () => {
+  it("未声明 = unknown,不是 complete", () => {
+    expect(UNKNOWN.actions.status).toBe("unknown");
+    expect(UNKNOWN.usage.status).toBe("unknown");
+  });
+
+  it("Turn 只能降级,不能把 Agent 未声明的通道升格成 complete", () => {
+    const upgraded = downgradeCoverage(UNKNOWN, { actions: { status: "complete" } });
+    expect(upgraded.actions.status).toBe("unknown");
+    const downgraded = downgradeCoverage(resolveAgentCoverage(completeCoverage), {
+      actions: { status: "partial", reason: "stream reconnected" },
+    });
+    expect(downgraded.actions).toEqual({ status: "partial", reason: "stream reconnected" });
+  });
+
+  it("聚合取最差值(unknown/unavailable < partial < complete)", () => {
+    const a = resolveAgentCoverage(completeCoverage);
+    const b = downgradeCoverage(a, { usage: { status: "unavailable" } });
+    const worst = worstCoverage([a, b]);
+    expect(worst.usage.status).toBe("unavailable");
+    expect(worst.events.status).toBe("complete");
+  });
+});
+
+async function evaluate(spec: ReturnType<typeof Scoped.usedNoTools>, ctx: ScoringContext): Promise<AssertionResult> {
+  const collector = new AssertionCollector();
+  collector.record(spec);
+  const [result] = await collector.finalize(ctx);
+  return result!;
+}
+
+describe("作用域断言的三值折叠", () => {
+  const toolEvents: StreamEvent[] = [
+    { type: "action.called", callId: "c1", name: "shell", input: { cmd: "ls" } } as StreamEvent,
+    { type: "action.result", callId: "c1", output: {}, status: "completed" } as StreamEvent,
+  ];
+
+  it("正断言:非 complete 通道上找到匹配仍通过(证据存在就是证据)", async () => {
+    const ctx = ctxWith({ events: toolEvents, coverage: UNKNOWN });
+    const r = await evaluate(Scoped.calledTool("shell"), ctx);
+    expect(r.outcome).toBe("passed");
+  });
+
+  it("正断言:非 complete 通道上没找到记 unavailable,不判失败", async () => {
+    const ctx = ctxWith({ coverage: UNKNOWN });
+    const r = await evaluate(Scoped.calledTool("shell"), ctx);
+    expect(r.outcome).toBe("unavailable");
+    expect(r.outcome === "unavailable" && r.reason).toContain("coverage:actions=unknown");
+  });
+
+  it("正断言:complete 通道上没找到才是 failed", async () => {
+    const r = await evaluate(Scoped.calledTool("shell"), ctxWith());
+    expect(r.outcome).toBe("failed");
+  });
+
+  it("负断言:找到反例即 failed(与覆盖无关)", async () => {
+    const ctx = ctxWith({ events: toolEvents, coverage: UNKNOWN });
+    const r = await evaluate(Scoped.notCalledTool("shell"), ctx);
+    expect(r.outcome).toBe("failed");
+  });
+
+  it("负断言:空流 + 非 complete 通道 = unavailable(空流证明不了「没发生」)", async () => {
+    const ctx = ctxWith({ coverage: UNKNOWN });
+    const r = await evaluate(Scoped.usedNoTools(), ctx);
+    expect(r.outcome).toBe("unavailable");
+  });
+
+  it("上限断言:实测已超限即 failed(partial 只会少采)", async () => {
+    const ctx = ctxWith({ usage: { inputTokens: 900, outputTokens: 200 }, coverage: UNKNOWN });
+    const r = await evaluate(Scoped.maxTokens(1000), ctx);
+    expect(r.outcome).toBe("failed");
+  });
+
+  it("上限断言:未超限但 usage 通道非 complete = unavailable(不能按零聚合)", async () => {
+    const ctx = ctxWith({ coverage: UNKNOWN });
+    const r = await evaluate(Scoped.maxTokens(1000), ctx);
+    expect(r.outcome).toBe("unavailable");
+    expect(r.outcome === "unavailable" && r.reason).toContain("coverage:usage=unknown");
+  });
+});
+
+describe("eventsSatisfy 作者参数错误", () => {
+  it("旧的 (predicate, label) 顺序在记录时给出迁移提示,不留到 finalize 才报 predicate is not a function", () => {
+    expect(() =>
+      Reflect.apply(Scoped.eventsSatisfy, undefined, [() => true, "has an event"]),
+    ).toThrow(/former \(predicate, label\) order is not supported/);
+  });
+
+  it("label 必须是非空字符串", () => {
+    expect(() => Scoped.eventsSatisfy("  ", () => true)).toThrow(/non-empty string label/);
+  });
+});
+
+describe("判定折叠:非 optional unavailable → errored", () => {
+  const unavailableGate: AssertionResult = {
+    name: "notCalledTool(bash)",
+    severity: "gate",
+    outcome: "unavailable",
+    reason: "coverage:actions=partial",
+  };
+  const passedGate: AssertionResult = { name: "ok", severity: "gate", outcome: "passed", score: 1 };
+
+  it("任一非 optional 断言 unavailable,attempt 即 errored(不分 gate/soft)", () => {
+    expect(computeVerdict({ assertions: [passedGate, unavailableGate] })).toBe("errored");
+    const softUnavailable: AssertionResult = { ...unavailableGate, severity: "soft" };
+    expect(computeVerdict({ assertions: [passedGate, softUnavailable] })).toBe("errored");
+  });
+
+  it(".optional() 的 unavailable 只保留在记录里,不影响 Verdict", () => {
+    const optional: AssertionResult = { ...unavailableGate, optional: true };
+    expect(computeVerdict({ assertions: [passedGate, optional] })).toBe("passed");
+  });
+
+  it("errored 压过 failed;failed 压过 skipped", () => {
+    const failedGate: AssertionResult = { name: "x", severity: "gate", outcome: "failed", score: 0 };
+    expect(computeVerdict({ assertions: [failedGate, unavailableGate] })).toBe("errored");
+    expect(computeVerdict({ assertions: [failedGate], skipReason: "later" })).toBe("failed");
+  });
+});
+
+describe("judge 未解析到模型 / key:记 unavailable,绝不静默、不崩", () => {
+  it("缺 key 时该条断言照常记录,finalize 落 unavailable(reason: judge-key-unresolved)", async () => {
+    const collector = new AssertionCollector();
+    const judge = buildJudge({
+      record: (spec) => collector.record(spec),
+      judge: { model: "gpt-x", apiKeyEnv: "NICEEVAL_TEST_NO_SUCH_KEY" },
+      getOutput: () => "output",
+      getInput: () => "input",
+    });
+    judge.autoevals.closedQA("是否切题?");
+    const [r] = await collector.finalize(ctxWith());
+    expect(r!.outcome).toBe("unavailable");
+    expect(r!.outcome === "unavailable" && r!.reason).toContain("judge-key-unresolved");
+  });
+
+  it("缺 model 时不在调用点抛错,落 unavailable(reason: judge-model-unresolved)", async () => {
+    const prevModel = process.env.NICEEVAL_JUDGE_MODEL;
+    delete process.env.NICEEVAL_JUDGE_MODEL;
+    try {
+      const collector = new AssertionCollector();
+      const judge = buildJudge({
+        record: (spec) => collector.record(spec),
+        judge: undefined,
+        getOutput: () => "output",
+        getInput: () => "input",
+      });
+      expect(() => judge.autoevals.factuality("参考答案").optional()).not.toThrow();
+      const [r] = await collector.finalize(ctxWith());
+      expect(r!.outcome).toBe("unavailable");
+      expect(r!.outcome === "unavailable" && r!.reason).toContain("judge-model-unresolved");
+      expect(r!.optional).toBe(true);
+    } finally {
+      if (prevModel !== undefined) process.env.NICEEVAL_JUDGE_MODEL = prevModel;
+    }
+  });
+});