niceeval 0.12.1 → 0.12.2-canary.31

package/docs-site/zh/reference/events.mdx

@@ -4,20 +4,20 @@ sidebarTitle: "事件流"
 description: "StreamEvent 的十种事件：每种的字段、什么时候吐、哪些断言消费它。adapter 的核心工作就是产出这条流。"
 ---
 
-adapter 的 `send` 返回一个 `Turn`，其中 `events: StreamEvent[]` 是**断言的唯一数据源**：`t.calledTool()`、`t.reply`、`toolOrder`、`noFailedActions`……全部从这条流上读。把你的 agent"这一轮做了什么"翻成这条流，整套断言就都能用。
+adapter 的 `send` 返回一个 `Turn`，其中 `events: StreamEvent[]` 是事件断言的事实来源。`turn.calledTool(...)`、`turn.toolOrder(...)`、`turn.event(...)` 与 `turn.succeeded()` 都从本轮的标准事件和逻辑工具 occurrence 派生，调用时直接登记 Boolean Assertion。把你的 agent“这一轮做了什么”如实翻成这条流，整套事件断言就都能用。
 
 ## Turn：send 的返回值
 
 ```ts
 interface Turn {
   events: StreamEvent[];                          // 本轮事件,按真实发生顺序
-  data?: JsonValue;                               // 结构化输出 → outputEquals / outputMatches
+  data?: JsonValue;                               // 结构化输出，可交给 t.check(...)
   status: "completed" | "failed" | "waiting";     // waiting = 停下等人(HITL)
   usage?: Usage;                                  // → maxTokens / maxCost / 成本报表,完整字段见下方
 }
 ```
 
-`data` 的语义是"本轮的结构化产物"：**应用的回答本身是结构化对象**（抽取、分类、表单填充）时才填，`outputEquals` / `outputMatches` 读它。只回文本的应用不填——不要把原始响应 body 或 `message` 文本复制进去凑数，也不要反过来把结构化输出序列化塞进 `events`。`usage` 拿得到就带，拿不到就不填——**别编数字**。
+`data` 的语义是“本轮的结构化产物”：**应用的回答本身是结构化对象**（抽取、分类、表单填充）时才填，评估作者可以用 `t.check(turn.data, ...)` 比较它。只回文本的应用不填——不要把原始响应 body 或 `message` 文本复制进去凑数，也不要反过来把结构化输出序列化后写进 `events`。`usage` 拿得到就带，拿不到就不填——**别编数字**。
 
 `usage` 的完整字段（`Usage` 类型）：
 
@@ -113,7 +113,17 @@ token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表
   type: "operation.started";
   operationId: string;
   operation:
