## Purpose

定义共享 expect 断言规则系统的核心概念和基础设施：ValueMatcher 统一匹配器、ContentExpectations 内容断言数组、KeyedExpectations 键控断言数组、以及相关的启动期校验和失败路径规范。

## Requirements

### Requirement: ValueMatcher 统一匹配器
系统 SHALL 提供共享 `ValueMatcher` 作为所有非状态类 value expectation 的基础匹配结构。`ValueMatcher` SHALL 支持 `equals`、`contains`、`regex`、`exists`、`empty`、`gt`、`gte`、`lt` 和 `lte` 字段。`equals` MUST 支持任意 JSON value，并使用深度相等比较。`contains` 和 `regex` SHALL 将实际值转换为字符串后匹配。`gt`、`gte`、`lt` 和 `lte` SHALL 将实际值转换为有限数字后比较，无法转换为有限数字时 SHALL 判定不匹配。一个 `ValueMatcher` 对象包含多个 matcher 字段时，系统 SHALL 要求全部 matcher 均通过。

所有类型为 `RawValueExpectation` 的 expect 字段 SHALL 同时接受 primitive 原始值（string / number / boolean / null）作为简写形式。原始值简写 SHALL 等价于 `{ equals: value }`。系统 SHALL 在 resolve 阶段将 primitive 原始值归一化为 `{ equals: value }` 对象形式，运行期逻辑 SHALL 仅处理 `ValueMatcher` 对象形式。数组和对象 MUST NOT 作为原始值简写；需要对数组或对象执行 equals 匹配时，配置 MUST 显式写成 `{ equals: value }`。

#### Scenario: equals 匹配对象
- **WHEN** 实际值为 `{status: "ok", count: 1}` 且 matcher 为 `{equals: {status: "ok", count: 1}}`
- **THEN** 系统 SHALL 使用深度相等判定该 matcher 通过

#### Scenario: contains 字符串化匹配
- **WHEN** 实际值为 `"service ready"` 且 matcher 为 `{contains: "ready"}`
- **THEN** 系统 SHALL 判定该 matcher 通过

#### Scenario: 数字范围组合匹配
- **WHEN** 实际值为 `50` 且 matcher 为 `{gte: 0, lte: 100}`
- **THEN** 系统 SHALL 判定该 matcher 通过

#### Scenario: 多 matcher 快速失败
- **WHEN** 实际值为 `"healthy"` 且 matcher 为 `{contains: "health", regex: "^ready$"}`
- **THEN** 系统 SHALL 在任一 matcher 不满足时判定该 matcher 对象不通过

#### Scenario: 字符串原始值简写等价 equals
- **WHEN** expect 字段配置为 `finishReason: "stop"` 且实际值为 `"stop"`
- **THEN** 系统 SHALL 在 resolve 阶段将 `"stop"` 归一化为 `{equals: "stop"}` 并判定通过

#### Scenario: 数字原始值简写等价 equals
- **WHEN** expect 字段配置为 `rowCount: 1` 且实际值为 `1`
- **THEN** 系统 SHALL 在 resolve 阶段将 `1` 归一化为 `{equals: 1}` 并判定通过

#### Scenario: 布尔原始值简写等价 equals
- **WHEN** expect 字段配置为 RawValueExpectation 类型且值为 `true`，实际值为 `true`
- **THEN** 系统 SHALL 在 resolve 阶段将 `true` 归一化为 `{equals: true}` 并判定通过

#### Scenario: null 原始值简写等价 equals
- **WHEN** expect 字段配置为 RawValueExpectation 类型且值为 `null`，实际值为 `null`
- **THEN** 系统 SHALL 在 resolve 阶段将 `null` 归一化为 `{equals: null}` 并判定通过

#### Scenario: 原始值简写不匹配
- **WHEN** expect 字段配置为 `finishReason: "stop"` 且实际值为 `"error"`
- **THEN** 系统 SHALL 判定不通过并生成 mismatch failure

