niceeval 0.6.1 → 0.6.2

package/src/context/session.ts

@@ -3,6 +3,7 @@
 
 import type { Agent, AgentContext, AgentSession, InputFile, InputRequest, InputResponse, Sandbox, StreamEvent, Telemetry, TraceSpan, Turn, Usage } from "../types.ts";
 import type { AgentOtelChannel } from "../o11y/otlp/turn-otel.ts";
+import { downgradeCoverage, resolveAgentCoverage, worstCoverage, type ResolvedCoverage } from "../scoring/coverage.ts";
 import { captureLoc } from "../source-loc.ts";
 import { t } from "../i18n/index.ts";
 
@@ -81,6 +82,10 @@ export class RunSession implements AgentSession {
   readonly events: StreamEvent[] = [];
   readonly pendingInputRequests: InputRequest[] = [];
   readonly usage: Usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, requests: 0 };
+  /** 本会话累计的证据覆盖(初值 = Agent 级默认,逐轮按 Turn.coverage 降级折叠)。 */
+  coverage!: ResolvedCoverage;
+  /** 本会话内的轮次计数(turn 时间树 / 展示标签 s<session>/t<turn> 用)。 */
+  turnCount = 0;
 }
 
 export interface SessionDeps {
@@ -91,6 +96,29 @@ export interface SessionDeps {
   flags: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
+  /** runner 绑定的作用域反馈(adapter ctx.progress/diagnostic);省略时 progress 退回 log。 */
+  feedback?: import("../types.ts").ScopedFeedback;
+  /** adapter send 在飞时通知 runner(errored 归因到嵌套的 `agent.run` 阶段用)。 */
+  onSendActive?: (active: boolean) => void;
+  /**
+   * 变更分类账的 send 窗口钩子(仅沙箱型 agent):`beforeSend` 在 adapter send 前落 eval 归因
+   * commit,`afterSend` 在返回后落 agent 归因 commit;label 是 `s<session>/t<turn>` 窗口标签。
+   * 提供钩子时 send 自动串行(同一 workdir 上重叠的 send 是写入竞争,窗口不重叠)。
+   */
+  ledgerHooks?: {
+    beforeSend(label: string): Promise<void>;
+    afterSend(label: string): Promise<void>;
+  };
+  /** 每轮 send 结束后回报墙钟包络(runner 挂成 eval.run 下的 turn 时间树节点)。 */
+  onTurn?: (info: {
+    sessionIndex: number;
+    turnIndex: number;
+    startedAt: number;
+    durationMs: number;
+    failed?: boolean;
+    traceId?: string;
+    traceAttribution?: "traceparent" | "window" | "none";
+  }) => void;
   /** 路径推导出的实验 id(经 send ctx 透给 adapter,见 AgentContext.experimentId)。 */
   experimentId?: string;
   /** tracing agent 的 OTLP 端点(经 send ctx 透给 adapter,用于注入导出 env)。 */
@@ -104,6 +132,10 @@ export class SessionManager {
   readonly allEvents: StreamEvent[] = [];
   readonly usage: Usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, requests: 0 };
   lastStatus: "completed" | "failed" | "waiting" = "completed";
+  /** Agent 级默认覆盖(全通道解析,未声明 = unknown)。 */
+  readonly agentCoverage: ResolvedCoverage;
+  /** attempt 级累计覆盖:各轮解析后覆盖的最差值,随每次 send 折叠。 */
+  coverage: ResolvedCoverage;
 
   /** 归属到本 attempt 的 span(逐轮攒;attempt 末尾连同 sweep 的迟到 span 一起挂 trace)。 */
   readonly otelSpans: TraceSpan[] = [];
@@ -116,18 +148,28 @@ export class SessionManager {
   private readonly sessions: RunSession[] = [];
   private turnCount = 0;
   private sessionCount = 0;
+  /** 沙箱型 send 的串行链(见 SessionDeps.ledgerHooks):窗口不重叠。 */
+  private sendChain: Promise<unknown> = Promise.resolve();
 
   constructor(private readonly deps: SessionDeps) {
+    this.agentCoverage = resolveAgentCoverage(deps.agent.coverage);
+    this.coverage = this.agentCoverage;
     this.primary = this.newSession();
   }
 
   newSession(): RunSession {
     const s = new RunSession();
     s.index = ++this.sessionCount;
+    s.coverage = this.agentCoverage;
     this.sessions.push(s);
     return s;
   }
 
+  /** 一轮的解析后覆盖:Agent 默认按 Turn.coverage 降级(只降不升)。 */
+  resolveTurnCoverage(turn: Turn): ResolvedCoverage {
+    return downgradeCoverage(this.agentCoverage, turn.coverage);
+  }
+
   async send(
     session: RunSession,
     text: string,
@@ -136,6 +178,23 @@ export class SessionManager {
   ): Promise<Turn> {
     // 抓住作者调 t.send / t.sendFile 那一行(view 把回复叠回这一行)。
     const loc = captureLoc();
+    if (this.deps.ledgerHooks) {
+      // 沙箱型 send 经串行链执行:同一 workdir 上重叠的 send 本身就是写入竞争,
+      // 合并窗口只会掩盖归因不确定性(见 docs/feature/sandbox/architecture.md)。
+      const run = this.sendChain.then(() => this.sendSerialized(session, text, loc, files, responses));
+      this.sendChain = run.catch(() => {});
+      return run;
+    }
+    return this.sendSerialized(session, text, loc, files, responses);
+  }
+
+  private async sendSerialized(
+    session: RunSession,
+    text: string,
+    loc: ReturnType<typeof captureLoc>,
+    files?: readonly InputFile[],
+    responses?: readonly InputResponse[],
+  ): Promise<Turn> {
     const ctx: AgentContext = {
       signal: this.deps.signal,
       model: this.deps.model,
@@ -145,6 +204,12 @@ export class SessionManager {
       sandbox: this.deps.sandbox,
       session,
       telemetry: this.deps.telemetry,
+      progress: (u) =>
+        this.deps.feedback
+          ? this.deps.feedback.progress(u)
+          : this.deps.log(u.current !== undefined && u.total !== undefined ? `${u.message} (${u.current}/${u.total})` : u.message),
+      diagnostic: (d) => this.deps.feedback?.diagnostic(d),
+      // log 是 progress({ message }) 的别名(见 AgentContext.log)。
       log: this.deps.log,
     };
 
@@ -162,9 +227,48 @@ export class SessionManager {
     this.allEvents.push(userEvent);
     session.events.push(userEvent);
     session.pendingInputRequests.length = 0;
-    const turn = this.deps.otel
-      ? await this.sendWithOtel(this.deps.otel, { text, files, responses }, ctx)
-      : await this.deps.agent.send({ text, files, responses }, ctx);
+    const turnIndex = ++session.turnCount;
+    const windowLabel = `s${session.index}/t${turnIndex}`;
+    // send 进入前:workdir 有未记录变化(fixture / setup / runCommand 副作用)先落 eval 归因。
+    await this.deps.ledgerHooks?.beforeSend(windowLabel);
+    let turn: Turn;
+    let sentTraceId: string | undefined;
+    let sentAttribution: "traceparent" | "window" | "none" | undefined;
+    this.deps.onSendActive?.(true);
+    try {
+      if (this.deps.otel) {
+        const r = await this.sendWithOtel(this.deps.otel, { text, files, responses }, ctx);
+        turn = r.turn;
+        sentTraceId = r.traceId;
+        sentAttribution = r.attribution;
+      } else {
+        turn = await this.deps.agent.send({ text, files, responses }, ctx);
+      }
+    } catch (e) {
+      this.deps.onTurn?.({
+        sessionIndex: session.index,
+        turnIndex,
+        startedAt: t0,
+        durationMs: Date.now() - t0,
+        failed: true,
+        traceAttribution: sentAttribution,
+      });
+      throw e;
+    } finally {
+      this.deps.onSendActive?.(false);
+      // send 返回后:这个 send 窗口内的全部 workspace 变化落 agent 归因(HITL waiting 同样收窗:
+      // adapter 义务保证返回时 agent 侧进程已退出或进入不再写 workspace 的静止态)。
+      await this.deps.ledgerHooks?.afterSend(windowLabel).catch(() => {});
+    }
+    this.deps.onTurn?.({
+      sessionIndex: session.index,
+      turnIndex,
+      startedAt: t0,
+      durationMs: Date.now() - t0,
+      failed: turn.status === "failed" ? true : undefined,
+      traceId: sentTraceId,
+      traceAttribution: sentAttribution,
+    });
 
     this.allEvents.push(...turn.events);
     session.events.push(...turn.events);
@@ -177,6 +281,10 @@ export class SessionManager {
       accumulateUsage(this.usage, turn.usage);
       accumulateUsage(session.usage, turn.usage);
     }
+    // 证据覆盖:attempt / session 级聚合取各轮最差值(见 scoring/coverage.ts)。
+    const turnCoverage = this.resolveTurnCoverage(turn);
+    this.coverage = worstCoverage([this.coverage, turnCoverage]);
+    session.coverage = worstCoverage([session.coverage, turnCoverage]);
     session.lastStatus = turn.status;
     this.lastStatus = turn.status;
     const reply = lastAssistantText(turn.events);
@@ -200,7 +308,7 @@ export class SessionManager {
     otel: AgentOtelChannel,
     input: { text: string; files?: readonly InputFile[]; responses?: readonly InputResponse[] },
     ctx: AgentContext,
-  ): Promise<Turn> {
+  ): Promise<{ turn: Turn; traceId: string; attribution: "traceparent" | "window" | "none" }> {
     const r = await otel.runTurn((headers) => {
       const turnCtx: AgentContext = ctx.telemetry
         ? { ...ctx, telemetry: { ...ctx.telemetry, headers } }
@@ -218,7 +326,7 @@ export class SessionManager {
       this.warnedNoSpans = true;
       this.deps.log(t("otel.noSpans"));
     }
-    return r.result;
+    return { turn: r.result, traceId: r.traceId, attribution: r.spans.length === 0 ? "none" : r.attribution };
   }
 }
 
@@ -236,7 +344,7 @@ function failureReason(events: readonly StreamEvent[]): string | undefined {
   return undefined;
 }
 
-/** 单行截断,口径同 src/runner/reporters/table.ts 的 truncateOneLine(折叠空白 + 120 字符上限)。 */
+/** 单行截断:折叠空白 + 120 字符上限。 */
 function truncateOneLine(s: string, width: number): string {
   const clean = s.replace(/\s+/g, " ").trim();
   if (clean.length <= width) return clean;

package/src/context/types.ts

@@ -2,6 +2,7 @@
 // `t` 的形状按 Agent 能力组装(见 docs/architecture.md「能力决定形状」)。
 
 import type { InputRequest, StreamEvent, ToolCall, Usage } from "../o11y/types.ts";
+import type { DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
 import type { AssertionHandle, ValueAssertion } from "../scoring/types.ts";
 import type {
   CommandOptions,
@@ -11,6 +12,9 @@ import type {
   SourceFiles,
 } from "../sandbox/types.ts";
 
+/** `t.send()` / `session.send()` 的入参:字符串,或带附件的结构化消息。 */
+export type SendInput = string | { text: string; files?: readonly import("../agents/types.ts").InputFile[] };
+
 /** t.send() 返回的句柄:从事件流派生便利字段 + expectOk。 */
 export interface TurnHandle {
   /** 本轮的原始事件流(工具调用、消息增量等);下面的派生字段都算自它。 */
@@ -59,8 +63,8 @@ export interface TurnHandle {
   calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
   /** 断言本轮事件按给定类型顺序出现(允许中间夹杂其它事件)。 */
   eventOrder(types: StreamEvent["type"][]): AssertionHandle;
-  /** 用自定义谓词对本轮整段事件流断言;失败时用 label 说明原因。 */
-  eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+  /** 用自定义谓词对本轮整段事件流断言;label 必填、进断言标题(谓词不透明,解释责任在 label)。 */
+  eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
   /** 断言本轮 token 用量不超过 max。 */
   maxTokens(max: number): AssertionHandle;
   /** 断言本轮花费(USD)不超过 usd。 */
@@ -93,7 +97,11 @@ export interface DiffView {
 
 /** 工具匹配小语言。 */
 export interface ToolMatch {
-  /** 只匹配入参包含这些键值的调用(浅层包含,非深度相等)。 */
+  /**
+   * 只匹配入参包含这些键值的调用:**深度部分匹配**——嵌套对象逐键下钻,数组按值比较;
+   * 值可以是 RegExp(对字符串字段测试,不命中时再对整个 input 的序列化串兜底测一次)
+   * 或谓词函数。不要求深度相等,多余的入参键不影响命中。
+   */
   input?: Record<string, unknown>;
   /** 精确匹配调用次数,省略则只要求「至少一次」。 */
   count?: number;
@@ -179,8 +187,8 @@ export interface SandboxHandle {
  * 只看最后一轮要用 `send()` 返回的 TurnHandle。
  */
 export interface SessionHandle {
-  /** 在这个会话里发一条消息,返回该轮的 TurnHandle。 */
-  send(text: string): Promise<TurnHandle>;
+  /** 在这个会话里发一条消息(字符串或结构化消息),返回该轮的 TurnHandle。 */
+  send(input: SendInput): Promise<TurnHandle>;
   /** 在这个会话里发一条带文件的消息,语义同 TestContext.sendFile。 */
   sendFile(path: string, text?: string): Promise<TurnHandle>;
   /** 取这个会话里等待中的 HITL 输入请求;拿不到就抛,语义同 TestContext.requireInputRequest。 */
@@ -223,8 +231,8 @@ export interface SessionHandle {
   calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
   /** 断言这个会话累计事件按给定类型顺序出现。 */
   eventOrder(types: StreamEvent["type"][]): AssertionHandle;
-  /** 用自定义谓词对这个会话累计的整段事件流断言。 */
-  eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+  /** 用自定义谓词对这个会话累计的整段事件流断言;label 必填、进断言标题。 */
+  eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
   /** 断言这个会话累计 token 用量不超过 max。 */
   maxTokens(max: number): AssertionHandle;
   /** 断言这个会话累计花费(USD)不超过 usd。 */
@@ -241,8 +249,8 @@ export interface SessionHandle {
  */
 export interface TestContext {
   // 会话
-  /** 向默认会话发一条消息,返回该轮的 TurnHandle。事件同时累加进默认会话的累计事件流,供下面的作用域断言使用。 */
-  send(text: string): Promise<TurnHandle>;
+  /** 向默认会话发一条消息(字符串或结构化消息),返回该轮的 TurnHandle。事件同时累加进默认会话的累计事件流,供下面的作用域断言使用。 */
+  send(input: SendInput): Promise<TurnHandle>;
   /** 发一条带文件(图片等多模态输入)的消息。`path` 相对项目根;读出后 base64 随 TurnInput.files 交给 adapter。 */
   sendFile(path: string, text?: string): Promise<TurnHandle>;
   /** 取默认会话里等待中的 HITL 输入请求;不传 filter 要求恰好一条,拿不到就抛。 */
@@ -276,7 +284,17 @@ export interface TestContext {
   readonly reasoningEffort?: string;
   /** 本次 attempt 生效的实验 flags(experiment.flags 的只读视图;实验条件,非命令行开关)。 */
   readonly flags: Readonly<Record<string, unknown>>;
-  /** 打一行调试日志;有 live 进度回调时走该回调,否则落到 stderr,不出现在最终结果里。 */
+  /**
+   * 作用域反馈:报告 eval 自己执行的长步骤(上传 fixture、跑构建……)。短命状态,scope 固定
+   * 为 `eval.run`;只报告不断言(见 docs/feature/eval/library/context.md「向运行反馈长步骤」)。
+   */
+  progress(update: ProgressUpdate): void;
+  /**
+   * 作用域反馈:报告运行结束后仍需保留的问题(永久事件,落 attempt diagnostics)。
+   * 即使 level 为 "error" 也不自动改变 verdict——测试结论仍由断言决定。
+   */
+  diagnostic(input: DiagnosticInput): void;
+  /** `progress({ message: msg })` 的别名(调试日志),不出现在最终结果里。 */
   log(msg: string): void;
   /** 立即中止本 eval 并标记为 skipped(verdict / EvalResult.skipReason),reason 不能为空。 */
   skip(reason: string): never;
@@ -330,8 +348,8 @@ export interface TestContext {
   calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
   /** 断言默认会话累计事件按给定类型顺序出现(允许中间夹杂其它事件)。 */
   eventOrder(types: StreamEvent["type"][]): AssertionHandle;
-  /** 用自定义谓词对默认会话累计的整段事件流断言;失败时用 label 说明原因。 */
-  eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+  /** 用自定义谓词对默认会话累计的整段事件流断言;label 必填、进断言标题。 */
+  eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
 
   // 工作区 / 沙箱
   /** 受限沙箱视图:能执行命令 / 读写文件 / 看最终 diff,不能 stop 沙箱本身(见 SandboxHandle)。 */

package/src/define.test.ts

@@ -1,13 +1,18 @@
+// cases: docs/engineering/unit-tests/sandbox/cases.md
 // SandboxSpec 链式钩子(.setup()/.teardown())的构造期契约:不可变、多次追加按顺序累加。
 // 执行顺序(setup 正序 / teardown 逆序 / LIFO cleanup)是 runner 的事,见
 // test/e2e-sandbox-hooks.test.ts;这里只测 dockerSandbox()/vercelSandbox()/e2bSandbox()/
 // defineSandbox() 这四个工厂产出的 spec 对象本身的构造行为。
 import { describe, expect, it } from "vitest";
 import { dockerSandbox, e2bSandbox, vercelSandbox, defineSandbox } from "./define.ts";
-import type { AgentSetup, AgentTeardown } from "./types.ts";
+// 从公开 subpath 取类型，守住下游共享 helper 的正式导入面。
+import type { SandboxHook, SandboxHookContext } from "./sandbox/index.ts";
 
-const noopSetup: AgentSetup = () => {};
-const noopTeardown: AgentTeardown = () => {};
+const noopSetup: SandboxHook = () => {};
+const noopTeardown: SandboxHook = () => {};
+// subpath 类型导出的守护由 typecheck 完成:这两个类型标注编译不过即失败,无需运行时断言。
+const _acceptsPublicHookContext = (_ctx: SandboxHookContext): void => {};
+void _acceptsPublicHookContext;
 
 describe("sandbox factories: .setup()/.teardown() chain", () => {
   it("dockerSandbox() starts with empty hook arrays", () => {
@@ -27,15 +32,15 @@ describe("sandbox factories: .setup()/.teardown() chain", () => {
   });
 
   it("multiple .setup() calls accumulate in append order", () => {
-    const a: AgentSetup = () => {};
-    const b: AgentSetup = () => {};
+    const a: SandboxHook = () => {};
+    const b: SandboxHook = () => {};
     const spec = dockerSandbox().setup(a).setup(b);
     expect(spec.setupHooks).toEqual([a, b]);
   });
 
   it("multiple .teardown() calls accumulate in append order (execution order is the runner's job)", () => {
-    const x: AgentTeardown = () => {};
-    const y: AgentTeardown = () => {};
+    const x: SandboxHook = () => {};
+    const y: SandboxHook = () => {};
     const spec = dockerSandbox().teardown(x).teardown(y);
     expect(spec.teardownHooks).toEqual([x, y]);
   });
@@ -72,7 +77,7 @@ describe("sandbox factories: .setup()/.teardown() chain", () => {
 
   it("each chain call produces an independent object (no shared mutable state)", () => {
     const base = dockerSandbox();
-    const other: AgentSetup = () => {};
+    const other: SandboxHook = () => {};
     const branchA = base.setup(noopSetup);
     const branchB = base.setup(other);
     expect(branchA.setupHooks).toEqual([noopSetup]);

package/src/define.ts

@@ -3,8 +3,6 @@
 
 import type {
   Agent,
-  AgentSetup,
-  AgentTeardown,
   Config,
   CustomSandboxSpec,
   DockerSandboxSpec,
@@ -13,6 +11,7 @@ import type {
   ExperimentDef,
   RemoteAgentDef,
   SandboxAgentDef,
+  SandboxHook,
   SandboxHooks,
   VercelSandboxSpec,
 } from "./types.ts";
@@ -24,6 +23,7 @@ export function defineSandboxAgent(def: SandboxAgentDef): Agent {
   return {
     name: def.name,
     kind: "sandbox",
+    coverage: def.coverage,
     setup: def.setup,
     tracing: def.tracing,
     spanMapper: def.spanMapper,
@@ -38,6 +38,7 @@ export function defineAgent(def: RemoteAgentDef): Agent {
   return {
     name: def.name,
     kind: "remote",
+    coverage: def.coverage,
     setup: def.setup,
     tracing: def.tracing,
     spanMapper: def.spanMapper,
@@ -63,9 +64,26 @@ export function defineExperiment(def: ExperimentDef): ExperimentDef {
     throw new Error(t("define.experimentIdRejected"));
   }
   if (!def.agent) throw new Error(t("define.experimentAgentRequired"));
+  // flags 必须可 JSON 序列化(进结果快照的 ExperimentRunInfo.flags):解析时即校验,
+  // 非 JSON 值(函数 / undefined / 循环引用 / bigint)直接报错,不等到落盘才炸。
+  if (def.flags !== undefined) {
+    for (const [key, value] of Object.entries(def.flags)) {
+      if (!isJsonValue(value)) {
+        throw new Error(t("define.experimentFlagNotJson", { key }));
+      }
+    }
+  }
   return def;
 }
 
+function isJsonValue(v: unknown): boolean {
+  if (v === null || typeof v === "string" || typeof v === "boolean") return true;
+  if (typeof v === "number") return Number.isFinite(v);
+  if (Array.isArray(v)) return v.every(isJsonValue);
+  if (typeof v === "object") return Object.values(v as Record<string, unknown>).every(isJsonValue);
+  return false;
+}
+
 /** 项目级配置。 */
 export function defineConfig(config: Config): Config {
   return config;
@@ -81,8 +99,8 @@ export function defineConfig(config: Config): Config {
 
 /** 链式追加中累积的钩子(setup 按追加顺序执行,teardown 执行时逆序,见 SandboxHooks)。 */
 interface HookState {
-  readonly setupHooks: readonly AgentSetup[];
-  readonly teardownHooks: readonly AgentTeardown[];
+  readonly setupHooks: readonly SandboxHook[];
+  readonly teardownHooks: readonly SandboxHook[];
 }
 
 /** 四个工厂共用:把当前钩子状态包成 `.setup()` / `.teardown()` 方法,调用即用新状态重新 build。 */
@@ -148,6 +166,8 @@ export function defineSandbox(def: {
   name: string;
   create: CustomSandboxSpec["create"];
   recommendedConcurrency?: number;
+  /** 可发布参数的投影(进结果快照);未实现时只落 provider 名。 */
+  publicConfig?: CustomSandboxSpec["publicConfig"];
 }): CustomSandboxSpec {
   if (!def.name) throw new Error(t("define.sandboxNameRequired"));
   if (typeof def.create !== "function") throw new Error(t("define.sandboxCreateRequired"));
@@ -155,6 +175,7 @@ export function defineSandbox(def: {
     provider: def.name,
     create: def.create,
     recommendedConcurrency: def.recommendedConcurrency,
+    publicConfig: def.publicConfig,
     setupHooks: state.setupHooks,
     teardownHooks: state.teardownHooks,
     ...hookMethods(state, build),

package/src/expect/index.ts

@@ -17,24 +17,31 @@ export interface MatchOptions {
 // ───────────────────────── 内部工厂 ─────────────────────────
 
 /**
- * 唯一的内部工厂。gate()/atLeast() 都基于它返回新的不可变实例,
- * 共享同一个 score(只换 severity / threshold)。
+ * 唯一的内部工厂。gate()/atLeast()/optional() 都基于它返回新的不可变实例,
+ * 共享同一个 score(只换 severity / threshold / isOptional)。
+ * `expected` 是期望条件的有界文本描述(如 `contains "Brooklyn"`),失败时进
+ * AssertionResult.expected 供 show/view 展示。
  */
 function createAssertion(
   name: string,
   severity: Severity,
   score: (value: unknown) => number | Promise<number>,
   threshold?: number,
+  opts?: { expected?: string; isOptional?: boolean },
 ): ValueAssertion {
   const self: ValueAssertion = {
     name,
     severity,
     threshold,
+    ...(opts?.isOptional ? { isOptional: true } : {}),
+    ...(opts?.expected !== undefined ? { expected: opts.expected } : {}),
     score,
     // 转成硬门槛(失败即整条 eval 不通过)。
-    gate: (t?: number) => createAssertion(name, "gate", score, t),
+    gate: (t?: number) => createAssertion(name, "gate", score, t, opts),
     // 软阈值:默认不改变 verdict;--strict 下软阈值失败也会使 verdict=failed。
-    atLeast: (t: number) => createAssertion(name, "soft", score, t),
+    atLeast: (t: number) => createAssertion(name, "soft", score, t, opts),
+    // 允许证据缺席:评不了只记 unavailable,不影响判定(与 severity 正交)。
+    optional: () => createAssertion(name, severity, score, threshold, { ...opts, isOptional: true }),
   };
   return Object.freeze(self);
 }
@@ -86,28 +93,44 @@ function toMatchTarget(value: unknown, opts?: MatchOptions): string {
 export function includes(needle: string | RegExp, opts?: MatchOptions): ValueAssertion {
   const label = needle instanceof RegExp ? needle.toString() : safeLabel(needle);
   const suffix = opts?.stripComments ? ", stripComments" : "";
-  return createAssertion(`includes(${label}${suffix})`, "gate", (value) => {
-    const s = toMatchTarget(value, opts);
-    if (needle instanceof RegExp) return needle.test(s) ? 1 : 0;
-    return s.includes(needle) ? 1 : 0;
-  });
+  return createAssertion(
+    `includes(${label}${suffix})`,
+    "gate",
+    (value) => {
+      const s = toMatchTarget(value, opts);
+      if (needle instanceof RegExp) return needle.test(s) ? 1 : 0;
+      return s.includes(needle) ? 1 : 0;
+    },
+    undefined,
+    { expected: needle instanceof RegExp ? `matches ${label}` : `contains ${label}` },
+  );
 }
 
 /** includes 的取反:不含子串 / 不命中正则则 1,否则 0。默认硬门槛。opts.stripComments 时只看真实代码。 */
 export function excludes(needle: string | RegExp, opts?: MatchOptions): ValueAssertion {
   const label = needle instanceof RegExp ? needle.toString() : safeLabel(needle);
   const suffix = opts?.stripComments ? ", stripComments" : "";
-  return createAssertion(`excludes(${label}${suffix})`, "gate", (value) => {
-    const s = toMatchTarget(value, opts);
-    if (needle instanceof RegExp) return needle.test(s) ? 0 : 1;
-    return s.includes(needle) ? 0 : 1;
-  });
+  return createAssertion(
+    `excludes(${label}${suffix})`,
+    "gate",
+    (value) => {
+      const s = toMatchTarget(value, opts);
+      if (needle instanceof RegExp) return needle.test(s) ? 0 : 1;
+      return s.includes(needle) ? 0 : 1;
+    },
+    undefined,
+    { expected: needle instanceof RegExp ? `does not match ${label}` : `does not contain ${label}` },
+  );
 }
 
 /** 深相等则 1,否则 0。默认硬门槛。 */
 export function equals(expected: unknown): ValueAssertion {
-  return createAssertion(`equals(${safeLabel(expected)})`, "gate", (value) =>
-    deepEqual(value, expected) ? 1 : 0,
+  return createAssertion(
+    `equals(${safeLabel(expected)})`,
+    "gate",
+    (value) => (deepEqual(value, expected) ? 1 : 0),
+    undefined,
+    { expected: safeLabel(expected) },
   );
 }
 
@@ -138,6 +161,7 @@ export function similarity(expected: string): ValueAssertion {
       return 1 - levenshtein(a, b) / maxLen;
     },
     0.6,
+    { expected: safeLabel(expected) },
   );
 }
 
@@ -150,27 +174,33 @@ export function satisfies(predicate: (v: unknown) => boolean, label?: string): V
 /** value 非 null / 非 undefined 则 1,否则 0。省掉 `x !== undefined` + isTrue 的样板。默认硬门槛。 */
 export function isDefined(label?: string): ValueAssertion {
   const name = label ? `isDefined(${label})` : "isDefined()";
-  return createAssertion(name, "gate", (value) => (value != null ? 1 : 0));
+  return createAssertion(name, "gate", (value) => (value != null ? 1 : 0), undefined, { expected: "defined" });
 }
 
 /** value === true 则 1,否则 0。带 label 的布尔断言(fileExists 等检查用)。默认硬门槛。 */
 export function isTrue(label?: string): ValueAssertion {
   const name = label ? `isTrue(${label})` : "isTrue()";
-  return createAssertion(name, "gate", (value) => (value === true ? 1 : 0));
+  return createAssertion(name, "gate", (value) => (value === true ? 1 : 0), undefined, { expected: "true" });
 }
 
 /** CommandResult.exitCode === 0 则 1,否则 0。默认硬门槛。 */
 export function commandSucceeded(): ValueAssertion {
-  return createAssertion("commandSucceeded()", "gate", (value) => {
-    if (value === null || typeof value !== "object") return 0;
-    return (value as { exitCode?: unknown }).exitCode === 0 ? 1 : 0;
-  });
+  return createAssertion(
+    "commandSucceeded()",
+    "gate",
+    (value) => {
+      if (value === null || typeof value !== "object") return 0;
+      return (value as { exitCode?: unknown }).exitCode === 0 ? 1 : 0;
+    },
+    undefined,
+    { expected: "exit 0" },
+  );
 }
 
 /** value === false 则 1,否则 0。带 label 的布尔断言。默认硬门槛。 */
 export function isFalse(label?: string): ValueAssertion {
   const name = label ? `isFalse(${label})` : "isFalse()";
-  return createAssertion(name, "gate", (value) => (value === false ? 1 : 0));
+  return createAssertion(name, "gate", (value) => (value === false ? 1 : 0), undefined, { expected: "false" });
 }
 
 /**