-    | { kind: "tool"; name: string; input: JsonValue; tool?: ToolName }
+    | {
+        kind: "tool";
+        name: string;
+        input: JsonValue;
+        tool?: ToolName;
+        /**
+         * Adapter 对 command / not-command 的协议级分类。暂时可选以兼容尚未迁移的
+         * 第三方 Adapter；缺失不得在 core 侧由 name、input 或 shell text 补造。
+         */
+        command?: CommandProjection;
+      }
     | { kind: "subagent"; name: string; remoteUrl?: string };
 }
 ```
@@ -184,17 +194,17 @@ token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表
 
 | 事件 | 说什么 | 消费它的断言 / API |
 |---|---|---|
-| `message` | agent（或用户）说了一段话 | `t.reply`、`messageIncludes`、judge 的材料 |
-| `operation.started`（`kind: "tool"`） | 发起一次工具调用 | `calledTool`、`toolOrder`、`maxToolCalls`、`notCalledTool` |
-| `operation.finished`（`kind: "tool"`） | 该次工具调用的结果 | `calledTool` 的 `status` 匹配、`noFailedActions` |
-| `operation.started`（`kind: "subagent"`） | 委派一个子 agent | `calledSubagent` |
-| `operation.finished`（`kind: "subagent"`） | 子 agent 返回 | `calledSubagent` 的 `status`、`noFailedActions` |
-| `input.requested` | 停下来等人输入（HITL） | `t.parked()`、`t.requireInputRequest()` |
-| `thinking` | 思考文本 | `event("thinking")`、view 展示 |
-| `compaction` | 上下文被压缩 | `event("compaction")`（adapter 的 parser 吐出这条事件即可断言,不需要任何声明） |
-| `error` | 本轮出错 | `event("error")`、view 展示 |
-
-任何事件都能被通用断言消费：`event(type)` / `notEvent(type)` / `eventOrder(types)` / `eventsSatisfy(label, predicate)`。
+| `message` | agent（或用户）说了一段话 | `turn.message`、`turn.event(eventMatch("message", ...))`、Judge 的材料 |
+| `operation.started`（`kind: "tool"`） | 发起一次工具调用 | `turn.calledTool(...)`、`turn.toolOrder(...)`、`turn.event(...)` |
+| `operation.finished`（`kind: "tool"`） | 该次工具调用的结果 | 带状态条件的 `ToolMatch` |
+| `operation.started`（`kind: "subagent"`） | 委派一个子 agent | `turn.event(eventMatch("operation.started", ...))` |
+| `operation.finished`（`kind: "subagent"`） | 子 agent 返回 | `turn.event(eventMatch("operation.finished", ...))` |
+| `input.requested` | 停下来等人输入（HITL） | `t.requireInputRequest()`、`turn.event(...)` |
+| `thinking` | 思考文本 | `turn.event(eventMatch("thinking", ...))`、view 展示 |
+| `compaction` | 上下文被压缩 | `turn.event(eventMatch("compaction"))` |
+| `error` | 本轮出错 | `turn.event(eventMatch("error", ...))`、view 展示 |
+
+事件断言共用三个入口：`event(match)`、`notEvent(match)` 与 `eventOrder(matches)`；它们都接收 `eventMatch(...)`，不另造 selector object 或匿名事件 predicate。
 
 ## 逐事件说明
 
@@ -210,14 +220,53 @@ token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表
 
 ```ts
 { type: "operation.started", operationId: string,
-  operation: { kind: "tool", name: string, input: JsonValue, tool?: ToolName } }
+  operation: { kind: "tool", name: string, input: JsonValue,
+    tool?: ToolName, command?: CommandProjection } }
 { type: "operation.finished", operationId: string, kind: "tool",
   output?: JsonValue, status: "completed" | "failed" | "rejected" }
 ```
 
 - 每个 tool `operation.started` 配一个**同 `operationId`** 的 tool `operation.finished`——并发调用靠它不错配。你的 agent 返回里有显式 id（AI SDK 的 `toolCallId`、Anthropic 的 `tool_use.id`）就直接用；实在没有再按顺序合成。
-- `status` 如实填：工具执行失败是 `"failed"`（`noFailedActions()` 会响）；**人否决是 `"rejected"`**（`noFailedActions()` 依然通过，`calledTool(..., { status: "rejected" })` 可精确断言）。两回事，别混。
+- `status` 如实填：工具执行失败是 `"failed"`；**人否决是 `"rejected"`**。评估作者用 `ToolMatch` 的状态条件精确区分，两回事不要混。
 - `name` 用工具的原始名字。
+- 只有 started 时，逻辑 occurrence 的状态是 `pending`，输出为 unavailable。finished 省略 `output` 也表示 unavailable，不能把缺失写成空 JSON 或普通不匹配。
+
+#### 将工具事件交给 `ToolMatch`
+
+同一个 `shell` 工具可以先后运行 `git status` 和 `pnpm test`。名称只能说明工具类别；需要辨认命令时，评估作者使用已归一的 command projection：
+
+```ts
+import { commandMatch } from "niceeval/expect";
+
+turn.calledTool(commandMatch("pnpm", { argsStart: ["test"] }));
+```
+
+`ToolMatch` 每次比较一条逻辑 occurrence。完整 selector、JSON、路径、输出与计数规则见 [Scoped assertions](https://github.com/NiceEval/NiceEval/blob/main/docs/feature/assertions/library/scoped-assertions.md)。
+
+原生协议直接给出单一 invocation 的 structured argv 时，从 `niceeval/adapter` 调用公开构造器：
+
+```ts
+import { commandProjection } from "niceeval/adapter";
+
+events.push({
+  type: "operation.started",
+  operationId: call.id,
+  operation: {
+    kind: "tool",
+    name: call.name,
+    input: call.input,
+    command: commandProjection({
+      state: "available",
+      executable: call.executable,
+      args: call.args,
+    }),
+  },
+});
+```
+
+`commandProjection()` 保留 Adapter 已确认的 original tokens，并调用同一份 `normalizeLogicalCommand()` 生成 `logical-command/v1` 投影。`pnpm exec niceeval show` 和 `npx niceeval show` 因此都能由 `commandMatch("niceeval", { argsStart: ["show"] })` 精确匹配。
+
+只有原生协议已经给出 argv，或协议 grammar 能无歧义地产生单一 invocation，才能把 original 标为 available。协议只给 shell source、内容已截断或脱敏时使用 `opaqueCommandProjection(reason)`；能确认不是 command 时使用 `notCommandProjection()`。无法确认 command / not-command 时降低 actions coverage，不能从 tool name、input 或 shell 文本猜测。
 
 ### 子 agent `operation.started` / `operation.finished` —— 委派了谁
 
@@ -228,7 +277,7 @@ token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表
   output?: JsonValue, status: "completed" | "failed" }
 ```
 