### Requirement: ValueMatcher 启动期校验
系统 SHALL 在启动期对所有 `RawValueExpectation` 字段执行严格的类型和语义校验。校验 SHALL 同时接受 primitive 原始值和 `ValueMatcher` 对象两种形式，但 MUST NOT 修改输入对象。当输入为 primitive 原始值时，系统 SHALL 视为合法配置（等价于 `{equals: value}`），无需进一步校验 matcher 字段。当输入为 `ValueMatcher` 对象时，`contains` MUST 为 string。`equals` MAY 为任意 JSON value。`exists` 和 `empty` MUST 为 boolean。`gt`、`gte`、`lt` 和 `lte` MUST 为有限数字（`Number.isFinite`）。`regex` MUST 为可编译的 string pattern，并通过 ReDoS 风险校验。`ValueMatcher` 对象 MUST 至少包含一个合法 matcher 字段，空对象 `{}` SHALL 导致启动期配置错误。`ValueMatcher` 对象 MUST NOT 包含未知字段，任何不属于 `equals`、`contains`、`regex`、`exists`、`empty`、`gt`、`gte`、`lt`、`lte` 的字段 SHALL 导致启动期配置错误。

#### Scenario: 空 matcher 对象被拒绝
- **WHEN** YAML 配置中任一 matcher 对象为空 `{}`
- **THEN** 系统 SHALL 在启动期配置校验失败，提示 matcher 必须包含至少一个合法字段

#### Scenario: 未知 matcher 字段被拒绝
- **WHEN** YAML 配置中任一 matcher 对象包含 `foo: "bar"` 等未知字段
- **THEN** 系统 SHALL 在启动期配置校验失败，提示该字段未知

#### Scenario: 数值 matcher 非有限数字被拒绝
- **WHEN** YAML 配置中任一 matcher 的 `gt`、`gte`、`lt` 或 `lte` 值为 `NaN`、`Infinity` 或非数字类型
- **THEN** 系统 SHALL 在启动期配置校验失败，提示数值 matcher 必须为有限数字

#### Scenario: 布尔 matcher 非布尔值被拒绝
- **WHEN** YAML 配置中任一 matcher 的 `exists` 或 `empty` 值不是布尔类型
- **THEN** 系统 SHALL 在启动期配置校验失败，提示该字段必须为布尔值

#### Scenario: 字符串原始值校验通过
- **WHEN** YAML 配置中 RawValueExpectation 字段值为字符串 `"stop"`
- **THEN** 系统 SHALL 接受该配置，但 SHALL NOT 在语义校验阶段修改输入对象

#### Scenario: 数字原始值校验通过
- **WHEN** YAML 配置中 RawValueExpectation 字段值为数字 `5000`
- **THEN** 系统 SHALL 接受该配置，但 SHALL NOT 在语义校验阶段修改输入对象

#### Scenario: null 原始值校验通过
- **WHEN** YAML 配置中 RawValueExpectation 字段值为 `null`
- **THEN** 系统 SHALL 接受该配置，但 SHALL NOT 在语义校验阶段修改输入对象

#### Scenario: 数组原始值被拒绝
- **WHEN** YAML 配置中 RawValueExpectation 字段值为数组 `[1, 2]`
- **THEN** 系统 SHALL 在启动期配置校验失败，提示必须为 primitive 原始值或 matcher 对象；如需数组 equals 匹配应写成 `{equals: [1, 2]}`

#### Scenario: 对象原始值必须显式 equals
- **WHEN** YAML 配置中 RawValueExpectation 字段值为对象 `{foo: "bar"}`，且 `foo` 不是合法 matcher 字段
- **THEN** 系统 SHALL 在启动期配置校验失败，提示 `foo` 是未知 matcher；如需对象 equals 匹配应写成 `{equals: {foo: "bar"}}`

### Requirement: empty matcher 语义
`empty: true` SHALL 在以下情况判定通过：实际值为 `null`、`undefined`、空字符串 `""`、空数组 `[]` 或空对象 `{}`。`empty: false` SHALL 在以上条件均不满足时判定通过。数字 `0` 和布尔 `false` SHALL NOT 被视为 empty。

#### Scenario: null 视为 empty
- **WHEN** 实际值为 `null` 且 matcher 为 `{empty: true}`
- **THEN** 系统 SHALL 判定该 matcher 通过

#### Scenario: 空字符串视为 empty
- **WHEN** 实际值为 `""` 且 matcher 为 `{empty: true}`
- **THEN** 系统 SHALL 判定该 matcher 通过

#### Scenario: 空数组视为 empty
- **WHEN** 实际值为 `[]` 且 matcher 为 `{empty: true}`
- **THEN** 系统 SHALL 判定该 matcher 通过

#### Scenario: 空对象视为 empty
- **WHEN** 实际值为 `{}` 且 matcher 为 `{empty: true}`
- **THEN** 系统 SHALL 判定该 matcher 通过