-被测系统把任务委派给子 agent（等它返回）时吐这一对，`operationId` 配对规则同上。喂 `calledSubagent("researcher")` 这类断言。
+被测系统把任务委派给子 agent（等它返回）时吐这一对，`operationId` 配对规则同上。评估作者用 `eventMatch("operation.started", ...)` / `eventMatch("operation.finished", ...)` 比较对应事件。
 
 ### `input.requested` —— 停下等人（HITL）
 
@@ -256,9 +305,9 @@ agent 停轮等人时，每个待回答的问题吐一条，同时该 Turn 的 `
 
 ## 映射的三条纪律
 
-1. **时序即事实**：事件按真实发生顺序排。`toolOrder` / `eventOrder` 靠子序匹配，顺序错了断言就失真。
-2. **`operationId` 配对**：每个 started operation 都要有同 `kind`、同 id 的 finished operation，缺一半会让 `calledTool(..., { status })` 匹配不上。
-3. **完整性没有声明层，由来源证明**：用官方转换器（`createClaudeSdkEventStream`、`turnFromAiSdk` 等）时，返回值本身保证**所有**工具调用都在流里；手工映射时完整与否完全取决于你的映射代码写没写全。只吐一部分时，`notCalledTool` / `maxToolCalls` 这类负断言会静默通过——没有报错，比失败更难发现。手工映射前确认自己的代码覆盖了全部工具调用，见[能力位参考](/zh/reference/capabilities)。
+1. **时序即事实**：事件按真实发生顺序排。`toolOrder` / `eventOrder` 用单调 cursor 匹配不同 occurrence 的子序列，顺序错了断言就失真。
+2. **`operationId` 配对**：每个 started operation 都要有同 `kind`、同 id 的 finished operation。只有配对完成，框架才能把状态与 input 归到同一个逻辑工具 occurrence。
+3. **完整性必须显式**：官方转换器按实际 adapter 能力声明 evidence coverage。负向断言在相关输入或 action coverage 不完整时是 `unavailable`，不会把“没观察到”冒充“没有发生”。手工映射同样要如实声明覆盖范围，见[能力位参考](/zh/reference/capabilities)。
 
 ## 一个完整的映射示例
 

package/docs-site/zh/reference/expect.mdx

@@ -1,27 +1,28 @@
 ---
-title: "niceeval/expect matchers 与自定义断言参考"
+title: "niceeval/expect Match 参考"
 sidebarTitle: "断言 Matchers"
-description: "niceeval/expect 参考：includes、equals、matches、similarity、satisfies，以及形状断言 includesUrl、hasSections。可链式调用 .gate() 或 .atLeast(0.7)，也可以用 makeAssertion 构建自定义 matcher。"
+description: "niceeval/expect 的纯 Match factory：组合文字、结构、条件，再交给 t.check 登记 Assertion。"
 ---
 
-`niceeval/expect` 提供一组可组合 matcher，传给 `t.check()` 或 `t.require()`。matcher 会返回一个 `Assertion`，并带有默认严重性：`gate` 或 `soft`。
+`niceeval/expect` 只提供纯 Match factory。Match 比较一个候选值，不记录结果，也不决定判定或分数。`t.check(value, match)` 在调用时读取 `value` 并直接登记 Assertion；返回的 handle 只配置同一条 entry。
 
 ```ts