#### Scenario: 数字 0 不视为 empty
- **WHEN** 实际值为 `0` 且 matcher 为 `{empty: true}`
- **THEN** 系统 SHALL 判定该 matcher 不通过

#### Scenario: 布尔 false 不视为 empty
- **WHEN** 实际值为 `false` 且 matcher 为 `{empty: true}`
- **THEN** 系统 SHALL 判定该 matcher 不通过

### Requirement: exists 与其他 matcher 的组合语义
当 `ValueMatcher` 同时包含 `exists: false` 和其他非存在性 matcher（如 `contains`、`regex`、`equals` 等）时，系统 SHALL 在启动期配置校验失败，提示 `exists: false` 不能与其他 matcher 组合使用。`exists: true` MAY 与其他 matcher 组合，语义为先确认存在再执行其他 matcher。

#### Scenario: exists false 与 contains 组合被拒绝
- **WHEN** YAML 配置中 matcher 为 `{exists: false, contains: "foo"}`
- **THEN** 系统 SHALL 在启动期配置校验失败，提示 `exists: false` 不能与其他 matcher 组合

#### Scenario: exists true 与 contains 组合允许
- **WHEN** 实际值为 `"hello foo"` 且 matcher 为 `{exists: true, contains: "foo"}`
- **THEN** 系统 SHALL 判定该 matcher 通过

### Requirement: regex 字段语义
系统 SHALL 使用 `regex` 作为唯一正则 matcher 字段。`regex` 值 MUST 为可编译的字符串 pattern。运行期 SHALL 固定使用无 flags 的 `new RegExp(pattern).test(String(actual))` 执行匹配。系统 MUST NOT 支持旧 `match` 字段。系统 SHALL 在启动期对所有 `regex` pattern 执行可编译校验和 ReDoS 风险校验。

#### Scenario: regex 任意位置匹配
- **WHEN** 实际值为 `"api status ok"` 且 matcher 为 `{regex: "status"}`
- **THEN** 系统 SHALL 判定该 matcher 通过，因为无 flags 的 JavaScript 正则仍会搜索整个字符串中的第一次匹配

#### Scenario: regex 完整匹配由用户声明锚点
- **WHEN** 实际值为 `"OK\n"` 且 matcher 为 `{regex: "^OK$"}`
- **THEN** 系统 SHALL 判定该 matcher 不通过，因为系统 MUST NOT 默认启用 multiline flags

#### Scenario: match 字段启动失败
- **WHEN** YAML 配置中任一 matcher 对象包含 `match: "ok"`
- **THEN** 系统 SHALL 在启动期配置校验失败，提示 `match` 是未知字段或不支持字段

#### Scenario: regex ReDoS 风险启动失败
- **WHEN** YAML 配置中任一 `regex` 为 `"(a+)+$"`
- **THEN** 系统 SHALL 在启动期配置校验失败，提示正则存在 ReDoS 风险

### Requirement: ContentExpectations 内容断言数组
系统 SHALL 提供共享 `ContentExpectations` 表达返回内容断言。`ContentExpectations` MUST 为有序数组，数组项 SHALL 为直接 `ValueMatcher`，或 `json`、`css`、`xpath` 三类 extractor expectation 之一。系统 SHALL 在 resolve 阶段将 Raw content DSL 解析为带 `kind` 字段的 Resolved `ContentExpectation` 执行计划，并按数组顺序执行全部 expectation，任一 expectation 失败时 SHALL 立即停止并返回该 expectation 的 failure。系统 MUST NOT 支持内容字段的非数组对象快捷写法。

#### Scenario: 直接 matcher 内容 expectation
- **WHEN** 内容字段配置 `[{contains: "ready"}, {regex: "listening on \\d+"}]` 且原始内容同时满足两条 expectation
- **THEN** 系统 SHALL 判定该内容字段通过

#### Scenario: 内容 expectation 数组快速失败
- **WHEN** 内容字段配置三条 expectation 且第二条 expectation 失败
- **THEN** 系统 SHALL 返回第二条 expectation 的 failure，并 MUST NOT 执行第三条 expectation

#### Scenario: 内容字段必须为数组
- **WHEN** YAML 中内容字段配置为 `{contains: "ok"}` 而不是数组
- **THEN** 系统 SHALL 在启动期配置校验失败，提示该内容字段必须为 expectation 数组