-import { includes, equals, matches, similarity, satisfies } from "niceeval/expect";
+import { and, excludes, includes, pattern } from "niceeval/expect";
 ```
 
 ## 使用方式
 
 ```ts
 t.check(t.reply, includes("confirmed"));
-t.check(turn.data, equals({ intent: "refund" }));
-t.require(turn.status, equals("completed"));
+t.check(t.reply, and(pattern(/order #\d+/i), excludes("cancelled")));
+const config = await t.check(rawConfig, pattern(/runtime/)).orStop();
 ```
 
-| 方法 | 失败时 | 适合 |
-|---|---|---|
-| `t.check` | 记录结果，继续执行 | 大多数断言 |
-| `t.require` | 立即抛出，中断 test | 后续执行没有意义的前置条件 |
+| 入口 | 作用 |
+|---|---|
+| `t.check(value, match)` | 严格两个参数，调用时登记 Assertion；失败不中止后续代码 |
+| `await handle.orStop()` | 同一 handle 的 async barrier；mismatch 或 below 时停止当前 continuation |
+| `handle.score(n)` / `t.score(n)` | 在计分制评估中让该项贡献分数，或直接登记 contribution |
 
 ## Matchers
 
@@ -31,241 +32,271 @@ t.require(turn.status, equals("completed"));
 
 {/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
 
-#### `includes`
+#### `and`
 
 ```ts
-export function includes(needle: string | RegExp, opts?: MatchOptions): ValueAssertion { ... }
+export function and(
+  first: BooleanMatch<unknown, unknown, MatchDomain>,
+  ...rest: readonly BooleanMatch<unknown, unknown, MatchDomain>[]
+): BooleanMatch<unknown, unknown, MatchDomain> { ... }
 ```
 
-String(value) 含子串 / 命中正则则 1,否则 0。默认硬门槛。opts.stripComments 时只看真实代码。
-
-#### `excludes`
+#### `or`
 
 ```ts
-export function excludes(needle: string | RegExp, opts?: MatchOptions): ValueAssertion { ... }
+export function or(
+  first: BooleanMatch<unknown, unknown, MatchDomain>,
+  ...rest: readonly BooleanMatch<unknown, unknown, MatchDomain>[]
+): BooleanMatch<unknown, unknown, MatchDomain> { ... }
 ```
 
-includes 的取反:不含子串 / 不命中正则则 1,否则 0。默认硬门槛。opts.stripComments 时只看真实代码。
-
-#### `equals`
+#### `not`
 
 ```ts
-export function equals(expected: unknown): ValueAssertion { ... }
+export function not<T>(match: BooleanMatch<T, T, "value">): BooleanMatch<T, T, "value"> { ... }
 ```
 
-深相等则 1,否则 0。默认硬门槛。
+#### `includes`
 
-#### `matches`
+```ts
+export function includes(text: string, options?: TextMatchOptions): BooleanMatch<string, string> { ... }
+```
+
+#### `excludes`
 
 ```ts
-export function matches(schema: unknown): ValueAssertion { ... }
+export function excludes(text: string, options?: TextMatchOptions): BooleanMatch<string, string> { ... }
 ```
 
-用 schema 校验 value——不是正则匹配,是 Standard Schema / zod 风格的结构校验。
-优先 Standard Schema(schema['~standard'].validate),否则退化到 zod 风格的
-.safeParse / .parse。校验通过 1,否则 0;任何异常 → 0。默认硬门槛。
+#### `pattern`
+
+```ts
+export function pattern(expression: RegExp, options?: TextMatchOptions): BooleanMatch<string, string> { ... }
+```
 
 #### `similarity`
 
 ```ts
-export function similarity(expected: string): ValueAssertion { ... }
+export function similarity(expected: string): ScoreMatch<string> { ... }
 ```
 
-纯字符串编辑距离,不是语义相似度——归一化 Levenshtein 距离 [0,1](1 - 编辑距离 / 较长串长度),
-不理解含义,同义改写 / 语序调整会被判低分。默认软分,阈值 0.6。
+归一化 Levenshtein similarity；它是连续分数，不携带默认阈值或 verdict 策略。
 
 #### `includesUrl`
 
 ```ts
-export function includesUrl(min = 1): ValueAssertion { ... }
+export function includesUrl(min = 1): BooleanMatch<string, string> { ... }
 ```
 
-文本含至少 min 条(默认 1)去重后的 http(s) 链接则 1,否则 0。默认硬门槛。
-「回答有没有引用真实来源」的形状断言:没有 Judge key 时,它是「至少引用一条来源链接」
-的最低成本兜底——被测方复读题目糊弄不过去,编造的链接则留给负例或 Judge 去抓。
+至少含 min 个去重 http(s) URL 的纯文本 matcher。
 
 #### `hasSections`
 
 ```ts
-export function hasSections(min = 2): ValueAssertion { ... }
+export function hasSections(min = 2): BooleanMatch<string, string> { ... }
 ```
 
-文本含至少 min 个(默认 2)Markdown 标题(行首 # 到 ######)则 1,否则 0。默认硬门槛。
-「回答是不是一份有结构的文档」的形状断言,适合研究报告、方案文档这类产出型回答——
-一段没有任何小标题的流水文本过不了。
+至少含 min 个 Markdown heading 的纯文本 matcher。
 
-#### `satisfies`
+#### `isDefined`
 
 ```ts
-export function satisfies(predicate: (v: unknown) => boolean, label?: string): ValueAssertion { ... }
+export function isDefined<T = unknown>(label?: string): BooleanMatch<T, Exclude<T, null | undefined>> { ... }
 ```
 
-谓词为真则 1,否则 0。默认硬门槛;name 带上 label 便于报告辨认。
-
-#### `isDefined`
+#### `isTrue`
 
 ```ts
-export function isDefined(label?: string): ValueAssertion { ... }
+export function isTrue<T = unknown>(label?: string): BooleanMatch<T, T & true> { ... }
 ```
 
-value 非 null / 非 undefined 则 1,否则 0。省掉 `x !== undefined` + isTrue 的样板。默认硬门槛。
+value === true 的 refinement matcher。
 
-#### `isTrue`
+#### `isFalse`
 
 ```ts
-export function isTrue(label?: string): ValueAssertion { ... }
+export function isFalse<T = unknown>(label?: string): BooleanMatch<T, T & false> { ... }
 ```
 
-value === true 则 1,否则 0。带 label 的布尔断言(fileExists 等检查用)。默认硬门槛。
+value === false 的 refinement matcher。
 
 #### `commandSucceeded`
 
 ```ts
-export function commandSucceeded(): ValueAssertion { ... }
+export function commandSucceeded<T = unknown>(): BooleanMatch<T, T & { readonly exitCode: 0 }> { ... }
 ```
 
-CommandResult.exitCode === 0 则 1,否则 0。默认硬门槛。
+CommandResult-like candidate 的 exitCode === 0 matcher；不读取 stdout / stderr。
 
-#### `isFalse`
+#### `equals`
 
 ```ts
-export function isFalse(label?: string): ValueAssertion { ... }
+export function equals<const T>(expected: T): BooleanMatch<unknown, T> { ... }
 ```
 
-value === false 则 1,否则 0。带 label 的布尔断言。默认硬门槛。
-
-#### `makeAssertion`
+#### `matches`
 
 ```ts
-export function makeAssertion(spec: {
-  name: string;
-  severity?: Severity;
-  threshold?: number;
-  score: (value: unknown) => number | Promise<number>;
-}): ValueAssertion { ... }
+export function matches<S extends StandardSchema>(
+  schema: S,
+): BooleanMatch<unknown, StandardSchema.InferInput<S>, "value"> { ... }
 ```
 
-自定义断言工厂:直接给名字 / 严重度 / 阈值 / score,一次调用即返回可用的 ValueAssertion——
-不像 gate()/atLeast() 那样需要二段链式调用来定级。severity 省略默认 gate。
+#### `satisfies`
 
-{/* GENERATED:END expect-matchers */}
+```ts
+export function satisfies<T, R extends T = T>(
+  label: string,
+  predicate: (value: T) => boolean | Promise<boolean>,
+): BooleanMatch<T, R> | BooleanMatch<T, T> { ... }
+```
 
-### 常见用法示例
+#### `defineValueMatch`
 
 ```ts
-t.check(t.reply, includes("Paris"));
-t.check(t.reply, includes(/order #\d+/i));
-t.check(turn.data, equals({ intent: "refund" }));
-t.check(turn.data, matches(OrderSchema)); // Standard Schema / Zod 结构校验;正则匹配用 includes
-t.check(t.reply, similarity("The answer explains the refund window").atLeast(0.8));
-t.check(turn.data, satisfies((value) => Array.isArray(value)));
+export function defineValueMatch<T, R extends T = T>(spec: {
+  readonly name: string;
+  readonly evaluate: (value: T) => boolean | Promise<boolean>;
+}): BooleanMatch<T, R> | BooleanMatch<T, T> { ... }
 ```
 
-## gate 和 soft
+#### `defineScoreMatch`
 
 ```ts
-t.check(t.reply, includes("required").gate());
-t.check(t.reply, includes("nice to have").atLeast(0.7));
+export function defineScoreMatch<T>(spec: {
+  readonly name: string;
+  readonly score: (value: T) => number | Promise<number>;
+}): ScoreMatch<T> { ... }
 ```
 
-每个 matcher 返回的 `Assertion`（即 `ValueAssertion`）都带有这些成员；`.gate()` 把它变成硬门槛，`.atLeast()` 变成软阈值：
+#### `eventMatch`
 
-{/* GENERATED:BEGIN value-assertion */}
+```ts
+export function eventMatch<K extends keyof EventOptionsByType>(
+  type: K,
+  options?: EventOptionsByType[K],
+): EventMatch<Extract<AssertionEvent, { readonly type: K }>> { ... }
+```
 
-{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+{/* GENERATED:END expect-matchers */}
 
-#### `name`
+### 匹配工具调用
+
+`ToolMatch` 比较一条 `LogicalToolOccurrence`。`calledTool` 接收 `ToolMatch`，或只按名称选择的薄糖；第二参数只表达次数。`notCalledTool` 使用相同 selector 表达零匹配。
 
 ```ts
-readonly name: string;
+import {
+  commandMatch,
+  jsonMatch,
+  referencesAnyPath,
+  toolMatch,
+} from "niceeval/expect";
+
+turn.calledTool(
+  toolMatch("get_weather", {
+    input: jsonMatch({ city: "Taipei", unit: "celsius" }),
+    status: "completed",
+  }),
+  { count: 1 },
+).label("精确查询天气");
+
+turn.calledTool(
+  toolMatch("read_file", {
+    input: referencesAnyPath([".env", "secrets/**"]),
+  }),
+).label("读取受限路径");
+
+turn.notCalledTool(commandMatch("rm", { argsStart: ["-rf"] }));
 ```
 
-#### `severity`
+普通 JSON 用 `jsonMatch`，路径用 `referencesAnyPath`，命令 token 用 `commandMatch`。输出不存在、材料不完整或 HITL 尚未完成时，Match 会成为 unavailable，不会伪装成普通不匹配。
 
-```ts
-readonly severity: Severity;
-```
+完整签名、材料状态与三值计数规则见 [Scoped assertions](https://github.com/NiceEval/NiceEval/blob/main/docs/feature/assertions/library/scoped-assertions.md)。
 
-#### `threshold`
+### 常见用法示例
 
 ```ts
-readonly threshold?: number;
+t.check(t.reply, includes("Paris"));
+t.check(t.reply, pattern(/order #\d+/i));
+t.check(turn.data, equals({ intent: "refund" }));
+t.check(turn.data, matches(OrderSchema));
+t.check(turn.data, satisfies("返回数组", Array.isArray));
+t.check(t.reply, similarity("The answer explains the refund window")).atLeast(0.8);
 ```
 
-#### `isOptional`
+## 组合与三态
 
 ```ts
-readonly isOptional?: boolean;
+t.check(t.reply, and(includes("required"), excludes("forbidden")));
+t.check(t.reply, or(includes("approved"), includes("accepted")));
 ```
 
-`.optional()` 链过的标记:评不了只记 unavailable,不把 attempt 拖成 errored。
+同一 `and` / `or` 里的 Match 必须属于同一 domain。布尔 Match 的内部结果是 `matched`、`mismatched` 或 `unavailable`：`or` 只有在没有子项命中且至少一项证据不完整时才返回 `unavailable`，不会把未知当成否定。Match 自身不持有判定、计分或控制流；`.atLeast(n)`、`.score(n)` 与 `.orStop()` 属于登记后的 AssertionHandle。
 
-#### `expected`
+下面列出 Match 值本身的稳定字段。品牌和 evaluator 是模块私有实现，不属于作者 API。
 
-```ts
-readonly expected?: string;
-```
+{/* GENERATED:BEGIN value-assertion */}
 
-期望条件的有界文本描述(如 `contains "Brooklyn"`),失败时进 AssertionResult.expected。
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
+### `Match`
 
-#### `score`
+#### `domain`
 
 ```ts
-score(value: unknown): number | Promise<number>;
+readonly domain: D;
 ```
 
-#### `gate`
+#### `name`
 
 ```ts
-gate(threshold?: number): ValueAssertion;
+readonly name: string;
 ```
 
-转成硬门槛断言:未达阈值(省略 threshold 则按 score &gt;= 1,即满分判定)整条评估用例判为 failed。返回新实例,不改原对象。
+### `BooleanMatch`
 
-#### `atLeast`
+#### `kind`
 
 ```ts
-atLeast(threshold: number): ValueAssertion;
+readonly kind: "boolean";
 ```
 
-转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条评估用例的 verdict;
-`--strict` 运行下,软阈值失败也会把整条评估用例的 verdict 计为 failed。返回新实例,不改原对象。
-
-#### `soft`
+#### `[matchRefinementBrand]`
 
 ```ts
-soft(): ValueAssertion;
+readonly [matchRefinementBrand]: () => R;
 ```
 
-转成纯记录的软断言:不设通过线,分数照实落盘、永不使该条 failed(judge 的默认严重度就是它)。
-无参数——要设线用 `.atLeast(threshold)`,不提供同义的 `soft(threshold)`。返回新实例,不改原对象。
+### `ScoreMatch`
 
-#### `optional`
+#### `kind`
 
 ```ts
-optional(): ValueAssertion;
+readonly kind: "score";
 ```
 
-允许这条断言证据缺席:评不了时只记录 `outcome: "unavailable"`,不影响判定。
-与 severity 正交(severity 说影不影响质量判定,optional 说证据允不允许缺席)。返回新实例,不改原对象。
+#### `atLeast`
+
+```ts
+atLeast(threshold: number): ThresholdedScoreMatch<T>;
+```
 
 {/* GENERATED:END value-assertion */}
 
 ## 自定义 matcher
 
 ```ts
-import { makeAssertion, type Assertion } from "niceeval/expect";
+import { defineValueMatch } from "niceeval/expect";
 
-function validEmail(): Assertion {
-  return makeAssertion({
+const validEmail = () =>
+  defineValueMatch<string>({
     name: "valid email",
-    score(value) {
-      return typeof value === "string" && value.includes("@") ? 1 : 0;
+    evaluate(value) {
+      return value.includes("@");
     },
   });
-}
 
 t.check(t.reply, validEmail());
 ```
 
-`makeAssertion` 接受单个 spec 对象（`name`、可选 `severity`/`threshold`、`score`），直接返回一个 `Assertion`；按惯例用一个同名函数包一层再调用，而不是把 `makeAssertion` 本身当工厂调用。
+布尔自定义 Match 用 `defineValueMatch`，连续分数用 `defineScoreMatch`。两者只实现单候选比较；读取文件、扫描事件、决定 coverage 或修改判定仍由 Assertion 登记入口与 Runner 负责。