#### Scenario: Resolved content expectation 使用 kind
- **WHEN** Raw 内容字段包含直接 matcher、json extractor、css extractor 和 xpath extractor
- **THEN** resolve 阶段 SHALL 分别生成 `kind="value"`、`kind="json"`、`kind="css"` 和 `kind="xpath"` 的 Resolved `ContentExpectation`

### Requirement: ContentExpectation 互斥性约束
一条 Raw `ContentExpectation` MUST 为直接 `ValueMatcher` 或恰好一个 extractor（`json`、`css`、`xpath` 之一）。系统 MUST NOT 允许同一条 Raw expectation 同时包含多个 extractor。直接 `ValueMatcher` expectation MUST NOT 包含 `json`、`css`、`xpath` 字段。系统 SHALL 在启动期对违反互斥性的 Raw expectation 报错。

#### Scenario: 多 extractor 被拒绝
- **WHEN** YAML 中内容 expectation 为 `{json: {path: "$.a"}, css: {selector: "div"}}`
- **THEN** 系统 SHALL 在启动期配置校验失败，提示一条 expectation 不能同时包含多个 extractor

#### Scenario: 直接 matcher 混入 extractor 被拒绝
- **WHEN** YAML 中内容 expectation 为 `{contains: "ok", json: {path: "$.a"}}`
- **THEN** 系统 SHALL 在启动期配置校验失败，提示直接 matcher 不能与 extractor 混用

### Requirement: 空 ContentExpectations 数组语义
`ContentExpectations` 空数组 `[]` SHALL 被系统接受为合法配置。运行期空数组 SHALL 等价于无内容 expectation，即该内容字段的断言直接通过。

#### Scenario: 空 body 数组通过
- **WHEN** HTTP target 配置 `expect.body: []` 且响应体为任意内容
- **THEN** 系统 SHALL 判定 body 阶段通过

### Requirement: ContentExpectations 非字符串值序列化
当 `ContentExpectations` 的观测源为非字符串值（如对象或数组）时，直接 `ValueMatcher` 的 `contains` 和 `regex` SHALL 先将值 JSON 序列化为字符串后匹配。`equals` SHALL 直接在原始结构化值上使用深度相等比较，不进行序列化。

#### Scenario: 对象序列化后 contains 匹配
- **WHEN** ContentExpectations 观测源为 `{status: "ok"}` 且 expectation 为 `{contains: "ok"}`
- **THEN** 系统 SHALL 将对象 JSON 序列化后执行 contains 匹配

#### Scenario: 对象 equals 不序列化
- **WHEN** ContentExpectations 观测源为 `{status: "ok"}` 且 expectation 为 `{equals: {status: "ok"}}`
- **THEN** 系统 SHALL 直接在结构化值上使用深度相等比较

### Requirement: ContentExpectations 提取器
系统 SHALL 支持在 `ContentExpectations` 中使用 `json`、`css` 和 `xpath` extractor。`json.path` MUST 使用现有 JSONPath 子集。`css.selector` MUST 为非空字符串，并 MAY 配置 `attr` 提取属性值。`xpath.path` MUST 为非空字符串，并 SHALL 在启动期进行可编译校验。Extractor 内部 MAY 包含任意 `ValueMatcher` 字段。Extractor expectation 未配置任何 matcher 时，resolve 阶段 SHALL 将其 Resolved matcher 物化为 `{ exists: true }`。

#### Scenario: json extractor 数字比较
- **WHEN** 原始内容为 JSON 字符串 `{"count": 2}` 且 expectation 为 `{json: {path: "$.count", gte: 1}}`
- **THEN** 系统 SHALL 解析 JSON、提取 `$.count` 并判定该 expectation 通过

#### Scenario: json extractor 存在性默认语义
- **WHEN** 原始内容为 JSON 字符串 `{"user": {"id": null}}` 且 expectation 为 `{json: {path: "$.user.id"}}`
- **THEN** resolve 阶段 SHALL 将该 expectation 的 matcher 物化为 `{exists: true}` 并在运行期判定通过

#### Scenario: css attr 存在性默认语义
- **WHEN** 原始内容包含 `<meta name="status" content="ok">` 且 expectation 为 `{css: {selector: "meta[name=status]", attr: "content"}}`
- **THEN** resolve 阶段 SHALL 将该 expectation 的 matcher 物化为 `{exists: true}` 并在属性存在时判定通过

#### Scenario: xpath 无匹配节点失败
- **WHEN** XML 内容中不存在 XPath 指向的节点，且 expectation 为 `{xpath: {path: "/root/status"}}`
- **THEN** 系统 SHALL 判定该 expectation 不通过并生成 phase 对应内容字段的 mismatch failure

### Requirement: KeyedExpectations 键控断言数组
系统 SHALL 提供共享 `KeyedExpectations` 表达键值型观测值断言。Raw `KeyedExpectations` SHALL 为动态键对象，每个键对应的值 MUST 为 `RawValueExpectation`；数组和对象简写 MUST 被拒绝，数组或对象 equals 匹配 MUST 显式写为 `{equals: <value>}`。Resolved `KeyedExpectations` SHALL 为有序数组，每个元素包含原始 key 和已归一化的 `ValueExpectation` matcher。调用方 MAY 指定 key 规范化策略；HTTP 与 LLM headers MUST 使用大小写不敏感的 key 匹配，并 MUST 在启动期校验或 resolve 阶段拒绝归一化后重复的 header key。DB rows 不做 key 归一化，按查询结果列名大小写敏感匹配。

#### Scenario: headers 字面量快捷写法
- **WHEN** 响应 headers 中 `content-type` 为 `application/json`，且配置为 `headers: {Content-Type: "application/json"}`
- **THEN** resolve 阶段 SHALL 将该项解析为 keyed expectation `{key: "Content-Type", matcher: {equals: "application/json"}}`，运行期按大小写不敏感 key 匹配并判定通过

#### Scenario: headers matcher 写法
- **WHEN** 响应 headers 中 `content-type` 为 `application/json; charset=utf-8`，且配置为 `headers: {Content-Type: {contains: "application/json"}}`
- **THEN** 系统 SHALL 判定该 header expectation 通过

#### Scenario: 缺失键 exists false
- **WHEN** 观测键值表中不存在 `x-debug`，且配置为 `{x-debug: {exists: false}}`
- **THEN** 系统 SHALL 判定该 keyed expectation 通过

#### Scenario: keyed 对象值必须显式 equals
- **WHEN** Raw keyed expectation 的某个值是对象 `{foo: "bar"}` 且未写在 `equals` 下
- **THEN** 系统 SHALL 在启动期配置校验失败，提示对象 equals 必须显式写成 `{equals: {foo: "bar"}}`

#### Scenario: keyed 数组值必须显式 equals
- **WHEN** Raw keyed expectation 的某个值是数组 `["a"]` 且未写在 `equals` 下
- **THEN** 系统 SHALL 在启动期配置校验失败，提示数组 equals 必须显式写成 `{equals: ["a"]}`

#### Scenario: header 归一化重复 key 被拒绝
- **WHEN** HTTP 或 LLM `expect.headers` 同时配置 `Content-Type` 和 `content-type`
- **THEN** 系统 SHALL 在启动期配置校验失败，提示 header key 归一化后重复

### Requirement: 结构化失败路径
系统 SHALL 在共享 matcher、content 和 keyed expectation 断言失败时生成结构化 `CheckFailure`。failure SHALL 包含 `kind`、`phase`、`path`、`message`，并在 mismatch 场景包含 `expected` 和 `actual`。内容 expectation failure path SHALL 包含数组下标，keyed expectation failure path SHALL 包含键名，extractor failure path SHALL 包含 extractor 类型和 path/selector 信息。failure.expected SHOULD 使用用户可理解的 matcher 或 expectation 片段，MUST NOT 直接暴露 Resolved `kind` 执行计划；单字段 `equals` 包装 SHOULD 展示为原始 expected 值。

#### Scenario: ContentExpectations 失败路径
- **WHEN** `expect.body[1].json` expectation 失败
- **THEN** failure.path SHALL 指向 `body[1].json($.path)` 或等价可定位路径，failure.phase SHALL 为 `body`

#### Scenario: KeyedExpectations 失败路径
- **WHEN** `expect.headers.Content-Type` 不匹配
- **THEN** failure.path SHALL 指向 `headers.Content-Type`，failure.phase SHALL 为 `headers`

#### Scenario: actual 截断
- **WHEN** matcher 失败时 actual 字符串长度超过 200 字符
- **THEN** 系统 SHALL 使用现有截断策略保存 failure.actual，避免历史记录写入过长内容