chore: merge release 1.3.5 call observability

Version bump in pyproject and __init__, CHANGELOG dated 2026-09-09,
README install lower bound raised to >=1.3.5, and release-prep evidence
(remote check, gates, real gateway smoke and one bounded live probe)
recorded in the 1.3.5 validation finding.

.env.example

@@ -2,7 +2,8 @@
 # 键名清单 = M1 设计文档 §8 定稿;缺关键配置直接报错,不做默认值兜底。
 
 # ══ 多源配置: {SCOPE}__{PROVIDER}__{N}__{FIELD} ══
-# PROVIDER 必须是注册表键(qwen/deepseek/openai,或 register_provider 注册后经 registry 传入)。
+# PROVIDER 必须是注册表键(八段: qwen/deepseek/zhipu/moonshot/minimax/openai/anthropic/google,
+#   或 register_provider 注册后经 registry 传入)。
 # 必填: BASE_URL / API_KEY / MODEL / TIMEOUT_S(或用平铺 LLM_TIMEOUT 作缺省)。
 LLM__QWEN__1__BASE_URL=
 LLM__QWEN__1__API_KEY=
@@ -15,7 +16,21 @@ LLM__QWEN__1__TIMEOUT_S=120
 # LLM__QWEN__1__EST_TOKENS=2000          # 可选调优覆盖: TPM 入场预扣量;未填则库按 tpm//60 派生
 # LLM__QWEN__1__TTFT_TIMEOUT_S=30        # 须与 INTER_TOKEN 成对;0 < inter < ttft < timeout
 # LLM__QWEN__1__INTER_TOKEN_TIMEOUT_S=15
-# LLM__QWEN__1__ENABLE_THINKING=true     # 三态: 缺省=不注入 / true=注入开启 / false=注入关闭
+# LLM__QWEN__1__ENABLE_THINKING=true     # 三态: 缺省=不表态 / true=要求开启 / false=要求关闭
+#   本键是语法糖: true ≡ auto、false ≡ none、缺省 ≡ 不表态。
+#   已登记模型须清单含 AUTO 才接受 true；nearest 不代选强度。
+#   未登记仍尽力＋warning，空 wire 可能零推理字节，不保证开启。
+#   M3 删除糖并选 medium 等表内档；M2.5/M2.7 AUTO 不再偷带 medium。
+#   完整 M1–M9 与缺测见 README「1.3.4 推理配置迁移」。
+#   有受管意图时 EXTRA_BODY/overlay 推理控制同值也拒绝；raw-only 须退出所有意图。
+# LLM__QWEN__1__REASONING_EFFORT=auto     # 本源默认推理档位;缺省=不表态(随模型自己的默认档)
+#   八档(封闭词汇): none | auto | minimal | low | medium | high | xhigh | max
+#     none = 要求不推理(与"缺省不表态"是两回事);auto = 要求推理但不指定强度
+#   与 ENABLE_THINKING 语义矛盾会在装配期报错(如 true + none、false + low),
+#   不做"后者赢"的静默兜底——两个键说同一件事,矛盾就是配置错误
+#   模型不支持所配档位时报错并列出它真正支持的档(库带能力表,含出处与实测日期)
+# LLM__QWEN__1__EFFORT_FALLBACK=error    # 档位打空时: error(默认,报错) | nearest(映射到最近的档)
+#   默认报错的理由是钱: 静默的 medium→max 在部分模型上是数倍账单;nearest 等距取弱侧
 # LLM__QWEN__1__MISSING_DONE=retry       # SSE 缺 [DONE]: retry(默认) | salvage
 # LLM__QWEN__1__TRUST_ENV=true           # false = 绕过本地代理(LAN 直连)
 # LLM__QWEN__1__EXTRA_BODY={"temperature":0}   # 本源恒定的采样参数(JSON 对象串)
@@ -98,9 +113,15 @@ PGW_TELEMETRY_BACKEND=none               # sqlite | postgres | none(必填)
 #                                               # 也要能拿原样的请求复现与重放;截断后这两件事都做不成,而既有下游正依赖这一行为。
 #                                               # 反面同样要看清: 不截断意味着客户合同、标书全文无限期留在 llm_calls 里,
 #                                               # 多租户下还混在同一张表。真在意留存面的部署应显式设一个上限,并配保留期与访问控制。
+#                                               # 1.3.5 补充: error_body(网关响应正文摘要)沿用库内 summarize_body 上限,
+#                                               # 结构化耗尽终态行的 error 说明自带有界限长(不含模型原始正文);
+#                                               # **两者都不在本键的覆盖面内**,估算留存面时要单独计。
 # PGW_PRICING_PATH=config/prices.json           # 可选: {"<model>": {"input_per_1m": x, "output_per_1m": y}};缺省 cost 恒 None
 #                                               # 可选第三档 "cached_input_per_1m": z —— 供应商 prompt cache 命中部分的单价;
 #                                               # 不填即命中部分也按 input 全额计(库不猜折扣率),cost 会偏高
+# 推理语义/fallback/能力表/wire 变化前须换从未使用的新 namespace 或 salt。
+# 保留租户前缀与 epoch；per-call 覆盖也要迁移，只改此处无效。
+# 未迁移仍可回放旧语义并绕过新拒绝；回滚旧身份会重见旧值，库不自动隔离。
 # PGW_CACHE_NAMESPACE=<项目名或租户前缀>          # 缓存启用时必填(防跨项目毒化)
 # PGW_CACHE_TTL_S=604800                        # 缓存启用时必填,须 > 0
 # PGW_STRUCTURED_MAX_RETRIES=2                  # 缺省 2(M2.5);0 = 解析失败不重问(CHS 策略)

CHANGELOG.md

@@ -1,5 +1,163 @@
 # Changelog
 
+## 1.3.5(2026-09-09)
+
+把治理单位从「一次尝试」补齐到「一次逻辑调用」(issue #19、#23)。此前重试、换源、结构化重问、embedding 分批都各自独立可见,而「这一次调用总共打了几次、总共花了多久、最后为什么失败」在库外拼不出来;结构化耗尽、embedding／OCR 的无源与准入拒绝更是**一条遥测行都没有**。
+
+### 公共面四项变更
+
+| # | 位置 | 变更 | 谁会当场断 |
+| --- | --- | --- | --- |
+| 1 | `polygateway.CallStats` | 新导出的 frozen dataclass(`logical_call_id` / `attempts` / `total_latency_ms`) | 无(纯新增) |
+| 2 | `LLMResponse` / `EmbeddingResponse` / `OcrTextResult` / `OcrLayoutResult` | 各追加**末尾**字段 `call_stats: CallStats \| None = None` | 按位置解包这四个类型的代码 |
+| 3 | `ports.TelemetryRecorder.record_llm_call()` | 新增 **10 个无默认值 keyword-only 参数**(26 → 36 参) | 任何自建 recorder——且**在装配期当场报错**,不再是运行期静默丢行 |
+| 4 | 遥测表 `llm_calls` | 追加 10 列(INSERT 字段 26 → 36,物理列 27 → 37);新增 `event_kind='terminal_failure'` 行 | 按旧口径计失败调用数的 SQL |
+
+第 3 条的装配期报错是有意的:`_record` 的 `except Exception` 会把旧签名 recorder 的 `TypeError` 吞成 warning,后果是下游升级后 **100% 丢遥测且调用照常成功**。降级方向的铁律管的是运行期写失败,不是装配错误。`**fields` 形态的 recorder 不受影响。
+
+### 下游必须做的事
+
+| 动作 | 说明 |
+| --- | --- |
+| **计失败调用改 `WHERE event_kind = 'terminal_failure'`** | 一次逻辑调用恰好一条终态行。`error IS NOT NULL` 跨尝试行与终态行,升级后计数会变大 |
+| `AVG(latency_ms)` 按 `event_kind` 分组 | 终态行的 `latency_ms` 是整个逻辑调用的总耗时,与单次尝试不同量纲 |
+| 自建 recorder 补齐 10 参 | 或改成 `**fields`;同时同步自己的 schema 与 INSERT 字段 |
+| PG manual 档下游补列 | `telemetry_schema_sql("postgres")` 自取;不补则这 10 个维度按现有列裁剪后静默不落库(库发一条点名警告) |
+| 注意失败行可能带 `http_status_code = 200` | MonkeyOCR 的 `success != true` 就是 200 下的失败,该列不可当成败判据 |
+
+费用口径**不变**:终态行 `cost IS NULL`、`usage_source='unavailable'`、token 为 0,不参与 `SUM(cost)`。400 密集负载下错误行会翻倍(既有 attempt 错误行 + 新增终态行),这是已批准的下游可见变化。
+
+### 其他
+
+- 新列全部可空、无默认值、追加在现有末列之后;**旧行不回填**(NULL 表达「补列之前根本没记过这件事」),滚动升级期新旧进程可写同一张表。
+- `error_body` 沿用 `summarize_body` 上限,结构化耗尽终态行的 `error` 带有界说明(不含模型原始正文);**两者都不在 `PGW_TELEMETRY_TEXT_CAP` 覆盖面内**。
+- 修正历史误标:`embed()` 非 200 的失败现在报 `operation="embedding"`。遥测新列 `operation` 由调用点给定,与 `exc.operation` 是两个语义。
+- 重试预算与退避、429 免预算与 stall 算法、取消结算、限流/熔断语义、缓存 key 公式一字未改。
+
+## 1.3.4(2026-09-09)
+
+> [!WARNING]
+> **patch 版号不代表无迁移成本。** 已登记但不含 AUTO 的 True／auto 配置及受管＋raw 双来源现在明确拒绝；受影响缓存必须在首次新语义读写前显式换 namespace／salt。升级步骤见 [README 迁移节](README.md#134-推理配置迁移)。
+
+- **推理意图**：已登记 AUTO 必须为能力清单成员，True 糖同约束；nearest 不代选强度。MiniMax on_base 改空，M3 要显式选 medium 等登记档；M2.5／M2.7 空 wire 流式 AUTO 各5轮定向复验通过，不代表全矩阵覆盖。未知仍尽力＋warning，不保证开启。
+- **所有权**：受管意图下两层 raw 推理控制同值／被遮蔽也拒绝；raw-only 与普通采样浅覆盖保留。自定义 on_base 禁止偷带强度。
+- **缓存迁移前置**：受影响调用更换从未承载旧语义的 namespace／salt；同版本 fallback、能力表、wire 变化亦需迁移。不加自动指纹，未迁移仍可回放旧语义。M1–M9、per-call／多源／回滚示例见 README。
+- **测试证据**：默认 FAIL，不整类 skip；404 仅完整独立证据可未覆盖，公共身份缺失无独立证据 FAIL。逐轮脱敏，UNKNOWN／SKIP／缺轮不算关闭覆盖；不可关闭与预期拒绝独立判定。缺型号级 400 机器字段基线仍 FAIL，不编造白名单。
+- **遥测守卫**：真实客户端／临时 SQLite 的 embedding、OCR 双入口成败 NULL、chat 阳性与四种行来源回归；不新增 schema、生产端口或成功 SSE 捕获器。
+
+**验收例外**：2026-09-09 用户正式批准不再补全模型矩阵，失败／UNKNOWN／不可达／缺轮及缺下游现行配置证据作为本版例外保留，不冒称 PASS。embedding 实测 503 不符合严格404未覆盖条件，仍为 FAIL；claude-opus-5 开启档位命题仍 FAIL，不能把 HTTP 200 当推理开启证明。独立审查、红绿／变异、日常与定向实测均按适用范围复用；具体失败、网络诊断及原始证据见[验证记录](research-wiki/findings/2026-09-09-134-thinking-contracts-validation.md)。该例外不取消下游缓存迁移前置，也不代表合并后检查、上传或外部包验收已执行。
+
+## 1.3.3(2026-09-05)
+
+推理从「开 / 关」升级为**档位**(issue #20)。`enable_thinking: bool | None` 表达不了新一代模型:GLM-5.3 官方强制推理、只接受 `low/high/max`,`none` 不是它的档位——二态布尔在它上面无档可填,下游只能手写 `extra_body`,而那条路会静默绕过本库为推理准备的三道机制。本版把档位做成一等公民:八档封闭词汇、源级与请求级两个入口、能力表按档位登记、缓存 key 与遥测各加一维。
+
+**版号是 patch(2026-09-05 人类指令,不因破坏性变更走 minor),但本版含五处破坏性变更与四条行为变更。** patch 版号从设计上就不承担预警职责,预警只能由这份 CHANGELOG 扛,故全部置于最前。
+
+### 请先读这一条(一):五处破坏性变更
+
+| # | 位置 | 变更 | 谁会当场断 |
+| --- | --- | --- | --- |
+| 1 | `ThinkingCapability` | 构造签名 `can_disable: bool` → `supported_efforts: tuple[Effort, ...]` | 自建能力表的调用方(**关键字与位置两种构造都断**) |
+| 2 | `ports.Transport.complete()` | 新增**无默认值**参数 `reasoning_effort` | 任何自建 transport 实现 |
+| 3 | `ports.TelemetryRecorder.record_llm_call()` | 新增无默认值参数 `reasoning_effort`(25 → 26 参) | 任何自建 recorder 实现 |
+| 4 | `thinking.resolve_thinking()` | 第三参数由 `bool` 换成 `Effort`,**返回类型由 `Mapping` 改为 `ThinkingResolution`** | 直调它的读侧代码一律断 |
+| 5 | `providers.ProviderProfile` | 两个字段 `thinking_on` / `thinking_off` → 单字段 `thinking: ThinkingWire` | 自建 profile 的调用方 |
+
+第 1 条的 `can_disable` **保留为只读派生属性**(`Effort.NONE in supported_efforts`),只读它的代码一行不用改;**构造则两种写法都断**:
+
+| 1.3.2 的写法 | 升级后 |
+| --- | --- |
+| `ThinkingCapability(can_disable=True, evidence="…")`(库自己那张表用的就是它) | `TypeError: ... got an unexpected keyword argument 'can_disable'` |
+| `ThinkingCapability(True, "…")` | `TypeError: 'bool' object is not iterable`——断在 `__post_init__` 的去重校验里,错误信息看不出真实原因 |
+| 迁移写法 | `ThinkingCapability(supported_efforts=(Effort.NONE, Effort.AUTO), evidence="…")` |
+
+第 2、3 条按这两个端口的既有纪律**不设默认值**:库外没有第三方实现者,带默认值只会让漏传时静默落一个默认值。第 4 条的新返回值是 `ThinkingResolution(payload, applied_effort)`——原来那个 mapping 现在是 `.payload`,多出来的 `.applied_effort` 是开了 `nearest` 映射后**真正发出去**的那一档。
+
+### 请先读这一条(二):不改一行代码也会变的四条行为
+
+| # | 变更 | 影响 |
+| --- | --- | --- |
+| 1 | `glm-5.3` / `glm-5.3-flash` / `gemini-3.1-pro` **首次进入能力表**,且三者都登记为**关不掉推理** | **本版唯一会打断存量配置的一条。** 1.3.2 里这三个型号未登记,给它们配 `ENABLE_THINKING=false` 会按 provider 形态尽力注入并**放行**(只发一条 warning);本版在**装配期**抛 `ThinkingUnsupportedError`。并排实测:`deepseek/glm-5.3 + ENABLE_THINKING=false` 在 1.3.2 返回 `{"thinking": {"type": "disabled"}}`,在本版当场报错 |
+| 2 | `openai` 段的**开启**方向由「形态未知即装配期报错」放宽为 `on_base={}` | 把任意兼容厂商挂在 `openai` 段下并配 `ENABLE_THINKING=true` 的下游:1.3.2 在装配期报错,本版放行且**一个字节都不注入**——走模型自己的默认档。若该模型默认不推理,这个配置既不报错也不开推理(见下方「已知限制」) |
+| 3 | `openai` 段的**关闭**方向由「形态未知即装配期报错」放宽为 `{"reasoning_effort": "none"}` | 同上但配 `ENABLE_THINKING=false` 的下游:1.3.2 在装配期报错,本版下发这个片段。放宽的依据是 `reasoning_effort` 是 OpenAI **官方**字段而非厂商方言,经网关的兼容端点不会把它打到不认识它的厂商 |
+| 4 | 缓存 key 加入 `reasoning_effort` | 只有**新配** `REASONING_EFFORT` 的源冷启动一次;只配 `ENABLE_THINKING` 或什么都没配的源,key 字面量逐字不变(已按 1.3.2 的实现逐字比对) |
+
+第 1 条是设计上有意为之:调用方要的是「不推理」的语义保证,给不了就必须说,而不是让它继续静默烧推理 token——升级后当场失败,正是这三个型号本来就关不掉推理的证据。报错文案带一条能立刻照做的替代(该模型最省的那一档 + 该配的 env 键名),不把人推回 `extra_body` 那条绕过库的路。
+
+**`qwen` / `deepseek` / `minimax` 三段的注入形态逐字未变。** 全量比对(4 个 1.3.2 已有的 provider 段 × 25 个模型 × `ENABLE_THINKING` 三态 = 300 种组合)显示,本版与 1.3.2 的差异**只有上表第 1、2、3 条**。`minimax` 的「开」尤其值得点名:它维持 `{"reasoning_effort": "medium"}` 逐字不变,因为真实网关实测显示 MiniMax-M3 在不带任何推理参数时**不推理**(5/5 轮),把它改成「不注入即为开」会让存量 `ENABLE_THINKING=true` 的调用静默停止推理。
+
+### 新增能力
+
+| 新增 | 说明 |
+| --- | --- |
+| 八档 `Effort`:`none` / `auto` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max` | 封闭词汇,取四家参考实现共同收敛的那一套。`none` = 要求不推理(与「不表态」是两回事),`auto` = 要求推理但不指定强度 |
+| `{SCOPE}__{PROVIDER}__{N}__REASONING_EFFORT` | 源级默认档。`ENABLE_THINKING` 保留,降为它的语法糖(`true` ≡ `auto`、`false` ≡ `none`、缺省 ≡ 不表态);两键语义矛盾(如 `true` + `none`)在**装配期**报错,不做「后者赢」的静默兜底 |
+| `{SCOPE}__{PROVIDER}__{N}__EFFORT_FALLBACK` | `error`(缺省,报错)或 `nearest`(映射到最近档并 warning)。默认报错的理由是钱:一次静默的 `medium → max` 在部分模型上是数倍账单 |
+| `chat(reasoning_effort=...)` | 请求级覆盖,优先级高于源级;裸字符串会在入口归一 |
+| `LLMResponse.applied_effort` | 本次**实际**跑在哪一档(开了 `nearest` 时与请求档分叉)。字段追加在末尾,既有字段只增不改名 |
+| 四个新 provider 段 `zhipu` / `moonshot` / `anthropic` / `google` | 连同 1.3.2 已有的 `qwen` / `deepseek` / `minimax` / `openai` 共**八段**。四段都是新增,不改变任何存量配置的行为 |
+| 能力表由 **5 条扩到 24 条** | 1.3.2 只登记 5 个型号,其余一律走「按 provider 形态尽力注入 + warning」。本版新登记 19 个:qwen 4 款、deepseek 2 款、GLM 6 款、kimi 2 款、gpt 2 款、claude 2 款、gemini 1 款 |
+| `kimi-k3` **首次登记**为可关闭 | 它在 1.3.2 未登记(配 `false` 走尽力注入 + warning,不报错)。本版实测坐实可关:请求 `none` 后短提示词 5/5 轮 + 长上下文 3/3 轮无任何推理信号、completion 恒 9 token,与同模型 max 档(rt 33-146)的锚点可分。两源分歧由此了结——OpenRouter 的 `mandatory:false` 是对的,官方档位表没列 `none` 只是没列 |
+| 包根新增导出 `Effort` / `EFFORT_ORDER` / `ThinkingWire` / `ThinkingResolution` | 深路径 import 会被内部重组打断,一律从 `polygateway` 包根取 |
+
+档位不支持时**报错必带可执行替代**:模型关不掉推理时,错误文案直接给出该模型最省的那一档和该配的 env 键名。只报错不给出路,下游只会退回 `extra_body`——而那正是 issue #20 的成因。
+
+### 遥测:第 26 个 INSERT 字段 `reasoning_effort`
+
+`llm_calls` 新增一列 `reasoning_effort TEXT`(INSERT 字段 25 → 26,物理列 26 → 27)。列可空,`NULL` 表示调用方**没表态**;它与 `'none'`(明确要求不推理)是两回事,折叠成任一档都等于替上游声称了一件它没说过的事。加这一列是为了让「不同档位是不是真有用」这类压测在数据侧能分组——此前 25 列里没有任何一列能回答「这一行跑在哪档」。
+
+**成功行与失败行不是同一把尺子。** 开了 `EFFORT_FALLBACK=nearest` 的源上,成功行记的是**映射后的实发档**(读 `response.applied_effort`);失败尝试没有响应、实发档无从得知,记的是**请求档**。故 `GROUP BY reasoning_effort` 不带 `error IS NULL` 时,两种尺子会混进同一个分组。缓存命中行与终态失败行同样只记请求档——它们手上没有选中源,源级档位与 `nearest` 映射都无从谈起。embedding / OCR 两条路径没有推理语义,该列恒 `NULL`。
+
+补列走既有的 `PGW_TELEMETRY_SCHEMA_MODE`,两端 DDL 与 `COLUMNS` 同源。**manual 档的下游会看到一处文案变化**:旧表的缺列告警会多点名 `reasoning_effort` 这个维度,并附上对应的 `ALTER TABLE ADD COLUMN` 语句。
+
+### 能力表口径:24 条里 17 条经 new-api 实测、7 条仍是文档推定
+
+`DEFAULT_CAPABILITIES` 共 24 条,每条 `evidence` 自报家门(实测日期、轮数 N、判据、锚点,或「文档推定」及其四方出处)。**读能力表请以逐条 evidence 为准,本版不存在「能力表已全部实测」这回事。** 未能实测的 7 条与原因:
+
+| 模型 | 未覆盖的原因 |
+| --- | --- |
+| `claude-opus-5`、`claude-sonnet-5` | 该渠道 claude 全系返回 429「api key 7 天限额已用完」,5/5 轮失败;`none` 档还额外依赖网关把 `reasoning_effort=none` 转成 `thinking` 关闭形态,同样未经验证 |
+| `gemini-3.1-pro` | 该渠道本型号上游报错(`bad_response_status_code` / `openai_error`),5/5 轮失败,连默认档基线都没取到。默认档「官方文档说 high、OpenRouter 说 medium」两源打架**仍未决**,本版不选边 |
+| `gpt-5.4` | 全账号限流(429 All available accounts are currently rate-limited),5/5 轮失败。同代的 `gpt-5.5` 已实测且与清单逐字相符,可作旁证但不是本型号的证据 |
+| `glm-5`、`glm-5.1`、`glm-5.2` | 请求这三个型号时,渠道 5/5 轮把流量路由到 `glm-5.3`(issue #20 记录的 6/6 复现);拿到的行为不属于本型号,整组数据作废 |
+
+`glm-5.2` 的下游风险要单独说:在这条渠道上给它配 `none`,库会照文档推定放行,而真正服务请求的 `glm-5.3` **关不掉推理**;运行期对账会喊,但那是事后。
+
+另有两条与实测相关的收获值得下游知道:同一批实测发现 `zhipu` / `moonshot` 这条渠道**不校验档位值**(未登记的 `medium` 也照单收下并返回 200),故「网关没报错」在这两家上**不构成**「该档受支持」的证据;而 `openai` 那条会校验(清单外的 `max` / `minimal` 被上游 400 拒)。
+
+### 已知限制:`auto` 不等于「强制开推理」(issue #21)
+
+`reasoning_effort=auto`(含它的语法糖 `ENABLE_THINKING=true`)在 `on_base={}` 的三个 provider 段(`openai` / `anthropic` / `google`)上表达的是「**用模型自己的默认档**」,库不注入任何字节。若某模型默认就不推理,这个配置**既不报错也不开推理**。正解是让 `auto` 受能力表约束——模型不支持「由模型自定」时报错并指路显式档位,属公共行为变更,留到下一版(gitea issue #21)。
+
+与之相连有一处**刻意的不一致**,请勿误读:`DEFAULT_CAPABILITIES` 里 `MiniMax-M3` 的 `supported_efforts` **不含 `auto`**(实测结论——它的默认档不推理),而 `minimax` 段的 wire 会为 `auto` 注入 `{"reasoning_effort":"medium"}` 并被放行。`resolve_thinking` 的 Phase 5 对 `auto` 无条件放行(`auto` 不是写进 `effort_key` 的取值,而是「不写 `effort_key`」),**能力表拦不住这条路**;当前是由 wire 侧的权宜之计兜住的。别把它读成「能力表能挡住 auto」。
+
+## 1.3.2(2026-08-28)
+
+**本版不改库代码。** `tools/` 与 `tests/` 都不在 pip 包内(脚本随仓库分发,见 README),故 1.3.2 的 wheel 与 1.3.1 **除版本号外没有任何差异**(`__version__` 与包元数据是唯一的改动)。升级它不会改变任何库行为——本版的内容是运维脚本 `tools/telemetry_retention.py` 的一处契约扩展,以及测试隔离的重建。若你只用库本体,可以跳过本版。
+
+### 运维脚本:`--table` 让删除目标不再由连接环境决定(issue #18)
+
+`tools/telemetry_retention.py` 此前删哪张表,取决于连接的 `search_path`——它的首项是 `"$user"`,所以**换个角色跑同一条命令,目标可能就换了一张表**。脚本会把解析到的限定名打出来,但那行打印与 `DELETE` 在同一次运行里,中间没有人。
+
+新增可选参数 `--table <schema>.llm_calls`:给了它,目标由参数精确解析(`to_regclass` 走引号限定名),绕开 `search_path`。
+
+| 情形 | 行为 |
+| --- | --- |
+| 不给 `--table` | **与 1.3.1 完全一致**,现有 cron 不受影响;但 `--apply` 时会多打印一行,提示目标是推断来的 |
+| 表名段不是 `llm_calls` | 退出 **1**。本脚本只清理遥测表,不是通用清理器——一次 `--table audit.events` 的手误,会对一张恰好也有 `created_at` / `tenant_id` 的业务表跑同一套分批 DELETE |
+| 显式指定的表不存在/不可见 | 退出 **2**,消息附一句"PG 中未加引号建的标识符在 catalog 里是小写"(大小写手误是这里的高频原因) |
+| 显式指定的是分区表 | 仍退出 **3** 让路给 `DROP PARTITION`,语义未变 |
+
+退出码契约未新增也未改动。**建议 cron 一律带上 `--table`**:那一行配置从此自己说明删的是哪张表。
+
+### 测试隔离:从"事后观测共享表"改成"权限上做不到"
+
+issue #18 报的是一条 PG 集成测试偶发红。查下来失败的断言并不在测被测脚本——它比对的是一张**三个迁移项目也在写**的表的前后行数,而报错时(61 行变 12 行)脚本本身被证明只动了自己的临时 schema。
+
+行数快照承载不了它想守的属性:别人一写就假红,而外部插入恰好抵消掉一次误删时又会假绿——后一半守的正是"审计表被删空"。现在这条属性交给数据库强制:跑脚本的测试角色拥有自己的临时表、对共享表**没有任何授权**,`search_path` 万一落空就是 `permission denied` 而不是"但愿有断言发现"。共享表 `llm_calls` 至此不再被本仓库任何测试读写,killed 的测试也不会再往里留孤儿行。
+
+对下游没有影响(测试不进包),列在这里是因为它解释了本版为何存在。
+
 ## 1.3.1(2026-08-26)
 
 「这次调用到底推理没推理」从此是库的**一等返回值**(issue #16 + #17): `LLMResponse.thinking_observation` 三态如实作答,判不出来时说 `unknown` 而不是伪装成「没推理」,并与推理能力表持续对账。
@@ -85,7 +243,6 @@ issue 判定「M3 开启推理静默失效,模型不推理」。实测推翻了
 - `TransportResult` 同步新增该字段并由 `RetryMW` 透传;裁定在 `openai_compat` 的流式与非流式**两条**组装路径各做一次。
 - 遥测的新列只经 `TelemetryEmitter._record` 这一个出口下沉给 recorder(单一 helper 铁律),且在那里由枚举归一化为裸 `str`——`StrEnum` 虽是 `str` 子类,asyncpg 的参数编码对 `str` 子类不保证接受,而遥测写失败只是一条 warning,这类问题不会当场炸,只会让 Postgres 那一路悄悄少一列数据。归一化按外部输入防御: `LLMResponse` 无运行时校验,下游填裸 `str` 完全自然,而直接取 `.value` 会抛异常并被降级路径吞成**丢掉整行**遥测;域外取值同样只降级记 `unknown` 并单独告警,不拿整行当代价。
 
-
 ## 1.3.0(2026-08-24)
 
 遥测后端从此**按需占用连接、失败可自愈、降级可查询**(issue #15)。提交方在一个 `max_connections=100` 的共享 PostgreSQL 上跑多 worker × 多 scope,发现库悄悄占掉了 40 条常驻连接,且余量一紧张就整个进程再也不落一行遥测——19 次调用一行未落、成本少记约 $5,是**人工比对**"日志里的完成里程碑条数 vs `llm_calls` 行数"才发现的。
@@ -154,7 +311,6 @@ issue 判定「M3 开启推理静默失效,模型不推理」。实测推翻了
 - SQLite 遥测初始化失败后终于有日志了。此前 `sqlite.py` 初始化失败直接 `return`,连一条 warning 都没有,整个进程零遥测且无任何痕迹。SQLite 侧本版**只做可见性**,不做 lazy 化与冷却重连(它的失败模式在装配期就会暴露,不是"跑到一半悄悄断")。
 - 写入路径不再用 `async with pool.acquire(...)`。`Pool.release()` 是 shielded 且默认复用 acquire 时记录的 timeout,预算到期时那次释放会正常等到完成——业务路径的真实上界因此是 ≈ 2 × 预算而不是一个预算。改为显式 acquire/release 后,承诺精确为"主写入尝试 ≤ 预算,释放路径独立有界(1s,超时即 terminate)"。
 
-
 ## 1.2.4(2026-08-20)
 
 熔断开路时,调用方第一次可以选择**等**而不是当场失败(issue #14)。此前准入侧有一格是空的:限流闸满时库允许排队(`{SCOPE}__QUOTA_FULL=wait|fail_fast`,缺省 `wait`),熔断门拒绝时**只有 fail-fast 一档且不可配**——而两者在准入语义上是同构的,都没发出请求、都带着"稍后再来"的提示。新键 `{SCOPE}__CIRCUIT_OPEN=fail_fast|wait` 补上这一格,形状与 `QUOTA_FULL` 逐项对齐。
@@ -176,7 +332,6 @@ issue 判定「M3 开启推理静默失效,模型不推理」。实测推翻了
 - `_pick_runnable`/`_on_no_runnable` 此前在 chat/embedding/OCR 三条治理循环里各存一份逐字复制,现收敛为 `middleware/admission.py::SourceAdmission` 一份。行为不变——差异用注入表达(调用内降权传空计数时恒等、AIMD pacer 为 `None` 时跳过),`permit` 结算的 warning 文案由三种归一为一种。
 - `GatewayUnavailableError` 的文档收回了重试职责:调用级的重试、退避、换源、等待冷却全部在库内,本异常表示那份预算已经用尽;下游据此再投属于**任务级**重试,语义不同。此前那句"业务侧 catch 本类做延期重投"读起来像在鼓励每个下游各写一份重试逻辑,而两边各写一份必然漂移。
 
-
 ## 1.2.3(2026-08-19)
 
 遥测表 `llm_calls` 的结构变更从此**由下游掌控**(issue #13)。此前两个后端都会在初始化期对下游数据库发 DDL:表不存在则建表,表存在但缺列则逐列 `ALTER TABLE ADD COLUMN`,而补列**没有任何开关**——库一升级、下次调用即自动执行。在共享的生产 Postgres 上这有三重问题:`ALTER` 取 ACCESS EXCLUSIVE 锁会排在长事务后阻塞该表其后的所有查询(而遥测是业务路径上的内联 `await`),多进程多版本共存时谁先补列是竞态,且这些 DDL 不进任何迁移记录、事后无从审计。调研过的 11 个同类系统(Celery / APScheduler / Alembic / Django contrib / Hangfire / Quartz.NET / dbt / Airbyte / Fivetran / Prefect / Airflow)里没有一个把它作为默认行为。

CLAUDE.md

@@ -103,6 +103,8 @@ make ci        # 只读验证(check + test)
 
 Gitea 包 registry 是 **owner 级**(`/iomgaa/-/packages/`)不是仓库级;PyPI 元数据不含仓库字段,故不会自动挂到 `PolyGateway/packages`,需在包页面手动 Link to a repository。
 
+发布验证补充（2026-09-09 实测）：私有索引不镜像 setuptools，下载 sdist 时 pip 即使带 `--no-deps` 仍可能尝试安装构建依赖；已具备构建工具的 conda 环境可加 `--no-build-isolation`，仍须核对下载来源与散列。包关联 POST 本次返回400，但匿名包页面和认证 GET 包 API 均证实已关联目标仓库；**400本身不算成功，也不能直接推断已关联**，必须读取实际 `repository.full_name` 与页面链接。包 API 可能要求认证（匿名401），页面仍应匿名亲查；不要为重试关联先解绑现有正确关系。
+
 ### 4.5 配置管理
 - 工程配置走 `pydantic-settings` + `.env`(模板 `.env.example`,敏感项不提交);严禁硬编码默认值;缺失关键配置直接报错。
 - 多源命名约定 `{SCOPE}__{PROVIDER}__{N}__{FIELD}`;韧性参数键名沿用三项目习惯(`LLM_TIMEOUT` 等),降低迁移成本。

Makefile

@@ -1,21 +1,34 @@
-.PHONY: install test lint format check ci wiki wiki-check
+.PHONY: install test lint format check ci wiki wiki-check shared-table-gate
 
 ENV := PolyGateway
 
+# 集成测试触碰共享表 llm_calls 的字面量门(issue #18)。
+# 这道门是**烟雾报警器,不是隔离证明**: 它拦不住 f"{schema}.{table}" 拼接、
+# 参数化查询,或不带限定名的 DELETE 配上 admin 的默认 search_path。真正的隔离
+# 来自两处——沙箱工厂不把管理连接交给用例,以及清理脚本以无权角色运行。
+# 留着它是因为字面量回归最常见、也最便宜拦。
+shared-table-gate:
+	@if grep -rn --include='*.py' 'public\.llm_calls' tests/; then \
+		echo ""; \
+		echo "错误: 集成测试不得触碰共享表(见上面的命中行)。"; \
+		echo "改用 tests/integration/conftest.py 的 pg_sandbox 工厂;注释里提到它请写「共享表 llm_calls」。"; \
+		exit 1; \
+	fi
+
 install:
 	conda run -n $(ENV) pip install -e ".[redis,postgres,structured,dev]"
 
 test:
 	conda run -n $(ENV) pytest tests/ --cov=src/polygateway --cov-report=term-missing
 
-lint:
+lint: shared-table-gate
 	conda run -n $(ENV) ruff check src/ tests/ --fix
 	conda run -n $(ENV) lint-imports
 
 format:
 	conda run -n $(ENV) ruff format src/ tests/
 
-check:
+check: shared-table-gate
 	conda run -n $(ENV) ruff format --check src/ tests/
 	conda run -n $(ENV) ruff check src/ tests/
 	conda run -n $(ENV) lint-imports

README.md

@@ -16,10 +16,12 @@
 | 熔断 | 双通道(连续失败 + 失败率窗口,健康证据抑制误熔);半开单探针带租约(持有者死亡自动回收);epoch fencing 拒绝迟到写回;开路时长指数递增;**开路时当场失败还是等冷却可配**(`CIRCUIT_OPEN`,单源 scope 应配 `wait`) |
 | 自适应并发 | AIMD:429 削减、成功缓升,防止打爆上游 |
 | 背压与判死 | 配额满与熔断开路**各自**可选等待或快速失败(`QUOTA_FULL` / `CIRCUIT_OPEN`,两键不可互相替代);等待期按双条件判死(本地非生产性等待与全局无进展**同时**超窗)。stall 窗口只计**非生产性**等待(429 退避/配额轮询/熔断冷却),与 `TIMEOUT_S` 无耦合 |
-| 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace(缓存隔离单位)+ salt + 采样参数,多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
+| 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace(缓存隔离单位)+ salt + 采样参数 + 请求级推理档位(同 messages 跑 low 与 max 不互相命中),多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
 | 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 |
-| 推理可观测性 | "这次到底推理没推理"由多信号裁定(推理正文压倒 usage 明细),三态落在 `LLMResponse.thinking_observation`:`observed` / `absent` / `unknown`——**`unknown` 是"本次判不出",不是"没推理"**;请求方向与实测观测矛盾时按 `(模型, 方向)` 各告警一次(能力表过期、开启未生效、注入了却观测不到);裁定结果随遥测落库 |
+| 推理可观测性 | "这次到底推理没推理"由多信号裁定(推理正文压倒 usage 明细),三态落在 `LLMResponse.thinking_observation`:`observed` / `absent` / `unknown`——**`unknown` 是"本次判不出",不是"没推理"**;本次实发档位与实测观测矛盾时按 `(源, 模型, 生效档位)` 各告警一次(能力表过期、开启未生效、注入了却观测不到;同一模型的 low 与 max 是两个独立的矛盾,不共用节流键);裁定结果随遥测落库 |
-| 遥测与成本 | 每次调用(含缓存命中与失败)必录 25 字段;SQLite / Postgres 后端(表已存在时**不需要** schema 建表权限,最小权限账号可直接用);按价格表折算成本落库(注意 `LLMResponse.cost` 本身恒为 `None`,成本只进遥测);多模态内容摘要落库不存原图 |
+| 推理档位 | 推理是**八档**(`none`/`auto`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`)而非开关:源级 `REASONING_EFFORT` + 请求级 `chat(reasoning_effort=...)`,`ENABLE_THINKING` 保留为语法糖;库带 24 条能力表(逐条 evidence 自报实测/文档推定),档位打空**默认报错并给出该模型最省的可用档与该配的键**,要静默映射需显式配 `EFFORT_FALLBACK=nearest`;实发档随 `LLMResponse.applied_effort` 与遥测落库 |
+| 遥测与成本 | 每次调用(含缓存命中与失败)必录 36 字段;三类行(`event_kind` = `attempt` / `cache_hit` / `terminal_failure`)加逐源诊断列(`http_status_code` / `error_type` / `cause_type` / `error_body`);SQLite / Postgres 后端(表已存在时**不需要** schema 建表权限,最小权限账号可直接用);按价格表折算成本落库(注意 `LLMResponse.cost` 本身恒为 `None`,成本只进遥测);多模态内容摘要落库不存原图 |
+| 逻辑调用统计 | 治理单位是**一次逻辑调用**而非一次尝试:四种响应(chat / embedding / OCR 两种)带 `call_stats`(`logical_call_id` / `attempts` / `total_latency_ms`),重试、换源、结构化重问、embedding 分批共享同一逻辑 ID;每次**领域失败**另落一条 `terminal_failure` 行,失败调用数从此是一条 `WHERE event_kind = 'terminal_failure'`,详见[1.3.5 逻辑调用统计与失败诊断](#135-逻辑调用统计与失败诊断) |
 | 遥测的资源与降级 | Postgres 池**闲时占 0 条连接**、忙时上限可配(`PGW_TELEMETRY_PG_POOL_MAX`,缺省 4),每次写入有硬预算(`PGW_TELEMETRY_PG_WRITE_TIMEOUT_S`,缺省 5s);后端不可用是**可恢复的降级**(冷却 60s 后自动重试,DBA 建完表/放开权限即自愈),永久失能只留给 DSN 本身写错;降级状态可编程查询——`client.telemetry_status` 给出 `degraded`/`fatal`/`reason`/`dropped_rows` 等只读快照,不必再靠人工对账。**对账要同时看 `degraded` 与 `dropped_rows`**: 池饱和超预算丢的行走行级丢弃,`degraded` 保持 `False`(后端没挂,是本进程并发超了),只按 `degraded` 告警会看不见这一类丢行——而它恰是 `pool_max` 配小了的唯一信号 |
 | 调用方维度 | 每次调用可带 `tenant_id`(遥测表的真实列,可挂 RLS、可建复合索引)与 `meta`(≤16 个自定义 KV);四个公共方法全覆盖,校验超限即报错;**库只交付列,不启用 RLS、不建索引** |
 | 遥测表治理 | `llm_calls` 是**下游的表**:PG 侧缺省**不再自动 `ALTER` 补列**(`PGW_TELEMETRY_SCHEMA_MODE` 三态,不设则 sqlite→auto、postgres→manual),manual 档点名缺列并按现有列裁剪写入;`telemetry_schema_sql(backend)` 自取可粘进迁移文件的建表/补列 SQL;`PGW_TELEMETRY_TEXT_CAP` 限正文长度(**不设 = 存全文**);保留期与访问控制走[生产部署 DDL 模板](#生产部署-ddl-模板postgresql)加 `tools/telemetry_retention.py` |
@@ -29,13 +31,91 @@
 
 **降级方向是铁律**:缓存/遥测后端掉线 → 降级而不冒泡(业务调用照常返回);限流/熔断后端掉线 → 报错而非放行(防击穿上游)。遥测的降级**不是静默的**——进入/恢复各一条日志、期间按行数与时间节流复述,并随时可经 `client.telemetry_status` 读到。`asyncio.CancelledError` 全链路穿透,in-flight 资源在 finally 释放;**资源所有权的纪律是「谁建的谁关」**——`aclose()` 只关自己 `from_env()`/`from_settings()` 建出来的组件,注入进来的 transport / recorder / limiter / breaker / cache 一律不碰(由注入方自己关)。
 
+## 1.3.4 推理配置迁移
+
+> [!WARNING]
+> **1.3.4 虽为 patch，升级仍会拒绝部分旧配置。** 已登记但不含 AUTO 的模型不再接受 `ENABLE_THINKING=true`／`REASONING_EFFORT=auto`；受管推理与 raw 控制并存（即使同值）也会拒绝。请先按下表选择显式档或 raw-only，并在受影响调用首次使用新语义前更换缓存 namespace／salt；**只升级包不会自动隔离旧缓存**。
+
+**先明确意图，再在首次新语义缓存读写前切换缓存身份。** `auto` 要求开启但不指定强度，不是 `None`（不表态），也不是库代选付费档位。已登记模型只有清单含 AUTO 才接受 True／auto；nearest 不把 AUTO 映射成强度。未知模型仍尽力＋warning，空开启片段可能零推理字节，不保证开启。完整型号证据见[批准设计 §4/5](research-wiki/designs/2026-09-09-134-thinking-contracts-design.md)。
+
+| 项 | 旧配置／受影响模型 | 用户明确选择的新配置（示例，不是成本推荐） |
+| --- | --- | --- |
+| M1 | MiniMax-M3 True／auto | 删除糖，`REASONING_EFFORT=medium` 可恢复旧 medium 字节；也可选表内其他档 |
+| M2 | deepseek-v4-pro／flash／flash-vision-exp、glm-5.2 True／auto | 删除糖，选 high 或 max；非空开关也不能豁免 AUTO 成员检查 |
+| M3 | glm-5.3／5.3-flash、kimi-k3／kimi-for-coding True／auto | 删除糖，选 low／high／max；nearest 不能修复 AUTO |
+| M4 | gpt-5.4／5.5、claude-opus-5／sonnet-5、gemini-3.1-pro True／auto | 删除糖，可选表内 medium；不可达不能补 AUTO，也不等于 live 证明 |
+| M5 | MiniMax-M2.5／M2.7 True／auto | 仍接受，但 on_base 不再偷带 medium，改为空片段；缓存须迁移。2026-09-09 两型各5轮流式 AUTO 复验通过，不外推到其他模式／渠道 |
+| M6 | qwen 五型、glm-5／5.1／4.6v True／auto | 保留；glm-5／5.1 历史身份不足仍未覆盖，不推及其他型号 |
+| M7 | 未登记模型 True／auto | 可保留尽力；确定保证须先独立取证再登记能力 |
+| M8 | 受管意图＋任一层 raw 推理控制，即使同值／被遮蔽 | 保留受管档并删除源 extra_body、请求 overlay 的控制键；或清空源糖／档和请求意图，仅 raw（applied_effort=NULL） |
+| M9 | 如 glm-5.3，请求 medium，nearest 改 error | 同步更换 namespace／salt；旧身份仍可能回放 nearest 成功，不执行新拒绝 |
+
+M8 包括 reasoning_effort、enable_thinking、thinking、thinking_budget、reasoning、thinkingConfig、output_config.effort 及当前 wire 声明的整个控制根。浅覆盖次序不改，不深合并；自定义 on_base 不能偷带自己的 effort_key 或标准强度字段，点号键仍是顶层字面键。工厂源级拒绝发生在装配期；请求显式档＋已知 raw 可前置拒绝；全量注入默认 transport 在 HTTP 前 RequestRejected，但可能已经准入，沿既有 finally 结算。自定义 transport 由实现方履约。
+
+### 显式缓存身份切换
+
+**不增加**自动 revision、fallback／能力表／wire 版本指纹，不强制所有 chat 冷启动。受影响调用须选从未承载旧语义的 namespace 或 salt；同版本 fallback、能力表或 wire 变化亦须再次迁移。未迁移可能命中旧缓存并绕过新拒绝：这是操作前置，不是自动安全机制。
+
+| 路径 | 切换示例／边界 |
+| --- | --- |
+| 工厂默认 | `PGW_CACHE_NAMESPACE=lab:tenant-a:thinking-134-a`，保留原租户前缀 |
+| per-call 覆盖 | `chat(..., cache_namespace="tenant-a:thinking-134-a", cache_salt="epoch-7")`；只改工厂默认无效 |
+| 请求级档 | M3 示例：源不表态，`chat(..., reasoning_effort="medium", cache_salt="epoch-7:thinking-134-a")` |
+| 全量注入／多源 | 构造参数 cache_namespace 同步切换；共享身份只要一个源受影响，该集合都要隔离或显式拆 scope |
+| 并行／回滚 | 新旧客户端不共用新身份；回滚旧 namespace 会重见旧值，旧键未清理；未来变更不能复用此标记包办 |
+
+### 证据与遥测读法
+
+真实成功尝试记 response.applied_effort；失败尝试记 effective 请求意图（可能零 HTTP）；缓存命中和 scope 终态只记**本次请求级**档，不借历史 applied 或源级补值。embedding、OCR text／layout 成败行均 NULL。实际档分析须排除缓存命中与错误行，未知 AUTO 不证明上游能力。
+
+测试侧默认 FAIL：404 只有请求、唯一尝试、完整无重复键 JSON、error.type=model_not_found 等独立证据全满足才 UNCOVERED；429／5xx／网络／解析错误不整类 skip。成功公共身份缺失无独立证据仍 FAIL；成功 SSE 不新增捕获器。关闭须完整合格轮次全 ABSENT，UNKNOWN 不能靠长度升格成功。不可关闭探测的 OBSERVED 仅支持本条件下未关闭；预期拒绝另按预声明类型、状态、机器字段判定。必需 live 的 SKIP／UNKNOWN／缺轮不因 pytest exit 0 通过发布门。
+
+**本版验收例外（2026-09-09 用户正式批准）**：不再补全模型矩阵；既有失败、UNKNOWN、不可达、缺轮及下游现行配置缺证据如实保留，不改成 PASS。M2 两型的定向成功不代表全模型通过；三项目实际配置迁移仍未核验，合成兼容测试不能代替，缓存迁移操作前置也未被豁免。逐项实测、网络诊断与证据索引见[1.3.4 验证记录](research-wiki/findings/2026-09-09-134-thinking-contracts-validation.md)。
+
+## 1.3.5 逻辑调用统计与失败诊断
+
+> [!WARNING]
+> **升级后失败行会变多,旧的"失败调用数" SQL 会多数。** 每次领域失败除逐次尝试行外另写一条 `terminal_failure` 行;自建 recorder 若未跟进 10 个新参数,会在**装配期**就报错(不是运行期静默丢行)。
+
+本版把治理单位从"一次尝试"补齐到"一次逻辑调用"。两件事: 四种响应带上 `call_stats`;遥测表补 10 列并新增一类行。
+
+### 读 `call_stats`
+
+```python
+resp = await client.chat([{"role": "user", "content": "hi"}])
+stats = resp.call_stats            # EmbeddingResponse / OcrTextResult / OcrLayoutResult 同名字段
+stats.logical_call_id              # 一次逻辑调用一个 ID:重试/换源/重问/分批共享
+stats.attempts                     # 真实打出去的尝试次数(免预算 429 也计;缓存命中为 0)
+stats.total_latency_ms             # 含缓存 IO、退避、准入等待、重问与内联遥测收尾的墙钟
+```
+
+`call_stats` 为 `None` 意为**未知**(如第三方合成的响应、或旧缓存条目回放),不得读成 0。失败时异常对象上**不挂任何统计字段**——要归因请查遥测表。
+
+### 下游 SQL 迁移五项
+
+| # | 改什么 | 理由 |
+| --- | --- | --- |
+| 1 | 计失败调用改成 `WHERE event_kind = 'terminal_failure'` | 一次逻辑调用恰好一条终态行 |
+| 2 | `error IS NOT NULL` 不再是失败调用的判据 | 它同时命中尝试错误行与终态行,升级后计数变大 |
+| 3 | `AVG(latency_ms)` 须按 `event_kind` 分组 | 终态行的 `latency_ms` 是**整个逻辑调用**的总耗时,与单次尝试不同量纲 |
+| 4 | 费用口径**不变** | 终态行 `cost IS NULL`、`usage_source='unavailable'`、token 为 0,不参与 `SUM(cost)` |
+| 5 | 失败行可能带 `http_status_code = 200` | MonkeyOCR 的 `success != true` 就是 200 下的失败,该列不可当成败判据 |
+
+归因查询的典型形态: 一条 `WHERE logical_call_id = :lcid` 同时拿到整池终态原因(`terminal_failure` 行的 `error` / `error_type`)与逐源现场(`attempt` 行的 `source_name` / `http_status_code` / `cause_type` / `error_body`)。**终态行的 `http_status_code`/`cause_type`/`error_body` 恒为 NULL**: 拿最后一个源的现场冒充整池归因是错的。
+
+### 存储侧升级
+
+新增 10 列全部可空、无默认值、追加在现有末列之后(`scope`、`operation`、`logical_call_id`、`event_kind`、`http_status_code`、`error_type`、`cause_type`、`error_body`、`attempts`、`total_latency_ms`),INSERT 字段 26 → 36、物理列 27 → 37。auto 档自动追加;manual 档一条 DDL 不发、按现有列裁剪写入并点名缺列(补列 SQL 由 `telemetry_schema_sql("postgres")` 自取)。**旧行的新列一律 NULL 且不回填**——NULL 表达的是"补列之前根本没记过这件事";滚动升级期新旧进程可写同一张表。
+
+自建 `TelemetryRecorder` 的下游请同步补齐这 10 个 keyword-only 无默认值参数(或改成 `**fields` 形态),并同步自己的 schema 与 INSERT 字段。装配期形状闸只能证明形状能被接受,证不了函数体真的落这些列。
+
 ## 安装
 
 发布在实验室 Gitea PyPI(公开包,匿名可装):
 
 ```bash
 pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
-    "polygateway[redis,postgres,structured]>=1.3.0,<2"
+    "polygateway[redis,postgres,structured]>=1.3.5,<2"
 ```
 
 核心仅依赖 `httpx` + `pydantic`;按需选 extras:
@@ -352,16 +432,20 @@ PGW_TELEMETRY_TEXT_CAP=2000        # 落库正文的字符上限;不设 = 存全
 | 正文体量 | `PGW_TELEMETRY_TEXT_CAP=2000`(按需调);超出部分头部硬切并附 `…(略 N 字)` |
 | 保留期 | 上面的分区模板 + `pg_partman` 的 `retention`,过期分区整块 `DROP` |
 | 访问控制 | 上面的三角色 + `REVOKE UPDATE, DELETE` + `FORCE` RLS |
-| 存量兜底 | 已经攒成一张大普通表、来不及改造分区时,用 `tools/telemetry_retention.py`(默认 dry-run,`--apply` 才动手;探测到分区表会直接退出让路给 `DROP PARTITION`) |
+| 存量兜底 | 已经攒成一张大普通表、来不及改造分区时,用 `tools/telemetry_retention.py`(默认 dry-run,`--apply` 才动手;探测到分区表会直接退出让路给 `DROP PARTITION`;**`--table <schema>.llm_calls` 把目标钉死**,不给则由连接的 `search_path` 推断) |
 
 **`PGW_TELEMETRY_TEXT_CAP` 的覆盖面必须说清,否则合规判断会出错。** cap 落在四处:`messages` 里每条消息的字符串 `content`、多模态 content 数组中 `type == "text"` 的 part 的 `text`,以及 `response` 与 `thinking` 两列。消息侧的这个面与缓存摘要函数 `digest_messages` 一致——**只碰 `content`**,消息里别的字段一概不碰。所以调用方自己塞进 `tool_calls.function.arguments`、`name` 等字段的内容**不在覆盖范围内**:开了 cap 不等于表里没有全文残留。另需知道:缺省是**不截断**(存全文),而截断之后遥测不再是可复现重放的证据。
 
+**1.3.5 新增的两处诊断文本同样不在 cap 覆盖内**:`error_body` 记网关响应正文,沿用库内既有的 `summarize_body` 上限(与 cap 无关,也不随它变化);`error` 在结构化耗尽的终态行上带一段有界说明(修复原因至多 200 字符 + 至多 3 条校验错误 × 200 字符,**不含模型原始正文**),自带独立限长。判断留存面时这两列按各自上限估算,不能算进 cap 的四处。
+
 ### 7. SQLite 侧的保留期
 
 SQLite 侧**不建议**对着一个大库文件跑 `DELETE` + `VACUUM`,而应**按天/按实验轮转库文件**——`runs/<date>.db`、`runs/<experiment>.db` 这样,到期直接删文件。这是三个现有下游(Video-Tree-TRM5 / CHSAnalyzer / dissect)天然就有的形态,比删行省事也安全得多:删文件是 O(1) 且不可能删错行,而 `VACUUM` 会重写整库、期间需要一倍磁盘空间,还会把并发写入方挡在外面。
 
 `tools/telemetry_retention.py` 的 SQLite 分支是给**存量场景**兜底的——已经攒成一个大库、来不及改轮转时用它,不是推荐路径。
 
+**`--apply` 之前先把目标钉死。** 不给 `--table` 时,脚本删哪张表取决于连接的 `search_path`——它的首项是 `"$user"`,故换个角色跑同一条命令,只要库里存在同名 schema 下的 `llm_calls`,删的就是另一张表。`--table <schema>.llm_calls` 让目标由参数精确解析、不再经 `search_path` 推断;表名段固定为 `llm_calls`(本脚本只清理遥测表,不是通用清理器),写别的名字会以退出码 1 被拒。cron 里跑 `--apply` 尤其该给它:那一行配置从此自己说明删的是哪张表。
+
 该脚本**随仓库分发,不在 pip 包内**(它是运维工具而非库能力,库本体不 import 它,也不该拿到 `DELETE` 权限),请从仓库的 [`tools/telemetry_retention.py`](https://gitea.iomgaa.online/iomgaa/PolyGateway/src/branch/main/tools/telemetry_retention.py) 取,用维护角色跑。
 
 ## 错误模型(四分类)
@@ -400,7 +484,7 @@ SQLite 侧**不建议**对着一个大库文件跑 `DELETE` + `VACUUM`,而应**
 
 | 键形态 | 作用 |
 | --- | --- |
-| `{SCOPE}__{PROVIDER}__{N}__{FIELD}` | 第 N 个源;FIELD **全集** = BASE_URL/API_KEY/MODEL/TIMEOUT_S/MAX_CONCURRENCY/RPM/TPM/EST_TOKENS/TTFT_TIMEOUT_S/INTER_TOKEN_TIMEOUT_S/ENABLE_THINKING/MISSING_DONE/TRUST_ENV/EXTRA_BODY(表外的 FIELD 直接报错) |
+| `{SCOPE}__{PROVIDER}__{N}__{FIELD}` | 第 N 个源;FIELD **全集** = BASE_URL/API_KEY/MODEL/TIMEOUT_S/MAX_CONCURRENCY/RPM/TPM/EST_TOKENS/TTFT_TIMEOUT_S/INTER_TOKEN_TIMEOUT_S/ENABLE_THINKING/REASONING_EFFORT/EFFORT_FALLBACK/MISSING_DONE/TRUST_ENV/EXTRA_BODY(表外的 FIELD 直接报错) |
 | `{SCOPE}__GLOBAL__*` | scope 级全局限额(跨源并发/RPM/TPM) |
 | `{SCOPE}__RETRY__*` / `BREAKER__*` / `BACKPRESSURE__*` / `SELECTOR` / `QUOTA_FULL` / `CIRCUIT_OPEN` | per-scope 韧性参数;缺省回落平铺键(`LLM_MAX_RETRIES` 等,兼容旧项目习惯) |
 | `{SCOPE}__BATCH_SIZE` / `NORMALIZE` / `EXPECTED_DIM` | 仅 `EmbeddingClient` 消费;`BATCH_SIZE` 必填(分批是行为关键,不设默认) |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "polygateway"
-version = "1.3.1"
+version = "1.3.5"
 description = "PolyGateway：实验室统一的大语言模型（LLM/VLM/OCR）调度与中转库——多源、限流、重试、熔断、缓存、遥测"
 # registry 包页面的正文只认这一项:缺了页面就是一片空白(1.1.2 的教训,twine 会警告
 # long_description missing 但不阻塞上传)。README 在打包时被固化进产物,发布后再改无效。

research-wiki/ARCHITECTURE.md

@@ -128,6 +128,7 @@ HTTP API → arq 队列 → worker 协程        脚本 → asyncio.gather 协
 **决策**: 借鉴 Clean Architecture 的三条原则——依赖规则(核心不依赖具体技术)、端口与适配器(Protocol 定义接缝)、组装点(所有构造集中注入);**不照搬**其面向应用的四层分层(Entities/Use Cases/Interface Adapters/Frameworks)。库内部的组织模式采用**中间件洋葱**(同 ASGI middleware / gRPC interceptor / Rust tower):重试、限流、熔断、缓存、遥测各为一层,层与层正交,顺序与取舍是配置。
 
 **背景与讨论**: 人类提问"是否借鉴《Clean Architecture》,是否有更好的指导思想"。结论:那本书为应用程序而写,库没有"用例层",硬套四层会造出空转抽象。对库更适配的思想来源:
+
 - **Hexagonal / Ports & Adapters**(Cockburn):三项目已在实践的本质。
 - **《A Philosophy of Software Design》(Ousterhout)的"深模块、窄接口"**:接口复杂度是用户付的成本。落地为——90% 用户三行起步(`from_env()` → `chat()`),全部可配置性经构造函数暴露给需要的人,但绝不强迫简单用户理解。
 - **中间件洋葱**:与治理栈天然同构。反面证据:三项目的 `GovernedLLMClient.chat()` 是约 500 行的方法,五层治理手工内联在一个重试循环里,横切关注点没有被切开,遥测调用因此被迫复制 4 次。洋葱模型下遥测就是一层,只写一次。
@@ -221,6 +222,10 @@ HTTP API → arq 队列 → worker 协程        脚本 → asyncio.gather 协
 
 **职责拆分(2026-08-25,issue #16/#17)**: 上面这条决策里的**推理**部分已从 `providers.py` 移出,落进新模块 `thinking.py`。起因是推理这件事从「请求侧注入什么参数」长成了「请求侧注入 + 响应侧裁定 + 两者对账」三件事,留在注册表里会让 `providers.py` 变成「推理的一切」,一句话说不清职责(P3)。拆后 `providers.py` 只回答**provider 是什么**(`ProviderProfile`、`DEFAULT_PROFILES`、`get_provider`/`register_provider`),`thinking.py` 承载**推理这件事的全部决策**(`ThinkingCapability`、`DEFAULT_CAPABILITIES`、`get_capability`/`register_capability`、`resolve_thinking`、`observe_thinking`、`reconcile_thinking`、`ThinkingUnsupportedError`);纯值类型 `ThinkingObservation` 归最内层 `types.py`(§5.1)。六个公共符号同批提升到包根导出——此前只能深路径 import,而深路径引用正是模块重组会打断下游的原因。
 
+**1.3.4 受管推理契约（2026-09-09 已批准）**：AUTO=要求开启、不指定强度；空 on_base 仅是协议无需开启字节，不是任意模型默认推理。已登记模型必须含 AUTO 才接受 True／AUTO，nearest 不将 AUTO 代选强度；未知模型按已知 wire 尽力＋warning，不保证开启。MiniMax on_base 改空，M3 仍不含 AUTO；M2.5／M2.7 空 wire 真实复验待完成，不新增能力条目。
+
+有受管意图（含 NONE／糖／未知模型）时，source.extra_body 或 request.overlay 任一层出现标准控制根或当前 wire 两向控制根／effort_key 均拒绝，同值和后层遮蔽也不豁免；无意图保留 raw-only，不推断 applied。on_base 不得含自己的 effort_key 或标准 reasoning_effort／output_config.effort，点号仍是字面顶层键，不新增私有方言解释器。工厂源级校验在装配期；chat 仅前置校验显式请求档与已知 raw；默认 transport 对选中源完整校验并在 HTTP 前 RequestRejected，可能已经准入，finally 结算不变。自定义 transport 由端口实现方履约，不新增 preflight。细则与 M1–M9 见[批准设计 §4–5](designs/2026-09-09-134-thinking-contracts-design.md)。
+
 ### D12 零业务假设 + 单向依赖(继承 GovDoc 铁律)
 
 **决策**: 库内禁止出现任何下游业务领域词汇(视频/文书/超声等)与业务 fixtures;扩展点一律 Protocol;import-linter 契约机械化执法(§8)。GovDoc 已证明这套纪律可执行(`pyproject.toml [tool.importlinter]`)。
@@ -372,7 +377,7 @@ flowchart TB
 | `cache_hit` | bool | 是否缓存命中 |
 | `call_id` | str | UUID,每次**尝试**独立 |
 
-新增字段(库扩展,全部带默认值): `source_name`(多源溯源)、`cost`(pricing 换算,可为 None)、`usage_source`(三态,见下)、`structured_data`(D14 阶梯通过后的解析产物;不参与缓存序列化,命中时由 CacheMW 复用 strategy 零网络重建)、`cached_prompt_tokens` 与 `model_reported`(2026-07-31,issue #3,见下)、`thinking_observation`(2026-08-25,issue #16/#17,见下)。
+新增字段(库扩展,全部带默认值): `source_name`(多源溯源)、`cost`(pricing 换算,可为 None)、`usage_source`(三态,见下)、`structured_data`(D14 阶梯通过后的解析产物;不参与缓存序列化,命中时由 CacheMW 复用 strategy 零网络重建)、`cached_prompt_tokens` 与 `model_reported`(2026-07-31,issue #3,见下)、`thinking_observation`(2026-08-25,issue #16/#17,见下)、`applied_effort`(2026-09-05,issue #20,见 §7.5/§7.8 与下文推理档位段:本次**实际**跑在哪一档,`nearest` 映射后与请求档分叉,`None` = 调用方不表态或该路径无推理语义)。
 
 **可观测字段(2026-07-31,issue #3;下游 dissect 的调用审计需求)**:
 
@@ -391,11 +396,13 @@ flowchart TB
 | `absent` | 上游明确上报本次未推理 | `reasoning_tokens == 0`(正面证据) |
 | `unknown` | 本次无任何信号,判不出来 | 两个信号双缺 |
 
+**测试证据边界（1.3.4）**：运行时 UNKNOWN 不告警不等于关闭测试成功。关闭须完整合格轮次全 ABSENT；不可关闭命题在完整合格轮次有 OBSERVED 可支持本条件下未关闭，全 ABSENT 证伪，无 OBSERVED 但 UNKNOWN 仅未覆盖。开启保留完整计划分母与多数 OBSERVED，不丢失败轮。身份缺失只有独立原始 JSON 证据才可归上游；公共身份丢失且无取证 FAIL，成功 SSE 不新增捕获器。默认 FAIL，仅完整请求／唯一尝试／完整无重复键 JSON／404 精确 error.type=model_not_found 可自动 UNCOVERED；一般400、429、5xx、解析与治理异常不整类 skip，预期拒绝另按预声明机器字段断言。逐轮安全报告在 tests/outputs，写失败 FAIL，不增加生产数据面。
+
 三态**不可折叠为布尔**: `unknown`(判不出)与 `absent`(确证没有)语义不同,把前者读作后者正是 `reasoning_tokens=None` 制造的那个歧义——MiniMax-M3 非流式开启推理时,推理内容已计费却不回传正文(2026-08-25 实测 completion 53 vs 关闭档 3),该档只能判 `unknown`,宣称「没推理」即撒谎。缺省取 `UNKNOWN` 使任何不填该字段的路径(非 OpenAI 兼容 transport、失败尝试、终态失败行)天然诚实——**默认值本身不撒谎**,这是 P5 在字段设计上的落法。
 
 判据取 `thinking.strip()` 而非 `bool(thinking)`: transport 收集 `reasoning_content` 时只判 truthy,上游返回纯空白串会被计成「观测到推理」(网关响应是外部输入,校验后使用)。裁定纯函数 `observe_thinking` 定义在 `thinking.py`,由 `openai_compat` 的流式与非流式**两条**组装路径各调一次(只填一条即分叉);`CacheMW._rehydrate` 回放时显式转回枚举实例(JSON 复活的是裸 `str`),域外取值降级为 `unknown` 并单独告警、内容照常复活——纯可观测性字段不该有能力作废内容完好的缓存(多项目共用同一 Redis 时,先升级者写入的新态会让未升级者每次判未命中、覆写回旧值,两版互打缓存);「整条作废」只留给真正破坏内容完整性的失败。该字段**不进缓存 key**——它是结果不是请求。
 
-**声明 × 观测对账(同批)**: `reconcile_thinking` 把请求方向(`enable_thinking`)与实测观测比对,矛盾即 warning、**不抛错**(可观测性属遥测方向,降级即 warning;且一次观测不足以否决一次成功的调用)。四种矛盾各有独立文案: 关闭请求却观测到推理(已登记 / 未登记两说,后者不得声称「能力表声称可关闭」——它根本没登记)、开启却上报未推理、开启却观测不到。`False × unknown` 与 `None × 任意` **不表态**: `unknown` 没有证伪力,拿它报警等于每次关闭调用都喊一遍,噪声即等于没有告警。节流按 per-transport-instance 的 `(source, model, direction)` 集合,与既有 `_warned_models` 同款形态但**不可复用同一个集合**(两者语义不同——一个记「未登记能力已告警过」,一个记「某源某方向的矛盾已告警过」,共用会让两种告警的生命周期纠缠;键空间本就不相交,故不是碰撞问题)。键含源名是因为多源多账号是本库的核心场景: 同一 model 跨 N 个源常态,漏掉源名会让第一个出问题的源喊完之后其余源永久静音,且告警定位不到该查哪个网关(源名在调用点拼进文案,不进纯判定函数的签名)。
+**声明 × 观测对账(同批;判据 2026-09-05 由布尔改档位,issue #20)**: `reconcile_thinking` 把本次**实际发出去的档位**(`effort: Effort | None`,即 `TransportResult.applied_effort`)与实测观测比对,矛盾即 warning、**不抛错**(可观测性属遥测方向,降级即 warning;且一次观测不足以否决一次成功的调用)。四种矛盾各有独立文案: 关闭请求却观测到推理(已登记 / 未登记两说,后者不得声称「能力表声称可关闭」——它根本没登记)、开启却上报未推理、开启却观测不到。判据必须写成 `effort is Effort.NONE` 的**身份比较**才落「要求关闭」一支,其余任何档(含 `auto`)落「要求开启」一支——`Effort.NONE` 的取值是非空串 `"none"`,任何靠真值性的写法(`if not effort`)恒为假,会把每个强度档送进关闭分支、告警方向整个颠倒。`none × unknown` 与 `None × 任意` **不表态**: `unknown` 没有证伪力,拿它报警等于每次关闭调用都喊一遍,噪声即等于没有告警。节流按 per-transport-instance 的 `(source, model, 生效档位)` 集合(第三段 2026-09-05 由 `enable_thinking` 改为**实际发出的档**: 同一模型的 low 与 max 是两个独立的矛盾,共用一个键会让第二个永久静音;而档位根本不经过 `enable_thinking` 那个字段,不改就是同一模型的所有档共用一个键),与既有 `_warned_models` 同款形态但**不可复用同一个集合**(两者语义不同——一个记「未登记能力已告警过」,一个记「某源某方向的矛盾已告警过」,共用会让两种告警的生命周期纠缠;键空间本就不相交,故不是碰撞问题)。键含源名是因为多源多账号是本库的核心场景: 同一 model 跨 N 个源常态,漏掉源名会让第一个出问题的源喊完之后其余源永久静音,且告警定位不到该查哪个网关(源名在调用点拼进文案,不进纯判定函数的签名)。
 
 这条对账的价值在于把「能力表过期」从**静默错觉**变成日志里的显式告警——能力表过期是必然事件(M3 的 evidence 曾停在 8-02 整整 23 天),成本是一次枚举比较。但**保障只覆盖可观测路径**: M3 非流式两个信号双缺,那里的推理开关哪天失效库同样看不见,这一点不得假装有。
 
@@ -524,12 +531,16 @@ flowchart TB
 
 ### 7.5 响应缓存
 
-**key 公式**: `sha256(canonical_json({model, messages_digest, namespace, salt, sampling}))`,前缀 `pgw:cache:`。
+**1.3.4 显式迁移前置（D3）**：key 与源指纹不新增包版本、语义 revision、fallback、能力表或 wire 版本。AUTO／raw／MiniMax 语义变更及同版本 fallback／能力表／自定义 wire 改变时，受影响调用集合必须在首次读写前切到从未承载旧语义的 namespace 或 salt。保留租户前缀与 epoch；覆盖工厂默认、全量注入和 per-call（只改默认对覆盖路径无效）。同一共享缓存身份只要一源受影响，整个调用集合须隔离或由下游显式拆分；不强制未受影响 chat 冷启动。新旧版本不共享新身份，回滚旧身份会重见旧值。**未迁移仍可能回放旧响应、绕过新拒绝**，库不会自动检查新可满足性；操作说明不能当自动防护。
+
+**key 公式**: `sha256(canonical_json({model, messages_digest, namespace, salt, sampling, reasoning_effort}))`,前缀 `pgw:cache:`。
 
 - `messages_digest`: 文本部分原文参与;多模态 content part(base64 图像等)先各自 sha256 摘要再参与——修正 Video-Tree 把整段 base64 进 hash 的开销问题,且 key 稳定性不变。
 - `namespace`: 必填(项目名/租户 id),修正 GovDoc 缓存 key 缺租户隔离与多项目共用 Redis 时的互相毒化风险。
 - `salt`: 可选,跨 epoch 强制重采样(Video-Tree 需求)。
 - `sampling`(2026-07-31,issue #4): 调用级采样参数,**仅非空时参与**(注意与 `salt` 的"仅非 None"不同——空串是有意义的 salt,而空采样参数与不传无差别),故空 overlay 时旧键逐字不变、存量缓存不冷启动。读 `request.sampling` 而非 `request.overlay`,不依赖"CacheMW 恰在 StructuredMW 外侧"的层序巧合。**不进 key 的后果**: 同 messages 跑 5 个 seed 会全部命中第一次的响应,标准差恒为 0 且不报错——受控实验静默作废。源级 `extra_body` 同理并入 `model_fingerprint`(全源皆空时字面量不变,否则追加 `|sha256(...)`,摘要对象是各源 `(model, extra_body)` 的 canonical JSON 排序去重——按模型而非源名,改源名不误触冷启动)。
+- `reasoning_effort`(2026-09-05,issue #20): **请求级**档位,仅 `is not None` 时参与(判据不能用真值性——`Effort.NONE` 是「明确要求不推理」,与 `None`「不表态」拿到的是两种响应,合并即毒化)。它不能靠 `model_fingerprint` 代劳: 后者是**装配期**算出的集合级指纹,同一个 client 上跑 low 与 max 在它眼里毫无分别,不进 key 就是 issue #4「5 个 seed 全命中同一响应」的逐字翻版。**源级** `reasoning_effort` 则与 `enable_thinking` 同规则并入 `_fingerprint_mark`(仅表态时追加,故全源不表态时字面量逐字不变、存量缓存不冷启动;两者取值域不相交,`"none"`/`"low"`… vs `true`/`false`,追进同一个列表不会摘要成同一身份)。
+- **key 记的是请求档,不是 `nearest` 映射后的生效档**: `CacheMW` 在洋葱里比 transport 更外一层,查缓存时 `resolve_thinking` 尚未执行,生效档根本拿不到。副作用是被映射到同一档的两个请求各占一个缓存槽(存两份相同响应,浪费但不毒化)。**由此的已知边界**: 能力表更新导致映射结果变化时(如某模型新增 `minimal` 档),请求档算出的 key 不变而实际发出的字节变了,会命中按旧映射存下的响应——能力表版本不进 `model_fingerprint` 是既有取舍的延续(provider 表与能力表都不在指纹里),要求严格隔离的调用方应换 `cache_namespace` 或 `cache_salt`。
 - **两条已知副作用**: ① 逐 rollout 变化的 `seed` 进 key 后该路径天然全部 miss(正确语义,但缓存对它不再省钱);② `model_fingerprint` 是**集合级**指纹而非本次选中源的指纹,同 scope 各源 `extra_body` 不同时仍可能返回另一源的响应(既有取舍的延续,与 `model` 同),要求逐源可复现应让每源独享 scope 或 namespace。
 - value = `LLMResponse` 的 JSON;TTL 必填且 > 0(禁止永不过期,继承 Video-Tree 校验);Redis 不可用 → get 返回 None、set 吞异常记 warning(静默降级)。**只缓存成功响应**;`ResultInvalidError` 的原始响应不缓存(避免固化坏结果)。
 
@@ -539,7 +550,7 @@ flowchart TB
 
 ### 7.7 多源与选源
 
-`SourceConfig`: name/provider/base_url/api_key/model/超时组/限额组(单源并发/RPM/TPM)/`est_tokens`(TPM 预扣量的**可选调优覆盖**,移植 CHS `config.py:55`;2026-07-20 缺口 G2 补,2026-07-30 由必填降为可选)/enable_thinking/`extra_body`(2026-07-31 issue #4: 本源恒定的采样参数,构造期校验保护键后转 `MappingProxyType`;**该字段令 SourceConfig 不再 hashable**——加任何 mapping 字段的固有代价,库内无以源作 dict key/set 元素的写法,要可变副本用 `dict(...)`、要改字段用 `dataclasses.replace`)。聚合自环境变量 `{SCOPE}__{PROVIDER}__{N}__{FIELD}`(§9)。
+`SourceConfig`: name/provider/base_url/api_key/model/超时组/限额组(单源并发/RPM/TPM)/`est_tokens`(TPM 预扣量的**可选调优覆盖**,移植 CHS `config.py:55`;2026-07-20 缺口 G2 补,2026-07-30 由必填降为可选)/enable_thinking/`reasoning_effort` 与 `effort_fallback`(2026-09-05 issue #20: 前者是本源默认推理档位,`None` = 不表态、`Effort.NONE` = 要求不推理,构造期与 `enable_thinking` 语义矛盾即 `ValueError`;后者取 `error`(缺省)或 `nearest`,决定请求档打空时报错还是映射到最近档)/`extra_body`(2026-07-31 issue #4: 本源恒定的采样参数,构造期校验保护键后转 `MappingProxyType`;**该字段令 SourceConfig 不再 hashable**——加任何 mapping 字段的固有代价,库内无以源作 dict key/set 元素的写法,要可变副本用 `dict(...)`、要改字段用 `dataclasses.replace`)。聚合自环境变量 `{SCOPE}__{PROVIDER}__{N}__{FIELD}`(§9)。
 
 **TPM 有效预扣量(2026-07-30,est_tokens 解耦设计,G2 闭环)**: `try_acquire`(§7.3)传入的 est 来自 `SourceConfig.effective_est_tokens()` 这一份纯方法,五个调用点(`QuotaGate` 入场 + chat/embedding 各自的成功侧与失败侧结算)共用,保证预扣与结算恒取同一值(`delta == 0`,否则押金会被整笔退回、TPM 闸退化成进门即放行)。规则:显式 `est_tokens > 0` 则原样用;否则 `tpm > 0` 时派生 `max(1, tpm // 60)`;`tpm == 0`(该闸不启用)时为 0。
 
@@ -551,14 +562,39 @@ flowchart TB
 
 ### 7.8 遥测与成本
 
-**必录字段**(继承三项目 15 字段规范): call_id、parent_call_id、session_id、model、provider、source_name、messages(JSON)、response、thinking、prompt_tokens、completion_tokens、usage_source、latency_ms、ttft_ms、max_inter_token_ms、cache_hit、error、**cost**、**cached_prompt_tokens**、**model_reported**、**sampling**、**reasoning_tokens**、**tenant_id**、**meta**、**thinking_observation**。
+**必录字段**(继承三项目 15 字段规范;当前 36 个 INSERT 字段,物理表列 37 = 36 + 数据库自填的 `created_at`,两套口径的区分见 `telemetry/schema.py` 模块 docstring): call_id、parent_call_id、session_id、model、provider、source_name、messages(JSON)、response、thinking、prompt_tokens、completion_tokens、usage_source、latency_ms、ttft_ms、max_inter_token_ms、cache_hit、error、**cost**、**cached_prompt_tokens**、**model_reported**、**sampling**、**reasoning_tokens**、**tenant_id**、**meta**、**thinking_observation**、**reasoning_effort**、**scope**、**operation**、**logical_call_id**、**event_kind**、**http_status_code**、**error_type**、**cause_type**、**error_body**、**attempts**、**total_latency_ms**。
 
-**`sampling` 列(2026-07-31,issue #4,端口 20 → 21)**: 列语义 = 「调用方采样意图 ⊎ 生效源 `extra_body`」的 canonical JSON,空则 NULL。**不含**结构化注入的 `response_format`——列名是采样参数,schema 不是,且数 KB schema 逐行落库会让审计表无谓膨胀。三个 emit 入口口径必须各自定死,否则同一列在不同行含义不同: `emit_attempt`(RetryMW 调用,**唯一**有生效源者)并上 `source.extra_body`;`emit_cache_hit` / `emit_terminal_failure`(TelemetryMW 最外层调用)无 source 可言,只记调用级——与 `model`/`source_name` 在终态行置空是同一先例,且缓存命中行无损(`sampling` 已进缓存 key,能命中即意味调用级参数与历史那次逐字相同)。三者统一读 `request.sampling` 而非 `request.overlay`(后者在 RetryMW 处已被结构化注入污染、在 TelemetryMW 处未被污染,直接用必然三行分叉)。OCR/embedding 路径因决策 G 剥离 `extra_body`,该列恒 NULL。
+**`sampling` 列(2026-07-31,issue #4,端口 20 → 21)**: 列语义 = 「调用方采样意图 ⊎ 生效源 `extra_body`」的 canonical JSON,空则 NULL。**不含**结构化注入的 `response_format`——列名是采样参数,schema 不是,且数 KB schema 逐行落库会让审计表无谓膨胀。三个 emit 入口口径必须各自定死,否则同一列在不同行含义不同: `emit_attempt`(RetryMW 调用,**唯一**有生效源者)并上 `source.extra_body`;`emit_cache_hit` / `emit_terminal_failure`(前者由 TelemetryMW 最外层调用,后者自 1.3.5 起由三个 client 的公开边界经 `emit_terminal_once` 统一写出)无 source 可言,只记调用级——与 `model`/`source_name` 在终态行置空是同一先例,且缓存命中行无损(`sampling` 已进缓存 key,能命中即意味调用级参数与历史那次逐字相同)。三者统一读 `request.sampling` 而非 `request.overlay`(后者在 RetryMW 处已被结构化注入污染、在 TelemetryMW 处未被污染,直接用必然三行分叉)。OCR/embedding 路径因决策 G 剥离 `extra_body`,该列恒 NULL。
 
 **`reasoning_tokens` 列(2026-08-11,issue #6,端口 21 → 22)**: 推理 token 已计入 `completion_tokens`,故成本总额一直是对的——这不是计费缺口而是**归因**缺口:缺了它,"这次调用花的钱里有多少花在推理上"无法区分,也就无从判断某个 scope 该不该关推理。供应商不报时记 NULL 而非 0(不可得 ≠ 为零,与 `usage_source='unavailable'` 同一纪律)。
 
 **`tenant_id`/`meta` 两列(2026-08-17,issue #11,端口 22 → 24)**: 见 §5.2 的调用方维度追加。两列都是 `TEXT NOT NULL DEFAULT ''`(`meta` 在 PG 是 `JSONB DEFAULT '{}'`),**缺省落哨兵而非 NULL**——PG 的 RLS `USING` 表达式对返回 false **或 NULL** 的行一律隐藏且不报错,故 NULL 的 `tenant_id` 不是"未归属",是对所有人永久不可见的黑洞;哨兵空串可被 `COUNT(*) WHERE tenant_id = ''` 一条 SQL 审计出历史欠账。PG 11+ 加带非易失默认值的列不重写全表,SQLite 加列是元数据操作且硬性要求 `NOT NULL` 列有非 NULL 常量默认值——三条约束在这个写法上同时满足。补列走既有 `_BACKFILL` 路径,失败仍只逐行降级、不判死。
 
+**`reasoning_effort` 列（1.3.4 四种行来源澄清，不改 schema）**：TEXT 可空，NULL 与明确要求不推理的 `'none'` 不同。只有真实成功尝试读 transport 的 response.applied_effort（nearest 后，不重算）；AUTO 是编码选择，不是服务端内部强度，未知 AUTO 不构成能力验证，raw-only 为 NULL。
+
+| 行类型 | 来源／限制 |
+| --- | --- |
+| 真实成功尝试 | response.applied_effort；未知／raw-only 限制如上 |
+| 失败尝试 | effective_effort（请求＞源＞糖）的意图，可能零 HTTP，不能称实际发出 |
+| cache_hit | 本次请求级 reasoning_effort，不读历史 applied、不推源级；观测回放历史，不是本次实测 |
+| scope 终态失败 | 本次请求级 reasoning_effort，可能尚未选源，不补逐次根因 |
+
+实际档分析须 `cache_hit=false AND error IS NULL`。embedding／OCR text／layout 的成功与失败尝试由 reasoning_applies=False 保证 NULL，真实 client→emitter→临时 SQLite 与 chat 阳性共同守卫，不能用空行集合证明。生产 emitter 单一出口、端口字段数和 DDL 不变。
+
+**逻辑调用十列(2026-09-09,issue #19/#23,端口 26 → 36)**: 本版把治理单位从"一次尝试"补齐到"一次逻辑调用"。十列按同一顺序追加在 `reasoning_effort` 之后,全部可空、无默认值、不回填旧行(NULL 表达的是"补列之前根本没记过这件事",与任何哨兵值不同;这一点与 `tenant_id` 故意相反——后者是 RLS 可见性需要哨兵,前者是归因需要区分真实缺口)。
+
+| 列 | 语义 |
+| --- | --- |
+| `scope` | 池名,`TelemetryEmitter` 构造期注入(三个 client 各一行),三类行都带;**不拿 `source_name` 顶替**(终态失败可能根本没选出源) |
+| `operation` | `chat` / `embed` / `recognize_text` / `parse_layout`,**由调用点给定**。它与 `PolyGatewayError.operation` 是两个语义: 后者是异常自报的出错环节(可为 `download_result` 这类子步骤),链路上任何位置不得读它来填本列 |
+| `logical_call_id` | 一次逻辑调用一个 ID;上下文缺席(库内现场构造的请求)落 NULL,**不造 ID** |
+| `event_kind` | 三态: `attempt` / `cache_hit` / `terminal_failure`,三类行的唯一机械判据 |
+| `http_status_code` / `cause_type` / `error_body` | 只在失败的 `attempt` 行上非空(成功行不统一填 200: 那会让"有状态码"不再等价于"失败了");终态行三列恒 NULL(**C1 红线**) |
+| `error_type` | 该行自身错误的类名;取消路径传字符串,故为 NULL |
+| `attempts` / `total_latency_ms` | 只属终态行(同一份冻结快照,与该行 `latency_ms` 同值),其余两类行 NULL |
+
+两条不变量: **I3** —— 每次领域失败至多一条终态行(`_CallContext.claim_terminal()` 去重;recorder 写失败仍只 warning,故 SQL 可见 ≤ 1);**I4** —— 非领域异常(编程错)**零条**终态行、原样传播、分类不被改写。终态行仍 `cost=NULL`、`usage_source='unavailable'`、token 0,费用聚合口径不变。诊断值的提取收敛在 Emitter 内一个纯 helper(`_error_fields`),只读领域异常的既有属性,**不遍历任意对象、不解析字符串猜诊断**。另立**装配期形状闸**: 旧签名 recorder 在构造 `TelemetryEmitter` 时当场 `ValueError`——降级方向的铁律管的是**运行期写失败**,装配错误放行的后果是下游 100% 丢遥测且调用照常成功。
+
 **`thinking_observation` 列(2026-08-25,issue #16/#17,端口 24 → 25)**: 落 `LLMResponse.thinking_observation` 的裸取值(`observed` / `absent` / `unknown`,两端均为可空 `TEXT`),语义见 §5.1。它补的是 `reasoning_tokens` 补不上的那一格: 后者为 NULL 时「没推理」与「没上报」不可区分,而供应商停报 `completion_tokens_details` 是会真实发生的事(MiniMax 这一路 2026-08-25 实测已停报,qwen 与 deepseek 在同一网关同一 key 上照常返回),届时按 `reasoning_tokens IS NULL OR = 0` 统计「未推理」会把推理了的调用一并算进去。有了本列,口径改为按本列取值分组,`unknown` 独立成一档而不再被并进「未推理」。
 
 **recorder 收到的必须是裸 `str` 而非枚举实例**: `TelemetryEmitter` 的 `_AttemptUsage` 内部持 `ThinkingObservation` 类型,`_record` 下沉时取 `.value`。`StrEnum` 虽是 `str` 子类,asyncpg 的参数编码对 `str` 子类不保证接受,而遥测写失败只降级为一条 warning——这类问题不会当场炸,只会让 Postgres 那一路悄悄少一列数据。归一化放在 emitter 侧,与 `tenant_id`/`meta`/`sampling` 由 emitter 定型后再交 recorder 是同一分工(recorder 只落库,不做语义判断)。列序纪律同上: 新列排在最末,两端 DDL 与两份 backfill 同步。
@@ -567,7 +603,7 @@ flowchart TB
 
 **schema 单一事实源、档位与冲突目标(2026-08-19,issue #13,决策见 D15)**: 列序、两端 DDL、两端补列语句、`INSERT` 构造与缺列告警收敛进 `telemetry/schema.py`——此前在两个 recorder 各存一份,而公共函数 `telemetry_schema_sql` 打印给下游的 SQL 必须与库真正执行的 DDL **同源**,三份必然漂移,漂移的表现是"下游照打印的 SQL 建完表,库仍报缺列"。补列自此由 `PGW_TELEMETRY_SCHEMA_MODE` 控制(三态: 不设按后端派生 sqlite→auto / postgres→manual,显式设置两侧均可覆盖): manual 档一条 DDL 都不发,改为按探测到的现有列**裁剪 `INSERT`**(裁剪是关掉 ALTER 的前提,否则缺列旧表每行写入都被拒 = 遥测全失)并发**一条**点名缺列、附可执行 SQL 的 warning;auto 档行为不变,且补列失败时**不裁剪**(该档承诺"把列补上",补不上就让缺列以逐行 warning 暴露)。**库内执行的补列语句与打印给人的那份是两套文本**: 库内不用 `ADD COLUMN IF NOT EXISTS`(它即便列已存在也先取 ACCESS EXCLUSIVE 锁,故库侧一律先探测后 ALTER),打印的那份带,以保证下游可重复执行。同批把 PG 写入的 `ON CONFLICT (call_id) DO NOTHING` 改为**无冲突目标**的 `ON CONFLICT DO NOTHING`: 带目标的语句要求恰好匹配 `(call_id)` 的唯一约束,而 PG 要求分区表的唯一约束必须包含分区键——按 `created_at` 分区(issue #12)后主键变成 `(call_id, created_at)`,该语句被 PG 直接拒收,而写失败只逐行 warning,表现为分区部署下遥测全线静默丢数据;无目标版本在两种表形态上都合法,普通表上语义逐字等价(表上只有主键这一个唯一约束),SQLite 的 `INSERT OR IGNORE` 本就无目标。
 
-**正文截断(2026-08-19,issue #12)**: `PGW_TELEMETRY_TEXT_CAP` 给落库正文一个可配置的字符上限,**缺省不设 = 不截断**(人类决策 E-a): 截断后的遥测不再是审计证据,也无法拿原样的请求复现与重放,而这正是既有下游在依赖的行为,默认改动即破坏;代价是 issue 那句"无限期保留全部租户全文不应是默认状态"只被解决一半——默认仍是全文,但下游第一次有了不写全文的手段。截断落在 `TelemetryEmitter._record`(全库唯一遥测出口,单一 helper 铁律)内,位于 `digest_messages` 之后、`json.dumps` 之前,作用面四处: 每条消息的字符串 `content`、多模态 part 中 `type == "text"` 的 `text`、`response`、`thinking`;超出部分头部硬切并附 `…(略 N 字)`。**按每条文本切而不是切整串 JSON**——后者会往不做任何校验的 TEXT 列里写进非法 JSON,让此后一切按 JSON 解析该列的分析全废。**且只产出新对象、绝不就地修改**: `digest_messages` 对非 list 的 `content` 原样透传同一个 dict 对象,就地截断会同时污染调用方持有的 messages、后续重试的请求体与缓存写入的 key 且全程无报错——红线由"cap 开与关两态下 `build_cache_key` 输出逐字节相同"的测试钉死。覆盖面须诚实声明: 只碰 `content`(与 `digest_messages` 处理面一致),调用方放进 `tool_calls.function.arguments` 等字段的内容不在其中。embedding 与 OCR 两条链路各自既有的 200 字符上限保留不动,与新 cap 是取更严者的关系。
+**正文截断(2026-08-19,issue #12)**: `PGW_TELEMETRY_TEXT_CAP` 给落库正文一个可配置的字符上限,**缺省不设 = 不截断**(人类决策 E-a): 截断后的遥测不再是审计证据,也无法拿原样的请求复现与重放,而这正是既有下游在依赖的行为,默认改动即破坏;代价是 issue 那句"无限期保留全部租户全文不应是默认状态"只被解决一半——默认仍是全文,但下游第一次有了不写全文的手段。截断落在 `TelemetryEmitter._record`(全库唯一遥测出口,单一 helper 铁律)内,位于 `digest_messages` 之后、`json.dumps` 之前,作用面四处: 每条消息的字符串 `content`、多模态 part 中 `type == "text"` 的 `text`、`response`、`thinking`;超出部分头部硬切并附 `…(略 N 字)`。**按每条文本切而不是切整串 JSON**——后者会往不做任何校验的 TEXT 列里写进非法 JSON,让此后一切按 JSON 解析该列的分析全废。**且只产出新对象、绝不就地修改**: `digest_messages` 对非 list 的 `content` 原样透传同一个 dict 对象,就地截断会同时污染调用方持有的 messages、后续重试的请求体与缓存写入的 key 且全程无报错——红线由"cap 开与关两态下 `build_cache_key` 输出逐字节相同"的测试钉死。覆盖面须诚实声明: 只碰 `content`(与 `digest_messages` 处理面一致),调用方放进 `tool_calls.function.arguments` 等字段的内容不在其中。embedding 与 OCR 两条链路各自既有的 200 字符上限保留不动,与新 cap 是取更严者的关系。**1.3.5 新增的两处诊断文本同样不在 cap 覆盖内**: `error_body` 沿用 `summarize_body` 的既有上限,结构化耗尽终态行的 `error` 说明自带有界限长(`repair=` 至多 200 字符 + `validation=` 至多 3 条 × 200 字符,**不含 `raw_text`**——模型正文的预算已由 attempt 行的 `response` 列承担)。两段限长常量与 `StructuredMW` 重问反馈共用同一份(`format_bounded_errors`),数值只有一份定义。
 
 - 后端: `SQLiteRecorder`(默认;WAL + busy_timeout、`INSERT OR IGNORE` 幂等、`asyncio.to_thread` 桥接、初始化/写入失败全降级不冒泡)与 `PostgresRecorder`。
 - **单一 helper 铁律**: 遥测调用点收敛为一个内部函数/上下文管理器;Video-Tree 与 GovDoc 各有 4-5 处逐字复制的 `record_llm_call(15 个参数)` 是本条的直接教训。

research-wiki/designs/2026-08-26-issue18-pg-test-isolation-design.md

@@ -0,0 +1,234 @@
+---
+type: design
+node_id: design:2026-08-26-issue18-pg-test-isolation
+title: "issue #18: 隔离靠权限强制,目标靠显式声明"
+date: 2026-08-26
+---
+
+# issue #18：隔离靠**权限强制**，目标靠**显式声明**
+
+> 类型：design｜日期：2026-08-26｜状态：待 Codex 审 → 人类审
+> 事实基础见 `findings/2026-08-26-issue18-shared-pg-test-isolation.md`（本文所有实测引用均出自该文）。
+> 两处需人类拍板的取舍已于 2026-08-26 会话中确认：`--table` **纳入**；7 条写真表的用例**全迁**；`public.llm_calls` 里那 11 行历史孤儿行**不清理**。
+
+## 1. issue #18 的诊断只对了一半
+
+issue 判定"行数断言依赖共享实例的当下状态"，方向对；它推荐的首选处置（标 `slow`，交发布清单统一跑）**不解决问题**——标 `slow` 只是把假红挪出日常关卡，而这条断言还有另一半失效：
+
+| 失效方向 | 表现 | 标 `slow` 之后 |
+|---|---|---|
+| 假红 | 外部进程写/删共享表 → 断言红，脚本无辜 | 挪到发布关卡，**照样红**，只是红得更少人看见 |
+| **假阴** | 外部插入与脚本误删互相抵消 → 行数相等 → 静默放行 | **原样保留** |
+
+这条断言守的是"脚本静默删了共享的真表"。假阴才是它真正的代价，而 `slow` 对假阴毫无作用。
+
+## 2. 根因三层
+
+| 层 | 事实 | 后果 |
+|---|---|---|
+| L1 | `_public_count` 是全套件唯一一处**全表口径**断言，而同文件的 `_RUN_PREFIX` 机制从设计上就假定"多个进程并行写同一张表" | 两套前提互斥，偶发红是必然而非意外 |
+| L2 | 一个**安全属性**（脚本不越界）被编码成对**全局可变量**（真表行数）的观测 | 假红 + 假阴，结论既不可靠也不可否证 |
+| L3 | 之所以只能这么写：`telemetry_retention.py` 的目标表由连接的 `search_path` 隐式决定（`to_regclass('llm_calls')`），**调用点无法声明"我要删哪张表"** | 测试没有别的手段表达"只许动这张表"，只好退回事后观测 |
+
+L3 不是测试的问题，是脚本契约的问题——它同时是生产风险：`search_path` 默认首项是 `"$user"`，换个角色跑同一条命令，只要库里存在同名 schema 下的 `llm_calls`，删的就是另一张表。脚本现有的应对是把解析结果打印出来，但那行打印与 `DELETE` 在同一次运行里，中间没有人。
+
+## 3. 设计主张
+
+1. **安全属性由数据库权限强制，不由断言观测**——测试跑脚本用的角色对 `public.llm_calls` 无任何权限，越界不是"会被发现"，而是"做不到"。
+2. **目标表由调用方声明**——`--table SCHEMA.NAME` 给出后，目标不再经 `search_path` 推断。
+3. **测试与真实共享表完全脱钩**——`public.llm_calls` 从此零测试触碰，隔离手法收敛为"临时 schema"一种，并由 lint 门机械化守住。
+
+## 4. 变更 A：`telemetry_retention.py` 新增 `--table SCHEMA.NAME`
+
+### 4.1 语义：声明即目标，不是"声明后比对"
+
+两种可能的实现要先分清：
+
+| | 做法 | 结果 |
+|---|---|---|
+| 否决 | 仍按 `search_path` 解析，再与声明比对，不符则退出 | 目标**仍然**由环境决定，`--table` 只是一道确认；且要为"不符"发明第四个退出码语义 |
+| **选定** | 给了 `--table` 就用 `to_regclass('"schema"."name"')` **精确解析**，绕开 `search_path` | 目标真正由参数决定；不存在则落入既有的"目标表不可用"语义 |
+
+选定做法的实现落点只有一处——`_purge_postgres` 里 `to_regclass($1)` 的入参从裸 `TABLE` 换成引号限定名，分区探测、统计、分批 DELETE 全部不变（它们本就用解析结果拼 `qualified`）。
+
+三条支撑它的 PG 语义已实测（PostgreSQL 16.14，见 finding §7）：`to_regclass('"schema"."llm_calls"')` 正常解析；**schema 不存在时返回 NULL 而不抛错**；引号限定名**区分大小写**（`"PGWPROBE_S_X"."llm_calls"` → NULL）。前两条决定了"找不到"能落进既有的退出码 2 而不需要新分支，第三条决定了 §4.2 的"逐字比较"是可实现的。
+
+### 4.2 参数与校验
+
+| 规则 | 行为 | 理由 |
+|---|---|---|
+| 仅 `--backend postgres` 接受 | sqlite 给了 `--table` → 退出 **1** | 与 `--batch-size` 同款；SQLite 库文件即目标，无 schema 概念，无歧义可消 |
+| 必须是**两段**限定名 | `--table llm_calls` → 退出 **1**，提示写成 `schema.表名` | 单段等于没声明，隐式性原样保留 |
+| **表名段必须逐字等于 `llm_calls`** | `--table audit.events` → 退出 **1**，消息点明本脚本只清理 `llm_calls` | 见 §4.4：不加这条，`--table` 会把本脚本从"遥测表清理器"扩成"任意同形表删除工具" |
+| 两段均非空;**schema 段须为普通标识符**(`[A-Za-z_][A-Za-z0-9_$]*`) | 不合法 → 退出 **1** | 复杂标识符（含引号的表名）不支持，此时退回不给 `--table` 的路径；写进 `--help`。**本行原写作"均不含 `.` 与 `\"`"，实现阶段核出"段内含 `.`"是不可达分支**——按 `.` 切分后恰好两段是前置条件，`a.b.c` 走的是"不是恰好两段"那条消息，故删去该半句 |
+| **逐字比较，不做大小写折叠** | 传 `_quote()` 包裹的限定名给 `to_regclass` | catalog 里存的是真实标识符；未加引号建的表在 catalog 中是小写。折叠会与"引号标识符区分大小写"的真实语义打架 |
+| 解析不到 | 退出 **2**，消息点名"显式指定的表 X 不存在"，并附一句"PG 中未加引号建的标识符在 catalog 里是小写" | 与 `search_path` 找不到的消息**分开写**：诊断方向不同。**退出码维持 2 而非 1**：`Public.llm_calls` 格式合法，找不到是环境事实而非参数非法——把它归成 1 会让"schema 真的不存在"这类该告警的情形被调度器当成不必重试的参数错误。大小写这类高频手误由消息文本消化，不由退出码 |
+| 无权限 | 后续 `COUNT` 抛 `PostgresError` → 既有 except → 退出 **2** | 无需新增分支 |
+
+退出码不新增。`1` 留给"参数写错了，重试也没用"，`2` 留给"环境不对，值得告警"——这条分界是脚本已有的对调度器契约（见 `_Parser.error` 的注释），本变更沿用。
+
+### 4.3 目标白名单：为什么表名段不可变
+
+`--table` 若只校验"两段、非空、无点无引号"，一次手误 `--table audit.events` 就会让脚本对一张**恰好也有 `created_at` 与 `tenant_id` 列**的业务表执行同一套 COUNT + 分批 DELETE。脚本的名字、`--help`、退出码 3 的分区提示、README 的定位全都是围绕遥测表 `llm_calls` 写的，它从未声称自己是通用清理器；让参数悄悄扩大作用域，是在一个**默认 dry-run、拿 DELETE 权限跑**的脚本上开一个静默的口子。
+
+故 `--table` 的可变部分只有 schema 一段。**为什么不干脆改叫 `--schema`**：cron 配置里的那一行必须自解释——运维读 crontab 时看到 `--table public.llm_calls` 就知道全部目标，看到 `--schema public` 还得回去查脚本常量才知道表名。多出的那条校验不是冗余，它本身就是"本脚本的作用域到此为止"的显式声明，且错误消息可以当场把边界告诉用户。
+
+### 4.4 未声明时的提示
+
+`--apply` 且未给 `--table` 时，在"目标表: x.y"之后补一行：
+
+```
+注意: 目标表由连接的 search_path 推断得到。要把目标钉死,请加 --table <schema>.<表名>。
+```
+
+只在 `--apply` 时打：dry-run 不可逆性为零，且它本就以"看清楚再决定"为用途，多一行提示是噪音。
+
+## 5. 变更 B：测试角色化——把安全网换成权限边界
+
+### 5.1 模型
+
+**凡是启动 `telemetry_retention.py` 子进程的用例，一律用临时登录角色跑，无一例外**——包括正向的 apply/dry-run/分区让路用例。只给"最坏情况"那一条用低权限角色是自欺：正向用例才是带 `--apply` 真删数据的那些，它们若仍用 `.env` 的 superuser DSN 跑，一旦 `search_path` 或 `--table` 出问题，删的就是真表，而新设计里已经没有行数快照会发现它。
+
+每个这样的用例临时建一个**登录角色** `tmp`，并 `CREATE SCHEMA s AUTHORIZATION tmp`，表由 `tmp` 自己建。于是：
+
+- `tmp` 是那张表的**属主**——与脚本文档要求的"用维护角色跑"形态一致，测的不是一个失真的现场
+- `tmp` 对 `public.llm_calls` 一无所有：实测 ACL 为 `{app=arwdDxt/app, chs3_test=ar/app}`，无 PUBLIC 授权
+
+**必须换角色的原因**：`.env` 里的 `app` 实测 `rolsuper = true`，superuser 无视一切权限检查，用它跑则这条防线不存在。无 `CREATEROLE` 权限的环境 `skip`（项目既有惯例，见 `least_privilege_dsn`）。
+
+防线已实测：临时角色裸连（`search_path = "$user", public`）对真表执行 `COUNT` 与 `DELETE`，两者均 `InsufficientPrivilegeError: permission denied for table llm_calls`。
+
+**约束：角色名与 schema 名必须错开。** 实测 `CREATE SCHEMA X AUTHORIZATION X` 时，`"$user"` 会命中自有 schema 并**遮蔽 public**——今天 `least_privilege_dsn` 正是同名形态。同名虽多一层巧合式防护，却让 §5.3 的最坏情况用例根本走不到 public，等于测了个假现场。故 `pg_sandbox` 一律用 `pgw_s_<uuid>` / `pgw_r_<uuid>` 两套名字。
+
+### 5.2 最坏情况从"事后观测"变成"确定性红灯"
+
+| 情形 | 旧 | 新 |
+|---|---|---|
+| `search_path` 失效，脚本落到 `public` | 事后数行数，可能被并发抵消 | 数据库拒绝 → 退出 2 → 测试红，**且一行都删不掉** |
+| 外部进程并发读写 `public` | 直接假红 | 与测试无关（不再读 `public`） |
+
+`_public_count` / `before_public` / 那条 `assert` 整体删除。
+
+### 5.3 新增一条"最坏情况"用例，替代被删掉的安全网
+
+用属主角色的 DSN **不挂 search_path** 跑脚本（于是解析走 `"$user", public`，角色同名 schema 不存在 → 落到 `public.llm_calls`），不给 `--table`：
+
+- 断言退出码 **2**、stderr 非空且点名 `llm_calls`、临时表内容一行未变
+- **不断言 PG 的英文错误原文**（服务端 `lc_messages` 不由测试掌握），也**不出现 `public.llm_calls` 字面量**（见 §7 的 lint 门）
+- 库里没有 `public.llm_calls` 的环境上，脚本报"找不到表"同样退出 2 —— 两条路都绿，用例不因环境而摇摆
+
+这条用例把"最坏情况"钉成确定性的红/绿，且完全不观测共享状态。
+
+## 6. 变更 C：7 条用例迁出 `public`
+
+| 用例 | 迁移后验的东西 |
+|---|---|
+| `TestSchema::test_schema_has_frozen_columns_in_order` | **变强**：现在验的是本机那张被历史 `_BACKFILL` 补过列的老表，迁到 fresh schema 后验的是**库当前 DDL 建出来的表** |
+| `TestObservabilityColumns::test_values_round_trip` | 不变（只要求表存在） |
+| `TestSchema::test_call_id_idempotent` / `test_concurrent_writes_all_land` | 不变（与表在哪无关） |
+| `TestDegradation::test_row_failure_does_not_poison_later_rows` / `test_aclose_idempotent` | 不变 |
+| `TestPoolFootprint::test_pool_does_not_preconnect_and_stays_within_pool_max` | 不变（验的是连接数），但**必须保留唯一 `application_name`**，见下 |
+
+### 6.1 `_RUN_PREFIX` 有两个职责，只能删掉其中一个
+
+| 职责 | 落点 | 处置 |
+|---|---|---|
+| call_id **行隔离** | `_cid()` 的 63 处调用、5 处 `LIKE '<前缀>%'` 过滤、`dsn` fixture teardown 的 `DELETE` | 删除——schema 隔离已完全取代它 |
+| **`application_name` 唯一** | `test_pool_does_not_preconnect_and_stays_within_pool_max` 用它标记本池连接，再查 `pg_stat_activity` 数连接数 | **保留**（就地生成 uuid）——连接是**实例级**共享资源，schema 隔离对它无效；改成固定名字会把并行进程的连接数进来，等于把偶发红从表层搬到连接层 |
+
+删除行隔离用途时调用点做**机械替换**（`_cid("c1")` → `"c1"`），不改任何断言语义；5 处 `LIKE` 过滤逐条在计划里列出并单独验证。
+
+### 6.2 顺带封掉一个仓库自己已记载的隐患
+
+`test_schema_has_frozen_columns_in_order` 今天查的是 `information_schema.columns WHERE table_name='llm_calls'`，**不带 schema 过滤**——库里任何一个残留的临时 schema 里的同名表都会污染结果。这不是推测：`production_template` 的 `except BaseException` 分支注释里已经写明了这个坑（"会被残留物在下一次运行里以列数不符的形态误伤"），当时的处置是让另一处 fixture 清理得更干净。迁移时补上 `table_schema = $1`，把它从"靠别人不留残留"改成"自己只看自己"。
+
+**用函数级而非 module 级 sandbox**：建/删一个 schema 是毫秒级，7 条用例的开销可忽略；module 级共享会把"用例之间互不影响"这条重新变成需要论证的事。
+
+## 7. 变更 D：`conftest.py` 收敛 + lint 门
+
+### 7.1 一个沙箱工厂取代七处样板
+
+`tests/integration/conftest.py` 新增：
+
+| fixture | 职责 |
+|---|---|
+| `pg_admin_dsn`（session） | 读 `.env`、缺失 `skip`、库名守卫（只许 `polygateway`）。**命名下划线语义上属内部**，用例不该直接用 |
+| `pg_sandbox`（function，工厂） | `await pg_sandbox(ddl=..., extra=(), owner_role=False)` → 返回 frozen dataclass（`schema` / `dsn` / `role`）；teardown 按 LIFO 统一 `DROP SCHEMA CASCADE` + `DROP OWNED BY` + `DROP ROLE` |
+
+三条硬约束（缺一条工厂就会自己变成污染源）：
+
+1. **资源逐步登记，`except BaseException` 清理**：建角色成功、建 schema 失败时不会走到 `yield`，普通 teardown 不执行，角色就永久留在实例上（角色是**全局**对象，不随库消失）。`production_template` 已有同款先例，工厂必须继承它而不是简化掉。
+2. **uuid 后缀取 12 位十六进制**：8 位在并行会话下碰撞概率虽低却非零，而碰撞的后果是 `CREATE ROLE` 失败或误清理别人的残留。加长的成本为零。
+3. **admin DSN 不做成 fixture**：改为模块私有函数，只被工厂内部调用。做成 fixture 就等于把一个能 `DELETE FROM public.llm_calls` 的连接摆在所有用例面前，"用例不该直接用"只是纪律不是机制。
+
+今天这套样板在两个文件里重复**七处**（`legacy_schema`、`pre_tenant_schema`、`fresh_schema`、`partitioned_schema`、`least_privilege_dsn`、`least_privilege_pre_tenant_dsn`、`production_template`，加 retention 侧两处）。收敛后清理逻辑只有一份——今天任何一处 teardown 写漏，残留都落在共享库里。
+
+### 7.2 机械化执法
+
+`make lint` / `make check` 各加一步：
+
+```
+tests/ 下不得出现字面量 public.llm_calls —— 命中即 exit 1
+```
+
+§5.3 的用例已按"不出现该字面量"设计，故门无需豁免名单——**注释与 docstring 同样不例外**，现有多处"共享的 public.llm_calls"措辞改写为"共享表 `llm_calls`"。豁免名单一旦开口，门就退化成建议。
+
+**这道门是烟雾报警器，不是隔离证明。** 它拦不住 `f"{schema}.{table}"` 拼接、`to_regclass($1)` 参数化、或不带限定名的 `DELETE FROM llm_calls` 配上 admin 的默认 `search_path`。真正的隔离来自两处：工厂 API 不把 admin DSN 交出去（§7.1 约束 3），以及脚本以无权角色运行（§5.1）。文档里必须这样写，否则下一个人会拿这道门当"tests 零触碰 public"的证明。
+
+## 8. 明确不做
+
+| 不做 | 理由 |
+|---|---|
+| 标 `slow` | §1：对假阴无效；改完之后这条用例的成败不再取决于外部服务状态，它**应该**留在日常关卡里 |
+| 建临时数据库（而非 schema） | PG 的 schema 对 DML/DDL 已是完备隔离；建库只换来"孤儿库更难清、需 CREATEDB、断连才能 DROP"三项成本 |
+| 清理 `public.llm_calls` 里那 11 行孤儿行 | 人类决策：那是与迁移项目共用的表，本次不动 |
+| 给 SQLite 分支加 `--table` | 库文件即目标，无歧义（§4.2） |
+| 动 Redis 集成测试 | 实测已是每用例 uuid 命名空间/scope，无全表口径断言，不属同类 |
+| 把 `--table` 做成必填 | 会打断下游既有 cron，属破坏性契约变更 |
+
+## 9. 残余风险（本设计**不**覆盖，需明写而非默认解决）
+
+| 风险 | 为什么不在本设计覆盖范围 | 缓解 |
+|---|---|---|
+| fixture / teardown 里用 admin 连接手滑写真表 | admin 连接必须存在（建 schema/角色本身就需要它），权限边界对它无效 | 工厂不把 admin DSN 交给用例；§7.2 的门能拦住字面量形态 |
+| 进程被 `SIGKILL` 时 pytest finalizer 不执行，残留 schema/角色 | 任何进程内机制都做不到 | 命名固定前缀 `pgw_s_` / `pgw_r_`，残留可一条 SQL 查出（`SELECT nspname FROM pg_namespace WHERE nspname LIKE 'pgw%'`）；**不做自动 TTL 清理**——并行会话下"清理别人的残留"会误删正在跑的 schema，比残留本身更危险 |
+| 共享实例上其他项目往真表写/删 | 不归本库管 | 改完之后本仓库测试对它完全不敏感，这正是本设计的目的 |
+| `production_template` 仍以管理身份执行不带限定名的 `DELETE` / `DROP TABLE` | 它有意不收敛进工厂（§7.1 末段），三角色与分区语义是它自己的 | 独立验证实测：它的连接 `search_path` **只有**自己那个 schema（`public` 不在路径里），故 `to_regclass('llm_calls')` 返回 `None`——search_path 一旦失手，报的是"关系不存在"而不是静默打到共享表 |
+| `pg_catalog_probe` 持管理连接 | 工厂自测需要查 catalog 核对残留，这个能力删不掉 | 探针只接受 `SELECT` 开头的语句（有用例钉住）;它不交出 DSN，故越界能力止于只读查询 |
+
+## 10. 版本号与发布
+
+**1.3.2**（patch）。需在 CHANGELOG 里如实写明：`tools/` 与 `tests/` **都不在 pip 包内**（README 已声明脚本随仓库分发），故 1.3.2 的 wheel 与 1.3.1 在库代码上逐字节相同，本版的对外内容是**运维脚本的契约扩展**与测试确定性，不是库能力更新。不得包装成库更新。
+
+发布按 CLAUDE.md §4.4.1 九步全走，其中与本变更直接相关的：README 需补 `--table` 用法与安装版本约束核对；`make wiki-check` 需在合并前跑过；合并后在 main 上补跑 `pytest -m slow`。
+
+## 11. 验收标准
+
+| # | 判据 | 验证方式 |
+|---|---|---|
+| 1a | `--table` 的**参数分类**：sqlite 互斥、非两段、空段、含点/引号、表名段非 `llm_calls` —— 各自退出 1 | 单测（`tests/unit/test_retention_tool.py`，无需 PG） |
+| 1b | `--table` 的**真实解析行为**：显式指向 sandbox 表成功删除；指向不存在的 schema → 2；指向无权表 → 2；指向分区表 → 仍 3 | **集成用例（必须真连 PG）**——单测只能验参数分类与拼出的目标字符串，验不了 `to_regclass` 的真实语义 |
+| 2 | 未给 `--table` 且 `--apply` 时打印推断提示 | **集成用例**断言 stdout —— 该提示行只在 PG 分支打印，不连库的单测触发不到它（本行原写作"单测断言 stdout"，计划阶段核出该判据不可执行，就地更正） |
+| 3 | 最坏情况（search_path 落到 public）**删不掉任何行**且退出 2 | §5.3 新用例 |
+| 4 | 整套 `tests/integration` 连跑三次全绿，其间 `public.llm_calls` 行数由外部任意变动 | 连跑 + 期间手工改动共享表行数 |
+| 5 | `tests/` 下 `public.llm_calls` 零命中 | `make lint` |
+| 6 | 迁移未削弱任何用例：7 条用例的断言逐条对照迁移前后 | 计划阶段逐条列表，verifier 复核 |
+| 6b | `test_pool_does_not_preconnect...` 仍持有唯一 `application_name` | 代码复核 + 两进程并发跑该用例 |
+| 6c | `test_schema_has_frozen_columns_in_order` 带 `table_schema` 过滤 | 故意在库里留一个残留同名表，用例仍绿 |
+| 6d | 沙箱工厂 setup 中途失败不留角色/schema | 注入一个会失败的 DDL，跑完查 `pg_namespace` / `pg_roles` 无 `pgw_%` 残留 |
+| 7 | 全套件 + `-m slow` 全绿 | 合并前 |
+
+## 12. 审查留痕（Codex，2026-08-26）
+
+报 6 项实质问题，**全部采纳**，其中两项为阻断级：
+
+| # | 意见 | 处置 |
+|---|---|---|
+| 1 | **阻断**：`--table` 未限定表名段，会把脚本扩成"任意同形表删除工具"（`--table audit.events` 且该表恰有 `created_at`/`tenant_id` 时真删数据） | 采纳，见 §4.2 新增规则与 §4.3 |
+| 2 | **阻断**：只给"最坏情况"用例换低权限角色，正向 apply 用例仍用 superuser 跑，则新安全网对最危险的那条路径不生效 | 采纳，§5.1 改为"凡启动脚本的用例一律用临时角色，无一例外" |
+| 3 | `_RUN_PREFIX` 有第二个职责（`application_name` 唯一），机械删除会让连接池用例失去并发隔离 | 采纳，§6.1；本会话的独立清点也得出同一结论 |
+| 4 | `test_schema_has_frozen_columns_in_order` 的 `information_schema` 查询不带 schema 过滤 | 采纳，§6.2；核实属实，且仓库注释已记载该坑 |
+| 5 | 沙箱工厂 setup 中途失败不清理、uuid 后缀偏短、admin DSN 做成 fixture 等于把越界能力摆在所有用例面前 | 采纳，§7.1 三条硬约束 |
+| 6 | lint 门只防字面量，不能当"零触碰"的证明；`--table` 的验收不能只靠 unit | 采纳，§7.2 定位改写 + §11 拆出 1a/1b |
+
+**一处处置与建议不同**：Codex 认为 `Public.llm_calls` 这类大小写手误落到退出 2 属"告警误分类"，建议归 1。本设计维持 2，理由写在 §4.2——该参数格式合法，能否解析到是环境事实；归 1 会让"schema 真的不存在"这类该重试告警的情形被调度器当成不必重试的参数错误。手误由错误消息文本消化。

research-wiki/designs/2026-09-04-reasoning-effort-design.md

@@ -0,0 +1,357 @@
+# 推理档位一等化设计(issue #20 及其一般形式)
+
+> **替代指针（2026-09-09）**：§3–6／8／12 的 AUTO 无条件放行、MiniMax 内置 medium、受管 raw 覆盖与缓存迁移／遥测总括语义，以[1.3.4 已批准设计](2026-09-09-134-thinking-contracts-design.md) §4–8 为准。历史调研与实验事实保留，不倒改为新语义已验证。
+
+- **日期**: 2026-09-04
+- **状态**: **2026-09-04 人类已批准**(经 Claude 自审 → Codex 独立审 → 人类审批门)
+- **触发**: issue #20 —— 智谱无 profile,下游只能手写 `extra_body`,本库为推理准备的三道机制被**静默**绕过
+- **影响面**: `SourceConfig`/`ChatRequest` 公共类型、`ProviderProfile`/`ThinkingCapability` 公共类型、`resolve_thinking`/`reconcile_thinking` 公共函数、缓存 key 公式(ARCH §7.5)、遥测端口(25 → 26 字段)、`.env` 键
+- **人类拍板(2026-09-04)**: 作用域取「源级默认 + 请求级覆盖」;档位不支持时「默认报错、可显式开映射」;不可关闭时「报错并给可执行替代」
+- **人类复核(2026-09-04,针对 Codex 异议)**: `effort_fallback` 的最近档映射**要实现**,不因当前无已知消费者而推迟;方案选择标准 = 架构可维护性/清晰度 > 代码简洁 > 鲁棒性
+
+---
+
+## 1. 问题不是 issue #20 说的那个
+
+issue #20 的字面诉求是补一条 `zhipu` profile。补上它**不能**解决它自己描述的失败,因为二态 bool 在新一代模型上无档可填。
+
+2026-09-04 调研,四份独立注册表(cherry-studio 客户端注册表、OpenRouter `/models` 的 `reasoning` 字段、LiteLLM 模型元数据、我们自己的网关 new-api `relaykit/relayconvert/reasoning/`)与六家官方文档,三条结论直接推翻 issue #20 的建议:
+
+| # | 结论 | 证据 |
+| --- | --- | --- |
+| 1 | **GLM-5.3 官方强制推理**,`thinking.type` 只接受 `enabled`;官方档位 `low/high/max`,`none` **不是**它的档位 | 智谱官方文档;cherry `toggle:false`;OpenRouter `mandatory:true` 三源一致 |
+| 2 | **`medium` 只在 GPT-5.x / Claude 5 / Gemini 3 三家存在** | 见 §8 档位表 |
+| 3 | 不可关闭不是孤例: GLM-5.3 系、Gemini 3 Pro / 3.1 Pro 为 mandatory;MiniMax M2.x **接受 `disabled` 但不生效** | 官方文档;与本库 2026-08-02 实测一致 |
+
+第 1 条意味着 issue #20 建议的 `can_disable=True` 不能登记:我们发出去的 `reasoning_effort:"none"` 是个**未定义值**,智谱按自己的方式处理(多半当最低档)。这正好解释 issue #20 自己观测到的「短提示词 rt≈1.2,5552 token 长上下文跳到 0/54/167」——低档本来就要想,只是短提示词下想得少。
+
+第 2 条意味着现有 `minimax` profile 那条「`thinking_on` 统一取 medium」的约定,推广到 GLM/kimi/deepseek 上全部是空档。
+
+**真实缺口**: `enable_thinking: bool | None` 这个类型表达不了现实。补数据不能修复类型。
+
+## 2. 现状审计(旧行为逐条处置)
+
+替换 `thinking.py` 的请求侧决策,响应侧与对账基本保留。逐条声明:
+
+| # | 现有行为 | 处置 |
+| --- | --- | --- |
+| 1 | `enable_thinking` 三态: None 不注入 / True 注入 on / False 注入 off | **保留**语义,降为 `reasoning_effort` 的语法糖(§4.2) |
+| 2 | `ProviderProfile.thinking_on/off` 两个固定片段,`None`=形态未知 | **替换**为 `ThinkingWire`(§3.3);`None`=未知的语义**保留**。**判据须按请求档位取相关字段**(旧版 `slot = thinking_on if enable_thinking else thinking_off` 即如此)——初稿 §4.1 Phase 2 写成「只看 `on_base`」是错的: 那会让「关闭形态已知、开启形态未知」的自定义 provider 在请求 `none` 时被误拒,且指路指向它已经做过的 `register_provider`,比不指更糟(2026-09-05 独立验证查出) |
+| 3 | `ThinkingCapability.can_disable: bool` | **替换**为 `supported_efforts`;`can_disable` 成为 `'none' in supported_efforts` 的派生(§3.2) |
+| 4 | `evidence: str` 强制附实测出处 | **保留**,且强化: 初始表全部标注「文档推定,待实测」 |
+| 5 | `resolve_thinking` 四道关卡(不表态/形态未知/能力未登记/不可关闭) | **保留四关的顺序与语义**,判据从 bool 换成档位(§4.1) |
+| 6 | 能力未登记 → warning 后尽力注入 | **保留**(新模型不该被库挡住,ARCH §5 R4) |
+| 7 | `observe_thinking` 多信号裁定三态 | **保留**,不改一行 |
+| 8 | `reconcile_thinking` 声明 × 观测对账,矛盾返回文案、不抛错 | **保留**,判据扩展到档位(§4.3) |
+| 9 | transport 按 `(source, model, direction)` 节流告警 | **替换**: 节流键的 `direction` 换成生效档位——同一模型 low 与 max 是两个独立的矛盾 |
+| 10 | `ThinkingUnsupportedError(ValueError)`,由 transport 翻译为 `RequestRejectedError` | **保留**,新增的档位错误走同一条路 |
+| 11 | `_build_payload` 中 `resolve_thinking` 结果先于 `extra_body`/`overlay` | **保留**(顺序即优先级,issue #4 决策 A) |
+| 12 | 缓存 key 不含任何推理参数 | **修复**(§5,现存缺口) |
+| 13 | 遥测无档位列 | **新增**一列(§6) |
+
+**有意放弃**: 无。第 3 条的 `can_disable` 是唯一的破坏性变更,迁移见 §12。
+
+## 3. 数据模型
+
+### 3.1 档位词汇
+
+八档封闭枚举,取四家参考实现共同收敛的词汇(cherry / OpenRouter / LiteLLM / new-api 用的是同一套):
+
+```python
+class Effort(StrEnum):
+    NONE = "none"; AUTO = "auto"          # 不推理 / 推理但档位由模型自定
+    MINIMAL = "minimal"; LOW = "low"; MEDIUM = "medium"
+    HIGH = "high"; XHIGH = "xhigh"; MAX = "max"
+```
+
+`none` 即「不推理」,与强度档同处一个词汇表——这是关键的表达力来源: 「能不能关」不再是独立的布尔,而是 `none` 在不在该模型的支持列表里。
+
+`auto` 不可省(自审补): newapi 上 26 个模型里有 9 个是**纯开关型**(qwen 五个、MiniMax-M3、glm-5/5.1/4.6v),它们能开推理但没有档位名可填。没有 `auto` 就只能拿某个强度档冒充「开」,而那正是现有 `thinking_on` 硬编码 `medium` 的病根。`auto` 的 wire = `on_base` 不附 `effort_key`,恰好等于旧的 `thinking_on` 行为。四家参考实现都有这一档(cherry 的 canonical selection `'default'|'none'|'auto'|Effort`;new-api 的 `ModeAdaptive`)。
+
+`Effort` 归 `types.py`(最内层纯值类型),与 `ThinkingObservation` 同处一处,理由相同: 它是 `SourceConfig`/`ChatRequest` 的字段类型,定义在决策模块会让 `types.py` 反向 import。
+
+### 3.2 `ThinkingCapability`: 能力(按 model)
+
+```python
+@dataclass(frozen=True)
+class ThinkingCapability:
+    supported_efforts: tuple[Effort, ...]   # 顺序 = 由弱到强
+    evidence: str
+```
+
+**不设 `default_effort` 字段**(Codex 审查采纳): 初稿有此字段,唯一消费者是「`enable_thinking=True` 等价于哪档」;自审把该语法糖改成 `Effort.AUTO` 后它就没有消费方了——§4 不用它决策,§6 遥测在不表态时记 `NULL`(库并不观测模型内部默认档,记推定值等于把「没看见」说成「发生了」,违既有纪律)。厂商默认档是**文档知识**,写进 `evidence` 文本即可,不必升格为必须逐模型维护的 API 字段(P1 YAGNI)。
+
+三个派生量,不单独存字段(存了就会漂移):
+
+| 派生 | 定义 | 用途 |
+| --- | --- | --- |
+| `can_disable` | `Effort.NONE in supported_efforts` | 兼容旧语义 |
+| `cheapest_effort` | 除 `none` 外的第一档 | 不可关闭时的可执行替代(§4.1 Phase 5) |
+| 是否档位型 | 除 `none`/`auto` 外仍有 ≥1 档 | 决定告警文案(纯开关型不该说「可选档位」) |
+
+OpenRouter 与 LiteLLM 两家**独立收敛到了同一形状**(`supported_efforts`+`default_effort` / `reasoning_effort_levels`+`default_reasoning_effort`),这是「档位清单即能力」这一形状可靠的旁证。我们只取其前半——两家都是**面向展示**的目录(要在 UI 上显示默认档),本库是**执行**路径,默认档不参与任何判定,故不设该字段。
+
+### 3.3 `ProviderProfile`: 形态(按 provider)
+
+```python
+@dataclass(frozen=True)
+class ThinkingWire:
+    off: Mapping[str, Any] | None      # 关闭档的片段;None = 该 provider 无关闭形态
+    on_base: Mapping[str, Any] | None  # 开启档的固定部分;None = 形态未知
+    effort_key: str | None             # 档位写进哪个键;None = 该 provider 无档位概念
+```
+
+`ProviderProfile.thinking_on/thinking_off` 由 `thinking: ThinkingWire` 取代。`None` 表示「未知」这一语义原样保留(issue #5 的核心成果,不可退回)。
+
+四个形态样例(经 new-api 中转的口径):
+
+| provider | off | on_base | effort_key |
+| --- | --- | --- | --- |
+| zhipu | `{"thinking":{"type":"disabled"}}` | `{"thinking":{"type":"enabled"}}` | `reasoning_effort` |
+| qwen | `{"enable_thinking": False}` | `{"enable_thinking": True}` | `None`(无档位,只有 toggle) |
+| openai / anthropic / google | `{"reasoning_effort":"none"}` | `{}` | `reasoning_effort` |
+| minimax | `{"reasoning_effort":"none"}` | `{}` | `reasoning_effort` |
+
+### 3.4 为什么不需要 cherry 的 endpoint contract 与 wireDialect
+
+cherry 有两层我们**明确不做**:
+
+1. **endpoint-keyed 的 per-model wire 覆盖**。它需要这层,是因为同一模型在 `openai-chat` / `openai-responses` / `anthropic-messages` / `google-generate-content` 四种协议下形态不同。**本库只有一个 chat transport(`openai_compat.py`)**,所有请求都是 OpenAI 兼容形态,跨协议转换由 new-api 在服务端完成(它自己就有一层 canonical intent,见 `relaykit/relayconvert/reasoning/intent.go`)。一个协议 = 一层形态。
+2. **`wireDialect` 代际方言**(Claude 4.6+ `adaptive` vs ≤4.5 `budget_tokens`;Gemini 3 `thinkingLevel` vs 2.x `thinkingBudget`)。这是**原生协议**才有的问题;我们发 OpenAI 形态的 `reasoning_effort`,代际差异由网关吸收。
+
+同理,`glm-5.2`(有 `none` 档)与 `glm-5.3`(无 `none` 档)**共用同一份 wire**——差别落在 capability 的 `supported_efforts` 上。本库既有的「形态按 provider、能力按 model」分层,恰好容纳档位而无需新增一层。
+
+## 4. 解析
+
+### 4.1 `resolve_thinking`: 五道关卡
+
+判定顺序即语义。前三关是既有的,判据从 bool 换成档位;**Phase 4「可执行替代」是新增的**,Phase 5 是既有第 4 关的档位化推广。
+
+| Phase | 条件 | 结果 |
+| --- | --- | --- |
+| 1 | 生效档位为 `None`(调用方不表态) | 返回 `{}`,不注入 |
+| 2 | **该请求档所需的**形态未知(请求 `none` 看 `wire.off`,其余档看 `wire.on_base`;`none` 方向须 `off` 与 `on_base` **皆为 `None`** 才算「整体形态未知」——单 `off is None` 是「该 provider 关不掉」,归 `_inject` 说清缺的是哪半边,2026-09-05 实现时补正) | `ThinkingUnsupportedError`,指路 `register_provider`/`extra_body` |
+| 3 | 能力未登记 | warning 后按 wire 尽力注入,**不校验档位** |
+| 4 | 请求 `none` 而该模型无 `none` 档 | `ThinkingUnsupportedError`,**给出 `cheapest_effort` 作为替代** |
+| 5 | 其余档位不在 `supported_efforts` 且未开映射 | `ThinkingUnsupportedError`,列出该模型可选档 |
+
+**4 必须先于 5**(自审补): `none` 只是 5 的一个特例,若让它落进 5 的通用分支,报错就退化成「不支持 none,可选 low/high/max」——丢掉了「这个模型根本关不掉」这个关键信息与可执行替代。
+
+Phase 4 的文案是本设计的一个交付物,而非装饰:
+
+> 模型 'glm-5.3' 无法关闭推理(官方 `thinking.type` 只接受 enabled);最省的档是 'low',请配 `LLM__ZHIPU__1__REASONING_EFFORT=low` 或调用时传 `reasoning_effort=Effort.LOW`。evidence: ...
+
+理由: 该分支若只报错不给出路,下游会去找 `extra_body` 那条绕过的路——**那正是 issue #20 的成因**。报错必须带可执行替代,否则等于把用户推回起点。
+
+映射(Phase 5 的逃生口)默认关闭,由 `SourceConfig.effort_fallback="nearest"` 显式开启,按 `supported_efforts` 的顺序取最近档并 warning。
+
+> **Codex 审查异议与人类复核**: Codex 指出本项当前无可复验的消费者,引入它要带来配置项、映射算法、warning 口径与测试面。人类 2026-09-04 复核后**确认实现**——理由是这条逃生口的价值不取决于今天有没有人用它:换模型是常态,而「换完就跑不起来」与「换完静默涨价」之间需要一个下游可以显式选择的中间档。故本项**随本期一并实现**,含映射方向、warning 口径与测试。默认关闭的理由是钱: 一次静默的 `medium→max` 在 GLM-5.3 上是数倍账单,「严禁默认值掩盖错误」(P5)在此有真金白银的含义。
+
+### 4.2 生效档位的优先级
+
+```
+request.reasoning_effort > source.reasoning_effort > source.enable_thinking(语法糖) > None
+```
+
+`enable_thinking` **保留不删**(它已被三项目消费,迁移兼容约束见 ARCH §5.1),降级为语法糖:
+
+| 旧写法 | 等价于 |
+| --- | --- |
+| `enable_thinking=False` | `reasoning_effort=Effort.NONE` |
+| `enable_thinking=True` | `reasoning_effort=Effort.AUTO`(注入 `on_base`,不附档位),不依赖能力表 |
+
+**`True` 的等价性分两种**(2026-09-04 实现时发现,更正初稿「与旧行为逐字节等价」的说法):
+
+| provider 类型 | 旧 `thinking_on` | 新 `AUTO` 注入 | 是否等价 |
+| --- | --- | --- | --- |
+| `on_base` 完整表达「开」(qwen/deepseek/zhipu/moonshot) | `{"enable_thinking": True}` 等 | 同左 | **逐字节等价** |
+| 靠档位表达「开」(openai/anthropic/google) | `{"reasoning_effort": "medium"}` | `{}`(不注入) | **行为变更** |
+| 同上但**默认不推理**(minimax) | `{"reasoning_effort": "medium"}` | 同左(2026-09-05 回退) | **逐字节等价** |
+
+第一行是**有意的**: 旧版那个 `medium` 是库替下游做的档位判断(profile 注释自己承认「取 medium 是因为它是五档里语义最接近厂商正常强度的一档」),而 `medium` 在 GLM/kimi/deepseek 的档位表里根本不存在——正是本设计要消灭的东西。语义仍是「开」(这三家的模型经 OpenRouter 登记默认即推理),只是不再强制一个档;要指定强度请显式配 `REASONING_EFFORT`。须进 CHANGELOG 的行为变更条目。
+
+**第三行是 2026-09-05 的回退(issue #21,人类拍板的最小修复)**: 上述「语义仍是开」依赖「模型默认就推理」这个前提,T10 真实网关实测证明 MiniMax-M3 不满足它——不发任何推理参数时 5/5 轮不推理。故 `minimax` 段的 `on_base` 改回 `{"reasoning_effort": "medium"}`,存量 `ENABLE_THINKING=true` 的行为逐字恢复。这是权宜之计: 正解是让 `auto` 受能力表约束(模型不支持「由模型自定」时报错并指路显式档位),属公共行为变更,下一版处理。
+
+**同源同时配 `enable_thinking` 与 `reasoning_effort` 且语义矛盾**(如 `True` + `none`)→ **构造期 `ValueError`**。不做「后者赢」的静默兜底: 两个字段表达同一件事时,矛盾是配置错误,不是优先级问题。
+
+### 4.3 `reconcile_thinking`: 对账扩展
+
+现有对账只判「要求关闭却观测到推理」与「要求开启却未推理」。档位化后新增一类可判定的矛盾:
+
+- 请求 `none`、模型登记 `can_disable=True`、却观测到 `OBSERVED` → 既有文案,**保留**(这正是 issue #20 第 3 条要恢复的机制)。
+- 请求非 `none` 档、观测到 `ABSENT` → 既有文案,保留。
+- **不做**「档位高低与 `reasoning_tokens` 多少的对账」: 档位与 token 数没有可判定的函数关系(issue #20 自己的数据里 glm-5.3-flash 的 medium 档 rt 在 8~56 之间跳),拿它报警必然是噪声。这条留给 §11 的压测,不进库。
+
+### 4.4 归一化不变式(实现期补,2026-09-05)
+
+库内一切档位判定都是 `is Effort.X` 的身份比较,故**每条能让档位进入库内的入口都必须先归一**
+(`types.coerce_effort`)。裸字符串不归一的后果不是报错而是**静默判否**——`("none" is Effort.NONE)`
+恒假,于是「已关闭」被当成「没表态」。
+
+已知三条入口,缺一即漏:
+
+| # | 入口 | 归一点 |
+| --- | --- | --- |
+| 1 | `.env` / `from_env()` / `from_settings()` | `config._cast` 委托 `coerce_effort` |
+| 2 | 构造函数全量注入 `SourceConfig(...)` 与 `chat(reasoning_effort=...)` | `SourceConfig.__post_init__` / `chat()` 入口 |
+| 3 | **缓存命中回放** `LLMResponse.applied_effort` | `CacheMW._coerce_applied_effort` |
+| 4 | **公共函数 `resolve_thinking()` 直调** | 函数入口自行 `coerce_effort`(2026-09-05 独立验证查出) |
+
+第 3 条是 T8 加 `applied_effort` 字段时才浮现的: 响应进 Redis 走 JSON,`StrEnum` 存成裸串,
+命中回放时类型已丢。与 `thinking_observation` 当年的坑**逐字相同**(见 issue #16/#17),故按同一
+先例处置: 域外取值降级为 `None` 且**不作废整条缓存**——多项目共用 Redis 时互相打缓存是老问题,
+为一个可观测字段丢掉整条响应不划算。
+
+第 4 条是本次换代**自己造出来的**: 该函数在 `__all__` 里,第三参数由 `bool` 换成 `Effort` 后,下游最自然的写法就是从 JSON/配置读出来的裸串 `"low"`。不归一则 `_inject` 撞 `.value` 抛 `AttributeError`——一个未文档化、不属四分类的异常。
+
+新增第五条入口时(新工厂、新 transport 参数、新的反序列化路径)必须同样过 `coerce_effort`。
+
+## 5. 缓存 key
+
+**更正一个误判(Codex 审查指出)**: 源级 `extra_body` 与 `enable_thinking` **早已进 key**——经 `build_model_fingerprint` 的 `_fingerprint_mark`(`client.py`),由 issue #4/#5 落地,ARCH §7.5 有明文。本设计**不存在**先前稿本断言的「现存毒化缺口」,那是把 `CacheMW` 只读 `request.sampling` 误当成了全部 key 来源。
+
+真正需要处置的是两处,均因请求级档位而新增:
+
+| 层 | 处置 | 理由 |
+| --- | --- | --- |
+| 源级 `reasoning_effort` | 并入 `_fingerprint_mark`,与 `enable_thinking` 同规则(**仅表态时**追加) | 与既有一致;全源不表态时指纹字面量不变,存量缓存不冷启动 |
+| 请求级 `reasoning_effort` | 进 `build_cache_key`,仅非 `None` 时参与 | `model_fingerprint` 是**装配期**算的集合级指纹,覆盖不到逐调用变化的值。不进 key 则同 messages 跑 low 与 max 会互相命中——issue #4「5 个 seed 全命中同一响应」的逐字翻版 |
+
+**已知取舍原样延续**: ARCH §7.5 已记载 `model_fingerprint` 是**集合级**而非本次选中源的指纹,同 scope 各源配置不同时仍可能返回另一源的响应;要求逐源可复现应让每源独享 scope 或 namespace。加入 `reasoning_effort` 后该取舍不变,本设计不扩大战线去改它。
+
+**冷启动代价**: 只有新配 `REASONING_EFFORT` 的源冷启动一次;存量只配 `ENABLE_THINKING` 的源字面量逐字不变。
+
+**key 用请求档,不用 `nearest` 映射后的生效档**(T6 实现时定,理由在此补正): 决定性的原因是
+`CacheMW` 位于洋葱中比 transport 更外的一层,查缓存时 `resolve_thinking` 尚未执行,生效档
+**根本拿不到**。副作用是被映射到同一档的两个请求(`minimal` 与 `low` 都映射到 `low`)各占一个
+缓存槽,存两份相同响应——浪费但不毒化,可接受。
+
+**由此带来一条已知边界**(与 ARCH §7.5 既有两条并列,不在本设计处理): 能力表更新导致映射结果
+变化时(如某模型新增 `minimal` 档),请求档 `minimal` 算出的 key 不变而实际发出的字节变了,
+会命中按旧映射存下的响应。能力表版本不进 `model_fingerprint` 是既有取舍的延续(provider 表
+与能力表都不在指纹里),要求严格隔离的调用方应换 `cache_namespace` 或 `cache_salt`。
+
+## 6. 遥测
+
+`llm_calls` 新增一列 `reasoning_effort TEXT`(INSERT 字段 25 → 26,物理列 26 → 27;两套口径的区分见 `telemetry/schema.py` 模块 docstring)。
+
+记的是**本次调用生效的档位**,不是配置值——`None`(不表态)与 `'low'` 必须能区分,故可空。
+
+不加此列则你要做的压测「不同档位是不是真有用」在数据侧无法分组: 现在 25 列里没有任何一列能回答「这一行用的是哪档」。补列走既有的 `PGW_TELEMETRY_SCHEMA_MODE` 机制,两端 DDL 与 `COLUMNS` 同源(schema.py 是单一事实源)。
+
+## 7. 备选方案对比
+
+| | 方案 | 改动面 | 权衡 |
+| --- | --- | --- | --- |
+| **A** | **最小补丁**: 只补 `zhipu` profile,`thinking_on` 填一个档,维持 bool | `providers.py` 一条 + `thinking.py` 两条 | issue #20 字面满足。但 §1 三条结论全部无解: GLM-5.3 填什么档都是错(`medium` 是空档、`none` 是未定义值);`can_disable` 只能在「让下游跑不起来」与「登记一个官方否认的能力」之间二选一。**治标** |
+| **B** | **能力表档位化 + 源级/请求级双入口**(本设计) | `types.py` 加 `Effort`、两个公共类型重构、`resolve_thinking` 加两关、缓存 key、遥测加列、`.env` 加键 | 表达力对齐现实;下游不必再走 `extra_body`;压测可按档位分组。代价是公共类型破坏性变更 + 一次缓存冷启动 |
+| **C** | **照抄 cherry 的完整 wire DSL**: closed operation 集合、`effortMap`、`budgetWire`、endpoint-keyed contract | B 的全部 + 一套 wire 解释器 + per-model wire 覆盖表 | 能表达 budget 型(qwen `thinking_budget`)与原生协议代际差异。但本库只有一个 OpenAI 兼容 transport(§3.4),这层复杂度当前无消费者——**违 P1 YAGNI** |
+
+**推荐 B**。A 治不了 issue #20 描述的病;C 的两项额外能力(多协议 wire、token 预算)在本库当前没有消费者,等真出现 budget 型需求时,`ThinkingWire` 增一个 `budget_key` 字段即可增量抵达,不必现在就上解释器。
+
+## 8. 初始能力表(全部标注「文档推定,待实测」)
+
+来源: 官方文档 + OpenRouter + cherry-studio + LiteLLM 四方交叉。**这是待验证的假设,不是结论**——LiteLLM 里同一个 kimi-k3 在 `moonshot/` 下是三档、在 `perplexity/` 下是六档,中转会改档位有第三方证据。人类已定:能力表数据以后统一经 new-api 实测。
+
+**落库规则**(Codex 审查补): 本表是**调研素材**,不是可直接转代码的表。只有 `supported_efforts` 能写成合法 `Effort` 元组的条目才进 `DEFAULT_CAPABILITIES`。分三档处置:
+
+| 情形 | 处置 |
+| --- | --- |
+| 档位清单与「能否关闭」皆无冲突 | 直接登记 |
+| **档位清单三源一致,仅「能否关闭」存疑**(如 kimi-k3: 官方档位无 `none`,OpenRouter 却标 `mandatory:false`) | 按**保守方向**登记(不含 `none`),evidence 注明存疑点。理由: 不登记会退回 Phase 3 的「尽力注入」,下游配 `none` 时静默失效——**那正是 issue #20 的病**;保守登记则报错并给出最低档,明确且有出路 |
+| 档位清单本身无该型号直接证据(`未查到`,或仅由**同系**推定如 `推定同上`) | 不登记,走 Phase 3 |
+
+第二档与第三档的分界是**有没有该型号自己的档位证据**,不是「关不关得掉存不存疑」: `kimi-k3` 进第二档,因为月之暗面官方文档直接写明它的三档是 `low/high/max`,只有「能否关」两源分歧;而 `gemini-3-flash`、`claude-haiku-5` 的档位清单是从同系型号(3.1-pro / opus-5)推来的,**没有该型号自己的文档**,故进第三档。Phase 3 并非静默——它会 warning 指路「实测后用 `register_capability` 登记」,且未登记模型的运行期对账文案也专门写了这一句;登记一个纯推定值反而会让下游以为库确认过。T10 实测时这三个型号优先补。`default` 列只是调研记录,按 §3.2 并入 `evidence` 文本,不进字段。
+
+| 模型 | supported_efforts(推定) | 厂商默认(入 evidence) | 关? |
+| --- | --- | --- | --- |
+| glm-5.3, glm-5.3-flash | low, high, max | max | ✗ |
+| glm-5.2 | none, high, max | max | ✓ |
+| kimi-k3 | low, high, max | max | ?(OR 标可关,但官方档位无 `none`——**待实测**) |
+| kimi-for-coding | 未查到 | — | ? |
+| deepseek-v4-pro / -flash / -flash-vision-exp | none, high, max | high | ✓ |
+| gpt-5.4, gpt-5.5 | none, low, medium, high, xhigh | medium | ✓ |
+| claude-opus-5, claude-sonnet-5 | low, medium, high, xhigh, max(+`none` 经网关转 `thinking` 关闭) | high | ✓ |
+| claude-haiku-5 | 推定同上 | — | ? |
+| gemini-3.1-pro | low, medium, high | 官说 high / OR 说 medium(**打架**) | ✗ |
+| gemini-3-flash | low, medium, high | — | ? |
+| MiniMax-M3 | none, auto | auto | ✓ |
+| MiniMax-M2.5, M2.7 | auto(**仅此一档**) | auto | ✗ |
+| glm-5, glm-5.1, glm-4.6v | none, auto | auto | ✓ |
+| qwen-plus-latest, qwen3.5-flash, qwen3.6-plus, qwen3.7-max, qwen3.7-plus | none, auto | auto | ✓ |
+
+三个 embedding 模型(text-embedding-v2/v4、qwen3-vl-embedding)无推理语义,不入表。
+
+## 9. 非功能维度
+
+| 维度 | 回答 |
+| --- | --- |
+| **并发** | 两张表仍是 `MappingProxyType` + 纯函数查找,无共享可变状态。transport 的 `_warned_models`/`_warned_mismatches` 是实例级 `set`,读写之间无 `await`,单事件循环内原子。节流键加入生效档位后基数上升(源×模型×档位),仍为有界小集合 |
+| **取消** | 档位解析全部是同步纯函数,不含 `await`,不改变 `CancelledError` 的穿透路径。既有保证不受影响 |
+| **降级方向** | 推理档位属**请求正确性**而非资源闸,故一律**报错不放行**(Phase 2/4/5(下同)),与「限流/熔断后端不可用须报错」同向。能力**未登记**是唯一例外——warning 后尽力注入,理由是新模型上线不该被库挡住(既有决策,保留) |
+| **幂等** | 纯函数,无副作用,同输入恒同输出。重复调用安全 |
+| **持久化** | 两处一次性影响: ① 缓存 key 变化 → 已配推理参数的 namespace 冷启动一次;② 遥测补列 → 走既有 `PGW_TELEMETRY_SCHEMA_MODE`,补列语句与 DDL 同源。均无部分写入风险(补列是 DDL 原子操作,缓存 miss 不损坏数据) |
+
+## 10. 错误处理与测试策略
+
+**错误分类**: 全部落 `RequestRejectedError`(不重试、不换源、不计熔断)。理由: 档位不支持是确定性的配置/参数问题,重试与换源都不会让它变对。路径与既有一致——`thinking.py` 抛 `ThinkingUnsupportedError(ValueError)`,transport 在请求期翻译。
+
+装配期 vs 运行期: 源级配置(`SourceConfig.reasoning_effort`)在**构造期**校验并报错;请求级(`ChatRequest.reasoning_effort`)只能在**运行期**校验,落 `RequestRejectedError` 上抛。
+
+**测试策略**(先失败后通过,每条对应一个行为):
+
+| 层 | 用例 |
+| --- | --- |
+| unit | 五道关卡各自的触发与不触发;`enable_thinking` 语法糖的三种等价;矛盾配置构造期报错;`nearest` 映射的取档方向;派生量(`can_disable`/`cheapest_effort`)与 `supported_efforts` 一致 |
+| unit | Phase 4 文案**含** `cheapest_effort` 与 env 键名(这是交付物,要断言内容而非只断言抛错) |
+| unit | 缓存 key: 同 messages 不同档位 → key 不同;不表态时 key 与存量形状一致(回归) |
+| integration | 遥测 `reasoning_effort` 列在两端(sqlite/pg)落值正确,不表态时为 NULL |
+| e2e(`slow`) | 经 new-api 对 §8 表逐模型实测,校正 `supported_efforts`;标 `slow`(成败取决于外部服务当下状态) |
+
+## 11. 明确不做
+
+1. **档位与 `reasoning_tokens` 的运行期对账**(§4.3): 无可判定的函数关系,拿它报警是噪声。
+2. **token 预算型控制**(`thinking_budget`/`budget_tokens`): qwen 系支持,但当前无下游需求;`ThinkingWire` 可增量加 `budget_key` 抵达。
+3. **原生协议 wire 与代际方言**(§3.4): 本库只有一个 OpenAI 兼容 transport。
+4. **档位对采样参数的联动**: DeepSeek 思考模式不支持 `temperature`/`top_p`,Moonshot kimi-k2.5+ 固定采样参数,传别的值 400。**本设计不代下游做参数裁剪**——这是模型的约束,应由 evidence 记录并让 400 如实抛出,库替下游删参数是「默认值掩盖错误」。记入能力表 evidence,不写进代码逻辑。
+5. **压测本身**: 「不同档位是不是真有用」是 `harness-eval` 范畴,依赖本设计的遥测列,不属于本设计。
+
+## 12. 迁移与兼容
+
+**破坏性变更五处**(初稿只列了第 1 条,其余四条为 2026-09-05 独立验证实测补全——照初稿写 CHANGELOG 会让下游撞上没有预告的 `TypeError`):
+
+| # | 位置 | 变更 | 谁会断 |
+| --- | --- | --- | --- |
+| 1 | `ThinkingCapability` | 构造签名 `can_disable` → `supported_efforts` | 自建能力表的调用方 |
+| 2 | `ports.Transport.complete()` | 新增**无默认值**参数 `reasoning_effort` | 任何自建 transport 实现 |
+| 3 | `ports.TelemetryRecorder.record_llm_call()` | 新增无默认值参数 `reasoning_effort` | 任何自建 recorder 实现 |
+| 4 | `thinking.resolve_thinking()` | 第三参数换语义(`bool` → `Effort`),**返回类型由 `Mapping` 改为 `ThinkingResolution`** | 读侧代码一律断 |
+| 5 | `providers.ProviderProfile` | `thinking_on`/`thinking_off` → `thinking: ThinkingWire` | 自建 profile 的调用方 |
+
+五者都在包根导出面或端口面上。
+
+**先更正**(Codex 审查指出): 初稿称「已核实 `reference/` 三项目无调用点,实际影响面为零」——**该结论不成立**。`reference/` 下当前**没有** GovDoc-SaaS / Video-Tree-TRM5 / CHSAnalyzer 三个目录(工作区实际只有本次调研克隆的四个开源项目),此前的 `grep` 因目录不存在而输出空,被误读成「无匹配」。
+
+真实的库内调用点(可复验):
+
+| 位置 | 用法 | 处置 |
+| --- | --- | --- |
+| `thinking.py:169` | 读 `capability.can_disable` | 改读派生属性,行为不变 |
+| `tests/unit/test_thinking.py:128` | `ThinkingCapability(True, "实测")` **位置参数构造** | 随实现同步改——这是不可兼容的部分 |
+| `tests/e2e/test_thinking_live.py:455` | 读 `can_disable` | 派生属性覆盖 |
+| `__init__.py` | 包根导出 `ThinkingCapability`/`register_capability` | 符号名不变,构造形态变 |
+
+**兼容策略**: 保留 `can_disable` 为只读派生属性(`Effort.NONE in supported_efforts`),**读侧代码一律不改**;位置参数构造无法兼容,库内三处随实现同步修改。
+
+**下游影响面: 推断而非核实**。三项目尚未迁移接入本库(M4 才做),`ThinkingCapability` 是 2026-08-02 才加入的库内表,下游调用它的可能性低——但工作区读不到三项目源码,这条只能是推断。**须人类在审批时确认**,或在实现计划里加一步「三项目可读时复验调用点」。版本号取 **1.3.3**(2026-09-05 人类指令,不走 minor)。
+
+**非破坏**: `SourceConfig.enable_thinking` 保留,行为等价(§4.2);`.env` 的 `ENABLE_THINKING` 键保留;新增键 `{SCOPE}__{PROVIDER}__{N}__REASONING_EFFORT`。三项目不改配置即可继续跑,除非它们配的是「关闭一个官方不可关的模型」——那种情况**本来就是静默失效**,现在会明确报错并给出替代档。
+
+## 13. 验收标准
+
+1. 五道关卡各有先失败后通过的测试证据;Phase 5 文案内容被断言。
+2. 同 messages 不同档位不再互相命中缓存。
+3. 遥测能按档位分组(压测的前置条件)。
+4. `.env` 只配 `ENABLE_THINKING` 的存量下游行为不变(回归测试)。
+5. 进 `DEFAULT_CAPABILITIES` 的条目**仅限** §8 中无 `?`/无冲突者,每条 `evidence` 标注「文档推定,待实测」并附出处;其余条目留在设计文档里等实测,不登记。
+6. import-linter 契约不破(`Effort` 落 `types.py`,不产生反向依赖)。

research-wiki/designs/2026-09-09-134-thinking-contracts-design.md

@@ -0,0 +1,332 @@
+---
+type: design
+node_id: design:2026-09-09-134-thinking-contracts-design
+title: "1.3.4 推理意图与测试证据设计"
+date: 2026-09-09
+---
+
+# 1.3.4：推理意图的可满足性与测试证据契约
+
+> 日期：2026-09-09。状态：**已通过独立审查并获人类正式批准；进入实施计划阶段，编码须先完成计划审查**。
+> 用户已批准合并处理 #25／#26／#21，及 D1（未知 AUTO 尽力＋告警）、D2（受管推理与 raw 冲突拒绝）、D3（下游显式迁移 namespace／salt）。下文细则供正式设计审查，不重新悬置已决方向。
+> 本轮只修订本文件；未改生产代码／测试、未提交、未启动子代理、未执行真实付费调用。既有审查历史与剩余证据门见 §11。
+
+## 1. 目标、非目标与事实源
+
+本批修复共同问题：库声明的推理意图、实际发送参数和验证证据应一致；无法确认的事实不得变成成功声明。
+
+| 范围 | 交付 | 明确不做 |
+| --- | --- | --- |
+| #21 | 已登记 AUTO 成员检查；移除默认 provider 偷选 medium；冲突守卫；能力证据审计与迁移说明 | 新推理 DSL、通用 overlay 系统、预算型推理、模型名猜测、无证据批量加 AUTO |
+| #25 | 测试侧窄归因函数、逐轮留证、未覆盖汇总；纯本地断言离线化 | 改四分类、整类异常 skip、重跑到绿、扩大生产遥测、自动豁免发布覆盖 |
+| #26 | 真实 client→治理→emitter→recorder 守护无推理路径，附变异证据 | 新端口、替换 reasoning_applies、遥测 schema 改造 |
+| 后续批次 | #19／#23 归 1.3.5，#22 归 1.3.6，#24 独立设计 | 调用上下文 API、deadline、429 算法、对冲或取消结算重构 |
+
+规范依据：CLAUDE.md、brainstorming／structured-logging skill、ARCHITECTURE D11、§4.5／5.1／6／7.5／7.8、docs-convention。
+旧设计：`2026-09-04-reasoning-effort-design.md` §3–6／8／12；旧实验：`findings/2026-08-02-thinking-switch-and-reasoning-tokens.md`、`2026-08-25-thinking-observability-regression.md`。
+Issue 原文：`/tmp/polygateway-issue-triage/open-issues.json`。旧文档的“26 模型”“仅 reasoning_tokens 可靠”“下游尚未迁移”不是本轮验证结论。
+
+## 2. 当前代码审计
+
+| 证据 | 事实与根因 |
+| --- | --- |
+| `thinking.py::_settle_tier` | `effort is AUTO or effort in supported_efforts` 无条件放行 AUTO；形态与模型能力不能共同约束它 |
+| `providers.py::ThinkingWire` | 空 on_base 当前文案混同协议形态与“任意模型默认推理”；需分开 |
+| `DEFAULT_PROFILES[minimax]` | on_base 当前为 reasoning_effort=medium，M3 不是仍必然不推理；问题是 applied_effort=auto 却发 medium |
+| `openai_compat.py::_build_payload` | resolution 后依次浅层 update extra_body／overlay；raw 可改写或新增推理控制，成功档位与最终字节失配 |
+| `client.py::_guard_thinking`／`middleware/cache.py` | 工厂仅解析源级意图；缓存命中早于 transport，请求级、全量注入及同版本策略变化都可能回放旧语义 |
+| `middleware/telemetry.py` | 成功尝试、失败尝试、缓存命中、终态失败的档位来源不同，不能统称“成功记实际档” |
+| `embedding.py::_emit`／`ocr.py::_emit` | 当前正确传 False；只测 emitter 不覆盖调用点，成功响应默认 None 还会掩盖变异 |
+| `test_thinking_live.py`／`test_embed_probe.py` | 前者按异常类别 skip、用正文子串识别 model_not_found；后者捕全部 PolyGatewayError 当“不支持”，都可能遮蔽库回归 |
+
+本轮核对 `origin/main..HEAD` 为既有 `758a127`／`6a09054`，保留历史提交、不重写；其外因判据按 §6 窄修正。
+当前 `reference/` 只有 cherry-studio、litellm、new-api、vercel-ai-sdk；GovDoc-SaaS、Video-Tree-TRM5、CHSAnalyzer 工作区均缺失，**未核验三项目现行配置**。迁移示例不是下游迁移完成证据。
+
+## 3. 备选方案与已批方向
+
+| 方案 | 收益 | 代价／结论 |
+| --- | --- | --- |
+| A：supported_efforts 包含 AUTO 的语义能力 | 不新增模型字段，统一可满足性判据 | 部分旧 True 配置报错，须审计清单并迁移；**用户已选 A** |
+| B：新增模型默认推理三态 | 默认开启与未知可分别表达 | 多维护一套事实，易与能力清单漂移；不选 |
+| C：provider／模型把 AUTO 映射固定档 | 保持旧配置字节 | 库代选付费档位，模型事实塞进 provider；用户不选 |
+
+| 决策 | 已批准 | 不采纳的备选及理由 |
+| --- | --- | --- |
+| D1 | 未登记 AUTO 保留尽力注入＋warning，不保证开启；已登记一律成员检查 | 不改成未知即拒绝；也不把未知当能力已验证 |
+| D2 | 有受管意图时拒绝 raw 推理冲突；无受管意图保留 raw | 不保留双来源互相覆盖，不从最终 payload 反向猜档位 |
+| D3 | 下游显式换 namespace／salt 隔离语义变化 | 不加自动 revision／包版本，不让所有 chat 擅自冷启动，不把能力解析搬进缓存 |
+
+Issue #25 选“离线硬契约＋有限可执行归因＋显式未覆盖”；#26 选真实客户端与轻量 recorder 为日常测试、临时 SQLite 为持久化锚点，不要求远程 PG。
+
+## 4. 推理语义与最终请求体契约
+
+### 4.1 词汇与决策矩阵
+
+`supported_efforts` 表示模型在**当前登记的 OpenAI 兼容 wire** 下、有依据可执行的语义集合，不是上游字符串枚举的逐字镜像。
+`AUTO` = 要求开启、不指定强度；不是 Python None（不表态），不是库任选一档，也不是上游必须接收 `auto` 字面值。
+`on_base=None` 是开启形态未知；`on_base={}` 是该协议不加开启字节，**能否据此满足已登记模型 AUTO 另查清单**。非空开关也不豁免成员检查。
+请求档＞源级 reasoning_effort＞enable_thinking 糖（True→AUTO、False→NONE）；None 不覆盖源级表态，源上两字段矛盾的既有构造校验保留。
+
+| 生效输入／条件 | 结果 |
+| --- | --- |
+| effort=None | 不注入，applied_effort=None；raw 仍按旧优先级发送，不推断其档位 |
+| 所需方向形态未知 | ThinkingUnsupportedError，指路注册 profile；不因模型未登记而假造 wire |
+| 已登记 AUTO 在清单 | 仅发 on_base，不附强度，applied_effort=AUTO |
+| 已登记 AUTO 不在清单 | 明确拒绝并列可用档；fallback=nearest 同样拒绝，不能建议 nearest 修复 |
+| 已登记显式强度不支持＋nearest | 保留最近开启档、等距弱侧；只有纯开关候选时可强度→已登记 AUTO，不能 AUTO→强度 |
+| NONE 不支持／没有 off 形态 | 保留专用不可关闭错误；替代配置由用户选择，不自动执行 |
+| 未登记 AUTO／强度／NONE | 按已知 wire 尽力注入＋warning；wire 表达不了仍拒绝，不编造支持清单，不保证开启／关闭／强度有效 |
+
+未知 AUTO 的空 on_base 可能发送零推理字节，返回 AUTO 仅表示尽力编码的选择，**不构成能力验证 PASS**。既有 warning 需明确能力未知、可能不生效，保留实例节流。
+NONE 方向仍按 `_wire_unknown_for` 既有分工：off、on_base 皆 None 才是整体未知；off None 而 on_base 已知是缺关闭形态。
+
+### 4.2 MiniMax 与能力证据
+
+移除默认 minimax.on_base 的 medium，改为空映射；M3 不加 AUTO。显式 medium 仅作为恢复旧字节的迁移示例，不是库推荐的最优成本档。
+按本轮源码清点，默认表 24 个型号、10 个含 AUTO；live 候选 26 型号不等于能力表 26 条。**本候选不授权新增任何 AUTO 条目**；追加须另附逐型号证据并复审，不因未知、不可达或同厂近代型号有能力而补登。
+
+| 模型组 | 已有证据与本批处置 |
+| --- | --- |
+| MiniMax-M3 | 2026-08-25 裸 HTTP 无参数不推理、medium 有推理；2026-09-05 evidence 同向。不加 AUTO，显式档保留 |
+| MiniMax-M2.5／M2.7 | 已有 AUTO；历史默认／mandatory 旁证及 T10 开启观测。T10 未留最终 wire，移除 medium 后需补空 on_base 实测，不冒充已复验 |
+| qwen3.7-plus／max、qwen3.6-plus、qwen3.5-flash、qwen-plus-latest、glm-4.6v | 保留已有 AUTO 与逐型号证据，不推及其他型号 |
+| glm-5／5.1 | 保留既有文档推定 AUTO；T10 回报 glm-5.3，身份不足，不算本型号实测 |
+| deepseek-v4-pro／flash／flash-vision-exp、glm-5.2／5.3／5.3-flash、kimi-k3／kimi-for-coding | 现无 AUTO；显式档成立不等于 AUTO wire 成立，本批仍拒绝其 AUTO |
+| gpt-5.5 | 现无 AUTO；历史报告 `tier_probe_20260905_184307.md:97` 无参数基线 5/5 rt=18、身份一致，是候选线索，但最终 payload／raw 覆盖未留证，不直接追加 |
+| gpt-5.4、claude-opus-5／sonnet-5、gemini-3.1-pro | 现无 AUTO；限额／上游错误导致未覆盖，不能以“默认 medium”或同代替代证据 |
+| claude-haiku-5、gemini-3-flash | 未登记 live 候选，按 D1 尽力＋告警；不自动登记 |
+
+历史报告仅局部抽查；本轮未全表复验、未新跑付费实验。默认 wire 改变的 M2 两型是发布前显式缺测项，不能靠缓存回放旧 medium 的成功结果过门。
+
+### 4.3 D2 冲突规则（窄边界，不做通用 overlay）
+
+“受管意图”指按 §4.1 得到的 effort 非 None，**包括 NONE、AUTO、糖及未知模型**。单凭 raw 不构成受管意图。
+当前浅层次序保持为 `基础 payload → resolution.payload → source.extra_body → request.overlay`；禁止改成深合并。守卫只校验所有权，不重写／删除 raw，不反推档位。
+
+| 检查对象 | 精确规则 |
+| --- | --- |
+| 已知 raw 推理控制 | 顶层 `reasoning_effort`、`enable_thinking`、`thinking`、`thinking_budget`、`reasoning`、`thinkingConfig` 为控制根；`output_config` 为对象且含 `effort` 也算控制。这是显式有限词表，不按任意键的子串／模型名猜测 |
+| 当前 profile 的控制根 | 加入 on_base、off 的全部顶层键及非 None 的 effort_key；即使本次为 AUTO 且 on_base 为空，也保护 effort_key／off 根。保护范围取开关两向并集，不只取本次实际注入键 |
+| 同值与遮蔽 | 有受管意图时，extra_body 或 overlay **任一层**出现控制根即拒绝，值相同也拒绝；被后一层遮蔽也不豁免，避免双来源随配置变化重新失配 |
+| 嵌套／浅覆盖 | `thinking={}`、`thinking={"budget_tokens":100}` 也拒绝：替换整个根会删除受管 type。当前 wire 持有某根时，raw 仅改其看似无关子键仍拒绝。根未被 wire 持有时，`output_config={"format":"json"}` 不因兄弟键 effort 被保护而误拒 |
+| 新增而非覆盖 | AUTO 的空片段遇 raw reasoning_effort=high 仍拒绝；qwen 受管开关遇 raw reasoning_effort／thinking_budget 也拒绝，不能只检查字典交集 |
+| 无受管意图 | 即请求、源级档与糖都不表态，保留 extra_body→overlay 原有浅覆盖（含 raw 推理），applied_effort=None；原 model/messages/stream/stream_options 禁写规则照旧 |
+
+自定义 wire 不新增路径 DSL：effort_key 仍是一个**顶层字面键**，不把点号解释成嵌套路径；on_base／off 可含嵌套对象，raw 守卫保护其整个顶层根。
+自定义 on_base 不得包含自己的 effort_key，也不得借标准 reasoning_effort 偷带档位；无论其值是 medium、auto 或 None 都拒绝为配置错误，不能默默删键。标准嵌套 `output_config.effort` 同属禁带强度的已知路径；不解析任意私有嵌套方言。需要强度请走显式档，不能将其固化在开启片段。
+其余自定义不透明方言的语义真实性由注册者提供证据；本批保证声明键不被 raw 冲掉，**不宣称可以识别所有未声明的私有别名／预算语义**。扩展别名应登记 wire 后受控，不新增通用参数解释器。
+
+### 4.4 守卫时机、错误与保证范围
+
+| 入口 | 时机／职责 |
+| --- | --- |
+| 工厂 `_guard_thinking` | 已有 profile／capability／source 材料齐全；装配期（网络及准入前）校验 wire、源级可满足性与源 extra_body 冲突，抛 ThinkingUnsupportedError（配置 ValueError）。工厂拒绝的源不能靠未来请求覆盖“救活” |
+| `chat` 前置参数校验 | 保留 validate_request_overlay；请求显式档＋调用 overlay 的已知控制词表冲突可在进入洋葱／准入前报配置 ValueError。不新增全源能力预解析，不声称这里可见自定义 transport 的注册表 |
+| 默认 transport `_build_payload` | 以本次选中源、实际 profile、请求覆盖后的意图，对两层 raw 再做完整守卫；全量注入与自定义注册表同样覆盖。ThinkingUnsupportedError 翻译 RequestRejectedError，HTTP 发送前拒绝，无重试／换源／故障熔断计数 |
+| 自定义 Transport | 不通过默认 transport 的调用仍由端口实现方履约；本批不添加 preflight 端口，不反射读取私有注册表，不承诺能验证任意注入实现 |
+
+transport 守卫**可能已经经过选源、限流预扣与准入**，拒绝后的结算沿既有 finally 路径；“零 HTTP”不等于“零准入操作”。不移动洋葱层次以制造所有请求均前置拒绝的过宽保证。
+真实成功尝试将同一 resolution.applied_effort 传给响应与 emitter，不重算；AUTO 是未指定强度的选择，不是服务端内部强度。服务端是否接受／执行推理由 ThinkingObservation 回答，失败与缓存行另见 §8。
+缓存命中不经过上述 transport 检查，所有“缓存不得绕过新拒绝”验收都以 §5 完成迁移为前置。
+
+## 5. D3 缓存迁移与下游配置
+
+### 5.1 显式迁移边界
+
+缓存身份继续沿 ARCH §7.5；**不加入自动 revision、包版本、fallback、能力表或 wire 版本字段**，不删除旧键、修改共享 Redis 或重写历史遥测。
+语义变更包括本次 AUTO 成员检查／raw 冲突规则、MiniMax wire 变化，以及同版本下 fallback=nearest→error、能力增删／映射变化、自定义 profile wire 变化；这些都由下游显式换 namespace／salt 隔离。现有源指纹包含部分配置不代表包含全部语义。
+
+| 操作 | 下游必须做／边界 |
+| --- | --- |
+| 迁移前 | 盘点工厂与全量注入、scope／租户、源级糖／档／raw、请求级覆盖、fallback、自定义 wire，以及实际 per-call namespace／salt 覆盖 |
+| 切换 | 为受影响调用集合选择从未承载旧语义的 namespace 或 salt；在首次新语义读写前部署到该集合全部调用者。租户前缀与原 epoch salt 保留后再追加人工迁移标记，不共享租户身份 |
+| 多源 | 一个缓存 scope 内只要有源受影响，必须隔离该共享身份的调用集合；要求更细范围由下游拆独立 scope／namespace，本批不替下游重分组 |
+| 并行与回滚 | 新旧客户端不得共享迁移后身份；回滚到旧 namespace 会重见旧语义，不能说旧键已被清理。未来策略变更须再次显式迁移，不能复用一次标记包办所有变化 |
+| 未完成迁移 | 旧缓存或同版本 nearest 写入可被 error 客户端命中，库不会自动验证其新可满足性。文档警示是操作前置，不是新增的自动安全机制 |
+
+**不要求所有 chat 冷启动**；未受影响调用可保留身份。若受影响与不受影响调用原本共享一套身份，下游须明确选择整体换标记的成本或先拆分，库不代选。
+
+### 5.2 旧→新配置与验证矩阵
+
+下表是**配置迁移示例及拟新增离线节点**，不是已执行测试。显式档均为当前清单成员示例，不代表所有渠道已实测、不作成本代选。所有受影响且启用缓存的行还须执行 §5.1。
+
+| ID／旧配置 | 受影响模型 | 新行为（源级工厂／请求级默认 transport） | 用户明确选择的新配置 | 离线验证锚点（拟） |
+| --- | --- | --- | --- | --- |
+| M1 `ENABLE_THINKING=true` 或 `REASONING_EFFORT=auto` | MiniMax-M3 | 装配 ThinkingUnsupportedError／请求 RequestRejected，零 HTTP | 删除糖，`REASONING_EFFORT=medium` 可恢复旧 medium 字节；也可选择表内其他档 | `test_thinking.py`：M3 AUTO 拒绝／medium payload |
+| M2 同上 | deepseek-v4-pro／flash／flash-vision-exp、glm-5.2 | 同上；开关 on_base 非空也拒绝 | 删除糖，显式 `REASONING_EFFORT=high` 或经用户选择 max | `test_thinking.py`：非空 wire AUTO 成员约束 |
+| M3 同上 | glm-5.3／5.3-flash、kimi-k3／kimi-for-coding | 同上，nearest 不能解 AUTO | 删除糖，显式 `REASONING_EFFORT=low`（也可选 high／max） | `test_thinking.py`：AUTO＋nearest 拒绝 |
+| M4 同上 | gpt-5.4／5.5、claude-opus-5／sonnet-5、gemini-3.1-pro | 同上；不可达不补 AUTO | 删除糖，用户选表内 `REASONING_EFFORT=medium`；这不是新增 live 证明 | `test_thinking.py`：空 wire 非成员拒绝 |
+| M5 同上 | MiniMax-M2.5／M2.7 | 仍 AUTO，on_base 从 medium 改空，真实语义待补测 | 保留 True／AUTO 并迁移缓存；需要旧 raw 字节者须完全退出受管意图，不可谎称该模型支持 medium | `test_thinking.py`：空 wire AUTO 字节；live 单列缺测 |
+| M6 同上 | qwen 五型、glm-5／5.1／4.6v | AUTO 仍是成员，原开关形态保留 | 保留配置；glm-5／5.1 仍身份未覆盖 | `test_thinking.py`：已登记 AUTO 放行 |
+| M7 同上 | 未登记模型（含两个 live 候选） | 已知形态尽力＋warning，不保证开启 | 可保留 AUTO；要求确定保证者先取得能力证据再登记，不自动加表 | `test_thinking.py`：未知空／非空 wire 警告 |
+| M8 源 HIGH＋`EXTRA_BODY={"reasoning_effort":"high"}`；或请求 AUTO＋raw HIGH | 所有受管模型，含未知 | 同值也拒绝；工厂或前置／transport 对应守卫报错 | 保留受管档并删除两层 raw 控制键；或清空源糖／档、请求不表态，仅 raw | transport 单测：同值、嵌套、被遮蔽、raw-only |
+| M9 请求 medium，源 `EFFORT_FALLBACK=nearest` 改 error | 如 glm-5.3（映射 low→拒绝） | 源未表态时两工厂均可装配；旧身份可命中，新隔离身份在 transport 拒绝 | 改 error 的同时显式迁移 namespace／salt | cache 单测：nearest 写入→error 读，新身份必须 miss |
+
+配置实例（仅列需替换项，其他已校验的源配置保留）：
+
+| 场景 | 旧 | 新 |
+| --- | --- | --- |
+| M3 源级 | `LLM__MINIMAX__1__ENABLE_THINKING=true` | 删除该键；`LLM__MINIMAX__1__REASONING_EFFORT=medium` |
+| 请求级 AUTO | 源不表态；`chat(..., reasoning_effort="auto")` | 源仍不表态；用户选择 `chat(..., reasoning_effort="medium", cache_salt="epoch-7:thinking-134-a")`（M3 示例） |
+| 工厂缓存 | `PGW_CACHE_NAMESPACE=lab:tenant-a` | `PGW_CACHE_NAMESPACE=lab:tenant-a:thinking-134-a`（人工标记，不是新增配置键） |
+| per-call 租户覆盖 | `cache_namespace="tenant-a", cache_salt="epoch-7"` | `cache_namespace="tenant-a:thinking-134-a", cache_salt="epoch-7"`；只改工厂默认值对此路径无效 |
+| 全量注入 | 构造参数 `cache_namespace="lab:tenant-a"` | 改成上述新 namespace；既有 cache／ttl 参数照常注入 |
+| 自定义 wire 偷带强度 | `on_base={"reasoning_effort":"high"}` | `on_base={}`、保留 effort_key；用户显式选 HIGH（须模型支持），并迁移缓存 |
+
+三项目迁移验收须由各自负责人提供脱敏的实际配置／装配与调用位置，映射 M1–M9、提交所选替代与缓存身份切换证据。**当前三项目均为未核验**；Protocol 合成兼容测试通过也不能代替现行配置迁移验收。
+
+### 5.3 旧行为处置
+
+| 旧行为 | 处置 |
+| --- | --- |
+| True→AUTO、请求＞源＞糖、None／NONE、未知尽力＋warning | 保留；未知仍受 wire 可表达性约束 |
+| 已登记 AUTO 无条件放行、MiniMax 偷带 medium、受管与 raw 双来源 | 替换，明确放弃这些隐式兼容；迁移见上 |
+| 原 raw-only、普通采样优先级、显式强度 nearest | 保留，不做通用 overlay 重构 |
+| 缓存旧键／历史遥测／响应字段／端口签名／成本口径 | 保留数据及签名，语义变化靠显式缓存身份迁移，历史不伪造新观测 |
+| 任务恢复／断点续跑 | 不适用，无任务状态；并行版本与持久化纪律见 §5.1 |
+
+## 6. #25：可执行的测试侧归因与证据
+
+### 6.1 输入来自哪里
+
+仅在测试侧增加一个纯分类函数及窄取证 fixture，复用 Markdown 报告；不新增生产事件、字段、端口或通用诊断框架。**不能从压平的最终异常字符串重建缺失尝试**。
+
+| 输入 | 可实现来源与限制 |
+| --- | --- |
+| 预期请求 | 测试矩阵显式提供目标 model、POST 端点路径、stream、允许的源 origin、预期推理／结构化片段与提示词摘要；不能调用待测 `_build_payload` 生成“预期” |
+| 实际请求与 HTTP 响应 | 利用既有 `OpenAICompatTransport(client_factory=...)` 注入带 httpx request／response hooks 的真实 AsyncClient；request hook 检查 method、规范 URL、JSON model／stream／控制片段，Authorization 与该源凭据仅在内存精确比较，输出布尔值 |
+| HTTP 错误体 | response hook 保留本次响应引用；该次 complete 结束后读取**已缓冲** content（最多接受 64 KiB 完整内容作为分类输入）。未缓冲／超限／解析失败均标证据不足；不在 hook 预读成功 SSE，不另发请求，不以摘要假装完整 JSON |
+| attempt 关联 | 测试专用窄 Transport 委托器原样转发 complete／embed 参数与异常，将入参 call_id（attempt UUID）放入任务局部 ContextVar 供 hooks 使用；finally 复位。只改测试装配，实际 payload／解析仍由真实 transport 执行 |
+| 逻辑调用与错误 | 每轮 chat 显式传 session_id=运行 ID、parent_call_id=本轮 UUID，并由测试在 chat 外围将同一二元组绑定任务局部上下文、finally 复位；委托器从该上下文建立二元组→attempt UUID 关联，保存原始异常类／cause 与 HTTP 记录。归因用逐次记录，不靠最后一个错误推断所有前序 |
+
+带取证的 live 用例走既有全量注入路径，工厂与默认 client_factory 的装配／鉴权构造另有离线回归，不能用测试工厂替换后宣称原工厂已验证。需验证工厂本身的 live 用例若没有该证据通道，失败就保持 FAIL，不补生产接口凑证据。
+请求 hook 校验不通过须记证据并使测试 FAIL；不得改写请求后再称原请求正确。凭据不写哈希、不落盘；URL 去 userinfo／query，只存安全 origin 标识与路径。
+
+### 6.2 精确分类：默认 FAIL
+
+分类输出为 FAIL 或外部未覆盖；外部未覆盖在 pytest 中可呈 SKIP，但报告与覆盖汇总必须记“未覆盖”。成功响应的行为断言仍单独执行，不经此分类器放宽。
+
+| 情形 | 精确规则 |
+| --- | --- |
+| 环境前置缺失 | 测试矩阵列出的必需凭据／可选外部 Protocol 包未提供，网络前记未覆盖；键存在但配置格式错误、值校验失败是 FAIL |
+| 404 model_not_found | 仅当本轮恰有一次实际 HTTP 尝试、无其他错误，请求检查全通过，响应为 404，完整 JSON 对象的 `error` 是对象且 `error.type == "model_not_found"`，默认 transport 对外为 RequestRejectedError 且 status 一致，才记“端点回报该请求型号不可用，未覆盖”。JSON 重复键也拒绝作为证据 |
+| 普通 404／伪机器字段 | 只在 message 出现子串、字段类型错误、截断体、未缓冲体、端点／model／鉴权不符、响应与 attempt 无法配对，一律 FAIL |
+| 429／5xx／401／403、网络错误 | **本批不建立自动外因豁免**：当前资料未给可核验的网关机器码白名单及独立归因来源，全部 FAIL 并保存实收证据；不能仅凭 HTTP 状态、Transient／SourceDead 类或“请求离线测过”跳过 |
+| no_sources／stalled／retry_exhausted／AllSourcesExhausted | FAIL；本批不从生产遥测补失踪逐次原因，不将“曾见过一条 429”推断为整个终态均外因 |
+| SSE／JSON 解析、空补全、ValueError、一般 RequestRejected／ResultInvalid、断言失败 | FAIL；请求正确不证明解析器或治理正确 |
+| CancelledError | 原样穿透，finally 清理，不变成 SKIP |
+| 成功但模型身份缺失／不符 | 实发 model 检查不通过是 FAIL；最终 model_reported 缺失／不符且没有独立原始响应身份取证时，保持 FAIL 并标记“身份来源无法区分”，不能推断上游没报。只有独立原始响应证据证明上游身份缺失／不在显式别名集合，才可记能力未覆盖；原始身份正确而解析／搬运丢失或改错必须 FAIL。本批不新增成功 SSE 捕获器，无该证据通道时按 FAIL 处理；别名不按前缀猜测 |
+
+没有证据通道时宁可 FAIL，不用抽象的“已证明外因”做逃生条件。运维人工确认可附外部证据供发布负责人决定豁免，**不自动把 FAIL 改 PASS 或扩大分类白名单**；未来扩大自动归因须独立给真实样本及反例契约。
+不追加裸 HTTP 对照诊断、自动重跑或悄悄缩小超时／stall；新增调用须先有人类模型／轮次／并发预算。
+
+### 6.3 覆盖判据与报告
+
+**先声明测试命题，再解释观测**：下述关闭成功判据只适用于“支持 NONE 的型号应成功关闭”，不是要求所有型号均可关闭。
+
+| 测试命题 | 观测与结论 |
+| --- | --- |
+| 已声明可关闭，验证受支持 NONE | 任一 OBSERVED 证伪关闭保证，FAIL；完整必需轮次且请求／身份合格、每轮 ABSENT 才可关闭覆盖 PASS；混入 UNKNOWN 记未覆盖 |
+| 已声明不可关闭，T10 绕过库能力守卫验证上游 | 合格 OBSERVED 是本轮仍推理的证据，可支持该测试条件下的不可关闭声明，不是关闭成功，也不得仅因 OBSERVED 而 FAIL；必须按预先固定命题及轮次集合比较观测与声明，UNKNOWN 不补足证据，不据有限探测声称证明所有上游参数均无法关闭 |
+| 有意请求不支持档位，验证预期拒绝 | 独立于外因分类器，直接断言预先声明的拒绝类型／状态与机器字段。符合预期的 400／RequestRejected 是负向契约通过，不是外因 SKIP；非预期错误仍 FAIL。上游探测照过请求资格、独立身份可得性与逐轮证据要求 |
+
+增加离线反例：可关闭声明＋OBSERVED 必须 FAIL；不可关闭声明＋合格 OBSERVED 不得仅因出现推理而 FAIL；原始 JSON／SSE 含正确 model 但公共响应丢失／改错，必须 FAIL 而非 SKIP。全 UNKNOWN 绝不能算关闭覆盖通过。
+本候选不采用 completion_tokens 长短作为通用关闭证明；旧 prompt_tokens 差异只保留为指定历史样本的 wire／观测回归锚点，不使 UNKNOWN 升格关闭能力 PASS。没有经单独审定的独立关闭证据就记未覆盖，运行时 UNKNOWN 不告警的既有语义不变。
+开启测试保留显式轮数和多数 OBSERVED 规则（`observed_count > planned_rounds / 2`），但必须先保证全部计划轮次完成且请求／身份合格；失败／缺轮不得从分母删除。未知模型单次成功不自动变成能力登记。
+
+逐轮先保存结果再判断后续处置；第 2 轮失败不能丢第 1 轮。报告字段包含矩阵 ID、provider、请求／回报模型、stream、请求档／响应 applied_effort、轮次、parent/session、attempt UUID、请求校验结果、异常类／status／安全摘要、已完成轮数及覆盖状态。
+完整错误体仅内存分类，落盘只存机器字段与沿用 2048 字符上限的脱敏摘要；清除已知凭据及私有提示词回显，无法安全保留则摘要省略并标明。不得写 Authorization、完整 .env 或私有提示词。
+每轮用唯一运行目录与轮次文件安全写入，汇总不能覆盖前轮失败；报告写失败使测试 FAIL，不允许无证据 skip。取消 finally 关闭自建资源，不引入无界网络等待。
+
+| 既有测试接缝 | 窄修正 |
+| --- | --- |
+| L9 `_MYSTERY_PROFILE` | 保留显式全 None profile，将“未知形态报错”纳入离线断言；默认 openai 已非未知 |
+| L8 `can_disable=False` | 装配拒绝只记本地契约通过，不写“与实测一致”；L8／T10 的 UNKNOWN 按上述覆盖门修正 |
+| `_rounds_or_skip`、默认基线、T10 | 统一精确分类与逐轮留证；部分档未覆盖不能汇总为模型全覆盖 |
+| compat Protocol／平铺键 | 完整合成 env／注入组件离线测装配；外部 Protocol 缺包只标该兼容项未覆盖，不声称读过缺失项目 |
+| embedding 探测 | 去掉捕全错误为“不支持”，使用同一窄判据及 finally 关闭；不扩展端点能力 |
+
+发布门分开统计离线契约与预先声明的 live 单元。必需单元 SKIP／UNKNOWN／缺行／未完成不能凭 pytest exit 0 放行，须重测或人类明示豁免；不自动缩小覆盖集合。
+
+## 7. #26：真实调用链与变异证据
+
+复用 `test_embedding.py`、`test_ocr_client.py` 的真实 client、脚本 transport、recorder 工装；仅替换外部传输，不 mock emitter，不手工 emit_attempt 伪造 False。
+
+| 验证 | 必须断言 |
+| --- | --- |
+| embed、recognize_text、parse_layout | 源分别填 True 糖／显式 HIGH；一次 Transient 后成功，每路径确有两条尝试行（一失败一成功），reasoning_effort 全 None |
+| 拒绝与耗尽 | 至少一条已发生的失败尝试落库且档位 NULL，主异常仍上抛；不凭本 issue 新增不存在的终态行 |
+| chat 阳性 | 已登记 AUTO 源的 True 糖失败行 auto；显式档失败行请求意图；nearest 成功行映射档；emitter 恒 NULL 必须被抓住 |
+| SQLite 锚点 | 每个无推理入口至少一组真实 client＋临时 SQLite，断言总行数、失败行数和 NULL 数，不用 all([])，不接共享 llm_calls |
+| wire 边界 | MockTransport／录制响应验证 embedding、OCR 不发推理参数；layout POST＋ZIP GET 属同一次治理尝试，不误算两条遥测 |
+| 并发 | 共享 recorder 并发 chat／无推理调用，**按测试指定的 (session_id, parent_call_id) 分组逻辑调用**；组内 call_id 是不同 attempt UUID，集合无交集、档位不串，不把 call_id 当所有重试共用的 ID |
+
+隔离副本／worktree 逐一变异并还原：embedding False→True；OCR False→True（两个入口分别红）；chat True→False；移除 emitter applies 短路。记录节点、目标语义失败断言、退出码，原实现及还原后通过。
+Issue #26 当前实现正确，先红来自上述变异，不为 TDD 改坏主工作区；仅因无关签名异常变红不算杀死目标变异。注入资源由测试自己关闭。
+
+## 8. 非功能与四种遥测行口径
+
+继续通过 `TelemetryEmitter` 唯一出口与现有 `llm_calls.reasoning_effort`；**不新增生产遥测字段、表、事件或旁路日志流水**。
+
+| 行类型 | reasoning_effort 来源 | 分析限制 |
+| --- | --- | --- |
+| 真实成功尝试 | response.applied_effort（nearest 后）；无推理路径由 applies=False 短路为 NULL | 不重算；未知 AUTO 仅尽力编码，不证明上游能力；raw-only 为 NULL |
+| 失败尝试 | effective_effort（请求＞源＞糖）；无推理路径 NULL | 是请求意图，不是已发出的／映射后的档，也可能零 HTTP |
+| 缓存命中 | **本次请求级** reasoning_effort | 不取历史 response.applied_effort，不推源级档；thinking_observation 回放历史，不是本次实测 |
+| scope 终态失败 | **本次请求级** reasoning_effort | 可能未选源；不推源级档或实际档，不凭本批补充逐次根因 |
+
+实际档分析仅使用真实成功尝试（排除 cache_hit、失败／终态行），还须保留未知／raw-only 的语义限制。#26 的 NULL 与 chat 阳性不能误套到缓存／终态来源上。
+
+| 维度 | 约束 |
+| --- | --- |
+| 并发／幂等 | 能力表不可变、注册返回新表；解析局部结果，不用全局最后档；同声明同意图同结果；报告按运行／逻辑调用／attempt 隔离 |
+| 取消 | 同步守卫不捕 BaseException；CancelledError 穿透，既有 in-flight finally 释放；不重构真实调用／遥测取消时序 |
+| 降级 | 缓存／遥测故障 warning 降级，限流／熔断后端不可用仍报错；配置守卫与运行期四分类见 §4.4 |
+| 持久化／原子性 | 无 schema／DDL；SQLite 临时文件，旧缓存不改写，报告安全写且失败显式失败；无任务恢复子系统 |
+| 告警／评估 | 未登记与对账 warning 保持实例节流；错误含 model、请求档、支持集合与可执行配置例，不泄露凭据；离线矩阵和变异须全过，live 覆盖基线待实际运行 |
+
+## 9. 实施接缝与文档同步
+
+| 接缝 | 预期改动 |
+| --- | --- |
+| thinking／providers | AUTO 成员约束、nearest 边界、文案、空 wire 语义、D2 窄纯校验；已有能力证据保留出处，不无证据追加 |
+| client／默认 transport | 工厂及请求前置可执行的守卫、最终双 raw 守卫与错误翻译；不改端口、不移动层序、不引入全源请求准入解析 |
+| cache | 本批不加语义 revision 或自动校验；只交付显式迁移回归与边界说明 |
+| 单元／轻集成／e2e | 真实调用链＋SQLite、分类输入与反例、逐轮完整性、隔离变异；M3 True 改为“本地拒绝”和“medium 真实开启”两个命题 |
+| 文档 | 实施时同步 ARCH D11／§5.1／7.5／7.8、README、CHANGELOG、.env.example、源码 docstring；旧设计标注被替代段，不追改历史实验事实 |
+
+Wiki 已下线，按 docs-convention 落到上述文件，不虚报 wiki 多页；schema／端口未变不 bump 字段数。本次仅写本设计，其他同步留正式批准后的计划。
+
+## 10. 验收矩阵与审批门
+
+下列均为**待实施验收**，不是本轮通过记录。凡缓存不得绕过／救活新拒绝的断言，统一以**已完成 §5.1 显式迁移前置**为条件。
+
+| 层 | 必需验收 |
+| --- | --- |
+| 解析离线 | None／NONE／AUTO／强度、已登记含／不含 AUTO、未知空／非空／未知 wire、nearest 两方向、默认与自定义注册表；AUTO 拒绝不提示 nearest |
+| raw 冲突 | 源／请求双入口，同值、被遮蔽、嵌套根替换、新增控制键、自定义 effort_key／off 根、非法 on_base；无受管意图保留 raw，普通采样不误拒 |
+| 守卫时机 | 工厂失败零准入／零 HTTP；前置可判请求冲突零准入；默认 transport 拒绝允许既有准入但零 HTTP、正确结算、无重试换源；全量注入同测 |
+| 缓存迁移 | 旧客户端写旧身份→新客户端使用全新身份 miss 并执行新拒绝；nearest 写→error 读、能力表／wire 变化均换身份；工厂默认、per-call 覆盖、全量注入、多源集合、并行旧新客户端覆盖 |
+| 缓存已知边界 | 另测未迁移的共享身份可能命中并绕过 transport；将其明确记录为操作风险，不把迁移前未拒绝伪装为迁移后安全已验证；无强制全部 chat 冷启动 |
+| 归因／防假绿 | 404 精确 type／仅 message／截断／重复键；400／429／503／SSE／no_sources 默认 FAIL；故意改错 model、Authorization、端点、SSE 解析必须红；第二轮失败保留第一轮证据；取消穿透 |
+| 遥测 | 四种行来源逐项断言；三个无推理入口真实调用链／SQLite NULL 与 chat 阳性；按 parent/session 归组且 attempt UUID 唯一；四类变异被目标断言杀死 |
+| 真实核心 | M3 AUTO／True 拒绝零网络、M3 medium 流／非流、M2.5／M2.7 空 wire AUTO、qwen AUTO；缺观测保留未覆盖，不靠旧缓存 |
+| 真实扩展 | 逐型号／模式列出默认基线、开启／关闭；身份缺失、UNKNOWN、不可达不算关闭 PASS，不用同系替代；新增 AUTO 如另获批准，逐型单列最终 wire／身份／信号 |
+| 迁移／全局门 | 三项目实际配置另取证；conda 静态检查、日常套件、独立 verifier；发布按 CLAUDE 显式跑 slow 与下游视角包验证，不能以本设计代替运行结果 |
+
+付费 live 必须先通过离线构造契约，再经人类批准模型／轮次／并发预算；生产超时不为赶结果压小。本文件不授权任何新真实付费调用。
+
+## 11. 审查历史、修订对应与当前状态
+
+前稿记录 Codex 4 项 Important；本轮按下表修订，**修订不等于独立复审通过**。上一轮 Claude 输出不对应本仓库，整份无效且不作为任何技术结论／通过证据引用。
+
+| Codex 项目 | 本轮修订与复审锚点 |
+| --- | --- |
+| 缓存迁移边界不足 | §5.1／5.2 M9、§10：D3 显式迁移，不加 revision；同版本 fallback／能力／wire 变化、全量注入和 per-call 覆盖均纳入；未迁移仍可能绕过 |
+| 遥测“成功＝实际档”过宽 | §8 四种行逐项来源，真实成功尝试才读 applied_effort；缓存与终态仍读请求级，不扩大生产遥测 |
+| UNKNOWN 被计关闭覆盖 PASS | §6.3／§10：UNKNOWN 不证实关闭，未覆盖不占 PASS；长度差不作通用关闭证明，运行时 UNKNOWN 语义不变 |
+| 缺下游迁移矩阵 | §5.2 M1–M9 与具体键／调用实例；受影响型号、错误时机、人工替代、离线锚点齐全；三项目现行配置明确未核验 |
+
+已决 D1–D3 的旧“未决推荐”段已移除。2026-09-09 第二轮 Codex 审查对修订版无 Critical／Important／Minor；native reviewer 另发现两个测试归因 Important：公共响应身份不足以归因上游，以及 NONE 关闭成功与不可关闭负向研究混同。父会话已在 §6.2／6.3 作最小修订（证据不足 FAIL、不新增成功 SSE 捕获器、按测试命题判定），native reviewer 定向复审通过（run `2f92c90a-298d-459d-8fcb-087dea475770`），无新增 Critical／Important／Minor。
+剩余证据门为 M2 空 wire 实测、其他 live 缺测及三项目实际迁移，不重新悬置已决 D1–D3。2026-09-09 用户已明确选择“批准并继续”，正式批准本文件；独立审查及 native reviewer 定向复审均已通过。
+**当前结论：设计已批准，进入实施计划；计划独立审查通过后直接执行。** 设计批准不等于变异、真实矩阵或下游迁移已通过；尚未取得的证据仍按 §10 门控。

research-wiki/designs/2026-09-09-135-call-observability-design.md

@@ -0,0 +1,202 @@
+# 1.3.5：逻辑调用统计与结构化失败诊断
+
+> 状态：独立审查及定向复审通过，**人类已于 2026-09-09 正式批准**（§10 六项批准项全数获批,可据此实施公共 API）。实施计划见 `research-wiki/plans/2026-09-09-135-call-observability.md`。
+> 日期：2026-09-09。范围：issue #19、#23。基线源码 HEAD e71a623。
+> 复用现有 Emitter / schema / 三条治理循环,不引入追踪平台、不做 deadline / hedging、不在库内复制上下游关联状态。
+
+## 1. 问题与边界
+
+治理单位是一次逻辑调用,但当前 `latency_ms` / `call_id` 只描述**单次尝试**:重试几次、等了多久、缓存有没有参与,SQL 答不出来。诊断侧,transport 抛出的领域错误已带 `status_code` / `operation` / `body_text`(errors.py:52),进 emitter 前却被 `str()` 压平成一列自由文本。终态失败可能没有选中源,但 **scope 始终已知**。
+
+中转把供应商 529 改写成 503 后,库只能如实记 503,不能猜回 529;未知成本、未知状态一律 NULL。本版不改重试预算、429 语义、stall、推理能力表与取消结算算法,不新增核心依赖。
+
+## 2. 方案
+
+| 方案 | 收益 | 代价 |
+| --- | --- | --- |
+| A：只在 RetryMW 加两个计数、错误列细分 | 补丁最小 | 漏缓存命中、结构化重问、embedding 分批与三类失败终态,回答不了"整次调用" |
+| B：每调用局部统计 + 领域异常下沉到单一出口,复用现有遥测行 | 统一边界、字段保真、不默认加成功行、不双计费用 | 增加内部上下文、响应字段与 recorder 字段;须补齐缺失的失败终态行 |
+| C：新增独立逻辑调用表 / 通用事件端口 | 完整追踪与任意事件分析 | 新存储与运维面,超出当前需求 |
+
+推荐 **B**。显式传递局部对象,不用 client 共享可变计数、不用模块级 ContextVar;不统一三条治理循环,只统一计数与诊断出口。
+
+## 3. 逻辑边界与公开统计
+
+四种响应(`LLMResponse`、`EmbeddingResponse`、`OcrTextResult`、`OcrLayoutResult`)追加 `call_stats: CallStats | None = None`。新增 frozen `CallStats` 并由包根导出——四份平铺字段会立刻漂移。
+
+| CallStats 字段 | 语义 |
+| --- | --- |
+| `logical_call_id: str` | 每次公开调用一个 UUID;重试、重问、分批共享;不占用既有 `parent_call_id` |
+| `attempts: int` | 准入后实际调用 transport 端口的次数;含免预算 429 与端口本地拒绝;**不是 HTTP 请求条数** |
+| `total_latency_ms: int` | 从输入校验通过到返回/异常传播前的单调时钟快照;含缓存、等待、重问、分批、内联记账与资源收尾 |
+
+输入校验异常发生在统计边界之外,保持原行为。第三方合成响应的 `None` 表示未知,不得默认伪造 0。
+
+- **缓存命中**:`attempts=0`、新 logical ID、本次缓存路径耗时;不回放历史统计。缓存持久化排除 `call_stats`(`_serialize` 显式剔除),`_rehydrate` 显式覆盖为 `None`——`_RESPONSE_FIELDS` 过滤会放行历史 dict,不覆盖就会有 dict 冒充 `CallStats`。缓存 key 白名单不变。
+- **embed 空输入**(embedding.py:180-190):合法零尝试,返回真实统计(`attempts=0`),**不写任何遥测行**——与 cache_hit 不同,不要按"必录"推断它有台账行。
+- **OCR layout** 的 POST + ZIP GET 在同一 transport 调用内(monkey_ocr.py:262-296),计 1 次尝试。
+- **chat 重问 / embedding 多批**计入同一上下文,不重置计数(重问经 `call_next` 重入 RetryMW,已核对)。
+
+`latency_ms` / `call_id` / `parent_call_id` 语义不变;"总耗时减最后一次尝试耗时"不等于纯等待(含其他本地工作)。不在响应里挂每次尝试的明细列表,避免公共响应无界增长。
+
+### 3.1 失败与取消
+
+本版**不向异常对象附加可变 `call_stats`**:第三方可能复用同一异常实例,first-write-wins 会把首次调用的统计误读成本次,覆盖写则串扰;复制任意异常又保证不了构造签名与自定义属性。异常类型与分类原样保留,失败侧的统计走 §6 的终态行。
+
+- 取消:`CancelledError` 保持原类型与语义,不在其上加字段;取消路径只**尽力**写一条终态,不 shield、不开新后台任务。
+- 任意内部非领域异常(编程错)原样传播,本版**不承诺**为其提供任何统计或终态行,也不偷偷改分类。
+
+## 4. 最小内部接缝
+
+`CallStats` 与私有可变 `_CallContext` 都落 `types.py`:`types.py` 不反向依赖实现层,不产生循环,也不动 import-linter 分层(`ports : types : errors` 并列最内层)。私有上下文只持计数、单调时钟与必要去重状态,不做 I/O。
+
+`ChatRequest` 追加内部上下文字段(`default=None, compare=False, repr=False`);`StructuredMW` 的 `dataclasses.replace` 保留同一引用(structured.py:96-110,已核对)。响应统计只在公共出口经 `replace` 附加。`GatewayClient` 需自存注入的 `now`(client.py 现未保存),**冻结快照是同步动作,不 await**。
+
+- 上下文创建/冻结:`GatewayClient` 在公开入口创建、`finally` 冻结;`RetryMW` 只在 transport 调用前登记一次尝试。
+- **OCR 例外(M1)**:`image` 的类型/空校验在 `_call` 内(ocr.py:238-241)而非公开方法,故上下文在该校验**通过之后**创建,§3 的"校验在边界外"对 OCR 才成立。
+- `EmbeddingClient` / `OcrClient` 显式把同一上下文传到每批/每次尝试;统计生效与否**不由 telemetry 是否启用决定**。
+- 每次尝试 ID 仍在当前循环产生,与上下文的 logical ID 一起交给 Emitter。不持久化断点,不引入任务恢复。
+
+## 5. 诊断字段与归因方式
+
+保留现有 `error` 字符串供人阅读;Emitter 改为接受**领域异常对象**而非调用方先 `str()`,由单一 helper 提取有限诊断字段。普通超时/网络翻译在 transport 侧保留直接 `__cause__` 类型,空 `str()` 退回类名;**不遍历任意异常对象、不猜测正文**。
+
+| 新增 INSERT 列 | 值域 / 来源 |
+| --- | --- |
+| `scope` | 配置池名,构造期注入 Emitter(见下);不拿 `source_name` 顶替 |
+| `operation` | **公开方法固定四值**:`chat` / `embed` / `recognize_text` / `parse_layout`;由三个 client 在调用点给定 |
+| `logical_call_id` | 当前调用上下文的 UUID;上下文缺席(库内现场构造的 `ChatRequest`)→ **NULL,不造 ID** |
+| `event_kind` | `attempt` / `cache_hit` / `terminal_failure`;旧行 NULL,不回填 |
+| `http_status_code` | **仅 attempt 行**:失败异常实收状态;无 HTTP 或未知 NULL;成功行不统一填 200 |
+| `error_type` | 该行自身错误的领域类名;成功行 NULL |
+| `cause_type` | **仅 attempt 行**:transport 直接捕获的底层异常类名,未知 NULL |
+| `error_body` | **仅 attempt 行**:既有 `summarize_body` 有界摘要,未知 NULL;不存 `raw_text`、不存全量原文 |
+| `attempts` / `total_latency_ms` | **仅 terminal_failure 行**填逻辑快照,其余行 NULL;快照在写入前冻结 |
+
+全部可空,追加到物理列末尾(与旧表 ALTER 追加位置一致,`schema.py` 的 DDL / BACKFILL / COLUMNS 三处同改)。
+
+**归因方式(C1,决定性)**:`GatewayUnavailableError` 家族从不携带 `status_code` / `body_text`(errors.py:118-166),终态行的 `http_status_code` / `cause_type` / `error_body` 因此**保持 NULL,这是它自身的真实状态**——不把最后一次 attempt 的状态码与正文搬上来伪装成整池诊断(那正是"不拿最后一个源冒充整池归因"的同一条红线)。终态行的 `error_type` 落它自己的类名(`AllSourcesExhausted` / `CircuitOpenError` / …),scope 级 reason 沿用**已有 error 文案**(`str(exc)` 已是 `"{scope} 网关暂时不可用: {reason}"`,不新增列)。逐源现场由同一 `logical_call_id` 的 attempt 行给出。
+
+```sql
+-- #19 验收:一次逻辑失败调用的完整现场(终态 + 各次尝试)
+SELECT event_kind, source_name, http_status_code, error_type, cause_type, error_body, error
+FROM llm_calls WHERE logical_call_id = :lcid ORDER BY created_at;
+```
+
+该查询必须同时给出"整池为何失败"(终态行 error 文案)与"每个源怎么死的"(attempt 行状态码/正文),测试按它断言。因此**本版不再为 `reason` / `per_source_reasons` 扩列**。
+
+**结构化耗尽的可定位性(C2)**:`ResultInvalidError("结构化输出阶梯耗尽")` 的 message 不含 `validation_errors` / `repair_error`(structured.py:80-86),而该失败发生在 StructuredMW 之上——RetryMW 侧的 attempt 行全是成功行,终态行是唯一记录。做法:**不写 `error_body`**(该列只属 attempt),由 Emitter 的单一 helper 对 `ResultInvalidError` 生成**有界结构化说明**并入现有 `error` 字符串,复用 structured.py 已有的取材口径(至多 3 条、每条 200 字符,与 `_format_errors` 同参数,拼装函数收敛在 helper 一处)。`raw_text` **不重复落库**(它是模型正文,attempt 行的 `response` 列已按 `text_cap` 记过一份;再存一份等于绕过既有正文预算)。该说明可能包含模型输出片段,故遵循与 `error` 现有正文相同的隐私边界,不额外扩大保留范围。
+
+**operation 的数据源(I1/I2)**:openai_compat.py:169 的 `_status_to_error` 硬编码 `operation="chat"`,而 `embed()` 的非 200 分支(:512)也走它 → 现存所有 embedding HTTP 失败的 `exc.operation` 都是错的。（行号勘误 2026-09-09:本句原写 "(:512、:527)",实测 `:527` 属 `_complete_stream`即流式 chat,`embed` 只有 `:512` 一处;归属以实施计划 §2 表为准,决策未变。）修正:`_status_to_error` 增 keyword `operation`,`embed` 传 **`"embedding"`**(沿用该异常侧既有词表,不改 `chat` / `ocr_text` / `parse` / `download_result` 四值)。新列 `operation` 与 `exc.operation` 是**两个语义**:前者是公开方法,后者是 HTTP 子操作;新列由调用点给定,**绝不读 `exc.operation`**,两者不做自动转换。OCR 两个公开方法各自在调用级给定自己的值。
+
+**scope 注入(M6)**:`TelemetryEmitter` 现在不知道 scope,`CacheMW` / `TelemetryMW` 自己也拿不到。构造期注入(三个 client 各一行),使 attempt / cache_hit / terminal_failure 三类行都带 scope,避免改三条调用链。model / provider / source 未选出时仍留原空值。
+
+**成功侧不加承诺**:成功行不承诺 HTTP 状态与错误体;**本版不宣称 SQL 可直接统计所有成功逻辑调用的总耗时**(成功不加终态行)。`error_body` 沿用 `summarize_body` 的既有上限,**不纳入 `PGW_TELEMETRY_TEXT_CAP` 覆盖面**(该键现覆盖四处,详见 §8)。
+
+## 6. 行语义与终态:只补确实缺失的失败
+
+保留每次 attempt 与 cache_hit 的既有行,**不为成功新增终态行**。终态行不得复制已有 attempt 的 token 与成本。所有统计边界内的领域失败均尝试写终态，**包括已有 attempt 错误行的直接 RequestRejectedError／ResultInvalidError**；不再沿用“该类错误已录所以外层不录”的旧假设，400 密集负载的错误行可能翻倍，调用失败计数必须只取 terminal_failure。
+
+**不变量(I3,统一措辞)**:
+
+| 结束形态 | 终态行数 |
+| --- | --- |
+| 以**领域错误**结束的逻辑调用 | 每次调用**尝试写一条**;持久化 best effort(recorder 写失败按既有降级只落 warning),故 SQL 可见行数 ≤ 1 |
+| 取消 | 三个 client **同策略尽力写一条**,允许 0 条 |
+| 非领域异常(编程错) | **0 条**,原样传播,本版无统计保证 |
+
+需要补的路径:chat 结构化耗尽(发生在 transport 成功之后,现无任何失败行)、embedding / OCR 的无源、准入拒绝、重试耗尽与尝试外取消。**取消口径统一(I4)**:chat 现由 TelemetryMW 对任何取消补终态(telemetry.py:487-495,含尝试内取消),embedding / OCR 按同一口径尽力补,避免下游按 `event_kind` 统计取消时拿到路径相关的结果。
+
+终态与 attempt **不是重复事实**(前者描述逻辑终态,后者描述尝试),用 `event_kind` 区分;**禁止按 `error IS NOT NULL` 跨两类直接计失败调用次数**。chat 现有 TelemetryMW 终态路径收敛到公开边界的单一 helper,避免两处同时写;embedding / OCR 复用该 helper。
+
+**终态行的请求摘要(M4)**:复用既有 200 字符输入摘要口径,描述**本次调用的整体输入**,但不扩大单行正文预算——embedding 终态取 `<embed texts=N batches=M>` 计数占位 + 第一批(至多 `batch_size` 条、每条 200 字符,与逐批行同款构造);OCR 终态沿用 `<ocr:{kind} image_bytes=…>` 占位,图像 bytes 永不入库。**失败批的具体文本由同 `logical_call_id` 的 attempt 行给出**,终态行不保存全量原输入。
+
+**错误文本口径(I7)**:OCR 现落 `"类名: msg"`(ocr.py:445-449,按类名归组的既有 metric 口径),chat / embed 落裸 `str(exc)`。改成"Emitter 收异常对象"后,该差异由统一出口的**显式文本策略参数**保留(OCR 保留类名前缀),**不再在三处复制参数列表**。
+
+**取消时的终态写(残余风险,显式定策)**:该 `await` 本身是新的取消点。策略是**取消优先、不屏蔽**:外部取消落在这一 await 上时,`CancelledError` 照常传播(调用方可能因此看到 `CancelledError` 而非领域错误,与 TelemetryMW 现有行为同款);不 shield、不建新后台任务。冻结统计快照是同步动作,不 await。
+
+终态行成本 NULL、usage `unavailable`;聚合费用仍只由 attempt / cache_hit 行决定。终态快照在写入前冻结,故不含自身写入耗时;成功响应快照包含其返回前已完成的内联遥测耗时。失败异常不附快照,不为对齐再 UPDATE 旧行。
+
+取消 attempt 既有字符串 `"cancelled"` 保留：Emitter接收 `PolyGatewayError | str | None`，字符串不解析猜测诊断，error_type/cause_type/http_status_code/error_body均NULL；终态取消同样使用明确取消文案。终态既有latency_ms与新增total_latency_ms取同一冻结快照，避免双时钟微差。
+
+## 7. recorder 兼容:装配期机械闸(C3)
+
+`TelemetryEmitter._record` 的 `except Exception` 会把旧 recorder 的 `TypeError` 吞成 warning(telemetry.py:463),后果是自定义 recorder 在下游升级后**100% 丢遥测且调用照常成功**——正是"遥测必录"要防的形态。文档级迁移清单挡不住它。
+
+机械闸:在 `TelemetryEmitter.__init__`(三个 client 的唯一汇流点,与 `text_cap` 值域校验同处)对 `recorder.record_llm_call` 做**一次** `inspect.signature(...).bind(**<完整新 kwargs 形状>)`,**不执行写入**;含 `**kwargs`(`VAR_KEYWORD`)者自动通过。校验失败 → 装配期抛错。若目标不可 inspect(C 实现等),同样按**配置错误**当场报错,不进入"运行期静默丢行"。
+
+边界诚实声明:签名 bind 只证明该形状能被接受,**不能证明函数体真的落这些列**;这是一道装配闸,不是行为验证。它既不是被否掉的 `runtime_checkable` 判定,也不是捕 `TypeError` 重试写入。是否扩主 `TelemetryRecorder` Protocol(备选:独立扩展端口保留旧实现)是 §10 的人类批准项;本草案不同时实现两套接口,自带两个 recorder 的 `**fields` 签名可接受新增参数,但其 schema、INSERT 字段与契约测试仍须同步,不能称后端完全不受影响。
+
+校验所用参数名从 `TelemetryRecorder.record_llm_call` 的协议签名派生，不手抄第四份字段清单；只用哨兵值做bind形状校验，不读取真实请求数据。结构化说明的限条数/限长复用现有常量，若需命名常量则在既有规则所有者中定义并由两个消费者引用，不复制数值。
+
+## 8. 下游可见变更与文档同步
+
+**SQL 迁移清单(I6,批准项须按此逐条看)**:
+
+| 影响面 | 变化 | 下游动作 |
+| --- | --- | --- |
+| 失败行数 | 新增 `terminal_failure` 行(每失败调用至多 1) | 计失败调用改 `WHERE event_kind = 'terminal_failure'` |
+| `error IS NOT NULL` | 同时命中 attempt 与 terminal 两类 | 不再作为"失败调用数"的判据 |
+| `AVG(latency_ms)` | terminal 行携带**逻辑总耗时**,量级大于单次尝试 | 时延看板一律按 `event_kind` 分组或过滤 |
+| 费用聚合 | terminal 行 `cost` 恒 NULL、usage `unavailable` | 费用仍只由 attempt / cache_hit 行决定,口径不变 |
+| 成功侧 | **不加**任何成功汇总行 | 成功逻辑调用总耗时仍从响应 `call_stats` 读,不从 SQL 读 |
+| `http_status_code` | 失败行上可能是 200(monkey_ocr.py:265-270 的 `success != true` 带 200 上抛) | 该列不可作失败判据 |
+
+**文档同步(M5,发布前必须同批)**:README:23 的"必录 26 字段"、README:399 与 ARCHITECTURE.md:592 的 `PGW_TELEMETRY_TEXT_CAP` 覆盖面四处枚举(须明确:`error_body` 沿用 `summarize_body` 上限,`error` 保留既有文本口径并仅对新增结构化说明限长;二者**不在 cap 覆盖内**)、ARCHITECTURE.md:565 的必录字段清单与 §7.8 补列一节、`.env.example` 相关注释、CHANGELOG 与 wiki(docs-convention §2)。**字段数与物理列数一律以 `inspect.signature` / `len(COLUMNS)` 实测改写,不凭记忆**(现状:26 个 INSERT 字段 + `created_at` = 27 物理列;本版新增 10 列)。
+
+## 9. 非功能与测试矩阵
+
+| 维度 | 要求 |
+| --- | --- |
+| 并发 | 每调用独立对象;同一 client 并发不串 logical ID / 计数 / 统计;无全局状态 |
+| 取消 | 各等待点穿透;`finally` 释放既有资源;终态写取消优先;不新增 shield 与后台任务 |
+| 降级 | recorder 写失败不改统计与主结果;准入后端仍 fail-closed;收尾失败仍原 warning |
+| 持久化 | schema 单一事实源;SQLite auto / PG manual 裁剪 INSERT 保持;不 ALTER 默认生产 PG、不改旧列、不回填旧行 |
+| 幂等 | attempt ID 唯一,终态独立 ID,不重复写同一终态;缓存命中不复制历史统计;不 UPDATE 计费 |
+
+验收优先离线:真实 client + 内存后端 + FakeClock + MockTransport + 临时 SQLite,复用 1.3.4 设施;不重跑未变的模型能力矩阵。
+
+| 测试族 | 必须证明 |
+| --- | --- |
+| logical 计数 | 一次成功、失败重试、免预算 429、多源拒绝、缓存命中、结构化重问、embedding 多批、OCR 双 HTTP、空输入(0 尝试且 0 遥测行) |
+| 计时 | 缓存 IO、退避、准入等待、重问、收尾均计入;关闭 recorder 仍正确;毫秒/秒不混用 |
+| 失败与取消 | 领域失败恰一次尝试写终态;取消三条路径同策略(允许 0 行);**终态写 await 上被取消 → `CancelledError` 传播**;permit / 探针释放不变;非领域异常 0 行且原样传播 |
+| 保真诊断 | 503 包装不改回 529;直接 529 记 529;空 Connect/Read/Write/PoolTimeout 文案有类型;embedding HTTP 失败的 `exc.operation` 为 `embedding`;新列 `operation` 恒为四值之一且不随异常变化 |
+| 归因 SQL | §5 那条按 `logical_call_id` 的查询同时给出终态 reason 文案与逐源状态码/正文;终态行三列为 NULL;结构化耗尽的 `error` 含有界 validation/repair 说明且不含 `raw_text` |
+| 行语义 | 三类行均带 scope;每失败调用至多一条终态;attempt 与 terminal 区分;费用不重复;`AVG(latency_ms)` 按 `event_kind` 分组的断言 |
+| 装配闸 | 旧签名 recorder → 装配期报错(非 warning);`**kwargs` recorder 通过;不可 inspect → 配置错误 |
+| 存储兼容 | SQLite 新旧表、PG manual 缺列裁剪 / auto 追加、旧行 NULL、新旧进程混写 |
+| 变异 | 计数位置、上下文复制、缓存历史回放、提前 `str()` 压平、终态双计费用分别红→绿;PG 真实集成 + 常规全套 + 独立验证 |
+
+## 10. 集中人类批准项
+
+| # | 决策 | 推荐 |
+| --- | --- | --- |
+| 1 | 公开响应结构 | 一个 `CallStats` 对象而非四类响应各铺三字段;需确认命名与消费便利性 |
+| 2 | 失败侧统计范围 | 不改/不复制异常;失败统计只落终态行,调用方仅在成功响应读 `call_stats`;需确认该取舍可接受 |
+| 3 | recorder 兼容路线 | 扩主 `TelemetryRecorder` Protocol + 装配期 bind 闸;备选独立扩展端口保留旧实现;需确认是否存在必须兼容的自定义 recorder |
+| 4 | 新增失败终态行 | 补漏但不加成功汇总;须批准 §8 表中**全部五项**下游可见变化(不止行数) |
+| 5 | 取消时终态写取消优先 | 调用方可能看到 `CancelledError` 而非领域错误(同 TelemetryMW 现状);需确认接受 |
+| 6 | `operation` 值域与异常侧修正 | 新列固定四值;`_status_to_error` 增 `operation` 参数、`embed` 传 `embedding`(修正现存误标,属下游可见的历史数据口径变化) |
+
+## 11. 独立审查处理表
+
+| 项 | 结论 | 落点 |
+| --- | --- | --- |
+| C1 终态缺诊断来源 | **不采纳"定向读 `__cause__` / `per_source_reasons` 扩列"**;终态保留自身 NULL 状态,归因由 `logical_call_id` 关联 attempt 行 + 既有 reason 文案完成,并写死 SQL 验收 | §5 |
+| C2 结构化耗尽可定位 | 采纳(变形):有界说明并入现有 `error` 字符串,不写 `error_body`、不重复存 `raw_text` | §5 |
+| C3 recorder 静默失败 | 采纳:装配期一次 `signature.bind` 形状校验,含 `**kwargs`,不可 inspect 即配置错误;明确不验证函数体 | §7 |
+| I1 / I2 operation 污染与未归一 | 采纳:新列固定四值由调用点给定,绝不读 `exc.operation`;只修 embedding 误标,其余异常侧词表不动 | §5 |
+| I3 / I4 终态不变量与取消口径 | 采纳(定稿措辞):领域失败每调用尝试写一条、持久化 best effort;取消三路同策略尽力允许 0;非领域异常 0 条 | §6 |
+| I5 上下文缺席语义 | 采纳:`None` → NULL,不造 ID | §5 |
+| I6 迁移影响不止行数 | 采纳:列全五项 SQL 影响并进批准项 | §8、§10 |
+| I7 OCR error 文本口径 | 采纳:保留类名前缀,由统一出口的显式文本策略参数承载,不复制参数列表 | §6 |
+| M1 OCR 校验与统计边界 | 采纳:上下文在 `image` 校验通过后创建 | §4 |
+| M2 embed 空输入 | 采纳:0 尝试且不写任何遥测行 | §3 |
+| M3 失败行可能带 200 | 采纳:写明该列不可作失败判据 | §8 |
+| M4 终态请求摘要未定 | 采纳:复用 200 字符口径,终态描述整体输入,不扩预算,不存全量原输入 | §6 |
+| M5 文档同步缺项 | 采纳:列全六处并要求实测改数字 | §8 |
+| M6 Emitter 不知 scope | 采纳:构造期注入 | §5 |
+| 残余风险(终态写成新取消点) | 采纳:显式定策"取消优先不屏蔽",并进测试族与批准项 | §6、§9、§10 |
+
+自审:方案 B 复用既有 Emitter / schema 与三条循环,不需要 #22 / #24 的新调度。未采纳的两项(异常 first-write-wins、终态搬运最后一次 attempt 的状态与正文)理由已写在正文,不是遗漏。本文档无代码实现与测试通过声明;**§10 六项已于 2026-09-09 获人类批准**,实施边界与红绿证据要求以上述实施计划为准。

research-wiki/designs/reasoning-effort.md

@@ -0,0 +1,16 @@
+---
+type: design
+node_id: design:reasoning-effort
+title: "推理档位一等化设计(issue #20 及其一般形式)"
+date: 2026-09-05
+---
+
+# 推理档位一等化设计(issue #20 及其一般形式)
+
+正文: `2026-09-04-reasoning-effort-design.md`。状态: **2026-09-04 人类已批准**。
+
+- **选定方案**: 方案 B「能力表档位化 + 源级/请求级双入口」。`Effort` 八档封闭枚举(含 `auto`)入 `types.py`;`ThinkingCapability` 由 `can_disable: bool` 改为 `supported_efforts: tuple[Effort, ...]`(「能不能关」= `none` 在不在列表里);`ProviderProfile` 的两个固定片段改为 `ThinkingWire(off / on_base / effort_key)`;生效档位 = 请求级 > 源级 > `enable_thinking` 语法糖。
+- **触发与真实缺口**: issue #20 字面要一条 zhipu profile,但补它不能解决它自己描述的失败——GLM-5.3 官方强制推理(智谱文档、cherry、OpenRouter 三源一致),`none` 是我们发出去的**未定义值**;而 `medium`(现 minimax profile 硬编码的档)在 GLM/kimi/deepseek 上根本不存在。缺口是**类型**表达不了现实,不是表里少一行。
+- **人类三项拍板(2026-09-04)**: 作用域「源级默认 + 请求级覆盖」;档位打空时「默认报错 + 可显式开 nearest 映射」;不可关闭时「报错并给出该模型最低档作为可执行替代」。复核 Codex 异议后追加确认: `effort_fallback` 随本期实现,不因当前无消费者而推迟。
+- **被否决备选及理由**: **方案 A 最小补丁**(只补 zhipu profile、维持 bool)——`thinking_on` 填什么档都是错的,`can_disable` 只能在「让下游跑不起来」与「登记一个官方否认的能力」间二选一,治标;**方案 C 照抄 cherry 完整 wire DSL**(closed operations、`effortMap`、`budgetWire`、endpoint-keyed contract)——它需要那层是因为要支持四种端点协议,而本库只有一个 OpenAI 兼容 transport,跨协议转换由 new-api 服务端完成,该复杂度当前无消费者(P1 YAGNI);**`default_effort` 字段**——自审把 `enable_thinking=True` 的语法糖改成 `Effort.AUTO` 后失去唯一消费方,厂商默认档降为 `evidence` 文本;**档位与 `reasoning_tokens` 的运行期对账**——无可判定的函数关系(实测同档 rt 在 8~56 间跳),报警必成噪声;**代下游裁剪采样参数**(DeepSeek 思考模式不支持 `temperature`)——那是「默认值掩盖错误」,记入 evidence 而不写进逻辑。
+- **审查留痕**: Claude 自审揪出两处实质缺陷(词汇缺 `auto`,导致 9 个纯开关型模型无档可填、等于把要修的 bug 重新实现一遍;五关顺序错置,使「关不掉」的特殊文案被通用分支吞掉)。Codex 独立审推翻两条**错误断言**: ① 源级 `extra_body`/`enable_thinking` **早已**经 `build_model_fingerprint` 进缓存 key(ARCH §7.5 有明文),不存在先前稿本断言的「现存毒化缺口」;② 「三项目无调用点」是对**不存在的目录**做 grep 得到的空结果,`reference/` 下当前并无三项目,迁移安全性只能是推断。另采纳其三条: 删 `default_effort`、补能力表落库规则、列出库内真实会断的调用点(`tests/unit/test_thinking.py:128` 的位置参数构造)。

research-wiki/docs-convention.md

@@ -2,7 +2,12 @@
 
 > **定位**: 用户文档站 = Gitea Wiki(`https://gitea.iomgaa.online/iomgaa/PolyGateway/wiki`);本文规定它的结构、更新时机与写作纪律。研发知识(设计/决策/验收)仍归 `research-wiki/`,两者职责不重叠。
 
-## 1. 结构:Diátaxis 四区(2026-07-23 建站,17 页)
+> [!CRITICAL]
+> **现状(2026-08-02 起):文档站已全量下线,当前只剩 `Home` 一页占位。** 八轮审查累计确认 93 处与源码不一致,近半落在参考区(手工镜像源码里已有的事实,必然漂移),且修正本身在引入次生偏差,逐轮修补不收敛——过期文档比没有文档更危险,它看起来权威。
+> Home 页现在做的唯一一件事是**把下游指向真实事实源**:签名/字段/参数语义 → 源码 docstring;全量环境变量键 → `.env.example`;版本变更与下游注意事项 → `CHANGELOG.md`;架构决策与行为论证 → `research-wiki/ARCHITECTURE.md`;快速上手 → `README.md`。
+> 历史内容未丢失,全在 wiki 仓库的 git 历史里(`git checkout e78bfb9 -- .`)。**本文以下各节描述的是重建时的目标结构与纪律,不是当前站点的现状**;在文档站重建之前,下面凡指向具体 wiki 页面的条目一律**不可执行**。
+
+## 1. 结构:Diátaxis 四区(重建目标;2026-07-23 建站 17 页,2026-08-02 全量下线)
 
 | 区 | 页面 | 职责(读者此刻要干什么) | 禁止 |
 |---|---|---|---|
@@ -25,6 +30,8 @@
 
 **门**: 版本 bump 的提交不允许单独存在——同一次交付里必须包含对应的 wiki/CHANGELOG 同步(发布检查清单第一项)。
 
+**站点下线期间(2026-08-02 至文档站重建)本表如何执行**: 上表左列的判据照旧,右列中指向具体 wiki 页面的项**全部落空,不必也无法执行**;仍然必须做的是 `CHANGELOG.md`、`README.md`、`.env.example` 与 `research-wiki/ARCHITECTURE.md` 四处。这道门因此**没有放松**——只是承接方从 wiki 换成了这四个文件,漏改它们与从前漏改 wiki 是同一性质的失败。
+
 ## 3. 写作纪律
 
 - 中文;表格优先;单个代码块 ≤ 15 行;每个配置片段可直接复制运行。

research-wiki/findings/2026-08-26-issue18-shared-pg-test-isolation.md

@@ -0,0 +1,91 @@
+---
+type: finding
+node_id: finding:2026-08-26-issue18-shared-pg-test-isolation
+title: "issue #18 实测: 偶发红的是安全网本身,不是被测脚本"
+date: 2026-08-26
+---
+
+# issue #18 实测：偶发红的是**安全网本身**，不是被测脚本
+
+> 类型：finding｜日期：2026-08-26｜实例 `polygateway` 库（PostgreSQL 16.14，共享）
+> 本文是 `designs/2026-08-26-issue18-pg-test-isolation-design.md` 的事实基础。
+> 实测与推断在 §5 明确分界——推断部分未做复现实验，不当作既定事实使用。
+
+## 1. 失败断言的唯一归属
+
+`assert 12 == 61` 只能对应 `test_retention_tool_pg.py::TestPlainTableBatches::test_apply_deletes_only_expired_rows_in_batches` 的最后一行：
+
+| 断言 | 形态 |
+|---|---|
+| `_call_ids(schema_dsn) == ["fresh-1", "fresh-2"]` | 列表比较，失败会打印列表 |
+| `"将删除行数: 5" in result.stdout` 等五条 | 子串判定，失败不打印数字对 |
+| `await _public_count(dsn) == before_public` | **整型比较，唯一能报出 `12 == 61`** |
+
+`before_public` 在 seed 之前取，`12` 是脚本跑完后的复测值。
+
+## 2. 被测脚本没有越界
+
+失败发生在最后一条，意味着它前面全部通过：`_call_ids(schema_dsn)` 恰为 `["fresh-1","fresh-2"]`（临时 schema 里 5 行过期行被删、2 行新鲜行留下）、stdout 里出现 `<临时schema>.llm_calls`、`将删除行数: 5`、三条批次行齐全。
+
+若 `search_path` 曾失效、脚本打到了 `public.llm_calls`，那么临时表 7 行一行不少，第二条断言就会先红。**故本次失败与 `telemetry_retention.py` 的行为无关**。
+
+## 3. 共享表的实测现状
+
+以 `.env` 的 `PGW_TELEMETRY_PG_DSN` 直连查得（2026-08-26）：
+
+| 项 | 实测值 |
+|---|---|
+| `public.llm_calls` 行数 | **11**，非分区普通表 |
+| 这 11 行的 `created_at` | 全部落在 `2026-07-22 14:00 ~ 14:26` |
+| 这 11 行的 `call_id` 形态 | 裸 hex 前缀（`3c915c04`、`c8071b6a` …）与一个 `c1`，**不是** `pgwtest-` 前缀 |
+| 表属主 / ACL | `app` / `{app=arwdDxt/app, chs3_test=ar/app}`（无 PUBLIC 授权） |
+| `.env` 里那个角色 | `app`，`rolsuper = true`、`rolcreatedb = true`、`rolcreaterole = true` |
+| 服务端版本 / 连接 | PostgreSQL 16.14；`max_connections = 100`，查时 54 个连接在用 |
+| 残留临时 schema / 角色 | 无（`pgw%` 命名下均为空） |
+
+失败时的 `12` 与这个 `11` 行基线同量级；`61` 意味着取快照那一刻库里另有约 49 行，随后消失。那 11 行是一个多月前留下的**孤儿行**：它们早于 7 天截止线，任何一次带 `--apply` 的存量清理都会删掉它们——这本身说明真实共享表上确实存在"测试/工具写完没清干净"的历史。
+
+## 4. 本仓库自己就是共享表的写入方
+
+`tests/integration/test_postgres_telemetry.py` 存在两套并行的隔离手法：
+
+| 手法 | 用在哪 | 是否触碰 `public.llm_calls` |
+|---|---|---|
+| 临时 schema（`legacy_schema`、`fresh_schema`、`pre_tenant_schema`、`partitioned_schema`、`least_privilege_dsn`、`least_privilege_pre_tenant_dsn`、`production_template`） | 需要特定表形态的用例 | 否，teardown 走 `DROP SCHEMA CASCADE` |
+| `_RUN_PREFIX` 前缀（模块级 `pgwtest-<uuid8>`） | `TestObservabilityColumns::test_values_round_trip`、`TestSchema` 三条、`TestDegradation` 两条、`TestPoolFootprint` 一条，**共 7 条** | **是**，写入真表，`dsn` fixture teardown 执行 `DELETE ... WHERE call_id LIKE '<前缀>-%'` |
+
+前缀隔离对**读**是完备的（每个进程只看自己的行），对**全表口径的观测**不设防——而 `_public_count` 正是全套件里唯一一处全表口径。
+
+## 5. 实测与推断的分界
+
+**实测（本会话工具输出）**：§1 的断言归属、§2 的失败顺序推理、§3 的全部数字、§4 的用例清单。
+
+**推断（未做复现实验）**：那 49 行的来源。同一 pytest 进程内 `test_postgres_telemetry.py` 排在 `test_retention_tool_pg.py` 之前（文件名序），且其 `dsn` fixture 是函数级、每条用例后立即清理，故同进程解释不成立；最合理的解释是**另一个进程**在同一秒窗口内完成了一轮"写 7 条 → teardown 删掉"的循环——并行的另一个开发会话，或 `~/Projects/m4-worktrees/` 下迁移项目的批跑（三个迁移项目正是用本库往这张表写遥测）。
+
+这条推断不影响结论：无论那 49 行由谁写删，`public.llm_calls` 的行数都是**不归本测试控制的全局可变量**，把它当断言基线在设计上就不成立。
+
+## 6. 与 `_public_count` 的设计意图的落差
+
+该断言的注释写明它要防的是"`search_path` 没生效导致静默删库"。行数快照防不住这件事：
+
+- **假红**：任何外部写/删都让它红（本次即是），而脚本完全正常
+- **假阴**：外部并发的增减可以与脚本的误删互相抵消，行数相等则静默放行——它守的是删库，这一半失效才是真正的代价
+
+一个安全属性被编码成对全局可变量的观测，两个方向都不成立。
+
+## 7. 方案可行性的实测(2026-08-26,同一实例)
+
+用一次性角色/schema 做的证伪实验(建 `pgwprobe_r_*` 角色 + `pgwprobe_s_*` schema,跑完全部 `DROP`,实例上无残留):
+
+| # | 探针 | 结果 |
+|---|---|---|
+| 1 | 角色以自己身份建表 | 属主为该角色(与"用维护角色跑"的现场一致) |
+| 2 | `to_regclass('"<schema>"."llm_calls"')` | 正常解析到该表 |
+| 3 | `to_regclass('"nosuch_schema_xyz"."llm_calls"')` | **返回 NULL,不抛错** |
+| 4 | `to_regclass('"<SCHEMA 大写>"."llm_calls"')` | **返回 NULL** —— 引号限定名区分大小写 |
+| 5 | 临时角色**裸连**(不挂 search_path) | `SHOW search_path` = `"$user", public`,`to_regclass('llm_calls')` 命中真表 |
+| 6 | 裸连对真表 `SELECT COUNT(*)` | `InsufficientPrivilegeError: permission denied for table llm_calls` |
+| 7 | 裸连对真表 `DELETE ... WHERE created_at < now()` | `InsufficientPrivilegeError: permission denied for table llm_calls` |
+| 8 | 角色名与 schema **同名**时裸连 | `"$user"` 命中自有 schema,**遮蔽 public** |
+
+第 6、7 条是新方案的核心防线：最坏情况下脚本连数都数不出来，更谈不上删。第 8 条是一条必须写进设计的约束——今天 `least_privilege_dsn` 的角色与 schema 恰好同名，若沿用该形态，"search_path 落到 public"的最坏情况用例会走到自有 schema 上，测出来的是个假现场。

research-wiki/findings/2026-09-09-134-thinking-contracts-validation.md

@@ -0,0 +1,268 @@
+---
+type: finding
+node_id: finding:2026-09-09-134-thinking-contracts-validation
+title: "1.3.4 推理契约验证与发布准备"
+date: 2026-09-09
+---
+
+# 1.3.4 推理契约验证与发布准备
+
+> 最新状态（2026-09-09）：**1.3.4 已发布并完成外部验收，#21/#25/#26 已评论关闭**。main/tag 指向 `af57f93adce24b43fd10b6d8e1281ab8ee43c0a8`；合并后门、下载独立安装及页面结果见文末。用户批准的未补全矩阵、FAIL／UNKNOWN／不可达／缺轮及缺下游配置例外保持原结论，不冒充 PASS。以下为分阶段历史，不追改当时结论；原始输出在 `tests/outputs/134/`，不提交。
+
+## 基线与修改边界
+
+| 项目 | 实际证据 |
+| --- | --- |
+| 起点 | `6a09054`，保留既有两个本地测试提交，工作区仅原 `.pi/` 与待提交设计／计划 |
+| T0 静态 | `t0-check.log`／`.exit`：make check，退出 0，import-linter 1 kept |
+| T0 指定测试 | `t0-baseline.log`／`.exit`：660 passed，退出 0 |
+| 生产范围 | 只修改 thinking／providers／client／openai_compat 四文件；端口、类型、缓存指纹、遥测 schema、embedding／OCR 循环未改 |
+| 文档回滚 | `2553fc7`／`dda5556`；wiki 工具 add_entity 会覆盖无 frontmatter 的同名文件，故先补原文 frontmatter，再以节点存在性保护调用工具，显式登记图节点／implements 边 |
+
+## 红绿证据
+
+| 任务 | 红证据 | 绿证据 |
+| --- | --- | --- |
+| T1 AUTO 成员／MiniMax／未知告警 | `t1-red.log`：9 failed，103 passed；都是未拒绝／旧 medium／缺不保证文案 | `t1-green.log`：112 passed |
+| T1 可执行迁移文案 | `t1-guidance-red.log`：1 failed，旧错误无配置例 | `t13-followup-green.log`：220 passed（含探针收尾） |
+| T2 on_base 不偷带档 | `t2-wire-red.log`：12 failed，旧解析接受非法开启片段 | `t2-green.log`：137 passed |
+| T2 raw 纯守卫 | 隔离 `raw-guard` 变异：28 failed，含嵌套根与所有档位 | 还原退出 0；详见 mutation-summary.json |
+| T3 标准 raw 实际 HTTP | `t3-raw-red-valid.log`：21 failed，旧 transport 发出了冲突请求 | `t3-green.log`：526 passed（工厂／配置／transport／retry／纯解析） |
+| T3 前置／准入 | `t3-entry-red.log`：4 failed，旧工厂构造后端／请求进入洋葱／冲突未拒绝 | 同上；额外半开探针测试证明可再次取得探针且 inflight=0 |
+| T3 自定义根 | 隔离 `custom-guard` 变异：3 failed，丢 wire 后私有根绕过 | `t3-custom-green.log`：3 passed |
+| T4 迁移 | `cache-isolation` 变异：去掉显式身份后能力／fallback／wire 各节点红 | `t4-final-green.log`：190 passed（缓存与遥测）；新旧身份回滚、租户、多源和 per-call 覆盖均有断言 |
+| T4 命中遥测 | `cache-row` 变异：1 failed，历史 low 不应替代本次 medium | 还原退出 0 |
+| T7 客户端 NULL | embed False→True：6 failed；OCR False→True：12 failed（text／layout 独立红） | `t7-final-green.log`：328 passed |
+| T7 阳性／emitter | chat True→False：并发实际档断言失败；去 applies 短路：6 failed | 各还原退出 0；chat 糖失败 auto、nearest 失败 medium／成功 low 另有真实链路断言 |
+
+隔离副本来源由 `mutation-import.log` 验证，路径为 `/tmp/pgw134-mutation-*`；无 `.env`、reference、`.pi/`。脚本 `mutate.py`、汇总 `mutation-summary.json`、逐例 `mutation-*-red.log/.exit` 和 `mutation-*-restored.log/.exit` 均留存。11 个变异全部退出 1，逐例还原全部退出 0，恢复后校验文件散列。factory 三个变异分别抓到 Authorization 缺失、timeout 退回 5 秒、trust_env 写死 True。
+
+## 调试记录（不把无效红当证据）
+
+| 现象 | 根因与处理 |
+| --- | --- |
+| 初始 raw 红测试反而 21 passed | 测试选 qwen 纯开关形态却请求 HIGH，旧实现先因形态拒绝；改用可表达 HIGH 的 openai 后全部因目标未拒绝而红。`t3-raw-red.log` 不计红证据，使用 `t3-raw-red-valid.log` |
+| 默认 HTTP factory 新测试 5 failed | 开发机 `socks://` 代理被 httpx 构造拒绝；测试 autouse 删除代理环境，仅隔离外部条件，不改生产 factory，仍分别验证 trust_env True／False。`t3-isolated-green.log`：207 passed |
+| factory 失败随 T3 提交进入历史 | `8e61a66` 当时附带上述未隔离测试；随后 `71f1bdf` 独立修复。最终工作区全绿；不声称每个历史提交均全绿 |
+| per-call 迁移工厂测试缺缓存参数 | 合成 env 仍为 cache_backend=none，loader 正确清空 namespace／ttl；改为 memory＋显式 TTL，新测试 9 passed，不改生产配置默认 |
+| conda run 默认捕获模式下 stdin 脚本未执行 | T0 第一次文档提交只有原始两文件；通过 --no-capture-output 重跑安全登记并单独提交，未将第一次零输出当登记成功 |
+| pi-lens LSP 报缺 pytest／loguru、旧 StrEnum Literal 噪音、Python 3.12 语法不支持 | 非 conda 解释器限制；父监督明确批准记录并继续既定 conda pytest／ruff／import-linter，不改枚举／不加 ignore。后续异步 stale 测试报告已标 superseded，最终实际全量单测输出为准 |
+
+## 当前检查与后续门
+
+| 检查 | 结果 |
+| --- | --- |
+| `conda run --no-capture-output -n PolyGateway pytest tests/unit/ -q` | `last-unit.log/.exit`：**1241 passed，3.95 秒，退出 0** |
+| `make check` | `last-check.log/.exit`：格式／ruff／import-linter通过，退出 0 |
+| `git diff --check` | 通过 |
+| 本轮网络／slow | 未执行；所有 HTTP 为 MockTransport，SQLite 为临时文件，无付费调用 |
+| 独立 verifier／集成／slow／下游迁移 | 由父会话后续执行，本轮不声明通过；设计所列真实缺测和下游缺失仍有效 |
+
+日志方案沿已批设计：未知能力沿既有 loguru warning，实际调用仍经 TelemetryEmitter 单点出口，四类行来源和 NULL 契约用既有 schema 验证，不新增运行时数据面。
+
+## T5／T6 与 T8 文档续作（起点 16fa0ca）
+
+本续作禁止发布／slow／付费调用，未改任何生产文件。已读完整批准设计、计划及 TDD／structured-logging／commit 技能。独立验证与全量集成／live 仍由父会话负责，本节不表示整个版本验收完成。
+
+| 门／节点 | 本会话实际结果／原始日志（tests/outputs/134/） |
+| --- | --- |
+| 受影响基线 | `t56-baseline.log`：client/config/openai_compat **338 passed** |
+| T5 新模块首次 | `t5-first.log`：98 passed；首次无行为红不计TDD，红证据来自下述隔离变异 |
+| 当前受影响 | `t56-current-diagnostics-proof.log`：client/live_evidence/config **325 passed**；旧异步2/131通知已被当前结果取代 |
+| 日常全单元 | `t56-accepted-unit.log/.exit`：**1357 passed，exit 0**（其后仅取证关联/报告字段收尾，受影响325再通过，最终门见提交日志） |
+| 静态 | `t56-accepted-check.log`：make check 通过；compileall 测试支持模块通过；生产43模块123依赖、1契约通过 |
+| live 采集 | `t56-accepted-collect.log/.exit`：e2e **90 tests collected，exit 0**；仅采集，不是真实通过 |
+
+### 隔离语义红→还原绿
+
+仓库外临时副本只复制 src/tests/必要工程文件，不复制 `.env`、reference、`.pi`；PYTHONPATH及 cwd 指向副本，import来源见 `t56-mutation-import.log`／`t56-consumer-mutation-import.log`。每个变异均目标 AssertionError、退出1，恢复散列一致后节点退出0，不靠 import error 当红。
+
+| 变异 | 目标节点（tests/unit/test_live_evidence.py） | 红／还原 |
+| --- | --- | --- |
+| 整类 skip | test_whole_exception_class_skip_is_forbidden | 1／0 |
+| 正文子串 model_not_found | test_incomplete_or_ambiguous_error_body_fails | 1／0 |
+| UNKNOWN 安静→PASS | test_coverage_is_proposition_specific | 1／0 |
+| 缺轮缩分母 | test_missing_round_never_reduces_denominator | 1／0 |
+| 身份无证据→skip | test_identity_requires_independent_raw_evidence | 1／0 |
+| 丢第一轮 | test_round_consumer_keeps_first_success_when_second_assertion_fails | 1／0 |
+| 部分档未覆盖→模型PASS | test_partial_uncovered_and_failed_rounds_never_become_model_pass | 1／0 |
+| 不交付独立raw快照 | test_raw_identity_snapshot_reaches_round_consumer | 1／0 |
+
+汇总与逐例日志：`t56-mutation-summary.json`、`t56-consumer-mutation-summary.json`、`t56-mutation-*-{red,restored}.log`；脚本 `mutate-live.py`／`mutate-live-consumer.py`。主工作区从未放回假绿策略。
+
+### 实现与矩阵边界
+
+取证按 session/parent→attempt→HTTP；零HTTP和多HTTP分开，404严格唯一完整证据，成功非流式原始JSON独立解析并拒重复键。成功SSE不预读、不捕获。真实RetryMW两并发逻辑轮次各503→成功验证精确成功call_id；取消ContextVar复位、资源关闭与逐轮报告写失败显式失败均有离线节点。报告不保存任何原始正文/异常，白名单字段含校验布尔、状态、身份资格与固定安全原因；假凭据/提示词sentinel逐文件无泄漏。
+
+四live文件均迁入窄通道，装配拒绝/平铺键/合成Protocol移入日常；外部Protocol缺包单列未覆盖。M3真实开启改medium，M2 AUTO复用既有T10档；L4迁为退出受管的raw-only高档，双来源本地拒绝由已实现单测守卫。L8不可关闭装配拒绝不计live，未知wire仍显式全None离线验证。UNKNOWN不靠completion长度或prompt锚点升格；L2b仅保留指定历史prompt锚点命题，不是关闭能力。
+
+默认轮数/并发未增加，删除额外UNKNOWN长度锚点调用；T10保留既有一次重试设置，去除60s stall缩小值。静态矩阵：L1–L7合计93逻辑调用，L8可关闭19型号×5=95，T10 NONE 26×5=130及条件长复核≤78，开启57档×5=285，默认基线15，其他chat6+embed1=7；总上界703，不含既有治理重试/结构化重问。没有执行这些调用。
+
+### 调试与未验证项
+
+| 项 | 实际处置 |
+| --- | --- |
+| 新RetryPolicy测试参数误写base_delay_s | 当前工具实报TypeError，查源码后改backoff_base_s/backoff_max_s，239及后续242/325通过；该失败不计目标红 |
+| make check初报SIM117/B017 | 合并测试上下文，按真实解析异常指定类型，不加ignore；最终静态门通过 |
+| pi-lens解释器/StrEnum噪音 | 记录 `t56-diagnostics.txt`，conda内真实导入与ruff为门，不改任务外枚举；pytest wrapper generator的return report是协议必需，独立next/send/StopIteration.value测试通过 |
+| T10型号→400机器字段基线不存在 | 父会话明确确认：不编造白名单，实际400默认FAIL并逐轮留证。纯负向契约精确类型/状态/type单独测试；具体live预期拒绝未验证、需人工基线 |
+| 结构化反馈重问（已被本次审查修复替代） | 原固定摘要会误拒正常反馈重问，独立审查判 P1；不再保留为可接受限制，修复与真实 StructuredMW 离线两响应证据见下节 |
+| 发布/集成/live/下游 | 本任务未执行，M2空wire、M3非流式UNKNOWN、身份不足、三项目实际配置缺失仍保留为证据门 |
+
+文档已同步README M1–M9、CHANGELOG未发布段、env注释、ARCH D11/5.1/7.5/7.8、旧设计替代指针及既有schema/metric；无版本bump、无新生产字段/DDL。Wiki站已下线，不虚报线上页更新。
+
+续作提交：`73008ad test: apply evidence-based live checks without hiding regressions`。最终提交前实际门：`t56-precommit-unit.log/.exit` **1357 passed/0**，`t56-precommit-affected.log` **331 passed**（包含生产默认factory节点），`t56-precommit-check.log/.exit` **make check通过/0**，`t56-precommit-collect.log` **90 collected**，`t56-precommit-compile.log`通过；`git diff --check`通过，`git diff --quiet -- src`确认生产零差异。T8仅文档部分完成，不勾选完整验收门。
+
+## 独立审查四项修复（起点 d332287）
+
+按 receiving-code-review 对照实际调用链核验 `verify134/live-contracts.md`：四项均成立。此处沿用户限定仅更新既有 finding／plan，不新建图实体或扩写设计。生产／版本零差异；没有 live、付费请求或子代理。本节是实现者核验，不冒充新一轮独立复审。
+
+| 审查项／核验依据 | 最小修复与守卫 |
+| --- | --- |
+| P1 结构化重问：StructuredMW._with_feedback 追加两消息，旧 hook 固定完整摘要必错 | 仅结构化模型 smoke 启用原提示词前缀摘要、成对 assistant/user 字符串与已有预算；首个 attempt 仍精确原消息。薄委托保存本次摘要只校验 HTTP 保真，不从 wire 反填预期，不关闭重问。真实 GatewayClient＋StructuredMW＋MockTransport 缺字段→合法响应恰两 HTTP PASS；破坏前缀、角色、内容类型、配对、预算、wire 均 FAIL；首轮凭空反馈另有 FAIL 守卫 |
+| P1 未登记候选：旧 None 分支被置 cannot_disable，ABSENT 假失败 | 明确 observation-only，先全轮请求／身份资格，再 UNCOVERED；ABSENT／OBSERVED／UNKNOWN 与资格 FAIL 四组运行真实 T10 消费者（剔除 .env 读取语句），不调用模型、不改长复核条件或轮次 |
+| P1 结论重新 UUID，多个型号失去对应关系 | 每用例显式传同一 run/model；子运行用该 run 下唯一 matrix_id 关联，结论含完整计划／完成分母。L1–L8、T10短长／各档／默认全部复用；两型号一 PASS 一 UNCOVERED，在 NONE、tiers、L8 三组逐文件验证关联和轮数 |
+| P2 机器字段未落盘 | 仅精确 model_not_found 保留；其他字符串（含假凭据 sentinel）为 omitted；写入端再拒未知机器值，绝不输出任意上游 type |
+
+### 本轮先红后绿与验证
+
+日志位于 `tests/outputs/134/`，各命令结果后立即保存 `.exit`，原命令不接管道。
+
+| 命令／节点 | 红证据 | 绿证据 |
+| --- | --- | --- |
+| `pytest tests/unit/test_live_evidence.py -k structured_reask -q` | `review-f1-red`：1 failed／6 passed，合法两响应误判 FAIL，exit 1 | `review-f1-green`：7 passed，exit 0 |
+| `pytest tests/unit/test_live_evidence.py -k first_attempt_requires -q` | `review-f1-first-red`：首轮多反馈被放行，1 failed，exit 1 | `review-final-affected`：含该节点共129 passed，exit 0 |
+| `pytest tests/unit/test_live_evidence.py -k unregistered_candidate -q` | `review-f2-red`：ABSENT 被误判FAIL，1 failed／3 passed，exit 1 | `review-f2-green`：4 passed，exit 0 |
+| `pytest tests/unit/test_live_evidence.py -k capability_conclusions -q` | `review-f3-red`：三组结论缺型号断言红，3 failed，exit 1 | `review-f3-green`：三组＋未登记四组共7 passed，exit 0 |
+| `pytest tests/unit/test_live_evidence.py -k safe_machine_type -q` | `review-f4-red`：三组缺机器字段，3 failed，exit 1 | `review-f4-green`：3 passed，exit 0 |
+| `conda run --no-capture-output -n PolyGateway pytest tests/unit/ -q` | — | `review-final-unit`：**1375 passed，exit 0** |
+| `make check` | — | `review-final-check`：格式／ruff／import-linter 1 kept，exit 0 |
+| `conda run --no-capture-output -n PolyGateway pytest tests/e2e/ -m slow --collect-only -q` | — | `review-final-collect`：**90 collected，exit 0**；不是90通过 |
+
+上表节点命令也均加 `conda run --no-capture-output -n PolyGateway`；未使用缺 import 的伪红。最终受影响文件129单测通过，相比111新增18节点。pi-lens仍提示非conda缺httpx/pytest/pydantic及StrEnum等旧噪音，按已批准方向记录后继续conda门；新增测试命名空间显式 Any 类型，不抑制真实错误。
+
+**尚未完成**：修复后独立复审、集成／make test覆盖率、真实能力取证、下游迁移和发布；T8/T9保持未勾选。M2空wire、M3非流UNKNOWN、真实机器拒绝白名单及外部服务状态不因离线绿变成已覆盖。
+
+## 重启恢复与 embedding 报告补漏（起点 3eb22d2）
+
+恢复时实际分支为 `feature/1.3.4-thinking-contracts`，HEAD=`3eb22d2`，已跟踪工作区无差异，仅既有 `.pi/` 未跟踪；前轮代码提交仍在，重启未丢代码。按用户限定只修测试与本 finding，不动生产 API／版本／计划，不联网、不付费、不运行 slow、不派子代理。本节为实现者验证，不冒充独立复审或版本验收。
+
+原 `tests/outputs/134/slow-gate.log` 保留，大小 1625 字节；`slow-gate.exit` 不存在，属于重启中断、未取得终态，不能宣称 slow 通过。修复前后 SHA-256 均为 `05967dcf749b13db815dd80449a0db5b3e7ad2144aa2ae216f8c9ab5ecb21bf5`。历史日志不覆盖、不续写，也不把旧 full-gate 作为本轮测试证据。
+
+| 根因／范围 | 本轮修复与证据 |
+| --- | --- |
+| embedding 消费者遗漏四个字段 | 仅在原 finally 报告出口增加 `requested_model=source.model`、`provider=source.provider`、`planned_rounds=1`、`completed_rounds=1`；完成计数指已收尾轮次，FAIL／UNCOVERED 也计入，不代表成功。沿用原 matrix／round／session／parent／attempt 关联，不新建报告框架 |
+| 环境可覆盖请求型号 | 既有 `test_live_evidence.py` 增加真实 probe 消费者回归：AST 仅剔除 `.env`／pytestmark 顶层读取，合成环境实际经过 GatewaySettings；两种 probe 型号覆盖都与原 chat 型号不同，HTTP 与报告必须等于本次 source，不能拿默认型号占位 |
+| 成功与所有目标错误路径 | 真实 OpenAICompatTransport＋LiveCapture＋ObservedTransport＋报告写入；仅 HTTP 边界 MockTransport。两型号×成功／503／严格404／ConnectError 共8节点，分别 PASS／FAIL／UNCOVERED／FAIL；同时断言唯一报告、逻辑 UUID／attempt 配对、请求校验、状态／错误类型与客户端关闭 |
+| 安全边界 | 假凭据及私有提示词 sentinel 放入成功 model 回显、错误正文和请求异常；逐份 Markdown 断言不泄漏，仍只写安全机器枚举／固定原因，不复制原始正文与异常 |
+
+日志均在 `tests/outputs/134/`，命令不接管道，先保存真实退出码到同名 `.exit` 再展示输出。
+
+| 命令（pytest 前缀均为 `conda run --no-capture-output -n PolyGateway`） | 实际结果／日志 |
+| --- | --- |
+| `pytest tests/unit/test_live_evidence.py -k embed_probe_report -q`（修复前） | `embed-report-red.log/.exit`：8 failed，129 deselected，exit 1；八例均在真实报告消费处 `KeyError: requested_model`，不是 import／mock 签名失败 |
+| 同命令（四字段补齐后） | `embed-report-green.log/.exit`：8 passed，129 deselected，exit 0 |
+| `pytest tests/unit/test_live_evidence.py tests/unit/test_embedding.py tests/unit/test_openai_compat.py::TestDefaultClientFactory -q` | `embed-report-affected.log/.exit`：188 passed，exit 0 |
+| `pytest tests/unit/ -q` | `embed-report-unit.log/.exit`：1383 passed，exit 0；格式化后 `embed-report-final-unit.log/.exit`：1383 passed，4.45秒，exit 0 |
+| `make check` | 首次 `embed-report-check.log/.exit` 为新断言排版失败（exit 2），不是行为红；仅对该测试文件运行 conda ruff format。`embed-report-check-green.log/.exit`：94文件格式合格、ruff通过、import-linter 1 kept／0 broken，exit 0 |
+
+pi-lens 仍报非 conda 解释器缺 httpx／pytest／dotenv／pydantic 及旧 StrEnum 噪音；按任务授权记录，不添加 ignore、不改枚举、不扩环境修复范围。实际 conda 解释器为 `/home/iomgaa/miniconda3/envs/PolyGateway/bin/python`，本会话导入四依赖成功（httpx 0.28.1、pytest 9.1.1、python-dotenv 1.2.3、pydantic 2.13.4）。conda 启动器自身另有 base Python 3.13 的 RequestsDependencyWarning；未静音，不宣称输出零告警，测试进程与静态门实际退出0。
+
+本修复不补写真正缺失的历史报告、不改变 embedding 能力判据；真实服务、slow、下游与发布证据仍由后续验收负责。
+
+## 独立审查补正：取消不计完成轮（起点 7f6a824）
+
+独立 verifier 指出：probe 的 finally 无条件写 `completed_rounds=1`，但 CancelledError 穿透时仍是 `FAIL／轮次未完成`，分母记录自相矛盾。已对照源码并在真实消费者复现，接受该问题；上节“已收尾即完成”的措辞不适用于取消，本节修正为**取得正常成功或普通异常分类终态才算完成**，不是 finally 执行过就完成。
+
+最小修复仅在 probe 初始化 `completed_rounds=0`，成功判定或普通异常分类返回后置1；finally 写实际计数。取消仍穿透、计数保留0，不新增捕获 BaseException、不动生产 API／版本／分类器。扩展原消费者参数化测试增加两型号取消节点：真实 task 在 MockTransport 进入等待后由调用方 cancel，断言 CancelledError 穿透、task.cancelled、报告 FAIL／未完成、planned=1／completed=0、原调用关联及客户端关闭；其他8例保持完成1。所有节点只替换外部 HTTP，不联网、不付费、不跑 slow。
+
+| 命令（pytest 前缀为 `conda run --no-capture-output -n PolyGateway`） | 本轮实际证据（tests/outputs/134/，各有 .log／.exit） |
+| --- | --- |
+| `pytest tests/unit/test_live_evidence.py -k 'embed_probe_report and cancelled' -q`，修复前 | `embed-cancel-red`：2 failed／137 deselected，exit1；两例均先验证取消穿透、报告存在及资源关闭，再因 `completed_rounds` 实际1而期望0失败 |
+| `pytest tests/unit/test_live_evidence.py -k embed_probe_report -q`，修复后 | `embed-cancel-green`：10 passed／129 deselected，exit0；覆盖原8例与新增2例 |
+| `pytest tests/unit/ -q` | `embed-cancel-unit`：1385 passed，4.08秒，exit0 |
+| `make check` | `embed-cancel-check`：格式／ruff通过，import-linter 1 kept／0 broken，exit0 |
+
+既有非 conda LSP 误报继续只记录（本次额外将 `asyncio.timeout` 误判为缺属性）；conda pytest 实际可执行，base RequestsDependencyWarning 未静音。此处是针对独立审查问题的实现及自验，修复后独立复核仍交父会话；不冒称审查门或版本验收已通过。原 slow 日志不改写。
+
+## 1.3.4 发布准备与用户验收例外（2026-09-09，起点 b7e6943）
+
+**授权与边界**：用户正式批准不再补全模型矩阵，保留失败／UNKNOWN／不可达、未完成轮次及缺下游现行配置证据为本版验收例外，继续 1.3.4 发布准备。例外不是测试通过，不调整分类器／覆盖分母／能力表，不把渠道问题自动归因成库外错误，也不免除受影响下游首次新语义读写前的缓存迁移。原设计／计划的“需取证或人类明确豁免”分支由本次授权满足；不勾选完整 T8/T9 或任何尚未执行的发布门。
+
+本轮仅修改 README、CHANGELOG、pyproject、包版本和本 finding。没有新增测试或生产行为变更；原红绿与变异按前述节点复用，不为了版本 bump 人为造红，不启动子代理，不重跑付费模型矩阵。`.env.example` 与 ARCH 的行为同步已在既有提交完成，Wiki 仍下线。
+
+### 已核对并复用的证据
+
+下表路径未写前缀时均相对 `tests/outputs/134/`；这些是已有原件，本轮只核对，不冒称本轮新跑。
+
+| 门／范围 | 原始证据与适用结论 |
+| --- | --- |
+| 生产独立审查 | run `b8552a94-dc93-4834-b9ff-c6b457c315ae` 的 `verify134/production.md`：目标生产 diff 无 Critical／Important／Minor；后续仅测试补漏及本轮文档／版本，不重演同一生产审查 |
+| 四项取证修复复审 | run `3bdee9d3-4678-4ddb-83d9-544156eb00cc` 的 `verify134/executable-retry.md`：HEAD 3eb22d2 四项真实消费者复审无问题，1375 单元／18 定向节点通过，90 仅采集 |
+| 取消计数独立复核 | run `c317eac4-e214-46fc-86a5-08a0d2187d3b` 的 `recovery/cancel-recheck.md`：b7e6943 限定复核无阻塞，139 取证单测与 make check 通过；取消 completed=0、普通终态=1、穿透与资源关闭 |
+| 红绿／变异 | 前文对应的11个契约变异、8个假绿变异、审查四项红绿及 embedding 报告／取消红绿均保留；不外推成新 live 证明 |
+| 日常全量 | `full-gate.log/.exit`：1508 passed、23 skipped、108 deselected、95%覆盖率、exit0；`full-gate-monitor-note.md` 说明外层监控包装失败不等于 pytest 失败。该历史全量早于 embedding 报告补漏；其后测试改动由1385单元及独立复核补证，不声称是新 HEAD 的完整全量 |
+| M2 空 wire AUTO | `recovery-20260909/m2-auto.log/.exit`：2 passed、80 deselected、exit0；M2.5 run `946ac7bf89d742aba8717e722c1e2f60`、M2.7 run `5587e6d9de1e4c7bb6a352afedb7e732` 各5/5轮流式、并发1，最终 wire 无偷带 medium、请求／身份资格及开启命题通过。只消除这两个单元的缺测，不外推其他模式／渠道 |
+| Redis 时间语义 | `recovery-20260909/non-llm-slow.log/.exit`：contracts/integration slow **18 passed、156 deselected、exit0**（1142.05秒），不等同整个 slow 套件通过 |
+
+上述独立报告原件位于 `/home/iomgaa/.pi/agent/sessions/--home-iomgaa-Projects-PolyGateway--/subagent-artifacts/outputs/<run>/`；本轮另原样复制到 `release/reused-reviews/`，不覆盖旧报告、不提交运行产物。
+
+### 最新实测、网络诊断与明确未覆盖
+
+| 项目 | 已取得的事实／本版结论 |
+| --- | --- |
+| 旧完整 slow 中断 | `slow-gate.log` 无对应 `.exit`，保留原 SHA-256 `05967dcf749b13db815dd80449a0db5b3e7ad2144aa2ae216f8c9ab5ecb21bf5`；不把日志中的局部成功当整套通过 |
+| embedding 定向实测 | `recovery-followup-20260909/embedding.log/.exit`：1 failed、exit1。独立三请求诊断 `channel-diagnosis-20260909.jsonl` 同一源 `minimax_1`、请求 `text-embedding-v1` 得503，`error.type=new_api_error`、`error.code=model_not_found`、无可用渠道语义命中；**不是**404且 type 不匹配，仍 FAIL，不改成严格404未覆盖或“所有网关不支持 embeddings” |
+| M3 与 claude 开启档位 | `recovery-followup-20260909/remaining-tiers.log/.exit`：1 passed、1 failed、60 deselected、exit1（首错停止）。M3 run `8c852937e7144fa4b1641744785c9b2b` 六个显式档各5轮、共30/30完成，流式开启命题 PASS；claude-opus-5 run `d0303b5033f4449d82838690f1671470` 五档各5轮、共25/25完成，但至少一个开启命题 FAIL。逐轮请求成功不等于型号能力 PASS，也不能据M3流式覆盖消除非流式 UNKNOWN |
+| claude 独立网络诊断 | `channel-diagnosis-20260909.jsonl` 中 high＋简单题／复杂题均 HTTP200、SSE有DONE、回报身份一致；usage推理token=0，reasoning_content原长1但去空白长0（只有空白）。可证明该次传输完成却缺非空推理信号，不能证明 high 已开启、不能把空白提升 OBSERVED，也不据此断言所有渠道／档位均不能推理。三请求诊断完成不等于三项能力通过 |
+| 剩余矩阵停止 | `remaining-20260909/matrix.log/.exit`：选中40节点，在首个 gemini-3-flash NONE 节点约1080秒后 KeyboardInterrupt，exit1，无测试终态通过汇总。日志不能独立证明停止原因或网络根因；保持未完成，不算40失败或40通过，不继续补跑 |
+| 其余证据缺口 | 历史 UNKNOWN／身份不足、未执行的型号／模式／关闭单元、型号级400机器字段基线、下游现行配置缺证据均按原记录保留。GovDoc／CHS 现行配置未取证，Video-Tree退出迁移后的历史兼容测试也非现行配置验收；不宣称三项目完成本版迁移 |
+
+所有已有逐轮报告仍保留在 `live/<run>/`，汇总文件不能覆盖失败原件。本轮盘点共有453份报告：PASS标签255、FAIL标签108、UNCOVERED标签33、无status的轮数汇总57；**混有逐轮、命题、pytest及历史报告，不能相加成独立模型／测试通过率**。716个历史证据文件的 SHA-256 清单保存在 `release/prior-evidence-sha256.json`，最终复核字节不变。盘点首跑因轮数汇总无status产生 KeyError，保存 `release/evidence-audit.log/.exit`（exit1）；修正盘点脚本区分汇总后 `release/evidence-audit-final.log/.exit` 为exit0，未修改原报告或生产代码。
+
+### 本轮发布准备亲跑结果与交接门
+
+| 检查／命令 | 实际结果／证据 |
+| --- | --- |
+| 先查远端占用 | 改文件前 `git ls-remote --tags origin refs/tags/v1.3.4 refs/tags/v1.3.4^{}`：exit0且空；匿名 GET 包 simple/polygateway 索引HTTP200、不含1.3.4；GET releases/tags/v1.3.4 HTTP404。日志 `release/remote-*`，未读取或输出凭据；未来发布前仍需复查以免竞态 |
+| 版本与 README 数字 | 两处版本均1.3.4；README安装下界改为 `>=1.3.4,<2`，新增醒目迁移警示和例外指针；CHANGELOG按实际日期2026-09-09定版。`inspect.signature` 实测 TelemetryRecorder 不含self为26参，能力表24条／含AUTO10条；`release/evidence-audit-final.log` |
+| `make check` | `release/check.log/.exit`：94文件格式通过、ruff通过、import-linter 1 kept／0 broken、exit0 |
+| `conda run --no-capture-output -n PolyGateway pytest tests/unit/test_package.py -q` | `release/package.log/.exit`：**6 passed，0.08秒，exit0**，两版本一致且导出面可用 |
+| `conda run --no-capture-output -n PolyGateway pytest tests/unit/ -q` | `release/unit.log/.exit`：**1385 passed，4.41秒，exit0**，未新增测试，无新付费调用 |
+
+conda 启动器既有 RequestsDependencyWarning 保留，不宣称零告警。本轮 conda 内实际导入 dotenv／httpx／redis.asyncio 成功；工具的非conda LSP旧诊断不转成代码修改或忽略规则。
+
+**可移交合并与包发布，不等于已发布。** 父会话按本版例外边界完成本次文档／版本差异审查，再执行合并后静态／日常门及未豁免的发布检查；不把本次例外解释为必须补全模型矩阵，也不把豁免项勾成已跑通过。merge／push／tag／构建／twine上传／下载解包独立安装／Release及registry页面检查均尚未执行；只能在实际完成后记录。不得覆盖已有同版本不同字节。
+
+## 1.3.4 发布完成与外部验收（2026-09-09）
+
+父会话已审 `dae12f9` 发布准备 diff，用户授权发布及指定例外；本轮无新生产／测试改动、不派子代理。已有红绿／变异与独立报告按适用范围复用，716份历史证据 SHA-256 复核不变。以下日志均相对 `tests/outputs/134/publish-20260909/`，命令无掩盖退出码管道；长跑由 tmux `pgw134-publish` 串行执行，`PYTHONUNBUFFERED=1`，每门独立 `.exit`。
+
+| 步骤 | 实际结果与证据 |
+| --- | --- |
+| 远端核验／合并 | fetch后 origin/main=`a716f12` 无新变更；精确文件名检查 registry 无1.3.4，tag无占用、Release404。`--no-ff` 合并为 `af57f93adce24b43fd10b6d8e1281ab8ee43c0a8`，与批准 `dae12f9` 树零差异；`merge.log`／`merge-summary.log` |
+| 合并后 `make lint` | exit0，ruff／import-linter 1 kept、0 broken，无自动修改；`lint.log/.exit` |
+| 合并后 `make test` | **1518 passed、23 skipped、108 deselected，95%覆盖率，276.42秒，exit0**；`daily.log/.exit`。skip与deselected不计通过 |
+| M2 AUTO定向 slow | **2 passed、80 deselected，46.85秒，exit0**；各5轮、并发1，空wire流式开启命题通过；`m2-auto.log/.exit`。M2.5 run `d4b158162ad543e5a4745d21b29ab03e`，M2.7 run `07a388cafa9f4fcf95dc0c6876fd0751`，均 planned=completed=5、无缺轮；实际逐轮／命题报告已读取 |
+| Redis时间语义 slow | contracts/integration选择 **18 passed、156 deselected，1109.45秒，exit0**；`redis-time.log/.exit`。`gates.exit=0`，未重启全型号矩阵 |
+| push与tag | main推送成功；注释tag对象 `0bdb0f70e4667a2fe50a567f0809a5a421c5442a`，解引用同上述main；`push-main.log`／`push-tag.log`／`remote-refs-after.log` |
+| 构建／上传 | 核实项目绝对dist路径且不是链接后清旧1.3.3产物；conda `python -m build`、`twine check dist/*`、twine上传均exit0，wheel/sdist各一份。凭据只从tea内存读取进入TWINE_PASSWORD，无token argv／日志；`build`／`twine-check`／`upload` 的 `.log/.exit` |
+| 独立下载／解包 | registry下载wheel与sdist，与本地构建SHA-256逐字匹配；包内五个关键生产文件与发布提交相同，wheel METADATA版本／Markdown正文、sdist README均与已发布README相符；`download-final.log/.exit`、`download-verification.json` |
+| 独立安装与行为 | `/tmp/pgw134-registry-eyges3d7/installed/polygateway/__init__.py`，仓库外 `python -I` 并显式target来源验证；M2空AUTO、M3 AUTO在error/nearest均拒绝、M3 medium、同值／新增raw冲突与raw-only保留全部通过 |
+| Release／包页面 | Release POST201，正文逐字来自CHANGELOG本节。匿名实际读取包页面、单版Release及Releases列表，均HTTP200、正文含迁移／例外；包页面有目标仓库链接，认证包API的 repository.full_name=`iomgaa/PolyGateway`；`pages-final.log/.exit`、`external-verification.json`及HTML／可见文本原件 |
+| issue收尾 | 仅#21/#25/#26评论后关闭，GET各自核实closed；评论明确验证范围、失败例外、缓存迁移及“不识别所有渠道故障”；`issues.log/.exit`和`issue*-after.json`。未改#19/#22/#23/#24 |
+
+产物 SHA-256：wheel `86ad5cc025bfda127c4f0e4bbe1252d1bb8943b7678f9ff5561200bac71fe2a2`；sdist `85620f993ff9d19845088a071d251049e3dfae8d035c05652bdb62b4340a1a66`。
+
+外部亲查地址：[包页面](https://gitea.iomgaa.online/iomgaa/-/packages/pypi/polygateway/1.3.4)、[v1.3.4 Release](https://gitea.iomgaa.online/iomgaa/PolyGateway/releases/tag/v1.3.4)、[Releases列表](https://gitea.iomgaa.online/iomgaa/PolyGateway/releases)。结果补记在独立 `docs/1.3.4-release-evidence` 分支，不改变已发布main/tag或覆盖同版本产物。
+
+### 真实失败与恢复（原件保留，不改写成功）
+
+| 检查失败 | 根因／处置与边界 |
+| --- | --- |
+| 最初索引grep误报占用 | `1.3.4` 被当正则匹配历史sha片段；改用完整字面 `polygateway-1.3.4`，并核对tag／Release均不存在。没有实际同版占用，没有覆盖 |
+| 首次sdist下载exit1 | 私有索引无setuptools，pip即使 `--no-deps` 仍启构建隔离；`download.log/.exit`保留。复用已下载wheel，sdist加 `--no-build-isolation` 使用现有conda构建工具后exit0；不新增依赖、不重传包 |
+| 包link POST400 | 返回 `invalid argument`，`release-create.log/.exit`保留exit1；不把400当成功／不猜根因。匿名页面已有仓库链接，认证GET包API证实本版正确关联，故无需解绑重挂；Release创建201不重复执行 |
+| 首次页面验证exit1 | 三个匿名页面及Release正文均通过，但额外包API匿名GET401；`pages.log/.exit`保留。仅该API沿现有tea认证GET后200，最终所有页面／API核对exit0；不扩大为发布包匿名不可下载 |
+
+上述操作差异已补入CLAUDE发布清单。conda启动器既有RequestsDependencyWarning仍保留。用户验收例外完全沿前节：embedding503与claude命题仍FAIL、M3非流UNKNOWN及其余未覆盖／缺下游资料未变；本轮成功不外推全矩阵或所有渠道。1.3.4发布任务到此停止，1.3.5由父会话继续。

research-wiki/findings/2026-09-09-135-call-observability-validation.md

@@ -0,0 +1,290 @@
+---
+type: finding
+node_id: finding:2026-09-09-135-call-observability-validation
+title: "1.3.5 T2/T3/T4 验收证据：36 列遥测、失败终态、PG 存储兼容与变异矩阵"
+date: 2026-09-09
+---
+
+# 1.3.5 T2/T3 验收证据
+
+> 范围：**仅 T2（遥测 10 列 / 诊断保真 / scope+operation / 装配闸）与 T3（终态行 / 取消 / 统一出口）**，
+> 外加计划 T4 中"签名与列数机械迁移"那一片（与 schema 同批完成，避免先提交 schema 却留写入缺键）。
+> **不含** T4 的 PG 集成、变异矩阵与文档同步——另任务承接，缺口见 §5。
+> 设计：`designs/2026-09-09-135-call-observability-design.md`；计划：`plans/2026-09-09-135-call-observability.md`。
+> 基线 HEAD `87c261b`（T1 已提交，1419 unit 全绿）。全部命令在 `PolyGateway` conda 环境执行。
+
+## 1. 红绿证据链
+
+TDD 纪律要求"先失败后通过"，且红必须是**行为红**而非 import 红。下表每行都对应本会话的真实工具输出。
+
+| # | 阶段 | 命令 | 结果 |
+| --- | --- | --- | --- |
+| 0 | 基线 | `pytest tests/unit -q` | **1419 passed**（对照底） |
+| 1 | 红（T2/T3 目标行为） | `pytest tests/unit/test_telemetry.py -k "RowLevelObservability or RecorderShapeGate"` | **26 failed**，证据 `tests/outputs/135/red-01-emitter-rows.txt` |
+| 2 | 实现后全量红面 | `pytest tests/unit -q` | **137 failed / 1308 passed**（机械迁移面暴露），`red-02-after-impl.txt` |
+| 3 | 迁移中 | 同上 | 60 → 25 → 8 → 4 failed（`red-03`/`red-04`/`red-05`） |
+| 4 | 绿 | `pytest tests/unit -q` | **1467 passed, 0 failed** |
+| 5 | 静态门 | `make check`（ruff lint+format + import-linter） | **Contracts: 1 kept, 0 broken** |
+
+第 1 步的红是行为红而非 import 红：新用例调用的是**已存在**的 `TelemetryEmitter`，
+失败形态是"缺 `scope=`/`operation=`/`stats=` 关键字"与"断言的列不存在"，不是模块导不进来。
+
+补测阶段另有两次真实红（均由 conda 实跑暴露、当场修正，非噪音）：
+`test_client.py` 的 `NameError: ResultInvalidError / ChatRequest`（漏 import）、
+`TestTerminalRowSqlSemantics` 的 `'coroutine' object has no attribute 'execute'`（async helper 漏 await）。
+
+## 2. 核心要求逐条对应
+
+### 2.1 36 列与 Emitter 完整一致（不留"schema 有列、写入缺键"）
+
+一次性同批改完五处列定义 + 端口签名 + Emitter 写入，故不存在中间态。
+
+| 判据 | 证据 |
+| --- | --- |
+| `len(COLUMNS) == 36`、物理列 37 | `test_telemetry.py::TestSchemaModule::test_columns_and_ddl_are_frozen`；`TestSQLiteSchemaMode` 断言 23 → 37 |
+| 五处列序一致（DDL/BACKFILL×2/COLUMNS） | 新建库与 ALTER 追加列序同为 `_EXPECTED_COLUMNS` |
+| 端口实测 36 字段、10 新参 keyword-only 且无默认值 | `test_ports.py::TestTelemetryRecorderSignature`（`inspect.signature` 实测，不凭记忆） |
+| **Emitter 实参键集合 == `schema.COLUMNS`** | `TestEmitterRecorderContract` 三入口逐个断言 `set(rows[0]) == set(COLUMNS)` |
+| 1.2.1 冻结 INSERT 未被改写 | 按 `_PRE_135_COLUMNS`（26 列）重现原文；全量 36 列另按占位符个数断言 |
+
+装配闸（C3）：`_assert_recorder_shape` 在 `TelemetryEmitter.__init__` 做一次 `signature.bind`，
+参数名**从协议签名派生**而非手抄第四份清单——`test_gate_derives_parameter_names_from_the_protocol`
+用 monkeypatch 换掉协议后闸自动跟随，证明没有硬编码。旧签名 recorder / 无该方法 / 不可 inspect
+一律装配期 `ValueError`（不是 warning：降级铁律管的是运行期写失败，不是配置错误）。
+
+### 2.2 三个 client 的**真实链路**失败终态
+
+不是只测 Emitter，而是驱动真实 client + MockTransport 到落库。
+
+| 链路 | 用例 | 断言 |
+| --- | --- | --- |
+| chat 重试耗尽 | `TestChatTerminalFailureRows::test_retry_exhaustion_writes_exactly_one_terminal_row` | 3 条 attempt + **恰 1 条**终态；终态 `attempts == 3` |
+| chat 结构化耗尽 | `test_structured_exhaustion_writes_the_only_failure_row` | attempt 行**全是成功行**，终态是唯一失败记录；error 含有界 `validation=`/`repair=` 且 < 1200 字符、不含 raw_text |
+| chat 400 直拒 | `test_request_rejected_now_has_both_an_attempt_and_a_terminal_row` | 尝试行 + 终态行**各 1**（已批准的行数翻倍）；两行共享同一 `logical_call_id` |
+| embedding | `test_embedding.py::TestReasonlessTelemetryContract::test_failed_attempts_still_have_null_effort` | attempt 数 == 脚本长度，终态恰 1 |
+| OCR 两方法 | `test_ocr_client.py` 同名用例（参数化 `recognize_text`/`parse_layout`） | 终态恰 1，且 `operation` 为**公开方法名** |
+
+去重：`test_terminal_row_is_written_once_per_logical_call` 连调出口 3 次，SQL 可见仍 1 条（`claim_terminal`）。
+非领域异常：`test_non_domain_exception_writes_no_terminal_row` —— `KeyError` 原样传播、**0 条**终态、分类不被改写。
+
+**双写已消除**：`TelemetryMW` 的两个终态分支删除，改由三个 client 的公开边界经
+`emit_terminal_once` 统一写出；`TestTelemetryMW::test_scope_level_failure_is_not_written_here_anymore`
+与 `test_cancellation_is_not_written_here_anymore` 锁死"本层不再写终态"，防回归双计。
+
+### 2.3 取消口径
+
+- chat 取消：`test_cancellation_writes_at_most_one_terminal_row` —— 恰 1 条，`error == "cancelled"`，
+  且 `error_type` 为 NULL（**字符串不解析猜诊断**）。
+- 三链路同策略"尽力写一条、允许 0"；`emit_terminal_once` **不 shield、不开后台任务**，
+  快照冻结是同步动作；写入 await 上再被取消则 `CancelledError` 原样传播（与 TelemetryMW 历史行为同款）。
+
+### 2.4 SQL 不双计（按真实 SQLite 落库断言）
+
+`TestTerminalRowSqlSemantics` 用真实 `SQLiteRecorder` 驱动一次失败 chat 后直接查表：
+
+| 迁移影响 | 断言 |
+| --- | --- |
+| 失败计数判据 | `error IS NOT NULL` 得 **3**（2 尝试 + 1 终态），`event_kind='terminal_failure'` 得 **1** |
+| 费用不双计 | 终态行 `cost IS NOT NULL` 计数为 **0**；且 `usage_source='unavailable'`、token 全 0 |
+| 时延分组 | 终态 `latency_ms` ≥ 任何单次尝试（含退避），故看板必须按 `event_kind` 分组 |
+| 双时钟微差 | 终态 `latency_ms == total_latency_ms`（同一份冻结快照） |
+| 逻辑两列归属 | 尝试行 `attempts`/`total_latency_ms` 恒 NULL |
+| §5 归因查询 | 同一 `logical_call_id` 同时给出整池 reason 文案与逐源 503 现场；终态 `http_status_code` 为 NULL（C1 不冒充） |
+
+### 2.5 诊断保真与 operation 修正
+
+- 中转把 529 改写成 503 → **记 503 不猜回 529**；直接 529 记 529。
+- 空 `str()` 的 Connect/Read/Write/PoolTimeout → `cause_type` 落对应 httpx 类名，`error` 退回类名。
+- 成功行五列全 NULL（**不统一填 200**）。
+- `_status_to_error` 增 keyword `operation`：`embed()` 非 200 改传 `"embedding"`（修正历史误标），
+  流式与非流式 chat 两处仍 `"chat"`（按实施计划 §2 归属表，未按设计行号误标）。
+- 新列 `operation` 恒为公开方法四值，**绝不读 `exc.operation`**：
+  `test_operation_is_given_by_the_call_site_not_the_exception` 用 `exc.operation="download_result"` 反证。
+- OCR `"类名: msg"` 前缀由出口的显式策略参数 `class_prefixed_error` 承载，不再三处各拼一遍。
+
+## 3. 有界 validation 说明的单一所有者
+
+`structured.py` 的 `_MAX_FEEDBACK_ERRORS`/`_MAX_ERROR_CHARS`/`_format_errors` 改名为
+公开的 `MAX_FEEDBACK_ERRORS`/`MAX_ERROR_CHARS`/`format_bounded_errors`，
+由"重问反馈"与"终态结构化说明"两个消费者共同引用，**数值只有一份**。
+行为逐字不变（`test_structured.py` 22 项全绿，含反馈文案用例）。
+
+## 4. 未改动确认（防越界）
+
+`errors.py`、`admission.py`、`ratelimit.py`、`breaker.py`、`sources.py`、`thinking.py`、
+`providers.py`、`telemetry/sqlite.py`、`telemetry/postgres.py`、`transports/monkey_ocr.py`
+一字未动——两个 recorder 靠 `**fields` + `schema.COLUMNS` 自动吃到新列。
+缓存 key 公式、重试预算与退避、429 免预算、stall 算法、取消结算、推理能力表均未触碰。
+唯一顺带修正：`RetryMW.__init__` 的 `emitter` 注解由 `object | None` 收紧为
+`TelemetryEmitter | None`（TYPE_CHECKING 导入，同层不破分层契约），因本轮改了它的 `_emit`。
+
+## 5. T4 验收（PG 存储兼容、变异矩阵、文档同步）
+
+基线 HEAD `393f2bf`（1467 unit 全绿），全部命令在 `PolyGateway` conda 环境执行。
+
+### 5.1 PG 存储兼容（真实实验室 Postgres，复用 `pg_sandbox`）
+
+机械迁移：`_EXPECTED_COLUMNS` 27 → 37 列、`_record_minimal` 字段字典补 10 键（与单测同款）、
+`_PRE_TENANT_COLUMNS` 的缺列集由4 列扩到 14 列。新十列一律由 `_CALL_OBSERVABILITY_COLUMNS` 派生，
+两处 manual 档告警的逐字断言改成按 `COLUMNS` 序派生的 `_PRE_TENANT_MISSING_NOTICE`——
+另抄一份列名必然漂移，而漂移的表现是“manual 档没补列”这条断言假绿。
+
+| 阶段 | 命令 | 结果 |
+| --- | --- | --- |
+| 机械迁移前（已知必红） | `pytest tests/integration/test_postgres_telemetry.py -q -x` | **1 failed / 18 passed**：manual 档列序断言 `Right contains 10 more items, first extra item: 'scope'` |
+| 机械迁移后 | 同上（无 `-x`） | **27 passed**，EXIT=0，`tests/outputs/135/pg-telemetry-after-mechanical.log` |
+| 新增四项验收后 | 同上 | **30 passed**，EXIT=0，`tests/outputs/135/pg-telemetry-new-cases.log` |
+
+新增 `TestCallObservabilityColumnsAcceptance`（对应计划 T4 的 PG 四项），共用一张 27 列的 1.3.4 形态旧表（`pre_135_schema`）：
+
+| 验收项 | 用例与关键断言 |
+| --- | --- |
+| auto 追加 10 列 + 旧行 NULL | `test_pre_135_table_gains_the_ten_columns_and_old_rows_stay_null`：物理列 27 → 37 且列序 == `_EXPECTED_COLUMNS`；attempt 行与 terminal 行十列取值**整体比对**（不是逐条 in）；历史行 `dict.fromkeys(...)` 十列全 NULL |
+| manual 缺列裁剪 | `test_manual_trims_the_insert_on_a_pre_135_table`：表结构逐字不动（== `_PRE_135_COLUMNS`）；裁剪后 26 列逐列等于提交值（防整体错位）；恰 1 条告警且含可直接粘贴的首/末列 ALTER；无“写入失败”/“补列失败”，`degraded is False` |
+| 新旧进程混写 | `test_old_and_new_writers_share_one_table`：新版建表写 36 列 → 旧版进程用 `insert_sql("postgres", 26 列集)` 写入 → 新版再写；三行共存、表结构不变、旧行新列全 NULL、无写入失败 warning |
+| 下游口径验收 | 同上用例尾部：`WHERE event_kind = 'terminal_failure'` 计得 1；`event_kind IS NULL` 计得 1（混写期旧行既不误计成失败也不误计成成功） |
+
+纪律：未引用 `assert_no_leftovers`（它是 `test_pg_sandbox.py` 的模块级 fixture，对本文件不可见，上提它要改 `conftest.py`）；
+未新建沙箱设施、未碰共享表 `llm_calls`、未读或打印 DSN。新增的只有一个 `_execute_args`（带参数单语句）与
+`_minimal_fields`（从 `_record_minimal` 拆出的字段字典，供“旧进程”复用同一份取值）。
+
+### 5.2 变异矩阵（仓库外副本，主工作区生产代码零改动）
+
+驱动脚本 `/tmp/pgw-135-mut/run_mutations.py`；每项“还原副本 → 施加单点变异（断言替换命中）→ 跑指定节点 → 还原”。
+完整日志 `tests/outputs/135/mutations.log`，脚本总退出码 **EXIT=0**。
+
+| # | 变异 | exit | 被杀断言（节选） |
+| --- | --- | --- | --- |
+| M1 | `register_attempt()` 挪到 transport 成功之后 | 1 | `test_failed_retries_are_counted`、`test_budget_free_429_still_counts_as_an_attempt`、`test_retry_exhausted_counts_every_attempt` |
+| M2 | `ChatRequest` 每次 `replace` 复制出新上下文 | 1 | `TestLogicalCallStats` 4 项 + `test_retry_exhaustion_writes_exactly_one_terminal_row` |
+| M3 | `_rehydrate` 去掉 `call_stats=None` 覆盖 | 1 | `test_historic_dict_never_impersonates_call_stats` |
+| M4 | Emitter 入口提前 `str(exc)` 压平 | 1 | 529/503 保真、4 个空超时文案 `cause_type`、类名前缀策略、结构化有界说明等 9 项 |
+| M5 | 终态行复制最后一次 attempt 的 token/cost | 1 | `test_terminal_rows_never_contribute_to_cost`、`test_terminal_row_costs_nothing` |
+| M6 | 去掉 `claim_terminal` 去重 | 1 | `test_terminal_row_is_written_once_per_logical_call`、`test_claim_terminal_is_true_once` |
+| M7 | 装配闸改为捕获 `TypeError` 后 warning | 1 | `test_old_signature_recorder_is_refused_at_assembly`、`test_uninspectable_recorder_is_a_configuration_error` |
+
+还原校验：副本 `.py` 文件集合散列与纯净态**逐字一致**（`66b58b9a…`），还原后同一批节点 **172 passed**。
+
+> **方法论陷阱（影响本仓所有变异证据的有效性）**：只设 `PYTHONPATH=<副本>/src` 是**无效的**——
+> `pyproject.toml` 的 `[tool.pytest.ini_options] pythonpath = ["src"]` 会把**仓库内**的 `src` 抢先塞进 `sys.path[0]`，
+> 于是测的仍是原代码。首轮实跑七项变异**全部“存活”（exit=0）**就是这个坑；
+> 改用 `-o pythonpath=<副本>` 覆盖后七项全部被杀。今后做变异必须先证“副本真的被导入”，
+> 否则“变异存活”会被误读成“测试不够强”，而真相是变异根本没生效。
+
+### 5.3 文档同步（字段数一律 `inspect` 实测，不凭记忆）
+
+实测值：`len(inspect.signature(TelemetryRecorder.record_llm_call).parameters) - 1 == 36`，`len(COLUMNS) == 36`，物理列 37。
+
+| 位置 | 改了什么 |
+| --- | --- |
+| `README.md` 能力表 | “必录 26 字段” → 36 字段 + 三类行与诊断列；新增“逻辑调用统计”一行 |
+| `README.md` 新小节 | 《1.3.5 逻辑调用统计与失败诊断》：`call_stats` 读法、**SQL 迁移五项**、归因查询、存储侧升级 |
+| `README.md` cap 覆盖面 | 补“`error_body` 沿用 `summarize_body` 上限、结构化说明自带限长，**两者都不在 cap 覆盖内**” |
+| `ARCHITECTURE.md` §7.8 | 必录字段 26 → 36（十列逐个列出）；新增“逻辑调用十列”段（列语义表 + 不变量 I3/I4 + `operation` vs `exc.operation` 两个语义 + 装配闸）；cap 段补两处诊断文本不在覆盖面 |
+| `CHANGELOG.md` | 新建《未发布》：公共面四项变更表 + 下游必须做的事（点名 `WHERE event_kind` 与装配期报错） |
+| `.env.example` | `PGW_TELEMETRY_TEXT_CAP` 块补 1.3.5 覆盖面例外 |
+| `schemas/llm-calls.md` | 标题 26 → 36 字段；十列逐行登记；新增《三类行与失败归因口径》（含归因 SQL 与迁移四条） |
+| `metrics/call-telemetry-coverage.md` | 新增《1.3.5 三类行与逻辑调用覆盖》；live 基线列**不写伪百分比** |
+
+版本号与发布步骤**未动**（任务边界）；`pyproject.toml` / `__init__.py` 仍为 1.3.4。
+
+### 5.4 本轮收口验证
+
+| 检查 | 命令 | 结果 |
+| --- | --- | --- |
+| 静态 | `make check`（ruff format+lint + import-linter） | 见 §7 实跑记录 |
+| 全量单测 | `pytest tests/unit -q` | 见 §7 |
+| 目标集成 | `pytest tests/integration/test_postgres_telemetry.py -q` | **30 passed** |
+
+## 6. 剩余缺口（不归本任务，不自称已关）
+
+| 缺口 | 说明 |
+| --- | --- |
+| 独立验证 | 未派全新上下文 verifier（合并前硬门，由父会话前台派） |
+| slow / e2e | 未跑，属发布清单第 4 步（CLAUDE §4.4.1） |
+| live 覆盖基线 | `metrics/call-telemetry-coverage.md` 的实际基线列仍待首次生产运行填入 |
+| 下游自建 recorder | 装配闸只能证明形状可被接受，证不了函数体真的落这些列（已写进 README/CHANGELOG） |
+
+## 7. 环境噪音记录（不是缺陷）
+
+自动检查器用**系统解释器 Python 3.13.9**（无 `redis`/`pydantic`/`httpx`/`loguru`/`asyncpg` 等依赖），
+持续报 `test_client.py` 2 项失败与大量 "Import could not be resolved"、`StrEnum is unknown import symbol`。
+已核实为环境问题、非本轮引入：
+
+- 失败根因是 `ModuleNotFoundError: No module named 'redis'`（optional extra），本轮 diff 对 redis 零改动；
+- 在**未改动的 HEAD** 上用同一系统解释器复跑，同样 2 failed / 90 passed；
+- 项目强制环境 `conda run -n PolyGateway`（Python 3.12.13）下：`test_client.py` 98 passed、全量 1467 passed。
+
+判据以 CLAUDE.md §2 规定的 conda 环境与 `make check` 为准。
+
+**T4 轮次同样现象（已逐项复现并关闭）**：检查器报 `tests/integration/test_postgres_telemetry.py` “2/3 failed”
+与 6 处 `Import "asyncpg" could not be resolved`。根因与上同：`asyncpg>=0.29` 是 optional extra
+（`pyproject.toml:25` 的 `postgres`），检查器解释器里没装。已做确定性复现：
+
+- 那 3 条恰是本文件**仅有的不依赖真实 PG 的用例**，其中 2 条要造 `PostgresRecorder`；
+- 用 `/home/iomgaa/miniconda3/bin/python`（无 asyncpg）跑这 3 条：**2 failed / 1 passed / 0.09s**，与检查器报告逐字吹合；
+- 同 3 条在 `conda run -n PolyGateway` 下：**3 passed**；整文件 **30 passed**（真实 PG）；
+- 被标记的 6 行均为**本轮未触及的旧行**，本轮只新增 1 处同款函数内 `import asyncpg`。
+
+未为此修改代码：给旧行加 type-ignore 属任务外改动（反 gold-plating），且并非真修复。
+
+## 8. 1.3.5 发布准备（2026-09-09，唯一 writer 会话）
+
+范围仅**发布准备文档与版本号**：README 安装下界、CHANGELOG 定版、两处版本、本节记录。生产代码与测试**零改动**（`git diff` 只有 `CHANGELOG.md` / `README.md` / `pyproject.toml` / `__init__.py` 各 1 行，外加本文件追加的这一节）。未 merge／push／tag／构建／上传。
+
+### 8.1 先查远端占用（改文件之前）
+
+| 检查 | 结果 |
+| --- | --- |
+| `git ls-remote --tags origin` | 最高 `refs/tags/v1.3.4`，**无 v1.3.5**；远端分支只有 `main`（`af57f93`）与 `docs/1.3.4-release-evidence` |
+| 本地 tag | 同样止于 `v1.3.4` |
+
+远端未被占用是**本次时点**的事实，父会话真正 push／tag 前仍须复查以防竞态。
+
+### 8.2 版本与文档数字（数字一律实测）
+
+| 项 | 结果 |
+| --- | --- |
+| 两处版本 | `pyproject.toml` 与 `src/polygateway/__init__.py` 同为 `1.3.5`；由 `tests/unit/test_package.py` 机械断言一致（**6 passed**） |
+| README 安装下界 | `>=1.3.4,<2` → `>=1.3.5,<2`（本版含装配期形状闸与 SQL 口径迁移，旧下界会让下游装到不含新列的包） |
+| README 迁移醒目度 | 《1.3.5 逻辑调用统计与失败诊断》为顶层小节且带 `[!WARNING]`（点名"失败行变多、旧失败 SQL 会多数、自建 recorder 装配期报错"），能力表"逻辑调用统计"一行直链该锚点；沿用 1.3.4 的同款版式，未重排既有 1.3.4 迁移节 |
+| CHANGELOG 定版 | `## 未发布` → `## 1.3.5(2026-09-09)`，日期取自本机 `date +%F` 实际值，正文未改 |
+| 字段数复核 | `inspect.signature(TelemetryRecorder.record_llm_call)` 去 self **36 参**、`len(schema.COLUMNS) == 36`、探针实测物理列 **37**——README／CHANGELOG 的 36／37 与实测吻合，非凭记忆 |
+
+README 静态数字未发现错误，故未做任何顺带修改。
+
+### 8.3 复用既有证据的适用边界（不拿旧证据顶替本版统计）
+
+| 证据 | 是否复用 | 边界 |
+| --- | --- | --- |
+| 独立验证（全新上下文 verifier，父会话前台派） | 复用结论：**0 阻塞** | 审的是本分支 `b4812e1` 的 1.3.5 变更面；本会话未重复派子代理，也未把它当作 live 覆盖或发布后检查的替代 |
+| 本版最终全套件 `make test` | **本版实跑，不复用** | `final-gates/make-test.log/.exit`：**1605 passed / 23 skipped / 108 deselected / 95%，exit 0** |
+| 本版真实 PG 集成 | **本版实跑，不复用** | `final-gates/pg-telemetry-verbose.log/.exit`：**30 passed，exit 0**（含新增四项列兼容验收） |
+| 本版 unit | **本版实跑** | 本轮版本号改动后复跑 `pytest tests/unit -q`：**1469 passed，exit 0**（`release/unit.log/.exit`） |
+| 1.3.4 模型矩阵／逐型号推理证据 | **按适用条件复用** | 1.3.5 对 `thinking.py`、能力表、wire 片段、缓存 key 公式、重试／限流／熔断语义**一字未改**（§4 已逐文件确认），故 1.3.4 的型号级结论在其原有边界内继续成立——连同它的 FAIL／UNKNOWN／不可达／缺轮**一并继承**，不因本版而升格。它**不能**充当 1.3.5 新增 API／schema 的证据，也不提供本版的测试统计数字 |
+| 1.3.4 的全模型矩阵重跑 | **不跑** | 本版未改推理路径；用户已批准不再补全模型矩阵。本会话不发全型号请求 |
+
+本版**改变的公共面**（`CallStats` 与四类响应新字段、端口 10 新参、遥测 10 列与 `terminal_failure` 行）全部由新写的离线真链路用例（三个 client + MockTransport 直到落库）、真实 SQLite 断言、真实 PG 30 项承担，见 §2、§2.4、§5.1。
+
+### 8.4 本轮受影响路径的真实现场（并发 1、超时不压、无全模型请求）
+
+| 亲跑 | 命令与证据 | 结果 |
+| --- | --- | --- |
+| 真实网关冒烟（复用既有 e2e，不另造工具） | `pytest tests/e2e/test_smoke_gateway.py -m slow -v`，tmux `pgw135-smoke`，`release/smoke-gateway.log/.exit` | **4 passed，exit 0**（流式／非流式／结构化 json／结构化模型四节点，9.55s） |
+| 有界现场探针（**恰 1 次**真实调用，全程走库） | `release/probe_call_stats.py` → `release/probe-call-stats.log/.exit`，tmux `pgw135-probe` | **exit 0**：`MiniMax-M3`／源 `minimax_1`，`call_stats.attempts=1`、`total_latency_ms=2581` ≥ 单次尝试 `2562`、`logical_call_id` 与落库行逐字一致；临时 SQLite 物理列 **37**、写入面 **36**、恰 1 条 `event_kind='attempt'` 行、`operation='chat'`、`scope='LLM'`、逻辑两列与四个诊断列全 NULL |
+
+探针脚本只落在 `tests/outputs/135/release/`（该目录 gitignore，不入库），不新增生产代码、测试或平台设施，未发裸 HTTP，沿用 `.env` 现有超时与单源配置。
+
+### 8.5 提交前收口门
+
+| 门 | 证据 | 结果 |
+| --- | --- | --- |
+| `make check` | `release/check.log/.exit` | **exit 0**：94 文件格式通过、ruff 通过、import-linter **1 kept / 0 broken** |
+| 包单测（两处版本一致） | `release/package.log/.exit` | **6 passed，exit 0** |
+| 全量 unit | `release/unit.log/.exit` | **1469 passed，exit 0** |
+
+23 项 skip 的理由已逐条留档（`final-gates/skip-reasons.log`）：17 项 redis 时间语义由 integration 变体覆盖、6 项需实验室语料 `data/soak/chs_images`；**skip 不计通过**。conda 启动器既有 `RequestsDependencyWarning` 保留，不宣称零告警。
+
+### 8.6 尚未执行（不得当成已完成）
+
+merge、push、`git tag -a v1.3.5`、`python -m build`、`twine check`／`upload`、`pip download` 解包验证、Gitea Release 与包页面／仓库关联检查**全部未执行**；`pytest -m slow` 的其余 e2e（本轮只跑了 `test_smoke_gateway.py` 四节点）与 live 覆盖基线同样未跑。§6 的四项缺口除"独立验证"已由父会话关闭外，其余保持开启。

research-wiki/graph/edges.json

@@ -200,6 +200,31 @@
       "id": "plan:plan-issue15-telemetry-pool-lifecycle",
       "label": "实现计划: 遥测连接池的资源语义与生命周期(issue #15)",
       "type": "plan"
+    },
+    {
+      "id": "design:reasoning-effort",
+      "label": "推理档位一等化设计(issue #20 及其一般形式)",
+      "type": "design"
+    },
+    {
+      "id": "plan:reasoning-effort",
+      "label": "实现计划: 推理档位一等化",
+      "type": "plan"
+    },
+    {
+      "id": "design:2026-09-09-134-thinking-contracts-design",
+      "label": "1.3.4 推理意图与测试证据设计",
+      "type": "design"
+    },
+    {
+      "id": "plan:2026-09-09-134-thinking-contracts",
+      "label": "1.3.4 推理契约实施计划",
+      "type": "plan"
+    },
+    {
+      "id": "finding:2026-09-09-134-thinking-contracts-validation",
+      "label": "1.3.4 T0–T4 与 T7 确定性验证",
+      "type": "finding"
     }
   ],
   "links": [
@@ -405,6 +430,48 @@
       "relation": "refines",
       "evidence": "复测确认 M3 can_disable 仍成立,并补记非流式不可观测、仅 reasoning_effort 有效两条限制",
       "added": "2026-08-26T04:49:18.648857+00:00"
+    },
+    {
+      "source": "plan:2026-08-26-issue18-pg-test-isolation",
+      "target": "design:2026-08-26-issue18-pg-test-isolation",
+      "relation": "implements",
+      "evidence": "9 个任务逐条实现设计 §4-§11",
+      "added": "2026-08-26T11:28:33.469681+00:00"
+    },
+    {
+      "source": "plan:reasoning-effort",
+      "target": "design:reasoning-effort",
+      "relation": "implements",
+      "evidence": "10 个任务逐条覆盖设计 §3-§8;T10 兑现人类「能力表统一经 new-api 实测」的决定",
+      "added": "2026-09-05T04:07:17.723586+00:00"
+    },
+    {
+      "source": "plan:2026-09-09-134-thinking-contracts",
+      "target": "design:2026-09-09-134-thinking-contracts-design",
+      "relation": "implements",
+      "evidence": "已批准设计；T0基线660 passed、make check通过",
+      "added": "2026-09-09T04:48:57.560089+00:00"
+    },
+    {
+      "source": "plan:2026-09-09-134-thinking-contracts",
+      "target": "finding:2026-09-09-134-thinking-contracts-validation",
+      "relation": "tested_by",
+      "evidence": "T0–T4/T7：1241单测与11隔离变异；未覆盖live/集成/发布",
+      "added": "2026-09-09T05:39:12.170598+00:00"
+    },
+    {
+      "source": "schema:llm-calls",
+      "target": "design:2026-09-09-134-thinking-contracts-design",
+      "relation": "implements",
+      "evidence": "复用既有26字段，四种行来源与无推理成败NULL；不增加生产数据面",
+      "added": "2026-09-09T06:32:06.527808+00:00"
+    },
+    {
+      "source": "plan:2026-09-09-135-call-observability",
+      "target": "design:2026-09-09-135-call-observability-design",
+      "relation": "implements",
+      "evidence": "1.3.5 逻辑调用统计与结构化失败诊断实施计划落地已批准设计",
+      "added": "2026-09-09T13:42:00.298915+00:00"
     }
   ]
 }

research-wiki/index.md

@@ -1,8 +1,10 @@
 # Research Wiki 索引
 
-> 自动生成，更新时间：2026-08-26 04:49 UTC
+> 自动生成，更新时间：2026-09-09 16:49 UTC
 
-## design (38)
+## design (43)
+
+- [1.3.4 推理意图与测试证据设计](designs/2026-09-09-134-thinking-contracts-design.md) `design:2026-09-09-134-thinking-contracts-design`
 - [2026-07-20-m1-core-design](designs/2026-07-20-m1-core-design.md) `design:2026-07-20-m1-core-design`
 - [2026-07-20-m2-distributed-design](designs/2026-07-20-m2-distributed-design.md) `design:2026-07-20-m2-distributed-design`
 - [2026-07-21-m25-resilience-design](designs/2026-07-21-m25-resilience-design.md) `design:2026-07-21-m25-resilience-design`
@@ -21,6 +23,8 @@
 - [2026-08-19-issue13-schema-mode-design](designs/2026-08-19-issue13-schema-mode-design.md) `design:2026-08-19-issue13-schema-mode-design`
 - [2026-08-19-issue14-admission-wait-policy-design](designs/2026-08-19-issue14-admission-wait-policy-design.md) `design:2026-08-19-issue14-admission-wait-policy-design`
 - [2026-08-24-issue15-telemetry-pool-lifecycle-design](designs/2026-08-24-issue15-telemetry-pool-lifecycle-design.md) `design:2026-08-24-issue15-telemetry-pool-lifecycle-design`
+- [2026-09-04-reasoning-effort-design](designs/2026-09-04-reasoning-effort-design.md) `design:2026-09-04-reasoning-effort-design`
+- [2026-09-09-135-call-observability-design](designs/2026-09-09-135-call-observability-design.md) `design:2026-09-09-135-call-observability-design`
 - [est_tokens 解耦: 拆分限流预扣与遥测用量兜底(issue #2)](designs/est-tokens-decoupling.md) `design:est-tokens-decoupling`
 - [GatewaySettings 装配校验补齐(第二轮)](designs/settings-invariants-round-2.md) `design:settings-invariants-round-2`
 - [GatewaySettings 跨字段不变量守卫的生效范围](designs/settings-invariant-guards.md) `design:settings-invariant-guards`
@@ -28,6 +32,7 @@
 - [issue #12: 遥测表的正文体量、保留期与访问控制](designs/issue12-telemetry-retention.md) `design:issue12-telemetry-retention`
 - [issue #13: 遥测 schema 自动 ALTER 降级为按后端不对称的显式档位](designs/issue13-schema-mode.md) `design:issue13-schema-mode`
 - [issue #15: 遥测连接池的资源语义与生命周期](designs/issue15-telemetry-pool-lifecycle.md) `design:issue15-telemetry-pool-lifecycle`
+- [issue #18: 隔离靠权限强制,目标靠显式声明](designs/2026-08-26-issue18-pg-test-isolation-design.md) `design:2026-08-26-issue18-pg-test-isolation`
 - [M1 核心里程碑设计:公共签名冻结与治理栈落地](designs/m1-core-design.md) `design:m1-core-design`
 - [M2 分布式:Redis 治理后端+背压+Postgres 遥测+pricing+Embedding+压测 harness](designs/m2-distributed.md) `design:m2-distributed`
 - [M2.5 治理韧性: 半死源隔离与健康感知调度](designs/m25-resilience.md) `design:m25-resilience`
@@ -38,17 +43,22 @@
 - [建表前先探测,判死只认「确定写不进去」](designs/issue9-telemetry-ddl-probe.md) `design:issue9-telemetry-ddl-probe`
 - [推理可观测性一等化(issue #16 + #17)](designs/2026-08-25-thinking-observability-design.md) `design:2026-08-25-thinking-observability-design`
 - [推理开关能力建模与 reasoning_tokens 采集(issue #5 + #6)](designs/2026-08-02-thinking-capability-design.md) `design:2026-08-02-thinking-capability-design`
+- [推理档位一等化设计(issue #20 及其一般形式)](designs/reasoning-effort.md) `design:reasoning-effort`
 - [治理后端故障归位为 scope 级不可用(Issue #7)](designs/governance-backend-error.md) `design:governance-backend-error`
 - [调用方自定义维度设计(issue #11)](designs/issue11-caller-dimensions.md) `design:issue11-caller-dimensions`
 - [采样参数透传设计(issue #4)](designs/sampling-params.md) `design:sampling-params`
 
-## finding (13)
+## finding (16)
+
+- [1.3.4 推理契约验证与发布准备](findings/2026-09-09-134-thinking-contracts-validation.md) `finding:2026-09-09-134-thinking-contracts-validation`
+- [1.3.5 T2/T3/T4 验收证据：36 列遥测、失败终态、PG 存储兼容与变异矩阵](findings/2026-09-09-135-call-observability-validation.md) `finding:2026-09-09-135-call-observability-validation`
 - [2026-07-20-m2-soak-workload](findings/2026-07-20-m2-soak-workload.md) `finding:2026-07-20-m2-soak-workload`
 - [2026-07-21-m25-acceptance](findings/2026-07-21-m25-acceptance.md) `finding:2026-07-21-m25-acceptance`
 - [2026-07-21-p6-soak-baseline](findings/2026-07-21-p6-soak-baseline.md) `finding:2026-07-21-p6-soak-baseline`
 - [2026-07-22-m4-acceptance](findings/2026-07-22-m4-acceptance.md) `finding:2026-07-22-m4-acceptance`
 - [2026-07-22-p7-ocr-soak](findings/2026-07-22-p7-ocr-soak.md) `finding:2026-07-22-p7-ocr-soak`
 - [issue #16/#17 实测: M3 推理正常,失效的是推理的可观测信号](findings/2026-08-25-thinking-observability-regression.md) `finding:2026-08-25-thinking-observability-regression`
+- [issue #18 实测: 偶发红的是安全网本身,不是被测脚本](findings/2026-08-26-issue18-shared-pg-test-isolation.md) `finding:2026-08-26-issue18-shared-pg-test-isolation`
 - [M2 verifier 三项 Important 补齐(不变量接线/网关保护/P3 验收)](findings/m2-verifier-fixes.md) `finding:m2-verifier-fixes`
 - [M2 真实数据压测: 场景矩阵与数据清单](findings/m2-soak-workload.md) `finding:m2-soak-workload`
 - [M2.5 验收: P6 同场景 58.1% → 98.96%](findings/m25-acceptance.md) `finding:m25-acceptance`
@@ -57,7 +67,10 @@
 - [P7 OCR soak 验收: 99.73% 与 13 不变量全 PASS](findings/p7-ocr-soak.md) `finding:p7-ocr-soak`
 - [推理开关与 reasoning_tokens: 供应商实测与业界做法](findings/2026-08-02-thinking-switch-and-reasoning-tokens.md) `finding:2026-08-02-thinking-switch-and-reasoning-tokens`
 
-## plan (33)
+## plan (38)
+
+- [1.3.4 推理契约实施计划](plans/2026-09-09-134-thinking-contracts.md) `plan:2026-09-09-134-thinking-contracts`
+- [1.3.5 逻辑调用统计与结构化失败诊断实施计划](plans/2026-09-09-135-call-observability.md) `plan:2026-09-09-135-call-observability`
 - [2026-07-20-m1-core-plan](plans/2026-07-20-m1-core-plan.md) `plan:2026-07-20-m1-core-plan`
 - [2026-07-20-m2-distributed-plan](plans/2026-07-20-m2-distributed-plan.md) `plan:2026-07-20-m2-distributed-plan`
 - [2026-07-21-m25-resilience-plan](plans/2026-07-21-m25-resilience-plan.md) `plan:2026-07-21-m25-resilience-plan`
@@ -73,7 +86,9 @@
 - [2026-08-19-issue12-telemetry-retention](plans/2026-08-19-issue12-telemetry-retention.md) `plan:2026-08-19-issue12-telemetry-retention`
 - [2026-08-19-issue13-schema-mode](plans/2026-08-19-issue13-schema-mode.md) `plan:2026-08-19-issue13-schema-mode`
 - [2026-08-24-issue15-telemetry-pool-lifecycle](plans/2026-08-24-issue15-telemetry-pool-lifecycle.md) `plan:2026-08-24-issue15-telemetry-pool-lifecycle`
+- [2026-09-04-reasoning-effort](plans/2026-09-04-reasoning-effort.md) `plan:2026-09-04-reasoning-effort`
 - [est_tokens 解耦实施计划](plans/est-tokens-decoupling.md) `plan:est-tokens-decoupling`
+- [issue #18 实现计划: 权限边界替代行数快照 + --table 锁死目标](plans/2026-08-26-issue18-pg-test-isolation.md) `plan:2026-08-26-issue18-pg-test-isolation`
 - [issue #8 实施计划: stall 非生产性等待口径](plans/issue8-stall-budget-plan.md) `plan:issue8-stall-budget-plan`
 - [M1 核心里程碑实现计划](plans/m1-core-plan.md) `plan:m1-core-plan`
 - [M2 分布式实现计划](plans/m2-distributed.md) `plan:m2-distributed`
@@ -85,6 +100,7 @@
 - [实现计划: HTTP 错误响应体留存(Issue #10)](plans/issue10-error-body-retention-plan.md) `plan:issue10-error-body-retention-plan`
 - [实现计划: issue12-telemetry-retention](plans/plan-issue12-telemetry-retention.md) `plan:plan-issue12-telemetry-retention`
 - [实现计划: issue13-schema-mode](plans/plan-issue13-schema-mode.md) `plan:plan-issue13-schema-mode`
+- [实现计划: 推理档位一等化](plans/reasoning-effort.md) `plan:reasoning-effort`
 - [实现计划: 治理后端故障归位为 scope 级不可用(Issue #7)](plans/governance-backend-error.md) `plan:governance-backend-error`
 - [实现计划: 遥测连接池的资源语义与生命周期(issue #15)](plans/plan-issue15-telemetry-pool-lifecycle.md) `plan:plan-issue15-telemetry-pool-lifecycle`
 - [推理可观测性一等化实现计划(issue #16 + #17,发 1.3.1)](plans/2026-08-25-thinking-observability-plan.md) `plan:2026-08-25-thinking-observability-plan`
@@ -93,11 +109,14 @@
 - [采样参数透传实现计划(issue #4)](plans/sampling-params-plan.md) `plan:sampling-params-plan`
 
 ## review (1)
+
 - [整分支审查: issue #14 熔断等待档](reviews/issue14-branch-review.md) `review:issue14-branch-review`
 
 ## schema (1)
-- [表结构: llm_calls(遥测 25 字段)](schemas/llm-calls.md) `schema:llm-calls`
+
+- [表结构: llm_calls(遥测 36 字段)](schemas/llm-calls.md) `schema:llm-calls`
 
 ## metric (2)
+
 - [OCR 治理调用成功率与错误分类分布](metrics/ocr-call-success.md) `metric:ocr-call-success`
 - [每次调用必录覆盖率(含缓存命中/失败/取消)](metrics/call-telemetry-coverage.md) `metric:call-telemetry-coverage`

research-wiki/log.md

@@ -144,3 +144,18 @@
 - [2026-08-26 04:49 UTC] 新增边: finding:2026-08-25-thinking-observability-regression --supports--> design:2026-08-25-thinking-observability-design
 - [2026-08-26 04:49 UTC] 新增边: finding:2026-08-25-thinking-observability-regression --refines--> design:2026-08-02-thinking-capability-design
 - [2026-08-26 04:49 UTC] 重建索引: 88 篇页面
+- [2026-08-26 11:28 UTC] 新增边: plan:2026-08-26-issue18-pg-test-isolation --implements--> design:2026-08-26-issue18-pg-test-isolation
+- [2026-08-26 11:28 UTC] 重建索引: 91 篇页面
+- [2026-09-05 04:06 UTC] 新增 design: 推理档位一等化设计(issue #20 及其一般形式) (design:reasoning-effort)
+- [2026-09-05 04:07 UTC] 新增 plan: 实现计划: 推理档位一等化 (plan:reasoning-effort)
+- [2026-09-05 04:07 UTC] 新增边: plan:reasoning-effort --implements--> design:reasoning-effort
+- [2026-09-05 04:07 UTC] 重建索引: 95 篇页面
+- [2026-09-09 04:48 UTC] 新增边: plan:2026-09-09-134-thinking-contracts --implements--> design:2026-09-09-134-thinking-contracts-design
+- [2026-09-09 04:48 UTC] 重建索引: 97 篇页面
+- [2026-09-09 05:39 UTC] 新增边: plan:2026-09-09-134-thinking-contracts --tested_by--> finding:2026-09-09-134-thinking-contracts-validation
+- [2026-09-09 05:39 UTC] 重建索引: 98 篇页面
+- [2026-09-09 06:32 UTC] 新增边: schema:llm-calls --implements--> design:2026-09-09-134-thinking-contracts-design
+- [2026-09-09 06:32 UTC] 重建索引: 98 篇页面
+- [2026-09-09 13:42 UTC] 新增边: plan:2026-09-09-135-call-observability --implements--> design:2026-09-09-135-call-observability-design
+- [2026-09-09 13:42 UTC] 重建索引: 100 篇页面
+- [2026-09-09 16:49 UTC] 重建索引: 101 篇页面

research-wiki/metrics/call-telemetry-coverage.md

@@ -7,3 +7,27 @@ date: 2026-07-20
 
 # 每次调用必录覆盖率(含缓存命中/失败/取消)
 
+## 1.3.4 契约与基线
+
+| 指标 | 确定性阈值／证据 | 实际 live 基线 |
+| --- | --- | --- |
+| 三个无推理入口成败行档位 NULL | embed、recognize_text、parse_layout 真实 client→emitter→临时 SQLite，非空失败／成功计数与 NULL 全部成立，契约要求100% | 待首次实际运行，不填伪百分比 |
+| chat 阳性 | 糖失败 auto、显式意图失败、nearest 成功实际档均精确匹配，要求100%；防恒 NULL 假绿 | 待首次实际运行 |
+| 四种行来源 | 真实成功=applied；失败=effective；cache_hit／scope终态=本次请求级 | 排除缓存／失败后才可做实际档分析 |
+| live 覆盖 | 逐轮 PASS／FAIL／UNCOVERED、计划轮数与缺轮分别统计；必需单元不因 pytest exit 0 自动放行 | 未执行；UNKNOWN／缺轮／skip 不能记PASS |
+
+复用 schema:llm-calls（无新字段／DDL），证据索引见 `findings/2026-09-09-134-thinking-contracts-validation.md`。独立错误取证只在 tests 内存，Markdown 只记录白名单安全摘要与布尔校验，不使用生产遥测旁路补失踪尝试。生产埋点仍是 TelemetryEmitter 单点出口。
+
+## 1.3.5 三类行与逻辑调用覆盖
+
+本版把覆盖度的计量单位从"一次尝试"改成"一次逻辑调用"——此前结构化耗尽、embedding／OCR 的无源与准入拒绝根本没有任何行,"每次调用必录"在这几条路径上是不成立的。
+
+| 指标 | 确定性阈值／证据 | 实际 live 基线 |
+| --- | --- | --- |
+| 领域失败的终态行覆盖 | chat 结构化耗尽、embedding／OCR 的 `no_sources`、准入拒绝、`retry_exhausted`、尝试外取消各恰有 **1** 条;单测以真实临时 SQLite 抓实 | 待首次实际运行,不填伪百分比 |
+| 至多一条(I3) | 同一逻辑调用重复进出口不产生第二条(`claim_terminal`);recorder 写失败仅 warning,故 SQL 可见 ≤ 1 | 待首次实际运行 |
+| 非领域异常 0 条(I4) | 编程错(如 `KeyError`)不写终态行、原样传播、分类不被改写 | 待首次实际运行 |
+| 诊断列保真 | 中转把 529 改写成 503 则记 503(**不猜回**);空 `str()` 的 httpx 超时类落 `cause_type`;成功行五列 NULL | 待首次实际运行 |
+| 存储兼容 | 真实 PG 沙箱: auto 追加十列、manual 裁剪写入、旧行新列恒 NULL、新旧进程混写共存 | 2026-09-09 实跑 30 passed(见下方证据索引) |
+
+本版**新增十列**(见 schema:llm-calls),不新建表、不新增依赖。证据索引见 `findings/2026-09-09-135-call-observability-validation.md`;覆盖度真实基线仍待首次生产运行填入,不写伪百分比。

research-wiki/plans/2026-08-26-issue18-pg-test-isolation.md

@@ -0,0 +1,297 @@
+---
+type: plan
+node_id: plan:2026-08-26-issue18-pg-test-isolation
+title: "issue #18 实现计划: 权限边界替代行数快照 + --table 锁死目标"
+date: 2026-08-26
+---
+
+# issue #18 实现计划
+
+> 类型：plan｜日期：2026-08-26｜分支 `fix/issue-18-pg-test-isolation`
+> 实现设计 `designs/2026-08-26-issue18-pg-test-isolation-design.md`（已过人类门）。设计的节号在下文直接引用；本计划只负责"动哪些文件、按什么顺序、怎么拿到证据"。
+> **本计划不涉及参考实现迁移，保真校验不适用。**
+
+> [!CAUTION]
+> **执行期唯一的不可逆风险，写在最前面。** 设计 §5.3 的"最坏情况"用例故意让脚本以裸 `search_path` 跑到共享表上。它**只有在沙箱角色就位之后才可以跑**——若在角色化之前用 `.env` 的 `app`（实测 superuser）跑它，`--older-than-days 7 --apply` 会真的删掉共享表里的过期行（实测那 11 行 2026-07-22 的数据全部早于任何截止线）。
+> 这条风险决定了下面的任务顺序：**沙箱工厂（Task 1）→ retention 全面角色化（Task 2）→ 才写这条用例**。它没有常规意义上的"先红"路径，见 Task 2 的说明。
+
+## 目标
+
+让 `tests/integration` 不再依赖也不再污染共享表 `llm_calls`，并把"清理脚本删错表"从事后可观测改成物理上做不到，随后发布 1.3.2。
+
+## 方案概述
+
+先建 `tests/integration/conftest.py` 的一次性沙箱工厂（独立 schema + 可选独占登录角色），把 retention 测试全面切到对真表无任何权限的角色上并删除行数快照；再给 `telemetry_retention.py` 加 `--table SCHEMA.llm_calls`（目标由参数精确解析、绕开 `search_path`，表名段锁死）；随后把 `test_postgres_telemetry.py` 的 7 条用例迁出真表、拆分 `_RUN_PREFIX` 的两个职责；最后加一道 lint 门防字面量回归，发布 1.3.2。
+
+## 涉及技术
+
+Python 3.12 / pytest + pytest-asyncio(auto) / asyncpg / PostgreSQL 16 权限与 `search_path` 语义 / argparse。
+
+## 文件结构
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `tests/integration/conftest.py` | **新建** | `PgSandbox` 与 `pg_sandbox` 工厂；admin DSN 私有化 |
+| `tests/integration/test_pg_sandbox.py` | **新建** | 工厂自身的行为测试（含 setup 中途失败不留残留） |
+| `tests/integration/test_retention_tool_pg.py` | 修改 | 全部用例角色化；删行数快照；补 `--table` 与最坏情况用例 |
+| `tools/telemetry_retention.py` | 修改 | 新增 `--table`；PG 分支目标解析改为"显式限定名优先" |
+| `tests/unit/test_retention_tool.py` | 修改 | `--table` 的参数分类用例（不连库） |
+| `tests/integration/test_postgres_telemetry.py` | 修改 | 7 条用例迁出真表；`_RUN_PREFIX` 双职责拆分；其余 fixture 收敛到工厂 |
+| `Makefile` | 修改 | `lint` / `check` 各加一道字面量门 |
+| `README.md` / `CHANGELOG.md` / `pyproject.toml` / `src/polygateway/__init__.py` | 修改 | `--table` 用法与 1.3.2 定版 |
+
+---
+
+## 跨任务共享接口（Task 1 产出，Task 2/4/5 消费）
+
+`tests/integration/conftest.py` 对外只有一个 fixture 与一个返回类型：
+
+```python
+@dataclass(frozen=True)
+class PgSandbox:
+    """一次性 PG 沙箱: 独立 schema + 可选独占登录角色。"""
+
+    schema: str
+    role: str | None
+    dsn: str              # 已挂 options=-csearch_path=<schema>
+    bare_dsn: str | None  # 同角色但不挂 search_path;role is None 时为 None
+```
+
+```python
+async def pg_sandbox(
+    *,
+    ddl: str | None = None,
+    extra: Sequence[str] = (),
+    role: Literal["none", "owner", "grantee"] = "none",
+    grants: Sequence[str] = ("SELECT", "INSERT"),
+) -> PgSandbox: ...
+```
+
+### 三种 `role` 的语义
+
+覆盖现有全部六个 fixture 的需求，**不得再加第四种**：
+
+| `role` | schema 属主 | `ddl`/`extra` 由谁执行 | 返回 DSN 的身份 | 对应今天的 fixture |
+|---|---|---|---|---|
+| `"none"` | admin | admin | admin | `fresh_schema` / `legacy_schema` / `pre_tenant_schema` / `partitioned_schema` |
+| `"owner"` | 临时角色 | **临时角色自己**（故表属主 = 该角色） | 临时角色 | 无（本次新增，retention 全部用例用） |
+| `"grantee"` | admin | **admin**（故表属主 = admin，与最小权限现场一致） | 临时角色（只被 `GRANT USAGE ON SCHEMA` + 表级 `grants`，**绝不 GRANT CREATE**） | `least_privilege_dsn` / `least_privilege_pre_tenant_dsn` |
+
+### `ddl` / `extra` 的执行契约
+
+1. **调用方传的 DDL 一律不带 schema 限定**（`CREATE TABLE llm_calls (...)`，不是 `CREATE TABLE {schema}.llm_calls`）。工厂在执行前对该连接 `SET search_path = <schema>`，由 search_path 定位。这条统一了两种今天并存的写法——`PG_DDL` 本就是裸表名，而 `_LEGACY_DDL` / `_PRE_TENANT_DDL` 今天带 `{schema}` 占位，**Task 5 要把这两个常量的 `{schema}.` 前缀去掉**。
+2. `extra` 在**同一连接、同一 search_path** 下按给定顺序逐条执行，不包事务（分区子表这类 DDL 各自提交即可）。
+3. `ddl is None` 时只建空 schema，不执行任何建表语句。
+
+### 临时角色的 DSN 构造
+
+- 密码：模块级常量（测试专用，非机密），沿用今天 `_PROBE_PASSWORD` 的做法。
+- `bare_dsn`：把 admin DSN 里的 `//user:pass@` 段整体替换为 `//<role>:<密码>@`（`re.sub(r"//[^@/]+@", ...)`，`count=1`），**不追加任何 `options` 参数**——它的用途就是让 `search_path` 回落到 `"$user", public`。
+- `dsn`：在 `bare_dsn` 基础上追加 `options=-csearch_path%3D<schema>`，分隔符按 DSN 里是否已有 `?` 选 `?` 或 `&`。
+- `role="none"` 时 `dsn` 用 admin 身份加同样的 options，`bare_dsn` 为 `None`——admin 的裸 DSN 不对用例开放（设计 §7.1 约束 3）。
+
+### 三条硬约束（设计 §5.1、§7.1，逐条都是验收点）
+
+1. schema 名 `pgw_s_<12 位 hex>`、角色名 `pgw_r_<12 位 hex>`，**两者前缀有意不同**——同名会让 `"$user"` 遮蔽真表，最坏情况用例就测不到真现场。
+2. 资源逐步登记：每建成一个对象就把它的清理动作入栈，`except BaseException` 时**逆序**执行并 re-raise；`yield` 之后的 teardown 走同一条清理路径。单个沙箱的清理顺序固定为 `DROP SCHEMA IF EXISTS <s> CASCADE` → `DROP OWNED BY <r>` → `DROP ROLE IF EXISTS <r>`（`DROP OWNED BY` 必须在 `DROP ROLE` 之前，否则角色仍持有对象无法删除）。一次用例内建多个沙箱时，沙箱之间也按 LIFO 清理。
+3. `role != "none"` 时先查 `rolcreaterole OR rolsuper`，**在建任何对象之前** `pytest.skip`（`production_template` 的教训：`pytest.skip` 抛的是 `BaseException`，若在清理块内触发会去 DROP 从未建过的对象，把 skip 盖掉）。
+
+---
+
+## Task 1：沙箱工厂
+
+- [ ] **文件**：`tests/integration/conftest.py`（新建）、`tests/integration/test_pg_sandbox.py`（新建）
+
+**行为**：实现上文《跨任务共享接口》全部内容。DSN 读取沿用今天两个文件里的做法（`dotenv_values(".env")` 合并 `os.environ`，剥掉 `+driver`，缺则 `skip`，库名不以 `/polygateway` 结尾则 `pytest.fail`）——这段逻辑今天重复两份，本任务收敛为一份私有函数。
+
+**测试要求（先红后绿的路径明确）**：先写 `test_pg_sandbox.py` 再写 `conftest.py`——此时 `pg_sandbox` fixture 不存在，pytest 报 `fixture 'pg_sandbox' not found`，六条用例全红，这就是本任务的先失败证据。随后实现工厂使其转绿。
+
+| 用例 | 断言 |
+|---|---|
+| `role="none"` 建表 | 表落在 `sandbox.schema` 下；`sandbox.bare_dsn is None` |
+| `role="owner"` 建表 | 表属主 = `sandbox.role`；`sandbox.role != sandbox.schema` 且两者前缀不同 |
+| `role="owner"` 的 `bare_dsn` | `SHOW search_path` 为 `"$user", public`；用它解析 `llm_calls` 得到的**不是**沙箱里那张表 |
+| `role="grantee"` | 该角色 `CREATE TABLE` 被拒（`asyncpg.exceptions.InsufficientPrivilegeError`），`INSERT` 正常 |
+| **setup 中途失败** | 传一段必然报错的 `ddl`（如 `CREATE TABLE llm_calls (bad_type NOT_A_TYPE)`），捕获异常后查 `pg_namespace` / `pg_roles`：本次 uuid 对应的 schema 与角色**都不存在** |
+| teardown 后无残留 | 在用例内部记下 `sandbox.schema` / `sandbox.role`，用一个**更外层**的 fixture（在 `pg_sandbox` 之后销毁）回查两者均已消失 |
+
+**验证**：
+```
+conda run -n PolyGateway pytest tests/integration/test_pg_sandbox.py -v
+```
+预期全绿；随后手工查实例：`SELECT nspname FROM pg_namespace WHERE nspname LIKE 'pgw%'` 与 `pg_roles` 同款查询均为空。
+
+---
+
+## Task 2：retention 测试角色化，删除行数快照
+
+- [ ] **文件**：`tests/integration/test_retention_tool_pg.py`（修改）
+
+**必须在 Task 3 之前完成**——见文首 CAUTION。
+
+**行为**：
+
+1. 删除 `_public_count`、`before_public` 与那条行数断言；删除本地的 `_make_schema` / `_drop_schema` / `_search_path_dsn` / `dsn` fixture，全部改用 `pg_sandbox`。
+2. **凡启动脚本的用例一律 `role="owner"`**（设计 §5.1，无一例外，含 dry-run 与分区让路两条）。
+3. 现有三条用例的其余断言逐条保留：`将删除行数: 5`、`'acme': 3`、批次 1/3 存在而批次 4 不存在、`已删除 5 行`、剩余 `fresh-1`/`fresh-2`、分区表退出 3 且含 `DROP PARTITION`/`DETACH`、缺 asyncpg 退出 2。
+4. 新增设计 §5.3 的**最坏情况**用例：用 `sandbox.bare_dsn`、不给 `--table`、`--older-than-days 7 --apply`。断言退出 **2**、stderr 非空且含 `llm_calls`、沙箱表一行不少。**不断言 PG 的英文错误原文**（`lc_messages` 不由测试掌握），**测试代码里不得出现 `public.llm_calls` 字面量**。
+
+**测试证据（这条用例没有常规先红路径，如实记录）**：让它变红的唯一方式是把角色换回 admin superuser——那会真删共享表的行，绝不执行。它的证伪由 `findings/2026-08-26-issue18-shared-pg-test-isolation.md` §7 的探针 6/7 提供：同款临时角色对真表的 `COUNT` 与 `DELETE` 均返回 `InsufficientPrivilegeError`。**提交说明里必须写明这一点**，不得含糊成"已验证"。
+
+其余改动的先红路径正常：删掉 `_public_count` 之前，先把三条既有用例切到沙箱并跑通（此时它们仍带旧断言），再删断言——若沙箱切换有问题，旧断言会先报出来。
+
+**验证**：
+```
+conda run -n PolyGateway pytest tests/integration/test_retention_tool_pg.py -v
+```
+预期全绿；连跑三次结果一致。
+
+---
+
+## Task 3：`--table` 参数与精确解析
+
+- [ ] **文件**：`tools/telemetry_retention.py`（修改）、`tests/unit/test_retention_tool.py`（修改）、`tests/integration/test_retention_tool_pg.py`（追加用例）
+
+**顺序**：**先写测试再改脚本**——四条集成用例与五条单测在脚本未改时全部先红（`--table` 未定义，argparse 直接以退出码 1 拒绝，而用例期望的是别的码/别的 stdout），实现后转绿。这就是本任务的先失败证据；Task 2 已先行完成，故这些用例从第一次运行起就跑在沙箱角色之下。
+
+**脚本行为**（设计 §4）：
+
+| 项 | 要求 |
+|---|---|
+| 参数 | `--table SCHEMA.NAME`，仅 `--backend postgres` 接受 |
+| 校验（全部退出 **1**） | sqlite 给了它；不是恰好两段；任一段为空；任一段含 `.` 或 `"`；**表名段不等于 `llm_calls`** |
+| 解析 | 给了 `--table` 时用 `to_regclass($1)` 传 `"<schema>"."llm_calls"`（`_quote` 包裹），绕开 `search_path`；未给时维持今天的裸 `TABLE` 解析 |
+| 解析不到 | 退出 **2**，消息点名显式指定的表，并附一句"PG 中未加引号建的标识符在 catalog 里是小写" |
+| 无权限 | 后续 `COUNT` 抛 `PostgresError`，走既有 except → 退出 **2**（不新增分支） |
+| 分区表 | 仍退出 **3**，逻辑不动 |
+| 提示行 | `--apply` 且**未**给 `--table` 时，在"目标表: x.y"之后打印一行，指出目标由 `search_path` 推断、可用 `--table` 钉死；dry-run 不打 |
+
+`--help` 的 epilog 补两句：本脚本只清理 `llm_calls`；含点或引号的复杂标识符不支持，此时退回不给 `--table` 的路径。
+
+**单测**（`tests/unit/test_retention_tool.py`，不连库）：`TestUsageErrors` 加五条，对应上表五种退出 1 的情形，逐条断言 stderr 含 `--table`；`TestHelp` 加一条断言 epilog 点明表名固定为 `llm_calls`。
+
+**集成用例**（`test_retention_tool_pg.py`，全部 `role="owner"`）：
+
+| 用例 | 构造 | 预期 |
+|---|---|---|
+| 显式指定成功 | `--table <sandbox.schema>.llm_calls` + `--apply` | 退出 0，删除结果与不给 `--table` 时逐条一致 |
+| 指向不存在的 schema | `--table pgw_s_nosuchxxxxxxxx.llm_calls` | 退出 **2**，stderr 点名该表；沙箱表一行不少 |
+| 指向无权的表 | 建两个 `role="owner"` 沙箱，用 A 的 DSN 指 B 的表 | 退出 **2**；A、B 两张表都不变 |
+| 指向分区表 | 分区沙箱 + `--table` | 仍退出 **3**，含 `DROP PARTITION` / `DETACH` 字样 |
+| 提示行（设计验收 #2） | 沙箱 DSN + `--apply`，**不给** `--table` | stdout 含推断提示。设计原写"单测断言 stdout"，但该行只在 PG 分支打印、不连库触发不到，故落在集成层；设计 §11 判据 2 已同步更正 |
+
+**验证**：
+```
+conda run -n PolyGateway pytest tests/unit/test_retention_tool.py tests/integration/test_retention_tool_pg.py -v
+```
+
+---
+
+## Task 4：7 条用例迁出真表，`_RUN_PREFIX` 拆职责
+
+- [ ] **文件**：`tests/integration/test_postgres_telemetry.py`（修改）
+
+**行为**：
+
+1. 七条用例改用 `pg_sandbox(role="none")`：`TestObservabilityColumns::test_values_round_trip`、`TestSchema` 三条、`TestDegradation::test_row_failure_does_not_poison_later_rows` 与 `test_aclose_idempotent`、`TestPoolFootprint::test_pool_does_not_preconnect_and_stays_within_pool_max`。
+2. `test_schema_has_frozen_columns_in_order` 的 `information_schema` 查询补 `table_schema = $1`（设计 §6.2；仓库注释已记载该隐患）。
+3. `TestPoolFootprint` **保留唯一 `application_name`**，就地生成 uuid（设计 §6.1）——这是实例级资源，schema 隔离对它无效。
+4. 删除 `_RUN_PREFIX` 的行隔离用途：`_cid()` 的 63 处调用机械替换为字面量（`_cid("c1")` → `"c1"`）；5 处 `LIKE` 逐条处置——`dsn` fixture teardown 的 `DELETE` 整条删除，`test_concurrent_writes_all_land` 的计数改 `COUNT(*)`，其余三处（legacy / least_privilege / manual-lp）改为不带前缀的精确条件。
+5. 删除已无引用的本地 `dsn` fixture 与其 teardown。
+
+**测试证据**：判据 6c 有明确先红路径——先在库里手工留一个残留同名表（`CREATE SCHEMA pgw_s_leftover; CREATE TABLE pgw_s_leftover.llm_calls (call_id TEXT)`），此时 `test_schema_has_frozen_columns_in_order` 因少了 `table_schema` 过滤而红；补上过滤后转绿；用完删掉该残留 schema。其余六条属迁移，证据形式是迁移前后断言逐条对照（设计 §11 判据 6），差异只允许出现在"表在哪"与"查询是否带 schema 过滤"两处——**这是回归门不是先红门，提交说明里如实这么写**。
+
+**验证**：
+```
+conda run -n PolyGateway pytest tests/integration/test_postgres_telemetry.py -v
+```
+判据 6b 另做：两个 shell 同时跑 `TestPoolFootprint` 那一条，两边都绿。
+
+---
+
+## Task 5：其余 fixture 收敛到工厂
+
+- [ ] **文件**：`tests/integration/test_postgres_telemetry.py`（修改）
+
+**行为**：
+
+1. `legacy_schema`、`pre_tenant_schema`、`fresh_schema`、`partitioned_schema` 改为 `role="none"`；`least_privilege_dsn`、`least_privilege_pre_tenant_dsn` 改为 `role="grantee"`。
+2. 按接口契约，`_LEGACY_DDL` 与 `_PRE_TENANT_DDL` 两个常量去掉 `{schema}.` 前缀与 `.format(schema=...)` 调用，改为裸表名由工厂的 search_path 定位。
+3. `production_template` **不收敛**：它要建三个角色、跑 README 解析出的整套模板 SQL、按月建分区，权限语义与失败期清理都是它自己的（设计 §7.1 末段与 Codex 意见 3）。工厂强行接管会把这些语义压扁。本任务只把它内部的 `_cid()` 调用一并处理掉。
+
+**测试证据**：这些 fixture 的既有用例断言**一行不改**——它们是这次收敛的验收器，改了就失去验收意义。这是回归门。
+
+**验证**：同 Task 4 的命令，预期全绿；在无 CREATEROLE 的账号下 `least_privilege` 系列仍能正确 skip。
+
+---
+
+## Task 6：lint 门与字面量清理
+
+- [ ] **文件**：`Makefile`（修改）、`tests/integration/*.py`（注释措辞）
+
+**行为**：`lint` 与 `check` 各加一步——`tests/` 下命中字面量 `public.llm_calls` 即 `exit 1` 并打印命中行。注释与 docstring **同样不豁免**，现有"共享的 public.llm_calls"改写为"共享表 `llm_calls`"。
+
+Makefile 里这道门的注释必须写明它的定位（设计 §7.2）：**烟雾报警器，不是隔离证明**——它拦不住 `f"{schema}.{table}"` 拼接与参数化查询，真正的隔离来自工厂不交出 admin DSN、脚本以无权角色运行。
+
+**测试证据**：故意加一行含该字面量的注释 → `make lint` 失败并打印该行；移除后 → 通过。
+
+**验证**：
+```
+make lint && make check
+```
+
+---
+
+## Task 7：独立验证（合并前硬门）
+
+- [ ] 派**全新上下文**的 verifier subagent（`verification-before-completion`），交给它设计 §11 的判据表逐条核对，重点：
+  - 判据 3（最坏情况删不掉任何行）是否真由权限拒绝达成，而非碰巧——它没有先红证据，须由 verifier 独立复核 findings §7 的探针与用例断言是否真的对应同一条防线
+  - 判据 4：整套 `tests/integration` 连跑三次，**其间由 verifier 手工改动真表行数**（插入若干行再删掉），全程应无任何用例受影响
+  - 判据 6：7 条用例迁移前后断言逐条对照
+  - `--table` 的五种退出 1 与三种退出 2/3 是否都有用例覆盖
+  - `tests/` 与实例上是否留下任何 `pgw_%` 残留
+
+---
+
+## Task 8：文档与版本号
+
+- [ ] **文件**：`README.md`、`CHANGELOG.md`、`pyproject.toml`、`src/polygateway/__init__.py`
+
+- README：`--table` 用法落在两处——"存量兜底"表格行与 SQLite 侧段落之后的脚本说明段；写明表名固定为 `llm_calls`。安装约束是 `>=1.3.0,<2` 范围式，**本版无需改**（已核）。
+- CHANGELOG：按设计 §10 如实写明 `tools/` 与 `tests/` 都不在 pip 包内，**1.3.2 的 wheel 与 1.3.1 在库代码上逐字节相同**，本版内容是运维脚本的契约扩展与测试确定性，不得包装成库能力更新。
+- 版本号两处一致改 `1.3.2`。
+- `make wiki-check WIKI=<路径>` 跑过（公共行为变更须同步用户文档站，`docs-convention.md` §2）。
+
+---
+
+## Task 9：发布 1.3.2
+
+- [ ] 按 CLAUDE.md §4.4.1 九步执行，一步不跳：合并 main（`--no-ff`）→ 在 main 上重跑 `make lint` 与全套件 → **显式跑 `pytest -m slow`** → 打 tag 并 push → `rm -rf dist && python -m build && twine check` → 上传 registry（token 走 `TWINE_PASSWORD`，不进命令行）→ `pip download` 验证并解包确认 → 建 Release + 挂仓库 → 以下游视角打开包页面与 Releases 页核对。
+- [ ] 关闭 issue #18，正文指向本计划与设计。
+
+---
+
+## 审查留痕（Codex，2026-08-26）
+
+报 5 项，**全部采纳**：
+
+| # | 意见 | 处置 |
+|---|---|---|
+| 1 | `ddl`/`extra` 的执行身份、search_path、顺序、schema 占位、失败清理顺序都没写成契约 | 新增《`ddl`/`extra` 的执行契约》一节；并据此在 Task 5 追加"去掉两个 DDL 常量的 `{schema}` 占位"这一步 |
+| 2 | 临时角色的密码来源与 DSN 构造规则缺失 | 新增《临时角色的 DSN 构造》一节 |
+| 3 | **Task 1 先实现 `--table`、Task 3 才写集成用例，先红路径不可能成立** | 采纳，任务重排：沙箱工厂 → retention 角色化 → `--table`（测试先写）。重排同时让 `--table` 的集成用例从第一次运行起就在沙箱角色之下，与文首 CAUTION 一致 |
+| 4 | 工厂测试缺"先写失败测试"的明确步骤 | Task 1 写明：先写 `test_pg_sandbox.py`，此时 `fixture 'pg_sandbox' not found` 全红 |
+| 5 | 设计验收 #2 说"单测断言 stdout"，计划却放在集成层 | 核实后确认是**设计写错了**——该提示行只在 PG 分支打印，不连库的单测触发不到。已就地更正设计 §11 判据 2，并在 Task 3 注明 |
+
+另外据 Codex 对 Task 4/5 的观察，两处证据形式（回归门而非先红门）已在任务里如实标注，不含糊成"已验证"。
+
+## Wiki 注册
+
+```bash
+.claude/tools/research_wiki.py add_entity research-wiki/ --type plan \
+    --id 2026-08-26-issue18-pg-test-isolation --title "issue #18 实现计划"
+.claude/tools/research_wiki.py add_edge research-wiki/ \
+    --from "plan:2026-08-26-issue18-pg-test-isolation" \
+    --to "design:2026-08-26-issue18-pg-test-isolation" --type implements
+.claude/tools/research_wiki.py rebuild_index research-wiki/
+```

research-wiki/plans/2026-09-04-reasoning-effort.md

@@ -0,0 +1,418 @@
+# 实现计划: 推理档位一等化
+
+- **设计**: `research-wiki/designs/2026-09-04-reasoning-effort-design.md`(2026-09-04 人类已批准)
+- **目标**: 把 `enable_thinking: bool | None` 升级为可表达厂商档位的 `Effort` 词汇,让「关不掉的模型」「打空的档位」从静默失效变成带出路的报错。
+- **方案概述**: 新增八档封闭枚举 `Effort`(含 `auto`);能力表从 `can_disable: bool` 改为 `supported_efforts: tuple[Effort, ...]`;provider 的两个固定片段改为 `ThinkingWire`(off / on_base / effort_key);档位入口取「源级默认 + 请求级覆盖」,进缓存 key 与遥测各一列。
+- **涉及技术**: Python 3.12 `StrEnum`、frozen dataclass、pydantic-settings env 解析、SQLite/Postgres DDL 补列、pytest。
+- **保真校验**: **不适用**。本计划实现的是库自研的推理决策(`thinking.py` 系 2026-08-25 新建),不属 ARCHITECTURE §1.4 的移植蓝本;且 `reference/` 三项目当前不在工作区(见设计 §12),无可比对源。
+
+---
+
+## 文件结构
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `src/polygateway/types.py` | 修改 | 新增 `Effort` 枚举;`SourceConfig`/`ChatRequest` 各加档位字段 |
+| `src/polygateway/thinking.py` | 修改 | `ThinkingCapability` 重构、`resolve_thinking` 五关、`reconcile_thinking` 判据、默认能力表重写 |
+| `src/polygateway/providers.py` | 修改 | `ThinkingWire` 新类型替换两个片段;`DEFAULT_PROFILES` 扩到 8 段 |
+| `src/polygateway/config.py` | 修改 | 两个新 env 键的解析与矛盾校验 |
+| `src/polygateway/client.py` | 修改 | `chat()` 签名加档位;`_fingerprint_mark` 纳入源级档位 |
+| `src/polygateway/middleware/cache.py` | 修改 | `build_cache_key` 纳入请求级档位 |
+| `src/polygateway/middleware/telemetry.py` | 修改 | `_record` 与三个 emit 入口传递生效档位 |
+| `src/polygateway/ports.py` | 修改 | `TelemetryRecorder.record_llm_call` 加一参(25 → 26 字段) |
+| `src/polygateway/telemetry/schema.py` | 修改 | `COLUMNS`、两端 DDL、补列声明 |
+| `src/polygateway/telemetry/{sqlite,postgres}.py` | 修改 | 落库新列 |
+| `src/polygateway/transports/openai_compat.py` | 修改 | 生效档位解析接线、告警节流键 |
+| `src/polygateway/__init__.py` | 修改 | 导出 `Effort`、`ThinkingWire` |
+| `.env.example` | 修改 | 两个新键的模板与注释 |
+| `tests/unit/test_thinking.py` | 修改 | 位置参数构造迁移 + 五关用例 |
+| `tests/unit/test_providers.py` | 修改 | `ThinkingWire` 用例 |
+| `tests/unit/test_cache.py` | 修改 | 档位进 key 的用例 |
+| `tests/unit/test_openai_compat.py` | 修改 | transport 接线与节流用例 |
+| `tests/unit/test_telemetry.py`、`tests/integration/test_redis_cache.py` | 修改 | 列数断言与缓存 key 回归 |
+| `tests/e2e/test_thinking_live.py` | 修改 | `can_disable` 读法迁移;新增逐模型档位实测(标 `slow`) |
+
+---
+
+## 关键接口(跨任务消费,此处定稿)
+
+```python
+# types.py
+class Effort(StrEnum):
+    NONE = "none"; AUTO = "auto"; MINIMAL = "minimal"; LOW = "low"
+    MEDIUM = "medium"; HIGH = "high"; XHIGH = "xhigh"; MAX = "max"
+
+_ORDER = (Effort.NONE, Effort.MINIMAL, Effort.LOW, Effort.MEDIUM,
+          Effort.HIGH, Effort.XHIGH, Effort.MAX)  # auto 不参与强弱序
+```
+
+```python
+# providers.py
+@dataclass(frozen=True)
+class ThinkingWire:
+    off: Mapping[str, Any] | None
+    on_base: Mapping[str, Any] | None
+    effort_key: str | None
+
+@dataclass(frozen=True)
+class ProviderProfile:
+    name: str
+    thinking: ThinkingWire
+    strip_think_tags: bool
+    supports_native_schema: bool = False
+```
+
+```python
+# thinking.py
+@dataclass(frozen=True)
+class ThinkingCapability:
+    supported_efforts: tuple[Effort, ...]
+    evidence: str
+
+    @property
+    def can_disable(self) -> bool: ...        # Effort.NONE in supported_efforts
+    @property
+    def cheapest_effort(self) -> Effort | None: ...  # 除 NONE 外按 _ORDER 最弱的一档
+    @property
+    def is_tiered(self) -> bool: ...          # 除 NONE/AUTO 外仍有 ≥1 档
+
+@dataclass(frozen=True)
+class ThinkingResolution:
+    """注入片段 + **实际**生效档。
+
+    返回 dataclass 而非裸 Mapping(CLAUDE.md 4.3「返回类型用 frozen dataclass」):
+    `nearest` 映射后请求档与实际档不同,遥测必须记后者,否则 T10 的压测按档位
+    分组时,被映射过的行会挂在一个从未真正发出的档下(Codex 审查指出)。
+    """
+    payload: Mapping[str, Any]
+    applied_effort: Effort | None   # Phase 1(不表态)为 None
+
+def resolve_thinking(
+    profile: ProviderProfile,
+    capability: ThinkingCapability | None,
+    effort: Effort | None,
+    *,
+    model: str,
+    fallback: str = "error",      # "error" | "nearest"
+    warn_unregistered: bool = True,
+) -> ThinkingResolution: ...
+
+def reconcile_thinking(
+    *,
+    effort: Effort | None,
+    observation: ThinkingObservation,
+    capability: ThinkingCapability | None,
+    model: str,
+) -> str | None: ...
+```
+
+```python
+# types.py 字段追加(均追加在末尾,不扰动既有位置构造)
+# SourceConfig: reasoning_effort: Effort | None = None
+#               effort_fallback: str = "error"
+# ChatRequest:  reasoning_effort: Effort | None = None
+```
+
+---
+
+## Task 1 — `Effort` 词汇与能力表重构
+
+**文件**: `src/polygateway/types.py`(改)、`src/polygateway/thinking.py`(改)、`src/polygateway/__init__.py`(改)、`tests/unit/test_thinking.py`(改)、`tests/e2e/test_thinking_live.py`(改)
+
+**行为**:
+1. `types.py` 新增 `Effort` 与 `_ORDER`(见上)。放 `types.py` 而非 `thinking.py`: 它是 `SourceConfig`/`ChatRequest` 的字段类型,定义在决策模块会让 `types.py` 反向 import(依赖铁律)。
+2. `ThinkingCapability` 改为 `supported_efforts` + `evidence`,加两个 `@property` 派生量。构造期校验: `supported_efforts` 非空、元素唯一、全部属 `Effort`,违反即 `ValueError`。
+3. `DEFAULT_CAPABILITIES` 按设计 §8 落库规则重写(见下表)。
+4. 迁移三处既有读点: `thinking.py` 内部读 `capability.can_disable` 改为读派生属性(行为不变);`tests/unit/test_thinking.py` 的 `ThinkingCapability(True, "实测")` 位置参数构造改为关键字构造;`tests/e2e/test_thinking_live.py` 读 `can_disable` 处确认派生属性可用。
+5. `__init__.py` 导出 `Effort`(包根导出是既有纪律: 深路径 import 正是模块重组会打断下游的原因,见 ARCH D11)。
+
+**初始 `DEFAULT_CAPABILITIES`**(evidence 一律以 `2026-09-04 文档推定(来源),待经 new-api 实测` 开头):
+
+| model | supported_efforts |
+|---|---|
+| `glm-5.3`, `glm-5.3-flash` | `(LOW, HIGH, MAX)` |
+| `glm-5.2` | `(NONE, HIGH, MAX)` |
+| `glm-5`, `glm-5.1`, `glm-4.6v` | `(NONE, AUTO)` |
+| `deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-v4-flash-vision-exp` | `(NONE, HIGH, MAX)` |
+| `gpt-5.4`, `gpt-5.5` | `(NONE, LOW, MEDIUM, HIGH, XHIGH)` |
+| `claude-opus-5`, `claude-sonnet-5` | `(NONE, LOW, MEDIUM, HIGH, XHIGH, MAX)` |
+| `gemini-3.1-pro` | `(LOW, MEDIUM, HIGH)` |
+| `kimi-k3` | `(LOW, HIGH, MAX)` —— 保守登记,evidence 注明 OpenRouter 标可关但官方档位无 `none` |
+| `MiniMax-M3` | `(NONE, AUTO)` |
+| `MiniMax-M2.7`, `MiniMax-M2.5` | `(AUTO,)` |
+| `qwen-plus-latest`, `qwen3.5-flash`, `qwen3.6-plus`, `qwen3.7-max`, `qwen3.7-plus` | `(NONE, AUTO)` |
+
+`claude-haiku-5`、`gemini-3-flash`、`kimi-for-coding` **不登记**(档位清单未知,走 Phase 3)。现有三条 MiniMax 条目的 evidence 原文保留并追加新形状说明——它们是实测得来的,比文档推定更硬,不得覆盖。
+
+**验收**: `can_disable` 对 11 类模型的返回与上表一致;`cheapest_effort` 对 `(LOW, HIGH, MAX)` 返回 `LOW`、对 `(NONE, AUTO)` 返回 `AUTO`、对 `(AUTO,)` 返回 `AUTO`;`is_tiered` 对 `(LOW, HIGH, MAX)` 为真、对 `(NONE, AUTO)` 与 `(AUTO,)` 为假;空元组构造报 `ValueError`。
+
+**测试**(先失败后通过): `tests/unit/test_thinking.py::test_capability_derives_can_disable`、`::test_cheapest_effort_skips_none`、`::test_is_tiered_excludes_none_and_auto`、`::test_empty_efforts_rejected`。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_thinking.py tests/unit/test_package.py -v` → PASS;`conda run -n PolyGateway make lint` → PASS(含 import-linter: `Effort` 落 `types.py` 不得产生反向依赖,设计 §13 第 6 条)
+
+- [ ] 提交: `refactor: make capability a tier list, since "can it be off" is one entry in it`
+
+---
+
+## Task 2 — `ThinkingWire` 与 8 段 provider 表
+
+**文件**: `src/polygateway/providers.py`(改)、`src/polygateway/__init__.py`(改)、`tests/unit/test_providers.py`(改)
+
+**行为**:
+1. 新增 `ThinkingWire`(见关键接口)。`None` 的语义严格沿用 issue #5: `on_base is None` = **开启形态未知**(请求开启档时报错),`off is None` = 该 provider 无关闭形态,`effort_key is None` = 该 provider 无档位概念。三者语义互不重叠,docstring 必须写明。
+2. `ProviderProfile.thinking_on`/`thinking_off` 两字段替换为 `thinking: ThinkingWire`。
+3. `DEFAULT_PROFILES` 由 4 段扩到 8 段:
+
+| provider | off | on_base | effort_key |
+|---|---|---|---|
+| `qwen` | `{"enable_thinking": False}` | `{"enable_thinking": True}` | `None` |
+| `deepseek` | `{"thinking": {"type": "disabled"}}` | `{"thinking": {"type": "enabled"}}` | `"reasoning_effort"` |
+| `zhipu` | `{"thinking": {"type": "disabled"}}` | `{"thinking": {"type": "enabled"}}` | `"reasoning_effort"` |
+| `moonshot` | `{"thinking": {"type": "disabled"}}` | `{"thinking": {"type": "enabled"}}` | `"reasoning_effort"` |
+| `minimax` | `{"reasoning_effort": "none"}` | `{}` | `"reasoning_effort"` |
+| `openai` | `{"reasoning_effort": "none"}` | `{}` | `"reasoning_effort"` |
+| `anthropic` | `{"reasoning_effort": "none"}` | `{}` | `"reasoning_effort"` |
+| `google` | `{"reasoning_effort": "none"}` | `{}` | `"reasoning_effort"` |
+
+`__init__.py` 同步导出 `ThinkingWire`。`openai` 段的两档由 `None`(未知)改为 OpenAI 标准形态,是本任务唯一的语义变更,理由写进注释: gpt-5.x 的 `reasoning_effort` 是 OpenAI 官方字段而非厂商方言,兜底段发它不会打到不认识它的厂商;真正未知形态的 provider 仍应走 `register_provider`。
+
+**验收**: `get_provider("zhipu").thinking.effort_key == "reasoning_effort"`;未注册名仍报错且错误文案列出全部 8 段;`register_provider` 仍返回新表不改共享状态。
+
+**测试**(先失败后通过): `tests/unit/test_providers.py::test_all_eight_profiles_registered`、`::test_wire_none_semantics_distinct`(三种 `None` 各自的含义不混淆)。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_providers.py -v` → PASS
+
+- [ ] 提交: `feat: give zhipu, moonshot, anthropic and google a wire of their own`
+
+---
+
+## Task 3 — `resolve_thinking` 五道关卡与 nearest 映射
+
+**文件**: `src/polygateway/thinking.py`(改)、`tests/unit/test_thinking.py`(改)
+
+**行为**: 按下表实现,**顺序不可调换**,每关的理由写进 docstring。
+
+| Phase | 条件 | 结果 |
+|---|---|---|
+| 1 | `effort is None` | 返回 `{}` |
+| 2 | **该请求档所需的**形态未知(请求 `none` 看 `wire.off`,其余档看 `wire.on_base`) | `ThinkingUnsupportedError`,指路 `register_provider`/`extra_body` |
+| 3 | `capability is None` | `warn_unregistered` 为真时 warning,随后按 wire 注入,**不校验档位** |
+| 4 | `effort is NONE` 且 `not capability.can_disable` | `ThinkingUnsupportedError`,文案含 `cheapest_effort` 与 env 键名 |
+| 5 | `effort not in supported_efforts` 且 `fallback == "error"` | `ThinkingUnsupportedError`;文案按 `capability.is_tiered` 分叉——档位型列出可选档,纯开关型说明「该模型只有开关没有档位,可用 `auto`/`none`」(设计 §3.2 第三个派生量的用途) |
+
+Phase 4 必须先于 5: `none` 只是 5 的特例,落进 5 会退化成「不支持 none,可选 low/high/max」,丢掉「这个模型根本关不掉」与可执行替代。
+
+**注入形态**:
+- `effort is NONE` → `wire.off`;`wire.off is None` 时报错(该 provider 无关闭形态)。
+- `effort is AUTO` → `wire.on_base`(不附档位)。这与旧 `thinking_on` 逐字节等价。
+- 其余档 → `{**wire.on_base, wire.effort_key: effort.value}`;`effort_key is None` 时报错并说明该 provider 只有开关没有档位。
+
+**nearest 映射**(`fallback == "nearest"`,人类 2026-09-04 复核确认实现): 按 `_ORDER` 在 `supported_efforts` 中取距请求档**位序最近**者,等距时**取弱侧**(省钱优先,不替下游涨价);`AUTO` 不参与距离计算,仅当它是唯一候选时才被选中;映射发生时 warning 记明「请求档 → 实际档 → 模型」。`effort is NONE` 且不可关时**不走映射**——那是 Phase 4 的领域,必须报错给出路,否则又变成静默降级。
+
+**验收**: 五关各自触发与不触发;`medium` 在 `(LOW, HIGH, MAX)` 上 `nearest` 映射到 `LOW`(等距取弱);`minimal` 映射到 `LOW`;`xhigh` 映射到 **`HIGH`**(与 `MAX` 等距,按「等距取弱」规则走——初稿此处写 `MAX` 是笔误,规则优先于例子)。**候选剔除 `none`**: 否则 `(none, auto)` 模型上请求 `high` 会被映射成 `none`,把「想浅一点」变成「别想了」,方向反转即 issue #20 那类静默失效。**`auto` 不受 Phase 5 清单约束**: 它在请求体里是「不写 `effort_key`」而非某个取值,可满足性只取决于 `on_base` 在不在;否则 `enable_thinking=True → AUTO` 会让存量源当场报错(能力表里档位型模型都不含 `auto`)。
+
+**测试**(先失败后通过,**五关各一条**,兑现设计 §13 第 1 条): `::test_phase1_absent_effort_injects_nothing`、`::test_phase2_unknown_wire_points_to_register`、`::test_phase3_unregistered_warns_then_injects`(并断言 `warn_unregistered=False` 时不喊)、`::test_phase4_before_phase5`(请求 `none` 打到 glm-5.3,断言文案**含** `cheapest_effort` 值与 `REASONING_EFFORT` 键名)、`::test_phase5_lists_tiers_for_tiered_model`、`::test_phase5_says_toggle_only_for_switch_model`。
+另: `::test_nearest_ties_go_cheaper`、`::test_none_never_maps`、`::test_auto_injects_on_base_only`、`::test_effort_key_none_rejects_tier`、`::test_resolution_reports_applied_effort_after_mapping`(请求 `medium` → 断言 `applied_effort is Effort.LOW`)。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_thinking.py -v` → PASS
+
+- [ ] 提交: `feat: refuse an impossible tier with the cheapest one that model does have`
+
+---
+
+## Task 4 — 源级配置入口
+
+**文件**: `src/polygateway/types.py`(改)、`src/polygateway/config.py`(改)、`.env.example`(改)、`tests/unit/test_config.py`(改)
+
+**行为**:
+1. `SourceConfig` 末尾追加 `reasoning_effort: Effort | None = None` 与 `effort_fallback: str = "error"`。
+2. `config.py` 的 `_SOURCE_FIELDS` 增两行: `"REASONING_EFFORT": ("reasoning_effort", "effort")`、`"EFFORT_FALLBACK": ("effort_fallback", "str")`。新增 `"effort"` 解析类型: 值必须属 `Effort` 取值域,否则报错并列出八档。
+3. `effort_fallback` 值域 `{"error", "nearest"}`,越界即报错(与 `_SELECTORS`/`_QUOTA_FULL` 同款 frozenset 校验)。
+4. **矛盾校验**(构造期): 同源同时给出 `enable_thinking` 与 `reasoning_effort` 且语义冲突时 `ValueError`。冲突定义: `enable_thinking is True` 且 `reasoning_effort is NONE`;或 `enable_thinking is False` 且 `reasoning_effort not in (None, Effort.NONE)`。二者一致(如 `False` + `none`)则放行。
+5. `.env.example` 加两键模板,注释写明八档取值、与 `ENABLE_THINKING` 的等价关系及矛盾会报错。
+
+**验收**: `LLM__ZHIPU__1__REASONING_EFFORT=low` 解析为 `Effort.LOW`;写 `lowest` 报错且文案列出八档;`ENABLE_THINKING=true` + `REASONING_EFFORT=none` 构造期报错。
+
+**测试**(先失败后通过): `tests/unit/test_config.py::test_effort_key_parsed`、`::test_invalid_effort_lists_vocabulary`、`::test_contradictory_thinking_flags_rejected`、`::test_consistent_flags_allowed`。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_config.py -v` → PASS
+
+- [ ] 提交: `feat: let a source name its reasoning tier, and say so when it contradicts itself`
+
+---
+
+## Task 5 — 请求级入口与优先级
+
+**文件**: `src/polygateway/types.py`(改)、`src/polygateway/thinking.py`(改,`effective_effort` 定义处)、`src/polygateway/client.py`(改)、`tests/unit/test_client.py`(改)
+
+**行为**:
+1. `ChatRequest` 末尾追加 `reasoning_effort: Effort | None = None`。
+2. `GatewayClient.chat()` 增关键字参数 `reasoning_effort: Effort | None = None`,存入 `ChatRequest`。
+3. 新增纯函数(放 `thinking.py`,与其余推理决策同处):
+
+```python
+def effective_effort(
+    *, request_effort: Effort | None, source_effort: Effort | None,
+    enable_thinking: bool | None,
+) -> Effort | None:
+    """生效档位: 请求级 > 源级 > enable_thinking 语法糖 > None。"""
+```
+
+语法糖映射: `True` → `Effort.AUTO`(注入 `on_base`,与旧行为逐字节等价,且不依赖能力表);`False` → `Effort.NONE`;`None` → 不表态。
+
+**验收**: 三层优先级各自生效;请求级 `None` 不会覆盖源级已配的档;只配 `enable_thinking=True` 的存量源解析为 `AUTO` 且最终 payload 与升级前逐字节相同。
+
+**测试**(先失败后通过): `::test_request_effort_wins_over_source`、`::test_none_request_does_not_clear_source`、`::test_enable_thinking_true_is_auto`、`::test_legacy_on_tier_matches_old_fragment`(回归门: **仅**对 `on_base` 完整表达「开」的 provider——qwen/deepseek/zhipu/moonshot——断言逐字节不变;minimax/openai/anthropic/google 的开档旧版硬编码 `medium`、新版不注入,是设计 §4.2 声明过的有意变更)。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_client.py -v` → PASS
+
+- [ ] 提交: `feat: let one call ask for a different tier than its source defaults to`
+
+---
+
+## Task 5b — 让 transport 拿得到请求级档位(端口签名扩展)
+
+**文件**: `src/polygateway/ports.py`(改)、`src/polygateway/middleware/retry.py`(改)、`src/polygateway/transports/openai_compat.py`(改)、`tests/unit/test_retry.py`(改)、`tests/unit/test_backpressure.py`(改)、`tests/integration/test_redis_cross_connection.py`(改)、`tests/unit/test_ports.py`(改)
+
+**为什么单列一步**(Codex 审查查出的阻断问题): T5 只把 `reasoning_effort` 放进 `ChatRequest`,但 `Transport` 协议收的是**拆开的**参数(`messages/source/stream/overlay/call_id`,`ports.py:39-49`),`RetryMW._attempt` 也只传这五个(`retry.py:282-288`)。不扩展协议,请求级档位根本到不了 `_build_payload`,设计 §4.2 的优先级落不了地。
+
+**行为**:
+1. `Transport.complete` 协议增关键字参数 `reasoning_effort: Effort | None`。**不设默认值**——与 `TelemetryRecorder` 同一既有约定: 库外无第三方实现者,完整签名成本为零,而给默认值会让漏传变成静默的「不表态」。
+2. `RetryMW._attempt` 调用处传 `request.reasoning_effort`。该中间件此前只读 `request` 的五个字段,新增第六个,不改其他语义。
+3. `OpenAICompatTransport.complete` 接收并透传给 `_build_payload`。
+4. 三个测试 fake 同步扩签名(`tests/unit/test_retry.py:72`、`tests/unit/test_backpressure.py:213`、`tests/integration/test_redis_cross_connection.py:76`)——`@runtime_checkable` 只查方法名不查签名,漏改会在调用时 `TypeError`,且错误现场离根因很远。
+
+**不动**: `EmbeddingTransport`、`OcrTransport` 两个协议——它们无推理语义(与 issue #4 给 embedding 加 `extra_body` 被否决同理: 装配期报错比静默无效更能指路)。
+
+**验收**: 请求级档位能一路到达 `_build_payload`;三个 fake 与协议签名一致;`tests/unit/test_ports.py` 的 Protocol 断言更新。
+
+**测试**(先失败后通过): `tests/unit/test_retry.py::test_request_tier_reaches_transport`(断言 fake 收到的 `reasoning_effort` 与 `ChatRequest` 一致)、`::test_embedding_transport_signature_unchanged`(回归: 未误改另两个协议)。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_retry.py tests/unit/test_backpressure.py tests/unit/test_ports.py -v` → PASS
+
+- [ ] 提交: `feat: carry the per-call tier down to the transport that must send it`
+
+---
+
+## Task 6 — 缓存 key
+
+**文件**: `src/polygateway/client.py`(改)、`src/polygateway/middleware/cache.py`(改)、`tests/unit/test_cache.py`(改)、`tests/integration/test_redis_cache.py`(改,该文件亦断言 key 形状)
+
+**行为**:
+1. `_fingerprint_mark`: 源级 `reasoning_effort` **仅在非 `None` 时**追加,规则与 `enable_thinking` 完全一致——全源不表态时指纹字面量逐字不变,存量缓存不冷启动。
+2. `build_cache_key` 增关键字参数 `reasoning_effort: Effort | None = None`,**仅非 `None` 时**写入 `key_obj["reasoning_effort"]`。
+3. `CacheMW.__call__` 传 `request.reasoning_effort`。
+
+**为什么两处都要**(写进注释): `model_fingerprint` 是装配期算的**集合级**指纹,覆盖不到逐次调用变化的请求级档位;不进 key 则同 messages 跑 low 与 max 互相命中,是 issue #4「5 个 seed 全命中同一响应」的逐字翻版。ARCH §7.5 记载的「集合级指纹仍可能返回另一源响应」这一既有取舍原样延续,本任务不扩大。
+
+**验收**: 同 messages 不同请求级档位 → key 不同;两者皆不表态 → key 与升级前逐字相同(回归);源级档位变化 → fingerprint 变化。
+
+**测试**(先失败后通过): `::test_request_tier_changes_key`、`::test_absent_tier_keeps_legacy_key`(断言具体 key 字符串不变)、`::test_source_tier_enters_fingerprint`。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit -k "cache or fingerprint" -v` → PASS
+
+- [ ] 提交: `fix: keep a low-tier answer out of the cache slot a max-tier one filled`
+
+---
+
+## Task 7 — 遥测新增 `reasoning_effort` 列
+
+**文件**: `src/polygateway/telemetry/schema.py`、`src/polygateway/ports.py`、`src/polygateway/telemetry/sqlite.py`、`src/polygateway/telemetry/postgres.py`、`src/polygateway/middleware/telemetry.py`(均改)、`tests/unit/test_telemetry.py`(改,含列数断言)、`tests/unit/test_ports.py`(改,Protocol 签名断言)、`tests/integration/test_postgres_telemetry.py`(改——该文件有 `_EXPECTED_COLUMNS` 完整**列序**断言与 pre-tenant 历史 DDL 的列子集推导,共 5 处,漏改则 PG 集成测试必红)、`src/polygateway/middleware/retry.py`(改,`emit_attempt` 调用点传新参)
+
+**行为**:
+1. `schema.py`: `COLUMNS` 末尾加 `"reasoning_effort"`(INSERT 字段 25 → 26,物理列 26 → 27);两端 DDL 追加 `reasoning_effort TEXT`(位置与 ALTER 追加一致);补列声明同步。**列数断言按物理列写**——两套口径混用是本模块最易错处(见其 docstring)。
+2. `ports.py`: `record_llm_call` 加 `reasoning_effort: str | None`(**不设默认值**,与既有约定一致: 库外无第三方实现者,少写一列会被 emitter 降级吞成 warning);docstring 的「25 字段冻结」改 26。
+3. 两个 recorder 落库新列。
+4. `middleware/telemetry.py`: `_record` 加参并传给 recorder(**唯一** `record_llm_call` 调用点,不复制参数列表);`emit_attempt` 增 `applied_effort` 关键字参数,由其三个调用方传值——`retry.py:411` 传实际档,`embedding.py:407` 与 `ocr.py:451` 传 `None`(无推理语义)。三个 emit 入口取值口径分列:
+
+| 入口 | 取值 | 理由 |
+|---|---|---|
+| `emit_attempt` | 成功时 `response.applied_effort`(T8 送上来的实际档);**失败时**回落到 `effective_effort(...)` 的请求档 | **不是**请求档: `nearest` 映射后二者不同(请求 `medium` → 实际 `LOW`),记请求档会让 T10 的压测把行挂在从未发出的档下。失败尝试没有 response,实际档不可知,记请求档并接受这一含义差别——总好过 issue #19 抱怨的「失败行无归因」 |
+| `emit_cache_hit` | `request.reasoning_effort` | 缓存命中没有选中源,源级档位无从谈起 |
+| `emit_terminal_failure` | `request.reasoning_effort` | 同上(可能根本没选出源) |
+
+与 `sampling` 列的现有做法同构(`emit_attempt` 合并源级,另两处只取请求级)。
+5. 值为 `Effort` 时取 `.value` 落库,`None` 落 `NULL`——与 `thinking_observation` 同一先例(`StrEnum` 是 `str` 子类,asyncpg 对子类编码不保证接受,遥测写失败只降级 warning,PG 那一路会静默少列)。
+
+**验收**: 两端建表列数断言更新且通过;三个入口各自落值正确;不表态时为 `NULL`;`telemetry_schema_sql` 打印的 SQL 与库实际执行的 DDL 同源。
+
+**测试**(先失败后通过): 既有遥测列数断言用例更新;`::test_effort_column_records_effective_tier`、`::test_cache_hit_records_request_tier_only`、`::test_absent_tier_is_null`。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit tests/integration -k telemetry -v` → PASS
+
+- [ ] 提交: `feat: record which tier a call actually ran at`
+
+---
+
+## Task 8 — transport 接线与对账
+
+**文件**: `src/polygateway/transports/openai_compat.py`(改)、`src/polygateway/thinking.py`(改)、`tests/unit/test_openai_compat.py`(改)
+
+**行为**:
+1. `_build_payload`: 用 `effective_effort(...)` 求生效档位后调 `resolve_thinking(..., fallback=source.effort_fallback)`。注入结果仍**先于** `source.extra_body` 与 `overlay`(顺序即优先级,issue #4 决策 A,两行不可调换)。
+2. `_warn_on_thinking_mismatch` 的节流键由 `(source.name, source.model, source.enable_thinking)` 改为 `(source.name, source.model, effective_effort)`——同一模型的 low 与 max 是两个独立的矛盾,共用一个键会让第二个永久静音。
+3. `reconcile_thinking` 签名的 `enable_thinking: bool | None` 改为 `effort: Effort | None`,判据: `effort is NONE` 对应原「要求关闭」分支,`effort` 为其余档对应原「要求开启」分支,`None` 仍返回 `None`。**不新增**「档位高低 vs `reasoning_tokens` 多少」的对账(设计 §4.3: 无可判定的函数关系,拿它报警必然是噪声)。
+4. `ThinkingUnsupportedError` 的捕获与翻译路径不变(→ `RequestRejectedError`,不重试不换源不计熔断)。
+5. **把实际档送出 transport**(否则遥测记不到 `nearest` 映射后的真实档):
+   - `TransportResult` 末尾追加 `applied_effort: Effort | None = None`——带默认值,非 OpenAI 兼容的 transport(OCR/embedding)可不填,与 `thinking_observation` 同一先例;
+   - `LLMResponse` 末尾追加 `applied_effort: Effort | None = None`——**字段只增不删不改名**,符合 ARCH §5.1 迁移兼容约束;对下游也有价值(它终于能知道这次实际跑在哪档);
+   - `RetryMW` 在 `retry.py:375` 的 `TransportResult → LLMResponse` 转换处带上该字段。
+
+**验收**: 档位不支持时抛 `RequestRejectedError` 且不触发重试与熔断计数;同源同模型不同档各喊一次告警;`reconcile` 三类文案与既有逐字一致(除方向描述由 bool 改档位);`nearest` 映射后 `LLMResponse.applied_effort` 是**映射后**的档。
+
+**测试**(先失败后通过): `::test_unsupported_tier_is_request_rejected`、`::test_no_retry_on_tier_error`、`::test_throttle_key_separates_tiers`、`::test_reconcile_none_vs_observed`、`::test_response_carries_mapped_tier`(请求 `medium`、能力 `(LOW,HIGH,MAX)` → 断言 `response.applied_effort is Effort.LOW`)。
+
+**验证**: `conda run -n PolyGateway pytest tests/unit -k "transport or openai_compat" -v` → PASS
+
+- [ ] 提交: `feat: wire the tier through the transport and keep each tier's warning distinct`
+
+---
+
+## Task 9 — 全套件、文档与 wiki
+
+**文件**: `CHANGELOG.md`、`.env.example`(复核)、Gitea Wiki(按 `research-wiki/docs-convention.md` §2)、`src/polygateway/__init__.py`(版本号)、`pyproject.toml`(版本号)
+
+**行为**:
+1. `make lint` + `make test` 全绿;`make format`。
+2. CHANGELOG 加「未发布」段: 破坏性变更(`ThinkingCapability` 构造签名)、新增(八档 `Effort`、两个 env 键、遥测新列、四个 provider 段)、行为变更(`openai` 段两档由未知改为 OpenAI 标准形态)。
+3. 按 docs-convention §2 同步 wiki(公共行为变更必须同步,版本 bump 不得裸发)。**CHANGELOG 必须覆盖三条行为变更**,漏第三条是独立验证点名的风险: ① `ThinkingCapability` 构造签名(破坏性);② minimax/openai/anthropic/google 开档不再注 `medium`;③ `openai` 兜底段由「形态未知即报错」放宽为标准形态——把别家模型挂在该段下并配 `ENABLE_THINKING=true` 的下游,旧版装配期报错,新版静默不注入任何字节(对这四段涉及的模型无害,它们默认即推理;但语义变了,须明写)。
+4. 版本号 **`1.3.3`**(2026-09-05 人类指令;不因破坏性变更走 minor),`pyproject.toml` 与 `src/polygateway/__init__.py` 两处一致。**本任务只 bump 不发布**——发布走 CLAUDE.md §4.4.1 全清单。
+
+**验收**: `make ci` 通过;CHANGELOG 与 wiki 均含破坏性变更条目。
+
+**验证**: `conda run -n PolyGateway make ci` → PASS
+
+- [ ] 提交: `docs: cut 1.3.3 notes for the tier work`
+
+---
+
+## Task 10 — e2e 实测校正初始能力表(标 `slow`)
+
+**文件**: `tests/e2e/test_thinking_live.py`(改)、`src/polygateway/thinking.py`(改——`DEFAULT_CAPABILITIES` 与 evidence 就在此处,实测结论要写回它,否则本任务只跑不改,设计 §8/§13 第 5 条落不了地)
+
+**行为**: 对 §Task 1 表中每个已登记模型,经 new-api 实测其 `supported_efforts`,方法论沿用 issue #20: 固定短提示词,逐档 N≥5,判据取 `usage.completion_tokens_details.reasoning_tokens`;对声明不可关的模型额外验证「请求 `none` 是否真被拒或真未关」。测试标 `slow`(成败取决于外部服务当下状态,默认不进日常套件)。实测结论逐条替换 `evidence` 中的「文档推定」。
+
+**为什么必须单列一个任务**: 人类 2026-09-04 定「能力表数据统一自己经 new-api 实测」;Task 1 落的是文档推定值,不实测则整张表都是假设。
+
+**验收**: 每个已登记模型有一条实测记录;与文档推定不符者更新 `supported_efforts` 并在 evidence 记明分歧(尤其 `kimi-k3` 的保守登记、`gemini-3.1-pro` 的默认档两源打架)。
+
+**验证**: `conda run -n PolyGateway pytest tests/e2e/test_thinking_live.py -m slow -v` → PASS(约 20-40 分钟,取决于网关)
+
+- [ ] 提交: `test: replace the guessed tier table with what the gateway actually does`
+
+---
+
+## 执行顺序与依赖
+
+```
+T1(词汇+能力表) ──┬─→ T3(五关) ─────────────→ T8(transport)
+T2(wire) ─────────┘                            ↑
+T4(源级) ─→ T5(请求级字段) ─→ T5b(端口签名) ──┤
+                    │                          │
+                    └─→ T6(缓存 key)           ↓
+                                          T7(遥测) ─→ T9(文档) ─→ T10(实测,回写能力表)
+```
+
+T1/T2 可并行;T3 依赖两者;T5 依赖 T4(语法糖等价关系);**T5b 依赖 T5**(要有 `ChatRequest.reasoning_effort` 才有得传);T6 依赖 T5;T8 依赖 T3 + T5b(没有 T5b 就拿不到请求级档位);**T7 依赖 T8**(自审纠正: 遥测要记的实际档由 T8 在 transport 内算出并经 `TransportResult`/`LLMResponse` 送上来,先做 T7 只能记到请求档);T9 在功能任务全绿后;T10 最后,且它会**改回 `thinking.py`**——与 T1 同一文件,故必须排在最后而非与其并行。
+
+执行方式: 10 个任务耦合度中等(共享 `Effort`/`ThinkingCapability`/`ThinkingWire` 三个类型),**直接按计划实现**,不派 `subagent-driven-development`——跨任务共享类型多,独立上下文的 subagent 容易在签名上分叉。

research-wiki/plans/2026-09-09-134-thinking-contracts.md

@@ -0,0 +1,393 @@
+---
+type: plan
+node_id: plan:2026-09-09-134-thinking-contracts
+title: "1.3.4 推理契约实施计划"
+date: 2026-09-09
+---
+
+# 1.3.4 推理契约与测试证据实施计划
+
+> 日期：2026-09-09。状态：**自审及 Codex 独立计划审查通过（复审 run ea38c3a7-12ef-4bf0-bb04-257ce37eb96f），T0–T7 已实现并通过确定性验证；T8 文档已同步，独立验证／集成／live 与 T9 待执行**。
+> 设计：`research-wiki/designs/2026-09-09-134-thinking-contracts-design.md`，用户已正式批准。
+> 目标：解决 #21 的受管推理语义漏洞、#25 的测试归因漏洞、#26 的客户端遥测守卫缺口，不扩展生产端口或遥测 schema。
+> 方案：在既有推理决策层添加窄校验并接入工厂／默认 transport；测试侧独立保留请求与响应证据，按明确命题判定覆盖。缓存仍由下游显式迁移，生产治理循环不重写。
+> 技术：Python 3.12+、asyncio、httpx hooks／MockTransport、frozen dataclass、pytest、临时 SQLite、ruff、import-linter；不新增依赖。
+
+本计划不涉及参考实现迁移，保真校验不适用；不得变更 Redis Lua、429／stall、取消结算、结构化重试或 #19／#23／#24 的生产机制。
+
+## 1. 基线、授权与执行纪律
+
+| 项目 | 固定边界 |
+| --- | --- |
+| 分支／历史 | `feature/1.3.4-thinking-contracts`；保留已有 `758a127`／`6a09054`，不重写 main 历史；开始时记录实际 HEAD 与 origin/main |
+| D1 | 已登记 AUTO 必须为清单成员；未知 AUTO 保留尽力＋warning，空 wire 可能不发送推理字节，不保证开启 |
+| D2 | 受管意图非 None 时，两层 raw 推理控制同值／被遮蔽也拒绝；raw-only 保留，不反向推断实际档 |
+| D3 | 不添加 fallback 指纹、语义 revision、能力表版本或新缓存前置解析；显式更换 namespace／salt 是操作前置，未迁移可能回放旧语义 |
+| 实施权限 | 一工作区仅一 writer；父会话负责前台委派与审核。用户已授权门通过后自行合并 main、测试并发布 1.3.X，无需逐步请示；1.4、新公共决策、验证豁免须停下确认 |
+| 证据与秘密 | 不打印 `.env`、token、Authorization、私有提示词；不提交 `.pi/`、运行报告或 reference；命令输出只记录安全路径、状态、退出码 |
+
+T0 开始调用 `writing-plans`；T1–T7 行为测试执行 `test-driven-development` 并阅读其 testing-anti-patterns；T1／T5 落日志前执行 `structured-logging`。每次提交执行 `commit` skill（英文祈使标题、无 AI 签名、显式路径暂存），T8 前执行 `requesting-code-review`／`verification-before-completion`，收到意见执行 `receiving-code-review`；异常先用 `systematic-debugging` 定根因。
+
+用户自主发布授权涵盖既有发布清单的真实 slow 套件，沿既有配置／轮次／并发执行，不重复索取这一授权。超出既有测试矩阵的新研究实验先提交型号、轮次、并发和费用预算；禁止借研究名义追加裸 HTTP 对照。设计要求的新增覆盖先用现有矩阵表达，无法表达且增加调用量时升级该预算决策。
+
+## 2. 文件职责与不变接缝
+
+| 创建／修改 | 精确路径 | 职责 |
+| --- | --- | --- |
+| 修改 | `src/polygateway/thinking.py` | AUTO 成员检查、nearest 边界、wire 与 raw 冲突纯校验、错误及未知告警文案 |
+| 修改 | `src/polygateway/providers.py` | MiniMax on_base 改空；修正空 wire docstring，不在声明层引入决策依赖 |
+| 修改 | `src/polygateway/client.py` | `_guard_thinking` 校验源 raw；`chat` 请求显式档＋已知 raw 冲突前置校验；指纹不改 |
+| 修改 | `src/polygateway/transports/openai_compat.py` | `_build_payload` 完整守卫，两层浅覆盖次序不改，沿 complete 的异常翻译 |
+| 修改 | `tests/unit/test_thinking.py`、`tests/unit/test_providers.py` | 纯解析、声明、已知／未知／自定义 wire、告警与边界 |
+| 修改 | `tests/unit/test_client.py`、`tests/unit/test_config.py`、`tests/unit/test_openai_compat.py`、`tests/unit/test_retry.py` | 工厂、请求前置、真实 transport、无 HTTP 拒绝与治理收尾；离线兼容 |
+| 修改 | `tests/unit/test_cache.py` | 显式迁移和未迁移风险回归；保留旧键黄金值 |
+| 修改 | `tests/unit/test_embedding.py`、`tests/unit/test_ocr_client.py`、`tests/unit/test_telemetry.py`、`tests/unit/test_monkey_ocr.py` | 三入口 NULL、阳性、SQLite 与 wire；不改变生产 emitter／client 循环 |
+| 新建 | `tests/live_evidence.py` | 测试专用 frozen 证据、有限归因、身份与覆盖判据、逐轮安全报告；无环境自读取 |
+| 新建 | `tests/e2e/conftest.py` | 测试侧 hooks、任务局部关联、薄 transport 委托与配置装配；不复制生产 payload／重试算法 |
+| 新建 | `tests/unit/test_live_evidence.py` | 分类、hooks／委托器和报告离线反例；导入新 conftest 中无副作用定义，不导入读 .env 的 live 模块 |
+| 修改 | `tests/e2e/test_smoke_gateway.py`、`tests/e2e/test_compat_projects.py`、`tests/e2e/test_embed_probe.py`、`tests/e2e/test_thinking_live.py` | 迁入窄证据通道、逐轮完整性与命题分流，保留必须真实执行的行为断言 |
+| 修改 | `README.md`、`CHANGELOG.md`、`.env.example`、`research-wiki/ARCHITECTURE.md`、`research-wiki/designs/2026-09-04-reasoning-effort-design.md` | 用户可达迁移说明、架构同步、旧设计被替代指针；不追改历史实验事实 |
+| 修改／登记 | `research-wiki/schemas/llm-calls.md`、`research-wiki/metrics/call-telemetry-coverage.md`、`research-wiki/graph/edges.json`、`research-wiki/index.md`、`research-wiki/log.md` | 复用既有实体，登记本计划与四种遥测口径；只接受工具对相关实体的必要索引更新 |
+| 新建（验收时） | `research-wiki/findings/2026-09-09-134-thinking-contracts-validation.md` | 红绿、变异、失败与豁免索引，≤300 行；原始输出留 `tests/outputs/134/` |
+| 修改（发布时） | `pyproject.toml`、`src/polygateway/__init__.py` | 两处版本一致到 1.3.4，不改变依赖或导出面 |
+
+生产不修改 `ports.py`、`types.py`、`errors.py`、cache／telemetry 实现及 embedding／OCR 循环；若实际实现需要突破该清单，先说明设计要求与最小原因，由父会话核定，不顺手改动。
+
+## 3. 跨任务接口（内部实现约定，不新增公共导出）
+
+### 3.1 推理守卫
+
+新函数置于 `thinking.py`，其余模块显式 import；保持决策方向 `client/transport → thinking → providers/types`。`Mapping`、`Any`、`Effort`、`ThinkingWire` 均为既有类型。函数体由 T2 实现，以下固定消费者签名：
+
+```python
+def validate_thinking_wire(wire: ThinkingWire, *, model: str) -> None:
+    """拒绝 on_base 偷带已知强度，抛 ThinkingUnsupportedError。"""
+def validate_thinking_raw(
+    raw: Mapping[str, Any], *, effort: Effort | None,
+    wire: ThinkingWire | None, origin: str,
+) -> None:
+    """effort 表态时拒绝 raw 控制；wire=None 只检查标准词表。"""
+```
+
+签名中的 wire 必填但可 None，None 是 chat 前置看不到实际 profile 的事实，不是容错默认；origin 只取固定位置名／源名，不含 raw 值。两函数无 I/O，不改变输入，抛现有 `ThinkingUnsupportedError`（ValueError 子类），不新建错误类。`validate_thinking_wire` 在 `resolve_thinking` 的 None 早退之前验证声明结构；不会要求无意图时 wire 必须已知，只拒绝结构上偷带强度。
+
+标准 raw 根：`reasoning_effort`、`enable_thinking`、`thinking`、`thinking_budget`、`reasoning`、`thinkingConfig`；`output_config` 为 Mapping 且有 `effort` 时冲突。wire 可见时并入 on_base／off 全部顶层根与 effort_key，点号只是字面键。
+
+wire 校验只拒绝 on_base 中自己的非 None effort_key、标准 reasoning_effort、标准嵌套 output_config.effort（含值为 auto／None）；不解析任意私有方言。未知／非当前方向的形态检查继续由现有 `_wire_unknown_for` 负责，不改变 off-only 可用性。
+
+### 3.2 测试证据与归因
+
+`tests/live_evidence.py` 不 import e2e conftest、不读环境、不发网络。上下文中的密钥只做内存比较，不进下列值类型。一个 attempt 可以记录零／一／多 HTTP 事件；不能用 len(attempts) 冒充 HTTP 数。
+
+```python
+@dataclass(frozen=True)
+class HttpEvidence:
+    call_id: str
+    request_checks: tuple[tuple[str, bool], ...]
+    status_code: int
+    error_body: bytes | None
+    raw_identity: tuple[bool, str | None]
+```
+
+`raw_identity` 是 T5 生产、T6 消费的**成功非流式原始身份快照**：(False, None) 表示未取证，(True, None) 表示已独立解析完整 JSON 对象且 model 缺失／为 null，(True, str) 表示原始字符串。由 response hook 保存的响应引用在该次 complete 结束后读取已缓冲 content，独立 JSON 解码（拒绝重复键）取得；不得从 TransportResult／LLMResponse.model_reported 回填。未缓冲、无可配对响应、非成功非流式、JSON 非对象／非法或 model 非字符串非 null 均不生成肯定证据，并保存原因供 FAIL；不把解析异常解释成身份缺失。成功 SSE 始终 (False, None)，不新增捕获器、不预读流。
+
+`request_checks` 必须完整包含 method／origin／path／model／stream（embedding 为 input_shape）／authorization／control／messages_digest，缺项不算全过；error_body 只允许 ≤65536 字节已缓冲完整错误体，超限或未缓冲为 None，并在安全报告写证据不足，不把截断文本拿来解析。记录只存在测试内存，不能直接 asdict 后落盘。
+
+```python
+@dataclass(frozen=True)
+class AttemptEvidence:
+    call_id: str
+    http: tuple[HttpEvidence, ...]
+    error: Exception | None
+```
+
+```python
+@dataclass(frozen=True)
+class LiveVerdict:
+    status: Literal["PASS", "FAIL", "UNCOVERED"]
+    reason: str
+```
+
+消费者固定为 T5→T6，纯函数与报告出口如下；参数所用 Path、Mapping、Sequence、ThinkingObservation、Effort 为标准库／现有领域类型：
+
+```python
+def classify_live_failure(
+    error: Exception, attempts: Sequence[AttemptEvidence],
+) -> LiveVerdict:
+    """异常分类仅 FAIL/UNCOVERED；取消不交给此函数。"""
+def write_live_round(
+    output_dir: Path, *, run_id: str, matrix_id: str, round_index: int,
+    safe_fields: Mapping[str, Any],
+) -> Path:
+    """只接受已脱敏报告字段，唯一文件写失败必须冒泡。"""
+```
+
+身份与命题判定继续放 `tests/live_evidence.py`，避免 e2e 中四份条件分支：
+
+```python
+def assess_model_identity(
+    *, requested: str, aliases: frozenset[str], reported: str | None,
+    raw_identity: tuple[bool, str | None], request_valid: bool,
+) -> LiveVerdict:
+    """raw_identity[0] 表示有独立原始身份取证；无证据不得归因上游。"""
+def assess_thinking_coverage(
+    observations: Sequence[ThinkingObservation], *, planned_rounds: int,
+    proposition: Literal["enabled", "disabled", "cannot_disable"],
+) -> LiveVerdict:
+    """输入须先过请求/身份资格；缺轮与 UNKNOWN 不补足证明。"""
+```
+
+拒绝能力测试不送入以上观测函数，按预声明异常类型／状态／机器字段独立断言。`cannot_disable` 保留 T10“实际未关闭与声明比较”的反证形态：完整合格轮次有 OBSERVED 可支持本条件下不可关闭；全 ABSENT 证伪声明；无 OBSERVED 但有 UNKNOWN 只能未覆盖。不得扩大成“证明所有私有上游参数都无法关闭”。
+
+### 3.3 测试侧取证装配
+
+新 `tests/e2e/conftest.py` 内 `ObservedTransport` 包裹**同一个**真实 `OpenAICompatTransport`，complete／embed 签名逐字保持 `ports.py`，参数原样传递。每次调用将 call_id 绑定实例持有的 ContextVar，finally reset；异常原样上抛，CancelledError 不转普通错误。不得在委托器做治理重试或 payload 修正。
+
+```python
+class LiveCapture:
+    def __init__(self, *, expectations: Mapping[str, Mapping[str, Any]]) -> None:
+        """按源名持有测试矩阵显式预期，不含凭据或真实响应。"""
+    def round_context(self, *, session_id: str, parent_call_id: str) -> AbstractContextManager[None]:
+        """外围绑定逻辑轮次，finally 复位，嵌套任务不串线。"""
+    def client_factory(self, source: SourceConfig) -> httpx.AsyncClient:
+        """按实际源构造带 hooks 客户端，沿生产 timeout/trust_env。"""
+    def attempts(self, *, session_id: str, parent_call_id: str) -> tuple[AttemptEvidence, ...]:
+        """返回本轮快照，含零 HTTP 的尝试，不从最终异常猜前序。"""
+    def raw_identity(self, *, session_id: str, parent_call_id: str, call_id: str) -> tuple[bool, str | None]:
+        """精确读取本逻辑轮次和成功 attempt 唯一 HTTP 事件的原始身份快照。"""
+```
+
+`LiveCapture.expectations` 由调用者按源名提供，内层必需键为 model、origin、path、stream（embedding 用 input_shape）、control、messages_digest；缺键直接测试配置错误，不自动从待测 payload 补齐。结构化预期片段放 control 的显式预期对象，输出路径由 write_live_round 单独接收；并发异构轮次使用各自 capture 实例，不共享可变“当前预期”。预期不调用生产 `_build_payload` 生成。实际请求 hooks 逐项比较，凭据不进 repr／序列化；可保留失败事实后由轮次出口 FAIL，不能改写实发请求“修正”它。
+
+取证 live 使用 `GatewayClient(...)` 全量注入。conftest 可复用 `client.py` 现有 `_build_limiter`／`_build_breaker`／`_build_selector`／`_build_structured` 等装配函数，但不新增生产注入口、不复制它们实现；自己创建的组件用 ExitStack／显式 finally 关闭，注入 GatewayClient 不会代关。工厂行为单独离线验证。未获得取证通道的工厂 live，异常一律保存后 FAIL。
+
+T5 按 `(session_id, parent_call_id) → AttemptEvidence.call_id → HttpEvidence` 保存快照；T6 使用最终 `LLMResponse.call_id` 调用 `capture.raw_identity(...)`，将返回值交给 `assess_model_identity(raw_identity=...)`，不可取本轮最后一条响应猜关联。查找必须精确匹配本轮且只有一条成功 HTTP 事件；重复／跨轮 call_id、多个候选响应是取证契约错误，报告后 FAIL，不降成外因未覆盖。未发 HTTP 或没有独立身份快照时返回 (False, None)。
+成功非流式原始 model 通过上述快照接口交付；成功 SSE 不加捕获器、不预读流。原始身份无从确认而公共结果缺失／不符时 FAIL；原始正确而结果丢失／改错也 FAIL。只要公共身份合格且请求合格，正常能力测试不要求新增成功 SSE 的原始副本。
+
+## 4. 任务与提交点
+
+### T0：基线、计划审查与文档回滚点
+
+- [x] 修改设计批准状态，新增本计划；父会话自审后前台 Codex 独立审，具体问题修正后方可执行 T1。计划无需再走人类门，不能把“已生成”当“已审”。
+- [x] 记录 `git status --short --branch`、`git log --oneline origin/main..HEAD`、实际 HEAD；确认源代码零差异，保存未跟踪文件清单，禁止暂存 `.pi/`。
+- [x] 执行基线：`make check`；`conda run -n PolyGateway pytest tests/unit/test_thinking.py tests/unit/test_providers.py tests/unit/test_client.py tests/unit/test_config.py tests/unit/test_openai_compat.py tests/unit/test_cache.py tests/unit/test_embedding.py tests/unit/test_ocr_client.py tests/unit/test_telemetry.py -q`。记录实际失败，不能先改期待绕过；本步骤预期现有非 slow 测试通过。
+- [x] 以 `research-wiki` 工具登记 design／plan 节点及 implements 边，现有同路径文档不可被 add_entity 模板覆盖；先读工具已有文件处理行为，再登记、重建索引、检查生成 diff。只在本计划 writer 移交后由父会话执行这些额外文件写入。
+- [x] 调用 commit skill，提交点 `docs: record approved thinking contracts and implementation plan`，形成生产修改前回滚点。
+
+### T1：AUTO 成员语义与默认 MiniMax wire
+
+**文件**：`thinking.py`、`providers.py`；`tests/unit/test_thinking.py`、`tests/unit/test_providers.py`，路径均按 §2。
+
+1. 先添加／替换 `test_auto_never_trips_phase5`，以已登记不含 AUTO 的空／非空 on_base 为反例；调用 resolve_thinking 的 error／nearest 都明确拒绝且不提示 nearest。先跑新测试，旧实现因未拒绝而红；再修改 `_settle_tier`、`_tier_unsupported`，避免 AUTO 进入 `EFFORT_ORDER.index`。
+2. 保留强度→纯开关 AUTO、等距弱侧、NONE 不自动映射、None 不表态、未知空／非空 wire 尽力警告。删除 default MiniMax 的 medium 并修正注释；先测试 M3 AUTO 拒绝、M3 medium payload、M2.5／M2.7 AUTO 空 payload 与 applied=AUTO。默认能力表成员不增删。
+3. 用 loguru sink 检查未知告警确实说明不保证生效，default transport 实例节流不改；不引入新日志通道，不输出 raw 密钥。按 structured-logging 明确这是既有 warning 与既有列的修正。
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_thinking.py tests/unit/test_providers.py -q`；新拒绝和 wire 回归先红后绿，其余保留行为通过。若旧下游形态测试依赖 M3 True，需要在 T3 明确改为已批准迁移样本，不能暗改能力表让它绿。
+
+- [x] 提交点：`fix: enforce registered auto reasoning capabilities`。
+
+### T2：纯 wire／raw 所有权校验
+
+**文件**：`src/polygateway/thinking.py`、`tests/unit/test_thinking.py`。实现 §3.1 两个签名；`resolve_thinking` 集中校验 wire，providers 不反向 import thinking。
+
+| 红绿组 | 最小反例／保留不变量 |
+| --- | --- |
+| 标准控制 | 六个顶层根＋output_config.effort；AUTO 空片段仍拒绝 raw high；NONE／糖／未知同测 |
+| 双来源 | 同值仍拒绝；分别传源与请求 raw 验证，被后层遮蔽也拒绝；不修改两个 Mapping |
+| 自定义 | on_base／off 根并集、effort_key 自定义字面键、点号不解释路径；on_base 偷带自己的键或标准强度值（含 None）拒绝 |
+| 嵌套 | 替换 thinking 整个根即拒绝；profile 不拥有 output_config 时仅 format 可过、effort 不可过；拥有根时 format 也不可覆写 |
+| 不误伤 | effort=None 时 raw 原样允许；temperature／seed／response_format 不属词表，合法普通采样保持；off-only 形态及当前方向未知语义保持 |
+
+新校验首次未实现导致的 import 错误不算行为红；可先在隔离基线把同输入经现有 payload 路径表现记录为“覆盖成功但本应拒绝”，或待 T3 在旧实现回放其失败断言，补齐语义红证据。纯函数自身还需逐例断言异常及未修改输入。
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_thinking.py -q`，每类目标反例有有效红绿，保留行为绿。
+
+- [x] 提交点：`fix: validate ownership of managed reasoning parameters`。
+
+### T3：接入工厂、请求入口和默认 transport
+
+**文件**：`src/polygateway/client.py`、`src/polygateway/transports/openai_compat.py`；`tests/unit/test_client.py`、`test_config.py`、`test_openai_compat.py`、`test_retry.py`。
+
+先在旧路径跑源 HIGH＋相同 raw HIGH、本次 AUTO＋raw HIGH 的行为反例，确认旧实现实际发出 raw 参数而未拒绝。再接入两守卫：工厂先求 effective_effort 并校验 source.extra_body；chat coerce 后调用 wire=None 的已知词表检查；transport 对当前 profile 和 effective_effort 分别检查 extra_body／overlay，再保持原浅 update 顺序。
+
+| 接缝 | 验收 |
+| --- | --- |
+| 工厂 | SourceConfig 仍能表达 raw-only；from_env／from_settings 对受管源拒绝发生在 limiter／HTTP client 创建之前；记录构建计数零，不以网络偶然没发代替 |
+| 请求前置 | 显式请求档与 overlay 已知键冲突，ValueError 且 handler／准入未触发；源级意图或自定义根留 transport 再查 |
+| 全量注入 | 真实 OpenAICompatTransport 翻译为 RequestRejectedError；MockTransport 记录零 HTTP，RetryMW 不换源不重试、limiter inflight=0、已有探针收尾路径正常 |
+| 参数保真 | raw-only 允许，applied=None；普通采样源＜请求＜结构化 overlay 的现状保留；显式档／nearest 成功 payload、TransportResult／LLMResponse applied 与真实成功遥测相符 |
+| 多源／并发 | 每次以选中源 profile 校验，不因另一个源清单不同提前判整个池死；共享 client 无“最后档”串线；错误不包含 raw 值 |
+
+工厂将来被请求覆盖不能救活一个已拒绝源，这是已批行为。不要为全量注入自定义 transport 添加 preflight 端口。已有 fixture 需要调整时，只将不再合法的受管＋raw 双来源改为显式单来源，新增拒绝反例保留迁移证明。
+
+**新增生产默认 HTTP factory 离线守卫**：现有 `tests/unit/test_openai_compat.py` 没有 auth／timeout／trust_env 构造断言，不能写作“保留”。新增 `TestDefaultClientFactory`，直接调用生产 `_default_client_factory(source)` 返回真实 AsyncClient，不使用 T5 的测试 factory，也不 mock 整个 AsyncClient。用两组不同假 api_key、非默认 timeout_s、trust_env=True／False 参数化；不发送网络，finally aclose。节点为 `test_authorization_uses_source_api_key`（检查 client.headers 及 build_request 生成的 Authorization）、`test_timeout_uses_source_timeout_for_all_phases`（connect/read/write/pool 全部等于输入 timeout_s）、`test_trust_env_uses_source_setting`（检查 client.trust_env）。在隔离副本逐个删除 Authorization 传入、遗漏 timeout 参数、遗漏 trust_env 参数／写死 True，指定节点必须因值不符红，再恢复通过；当前实现本来正确，以这些语义变异作为红证据，不改生产 factory 凑红。
+独立命令：`conda run -n PolyGateway pytest tests/unit/test_openai_compat.py::TestDefaultClientFactory -q`，原始实现绿、每个遗漏变异被对应断言杀死、恢复绿；这套测试与 T5 hooks 校验分别验证生产装配和测试取证两条路径。
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_client.py tests/unit/test_config.py tests/unit/test_openai_compat.py tests/unit/test_retry.py -q`，加 T1／T2 的测试一起跑；工厂／请求／全量注入拒绝均有旧实现红、新实现绿。
+
+- [x] 提交点：`fix: reject conflicting raw reasoning overrides before sending`。
+
+### T4：显式缓存迁移和四种遥测口径回归
+
+**文件**：`tests/unit/test_cache.py`、`tests/unit/test_client.py`、`tests/unit/test_telemetry.py`；不改生产 cache、指纹或 emitter。
+
+使用真实 InMemoryCache、GatewayClient、默认 transport＋MockTransport 构造两个客户端。旧语义 payload 可按 1.3.3 真实序列化形态预写（历史数据夹具，不需要在当前生产放回漏洞）；同版本 nearest→error 则运行真实客户端写入。
+
+| 场景 | 断言 |
+| --- | --- |
+| 旧 AUTO／raw 记录 | 旧身份可回放是已知风险；换全新 namespace 或 salt 后 miss，实际进入新拒绝，异常不缓存 |
+| nearest→error | 源不表态、请求 medium、模型 glm-5.3；nearest 写入后 error 同身份可命中；error 换身份后零 HTTP 拒绝，不添加 fallback 指纹 |
+| 能力表变化 | 新增 `TestExplicitCacheMigration::test_capability_change_requires_explicit_identity`：相同源配置、请求 AUTO 和 wire，两客户端注入同一测试模型的不同能力表（旧含 AUTO＋HIGH，新仅 HIGH），源级不表态以允许装配。旧客户端真实写入后新客户端同身份回放且无新 HTTP；换全新 namespace 或 salt（参数化）后 miss，进入新能力表并 RequestRejected、无新 HTTP、不写失败值。只用局部测试能力表，不修改 DEFAULT |
+| 自定义 wire 变化 | 新增 `TestExplicitCacheMigration::test_custom_wire_change_requires_explicit_identity`：相同源／模型／能力表及请求 HIGH，分别注入同名自定义 profile 的旧／新 effort_key（例如 depth_a／depth_b），on_base 均为空。旧客户端写缓存，新客户端同身份回放旧值且无新 HTTP；新 namespace 或 salt 后 miss，MockTransport 必须收到 depth_b=high 且无 depth_a，返回可区分的新结果，旧身份仍能回放旧值。profile 仅局部注入，不改源配置让现有指纹意外变化 |
+| 入口与范围 | 工厂默认 namespace、per-call 覆盖默认、构造全量注入、共享多源 scope、两个租户原前缀保留；只改默认无法覆盖 per-call，需专门反例 |
+| 并行／回滚 | 旧新身份可并行且不覆盖对方；回到旧身份确实重见旧值；未受影响调用 key 黄金值逐字不变 |
+| 四行口径 | 真实成功=applied、失败尝试=effective 意图、cache_hit／scope 终态=本次请求级；缓存不读取历史 applied 作本次遥测档 |
+
+该任务多数是已有正确行为的守卫，不人为改生产获得红：隔离变异遗漏 namespace／salt、将 cache_hit 遥测改读历史 applied，要求相应行为断言红，恢复后绿。T3 新拒绝路径旧实现红绿可复用，但不能只报它替代迁移维度证据。
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_cache.py tests/unit/test_client.py tests/unit/test_telemetry.py -q`。两项新增能力／wire 迁移节点均置于 `tests/unit/test_cache.py::TestExplicitCacheMigration`，单跑 `conda run -n PolyGateway pytest tests/unit/test_cache.py::TestExplicitCacheMigration -q`；分别在隔离副本去掉其 namespace／salt 隔离输入，必须因没有新拒绝／新 wire 而红，恢复后绿，不能只以 nearest→error 的测试代替这两类。两客户端的源指纹必须断言相等，生产指纹算法一字不改。
+
+- [x] 提交点：`test: pin explicit cache migration and reasoning row semantics`。
+
+### T5：有限测试归因和独立取证
+
+**文件**：新增 `tests/live_evidence.py`、`tests/e2e/conftest.py`、`tests/unit/test_live_evidence.py`。按 §3.2／3.3 实现；不读 .env 的模块可被日常单测安全 import。执行 structured-logging：记录内容按设计 §6，不另建库表。
+
+1. 纯分类默认 FAIL。仅一条完整 HTTP 错误、请求检查齐全、无别的 attempt 异常、404、完整无重复键 JSON 的 error.type 精确匹配、外抛 RequestRejectedError 且 status 一致，才 UNCOVERED；多次尝试／多 HTTP、不同 call_id、空检查元组、重复 JSON 键均 FAIL。
+2. hooks 不预读成功 SSE，不将 summary 当 JSON；response 引用等该次 transport 完成后检查 content 是否已缓冲。64 KiB 上限、0 字节、非对象 error、重复键、坏编码各有反例。薄委托器 finally 恢复上下文，零 HTTP 尝试也保存。
+3. 身份函数区分 raw 取证缺失和原始响应明确缺 model；增加 `test_raw_identity_snapshot_reaches_round_consumer`，用真实默认 transport＋MockTransport 非流式响应依次覆盖正确 model、缺失／null，以及 JSON 非对象／非法／重复键，断言 §3.3 accessor 的来源和区别；故意让公共响应丢 model 时原始快照仍保留正确串并判 FAIL。并发两逻辑轮次＋一次重试验证按 session／parent／成功 call_id 精确选择，不回放前次失败的身份；成功 SSE 快照未取证且公共身份异常时必须 FAIL。覆盖函数按 enabled／disabled／cannot_disable 命题判断，UNKNOWN 不假绿；预期 400 负向契约单独测。
+4. 用 MockTransport 驱动 request／response hooks：改错 model、Authorization、端点、SSE／JSON 解析→FAIL；成功 SSE 不被提前消费；原始 model 正确但公共字段错误→FAIL。交错并发及取消证明 context reset、凭据不泄露、资源释放；薄委托器不额外调用一次 HTTP。
+5. 安全报告每轮独立文件，采用 run UUID＋轮次与矩阵安全标识；只接受白名单 safe_fields，拒绝原始异常／HttpEvidence 对象直接序列化。第二轮失败仍可读第一轮；写入失败是 FAIL；最终汇总统计 PASS／FAIL／UNCOVERED 和缺轮，不能只数 pytest 退出码。
+
+对旧策略红证据：用合成记录隔离执行现有“整类 skip／正文子串／UNKNOWN 安静”判据，目标测试要求 FAIL／UNCOVERED，确认语义不符；恢复新纯函数后通过。新文件缺失造成 import error 不计红。
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_live_evidence.py -q`。安全测试使用假的唯一 sentinel 凭据／私有提示词，逐文件检查不出现 sentinel，不能拿真实密钥做输出搜索。
+
+- [x] 实现及离线证据完成：窄分类／hooks／独立身份／逐轮安全报告；与 T6 合并提交。
+
+### T6：迁移四个 live 文件并离线化装配断言
+
+**文件**：四个 `tests/e2e/test_*.py` 路径见 §2，`tests/e2e/conftest.py`、`tests/unit/test_live_evidence.py`、`tests/unit/test_client.py`、`tests/unit/test_config.py`。
+
+| 原接缝 | 改动与离线验收 |
+| --- | --- |
+| smoke／compat chat | 每轮 session_id＋parent_call_id，委托原参数，先报告再 skip／raise；仍验证流／非流、结构化 JSON／模型。断言异常也必须留报告，不只包 await 的异常 |
+| compat 平铺键 | 移到 test_config.py 的完整合成 env，删除逐源 TIMEOUT_S 才能验证 LLM_TIMEOUT 回落；不靠真实配置“恰好已有覆盖”过测。无 HTTP、无可达 Redis／PG，明确其仅是本库兼容契约 |
+| compat Protocol | 既有真实外部 Protocol 缺包时记录未覆盖；合成 runtime Protocol 和本库调用签名在 test_client.py 无 slow 执行，不能宣称缺失仓库原测试通过 |
+| embedding probe | 走同一薄 embed 委托和窄分类，所有路径 finally 关闭；model_not_found 不写成“网关不支持 embeddings”；timeout／trust_env 取已校验源配置，不用 30s 硬编码压紧生产预算 |
+| L1–L9 | M3 True 拒绝单独离线／本地断言，真实开启用显式 medium，保留未登记／未知 wire 场景；L8 装配拒绝只计本地契约，不算 live 能力 |
+| T10 | 预声明 NONE 可关闭／不可关闭／档位预期拒绝；每轮结束即留证。去掉“仅保留可用轮降低分母”、completion 长短提升 UNKNOWN 的成功逻辑；模型部分档未覆盖不可汇总全 PASS |
+
+保持原 `_MODEL_PROVIDER`／显式别名表，不新增 AUTO 成员。`_run_rounds`、`_probe_effort` 返回路径不许遗漏失败轮；默认基线也走同一证据出口。T10 临时能力表仅为探测绕过清单，不写回 DEFAULT；其控制字段预期由矩阵声明，不能调用被测 resolver 产生预期。
+
+既有 `_tier_settings` 将 stall 强制压到 60s，迁移时去掉该临时缩小值，沿已校验生产配置；不得因持续 429 慢而修改 #22 算法。保留既有轮次／并发设置；先收集矩阵和预计调用数，额外研究不自动展开。M2.5／M2.7 AUTO 复用 T10 现有登记档，M3 medium 流／非流复用对应原开启用例，不以新增多轮研究暗增预算。
+
+测试工厂替代仅改变取证装配，不能靠调用生产私有 `_client_factory` 的同一实现来证明鉴权构造正确；生产默认 factory 的头／timeout／trust_env 离线守卫由 T3 **新增** `TestDefaultClientFactory`，T6 验证时一并运行，不宣称旧源码已有覆盖。各能力轮次用 §3.3 的 `raw_identity(session_id=..., parent_call_id=..., call_id=resp.call_id)` 给身份函数提供独立快照，缺失来源不得猜测。live 无取证通道的失败按 FAIL，不为凑分类额外开生产接口。
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_live_evidence.py tests/unit/test_client.py tests/unit/test_config.py tests/unit/test_openai_compat.py::TestDefaultClientFactory -q`；`conda run -n PolyGateway pytest tests/e2e/ -m slow --collect-only -q`（只采集，不视作真实通过）。在离线注入旧整类 skip、丢第一轮、UNKNOWN→PASS、identity 丢失→skip 变异，分别红；新实现恢复绿。
+
+- [x] 实现及日常离线验证／90节点collect-only完成；未执行live，不代表能力覆盖通过。
+
+### T7：无推理路径真链路与四类变异
+
+**文件**：`tests/unit/test_embedding.py`、`tests/unit/test_ocr_client.py`、`tests/unit/test_telemetry.py`、`tests/unit/test_monkey_ocr.py`；生产不改。
+
+复用 `_embed_client`／`_client`／脚本 transport／内存 recorder，参数化 embed、recognize_text、parse_layout 与源 True／HIGH，两次尝试（Transient→成功）必须恰有 2 行、一错一成、所有 reasoning_effort None。再覆盖 RequestRejected 一行和耗尽非零失败行；不要求新增不存在的逻辑终态。SQL 锚点用真实 `SQLiteRecorder(tmp_path / "reasonless.sqlite", auto_migrate=True)`，三入口分别走 client→emitter→SQLite，查询总数／失败数／NULL 数，finally 同步 close 注入 recorder。
+
+chat 阳性走真实 RetryMW＋emitter：True 糖失败 auto、显式请求失败保留意图、nearest 成功为实际映射档。四行遥测继续沿 T4 口径。共享 recorder 并发用测试 session／parent 配对，attempt call_id 唯一且集合不相交。embedding 默认 transport 和 MonkeyOCR text／layout 真实 MockTransport 回包验证 wire 无推理键，不仅断言 emitter 的 False 实参。
+
+| 隔离变异 | 必须被哪些断言杀死 |
+| --- | --- |
+| `embedding.py::_emit` False→True | 误配 True／HIGH 的失败尝试 NULL 断言 |
+| `ocr.py::_emit` False→True | text 和 layout 各一个独立节点均因错误行非 NULL 红 |
+| `middleware/retry.py::_emit` True→False | chat 阳性实际档／请求档断言，不是签名 TypeError |
+| `middleware/telemetry.py::_attempt_effort` 去掉 applies 短路 | 无推理真实失败行断言；确认不是全空数据或假 recorder |
+
+工作方法：以 T7 当前提交建仓库外临时副本（仅 src／tests／必要工程文件，不复制 `.env`／reference／.pi），用 `PYTHONPATH=<副本>/src` 和副本 cwd 执行 conda pytest；先检查 `polygateway.__file__` 指向副本。逐个变异、跑指定节点记录 exit 1 和目标断言、恢复文件校验散列，再跑 exit 0。绝不在主工作区改 False 假装先红。
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_embedding.py tests/unit/test_ocr_client.py tests/unit/test_telemetry.py tests/unit/test_monkey_ocr.py tests/unit/test_retry.py -q`，再执行上表隔离变异；原实现绿、四类有效红、还原绿。
+
+- [x] 提交点：`test: guard reasoning-free telemetry through real client paths`。
+
+### T8：文档、日志登记与独立验证
+
+**文件**：§2 列出的用户文档／架构／旧设计／schema／metric／知识索引，以及验收 finding；不新增运行时字段。
+
+同步设计 M1–M9 到 README 可执行迁移节与 `.env.example` 注释，保留型号证据来源；CHANGELOG 未发布段点名 AUTO 新拒绝、未知尽力、raw 同值拒绝、显式缓存身份迁移、UNKNOWN／SKIP 限制。schema 既有 reasoning_effort “实际发出”总括修成四种行来源，不修改 DDL；metric 复用既有 call-telemetry-coverage，记录三个无推理入口错误行 NULL／chat 阳性为 100% 契约，真实覆盖基线留待首次实际运行，不能填伪百分比。
+
+由父会话前台派全新 verifier：只给批准设计、计划、分支 diff、验证命令，不给实现自评。至少覆盖正确性／回归和测试归因／范围两个角度；Critical／Important 清零。审查先核对实际路径与仓库语言，不接受不存在文件的结果。补丁回到单 writer，重跑受影响红绿及静态门。
+
+| 检查 | 命令／证据要求 |
+| --- | --- |
+| 静态与边界 | `make check`；`git diff --check`；`conda run -n PolyGateway python -m compileall -q src/polygateway tests/live_evidence.py tests/e2e/conftest.py` |
+| 日常全量 | `make test`，保存真实退出码／coverage ≥80%，不能只运行改动文件；连接依赖 skip 单列 |
+| LSP | 若会话已有 LSP diagnostics 工具，对四个生产变更文件和新增测试支持文件取诊断；本轮检查 conda 内 pyright／basedpyright 均未安装且工程无其配置，不安装新依赖或虚报 LSP 通过。可用时命令 `conda run -n PolyGateway pyright src/polygateway/thinking.py src/polygateway/providers.py src/polygateway/client.py src/polygateway/transports/openai_compat.py tests/live_evidence.py tests/e2e/conftest.py`，不可用明确记未执行，ruff／import-linter／compileall 是实际既有静态门，不冒称等价 LSP |
+| 真实采集清单 | `conda run -n PolyGateway pytest tests/ -m slow --collect-only -q`，先列必需节点、型号／模式／轮次／并发／所用配置身份（不含秘密） |
+| 真实执行 | `conda run --no-capture-output -n PolyGateway pytest tests/ -m slow -ra`；保持生产超时，检查每项报告而非仅 exit 0 |
+| 反回归 | 四类 #26 变异＋T4 缓存迁移＋T5/T6 假绿反例全部有独立失败断言与还原通过，finding 引用原始报告路径 |
+
+长跑用 tmux，`PYTHONUNBUFFERED=1`，命令 stdout／stderr 重定向到 `tests/outputs/134/`，原命令后立刻独立保存 `$?`；不得接 `tail` 管道改写退出码。父会话等待准确 tmux 完成信号／PID，不能 pgrep 完整命令自匹配。不把初次失败覆盖成重跑后的单一绿日志。
+
+- [ ] 提交点：`docs: document reasoning ownership and explicit cache migration`；必要修复各自按 commit skill 提交，不把 verifier 自动反馈当授权扩范围。
+
+### T9：发布准备、合并后复验与 1.3.4 发布
+
+仅在 T8 无未处理阻塞后执行。用户已授权所有本节动作，无需为 merge／push／上传再请示；发现 1.3.4 已存在不可覆盖，停下协调版本，不能私自跳到 1.4。
+
+| 顺序 | 精确动作与完成证据 |
+| --- | --- |
+| 文档先行 | 更新 README 安装约束与能力说明；CHANGELOG 定版为 1.3.4（实际日期），pyproject 和包 `__version__` 同步；本计划复选框只能按已得证据勾选 |
+| 发版提交 | 执行 commit skill，标题 `chore: prepare release 1.3.4`，先核对测试报告和 staged 无秘密；运行 `conda run -n PolyGateway pytest tests/unit/test_package.py -q`，不改变公共字段计数 |
+| 合并 | `git fetch origin`，确认远端未出现未审变更；`git switch main`，`git merge --no-ff feature/1.3.4-thinking-contracts`。保留已有两个本地提交，禁止 reset／force push |
+| 合并后门 | main 上重新 `make lint`、`make test`、`conda run --no-capture-output -n PolyGateway pytest tests/ -m slow -ra`；若 lint --fix 改代码，重新审 diff、提交并重跑，不把脏代码与 tag 分离 |
+| 推送与 tag | `git push origin main`；`git tag -a v1.3.4 -m "Release 1.3.4"`；`git push origin v1.3.4`，核对远端 tag 指向最终已验证提交 |
+| 构建 | 核实 cwd 后按 CLAUDE 清除旧 dist 产物；`conda run -n PolyGateway python -m build`；`conda run -n PolyGateway python -m twine check dist/*`；缺构建工具先报告环境缺项，不更改核心依赖 |
+| 上传 | 从既有 tea 配置安全取 token，仅放 TWINE_PASSWORD 环境变量；`conda run -n PolyGateway python -m twine upload --repository-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi dist/*`，TWINE_USERNAME 沿已有账号；不在 argv／日志输出 token，不把命令成功当最终发布完成 |
+| 下载检查 | `conda run -n PolyGateway pip download --no-deps --index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ polygateway==1.3.4 -d <临时目录>`；解包核对新守卫与 MiniMax wire、版本、README 元数据；从仓库外使用该环境 Python 将 wheel 安装到独立 target 并验证 import 来源及拒绝行为 |
+| 外部可见 | 建 Gitea v1.3.4 Release（正文来自定版 CHANGELOG）；调用 `POST /api/v1/packages/iomgaa/pypi/polygateway/-/link/PolyGateway`；查看 Release／registry 包页面正文、仓库链接、下载产物，逐项记录 URL 与实际结果 |
+
+测试不在 wheel 内，下载后以无网络小调用核对已安装 `resolve_thinking` 和冲突守卫；不要从工作树 src import 后宣称发布包通过。只在外部结果确认后评论／关闭 #21/#25/#26，正文引用各自验证与迁移边界，不能称所有渠道故障已自动识别。若上传成功但页面／下载校验失败，记录部分发布状态，不重发同版本不同字节。
+
+- [ ] 提交／发布点：main 的发布提交与 `v1.3.4` 对齐；Release 与 registry 外部验证全部成立。
+
+## 5. 阻塞矩阵：哪些可以执行，哪些不能冒充通过
+
+| 缺口 | 本库可完成 | 不可自行宣称／处置 |
+| --- | --- | --- |
+| 下游工作区缺失 | 本库完整合成 env、runtime Protocol、M1–M9 与显式缓存迁移回归 | GovDoc／CHS 实际配置未取证、Video-Tree 已退出迁移但历史兼容面仍可测；三者均不能虚构实测。提前向父会话登记缺口，发布前须拿到相关负责人脱敏配置与验证证据，或人类明确豁免缺失项；不阻止独立离线实现继续 |
+| M2 空 wire AUTO | 默认 wire 单测、实际既有 T10 型号档位复验 | 真实缺身份／无信号／不可达不能当已验证；需有效重测或人类具名豁免，不补回 medium 或无证据改表 |
+| M3 非流式 UNKNOWN | 可验证 payload、响应形态、UNKNOWN 不假绿 | 不把长度差当开启／关闭证明；必需能力单元无法满足时保留未覆盖并走人类决策，不新增临时“通过”阈值 |
+| 429／5xx／网络失败 | 完整证据保存，库回归用离线契约定位 | 本批归因默认 FAIL 是设计批准范围，不能为了 #25 关闭率改宽 skip；外部证据由人类决定发布豁免 |
+| 研究新增预算 | 原有 slow 套件按已有授权跑，已有配置保持 | 额外模型／轮次／对照实验需预算批准；不得将批准设计偷换成无限研究调用授权 |
+| 设计外漏洞 | 独立记录实际文件与反例，父会话核定是否阻塞 | 不顺手实施 #19／#22／#23／#24、新 schema 或新 deadline；无强制单源分支 |
+
+## 6. 自审与验收映射
+
+| 设计节／需求 | 任务 |
+| --- | --- |
+| §4.1／4.2 AUTO 与 MiniMax、未知尽力 | T1，T3 双入口，T6/T8 真实证据 |
+| §4.3／4.4 raw 同值／嵌套／自定义／时机 | T2、T3；无公共端口新增、无深合并 |
+| §5 D3 与 M1–M9 | T4、T8；未迁移风险显式保留，绝不补指纹 |
+| §6 归因／身份／UNKNOWN／负向命题 | T5、T6；完整请求证据、默认 FAIL、逐轮持久化 |
+| §7 无推理路径与变异 | T7；三入口真 client＋SQLite，四类隔离变异 |
+| §8 四种行口径与日志 | T1／T4／T7／T8；既有 schema／emitter，不新增数据面 |
+| §9／10 文档、下游与发布门 | T8／T9及阻塞矩阵；外部结果与测试缺口不冒充通过 |
+
+自审已核对：生产守卫所有消费者在 §3 定义；新增测试文件有确定路径；conftest 当前不存在故明确新建；默认工厂不支持 transport 注入故使用已批准全量注入而非偷扩 API；缓存不改指纹；无从公共 model_reported 倒推上游身份；所有命令均在 conda 环境；未执行的测试不写为已通过。
+计划审查由父会话组织，完成后直接实施，不新增人类计划审批门。执行中本文件任务勾选与 finding 保持实际状态一致；本次计划编写未运行 pytest、变异或真实模型调用。
+
+## 本轮实施证据
+
+T0–T4／T7 的命令、实际失败与修复、11 个隔离变异及 1241 项单测通过，见 `findings/2026-09-09-134-thinking-contracts-validation.md`。T5/T6 已续作：1357单元通过、8个隔离假绿变异exit1/还原0、e2e 90节点仅采集；T8文档同步完成。未执行live、集成、独立verifier和发布。具体节点及残余见同一finding续作节。
+
+### T5/T6续作决策记录
+
+父会话确认无已批准型号→400机器type白名单：不编造，缺机器证据400默认FAIL；精确预期拒绝契约离线守卫，具体live负向缺基线记录未验证。不可关闭命题完整合格轮次有OBSERVED支持本条件下未关闭，全ABSENT证伪，无OBSERVED但UNKNOWN未覆盖。T8复选框保持未勾选，因为独立verifier与全量/live证据门未执行；本轮仅其文档同步部分完成，禁止发布。
+
+T5/T6实现提交：`73008ad`。最终日常单元1357、受影响含factory331、make check、compileall、e2e collect-only90通过；完整T8/T9仍未执行。日志路径及8项红→还原绿详见同一finding。
+
+### 独立审查修复续作（d332287 后）
+
+已按 receiving-code-review 核验四项并仅修改测试及本计划／finding：结构化重问采用先验前缀／反馈角色与预算＋委托摘要的 wire 保真；未登记候选先资格再观测未覆盖；同一用例 run/model 关联所有子运行并保留计划／完成分母；落盘机器字段只准 model_not_found／omitted。没有生产／版本修改、slow执行或额外调用预算。
+
+新增18个离线节点，四项及首轮精确消息守卫均有目标断言先红→绿。最终129项取证单测、1375全单元、make check及e2e collect-only90通过；命令日志／退出码详见既有finding“独立审查四项修复”。修复后独立复审、集成与live尚未完成，**T8/T9仍不勾选，不放行发布**。原结构化重问“保守FAIL”说明已标为被本次修复替代，不能再当成可接受限制。

research-wiki/plans/2026-09-09-135-call-observability.md

@@ -0,0 +1,455 @@
+---
+type: plan
+node_id: plan:2026-09-09-135-call-observability
+title: "1.3.5 逻辑调用统计与结构化失败诊断实施计划"
+date: 2026-09-09
+---
+
+# 1.3.5 逻辑调用统计与结构化失败诊断实施计划
+
+> 设计：`research-wiki/designs/2026-09-09-135-call-observability-design.md`，**人类于 2026-09-09 正式批准**（§10 六项批准项全数获批）。
+> 计划审核门：Claude 自审 + **独立模型替代审查**（用户已同意以独立模型替代 Codex 那一道，结论仍须逐条核验后就地修订）；plan 无人类门，审毕直接执行。
+> 目标：把治理单位从"一次尝试"补齐到"一次逻辑调用"——四种响应带 `CallStats`，遥测补 10 列诊断/归因字段与 `terminal_failure` 行（issue #19、#23）。
+> 方案：设计方案 B——每调用一个显式传递的私有可变上下文 + 领域异常下沉到单一遥测出口；复用既有 Emitter / schema / 三条治理循环，不新增表、不新增依赖、不引入追踪平台。
+> 技术：Python 3.12+、asyncio、frozen dataclass、`inspect.signature`、pytest + FakeClock + MockTransport、临时 SQLite、真实 PG 沙箱、ruff、import-linter。
+> 基线 HEAD：`a81cc91`（分支 `feature/1.3.5-call-observability`，工作区仅 `CLAUDE.md` 既有 markdown 格式差异与未跟踪 `.pi/`，两者本计划一律不动、不暂存）。
+
+本计划不涉及 `reference/` 参考实现迁移（治理主循环、Lua 限流、熔断状态机、退避公式一字不改），**保真校验不适用**。不得变更：重试预算与退避、429 免预算与 stall 算法、取消结算、限流/熔断语义、推理能力表与档位解析、缓存 key 公式、`#22`/`#24` 的调度机制。
+
+## 1. 边界、授权与执行纪律
+
+| 项目 | 固定边界 |
+| --- | --- |
+| 唯一 writer | 一工作区一 writer；父会话负责前台委派与审核派发。用户已授权本轮无需逐步请示，1.3.X 合并/发布授权沿用；跨到 1.4、新公共决策或验证豁免须停下确认 |
+| 公共承诺 | 只做设计已批准的四项公共面变更：`CallStats` 导出、四响应新增字段、`TelemetryRecorder` 扩 10 参、`terminal_failure` 行；**不新增其它公共 API、不改既有字段名与位置** |
+| 依赖铁律 | `ports.py`/`types.py`/`errors.py` 保持最内层，`types.py` 不 import 任何实现层；`middleware/` 只依赖端口与内核；`transports/`、`telemetry/`、`backends/` 互不依赖（import-linter 执法） |
+| 取消 | `CancelledError` 永不吞没；终态写**取消优先、不 shield、不开后台任务**；快照冻结是同步动作，不 await |
+| 降级方向 | recorder 写失败仍只 warning；限流/熔断后端仍 fail-closed；装配期签名不符 → **当场报错**（不是 warning） |
+| 证据与秘密 | 不打印 `.env`、token、Authorization；不提交 `.pi/`、`tests/outputs/`、reference；命令输出只记安全路径、状态与退出码 |
+| 证据复用 | 已发布 1.3.4 的有效证据（能力矩阵、live 轮次、发布外部验证）**直接引用不重建**；本版**不补跑未变更的模型能力矩阵**，无需新增付费调用 |
+
+Skill 纪律：T0 已执行 `writing-plans`；T1–T3 行为变更执行 `test-driven-development`（先失败后通过的证据须落在本会话工具输出里）；T1 触及运行时数据落库，执行 `structured-logging`；每次提交执行 `commit`（英文祈使标题、无 AI 签名、显式路径暂存）；T4 前执行 `requesting-code-review` 与 `verification-before-completion`，收到意见执行 `receiving-code-review`；异常先 `systematic-debugging` 定根因。
+
+## 2. 文件职责与不变接缝
+
+| 动作 | 精确路径 | 职责 |
+| --- | --- | --- |
+| 修改 | `src/polygateway/types.py` | 新增 `CallStats`、私有 `_CallContext`、`CallOperation`/`EventKind` 词表；`ChatRequest` 追加内部上下文字段；四种响应追加 `call_stats` |
+| 修改 | `src/polygateway/__init__.py` | 导出 `CallStats`（`__all__` 保序插入）；版本号在 T4 统一 |
+| 修改 | `src/polygateway/ports.py` | `TelemetryRecorder.record_llm_call` 追加 10 个 keyword-only 无默认值参数（唯一签名事实源） |
+| 修改 | `src/polygateway/telemetry/schema.py` | `SQLITE_DDL` / `PG_DDL` / `SQLITE_BACKFILL` / `_PG_BACKFILL_DECLS` / `COLUMNS` **五处**同序同增 10 列，追加在物理列末尾（`PG_BACKFILL`、`_ALTER_BY_BACKEND`、`telemetry_schema_sql` 自动派生，不手改） |
+| 修改 | `src/polygateway/middleware/telemetry.py` | Emitter 构造期注入 `scope` + 装配闸；三个 emit 入口收 `operation` 与领域异常对象；诊断字段单一提取 helper；`event_kind`；终态出口 helper；`TelemetryMW` 只保留 cache_hit |
+| 修改 | `src/polygateway/middleware/structured.py` | 有界错误说明常量与拼装函数改为库内可复用（重问反馈与遥测说明同一口径，数值只一份） |
+| 修改 | `src/polygateway/middleware/retry.py` | transport 调用前登记一次尝试；`_emit` 传异常对象与 `operation="chat"` |
+| 修改 | `src/polygateway/middleware/cache.py` | `_serialize` 剔除 `call_stats`；`_rehydrate` 显式覆盖为 `None`（防历史 dict 冒充） |
+| 修改 | `src/polygateway/client.py` | 自存 `now`/`emitter`；`chat` 创建上下文、附加统计、领域失败与取消经单一终态出口 |
+| 修改 | `src/polygateway/embedding.py` | `embed` 拥有上下文（空输入 0 尝试 0 遥测行）；逐批传递；终态请求摘要按 §3.5 |
+| 修改 | `src/polygateway/ocr.py` | 上下文在 `image` 校验通过后创建；两公开方法各自给 `operation`；错误文本保留类名前缀（经出口的显式策略参数） |
+| 修改 | `src/polygateway/transports/openai_compat.py` | `_status_to_error` 增 keyword-only `operation`；三个调用点显式给值：`:512`（`embed` 非 200）传 `"embedding"`（修正历史误标）、`:527`（流式 chat）与 `:625`（非流式 chat）传 `"chat"`；`ocr_text`/`parse`/`download_result` 词表不动。**归属以本表为准**：设计 §5 把 `:527` 也叙述成 `embed()` 的分支，实测 `:527` 属 `_complete_stream`（流式 chat）、`embed` 只有 `:512` 一处；勿按设计行号把两条 chat 失败回退误标成 embedding |
+| 修改 | `tests/unit/test_types.py`、`tests/unit/test_ports.py` | `CallStats`/上下文纯行为、端口签名实测（含无默认值与 keyword-only） |
+| 修改 | `tests/unit/test_telemetry.py` | 列序/列数、三类行语义、诊断保真、装配闸、SQLite 新旧表、`_record_minimal` 字段字典 |
+| 修改 | `tests/unit/test_retry.py`、`test_client.py`、`test_cache.py`、`test_structured.py` | 计数/计时/缓存命中/结构化耗尽终态与历史 dict 防护 |
+| 修改 | `tests/unit/test_embedding.py`、`test_ocr_client.py`、`test_openai_compat.py`、`test_monkey_ocr.py` | 多批、空输入、双 HTTP 一次尝试、`exc.operation` 修正、200 失败行 |
+| 修改 | `tests/unit/test_pricing.py`、`tests/unit/test_usage_source_domain.py` | **仅 Emitter 调用点机械迁移**（`TelemetryEmitter(` 补 `scope=`、`emit_*` 补 `operation=`、`emit_terminal_failure` 去 `latency_ms` 改传 `stats`）；两文件的 `_MemoryRecorder` 是 `**fields` 形态，recorder 签名不动 |
+| 修改 | `tests/integration/test_postgres_telemetry.py` | PG auto 追加 / manual 缺列裁剪 / 旧行 NULL / 新旧进程混写（真实 `pg_sandbox`） |
+| 修改 | `README.md`、`CHANGELOG.md`、`.env.example`、`research-wiki/ARCHITECTURE.md`、`research-wiki/schemas/llm-calls.md`、`research-wiki/metrics/call-telemetry-coverage.md` | 字段数实测改写、cap 覆盖面澄清、SQL 迁移五项、终态行语义 |
+| 新建（验收时） | `research-wiki/findings/2026-09-09-135-call-observability-validation.md` | 红绿、变异、失败与豁免索引，≤300 行；原始输出留 `tests/outputs/135/` |
+
+**不改**：`errors.py`（异常类与分类逐字不动，不加可变字段）、`middleware/admission.py`、`middleware/ratelimit.py`、`middleware/breaker.py`、`sources.py`、`thinking.py`、`providers.py`、`telemetry/sqlite.py`、`telemetry/postgres.py`（两个 recorder 靠 `**fields` + `schema.COLUMNS` 自动吃到新列，逻辑零改动）、`transports/monkey_ocr.py`（双 HTTP 仍在同一 transport 调用内，不拆）。若实现时发现必须突破本清单，先说明设计依据与最小原因交父会话核定，不顺手改。
+
+## 3. 跨任务接口（可执行定义，禁止占位）
+
+### 3.1 统计内核（`types.py`）
+
+`types.py` 需新增 `import uuid`、`from collections.abc import Callable` 与 `from typing import Literal`（`Mapping`/`Any` 已在；全文现无 `Literal`）。
+
+**运行时求值约束（`types.py` 无 `from __future__ import annotations`，实测 :1-17）**：`Callable` 与 `Literal` 必须是**运行时 import**，不得放进 `TYPE_CHECKING`（`_CallContext.__init__` 的函数注解与 `CallOperation` 别名都在 def/赋值时求值）；且 `_CallContext` 必须**定义在 `ChatRequest`（:339）之前**，否则 `call_context: _CallContext | None` 的类注解在类创建时即 `NameError`。
+
+上下文是**每调用一个实例**的单任务对象：chat 重试、结构化重问、embedding 分批都在同一任务内串行推进，故计数无需锁；严禁提升为 client 实例属性。
+
+```python
+CallOperation = Literal["chat", "embed", "recognize_text", "parse_layout"]
+CALL_OPERATIONS: tuple[CallOperation, ...] = ("chat", "embed", "recognize_text", "parse_layout")
+EventKind = Literal["attempt", "cache_hit", "terminal_failure"]
+EVENT_KINDS: tuple[EventKind, ...] = ("attempt", "cache_hit", "terminal_failure")
+
+
+@dataclass(frozen=True)
+class CallStats:
+    """一次公开调用的统计快照;第三方合成响应的 `None` 表示未知,不得伪造 0。"""
+
+    logical_call_id: str
+    attempts: int
+    total_latency_ms: int
+
+
+class _CallContext:
+    """私有可变逻辑调用上下文:只持计数、单调时钟与终态去重位,不做 I/O。"""
+
+    __slots__ = ("logical_call_id", "_now", "_started", "_attempts", "_terminal_claimed")
+
+    def __init__(self, *, now: Callable[[], float]) -> None: ...
+
+    def register_attempt(self) -> None:
+        """transport 调用前登记一次尝试(含免预算 429 与端口本地拒绝)。"""
+
+    def snapshot(self) -> CallStats:
+        """同步冻结当前快照;绝不 await,可多次调用。"""
+
+    def claim_terminal(self) -> bool:
+        """首次 True、其后 False:保证每逻辑调用至多写一条终态行。"""
+```
+
+`ChatRequest` 追加（末尾，`dataclasses.replace` 保留同一引用；`StructuredMW` 的 replace 已核对不重建它）：
+
+```python
+    call_context: _CallContext | None = field(default=None, compare=False, repr=False)
+    """库内部逻辑调用上下文;`None` = 库内现场构造的请求,遥测 logical_call_id 落 NULL。"""
+```
+
+`LLMResponse`、`EmbeddingResponse`、`OcrTextResult`、`OcrLayoutResult` 各追加**末尾**字段：
+
+```python
+    call_stats: CallStats | None = None
+```
+
+### 3.2 遥测出口（`middleware/telemetry.py`）
+
+Emitter 是全库唯一 `record_llm_call` 调用点，本版新增的一切诊断/归因取值也只在这里定型。
+
+```python
+class TelemetryEmitter:
+    def __init__(
+        self,
+        recorder: TelemetryRecorder,
+        *,
+        scope: str,
+        pricing: PricingTable | None = None,
+        text_cap: int | None,
+    ) -> None:
+        """`scope` 构造期注入(三个 client 各一行),使三类行都带池名;不拿 source_name 顶替。
+
+        同处执行装配闸 `_assert_recorder_shape(recorder)`。
+        """
+
+    async def emit_attempt(
+        self,
+        *,
+        request: ChatRequest,
+        source: SourceConfig,
+        call_id: str,
+        latency_ms: int,
+        response: LLMResponse | None,
+        error: PolyGatewayError | str | None,
+        reasoning_applies: bool,
+        operation: CallOperation,
+        class_prefixed_error: bool = False,
+    ) -> None:
+        """`event_kind='attempt'`;失败异常对象在此提取 status/cause/body 四列。"""
+
+    async def emit_cache_hit(
+        self, *, request: ChatRequest, response: LLMResponse, operation: CallOperation
+    ) -> None:
+        """`event_kind='cache_hit'`;attempts/total_latency_ms 列恒 NULL。"""
+
+    async def emit_terminal_failure(
+        self,
+        *,
+        request: ChatRequest,
+        call_id: str,
+        error: PolyGatewayError | str,
+        operation: CallOperation,
+        stats: CallStats,
+        class_prefixed_error: bool = False,
+    ) -> None:
+        """`event_kind='terminal_failure'`;`latency_ms` 与 `total_latency_ms` 同取 `stats`。"""
+```
+
+`emit_terminal_failure` **不再收 `latency_ms`**（同一冻结快照供两列，避免双时钟微差）。诊断提取收敛为一个纯 helper，只读领域异常的既有属性，**不遍历任意对象、不猜正文**：
+
+```python
+@dataclass(frozen=True)
+class _ErrorFields:
+    """一行遥测的错误列;未知一律 None。"""
+
+    error: str | None
+    error_type: str | None
+    cause_type: str | None
+    http_status_code: int | None
+    error_body: str | None
+
+
+def _error_fields(
+    error: PolyGatewayError | str | None,
+    *,
+    event_kind: EventKind,
+    class_prefixed: bool,
+) -> _ErrorFields:
+    """三种入参形态的唯一定型点(设计 §5/§6)。"""
+```
+
+判定规则（测试逐条钉死）：
+
+| 入参 | error | error_type | cause_type / http_status_code / error_body |
+| --- | --- | --- | --- |
+| `None` | None | None | 全 None |
+| `str`（如既有 `"cancelled"`） | 原样 | None | 全 None（**不解析字符串猜诊断**） |
+| 领域异常，`event_kind='attempt'` | 见下 | `type(exc).__name__` | `type(exc.__cause__).__name__ or None` / `exc.status_code` / `summarize_body` 已产出的 `exc.body_text or None` |
+| 领域异常，`event_kind='terminal_failure'` | 见下 | `type(exc).__name__` | **全 None**（C1：不搬最后一次 attempt 的状态与正文冒充整池归因） |
+
+error 文本：`str(exc)` 为空退回 `type(exc).__name__`；`class_prefixed=True` 时前置 `"{类名}: "`（OCR 既有 metric 归组口径）；取消路径一律传字符串（attempt 行沿用既有 `"cancelled"`，终态行用同一明确取消文案），故 `error_type` 与其余三列均 NULL；`ResultInvalidError` 且为终态时并入有界结构化说明：
+
+```python
+def _structured_detail(exc: ResultInvalidError) -> str:
+    """结构化耗尽的有界说明:`repair=` 至多 200 字符 + `validation=` 至多 3 条×200 字符;
+    **不含 raw_text**(模型正文预算已由 attempt 行的 response 列承担),两段以 ` | ` 拼接。"""
+```
+
+复用 `structured.py` 的既有规则所有者，不复制数值：把 `_MAX_FEEDBACK_ERRORS`/`_MAX_ERROR_CHARS` 改名为 `MAX_FEEDBACK_ERRORS`/`MAX_ERROR_CHARS`，`_format_errors` 改名 `format_bounded_errors(errors: Sequence[str]) -> str`（行为逐字不变），`StructuredMW` 与 `_structured_detail` 两个消费者共同引用。
+
+装配闸（设计 §7，C3）：
+
+```python
+def _assert_recorder_shape(recorder: TelemetryRecorder) -> None:
+    """装配期一次 `signature.bind` 形状校验:不执行写入,只证明该形状能被接受。
+
+    参数名从 `TelemetryRecorder.record_llm_call` 的协议签名派生(不手抄第四份清单),
+    绑定用哨兵 `None`,不读真实请求数据。`**kwargs`(VAR_KEYWORD)自动通过;
+    `TypeError` → `ValueError` 装配期报错;不可 inspect(C 实现等)同样按配置错误报错。
+    """
+```
+
+终态唯一出口（公开边界 helper，三个 client 共用）：
+
+```python
+async def emit_terminal_once(
+    emitter: TelemetryEmitter | None,
+    *,
+    request: ChatRequest,
+    context: _CallContext,
+    error: PolyGatewayError | str,
+    operation: CallOperation,
+    class_prefixed_error: bool = False,
+) -> None:
+    """去重(claim_terminal)+ 同步冻结快照 + best effort 写入。
+
+    `emitter is None` 或已写过 → 直接返回;写入侧异常按既有降级只落 warning;
+    **`CancelledError` 原样传播**(取消优先,不 shield、不开后台任务)。
+    """
+```
+
+`TelemetryMW` 相应收缩：删除其 `except (GatewayUnavailableError, GovernanceBackendError, SourceNotConfiguredError)` 与 `except CancelledError` 两个终态分支（改由 `GatewayClient.chat` 的边界统一写，避免两处同时写），保留 `cache_hit` 记录并传 `operation="chat"`。
+
+### 3.3 `_record` 的 10 个新列取值（唯一定型点）
+
+| 列 | attempt | cache_hit | terminal_failure |
+| --- | --- | --- | --- |
+| `scope` | 构造期注入值 | 同 | 同 |
+| `operation` | 调用点给定的四值之一，**绝不读 `exc.operation`** | 同 | 同 |
+| `logical_call_id` | `request.call_context.logical_call_id`，上下文缺席 → NULL（不造 ID） | 同 | 同 |
+| `event_kind` | `'attempt'` | `'cache_hit'` | `'terminal_failure'` |
+| `http_status_code` / `cause_type` / `error_body` | 见 §3.2 表（成功行全 NULL，成功不统一填 200） | 全 NULL | 全 NULL |
+| `error_type` | 该行自身错误类名 | NULL | 自身类名（`AllSourcesExhausted` / `CircuitOpenError` / `ResultInvalidError` / …） |
+| `attempts` / `total_latency_ms` | NULL | NULL | `stats` 两字段 |
+
+其余 26 列口径逐字不变；终态行仍 `cost=None`、`usage_source='unavailable'`、token 0，不复制 attempt 的用量与费用。
+
+### 3.4 schema 与端口（`telemetry/schema.py`、`ports.py`）
+
+10 列按**同一顺序**追加进五处（`SQLITE_DDL`、`PG_DDL`、`SQLITE_BACKFILL`、`_PG_BACKFILL_DECLS`、`COLUMNS`），全部可空、无默认值，物理位置在现有末列 `reasoning_effort` 之后：
+
+| 顺序 | 列名 | SQLite | Postgres |
+| --- | --- | --- | --- |
+| 1 | `scope` | TEXT | TEXT |
+| 2 | `operation` | TEXT | TEXT |
+| 3 | `logical_call_id` | TEXT | TEXT |
+| 4 | `event_kind` | TEXT | TEXT |
+| 5 | `http_status_code` | INTEGER | INTEGER |
+| 6 | `error_type` | TEXT | TEXT |
+| 7 | `cause_type` | TEXT | TEXT |
+| 8 | `error_body` | TEXT | TEXT |
+| 9 | `attempts` | INTEGER | INTEGER |
+| 10 | `total_latency_ms` | INTEGER | INTEGER |
+
+`COLUMNS` 由 26 → 36，物理列（含 `created_at`）27 → 37。**不建索引、不改旧列、不回填旧行、不 ALTER 默认生产 PG**（manual 档仍裁剪写入）。`ports.py` 按同序追加 10 个 keyword-only 无默认值参数，docstring 更新为"36 字段冻结"，并说明 `error_body` 沿用 `summarize_body` 上限、不进 `PGW_TELEMETRY_TEXT_CAP` 覆盖面。
+
+### 3.5 三条链路的上下文所有权
+
+| 链路 | 创建点 | 传递 | 附加统计 | 终态 |
+| --- | --- | --- | --- | --- |
+| chat | `GatewayClient.chat`：overlay/维度/档位三项校验**之后**（校验异常保持原行为，在统计边界外） | 放进 `ChatRequest.call_context`，洋葱各层经 `replace` 保留同一引用；`RetryMW._attempt` 在 `transport.complete` 前 `register_attempt()`（**上下文为 `None` 时跳过**——库内现场构造的 `ChatRequest` 不得因此报错） | 返回前 `dataclasses.replace(response, call_stats=ctx.snapshot())`（含缓存命中路径与内联遥测耗时） | `except PolyGatewayError` / `except CancelledError` 各调 `emit_terminal_once`，随后原样 `raise`；非领域异常不捕、无终态 |
+| embed | `EmbeddingClient.embed`：`texts` 类型校验与**调用方维度校验**（`validate_caller_dimensions`）之后；`expected_dim` 校验在 `_attempt` 内，本就在统计边界内 | 显式参数传到 `_embed_batch` → `_attempt`；`_emit` 现场构造的 `ChatRequest` 带 `call_context=ctx`；`transport.embed` 前登记 | 合并结果 `replace(..., call_stats=ctx.snapshot())`；**空输入返回真实 `attempts=0` 统计且不写任何遥测行** | 同上，`operation="embed"`；终态 messages = `<embed texts=N batches=M>` 占位 + 第一批（至多 `batch_size` 条、每条 200 字符，与逐批行同款构造） |
+| OCR | `OcrClient._call`：`image` 的 `bytes`/非空校验**通过之后**（M1 例外） | `_call` 拥有上下文并返回 `tuple[_AttemptOutcome, CallStats]`，两个公开方法据此附加统计；`transport` 调用前登记（layout 的 POST+ZIP GET 计 **1** 次） | `OcrTextResult` / `OcrLayoutResult` 的 `call_stats` | `_call` 内 `except PolyGatewayError` / `except CancelledError` 调 `emit_terminal_once`，`operation` 由公开方法传入（`recognize_text` / `parse_layout`），`class_prefixed_error=True`；`no_sources` 的 `raise` 在循环之前，`try` 必须**包住该 raise**，否则无源终态行写不出 |
+
+`GatewayClient` 需自存 `self._now` 与 `self._emitter`（现未保存）；统计生效与否**不由 telemetry 是否启用决定**（`emitter is None` 时统计照常，仅无行可写）。
+
+## 4. 任务与提交点
+
+### T0：设计批准状态、计划与基线（本任务）
+
+- [x] 设计文档状态行改为"人类已批准（2026-09-09）"，新建本计划（≤600 行）。
+- [x] 记录基线：`git status --short --branch`、`git log --oneline -3`、HEAD `a81cc91`；确认源码零差异，`CLAUDE.md` 既有 markdown 差异与 `.pi/` 一律不动、不暂存。
+- [ ] 基线验证（由执行者在 T1 之前跑一次，作为"先失败"的对照底）：`make check`；`conda run -n PolyGateway pytest tests/unit -q` → 预期全绿。**基线计数以本会话实跑输出为准**（近期会话记录为 1385 项量级），不拿计划里的数字当期待值；实际失败照录，不改期待绕过。
+- [ ] 计划自审 + 独立模型审查（替代 Codex，用户已同意）；意见逐条核验后就地修订。
+- [ ] wiki 登记：`.claude/tools/research_wiki.py add_entity/add_edge/rebuild_index`（design ↔ plan `implements`），登记前先确认工具不覆盖同路径已有文档。
+- [ ] 提交点：`docs: record approved call observability design and plan`（生产改动前的回滚点）。
+
+### T1：统计内核与三条链路的逻辑边界（不动遥测列）
+
+**文件**：`types.py`、`__init__.py`、`client.py`、`embedding.py`、`ocr.py`、`middleware/retry.py`、`middleware/cache.py`；测试 `tests/unit/test_types.py`、`test_client.py`、`test_retry.py`、`test_cache.py`、`test_embedding.py`、`test_ocr_client.py`、`test_structured.py`。
+
+按 §3.1 与 §3.5 实现。先写测试并确认在旧实现上红（`AttributeError: 'LLMResponse' object has no attribute 'call_stats'` 不算行为红——先落一个"同一次调用的重试次数无处可读"的行为断言，再实现）。
+
+| 红绿组 | 必须证明 |
+| --- | --- |
+| 计数 | 一次成功=1；失败重试=实际尝试数；免预算 429 计入；多源拒绝（端口本地拒绝）计入；结构化重问计入同一上下文且不重置；embedding 三批=3；OCR layout 双 HTTP=1；缓存命中=0；空输入=0 |
+| 逻辑 ID | 重试/重问/分批共享同一 `logical_call_id`；同一 client 并发两次调用互不串（`asyncio.gather` 两路各自计数与 ID）；`parent_call_id` 语义不变 |
+| 计时（FakeClock） | 缓存 IO、退避 sleep、准入等待、重问、内联遥测收尾全部计入 `total_latency_ms`；毫秒/秒不混用（1.5s → 1500）；`emitter=None` 时统计仍正确。**替身构造要求**：假缓存后端的 `get`/`set` 与假 recorder 的 `record_llm_call` 内部**必须主动推进 FakeClock**，否则"缓存 IO/内联遥测计入总耗时"的断言会退化成恒等于 0 的空转绿 |
+| 缓存不毒化 | `_serialize` 输出无 `call_stats` 键；手写含 `"call_stats": {...}` 的历史条目命中后 `response.call_stats is None`（**dict 不得冒充 `CallStats`**）；缓存 key 逐字节不变（黄金值） |
+| 附加点 | 失败异常上**不附任何统计字段**（`hasattr(exc, "call_stats") is False`）；`CancelledError` 类型与语义不变；非领域异常原样传播 |
+| 空输入 | `embed([])` 返回 `attempts=0`、真实 `logical_call_id`，且注入的内存 recorder **零行** |
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_types.py tests/unit/test_client.py tests/unit/test_retry.py tests/unit/test_cache.py tests/unit/test_embedding.py tests/unit/test_ocr_client.py tests/unit/test_structured.py -q` → 目标断言先红后绿，其余保留行为绿；`make check`（含 import-linter：`types.py` 不得引入实现层 import）。
+
+- [ ] 提交点：`feat: track logical call statistics across governed calls`
+
+### T2：遥测 10 列、诊断保真、scope/operation 与装配闸
+
+**文件**：`telemetry/schema.py`、`ports.py`、`middleware/telemetry.py`、`middleware/structured.py`、`middleware/retry.py`、`transports/openai_compat.py`、三个 client 的 Emitter 构造行；测试 `tests/unit/test_telemetry.py`、`test_ports.py`、`test_openai_compat.py`、`test_monkey_ocr.py`、`test_structured.py`。
+
+按 §3.2–§3.4 实现（本任务只产出 attempt / cache_hit 两类行的新列，终态行留 T3）。先写测试确认旧实现红：现状下 `error` 列是被 `str()` 压平的自由文本、无 `scope`/`operation` 列、旧签名 recorder 只落 warning。
+
+| 红绿组 | 必须证明 |
+| --- | --- |
+| 列与 SQL | `len(COLUMNS) == 36`、物理列 37、五处列序一致（新建库与 ALTER 追加列序相同）；`insert_sql` 两端语句更新；`telemetry_schema_sql` 输出与库内 DDL 同源 |
+| 端口 | `inspect.signature` 实测 10 个新参存在、keyword-only、无默认值；docstring 字段数与实测一致 |
+| 诊断保真 | 中转把 529 改写成 503 → 记 503（**不猜回 529**）；直接 529 → 529；空 `str()` 的 Connect/Read/Write/PoolTimeout → error 落类名、`cause_type` 为对应 httpx 类名；`error_body` 为 `summarize_body` 摘要且不等于 `raw_text`；成功行五列 NULL（不填 200） |
+| operation | `embed` 非 200 → `exc.operation == "embedding"`（历史误标修正）；新列 `operation` 恒为四值之一，与 `exc.operation` 无关、不随异常变化；`monkey_ocr` 的 `success != true` 带 **200** 的失败行 → `http_status_code == 200`（该列不可作失败判据） |
+| scope | attempt 与 cache_hit 行都带 scope；model/provider/source 未选出时仍留原空值 |
+| 字符串入参 | 取消 attempt 的 `"cancelled"` 仍原样落 `error`，其余四列 NULL（**不解析字符串**） |
+| 装配闸 | 旧签名 recorder → 构造 `TelemetryEmitter`（即三个 client 装配）**抛错**而非 warning；`**kwargs` recorder 通过；不可 inspect 的对象 → 配置错误报错；参数名确由协议签名派生（改协议后闸自动跟随的断言） |
+| 有界说明 | `format_bounded_errors` 重命名后 `StructuredMW` 反馈文案逐字不变（黄金串）；常量只有一份定义 |
+
+**验证**：`conda run -n PolyGateway pytest tests/unit/test_telemetry.py tests/unit/test_ports.py tests/unit/test_openai_compat.py tests/unit/test_monkey_ocr.py tests/unit/test_structured.py -q`；`make check`。
+
+- [ ] 提交点：`feat: record scope, operation and failure diagnostics per row`
+
+### T3：终态行、取消口径与统一出口
+
+**文件**：`middleware/telemetry.py`（终态 helper 与 `TelemetryMW` 收缩）、`client.py`、`embedding.py`、`ocr.py`；测试 `tests/unit/test_telemetry.py`、`test_client.py`、`test_embedding.py`、`test_ocr_client.py`、`test_structured.py`、`test_retry.py`。
+
+按 §3.2 的 `emit_terminal_once` 与 §3.5 的三条链路实现。先写测试确认旧实现红：结构化耗尽当前**没有任何失败行**；embedding/OCR 的无源、准入拒绝、重试耗尽与尝试外取消同样无终态行。
+
+| 红绿组 | 必须证明 |
+| --- | --- |
+| 补漏 | chat 结构化耗尽、embedding/OCR 的 `no_sources`、准入拒绝、`retry_exhausted`、尝试外取消各恰有 **1** 条 `terminal_failure` |
+| 不变量 I3 | 领域失败每调用至多 1 条（recorder 写失败仅 warning，SQL 可见 ≤1）；重复调用出口不产生第二条（`claim_terminal`）；直接 `RequestRejectedError` / `ResultInvalidError` 现在**既有 attempt 错误行也有终态行**（400 密集负载错误行翻倍是已批准的下游可见变化） |
+| 非领域异常 | 编程错（如 `KeyError`）→ **0 条**终态行、原样传播、分类不被改写 |
+| 取消三路 | chat / embed / OCR 同策略尽力写一条（允许 0）；**终态写的 await 上被取消 → `CancelledError` 传播**（不 shield、无后台任务）；permit 与探针释放行为不变（`inflight == 0`） |
+| 归因 SQL | 设计 §5 那条 `WHERE logical_call_id = :lcid` 查询同时给出终态 reason 文案与逐源状态码/正文；终态行 `http_status_code`/`cause_type`/`error_body` 三列 NULL；结构化耗尽的终态 `error` 含有界 validation/repair 说明且**不含 `raw_text`** |
+| 行语义 | 三类行均带 scope；`event_kind` 可区分；`SUM(cost)` 不因终态行变化（终态 `cost IS NULL`、usage `unavailable`）；`AVG(latency_ms)` 按 `event_kind` 分组的断言；终态 `latency_ms == total_latency_ms`（同一快照） |
+| 快照时机 | 终态快照不含自身写入耗时（FakeClock：写入内推进时钟，列值不变）；成功响应快照含返回前已完成的内联遥测耗时 |
+| 摘要 | embedding 终态 messages 为占位 + 第一批截断文本，不含全量原输入；OCR 终态沿用 `<ocr:{kind} image_bytes=…>`，图像 bytes 不入库；OCR 终态 error 保留类名前缀 |
+
+**验证**：`conda run -n PolyGateway pytest tests/unit -q`（全量单测，含上述文件）；`make check`。
+
+- [ ] 提交点：`feat: emit one terminal failure row per logical call`
+
+### T4：旧测试机械核对、存储兼容、变异证据、文档与独立验证
+
+**文件**：下述机械核对清单 + `tests/integration/test_postgres_telemetry.py` + 文档清单 + 验收 finding。
+
+**一次机械核对（禁止分散反复修）**：本版真正的破坏面**不只是 recorder 签名，还有 Emitter 侧**（`TelemetryEmitter.__init__` 新增必填 `scope`、三个 `emit_*` 新增必填 `operation`、`emit_terminal_failure` 去 `latency_ms` 改收 `stats`），这些关键词不含 `record_llm_call`/`COLUMNS`。故全量清单用：
+
+```bash
+grep -rn "record_llm_call\|COLUMNS\|_EXPECTED_COLUMNS\|TelemetryEmitter(\|emit_attempt(\|emit_cache_hit(\|emit_terminal_failure(" tests/ --include=*.py
+```
+
+一轮改完再跑，不逐个文件试错。已核实的免改项：`tests/unit/test_backpressure.py:231` 的假 emitter 是 `emit_attempt(self, *args, **kwargs)`，兼容；`tests/integration/` 无 Emitter 构造点。已知点：
+
+| 位置 | 动作 |
+| --- | --- |
+| `tests/unit/test_ports.py:99` `_DummyRecorder` | 显式签名补齐 10 参（它是"新签名可实现"的活证据，不改成 `**kwargs`） |
+| `tests/unit/test_ports.py:264` `TestTelemetryRecorderSignature` | 新参进 `no default` / keyword-only 参数化 |
+| `tests/unit/test_telemetry.py:40` `_EXPECTED_COLUMNS`、:220/:321/:597/:639/:647/:686-698 计数与尾部断言 | 26→36、27→37、尾部 10 列、旧表 backfill 目标列数 |
+| `tests/unit/test_telemetry.py:108` `_record_minimal` | 字段字典补 10 键（默认 NULL 形态） |
+| `tests/integration/test_postgres_telemetry.py:100` 字段字典 | 同上（该函数返回值被逐列断言消费，改动须与 `COLUMNS` 同序） |
+| `test_client.py` / `test_embedding.py` / `test_ocr_client.py` / `test_openai_compat.py` / `test_pricing.py` / `test_cache.py` / `test_usage_source_domain.py` 的 `_MemoryRecorder` | 均为 `**fields` 形态，**recorder 签名无需改**；只需核对断言里的字段计数与新列期望 |
+| `tests/unit/test_pricing.py`、`tests/unit/test_usage_source_domain.py` 的 **Emitter 调用点** | **须改**：`TelemetryEmitter(` 补 `scope=`、`emit_attempt(`/`emit_cache_hit(` 补 `operation=`；`test_usage_source_domain.py:297` 的 `emit_terminal_failure(...)` 同时缺 `scope`/`operation`/`stats` 且多传 `latency_ms`，不改必 `TypeError`（recorder 形态兼容 ≠ emitter 调用点兼容） |
+
+**存储兼容**（真实 PG，复用 `tests/integration/conftest.py` 的 `pg_sandbox` / `pg_catalog_probe`，不新建沙箱设施；**不引用 `assert_no_leftovers`**——它是 `tests/integration/test_pg_sandbox.py:19` 的模块级 fixture，对 `test_postgres_telemetry.py` 不可见，上提它要改 §2 清单外的 `conftest.py`。本版不新增沙箱资源创建路径，残留风险与 1.3.4 逐字相同，由该文件既有用例覆盖，属可复用的既有证据）：
+
+- SQLite：新建库 37 列；旧表（1.3.4 形态 27 列）auto 档补齐 10 列且列序与新建库一致；manual 档不发 DDL、按现有列裁剪写入并发一条点名缺列的 warning；旧行新列为 NULL。
+- PG（验收取以下**四项**）：auto 追加 10 列；**manual 缺列裁剪**写入成功且不抛（`_trim_columns` 路径）；旧行新列为 NULL；新旧进程混写同一表（旧列集写入 + 新列集写入并存）。
+
+**变异证据**（仓库外临时副本 + `PYTHONPATH=<副本>/src`，先确认 `polygateway.__file__` 指向副本；逐个变异 → 跑指定节点记 exit 1 与被杀断言 → 恢复校验散列 → exit 0；**绝不在主工作区改生产代码凑红**）：
+
+| 变异 | 必须被杀死的断言 |
+| --- | --- |
+| `register_attempt()` 移到 transport 调用之后的 `except` 分支外/内错位 | 失败重试与 429 计数断言 |
+| `ChatRequest` 上下文字段改为 `replace` 时新建实例（模拟上下文复制） | 重问/分批共享同一 `logical_call_id` 的断言 |
+| `_rehydrate` 去掉 `call_stats=None` 覆盖 | 历史 dict 冒充 `CallStats` 的断言 |
+| Emitter 入口提前 `str(exc)` 压平 | `error_type`/`http_status_code`/`error_body` 保真断言 |
+| 终态行复制最后一次 attempt 的 token/cost | 费用聚合与终态 `cost IS NULL` 断言 |
+| 去掉 `claim_terminal` 去重 | 每失败调用至多一条终态的断言 |
+| 装配闸改为捕获 `TypeError` 后 warning | 旧签名 recorder 装配期报错的断言 |
+
+**文档同步（发布前必须同批；wiki 站点自 2026-08-02 下线，按 docs-convention §2 的下线期条款，承接方为 README / CHANGELOG / .env.example / ARCHITECTURE 四处）**：
+
+| 位置 | 改什么 |
+| --- | --- |
+| `README.md:23` | "必录 26 字段" → 实测值（`len(inspect.signature(TelemetryRecorder.record_llm_call).parameters) - 1`，预期 36），不凭记忆 |
+| `README.md:26/399/455`、`ARCHITECTURE.md:592`、`.env.example:109` | `PGW_TELEMETRY_TEXT_CAP` 覆盖面仍是四处；明确 `error_body` 沿用 `summarize_body` 上限、`error` 的新增结构化说明另有独立限长，**二者都不在 cap 覆盖内** |
+| `README.md` 能力表 + 新增小节 | 四响应的 `call_stats` 读法；设计 §8 的 SQL 迁移**五项**（失败行数改判据、`error IS NOT NULL` 不再是判据、`AVG(latency_ms)` 须按 `event_kind` 分组、费用口径不变、失败行可能带 200） |
+| `ARCHITECTURE.md:565` 必录字段清单 + §7.8 补列一节 | 追加 10 列语义、`event_kind` 三态、终态行不变量 I3/I4、`operation` 与 `exc.operation` 是两个语义 |
+| `CHANGELOG.md` 未发布段 | 公共面四项 + 下游动作清单（点名"计失败调用改 `WHERE event_kind = 'terminal_failure'`"与自定义 recorder 的装配期报错） |
+| `research-wiki/schemas/llm-calls.md`、`metrics/call-telemetry-coverage.md` | 复用既有实体登记新列与三类行口径；真实覆盖基线待首次运行填，不写伪百分比 |
+
+**验收命令与证据**：
+
+| 检查 | 命令 / 要求 |
+| --- | --- |
+| 静态 | `make check`；`git diff --check`；`conda run -n PolyGateway python -m compileall -q src/polygateway` |
+| 日常全量 | `make test`（真实退出码、coverage ≥80%，连接依赖 skip 单列） |
+| 集成 | `conda run -n PolyGateway pytest tests/integration/test_postgres_telemetry.py tests/integration/test_governance_stack.py -q` |
+| 契约 | `conda run -n PolyGateway pytest tests/contracts -q`（限流契约随实现一起交付的既有套件） |
+| 变异 | 上表七项逐条 exit 1 → 还原 exit 0，日志留 `tests/outputs/135/` |
+| 独立验证 | 由**父会话前台派全新上下文 verifier**：只给批准设计、本计划、分支 diff 与命令，不给实现自评；至少覆盖"正确性/回归"与"下游可见变化/范围"两角度，Critical/Important 清零 |
+| slow | `pytest -m slow` 属发布清单第 4 步（CLAUDE §4.4.1），在合并 main 之后统一跑；**本版不新增 live 轮次、不补跑未变更的模型能力矩阵**，1.3.4 已有有效证据直接引用 |
+
+长跑用 tmux，`PYTHONUNBUFFERED=1`，输出重定向到 `tests/outputs/135/`，命令后**不得接管道**（退出码失真），完成判定用 `wait`/PID 轮询，不用会自匹配的 `pgrep -f`。
+
+- [ ] 提交点：`docs: document logical call telemetry and migration impact`（机械核对与存储兼容若需单独回滚点，可先提 `test: align telemetry fixtures with the 36-field recorder`，仍在 5 个提交内）
+
+## 5. 测试矩阵 → 任务映射（设计 §9 逐族落位）
+
+| 设计测试族 | 任务 |
+| --- | --- |
+| logical 计数（含空输入 0 尝试 0 行） | T1 |
+| 计时（缓存/退避/准入/重问/收尾、关 recorder） | T1（快照时机的终态部分在 T3） |
+| 失败与取消（三路同策略、终态 await 取消传播、非领域异常 0 行） | T3 |
+| 保真诊断（529/503、空超时文案、`exc.operation`、新列四值） | T2 |
+| 归因 SQL（终态 reason + 逐源现场、结构化说明无 `raw_text`） | T3 |
+| 行语义（三类行 scope、至多一条终态、费用不重复、`AVG` 分组） | T2（前两项）+ T3 |
+| 装配闸（旧签名报错、`**kwargs` 通过、不可 inspect） | T2 |
+| 存储兼容（SQLite 新旧表、PG manual/auto、旧行 NULL、混写） | T4 |
+| 变异（计数位置、上下文复制、缓存回放、提前压平、终态双计费用） | T4 |
+
+**共享测试设施一律复用，不新建**：`tests/contracts/conftest.py:26` 与 `tests/unit/test_ocr_client.py:344` 的 `FakeClock`（注入 `now`/`sleep`，确定性计时）；各测试文件既有的 `_MemoryRecorder`（`**fields`）与脚本化 MockTransport；`tmp_path` + 真实 `SQLiteRecorder(auto_migrate=...)`；`tests/integration/conftest.py` 的 PG 沙箱三件套。真实 LLM 输出如产生，按 CLAUDE §4.6 落 `tests/outputs/<module>/`。
+
+## 6. 阻塞矩阵与发布交接
+
+| 情形 | 本库可完成 | 不可自行宣称/处置 |
+| --- | --- | --- |
+| 无 PG 可用 | 单测与 SQLite 全部覆盖；PG 用例 skip 并单列 | 不得把 skip 记作通过；发布前须补跑或取人类具名豁免 |
+| 下游自定义 recorder 未知 | 装配闸 + 迁移文档 + `**kwargs` 兼容路径 | 不能声称"后端完全不受影响"：其 schema、INSERT 字段与契约测试仍须同步 |
+| 设计外漏洞 | 独立记录实际文件与反例，交父会话核定 | 不顺手实施 #20 之外的 issue、不新增表/端口/deadline/hedging |
+| 发布 | 门全绿后按 CLAUDE §4.4.1 逐步执行（文档先行 → CHANGELOG 定版 → 双处版本号 → 合并 main → `make lint`/`make test`/`pytest -m slow` → tag → 构建 → 上传 → 下载验证 → Release + 挂仓库 + 页面核对） | 本计划**不复制**该清单，也不预先勾选任何发布步骤；只 bump 版本号不叫发布 |
+
+## 7. 自审
+
+- 设计每节可指到任务：§3→T1、§4→T1、§5→T2/T3、§6→T3、§7→T2、§8→T4、§9→§5 映射表、§10 六项批准项全部落在 T1–T3 的公共面改动内。
+- 无占位符与待定项：跨任务消费的类型（`CallStats`、`_CallContext`、`_ErrorFields`）、四个 emit 入口、两个 helper（`_assert_recorder_shape`、`emit_terminal_once`）、10 列取值表、10 列 DDL 类型均已写出可执行定义；被引用的 `PolyGatewayError`、`ResultInvalidError`、`summarize_body`、`format_bounded_errors`、`FakeClock`、`pg_sandbox` 全部指向既有实现或本计划已定义项。
+- 一致性核对：`emit_terminal_failure` 去掉 `latency_ms` 后，唯一调用者是 `emit_terminal_once`；`TelemetryMW` 的终态分支删除后 chat 终态只剩客户端边界一处；`operation` 只由调用点给定，链路上无任何位置读 `exc.operation`。
+- 未采纳项（异常上挂可变统计、终态搬运最后一次 attempt 的状态与正文、成功侧汇总行）理由在设计正文，本计划不复活。
+- 本计划编写过程**未运行 pytest、未做变异、未调用任何模型、未提交**；T0 基线验证与其后各任务的红绿证据由执行者在自己的会话内出示。

research-wiki/plans/reasoning-effort.md

@@ -0,0 +1,15 @@
+---
+type: plan
+node_id: plan:reasoning-effort
+title: "实现计划: 推理档位一等化"
+date: 2026-09-05
+---
+
+# 实现计划: 推理档位一等化
+
+正文: `2026-09-04-reasoning-effort.md`(378 行,10 任务)。实现 `design:reasoning-effort`。
+
+- **拆分逻辑**: T1(`Effort` 词汇 + 能力表)与 T2(`ThinkingWire` + 8 段 provider 表)可并行 → T3(五道关卡 + nearest 映射)→ T4(源级 env 入口)→ T5(请求级入口与优先级)→ T6(缓存 key 两处)/T7(遥测第 26 列)→ T8(transport 接线与告警节流)→ T9(CHANGELOG/wiki/1.4.0)→ T10(经 new-api 逐模型实测,标 `slow`)。
+- **T10 单列的理由**: 人类定「能力表数据统一自己经 new-api 实测」。T1 落的是文档推定值(四方交叉: 官方文档/OpenRouter/cherry-studio/LiteLLM),不实测则整张表都是假设——LiteLLM 里同一个 kimi-k3 在 `moonshot/` 下三档、`perplexity/` 下六档,中转改档位有第三方证据。
+- **执行方式**: 直接按计划实现,**不派** `subagent-driven-development`——10 个任务共享 `Effort`/`ThinkingCapability`/`ThinkingWire` 三个类型,独立上下文的 subagent 容易在签名上分叉。
+- **保真校验**: 不适用(`thinking.py` 系库自研,非 `reference/` 移植蓝本;且三项目当前不在工作区)。

research-wiki/schemas/llm-calls.md

@@ -1,12 +1,11 @@
 ---
 type: schema
 node_id: schema:llm-calls
-title: "表结构: llm_calls(遥测 25 字段)"
+title: "表结构: llm_calls(遥测 36 字段)"
 date: 2026-07-20
 ---
 
-# 表结构: llm_calls(遥测 25 字段)
+# 表结构: llm_calls(遥测 36 字段)
-
 
 ## 列定义(冻结,M1 设计 §4.4 / ARCH §7.8)
 
@@ -31,6 +30,38 @@ date: 2026-07-20
 | tenant_id | TEXT NOT NULL DEFAULT '' | 调用方租户(2026-08-17,issue #11);**缺省落哨兵空串而非 NULL**——PG 的 RLS `USING` 对返回 NULL 的行一律隐藏且不报错,NULL 的租户不是「未归属」而是对所有人永久不可见 |
 | meta | TEXT / JSONB NOT NULL DEFAULT '' / '{}' | 调用方自定义维度(同批,≤16 个 KV);SQLite 存 canonical JSON 串,PG 存 JSONB |
 | thinking_observation | TEXT | 本次推理是否真的发生的三态裁定(2026-08-25,issue #16/#17);`observed` / `absent` / `unknown`。见下方口径 |
+| reasoning_effort | TEXT | 按四种行来源记录的推理意图／实际编码档位(2026-09-09 澄清,issue #20/#26);八档 `Effort` 字面量之一,NULL = 调用方未表态(与 `none`「明确要求不推理」不可混同)。见下方口径 |
+| scope | TEXT | 池名(2026-09-09,issue #19/#23);Emitter 构造期注入,三类行都带,**不拿 `source_name` 顶替** |
+| operation | TEXT | `chat` / `embed` / `recognize_text` / `parse_layout`,由调用点给定;与 `PolyGatewayError.operation` 是两个语义,链路上不得读后者填本列 |
+| logical_call_id | TEXT | 一次逻辑调用一个 ID(重试／换源／重问／分批共享);上下文缺席落 NULL,**不造 ID** |
+| event_kind | TEXT | 三态 `attempt` / `cache_hit` / `terminal_failure`——三类行的唯一机械判据。见下方口径 |
+| http_status_code | INTEGER | 失败 attempt 行的实收状态码(中转改写过就记改写后的,**不猜回原值**);成功行与终态行恒 NULL,且 200 也可能是失败行(MonkeyOCR `success != true`) |
+| error_type | TEXT | 该行自身错误的类名;取消路径传字符串故为 NULL |
+| cause_type | TEXT | `__cause__` 的类名(如 `ReadTimeout`)——httpx 超时类的 `str()` 为空,只靠 error 列分不出是哪种超时;仅失败 attempt 行非空 |
+| error_body | TEXT | 网关响应正文摘要(`summarize_body` 上限,**不在 `PGW_TELEMETRY_TEXT_CAP` 覆盖面内**);仅失败 attempt 行非空 |
+| attempts | INTEGER | 该逻辑调用真实打出去的尝试次数(免预算 429 也计);**只属终态行** |
+| total_latency_ms | INTEGER | 该逻辑调用的总墙钟(含缓存 IO、退避、准入等待、重问);**只属终态行**,与该行 `latency_ms` 同取一份冻结快照 |
+
+## 三类行与失败归因口径(2026-09-09,issue #19/#23)
+
+遥测行不再只有"一次尝试"一种。`event_kind` 三态同时决定其余列的取值面:
+
+| event_kind | 什么时候写 | 列取值 |
+| --- | --- | --- |
+| `attempt` | 每次真实尝试(含失败与取消) | 失败时诊断四列可非空;`attempts`/`total_latency_ms` NULL |
+| `cache_hit` | 缓存命中 | 诊断四列与快照两列全 NULL |
+| `terminal_failure` | 每次**领域失败**的整池终态,每逻辑调用至多一条 | `attempts`/`total_latency_ms` 非空;`http_status_code`/`cause_type`/`error_body` 恒 NULL;`cost` NULL、`usage_source='unavailable'`、token 0 |
+
+两条不变量: 每次领域失败至多一条终态行(I3,`claim_terminal()` 去重);非领域异常(编程错)**零条**终态行、原样传播(I4)。
+
+**终态行三列恒 NULL 是红线**: 把最后一次 attempt 的状态码与正文搬上来,等于拿最后一个源冒充整池归因。逐源现场由同一 `logical_call_id` 的 attempt 行给出:
+
+```sql
+SELECT event_kind, source_name, http_status_code, error_type, cause_type, error, error_body
+FROM llm_calls WHERE logical_call_id = :lcid ORDER BY created_at;
+```
+
+下游口径迁移四条: ① 计失败调用改 `WHERE event_kind = 'terminal_failure'`;② `error IS NOT NULL` 不再是失败调用判据(跨两类行);③ `AVG(latency_ms)` 须按 `event_kind` 分组(终态行是整个逻辑调用的总耗时);④ 费用口径不变(终态行 cost 恒 NULL)。
 
 ## usage/成本口径(2026-07-30,est_tokens 解耦)
 
@@ -104,6 +135,35 @@ ORDER BY model, calls DESC;
 
 三条限定各有理由: `cache_hit = false` 与 `cost`/`cached_prompt_tokens` 同源——缓存命中行原样回放历史观测值,计入即重复计数;`error IS NULL` 排除失败尝试与终态失败行,那些行的本列恒为 `unknown`(无响应可裁定,默认值本身不撒谎),混进来会把「观测不到」的占比整体抬高;时间窗是为了让**变化**可见——某模型的 `unknown` 占比从 0 跳到 100%,正是它停报推理信号的那一天。补列之前写入的历史行本列为 NULL,与 `unknown` 是两回事(前者是那时还没有这一列),跨版本对比须显式区分。
 
+## 推理档位口径(2026-09-04,issue #20)
+
+`reasoning_effort` 的来源取决于行类型，不能总括为「实际发出」——补列之前,25 列里没有任何一列答得出,于是「不同档位是不是真有用」在数据侧无从分组。NULL 有两个来源(调用方未表态 / 档位名读不懂),两者都**不可**折叠进 `none`:`none` 是一次「要求不推理」的表态。
+
+三个 emit 入口的取值同样各自定死,与 `sampling` 同构:
+
+| 入口 | 有生效源? | 记什么 |
+| --- | --- | --- |
+| `emit_attempt`(成功) | 有 | `response.applied_effort`——transport 裁定的**实发档** |
+| `emit_attempt`(失败) | 有 | `effective_effort(请求级 > 源级 > enable_thinking)` 的**请求档** |
+| `emit_cache_hit` | 无 | 本次 `request.reasoning_effort`，不取历史 applied、不推源级 |
+| `emit_terminal_failure` | 无 | 本次 `request.reasoning_effort`，可能尚未选源 |
+
+真实成功尝试必须读实际编码档而非重算（分析须同时排除 cache_hit 和 error；未知 AUTO 仅尽力，不证明上游推理，raw-only=NULL）: 源上开了 `EFFORT_FALLBACK=nearest` 时请求 `medium` 而模型只有 low/high/max,实发的是 `low`,重算会把整行挂在一个从未发出过的档下。失败尝试没有响应,实发档无从得知,故退回请求档——于是开了映射的源上**成功行与失败行不是同一把尺子**,跨 `error IS NULL` 混合统计前必须显式分开。仍然记而不留空,是因为档位错误(`resolve_thinking` 的 Phase 2/4/5)根本没发 HTTP 就被拒,这类行记的正是**被拒绝的那一档**,而「哪一档配错了」正是排障要的信号。
+
+OCR / embedding 路径的该列**恒为 NULL**(`emit_attempt(reasoning_applies=False)`),理由与 `sampling` 逐字相同: 两条路径的 payload 不带推理参数,源上即便误配了 `ENABLE_THINKING`,记一个档也是记录一个从未发出的参数。
+
+按档位看推理产出,即压测「高档是不是真的多想」的基本查询:
+
+```sql
+SELECT model, reasoning_effort,
+       count(*) AS calls,
+       round(avg(reasoning_tokens)) AS avg_reasoning_tokens
+FROM llm_calls
+WHERE cache_hit = false AND error IS NULL AND reasoning_effort IS NOT NULL
+GROUP BY model, reasoning_effort
+ORDER BY model, calls DESC;
+```
+
 ## 埋点位置(单一 helper 铁律)
 
 - `middleware/telemetry.py::TelemetryEmitter` 是全库**唯一** `record_llm_call` 调用点;
@@ -113,3 +173,7 @@ ORDER BY model, calls DESC;
 ## 评估基线
 
 首版无历史基线,标"待首次运行后建立";验收断言: 单测覆盖成功/失败/缓存命中/取消四路径各产生恰一行;并发 50 协程写全落库。
+
+## 1.3.4 测试侧证据（不新增 schema）
+
+`tests/live_evidence.py`／e2e conftest 只在内存保存完整错误体与独立非流式身份，逐轮 Markdown 白名单输出到 `tests/outputs/134/live/`；凭据、Authorization、提示词、原始异常／响应均不落报告。生产数据仍经 TelemetryEmitter。评估复用 `metric:call-telemetry-coverage`，实际 live 覆盖基线待首次执行。

src/polygateway/__init__.py

@@ -22,16 +22,25 @@ from polygateway.errors import (
 )
 from polygateway.ocr import OcrClient
 from polygateway.pricing import ModelPrice, PricingTable
-from polygateway.providers import DEFAULT_PROFILES, ProviderProfile, register_provider
+from polygateway.providers import (
+    DEFAULT_PROFILES,
+    ProviderProfile,
+    ThinkingWire,
+    register_provider,
+)
 from polygateway.telemetry.schema import telemetry_schema_sql
 from polygateway.thinking import (
     ThinkingCapability,
+    ThinkingResolution,
     ThinkingUnsupportedError,
     get_capability,
     register_capability,
     resolve_thinking,
 )
 from polygateway.types import (
+    EFFORT_ORDER,
+    CallStats,
+    Effort,
     EmbeddingResponse,
     LLMResponse,
     OcrLayoutElement,
@@ -42,11 +51,14 @@ from polygateway.types import (
     ThinkingObservation,
 )
 
-__version__ = "1.3.1"
+__version__ = "1.3.5"
 
 __all__ = [
     "DEFAULT_PROFILES",
+    "EFFORT_ORDER",
+    "Effort",
     "AllSourcesExhausted",
+    "CallStats",
     "CircuitOpenError",
     "EmbeddingClient",
     "EmbeddingResponse",
@@ -73,7 +85,9 @@ __all__ = [
     "TelemetryStatus",
     "ThinkingCapability",
     "ThinkingObservation",
+    "ThinkingResolution",
     "ThinkingUnsupportedError",
+    "ThinkingWire",
     "TransientError",
     "__version__",
     "gather_bounded",

src/polygateway/client.py

@@ -9,6 +9,7 @@
 from __future__ import annotations
 
 import asyncio
+import dataclasses
 import hashlib
 import json
 import random
@@ -19,11 +20,12 @@ from polygateway.backends.memory.breaker import InMemoryGate
 from polygateway.backends.memory.cache import InMemoryCache
 from polygateway.backends.memory.limiter import InMemoryLimiter
 from polygateway.config import GatewaySettings
+from polygateway.errors import PolyGatewayError
 from polygateway.middleware.base import compose
 from polygateway.middleware.cache import CacheMW
 from polygateway.middleware.retry import RetryMW
 from polygateway.middleware.structured import StructuredMW
-from polygateway.middleware.telemetry import TelemetryEmitter, TelemetryMW
+from polygateway.middleware.telemetry import TelemetryEmitter, TelemetryMW, emit_terminal_once
 from polygateway.ports import TelemetryStatusProvider
 from polygateway.pricing import PricingTable
 from polygateway.providers import get_provider
@@ -34,12 +36,20 @@ from polygateway.sources import (
     RoundRobinSelector,
     SourceCooldownMemo,
 )
-from polygateway.thinking import get_capability, resolve_thinking
+from polygateway.thinking import (
+    effective_effort,
+    get_capability,
+    resolve_thinking,
+    validate_thinking_raw,
+)
 from polygateway.transports.openai_compat import OpenAICompatTransport
 from polygateway.types import (
     ChatRequest,
+    Effort,
     LLMResponse,
     TelemetryStatus,
+    _CallContext,
+    coerce_effort,
     validate_caller_dimensions,
     validate_request_overlay,
 )
@@ -80,23 +90,44 @@ def _guard_thinking(
     就带着指路信息炸掉。`get_provider` 现在就是同一形态的双点调用。
     """
     for source, profile in zip(sources, profiles, strict=True):
+        effort = effective_effort(
+            request_effort=None,
+            source_effort=source.reasoning_effort,
+            enable_thinking=source.enable_thinking,
+        )
         resolve_thinking(
             profile,
             get_capability(source.model, table=capabilities),
-            source.enable_thinking,
+            effort,
             model=source.model,
+            # 与 transport 用同一个 fallback,否则配了 nearest 的源会在装配期就被
+            # 判死,而它在运行期本来是能映射到最近档跑起来的
+            fallback=source.effort_fallback,
+        )
+        validate_thinking_raw(
+            source.extra_body,
+            effort=effort,
+            wire=profile.thinking,
+            origin=f"源 {source.name} extra_body",
         )
 
 
 def _fingerprint_mark(source: SourceConfig) -> str:
-    """单源的指纹标记;`enable_thinking` 仅在**表态时**追加。
+    """单源的指纹标记;`enable_thinking` 与 `reasoning_effort` 仅在**表态时**追加。
 
     只在表态时追加不是省事: 这样只配了 `extra_body` 的存量源字面量与 issue #4
     时期逐字相同,升级本版本不会给它们平白来一次全量缓存冷启动。
+
+    `reasoning_effort`(issue #20)与 `enable_thinking` 同规则、同理由: 它一旦真正
+    改变请求体,"把源级档位从 low 改成 max 后重启"就会读到 low 档时缓存的旧响应。
+    两者取值域不相交(`"none"`/`"low"`… vs `true`/`false`),故追加进同一个列表也
+    不会把两种写法摘要成同一身份。
     """
     parts: list[Any] = [source.model, dict(source.extra_body)]
     if source.enable_thinking is not None:
         parts.append(source.enable_thinking)
+    if source.reasoning_effort is not None:
+        parts.append(source.reasoning_effort)
     return json.dumps(parts, sort_keys=True, ensure_ascii=False)
 
 
@@ -104,16 +135,25 @@ def build_model_fingerprint(sources: Iterable[SourceConfig]) -> str:
     """缓存 key 的模型身份: 多源 scope = 排序去重的 model 合集。
 
     配置级采样参数(`extra_body`)必须参与,否则把 temperature 从 0 改成 1
-    后重启仍会读到旧缓存(issue #4 设计决策 C)。`enable_thinking` 同理
+    后重启仍会读到旧缓存(issue #4 设计决策 C)。`enable_thinking`(issue #5)与
-    (issue #5): 它一旦真正改变请求体,"关掉推理后重启"就会读到开着推理时
+    源级 `reasoning_effort`(issue #20)同理: 它们一旦真正改变请求体,"关掉推理后
-    缓存的旧响应。全源两者皆未表态时字面量与历史实现逐字相同,不触发存量
+    重启"就会读到开着推理时缓存的旧响应。全源三者皆未表态时字面量与历史实现逐字
-    缓存冷启动。
+    相同,不触发存量缓存冷启动。
+
+    注意本指纹是**装配期**算出的**集合级**身份,覆盖不到逐次调用变化的请求级档位
+    ——后者由 `build_cache_key` 的 `reasoning_effort` 参数单独承担(ARCH §7.5)。
     """
     fingerprint = ",".join(sorted({s.model for s in sources}))
-    # 按 (model, extra_body[, enable_thinking]) 而非源名摘要: 语义是"本 scope
+    # 按 (model, extra_body[, enable_thinking][, reasoning_effort]) 而非源名摘要:
-    # 会用哪些(模型, 请求形态)组合",改源名不该误触全量冷启动
+    # 语义是"本 scope 会用哪些(模型, 请求形态)组合",改源名不该误触全量冷启动。
+    # 过滤条件必须与 `_fingerprint_mark` 追加的字段逐项对齐: 漏掉一项,只配了该项
+    # 的源根本进不了 marks,`_fingerprint_mark` 改了也白改
     marks = sorted(
-        {_fingerprint_mark(s) for s in sources if s.extra_body or s.enable_thinking is not None}
+        {
+            _fingerprint_mark(s)
+            for s in sources
+            if s.extra_body or s.enable_thinking is not None or s.reasoning_effort is not None
+        }
     )
     if marks:
         digest = hashlib.sha256("".join(marks).encode("utf-8")).hexdigest()
@@ -200,7 +240,7 @@ class GatewayClient:
         rng: Any = random.random,
     ) -> None:
         emitter = (
-            TelemetryEmitter(telemetry, pricing=pricing, text_cap=text_cap)
+            TelemetryEmitter(telemetry, scope=scope, pricing=pricing, text_cap=text_cap)
             if telemetry is not None
             else None
         )
@@ -252,6 +292,10 @@ class GatewayClient:
         self._structured_available = structured_strategy is not None
         self._terminal = terminal  # 内部引用: 装配自省/测试用
         self._handler = compose(middlewares, terminal)
+        # 逻辑调用统计需要同一只注入钟(1.3.5);现之前只传给中间件未自存
+        self._now = now
+        # 终态行由公开边界统一写出(T3),故边界也需持有 emitter
+        self._emitter = emitter
         self._transport = transport
         self._telemetry = telemetry
         self._cache = cache
@@ -289,6 +333,7 @@ class GatewayClient:
         structured: type[BaseModel] | Literal["json"] | None = None,
         stream: bool = True,
         overlay: Mapping[str, Any] | None = None,
+        reasoning_effort: Effort | str | None = None,
         tenant_id: str | None = None,
         meta: Mapping[str, Any] | None = None,
     ) -> LLMResponse:
@@ -298,6 +343,11 @@ class GatewayClient:
         高于源级 `extra_body`、低于结构化输出的注入。带默认值的 keyword-only
         参数不影响既有调用点(issue #4)。
 
+        `reasoning_effort` 是本次调用的推理档位,优先级高于源级 `REASONING_EFFORT`
+        与 `ENABLE_THINKING`(设计 §4.2)。`None` 是**不表态**(随源级配置),与
+        `Effort.NONE`("要求不推理")严格区分。裸字符串(`"low"`)也收,在此归一成
+        `Effort`,非法值当场 `ValueError`——与 `SourceConfig` 那条装配路同口径。
+
         `tenant_id` 与 `meta` 是调用方自定义维度,只进遥测、**不进缓存 key**
         (租户隔离由 `cache_namespace` 负责,ARCH §7.5);前者享有真实列待遇
         (可挂 RLS、可进复合索引),后者是任意 KV 容器(issue #11)。
@@ -317,6 +367,18 @@ class GatewayClient:
         dimension_tenant_id, dimensions = validate_caller_dimensions(
             tenant_id, meta, origin="chat(tenant_id=..., meta=...)"
         )
+        # 同样必须在洋葱之外归一: 档位一路要被 `is Effort.NONE` 身份比较,裸字符串
+        # 进去会在 transport 的错误路径上抛 `AttributeError`——那不属错误四分类,
+        # 会穿透 `except ThinkingUnsupportedError` 与 RetryMW 的分类捕获(库铁律
+        # 「错误分类驱动」)。归一失败是调用方编程错误,抛裸 ValueError 不进洋葱
+        effort = (
+            None
+            if reasoning_effort is None
+            else coerce_effort(reasoning_effort, origin="chat(reasoning_effort=...)")
+        )
+        validate_thinking_raw(sampling, effort=effort, wire=None, origin="chat overlay")
+        # 三项校验均已通过 → 进入统计边界(设计 §3: 输入校验异常在边界之外,保持原行为)
+        context = _CallContext(now=self._now)
         request = ChatRequest(
             messages=messages,
             session_id=session_id,
@@ -327,10 +389,34 @@ class GatewayClient:
             stream=stream,
             overlay=sampling,
             sampling=sampling,
+            reasoning_effort=effort,
             tenant_id=dimension_tenant_id,
             meta=dimensions,
+            call_context=context,
         )
-        return await self._handler(request)
+        try:
+            response = await self._handler(request)
+        except PolyGatewayError as exc:
+            # 统计边界内的一切领域失败均尝试写一条终态行(1.3.5 设计 §6 I3),
+            # 包括已有 attempt 错误行的 RequestRejected / ResultInvalid——两类行描述
+            # 的不是同一件事(尝试 vs 逻辑终态),由 `event_kind` 区分
+            await emit_terminal_once(
+                self._emitter, request=request, context=context, error=exc, operation="chat"
+            )
+            raise
+        except asyncio.CancelledError:
+            # 尽力而为且**取消优先**: 不 shield、不开后台任务;写入那一次 await 上
+            # 再被取消则 `CancelledError` 照常传播(与 TelemetryMW 历史行为同款)
+            await emit_terminal_once(
+                self._emitter,
+                request=request,
+                context=context,
+                error="cancelled",
+                operation="chat",
+            )
+            raise
+        # 快照在返回前冻结: 故它含缓存命中路径与已完成的内联遥测耗时
+        return dataclasses.replace(response, call_stats=context.snapshot())
 
     async def aclose(self) -> None:
         """幂等释放**自建**资源: transport、遥测、缓存、限流/熔断后端。

src/polygateway/config.py

@@ -25,6 +25,7 @@ from polygateway.types import (
     GlobalLimits,
     RetryPolicy,
     SourceConfig,
+    coerce_effort,
 )
 
 if TYPE_CHECKING:
@@ -43,6 +44,11 @@ _SOURCE_FIELDS: dict[str, tuple[str, str]] = {
     "TTFT_TIMEOUT_S": ("ttft_timeout_s", "float"),
     "INTER_TOKEN_TIMEOUT_S": ("inter_token_timeout_s", "float"),
     "ENABLE_THINKING": ("enable_thinking", "bool"),
+    # 档位两键(issue #20);值域校验分工: 档位在此(解析即校验,报错点得出 env 键名),
+    # fallback 交给 SourceConfig 构造期(那道同时覆盖构造函数注入与 dataclasses.replace)
+    "REASONING_EFFORT": ("reasoning_effort", "effort"),
+    # 归一化(strip+lower)在 SourceConfig 构造期,与值域校验同处一点,故这里是裸 "str"
+    "EFFORT_FALLBACK": ("effort_fallback", "str"),
     "MISSING_DONE": ("missing_done", "str"),
     "TRUST_ENV": ("trust_env", "bool"),
     "EXTRA_BODY": ("extra_body", "json"),
@@ -93,6 +99,10 @@ def _cast(raw: str, kind: str, key: str) -> object:
             if lowered in ("0", "false", "no", "off"):
                 return False
             raise ValueError(f"非法布尔值: {raw!r}")
+        if kind == "effort":
+            # 归一化只有一份实现(`types.coerce_effort`),env 路与两条装配路同口径;
+            # origin 传空串是因为 env 键名由下面统一的"配置 X 解析失败"补上
+            return coerce_effort(raw, origin="")
         if kind == "json":
             # JSONDecodeError 是 ValueError 子类,复用下方的统一包装
             parsed = json.loads(raw)

src/polygateway/embedding.py

@@ -16,6 +16,7 @@
 from __future__ import annotations
 
 import asyncio
+import dataclasses
 import math
 import random
 import time
@@ -41,12 +42,13 @@ from polygateway.middleware.admission import SourceAdmission, settle_and_release
 from polygateway.middleware.breaker import BreakerGate
 from polygateway.middleware.ratelimit import QuotaGate
 from polygateway.middleware.retry import StallClock, _failure_reason, backoff_delay
-from polygateway.middleware.telemetry import TelemetryEmitter
+from polygateway.middleware.telemetry import TelemetryEmitter, emit_terminal_once
 from polygateway.types import (
     ChatRequest,
     EmbeddingResponse,
     LLMResponse,
     TelemetryStatus,
+    _CallContext,
     strip_unsupported_extra_body,
     validate_caller_dimensions,
 )
@@ -127,7 +129,9 @@ class EmbeddingClient:
         self._transport = transport
         self._retry = retry
         self._emitter = (
-            TelemetryEmitter(telemetry, pricing=pricing, text_cap=text_cap) if telemetry else None
+            TelemetryEmitter(telemetry, scope=self._scope, pricing=pricing, text_cap=text_cap)
+            if telemetry
+            else None
         )
         self._telemetry = telemetry
         # 限流/熔断后端在此之外只以 QuotaGate/BreakerGate 的形态存在,自持一份
@@ -184,7 +188,11 @@ class EmbeddingClient:
         dimension_tenant_id, dimensions = validate_caller_dimensions(
             tenant_id, meta, origin="embed(tenant_id=..., meta=...)"
         )
+        # 校验均已通过 → 进入统计边界(设计 §3.5: `texts` 类型与调用方维度校验之后)
+        context = _CallContext(now=self._now)
         if not texts:
+            # 合法零尝试: 返回真实统计(attempts=0),且**不写任何遥测行**
+            # ——与 cache_hit 不同,不要按"遥测必录"推断它有台账行(设计 §3 M2)
             return EmbeddingResponse(
                 vectors=[],
                 dim=0,
@@ -195,7 +203,40 @@ class EmbeddingClient:
                 latency_ms=0,
                 call_id=str(uuid.uuid4()),
                 source_name="",
+                call_stats=context.snapshot(),
             )
+        try:
+            return await self._embed_all(
+                texts, session_id, parent_call_id, dimension_tenant_id, dimensions, context
+            )
+        except PolyGatewayError as exc:
+            await self._emit_terminal(
+                texts, session_id, parent_call_id, dimension_tenant_id, dimensions, context, exc
+            )
+            raise
+        except asyncio.CancelledError:
+            # 三条链路同一口径尽力写一条(允许 0 条);取消优先,不 shield
+            await self._emit_terminal(
+                texts,
+                session_id,
+                parent_call_id,
+                dimension_tenant_id,
+                dimensions,
+                context,
+                "cancelled",
+            )
+            raise
+
+    async def _embed_all(
+        self,
+        texts: list[str],
+        session_id: str | None,
+        parent_call_id: str | None,
+        tenant_id: str | None,
+        meta: dict[str, Any],
+        context: _CallContext,
+    ) -> EmbeddingResponse:
+        """切批串行执行并合并;无源的 raise 必须在本方法内——否则无源终态行写不出。"""
         if not self._sources:
             raise AllSourcesExhausted(scope=self._scope, reason="no_sources", retry_after_s=0.0)
         outcomes = []
@@ -205,11 +246,49 @@ class EmbeddingClient:
                     texts[start : start + self._batch_size],
                     session_id,
                     parent_call_id,
-                    dimension_tenant_id,
+                    tenant_id,
-                    dimensions,
+                    meta,
+                    context,
                 )
             )
-        return self._merge(outcomes)
+        # 全批共享同一上下文,故分批是实现细节而非 N 次独立逻辑调用
+        return dataclasses.replace(self._merge(outcomes), call_stats=context.snapshot())
+
+    async def _emit_terminal(
+        self,
+        texts: list[str],
+        session_id: str | None,
+        parent_call_id: str | None,
+        tenant_id: str | None,
+        meta: dict[str, Any],
+        context: _CallContext,
+        error: PolyGatewayError | str,
+    ) -> None:
+        """终态行的请求摘要(设计 §6 M4): 计数占位 + 第一批截断文本。
+
+        描述的是**本次调用的整体输入**但不扩大单行正文预算: 失败批的具体文本由同
+        `logical_call_id` 的 attempt 行给出,终态行不保存全量原输入。
+        """
+        batches = math.ceil(len(texts) / self._batch_size)
+        messages = [{"role": "user", "content": f"<embed texts={len(texts)} batches={batches}>"}]
+        # 与逐批行同款构造(至多 `batch_size` 条、每条 200 字符)
+        messages += [
+            {"role": "user", "content": t[:_TELEMETRY_TEXT_CAP]} for t in texts[: self._batch_size]
+        ]
+        await emit_terminal_once(
+            self._emitter,
+            request=ChatRequest(
+                messages=messages,
+                session_id=session_id,
+                parent_call_id=parent_call_id,
+                tenant_id=tenant_id,
+                meta=meta,
+                call_context=context,
+            ),
+            context=context,
+            error=error,
+            operation="embed",
+        )
 
     # —— 治理循环(与 RetryMW 同构;设计 §7.1 已声明的有限重复)——
 
@@ -220,6 +299,7 @@ class EmbeddingClient:
         parent_call_id: str | None,
         tenant_id: str | None,
         meta: dict[str, Any],
+        context: _CallContext,
     ) -> _BatchOutcome:
         fails = 0
         reasons: dict[str, str] = {}
@@ -232,7 +312,7 @@ class EmbeddingClient:
                 continue
             async with clock.attempting():
                 outcome = await self._attempt(
-                    batch, *picked, reasons, session_id, parent_call_id, tenant_id, meta
+                    batch, *picked, reasons, session_id, parent_call_id, tenant_id, meta, context
                 )
             if isinstance(outcome, _BatchOutcome):
                 return outcome
@@ -258,10 +338,13 @@ class EmbeddingClient:
         parent_call_id: str | None,
         tenant_id: str | None,
         meta: dict[str, Any],
+        context: _CallContext,
     ) -> _BatchOutcome | _FailedBatch:
         call_id = str(uuid.uuid4())
         started = self._now()
         actual = 0
+        # 登记在 transport 调用**之前**(同 RetryMW): 失败与取消的尝试也真的发出去了
+        context.register_attempt()
         try:
             result = await self._transport.embed(texts=batch, source=source, call_id=call_id)
             if self._expected_dim is not None and result.dim != self._expected_dim:
@@ -287,6 +370,7 @@ class EmbeddingClient:
                 parent_call_id,
                 tenant_id,
                 meta,
+                context,
                 result,
             )
             return _BatchOutcome(result, source, call_id, latency_ms)
@@ -301,6 +385,7 @@ class EmbeddingClient:
                 parent_call_id,
                 tenant_id,
                 meta,
+                context,
                 error=exc,
             )
             raise
@@ -316,6 +401,7 @@ class EmbeddingClient:
                 parent_call_id,
                 tenant_id,
                 meta,
+                context,
                 error="cancelled",
             )
             raise
@@ -336,6 +422,7 @@ class EmbeddingClient:
                 parent_call_id,
                 tenant_id,
                 meta,
+                context,
                 error=exc,
             )
             return _FailedBatch(exc, immediate=dead)
@@ -372,8 +459,9 @@ class EmbeddingClient:
         parent_call_id: str | None,
         tenant_id: str | None,
         meta: dict[str, Any],
+        context: _CallContext,
         result: EmbeddingTransportResult | None = None,
-        error: object | None = None,
+        error: PolyGatewayError | str | None = None,
     ) -> None:
         """逐批遥测(经同一 Emitter): messages=截断 texts、向量绝不入库。"""
         if self._emitter is None:
@@ -386,6 +474,7 @@ class EmbeddingClient:
             parent_call_id=parent_call_id,
             tenant_id=tenant_id,
             meta=meta,
+            call_context=context,
         )
         response = None
         if result is not None:
@@ -410,7 +499,12 @@ class EmbeddingClient:
             call_id=call_id,
             latency_ms=int((self._now() - started) * 1000),
             response=response,
-            error=None if error is None else str(error),
+            # 异常对象原样下传: 状态码/底层异常类型/网关正文在 Emitter 内定型
+            error=error,
+            # embedding payload 硬编码 {model, input},从不带推理参数;源上即便
+            # 误配了 ENABLE_THINKING,记一个档也是替这次调用声称它没做过的事
+            reasoning_applies=False,
+            operation="embed",
         )
 
     def _merge(self, outcomes: list[_BatchOutcome]) -> EmbeddingResponse:

src/polygateway/middleware/cache.py

@@ -17,7 +17,7 @@ from typing import TYPE_CHECKING, Any
 
 from loguru import logger
 
-from polygateway.types import ChatRequest, LLMResponse, ThinkingObservation
+from polygateway.types import ChatRequest, Effort, LLMResponse, ThinkingObservation
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -53,6 +53,29 @@ def _coerce_observation(raw: Any) -> ThinkingObservation:
         return ThinkingObservation.UNKNOWN
 
 
+def _coerce_applied_effort(raw: Any) -> Effort | None:
+    """缓存里的档位字符串 → 枚举;域外取值降级为 `None`,**不作废整条缓存**。
+
+    与 `_coerce_observation` 同源同向,理由逐条相同: 多项目共用一个 Redis 时,
+    先升级的进程可能写入本版没有的档位名,未升级的进程若把这些条目判成未命中,
+    两个版本就会互相打对方的缓存。归因字段不该有能力废掉内容完好的响应。
+
+    降级到 `None` 而不是别的档: 它的语义是"库不知道这次跑在哪档",对一个读不懂
+    的取值这是唯一诚实的说法——随便挑一档等于替上游声称了一件它没说过的事。
+    """
+    if raw is None:
+        return None
+    try:
+        return Effort(raw)
+    except ValueError:
+        logger.warning(
+            "缓存条目的 applied_effort 取值 {!r} 不在本版档位词汇内(多半由更新版本的"
+            "进程写入),已降级为 None;响应内容照常复活——归因字段不作废缓存",
+            raw,
+        )
+        return None
+
+
 def digest_messages(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
     """多模态 content part 先各自 sha256 摘要再参与序列化;文本原文参与。
 
@@ -83,12 +106,21 @@ def build_cache_key(
     salt: str | None,
     *,
     sampling: Mapping[str, Any] | None = None,
+    reasoning_effort: Effort | None = None,
 ) -> str:
     """缓存 key 公式;salt 仅非 None 时参与(VT 旧键语义: 不传 salt 键形不变)。
 
     `sampling` 仅**非空**时参与(与 salt 的"仅非 None"不同——空串是有意义的
     salt,而空采样参数与不传无语义差别)。它必须进 key: 否则同 messages 跑 5 个
     seed 会全部命中第一次的响应,标准差恒为 0 且不报错(issue #4 决策 C)。
+
+    `reasoning_effort` 是**请求级**档位(issue #20),仅非 `None` 时参与。它不能靠
+    `model_fingerprint` 代劳: 后者是**装配期**算出的集合级指纹,一次调用改档位不会
+    让它变一个字节;不进 key 则同 messages 跑 low 与 max 互相命中,是 issue #4
+    「5 个 seed 全命中同一响应」的逐字翻版。
+
+    判据用 `is not None` 而非真值: `Effort.NONE`(明确要求不推理)与 `None`
+    (不表态)语义不同——前者拿到的是没有推理过程的响应,合并即毒化。
     """
     key_obj: dict[str, Any] = {
         "model": model_fingerprint,
@@ -99,6 +131,8 @@ def build_cache_key(
         key_obj["salt"] = salt
     if sampling:
         key_obj["sampling"] = dict(sampling)
+    if reasoning_effort is not None:
+        key_obj["reasoning_effort"] = str(reasoning_effort)
     payload = json.dumps(key_obj, sort_keys=True, ensure_ascii=False)
     return _KEY_PREFIX + hashlib.sha256(payload.encode("utf-8")).hexdigest()
 
@@ -139,6 +173,9 @@ class CacheMW:
             namespace,
             request.cache_salt,
             sampling=request.sampling,
+            # 请求级档位必须逐次进 key: `self._fingerprint` 是装配期的集合级指纹,
+            # 同一个 client 上 low 与 max 两次调用在它眼里毫无分别(issue #20)
+            reasoning_effort=request.reasoning_effort,
         )
         cached = await self._safe_get(key)
         if cached is not None:
@@ -162,6 +199,8 @@ class CacheMW:
             # 键缺失即升级前写入的旧条目,交给 dataclass 默认值
             if "thinking_observation" in fields:
                 fields["thinking_observation"] = _coerce_observation(fields["thinking_observation"])
+            if "applied_effort" in fields:
+                fields["applied_effort"] = _coerce_applied_effort(fields["applied_effort"])
             fields.update(
                 cache_hit=True,
                 latency_ms=0,
@@ -169,6 +208,10 @@ class CacheMW:
                 max_inter_token_ms=None,
                 call_id=str(uuid.uuid4()),
                 structured_data=structured_data,
+                # 显式覆盖: 历史条目里的 `call_stats` 是个 dict,而 `_RESPONSE_FIELDS`
+                # 过滤**会放行它**——不覆盖就会有 dict 冒充 `CallStats` 漏给调用方。
+                # 本次调用的真实统计由公开边界在返回前追加(设计 §3)
+                call_stats=None,
             )
             return LLMResponse(**fields)
         except Exception as exc:
@@ -191,6 +234,9 @@ class CacheMW:
     def _serialize(self, response: LLMResponse) -> str:
         data = dataclasses.asdict(response)
         data.pop("structured_data", None)  # pydantic 实例不可 JSON 往返(设计 §2.1)
+        # 统计描述**本次**调用,存进去再放出来等于向下一个调用方谎称
+        # 它重试了 N 次;`asdict` 会把 `CallStats` 摊成 dict,故必须显式剔除
+        data.pop("call_stats", None)
         return json.dumps(data, ensure_ascii=False)
 
     async def _safe_get(self, key: str) -> str | None:

src/polygateway/middleware/retry.py

@@ -42,6 +42,7 @@ from polygateway.types import LLMResponse
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Awaitable, Callable
 
+    from polygateway.middleware.telemetry import TelemetryEmitter
     from polygateway.ports import (
         GateDecision,
         Permit,
@@ -181,7 +182,7 @@ class RetryMW:
         circuit_open: str = "fail_fast",
         cooldown_memo: SourceCooldownMemo | None = None,
         pacer: AdaptivePacer | None = None,
-        emitter: object | None = None,
+        emitter: TelemetryEmitter | None = None,
         now: Callable[[], float] = time.monotonic,
         sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
         rng: Callable[[], float] = random.random,
@@ -278,6 +279,11 @@ class RetryMW:
         call_id = str(uuid.uuid4())
         started = self._now()
         actual = 0
+        # 登记在 transport 调用**之前**(1.3.5 设计 §4): 失败与取消的尝试同样
+        # "真的打出去了",挪到成功之后会让诊断最需要看见的那几次从计数里消失。
+        # 上下文为 None = 库内现场构造的请求,跳过而不是报错
+        if request.call_context is not None:
+            request.call_context.register_attempt()
         try:
             result = await self._transport.complete(
                 messages=request.messages,
@@ -285,6 +291,9 @@ class RetryMW:
                 stream=request.stream,
                 overlay=request.overlay,
                 call_id=call_id,
+                # 逐次尝试原样重传: 换源不改变调用方要的档位(源级默认由 transport
+                # 自己按选中的源解析,两者在 effective_effort 里汇合)
+                reasoning_effort=request.reasoning_effort,
             )
             if result.usage_source == "unavailable":
                 # 用量不可得时按入场预扣量结算(delta==0),否则押金会被整笔退回,
@@ -392,6 +401,9 @@ class RetryMW:
             reasoning_tokens=result.reasoning_tokens,
             # 裁定归 transport(它才见得到原始信号),本层只搬运不改判
             thinking_observation=result.thinking_observation,
+            # 同理: 实际档由做注入的那一层裁定(`nearest` 映射后与请求档分叉),
+            # 本层若"顺手"改读 request.reasoning_effort,记的就是从未发出过的档
+            applied_effort=result.applied_effort,
         )
 
     async def _emit(
@@ -402,9 +414,13 @@ class RetryMW:
         started: float,
         *,
         response: LLMResponse | None = None,
-        error: object | None = None,
+        error: PolyGatewayError | str | None = None,
     ) -> None:
-        """逐次遥测(经注入的单一 Emitter);遥测失败不得影响调用(铁律)。"""
+        """逐次遥测(经注入的单一 Emitter);遥测失败不得影响调用(铁律)。
+
+        异常**对象原样下传**而非先 `str()` 压平(1.3.5 设计 §5): 状态码、底层异常
+        类型与网关响应体已经在异常上了,在这里压平就是把它们丢掉。
+        """
         if self._emitter is None:
             return
         try:
@@ -414,7 +430,11 @@ class RetryMW:
                 call_id=call_id,
                 latency_ms=int((self._now() - started) * 1000),
                 response=response,
-                error=None if error is None else str(error),
+                error=error,
+                # chat 路径是唯一带推理参数的路径,故实发档由这里的响应说了算
+                reasoning_applies=True,
+                # 公开方法四值之一;本中间件只服务 chat 洋葱
+                operation="chat",
             )
         except asyncio.CancelledError:
             raise

src/polygateway/middleware/structured.py

@@ -14,6 +14,8 @@ from typing import TYPE_CHECKING
 from polygateway.errors import ResultInvalidError
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from polygateway.ports import CallNext, StructuredOutputStrategy
     from polygateway.types import ChatRequest, LLMResponse
 
@@ -22,12 +24,18 @@ _FEEDBACK_TEMPLATE = (
     "Your previous reply was not valid JSON matching the required schema. "
     "Errors: {errors}. Reply with ONLY the corrected JSON object."
 )
-_MAX_FEEDBACK_ERRORS = 3
+MAX_FEEDBACK_ERRORS = 3
-_MAX_ERROR_CHARS = 200
+MAX_ERROR_CHARS = 200
 
 
-def _format_errors(errors: list[str]) -> str:
+def format_bounded_errors(errors: Sequence[str]) -> str:
-    clipped = [e[:_MAX_ERROR_CHARS] for e in errors[:_MAX_FEEDBACK_ERRORS]]
+    """校验错误的有界拼装: 至多 3 条 × 每条 200 字符。
+
+    **本模块是这条规则的所有者**: 重问反馈文案与 1.3.5 终态行的结构化说明
+    两个消费者共用同一份实现与同一组数值——数值复制成两份必然漂移,而漂移后
+    "模型看到的错误"与"台账里记的错误"就不再是同一件事。行为与重命名前逐字相同。
+    """
+    clipped = [e[:MAX_ERROR_CHARS] for e in list(errors)[:MAX_FEEDBACK_ERRORS]]
     return "; ".join(clipped) if clipped else "output could not be parsed"
 
 
@@ -104,7 +112,10 @@ class StructuredMW:
         messages = [
             *current.messages,
             {"role": "assistant", "content": bad_content},
-            {"role": "user", "content": _FEEDBACK_TEMPLATE.format(errors=_format_errors(errors))},
+            {
+                "role": "user",
+                "content": _FEEDBACK_TEMPLATE.format(errors=format_bounded_errors(errors)),
+            },
         ]
         reask = dataclasses.replace(current, messages=messages)
         if self._escalation is not None:

src/polygateway/middleware/telemetry.py

@@ -2,13 +2,19 @@
 
 Emitter 是全库**唯一**调用 `record_llm_call` 的地方(三项目 4 处逐字复制
 15 参调用的教训)。分工: RetryMW 经 Emitter 逐次记录每次尝试;TelemetryMW
-(最外层)只记尝试层看不见的事件——缓存命中、scope 级失败、取消;
+(最外层)只记尝试层看不见的缓存命中;而**终态失败行**由三个 client 的公开
-RequestRejected/ResultInvalid 已被尝试层记录,最外层放行不重复记。
+边界经 `emit_terminal_once` 统一写出(1.3.5)——两处同时写就会双计。
+
+一行遥测属于三类事件之一(`event_kind`): `attempt`(一次尝试)、`cache_hit`
+(未产生网关调用)、`terminal_failure`(一次**逻辑调用**的失败终态)。后两者与
+前者**不是重复事实**,故统计失败调用次数只能取 `terminal_failure`,
+不得按 `error IS NOT NULL` 跨两类直接计数(设计 §6/§8)。
 """
 
 from __future__ import annotations
 
 import asyncio
+import inspect
 import json
 import time
 import uuid
@@ -17,21 +23,28 @@ from typing import TYPE_CHECKING
 
 from loguru import logger
 
-from polygateway.errors import (
+from polygateway.errors import PolyGatewayError, ResultInvalidError
-    GatewayUnavailableError,
-    GovernanceBackendError,
-    SourceNotConfiguredError,
-)
 from polygateway.middleware.cache import digest_messages
-from polygateway.types import ThinkingObservation, canonical_sampling_json, merge_sampling
+from polygateway.middleware.structured import MAX_ERROR_CHARS, format_bounded_errors
+from polygateway.ports import TelemetryRecorder
+from polygateway.thinking import effective_effort
+from polygateway.types import Effort, ThinkingObservation, canonical_sampling_json, merge_sampling
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
     from typing import Any
 
-    from polygateway.ports import CallNext, TelemetryRecorder
+    from polygateway.ports import CallNext
     from polygateway.pricing import PricingTable
-    from polygateway.types import ChatRequest, LLMResponse, SourceConfig
+    from polygateway.types import (
+        CallOperation,
+        CallStats,
+        ChatRequest,
+        EventKind,
+        LLMResponse,
+        SourceConfig,
+        _CallContext,
+    )
 
 
 def _canonical_meta_json(meta: Mapping[str, Any]) -> str:
@@ -80,6 +93,70 @@ def _normalize_observation(raw: object) -> str:
         return ThinkingObservation.UNKNOWN.value
 
 
+def _normalize_effort(raw: object) -> str | None:
+    """实际档位 → 落库用的裸 str;不表态与域外取值都落 `NULL`。
+
+    **不写 `raw.value`**,理由与 `_normalize_observation` 逐字相同: `LLMResponse`
+    是无运行时校验的 frozen dataclass,测试替身写 `applied_effort="low"` 完全自然,
+    而 `.value` 会当场抛 `AttributeError`,被 `_record` 的 `except Exception` 吞成
+    一条泛化 warning —— 丢的不是这一列,是**整行**。
+
+    域外取值降级为 `None` 而不抛,方向与 `CacheMW._coerce_applied_effort` 一致
+    (设计 §4.4): 多项目共用一套后端时,更新版本的进程可能带来本版没有的档位名,
+    归因字段不该有能力废掉一整行遥测。降级到 `None` 也是唯一诚实的说法——库确实
+    不知道这次跑在哪档,随便挑一档等于替上游声称了一件它没说过的事。
+
+    注意 `None` 在本列有**两个**来源(不表态 / 读不懂),二者都不可折叠进 `'none'`:
+    `'none'` 是"明确要求不推理",是一次表态。
+    """
+    if raw is None:
+        return None
+    try:
+        return Effort(raw).value
+    except ValueError:
+        logger.warning(
+            "推理档位取值 {!r} 不在本版档位词汇内,本行 reasoning_effort 降级记为 NULL"
+            "(其余列照常落库)",
+            raw,
+        )
+        return None
+
+
+def _attempt_effort(
+    *,
+    request: ChatRequest,
+    source: SourceConfig,
+    response: LLMResponse | None,
+    applies: bool,
+) -> str | None:
+    """一次尝试该记哪一档: 成功读**实发档**,失败退回**请求档**(设计 §6)。
+
+    成功行一律读 `response.applied_effort` 而**绝不重算**: 源上开了
+    `EFFORT_FALLBACK=nearest` 时,请求 `medium` 而模型只有 low/high/max,实发的是
+    `low`;此处重算 `effective_effort` 必然算成请求档,于是整行被挂在一个从未发出
+    过的分组下——而两个值在没开映射的源上恒等,这个错在本地跑不出来。
+
+    失败尝试没有响应,实发档无从得知,故退回请求档并**接受这层含义差别**: 开了映射
+    的源上,成功行是映射后的档、失败行是请求档,两种行不是同一把尺子。仍然记而不是
+    留空,是因为档位错误(`resolve_thinking` 的 Phase 2/4/5)根本没发 HTTP 就被拒,
+    这类行记的正是**被拒绝的那一档**——"哪一档配错了"是压测与排障要的信号。
+
+    回落走 `effective_effort` 而非裸读两个字段: `enable_thinking` 也是一次表态
+    (语法糖),漏掉它就会把一次明确要求推理的调用记成"没表态"。
+    """
+    if not applies:
+        return None
+    if response is not None:
+        return _normalize_effort(response.applied_effort)
+    return _normalize_effort(
+        effective_effort(
+            request_effort=request.reasoning_effort,
+            source_effort=source.reasoning_effort,
+            enable_thinking=source.enable_thinking,
+        )
+    )
+
+
 def _cap_text(text: str, cap: int | None) -> str:
     """超出 cap 时头部硬切并附省略标记 `…(略 N 字)`;cap 为 None 原样返回。"""
     if cap is None or len(text) <= cap:
@@ -160,26 +237,159 @@ class _AttemptUsage:
         )
 
 
+@dataclass(frozen=True)
+class _ErrorFields:
+    """一行遥测的错误列;未知一律 `None`。
+
+    存在的理由是把"三种入参形态 × 两类行"的定型规则收敛到**一处**:
+    改前调用方先 `str(exc)` 压平,状态码、底层异常类型与网关正文全部丢失。
+    """
+
+    error: str | None = None
+    error_type: str | None = None
+    cause_type: str | None = None
+    http_status_code: int | None = None
+    error_body: str | None = None
+
+
+def _structured_detail(exc: ResultInvalidError) -> str:
+    """结构化阶梯耗尽的**有界**说明(设计 §5 C2)。
+
+    `ResultInvalidError("结构化输出阶梯耗尽")` 的 message 不含校验与修复错误,而该
+    失败发生在 StructuredMW 之上——RetryMW 侧的 attempt 行全是**成功行**,终态行是
+    唯一记录。故把说明并入现有 `error` 串。
+
+    **不含 `raw_text`**: 它是模型正文,attempt 行的 `response` 列已按 `text_cap` 记过
+    一份;再存一份等于绕过既有的正文预算。条数与限长复用 `structured.py` 的同一
+    套常量(重问反馈与本说明同一口径),数值只有一份。
+    """
+    parts: list[str] = []
+    if exc.repair_error:
+        parts.append(f"repair={exc.repair_error[:MAX_ERROR_CHARS]}")
+    if exc.validation_errors:
+        parts.append(f"validation={format_bounded_errors(exc.validation_errors)}")
+    return " | ".join(parts)
+
+
+def _error_fields(
+    error: PolyGatewayError | str | None,
+    *,
+    event_kind: EventKind,
+    class_prefixed: bool,
+) -> _ErrorFields:
+    """三种入参形态的唯一定型点(设计 §5/§6)。
+
+    - `None` → 全 None(成功行不统一填 200: 那会让"有状态码"不再等价于"失败了")。
+    - `str`(取消路径的 `"cancelled"`)→ 原样落 `error`,**不解析字符串猜诊断**。
+    - 领域异常 → 只读它既有的属性,不遍历任意对象、不猜正文。
+
+    **终态行的三列恒为 NULL(C1 红线)**: `GatewayUnavailableError` 家族从不携带
+    状态码与响应体,NULL 正是它自身的真实状态——把最后一次 attempt 的状态码与正文
+    搬上来,就是拿最后一个源冒充整池归因。逐源现场由同一 `logical_call_id` 的
+    attempt 行给出。
+    """
+    if error is None:
+        return _ErrorFields()
+    if isinstance(error, str):
+        return _ErrorFields(error=error)
+    name = type(error).__name__
+    # 空 `str()` 退回类名(httpx 的 Connect/Read/Write/PoolTimeout 文案就是空的);
+    # `class_prefixed` 是 OCR 的既有口径(按类名归组的 metric),故逐字保留它的拼法
+    text = f"{name}: {error}" if class_prefixed else (str(error) or name)
+    if event_kind == "terminal_failure":
+        if isinstance(error, ResultInvalidError):
+            detail = _structured_detail(error)
+            if detail:
+                text = f"{text} | {detail}"
+        return _ErrorFields(error=text, error_type=name)
+    cause = error.__cause__
+    return _ErrorFields(
+        error=text,
+        error_type=name,
+        cause_type=type(cause).__name__ if cause is not None else None,
+        # getattr 而非直读: 本函数在 `_record` 的降级 try **之外**求值,
+        # 一个非领域异常误传进来不得把一次真实失败换成 AttributeError
+        http_status_code=getattr(error, "status_code", None),
+        # 空串归 None: 既有 `body_text` 的缺省就是空串,而本列的语义是"未知"
+        error_body=getattr(error, "body_text", "") or None,
+    )
+
+
+def _assert_recorder_shape(recorder: TelemetryRecorder) -> None:
+    """装配期一次 `signature.bind` 形状校验: 不执行写入,只证明该形状能被接受。
+
+    `_record` 的 `except Exception` 会把旧 recorder 的 `TypeError` 吞成 warning,
+    后果是自定义 recorder 在下游升级后**100% 丢遥测且调用照常成功**——正是
+    "遥测必录"要防的形态,而文档级迁移清单挡不住它。故在装配期当场报错
+    (不是 warning: 降级方向的铁律管的是**运行期写失败**,不是装配错误)。
+
+    参数名从 `TelemetryRecorder.record_llm_call` 的协议签名**派生**(不手抄第四份
+    字段清单),绑定用哨兵 `None`,不读任何真实请求数据;`**kwargs`
+    (VAR_KEYWORD)自动通过。不可 inspect(C 实现等)同样按配置错误报错——宁可
+    装配不起来,不进入"运行期静默丢行"。
+
+    边界诚实声明: 它只证明该形状能被接受,**不能证明函数体真的落这些列**。
+
+    Raises:
+        ValueError: 签名不符、不可 inspect,或协议本身不可 inspect。
+    """
+    try:
+        # 模块全局查找而非常量快照: 协议改了,闸就跟着改(测试可据此机械验证)
+        protocol = inspect.signature(TelemetryRecorder.record_llm_call).parameters
+    except (TypeError, ValueError) as exc:  # pragma: no cover - 协议一向可 inspect
+        raise ValueError(f"TelemetryRecorder.record_llm_call 签名不可读取: {exc}") from exc
+    sentinels = {name: None for name in protocol if name != "self"}
+    label = type(recorder).__name__
+    method = getattr(recorder, "record_llm_call", None)
+    if method is None:
+        # 连方法都没有: 比旧签名更明确的配置错误。不让它以裸 AttributeError
+        # 逆流而上——那不属错误四分类,且现场离"注错了东西"这个真因很远
+        raise ValueError(
+            f"注入的遥测 recorder {label} 没有 record_llm_call 方法,不满足 TelemetryRecorder 端口"
+        )
+    try:
+        signature = inspect.signature(method)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            f"遥测 recorder {label} 的 record_llm_call 不可 inspect(如 C 实现),"
+            "无法在装配期确认它接受当前字段形状;请换成 Python 实现或包一层"
+        ) from exc
+    try:
+        signature.bind(**sentinels)
+    except TypeError as exc:
+        raise ValueError(
+            f"遥测 recorder {label} 的 record_llm_call 签名与 TelemetryRecorder 不符"
+            f"(当前 {len(sentinels)} 个字段): {exc}。"
+            "这一条故意在装配期报错——放行的后果是每行遥测都被降级成 warning 后丢弃"
+        ) from exc
+
+
 class TelemetryEmitter:
-    """从请求与结果组装 25 字段并写入 recorder;一切写失败降级 warning。"""
+    """从请求与结果组装 36 字段并写入 recorder;一切写失败降级 warning。"""
 
     def __init__(
         self,
         recorder: TelemetryRecorder,
         *,
+        scope: str,
         pricing: PricingTable | None = None,
         text_cap: int | None,
     ) -> None:
-        """`text_cap` 无默认值是有意的: 它是关键行为参数,漏传即静默改变落库正文。
+        """`text_cap` 与 `scope` 无默认值是有意的: 两者都是关键行为参数。
 
+        `text_cap` 漏传即静默改变落库正文;`scope` 漏传则三类行都失去池名
+        ——终态失败可能根本没选出源,但 scope 始终已知,不拿 `source_name` 顶替。
         本类是库内部类,唯一构造者是三个公共 Client,必填能保证没有一处漏传。
-        同理,值域校验也放在这一处: 三个 Client 的 `text_cap` 全部汇流到这里,
+
+        同理,值域校验与**装配闸**都放在这一处: 三个 Client 全部汇流到这里,
         `GatewaySettings` 那道只管 env 一条路,而直接构造 Client 是库承诺的另一
-        条公共装配路——`text_cap=0` 会让每条正文只剩一个省略标记(P5 不得静默)。
+        条公共装配路(`text_cap=0` 会让每条正文只剩一个省略标记;P5 不得静默)。
         """
         if text_cap is not None and text_cap <= 0:
             raise ValueError(f"text_cap 必须 > 0(不截断请传 None): {text_cap}")
+        _assert_recorder_shape(recorder)
         self._recorder = recorder
+        self._scope = scope
         self._pricing = pricing
         self._text_cap = text_cap
 
@@ -191,9 +401,24 @@ class TelemetryEmitter:
         call_id: str,
         latency_ms: int,
         response: LLMResponse | None,
-        error: str | None,
+        error: PolyGatewayError | str | None,
+        reasoning_applies: bool,
+        operation: CallOperation,
+        class_prefixed_error: bool = False,
     ) -> None:
-        """逐次尝试记录(RetryMW 调用);失败尝试无用量可言,记 0 并标 unavailable。"""
+        """逐次尝试记录(三个 Client 的重试层调用);失败尝试无用量可言,记 0 并标 unavailable。
+
+        `reasoning_applies` 声明**这条调用路径有没有推理语义**: chat 路径为
+        `True`,embedding / OCR 路径为 `False`。它不能由 emitter 自己推断——三条路径
+        共用同一个 `SourceConfig` 类型,一个误配了 `ENABLE_THINKING` 的 embedding 源
+        会让下面的回落算出 `auto`,给一次从来不带推理参数的调用挂上一个从未发出过的
+        档。**不设默认值**: 与 `TelemetryRecorder` 同一约定,库外无第三方调用者,漏传
+        当场 TypeError,好过被静默当成"没表态"。`operation` 同理且另有一层:
+        它只能由调用点给定,**绝不读 `exc.operation`**(后者是 HTTP 子操作)。
+
+        `error` 收**领域异常对象**而非预先 `str()` 压平的文本: 状态码/底层异常类型/
+        网关正文在此提取成四列(设计 §5)。取消路径仍传既有字符串 `"cancelled"`。
+        """
         usage = _AttemptUsage.of(response)
         await self._record(
             request=request,
@@ -210,7 +435,7 @@ class TelemetryEmitter:
             ttft_ms=usage.ttft_ms,
             max_inter_token_ms=usage.max_inter_token_ms,
             cache_hit=False,
-            error=error,
+            errors=_error_fields(error, event_kind="attempt", class_prefixed=class_prefixed_error),
             cached_prompt_tokens=usage.cached_prompt_tokens,
             model_reported=usage.model_reported,
             reasoning_tokens=usage.reasoning_tokens,
@@ -219,10 +444,22 @@ class TelemetryEmitter:
             sampling=canonical_sampling_json(merge_sampling(source.extra_body, request.sampling)),
             tenant_id=request.tenant_id,
             meta=request.meta,
+            reasoning_effort=_attempt_effort(
+                request=request, source=source, response=response, applies=reasoning_applies
+            ),
+            operation=operation,
+            event_kind="attempt",
+            attempts=None,
+            total_latency_ms=None,
         )
 
-    async def emit_cache_hit(self, *, request: ChatRequest, response: LLMResponse) -> None:
+    async def emit_cache_hit(
-        """缓存命中记录: cache_hit=True、latency_ms=0(VT 同款)。"""
+        self, *, request: ChatRequest, response: LLMResponse, operation: CallOperation
+    ) -> None:
+        """缓存命中记录: cache_hit=True、latency_ms=0(VT 同款)。
+
+        逻辑计数两列恒 NULL: 本行描述的是"一次命中",不是一次逻辑调用的终态。
+        """
         await self._record(
             request=request,
             call_id=response.call_id,
@@ -238,7 +475,7 @@ class TelemetryEmitter:
             ttft_ms=None,
             max_inter_token_ms=None,
             cache_hit=True,
-            error=None,
+            errors=_ErrorFields(),
             # 决策 B1: 与 model/prompt_tokens 同一口径,原样回放历史值。
             # 统计供应商缓存命中率必须带 WHERE cache_hit = false,否则重复计数。
             cached_prompt_tokens=response.cached_prompt_tokens,
@@ -254,12 +491,31 @@ class TelemetryEmitter:
             # 记到上一个租户头上,两边的账同时错且无任何报错(issue #11 设计 §4.3)
             tenant_id=request.tenant_id,
             meta=request.meta,
+            # 与 sampling 同一口径: 命中行没有选中源,源级档位与 `nearest` 映射
+            # 都无从谈起,只记调用方这次要的档(response 里那个是历史那次实发的)
+            reasoning_effort=_normalize_effort(request.reasoning_effort),
+            operation=operation,
+            event_kind="cache_hit",
+            attempts=None,
+            total_latency_ms=None,
         )
 
     async def emit_terminal_failure(
-        self, *, request: ChatRequest, call_id: str, latency_ms: int, error: str
+        self,
+        *,
+        request: ChatRequest,
+        call_id: str,
+        error: PolyGatewayError | str,
+        operation: CallOperation,
+        stats: CallStats,
+        class_prefixed_error: bool = False,
     ) -> None:
-        """scope 级失败/取消记录: 无具体源,溯源字段置空标记。"""
+        """一次**逻辑调用**的失败终态: 无具体源,溯源字段置空标记。
+
+        `latency_ms` 与 `total_latency_ms` 同取**同一份冻结快照**,避免双时钟微差;
+        故本方法不再收 `latency_ms`。token 与 cost 一律不从 attempt 行复制
+        (费用聚合仍只由 attempt / cache_hit 行决定,口径不变)。
+        """
         await self._record(
             request=request,
             call_id=call_id,
@@ -271,11 +527,13 @@ class TelemetryEmitter:
             prompt_tokens=0,
             completion_tokens=0,
             usage_source="unavailable",
-            latency_ms=latency_ms,
+            latency_ms=stats.total_latency_ms,
             ttft_ms=None,
             max_inter_token_ms=None,
             cache_hit=False,
-            error=error,
+            errors=_error_fields(
+                error, event_kind="terminal_failure", class_prefixed=class_prefixed_error
+            ),
             cached_prompt_tokens=None,
             model_reported=None,
             reasoning_tokens=None,
@@ -286,6 +544,12 @@ class TelemetryEmitter:
             # 源不可知,但租户归属是已知的——终态失败行恰是审计最需要的
             tenant_id=request.tenant_id,
             meta=request.meta,
+            # 可能根本没选出源,故与 sampling 同样只取请求档
+            reasoning_effort=_normalize_effort(request.reasoning_effort),
+            operation=operation,
+            event_kind="terminal_failure",
+            attempts=stats.attempts,
+            total_latency_ms=stats.total_latency_ms,
         )
 
     async def _record(
@@ -305,7 +569,9 @@ class TelemetryEmitter:
         ttft_ms: float | None,
         max_inter_token_ms: float | None,
         cache_hit: bool,
-        error: str | None,
+        # 1.3.5: 错误四列已由 `_error_fields` 定型(三种入参形态 × 两类行的唯一规则所有者),
+        # 本方法只搬运——拆成五个平铺参数就是把"一处定型"换回"三处各自拼"
+        errors: _ErrorFields,
         cached_prompt_tokens: int | None,
         model_reported: str | None,
         sampling: str | None,
@@ -317,6 +583,15 @@ class TelemetryEmitter:
         # issue #11: 未归一化的调用方维度,归一化在本方法内收口(recorder 只落库)
         tenant_id: str | None,
         meta: Mapping[str, Any],
+        # issue #20: 已由各入口按自己的口径定型成裸 str/None(口径差别见三个入口的
+        # 注释),本方法只搬运——把定型放这里就得再传一遍 response/source,等于把
+        # "唯一 record_llm_call 调用点"换成"两处口径判断",那正是要避免的复制
+        reasoning_effort: str | None,
+        # —— 1.3.5: 行形态与逻辑调用快照 ——
+        operation: CallOperation,
+        event_kind: EventKind,
+        attempts: int | None,
+        total_latency_ms: int | None,
     ) -> None:
         try:
             # 成本换算(M2 §6): 成功行按单价换算;缓存命中 0.0(未产生新调用);
@@ -327,7 +602,7 @@ class TelemetryEmitter:
                 # 用量不可得: 宁可算不出成本,也不算错成本(解耦设计 §3.1 不变式)。
                 # 必须排在 cache_hit 之后——缓存命中未产生新调用,0.0 是事实而非未知
                 cost = None
-            elif error is None and model and self._pricing is not None:
+            elif errors.error is None and model and self._pricing is not None:
                 cost = self._pricing.cost(
                     model, prompt_tokens, completion_tokens, cached_prompt_tokens
                 )
@@ -339,6 +614,7 @@ class TelemetryEmitter:
                 _cap_messages(digest_messages(request.messages), self._text_cap),
                 ensure_ascii=False,
             )
+            context = request.call_context
             await self._recorder.record_llm_call(
                 call_id=call_id,
                 parent_call_id=request.parent_call_id,
@@ -356,7 +632,7 @@ class TelemetryEmitter:
                 ttft_ms=ttft_ms,
                 max_inter_token_ms=max_inter_token_ms,
                 cache_hit=cache_hit,
-                error=error,
+                error=errors.error,
                 cost=cost,
                 cached_prompt_tokens=cached_prompt_tokens,
                 model_reported=model_reported,
@@ -370,6 +646,20 @@ class TelemetryEmitter:
                 # 保证接受,而遥测写失败只降级成一条 warning——不会当场炸,只会让
                 # Postgres 那一路悄悄少一列数据
                 thinking_observation=_normalize_observation(thinking_observation),
+                reasoning_effort=reasoning_effort,
+                # —— 1.3.5 十列 ——
+                scope=self._scope,
+                # 调用点给定的公开方法四值,**绝不读 `exc.operation`**(设计 §5 I1/I2)
+                operation=operation,
+                # 上下文缺席(库内现场构造的 ChatRequest)→ NULL,**不造 ID**(I5)
+                logical_call_id=None if context is None else context.logical_call_id,
+                event_kind=event_kind,
+                http_status_code=errors.http_status_code,
+                error_type=errors.error_type,
+                cause_type=errors.cause_type,
+                error_body=errors.error_body,
+                attempts=attempts,
+                total_latency_ms=total_latency_ms,
             )
         except asyncio.CancelledError:
             raise
@@ -377,36 +667,69 @@ class TelemetryEmitter:
             logger.warning("遥测记录失败(降级不冒泡): {}", exc)
 
 
+async def emit_terminal_once(
+    emitter: TelemetryEmitter | None,
+    *,
+    request: ChatRequest,
+    context: _CallContext,
+    error: PolyGatewayError | str,
+    operation: CallOperation,
+    class_prefixed_error: bool = False,
+) -> None:
+    """三个 client 共用的**终态唯一出口**: 去重 + 同步冻结快照 + best effort 写入。
+
+    去重由 `claim_terminal()` 承担(每逻辑调用至多一条终态行);`emitter is None`
+    或已写过 → 直接返回。
+
+    **降级范围包含诊断字段的提取与构建**,不只是写入那一步: `_record` 内的
+    `except Exception` 只兜住落库,而 `_error_fields` / `canonical_sampling_json`
+    在它**之外**求值——下游经公共端口(自实现 `StructuredOutputStrategy` 或
+    transport)构造出的 `ResultInvalidError(validation_errors=(非 str,))` 会让提取期
+    抛 `TypeError` 顶替调用方本该收到的领域异常,错误四分类被击穿且终态行照样丢。
+    故在此整段兜底,与 RetryMW 的 attempt 出口(`retry.py::_emit`)同款写法。
+    终态行按 best effort: 兜底命中时本次逻辑调用**没有**终态行(`claim_terminal()`
+    已消耗,不补写、不重试——重写一遍只会把同一个提取期异常再抛一次)。
+
+    **`CancelledError` 原样传播**(取消优先,不 shield、不开后台任务): 这一次
+    `await` 本身就是新的取消点,外部取消落在它上时调用方会看到 `CancelledError`
+    而非领域错误——与 TelemetryMW 的历史行为同款,已经人类批准(设计 §6/§10)。
+    快照冻结是**同步**动作,故终态行不含它自身的写入耗时。
+    """
+    if emitter is None or not context.claim_terminal():
+        return
+    try:
+        stats = context.snapshot()
+        await emitter.emit_terminal_failure(
+            request=request,
+            call_id=str(uuid.uuid4()),
+            error=error,
+            operation=operation,
+            stats=stats,
+            class_prefixed_error=class_prefixed_error,
+        )
+    except asyncio.CancelledError:
+        raise
+    except Exception as exc:
+        logger.warning("终态遥测记录失败(降级不冒泡): {}", exc)
+
+
 class TelemetryMW:
-    """洋葱最外层: 观测尝试层看不见的路径,任何路径都留痕(遥测必录)。"""
+    """洋葱最外层: 只观测尝试层看不见的**缓存命中**。
+
+    1.3.5 起不再在此写终态失败行: 终态由 `GatewayClient.chat` 的公开边界经
+    `emit_terminal_once` 统一写出。两处同时写会让同一次失败出两条终态行,
+        而下游正是按 `event_kind = 'terminal_failure'` 计失败调用次数的。
+    """
 
     def __init__(
         self, emitter: TelemetryEmitter, now: Callable[[], float] = time.monotonic
     ) -> None:
         self._emitter = emitter
-        self._now = now
+        # `now` 自 1.3.5 起本类不再读取(终态行迁到公开边界后无耗时可测),但形参保留:
+        # 删它会平白打断 `TelemetryMW(emitter, now=...)` 这一既有装配写法
 
     async def __call__(self, request: ChatRequest, call_next: CallNext) -> LLMResponse:
-        started = self._now()
-        try:
         response = await call_next(request)
-        except (GatewayUnavailableError, GovernanceBackendError, SourceNotConfiguredError) as exc:
-            await self._emitter.emit_terminal_failure(
-                request=request,
-                call_id=str(uuid.uuid4()),
-                latency_ms=int((self._now() - started) * 1000),
-                error=str(exc),
-            )
-            raise
-        except asyncio.CancelledError:
-            # 尽力而为: 取消也留痕(§5.1 约定④);随后立即重抛
-            await self._emitter.emit_terminal_failure(
-                request=request,
-                call_id=str(uuid.uuid4()),
-                latency_ms=int((self._now() - started) * 1000),
-                error="cancelled",
-            )
-            raise
         if response.cache_hit:
-            await self._emitter.emit_cache_hit(request=request, response=response)
+            await self._emitter.emit_cache_hit(request=request, response=response, operation="chat")
         return response

src/polygateway/ocr.py

@@ -37,15 +37,17 @@ from polygateway.middleware.admission import SourceAdmission, settle_and_release
 from polygateway.middleware.breaker import BreakerGate
 from polygateway.middleware.ratelimit import QuotaGate
 from polygateway.middleware.retry import StallClock, _failure_reason, backoff_delay
-from polygateway.middleware.telemetry import TelemetryEmitter
+from polygateway.middleware.telemetry import TelemetryEmitter, emit_terminal_once
 from polygateway.ports import OutcomeAwareSelector
 from polygateway.types import (
+    CallStats,
     ChatRequest,
     LLMResponse,
     OcrLayoutResult,
     OcrTextResult,
     TelemetryStatus,
     Usage,
+    _CallContext,
     strip_unsupported_extra_body,
     validate_caller_dimensions,
 )
@@ -65,6 +67,7 @@ if TYPE_CHECKING:
     )
     from polygateway.types import (
         BackpressurePolicy,
+        CallOperation,
         OcrLayoutTransportResult,
         OcrTextTransportResult,
         RetryPolicy,
@@ -126,7 +129,9 @@ class OcrClient:
         self._breaker = BreakerGate(breaker, scope=self._scope)
         self._transport = transport
         self._retry = retry
-        self._emitter = TelemetryEmitter(telemetry, text_cap=text_cap) if telemetry else None
+        self._emitter = (
+            TelemetryEmitter(telemetry, scope=self._scope, text_cap=text_cap) if telemetry else None
+        )
         self._telemetry = telemetry
         # 限流/熔断后端在此之外只以 QuotaGate/BreakerGate 的形态存在,自持一份
         # 引用才关得到自建的 redis 客户端(设计 §3.4)
@@ -176,8 +181,14 @@ class OcrClient:
         dimension_tenant_id, dimensions = validate_caller_dimensions(
             tenant_id, meta, origin="recognize_text(tenant_id=..., meta=...)"
         )
-        outcome = await self._call(
+        outcome, call_stats = await self._call(
-            "text", image, session_id, parent_call_id, dimension_tenant_id, dimensions
+            "text",
+            "recognize_text",
+            image,
+            session_id,
+            parent_call_id,
+            dimension_tenant_id,
+            dimensions,
         )
         result = outcome.result
         return OcrTextResult(
@@ -187,6 +198,7 @@ class OcrClient:
             latency_ms=outcome.latency_ms,
             call_id=outcome.call_id,
             raw=result.raw,
+            call_stats=call_stats,
         )
 
     async def parse_layout(
@@ -206,8 +218,14 @@ class OcrClient:
         dimension_tenant_id, dimensions = validate_caller_dimensions(
             tenant_id, meta, origin="parse_layout(tenant_id=..., meta=...)"
         )
-        outcome = await self._call(
+        outcome, call_stats = await self._call(
-            "layout", image, session_id, parent_call_id, dimension_tenant_id, dimensions
+            "layout",
+            "parse_layout",
+            image,
+            session_id,
+            parent_call_id,
+            dimension_tenant_id,
+            dimensions,
         )
         result = outcome.result
         return OcrLayoutResult(
@@ -218,6 +236,7 @@ class OcrClient:
             latency_ms=outcome.latency_ms,
             call_id=outcome.call_id,
             raw=result.raw,
+            call_stats=call_stats,
         )
 
     async def check_health(self) -> dict[str, bool]:
@@ -237,16 +256,60 @@ class OcrClient:
     async def _call(
         self,
         kind: _OcrKind,
+        operation: CallOperation,
         image: bytes,
         session_id: str | None,
         parent_call_id: str | None,
         tenant_id: str | None,
         meta: dict[str, Any],
-    ) -> _AttemptOutcome:
+    ) -> tuple[_AttemptOutcome, CallStats]:
         if not isinstance(image, bytes):
             raise TypeError("image 必须是 bytes(路径读取/批量拼帧留业务侧,D9)")
         if not image:
             raise ValueError("image 不能为空")
+        # M1 例外: `image` 校验在 `_call` 内而非公开方法,故上下文在该校验
+        # **通过之后**创建——这样设计 §3 的"校验在统计边界外"对 OCR 才成立
+        context = _CallContext(now=self._now)
+        try:
+            return await self._run(
+                kind, operation, image, session_id, parent_call_id, tenant_id, meta, context
+            )
+        except PolyGatewayError as exc:
+            await self._emit_terminal(
+                kind, operation, image, session_id, parent_call_id, tenant_id, meta, context, exc
+            )
+            raise
+        except asyncio.CancelledError:
+            # 三条链路同一口径尽力写一条(允许 0 条);取消优先,不 shield
+            await self._emit_terminal(
+                kind,
+                operation,
+                image,
+                session_id,
+                parent_call_id,
+                tenant_id,
+                meta,
+                context,
+                "cancelled",
+            )
+            raise
+
+    async def _run(
+        self,
+        kind: _OcrKind,
+        operation: CallOperation,
+        image: bytes,
+        session_id: str | None,
+        parent_call_id: str | None,
+        tenant_id: str | None,
+        meta: dict[str, Any],
+        context: _CallContext,
+    ) -> tuple[_AttemptOutcome, CallStats]:
+        """选源与重试循环。
+
+        无源的 raise 必须在本方法内(而非循环之前的调用方): 它得被 `_call` 的
+        `try` 包住,否则无源终态行根本写不出来(设计 §3.5)。
+        """
         if not self._sources:
             raise AllSourcesExhausted(scope=self._scope, reason="no_sources", retry_after_s=0.0)
         fails = 0
@@ -260,10 +323,19 @@ class OcrClient:
                 continue
             async with clock.attempting():
                 outcome = await self._attempt(
-                    kind, image, *picked, reasons, session_id, parent_call_id, tenant_id, meta
+                    kind,
+                    operation,
+                    image,
+                    *picked,
+                    reasons,
+                    session_id,
+                    parent_call_id,
+                    tenant_id,
+                    meta,
+                    context,
                 )
             if isinstance(outcome, _AttemptOutcome):
-                return outcome
+                return outcome, context.snapshot()
             fails += 1
             if fails >= self._retry.max_attempts:
                 raise AllSourcesExhausted(
@@ -278,6 +350,7 @@ class OcrClient:
     async def _attempt(
         self,
         kind: _OcrKind,
+        operation: CallOperation,
         image: bytes,
         source: SourceConfig,
         permit: Permit,
@@ -287,11 +360,14 @@ class OcrClient:
         parent_call_id: str | None,
         tenant_id: str | None,
         meta: dict[str, Any],
+        context: _CallContext,
     ) -> _AttemptOutcome | _FailedAttempt:
         call_id = str(uuid.uuid4())
         started = self._now()
         # 四个 emit 分支(成功/终态拒绝/取消/可重试失败)都必须带调用方维度:
         # 失败行与取消行同样需要租户归属,漏掉任一分支就会写出无归属的行
+        # layout 的 POST + ZIP GET 在同一次 `_invoke` 内,故这里只登记 **1** 次
+        context.register_attempt()
         try:
             result = await self._invoke(kind, image, source, call_id)
             await self._record_quietly(self._breaker.record_success(entry))
@@ -300,6 +376,7 @@ class OcrClient:
             latency_ms = int((self._now() - started) * 1000)
             await self._emit(
                 kind,
+                operation,
                 image,
                 source,
                 call_id,
@@ -308,6 +385,7 @@ class OcrClient:
                 parent_call_id,
                 tenant_id,
                 meta,
+                context,
                 result,
             )
             return _AttemptOutcome(result, source, call_id, latency_ms)
@@ -315,6 +393,7 @@ class OcrClient:
             await self._gate_on_terminal(exc, entry)
             await self._emit(
                 kind,
+                operation,
                 image,
                 source,
                 call_id,
@@ -323,6 +402,7 @@ class OcrClient:
                 parent_call_id,
                 tenant_id,
                 meta,
+                context,
                 error=exc,
             )
             raise
@@ -331,6 +411,7 @@ class OcrClient:
                 await self._record_quietly(self._breaker.release_probe(entry))
             await self._emit(
                 kind,
+                operation,
                 image,
                 source,
                 call_id,
@@ -339,6 +420,7 @@ class OcrClient:
                 parent_call_id,
                 tenant_id,
                 meta,
+                context,
                 error="cancelled",
             )
             raise
@@ -350,6 +432,7 @@ class OcrClient:
             self._feed_outcome(source.name, ok=False)
             await self._emit(
                 kind,
+                operation,
                 image,
                 source,
                 call_id,
@@ -358,6 +441,7 @@ class OcrClient:
                 parent_call_id,
                 tenant_id,
                 meta,
+                context,
                 error=exc,
             )
             return _FailedAttempt(exc, immediate=dead)
@@ -399,9 +483,60 @@ class OcrClient:
         except (GovernanceBackendError, SourceNotConfiguredError) as exc:
             logger.warning("OCR 治理记账写回降级(不冒泡): {}", exc)
 
+    def _request_for(
+        self,
+        kind: _OcrKind,
+        image: bytes,
+        session_id: str | None,
+        parent_call_id: str | None,
+        tenant_id: str | None,
+        meta: dict[str, Any],
+        context: _CallContext,
+    ) -> ChatRequest:
+        """OCR 行的现场 ChatRequest: 占位摘要,**图像 bytes 永不入库**。
+
+        尝试行与终态行共用同一个构造点: 占位字面量复制成两份就会漂移。
+        调用方维度与上下文必须显式填回(OCR 不走 chat 洋葱),否则 OCR 行的
+        维度恒为空、`logical_call_id` 恒为 NULL。
+        """
+        return ChatRequest(
+            messages=[{"role": "user", "content": f"<ocr:{kind} image_bytes={len(image)}>"}],
+            session_id=session_id,
+            parent_call_id=parent_call_id,
+            tenant_id=tenant_id,
+            meta=meta,
+            call_context=context,
+        )
+
+    async def _emit_terminal(
+        self,
+        kind: _OcrKind,
+        operation: CallOperation,
+        image: bytes,
+        session_id: str | None,
+        parent_call_id: str | None,
+        tenant_id: str | None,
+        meta: dict[str, Any],
+        context: _CallContext,
+        error: PolyGatewayError | str,
+    ) -> None:
+        """终态行: 沿用 `<ocr:{kind} image_bytes=…>` 占位,错误文本保留类名前缀。"""
+        await emit_terminal_once(
+            self._emitter,
+            request=self._request_for(
+                kind, image, session_id, parent_call_id, tenant_id, meta, context
+            ),
+            context=context,
+            error=error,
+            operation=operation,
+            # metric ocr-call-success 的注册口径是按类名归组,终态行同款保留
+            class_prefixed_error=True,
+        )
+
     async def _emit(
         self,
         kind: _OcrKind,
+        operation: CallOperation,
         image: bytes,
         source: SourceConfig,
         call_id: str,
@@ -410,20 +545,15 @@ class OcrClient:
         parent_call_id: str | None,
         tenant_id: str | None,
         meta: dict[str, Any],
+        context: _CallContext,
         result: OcrTextTransportResult | OcrLayoutTransportResult | None = None,
-        error: object | None = None,
+        error: PolyGatewayError | str | None = None,
     ) -> None:
         """逐尝试遥测(单一 Emitter): messages 占位摘要,图像 bytes 绝不入库。"""
         if self._emitter is None:
             return
-        # 这个 ChatRequest 只为复用同一个 Emitter 而现场构造(OCR 不走 chat 洋葱),
+        request = self._request_for(
-        # 故调用方维度必须在这里显式填回,否则 OCR 行的维度恒为空
+            kind, image, session_id, parent_call_id, tenant_id, meta, context
-        request = ChatRequest(
-            messages=[{"role": "user", "content": f"<ocr:{kind} image_bytes={len(image)}>"}],
-            session_id=session_id,
-            parent_call_id=parent_call_id,
-            tenant_id=tenant_id,
-            meta=meta,
         )
         latency_ms = int((self._now() - started) * 1000)
         response = None
@@ -443,18 +573,19 @@ class OcrClient:
                 source_name=source.name,
                 usage_source="measured",
             )
-        # 错误带异常类名前缀(metric ocr-call-success 注册口径: 按类名归组)
+        # 错误文本的类名前缀现由出口的显式策略参数承担(设计 §6 I7):
-        if error is None or isinstance(error, str):
+        # 三处各拼一遍才是下一次漂移的种子,而取消行传的是字符串,不受前缀影响
-            error_text = error
-        else:
-            error_text = f"{type(error).__name__}: {error}"
         await self._emitter.emit_attempt(
             request=request,
             source=source,
             call_id=call_id,
             latency_ms=latency_ms,
             response=response,
-            error=error_text,
+            error=error,
+            # OCR 走 MonkeyOCR 自有端点,没有推理参数可言(理由同 embedding)
+            reasoning_applies=False,
+            operation=operation,
+            class_prefixed_error=True,
         )
 
     @staticmethod

src/polygateway/ports.py

@@ -12,6 +12,7 @@ from typing import Any, Protocol, runtime_checkable
 
 from .types import (
     ChatRequest,
+    Effort,
     EmbeddingTransportResult,
     LLMResponse,
     OcrLayoutResult,
@@ -36,7 +37,16 @@ class Middleware(Protocol):
 
 @runtime_checkable
 class Transport(Protocol):
-    """一次原始调用的协议细节(请求组装/流式解析/错误翻译);不含任何治理。"""
+    """一次原始调用的协议细节(请求组装/流式解析/错误翻译);不含任何治理。
+
+    `reasoning_effort` 是本次调用要求的推理档位(`None` = 不表态,随源级配置)。
+    它必须走**协议参数**而不能让 transport 自己去读 `ChatRequest`: 端口只收拆开的
+    请求要素,是为了让 transport 不依赖洋葱内部的请求类型(P7 端口最内层)。
+
+    该参数**不设默认值**,与 `TelemetryRecorder.record_llm_call` 同一既有约定:
+    库外无第三方实现者,写全签名的成本为零,而默认值会把"某一层漏传"变成静默的
+    "调用方没表态"——一次本该报错的漏配就此变成一次悄悄涨价的调用。
+    """
 
     async def complete(
         self,
@@ -46,6 +56,7 @@ class Transport(Protocol):
         stream: bool,
         overlay: dict[str, Any],
         call_id: str,
+        reasoning_effort: Effort | None,
     ) -> TransportResult: ...
 
 
@@ -260,7 +271,7 @@ class TelemetryStatusProvider(Protocol):
 
 @runtime_checkable
 class TelemetryRecorder(Protocol):
-    """遥测后端;25 字段冻结(M1 设计 §4.4 + issue #3/#4/#11/#16),唯一调用点是 TelemetryEmitter。
+    """遥测后端;36 字段冻结(M1 设计 §4.4 + issue #3/#4/#11/#16/#20 + 1.3.5),唯一调用点是 TelemetryEmitter。
 
     新增参数不设默认值: 库外无第三方实现者(三项目迁移时删除了各自的同名
     Protocol),完整签名的成本为零,而少写一列会被 emitter 的降级吞成 warning。
@@ -270,8 +281,20 @@ class TelemetryRecorder(Protocol):
     `thinking_observation` 同理: emitter 已把 `ThinkingObservation` 取成 `.value`
     的裸 `str`(`StrEnum` 是 `str` 子类,而 asyncpg 的参数编码对子类不保证接受,
     遥测写失败又只降级成 warning——PG 那一路会静默少一列数据)。
+    `reasoning_effort` 同一先例(issue #20): emitter 已把 `Effort` 取成 `.value`
+    的裸 `str`,`None` 表示调用方没表态——它与 `'none'`(明确要求不推理)不可折叠。
+
     recorder 只负责落库,不做任何语义判断,与 `sampling` 列由
     `canonical_sampling_json()` 在 emitter 侧定型是同一先例。
+
+    1.3.5 新增十列同理已在 emitter 侧定型: `operation` 是**公开方法**四值之一
+    (与 `PolyGatewayError.operation` 这个 HTTP 子操作是两个语义);`event_kind` 区分
+    attempt / cache_hit / terminal_failure 三类行;`attempts` 与 `total_latency_ms`
+    只在终态行非空;`error_body` 沿用 transport 侧 `summarize_body` 的上限,
+    **不进 `PGW_TELEMETRY_TEXT_CAP` 的覆盖面**。
+
+    **本签名是装配闸的唯一事实源**: `TelemetryEmitter.__init__` 按它派生参数名做
+    一次 `signature.bind` 形状校验(设计 §7),改本签名即改闸的判据。
     """
 
     async def record_llm_call(
@@ -302,4 +325,15 @@ class TelemetryRecorder(Protocol):
         tenant_id: str,
         meta: str,
         thinking_observation: str,
+        reasoning_effort: str | None,
+        scope: str,
+        operation: str,
+        logical_call_id: str | None,
+        event_kind: str,
+        http_status_code: int | None,
+        error_type: str | None,
+        cause_type: str | None,
+        error_body: str | None,
+        attempts: int | None,
+        total_latency_ms: int | None,
     ) -> None: ...

src/polygateway/providers.py

@@ -14,75 +14,146 @@ from types import MappingProxyType
 from typing import Any
 
 
+@dataclass(frozen=True)
+class ThinkingWire:
+    """一个 provider 表达"开/关/多深"的请求体形态(设计 §3.3)。
+
+    三个字段各自的 `None` **语义互不重叠**,混淆任意两个都会退回 issue #5 修掉的
+    那种静默失效:
+
+    ==============  ==========================================================
+    ``on_base=None``  **形态未知**: 本库不知道该 provider 如何表达"开",配了开关
+                      即装配期报错并指路 `register_provider`/`extra_body`
+    ``off=None``      已知开启形态,但**没有关闭形态**(该 provider 关不掉)
+    ``effort_key``    ``None`` = 该 provider 只有开关、没有档位(qwen 系靠
+      ``=None``       ``thinking_budget`` 调深度,不是档位)
+    ==============  ==========================================================
+
+    `on_base={}` 与 `on_base=None` 不可混: 前者是协议无需额外开启字节，
+    是否满足 AUTO 由模型能力清单决定；后者是“不知道怎么表达”。
+
+    **为什么不是 cherry-studio 那套 wire DSL**: 它要支持 openai-chat /
+    openai-responses / anthropic-messages / google-generate-content 四种端点协议,
+    故需要 closed operation 集合与 `budgetWire` 代际变体。本库只有一个 OpenAI 兼容
+    transport,跨协议转换由 new-api 在服务端完成(它自己就有一层 canonical intent),
+    一个协议一层形态即够(P1 YAGNI)。
+    """
+
+    off: Mapping[str, Any] | None
+    on_base: Mapping[str, Any] | None
+    effort_key: str | None
+
+
 @dataclass(frozen=True)
 class ProviderProfile:
     """单个 provider 的能力与差异声明。
 
-    thinking_on/thinking_off 分别是 `SourceConfig.enable_thinking` 为
+    `thinking` 声明推理参数的**形态**(按 provider 变,数年不变一次);
-    True/False 时并入请求体的参数片段(`enable_thinking` 为 None 时二者都不
+    `strip_think_tags` 声明响应 content 需剥离 ``<think>`` 标签(qwen 系);
-    注入,用模型默认);strip_think_tags 声明响应 content 需剥离 ``<think>``
+    `supports_native_schema` 供 D14 阶梯选择原生 response_format。
-    标签(qwen 系);supports_native_schema 供 D14 阶梯选择原生 response_format。
 
-    两档各有三种取值,**语义互不重叠**(issue #5):
+    注: 本类只声明**形态**(参数长什么样,按 provider 变);某个具体模型支持哪些
-
+    档位属**能力**(按 model 变),见 `thinking.ThinkingCapability`。二者合一在
-    ==========  ==========================================================
+    provider 级表达不了代际差异——glm-5.2 能关而 glm-5.3 不能,形态却完全相同。
-    ``{...}``   已知的注入片段
-    ``{}``      已知**无需注入**任何参数即处于该档
-    ``None``    **未知**: 本库不知道该 provider 如何表达这一档
-    ==========  ==========================================================
-
-    `None` 与 `{}` 必须分开: 二者曾同为空字典,导致 `enable_thinking=False`
-    对 minimax/openai 源静默失效——调用方以为关掉了推理,实际什么都没发生。
-    现在 `None` 会在装配期显式报错并指路 `register_provider` / `extra_body`。
-
-    注: 本类只声明**形态**(参数长什么样,按 provider 变);某个具体模型能否
-    关闭推理属**能力**(按 model 变),见 `ThinkingCapability`。
     """
 
     name: str
-    thinking_on: Mapping[str, Any] | None
+    thinking: ThinkingWire
-    thinking_off: Mapping[str, Any] | None
     strip_think_tags: bool
     supports_native_schema: bool = False
 
 
+# 经 new-api 中转的口径。四家参考实现(cherry-studio / OpenRouter / LiteLLM /
+# new-api 自身)一致的结论: OpenAI 兼容端点上,档位一律走标准的 `reasoning_effort`,
+# 跨协议转换(→ Claude 的 thinking、Gemini 的 thinkingConfig)由网关服务端完成。
 DEFAULT_PROFILES: Mapping[str, ProviderProfile] = MappingProxyType(
     {
         # 注入片段出处: VT llm.py:130-144(开启形态)与 CHS invokers.py:230-238(关闭形态)
         "qwen": ProviderProfile(
             name="qwen",
-            thinking_on={"enable_thinking": True},
+            thinking=ThinkingWire(
-            thinking_off={"enable_thinking": False},
+                off={"enable_thinking": False},
+                on_base={"enable_thinking": True},
+                # 百炼的深度控制是 `thinking_budget`(token 预算)而非档位;
+                # 预算型控制本库当前不支持(设计 §11 明确不做)
+                effort_key=None,
+            ),
             strip_think_tags=True,
         ),
+        # 官方 thinking_mode 文档: thinking:{type} 是开关,reasoning_effort 是深度,
+        # V4 一代两者并用(deepseek-v4-* 的档位见能力表)
         "deepseek": ProviderProfile(
             name="deepseek",
-            thinking_on={"thinking": {"type": "enabled"}},
+            thinking=ThinkingWire(
-            thinking_off={"thinking": {"type": "disabled"}},
+                off={"thinking": {"type": "disabled"}},
+                on_base={"thinking": {"type": "enabled"}},
+                effort_key="reasoning_effort",
+            ),
             strip_think_tags=False,
         ),
-        # OpenAI 兼容基线段名: 实践中被复用为**任意**兼容厂商的兜底(下游把
+        # issue #20。智谱官方迁移建议原文: 原先用 {"type":"disabled"} 的应改为
-        # kimi-k3 挂在 provider=openai 下),故不能下发任何厂商方言参数——发给
+        # {"type":"enabled"} + reasoning_effort="low"——GLM-5.3 起 thinking.type
-        # 不认识它的厂商会 400。两档标 None(未知): 配了 enable_thinking 即在
+        # 不再接受 disabled,故"关"这一档由能力表按型号裁定(5.2 能关,5.3 不能)
-        # 装配期报错并指路,真 OpenAI 推理模型的用户走 register_provider
+        "zhipu": ProviderProfile(
-        "openai": ProviderProfile(
+            name="zhipu",
-            name="openai",
+            thinking=ThinkingWire(
-            thinking_on=None,
+                off={"thinking": {"type": "disabled"}},
-            thinking_off=None,
+                on_base={"thinking": {"type": "enabled"}},
+                effort_key="reasoning_effort",
+            ),
             strip_think_tags=False,
         ),
-        # 注入形态出处: 2026-08-02 经自建 new-api 中转实测(findings §2),
+        # kimi-k3 的档位是 low/high/max;thinking.type 为月之暗面的开关形态
-        # 2026-08-25 复测结论不变(findings 2026-08-25 §5);**直连官方端点未验证**。
+        "moonshot": ProviderProfile(
-        # 实测 enable_thinking / thinking 两种写法均被静默丢弃(prompt_tokens
+            name="moonshot",
-        # 恒定等于基线 194),reasoning_effort 才是真开关——本片段的选型据此成立。
+            thinking=ThinkingWire(
-        # "开"取 medium: qwen 的 enable_thinking:true 与 deepseek 的
+                off={"thinking": {"type": "disabled"}},
-        # thinking:{enabled} 都不指定预算、由模型自定,medium 是五档里语义最接近
+                on_base={"thinking": {"type": "enabled"}},
-        # "厂商正常强度"的一档;取 high 等于替下游做"加钱换质量"的业务判断。
+                effort_key="reasoning_effort",
-        # 要精确控制档位经 `SourceConfig.extra_body`(优先级高于本片段)
+            ),
+            strip_think_tags=False,
+        ),
+        # 2026-08-02 经 new-api 中转实测(findings §2),2026-08-25 复测结论不变。
+        # enable_thinking / thinking 两种写法均被静默丢弃(prompt_tokens 恒等于基线
+        # 194),reasoning_effort 才是真开关——本段形态据此成立。
+        # 开启片段不代选强度；AUTO 可满足性由具体模型能力清单决定。
         "minimax": ProviderProfile(
             name="minimax",
-            thinking_on={"reasoning_effort": "medium"},
+            thinking=ThinkingWire(
-            thinking_off={"reasoning_effort": "none"},
+                off={"reasoning_effort": "none"},
+                on_base={},
+                effort_key="reasoning_effort",
+            ),
+            strip_think_tags=False,
+        ),
+        # OpenAI 兼容基线段名: 实践中被复用为**任意**兼容厂商的兜底。两档此前标
+        # None(未知),因为当时无法区分"厂商方言"与"标准字段";`reasoning_effort`
+        # 是 OpenAI **官方**字段而非方言,发给经网关的兼容端点不会打到不认识它的
+        # 厂商,故 2026-09-04 起给出标准形态。真正形态未知的 provider 仍走
+        # register_provider 注册,而不是挂在本段下
+        "openai": ProviderProfile(
+            name="openai",
+            thinking=ThinkingWire(
+                off={"reasoning_effort": "none"}, on_base={}, effort_key="reasoning_effort"
+            ),
+            strip_think_tags=False,
+        ),
+        # Claude 5 系原生是 thinking.type=adaptive + output_config.effort,Gemini 3 系
+        # 原生是 thinkingConfig.thinkingLevel;两者的代际方言(Claude ≤4.5 的
+        # budget_tokens、Gemini 2.x 的 thinkingBudget)由 new-api 的 canonical intent
+        # 层吸收,本库只发 OpenAI 形态(设计 §3.4)
+        "anthropic": ProviderProfile(
+            name="anthropic",
+            thinking=ThinkingWire(
+                off={"reasoning_effort": "none"}, on_base={}, effort_key="reasoning_effort"
+            ),
+            strip_think_tags=False,
+        ),
+        "google": ProviderProfile(
+            name="google",
+            thinking=ThinkingWire(
+                off={"reasoning_effort": "none"}, on_base={}, effort_key="reasoning_effort"
+            ),
             strip_think_tags=False,
         ),
     }

src/polygateway/telemetry/schema.py

@@ -5,8 +5,8 @@
 多处各存一份必然漂移,而漂移的表现是"下游照打印的 SQL 建完表,库仍报缺列"。
 
 **`COLUMNS` 是 INSERT 字段序,不是物理列序**: 数据库自填的 `created_at` 不在其中(它带
-`DEFAULT now()` / `datetime('now')`,库从不显式写它)。物理表列 = 25 个 INSERT 字段 +
+`DEFAULT now()` / `datetime('now')`,库从不显式写它)。物理表列 = 36 个 INSERT 字段 +
-`created_at` = 26;列数断言一律按物理列数写,两套口径混用是最易错处。
+`created_at` = 37;列数断言一律按物理列数写,两套口径混用是最易错处。
 
 本模块只依赖标准库: `telemetry/` 与 `backends/`、`transports/`、`structured/` 同层且
 互不依赖(import-linter 契约执法)。
@@ -51,7 +51,18 @@ CREATE TABLE IF NOT EXISTS llm_calls (
     reasoning_tokens     INTEGER,
     tenant_id            TEXT    NOT NULL DEFAULT '',
     meta                 TEXT    NOT NULL DEFAULT '{}',
-    thinking_observation TEXT
+    thinking_observation TEXT,
+    reasoning_effort     TEXT,
+    scope                TEXT,
+    operation            TEXT,
+    logical_call_id      TEXT,
+    event_kind           TEXT,
+    http_status_code     INTEGER,
+    error_type           TEXT,
+    cause_type           TEXT,
+    error_body           TEXT,
+    attempts             INTEGER,
+    total_latency_ms     INTEGER
 );
 """
 
@@ -82,7 +93,18 @@ CREATE TABLE IF NOT EXISTS llm_calls (
     reasoning_tokens     INTEGER,
     tenant_id            TEXT NOT NULL DEFAULT '',
     meta                 JSONB NOT NULL DEFAULT '{}'::jsonb,
-    thinking_observation TEXT
+    thinking_observation TEXT,
+    reasoning_effort     TEXT,
+    scope                TEXT,
+    operation            TEXT,
+    logical_call_id      TEXT,
+    event_kind           TEXT,
+    http_status_code     INTEGER,
+    error_type           TEXT,
+    cause_type           TEXT,
+    error_body           TEXT,
+    attempts             INTEGER,
+    total_latency_ms     INTEGER
 );
 """
 
@@ -100,6 +122,21 @@ SQLITE_BACKFILL = (
     # 可空: 补列之前的行没有裁定结果,NULL 如实表达"这行根本没记过这件事",
     # 与哨兵串 'unknown'(库确实裁过但判不出来)是两回事,不得混同
     ("thinking_observation", "TEXT"),
+    # 同样可空,但这里 NULL 表达的是"调用方没表态"(issue #20): 它与 'none'
+    # (明确要求不推理)是两回事,折叠成任一档都等于替上游声称了它没说过的事
+    ("reasoning_effort", "TEXT"),
+    # 1.3.5 十列: 全部可空且无默认值——旧行的 NULL 表达的是"补列之前根本没记过
+    # 这件事",与任何哨兵值都不是一回事,故不回填(设计 §5)
+    ("scope", "TEXT"),
+    ("operation", "TEXT"),
+    ("logical_call_id", "TEXT"),
+    ("event_kind", "TEXT"),
+    ("http_status_code", "INTEGER"),
+    ("error_type", "TEXT"),
+    ("cause_type", "TEXT"),
+    ("error_body", "TEXT"),
+    ("attempts", "INTEGER"),
+    ("total_latency_ms", "INTEGER"),
 )
 
 # PG 补列的列定义。语句由此派生成两份文本(见下),使"库内执行的那份"与"打印给
@@ -114,6 +151,18 @@ _PG_BACKFILL_DECLS = (
     ("meta", "JSONB NOT NULL DEFAULT '{}'::jsonb"),
     # 可空,理由同 SQLITE_BACKFILL 同名项
     ("thinking_observation", "TEXT"),
+    ("reasoning_effort", "TEXT"),
+    # 1.3.5 十列,列序与 SQLITE_BACKFILL 逐项对齐(两条路径的物理列序不许分叉)
+    ("scope", "TEXT"),
+    ("operation", "TEXT"),
+    ("logical_call_id", "TEXT"),
+    ("event_kind", "TEXT"),
+    ("http_status_code", "INTEGER"),
+    ("error_type", "TEXT"),
+    ("cause_type", "TEXT"),
+    ("error_body", "TEXT"),
+    ("attempts", "INTEGER"),
+    ("total_latency_ms", "INTEGER"),
 )
 
 # 新列排在 created_at 之后: 与旧表 ALTER 追加的位置一致(见 SQLITE_BACKFILL 同款注释)。
@@ -151,6 +200,18 @@ COLUMNS = (
     "tenant_id",
     "meta",
     "thinking_observation",
+    "reasoning_effort",
+    # —— 1.3.5 逻辑调用统计与结构化失败诊断(issue #19/#23)——
+    "scope",
+    "operation",
+    "logical_call_id",
+    "event_kind",
+    "http_status_code",
+    "error_type",
+    "cause_type",
+    "error_body",
+    "attempts",
+    "total_latency_ms",
 )
 
 _COLUMN_SET = frozenset(COLUMNS)

src/polygateway/telemetry/sqlite.py

@@ -143,7 +143,7 @@ class SQLiteRecorder:
                     logger.warning("SQLite 遥测补列失败(写入将逐行降级): {}", exc)
 
     async def record_llm_call(self, **fields: object) -> None:
-        """写一行遥测;字段集合即 25 字段冻结签名(ports.TelemetryRecorder)。
+        """写一行遥测;字段集合即 36 字段冻结签名(ports.TelemetryRecorder)。
 
         取值按 `self._columns`(manual 档可能已被裁剪),与 `self._insert` 的
         占位符同序——两者必须一起改,分开改就是把值写进错位的列。

src/polygateway/thinking.py

@@ -14,8 +14,8 @@ from typing import Any
 
 from loguru import logger
 
-from polygateway.providers import ProviderProfile
+from polygateway.providers import ProviderProfile, ThinkingWire
-from polygateway.types import ThinkingObservation
+from polygateway.types import EFFORT_ORDER, Effort, ThinkingObservation, coerce_effort
 
 
 def observe_thinking(*, thinking: str, reasoning_tokens: int | None) -> ThinkingObservation:
@@ -54,50 +54,314 @@ class ThinkingUnsupportedError(ValueError):
 
 @dataclass(frozen=True)
 class ThinkingCapability:
-    """某个**具体模型**能否关闭推理(issue #5);登记必须附实测证据与日期。
+    """某个**具体模型**支持哪些推理档位(设计 §3.2);登记必须附证据与日期。
 
     与 `ProviderProfile` 的分工: 后者声明**形态**(参数长什么样,按 provider 变,
     数年不变一次),本类声明**能力**(按 model 变,同一 provider 每代都变)。二者
     合一在 provider 级表达不了代际差异——实测 MiniMax-M3 可关闭推理,而同厂的
     M2.7/M2.5 三种参数形态全部无效(findings §2.3),profile 一格管不住三个模型。
 
+    **档位清单而非布尔**(2026-09-04): 旧版是 `can_disable: bool`,表达不了
+    "关不掉但能调到最低档"这第三种情况——而 GLM-5.3 系与 Gemini 3 Pro 都是它。
+    现在"能不能关"就是 `Effort.NONE` 在不在清单里,是派生量而非独立字段;三个
+    派生量一律不存字段,存了必与清单漂移。
+
     `evidence` 不是装饰: 能力表过期是必然事件,没有出处就无从判断该不该信它。
+    文档推定与实测必须在 evidence 里说清楚是哪种——前者会被 new-api 中转改写
+    (LiteLLM 里同一个 kimi-k3 在 `moonshot/` 下三档、`perplexity/` 下六档)。
     """
 
-    can_disable: bool
+    supported_efforts: tuple[Effort, ...]
     evidence: str
 
+    def __post_init__(self) -> None:
+        """构造期校验: 空清单与重复档都是登记错误,不能等到请求期才炸。"""
+        if not self.supported_efforts:
+            raise ValueError("supported_efforts 至少要有一档: 空清单表达不了任何能力")
+        if len(set(self.supported_efforts)) != len(self.supported_efforts):
+            raise ValueError(f"supported_efforts 有重复档: {self.supported_efforts}")
+
+    @property
+    def can_disable(self) -> bool:
+        """能否关闭推理 = `none` 在不在清单里(旧 `can_disable` 字段的等价物)。"""
+        return Effort.NONE in self.supported_efforts
+
+    @property
+    def cheapest_effort(self) -> Effort | None:
+        """除 `none` 外最省的一档;关不掉时作为**可执行替代**推荐给调用方。
+
+        `AUTO` 参与候选(纯开关型模型只有它可推荐),但因不在 `EFFORT_ORDER` 中,
+        仅当没有任何强度档时才被选中。全清单只有 `none` 时返回 None——那种模型
+        没有"最省的开启档"可言。
+        """
+        tiers = [e for e in EFFORT_ORDER if e is not Effort.NONE and e in self.supported_efforts]
+        if tiers:
+            return tiers[0]
+        return Effort.AUTO if Effort.AUTO in self.supported_efforts else None
+
+    @property
+    def is_tiered(self) -> bool:
+        """是否档位型(除 `none`/`auto` 外仍有强度档)。
+
+        用途是**告警文案**: 对纯开关型模型说"可选档位: ..."是错的,它没有档位。
+        """
+        return any(e not in (Effort.NONE, Effort.AUTO) for e in self.supported_efforts)
+
+
+# 证据分三类,evidence 里必须自报家门:
+#   实测 = 经 new-api 中转打过真实请求(最硬,不得被文档推定覆盖);
+#   文档推定 = 官方文档 / OpenRouter / cherry-studio / LiteLLM 四方交叉;
+#   实测未覆盖 = T10 试过但拿不到数据(渠道限额/上游报错/被路由到别的模型),
+#     此时**必须写明原因**——"没测到"与"测了没问题"是两回事,T9 之类的下游
+#     文档任务不得把前者写成后者。
+_MEASURED = "2026-08-02 经 new-api 中转实测"
+_T10 = "2026-09-05 经 new-api 中转实测(T10: 短提示词 N=5,声称可关的再加长上下文 N=3 复核)"
+_DOC = "2026-09-04 文档推定(官方文档 + OpenRouter + cherry-studio + LiteLLM 四方交叉)"
+
+# T10 的三条判据(报告见 tests/outputs/thinking/,用例见 tests/e2e/test_thinking_live.py):
+#   ① 关闭方向要求**每轮**未观测到推理,任一轮观测到即证伪;
+#   ② 短提示词下的"关掉了"必须过长上下文复核——glm-5.3-flash 正是短提示词 5/5
+#      未观测到推理、5000 token 长上下文下 2/3 轮露馅(issue #20 的原始现象);
+#   ③ 上游整片不回传推理信号(kimi/MiniMax/qwen/gpt 这几路的关闭档都是)时,
+#      "没看见"不算"没发生",另取一个无魔数锚点: 关闭档的 completion_tokens
+#      必须严格小于 max 档。
 
 DEFAULT_CAPABILITIES: Mapping[str, ThinkingCapability] = MappingProxyType(
     {
+        # —— MiniMax ——
         "MiniMax-M3": ThinkingCapability(
-            can_disable=True,
+            supported_efforts=(
+                Effort.NONE,
+                Effort.MINIMAL,
+                Effort.LOW,
+                Effort.MEDIUM,
+                Effort.HIGH,
+                Effort.XHIGH,
+                Effort.MAX,
+            ),
             evidence=(
-                "2026-08-02 经 new-api 中转实测 N=10: reasoning_effort=none 稳定关闭,零跳变;"
+                f"{_T10}: reasoning_effort=none 关闭成立(短 5/5 + 长上下文 3/3 未观测到推理,"
-                "2026-08-25 复测依然成立(prompt 194 = 基线、completion 3、无推理正文)。"
+                "completion 恒 3 token,且与 max 档 completion 57-173 锚点可分);六个强度值各 N=5 "
-                "两条限制(findings 2026-08-25-thinking-observability-regression §3.1/§5): "
+                "全部观测到推理,rt 分布完全重叠(minimal 64-124 / low 55-112 / medium 51-104 / "
-                "① 非流式路径观测不到推理信号——推理已计费,但正文与 usage 明细都不回传;"
+                "high 62-128 / xhigh 58-118 / max 57-170)——**它们是'开'的六种写法,不是六个深度档**,"
-                "② enable_thinking / thinking:{type:enabled} 对本模型无效,仅 reasoning_effort 是真开关"
+                "MiniMax 官方只有开/关两态,配哪一个都一样贵。"
+                "**`auto` 已从清单移除**: 实测当时 minimax 的「开」在 wire 上是 on_base={}"
+                "(什么参数都不注入),而 M3 的默认档实测不推理,故 auto 在这条路上表达不了「开」"
+                "(N=5 全部未观测到推理)。`resolve_thinking` 的 Phase 5 无条件放行 auto,能力表"
+                "堵不住这条,故 2026-09-05 由 wire 侧兜住: on_base 改回 {'reasoning_effort': 'medium'},"
+                "存量 ENABLE_THINKING=true 恢复真开推理(权宜之计,正解见 issue #21)。"
+                "本清单仍不含 auto——它记的是实测结论,不随 wire 的权宜之计变动。"
+                f"历史: {_MEASURED} N=10 同样成立;enable_thinking / thinking:{{type}} 两种写法对本模型"
+                "无效,reasoning_effort 才是真开关(findings 2026-08-25 §3.1/§5)。"
+                "另: 2026-08-25 记录的'MiniMax 这一路已停报 completion_tokens_details'本次**不再成立**"
+                "——开启档 rt 有值,只有关闭档整片缺 details"
             ),
         ),
         "MiniMax-M2.7": ThinkingCapability(
-            can_disable=False,
+            supported_efforts=(Effort.AUTO,),
             evidence=(
-                "2026-08-02 实测 reasoning_effort=none / thinking:{disabled} / thinking:{adaptive} "
+                f"{_T10}: 请求 none 时 5/5 轮仍观测到推理(rt 100-161、推理正文 274-482 字符),"
-                "各 N=3 全部无效;OpenRouter 注册表登记 mandatory:true,models.dev 登记无控制手段"
+                "**关不掉**成立;auto 档 5/5 观测到推理。"
+                f"历史({_MEASURED}): reasoning_effort=none / thinking:{{disabled}} / thinking:{{adaptive}} "
+                "各 N=3 全部无效;OpenRouter 登记 mandatory:true,models.dev 登记无控制手段"
             ),
         ),
         "MiniMax-M2.5": ThinkingCapability(
-            can_disable=False,
+            supported_efforts=(Effort.AUTO,),
-            evidence="2026-08-02 实测同 M2.7: 三种形态各 N=3 全部无效;外部注册表同样登记为强制推理",
+            evidence=(
+                f"{_T10}: 请求 none 时 5/5 轮仍观测到推理(rt 104-158),**关不掉**成立;"
+                "auto 档 5/5 观测到推理(rt 121-245)。"
+                f"历史({_MEASURED}): 三种形态各 N=3 全部无效;外部注册表同样登记为强制推理"
             ),
+        ),
+        # —— qwen(百炼系,开关型) ——
         "qwen3.7-plus": ThinkingCapability(
-            can_disable=True,
+            supported_efforts=(Effort.NONE, Effort.AUTO),
-            evidence="2026-08-02 实测 enable_thinking=false 关闭(completion 5 token,无推理)",
+            evidence=(
+                f"{_T10}: none 关闭成立(短 5/5 + 长 3/3 未观测到推理,且与 auto 档 completion 锚点可分);"
+                "auto 档 5/5 观测到推理。无强度档: 该 provider 的 wire 没有 effort_key,请求 max 当场被库"
+                "拒(百炼靠 thinking_budget 调深度,预算型控制本库不支持)。"
+                f"历史({_MEASURED}): enable_thinking=false 关闭(completion 5 token)"
             ),
+        ),
+        "qwen3.7-max": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.AUTO),
+            evidence=f"{_T10}: 同 qwen3.7-plus——none 短 5/5 + 长 3/3 关闭且锚点可分,auto 档 5/5 观测到推理",
+        ),
+        "qwen3.6-plus": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.AUTO),
+            evidence=f"{_T10}: none 短 5/5 + 长 3/3 关闭且锚点可分,auto 档 5/5 观测到推理",
+        ),
+        "qwen3.5-flash": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.AUTO),
+            evidence=f"{_T10}: none 短 5/5 + 长 3/3 关闭且锚点可分,auto 档 5/5 观测到推理",
+        ),
+        "qwen-plus-latest": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.AUTO),
+            evidence=f"{_T10}: none 短 5/5 + 长 3/3 关闭且锚点可分,auto 档 5/5 观测到推理",
+        ),
+        # —— deepseek ——
         "deepseek-v4-pro": ThinkingCapability(
-            can_disable=True,
+            supported_efforts=(Effort.NONE, Effort.HIGH, Effort.MAX),
-            evidence="2026-08-02 实测 thinking:{type:disabled} 关闭(completion 3 token,无推理)",
+            evidence=(
+                f"{_T10}: none 关闭成立(短 5/5 + 长 3/3 未观测到推理,与 max 档锚点可分);"
+                "high / max 各 N=5 全部观测到推理(rt 59-73 / 56-69,推理正文 max 档明显更长: "
+                "135-186 vs 101-124 字符)。默认档按官方 thinking_mode 文档为 high"
+            ),
+        ),
+        "deepseek-v4-flash": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.HIGH, Effort.MAX),
+            evidence=(
+                f"{_T10}: none 关闭成立(短 5/5 + 长 3/3,锚点可分);high / max 各 N=5 全部观测到推理"
+                "(rt 16-36 / 12-42)。与 v4-pro 同档,印证官方'与 deepseek-v4-pro 一致'的说法"
+            ),
+        ),
+        "deepseek-v4-flash-vision-exp": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.HIGH, Effort.MAX),
+            evidence=(
+                f"{_T10}: none 关闭成立(短 5/5 + 长 3/3,锚点可分);high / max 各 N=5 全部观测到推理"
+                "(rt 12-17 / 17-34)"
+            ),
+        ),
+        # —— 智谱 ——
+        "glm-5.3": ThinkingCapability(
+            supported_efforts=(Effort.LOW, Effort.HIGH, Effort.MAX),
+            evidence=(
+                f"{_T10}: **推理不可关闭已实测坐实**——请求 none(注入 thinking:{{type:disabled}})后 "
+                "5 轮里 4 轮仍观测到推理(rt 7、推理正文 12 字符),只有 1 轮 rt=0;"
+                "low / high / max 各 N=5 全部观测到推理(rt 55-77 / 47-63 / 48-60,三档分不出深浅)。"
+                "这一条了结了 issue #20 的核心争议: 当时短提示词下 rt≈1.2 看着像关掉了,实为采样噪声。"
+                f"文档侧三源一致({_DOC}): 智谱官方 thinking.type 只接受 enabled、迁移建议改用 "
+                "enabled + reasoning_effort=low,cherry-studio 标 toggle:false,OpenRouter 标 mandatory:true。"
+                "默认 max。**注意本渠道不校验档位值**: 未登记的 medium 也会被照单接受(实测 rt 62),"
+                "故'网关没报错'在这一路上不构成'该档受支持'的证据"
+            ),
+        ),
+        "glm-5.3-flash": ThinkingCapability(
+            supported_efforts=(Effort.LOW, Effort.HIGH, Effort.MAX),
+            evidence=(
+                f"{_T10}: **推理不可关闭,且是判据②唯一的现役样本**——请求 none 时短提示词 5/5 轮"
+                "未观测到推理(看着完全像关掉了),换成 5000 token 长上下文后 3 轮里 2 轮露馅"
+                "(rt=2、有推理正文)。只跑短提示词的实测会在这个模型上得出相反结论。"
+                "low / high / max 各 N=5 全部观测到推理(rt 8-60 / 27-91 / 27-70)。默认 max"
+            ),
+        ),
+        "glm-5.2": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.HIGH, Effort.MAX),
+            evidence=(
+                f"{_DOC}: cherry-studio 登记 none/high/max(官方端点默认 max,百炼上默认 high)。"
+                "**T10 实测未覆盖——该渠道把本型号路由到了别的模型**: 请求 glm-5.2 时 5/5 轮回报 "
+                "model=glm-5.3(issue #20 记录的 6/6 复现),拿到的行为不属于本型号,故整组数据作废、"
+                "本行仍是文档推定。**下游风险**: 在本渠道上给 glm-5.2 配 none,库会照本行放行,"
+                "而真正服务请求的 glm-5.3 关不掉推理——运行期 reconcile 会喊,但那是事后"
+            ),
+        ),
+        "glm-5": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.AUTO),
+            evidence=(
+                f"{_DOC}: OpenRouter 登记只支持 reasoning 开关、无 reasoning_effort;cherry-studio 标 toggle:true。"
+                "**T10 实测未覆盖**: 与 glm-5.2 同因——5/5 轮回报 model=glm-5.3,数据不属于本型号"
+            ),
+        ),
+        "glm-5.1": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.AUTO),
+            evidence=(
+                f"{_DOC}: 同 glm-5(OpenRouter reasoning.mandatory=false 且无 supported_efforts)。"
+                "**T10 实测未覆盖**: 5/5 轮回报 model=glm-5.3,数据不属于本型号"
+            ),
+        ),
+        "glm-4.6v": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.AUTO),
+            evidence=(
+                f"{_T10}: none 关闭成立,且是全表**证据最硬**的一条——短 5/5 + 长 3/3 全部裁定 ABSENT"
+                "(上游明确上报 reasoning_tokens=0,不是'看不见'),无需锚点旁证;"
+                "auto 档 5/5 观测到推理(rt 57-153)。model_reported 与请求一致,未被路由"
+            ),
+        ),
+        # —— 月之暗面 ——
+        "kimi-k3": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.LOW, Effort.HIGH, Effort.MAX),
+            evidence=(
+                f"{_T10}: **可关闭——推翻 T1 的保守登记**。请求 none(注入 thinking:{{type:disabled}})后"
+                "短 5/5 + 长上下文 3/3 轮无任何推理信号,completion 恒 9 token;同一模型 max 档 "
+                "completion 明显更大且带推理正文(rt 33-146),锚点可分——故'没看见'这次有正面证据支撑。"
+                "两源分歧由此了结: OpenRouter 的 mandatory:false 是对的,官方档位表没列 none 只是没列。"
+                "low / high / max 各 N=5 全部观测到推理(rt 21-53 / 38-60 / 33-146)。"
+                "**model_reported 是 `k3`**(别名,非串台)。官方提示切换档位会使 prefix cache 失效,"
+                "不宜在会话中途改档"
+            ),
+        ),
+        "kimi-for-coding": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.LOW, Effort.HIGH, Effort.MAX),
+            evidence=(
+                f"{_T10}: 本型号在 T1 时因'档位清单无直接证据'走 Phase 3 不登记(设计 §8 第三档),"
+                "现有它自己的实测证据故补登。none: 短 5/5 + 长 3/3 无推理信号、completion 恒 2 token,"
+                "与开启档锚点可分;low / high / max 各 N=3 全部观测到推理(rt 8-40 / 25-75 / 62-85)。"
+                "档位词汇沿用月之暗面官方的 low/high/max: 本渠道对 moonshot **不校验档位值**"
+                "(minimal/medium/xhigh 照样返回 200 并推理),故'没被拒'不构成'受支持',"
+                "登记一个厂商没声明的档等于替它做承诺"
+            ),
+        ),
+        # —— OpenAI ——
+        "gpt-5.4": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.LOW, Effort.MEDIUM, Effort.HIGH, Effort.XHIGH),
+            evidence=(
+                f"{_DOC}: OpenRouter 登记 none/low/medium/high/xhigh,默认 medium;LiteLLM 登记 minimal 不支持。"
+                "**T10 实测未覆盖**: 该渠道本型号所有账号限流(429 All available accounts are "
+                "currently rate-limited),5/5 轮失败。同代的 gpt-5.5 已实测且与本清单逐字相符"
+            ),
+        ),
+        "gpt-5.5": ThinkingCapability(
+            supported_efforts=(Effort.NONE, Effort.LOW, Effort.MEDIUM, Effort.HIGH, Effort.XHIGH),
+            evidence=(
+                f"{_T10}: 清单**逐条对上**,是全表验证最完整的一行。none 关闭成立(短 5/5 + 长 3/3,"
+                "锚点可分);low/medium/high/xhigh 各 N=5 全部观测到推理,且 rt 随档位单调上升"
+                "(18-21 / 18-22 / 22-34 / 35-65)——本渠道上少见的、档位真的分得开的模型;"
+                "清单外的 max 与 minimal 各 N=3 全部被上游 400 拒("
+                "Unsupported value),说明这一路**会校验档位值**,与 zhipu/moonshot 的照单全收相反"
+            ),
+        ),
+        # —— Anthropic ——
+        "claude-opus-5": ThinkingCapability(
+            supported_efforts=(
+                Effort.NONE,
+                Effort.LOW,
+                Effort.MEDIUM,
+                Effort.HIGH,
+                Effort.XHIGH,
+                Effort.MAX,
+            ),
+            evidence=(
+                f"{_DOC}: Anthropic 官方 adaptive thinking + output_config.effort 五档(low/medium/high/"
+                "xhigh/max),默认 high;OpenRouter 标 mandatory:false 故可关。"
+                "**T10 实测未覆盖**: 该渠道 claude 全系返回 429「api key 7天限额已用完」,5/5 轮失败。"
+                "关闭档仍依赖 new-api 把 reasoning_effort=none 转成 thinking 关闭形态,未经验证"
+            ),
+        ),
+        "claude-sonnet-5": ThinkingCapability(
+            supported_efforts=(
+                Effort.NONE,
+                Effort.LOW,
+                Effort.MEDIUM,
+                Effort.HIGH,
+                Effort.XHIGH,
+                Effort.MAX,
+            ),
+            evidence=(
+                f"{_DOC}: 同 claude-opus-5(OpenRouter supported_efforts 与默认档一致)。"
+                "**T10 实测未覆盖**: 同因 429「api key 7天限额已用完」"
+            ),
+        ),
+        # —— Google ——
+        "gemini-3.1-pro": ThinkingCapability(
+            supported_efforts=(Effort.LOW, Effort.MEDIUM, Effort.HIGH),
+            evidence=(
+                f"{_DOC}: **推理不可关闭**——Google 官方文档明确 Gemini 3 Pro / 3.1 Pro 无法关闭思考,"
+                "OpenRouter 亦标 mandatory:true。thinking_level 三档;默认档两源打架"
+                "(官方文档说 HIGH,OpenRouter 说 medium)。"
+                "**T10 实测未覆盖**: 该渠道本型号上游报错(bad_response_status_code / openai_error),"
+                "5/5 轮失败,连默认档基线都没取到,两源分歧仍悬着"
+            ),
         ),
     }
 )
@@ -127,67 +391,370 @@ def register_capability(
     return table
 
 
+@dataclass(frozen=True)
+class ThinkingResolution:
+    """请求体注入片段 + 本次**实际**生效的档位(设计 §4.1)。
+
+    返回 dataclass 而非裸 Mapping,是因为 `nearest` 映射后"请求的档"与"真正发出
+    去的档"会分叉(请求 `medium`、模型只有 low/high/max → 实际发 `low`)。遥测必
+    须记后者: 记请求档会让按档位分组的压测把整行数据挂在一个从未真正发出过的档
+    下,而那种数据错得看不出来。
+
+    `applied_effort is None` 只出现在 Phase 1(调用方不表态): 库既不注入,也不
+    去推定模型自己的默认档——"没看见"不许说成"发生了"。
+    """
+
+    payload: Mapping[str, Any]
+    applied_effort: Effort | None
+
+
+def effective_effort(
+    *,
+    request_effort: Effort | None,
+    source_effort: Effort | None,
+    enable_thinking: bool | None,
+) -> Effort | None:
+    """求本次生效的档位: 请求级 > 源级 > `enable_thinking` 语法糖 > 不表态(设计 §4.2)。
+
+    **收口成一个纯函数**是本函数存在的全部理由: 装配守卫(`client._guard_thinking`)
+    与请求热路径(`openai_compat._build_payload`)必须给出**同一个**判定,两处各写
+    一份就地转换迟早会分叉,而分叉的形态是"装配期放行、运行期报错"——最难查的那种。
+
+    **一律用 `is None` 判有没有表态,不靠真值性**: `Effort.NONE`(要求不推理)与
+    `enable_thinking=False` 都是**表态**而非缺省,`x or y` 式的回落会把后者当成没配
+    从而跳到下一层——那正是本次要消灭的静默失效。
+
+    语法糖排在最末且 `True → AUTO`(开启但不指定强度,不依赖能力表),不是旧版那个
+    硬编码的 `medium`: 那是库替下游做的档位判断,而 `medium` 在 GLM/kimi/deepseek 的
+    档位表里根本不存在(设计 §4.2 声明过的有意变更)。
+
+    同源同时配 `enable_thinking` 与 `reasoning_effort` 且语义矛盾,已由
+    `SourceConfig.__post_init__` 在构造期报错,故这里不再判——两个字段说同一件事时,
+    矛盾是配置错误,不是优先级问题。
+    """
+    if request_effort is not None:
+        return request_effort
+    if source_effort is not None:
+        return source_effort
+    if enable_thinking is None:
+        return None
+    return Effort.AUTO if enable_thinking else Effort.NONE
+
+
+_RAW_THINKING_ROOTS = frozenset(
+    {
+        "reasoning_effort",
+        "enable_thinking",
+        "thinking",
+        "thinking_budget",
+        "reasoning",
+        "thinkingConfig",
+    }
+)
+
+
+def _has_output_effort(raw: Mapping[str, Any]) -> bool:
+    """标准嵌套强度只检查明确的路径，不猜私有方言。"""
+    output = raw.get("output_config")
+    return isinstance(output, Mapping) and "effort" in output
+
+
+def validate_thinking_wire(wire: ThinkingWire, *, model: str) -> None:
+    """拒绝开启片段代选强度，未知形态仍交由请求方向检查。"""
+    base = wire.on_base
+    if base is not None and (
+        "reasoning_effort" in base
+        or (wire.effort_key is not None and wire.effort_key in base)
+        or _has_output_effort(base)
+    ):
+        raise ThinkingUnsupportedError(
+            f"模型 {model!r} 的 on_base 不得包含强度档位；请移除强度并显式传 reasoning_effort"
+        )
+
+
+def validate_thinking_raw(
+    raw: Mapping[str, Any],
+    *,
+    effort: Effort | None,
+    wire: ThinkingWire | None,
+    origin: str,
+) -> None:
+    """受管推理只有一个来源；同值或被遮蔽的 raw 控制也拒绝。"""
+    if effort is None:
+        return
+    roots = set(_RAW_THINKING_ROOTS)
+    if wire is not None:
+        for fragment in (wire.on_base, wire.off):
+            if fragment is not None:
+                roots.update(fragment)
+        if wire.effort_key is not None:
+            roots.add(wire.effort_key)
+    if roots.intersection(raw) or _has_output_effort(raw):
+        # 不打印 raw 或自定义键名，防配置中夹带秘密。
+        raise ThinkingUnsupportedError(
+            f"{origin} 与受管 reasoning_effort={effort.value!r} 冲突；"
+            "请删除 raw 推理控制，或移除源级/请求级推理表态后仅用 raw"
+        )
+
+
 def resolve_thinking(
     profile: ProviderProfile,
     capability: ThinkingCapability | None,
-    enable_thinking: bool | None,
+    effort: Effort | str | None,
     *,
     model: str,
+    fallback: str = "error",
     warn_unregistered: bool = True,
-) -> Mapping[str, Any]:
+) -> ThinkingResolution:
-    """三态 + 两层能力 → 请求体注入片段;不可满足时 ValueError。
+    """档位 + 两层声明(形态/能力)→ 注入片段;不可满足时 `ThinkingUnsupportedError`。
 
     调用点负责翻译: 装配期直接冒泡(配置错误),transport 内翻译为
-    `RequestRejectedError`(四分类之一)。判定顺序即语义,不可调换——形态未知时
+    `RequestRejectedError`(四分类之一)。**判定顺序即语义,不可调换**:
-    无从注入,能力如何无关紧要,故 Phase 2 必须先于 Phase 4;未登记模型没有
+
-    `can_disable` 可读,故 Phase 3 必须先于 Phase 4。
+    ==========  ================================================================
+    Phase 1     不表态 → 不注入。与 `Effort.NONE` 严格区分: 前者是"随模型默认",
+                后者是"要求不推理"
+    Phase 2     **该请求档所需的**形态未知 → 报错(判据见 `_wire_unknown_for`)。
+                无从注入时,模型能力如何都无关紧要,故必须先于 4/5
+    Phase 3     能力未登记 → 尽力注入且**不校验档位**。没有清单可比对,拿空清单
+                去拒绝档位就是凭空报错;新模型上线不该被库挡住(设计 §5 R4)
+    Phase 4     请求 `none` 而模型关不掉 → 报错并给出 `cheapest_effort`
+    Phase 5     其余档位打空 → 报错(或按 `fallback` 映射)
+    ==========  ================================================================
+
+    **4 必须先于 5**: `none` 只是 5 的一个特例,若让它落进 5 的通用分支,报错就
+    退化成"不支持 none,可选 low/high/max"——丢掉"这个模型根本关不掉"这个关键
+    信息与可执行替代,下游随后就会去找 `extra_body` 那条绕过的路,而那正是
+    issue #20 的成因。
+
+    **已登记的 AUTO 同样受清单约束**: 开启形态不证明模型支持不指定强度。
+    AUTO 不在强弱轴上，不允许 nearest 静默代选付费档位；未知模型仍尽力并告警。
 
     `model` 只用于错误与告警文案: 报错能定位到具体模型才有可操作性,而
     `capability` 为 None(未登记)时无从从别处取得模型名。
 
-    `warn_unregistered=False` 供请求热路径去重用: 装配期已经喊过一次,逐次
+    `fallback="nearest"` 是 Phase 5 的逃生口,**默认关闭的理由是钱**: 一次静默的
-    调用再喊只会刷屏。判定结果不受此参数影响。
+    `medium → max` 在 GLM-5.3 上是数倍账单(P5"严禁默认值掩盖错误")。
+
+    `warn_unregistered=False` 供请求热路径去重用: 装配期已经喊过一次,逐次调用
+    再喊只会刷屏。判定结果不受此参数影响。
+
+    **裸字符串也收**(设计 §4.4 第 4 条入口): 本函数在 `__all__` 里,下游直调时
+    传的天然是从 JSON/配置读出来的 `"low"`,而第三参数本次由 `bool` 换成 `Effort`
+    正是这条入口冒出来的时机。签名照实写 `Effort | str`——下面每一关的判据都是
+    `is Effort.X` 的身份比较,`"none" is Effort.NONE` 恒假,不归一的后果不是报错
+    而是**静默判否**: Phase 2 按开启方向取字段、Phase 4 整条被绕过,最后在拼错误
+    文案时才以 `AttributeError` 现形(一个未文档化、也不属四分类的异常)。
     """
-    # Phase 1: 调用方不表态 —— 与 False 严格区分,用模型默认档
+    validate_thinking_wire(profile.thinking, model=model)
-    if enable_thinking is None:
+    # Phase 0: 归一 —— 判据全是身份比较,入口不归一则后面每一关都在拿裸串比枚举
-        return {}
+    if effort is not None:
-    slot = profile.thinking_on if enable_thinking else profile.thinking_off
+        effort = coerce_effort(effort, origin=f"resolve_thinking(model={model!r})")
-    direction = "thinking_on" if enable_thinking else "thinking_off"
+    # Phase 1: 调用方不表态 —— 与 Effort.NONE 严格区分,用模型自己的默认档
-    # Phase 2: 形态未知 —— 提供了开关却不知道怎么发,静默放行就是欺骗调用方
+    if effort is None:
-    if slot is None:
+        return ThinkingResolution({}, None)
+    wire = profile.thinking
+    # Phase 2: 形态未知 —— 给了档位却不知道怎么发,静默放行就是欺骗调用方
+    if _wire_unknown_for(wire, effort):
         raise ThinkingUnsupportedError(
-            f"provider {profile.name!r} 的 {direction} 形态未知(模型 {model!r}): "
+            f"provider {profile.name!r} 的推理形态未知(模型 {model!r},请求档位 "
-            f"本库不知道该 provider 如何表达这一档。请用 register_provider 注册形态,"
+            f"{effort.value!r}): 本库不知道该 provider 如何表达推理。请用 "
-            f"或改用 SourceConfig.extra_body 直接下发供应商参数"
+            f"register_provider 注册形态,或改用 SourceConfig.extra_body 直接下发供应商参数"
         )
     # Phase 3: 能力未登记 —— 新模型上线不该被库挡住,但也不该假装成功
     if capability is None:
+        payload = _inject(profile, effort, model=model)
         if warn_unregistered:
-            _warn_unregistered(model, profile, slot)
+            _warn_unregistered(model, profile, effort, payload)
-        return slot
+        return ThinkingResolution(payload, effort)
-    # Phase 4: 明确不支持关闭 —— 调用方要的是"不推理"的语义保证,给不了必须说
+    # Phase 4: 明确关不掉 —— 调用方要的是"不推理"的语义保证,给不了必须说,且必须
-    if enable_thinking is False and not capability.can_disable:
+    # 带一条能立刻照做的替代(见 docstring: 4 先于 5 的理由)
-        raise ThinkingUnsupportedError(
+    if effort is Effort.NONE and not capability.can_disable:
-            f"模型 {model!r} 无法关闭推理,enable_thinking=False 无法满足: "
+        raise ThinkingUnsupportedError(_cannot_disable(model, capability))
-            f"{capability.evidence}。该模型的推理是固有属性,任何参数都关不掉——"
+    # Phase 5: 已登记选择必须可满足；AUTO 不允许按强度距离映射
-            f"需要关闭思维链请换用支持关闭的模型"
+    applied = _settle_tier(effort, capability, model=model, fallback=fallback)
+    return ThinkingResolution(_inject(profile, applied, model=model), applied)
+
+
+def _wire_unknown_for(wire: ThinkingWire, effort: Effort) -> bool:
+    """Phase 2 的判据: **按请求档取相关字段**,不是一律看 `on_base`。
+
+    旧版 `slot = thinking_on if enable_thinking else thinking_off` 即如此。只看
+    `on_base` 会让"关闭形态已知、开启形态未知"的自定义 provider 在请求 `none` 时
+    被误拒,且指向它已经做过的 `register_provider`(设计 §2 处置表第 2 条)。
+
+    请求 `none` 时判据是**两者皆 None**,而不是单看 `off`: `ThinkingWire` 的三个
+    `None` 语义互不重叠——`off is None` 而 `on_base` 已知是"该 provider 关不掉"
+    (由 `_inject` 说清是缺了哪半边),只有两者皆 None 才是"整个形态未知",此时
+    指路 `register_provider` 才是对的方向。
+    """
+    if effort is not Effort.NONE:
+        return wire.on_base is None
+    return wire.off is None and wire.on_base is None
+
+
+def _settle_tier(
+    effort: Effort, capability: ThinkingCapability, *, model: str, fallback: str
+) -> Effort:
+    """Phase 5: 请求档在不在清单里;不在则按 `fallback` 映射或报错,返回**实际**档。
+
+    AUTO 与强度档统一检查成员，但不参与最近强度映射。
+    """
+    if effort in capability.supported_efforts:
+        return effort
+    mapped = (
+        _nearest_effort(effort, capability)
+        if fallback == "nearest" and effort is not Effort.AUTO
+        else None
+    )
+    if mapped is None:
+        raise ThinkingUnsupportedError(
+            _tier_unsupported(model, effort, capability, fallback=fallback)
         )
-    return slot
-
-
-def _warn_unregistered(model: str, profile: ProviderProfile, slot: Mapping[str, Any]) -> None:
     logger.warning(
-        "模型 {} 的推理能力未登记,按 provider {} 的形态尽力注入 {};"
+        "模型 {} 不支持 reasoning_effort={},按 effort_fallback=nearest 改用最近的 {} 档;"
-        "若该模型实际不支持这一档,本次设置将静默失效。实测后请用 register_capability 登记",
+        "本次真正发出去的、以及遥测成功行记的都是后者,但**缓存 key 记的是前者**"
+        "(CacheMW 在洋葱里比 transport 更外,查缓存时映射尚未发生,拿不到实发档)",
+        model,
+        effort.value,
+        mapped.value,
+    )
+    return mapped
+
+
+def _inject(profile: ProviderProfile, effort: Effort, *, model: str) -> Mapping[str, Any]:
+    """按 wire 把档位写成请求体片段;wire 表达不了这一档时报错。
+
+    自己重读 `wire` 而不由调用方传 `on_base`: Phase 2 的判据按请求档取相关字段
+    (`none` 看 `off`,其余档看 `on_base`)之后,"on_base 一定不是 None"这条前提
+    只对非 `none` 档成立,写进签名反而是句假话。
+
+    三种 `None` 的语义在此**各自兑现**(ThinkingWire 的 docstring 定义了它们):
+    `off is None` = 该 provider 关不掉,`effort_key is None` = 它只有开关没有档位。
+    两者都不是"形态未知",故都不指向 `register_provider`——指错了排查方向比不指
+    还糟。
+    """
+    wire = profile.thinking
+    if effort is Effort.NONE:
+        if wire.off is None:
+            raise ThinkingUnsupportedError(
+                f"provider {profile.name!r} 没有关闭形态(模型 {model!r}): "
+                f"本库知道它如何表达开启,但该 provider 没有可用的关闭参数。"
+                f"需要不推理请换用支持关闭的 provider 或模型"
+            )
+        return wire.off
+    # 非 none 档的开启形态由 Phase 2 保证已知(内部不变量,不承担生产校验)
+    assert wire.on_base is not None
+    if effort is Effort.AUTO:
+        # auto = 开启但不指定强度: 逐字节等于升级前的 `thinking_on`
+        return wire.on_base
+    if wire.effort_key is None:
+        raise ThinkingUnsupportedError(
+            f"provider {profile.name!r} 只有推理开关、没有档位键(模型 {model!r}),"
+            f"表达不了 reasoning_effort={effort.value!r}: 请改用 auto/none 两档,"
+            f"或用 register_provider 给该 provider 注册 effort_key"
+        )
+    return {**wire.on_base, wire.effort_key: effort.value}
+
+
+def _cannot_disable(model: str, capability: ThinkingCapability) -> str:
+    """Phase 4 的文案: 报错必须带一条能立刻照做的替代,否则等于把用户推回起点。
+
+    只报"关不掉"而不给出路,下游就会去找 `extra_body` 那条绕过库的路——issue #20
+    的成因正是如此。故文案必须含 `cheapest_effort` 的值与 env 键名两样东西。
+    """
+    # Phase 4 只在 none 不在清单里时触发,而清单构造期保证非空,故必有一档可推荐
+    alternative = capability.cheapest_effort
+    assert alternative is not None
+    return (
+        f"模型 {model!r} 无法关闭推理,reasoning_effort='none' 无法满足: "
+        f"{capability.evidence}。最省的开启档是 {alternative.value!r}——请配 "
+        f"{{SCOPE}}__{{PROVIDER}}__{{N}}__REASONING_EFFORT={alternative.value},"
+        f"或调用时传 reasoning_effort=Effort.{alternative.name};"
+        f"真正需要不推理请换用支持关闭的模型"
+    )
+
+
+def _tier_unsupported(
+    model: str, effort: Effort, capability: ThinkingCapability, *, fallback: str
+) -> str:
+    """Phase 5 的文案: 按 `is_tiered` 分叉,纯开关型模型不能被告知"可选档位"。
+
+    它没有档位——对它说"可选档位: none, auto"是把开关说成了强度轴,下游照着找
+    档位只会一无所获(设计 §3.2 第三个派生量的用途就是这一句话该怎么说)。
+    """
+    listed = ", ".join(e.value for e in _ordered(capability.supported_efforts))
+    head = f"模型 {model!r} 不支持 reasoning_effort={effort.value!r}: {capability.evidence}。"
+    body = (
+        f"该模型的可选档位: {listed}"
+        if capability.is_tiered
+        else f"该模型只有开关、没有强度档位,可用: {listed}"
+    )
+    # 已经开着 nearest 还走到这里,说明映射本身无解,再劝一遍是废话
+    hint = (
+        ""
+        if fallback == "nearest" or effort is Effort.AUTO
+        else ";若希望自动落到最近的档,请配 EFFORT_FALLBACK=nearest"
+    )
+    if effort is Effort.AUTO:
+        example = capability.cheapest_effort or Effort.NONE
+        hint = (
+            ";请显式选择清单中的档位，例如 "
+            f"{{SCOPE}}__{{PROVIDER}}__{{N}}__REASONING_EFFORT={example.value}，"
+            f"或调用时传 reasoning_effort=Effort.{example.name}；库不会自动应用此选择"
+        )
+    return f"{head}{body}{hint}"
+
+
+def _ordered(efforts: tuple[Effort, ...]) -> list[Effort]:
+    """按由弱到强列出档位;`auto` 不在强弱轴上,排在末尾。"""
+    ordered = [e for e in EFFORT_ORDER if e in efforts]
+    if Effort.AUTO in efforts:
+        ordered.append(Effort.AUTO)
+    return ordered
+
+
+def _nearest_effort(requested: Effort, capability: ThinkingCapability) -> Effort | None:
+    """取距 `requested` 位序最近的**开启档**;等距取弱侧,无开启档时返回 None。
+
+    候选**剔除 `none`**: 把"想得浅一点"映射成"别想了"是方向反转而非省钱,正是
+    issue #20 那种静默失效的翻版。`none` 的领域归 Phase 4,它在那里已经被处理过,
+    走不到这里(能关就不会打空,不能关就已经报错)。
+
+    `auto` 不在强弱轴上(`EFFORT_ORDER` 不含它),故不参与距离计算,只在一个强度
+    档都没有时兜底——它恰好是纯开关型模型唯一能表达"开"的档。
+
+    **等距取弱**的理由是钱: 一次静默的 `medium → max` 在 GLM-5.3 上是数倍账单,
+    库不替下游涨价。
+    """
+    candidates = [
+        e for e in EFFORT_ORDER if e is not Effort.NONE and e in capability.supported_efforts
+    ]
+    if not candidates:
+        return Effort.AUTO if Effort.AUTO in capability.supported_efforts else None
+    target = EFFORT_ORDER.index(requested)
+    # 排序键第二位是位序本身: 距离相同时位序小的(更省的)胜出
+    return min(
+        candidates, key=lambda e: (abs(EFFORT_ORDER.index(e) - target), EFFORT_ORDER.index(e))
+    )
+
+
+def _warn_unregistered(
+    model: str, profile: ProviderProfile, effort: Effort, payload: Mapping[str, Any]
+) -> None:
+    logger.warning(
+        "模型 {} 的推理能力未登记,按 provider {} 的形态尽力注入 {}(请求档位 {});"
+        "不保证开启、关闭或强度生效。实测后请用 register_capability 登记",
         model,
         profile.name,
-        dict(slot),
+        dict(payload),
+        effort.value,
     )
 
 
 def reconcile_thinking(
     *,
-    enable_thinking: bool | None,
+    effort: Effort | None,
     observation: ThinkingObservation,
     capability: ThinkingCapability | None,
     model: str,
@@ -197,6 +764,17 @@ def reconcile_thinking(
     能力表过期是必然事件(M3 的 evidence 曾停在 8-02 整整 23 天),而过期的
     表现是静默错觉。本函数把它变成可报警事件,代价是一次枚举比较。
 
+    **判据是档位而非布尔**(2026-09-05,设计 §4.3): `Effort.NONE` 走"要求关闭"
+    一支,其余任何档走"要求开启"一支,`None`(不表态)仍沉默。判据必须写成
+    `is Effort.NONE` 的**身份比较**——它的取值是非空串 `"none"`,任何靠真值性
+    的写法(`if not effort`)都恒为假,会把每个强度档送进关闭分支,告警方向整个
+    颠倒。传入的应是**实际发出去**的那一档(`nearest` 映射后与请求档分叉),
+    否则文案会说一个从未发出过的档。
+
+    **不新增**「档位高低 vs `reasoning_tokens` 多少」的对账(设计 §4.3/§11 第 1
+    条): 二者没有可判定的函数关系(实测同一档 rt 在 8~56 之间跳),拿它报警必然
+    是噪声,而噪声等于没有告警。该问题归 §11 的压测,不进库。
+
     **只判定、不打日志**: 文案作为返回值交给调用点,单测才能直接断言告警内容,
     而不必去解析日志格式;节流也才能留在握有实例状态的 transport 里。
 
@@ -205,24 +783,26 @@ def reconcile_thinking(
     与遥测落地,处置权归下游。
     """
     # Phase 1: 调用方不表态 —— 没提要求就无从谈"违背"
-    if enable_thinking is None:
+    if effort is None:
         return None
     # Phase 2: 要求关闭 —— 只有 OBSERVED 能证伪。UNKNOWN 没有证伪力,拿它报警
     # 等于每次关闭调用都喊一遍(M3 关闭档恒落此档),噪声即等于没有告警
-    if enable_thinking is False:
+    if effort is Effort.NONE:
         if observation is not ThinkingObservation.OBSERVED:
             return None
         return _off_but_observed(model, capability)
-    # Phase 3: 要求开启 —— ABSENT 是正面证伪,UNKNOWN 是"看不见",两者文案不可混
+    # Phase 3: 要求开启(含 auto 与各强度档)—— ABSENT 是正面证伪,UNKNOWN 是
+    # "看不见",两者文案不可混。文案写出**是哪一档**: transport 的节流键正按档
+    # 分离,文案不分档的话,两条告警长得一模一样,看的人分不出是哪一档出的问题
     if observation is ThinkingObservation.ABSENT:
         return (
-            f"模型 {model!r} 的 enable_thinking=True 未生效: 已注入开启参数,"
+            f"模型 {model!r} 的 reasoning_effort={effort.value!r} 未生效: 已注入开启参数,"
             f"上游却明确上报本次未推理(reasoning_tokens=0)"
         )
     if observation is ThinkingObservation.UNKNOWN:
         return (
-            f"模型 {model!r} 的 enable_thinking=True 无法确认是否生效: 已注入开启参数,"
+            f"模型 {model!r} 的 reasoning_effort={effort.value!r} 无法确认是否生效: "
-            f"但本次响应观测不到任何推理信号(推理正文与 usage 明细双缺)。"
+            f"已注入开启参数,但本次响应观测不到任何推理信号(推理正文与 usage 明细双缺)。"
             f"若走的是非流式路径,推理内容可能已计费却不回传"
         )
     return None
@@ -236,12 +816,12 @@ def _off_but_observed(model: str, capability: ThinkingCapability | None) -> str:
     """
     if capability is None:
         return (
-            f"模型 {model!r} 的 enable_thinking=False 未被满足: 实测观测到推理发生,"
+            f"模型 {model!r} 的 reasoning_effort='none' 未被满足: 实测观测到推理发生,"
             f"且该模型的推理能力尚未登记(本次按 provider 形态尽力注入)。"
             f"请实测后用 register_capability 登记其真实能力"
         )
     return (
-        f"模型 {model!r} 的 enable_thinking=False 未被满足: 实测观测到推理发生,"
+        f"模型 {model!r} 的 reasoning_effort='none' 未被满足: 实测观测到推理发生,"
         f"而能力表登记 can_disable={capability.can_disable}(evidence: {capability.evidence})。"
         f"能力表可能已过期——请复测后用 register_capability 更新登记"
     )

src/polygateway/transports/openai_compat.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import json
 import re
 import time
+from dataclasses import replace
 from typing import TYPE_CHECKING, Any
 
 import httpx
@@ -28,13 +29,20 @@ from polygateway.streaming import StreamLivenessTimeout, stream_with_liveness_ti
 from polygateway.thinking import (
     ThinkingCapability,
     ThinkingUnsupportedError,
+    effective_effort,
     get_capability,
     observe_thinking,
     reconcile_thinking,
     resolve_thinking,
+    validate_thinking_raw,
 )
 from polygateway.transports._http_errors import compose_message, summarize_body
-from polygateway.types import EmbeddingTransportResult, SourceConfig, TransportResult
+from polygateway.types import (
+    Effort,
+    EmbeddingTransportResult,
+    SourceConfig,
+    TransportResult,
+)
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Callable, Mapping
@@ -146,18 +154,28 @@ def _classify(status: int) -> tuple[type[PolyGatewayError], str]:
 
 
 def _status_to_error(
-    source: SourceConfig, status: int, body_text: str, headers: Mapping[str, str]
+    source: SourceConfig,
+    status: int,
+    body_text: str,
+    headers: Mapping[str, str],
+    *,
+    operation: str,
 ) -> Exception:
     """非 2xx → 领域错误,**全部分支**携带响应体摘要(issue #10)。
 
     摘要只算一次,message 与 `body_text` 共用同一份串: 两份不同长度会让"遥测里
     看到的"与"下游 catch 到的"对不上,排查时反而多一层困惑。
+
+    `operation` 是 **HTTP 子操作**词表(`chat` / `embedding` / `ocr_text` / ...),由
+    调用点显式给定。它曾被硬编码成 `"chat"`,而 `embed()` 的非 200 分支也走它
+    ——于是现存所有 embedding HTTP 失败的 `exc.operation` 都是错的(1.3.5 设计 §5 I1)。
+    注意它与遥测新列 `operation`(公开方法四值)是**两个语义**,不做自动转换。
     """
     summary = summarize_body(body_text)
     ctx: dict[str, Any] = {
         "source_name": source.name,
         "status_code": status,
-        "operation": "chat",
+        "operation": operation,
         "body_text": summary,
     }
     if status == 429:
@@ -327,7 +345,7 @@ class OpenAICompatTransport:
         # 一个容器会让两种告警的生命周期纠缠在一起——将来任一侧想加清空/过期策略,
         # 都会连带改掉另一侧的行为。(键空间恰好不相交,故当下**不会**互相压制;
         # 分开维护的理由是语义,不是碰撞)
-        self._warned_mismatches: set[tuple[str, str, bool | None]] = set()
+        self._warned_mismatches: set[tuple[str, str, Effort | None]] = set()
         self._client_factory = client_factory or _default_client_factory
         self._clients: dict[str, httpx.AsyncClient] = {}
 
@@ -346,7 +364,14 @@ class OpenAICompatTransport:
         profile: ProviderProfile,
         stream: bool,
         overlay: dict[str, Any],
-    ) -> dict[str, Any]:
+        reasoning_effort: Effort | None,
+    ) -> tuple[dict[str, Any], Effort | None]:
+        """组装请求体,并交回本次**实际**发出去的档位(`None` = 未表态,不注入)。
+
+        返回二元组而非只返回 payload: 实际档在 `nearest` 映射后与请求档分叉,而
+        除本函数外没有第二处知道映射结果——不交出去,遥测就只能事后再算一遍,
+        算出来必是请求档。
+        """
         payload: dict[str, Any] = {"model": source.model, "messages": messages, "stream": stream}
         if stream:
             payload["stream_options"] = {"include_usage": True}  # 强制 usage 帧(三项目同款)
@@ -355,20 +380,31 @@ class OpenAICompatTransport:
         capability = get_capability(source.model, table=self._capabilities)
         first_time = source.model not in self._warned_models
         self._warned_models.add(source.model)
-        payload.update(
+        # 三层优先级在此汇合: 请求级 > 源级 > enable_thinking 语法糖(设计 §4.2)。
-            resolve_thinking(
+        # 判定与装配守卫共用同一个纯函数,两处分叉就会变成"装配期放行、运行期报错"
+        effort = effective_effort(
+            request_effort=reasoning_effort,
+            source_effort=source.reasoning_effort,
+            enable_thinking=source.enable_thinking,
+        )
+        resolution = resolve_thinking(
             profile,
             capability,
-                source.enable_thinking,
+            effort,
             model=source.model,
+            # 源级 `EFFORT_FALLBACK` 必须真的走到这里: 硬编码 "error" 会让人类明确
+            # 要求实现的 `nearest` 在零告警下变成死代码(2026-09-05 独立验证查出)
+            fallback=source.effort_fallback,
             warn_unregistered=first_time,
         )
-        )
+        for raw, origin in ((source.extra_body, "source extra_body"), (overlay, "request overlay")):
+            validate_thinking_raw(raw, effort=effort, wire=profile.thinking, origin=origin)
+        payload.update(resolution.payload)
         # 顺序即优先级(issue #4 设计决策 A): 配置级 extra_body 在前,调用级
         # overlay(含结构化注入)在后覆盖之。两行不可调换
         payload.update(source.extra_body)
         payload.update(overlay)
-        return payload
+        return payload, resolution.applied_effort
 
     async def complete(
         self,
@@ -378,12 +414,22 @@ class OpenAICompatTransport:
         stream: bool,
         overlay: dict[str, Any],
         call_id: str,
+        reasoning_effort: Effort | None,
     ) -> TransportResult:
-        """一次原始调用;HTTP/线路/流式异常按 ARCH §6.2 翻译为领域错误。"""
+        """一次原始调用;HTTP/线路/流式异常按 ARCH §6.2 翻译为领域错误。
+
+        `reasoning_effort` 是**请求级**档位(`None` = 不表态);它与源级配置的优先级
+        在 `_build_payload` 里由 `effective_effort` 裁定,本层只负责把它送到。
+        """
         profile = get_provider(source.provider, registry=self._registry)
         try:
-            payload = self._build_payload(
+            payload, applied_effort = self._build_payload(
-                messages=messages, source=source, profile=profile, stream=stream, overlay=overlay
+                messages=messages,
+                source=source,
+                profile=profile,
+                stream=stream,
+                overlay=overlay,
+                reasoning_effort=reasoning_effort,
             )
         except ThinkingUnsupportedError as exc:
             # 推理开关不可满足是**请求本身**的问题: 换源重试都救不了它。只捕这个
@@ -408,27 +454,37 @@ class OpenAICompatTransport:
         except httpx.TransportError as exc:
             # VT 宽集: 覆盖断连/协议错误/读写失败(设计 §9 行 8)
             raise TransientError(f"{source.name} 网络错误: {exc}", **ctx) from exc
-        # 此处是唯一同时握有请求方向与响应结果的地方,对账只能落在这里
+        # 实际发出去的档只有 `_build_payload` 知道,而组装 TransportResult 的两条
+        # 路径都在更深一层。在此唯一汇合点补齐,好过给两条路径各加一个参数——那正是
+        # 遥测那边被明令禁止的"复制参数列表"形态,两条路径迟早只改一条
+        result = replace(result, applied_effort=applied_effort)
+        # 此处是唯一同时握有请求档位与响应结果的地方,对账只能落在这里
         self._warn_on_thinking_mismatch(source, result)
         return result
 
     def _warn_on_thinking_mismatch(self, source: SourceConfig, result: TransportResult) -> None:
-        """声明与观测矛盾即 warning;按 (source, model, direction) 节流,同组合只喊一次。
+        """声明与观测矛盾即 warning;按 (source, model, 实际档位) 节流,同组合只喊一次。
 
-        三段缺一不可。**方向**: 同一模型的开、关两档是两个独立的矛盾。**源名**:
+        三段缺一不可。**档位**: 同一模型的 low 与 max 是两个独立的矛盾,共用一个
-        多源多账号是本库的核心场景,同一 model 跨 N 个源是常态,而每个源背后是
+        键会让第二个永久静音(旧版拿 `enable_thinking` 当第三段,而档位根本不经过
-        独立的账号/网关,一个源的行为不代表另一个——漏掉源名,5 个源里第一个出
+        那个字段,于是同一模型的所有档共用一个键)。**源名**: 多源多账号是本库的
-        问题的喊完一次,其余四个永久静音。逐次调用刷屏会把告警变成噪声,噪声等于
+        核心场景,同一 model 跨 N 个源是常态,而每个源背后是独立的账号/网关,一个
-        没有告警。
+        源的行为不代表另一个——漏掉源名,5 个源里第一个出问题的喊完一次,其余四个
+        永久静音。逐次调用刷屏会把告警变成噪声,噪声等于没有告警。
+
+        档位取 `result.applied_effort`(真正发出去的那一档)而非请求档: `nearest`
+        映射后二者分叉,而对账问的是"我发出去的要求有没有被满足"——拿一个从未发出
+        过的档去对账,文案与键都指向了一次不存在的请求。被映射到同一档的两个请求
+        因此共用一个键,这正是它们该有的关系(同一条实际要求,同一个矛盾)。
 
         **先判键再对账**: `reconcile_thinking` 会拼含完整 `evidence` 的长字符串,
         而非流式档每次调用都命中这一分支,节流后再拼是纯粹的热路径浪费。
         """
-        key = (source.name, source.model, source.enable_thinking)
+        key = (source.name, source.model, result.applied_effort)
         if key in self._warned_mismatches:
             return
         message = reconcile_thinking(
-            enable_thinking=source.enable_thinking,
+            effort=result.applied_effort,
             observation=result.thinking_observation,
             capability=get_capability(source.model, table=self._capabilities),
             model=source.model,
@@ -463,7 +519,10 @@ class OpenAICompatTransport:
         except httpx.TransportError as exc:
             raise TransientError(f"{source.name} 网络错误: {exc}", **ctx) from exc
         if resp.status_code != 200:
-            raise _status_to_error(source, resp.status_code, resp.text, resp.headers)
+            # 历史误标修正: 本分支属 `embed()`,与上方 ctx 同为 `"embedding"`
+            raise _status_to_error(
+                source, resp.status_code, resp.text, resp.headers, operation="embedding"
+            )
         return _parse_embedding_payload(resp, source, len(texts))
 
     async def _complete_stream(
@@ -478,7 +537,9 @@ class OpenAICompatTransport:
         async with client.stream("POST", url, json=payload) as resp:
             if resp.status_code != 200:
                 body = (await resp.aread()).decode("utf-8", errors="replace")
-                raise _status_to_error(source, resp.status_code, body, resp.headers)
+                raise _status_to_error(
+                    source, resp.status_code, body, resp.headers, operation="chat"
+                )
             sink: dict[str, Any] = {}
             guarded = stream_with_liveness_timeouts(
                 _iter_sse_deltas(resp.aiter_lines(), sink),
@@ -576,7 +637,9 @@ class OpenAICompatTransport:
         """非流式快路径(三项目均无,库新增): 单 JSON 响应,仅 total 超时。"""
         resp = await client.post(url, json=payload)
         if resp.status_code != 200:
-            raise _status_to_error(source, resp.status_code, resp.text, resp.headers)
+            raise _status_to_error(
+                source, resp.status_code, resp.text, resp.headers, operation="chat"
+            )
         try:
             body = resp.json()
         except json.JSONDecodeError as exc:

src/polygateway/types.py

@@ -8,16 +8,20 @@ import dataclasses
 import json
 import math
 import re
-from collections.abc import Mapping
+import uuid
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
 from enum import StrEnum
 from types import MappingProxyType
-from typing import Any
+from typing import Any, Literal
 
 from loguru import logger
 
 _MISSING_DONE_DOMAIN = frozenset({"retry", "salvage"})
 
+_EFFORT_FALLBACK_DOMAIN = frozenset({"error", "nearest"})
+"""`SourceConfig.effort_fallback` 的值域: 请求档打空时报错,还是映射到最近的档。"""
+
 _PROTECTED_OVERLAY_KEYS: Mapping[str, str] = MappingProxyType(
     {
         "model": "会让遥测记录的 model 与实际请求分叉,成本按错单价换算",
@@ -167,6 +171,89 @@ def canonical_sampling_json(merged: Mapping[str, Any]) -> str | None:
     return json.dumps(dict(merged), sort_keys=True, ensure_ascii=False)
 
 
+class Effort(StrEnum):
+    """推理强度档位的封闭词汇(设计 §3.1)。
+
+    取值直接写进请求体(`reasoning_effort` 等键),**改名即改变发出去的字节**,
+    且会进缓存 key 与遥测落库,历史数据会断层。
+
+    八档而非六档: `none`(不推理)与 `auto`(推理,档位由模型自定)必须同时存在。
+    `auto` 不可省——newapi 上 26 个可调用模型里有 9 个是**纯开关型**(qwen 五个、
+    MiniMax-M3、glm-5/5.1/4.6v),它们能开推理却没有强度档可填;没有 `auto` 就只
+    能拿某个强度档冒充"开",而那正是本次要修的病根(旧 `thinking_on` 硬编码
+    `medium`,可 `medium` 在 GLM/kimi/deepseek 的档位表里根本不存在)。
+
+    词汇取四家参考实现共同收敛的一套(cherry-studio 的 canonical selection、
+    OpenRouter 的 `supported_efforts`、LiteLLM 的 `reasoning_effort_levels`、
+    new-api 的 `relayconvert/reasoning`),不自创。
+
+    **枚举定义在最内层而非决策层**: 它是 `SourceConfig`/`ChatRequest`/
+    `LLMResponse` 的字段类型,放进 `thinking.py` 会让 `types.py` 反向 import
+    决策模块(P7 依赖铁律),与 `ThinkingObservation` 同一理由。
+    """
+
+    NONE = "none"
+    AUTO = "auto"
+    MINIMAL = "minimal"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+    MAX = "max"
+
+
+EFFORT_ORDER: tuple[Effort, ...] = (
+    Effort.NONE,
+    Effort.MINIMAL,
+    Effort.LOW,
+    Effort.MEDIUM,
+    Effort.HIGH,
+    Effort.XHIGH,
+    Effort.MAX,
+)
+"""由弱到强的强度序;`AUTO` **不在其中**——它是"由模型自定",在强弱轴上没有位置。
+
+供能力表求"最省的开启档"与 `nearest` 映射取最近档。公开(非 `_` 前缀)是因为
+`thinking.py` 要跨模块消费它,跨模块引用私有名是坏味道。
+"""
+
+
+def coerce_effort(raw: Any, *, origin: str) -> Effort:
+    """把外部传入的档位**归一**成 `Effort`;非法值报 `ValueError` 并列全八档。
+
+    存在的理由是"归一化点必须在入口":库内一律用 `is Effort.NONE` 做身份比较
+    (枚举成员唯一,`is` 比 `==` 更能表达"就是这一档"),而 `Effort` 是 `StrEnum`
+    ——下游从 JSON/配置/命令行读出来的天然是裸字符串,`"none" is Effort.NONE`
+    恒为假。不在入口归一,身份比较就会在**错误路径上**误判(把一致的配置判成
+    矛盾),随后拼错误文案时再 `.value` 抛 `AttributeError`,连承诺的 `ValueError`
+    都拿不到(2026-09-05 独立验证实测)。
+
+    故裸字符串**接受并归一**而非拒收: 拒收会把 `.env` 之外的两条装配路(工厂 /
+    构造函数全量注入,CLAUDE.md §4.5)口径劈成两半,而 `.env` 那条早已是"解析即
+    归一"。`strip().lower()` 与 `config._to_effort` 同口径,理由同样是配置里的
+    行尾空格与大写写法是常态,而档位取值本身没有大小写语义。
+
+    `origin` 指回具体的配置项或调用点: 档位在源级、请求级两处都能配,只说
+    "非法档位"要人自己去找是哪一处填错了。传空串表示调用方自己会补上下文
+    (`config._cast` 的 `配置 X 解析失败` 已经说了是哪个 env 键)。
+    """
+    if isinstance(raw, Effort):
+        return raw
+    prefix = f"{origin}: " if origin else ""
+    listed = ", ".join(e.value for e in Effort)
+    if isinstance(raw, str):
+        try:
+            return Effort(raw.strip().lower())
+        except ValueError:
+            # 不 `from exc`: 枚举原生的 "'lowest' is not a valid Effort" 只是同一
+            # 件事的英文复述,链上去反而把可操作的那句挤到后面
+            raise ValueError(f"{prefix}非法推理档位 {raw!r};允许: {listed}") from None
+    raise ValueError(
+        f"{prefix}推理档位必须是 Effort 或其字面量字符串,"
+        f"收到 {type(raw).__name__}: {raw!r};允许: {listed}"
+    )
+
+
 class ThinkingObservation(StrEnum):
     """一次调用中"推理是否真的发生"的裁定结果(issue #16/#17)。
 
@@ -188,6 +275,91 @@ class ThinkingObservation(StrEnum):
     UNKNOWN = "unknown"
 
 
+CallOperation = Literal["chat", "embed", "recognize_text", "parse_layout"]
+"""遥测 `operation` 列的值域: **公开方法**四值,由调用点给定。
+
+与 `PolyGatewayError.operation`(HTTP 子操作,如 `download_result`)是**两个语义**,
+不做自动转换;链路上任何位置都不得读 `exc.operation` 来填本列(设计 §5 I1/I2)。"""
+
+CALL_OPERATIONS: tuple[CallOperation, ...] = ("chat", "embed", "recognize_text", "parse_layout")
+
+EventKind = Literal["attempt", "cache_hit", "terminal_failure"]
+"""一行遥测描述的事件形态;旧行 NULL,不回填。
+
+终态行与 attempt 行**不是重复事实**(前者描述逻辑终态,后者描述单次尝试),
+故禁止按 `error IS NOT NULL` 跨两类直接计失败调用次数(设计 §6/§8)。"""
+
+EVENT_KINDS: tuple[EventKind, ...] = ("attempt", "cache_hit", "terminal_failure")
+
+
+@dataclass(frozen=True)
+class CallStats:
+    """一次**公开调用**(而非单次尝试)的统计快照(设计 §3)。
+
+    四种响应各平铺三字段会立刻漂移,故收敛成单一对象并由包根导出。
+    第三方合成响应的 `None` 表示**未知**,不得伪造 0。
+    """
+
+    logical_call_id: str
+    """每次公开调用一个 UUID;重试、结构化重问、embedding 分批共享同一个。
+
+    不占用既有 `parent_call_id`(后者是调用方的业务关联,语义不变)。"""
+
+    attempts: int
+    """准入后实际调用 transport 端口的次数;含免预算 429 与端口本地拒绝。
+
+    **不是 HTTP 请求条数**: OCR layout 的 POST + ZIP GET 在同一次 transport
+    调用内,计 1 次。缓存命中与空输入是合法的零尝试。"""
+
+    total_latency_ms: int
+    """从输入校验通过到返回/异常传播前的单调时钟快照。
+
+    含缓存 IO、退避等待、准入等待、重问、分批与内联记账。
+    "总耗时减最后一次尝试耗时"**不等于**纯等待(含其他本地工作)。"""
+
+
+class _CallContext:
+    """私有可变逻辑调用上下文: 只持计数、单调时钟与终态去重位,不做 I/O。
+
+    **每调用一个实例**的单任务对象: chat 重试、结构化重问、embedding 分批
+    都在同一任务内串行推进,故计数无需锁。**严禁提升为 client 实例属性**
+    ——那会让同一 client 的并发调用互相串掉计数与逻辑 ID(库铁律"纯 asyncio 中立"、
+    VT `evolve_llm = llm` 教训的同一形态)。
+    """
+
+    __slots__ = ("_attempts", "_now", "_started", "_terminal_claimed", "logical_call_id")
+
+    def __init__(self, *, now: Callable[[], float]) -> None:
+        self.logical_call_id = str(uuid.uuid4())
+        self._now = now
+        self._started = now()
+        self._attempts = 0
+        self._terminal_claimed = False
+
+    def register_attempt(self) -> None:
+        """transport 调用**前**登记一次尝试(含免预算 429 与端口本地拒绝)。
+
+        登记点在调用前而非成功后: 否则失败与取消的尝试会从计数里消失,
+        而那正是诊断时最需要看见的那几次。
+        """
+        self._attempts += 1
+
+    def snapshot(self) -> CallStats:
+        """同步冻结当前快照;**绝不 await**,可多次调用。"""
+        return CallStats(
+            logical_call_id=self.logical_call_id,
+            attempts=self._attempts,
+            total_latency_ms=int((self._now() - self._started) * 1000),
+        )
+
+    def claim_terminal(self) -> bool:
+        """首次 `True`、其后 `False`: 保证每逻辑调用至多写一条终态行。"""
+        if self._terminal_claimed:
+            return False
+        self._terminal_claimed = True
+        return True
+
+
 @dataclass(frozen=True)
 class LLMResponse:
     """一次治理调用的统一响应(与三项目超集兼容,ARCH §5.1)。"""
@@ -240,6 +412,19 @@ class LLMResponse:
     实测开启档 completion 53 vs 关闭档 3),该档即为 `UNKNOWN`。
     要判"确实没推理"只认 `ABSENT`(上游明确上报 0)。"""
 
+    applied_effort: Effort | None = None
+    """本次调用**真正发出去**的推理档位(issue #20);`None` = 调用方未表态。
+
+    与 `ChatRequest.reasoning_effort`(请求档)可能分叉: 源上配了
+    `EFFORT_FALLBACK=nearest` 时,请求 `medium` 而模型只有 low/high/max,实际发
+    出的是 `low`。遥测按本字段分组,记请求档会把整行挂在一个从未发出过的档下。
+
+    `None` 不是"没推理": 库不表态时也不推定模型自己的默认档——"没看见"不许说成
+    "发生了"(同 `thinking_observation` 的 `UNKNOWN` 一脉)。"""
+
+    call_stats: CallStats | None = None
+    """本次**逻辑调用**的统计快照(1.3.5);`None` = 未知,不得读成 0。"""
+
 
 @dataclass(frozen=True)
 class ChatRequest:
@@ -275,6 +460,27 @@ class ChatRequest:
     再进一次既重复又会让存量缓存全量冷启动;且 `meta` 承载的是审计维度而非
     语义维度,同 messages 同 namespace 下换个 batch_id 不应导致 miss。"""
 
+    # —— 请求级推理档位(issue #20;追加在末尾,不扰动既有字段的位置构造)——
+    reasoning_effort: Effort | None = None
+    """本次调用要求的推理档位,压过源级默认(设计 §4.2 的最高优先级层)。
+
+    `None` 是**不表态**(随源级配置),与 `Effort.NONE`("要求不推理")严格区分:
+    把前者读成后者会让一次没写档位的调用悄悄关掉源上配好的推理。
+
+    独立成字段而非塞进 `overlay`: `overlay` 是采样参数的直通层,库不解释其内容,
+    而档位要经能力表校验、要进缓存 key、要落遥测——混进直通层等于放弃这三样,
+    正是 issue #20 里下游手写 `extra_body` 绕过全部治理的那条路。"""
+
+    # —— 库内部逻辑调用上下文(1.3.5;追加在末尾,不扰动既有字段的位置构造)——
+    call_context: _CallContext | None = field(default=None, compare=False, repr=False)
+    """库内部逻辑调用上下文;`None` = 库内现场构造的请求,遥测 `logical_call_id` 落 NULL。
+
+    `compare=False, repr=False` 不是洁癖: 进 `compare` 会让两个内容相同的请求因
+    "不是同一次调用"而不相等,进 `repr` 则把库内部件泄进调用方的日志。
+
+    洋葱各层经 `dataclasses.replace` 派生请求时保留**同一引用**(不是拷贝),
+    重试/重问/分批才能共享同一个逻辑 ID 与计数。"""
+
 
 @dataclass(frozen=True)
 class Usage:
@@ -341,6 +547,13 @@ class TransportResult:
     默认 `UNKNOWN` 而非 `ABSENT`: 不做裁定的 transport(OCR/embedding 等)沉默
     时,不该替上游做出"没推理"这个它从未做过的声明。"""
 
+    applied_effort: Effort | None = None
+    """本次调用真正发出去的推理档位(issue #20),由做注入的 transport 填。
+
+    只有做了注入的那一层知道它: `nearest` 映射后请求档与实际档分叉(请求
+    `medium` → 实发 `low`),中间件事后再算一遍必然算成请求档。默认 `None` 是
+    "未表态/不注入推理参数"(OCR、embedding 等 transport 沉默即此)。"""
+
 
 @dataclass(frozen=True)
 class SourceConfig:
@@ -348,6 +561,10 @@ class SourceConfig:
 
     限额闸 0 表示不启用;`enable_thinking` 三态: None=不注入(模型默认)、
     True=注入开启参数、False=注入关闭参数(统一 VT 与 CHS 相反的现状)。
+
+    2026-09-04 起 `enable_thinking` 降级为 `reasoning_effort` 的语法糖
+    (`True`→`AUTO`、`False`→`NONE`),保留不删是因为它已被三项目消费
+    (迁移兼容约束,ARCH §5.1)。两个字段说的是同一件事,故矛盾即报错。
     """
 
     name: str
@@ -372,10 +589,29 @@ class SourceConfig:
     (加任何 mapping 字段的固有代价,裸 dict 亦然),库内无以源作 key 的写法;
     要可变副本用 `dict(source.extra_body)`,要改字段用 `dataclasses.replace`。"""
 
+    reasoning_effort: Effort | None = None
+    """本源默认的推理档位;None = 不表态(与 `Effort.NONE`「要求不推理」不同)。
+
+    裸字符串(`"low"`、`" LOW "`)也收,构造期由 `coerce_effort` 归一成 `Effort`,
+    非法值当场 `ValueError` 并列出八档;**构造完成后本字段一定是 `Effort`**,库内
+    的 `is Effort.NONE` 身份比较依赖这条不变式。
+
+    **追加在末尾**是硬要求:三项目的测试按位置构造 fake,插在中间会静默错位
+    (本模块头部 docstring 的字段保序约定)。"""
+
+    effort_fallback: str = "error"
+    """请求档打空时的处置: `error`(默认,报错)或 `nearest`(映射到最近的档)。
+
+    默认报错的理由是钱: 一次静默的 `medium → max` 在 GLM-5.3 上是数倍账单
+    (P5「严禁默认值掩盖错误」)。值域在此把关而非交给 `resolve_thinking`——
+    后者对未知值是 fail-closed(按 `error` 处理),不会替配置兜错,漏判的结果
+    就是 `EFFORT_FALLBAK` 这种拼写错误静默失效。"""
+
     def __post_init__(self) -> None:
         self._validate_identity()
         self._validate_gates()
         self._validate_watchdog()
+        self._validate_thinking()
         self._freeze_extra_body()
 
     def effective_est_tokens(self) -> int:
@@ -413,6 +649,52 @@ class SourceConfig:
         ):
             raise ValueError("看门狗不变式要求 0 < inter_token < ttft < timeout_s")
 
+    def _validate_thinking(self) -> None:
+        """推理两键的**归一化**、值域与互不矛盾(issue #20 设计 §4.2)。
+
+        归一化必须先于下面的矛盾判定: 判据用的是 `is Effort.NONE`,而本类是公共
+        入口,`reasoning_effort="none"` 这种裸字符串写法(从 JSON/配置读出来的
+        常态)会让它误判成矛盾,再拼文案时 `.value` 直接 `AttributeError`。同一
+        理由也适用于下游读侧——归一化后库内一律是 `Effort`,`is` 比较才安全。
+
+        矛盾**报错而非「后者赢」**: `enable_thinking` 与 `reasoning_effort` 表达的是
+        同一件事,静默取其一等于替下游猜它到底想要哪个,而猜错的代价是账单——
+        猜成开启就是白花钱,猜成关闭就是拿到一个没推理过的答案。
+
+        判据是「二者是否都在说关闭」: `enable_thinking is False` 与
+        `reasoning_effort is NONE` 必须同真同假。`True` + 某个开启档(如 `low`)
+        不算矛盾,那只是把同一件事说了两遍,且后者更精确。
+        """
+        if self.reasoning_effort is not None:
+            # frozen dataclass 改字段走 object.__setattr__(同款先例: _freeze_extra_body)
+            object.__setattr__(
+                self,
+                "reasoning_effort",
+                coerce_effort(
+                    self.reasoning_effort, origin=f"SourceConfig({self.name}).reasoning_effort"
+                ),
+            )
+        if isinstance(self.effort_fallback, str):
+            # 与相邻的 `REASONING_EFFORT` 同口径: `.env` 里的行尾空格与大写写法是
+            # 常态,而 `nearest`/`error` 本身没有大小写语义。归一化放在值域校验的
+            # 同一处(而不是 env 解析处),三条配置路一并覆盖
+            object.__setattr__(self, "effort_fallback", self.effort_fallback.strip().lower())
+        if self.effort_fallback not in _EFFORT_FALLBACK_DOMAIN:
+            raise ValueError(
+                f"SourceConfig.effort_fallback(EFFORT_FALLBACK)非法值 "
+                f"{self.effort_fallback!r};允许: {sorted(_EFFORT_FALLBACK_DOMAIN)}"
+            )
+        if self.enable_thinking is None or self.reasoning_effort is None:
+            return
+        if (self.enable_thinking is False) != (self.reasoning_effort is Effort.NONE):
+            raise ValueError(
+                f"源 {self.name!r} 的 enable_thinking={self.enable_thinking} 与 "
+                f"reasoning_effort={self.reasoning_effort.value!r} 相互矛盾: "
+                f"enable_thinking 已是 reasoning_effort 的语法糖"
+                f"(True={Effort.AUTO.value}、False={Effort.NONE.value})。"
+                f"请只保留其中一个,或让两者语义一致"
+            )
+
     def _freeze_extra_body(self) -> None:
         """校验后转只读视图: 装配完成的源不应再被就地改采样参数(设计决策 E)。"""
         validated = validate_request_overlay(
@@ -539,6 +821,8 @@ class OcrTextResult:
     latency_ms: int
     call_id: str
     raw: dict[str, Any]
+    call_stats: CallStats | None = None
+    """本次逻辑调用的统计快照(1.3.5);`None` = 未知。"""
 
 
 @dataclass(frozen=True)
@@ -556,6 +840,8 @@ class OcrLayoutResult:
     latency_ms: int
     call_id: str
     raw: dict[str, Any]
+    call_stats: CallStats | None = None
+    """本次逻辑调用的统计快照(1.3.5);`None` = 未知。"""
 
 
 @dataclass(frozen=True)
@@ -600,3 +886,5 @@ class EmbeddingResponse:
     call_id: str
     source_name: str
     cost: float | None = None
+    call_stats: CallStats | None = None
+    """本次逻辑调用(含全部分批)的统计快照(1.3.5);`None` = 未知。"""

tests/e2e/conftest.py

@@ -0,0 +1,540 @@
+"""测试侧独立 HTTP 取证装配；无环境自读取或成功 SSE 预读。"""
+
+from collections.abc import AsyncIterator, Iterator, Mapping
+from contextlib import AsyncExitStack, asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+import httpx
+import pytest
+
+from polygateway import GatewayClient, GatewaySettings
+from polygateway.client import (
+    _aclose_component,
+    _build_breaker,
+    _build_limiter,
+    _build_selector,
+    _build_structured,
+)
+from polygateway.providers import get_provider
+from polygateway.transports.openai_compat import OpenAICompatTransport
+from polygateway.types import Effort, EmbeddingTransportResult, SourceConfig, TransportResult
+from tests.live_evidence import (
+    AttemptEvidence,
+    HttpEvidence,
+    LiveVerdict,
+    assess_model_identity,
+    classify_live_failure,
+    messages_digest,
+    request_is_valid,
+    safe_attempts,
+    strict_json,
+    write_live_round,
+)
+
+
+@dataclass
+class _Exchange:
+    """仅在 attempt 生命周期持有原始响应引用。"""
+
+    request: httpx.Request
+    checks: tuple[tuple[str, bool], ...]
+    response: httpx.Response | None = None
+
+
+@dataclass
+class _Attempt:
+    """任务内可变收集器，结束时转换为冻结快照。"""
+
+    call_id: str
+    exchanges: list[_Exchange] = field(default_factory=list)
+    messages_digest: str | None = None
+    messages_valid: bool = False
+
+
+class LiveCapture:
+    """矩阵显式预期与按逻辑轮次关联的独立证据。"""
+
+    def __init__(self, *, expectations: Mapping[str, Mapping[str, Any]]) -> None:
+        """预期缺项即配置错误，不从实发 payload 补齐。"""
+        for expected in expectations.values():
+            required = {"model", "origin", "path", "control", "messages_digest"}
+            if not required <= expected.keys() or ("stream" in expected) == (
+                "input_shape" in expected
+            ):
+                raise ValueError("取证矩阵缺少必需预期或混用 chat/embed")
+            if not isinstance(expected["control"], dict):
+                raise ValueError("control 必须是显式对象")
+            if "structured_max_retries" in expected and (
+                "stream" not in expected
+                or type(expected["structured_max_retries"]) is not int
+                or expected["structured_max_retries"] < 0
+                or type(expected.get("messages_prefix_length")) is not int
+                or expected["messages_prefix_length"] < 1
+            ):
+                raise ValueError("结构化预期缺少合法前缀长度或重问预算")
+        self._expectations = {name: dict(value) for name, value in expectations.items()}
+        self._round: ContextVar[tuple[str, str]] = ContextVar("live_round")
+        self._attempt: ContextVar[_Attempt] = ContextVar("live_attempt")
+        self._records: dict[tuple[str, str], list[AttemptEvidence]] = {}
+        self._owners: dict[str, tuple[str, str]] = {}
+        self._notes: dict[tuple[str, str], list[str]] = {}
+
+    @contextmanager
+    def round_context(self, *, session_id: str, parent_call_id: str) -> Iterator[None]:
+        """外围逻辑轮次绑定，异常和取消均复位。"""
+        key = session_id, parent_call_id
+        token = self._round.set(key)
+        self._records.setdefault(key, [])
+        self._notes.setdefault(key, [])
+        try:
+            yield
+        finally:
+            self._round.reset(token)
+
+    @contextmanager
+    def attempt_context(self, call_id: str) -> Iterator[None]:
+        """零 HTTP 尝试也有快照；重复／跨轮 UUID 是契约错误。"""
+        key = self._round.get()
+        if call_id in self._owners:
+            raise ValueError("重复或跨轮 call_id")
+        self._owners[call_id] = key
+        attempt = _Attempt(call_id)
+        token = self._attempt.set(attempt)
+        error = None
+        try:
+            yield
+        except Exception as exc:
+            error = exc
+            raise
+        finally:
+            try:
+                events = tuple(
+                    self._snapshot(exchange, call_id, key) for exchange in attempt.exchanges
+                )
+                self._records[key].append(AttemptEvidence(call_id, events, error))
+            finally:
+                self._attempt.reset(token)
+
+    def _snapshot(self, exchange: _Exchange, call_id: str, key: tuple[str, str]) -> HttpEvidence:
+        """complete 结束后只读已缓冲内容，拒绝截断和歧义身份。"""
+        response = exchange.response
+        identity: tuple[bool, str | None] = (False, None)
+        body = None
+        status = response.status_code if response is not None else 0
+        if response is None:
+            self._notes[key].append("无可配对响应")
+        else:
+            try:
+                content = response.content
+            except httpx.ResponseNotRead:
+                self._notes[key].append("响应未缓冲，证据不足")
+            else:
+                if status >= 400:
+                    if len(content) <= 65536:
+                        body = content
+                    else:
+                        self._notes[key].append("错误体超过 64 KiB，不接受截断证据")
+                elif 200 <= status < 300 and dict(exchange.checks).get("stream") is not None:
+                    try:
+                        payload = strict_json(exchange.request.content)
+                    except (ValueError, UnicodeError):
+                        payload = {}
+                    if isinstance(payload, dict) and payload.get("stream") is False:
+                        try:
+                            data = strict_json(content)
+                            if not isinstance(data, dict):
+                                raise ValueError("原始 JSON 非对象")
+                            model = data.get("model")
+                            if model is not None and not isinstance(model, str):
+                                raise ValueError("原始 model 类型非法")
+                            identity = (True, model)
+                        except (ValueError, UnicodeError):
+                            self._notes[key].append("原始 JSON 身份无法独立解析")
+        return HttpEvidence(call_id, exchange.checks, status, body, identity)
+
+    def observe_messages(self, source: SourceConfig, messages: list[dict[str, Any]]) -> None:
+        """先验前缀／反馈契约与委托摘要分开；摘要仅验证 HTTP 序列化保真。"""
+        expected = self._expectations[source.name]
+        if "structured_max_retries" not in expected:
+            return
+        attempt = self._attempt.get()
+        prefix_length = expected["messages_prefix_length"]
+        feedback = messages[prefix_length:]
+        attempt.messages_digest = messages_digest(messages)
+        attempt.messages_valid = (
+            (not feedback or bool(self._records[self._round.get()]))
+            and messages_digest(messages[:prefix_length]) == expected["messages_digest"]
+            and len(feedback) % 2 == 0
+            and len(feedback) <= 2 * expected["structured_max_retries"]
+            and all(
+                isinstance(message, dict)
+                and set(message) == {"role", "content"}
+                and message["role"] == ("assistant" if index % 2 == 0 else "user")
+                and isinstance(message["content"], str)
+                for index, message in enumerate(feedback)
+            )
+        )
+
+    def client_factory(self, source: SourceConfig) -> httpx.AsyncClient:
+        """鉴权仅内存比较；沿已校验源 timeout/trust_env。"""
+        expected = self._expectations[source.name]
+
+        async def request_hook(request: httpx.Request) -> None:
+            """校验实发请求而不修正它。"""
+            attempt = self._attempt.get()
+            try:
+                payload = strict_json(request.content)
+            except (ValueError, UnicodeError):
+                payload = {}
+            if not isinstance(payload, dict):
+                payload = {}
+            url = request.url
+            origin = str(
+                url.copy_with(path="", query=None, fragment=None, username=None, password=None)
+            ).rstrip("/")
+            # control 是本轮完整附加字段；基础键以外均比较，漏／多键都失败。
+            basic = {"model", "messages", "stream", "stream_options", "input"}
+            control = {k: v for k, v in payload.items() if k not in basic}
+            checks = {
+                "method": request.method == "POST",
+                "origin": origin == expected["origin"]
+                and not url.username
+                and not url.password
+                and not url.query,
+                "path": url.path == expected["path"],
+                "model": payload.get("model") == expected["model"],
+                "authorization": request.headers.get("Authorization") == f"Bearer {source.api_key}",
+                "control": control == expected["control"],
+                "messages_digest": (
+                    attempt.messages_valid
+                    and messages_digest(payload.get("messages")) == attempt.messages_digest
+                    if "structured_max_retries" in expected
+                    else messages_digest(payload.get("messages", payload.get("input")))
+                    == expected["messages_digest"]
+                ),
+            }
+            if "stream" in expected:
+                checks["stream"] = payload.get("stream") is expected["stream"] and (
+                    payload.get("stream_options") == {"include_usage": True}
+                    if expected["stream"]
+                    else "stream_options" not in payload
+                )
+            else:
+                texts = payload.get("input")
+                checks["input_shape"] = (
+                    isinstance(texts, list)
+                    and all(isinstance(text, str) for text in texts)
+                    and len(texts) == expected["input_shape"]
+                )
+            attempt.exchanges.append(_Exchange(request, tuple(checks.items())))
+
+        async def response_hook(response: httpx.Response) -> None:
+            """只持有引用，绝不提前读取成功 SSE。"""
+            attempt = self._attempt.get()
+            matching = [event for event in attempt.exchanges if event.request is response.request]
+            if len(matching) != 1 or matching[0].response is not None:
+                raise ValueError("响应无法唯一配对")
+            matching[0].response = response
+
+        return httpx.AsyncClient(
+            headers={"Authorization": f"Bearer {source.api_key}"},
+            timeout=source.timeout_s,
+            trust_env=source.trust_env,
+            event_hooks={"request": [request_hook], "response": [response_hook]},
+        )
+
+    def attempts(self, *, session_id: str, parent_call_id: str) -> tuple[AttemptEvidence, ...]:
+        """按逻辑轮次返回不可变快照。"""
+        return tuple(self._records.get((session_id, parent_call_id), ()))
+
+    def notes(self, *, session_id: str, parent_call_id: str) -> tuple[str, ...]:
+        """只含固定安全原因，不包含响应正文。"""
+        return tuple(self._notes.get((session_id, parent_call_id), ()))
+
+    def raw_identity(
+        self, *, session_id: str, parent_call_id: str, call_id: str
+    ) -> tuple[bool, str | None]:
+        """精确取最终成功 attempt，不猜本轮最后一条响应。"""
+        key = session_id, parent_call_id
+        if call_id in self._owners and self._owners[call_id] != key:
+            raise ValueError("跨轮 call_id 身份查询")
+        matches = [attempt for attempt in self._records.get(key, []) if attempt.call_id == call_id]
+        if len(matches) > 1:
+            raise ValueError("重复 call_id 身份查询")
+        if not matches:
+            return False, None
+        events = [event for event in matches[0].http if 200 <= event.status_code < 300]
+        if len(events) > 1:
+            raise ValueError("多个成功 HTTP 身份候选")
+        return events[0].raw_identity if events else (False, None)
+
+
+class ObservedTransport:
+    """原样委托同一个真实 transport，无重试、payload 修正或异常翻译。"""
+
+    def __init__(self, transport: OpenAICompatTransport, capture: LiveCapture) -> None:
+        """资源所有权留给装配者。"""
+        self._transport = transport
+        self._capture = capture
+
+    async def complete(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        source: SourceConfig,
+        stream: bool,
+        overlay: dict[str, Any],
+        call_id: str,
+        reasoning_effort: Effort | None,
+    ) -> TransportResult:
+        """与生产端口逐参数同签名。"""
+        with self._capture.attempt_context(call_id):
+            self._capture.observe_messages(source, messages)
+            return await self._transport.complete(
+                messages=messages,
+                source=source,
+                stream=stream,
+                overlay=overlay,
+                call_id=call_id,
+                reasoning_effort=reasoning_effort,
+            )
+
+    async def embed(
+        self, *, texts: list[str], source: SourceConfig, call_id: str
+    ) -> EmbeddingTransportResult:
+        """embedding 使用同一取证关联，不套 chat 推理判据。"""
+        with self._capture.attempt_context(call_id):
+            return await self._transport.embed(texts=texts, source=source, call_id=call_id)
+
+
+@asynccontextmanager
+async def observed_client(
+    settings: GatewaySettings, capture: LiveCapture, *, capabilities=None
+) -> AsyncIterator[GatewayClient]:
+    """全量注入复用生产装配函数；自建组件显式关闭，不启用响应缓存。"""
+    async with AsyncExitStack() as stack:
+        sources = list(settings.sources)
+        limiter = _build_limiter(settings, sources)
+        stack.push_async_callback(_aclose_component, limiter)
+        breaker = _build_breaker(settings)
+        stack.push_async_callback(_aclose_component, breaker)
+        real = OpenAICompatTransport(
+            client_factory=capture.client_factory, capabilities=capabilities
+        )
+        stack.push_async_callback(real.aclose)
+        strategy, escalation = _build_structured(
+            [get_provider(source.provider) for source in sources]
+        )
+        client = GatewayClient(
+            scope=settings.scope,
+            sources=sources,
+            selector=_build_selector(settings.selector),
+            limiter=limiter,
+            breaker=breaker,
+            transport=ObservedTransport(real, capture),
+            retry=settings.retry,
+            backpressure=settings.backpressure,
+            quota_full=settings.quota_full,
+            circuit_open=settings.circuit_open,
+            structured_strategy=strategy,
+            structured_escalation=escalation,
+            structured_max_retries=settings.structured_max_retries,
+        )
+        stack.push_async_callback(client.aclose)
+        yield client
+
+
+def chat_expectations(
+    settings: GatewaySettings,
+    *,
+    messages: list[dict[str, Any]],
+    stream: bool,
+    controls: Mapping[str, dict[str, Any]],
+    structured_max_retries: int | None = None,
+) -> dict[str, dict[str, Any]]:
+    """URL 从源配置声明，控制片段必须由矩阵独立给出。"""
+    result = {}
+    for source in settings.sources:
+        url = httpx.URL(source.base_url)
+        result[source.name] = {
+            "model": source.model,
+            "origin": str(
+                url.copy_with(path="", query=None, fragment=None, username=None, password=None)
+            ).rstrip("/"),
+            "path": url.path.rstrip("/") + "/chat/completions",
+            "stream": stream,
+            "control": controls[source.name],
+            "messages_digest": messages_digest(messages),
+        }
+        if structured_max_retries is not None:
+            result[source.name].update(
+                messages_prefix_length=len(messages), structured_max_retries=structured_max_retries
+            )
+    return result
+
+
+def enforce_verdict(verdict: LiveVerdict) -> None:
+    """仅在报告已写入后调用；默认失败，不打印上游异常正文。"""
+    if verdict.status == "UNCOVERED":
+        pytest.skip(verdict.reason)
+    assert verdict.status == "PASS", verdict.reason
+
+
+async def captured_chat_round(
+    client: GatewayClient,
+    capture: LiveCapture,
+    *,
+    run_id: str,
+    matrix_id: str,
+    round_index: int,
+    output_dir: Path,
+    messages: list[dict[str, Any]],
+    models: Mapping[str, str],
+    aliases: Mapping[str, frozenset[str]],
+    validate=None,
+    providers: Mapping[str, str] | None = None,
+    source_efforts: Mapping[str, Effort | None] | None = None,
+    **kwargs: Any,
+) -> tuple[Any, LiveVerdict]:
+    """请求、身份与行为断言均先记逐轮证据；异常不漏轮。"""
+    parent = uuid4().hex
+    response = None
+    error = None
+    verdict = LiveVerdict("FAIL", "轮次未完成")
+    with capture.round_context(session_id=run_id, parent_call_id=parent):
+        try:
+            response = await client.chat(
+                messages, session_id=run_id, parent_call_id=parent, **kwargs
+            )
+            attempts = capture.attempts(session_id=run_id, parent_call_id=parent)
+            events = [event for attempt in attempts for event in attempt.http]
+            successful = [attempt for attempt in attempts if attempt.call_id == response.call_id]
+            success_paired = (
+                len(successful) == 1
+                and successful[0].error is None
+                and len(successful[0].http) == 1
+                and 200 <= successful[0].http[0].status_code < 300
+            )
+            verdict = assess_model_identity(
+                requested=models[response.source_name],
+                aliases=aliases.get(models[response.source_name], frozenset()),
+                reported=response.model_reported,
+                raw_identity=capture.raw_identity(
+                    session_id=run_id, parent_call_id=parent, call_id=response.call_id
+                ),
+                request_valid=success_paired
+                and bool(events)
+                and all(request_is_valid(event) for event in events),
+            )
+            if verdict.status == "PASS" and validate is not None:
+                validate(response)
+        except Exception as exc:
+            error = exc
+            verdict = classify_live_failure(
+                exc, capture.attempts(session_id=run_id, parent_call_id=parent)
+            )
+        finally:
+            attempts = capture.attempts(session_id=run_id, parent_call_id=parent)
+            # 上游 model 可能回显提示词；仅输出允许集合内的名字，其他统一省略。
+            allowed = set(models.values()) | {
+                alias for values in aliases.values() for alias in values
+            }
+            write_live_round(
+                output_dir,
+                run_id=run_id,
+                matrix_id=matrix_id,
+                round_index=round_index,
+                safe_fields={
+                    "session_id": run_id,
+                    "parent_call_id": parent,
+                    "requested_model": list(models.values()),
+                    "provider": list(providers.values()) if providers is not None else None,
+                    "attempts": safe_attempts(attempts),
+                    "status": verdict.status,
+                    "reason": verdict.reason,
+                    "stream": kwargs.get("stream", True),
+                    "requested_effort": kwargs.get("reasoning_effort")
+                    or (list(source_efforts.values()) if source_efforts is not None else None),
+                    "completed_rounds": 1,
+                    "prompt_tokens": response.prompt_tokens if response else None,
+                    "completion_tokens": response.completion_tokens if response else None,
+                    "reasoning_tokens": response.reasoning_tokens if response else None,
+                    "thinking_chars": len(response.thinking) if response else None,
+                    "evidence_notes": (
+                        "原始异常／正文摘要省略以避免回显泄露",
+                        *capture.notes(session_id=run_id, parent_call_id=parent),
+                    ),
+                    "reported_model": response.model_reported
+                    if response and response.model_reported in allowed
+                    else None,
+                    "applied_effort": response.applied_effort if response else None,
+                    "thinking_observation": response.thinking_observation if response else None,
+                    "error_type": type(error).__name__ if error else None,
+                    "error_status": getattr(error, "status_code", None),
+                },
+            )
+    return response, verdict
+
+
+def declared_control(provider: str, effort: Effort | None) -> dict[str, Any]:
+    """测试矩阵的独立 wire 声明；不调用 resolver 或生产 payload 构造器。"""
+    if effort is None:
+        return {}
+    if provider == "qwen":
+        if effort not in (Effort.AUTO, Effort.NONE):
+            raise ValueError("测试矩阵未声明 qwen 强度映射")
+        return {"enable_thinking": effort is not Effort.NONE}
+    if provider in {"deepseek", "zhipu", "moonshot"}:
+        result: dict[str, Any] = {
+            "thinking": {"type": "disabled" if effort is Effort.NONE else "enabled"}
+        }
+        if effort not in (Effort.AUTO, Effort.NONE):
+            result["reasoning_effort"] = effort.value
+        return result
+    if provider not in {"minimax", "openai", "anthropic", "google"}:
+        raise ValueError("测试矩阵没有该 provider 的控制声明")
+    return {} if effort is Effort.AUTO else {"reasoning_effort": effort.value}
+
+
+def source_controls(settings: GatewaySettings) -> dict[str, dict[str, Any]]:
+    """源级矩阵预期独立表达；受管 raw 冲突由生产路径拒绝。"""
+    result = {}
+    for source in settings.sources:
+        effort = source.reasoning_effort
+        if effort is None and source.enable_thinking is not None:
+            effort = Effort.AUTO if source.enable_thinking else Effort.NONE
+        control = declared_control(source.provider, effort)
+        if effort is None:
+            control.update(source.extra_body)
+        else:
+            # 不用 update 覆盖控制声明，否则会掩盖所有权回归。
+            for key, value in source.extra_body.items():
+                if key in control:
+                    raise ValueError("取证矩阵有双来源控制")
+                control[key] = value
+        result[source.name] = control
+    return result
+
+
+# pytest 用例终态补充网络前缺配置、装配失败及未完成轮次；不代替逐轮报告。
+@pytest.hookimpl(wrapper=True)
+def pytest_runtest_makereport(item, call):
+    """仅记录安全矩阵标识和阶段结果，不序列化 pytest 异常长文本。"""
+    report = yield
+    if report.skipped or report.failed:
+        write_live_round(
+            Path("tests/outputs/134/live"),
+            run_id=uuid4().hex,
+            matrix_id="pytest-" + messages_digest(item.nodeid)[:16],
+            round_index=0,
+            safe_fields={
+                "status": "UNCOVERED" if report.skipped else "FAIL",
+                "reason": "用例阶段未覆盖或失败；详情按逐轮安全证据核验，不能视为能力通过",
+                "evidence_notes": [report.when],
+            },
+        )
+    return report

tests/e2e/test_compat_projects.py

@@ -1,98 +1,119 @@
-"""GovDoc 与 Video-Tree 最小接入冒烟(2026-07-20 拍板: 两个项目都做)。
+"""历史接入调用形态的真实冒烟；不能替代缺失下游的现行配置验收。"""
-
-复刻两项目的真实调用点形态,对真实网关跑一次治理调用,证明"调用点零改动
-迁移"成立;并验证 VT 现有平铺键名(LLM_TIMEOUT 等)可直接装配。
-reference/ 只读——本文件只 import 其 Protocol,绝不修改。
-"""
 
 import os
 import sys
 from pathlib import Path
+from uuid import uuid4
 
 import pytest
 from dotenv import dotenv_values
 
-from polygateway import GatewayClient
+from polygateway import Effort, GatewayClient, GatewaySettings
+from tests.e2e.conftest import (
+    LiveCapture,
+    captured_chat_round,
+    chat_expectations,
+    enforce_verdict,
+    observed_client,
+    source_controls,
+)
+from tests.live_evidence import write_live_round
 
 _REPO = Path(__file__).resolve().parents[2]
 _ENV = {k: v for k, v in {**dotenv_values(".env"), **os.environ}.items() if v is not None}
-_HAS_SOURCE = any(k.split("__")[0] == "LLM" and k.endswith("__API_KEY") for k in _ENV)
+_HAS_SOURCE = any(k.startswith("LLM__") and k.endswith("__API_KEY") for k in _ENV)
-
-# 真实网关调用: 与 test_thinking_live.py 同待遇标 slow(pytest addopts 默认排除,
-# 显式 `pytest -m slow` 运行)。理由是这些用例的成败取决于网关此刻快不快,而
-# pre-commit 关卡跑全套件——网关一抖就挡住与之无关的提交,久了会把"测试红了
-# 先怀疑网关"变成惯性,真 bug 也会被当成抖动重试掉。发版清单负责让它们真跑。
 pytestmark = [
     pytest.mark.slow,
-    pytest.mark.skipif(
+    pytest.mark.skipif(not _HAS_SOURCE, reason="缺少矩阵必需凭据，未覆盖"),
-        not _HAS_SOURCE, reason="需真实网关凭据: 在 .env 配置 LLM__{PROVIDER}__1__*"
-    ),
 ]
+_OUT = Path("tests/outputs/134/live")
 
 
-@pytest.fixture
+async def _call_shape(matrix, **kwargs):
-async def client():
+    """session/parent 总由逐轮 UUID 传入；保留 cache_salt 调用形态。"""
-    c = GatewayClient.from_env("LLM", env=_ENV)
+    settings = GatewaySettings.from_env("LLM", env=_ENV)
-    yield c
+    messages = [{"role": "user", "content": "Reply with exactly: compatibility-ok"}]
-    await c.aclose()
+    capture = LiveCapture(
+        expectations=chat_expectations(
+            settings, messages=messages, stream=True, controls=source_controls(settings)
+        )
+    )
+
+    def validate(response):
+        assert response.content.strip() and response.call_id
+
+    async with observed_client(settings, capture) as client:
+        _, verdict = await captured_chat_round(
+            client,
+            capture,
+            run_id=uuid4().hex,
+            matrix_id=matrix,
+            round_index=1,
+            output_dir=_OUT,
+            messages=messages,
+            models={s.name: s.model for s in settings.sources},
+            providers={s.name: s.provider for s in settings.sources},
+            source_efforts={
+                s.name: s.reasoning_effort
+                if s.reasoning_effort is not None
+                else (Effort.AUTO if s.enable_thinking else Effort.NONE)
+                if s.enable_thinking is not None
+                else None
+                for s in settings.sources
+            },
+            aliases={},
+            validate=validate,
+            **kwargs,
+        )
+        enforce_verdict(verdict)
 
 
 class TestGovDocOnboarding:
-    """GovDoc agent/loop.py:377 调用形态: session_id + parent_call_id。"""
+    """历史 session_id＋parent_call_id 调用点契约。"""
 
-    async def test_call_site_shape_runs_governed(self, client):
+    async def test_call_site_shape_runs_governed(self):
-        response = await client.chat(
+        await _call_shape("compat-parent")
-            [{"role": "user", "content": "Reply with exactly: govdoc-ok"}],
-            session_id="govdoc-e2e",
-            parent_call_id="step-1",
-        )
-        assert response.content.strip()
-        assert response.call_id  # GovernedLLMClient 契约字段全在
 
-    async def test_structural_protocol_match(self, client):
+    async def test_structural_protocol_match(self):
+        """外部 Protocol 缺包单列未覆盖；合成契约另在 unit 跑。"""
+        run_id = uuid4().hex
         sys.path.insert(0, str(_REPO / "reference/GovDoc-SaaS/packages/docagent-core/src"))
         try:
             from docagent_core.protocols import LLMProvider
         except ImportError:
-            pytest.skip("GovDoc protocols 依赖不可导入(结构断言已由单测兜底覆盖)")
+            write_live_round(
+                _OUT,
+                run_id=run_id,
+                matrix_id="external-protocol",
+                round_index=0,
+                safe_fields={
+                    "status": "UNCOVERED",
+                    "reason": "外部 Protocol 包缺失；未验证真实下游",
+                },
+            )
+            pytest.skip("外部 Protocol 包缺失，未覆盖")
         finally:
             sys.path.pop(0)
+        status = "FAIL"
+        client = None
+        try:
+            client = GatewayClient.from_env("LLM", env=_ENV)
             assert isinstance(client, LLMProvider)
+            status = "PASS"
+        finally:
+            if client is not None:
+                await client.aclose()
+            write_live_round(
+                _OUT,
+                run_id=run_id,
+                matrix_id="external-protocol",
+                round_index=0,
+                safe_fields={"status": status, "reason": "外部 Protocol 结构契约，不是模型能力"},
+            )
 
 
 class TestVideoTreeOnboarding:
-    """VT loop.py:336 调用形态: session_id + cache_salt(跨 epoch 重采样)。"""
+    """历史 cache_salt 调用点契约，平铺键装配已移至 unit。"""
 
-    async def test_call_site_shape_with_cache_salt(self, client):
+    async def test_call_site_shape_with_cache_salt(self):
-        response = await client.chat(
+        await _call_shape("compat-salt", cache_salt="epoch-1")
-            [{"role": "user", "content": "Reply with exactly: vt-ok"}],
-            session_id="vt-e2e",
-            cache_salt="epoch-1",
-        )
-        assert response.content.strip()
-
-    async def test_flat_legacy_keys_assemble(self):
-        """VT 现有键名(LLM_TIMEOUT/LLM_MAX_RETRIES 等)零改名装配成功。"""
-        source_keys = {k: v for k, v in _ENV.items() if k.split("__")[0] == "LLM" and "__" in k}
-        flat_env = {
-            **source_keys,
-            # 与 .env 的 LLM__MINIMAX__1__TIMEOUT_S 同值。取 120(VT 旧值)会让本用例的
-            # 超时比生产配置还紧一半,在慢网关上必然间歇红——而本用例断言的是平铺
-            # 键名能否解析成 SourceConfig.timeout_s,超时取值本身不是被测对象
-            "LLM_TIMEOUT": "300",
-            "LLM_MAX_RETRIES": "3",
-            "LLM_RETRY_BASE_DELAY": "2.0",
-            "LLM_RETRY_MAX_DELAY": "30.0",
-            "LLM_CIRCUIT_BREAKER_THRESHOLD": "5",
-            "LLM_CIRCUIT_BREAKER_COOLDOWN": "60",
-            "LLM_TTFT_TIMEOUT": "30",
-            "LLM_INTER_TOKEN_TIMEOUT": "15",
-            "PGW_CACHE_BACKEND": "none",
-            "PGW_TELEMETRY_BACKEND": "none",
-        }
-        client = GatewayClient.from_env("LLM", env=flat_env)
-        try:
-            resp = await client.chat([{"role": "user", "content": "Reply: flat-ok"}])
-            assert resp.content.strip()
-        finally:
-            await client.aclose()

tests/e2e/test_embed_probe.py

@@ -1,89 +1,98 @@
-"""真实网关 /embeddings 端点探测(M2 设计 §11.6;人类默认口径: 实现时探测)。
+"""真实 embedding 探测；404 仅证明请求型号不可用，不外推端点能力。"""
-
-对 .env 的 LLM 源网关发一次真实 embeddings 请求: 支持则记录向量证据,
-不支持(404/翻译为领域错误)则 skip 并把响应记录进 tests/outputs/
-(降级证据)。无 EMBED scope 配置时复用 LLM 源的 base_url/api_key。
-"""
-
-from __future__ import annotations
 
 import dataclasses
 import os
-from datetime import datetime
 from pathlib import Path
+from uuid import uuid4
 
+import httpx
 import pytest
 from dotenv import dotenv_values
 
-from polygateway.errors import PolyGatewayError
+from polygateway import GatewaySettings
 from polygateway.transports.openai_compat import OpenAICompatTransport
-from polygateway.types import SourceConfig
+from tests.e2e.conftest import LiveCapture, ObservedTransport, enforce_verdict
+from tests.live_evidence import (
+    LiveVerdict,
+    classify_live_failure,
+    messages_digest,
+    request_is_valid,
+    safe_attempts,
+    write_live_round,
+)
 
 _ENV = {k: v for k, v in {**dotenv_values(".env"), **os.environ}.items() if v is not None}
-
-# 真实网关调用: 与 test_thinking_live.py 同待遇标 slow(pytest addopts 默认排除,
-# 显式 `pytest -m slow` 运行)。理由见 test_compat_projects.py 同处注释。
 pytestmark = [
     pytest.mark.slow,
-    pytest.mark.skipif(
+    pytest.mark.skipif("LLM__MINIMAX__1__BASE_URL" not in _ENV, reason="缺少矩阵必需配置，未覆盖"),
-        "LLM__MINIMAX__1__BASE_URL" not in _ENV,
-        reason="缺真实网关配置(.env)",
-    ),
 ]
 
-_OUT = Path("tests/outputs/embedding")
-
-
-def _record(name: str, lines: list[str]) -> Path:
-    _OUT.mkdir(parents=True, exist_ok=True)
-    path = _OUT / f"{name}_{datetime.now():%Y%m%d_%H%M%S}.md"
-    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
-    return path
-
 
 async def test_probe_real_gateway_embeddings():
-    source = SourceConfig(
+    """沿已校验源的 timeout/trust_env，所有路径 finally 关闭。"""
-        name="probe_1",
+    settings = GatewaySettings.from_env("LLM", env=_ENV)
-        provider="minimax",
+    configured = next(s for s in settings.sources if s.name == "minimax_1")
-        base_url=_ENV["LLM__MINIMAX__1__BASE_URL"],
+    source = dataclasses.replace(
-        api_key=_ENV["LLM__MINIMAX__1__API_KEY"],
+        configured, model=_ENV.get("PGW_EMBED_PROBE_MODEL", "text-embedding-v1")
-        model=_ENV.get("PGW_EMBED_PROBE_MODEL", "text-embedding-v1"),
-        timeout_s=30.0,
-        est_tokens=8,
     )
-    transport = OpenAICompatTransport()
+    texts = ["polygateway embedding probe"]
+    url = httpx.URL(source.base_url)
+    capture = LiveCapture(
+        expectations={
+            source.name: {
+                "model": source.model,
+                "origin": str(url.copy_with(path="", query=None)).rstrip("/"),
+                "path": url.path.rstrip("/") + "/embeddings",
+                "input_shape": 1,
+                "control": {},
+                "messages_digest": messages_digest(texts),
+            }
+        }
+    )
+    real = OpenAICompatTransport(client_factory=capture.client_factory)
+    transport = ObservedTransport(real, capture)
+    run_id, parent, call_id = uuid4().hex, uuid4().hex, uuid4().hex
+    verdict = LiveVerdict("FAIL", "轮次未完成")
+    completed_rounds = 0
     try:
-        result = await transport.embed(
+        with capture.round_context(session_id=run_id, parent_call_id=parent):
-            texts=["polygateway embedding probe"], source=source, call_id="probe"
+            try:
-        )
+                result = await transport.embed(texts=texts, source=source, call_id=call_id)
-    except PolyGatewayError as exc:
+                events = [
-        path = _record(
+                    e
-            "probe_unsupported",
+                    for a in capture.attempts(session_id=run_id, parent_call_id=parent)
-            [
+                    for e in a.http
-                "# Embedding 端点探测: 网关不支持",
+                ]
-                f"- base_url: {source.base_url}",
+                assert len(events) == 1 and request_is_valid(events[0])
-                f"- model: {source.model}",
-                f"- 错误分类: {type(exc).__name__}",
-                f"- status_code: {exc.status_code}",
-                f"- 详情: {exc}",
-                "",
-                "结论: e2e 按设计 §11.6 降级,embedding 行为由 unit 全覆盖。",
-            ],
-        )
-        await transport.aclose()
-        pytest.skip(f"网关不支持 embeddings({type(exc).__name__}),证据: {path}")
-    else:
-        await transport.aclose()
                 assert result.dim > 0 and len(result.vectors) == 1
-        _record(
+                verdict = LiveVerdict("PASS", "向量形状与实发请求合格")
-            "probe_supported",
+                completed_rounds = 1
-            [
+            except Exception as error:
-                "# Embedding 端点探测: 网关支持",
+                verdict = classify_live_failure(
-                f"- base_url: {source.base_url}",
+                    error, capture.attempts(session_id=run_id, parent_call_id=parent)
-                f"- model: {source.model}",
-                f"- dim: {result.dim}",
-                f"- usage: {result.prompt_tokens}({result.usage_source})",
-                f"- 向量前 5 维: {result.vectors[0][:5]}",
-                f"- raw: {dataclasses.asdict(result)['raw']}",
-            ],
                 )
+                completed_rounds = 1
+            finally:
+                write_live_round(
+                    Path("tests/outputs/134/live"),
+                    run_id=run_id,
+                    matrix_id="embedding",
+                    round_index=1,
+                    safe_fields={
+                        "requested_model": source.model,
+                        "provider": source.provider,
+                        "planned_rounds": 1,
+                        "completed_rounds": completed_rounds,
+                        "status": verdict.status,
+                        "reason": verdict.reason,
+                        "session_id": run_id,
+                        "parent_call_id": parent,
+                        "attempts": safe_attempts(
+                            capture.attempts(session_id=run_id, parent_call_id=parent)
+                        ),
+                        "evidence_notes": capture.notes(session_id=run_id, parent_call_id=parent),
+                    },
+                )
+    finally:
+        await real.aclose()
+    enforce_verdict(verdict)

tests/e2e/test_smoke_gateway.py

@@ -1,123 +1,116 @@
-"""真实网关端到端冒烟(M1 验收第 7 步)。
+"""真实网关冒烟：逐轮独立取证，行为断言失败也必须留档。"""
 
-前置: `.env` 配置至少一个 `LLM__{PROVIDER}__1__*` 真实源 + 韧性键。
-缺配置时 skip(验收前必须真跑)。输出结构化 Markdown 落
-`tests/outputs/e2e/`(CLAUDE.md §4.6,不提交 git)。
-"""
-
-import json
 import os
-from datetime import datetime
 from pathlib import Path
+from uuid import uuid4
 
 import pytest
 from dotenv import dotenv_values
 from pydantic import BaseModel
 
-from polygateway import GatewayClient
+from polygateway import Effort, GatewaySettings
+from tests.e2e.conftest import (
+    LiveCapture,
+    captured_chat_round,
+    chat_expectations,
+    enforce_verdict,
+    observed_client,
+    source_controls,
+)
 
 _ENV = {k: v for k, v in {**dotenv_values(".env"), **os.environ}.items() if v is not None}
-_HAS_SOURCE = any(k.split("__")[0] == "LLM" and k.endswith("__API_KEY") for k in _ENV)
+_HAS_SOURCE = any(k.startswith("LLM__") and k.endswith("__API_KEY") for k in _ENV)
-
-# 真实网关调用: 与 test_thinking_live.py 同待遇标 slow(pytest addopts 默认排除,
-# 显式 `pytest -m slow` 运行)。理由见 test_compat_projects.py 同处注释。
 pytestmark = [
     pytest.mark.slow,
-    pytest.mark.skipif(
+    pytest.mark.skipif(not _HAS_SOURCE, reason="缺少矩阵必需凭据，未覆盖"),
-        not _HAS_SOURCE,
-        reason="需真实网关凭据: 在 .env 配置 LLM__{PROVIDER}__1__*(M1 验收前必须真跑)",
-    ),
 ]
 
-_OUT_DIR = Path("tests/outputs/e2e")
-
 
 class MiniAnswer(BaseModel):
+    """最小结构化响应契约。"""
+
     answer: int
     reason: str
 
 
-def _report(name: str, sections: list[tuple[str, str]]) -> Path:
+async def _smoke(matrix, prompt, validate, *, stream=True, structured=None):
-    _OUT_DIR.mkdir(parents=True, exist_ok=True)
+    """全量注入仅替换取证装配，仍调用生产结构化策略。"""
-    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    settings = GatewaySettings.from_env("LLM", env=_ENV)
-    path = _OUT_DIR / f"{name}_{ts}.md"
+    messages = [{"role": "user", "content": prompt}]
-    body = [f"# e2e 冒烟: {name}", ""]
+    controls = source_controls(settings)
-    for title, content in sections:
+    capture = LiveCapture(
-        body += [f"## {title}", "", "```", content, "```", ""]
+        expectations=chat_expectations(
-    path.write_text("\n".join(body), encoding="utf-8")
+            settings,
-    return path
+            messages=messages,
-
+            stream=stream,
-
+            controls=controls,
-@pytest.fixture
+            structured_max_retries=(
-async def client():
+                settings.structured_max_retries if isinstance(structured, type) else None
-    c = GatewayClient.from_env("LLM", env=_ENV)
+            ),
-    yield c
+        )
-    await c.aclose()
+    )
+    async with observed_client(settings, capture) as client:
+        _, verdict = await captured_chat_round(
+            client,
+            capture,
+            run_id=uuid4().hex,
+            matrix_id=matrix,
+            round_index=1,
+            output_dir=Path("tests/outputs/134/live"),
+            messages=messages,
+            models={s.name: s.model for s in settings.sources},
+            providers={s.name: s.provider for s in settings.sources},
+            source_efforts={
+                s.name: s.reasoning_effort
+                if s.reasoning_effort is not None
+                else (Effort.AUTO if s.enable_thinking else Effort.NONE)
+                if s.enable_thinking is not None
+                else None
+                for s in settings.sources
+            },
+            aliases={},
+            validate=validate,
+            stream=stream,
+            structured=structured,
+        )
+        enforce_verdict(verdict)
 
 
 class TestRealGatewaySmoke:
-    async def test_stream_chat(self, client):
+    """保留流／非流和结构化真实行为断言。"""
-        resp = await client.chat(
-            [{"role": "user", "content": "Reply with exactly: pong"}], session_id="e2e-smoke"
-        )
-        path = _report(
-            "stream_chat",
-            [
-                ("响应", resp.content),
-                (
-                    "元数据",
-                    json.dumps(
-                        {
-                            "model": resp.model,
-                            "source": resp.source_name,
-                            "usage_source": resp.usage_source,
-                            "prompt_tokens": resp.prompt_tokens,
-                            "completion_tokens": resp.completion_tokens,
-                            "latency_ms": resp.latency_ms,
-                            "ttft_ms": resp.ttft_ms,
-                        },
-                        ensure_ascii=False,
-                        indent=2,
-                    ),
-                ),
-            ],
-        )
-        assert resp.content.strip()
-        assert resp.ttft_ms is not None and resp.latency_ms > 0
-        print(f"输出: {path}")
 
-    async def test_non_stream_fast_path(self, client):
+    async def test_stream_chat(self):
-        resp = await client.chat(
+        def validate(response):
-            [{"role": "user", "content": "Reply with exactly: pong"}], stream=False
+            assert response.content.strip()
-        )
+            assert response.ttft_ms is not None and response.latency_ms > 0
-        _report("non_stream", [("响应", resp.content)])
-        assert resp.content.strip() and resp.ttft_ms is None
 
-    async def test_structured_json_tier(self, client):
+        await _smoke("smoke-stream", "Reply with exactly: pong", validate)
-        resp = await client.chat(
+
-            [{"role": "user", "content": 'Reply ONLY with JSON: {"ok": true}'}],
+    async def test_non_stream_fast_path(self):
+        def validate(response):
+            assert response.content.strip() and response.ttft_ms is None
+
+        await _smoke("smoke-json", "Reply with exactly: pong", validate, stream=False)
+
+    async def test_structured_json_tier(self):
+        def validate(response):
+            assert isinstance(response.structured_data, dict | list)
+
+        await _smoke(
+            "smoke-structured-json",
+            'Reply ONLY with JSON: {"ok": true}',
+            validate,
             structured="json",
         )
-        _report("structured_json", [("解析产物", repr(resp.structured_data))])
-        assert isinstance(resp.structured_data, dict | list)
 
-    async def test_structured_model_ladder(self, client):
+    async def test_structured_model_ladder(self):
-        resp = await client.chat(
+        def validate(response):
-            [
+            assert isinstance(response.structured_data, MiniAnswer)
-                {
+            assert response.structured_data.answer == 5
-                    "role": "user",
+
-                    "content": "What is 2+3? Reply ONLY with JSON matching "
+        await _smoke(
-                    '{"answer": <int>, "reason": <short string>}',
+            "smoke-structured-model",
-                }
+            'What is 2+3? Reply ONLY with JSON matching {"answer": <int>, "reason": <short string>}',
-            ],
+            validate,
             structured=MiniAnswer,
         )
-        _report(
-            "structured_model",
-            [
-                ("原始响应", resp.content),
-                ("校验产物", resp.structured_data.model_dump_json()),
-            ],
-        )
-        assert isinstance(resp.structured_data, MiniAnswer)
-        assert resp.structured_data.answer == 5

tests/integration/conftest.py

@@ -0,0 +1,248 @@
+"""PG 集成测试的一次性沙箱工厂(issue #18)。
+
+**为什么把它收敛成一份**: 在此之前,"建临时 schema → 挂 search_path → teardown
+删净"这套样板在两个测试文件里重复了七处,清理逻辑各写各的——任何一处写漏,残留都
+落在与真实批跑共用的那个库上。工厂让清理只有一份实现,并让"用例拿不到管理连接"
+成为结构事实而不是纪律。
+
+**admin DSN 不做成 fixture**: 它能对共享表执行任何语句。做成 fixture 等于把这个
+能力摆在每一条用例面前,"用例不该直接用"就只是一句提醒。故它是模块私有函数,
+只被工厂内部调用,`PgSandbox` 也不携带它。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+from uuid import uuid4
+
+import pytest
+from dotenv import dotenv_values
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# 测试专用口令: 这些角色只在单条用例的生命周期内存在,且只对自建 schema 有权。
+# 它不是机密,写死在这里比走 .env 更清楚——.env 里的每一项都该是真实部署会用的。
+_SANDBOX_PASSWORD = "pgw-sandbox-not-a-secret"  # noqa: S105
+
+_Role = Literal["none", "owner", "grantee"]
+
+
+@dataclass(frozen=True)
+class PgSandbox:
+    """一次性 PG 沙箱: 独立 schema + 可选独占登录角色。"""
+
+    schema: str
+    role: str | None
+    dsn: str
+    """已挂 `options=-csearch_path=<schema>`,用例默认用它。"""
+    bare_dsn: str | None
+    """同角色但**不挂** search_path(回落 `"$user", public`);`role="none"` 时为 None。"""
+
+
+def _admin_dsn() -> str | None:
+    """读 `.env` 的 `PGW_TELEMETRY_PG_DSN` 并剥掉 SQLAlchemy 风格的 `+driver` 后缀。"""
+    merged = {**dotenv_values(".env"), **os.environ}
+    raw = merged.get("PGW_TELEMETRY_PG_DSN")
+    if not raw:
+        return None
+    scheme, sep, rest = raw.partition("://")
+    return f"{scheme.partition('+')[0]}{sep}{rest}"
+
+
+def _require_admin_dsn() -> str:
+    """取管理连接串;未配置则 skip,连错库则 fail(不是 skip)。
+
+    库名守卫不肯降级成 skip: 这个实例上还有 app/chs_prod 等在用库,把"连错库"
+    悄悄跳过,等于让一次配置事故以"没跑那些测试"的形态过关。
+    """
+    value = _admin_dsn()
+    if value is None:
+        pytest.skip("PGW_TELEMETRY_PG_DSN 未配置")
+    if not value.rstrip("/").endswith("/polygateway"):
+        pytest.fail(f"PG 集成测试只允许连 polygateway 专用库,当前 DSN 库名不符: {value!r}")
+    return value
+
+
+def _with_search_path(dsn: str, schema: str) -> str:
+    sep = "&" if "?" in dsn else "?"
+    return f"{dsn}{sep}options=-csearch_path%3D{schema}"
+
+
+def _as_role(dsn: str, role: str) -> str:
+    """把 DSN 的用户名口令段换成沙箱角色的,其余(主机/库/参数)原样保留。
+
+    **换不掉就报错,绝不原样返回**: `postgresql://h:5432/db`(口令走 PGPASSWORD /
+    .pgpass / trust)与 `postgresql:///db?host=/var/run/postgresql`(unix socket)
+    都是合法 DSN,却没有可替换的内联凭据段。静默返回原串的后果不是测试报错,而是
+    沙箱以**管理身份**建成、用例照常绿,同时 `bare_dsn` 变成超级用户连接——最坏
+    情况用例会拿它跑真实 `--apply`,删空共享表之后才在退出码断言上红。
+    这正是 P5"严禁默认值掩盖错误"要挡的形态。
+    """
+    swapped, count = re.subn(r"//[^@/]+@", f"//{role}:{_SANDBOX_PASSWORD}@", dsn, count=1)
+    if count != 1:
+        raise RuntimeError(
+            f"DSN 里没有可替换的内联凭据段,沙箱角色 {role} 无法生效,拒绝以管理身份继续。"
+            "请把 PGW_TELEMETRY_PG_DSN 写成 postgresql://<用户>:<口令>@<主机>/<库> 的形态。"
+        )
+    return swapped
+
+
+@pytest.fixture
+async def pg_catalog_probe():
+    """只读地查 PG catalog,**仅供工厂自测核对残留**,不是通用查询入口。
+
+    它拿的是管理连接,故有意只暴露给 `test_pg_sandbox.py` 这一类"验证隔离本身
+    是否成立"的用例;业务断言一律走 `PgSandbox.dsn`。
+    """
+    import asyncpg
+
+    dsn = _require_admin_dsn()
+
+    async def probe(sql: str, *args: object) -> list[tuple]:
+        # 只读校验不是形式主义: 这个闭包持的是管理连接,不设限就等于把"用例够不到
+        # 管理能力"这句话降格成一句 docstring 里的请求。
+        if not sql.lstrip().upper().startswith("SELECT"):
+            raise RuntimeError(f"pg_catalog_probe 只接受 SELECT 语句,收到: {sql[:60]!r}")
+        conn = await asyncpg.connect(dsn, timeout=10)
+        try:
+            return [tuple(r) for r in await conn.fetch(sql, *args)]
+        finally:
+            await conn.close()
+
+    return probe
+
+
+@pytest.fixture
+async def pg_sandbox():
+    """一次性沙箱工厂: `await pg_sandbox(ddl=..., role=...)`,清理由 fixture 兜底。
+
+    同一条用例可以要多个沙箱(如"A 的角色去动 B 的表"),它们按后进先出清理。
+    """
+    import asyncpg
+
+    admin_dsn = _require_admin_dsn()
+    # 清理动作栈: 每建成一个对象就入栈一条,setup 中途失败与正常 teardown 共用
+    # 同一条退栈路径——两处各写一份的话,失败那条永远是没被测过的那份。
+    cleanups: list[str] = []
+
+    async def _run_as_admin(*statements: str) -> None:
+        conn = await asyncpg.connect(admin_dsn, timeout=10)
+        try:
+            for statement in statements:
+                await conn.execute(statement)
+        finally:
+            await conn.close()
+
+    async def _unwind(statements: list[str]) -> None:
+        """逆序执行清理并**逐条容错**: 一条失败不该拖累其余对象的清理。
+
+        吞掉异常是不行的(残留会静默累积),但让第一条失败中断整栈更糟——角色是
+        全局对象,漏掉的每一个都要人手工去删。故全部试完再抛出第一个异常。
+        """
+        first: BaseException | None = None
+        for statement in reversed(statements):
+            try:
+                await _run_as_admin(statement)
+            except Exception as exc:  # noqa: BLE001 — 见 docstring: 收集而非吞没
+                first = first or exc
+        statements.clear()
+        if first is not None:
+            raise first
+
+    async def make(
+        *,
+        ddl: str | None = None,
+        extra: Sequence[str] = (),
+        role: _Role = "none",
+        grants: Sequence[str] = ("SELECT", "INSERT"),
+    ) -> PgSandbox:
+        # 权限门在建任何对象**之前**: pytest.skip 抛的是 BaseException,若它在
+        # 已建对象之后触发,清理会去 DROP 从未建成的东西并把 skip 盖掉。
+        if role != "none":
+            conn = await asyncpg.connect(admin_dsn, timeout=10)
+            try:
+                can_create = await conn.fetchval(
+                    "SELECT rolcreaterole OR rolsuper FROM pg_roles WHERE rolname = current_user"
+                )
+            finally:
+                await conn.close()
+            if not can_create:
+                pytest.skip("当前账号无权建临时角色,跳过需要独占角色的用例")
+
+        # schema 与角色的前缀有意不同: 同名会让 "$user" 命中自有 schema 并遮蔽
+        # 共享表,于是"search_path 落到共享表"这个最坏情况就再也构造不出来。
+        suffix = uuid4().hex[:12]
+        schema = f"pgw_s_{suffix}"
+        role_name = f"pgw_r_{suffix}" if role != "none" else None
+
+        # 本次调用自己的清理栈: 失败只回滚**本次**建成的对象。同一条用例常要两个
+        # 沙箱(如"A 的角色去动 B 的表"),回滚整栈会把已通过断言依赖的对象也删掉。
+        local: list[str] = []
+        try:
+            if role_name is not None:
+                await _run_as_admin(f"CREATE ROLE {role_name} LOGIN PASSWORD '{_SANDBOX_PASSWORD}'")
+                # DROP OWNED BY 必须排在 DROP ROLE 之前: 角色仍持有对象时删不掉
+                local.append(f"DROP ROLE IF EXISTS {role_name}")
+                local.append(f"DROP OWNED BY {role_name}")
+            owner_clause = f" AUTHORIZATION {role_name}" if role == "owner" else ""
+            await _run_as_admin(f"CREATE SCHEMA {schema}{owner_clause}")
+            local.append(f"DROP SCHEMA IF EXISTS {schema} CASCADE")
+
+            bare = _as_role(admin_dsn, role_name) if role_name is not None else None
+            # role="owner" 时 DDL 由角色自己执行,表属主才会是它;"grantee" 的现场
+            # 恰恰相反——表由别的账号建好,角色只拿到表级权限。
+            ddl_dsn = _with_search_path(bare if role == "owner" else admin_dsn, schema)
+            if ddl is not None:
+                conn = await asyncpg.connect(ddl_dsn, timeout=10)
+                try:
+                    await conn.execute(ddl)
+                    for statement in extra:
+                        await conn.execute(statement)
+                finally:
+                    await conn.close()
+
+            if role == "grantee":
+                await _run_as_admin(f"GRANT USAGE ON SCHEMA {schema} TO {role_name}")
+                if ddl is not None:
+                    await _run_as_admin(
+                        f"GRANT {', '.join(grants)} ON ALL TABLES IN SCHEMA {schema} TO {role_name}"
+                    )
+                # 关键: 绝不 GRANT CREATE ON SCHEMA —— 缺的正是这一项
+
+            used = bare if role_name is not None else admin_dsn
+            sandbox = PgSandbox(
+                schema=schema,
+                role=role_name,
+                dsn=_with_search_path(used, schema),
+                bare_dsn=bare,
+            )
+            if role_name is not None:
+                # 字符串替换成功不等于连上去就是那个角色(PGUSER 等环境变量仍可能
+                # 盖掉 DSN 里的用户名)。这道校验按**实际身份**兜底: 整个设计的价值
+                # 都压在"跑脚本的那个连接对共享表无权"上,不值得只用一次字符串比较
+                # 来担保。它必须留在 try 之内——出了这个块,清理动作已经并进 fixture
+                # 级的栈,再回滚一次就会对同一个角色跑两遍 DROP OWNED BY(它没有
+                # IF EXISTS,第二遍必报错)。
+                conn = await asyncpg.connect(sandbox.dsn, timeout=10)
+                try:
+                    actual = await conn.fetchval("SELECT current_user")
+                finally:
+                    await conn.close()
+                if actual != role_name:
+                    raise RuntimeError(
+                        f"沙箱 DSN 连上去的身份是 {actual!r},不是预期的 {role_name!r};"
+                        "权限边界不成立,拒绝把这个沙箱交出去。"
+                    )
+        except BaseException:
+            await _unwind(local)
+            raise
+        cleanups.extend(local)
+
+        return sandbox
+
+    yield make
+    await _unwind(cleanups)

tests/integration/test_pg_sandbox.py

@@ -0,0 +1,201 @@
+"""`conftest.py` 沙箱工厂自身的行为测试(issue #18 Task 1)。
+
+工厂是本次一切隔离的地基: 它若在 setup 中途失败时漏掉清理、或让角色名与
+schema 名撞上,受害的不是这一个文件,而是此后每一条 PG 用例。故它必须先被测。
+
+**这里的断言全部只看自建对象与 PG catalog**,不读任何共享数据。
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tests.integration.conftest import _as_role
+
+_DDL = "CREATE TABLE llm_calls (call_id TEXT PRIMARY KEY, created_at TIMESTAMPTZ DEFAULT now())"
+
+
+@pytest.fixture
+async def assert_no_leftovers(pg_catalog_probe):
+    """收集沙箱名,在 `pg_sandbox` 清理之后回查它们是否真的没了。
+
+    必须比 `pg_sandbox` **先** setup: pytest 的 finalizer 是后进先出,先 setup
+    的后 teardown——本 fixture 的检查因此发生在沙箱清理之后,而不是之前。
+    """
+    seen: list[tuple[str, str | None]] = []
+    yield seen
+    for schema, role in seen:
+        left = await pg_catalog_probe("SELECT nspname FROM pg_namespace WHERE nspname = $1", schema)
+        assert left == [], f"沙箱 schema 未清理: {schema}"
+        if role is not None:
+            left = await pg_catalog_probe("SELECT rolname FROM pg_roles WHERE rolname = $1", role)
+            assert left == [], f"沙箱角色未清理: {role}"
+
+
+async def _oid_of_llm_calls(dsn: str) -> int | None:
+    import asyncpg
+
+    conn = await asyncpg.connect(dsn, timeout=10)
+    try:
+        return await conn.fetchval("SELECT to_regclass('llm_calls')::oid")
+    finally:
+        await conn.close()
+
+
+class TestRoleDsnConstruction:
+    """凭据替换失败必须**当场报错**,不许退回管理身份(合并前审查的 P1)。
+
+    这条防线的失效形态特别隐蔽: 替换不上时 `re.sub` 原样返回管理连接串,沙箱
+    "看起来"建好了、用例照常绿,而 `bare_dsn` 其实是超级用户——最坏情况用例
+    会拿它跑真实 `--apply`,把共享表删空之后才在 `assert returncode == 2` 上红。
+    行已经没了。设计 §5.1 要的是"越界做不到",不是"越界会被发现"。
+    """
+
+    def test_inline_credentials_are_replaced(self):
+        swapped = _as_role("postgresql://app:secret@h:5432/polygateway", "pgw_r_x")
+
+        assert swapped.startswith("postgresql://pgw_r_x:")
+        assert "app:secret" not in swapped
+
+    @pytest.mark.parametrize(
+        "dsn",
+        [
+            "postgresql://h:5432/polygateway",  # 口令走 PGPASSWORD / .pgpass / trust
+            "postgresql:///polygateway?host=/var/run/postgresql",  # unix socket
+        ],
+    )
+    def test_a_dsn_without_inline_credentials_is_refused(self, dsn):
+        """这两种都是合法 DSN,今天的 .env 恰好不是它们——恰好而已。"""
+        with pytest.raises(RuntimeError, match="沙箱角色"):
+            _as_role(dsn, "pgw_r_x")
+
+
+class TestCatalogProbeIsReadOnly:
+    """探针拿的是管理连接,故它只许查——否则"用例够不到管理能力"就是句空话。"""
+
+    async def test_non_select_statements_are_refused(self, pg_catalog_probe):
+        with pytest.raises(RuntimeError, match="只接受 SELECT"):
+            await pg_catalog_probe("DELETE FROM llm_calls WHERE call_id = 'nope'")
+
+
+class TestSchemaOnlySandbox:
+    async def test_table_lands_in_the_sandbox_schema_and_bare_dsn_is_absent(self, pg_sandbox):
+        """`role="none"`: 表落在自建 schema 下;不发角色,故没有裸 DSN 可给。"""
+        sandbox = await pg_sandbox(ddl=_DDL)
+
+        import asyncpg
+
+        conn = await asyncpg.connect(sandbox.dsn, timeout=10)
+        try:
+            where = await conn.fetchval(
+                "SELECT n.nspname FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace "
+                "WHERE c.oid = to_regclass('llm_calls')"
+            )
+        finally:
+            await conn.close()
+
+        assert where == sandbox.schema
+        assert sandbox.role is None
+        assert sandbox.bare_dsn is None
+
+
+class TestOwnerRoleSandbox:
+    async def test_the_role_owns_its_own_table(self, pg_sandbox):
+        """`role="owner"`: 表由角色自己建,故属主是它——与"用维护角色跑"的现场一致。"""
+        sandbox = await pg_sandbox(ddl=_DDL, role="owner")
+
+        import asyncpg
+
+        conn = await asyncpg.connect(sandbox.dsn, timeout=10)
+        try:
+            owner = await conn.fetchval(
+                "SELECT pg_get_userbyid(relowner) FROM pg_class WHERE oid = to_regclass('llm_calls')"
+            )
+        finally:
+            await conn.close()
+
+        assert owner == sandbox.role
+        # 名字必须错开: 同名会让 "$user" 命中自有 schema 并遮蔽真表,
+        # 最坏情况用例就再也走不到那条真实路径上(设计 §5.1 实测)
+        assert sandbox.role != sandbox.schema
+        assert not sandbox.role.startswith("pgw_s_")
+        assert not sandbox.schema.startswith("pgw_r_")
+
+    async def test_bare_dsn_falls_through_to_the_default_search_path(self, pg_sandbox):
+        """裸 DSN 必须真的回落到 `"$user", public`——最坏情况用例全靠它构造现场。"""
+        sandbox = await pg_sandbox(ddl=_DDL, role="owner")
+
+        import asyncpg
+
+        conn = await asyncpg.connect(sandbox.bare_dsn, timeout=10)
+        try:
+            path = await conn.fetchval("SHOW search_path")
+        finally:
+            await conn.close()
+
+        assert path == '"$user", public'
+        # 裸 DSN 解析到的绝不能是沙箱里那张表(否则"落到共享表"的现场是假的)
+        assert await _oid_of_llm_calls(sandbox.bare_dsn) != await _oid_of_llm_calls(sandbox.dsn)
+
+
+class TestGranteeRoleSandbox:
+    async def test_grantee_can_write_but_cannot_create(self, pg_sandbox):
+        """`role="grantee"`: 表属主是 admin,角色只拿表级权限——最小权限部署的现场。"""
+        import asyncpg
+
+        sandbox = await pg_sandbox(ddl=_DDL, role="grantee")
+
+        conn = await asyncpg.connect(sandbox.dsn, timeout=10)
+        try:
+            await conn.execute("INSERT INTO llm_calls (call_id) VALUES ('g1')")
+            assert await conn.fetchval("SELECT count(*) FROM llm_calls") == 1
+            with pytest.raises(asyncpg.exceptions.InsufficientPrivilegeError):
+                await conn.execute("CREATE TABLE another (x TEXT)")
+        finally:
+            await conn.close()
+
+
+class TestCleanup:
+    async def test_setup_failure_leaves_nothing_behind(self, pg_sandbox, pg_catalog_probe):
+        """建到一半失败时也必须删净——角色是**全局**对象,残留不随库消失。"""
+        before_schemas = await pg_catalog_probe(
+            "SELECT nspname FROM pg_namespace WHERE nspname LIKE 'pgw!_%' ESCAPE '!'"
+        )
+        before_roles = await pg_catalog_probe(
+            "SELECT rolname FROM pg_roles WHERE rolname LIKE 'pgw!_%' ESCAPE '!'"
+        )
+
+        with pytest.raises(Exception):  # noqa: B017 — 工厂原样抛出 PG 的 DDL 错误
+            await pg_sandbox(ddl="CREATE TABLE llm_calls (bad NOT_A_REAL_TYPE)", role="owner")
+
+        assert (
+            await pg_catalog_probe(
+                "SELECT nspname FROM pg_namespace WHERE nspname LIKE 'pgw!_%' ESCAPE '!'"
+            )
+            == before_schemas
+        )
+        assert (
+            await pg_catalog_probe(
+                "SELECT rolname FROM pg_roles WHERE rolname LIKE 'pgw!_%' ESCAPE '!'"
+            )
+            == before_roles
+        )
+
+    async def test_a_failure_does_not_roll_back_earlier_sandboxes(self, pg_sandbox):
+        """一次失败只回滚它自己建的东西——同一条用例里先建成的沙箱必须毫发无损。
+
+        "A 的角色去动 B 的表"这类用例一条要两个沙箱;若失败回滚把整栈清空,受害的
+        是那些**已经通过**的断言所依赖的对象,而症状会以"表不见了"的形态出现在
+        与真因无关的地方。
+        """
+        good = await pg_sandbox(ddl=_DDL, role="owner")
+
+        with pytest.raises(Exception):  # noqa: B017 — 工厂原样抛出 PG 的 DDL 错误
+            await pg_sandbox(ddl="CREATE TABLE llm_calls (bad NOT_A_REAL_TYPE)", role="owner")
+
+        assert await _oid_of_llm_calls(good.dsn) is not None, "先前建成的沙箱被误清理"
+
+    async def test_teardown_removes_schema_and_role(self, assert_no_leftovers, pg_sandbox):
+        """正常路径的清理: 断言发生在 `pg_sandbox` teardown **之后**(见 fixture 说明)。"""
+        sandbox = await pg_sandbox(ddl=_DDL, role="owner")
+        assert_no_leftovers.append((sandbox.schema, sandbox.role))

tests/integration/test_redis_cross_connection.py

@@ -73,7 +73,7 @@ class ScriptedTransport:
         self.hang = hang
         self.calls: list[str] = []
 
-    async def complete(self, *, messages, source, stream, overlay, call_id):
+    async def complete(self, *, messages, source, stream, overlay, call_id, reasoning_effort):
         self.calls.append(source.name)
         if self.hang:
             await asyncio.Event().wait()

tests/integration/test_retention_tool_pg.py

@@ -1,11 +1,12 @@
 """`tools/telemetry_retention.py` 的 PostgreSQL 分支测试(issue #12 Task 3,真实 PG)。
 
-DSN 走 .env `PGW_TELEMETRY_PG_DSN`,缺则 skip。
+隔离纪律(issue #18): 本文件跑的是一个**会删数据的脚本**,而实例上的共享表 `llm_calls`
+与真实批跑共用。故**凡启动脚本的用例一律用 `pg_sandbox(role="owner")` 的临时角色跑**:
+该角色对共享表一无所有,越界不是"会被发现",而是数据库层面做不到。
 
-隔离纪律(M4 事故教训): `public.llm_calls` 是与真实批跑共享的表,而本测试跑的是
+这条纪律取代了此前那条"跑完对比共享表行数"的安全网——行数快照守的是安全属性,却把它
-一个**会删数据的脚本**——一律在自建的临时 schema 里操作(DSN 挂 search_path),
+编码成对全局可变量的观测: 外部进程一写就假红,外部插入与脚本误删互相抵消则假阴。
-teardown 只 `DROP SCHEMA ... CASCADE`;分批删除那例另行断言 `public.llm_calls`
+权限边界两个方向都没有。
-的行数前后不变,把"search_path 没生效"这种最坏情况钉成红灯而不是静默删库。
 """
 
 from __future__ import annotations
@@ -16,10 +17,8 @@ import subprocess
 import sys
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
-from uuid import uuid4
 
 import pytest
-from dotenv import dotenv_values
 
 from polygateway.telemetry.schema import PG_DDL
 
@@ -55,20 +54,6 @@ def _partitioned_ddl() -> str:
     )
 
 
-def _dsn_value() -> str | None:
-    merged = {**dotenv_values(".env"), **os.environ}
-    raw = merged.get("PGW_TELEMETRY_PG_DSN")
-    if not raw:
-        return None
-    scheme, sep, rest = raw.partition("://")
-    return f"{scheme.partition('+')[0]}{sep}{rest}"
-
-
-def _search_path_dsn(dsn: str, schema: str) -> str:
-    sep = "&" if "?" in dsn else "?"
-    return f"{dsn}{sep}options=-csearch_path%3D{schema}"
-
-
 def _stamp(delta: timedelta) -> datetime:
     return datetime.now(UTC) + delta
 
@@ -84,43 +69,6 @@ def _run(*args: str, env: dict[str, str] | None = None) -> subprocess.CompletedP
     )
 
 
-@pytest.fixture
-async def dsn():
-    value = _dsn_value()
-    if value is None:
-        pytest.skip("PGW_TELEMETRY_PG_DSN 未配置")
-    # 隔离守卫: 该实例有 app/chs_prod 等在用库,只许打 polygateway 专用库
-    if not value.rstrip("/").endswith("/polygateway"):
-        pytest.fail(f"保留期脚本测试只允许连 polygateway 专用库,当前 DSN 库名不符: {value!r}")
-    return value
-
-
-async def _make_schema(dsn_value: str, prefix: str, ddl: str, extra: tuple[str, ...] = ()) -> str:
-    import asyncpg
-
-    name = f"pgwret_{prefix}_{uuid4().hex[:8]}"
-    conn = await asyncpg.connect(dsn_value, timeout=10)
-    try:
-        await conn.execute(f"CREATE SCHEMA {name}")
-        await conn.execute(f"SET search_path = {name}")
-        await conn.execute(ddl)
-        for statement in extra:
-            await conn.execute(statement)
-    finally:
-        await conn.close()
-    return name
-
-
-async def _drop_schema(dsn_value: str, name: str) -> None:
-    import asyncpg
-
-    conn = await asyncpg.connect(dsn_value, timeout=10)
-    try:
-        await conn.execute(f"DROP SCHEMA {name} CASCADE")
-    finally:
-        await conn.close()
-
-
 async def _seed(schema_dsn: str, rows: list[tuple[str, str, datetime]]) -> None:
     import asyncpg
 
@@ -142,50 +90,31 @@ async def _call_ids(schema_dsn: str) -> list[str]:
     return [r["call_id"] for r in rows]
 
 
-async def _public_count(dsn_value: str) -> int:
-    """共享表的行数;本测试全程不得让它变动一行。"""
-    import asyncpg
-
-    conn = await asyncpg.connect(dsn_value, timeout=10)
-    try:
-        if await conn.fetchval("SELECT to_regclass('public.llm_calls')") is None:
-            return -1
-        return await conn.fetchval("SELECT COUNT(*) FROM public.llm_calls")
-    finally:
-        await conn.close()
-
-
 @pytest.fixture
-async def partitioned_schema(dsn):
+async def partitioned_sandbox(pg_sandbox):
     """临时 schema 内的**分区表**: 脚本必须认出它并让路给 DROP PARTITION。"""
-    name = await _make_schema(
+    return await pg_sandbox(
-        dsn,
+        ddl=_partitioned_ddl(),
-        "part",
-        _partitioned_ddl(),
         extra=(
             "CREATE TABLE llm_calls_all PARTITION OF llm_calls "
             "FOR VALUES FROM ('2000-01-01') TO ('2100-01-01')",
         ),
+        role="owner",
     )
-    yield _search_path_dsn(dsn, name), name
-    await _drop_schema(dsn, name)
 
 
 @pytest.fixture
-async def plain_schema(dsn):
+async def plain_sandbox(pg_sandbox):
     """临时 schema 内的普通表: 存量场景,脚本的分批 DELETE 兜底路径。"""
-    name = await _make_schema(dsn, "plain", PG_DDL)
+    return await pg_sandbox(ddl=PG_DDL, role="owner")
-    yield _search_path_dsn(dsn, name), name
-    await _drop_schema(dsn, name)
 
 
 class TestPartitionedTarget:
     async def test_partitioned_table_exits_three_without_deleting_anything(
-        self, partitioned_schema
+        self, partitioned_sandbox
     ):
-        schema_dsn, schema = partitioned_schema
         await _seed(
-            schema_dsn,
+            partitioned_sandbox.dsn,
             [
                 ("part-old-1", "", _stamp(timedelta(days=-30))),
                 ("part-old-2", "acme", _stamp(timedelta(days=-20))),
@@ -194,24 +123,28 @@ class TestPartitionedTarget:
 
         # 带 --apply 跑: 危险的那条路径必须在真正删之前就被分区探测拦住
         result = _run(
-            "--backend", "postgres", "--dsn", schema_dsn, "--older-than-days", "7", "--apply"
+            "--backend",
+            "postgres",
+            "--dsn",
+            partitioned_sandbox.dsn,
+            "--older-than-days",
+            "7",
+            "--apply",
         )
 
         assert result.returncode == 3, (result.stdout, result.stderr)
         combined = result.stdout + result.stderr
         assert "DROP PARTITION" in combined
         assert "DETACH" in combined
-        assert await _call_ids(schema_dsn) == ["part-old-1", "part-old-2"]
+        assert await _call_ids(partitioned_sandbox.dsn) == ["part-old-1", "part-old-2"]
         # 脚本必须报出它解析到的**限定表名**: 这是"我删的到底是哪张表"的唯一凭据
-        assert f"{schema}.llm_calls" in result.stdout
+        assert f"{partitioned_sandbox.schema}.llm_calls" in result.stdout
 
 
 class TestPlainTableBatches:
-    async def test_apply_deletes_only_expired_rows_in_batches(self, plain_schema, dsn):
+    async def test_apply_deletes_only_expired_rows_in_batches(self, plain_sandbox):
-        schema_dsn, schema = plain_schema
-        before_public = await _public_count(dsn)
         await _seed(
-            schema_dsn,
+            plain_sandbox.dsn,
             [
                 ("old-1", "", _stamp(timedelta(days=-40))),
                 ("old-2", "acme", _stamp(timedelta(days=-30))),
@@ -227,7 +160,7 @@ class TestPlainTableBatches:
             "--backend",
             "postgres",
             "--dsn",
-            schema_dsn,
+            plain_sandbox.dsn,
             "--older-than-days",
             "7",
             "--apply",
@@ -236,8 +169,8 @@ class TestPlainTableBatches:
         )
 
         assert result.returncode == 0, (result.stdout, result.stderr)
-        assert await _call_ids(schema_dsn) == ["fresh-1", "fresh-2"]
+        assert await _call_ids(plain_sandbox.dsn) == ["fresh-1", "fresh-2"]
-        assert f"{schema}.llm_calls" in result.stdout
+        assert f"{plain_sandbox.schema}.llm_calls" in result.stdout
         assert "将删除行数: 5" in result.stdout
         assert "'acme': 3" in result.stdout
         # 5 行 / 每批 2 行 = 3 批,每批各自提交;批次行必须真的出现三条
@@ -245,30 +178,200 @@ class TestPlainTableBatches:
         assert "批次 3" in result.stdout
         assert "批次 4" not in result.stdout
         assert "已删除 5 行" in result.stdout
-        assert await _public_count(dsn) == before_public
 
-    async def test_dry_run_on_a_plain_table_deletes_nothing(self, plain_schema):
+    async def test_dry_run_on_a_plain_table_deletes_nothing(self, plain_sandbox):
-        schema_dsn, _ = plain_schema
+        await _seed(plain_sandbox.dsn, [("old-1", "acme", _stamp(timedelta(days=-30)))])
-        await _seed(schema_dsn, [("old-1", "acme", _stamp(timedelta(days=-30)))])
 
-        result = _run("--backend", "postgres", "--dsn", schema_dsn, "--older-than-days", "7")
+        result = _run("--backend", "postgres", "--dsn", plain_sandbox.dsn, "--older-than-days", "7")
 
         assert result.returncode == 0, (result.stdout, result.stderr)
         assert "将删除行数: 1" in result.stdout
         assert "dry-run" in result.stdout
-        assert await _call_ids(schema_dsn) == ["old-1"]
+        assert await _call_ids(plain_sandbox.dsn) == ["old-1"]
+
+
+class TestExplicitTable:
+    """`--table SCHEMA.NAME` 的真实解析行为(issue #18 设计 §4.1;判据 1b)。
+
+    单测只能验参数分类,验不了 `to_regclass` 的语义——schema 不存在返 NULL 而非抛错、
+    引号限定名区分大小写、无权限落在 `COUNT` 而非解析,这三条都必须真连库才成立。
+    """
+
+    async def test_explicit_table_deletes_exactly_like_the_implicit_path(self, plain_sandbox):
+        await _seed(
+            plain_sandbox.dsn,
+            [
+                ("old-1", "", _stamp(timedelta(days=-40))),
+                ("old-2", "acme", _stamp(timedelta(days=-30))),
+                ("old-3", "acme", _stamp(timedelta(days=-20))),
+                ("old-4", "acme", _stamp(timedelta(days=-15))),
+                ("old-5", "", _stamp(timedelta(days=-10))),
+                ("fresh-1", "acme", _stamp(timedelta(days=-1))),
+                ("fresh-2", "", _stamp(timedelta(hours=-1))),
+            ],
+        )
+
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            plain_sandbox.dsn,
+            "--older-than-days",
+            "7",
+            "--apply",
+            "--batch-size",
+            "2",
+            "--table",
+            f"{plain_sandbox.schema}.llm_calls",
+        )
+
+        # 与不给 --table 的那条用例逐条同款: 显式声明只改"怎么找到表",不改任何行为
+        assert result.returncode == 0, (result.stdout, result.stderr)
+        assert await _call_ids(plain_sandbox.dsn) == ["fresh-1", "fresh-2"]
+        assert f"{plain_sandbox.schema}.llm_calls" in result.stdout
+        assert "将删除行数: 5" in result.stdout
+        assert "'acme': 3" in result.stdout
+        assert "批次 1" in result.stdout
+        assert "批次 3" in result.stdout
+        assert "批次 4" not in result.stdout
+        assert "已删除 5 行" in result.stdout
+
+    async def test_table_in_a_nonexistent_schema_exits_two(self, plain_sandbox):
+        """schema 不存在时 `to_regclass` 返 NULL(不抛错),故落进既有的"目标不可用"。"""
+        await _seed(plain_sandbox.dsn, [("old-1", "acme", _stamp(timedelta(days=-30)))])
+        missing = "pgw_s_nosuchxxxxxxxx"
+
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            plain_sandbox.dsn,
+            "--older-than-days",
+            "7",
+            "--apply",
+            "--table",
+            f"{missing}.llm_calls",
+        )
+
+        assert result.returncode == 2, (result.stdout, result.stderr)
+        assert missing in result.stderr
+        assert "llm_calls" in result.stderr
+        assert await _call_ids(plain_sandbox.dsn) == ["old-1"]
+
+    async def test_table_owned_by_another_role_exits_two(self, pg_sandbox):
+        """拿 A 的连接指 B 的表: 权限拒绝,两张表都不能少一行。"""
+        sandbox_a = await pg_sandbox(ddl=PG_DDL, role="owner")
+        sandbox_b = await pg_sandbox(ddl=PG_DDL, role="owner")
+        await _seed(sandbox_a.dsn, [("a-old", "acme", _stamp(timedelta(days=-30)))])
+        await _seed(sandbox_b.dsn, [("b-old", "acme", _stamp(timedelta(days=-30)))])
+
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            sandbox_a.dsn,
+            "--older-than-days",
+            "7",
+            "--apply",
+            "--table",
+            f"{sandbox_b.schema}.llm_calls",
+        )
+
+        assert result.returncode == 2, (result.stdout, result.stderr)
+        assert await _call_ids(sandbox_a.dsn) == ["a-old"]
+        assert await _call_ids(sandbox_b.dsn) == ["b-old"]
+
+    async def test_explicit_partitioned_table_still_exits_three(self, partitioned_sandbox):
+        await _seed(partitioned_sandbox.dsn, [("part-old-1", "acme", _stamp(timedelta(days=-30)))])
+
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            partitioned_sandbox.dsn,
+            "--older-than-days",
+            "7",
+            "--apply",
+            "--table",
+            f"{partitioned_sandbox.schema}.llm_calls",
+        )
+
+        assert result.returncode == 3, (result.stdout, result.stderr)
+        combined = result.stdout + result.stderr
+        assert "DROP PARTITION" in combined
+        assert "DETACH" in combined
+        assert await _call_ids(partitioned_sandbox.dsn) == ["part-old-1"]
+
+
+class TestInferredTargetHint:
+    async def test_apply_without_table_warns_that_the_target_was_inferred(self, plain_sandbox):
+        """未钉死目标时必须当场说清"这张表是猜出来的"(设计 §4.4;判据 2)。
+
+        该提示行只在 PG 分支打印,不连库的单测触发不到它,故验收落在集成层。
+        """
+        await _seed(plain_sandbox.dsn, [("old-1", "acme", _stamp(timedelta(days=-30)))])
+
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            plain_sandbox.dsn,
+            "--older-than-days",
+            "7",
+            "--apply",
+        )
+
+        assert result.returncode == 0, (result.stdout, result.stderr)
+        assert "search_path" in result.stdout
+        assert "--table" in result.stdout
+
+    async def test_dry_run_does_not_print_the_hint(self, plain_sandbox):
+        """dry-run 不可逆性为零,它本就以"看清楚再决定"为用途,多一行提示是噪音。"""
+        await _seed(plain_sandbox.dsn, [("old-1", "acme", _stamp(timedelta(days=-30)))])
+
+        result = _run("--backend", "postgres", "--dsn", plain_sandbox.dsn, "--older-than-days", "7")
+
+        assert result.returncode == 0, (result.stdout, result.stderr)
+        assert "--table" not in result.stdout
+
+
+class TestSearchPathFallsThrough:
+    async def test_bare_search_path_cannot_touch_the_shared_table(self, plain_sandbox):
+        """最坏情况: `search_path` 没生效,脚本落到共享表 `llm_calls` 上(设计 §5.3)。
+
+        用沙箱角色的**裸** DSN 跑(search_path 回落 `"$user", public`,而角色名与 schema
+        名有意错开,故 `"$user"` 命不中沙箱),不给 `--table`,带 `--apply`。角色对共享表
+        无任何权限,于是两条可能的路都收敛到退出码 2: 库里有那张表则 `COUNT` 被权限拒绝,
+        没有则解析不到。**不断言 PG 的英文原文**——服务端 `lc_messages` 不由测试掌握。
+        """
+        await _seed(plain_sandbox.dsn, [("old-1", "acme", _stamp(timedelta(days=-30)))])
+
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            plain_sandbox.bare_dsn,
+            "--older-than-days",
+            "7",
+            "--apply",
+        )
+
+        assert result.returncode == 2, (result.stdout, result.stderr)
+        assert result.stderr.strip()
+        assert "llm_calls" in result.stderr
+        # 沙箱表一行不少: 脚本既没删共享表,也没绕回来删自己这张
+        assert await _call_ids(plain_sandbox.dsn) == ["old-1"]
 
 
 class TestMissingAsyncpg:
-    async def test_missing_asyncpg_exits_two_without_touching_rows(self, plain_schema, tmp_path):
+    async def test_missing_asyncpg_exits_two_without_touching_rows(self, plain_sandbox, tmp_path):
         """缺 asyncpg 必须明确报错退出(码 2),不静默降级——这是运维工具不是库路径。
 
         用一个只 `raise ImportError` 的临时 `asyncpg.py` 挂进子进程的 PYTHONPATH 构造该
         场景: 脚本跑在子进程里,monkeypatch 对它无效。DSN 用**真实可连**的临时 schema,
         这样"没有导入守卫"的实现会走通并退出 0,而不是碰巧也退出 2 而假绿。
         """
-        schema_dsn, _ = plain_schema
+        await _seed(plain_sandbox.dsn, [("old-1", "acme", _stamp(timedelta(days=-30)))])
-        await _seed(schema_dsn, [("old-1", "acme", _stamp(timedelta(days=-30)))])
         stub = tmp_path / "stub"
         stub.mkdir()
         (stub / "asyncpg.py").write_text(
@@ -285,7 +388,7 @@ class TestMissingAsyncpg:
             "--backend",
             "postgres",
             "--dsn",
-            schema_dsn,
+            plain_sandbox.dsn,
             "--older-than-days",
             "7",
             "--apply",
@@ -295,4 +398,4 @@ class TestMissingAsyncpg:
         assert result.returncode == 2, (result.stdout, result.stderr)
         assert "asyncpg" in result.stderr
         assert "pip install" in result.stderr
-        assert await _call_ids(schema_dsn) == ["old-1"]
+        assert await _call_ids(plain_sandbox.dsn) == ["old-1"]

tests/live_evidence.py

@@ -0,0 +1,316 @@
+"""真实测试的有限证据判定；不读取环境、不请求网络、不记录原始正文。"""
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+from uuid import uuid4
+
+from polygateway.errors import RequestRejectedError
+from polygateway.types import ThinkingObservation
+
+
+@dataclass(frozen=True)
+class HttpEvidence:
+    """一次 HTTP 的内存证据，禁止直接序列化。"""
+
+    call_id: str
+    request_checks: tuple[tuple[str, bool], ...]
+    status_code: int
+    error_body: bytes | None
+    raw_identity: tuple[bool, str | None]
+
+
+@dataclass(frozen=True)
+class AttemptEvidence:
+    """一次 transport 尝试，可以没有 HTTP。"""
+
+    call_id: str
+    http: tuple[HttpEvidence, ...]
+    error: Exception | None
+
+
+@dataclass(frozen=True)
+class LiveVerdict:
+    """测试命题的结论，不等同于 pytest 退出码。"""
+
+    status: Literal["PASS", "FAIL", "UNCOVERED"]
+    reason: str
+
+
+def strict_json(body: bytes) -> Any:
+    """独立解析完整 UTF-8 JSON，拒绝重复键及非标准常量。"""
+
+    def pairs(items: list[tuple[str, Any]]) -> dict[str, Any]:
+        """重复键不允许被后值掩盖。"""
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise ValueError("重复 JSON 键")
+            result[key] = value
+        return result
+
+    def invalid(value: str) -> None:
+        """拒绝非标准数值常量。"""
+        raise ValueError("非法 JSON 常量")
+
+    return json.loads(body.decode("utf-8"), object_pairs_hook=pairs, parse_constant=invalid)
+
+
+def messages_digest(messages: Any) -> str:
+    """只在内存比较提示词摘要，不写提示词。"""
+    return hashlib.sha256(
+        json.dumps(messages, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+
+
+def request_is_valid(event: HttpEvidence) -> bool:
+    """完整且无重复的显式检查才能作为请求资格。"""
+    checks = dict(event.request_checks)
+    common = {"method", "origin", "path", "model", "authorization", "control", "messages_digest"}
+    return (
+        len(checks) == len(event.request_checks)
+        and set(checks) in (common | {"stream"}, common | {"input_shape"})
+        and all(value is True for value in checks.values())
+    )
+
+
+def _single_error(error: Exception, attempts: Sequence[AttemptEvidence]) -> HttpEvidence | None:
+    """仅接受可与最终异常精确配对的独立单次错误。"""
+    if not isinstance(error, RequestRejectedError) or len(attempts) != 1:
+        return None
+    attempt = attempts[0]
+    if attempt.error is not error or len(attempt.http) != 1:
+        return None
+    event = attempt.http[0]
+    if event.call_id != attempt.call_id or not request_is_valid(event):
+        return None
+    if event.status_code != error.status_code:
+        return None
+    return event
+
+
+def error_machine_type(event: HttpEvidence) -> str | None:
+    """完整错误体中的唯一机器字段；不检查正文子串。"""
+    body = event.error_body
+    if body is None or not 0 < len(body) <= 65536:
+        return None
+    try:
+        data = strict_json(body)
+    except (ValueError, UnicodeError):
+        return None
+    if not isinstance(data, dict) or not isinstance(data.get("error"), dict):
+        return None
+    value = data["error"].get("type")
+    return value if isinstance(value, str) else None
+
+
+def classify_live_failure(error: Exception, attempts: Sequence[AttemptEvidence]) -> LiveVerdict:
+    """默认失败；唯一自动外因是完整证据支持的 404 model_not_found。"""
+    event = _single_error(error, attempts)
+    if (
+        event is not None
+        and event.status_code == 404
+        and error_machine_type(event) == "model_not_found"
+    ):
+        return LiveVerdict("UNCOVERED", "端点回报该请求型号不可用")
+    return LiveVerdict("FAIL", "无满足窄外因契约的完整独立证据")
+
+
+def assess_expected_rejection(
+    error: Exception, attempts: Sequence[AttemptEvidence], *, status_code: int, machine_type: str
+) -> LiveVerdict:
+    """预先声明的拒绝命题，不把一般 400 当不支持档位。"""
+    event = _single_error(error, attempts)
+    if (
+        event is not None
+        and event.status_code == status_code
+        and error_machine_type(event) == machine_type
+    ):
+        return LiveVerdict("PASS", "符合预声明的拒绝类型、状态和机器字段")
+    return LiveVerdict("FAIL", "不符合预声明拒绝证据")
+
+
+def assess_model_identity(
+    *,
+    requested: str,
+    aliases: frozenset[str],
+    reported: str | None,
+    raw_identity: tuple[bool, str | None],
+    request_valid: bool,
+) -> LiveVerdict:
+    """公共身份异常只有原始独立证据才能归因上游。"""
+    if not request_valid:
+        return LiveVerdict("FAIL", "实发请求校验不完整或不符")
+    allowed = {requested, *aliases}
+    captured, raw = raw_identity
+    if captured and raw != reported:
+        return LiveVerdict("FAIL", "公共身份与独立原始身份不一致")
+    if reported in allowed:
+        return LiveVerdict("PASS", "身份合格")
+    if not captured:
+        return LiveVerdict("FAIL", "身份来源无法区分")
+    return LiveVerdict("UNCOVERED", "独立原始响应身份缺失或不属于显式别名")
+
+
+def assess_thinking_coverage(
+    observations: Sequence[ThinkingObservation],
+    *,
+    planned_rounds: int,
+    proposition: Literal["enabled", "disabled", "cannot_disable"],
+) -> LiveVerdict:
+    """按独立命题裁定；缺轮不减分母，UNKNOWN 不证明关闭。"""
+    if planned_rounds < 1 or len(observations) != planned_rounds:
+        return LiveVerdict("FAIL", "计划轮次不完整")
+    if any(not isinstance(item, ThinkingObservation) for item in observations):
+        return LiveVerdict("FAIL", "观测类型不符")
+    observed = observations.count(ThinkingObservation.OBSERVED)
+    unknown = observations.count(ThinkingObservation.UNKNOWN)
+    if proposition == "enabled":
+        if observed > planned_rounds / 2:
+            return LiveVerdict("PASS", "完整轮次多数观测到推理")
+        return LiveVerdict("UNCOVERED" if unknown else "FAIL", "开启证据未达多数")
+    if proposition == "disabled":
+        if observed:
+            return LiveVerdict("FAIL", "观测到推理，证伪关闭声明")
+        return LiveVerdict(
+            "UNCOVERED" if unknown else "PASS",
+            "UNKNOWN 不证明关闭" if unknown else "每轮明确 ABSENT",
+        )
+    if proposition == "cannot_disable":
+        if observed:
+            return LiveVerdict("PASS", "本条件下仍推理；不外推所有私有参数")
+        return LiveVerdict("UNCOVERED" if unknown else "FAIL", "缺少仍推理的证据")
+    raise ValueError("未知测试命题")
+
+
+def summarize_verdicts(verdicts: Sequence[LiveVerdict], *, planned_rounds: int) -> dict[str, int]:
+    """保留失败、未覆盖与缺轮的独立计数。"""
+    if planned_rounds < len(verdicts):
+        raise ValueError("实际轮次超出计划")
+    return {
+        **{
+            status: sum(v.status == status for v in verdicts)
+            for status in ("PASS", "FAIL", "UNCOVERED")
+        },
+        "missing": planned_rounds - len(verdicts),
+    }
+
+
+_SAFE_FIELDS = frozenset(
+    {
+        "provider",
+        "requested_model",
+        "reported_model",
+        "stream",
+        "requested_effort",
+        "applied_effort",
+        "session_id",
+        "parent_call_id",
+        "attempts",
+        "status",
+        "reason",
+        "completed_rounds",
+        "planned_rounds",
+        "thinking_observation",
+        "prompt_tokens",
+        "completion_tokens",
+        "reasoning_tokens",
+        "thinking_chars",
+        "counts",
+        "proposition",
+        "error_type",
+        "error_status",
+        "evidence_notes",
+        "subruns",
+    }
+)
+_ATTEMPT_FIELDS = frozenset({"call_id", "error_type", "http"})
+_HTTP_FIELDS = frozenset(
+    {"status_code", "request_checks", "identity_captured", "error_body_complete", "machine_type"}
+)
+
+
+def _validate_safe(fields: Mapping[str, Any]) -> None:
+    """拒绝原始异常和证据对象，嵌套字段也有白名单。"""
+    if set(fields) - _SAFE_FIELDS:
+        raise ValueError("报告含非白名单字段")
+    for attempt in fields.get("attempts", []):
+        if not isinstance(attempt, dict) or set(attempt) != _ATTEMPT_FIELDS:
+            raise ValueError("非法 attempt 报告")
+        for event in attempt["http"]:
+            if not isinstance(event, dict) or set(event) != _HTTP_FIELDS:
+                raise ValueError("非法 HTTP 报告")
+            if event["machine_type"] not in ("model_not_found", "omitted"):
+                raise ValueError("报告机器字段不是认可枚举")
+            if not isinstance(event["request_checks"], dict) or any(
+                type(v) is not bool for v in event["request_checks"].values()
+            ):
+                raise ValueError("请求校验报告只允许布尔值")
+    # 不提供 default=str：原始异常、bytes、dataclass 均必须失败。
+    json.dumps(fields, ensure_ascii=False, allow_nan=False)
+
+
+def write_live_round(
+    output_dir: Path,
+    *,
+    run_id: str,
+    matrix_id: str,
+    round_index: int,
+    safe_fields: Mapping[str, Any],
+) -> Path:
+    """仅接收已脱敏字段；独占文件写入失败必须冒泡。"""
+    _validate_safe(safe_fields)
+    if round_index < 0 or not re.fullmatch(r"[a-zA-Z0-9_-]+", run_id + matrix_id):
+        raise ValueError("报告路径标识非法")
+    directory = output_dir / run_id
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{matrix_id}-{round_index}-{uuid4().hex}.md"
+    text = json.dumps(dict(safe_fields), ensure_ascii=False, indent=2, allow_nan=False)
+    with path.open("x", encoding="utf-8") as handle:
+        handle.write(f"# {matrix_id} · 轮次 {round_index}\n\n```json\n{text}\n```\n")
+    return path
+
+
+def safe_attempts(attempts: Sequence[AttemptEvidence]) -> list[dict[str, Any]]:
+    """只导出事实、异常类与认可机器枚举；任意上游字符串一律省略。"""
+    return [
+        {
+            "call_id": attempt.call_id,
+            "error_type": type(attempt.error).__name__ if attempt.error else None,
+            "http": [
+                {
+                    "status_code": event.status_code,
+                    "request_checks": dict(event.request_checks),
+                    "identity_captured": event.raw_identity[0],
+                    "error_body_complete": event.error_body is not None,
+                    "machine_type": (
+                        "model_not_found"
+                        if error_machine_type(event) == "model_not_found"
+                        else "omitted"
+                    ),
+                }
+                for event in attempt.http
+            ],
+        }
+        for attempt in attempts
+    ]
+
+
+def combine_live_verdicts(verdicts: Sequence[LiveVerdict]) -> LiveVerdict:
+    """部分失败优先于未覆盖；部分未覆盖不得汇总全 PASS。"""
+    if any(verdict.status == "FAIL" for verdict in verdicts):
+        return LiveVerdict("FAIL", "至少一个必需命题失败")
+    if not verdicts or any(verdict.status == "UNCOVERED" for verdict in verdicts):
+        return LiveVerdict("UNCOVERED", "至少一个必需命题未覆盖")
+    return LiveVerdict("PASS", "所有必需命题通过")
+
+
+def qualify_live_rounds(verdicts: Sequence[LiveVerdict], *, planned_rounds: int) -> LiveVerdict:
+    """汇总请求／身份资格，缺轮绝不缩小分母。"""
+    if planned_rounds < 1 or len(verdicts) != planned_rounds:
+        return LiveVerdict("FAIL", "计划轮次缺失")
+    return combine_live_verdicts(verdicts)

tests/unit/test_backpressure.py

@@ -210,7 +210,7 @@ class ClockAdvancingTransport:
         self.clock = clock
         self.calls = []
 
-    async def complete(self, *, messages, source, stream, overlay, call_id):
+    async def complete(self, *, messages, source, stream, overlay, call_id, reasoning_effort):
         self.calls.append((source.name, call_id))
         advance, action = self.script.pop(0)
         self.clock.advance(advance)

tests/unit/test_cache.py

@@ -11,7 +11,13 @@ from polygateway.backends.memory.cache import InMemoryCache
 from polygateway.errors import ResultInvalidError, TransientError
 from polygateway.middleware.cache import CacheMW, build_cache_key, digest_messages
 from polygateway.middleware.telemetry import TelemetryEmitter
-from polygateway.types import ChatRequest, LLMResponse, SourceConfig, ThinkingObservation
+from polygateway.types import (
+    ChatRequest,
+    Effort,
+    LLMResponse,
+    SourceConfig,
+    ThinkingObservation,
+)
 
 _MSGS = [{"role": "user", "content": "hi"}]
 
@@ -114,6 +120,62 @@ class TestKeyFormula:
             "m", messages2, "p", None
         )
 
+    def test_request_tier_changes_key(self):
+        """同 messages 跑 low 与 max 不得互相命中(issue #20;issue #4 的逐字翻版)。
+
+        请求级档位必须**独立于** `model_fingerprint` 进 key: 后者是装配期算出的
+        集合级指纹,一次调用改档位不会让它变一个字节。
+        """
+        k_low = build_cache_key("m", _MSGS, "proj", None, reasoning_effort=Effort.LOW)
+        k_max = build_cache_key("m", _MSGS, "proj", None, reasoning_effort=Effort.MAX)
+        assert k_low != k_max
+
+    def test_explicit_none_tier_is_not_the_absent_tier(self):
+        """`None`(不表态)与 `Effort.NONE`(要求不推理)是两个 key。
+
+        二者合并即毒化: "没写档位"的调用会读到"明确关掉推理"那次的响应,
+        而后者的内容恰恰是缺推理过程的。
+        """
+        assert build_cache_key("m", _MSGS, "proj", None) != build_cache_key(
+            "m", _MSGS, "proj", None, reasoning_effort=Effort.NONE
+        )
+
+    def test_absent_tier_keeps_legacy_key(self):
+        """不表态档位时键形逐字不变,存量缓存不被本次升级全量作废。
+
+        golden 值与 `test_empty_sampling_keeps_legacy_key` 同源,取自加
+        `reasoning_effort` 维度之前的实现,不得随实现漂移。
+        """
+        assert build_cache_key(
+            "qwen-max",
+            [{"role": "user", "content": "hi"}],
+            "proj",
+            None,
+            reasoning_effort=None,
+        ) == ("pgw:cache:c54544e8672f4c91373b4a72716a88497445b440b89445aa5379b356b228f58b")
+
+    def test_declared_tier_key_is_a_golden(self):
+        """配了档位那一侧同样要有 golden: 字面量变了就是所有该档缓存冷启动。
+
+        存量(不表态)那侧的 golden 由 `test_absent_tier_keeps_legacy_key` 守着,
+        而"档位怎么写进 key"此前没有任何字面量断言——变异实测把 `str(...)` 换成
+        `repr(...)`,全套件依然全绿(2026-09-05 独立验证查出)。
+        """
+        assert build_cache_key(
+            "qwen-max",
+            [{"role": "user", "content": "hi"}],
+            "proj",
+            None,
+            reasoning_effort=Effort.LOW,
+        ) == ("pgw:cache:21d7be93729635b27d4ee54e0e7e7310554bb04faf08919f8ce83794ac33f575")
+        assert build_cache_key(
+            "qwen-max",
+            [{"role": "user", "content": "hi"}],
+            "proj",
+            "s1",
+            reasoning_effort=Effort.NONE,
+        ) == ("pgw:cache:44f4f1ce1ee39e5003a27f4f21a531554cb54d1c66e936d11008d4ff06ddc5e6")
+
 
 class _Terminal:
     def __init__(self, response):
@@ -163,6 +225,21 @@ class TestCacheFlow:
         third = await mw(ChatRequest(messages=_MSGS, sampling={"seed": 1}), terminal)
         assert third.cache_hit is True and terminal.calls == 2
 
+    async def test_differing_reasoning_effort_does_not_hit(self):
+        """接线门: `CacheMW` 必须把 `request.reasoning_effort` 传进 key 公式。
+
+        只测 `build_cache_key` 不够——参数加了却没人传是本改动最可能的落地方式,
+        那种缺口在公式层的用例里完全看不见。
+        """
+        backend = InMemoryCache()
+        mw = _mw(backend)
+        terminal = _Terminal(_resp())
+        await mw(ChatRequest(messages=_MSGS, reasoning_effort=Effort.LOW), terminal)
+        await mw(ChatRequest(messages=_MSGS, reasoning_effort=Effort.MAX), terminal)
+        assert terminal.calls == 2  # 两档各自回源
+        third = await mw(ChatRequest(messages=_MSGS, reasoning_effort=Effort.LOW), terminal)
+        assert third.cache_hit is True and terminal.calls == 2  # 同档才命中
+
     async def test_structured_injection_does_not_pollute_key(self):
         """CacheMW 读 sampling 而非 overlay: 结构化注入不该改变缓存身份。"""
         backend = InMemoryCache()
@@ -324,6 +401,69 @@ class TestThinkingObservationRehydration:
         assert hit.thinking_observation is ThinkingObservation.UNKNOWN
 
 
+class TestAppliedEffortRehydration:
+    """issue #20: 实际档同样必须复活成枚举,理由与 `thinking_observation` 逐条相同。
+
+    JSON 里存的是 `StrEnum` 的字符串值;不转就复活成裸 str,而库内一路是
+    `is Effort.LOW` 的身份比较——命中路径上会静默判否,且下游拿到的类型与字段
+    注解分叉。缓存是档位的**第三条入口**(另两条是 `.env` 解析与 `chat()` 参数),
+    归一化不变式必须在这里也闭合。
+    """
+
+    async def test_hit_replays_enum_instance_not_bare_str(self):
+        backend = InMemoryCache()
+        mw = _mw(backend)
+        terminal = _Terminal(_resp(applied_effort=Effort.LOW))
+        await mw(ChatRequest(messages=_MSGS), terminal)
+        hit = await mw(ChatRequest(messages=_MSGS), terminal)
+        assert hit.cache_hit is True and terminal.calls == 1
+        assert isinstance(hit.applied_effort, Effort)
+        assert hit.applied_effort is Effort.LOW
+
+    async def test_unknown_tier_degrades_to_none_and_still_hits(self):
+        """域外档位降级为 None(=不知道这次跑在哪档),不作废内容完好的条目。
+
+        降级方向与 `thinking_observation` 同源: 共用一个 Redis 的项目里,先升级
+        的那个可能写入本版没有的档位名,未升级的项目若判成未命中,两个版本就会
+        互相打对方的缓存。归因字段不该有能力废掉一条内容完好的响应。
+        """
+        backend = InMemoryCache()
+        mw = _mw(backend)
+        key = build_cache_key("m", _MSGS, "proj", None)
+        poisoned = dataclasses.asdict(_resp(content="from-a-newer-version"))
+        poisoned["applied_effort"] = "ultra"
+        poisoned.pop("structured_data", None)
+        await backend.set(key, json.dumps(poisoned), 3600)
+        terminal = _Terminal(_resp())
+        messages: list[str] = []
+        sink_id = logger.add(messages.append, level="WARNING")
+        try:
+            resp = await mw(ChatRequest(messages=_MSGS), terminal)
+        finally:
+            logger.remove(sink_id)
+        assert terminal.calls == 0 and resp.cache_hit is True
+        assert resp.content == "from-a-newer-version"
+        assert resp.applied_effort is None
+        hits = [m for m in messages if "ultra" in m]
+        assert len(hits) == 1, f"域外档位必须单独告警一次,实得 {len(hits)} 条: {messages}"
+        assert "applied_effort" in hits[0]
+        assert [m for m in messages if "重建失败" in m] == []
+
+    async def test_legacy_entry_without_key_rehydrates_to_none(self):
+        """升级前写入的条目没有该键,必须照常复活并落到默认 None。"""
+        backend = InMemoryCache()
+        mw = _mw(backend)
+        key = build_cache_key("m", _MSGS, "proj", None)
+        legacy = dataclasses.asdict(_resp(content="legacy"))
+        legacy.pop("applied_effort")
+        legacy.pop("structured_data", None)
+        await backend.set(key, json.dumps(legacy), 3600)
+        terminal = _Terminal(_resp())
+        hit = await mw(ChatRequest(messages=_MSGS), terminal)
+        assert hit.content == "legacy" and terminal.calls == 0
+        assert hit.applied_effort is None
+
+
 class _BrokenBackend:
     async def get(self, key):
         raise ConnectionError("redis down")
@@ -430,7 +570,7 @@ class TestTelemetryCapDoesNotPoisonTheCacheKey:
         before = build_cache_key("m", messages, "proj", None)
 
         rec = self._Rows()
-        await TelemetryEmitter(rec, text_cap=8).emit_attempt(
+        await TelemetryEmitter(rec, text_cap=8, scope="LLM").emit_attempt(
             request=ChatRequest(messages=messages),
             source=SourceConfig(
                 name="s1",
@@ -444,6 +584,8 @@ class TestTelemetryCapDoesNotPoisonTheCacheKey:
             latency_ms=1,
             response=_resp(),
             error=None,
+            reasoning_applies=True,
+            operation="chat",
         )
         # 截断确实发生了(否则本用例恒真)
         logged = json.loads(rec.rows[0]["messages"])
@@ -451,3 +593,301 @@ class TestTelemetryCapDoesNotPoisonTheCacheKey:
         assert "(略 112 字)" in logged[1]["content"][0]["text"]
 
         assert build_cache_key("m", messages, "proj", None) == before
+
+
+class TestExplicitCacheMigration:
+    """相同模型身份不代表相同推理策略，隔离必须由调用方显式选择。"""
+
+    def _client(self, cache, source, *, capabilities=None, registry=None):
+        import httpx
+
+        from polygateway.transports.openai_compat import OpenAICompatTransport
+        from tests.unit.test_client import _client, _sse
+
+        sent = []
+
+        def handler(request):
+            payload = json.loads(request.content)
+            sent.append(payload)
+            return _sse(json.dumps(payload, sort_keys=True))
+
+        transport = OpenAICompatTransport(
+            client_factory=lambda src: httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+            capabilities=capabilities,
+            registry=registry,
+        )
+        client = _client(
+            sources=[source],
+            transport=transport,
+            cache=cache,
+            cache_namespace="tenant-a",
+            cache_ttl_s=60,
+        )
+        return client, transport, sent
+
+    @pytest.mark.parametrize("isolation", ["namespace", "salt"])
+    @pytest.mark.parametrize("change", ["capability", "fallback"])
+    async def test_capability_change_requires_explicit_identity(self, isolation, change):
+        from polygateway.client import build_model_fingerprint
+        from polygateway.errors import RequestRejectedError
+        from polygateway.thinking import ThinkingCapability
+        from tests.unit.test_client import _source
+
+        cache = InMemoryCache()
+        source = _source(provider="openai", model="migration-model")
+        if change == "capability":
+            old_cap = ThinkingCapability((Effort.AUTO, Effort.HIGH), "本地旧声明")
+            new_cap = ThinkingCapability((Effort.HIGH,), "本地新声明")
+            tier = Effort.AUTO
+            new_source = source
+        else:
+            old_cap = new_cap = ThinkingCapability((Effort.LOW, Effort.HIGH), "本地映射声明")
+            source = dataclasses.replace(source, effort_fallback="nearest")
+            new_source = dataclasses.replace(source, effort_fallback="error")
+            tier = Effort.MEDIUM
+        assert build_model_fingerprint([source]) == build_model_fingerprint([new_source])
+        old, old_transport, old_sent = self._client(
+            cache, source, capabilities={source.model: old_cap}
+        )
+        new, new_transport, new_sent = self._client(
+            cache, new_source, capabilities={source.model: new_cap}
+        )
+        identity = (
+            {"cache_namespace": "tenant-a:migrated"}
+            if isolation == "namespace"
+            else {"cache_salt": "migrated"}
+        )
+        try:
+            original = await old.chat(_MSGS, reasoning_effort=tier)
+            replay = await new.chat(_MSGS, reasoning_effort=tier)
+            assert replay.cache_hit and replay.content == original.content
+            assert len(old_sent) == 1 and not new_sent
+            with pytest.raises(RequestRejectedError):
+                await new.chat(_MSGS, reasoning_effort=tier, **identity)
+            assert not new_sent
+            assert (await old.chat(_MSGS, reasoning_effort=tier)).cache_hit
+        finally:
+            await old_transport.aclose()
+            await new_transport.aclose()
+
+    @pytest.mark.parametrize("isolation", ["namespace", "salt"])
+    async def test_custom_wire_change_requires_explicit_identity(self, isolation):
+        from polygateway.client import build_model_fingerprint
+        from polygateway.providers import ProviderProfile, ThinkingWire
+        from polygateway.thinking import ThinkingCapability
+        from tests.unit.test_client import _source
+
+        source = _source(provider="custom", model="migration-model")
+        caps = {source.model: ThinkingCapability((Effort.HIGH,), "本地声明")}
+
+        def profile(key):
+            return {
+                "custom": ProviderProfile(
+                    name="custom",
+                    thinking=ThinkingWire(off=None, on_base={}, effort_key=key),
+                    strip_think_tags=False,
+                )
+            }
+
+        cache = InMemoryCache()
+        old, t1, sent1 = self._client(cache, source, capabilities=caps, registry=profile("depth_a"))
+        new, t2, sent2 = self._client(cache, source, capabilities=caps, registry=profile("depth_b"))
+        assert build_model_fingerprint(old._terminal._sources) == build_model_fingerprint(
+            new._terminal._sources
+        )
+        identity = (
+            {"cache_namespace": "tenant-a:migrated"}
+            if isolation == "namespace"
+            else {"cache_salt": "migrated"}
+        )
+        try:
+            original = await old.chat(_MSGS, reasoning_effort=Effort.HIGH)
+            assert (await new.chat(_MSGS, reasoning_effort=Effort.HIGH)).cache_hit
+            migrated = await new.chat(_MSGS, reasoning_effort=Effort.HIGH, **identity)
+            assert not migrated.cache_hit and migrated.content != original.content
+            assert len(sent1) == len(sent2) == 1
+            assert sent2[0]["depth_b"] == "high" and "depth_a" not in sent2[0]
+            assert (await old.chat(_MSGS, reasoning_effort=Effort.HIGH)).content == original.content
+        finally:
+            await t1.aclose()
+            await t2.aclose()
+
+    @pytest.mark.parametrize("isolation", ["namespace", "salt"])
+    async def test_legacy_raw_override_requires_explicit_identity(self, isolation):
+        from polygateway.client import build_model_fingerprint
+        from polygateway.errors import RequestRejectedError
+        from tests.unit.test_client import _source
+
+        source = _source(
+            provider="openai", reasoning_effort="high", extra_body={"reasoning_effort": "low"}
+        )
+        cache = InMemoryCache()
+        key = build_cache_key(build_model_fingerprint([source]), _MSGS, "tenant-a", None)
+        legacy = dataclasses.asdict(_resp(content="legacy-raw-low", applied_effort=Effort.HIGH))
+        legacy.pop("structured_data", None)
+        await cache.set(key, json.dumps(legacy), 60)
+        client, transport, sent = self._client(cache, source)
+        identity = (
+            {"cache_namespace": "tenant-a:migrated"}
+            if isolation == "namespace"
+            else {"cache_salt": "migrated"}
+        )
+        try:
+            assert (await client.chat(_MSGS)).content == "legacy-raw-low"
+            with pytest.raises(RequestRejectedError, match="冲突"):
+                await client.chat(_MSGS, **identity)
+            assert sent == []
+            assert await cache.get(key) is not None
+        finally:
+            await transport.aclose()
+
+    async def test_per_call_namespace_survives_a_changed_factory_default(self):
+        from polygateway import GatewayClient, GatewaySettings
+        from tests.unit.test_client import _ENV, _source
+
+        cache = InMemoryCache()
+        source = _source()
+        old, transport, sent = self._client(cache, source)
+        try:
+            await old.chat(_MSGS, cache_namespace="tenant-a")
+            # 工厂路径和全量注入配置同模型身份；只改默认不能改变显式租户覆盖。
+            settings = GatewaySettings.from_env(
+                env={
+                    **_ENV,
+                    "PGW_CACHE_BACKEND": "memory",
+                    "PGW_CACHE_NAMESPACE": "changed-default",
+                    "PGW_CACHE_TTL_S": "60",
+                }
+            )
+            new = GatewayClient.from_settings(settings, cache=cache)
+            try:
+                assert (await new.chat(_MSGS, cache_namespace="tenant-a")).cache_hit
+                assert len(sent) == 1
+            finally:
+                await new.aclose()
+        finally:
+            await transport.aclose()
+
+    async def test_shared_source_pool_migration_preserves_tenant_boundaries(self):
+        import httpx
+
+        from polygateway.errors import RequestRejectedError
+        from polygateway.thinking import ThinkingCapability
+        from polygateway.transports.openai_compat import OpenAICompatTransport
+        from tests.unit.test_client import _client, _source, _sse
+
+        sources = [
+            _source(name=name, provider="openai", model="shared-model") for name in ("a", "b")
+        ]
+        cache = InMemoryCache()
+        sent = []
+
+        def handler(request):
+            sent.append(request)
+            return _sse()
+
+        transports = [
+            OpenAICompatTransport(
+                client_factory=lambda src: httpx.AsyncClient(
+                    transport=httpx.MockTransport(handler)
+                ),
+                capabilities={"shared-model": ThinkingCapability(choices, "本地声明")},
+            )
+            for choices in ((Effort.AUTO, Effort.HIGH), (Effort.HIGH,))
+        ]
+        clients = [
+            _client(
+                sources=sources, transport=t, cache=cache, cache_namespace="default", cache_ttl_s=60
+            )
+            for t in transports
+        ]
+        try:
+            for tenant in ("tenant-a", "tenant-b"):
+                await clients[0].chat(_MSGS, reasoning_effort="auto", cache_namespace=tenant)
+                assert (
+                    await clients[1].chat(_MSGS, reasoning_effort="auto", cache_namespace=tenant)
+                ).cache_hit
+                with pytest.raises(RequestRejectedError):
+                    await clients[1].chat(
+                        _MSGS, reasoning_effort="auto", cache_namespace=tenant + ":new"
+                    )
+            assert len(sent) == 2
+            for tenant in ("tenant-a", "tenant-b"):
+                assert (
+                    await clients[0].chat(_MSGS, reasoning_effort="auto", cache_namespace=tenant)
+                ).cache_hit
+        finally:
+            for transport in transports:
+                await transport.aclose()
+
+
+class TestCallStatsNotPoisoned:
+    """缓存不得回放历史统计(1.3.5 设计 §3)。
+
+    统计描述**本次**调用;把上次那条存进去再放出来,等于对调用方谎称这次
+    重试了 N 次、耗了 M 毫秒。
+    """
+
+    async def test_serialized_payload_carries_no_call_stats_key(self):
+        from polygateway.types import CallStats
+
+        backend = InMemoryCache()
+        mw = _mw(backend)
+        stats = CallStats(logical_call_id="lc-1", attempts=3, total_latency_ms=900)
+        terminal = _Terminal(_resp(call_stats=stats))
+        await mw(ChatRequest(messages=_MSGS), terminal)
+        key = build_cache_key("m", _MSGS, "proj", None)
+        stored = json.loads(await backend.get(key))
+        assert "call_stats" not in stored  # asdict 会把它摊成 dict,必须显式剔除
+
+    async def test_historic_dict_never_impersonates_call_stats(self):
+        """旧条目里的 `call_stats` dict 会被 `_RESPONSE_FIELDS` 放行,必须显式覆盖。
+
+        不覆盖就会有一个 dict 冒充 `CallStats` 从公共 API 漏给调用方,
+        `resp.call_stats.attempts` 当场 `AttributeError`。
+        """
+        backend = InMemoryCache()
+        mw = _mw(backend)
+        key = build_cache_key("m", _MSGS, "proj", None)
+        poisoned = {
+            "content": "legacy",
+            "thinking": "",
+            "model": "m",
+            "provider": "p",
+            "prompt_tokens": 1,
+            "completion_tokens": 2,
+            "latency_ms": 30,
+            "ttft_ms": 5.0,
+            "max_inter_token_ms": 2.0,
+            "cache_hit": False,
+            "call_id": "orig",
+            "source_name": "s1",
+            "usage_source": "measured",
+            "call_stats": {
+                "logical_call_id": "stale-lc",
+                "attempts": 7,
+                "total_latency_ms": 9999,
+            },
+        }
+        await backend.set(key, json.dumps(poisoned), ttl_s=100)
+        terminal = _Terminal(_resp())
+        hit = await mw(ChatRequest(messages=_MSGS), terminal)
+        assert hit.content == "legacy" and terminal.calls == 0  # 真的走了缓存
+        assert hit.call_stats is None  # dict 不得冒充 CallStats
+
+    async def test_cache_key_is_unchanged_by_the_new_field(self):
+        """新增内部字段不得扰动 key 公式,否则存量缓存全量冷启动(黄金值)。"""
+        from polygateway.types import _CallContext
+
+        class _Clock:
+            def __call__(self):
+                return 1000.0
+
+        ctx = _CallContext(now=_Clock())
+        bare = build_cache_key("m", _MSGS, "proj", None)
+        assert bare == build_cache_key("m", _MSGS, "proj", None)
+        # 带上下文的请求与不带的请求必须落在同一个 key 上
+        with_ctx = ChatRequest(messages=_MSGS, call_context=ctx)
+        without = ChatRequest(messages=_MSGS)
+        assert with_ctx.cache_namespace == without.cache_namespace
+        assert digest_messages(with_ctx.messages) == digest_messages(without.messages)

tests/unit/test_client.py

@@ -12,6 +12,8 @@ from polygateway import (
     AllSourcesExhausted,
     GatewayClient,
     GatewaySettings,
+    RequestRejectedError,
+    ResultInvalidError,
     gather_bounded,
 )
 from polygateway.backends.memory.breaker import InMemoryGate
@@ -24,6 +26,8 @@ from polygateway.transports.openai_compat import OpenAICompatTransport
 from polygateway.types import (
     BackpressurePolicy,
     BreakerConfig,
+    ChatRequest,
+    Effort,
     GlobalLimits,
     RetryPolicy,
     SourceConfig,
@@ -198,6 +202,229 @@ class TestSamplingOverlay:
         assert [c["seed"] for c in captured] == [1, 2]
 
 
+class TestReasoningEffortPriority:
+    """三层优先级: 请求级 > 源级 > `enable_thinking` 语法糖 > 不表态(设计 §4.2)。
+
+    一律抓**真实请求体**而非只查 `ChatRequest` 字段: 档位的价值全在发出去的那几个
+    字节上,只断言中间态会让"字段填了但一路没人读"这种缺口继续通过测试——issue #20
+    的 `extra_body` 绕行正是这么长出来的。
+    """
+
+    def _capturing_client(self, captured, **overrides):
+        def handler(request):
+            captured.append(json.loads(request.content))
+            return _sse()
+
+        return _client(handler=handler, **overrides)
+
+    def _zhipu(self, **overrides):
+        # glm-5.3 的档位是 low/high/max(能力表已登记),zhipu 的 wire 三样俱全,
+        # 是唯一能同时看清"开启形态"与"档位键"的组合
+        overrides.setdefault("model", "glm-5.3")
+        return _source(provider="zhipu", **overrides)
+
+    async def test_request_effort_wins_over_source(self):
+        captured = []
+        source = self._zhipu(reasoning_effort=Effort.LOW)
+        async with self._capturing_client(captured, sources=[source]) as client:
+            await client.chat([{"role": "user", "content": "hi"}], reasoning_effort=Effort.MAX)
+        assert captured[0]["reasoning_effort"] == "max"
+        assert captured[0]["thinking"] == {"type": "enabled"}
+
+    async def test_none_request_does_not_clear_source(self):
+        """请求级不表态 ≠ 请求级要求"不推理": 前者必须让源级默认继续生效。"""
+        captured = []
+        source = self._zhipu(reasoning_effort=Effort.LOW)
+        async with self._capturing_client(captured, sources=[source]) as client:
+            await client.chat([{"role": "user", "content": "hi"}])
+        assert captured[0]["reasoning_effort"] == "low"
+
+    async def test_request_none_tier_is_an_opinion_not_an_absence(self):
+        """请求级 `none` 是"要求不推理",不得被当成"没表态"而回落到源级档位。"""
+        captured = []
+        source = self._zhipu(model="glm-5.2", reasoning_effort=Effort.MAX)
+        async with self._capturing_client(captured, sources=[source]) as client:
+            await client.chat([{"role": "user", "content": "hi"}], reasoning_effort=Effort.NONE)
+        assert captured[0]["thinking"] == {"type": "disabled"}
+        assert "reasoning_effort" not in captured[0]
+
+    @pytest.mark.parametrize(
+        "provider,model,tier",
+        [
+            ("deepseek", "deepseek-v4-pro", "high"),
+            ("zhipu", "glm-5.3", "low"),
+            ("moonshot", "kimi-k3", "low"),
+            ("minimax", "MiniMax-M3", "medium"),
+        ],
+    )
+    async def test_legacy_auto_requires_explicit_migration(self, provider, model, tier):
+        """旧糖配置明确拒绝，显式选择才能恢复可执行请求。"""
+        from dataclasses import replace
+
+        captured = []
+        source = _source(provider=provider, model=model, enable_thinking=True)
+        client = self._capturing_client(captured, sources=[source])
+        try:
+            with pytest.raises(RequestRejectedError):
+                await client.chat([])
+            assert captured == []
+        finally:
+            await client._transport.aclose()
+        client = self._capturing_client(
+            captured, sources=[replace(source, enable_thinking=None, reasoning_effort=tier)]
+        )
+        try:
+            await client.chat([])
+            assert captured[0]["reasoning_effort"] == tier
+        finally:
+            await client._transport.aclose()
+
+
+class TestEffortFallbackWiring:
+    """源级 `effort_fallback` 必须真的走到 `resolve_thinking`(issue #20)。
+
+    只测配置值域与纯函数是不够的: 变异实测显示把 `fallback=source.effort_fallback`
+    换成硬编码 `"error"`,全套单测依然全绿——`nearest` 是人类明确要求实现的功能,
+    没有端到端用例它会在零告警下变成死代码(2026-09-05 独立验证查出)。
+
+    **该形态有两道门,必须各测各的**: transport 那道决定发出去的字节,`_guard_thinking`
+    那道决定装配能不能过。只钉住 transport,装配守卫退化成硬编码 `error` 时,配了
+    `nearest` 的源会在**运行期本来跑得起来**的情况下于装配期当场被判死,而这半边
+    第一轮修复时正是漏掉的那半边(M22)。
+    """
+
+    def _capturing_client(self, captured, **overrides):
+        def handler(request):
+            captured.append(json.loads(request.content))
+            return _sse()
+
+        return _client(handler=handler, **overrides)
+
+    async def test_nearest_sends_the_mapped_tier(self):
+        """glm-5.3 只有 low/high/max: 请求 `medium` 等距,按"取弱"落到 low。"""
+        captured = []
+        source = _source(provider="zhipu", model="glm-5.3", effort_fallback="nearest")
+        async with self._capturing_client(captured, sources=[source]) as client:
+            await client.chat([{"role": "user", "content": "hi"}], reasoning_effort=Effort.MEDIUM)
+        assert captured[0]["reasoning_effort"] == "low"
+
+    async def test_error_fallback_refuses_the_same_request(self):
+        """默认 `error` 必须报错而不是映射: 一次静默的换档就是一笔没打招呼的账单。"""
+        captured = []
+        source = _source(provider="zhipu", model="glm-5.3")
+        async with self._capturing_client(captured, sources=[source]) as client:
+            with pytest.raises(RequestRejectedError, match="medium"):
+                await client.chat(
+                    [{"role": "user", "content": "hi"}], reasoning_effort=Effort.MEDIUM
+                )
+        assert captured == []  # 请求根本没发出去
+
+    def test_nearest_survives_the_assembly_guard(self):
+        """装配守卫也必须用源级 `fallback`: 运行期能映射的源不该在装配期被判死。
+
+        源级 `medium` + glm-5.3(只有 low/high/max)是 `nearest` 唯一能被观测到的
+        装配期形态——守卫硬编码 `error` 时,这次 `from_env` 会抛
+        `ThinkingUnsupportedError` 而不是返回 client。
+        """
+        env = dict(_ENV)
+        for key in list(env):
+            if key.startswith("LLM__QWEN__"):
+                del env[key]
+        env.update(
+            {
+                "LLM__ZHIPU__1__BASE_URL": "https://gw.example/v1",
+                "LLM__ZHIPU__1__API_KEY": "sk-a",
+                "LLM__ZHIPU__1__MODEL": "glm-5.3",
+                "LLM__ZHIPU__1__TIMEOUT_S": "120",
+                "LLM__ZHIPU__1__REASONING_EFFORT": "medium",
+                "LLM__ZHIPU__1__EFFORT_FALLBACK": "nearest",
+            }
+        )
+        client = GatewayClient.from_env("LLM", env=env)
+        assert isinstance(client, GatewayClient)
+
+
+class TestAppliedTierReachesTheCaller:
+    """`LLMResponse.applied_effort` 报的是**真正发出去的**那一档(计划 T8-5)。
+
+    对下游是新能力(它终于能知道这次跑在哪档),对遥测是前置条件: 记请求档会让
+    按档分组的压测把整行挂在一个从未发出过的档下,而那种数据错得看不出来。
+    """
+
+    async def test_response_carries_the_mapped_tier(self):
+        """glm-5.3 无 `medium`: 开了 nearest 后实际跑的是 low,响应必须这么说。"""
+        source = _source(provider="zhipu", model="glm-5.3", effort_fallback="nearest")
+        async with _client(sources=[source]) as client:
+            resp = await client.chat(
+                [{"role": "user", "content": "hi"}], reasoning_effort=Effort.MEDIUM
+            )
+        assert resp.applied_effort is Effort.LOW
+
+    async def test_no_statement_leaves_the_field_none(self):
+        async with _client() as client:
+            resp = await client.chat([{"role": "user", "content": "hi"}])
+        assert resp.applied_effort is None
+
+
+class TestUnsupportedTierIsRefusedNotRetried:
+    """档位不可满足 = 请求本身的问题: 报 `RequestRejectedError`,不重试、不伤熔断。
+
+    重试与换源都不会让它变对(设计 §10),而把它计进熔断更糟——一次配置错误会
+    把一个健康的源关掉,拖垮与推理无关的所有调用。
+    """
+
+    async def test_tier_error_never_reaches_the_gateway_or_the_breaker(self):
+        sent = []
+
+        def handler(request):
+            sent.append(request)
+            return _sse()
+
+        # 阈值取 1: 只要这次失败被计进熔断,门当场开路,断言立刻可见
+        gate = InMemoryGate(config=BreakerConfig(1, 60.0, 120.0))
+        source = _source(name="zp", provider="zhipu", model="glm-5.3")
+        async with _client(sources=[source], handler=handler, breaker=gate) as client:
+            with pytest.raises(RequestRejectedError, match="无法关闭推理"):
+                await client.chat([{"role": "user", "content": "hi"}], reasoning_effort=Effort.NONE)
+        assert sent == [], "请求根本不该发出去: 档位不可满足在组装期就已判定"
+        assert (await gate.try_enter("zp", "w")).allowed, "配置错误不得计入熔断失败"
+
+
+class TestRequestTierNormalization:
+    """`chat(reasoning_effort=...)` 是公共入口,裸字符串必须在此归一(issue #20)。
+
+    两条装配路(工厂 / 构造函数全量注入,CLAUDE.md §4.5)与 `.env` 路的口径必须
+    一致——后者早已是"解析即归一"。不归一的后果不是"少个类型注解"那么轻: 档位
+    一路要被 `is Effort.NONE` 身份比较,裸字符串会在 transport 的错误路径上抛
+    `AttributeError`,而它不属错误四分类,会穿透 `except ThinkingUnsupportedError`
+    与 RetryMW 的分类捕获,以未分类异常冒出 `chat()`(2026-09-05 独立验证实测)。
+    """
+
+    def _capturing_client(self, captured, **overrides):
+        def handler(request):
+            captured.append(json.loads(request.content))
+            return _sse()
+
+        return _client(handler=handler, **overrides)
+
+    async def test_bare_string_tier_reaches_the_wire(self):
+        captured = []
+        source = _source(provider="zhipu", model="glm-5.3")
+        async with self._capturing_client(captured, sources=[source]) as client:
+            await client.chat([{"role": "user", "content": "hi"}], reasoning_effort="max")
+        assert captured[0]["reasoning_effort"] == "max"
+
+    async def test_illegal_tier_is_a_value_error_listing_the_vocabulary(self):
+        """非法档位是调用方编程错误: 当场 `ValueError`,不进洋葱、不成为未分类异常。"""
+        source = _source(provider="zhipu", model="glm-5.3")
+        async with _client(sources=[source]) as client:
+            with pytest.raises(ValueError) as exc:
+                await client.chat([{"role": "user", "content": "hi"}], reasoning_effort="lowest")
+        message = str(exc.value)
+        assert "chat(reasoning_effort=...)" in message
+        assert all(tier.value in message for tier in Effort)
+
+
 class _MemoryRecorder:
     """收下遥测行原样存起来;断言"哪些行被写了"必须能看到零行的情形。"""
 
@@ -324,6 +551,61 @@ class TestModelFingerprint:
         b = build_model_fingerprint([_source(extra_body={"temperature": 1})])
         assert a != b
 
+    def test_source_tier_enters_fingerprint(self):
+        """源级 `reasoning_effort` 改变请求体,就必须改变缓存身份(与 issue #5 同理)。
+
+        本用例同时守着一个易漏点: 只配 `REASONING_EFFORT`、既无 `extra_body` 也无
+        `ENABLE_THINKING` 的源,必须能进入指纹的 marks 集合——否则 `_fingerprint_mark`
+        改了也白改,四个指纹会全部相等。
+        """
+        from polygateway.client import build_model_fingerprint
+
+        plain = build_model_fingerprint([_source()])
+        low = build_model_fingerprint([_source(reasoning_effort=Effort.LOW)])
+        max_ = build_model_fingerprint([_source(reasoning_effort=Effort.MAX)])
+        off = build_model_fingerprint([_source(reasoning_effort=Effort.NONE)])
+        assert len({plain, low, max_, off}) == 4
+
+    def test_source_tier_is_distinguished_from_the_thinking_sugar(self):
+        """`reasoning_effort=NONE` 与 `enable_thinking=False` 不得摘要成同一个指纹。
+
+        两者语义等价但取值不同(`"none"` vs `false`),让它们撞车会把"两种写法"
+        变成"一种缓存身份",日后任一侧语义微调都会静默复用另一侧的响应。
+        """
+        from polygateway.client import build_model_fingerprint
+
+        by_tier = build_model_fingerprint([_source(reasoning_effort=Effort.NONE)])
+        by_sugar = build_model_fingerprint([_source(enable_thinking=False)])
+        assert by_tier != by_sugar
+
+    def test_absent_tier_fingerprint_is_byte_identical_to_before(self):
+        """不表态档位的存量源不得因本次升级平白冷启动: 字面量逐字相同。
+
+        两条: 纯净源仍是裸 model 合集;只配 extra_body 的源仍是升级前那个摘要。
+        """
+        import hashlib
+        import json
+
+        from polygateway.client import build_model_fingerprint
+
+        assert build_model_fingerprint([_source()]) == "qwen-max"
+        mark = json.dumps(["qwen-max", {"temperature": 0}], sort_keys=True, ensure_ascii=False)
+        expected = "qwen-max|" + hashlib.sha256(mark.encode("utf-8")).hexdigest()
+        assert build_model_fingerprint([_source(extra_body={"temperature": 0})]) == expected
+
+    def test_declared_tier_fingerprint_is_a_golden(self):
+        """配了档位那一侧的指纹字面量也要钉死: 它变了就是该源整段缓存冷启动。
+
+        存量(不表态)那侧由 `test_absent_tier_fingerprint_is_byte_identical_to_before`
+        守着;本条守的是"档位怎么摘要进 mark"。字面量硬编码,不在测试里重算——
+        重算等于把实现抄一遍,实现改了两边一起变,断言就白写了。
+        """
+        from polygateway.client import build_model_fingerprint
+
+        assert build_model_fingerprint([_source(reasoning_effort=Effort.LOW)]) == (
+            "qwen-max|76f2b3e419e1a727f7f31b6144da0b40d62a00ca93c91ce5901b4ebd48c0b8c0"
+        )
+
 
 class TestFactories:
     def test_from_env_assembles(self):
@@ -566,11 +848,19 @@ _CACHE_ENV = dict(
 
 
 class _Closable:
-    """记 close 次数的假组件;所有权纪律的唯一观测点。"""
+    """记 close 次数的假组件;所有权纪律的唯一观测点。
+
+    带 `record_llm_call(**fields)` 是因为它也被当作注入的 telemetry recorder 用:
+    1.3.5 的装配闸在构造期就会拒掉不满足 `TelemetryRecorder` 的对象
+    (否则下游升级后 100% 丢遥测而调用照常成功)。`**fields` 形态天然兼容。
+    """
 
     def __init__(self):
         self.closed = 0
 
+    async def record_llm_call(self, **fields):
+        pass
+
     async def aclose(self):
         self.closed += 1
 
@@ -581,6 +871,9 @@ class _SyncClosable:
     def __init__(self):
         self.closed = 0
 
+    async def record_llm_call(self, **fields):
+        pass
+
     def close(self):
         self.closed += 1
 
@@ -983,3 +1276,444 @@ class TestTelemetryStatusExposure:
         assert _ocr_client().telemetry_status is None
         assert _ocr_client(telemetry=_Closable()).telemetry_status is None
         self._assert_snapshot(_ocr_client(telemetry=self._recorder(tmp_path)).telemetry_status)
+
+
+class TestManagedReasoningAdmission:
+    """入口前置与实际准入边界保持明确。"""
+
+    @pytest.mark.parametrize("factory", ["env", "settings"])
+    def test_factory_rejects_conflict_before_building_backends(self, monkeypatch, factory):
+        env = {
+            **_ENV,
+            "LLM__QWEN__1__MODEL": "qwen3.7-plus",
+            "LLM__QWEN__1__ENABLE_THINKING": "true",
+            "LLM__QWEN__1__EXTRA_BODY": '{"enable_thinking":true}',
+        }
+        built = []
+
+        def forbidden(*args, **kwargs):
+            built.append(True)
+            raise AssertionError("后端不得构造")
+
+        monkeypatch.setattr("polygateway.client._build_limiter", forbidden)
+        with pytest.raises(ValueError, match="冲突"):
+            if factory == "env":
+                GatewayClient.from_env(env=env)
+            else:
+                GatewayClient.from_settings(GatewaySettings.from_env(env=env))
+        assert not built
+
+    async def test_request_conflict_does_not_enter_onion(self):
+        client = _client()
+
+        async def forbidden(request):
+            raise AssertionError("不得进入洋葱")
+
+        client._handler = forbidden
+        try:
+            with pytest.raises(ValueError, match="冲突"):
+                await client.chat([], reasoning_effort="high", overlay={"reasoning_effort": "high"})
+        finally:
+            await client._transport.aclose()
+
+    async def test_source_conflict_releases_admitted_permit(self):
+        source = _source(
+            reasoning_effort="high", provider="openai", extra_body={"reasoning_effort": "high"}
+        )
+        sent = []
+        client = _client(sources=[source], handler=lambda request: sent.append(request) or _sse())
+        try:
+            with pytest.raises(RequestRejectedError, match="冲突"):
+                await client.chat([])
+            assert sent == []
+            assert (await client._limiter_backend.source_stats(source.name)).inflight == 0
+        finally:
+            await client._transport.aclose()
+
+
+async def test_managed_conflict_returns_half_open_probe_and_permit():
+    """本地拒绝没有上游响应，不计故障且必须归还半开探针。"""
+    from tests.contracts.conftest import FakeClock
+
+    clock = FakeClock()
+    source = _source(
+        provider="openai", reasoning_effort="high", extra_body={"reasoning_effort": "high"}
+    )
+    gate = InMemoryGate(config=BreakerConfig(1, 1, 10), now=clock)
+    entry = await gate.try_enter(source.name, "setup")
+    await gate.record_failure(entry, "source_dead", True)
+    clock.advance(2)
+    client = _client(sources=[source], breaker=gate)
+    try:
+        with pytest.raises(RequestRejectedError, match="冲突"):
+            await client.chat([])
+        assert (await client._limiter_backend.source_stats(source.name)).inflight == 0
+        next_entry = await gate.try_enter(source.name, "next")
+        assert next_entry.allowed and next_entry.is_probe
+        await gate.release_probe(next_entry)
+    finally:
+        await client._transport.aclose()
+
+
+async def test_synthetic_runtime_protocol_and_legacy_call_signatures():
+    """合成 Protocol 仅证明本库兼容契约，不冒充缺失下游实际验收。"""
+    import inspect
+    from typing import Protocol, runtime_checkable
+
+    @runtime_checkable
+    class Caller(Protocol):
+        """旧调用点只依赖 chat 协议。"""
+
+        async def chat(self, messages, **kwargs): ...
+
+    client = GatewayClient.from_env("LLM", env=_ENV)
+    try:
+        assert isinstance(client, Caller)
+        signature = inspect.signature(client.chat)
+        signature.bind([], session_id="session", parent_call_id="step")
+        signature.bind([], session_id="session", cache_salt="epoch-1")
+        assert client._transport._clients == {}
+    finally:
+        await client.aclose()
+
+
+class _StatsClock:
+    """确定性单调钟;测试主动推进以断言"哪些区段计入了总耗时"。"""
+
+    def __init__(self, start=1000.0):
+        self.t = start
+
+    def __call__(self):
+        return self.t
+
+    def advance(self, seconds):
+        self.t += seconds
+
+
+class _TickingCache:
+    """假缓存后端: 每次 IO 推进注入钟。
+
+    不推进时钟的替身会让"缓存 IO 计入总耗时"的断言退化成恒等于 0 的空转绿
+    (计划 §T1 替身构造要求)。
+    """
+
+    def __init__(self, clock, tick=0.25):
+        self._clock = clock
+        self._tick = tick
+        self._data = {}
+
+    async def get(self, key):
+        self._clock.advance(self._tick)
+        return self._data.get(key)
+
+    async def set(self, key, value, ttl_s):
+        self._clock.advance(self._tick)
+        self._data[key] = value
+
+
+class _TickingRecorder:
+    """假 recorder: 写入时推进注入钟,用于断言内联遥测收尾计入总耗时。"""
+
+    def __init__(self, clock, tick=0.5):
+        self._clock = clock
+        self._tick = tick
+        self.rows = []
+
+    async def record_llm_call(self, **fields):
+        self._clock.advance(self._tick)
+        self.rows.append(fields)
+
+
+class TestLogicalCallStats:
+    """一次公开 chat 调用的统计(1.3.5 设计 §3)。"""
+
+    _MSG = [{"role": "user", "content": "hi"}]
+
+    async def test_success_reports_one_attempt(self):
+        async with _client() as client:
+            resp = await client.chat(self._MSG)
+        assert resp.call_stats is not None
+        assert resp.call_stats.attempts == 1
+        assert resp.call_stats.logical_call_id
+
+    async def test_concurrent_calls_do_not_share_counters_or_ids(self):
+        """同一 client 并发两路必须各自计数与各自 ID(库铁律「纯 asyncio 中立」)。
+
+        上下文若被提升成 client 实例属性,这条就会红——那正是 VT
+        `evolve_llm = llm` 教训的同一形态。
+        """
+        async with _client() as client:
+            a, b = await asyncio.gather(client.chat(self._MSG), client.chat(self._MSG))
+        assert a.call_stats.logical_call_id != b.call_stats.logical_call_id
+        assert a.call_stats.attempts == b.call_stats.attempts == 1
+
+    async def test_cache_hit_is_zero_attempts_with_a_fresh_logical_id(self):
+        """命中不产生网关调用 → 0 尝试;且是**新**逻辑调用,不回放历史统计。"""
+        clock = _StatsClock()
+        cache = _TickingCache(clock)
+        async with _client(
+            cache=cache, cache_namespace="proj", cache_ttl_s=600, now=clock
+        ) as client:
+            first = await client.chat(self._MSG)
+            second = await client.chat(self._MSG)
+        assert first.cache_hit is False and first.call_stats.attempts == 1
+        assert second.cache_hit is True
+        assert second.call_stats.attempts == 0
+        assert second.call_stats.logical_call_id != first.call_stats.logical_call_id
+
+    async def test_cache_io_counts_into_total_latency(self):
+        """缓存读写是本次调用真实花掉的时间,必须进总耗时(设计 §3)。"""
+        clock = _StatsClock()
+        cache = _TickingCache(clock, tick=0.25)
+        async with _client(
+            cache=cache, cache_namespace="proj", cache_ttl_s=600, now=clock
+        ) as client:
+            hit = (await client.chat(self._MSG), await client.chat(self._MSG))[1]
+        # 命中路径只有一次 get(0.25s),无网关调用
+        assert hit.call_stats.attempts == 0
+        assert hit.call_stats.total_latency_ms == 250
+
+    async def test_inline_telemetry_teardown_counts_into_total_latency(self):
+        """成功响应的快照含返回前已完成的内联遥测耗时(设计 §6)。"""
+        clock = _StatsClock()
+        recorder = _TickingRecorder(clock, tick=0.5)
+        async with _client(telemetry=recorder, now=clock) as client:
+            resp = await client.chat(self._MSG)
+        assert recorder.rows  # 确实写了行,否则本断言空转
+        assert resp.call_stats.total_latency_ms == 500
+
+    async def test_milliseconds_not_seconds(self):
+        """毫秒/秒不混用: 1.5s 必须是 1500 而不是 1 或 1.5。"""
+        clock = _StatsClock()
+        recorder = _TickingRecorder(clock, tick=1.5)
+        async with _client(telemetry=recorder, now=clock) as client:
+            resp = await client.chat(self._MSG)
+        assert resp.call_stats.total_latency_ms == 1500
+
+    async def test_stats_work_without_any_telemetry(self):
+        """统计生效与否**不由 telemetry 是否启用决定**(设计 §3.5)。"""
+        async with _client(telemetry=None) as client:
+            resp = await client.chat(self._MSG)
+        assert resp.call_stats is not None and resp.call_stats.attempts == 1
+
+    async def test_failure_exception_carries_no_stats_attribute(self):
+        """本版**不向异常对象附加统计**(设计 §3.1): 第三方可能复用同一异常实例。"""
+
+        def reject(request):
+            return httpx.Response(400, json={"error": {"message": "bad"}})
+
+        async with _client(handler=reject) as client:
+            with pytest.raises(RequestRejectedError) as exc:
+                await client.chat(self._MSG)
+        assert hasattr(exc.value, "call_stats") is False
+
+    async def test_input_validation_stays_outside_the_stats_boundary(self):
+        """校验异常保持原行为,发生在统计边界之外(设计 §3)。"""
+        async with _client() as client:
+            with pytest.raises(ValueError, match="meta"):
+                await client.chat(self._MSG, meta={"BAD-KEY": 1})
+
+
+class TestChatTerminalFailureRows:
+    """chat 链路的**真实**终态行(1.3.5 设计 §6;补漏而非改口径)。
+
+    这些路径改前一条失败行都没有(结构化耗尽)或只有尝试行,
+    "这次调用到底失败了几次"因此 SQL 答不出来。
+    """
+
+    _MSG = [{"role": "user", "content": "hi"}]
+
+    def _rows(self, recorder, kind):
+        return [r for r in recorder.rows if r["event_kind"] == kind]
+
+    async def test_structured_exhaustion_writes_the_only_failure_row(self):
+        """结构化耗尽发生在 transport 成功之后: attempt 行全是成功行,终态是唯一记录。"""
+        from pydantic import BaseModel
+
+        class Answer(BaseModel):
+            answer: int
+
+        recorder = _MemoryRecorder()
+        async with _client(
+            handler=lambda request: _sse("not json at all"),
+            telemetry=recorder,
+            structured_max_retries=1,
+        ) as client:
+            with pytest.raises(ResultInvalidError):
+                await client.chat(self._MSG, structured=Answer)
+        attempts = self._rows(recorder, "attempt")
+        terminals = self._rows(recorder, "terminal_failure")
+        assert [a["error"] for a in attempts] == [None, None]  # 两次尝试都成功
+        assert len(terminals) == 1
+        row = terminals[0]
+        assert row["error_type"] == "ResultInvalidError"
+        # C2: 有界结构化说明并入 error,且不含 raw_text(正文预算已由 attempt 行承担)
+        assert "validation=" in row["error"] or "repair=" in row["error"]
+        assert len(row["error"]) < 1200
+
+    async def test_retry_exhaustion_writes_exactly_one_terminal_row(self):
+        """重试耗尽: 逐次 attempt 行之外只能有**一条**终态行。
+
+        终态行的 `attempts` 是整次逻辑调用的真实尝试数——这正是改前 SQL
+        答不出的"这次调用到底重试了几次"。
+        """
+        recorder = _MemoryRecorder()
+        async with _client(
+            handler=lambda request: httpx.Response(503),
+            telemetry=recorder,
+            retry=RetryPolicy(3, 0.001, 0.01),
+        ) as client:
+            with pytest.raises(AllSourcesExhausted):
+                await client.chat(self._MSG)
+        attempts = self._rows(recorder, "attempt")
+        terminals = self._rows(recorder, "terminal_failure")
+        assert len(attempts) == 3
+        assert len(terminals) == 1
+        row = terminals[0]
+        assert row["error_type"] == "AllSourcesExhausted"
+        assert row["attempts"] == 3  # 整次逻辑调用的尝试数
+        assert row["scope"] == "llm" and row["operation"] == "chat"
+        # 终态行的 latency_ms 与 total_latency_ms 同取一份冻结快照
+        assert row["latency_ms"] == row["total_latency_ms"]
+
+    async def test_request_rejected_now_has_both_an_attempt_and_a_terminal_row(self):
+        """已批准的下游可见变化: 400 密集负载的错误行翻倍,失败计数只能取终态。"""
+        recorder = _MemoryRecorder()
+        async with _client(
+            handler=lambda request: httpx.Response(400, json={"error": {"message": "bad"}}),
+            telemetry=recorder,
+        ) as client:
+            with pytest.raises(RequestRejectedError):
+                await client.chat(self._MSG)
+        attempts = self._rows(recorder, "attempt")
+        terminals = self._rows(recorder, "terminal_failure")
+        assert len(attempts) == 1 and attempts[0]["http_status_code"] == 400
+        assert len(terminals) == 1
+        # C1: 终态不搬运最后一次 attempt 的状态码与正文
+        assert terminals[0]["http_status_code"] is None
+        assert terminals[0]["error_body"] is None
+        # 两类行共享同一 logical_call_id,归因查询才连得起来
+        assert attempts[0]["logical_call_id"] == terminals[0]["logical_call_id"]
+
+    async def test_non_domain_exception_writes_no_terminal_row(self):
+        """编程错原样传播,本版**不承诺**任何统计或终态行,也不偷偷改分类。"""
+        recorder = _MemoryRecorder()
+
+        async def boom(request):
+            raise KeyError("programming error")
+
+        async with _client(telemetry=recorder) as client:
+            client._handler = boom
+            with pytest.raises(KeyError):
+                await client.chat(self._MSG)
+        assert self._rows(recorder, "terminal_failure") == []
+
+    async def test_cancellation_writes_at_most_one_terminal_row(self):
+        """取消尽力写一条(允许 0),且 `CancelledError` 类型与语义不变。"""
+        recorder = _MemoryRecorder()
+
+        async def hang(request):
+            raise asyncio.CancelledError
+
+        async with _client(telemetry=recorder) as client:
+            client._handler = hang
+            with pytest.raises(asyncio.CancelledError):
+                await client.chat(self._MSG)
+        terminals = self._rows(recorder, "terminal_failure")
+        assert len(terminals) == 1
+        assert terminals[0]["error"] == "cancelled"
+        # 字符串不解析猜诊断
+        assert terminals[0]["error_type"] is None
+
+    async def test_terminal_row_is_written_once_per_logical_call(self):
+        """`claim_terminal` 去重: 同一次调用即便出口被多次触达也只有一条。"""
+        from polygateway.middleware.telemetry import emit_terminal_once
+        from polygateway.types import _CallContext
+
+        recorder = _MemoryRecorder()
+        async with _client(telemetry=recorder) as client:
+            context = _CallContext(now=client._now)
+            request = ChatRequest(messages=self._MSG, call_context=context)
+            for _ in range(3):
+                await emit_terminal_once(
+                    client._emitter,
+                    request=request,
+                    context=context,
+                    error=AllSourcesExhausted(
+                        scope="llm", reason="retry_exhausted", retry_after_s=1.0
+                    ),
+                    operation="chat",
+                )
+        assert len(self._rows(recorder, "terminal_failure")) == 1
+
+
+@pytest.fixture
+def captured_warnings():
+    """捕获库发出的 WARNING;loguru 不经标准 logging,pytest 的 caplog 抓不到。
+
+    名字避开裸 `warnings`: 那会遮蔽标准库模块名,本文件将来任何一次
+    `import warnings` 都会与它静默互相顶掉,而报错点离真因很远。
+    """
+    from loguru import logger
+
+    messages: list[str] = []
+    sink_id = logger.add(messages.append, level="WARNING")
+    yield messages
+    logger.remove(sink_id)
+
+
+class TestTerminalEmitDegradation:
+    """终态出口的降级方向: 诊断字段的**提取**同样在降级范围内(铁律"遥测写失败降级不冒泡")。
+
+    改前 `_record` 的 except 只包住写入本身,而错误诊断列在它之外求值——
+    经公共扩展点(自实现 `StructuredOutputStrategy`/transport)构造出的
+    `ResultInvalidError(validation_errors=(非 str,))` 会让提取期抛 `TypeError`
+    顶替调用方本该收到的领域异常,错误四分类当场被击穿。
+    """
+
+    _MSG = [{"role": "user", "content": "hi"}]
+
+    def _rows(self, recorder, kind):
+        return [r for r in recorder.rows if r["event_kind"] == kind]
+
+    async def test_broken_validation_errors_keep_the_domain_error(self, captured_warnings):
+        """自实现策略给出非 str 的 `validation_errors`: 领域异常必须原样上抛。"""
+
+        class _BadStrategy:
+            """公共端口 `StructuredOutputStrategy` 的下游实现(库外没有类型执法)。"""
+
+            def request_overlay(self, schema):
+                return {}
+
+            def parse(self, text):
+                raise ResultInvalidError("模型返回不可解析", validation_errors=(object(),))
+
+        recorder = _MemoryRecorder()
+        async with _client(telemetry=recorder, structured_strategy=_BadStrategy()) as client:
+            with pytest.raises(ResultInvalidError):  # 不是 TypeError
+                await client.chat(self._MSG, structured="json")
+        # 降级有声: 静默吞掉等于遥测缺口无人知道
+        assert [m for m in captured_warnings if "终态遥测记录失败" in m]
+        # 尝试行不受影响;终态行按 best effort 允许 0 条,但绝不能重复
+        assert len(self._rows(recorder, "attempt")) == 1
+        assert len(self._rows(recorder, "terminal_failure")) <= 1
+
+    async def test_cancellation_is_never_swallowed_by_the_degradation(self):
+        """降级不得吞取消: 写入那一次 await 上被取消,`CancelledError` 照常传播。"""
+        from polygateway.middleware.telemetry import emit_terminal_once
+        from polygateway.types import _CallContext
+
+        class _CancellingEmitter:
+            async def emit_terminal_failure(self, **kwargs):
+                raise asyncio.CancelledError
+
+        context = _CallContext(now=asyncio.get_running_loop().time)
+        request = ChatRequest(messages=self._MSG, call_context=context)
+        with pytest.raises(asyncio.CancelledError):
+            await emit_terminal_once(
+                _CancellingEmitter(),
+                request=request,
+                context=context,
+                error=AllSourcesExhausted(scope="llm", reason="retry_exhausted", retry_after_s=1.0),
+                operation="chat",
+            )

tests/unit/test_config.py

@@ -8,6 +8,8 @@ from loguru import logger
 
 from polygateway.client import GatewayClient
 from polygateway.config import EmbeddingSettings, GatewaySettings, OcrSettings
+from polygateway.providers import ProviderProfile, ThinkingWire, register_provider
+from polygateway.types import Effort, SourceConfig
 
 _BASE_ENV = {
     "LLM__QWEN__1__BASE_URL": "https://gw-a.example/v1",
@@ -132,6 +134,113 @@ class TestExtraBodyParsing:
             GatewaySettings.from_env("LLM", env=env)
 
 
+class TestReasoningEffortParsing:
+    """源级推理档位两个键的 env 解析(issue #20 Task 4)。"""
+
+    def test_effort_key_parsed(self):
+        env = _env(**{"LLM__QWEN__1__REASONING_EFFORT": "low"})
+        s = GatewaySettings.from_env("LLM", env=env)
+        assert s.sources[0].reasoning_effort is Effort.LOW
+
+    def test_absent_keys_keep_the_source_silent(self):
+        """未配置 = 不表态,与 `Effort.NONE`(要求不推理)是两回事;映射默认关闭。"""
+        src = GatewaySettings.from_env("LLM", env=_env()).sources[0]
+        assert src.reasoning_effort is None
+        assert src.effort_fallback == "error"
+
+    def test_invalid_effort_lists_vocabulary(self):
+        """写错档位的人要的是"那该填什么",故报错必须把八档全摆出来。"""
+        env = _env(**{"LLM__QWEN__1__REASONING_EFFORT": "lowest"})
+        with pytest.raises(ValueError) as exc:
+            GatewaySettings.from_env("LLM", env=env)
+        message = str(exc.value)
+        assert "REASONING_EFFORT" in message
+        assert all(tier.value in message for tier in Effort)
+
+    def test_effort_fallback_parsed(self):
+        env = _env(**{"LLM__QWEN__1__EFFORT_FALLBACK": "nearest"})
+        s = GatewaySettings.from_env("LLM", env=env)
+        assert s.sources[0].effort_fallback == "nearest"
+
+    def test_effort_key_tolerates_case_and_whitespace(self):
+        """`.env` 里的行尾空格与大写写法是常态,档位取值本身没有大小写语义。"""
+        env = _env(**{"LLM__QWEN__1__REASONING_EFFORT": " LOW "})
+        assert GatewaySettings.from_env("LLM", env=env).sources[0].reasoning_effort is Effort.LOW
+
+    def test_effort_fallback_tolerates_case_and_whitespace(self):
+        """与相邻的 REASONING_EFFORT 同口径: 同一份 .env 里两个键脾气不同即是坑。
+
+        `EFFORT_FALLBACK=Nearest` 此前会原样落到 `SourceConfig`,被值域校验拒掉
+        ——而人看着 .env 里明明写了 nearest(2026-09-05 独立验证查出)。
+        """
+        env = _env(**{"LLM__QWEN__1__EFFORT_FALLBACK": " Nearest "})
+        assert GatewaySettings.from_env("LLM", env=env).sources[0].effort_fallback == "nearest"
+
+    def test_invalid_effort_fallback_rejected(self):
+        """`resolve_thinking` 对未知 fallback 值是 fail-closed,不会替配置兜错。"""
+        env = _env(**{"LLM__QWEN__1__EFFORT_FALLBACK": "closest"})
+        with pytest.raises(ValueError) as exc:
+            GatewaySettings.from_env("LLM", env=env)
+        message = str(exc.value)
+        assert "effort_fallback" in message
+        assert "nearest" in message and "error" in message
+
+
+class TestThinkingFlagContradiction:
+    """`enable_thinking` 与 `reasoning_effort` 说的是同一件事(设计 §4.2 语法糖)。
+
+    矛盾时报错而非「后者赢」: 两个字段表达同一件事时,矛盾是配置错误,
+    静默取其一等于替下游猜它想要哪个。
+    """
+
+    def _source(self, enable_thinking, effort):
+        env = _env(
+            **{
+                "LLM__QWEN__1__ENABLE_THINKING": enable_thinking,
+                "LLM__QWEN__1__REASONING_EFFORT": effort,
+            }
+        )
+        return GatewaySettings.from_env("LLM", env=env).sources[0]
+
+    @pytest.mark.parametrize(
+        ("enable_thinking", "effort"),
+        [("true", "none"), ("false", "low"), ("false", "auto"), ("false", "max")],
+    )
+    def test_contradictory_thinking_flags_rejected(self, enable_thinking, effort):
+        with pytest.raises(ValueError) as exc:
+            self._source(enable_thinking, effort)
+        message = str(exc.value)
+        assert "enable_thinking" in message and "reasoning_effort" in message
+
+    @pytest.mark.parametrize(
+        ("enable_thinking", "effort"),
+        [("false", "none"), ("true", "auto"), ("true", "low")],
+    )
+    def test_consistent_flags_allowed(self, enable_thinking, effort):
+        """语义一致就放行: `False`+`none` 与 `True`+某个开启档都只是说了两遍。"""
+        src = self._source(enable_thinking, effort)
+        assert src.enable_thinking is (enable_thinking == "true")
+        assert src.reasoning_effort is Effort(effort)
+
+    def test_one_sided_declaration_never_trips_the_guard(self):
+        """只配一个键是常态(存量源全是这样),不得被矛盾守卫误伤。"""
+        assert self._source("true", None).reasoning_effort is None
+        assert self._source(None, "high").enable_thinking is None
+
+    def test_contradiction_guarded_on_direct_construction(self):
+        """守卫挂在构造期而非 env 解析处: 构造函数全量注入那条装配路同样过闸。"""
+        base = SourceConfig(
+            name="s1",
+            provider="qwen",
+            base_url="https://gw.example/v1",
+            api_key="sk-x",
+            model="qwen-max",
+            timeout_s=60.0,
+        )
+        with pytest.raises(ValueError, match="reasoning_effort"):
+            dataclasses.replace(base, enable_thinking=True, reasoning_effort=Effort.NONE)
+
+
 class TestResilienceKeys:
     def test_flat_legacy_keys(self):
         s = GatewaySettings.from_env("LLM", env=_env())
@@ -637,10 +746,41 @@ class TestCrossFieldInvariants:
             GatewayClient.from_settings(settings)
 
     def test_unknown_thinking_shape_fails_at_assembly(self):
-        """provider=openai 是任意兼容厂商的兜底段名,形态未知即报错并指路。"""
+        # 形态未知即报错并指路。2026-09-04 起默认表 8 段全部有形态(openai 段改发
-        settings = self._thinking_sources("openai", "kimi-k3", False)
+        # OpenAI 标准的 reasoning_effort),故样本改为显式注册一个未知段——守卫测的
+        # 是机制,不是某个段当时的配置
+        mystery = ProviderProfile(
+            name="mystery",
+            thinking=ThinkingWire(off=None, on_base=None, effort_key=None),
+            strip_think_tags=False,
+        )
+        settings = self._thinking_sources("mystery", "kimi-k3", False)
         with pytest.raises(ValueError, match="register_provider"):
-            GatewayClient.from_settings(settings)
+            GatewayClient.from_settings(settings, registry=register_provider(mystery))
+
+    def test_source_tier_the_model_cannot_satisfy_fails_at_assembly(self):
+        """守卫必须读**源级档位**,而不只是 `enable_thinking`(设计 §4.2 三层优先级)。
+
+        变异实测: 把 `_guard_thinking` 的 `source_effort=source.reasoning_effort`
+        改成 `None`,全套单测依然全绿(2026-09-05 独立验证查出)。文案里必须出现
+        可执行替代 `low`——glm-5.3 官方关不掉推理,只报"不行"会把人推回
+        `extra_body` 那条绕过治理的老路(issue #20 的成因)。
+        """
+        base = self._base()
+        src = dataclasses.replace(
+            base.sources[0], provider="zhipu", model="glm-5.3", reasoning_effort=Effort.NONE
+        )
+        with pytest.raises(ValueError) as exc:
+            GatewayClient.from_settings(dataclasses.replace(base, sources=(src,)))
+        message = str(exc.value)
+        assert "glm-5.3" in message
+        assert "low" in message
+
+    def test_openai_segment_now_assembles_with_the_standard_field(self):
+        # 行为变更(2026-09-04): reasoning_effort 是 OpenAI 官方字段而非厂商方言,
+        # 经网关的兼容端点收得下,故兜底段不再把"关闭"判为形态未知
+        settings = self._thinking_sources("openai", "gpt-5.5", False)
+        assert GatewayClient.from_settings(settings) is not None
 
     def test_supported_combination_assembles(self):
         settings = self._thinking_sources("minimax", "MiniMax-M3", False)
@@ -857,3 +997,47 @@ class TestCrossFieldInvariants:
         )
         client = GatewayClient.from_settings(settings)
         assert client is not None
+
+
+async def test_flat_legacy_keys_assemble_without_source_timeout_or_network():
+    """完整合成 env 验证平铺回落，不借真实配置或 Redis/PG。"""
+    env = dict(_BASE_ENV)
+    del env["LLM__QWEN__1__TIMEOUT_S"]
+    env.update({"LLM_TIMEOUT": "317", "LLM_TTFT_TIMEOUT": "41", "LLM_INTER_TOKEN_TIMEOUT": "19"})
+    settings = GatewaySettings.from_env("LLM", env=env)
+    assert settings.sources[0].timeout_s == 317
+    assert settings.sources[0].ttft_timeout_s == 41
+    assert settings.sources[0].inter_token_timeout_s == 19
+    assert settings.retry.max_attempts == 3
+    client = GatewayClient.from_settings(settings)
+    try:
+        assert client._transport._clients == {}
+    finally:
+        await client.aclose()
+
+
+@pytest.mark.parametrize("model", ["MiniMax-M2.7", "MiniMax-M3"])
+def test_live_assembly_rejection_is_local_only(model):
+    """M2.7 NONE 与 M3 AUTO 的旧 live 装配断言离线执行。"""
+    env = _env(**{"LLM__QWEN__1__MODEL": model})
+    settings = GatewaySettings.from_env("LLM", env=env)
+    source = dataclasses.replace(
+        settings.sources[0], provider="minimax", enable_thinking=model == "MiniMax-M3"
+    )
+    with pytest.raises(ValueError, match=model):
+        GatewayClient.from_settings(dataclasses.replace(settings, sources=(source,)))
+
+
+def test_live_unknown_wire_assembly_is_local_only():
+    """L9 明确全 None profile，不从当前默认注册表猜未知形态。"""
+    mystery = ProviderProfile(
+        name="mystery",
+        thinking=ThinkingWire(off=None, on_base=None, effort_key=None),
+        strip_think_tags=False,
+    )
+    settings = GatewaySettings.from_env("LLM", env=_BASE_ENV)
+    source = dataclasses.replace(settings.sources[0], provider="mystery", enable_thinking=False)
+    with pytest.raises(ValueError, match="register_provider"):
+        GatewayClient.from_settings(
+            dataclasses.replace(settings, sources=(source,)), registry=register_provider(mystery)
+        )

tests/unit/test_embedding.py

@@ -533,3 +533,115 @@ class TestEmbeddingSettings:
         s = EmbeddingSettings.from_env("EMBED", env=self._ENV)
         client = EmbeddingClient.from_settings(s)
         assert isinstance(client, EmbeddingClient)
+
+
+class TestReasonlessTelemetryContract:
+    """从真实客户端到落库，误配推理配置也不能产生推理档。"""
+
+    @pytest.mark.parametrize("config", [{"enable_thinking": True}, {"reasoning_effort": "high"}])
+    @pytest.mark.parametrize("backend", ["memory", "sqlite"])
+    async def test_failed_then_successful_attempts_have_null_effort(
+        self, config, backend, tmp_path
+    ):
+        import sqlite3
+
+        from polygateway.telemetry.sqlite import SQLiteRecorder
+
+        path = tmp_path / "embed.sqlite"
+        recorder = (
+            _MemoryRecorder() if backend == "memory" else SQLiteRecorder(path, auto_migrate=True)
+        )
+        client, _ = _embed_client(
+            [_src(**config)], [TransientError("retry"), "ok"], telemetry=recorder
+        )
+        try:
+            await client.embed(["text"], session_id="run", parent_call_id="embed")
+            if backend == "memory":
+                rows = [(r["error"], r["reasoning_effort"]) for r in recorder.rows]
+            else:
+                with sqlite3.connect(path) as db:
+                    rows = db.execute("SELECT error, reasoning_effort FROM llm_calls").fetchall()
+            assert len(rows) == 2
+            assert sum(bool(error) for error, _ in rows) == 1
+            assert [tier for _, tier in rows] == [None, None]
+        finally:
+            await client.aclose()
+            if backend == "sqlite":
+                recorder.close()
+
+    @pytest.mark.parametrize("exhausted", [False, True])
+    async def test_failed_attempts_still_have_null_effort(self, exhausted):
+        from polygateway.errors import AllSourcesExhausted
+
+        script = (
+            [TransientError("retry")] * 3 if exhausted else [RequestRejectedError("bad request")]
+        )
+        recorder = _MemoryRecorder()
+        client, _ = _embed_client([_src(enable_thinking=True)], script, telemetry=recorder)
+        with pytest.raises(AllSourcesExhausted if exhausted else RequestRejectedError):
+            await client.embed(["text"])
+        # 1.3.5: 逐次 attempt 行之外,本次逻辑调用另有**一条**终态行
+        attempts = [r for r in recorder.rows if r["event_kind"] == "attempt"]
+        terminals = [r for r in recorder.rows if r["event_kind"] == "terminal_failure"]
+        assert len(attempts) == len(script)
+        assert len(terminals) == 1
+        # 推理档在三类行上都必须是 NULL: embed payload 从不带推理参数
+        assert all(r["error"] and r["reasoning_effort"] is None for r in recorder.rows)
+
+    async def test_embedding_wire_ignores_reasoning_configuration(self):
+        seen = []
+
+        def handler(request):
+            seen.append(json.loads(request.content))
+            return httpx.Response(200, json=_ok_body([[1.0]], usage={"prompt_tokens": 1}))
+
+        transport = _transport_with(handler)
+        try:
+            await transport.embed(
+                texts=["text"],
+                source=_src(enable_thinking=True, reasoning_effort="high"),
+                call_id="wire",
+            )
+            assert seen == [{"model": "embed-1", "input": ["text"]}]
+        finally:
+            await transport.aclose()
+
+
+class TestEmbedLogicalCallStats:
+    """分批共享同一逻辑调用(1.3.5 设计 §3/§3.5)。"""
+
+    async def test_three_batches_count_three_attempts(self):
+        """分批是库的实现细节,但每批都真打了一次网关,故计 3 次尝试。"""
+        client, _ = _embed_client([_src()], ["ok", "ok", "ok"], batch_size=2)
+        resp = await client.embed(["a", "bb", "ccc", "dddd", "eeeee"])
+        assert resp.call_stats is not None
+        assert resp.call_stats.attempts == 3
+
+    async def test_separate_calls_get_distinct_logical_ids(self):
+        """一次公开调用一个 ID: 两次 `embed` 不得共用同一个。
+
+        共用就意味着上下文被提升成了 client 实例属性(库铁律禁止的形态)。
+        """
+        client, _ = _embed_client([_src()], ["ok"] * 5, batch_size=2)
+        first = await client.embed(["a", "bb", "ccc", "dddd", "eeeee"])  # 3 批
+        second = await client.embed(["x", "y"])  # 1 批
+        assert first.call_stats.attempts == 3 and second.call_stats.attempts == 1
+        assert first.call_stats.logical_call_id != second.call_stats.logical_call_id
+
+    async def test_retry_within_a_batch_is_counted(self):
+        client, _ = _embed_client([_src(), _src(name="e2")], [TransientError("t1"), "ok"])
+        resp = await client.embed(["a"])
+        assert resp.call_stats.attempts == 2
+
+    async def test_empty_input_is_zero_attempts_and_writes_no_telemetry_row(self):
+        """合法零尝试: 返回真实统计,且**不写任何遥测行**(设计 §3 M2)。
+
+        与 cache_hit 不同——不要按"遥测必录"推断空输入也有台账行。
+        """
+        rec = _MemoryRecorder()
+        client, _ = _embed_client([_src()], [], telemetry=rec)
+        resp = await client.embed([])
+        assert resp.call_stats is not None
+        assert resp.call_stats.attempts == 0
+        assert resp.call_stats.logical_call_id  # 真实 ID,不是空串
+        assert rec.rows == []  # 零遥测行

tests/unit/test_monkey_ocr.py

@@ -405,3 +405,31 @@ class TestLifecycle:
         await t.check_health(source=_source())
         await t.aclose()
         await t.aclose()
+
+
+@pytest.mark.parametrize("method", ["recognize_text", "parse_layout"])
+async def test_ocr_wire_does_not_send_reasoning_configuration(method):
+    """真实 multipart 与 ZIP 下载两段均不发送源级推理配置。"""
+    sent = []
+
+    def handler(request):
+        sent.append(request)
+        if request.method == "GET":
+            return httpx.Response(200, content=_zip_bytes())
+        return httpx.Response(
+            200, json=_text_body() if method == "recognize_text" else _parse_body()
+        )
+
+    transport = _transport_for(handler)
+    try:
+        await getattr(transport, method)(
+            image=b"image",
+            source=_source(enable_thinking=True, reasoning_effort="high"),
+            call_id="wire",
+        )
+        assert len(sent) == (1 if method == "recognize_text" else 2)
+        for request in sent:
+            for key in (b"reasoning_effort", b"enable_thinking", b"thinking_budget"):
+                assert key not in request.content
+    finally:
+        await transport.aclose()

tests/unit/test_ocr_client.py

@@ -564,3 +564,91 @@ class TestAssembly:
         client = OcrClient.from_env("OCR", env=dict(self._ENV))
         await client.aclose()
         await client.aclose()
+
+
+class TestReasonlessTelemetryContract:
+    """text/layout 两个入口分别验证错误行不受源级推理配置污染。"""
+
+    @pytest.mark.parametrize(
+        "method,action", [("recognize_text", "text"), ("parse_layout", "layout")]
+    )
+    @pytest.mark.parametrize("config", [{"enable_thinking": True}, {"reasoning_effort": "high"}])
+    @pytest.mark.parametrize("backend", ["memory", "sqlite"])
+    async def test_failed_then_successful_attempts_have_null_effort(
+        self, method, action, config, backend, tmp_path
+    ):
+        import sqlite3
+
+        from polygateway.telemetry.sqlite import SQLiteRecorder
+
+        path = tmp_path / "ocr.sqlite"
+        recorder = (
+            _MemoryRecorder() if backend == "memory" else SQLiteRecorder(path, auto_migrate=True)
+        )
+        client, _, _ = _client(
+            [_src(**config)], [TransientError("retry"), action], telemetry=recorder
+        )
+        try:
+            await getattr(client, method)(b"image", session_id="run", parent_call_id=method)
+            if backend == "memory":
+                rows = [(r["error"], r["reasoning_effort"]) for r in recorder.rows]
+            else:
+                with sqlite3.connect(path) as db:
+                    rows = db.execute("SELECT error, reasoning_effort FROM llm_calls").fetchall()
+            assert len(rows) == 2
+            assert sum(bool(error) for error, _ in rows) == 1
+            assert [tier for _, tier in rows] == [None, None]
+        finally:
+            await client.aclose()
+            if backend == "sqlite":
+                recorder.close()
+
+    @pytest.mark.parametrize("method", ["recognize_text", "parse_layout"])
+    @pytest.mark.parametrize("exhausted", [False, True])
+    async def test_failed_attempts_still_have_null_effort(self, method, exhausted):
+        script = (
+            [TransientError("retry")] * 3 if exhausted else [RequestRejectedError("bad request")]
+        )
+        recorder = _MemoryRecorder()
+        client, _, _ = _client([_src(enable_thinking=True)], script, telemetry=recorder)
+        with pytest.raises(AllSourcesExhausted if exhausted else RequestRejectedError):
+            await getattr(client, method)(b"image")
+        # 1.3.5: 逐次 attempt 行之外,本次逻辑调用另有**一条**终态行
+        attempts = [r for r in recorder.rows if r["event_kind"] == "attempt"]
+        terminals = [r for r in recorder.rows if r["event_kind"] == "terminal_failure"]
+        assert len(attempts) == len(script)
+        assert len(terminals) == 1
+        # 终态行的 operation 是**公开方法**名,与尝试行一致
+        assert terminals[0]["operation"] == method
+        assert all(r["error"] and r["reasoning_effort"] is None for r in recorder.rows)
+
+
+class TestOcrLogicalCallStats:
+    """OCR 两个公开方法各自拥有一次逻辑调用(1.3.5 设计 §3/§3.5)。"""
+
+    async def test_text_success_counts_one_attempt(self):
+        client, _, _ = _client([_src()], ["text"])
+        r = await client.recognize_text(b"jpg")
+        assert r.call_stats is not None and r.call_stats.attempts == 1
+
+    async def test_layout_two_http_calls_count_as_one_attempt(self):
+        """POST + ZIP GET 在同一次 transport 调用内,计 **1** 次尝试而非 2。
+
+        `attempts` 的语义是"调用 transport 端口的次数",不是 HTTP 请求条数。
+        """
+        client, _, _ = _client([_src()], ["layout"])
+        r = await client.parse_layout(b"jpg")
+        assert r.call_stats is not None and r.call_stats.attempts == 1
+
+    async def test_retry_counts_every_attempt(self):
+        client, _, _ = _client([_src(), _src(name="m2")], [TransientError("t1"), "text"])
+        r = await client.recognize_text(b"jpg")
+        assert r.call_stats.attempts == 2
+
+    async def test_input_validation_stays_outside_the_stats_boundary(self):
+        """`image` 类型/空校验先于上下文创建(M1 例外),保持原异常行为。"""
+        client, _, _ = _client([_src()], [])
+        with pytest.raises(TypeError):
+            await client.recognize_text("not-bytes")
+        with pytest.raises(ValueError):
+            await client.recognize_text(b"")

tests/unit/test_openai_compat.py

@@ -16,13 +16,14 @@ from polygateway.errors import (
 )
 from polygateway.middleware.telemetry import TelemetryEmitter
 from polygateway.pricing import ModelPrice, PricingTable
+from polygateway.providers import ProviderProfile, ThinkingWire, register_provider
 from polygateway.transports._http_errors import summarize_body
 from polygateway.transports.openai_compat import (
     OpenAICompatTransport,
     _iter_sse_deltas,
     _sse_data_payload,
 )
-from polygateway.types import ChatRequest, LLMResponse, SourceConfig, ThinkingObservation
+from polygateway.types import ChatRequest, Effort, LLMResponse, SourceConfig, ThinkingObservation
 
 
 def _source(**overrides):
@@ -60,20 +61,22 @@ def _sse_stream(*frames, done=True):
     return httpx.Response(200, content=text.encode(), headers={"content-type": "text/event-stream"})
 
 
-def _transport_for(handler):
+def _transport_for(handler, *, registry=None):
     mock = httpx.MockTransport(handler)
     return OpenAICompatTransport(
-        client_factory=lambda src: httpx.AsyncClient(base_url=src.base_url, transport=mock)
+        client_factory=lambda src: httpx.AsyncClient(base_url=src.base_url, transport=mock),
+        registry=registry,
     )
 
 
-async def _complete(transport, source, *, stream=True, overlay=None):
+async def _complete(transport, source, *, stream=True, overlay=None, reasoning_effort=None):
     return await transport.complete(
         messages=[{"role": "user", "content": "hi"}],
         source=source,
         stream=stream,
         overlay=overlay or {},
         call_id="cid-1",
+        reasoning_effort=reasoning_effort,
     )
 
 
@@ -113,13 +116,15 @@ async def _recorded_cost(result, source):
         source_name=source.name,
         usage_source=result.usage_source,
     )
-    await TelemetryEmitter(recorder, pricing=_PRICING, text_cap=None).emit_attempt(
+    await TelemetryEmitter(recorder, pricing=_PRICING, text_cap=None, scope="LLM").emit_attempt(
         request=ChatRequest(messages=[{"role": "user", "content": "hi"}]),
         source=source,
         call_id="cid-1",
         latency_ms=1,
         response=response,
         error=None,
+        reasoning_applies=True,
+        operation="chat",
     )
     return recorder.rows[0]["cost"]
 
@@ -619,13 +624,67 @@ class TestThinkingReconciliation:
         try:
             await _complete(transport, self._minimax(False))
             await _complete(transport, self._minimax(False))
-            await _complete(transport, self._minimax(True))
+            await _complete(transport, self._minimax(True), reasoning_effort=Effort.MEDIUM)
-            await _complete(transport, self._minimax(True))
+            await _complete(transport, self._minimax(True), reasoning_effort=Effort.MEDIUM)
         finally:
             logger.remove(sink_id)
         hits = [m for m in messages if "MiniMax-M3" in m]
         assert len(hits) == 2, f"两个方向各应告警一次,实得 {len(hits)} 次"
 
+    async def test_each_tier_of_one_model_earns_its_own_warning(self):
+        """同一源同一模型的两个强度档是**两个独立的矛盾**,不得共用一个节流键。
+
+        节流键沿用旧的 `enable_thinking` 三态时,两次请求的键逐字相同(都是
+        `None`——档位根本不经过那个字段),于是 `max` 档的矛盾被 `low` 档那次
+        永久静音。档位化后 low 与 max 各喊一次,重复的 low 仍只喊一次。
+        """
+        transport = _transport_for(self._zero_signal)
+        source = _source(name="zp", provider="zhipu", model="glm-5.3")
+        messages: list[str] = []
+        sink_id = logger.add(messages.append, level="WARNING")
+        try:
+            await _complete(transport, source, reasoning_effort=Effort.LOW)
+            await _complete(transport, source, reasoning_effort=Effort.LOW)
+            await _complete(transport, source, reasoning_effort=Effort.MAX)
+        finally:
+            logger.remove(sink_id)
+        hits = [m for m in messages if "glm-5.3" in m]
+        assert len(hits) == 2, f"low 与 max 应各告警一次,实得 {len(hits)} 次"
+
+    def _zero_signal(self, request):
+        """零推理信号的成功响应 → UNKNOWN,与"要求开启"矛盾(M3 实测形态)。"""
+        return _sse_stream(_chunk(content="ok"), _chunk(usage=_USAGE))
+
+
+class TestAppliedTierLeavesTheTransport:
+    """本次**实际**发出去的档必须随 TransportResult 上浮(设计 §4.1 / 计划 T8-5)。
+
+    不上浮就只能由遥测自己再算一遍请求档,而 `nearest` 映射后两者不同——压测
+    要按档分组的那一列会挂在一个从未真正发出过的档下,且错得看不出来。
+    """
+
+    def _ok(self, request):
+        return _sse_stream(_chunk(content="ok"), _chunk(usage=_USAGE))
+
+    async def test_result_carries_the_mapped_tier_not_the_requested_one(self):
+        """glm-5.3 只有 low/high/max: 请求 `medium`,实际发出的是 `low`。"""
+        transport = _transport_for(self._ok)
+        source = _source(provider="zhipu", model="glm-5.3", effort_fallback="nearest")
+        result = await _complete(transport, source, reasoning_effort=Effort.MEDIUM)
+        assert result.applied_effort is Effort.LOW
+
+    async def test_result_carries_the_tier_that_was_asked_for_when_supported(self):
+        transport = _transport_for(self._ok)
+        source = _source(provider="zhipu", model="glm-5.3")
+        result = await _complete(transport, source, reasoning_effort=Effort.MAX)
+        assert result.applied_effort is Effort.MAX
+
+    async def test_no_statement_stays_none(self):
+        """不表态时库既不注入也不推定模型默认档——"没看见"不许说成"发生了"。"""
+        transport = _transport_for(self._ok)
+        result = await _complete(transport, _source())
+        assert result.applied_effort is None
+
 
 class TestNonStreamFastPath:
     async def test_non_stream_parses_message(self):
@@ -647,59 +706,44 @@ class TestNonStreamFastPath:
 
 
 class TestRequestShaping:
-    @pytest.mark.parametrize(
+    @pytest.mark.parametrize("tier", [Effort.MEDIUM, Effort.NONE])
-        ("enable_thinking", "expected"),
+    async def test_minimax_explicit_tier_is_sent(self, tier):
-        [(True, {"enable_thinking": True}), (False, {"enable_thinking": False}), (None, {})],
-    )
-    async def test_thinking_tri_state_injection(self, enable_thinking, expected):
         seen = {}
 
         def handler(request):
             seen.update(json.loads(request.content))
             return _sse_stream(_chunk(content="x"), _chunk(usage=_USAGE))
 
-        await _complete(_transport_for(handler), _source(enable_thinking=enable_thinking))
+        transport = _transport_for(handler)
-        assert {k: seen[k] for k in expected} == expected
+        try:
-        if enable_thinking is None:
+            result = await _complete(
+                transport, _source(provider="minimax", model="MiniMax-M3"), reasoning_effort=tier
+            )
+            assert seen["reasoning_effort"] == tier.value
+            assert result.applied_effort is tier
             assert "enable_thinking" not in seen
-        assert seen["stream_options"] == {"include_usage": True}
+        finally:
+            await transport.aclose()
 
-    @pytest.mark.parametrize(
+    async def test_raw_only_keeps_source_then_request_priority(self):
-        ("enable_thinking", "expected"),
-        [(True, "medium"), (False, "none")],
-    )
-    async def test_minimax_injects_reasoning_effort(self, enable_thinking, expected):
-        """issue #5: MiniMax 认的是 reasoning_effort,不是 enable_thinking。"""
         seen = {}
 
         def handler(request):
             seen.update(json.loads(request.content))
             return _sse_stream(_chunk(content="x"), _chunk(usage=_USAGE))
 
-        source = _source(
+        transport = _transport_for(handler)
-            name="mm", provider="minimax", model="MiniMax-M3", enable_thinking=enable_thinking
+        try:
+            result = await _complete(
+                transport,
+                _source(extra_body={"reasoning_effort": "low", "temperature": 0}),
+                overlay={"reasoning_effort": "high", "temperature": 1},
             )
-        await _complete(_transport_for(handler), source)
-        assert seen["reasoning_effort"] == expected
-        assert "enable_thinking" not in seen  # 旧形态实测被静默丢弃,不再下发
-
-    async def test_extra_body_overrides_the_profile_slot(self):
-        """注入顺序即优先级: profile → extra_body → overlay,两行不可调换。"""
-        seen = {}
-
-        def handler(request):
-            seen.update(json.loads(request.content))
-            return _sse_stream(_chunk(content="x"), _chunk(usage=_USAGE))
-
-        source = _source(
-            name="mm",
-            provider="minimax",
-            model="MiniMax-M3",
-            enable_thinking=True,
-            extra_body={"reasoning_effort": "high"},
-        )
-        await _complete(_transport_for(handler), source)
             assert seen["reasoning_effort"] == "high"
+            assert seen["temperature"] == 1
+            assert result.applied_effort is None
+        finally:
+            await transport.aclose()
 
     async def test_model_that_cannot_disable_is_rejected_not_silently_ignored(self):
         """M2.x 关不掉推理: 必须是四分类之一的 RequestRejected,不是裸 ValueError。
@@ -758,9 +802,15 @@ class TestRequestShaping:
         def handler(request):  # pragma: no cover - 不该走到发请求
             raise AssertionError("请求不该发出")
 
-        source = _source(name="k3", provider="openai", model="kimi-k3", enable_thinking=False)
+        # 2026-09-04 起默认表 8 段全部有形态,守卫样本改为显式注册的未知段
+        mystery = ProviderProfile(
+            name="mystery",
+            thinking=ThinkingWire(off=None, on_base=None, effort_key=None),
+            strip_think_tags=False,
+        )
+        source = _source(name="k3", provider="mystery", model="kimi-k3", enable_thinking=False)
         with pytest.raises(RequestRejectedError, match="register_provider"):
-            await _complete(_transport_for(handler), source)
+            await _complete(_transport_for(handler, registry=register_provider(mystery)), source)
 
     async def test_overlay_merged_into_payload(self):
         seen = {}
@@ -976,3 +1026,121 @@ class TestLifecycle:
         await _complete(transport, _source())
         await transport.aclose()
         await transport.aclose()
+
+
+class TestManagedReasoningOwnership:
+    """通过真实 transport 验证拒绝发生在 HTTP 之前。"""
+
+    @pytest.mark.parametrize(
+        "raw",
+        [
+            {"reasoning_effort": "high"},
+            {"enable_thinking": True},
+            {"thinking": {}},
+            {"thinking_budget": 100},
+            {"reasoning": {}},
+            {"thinkingConfig": {}},
+            {"output_config": {"effort": "low"}},
+        ],
+    )
+    @pytest.mark.parametrize("layer", ["source", "request", "shadowed"])
+    async def test_raw_control_is_rejected_before_http(self, raw, layer):
+        sent = []
+
+        def handler(request):
+            sent.append(request)
+            return _sse_stream(_chunk(content="ok"), _chunk(usage=_USAGE))
+
+        source = _source(
+            provider="openai",
+            reasoning_effort=Effort.HIGH,
+            extra_body=raw if layer != "request" else {},
+        )
+        overlay = raw if layer != "source" else {}
+        transport = _transport_for(handler)
+        try:
+            with pytest.raises(RequestRejectedError):
+                await _complete(transport, source, overlay=overlay)
+            assert sent == []
+        finally:
+            await transport.aclose()
+
+
+class TestDefaultClientFactory:
+    """直接检查生产 factory，不用取证测试的另一套 factory 代替。"""
+
+    @pytest.fixture(autouse=True)
+    def isolate_proxy_environment(self, monkeypatch):
+        """离线构造测试不继承开发机代理；仍真实验证 trust_env 传递。"""
+        for key in ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY"):
+            monkeypatch.delenv(key, raising=False)
+            monkeypatch.delenv(key.lower(), raising=False)
+
+    @pytest.mark.parametrize("key", ["fake-a", "fake-b"])
+    async def test_authorization_uses_source_api_key(self, key):
+        from polygateway.transports.openai_compat import _default_client_factory
+
+        client = _default_client_factory(_source(api_key=key))
+        try:
+            assert client.headers["Authorization"] == f"Bearer {key}"
+            assert (
+                client.build_request("POST", "https://gw.example/v1/chat/completions").headers[
+                    "Authorization"
+                ]
+                == f"Bearer {key}"
+            )
+        finally:
+            await client.aclose()
+
+    @pytest.mark.parametrize("timeout", [17.0, 53.0])
+    async def test_timeout_uses_source_timeout_for_all_phases(self, timeout):
+        from polygateway.transports.openai_compat import _default_client_factory
+
+        client = _default_client_factory(_source(timeout_s=timeout))
+        try:
+            assert [
+                client.timeout.connect,
+                client.timeout.read,
+                client.timeout.write,
+                client.timeout.pool,
+            ] == [timeout] * 4
+        finally:
+            await client.aclose()
+
+    @pytest.mark.parametrize("trust_env", [True, False])
+    async def test_trust_env_uses_source_setting(self, trust_env):
+        from polygateway.transports.openai_compat import _default_client_factory
+
+        client = _default_client_factory(_source(trust_env=trust_env))
+        try:
+            assert client.trust_env is trust_env
+        finally:
+            await client.aclose()
+
+
+@pytest.mark.parametrize("key", ["depth.key", "off_control", "switch"])
+async def test_custom_profile_raw_roots_cannot_override_managed_intent(key):
+    registry = {
+        "custom": ProviderProfile(
+            name="custom",
+            thinking=ThinkingWire(
+                off={"off_control": False}, on_base={"switch": True}, effort_key="depth.key"
+            ),
+            strip_think_tags=False,
+        )
+    }
+    sent = []
+    transport = _transport_for(
+        lambda request: sent.append(request) or _sse_stream(_chunk(content="x")), registry=registry
+    )
+    try:
+        with pytest.raises(RequestRejectedError, match="冲突"):
+            await _complete(
+                transport,
+                _source(provider="custom"),
+                reasoning_effort=Effort.HIGH,
+                overlay={key: True},
+            )
+        assert sent == []
+    finally:
+        await transport.aclose()

tests/unit/test_package.py

@@ -60,12 +60,15 @@ def test_thinking_public_surface_exported():
 
     `observe_thinking` / `reconcile_thinking` **不**导出: 它们是 transport 内部
     的裁定与对账,下游读 `LLMResponse.thinking_observation` 即可,导出即多一份
-    永久承诺。
+    永久承诺。`ThinkingResolution` 则**要**导出——它是已导出的 `resolve_thinking`
+    的返回类型,不导出等于下游拿得到实例却写不出类型标注。
     """
     for name in (
         "ThinkingCapability",
         "ThinkingObservation",
+        "ThinkingResolution",
         "ThinkingUnsupportedError",
+        "ThinkingWire",
         "get_capability",
         "register_capability",
         "resolve_thinking",
@@ -74,3 +77,14 @@ def test_thinking_public_surface_exported():
         assert name in polygateway.__all__, name
     assert "observe_thinking" not in polygateway.__all__
     assert "reconcile_thinking" not in polygateway.__all__
+
+
+def test_every_promised_export_is_actually_importable():
+    """`__all__` 里的每个名字都必须真的绑在包上。
+
+    只维护 `__all__` 而漏掉 import,`from polygateway import X` 与 `import *`
+    都会当场炸,而逐个点名的用例只覆盖它当时想到的符号——2026-09-04 的
+    `ThinkingWire` 正是这样漏进来的(在 `__all__` 里躺了一个提交却 import 不到)。
+    """
+    missing = [name for name in polygateway.__all__ if not hasattr(polygateway, name)]
+    assert not missing, f"__all__ 承诺了但没绑上的符号: {missing}"

tests/unit/test_ports.py

@@ -1,15 +1,18 @@
 """ports.py 端口冻结测试(M1 设计 §4): Protocol 结构性检查 + Gate 快照校验。"""
 
+import inspect
 from typing import Any
 
 import pytest
 
 from polygateway.ports import (
     CacheBackend,
+    EmbeddingTransport,
     GateDecision,
     GateState,
     GateUpdate,
     Middleware,
+    OcrTransport,
     Permit,
     ProviderGate,
     RateLimiter,
@@ -69,7 +72,7 @@ class _DummyMw:
 
 
 class _DummyTransport:
-    async def complete(self, *, messages, source, stream, overlay, call_id):
+    async def complete(self, *, messages, source, stream, overlay, call_id, reasoning_effort):
         raise NotImplementedError
 
 
@@ -121,6 +124,18 @@ class _DummyRecorder:
         reasoning_tokens,
         tenant_id,
         meta,
+        thinking_observation,
+        reasoning_effort,
+        scope,
+        operation,
+        logical_call_id,
+        event_kind,
+        http_status_code,
+        error_type,
+        cause_type,
+        error_body,
+        attempts,
+        total_latency_ms,
     ) -> None: ...
 
 
@@ -142,6 +157,34 @@ def test_protocols_are_runtime_checkable(impl, protocol):
     assert isinstance(impl, protocol)
 
 
+class TestReasoningTierIsOnlyOnTheChatPort:
+    """档位属于 chat 端口,且**只属于**它(Task 5b)。
+
+    `@runtime_checkable` 只查方法名不查签名,故协议签名本身必须被显式断言——
+    否则实现漏改一个参数,要到运行期调用才会以 `TypeError` 现形,而那时的现场
+    离根因已经很远。
+    """
+
+    def test_chat_transport_carries_the_per_call_tier(self):
+        params = inspect.signature(Transport.complete).parameters
+        assert "reasoning_effort" in params
+        # 不给默认值是有意的(与 TelemetryRecorder 同一既有约定): 库外无第三方
+        # 实现者,写全签名成本为零,而默认值会把"漏传"变成静默的"不表态"
+        assert params["reasoning_effort"].default is inspect.Parameter.empty
+
+    @pytest.mark.parametrize(
+        ("protocol", "method"),
+        [
+            (EmbeddingTransport, "embed"),
+            (OcrTransport, "recognize_text"),
+            (OcrTransport, "parse_layout"),
+        ],
+    )
+    def test_other_transports_have_no_reasoning_tier(self, protocol, method):
+        """embedding 与 OCR 没有推理语义,给它们加档位只会静默无效(issue #4 同款决策)。"""
+        assert "reasoning_effort" not in inspect.signature(getattr(protocol, method)).parameters
+
+
 class _DummyStatusProvider(_DummyRecorder):
     @property
     def telemetry_status(self) -> TelemetryStatus:
@@ -244,7 +287,48 @@ class TestTelemetryRecorderSignature:
         params = inspect.signature(TelemetryRecorder.record_llm_call).parameters
         assert {"tenant_id", "meta"} <= set(params)
 
-    @pytest.mark.parametrize("name", ["tenant_id", "meta", "thinking_observation"])
+    def test_call_observability_fields_are_declared(self):
+        """1.3.5 十列进协议(issue #19/#23);字段总数以实测为准不凭记忆。
+
+        本签名同时是装配闸的事实源(`_assert_recorder_shape` 按它派生参数名),
+        故它与实现一旦漂移,下游自定义 recorder 会在装配期就被拒。
+        """
+        import inspect
+
+        params = inspect.signature(TelemetryRecorder.record_llm_call).parameters
+        assert {
+            "scope",
+            "operation",
+            "logical_call_id",
+            "event_kind",
+            "http_status_code",
+            "error_type",
+            "cause_type",
+            "error_body",
+            "attempts",
+            "total_latency_ms",
+        } <= set(params)
+        assert len(params) - 1 == 36  # 减掉 self
+
+    @pytest.mark.parametrize(
+        "name",
+        [
+            "tenant_id",
+            "meta",
+            "thinking_observation",
+            "reasoning_effort",
+            "scope",
+            "operation",
+            "logical_call_id",
+            "event_kind",
+            "http_status_code",
+            "error_type",
+            "cause_type",
+            "error_body",
+            "attempts",
+            "total_latency_ms",
+        ],
+    )
     def test_caller_dimensions_have_no_default(self, name):
         import inspect
 

tests/unit/test_pricing.py

@@ -169,7 +169,7 @@ def _source(model="qwen-max"):
 class TestEmitterCost:
     async def test_success_row_costed(self):
         rec = _MemoryRecorder()
-        emitter = TelemetryEmitter(rec, pricing=_TABLE, text_cap=None)
+        emitter = TelemetryEmitter(rec, pricing=_TABLE, text_cap=None, scope="LLM")
         await emitter.emit_attempt(
             request=_REQ,
             source=_source(),
@@ -177,18 +177,20 @@ class TestEmitterCost:
             latency_ms=1,
             response=_resp(),
             error=None,
+            reasoning_applies=True,
+            operation="chat",
         )
         assert rec.rows[0]["cost"] == pytest.approx(7.2)
 
     async def test_cache_hit_row_costs_zero(self):
         rec = _MemoryRecorder()
-        emitter = TelemetryEmitter(rec, pricing=_TABLE, text_cap=None)
+        emitter = TelemetryEmitter(rec, pricing=_TABLE, text_cap=None, scope="LLM")
-        await emitter.emit_cache_hit(request=_REQ, response=_resp(cache_hit=True))
+        await emitter.emit_cache_hit(request=_REQ, response=_resp(cache_hit=True), operation="chat")
         assert rec.rows[0]["cost"] == 0.0
 
     async def test_failure_row_cost_none(self):
         rec = _MemoryRecorder()
-        emitter = TelemetryEmitter(rec, pricing=_TABLE, text_cap=None)
+        emitter = TelemetryEmitter(rec, pricing=_TABLE, text_cap=None, scope="LLM")
         await emitter.emit_attempt(
             request=_REQ,
             source=_source(),
@@ -196,12 +198,14 @@ class TestEmitterCost:
             latency_ms=1,
             response=None,
             error="TransientError: boom",
+            reasoning_applies=True,
+            operation="chat",
         )
         assert rec.rows[0]["cost"] is None
 
     async def test_unknown_model_none_without_blocking(self):
         rec = _MemoryRecorder()
-        emitter = TelemetryEmitter(rec, pricing=_TABLE, text_cap=None)
+        emitter = TelemetryEmitter(rec, pricing=_TABLE, text_cap=None, scope="LLM")
         await emitter.emit_attempt(
             request=_REQ,
             source=_source(model="mystery"),
@@ -209,13 +213,15 @@ class TestEmitterCost:
             latency_ms=1,
             response=_resp(model="mystery"),
             error=None,
+            reasoning_applies=True,
+            operation="chat",
         )
         assert rec.rows[0]["cost"] is None
 
     async def test_no_pricing_keeps_none(self):
         """未注入价格表 = M1 现状: cost 恒 None(回归)。"""
         rec = _MemoryRecorder()
-        emitter = TelemetryEmitter(rec, text_cap=None)
+        emitter = TelemetryEmitter(rec, text_cap=None, scope="LLM")
         await emitter.emit_attempt(
             request=_REQ,
             source=_source(),
@@ -223,5 +229,7 @@ class TestEmitterCost:
             latency_ms=1,
             response=_resp(),
             error=None,
+            reasoning_applies=True,
+            operation="chat",
         )
         assert rec.rows[0]["cost"] is None

tests/unit/test_providers.py

@@ -1,57 +1,114 @@
-"""providers.py 注册表测试(M1 设计 §7;register_provider 为纯函数,无可变全局)。"""
+"""providers.py 注册表测试(M1 设计 §7;register_provider 为纯函数,无可变全局)。
+
+2026-09-04 起 profile 存的是 `ThinkingWire`(off / on_base / effort_key)而非两个
+固定片段——档位型模型(GLM-5.3、kimi-k3、deepseek-v4…)的"开"档需要附一个档位值,
+两个固定片段表达不了。
+"""
 
 import pytest
 
 from polygateway.providers import (
     DEFAULT_PROFILES,
     ProviderProfile,
+    ThinkingWire,
     get_provider,
     register_provider,
 )
 
+_EXPECTED_SEGMENTS = frozenset(
+    {"qwen", "deepseek", "zhipu", "moonshot", "minimax", "openai", "anthropic", "google"}
+)
+
 
 class TestDefaultProfiles:
-    def test_qwen_profile(self):
+    def test_all_eight_profiles_registered(self):
-        p = get_provider("qwen")
+        """issue #20: 智谱缺段,下游只能把 GLM 挂在 openai 兜底段下再手写 extra_body。"""
-        assert p.thinking_on == {"enable_thinking": True}
+        assert set(DEFAULT_PROFILES) == _EXPECTED_SEGMENTS
-        assert p.thinking_off == {"enable_thinking": False}
-        assert p.strip_think_tags is True
-        assert p.supports_native_schema is False
 
-    def test_deepseek_profile(self):
+    def test_qwen_is_a_switch_with_no_tiers(self):
-        p = get_provider("deepseek")
+        w = get_provider("qwen").thinking
-        assert p.thinking_on == {"thinking": {"type": "enabled"}}
+        assert w.on_base == {"enable_thinking": True}
-        assert p.thinking_off == {"thinking": {"type": "disabled"}}
+        assert w.off == {"enable_thinking": False}
-        assert p.strip_think_tags is False
+        assert w.effort_key is None  # 百炼靠 thinking_budget 调深度,不是档位
+        assert get_provider("qwen").strip_think_tags is True
 
-    def test_openai_slots_are_unknown_not_empty(self):
+    def test_deepseek_carries_both_switch_and_tier(self):
-        """issue #5: 该段名实践中被复用为任意兼容厂商的兜底(下游把 kimi 挂在此),
+        w = get_provider("deepseek").thinking
+        assert w.on_base == {"thinking": {"type": "enabled"}}
+        assert w.off == {"thinking": {"type": "disabled"}}
+        assert w.effort_key == "reasoning_effort"
 
-        故不能下发任何厂商方言参数。None = 形态未知 → 配了 enable_thinking 即报错,
+    def test_zhipu_matches_the_vendor_migration_note(self):
-        而不是空字典那种"注入了个寂寞"的静默失效。
+        """智谱官方: thinking.type=enabled + reasoning_effort 才是 GLM-5.3 的正确形态。"""
+        w = get_provider("zhipu").thinking
+        assert w.on_base == {"thinking": {"type": "enabled"}}
+        assert w.off == {"thinking": {"type": "disabled"}}
+        assert w.effort_key == "reasoning_effort"
+
+    def test_openai_family_sends_the_standard_field_only(self):
+        """gpt/claude/gemini 经网关都吃 OpenAI 标准的 reasoning_effort,不下发厂商方言。
+
+        minimax 2026-09-05 起不在本组: 它的形态相同,但"开"这一档被迫带上了一个
+        档位值(见 `test_minimax_on_tier_carries_a_tier_value`)。
         """
-        p = get_provider("openai")
+        for name in ("openai", "anthropic", "google"):
-        assert p.thinking_on is None and p.thinking_off is None
+            w = get_provider(name).thinking
-        assert p.strip_think_tags is False
+            assert w.on_base == {}, name
+            assert w.off == {"reasoning_effort": "none"}, name
+            assert w.effort_key == "reasoning_effort", name
 
-    def test_minimax_profile_uses_reasoning_effort(self):
+    def test_minimax_on_does_not_select_a_tier(self):
-        """2026-08-02 实测: reasoning_effort 才是 MiniMax 认的开关。"""
+        """形态不代替模型能力，也不替调用者选择付费档位。"""
-        p = get_provider("minimax")
+        w = get_provider("minimax").thinking
-        assert p.thinking_off == {"reasoning_effort": "none"}
+        assert w.on_base == {}
-        assert p.thinking_on == {"reasoning_effort": "medium"}
+        assert w.off == {"reasoning_effort": "none"}
-        assert p.strip_think_tags is False
+        assert w.effort_key == "reasoning_effort"
 
     def test_unknown_provider_fails_loudly(self):
         """消灭子串猜测: 未注册 provider 装配期即报错,不做模糊匹配。"""
         with pytest.raises(ValueError, match="glm"):
-            get_provider("glm")
+            get_provider("glm")  # 段名是 zhipu,不是 glm
         with pytest.raises(ValueError):
             get_provider("qwen2")  # 子串相似也不放行
 
+    def test_error_lists_every_registered_segment(self):
+        with pytest.raises(ValueError, match="zhipu"):
+            get_provider("nope")
+
+
+class TestWireNoneSemantics:
+    """三个 `None` 语义互不重叠(issue #5 的成果,不可退回成"注入了个寂寞")。"""
+
+    def test_on_base_none_means_shape_unknown(self):
+        w = ThinkingWire(off=None, on_base=None, effort_key=None)
+        assert w.on_base is None
+
+    def test_off_none_means_no_off_shape(self):
+        """有开启形态但没有关闭形态,与"整个形态未知"是两回事。"""
+        w = ThinkingWire(off=None, on_base={"x": 1}, effort_key=None)
+        assert w.on_base is not None and w.off is None
+
+    def test_effort_key_none_means_switch_only(self):
+        """qwen 是这一档: 能开能关,但没有档位可谈。"""
+        assert get_provider("qwen").thinking.effort_key is None
+
+    def test_empty_on_base_is_not_none(self):
+        """`{}` = 已知无需注入任何参数即处于该档;`None` = 不知道怎么表达。
+
+        样本 2026-09-05 由 minimax 换成 openai: minimax 的 `on_base` 因 issue #21
+        改回带值,不再是空片段;openai 段是现存 `{}` 语义的代表。
+        """
+        w = get_provider("openai").thinking
+        assert w.on_base == {} and w.on_base is not None
+
 
 class TestPureFunctionRegistration:
     def test_register_returns_new_mapping(self):
-        glm = ProviderProfile(name="glm", thinking_on={}, thinking_off={}, strip_think_tags=False)
+        glm = ProviderProfile(
+            name="glm",
+            thinking=ThinkingWire(off={}, on_base={}, effort_key=None),
+            strip_think_tags=False,
+        )
         table = register_provider(glm)
         assert get_provider("glm", registry=table) is glm
         # 默认表未被污染(无可变全局状态铁律)
@@ -59,12 +116,14 @@ class TestPureFunctionRegistration:
             get_provider("glm")
 
     def test_register_on_custom_base_and_override(self):
-        custom_qwen = ProviderProfile(
+        custom = ProviderProfile(
-            name="qwen", thinking_on={"x": 1}, thinking_off={}, strip_think_tags=False
+            name="qwen",
+            thinking=ThinkingWire(off={}, on_base={"x": 1}, effort_key=None),
+            strip_think_tags=False,
         )
-        table = register_provider(custom_qwen, base=DEFAULT_PROFILES)
+        table = register_provider(custom, base=DEFAULT_PROFILES)
-        assert get_provider("qwen", registry=table).thinking_on == {"x": 1}
+        assert get_provider("qwen", registry=table).thinking.on_base == {"x": 1}
-        assert get_provider("qwen").thinking_on == {"enable_thinking": True}
+        assert get_provider("qwen").thinking.on_base == {"enable_thinking": True}
 
     def test_default_profiles_mapping_is_read_only(self):
         with pytest.raises(TypeError):

tests/unit/test_retention_tool.py

@@ -261,6 +261,157 @@ class TestUsageErrors:
 
         assert result.returncode == 1
 
+    # --- --table 的参数分类(issue #18 设计 §4.2);真实解析行为在集成层验 ---
+
+    def test_sqlite_with_table_exits_one(self, tmp_path):
+        """SQLite 库文件即目标,无 schema 概念,故 `--table` 在该分支无歧义可消。"""
+        result = _run(
+            "--backend",
+            "sqlite",
+            "--path",
+            str(tmp_path / "x.db"),
+            "--older-than-days",
+            "7",
+            "--table",
+            "some_schema.llm_calls",
+        )
+
+        assert result.returncode == 1
+        assert "--table" in result.stderr
+        # 单看退出码与 "--table" 字样会被 argparse 的 "unrecognized arguments" 蒙混
+        # 过去(它也是退出 1、也回显参数名)。必须钉住"参数已被识别、因规则被拒"。
+        assert "unrecognized" not in result.stderr
+
+    def test_table_without_schema_qualifier_exits_one(self):
+        """单段等于没声明: 目标仍由 `search_path` 决定,隐式性原样保留,故拒绝。"""
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            "postgresql://x/y",
+            "--older-than-days",
+            "7",
+            "--table",
+            "llm_calls",
+        )
+
+        assert result.returncode == 1
+        assert "--table" in result.stderr
+        # 单看退出码与 "--table" 字样会被 argparse 的 "unrecognized arguments" 蒙混
+        # 过去(它也是退出 1、也回显参数名)。必须钉住"参数已被识别、因规则被拒"。
+        assert "unrecognized" not in result.stderr
+
+    def test_table_with_empty_segment_exits_one(self):
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            "postgresql://x/y",
+            "--older-than-days",
+            "7",
+            "--table",
+            ".llm_calls",
+        )
+
+        assert result.returncode == 1
+        assert "--table" in result.stderr
+        # 单看退出码与 "--table" 字样会被 argparse 的 "unrecognized arguments" 蒙混
+        # 过去(它也是退出 1、也回显参数名)。必须钉住"参数已被识别、因规则被拒"。
+        assert "unrecognized" not in result.stderr
+
+    def test_table_with_quote_in_a_segment_exits_one(self):
+        """含引号的复杂标识符不支持: 此时退回不给 `--table` 的路径(见 epilog)。"""
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            "postgresql://x/y",
+            "--older-than-days",
+            "7",
+            "--table",
+            'sch"ema.llm_calls',
+        )
+
+        assert result.returncode == 1
+        assert "--table" in result.stderr
+        # 单看退出码与 "--table" 字样会被 argparse 的 "unrecognized arguments" 蒙混
+        # 过去(它也是退出 1、也回显参数名)。必须钉住"参数已被识别、因规则被拒"。
+        assert "unrecognized" not in result.stderr
+
+    def test_table_naming_another_table_exits_one(self):
+        """表名段锁死: 不加这条,`--table` 会把本脚本扩成"任意同形表删除工具"。"""
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            "postgresql://x/y",
+            "--older-than-days",
+            "7",
+            "--table",
+            "audit.events",
+        )
+
+        assert result.returncode == 1
+        assert "--table" in result.stderr
+        # 单看退出码与 "--table" 字样会被 argparse 的 "unrecognized arguments" 蒙混
+        # 过去(它也是退出 1、也回显参数名)。必须钉住"参数已被识别、因规则被拒"。
+        assert "unrecognized" not in result.stderr
+        # 错误消息要当场把边界说清: 本脚本的作用域到 llm_calls 为止
+        assert "llm_calls" in result.stderr
+
+
+class TestTableIdentifierWhitelist:
+    """schema 段只收普通标识符: 让 `--help` 说的"不支持复杂标识符"成为事实。
+
+    这不是安全边界(`to_regclass($1)` 参数化 + `_quote` 转义,注入面本就不存在),
+    是**契约边界**: 帮助文本写着不支持,实现却照单全收,受害的是照文档做判断的人。
+    """
+
+    def test_schema_with_a_space_exits_one(self):
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            "postgresql://x/y",
+            "--older-than-days",
+            "7",
+            "--table",
+            "bad schema.llm_calls",
+        )
+
+        assert result.returncode == 1
+        assert "--table" in result.stderr
+
+    def test_schema_with_a_semicolon_exits_one(self):
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            "postgresql://x/y",
+            "--older-than-days",
+            "7",
+            "--table",
+            "a;b.llm_calls",
+        )
+
+        assert result.returncode == 1
+        assert "--table" in result.stderr
+
+    def test_a_plain_identifier_with_underscores_and_digits_is_accepted(self):
+        """收紧不得误伤正常名字: 这条走到连接阶段才失败(退出 2),说明校验放行了。"""
+        result = _run(
+            "--backend",
+            "postgres",
+            "--dsn",
+            "postgresql://127.0.0.1:1/nope",
+            "--older-than-days",
+            "7",
+            "--table",
+            "pgw_s_a1b2c3.llm_calls",
+        )
+
+        assert result.returncode == 2
+
 
 class TestHelp:
     def test_help_names_the_maintenance_role_and_the_recommended_path(self):
@@ -271,3 +422,12 @@ class TestHelp:
         assert "维护角色" in result.stdout
         assert "REVOKE" in result.stdout
         assert "PARTITION" in result.stdout
+
+    def test_help_states_the_table_name_is_fixed(self):
+        """`--table` 只有 schema 一段可变,这条边界必须写在运维会读到的地方。"""
+        result = _run("--help")
+
+        assert result.returncode == 0
+        assert "--table" in result.stdout
+        assert "只清理" in result.stdout
+        assert "llm_calls" in result.stdout

tests/unit/test_retry.py

@@ -5,6 +5,7 @@
 """
 
 import asyncio
+import dataclasses
 
 import pytest
 
@@ -24,6 +25,7 @@ from polygateway.types import (
     BackpressurePolicy,
     BreakerConfig,
     ChatRequest,
+    Effort,
     GlobalLimits,
     RetryPolicy,
     SourceConfig,
@@ -63,14 +65,21 @@ def _ok(content="ok"):
 
 
 class FakeTransport:
-    """按脚本逐次返回结果或抛异常;记录每次 (source_name, call_id)。"""
+    """按脚本逐次返回结果或抛异常;记录每次 (source_name, call_id) 与收到的档位。
+
+    `reasoning_effort` 刻意**不给默认值**,与 `Transport` 协议保持逐字一致:
+    `@runtime_checkable` 只查方法名不查签名,fake 上多一个默认值就会把"中间件漏传"
+    这类缺口伪装成"调用方没表态",而报错现场离根因很远。
+    """
 
     def __init__(self, script):
         self.script = list(script)
         self.calls = []
+        self.efforts = []
 
-    async def complete(self, *, messages, source, stream, overlay, call_id):
+    async def complete(self, *, messages, source, stream, overlay, call_id, reasoning_effort):
         self.calls.append((source.name, call_id))
+        self.efforts.append(reasoning_effort)
         action = self.script.pop(0)
         if isinstance(action, Exception):
             raise action
@@ -135,6 +144,37 @@ def _harness(
 _REQ = ChatRequest(messages=[{"role": "user", "content": "hi"}])
 
 
+class TestRequestTierReachesTransport:
+    """请求级档位必须一路穿过洋葱到达 transport(Task 5b)。
+
+    `ChatRequest` 上填了字段而中间件不搬运,是"看起来配了、实际没发出去"的静默
+    失效——正是 issue #20 里下游改用 extra_body 绕过治理的成因。
+    """
+
+    async def test_request_tier_reaches_transport(self):
+        mw, _, _, transport, *_ = _harness([_src("a")], [_ok()])
+        await mw(
+            ChatRequest(messages=[{"role": "user", "content": "hi"}], reasoning_effort=Effort.HIGH)
+        )
+        assert transport.efforts == [Effort.HIGH]
+
+    async def test_absent_tier_is_carried_as_none(self):
+        """不表态也要显式传下去: 漏传与"传了 None"在协议上必须区分不开才安全。"""
+        mw, _, _, transport, *_ = _harness([_src("a")], [_ok()])
+        await mw(_REQ)
+        assert transport.efforts == [None]
+
+    async def test_tier_is_carried_on_every_retry_attempt(self):
+        """换源重试时档位不得在第二次尝试上丢失。"""
+        mw, _, _, transport, *_ = _harness(
+            [_src("a"), _src("b")], [TransientError("boom", source_name="a"), _ok()]
+        )
+        await mw(
+            ChatRequest(messages=[{"role": "user", "content": "hi"}], reasoning_effort=Effort.LOW)
+        )
+        assert transport.efforts == [Effort.LOW, Effort.LOW]
+
+
 class TestSuccessPath:
     async def test_first_attempt_success_builds_response(self):
         mw, limiter, gate, transport, sleep, _ = _harness([_src("a")], [_ok("hello")])
@@ -249,6 +289,33 @@ class TestObservabilityPassthrough:
         resp = await mw(_REQ)
         assert resp.thinking_observation is ThinkingObservation.UNKNOWN
 
+    async def test_applied_tier_reaches_the_response(self):
+        """issue #20: 实际发出的档由 transport 裁定,本层只搬运。
+
+        搬运这一步漏掉,`LLMResponse.applied_effort` 恒为 None,而遥测正是从这个
+        字段取"这一行跑在哪档"——整列会静默地全是 NULL。
+        """
+        result = TransportResult(
+            content="ok",
+            thinking="",
+            prompt_tokens=10,
+            completion_tokens=5,
+            usage_source="measured",
+            ttft_ms=12.0,
+            max_inter_token_ms=3.0,
+            raw={},
+            applied_effort=Effort.HIGH,
+        )
+        mw, *_ = _harness([_src("a")], [result])
+        resp = await mw(_REQ)
+        assert resp.applied_effort is Effort.HIGH
+
+    async def test_unstated_tier_stays_none(self):
+        """不表态的调用不得被填成某个档: 那等于替调用方声称它做过一个选择。"""
+        mw, *_ = _harness([_src("a")], [_ok()])
+        resp = await mw(_REQ)
+        assert resp.applied_effort is None
+
 
 class TestRetryAndFailover:
     async def test_transient_switches_source_then_succeeds(self):
@@ -710,3 +777,60 @@ class TestRateLimitPushback:
             await mw(_REQ)
         assert ei.value.reason == "retry_exhausted"
         assert len(transport.calls) == 3
+
+
+class TestLogicalAttemptCounting:
+    """尝试登记在 transport 调用**之前**(1.3.5 设计 §4)。
+
+    登记点若挪到成功之后,失败与取消的尝试就会从计数里消失——而那正是
+    诊断时最需要看见的几次。
+    """
+
+    def _ctx(self, clock):
+        from polygateway.types import _CallContext
+
+        return _CallContext(now=clock)
+
+    async def test_single_success_counts_one(self):
+        mw, _, _, _, _, clock = _harness([_src("a")], [_ok()])
+        ctx = self._ctx(clock)
+        await mw(dataclasses.replace(_REQ, call_context=ctx))
+        assert ctx.snapshot().attempts == 1
+
+    async def test_failed_retries_are_counted(self):
+        """两次可重试失败 + 一次成功 = 3 次尝试,不是 1 次。"""
+        mw, _, _, transport, _, clock = _harness(
+            [_src("a")], [TransientError("t1"), TransientError("t2"), _ok()]
+        )
+        ctx = self._ctx(clock)
+        await mw(dataclasses.replace(_REQ, call_context=ctx))
+        assert ctx.snapshot().attempts == 3 == len(transport.calls)
+
+    async def test_budget_free_429_still_counts_as_an_attempt(self):
+        """429 免的是重试预算,不是"没发生过"——它确实打到了网关。"""
+        mw, _, _, transport, _, clock = _harness(
+            [_src("a")],
+            [
+                TransientError("t1", status_code=429, retry_after_s=1.0),
+                TransientError("t2", status_code=429, retry_after_s=1.0),
+                _ok(),
+            ],
+        )
+        ctx = self._ctx(clock)
+        await mw(dataclasses.replace(_REQ, call_context=ctx))
+        assert ctx.snapshot().attempts == 3 == len(transport.calls)
+
+    async def test_retry_exhausted_counts_every_attempt(self):
+        mw, _, _, transport, _, clock = _harness(
+            [_src("a")], [TransientError(str(i)) for i in range(5)], max_attempts=3
+        )
+        ctx = self._ctx(clock)
+        with pytest.raises(AllSourcesExhausted):
+            await mw(dataclasses.replace(_REQ, call_context=ctx))
+        assert ctx.snapshot().attempts == 3 == len(transport.calls)
+
+    async def test_absent_context_does_not_break_the_call(self):
+        """库内现场构造的 `ChatRequest` 没有上下文,不得因此报错(设计 §3.5)。"""
+        mw, _, _, _, _, _ = _harness([_src("a")], [_ok()])
+        resp = await mw(_REQ)
+        assert resp.content == "ok" and _REQ.call_context is None

tests/unit/test_thinking.py

@@ -8,17 +8,29 @@
 import pytest
 from loguru import logger
 
-from polygateway.providers import get_provider
+from polygateway.providers import ProviderProfile, ThinkingWire, get_provider
 from polygateway.thinking import (
     DEFAULT_CAPABILITIES,
     ThinkingCapability,
+    ThinkingUnsupportedError,
+    effective_effort,
     get_capability,
     observe_thinking,
     reconcile_thinking,
     register_capability,
     resolve_thinking,
 )
-from polygateway.types import ThinkingObservation
+from polygateway.types import Effort, ThinkingObservation
+
+_MYSTERY = ProviderProfile(
+    name="mystery",
+    thinking=ThinkingWire(off=None, on_base=None, effort_key=None),
+    strip_think_tags=False,
+)
+"""形态完全未知的 provider(issue #5 的守卫对象)。
+
+2026-09-04 起默认表 8 段全部有形态,故未知样本改为显式构造——测的是**机制**
+(不知道怎么表达就报错并指路),不是某个段当时的配置。"""
 
 
 def _warnings():
@@ -125,7 +137,7 @@ class TestThinkingCapability:
         assert get_capability("some-brand-new-model") is None
 
     def test_register_capability_is_pure(self):
-        table = register_capability("x-1", ThinkingCapability(True, "实测"))
+        table = register_capability("x-1", ThinkingCapability((Effort.NONE, Effort.AUTO), "实测"))
         assert get_capability("x-1", table=table) is not None
         assert get_capability("x-1") is None  # 默认表未被污染
 
@@ -135,66 +147,399 @@ class TestThinkingCapability:
 
 
 class TestResolveThinking:
-    """五条判定规则(顺序即语义);设计 §5 真值表。"""
+    """五道关卡(顺序即语义)与 nearest 映射;设计 §4.1。
 
-    def test_rule1_none_injects_nothing(self):
+    每一关都有独立的失败模式,漏测哪一关,判定顺序被调换都不会被抓住——而顺序
+    在本函数里**就是**语义(Phase 4 落进 Phase 5 就丢掉"这个模型根本关不掉")。
+    """
+
+    # —— Phase 1: 不表态 ——
+
+    def test_phase1_absent_effort_injects_nothing(self):
+        """没表态就什么都不注入,用模型自己的默认档(与 `none` 严格区分)。"""
         got = resolve_thinking(get_provider("minimax"), None, None, model="MiniMax-M3")
-        assert got == {}
+        assert got.payload == {}
+        assert got.applied_effort is None
 
-    @pytest.mark.parametrize("enable", [True, False])
+    # —— Phase 2: 形态未知 ——
-    def test_rule2_unknown_shape_raises_and_points_the_way(self, enable):
-        with pytest.raises(ValueError, match="register_provider") as exc:
-            resolve_thinking(get_provider("openai"), None, enable, model="kimi-k3")
-        assert "extra_body" in str(exc.value)
 
-    def test_rule3_unregistered_model_warns_but_passes(self):
+    @pytest.mark.parametrize("effort", [Effort.NONE, Effort.AUTO, Effort.HIGH])
+    def test_phase2_unknown_wire_points_to_register(self, effort):
+        """不知道怎么发就报错并指路;静默放行是 issue #5 修掉的那种欺骗。
+
+        文案必须报出**请求的档位**而非"开/关"方向: `Effort` 是非空字符串,拿它
+        的真值判方向会把 `none` 说成"开启形态未知",指错了排查方向。
+        """
+        with pytest.raises(ThinkingUnsupportedError, match="register_provider") as exc:
+            resolve_thinking(_MYSTERY, None, effort, model="kimi-k3")
+        msg = str(exc.value)
+        assert "extra_body" in msg
+        assert "kimi-k3" in msg
+        assert effort.value in msg
+
+    def test_phase2_reads_the_form_the_asked_for_tier_needs(self):
+        """请求 `none` 只需要**关闭**形态: 开启形态未知与这次请求无关。
+
+        旧版 `slot = thinking_on if enable_thinking else thinking_off` 即按请求方向
+        取字段;档位化后一度写成"只看 `on_base`",于是一个已注册了关闭形态的自定义
+        provider 在请求 `none` 时被误拒,还被指向它已经做过的 `register_provider`
+        ——指错方向比不指更糟(设计 §2 处置表第 2 条,2026-09-05 独立验证查出)。
+        """
+        profile = ProviderProfile(
+            name="off_only",
+            thinking=ThinkingWire(
+                off={"thinking": {"type": "disabled"}}, on_base=None, effort_key=None
+            ),
+            strip_think_tags=False,
+        )
+        cap = ThinkingCapability((Effort.NONE, Effort.AUTO), "构造: 关得掉,开启形态却未登记")
+        got = resolve_thinking(profile, cap, Effort.NONE, model="x-1")
+        assert got.payload == {"thinking": {"type": "disabled"}}
+        assert got.applied_effort is Effort.NONE
+
+    @pytest.mark.parametrize("effort", [Effort.AUTO, Effort.HIGH])
+    def test_phase2_still_fires_when_the_on_form_is_the_missing_half(self, effort):
+        """反方向不得被一并放过: 要开推理而开启形态未知,仍须报错并指路注册。"""
+        profile = ProviderProfile(
+            name="off_only",
+            thinking=ThinkingWire(
+                off={"thinking": {"type": "disabled"}}, on_base=None, effort_key=None
+            ),
+            strip_think_tags=False,
+        )
+        cap = ThinkingCapability((Effort.NONE, Effort.AUTO, Effort.HIGH), "构造")
+        with pytest.raises(ThinkingUnsupportedError, match="register_provider") as exc:
+            resolve_thinking(profile, cap, effort, model="x-1")
+        assert effort.value in str(exc.value)
+
+    def test_phase2_beats_the_capability_checks(self):
+        """形态未知时无从注入,能力如何无关紧要——Phase 2 必须先于 4/5。"""
+        cap = ThinkingCapability((Effort.AUTO,), "构造")
+        with pytest.raises(ThinkingUnsupportedError, match="register_provider"):
+            resolve_thinking(_MYSTERY, cap, Effort.NONE, model="whatever")
+
+    # —— Phase 3: 能力未登记 ——
+
+    def test_phase3_unregistered_warns_then_injects(self):
+        """新模型上线不该被库挡住,但也不该假装成功: 喊一声再尽力注入。"""
         messages, sink_id = _warnings()
         try:
-            got = resolve_thinking(get_provider("minimax"), None, False, model="MiniMax-M9")
+            got = resolve_thinking(get_provider("minimax"), None, Effort.NONE, model="MiniMax-M9")
         finally:
             logger.remove(sink_id)
-        assert got == {"reasoning_effort": "none"}
+        assert got.payload == {"reasoning_effort": "none"}
+        assert got.applied_effort is Effort.NONE
         assert any("MiniMax-M9" in m for m in messages)
 
-    def test_rule4_cannot_disable_raises_with_the_model_name(self):
+    def test_phase3_can_be_silenced_on_the_hot_path(self):
-        cap = get_capability("MiniMax-M2.7")
+        """装配期已经喊过一次,逐次调用再喊只会刷屏;判定结果不受影响。"""
-        with pytest.raises(ValueError, match="MiniMax-M2.7"):
+        messages, sink_id = _warnings()
-            resolve_thinking(get_provider("minimax"), cap, False, model="MiniMax-M2.7")
+        try:
+            got = resolve_thinking(
+                get_provider("minimax"),
+                None,
+                Effort.NONE,
+                model="MiniMax-M9",
+                warn_unregistered=False,
+            )
+        finally:
+            logger.remove(sink_id)
+        assert got.payload == {"reasoning_effort": "none"}
+        assert not [m for m in messages if "MiniMax-M9" in m]
 
-    def test_rule4_only_blocks_the_off_direction(self):
+    def test_phase3_does_not_validate_tiers(self):
-        """关不掉 ≠ 开不了: M2.x 默认就在推理,开的方向不该被拦。"""
+        """能力未知就没有清单可比对,拿空清单去拒绝档位等于凭空报错。"""
-        cap = get_capability("MiniMax-M2.7")
+        got = resolve_thinking(
-        got = resolve_thinking(get_provider("minimax"), cap, True, model="MiniMax-M2.7")
+            get_provider("zhipu"),
-        assert got == {"reasoning_effort": "medium"}
+            None,
+            Effort.XHIGH,
+            model="glm-9-not-registered",
+            warn_unregistered=False,
+        )
+        assert got.payload == {"thinking": {"type": "enabled"}, "reasoning_effort": "xhigh"}
+        assert got.applied_effort is Effort.XHIGH
 
-    def test_rule5_normal_path(self):
+    # —— Phase 4: 关不掉 ——
+
+    def test_phase4_before_phase5(self):
+        """请求 `none` 而模型关不掉: 文案必须给出可执行替代与 env 键名。
+
+        若落进 Phase 5 的通用分支,报错会退化成"不支持 none,可选 low/high/max",
+        丢掉"这个模型根本关不掉"这个关键信息——下游随后就会去找 extra_body 那条
+        绕过的路,而那正是 issue #20 的成因。
+        """
+        cap = get_capability("glm-5.3")
+        with pytest.raises(ThinkingUnsupportedError) as exc:
+            resolve_thinking(get_provider("zhipu"), cap, Effort.NONE, model="glm-5.3")
+        msg = str(exc.value)
+        assert "glm-5.3" in msg
+        assert "'low'" in msg, "必须给出 cheapest_effort 的值"
+        assert "REASONING_EFFORT" in msg, "必须给出 env 键名"
+        assert "可选档位" not in msg, "退化成 Phase 5 的通用文案即失去可执行替代"
+
+    def test_phase4_never_maps_even_with_nearest(self):
+        """`none` 不走映射: 把"关不掉"映射成"开着最低档"就是又一次静默降级。"""
+        cap = get_capability("glm-5.3")
+        with pytest.raises(ThinkingUnsupportedError, match="REASONING_EFFORT"):
+            resolve_thinking(
+                get_provider("zhipu"), cap, Effort.NONE, model="glm-5.3", fallback="nearest"
+            )
+
+    @pytest.mark.parametrize("model", ["MiniMax-M2.5", "MiniMax-M2.7"])
+    def test_phase4_only_blocks_the_off_direction(self, model):
+        """已登记 AUTO 只发开启片段，不由库代选 medium。"""
+        got = resolve_thinking(
+            get_provider("minimax"), get_capability(model), Effort.AUTO, model=model
+        )
+        assert got.payload == {}
+        assert got.applied_effort is Effort.AUTO
+
+    def test_phase4_passes_when_none_is_registered(self):
         cap = get_capability("MiniMax-M3")
-        assert resolve_thinking(get_provider("minimax"), cap, False, model="MiniMax-M3") == {
+        got = resolve_thinking(get_provider("minimax"), cap, Effort.NONE, model="MiniMax-M3")
-            "reasoning_effort": "none"
+        assert got.payload == {"reasoning_effort": "none"}
-        }
+        assert got.applied_effort is Effort.NONE
 
-    def test_unknown_shape_beats_capability_check(self):
+    # —— Phase 5: 档位打空 ——
-        """第 2 步先于第 4 步: 形态未知时无从注入,能力如何无关紧要。"""
+
-        cap = ThinkingCapability(can_disable=False, evidence="构造")
+    def test_phase5_lists_tiers_for_tiered_model(self):
-        with pytest.raises(ValueError, match="register_provider"):
+        """档位型模型: 文案必须列出它真有的档,否则下游只能猜。"""
-            resolve_thinking(get_provider("openai"), cap, False, model="whatever")
+        cap = get_capability("glm-5.3")
+        with pytest.raises(ThinkingUnsupportedError) as exc:
+            resolve_thinking(get_provider("zhipu"), cap, Effort.MEDIUM, model="glm-5.3")
+        msg = str(exc.value)
+        assert "medium" in msg and "glm-5.3" in msg
+        assert "可选档位" in msg
+        assert "low" in msg and "high" in msg and "max" in msg
+
+    def test_phase5_says_toggle_only_for_switch_model(self):
+        """纯开关型模型没有档位,对它说"可选档位"是错的(设计 §3.2 第三个派生量)。
+
+        样本 2026-09-05 由 MiniMax-M3 换成 glm-4.6v: T10 实测 M3 的六个强度值全部生效,
+        它不再是纯开关型;glm-4.6v 是实测证据最硬的 (none, auto) 模型,且 zhipu 的 wire
+        有 effort_key——这两点缺一不可,否则命中的是"该 provider 没有档位键"那条分支。
+        """
+        cap = get_capability("glm-4.6v")  # (none, auto): 能开能关,但没有强度档
+        with pytest.raises(ThinkingUnsupportedError) as exc:
+            resolve_thinking(get_provider("zhipu"), cap, Effort.HIGH, model="glm-4.6v")
+        msg = str(exc.value)
+        assert "可选档位" not in msg
+        assert "该模型只有开关" in msg
+        assert "auto" in msg and "none" in msg
+
+    def test_phase5_wording_forks_on_is_tiered(self):
+        """两条分叉必须真的不同——同一句话套两种模型等于没分叉。"""
+        with pytest.raises(ThinkingUnsupportedError) as tiered:
+            resolve_thinking(
+                get_provider("zhipu"), get_capability("glm-5.3"), Effort.MEDIUM, model="glm-5.3"
+            )
+        with pytest.raises(ThinkingUnsupportedError) as switch:
+            resolve_thinking(
+                get_provider("zhipu"),
+                get_capability("glm-4.6v"),
+                Effort.MEDIUM,
+                model="glm-4.6v",
+            )
+        assert str(tiered.value) != str(switch.value)
+
+    def test_phase5_passes_a_supported_tier(self):
+        cap = get_capability("glm-5.3")
+        got = resolve_thinking(get_provider("zhipu"), cap, Effort.MAX, model="glm-5.3")
+        assert got.payload == {"thinking": {"type": "enabled"}, "reasoning_effort": "max"}
+        assert got.applied_effort is Effort.MAX
+
+    @pytest.mark.parametrize(
+        "provider,model", [("deepseek", "deepseek-v4-pro"), ("minimax", "MiniMax-M3")]
+    )
+    @pytest.mark.parametrize("fallback", ["error", "nearest"])
+    def test_unregistered_auto_choice_is_rejected(self, provider, model, fallback):
+        """有开启形态也不代表已登记模型支持 AUTO，nearest 不可代选。"""
+        with pytest.raises(ThinkingUnsupportedError) as exc:
+            resolve_thinking(
+                get_provider(provider),
+                get_capability(model),
+                Effort.AUTO,
+                model=model,
+                fallback=fallback,
+            )
+        assert model in str(exc.value)
+        assert "auto" in str(exc.value)
+        assert "EFFORT_FALLBACK=nearest" not in str(exc.value)
+
+    def test_minimax_explicit_medium_restores_old_wire(self):
+        got = resolve_thinking(
+            get_provider("minimax"), get_capability("MiniMax-M3"), Effort.MEDIUM, model="MiniMax-M3"
+        )
+        assert got.payload == {"reasoning_effort": "medium"}
+        assert got.applied_effort is Effort.MEDIUM
+
+    @pytest.mark.parametrize("provider", ["openai", "qwen"])
+    def test_unknown_auto_warns_without_promising_effect(self, provider):
+        messages, sink = _warnings()
+        try:
+            got = resolve_thinking(
+                get_provider(provider), None, Effort.AUTO, model="unregistered-model"
+            )
+        finally:
+            logger.remove(sink)
+        assert got.applied_effort is Effort.AUTO
+        assert any("不保证" in str(message) for message in messages)
+
+    # —— nearest 映射(fallback 的逃生口)——
+
+    def test_nearest_ties_go_cheaper(self):
+        """等距取弱: 省钱优先,库不替下游涨价(一次 medium→max 是数倍账单)。"""
+        cap = get_capability("glm-5.3")  # (low, high, max)
+        messages, sink_id = _warnings()
+        try:
+            got = resolve_thinking(
+                get_provider("zhipu"), cap, Effort.MEDIUM, model="glm-5.3", fallback="nearest"
+            )
+        finally:
+            logger.remove(sink_id)
+        assert got.payload == {"thinking": {"type": "enabled"}, "reasoning_effort": "low"}
+        assert any("glm-5.3" in m and "medium" in m and "low" in m for m in messages)
+
+    def test_nearest_ties_go_cheaper_on_the_strong_side_too(self):
+        """xhigh 与 high/max 位序各差 1,同样取弱侧——规则不因方向而变。"""
+        cap = get_capability("glm-5.3")
+        got = resolve_thinking(
+            get_provider("zhipu"), cap, Effort.XHIGH, model="glm-5.3", fallback="nearest"
+        )
+        assert got.applied_effort is Effort.HIGH
+
+    def test_nearest_goes_up_when_the_only_neighbour_is_stronger(self):
+        """minimal 之下无档可选,映射必须上行到 low,而不是无解报错。"""
+        cap = get_capability("glm-5.3")
+        got = resolve_thinking(
+            get_provider("zhipu"), cap, Effort.MINIMAL, model="glm-5.3", fallback="nearest"
+        )
+        assert got.applied_effort is Effort.LOW
+
+    def test_nearest_never_turns_reasoning_off(self):
+        """请求"想得浅一点"绝不能被映射成"别想了": 那是方向反转,不是省钱。"""
+        cap = get_capability("glm-4.6v")  # (none, auto)
+        got = resolve_thinking(
+            get_provider("zhipu"), cap, Effort.HIGH, model="glm-4.6v", fallback="nearest"
+        )
+        assert got.applied_effort is Effort.AUTO
+        assert got.payload == {"thinking": {"type": "enabled"}}
+
+    def test_nearest_still_errors_when_no_on_tier_exists(self):
+        """只能关不能开的模型,映射无解——报错而非挑一个反向的档。"""
+        cap = ThinkingCapability((Effort.NONE,), "构造: 只登记了关闭档")
+        with pytest.raises(ThinkingUnsupportedError, match="only-off"):
+            resolve_thinking(
+                get_provider("minimax"), cap, Effort.HIGH, model="only-off", fallback="nearest"
+            )
+
+    def test_error_fallback_is_the_default(self):
+        """默认关闭映射的理由是钱: 静默的 medium→max 在 GLM-5.3 上是数倍账单。"""
+        cap = get_capability("glm-5.3")
+        with pytest.raises(ThinkingUnsupportedError):
+            resolve_thinking(get_provider("zhipu"), cap, Effort.MEDIUM, model="glm-5.3")
+
+    def test_resolution_reports_applied_effort_after_mapping(self):
+        """遥测记的必须是**实际**发出去的档,否则压测按档分组时挂在从未发出的档下。"""
+        cap = get_capability("glm-5.3")
+        got = resolve_thinking(
+            get_provider("zhipu"), cap, Effort.MEDIUM, model="glm-5.3", fallback="nearest"
+        )
+        assert got.applied_effort is Effort.LOW
+        assert got.applied_effort is not Effort.MEDIUM
+
+    # —— 注入形态 ——
+
+    def test_auto_injects_on_base_only(self):
+        """`auto` 逐字节等于旧的 `thinking_on`: 开启,但不附任何档位。"""
+        got = resolve_thinking(
+            get_provider("qwen"), get_capability("qwen3.7-plus"), Effort.AUTO, model="qwen3.7-plus"
+        )
+        assert got.payload == {"enable_thinking": True}
+
+    def test_effort_key_none_rejects_a_tier(self):
+        """qwen 系只有开关没有档位键: 硬塞一个档位只会发出一个厂商不认的字段。"""
+        cap = ThinkingCapability((Effort.NONE, Effort.LOW), "构造: 假设它有档位")
+        with pytest.raises(ThinkingUnsupportedError, match="没有档位键"):
+            resolve_thinking(get_provider("qwen"), cap, Effort.LOW, model="qwen-hypothetical")
+
+    def test_provider_without_an_off_form_says_which_half_is_missing(self):
+        """`off is None` ≠ `on_base is None`: 前者是"关不了",后者是"不知道怎么发"。"""
+        profile = ProviderProfile(
+            name="no_off",
+            thinking=ThinkingWire(off=None, on_base={}, effort_key="reasoning_effort"),
+            strip_think_tags=False,
+        )
+        cap = ThinkingCapability((Effort.NONE, Effort.LOW), "构造: 能力表说能关,形态却没有")
+        with pytest.raises(ThinkingUnsupportedError, match="没有关闭形态") as exc:
+            resolve_thinking(profile, cap, Effort.NONE, model="x-1")
+        assert "register_provider" not in str(exc.value), "形态已知,不该指向注册"
+
+    # —— 归一化: 本函数是档位进入库内的第四条入口(设计 §4.4) ——
+
+    def test_a_bare_string_tier_is_normalised_at_the_door(self):
+        """`resolve_thinking` 在 `__all__` 里,下游直调时传的天然是裸串。
+
+        第三参数本次由 `bool` 换成 `Effort`,而下游最自然的写法是从 JSON/配置读出来
+        的 `"low"`。不在入口归一,`_inject` 撞 `.value` 抛的是 `AttributeError`——
+        一个未文档化、也不属错误四分类的异常(2026-09-05 独立验证查出)。
+        """
+        got = resolve_thinking(
+            get_provider("zhipu"), get_capability("glm-5.3"), "low", model="glm-5.3"
+        )
+        assert got.payload == {"thinking": {"type": "enabled"}, "reasoning_effort": "low"}
+        assert got.applied_effort is Effort.LOW
+
+    def test_a_bare_none_string_still_means_the_off_tier(self):
+        """裸 `"none"` 必须走到关闭形态,而不是被当成某个开启档。
+
+        身份比较 `"none" is Effort.NONE` 恒假,漏归一的后果是**静默判否**:
+        `_wire_unknown_for` 的 `effort is not Effort.NONE` 恒真,于是关闭请求会去看
+        `on_base`——正是设计 §2 处置表第 2 条点名要避免的误判方向。
+        """
+        got = resolve_thinking(
+            get_provider("zhipu"), get_capability("glm-5.2"), "none", model="glm-5.2"
+        )
+        assert got.payload == {"thinking": {"type": "disabled"}}
+        assert got.applied_effort is Effort.NONE
+
+    def test_a_bare_none_string_reaches_phase4_on_a_model_that_cannot_disable(self):
+        """漏归一时 Phase 4 整条被绕过: 关不掉的模型会被静默放行成"开启"。"""
+        with pytest.raises(ThinkingUnsupportedError, match="无法关闭推理") as exc:
+            resolve_thinking(
+                get_provider("zhipu"), get_capability("glm-5.3"), "none", model="glm-5.3"
+            )
+        assert "'low'" in str(exc.value), "Phase 4 的可执行替代不能丢"
+
+    def test_an_illegal_tier_string_names_this_function_as_the_origin(self):
+        """非法档位报 `ValueError` 并指回**是哪一处**填错——档位有四条入口,不说清
+        就得让人自己去翻。"""
+        with pytest.raises(ValueError, match="resolve_thinking") as exc:
+            resolve_thinking(
+                get_provider("zhipu"), get_capability("glm-5.3"), "lowest", model="glm-5.3"
+            )
+        assert "非法推理档位" in str(exc.value)
 
 
 class TestReconcileThinking:
-    """声明 × 观测对账(设计 §5): 矛盾出文案,不表态出 None。
+    """声明 × 观测对账(设计 §4.3): 矛盾出文案,不表态出 None。
 
     文案本身是被断言对象——判定与日志分离正是为此: 告警内容可直接比对,不必
     去解析日志格式。
+
+    判据自 2026-09-05 起是**档位**而非布尔(设计 §4.3): `Effort.NONE` 走"要求
+    关闭"一支,其余档走"要求开启"一支。档位化不是换个参数名——文案里写的是本次
+    真正发出去的那一档,而 transport 的节流键正按它分离,两者必须同源。
     """
 
     _CAP = ThinkingCapability(
-        can_disable=True, evidence="2026-08-02 实测 reasoning_effort=none 可关闭"
+        (Effort.NONE, Effort.AUTO), "2026-08-02 实测 reasoning_effort=none 可关闭"
     )
 
     def test_off_but_observed_with_a_registered_capability_blames_the_table(self):
         """已登记却实测推理了 = 能力表漂移: 必须附 evidence 与更新指路。"""
         msg = reconcile_thinking(
-            enable_thinking=False,
+            effort=Effort.NONE,
             observation=ThinkingObservation.OBSERVED,
             capability=self._CAP,
             model="MiniMax-M3",
@@ -207,7 +552,7 @@ class TestReconcileThinking:
     def test_off_but_observed_unregistered_never_claims_a_table_entry(self):
         """未登记模型没有"能力表声称"这回事——说它就是撒谎。"""
         msg = reconcile_thinking(
-            enable_thinking=False,
+            effort=Effort.NONE,
             observation=ThinkingObservation.OBSERVED,
             capability=None,
             model="MiniMax-M9",
@@ -219,13 +564,13 @@ class TestReconcileThinking:
 
     def test_registered_and_unregistered_wordings_differ(self):
         registered = reconcile_thinking(
-            enable_thinking=False,
+            effort=Effort.NONE,
             observation=ThinkingObservation.OBSERVED,
             capability=self._CAP,
             model="MiniMax-M3",
         )
         unregistered = reconcile_thinking(
-            enable_thinking=False,
+            effort=Effort.NONE,
             observation=ThinkingObservation.OBSERVED,
             capability=None,
             model="MiniMax-M3",
@@ -236,7 +581,7 @@ class TestReconcileThinking:
     def test_on_but_absent_is_a_contradiction(self, capability):
         """上游明确上报未推理: 这是唯一的正面证伪,与能力表登记与否无关。"""
         msg = reconcile_thinking(
-            enable_thinking=True,
+            effort=Effort.AUTO,
             observation=ThinkingObservation.ABSENT,
             capability=capability,
             model="qwen3.7-plus",
@@ -248,7 +593,7 @@ class TestReconcileThinking:
     def test_on_but_unknown_admits_it_cannot_confirm(self, capability):
         """issue #17 的诚实版本: 明说"我注入了,但我看不见结果"。"""
         msg = reconcile_thinking(
-            enable_thinking=True,
+            effort=Effort.AUTO,
             observation=ThinkingObservation.UNKNOWN,
             capability=capability,
             model="MiniMax-M3",
@@ -265,7 +610,7 @@ class TestReconcileThinking:
         """
         assert (
             reconcile_thinking(
-                enable_thinking=False,
+                effort=Effort.NONE,
                 observation=ThinkingObservation.ABSENT,
                 capability=self._CAP,
                 model="qwen3.7-plus",
@@ -277,7 +622,7 @@ class TestReconcileThinking:
         """UNKNOWN 没有证伪力: 拿它报警等于每次关闭调用都喊(M3 关闭档恒落此档)。"""
         assert (
             reconcile_thinking(
-                enable_thinking=False,
+                effort=Effort.NONE,
                 observation=ThinkingObservation.UNKNOWN,
                 capability=self._CAP,
                 model="MiniMax-M3",
@@ -293,7 +638,7 @@ class TestReconcileThinking:
         """调用方不表态,就无从谈"违背"。"""
         assert (
             reconcile_thinking(
-                enable_thinking=None,
+                effort=None,
                 observation=observation,
                 capability=self._CAP,
                 model="MiniMax-M3",
@@ -304,10 +649,276 @@ class TestReconcileThinking:
     def test_on_and_observed_is_exactly_what_was_asked_for(self):
         assert (
             reconcile_thinking(
-                enable_thinking=True,
+                effort=Effort.AUTO,
                 observation=ThinkingObservation.OBSERVED,
                 capability=self._CAP,
                 model="MiniMax-M3",
             )
             is None
         )
+
+    @pytest.mark.parametrize("effort", [Effort.LOW, Effort.HIGH, Effort.MAX])
+    def test_a_strength_tier_is_an_on_request_not_an_off_one(self, effort):
+        """强度档必须走"要求开启"一支: 观测到推理正是它要的结果,不得报警。
+
+        判据写成真值性(`if not effort`)会在这里翻车——`Effort.NONE` 的取值是
+        非空串 `"none"`,恒为真;那种写法会把每一个强度档都送进"要求关闭"分支,
+        于是"想了"被当成矛盾,而"没想"反倒沉默,告警方向整个颠倒。
+        """
+        assert (
+            reconcile_thinking(
+                effort=effort,
+                observation=ThinkingObservation.OBSERVED,
+                capability=ThinkingCapability((Effort.LOW, Effort.HIGH, Effort.MAX), "构造"),
+                model="glm-5.3",
+            )
+            is None
+        )
+
+    def test_the_wording_names_the_tier_that_was_asked_for(self):
+        """文案要写出**本次这一档**: 节流键按档分离,文案不分档就看不出是哪一档。"""
+        low = reconcile_thinking(
+            effort=Effort.LOW,
+            observation=ThinkingObservation.ABSENT,
+            capability=None,
+            model="glm-5.3",
+        )
+        max_ = reconcile_thinking(
+            effort=Effort.MAX,
+            observation=ThinkingObservation.ABSENT,
+            capability=None,
+            model="glm-5.3",
+        )
+        assert low is not None and max_ is not None
+        assert "low" in low and "max" in max_
+        assert low != max_
+
+    def test_none_and_observed_is_the_issue_20_contradiction(self):
+        """请求 `none` 却观测到推理 —— issue #20 要恢复的那条报警,判据是**档位相等**。
+
+        与上一条互为对照: 同样是 OBSERVED,`none` 必须喊、强度档必须沉默。把分支
+        条件写反(`is not Effort.NONE`)会让这两条同时红,单有一条则抓不住。
+        """
+        msg = reconcile_thinking(
+            effort=Effort.NONE,
+            observation=ThinkingObservation.OBSERVED,
+            capability=None,
+            model="glm-5.3",
+        )
+        assert msg is not None and "none" in msg
+
+
+class TestEffortVocabulary:
+    """八档封闭词汇(设计 §3.1);`auto` 不可省——9 个纯开关型模型无强度档可填。"""
+
+    def test_none_and_auto_are_distinct_members(self):
+        assert Effort.NONE != Effort.AUTO
+        assert Effort("none") is Effort.NONE
+        assert Effort("auto") is Effort.AUTO
+
+    def test_vocabulary_is_exactly_eight(self):
+        assert len(list(Effort)) == 8
+
+    def test_values_are_wire_literals(self):
+        # 档位值直接写进请求体,改名即改变发出去的字节
+        assert [e.value for e in Effort] == [
+            "none",
+            "auto",
+            "minimal",
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+            "max",
+        ]
+
+
+class TestCapabilityTierList:
+    """能力表从 bool 变成档位清单(设计 §3.2);三个派生量不存字段,存了必漂移。"""
+
+    def test_capability_derives_can_disable(self):
+        assert ThinkingCapability((Effort.NONE, Effort.AUTO), "实测").can_disable is True
+        assert ThinkingCapability((Effort.LOW, Effort.MAX), "实测").can_disable is False
+
+    def test_cheapest_effort_skips_none(self):
+        # 「关不掉时的可执行替代」取的是除 none 外最弱的一档
+        assert (
+            ThinkingCapability((Effort.LOW, Effort.HIGH, Effort.MAX), "实测").cheapest_effort
+            is Effort.LOW
+        )
+        assert (
+            ThinkingCapability((Effort.NONE, Effort.HIGH, Effort.MAX), "实测").cheapest_effort
+            is Effort.HIGH
+        )
+        assert ThinkingCapability((Effort.NONE, Effort.AUTO), "实测").cheapest_effort is Effort.AUTO
+        assert ThinkingCapability((Effort.AUTO,), "实测").cheapest_effort is Effort.AUTO
+
+    def test_cheapest_effort_is_none_when_only_none(self):
+        # 只能关不能开: 没有可推荐的「最省的开启档」
+        assert ThinkingCapability((Effort.NONE,), "实测").cheapest_effort is None
+
+    def test_is_tiered_excludes_none_and_auto(self):
+        # 纯开关型模型不该被告知「可选档位」——它没有档位
+        assert ThinkingCapability((Effort.NONE, Effort.AUTO), "实测").is_tiered is False
+        assert ThinkingCapability((Effort.AUTO,), "实测").is_tiered is False
+        assert ThinkingCapability((Effort.LOW, Effort.MAX), "实测").is_tiered is True
+
+    def test_empty_efforts_rejected(self):
+        with pytest.raises(ValueError, match="至少"):
+            ThinkingCapability((), "实测")
+
+    def test_duplicate_efforts_rejected(self):
+        with pytest.raises(ValueError, match="重复"):
+            ThinkingCapability((Effort.LOW, Effort.LOW), "实测")
+
+    def test_glm53_cannot_be_disabled(self):
+        # 三源一致(智谱官方文档/cherry-studio/OpenRouter): thinking.type 只接受 enabled
+        cap = get_capability("glm-5.3")
+        assert cap is not None
+        assert cap.can_disable is False
+        assert cap.cheapest_effort is Effort.LOW
+
+    def test_m2_series_still_cannot_be_disabled(self):
+        # 迁移回归: 旧表用 can_disable=False 表达的事实,新表用「none 不在清单里」表达
+        assert get_capability("MiniMax-M2.7").can_disable is False
+        assert get_capability("MiniMax-M2.5").can_disable is False
+        assert get_capability("MiniMax-M3").can_disable is True
+
+
+class TestEffectiveEffort:
+    """三层优先级的**唯一**判定处(设计 §4.2): 请求级 > 源级 > 语法糖 > 不表态。
+
+    收口成一个纯函数,是因为它此前在装配守卫与 transport 里各写了一份就地转换:
+    两份各自演化的判定,迟早会在"装配期放行、运行期报错"这种最难查的形态上分叉。
+    """
+
+    def test_request_beats_source(self):
+        assert (
+            effective_effort(
+                request_effort=Effort.MAX, source_effort=Effort.LOW, enable_thinking=None
+            )
+            is Effort.MAX
+        )
+
+    def test_source_beats_sugar(self):
+        assert (
+            effective_effort(request_effort=None, source_effort=Effort.HIGH, enable_thinking=None)
+            is Effort.HIGH
+        )
+
+    def test_none_request_does_not_clear_source(self):
+        """请求级"没表态"绝不能被读成"要求关闭"——那会静默改掉源级的默认档。"""
+        assert (
+            effective_effort(request_effort=None, source_effort=Effort.LOW, enable_thinking=None)
+            is Effort.LOW
+        )
+
+    def test_request_none_tier_is_an_opinion(self):
+        """`Effort.NONE` 是一次明确的表态,必须压过源级档位而不是被当成缺省。"""
+        assert (
+            effective_effort(
+                request_effort=Effort.NONE, source_effort=Effort.MAX, enable_thinking=None
+            )
+            is Effort.NONE
+        )
+
+    def test_enable_thinking_true_is_auto(self):
+        """`True` → `auto`(开启但不指定强度),而**不是**旧版硬编码的 medium。"""
+        assert (
+            effective_effort(request_effort=None, source_effort=None, enable_thinking=True)
+            is Effort.AUTO
+        )
+
+    def test_enable_thinking_false_is_the_none_tier(self):
+        assert (
+            effective_effort(request_effort=None, source_effort=None, enable_thinking=False)
+            is Effort.NONE
+        )
+
+    def test_sugar_is_the_last_word_only(self):
+        """语法糖排在最末: 显式配了档位就以档位为准(矛盾组合已被构造期挡下)。"""
+        assert (
+            effective_effort(request_effort=None, source_effort=Effort.LOW, enable_thinking=True)
+            is Effort.LOW
+        )
+
+    def test_all_absent_is_no_opinion(self):
+        """三层都不表态 → None(随模型默认),与 `Effort.NONE` 严格区分。"""
+        assert (
+            effective_effort(request_effort=None, source_effort=None, enable_thinking=None) is None
+        )
+
+
+class TestThinkingWireOwnership:
+    """开启片段只能表达开启，不能携带隐式强度。"""
+
+    @pytest.mark.parametrize(
+        "base",
+        [
+            {"reasoning_effort": "high"},
+            {"reasoning_effort": None},
+            {"depth": "auto"},
+            {"output_config": {"effort": "low"}},
+        ],
+    )
+    @pytest.mark.parametrize("effort", [None, Effort.AUTO, Effort.HIGH])
+    def test_on_base_cannot_hide_a_tier(self, base, effort):
+        profile = ProviderProfile(
+            name="custom",
+            thinking=ThinkingWire(off={"depth": "none"}, on_base=base, effort_key="depth"),
+            strip_think_tags=False,
+        )
+        with pytest.raises(ThinkingUnsupportedError, match="on_base"):
+            resolve_thinking(profile, None, effort, model="custom-model")
+
+
+class TestThinkingRawOwnership:
+    """纯规则覆盖标准、自定义根与无意图逃生口。"""
+
+    @pytest.mark.parametrize(
+        "raw",
+        [
+            {"reasoning_effort": "high"},
+            {"enable_thinking": True},
+            {"thinking": {}},
+            {"thinking_budget": 100},
+            {"reasoning": {}},
+            {"thinkingConfig": {}},
+            {"output_config": {"effort": None}},
+            {"depth.key": None},
+            {"off_control": {}},
+        ],
+    )
+    @pytest.mark.parametrize("effort", [Effort.NONE, Effort.AUTO, Effort.HIGH])
+    def test_control_roots_rejected_without_mutating_input(self, raw, effort):
+        from copy import deepcopy
+
+        from polygateway.thinking import validate_thinking_raw
+
+        wire = ThinkingWire(off={"off_control": False}, on_base={}, effort_key="depth.key")
+        before = deepcopy(raw)
+        with pytest.raises(ThinkingUnsupportedError):
+            validate_thinking_raw(raw, effort=effort, wire=wire, origin="test")
+        assert raw == before
+        validate_thinking_raw(raw, effort=None, wire=wire, origin="test")
+        assert raw == before
+
+    def test_output_format_is_not_effort_unless_wire_owns_root(self):
+        from polygateway.thinking import validate_thinking_raw
+
+        raw = {"output_config": {"format": "json"}, "temperature": 0, "seed": 7}
+        validate_thinking_raw(raw, effort=Effort.AUTO, wire=None, origin="test")
+        wire = ThinkingWire(off=None, on_base={"output_config": {"enabled": True}}, effort_key=None)
+        with pytest.raises(ThinkingUnsupportedError):
+            validate_thinking_raw(raw, effort=Effort.AUTO, wire=wire, origin="test")
+
+
+def test_auto_rejection_explains_how_to_choose_explicitly():
+    """可执行配置是指路，不由库自动应用其建议。"""
+    with pytest.raises(ThinkingUnsupportedError) as error:
+        resolve_thinking(
+            get_provider("minimax"), get_capability("MiniMax-M3"), Effort.AUTO, model="MiniMax-M3"
+        )
+    assert "REASONING_EFFORT=" in str(error.value)
+    assert "reasoning_effort=Effort." in str(error.value)
+    assert "EFFORT_FALLBACK=nearest" not in str(error.value)

tests/unit/test_types.py

@@ -10,6 +10,7 @@ from polygateway.types import (
     BackpressurePolicy,
     BreakerConfig,
     ChatRequest,
+    Effort,
     GlobalLimits,
     LLMResponse,
     RetryPolicy,
@@ -566,3 +567,187 @@ class TestChatRequestDimensions:
         )
         assert request.tenant_id == "t1"
         assert request.meta == {"batch": "b-42"}
+
+
+class TestSourceConfigEffortNormalization:
+    """源级档位在**构造期**归一成 `Effort`(issue #20;2026-09-05 独立验证查出)。
+
+    库内一律用 `is Effort.NONE` 做身份比较,而 `Effort` 是 `StrEnum`——下游从
+    JSON/配置读出来的天然是裸字符串,不归一就会在**错误路径上**误判并二次崩溃。
+    """
+
+    def test_bare_string_tier_is_normalized(self):
+        """`reasoning_effort="low"` 必须存成 `Effort.LOW`,而不是原样留个 str。"""
+        assert _make_source(reasoning_effort="low").reasoning_effort is Effort.LOW
+
+    def test_whitespace_and_case_are_normalized(self):
+        """与 `.env` 那条路同口径: 行尾空格与大写写法是常态,档位无大小写语义。"""
+        assert _make_source(reasoning_effort=" LOW ").reasoning_effort is Effort.LOW
+
+    def test_consistent_bare_string_survives_the_contradiction_guard(self):
+        """设计 §4.2 明说"二者一致则放行",裸字符串写法不得被判成矛盾。
+
+        修复前实测: `("none" is Effort.NONE)` 为假 → 判为矛盾 → 拼文案时 `.value`
+        抛 `AttributeError`,连承诺的 `ValueError` 都拿不到。
+        """
+        source = _make_source(enable_thinking=False, reasoning_effort="none")
+        assert source.reasoning_effort is Effort.NONE
+
+    def test_contradiction_still_caught_through_a_bare_string(self):
+        """归一化不得把矛盾一并抹平: `True` + `"none"` 仍是配置错误。"""
+        with pytest.raises(ValueError, match="矛盾"):
+            _make_source(enable_thinking=True, reasoning_effort="none")
+
+    def test_illegal_tier_lists_the_whole_vocabulary(self):
+        """写错档位的人要的是"那该填什么",故报错必须把八档全摆出来并指回字段。"""
+        with pytest.raises(ValueError) as exc:
+            _make_source(reasoning_effort="lowest")
+        message = str(exc.value)
+        assert "reasoning_effort" in message
+        assert all(tier.value in message for tier in Effort)
+
+    def test_non_string_tier_is_a_value_error_not_a_crash(self):
+        """非字符串同样只能是 `ValueError`: 公共入口不许把类型错误漏成 `AttributeError`。"""
+        with pytest.raises(ValueError, match="推理档位"):
+            _make_source(reasoning_effort=3)
+
+
+class TestCallStatsAndContext:
+    """逻辑调用统计内核(1.3.5 设计 §3/§4)。"""
+
+    def test_call_stats_is_frozen_snapshot(self):
+        from polygateway.types import CallStats
+
+        stats = CallStats(logical_call_id="lc-1", attempts=2, total_latency_ms=15)
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            stats.attempts = 3
+
+    def test_context_counts_attempts_and_freezes_elapsed(self):
+        """快照是同步冻结的时间切片: 登记两次尝试后耗时按注入钟折算成毫秒。"""
+        from polygateway.types import _CallContext
+
+        clock = _FakeMonotonic()
+        ctx = _CallContext(now=clock)
+        clock.advance(1.5)
+        ctx.register_attempt()
+        ctx.register_attempt()
+        stats = ctx.snapshot()
+        assert stats.attempts == 2
+        assert stats.total_latency_ms == 1500  # 秒→毫秒,不混用单位
+
+    def test_snapshot_is_repeatable_and_tracks_later_time(self):
+        from polygateway.types import _CallContext
+
+        clock = _FakeMonotonic()
+        ctx = _CallContext(now=clock)
+        first = ctx.snapshot()
+        clock.advance(2.0)
+        second = ctx.snapshot()
+        assert first.total_latency_ms == 0 and second.total_latency_ms == 2000
+        assert first.logical_call_id == second.logical_call_id
+
+    def test_each_context_gets_its_own_logical_id(self):
+        from polygateway.types import _CallContext
+
+        clock = _FakeMonotonic()
+        assert _CallContext(now=clock).logical_call_id != _CallContext(now=clock).logical_call_id
+
+    def test_claim_terminal_is_true_once(self):
+        """终态去重位: 保证每逻辑调用至多写一条终态行(设计 §6 不变量 I3)。"""
+        from polygateway.types import _CallContext
+
+        ctx = _CallContext(now=_FakeMonotonic())
+        assert ctx.claim_terminal() is True
+        assert ctx.claim_terminal() is False
+
+    def test_chat_request_context_does_not_affect_equality_or_repr(self):
+        """上下文是库内部件: 进 `compare`/`repr` 会污染既有请求语义与日志。"""
+        from polygateway.types import _CallContext
+
+        ctx = _CallContext(now=_FakeMonotonic())
+        bare = ChatRequest(messages=[{"role": "user", "content": "hi"}])
+        with_ctx = dataclasses.replace(bare, call_context=ctx)
+        assert with_ctx.call_context is ctx
+        assert with_ctx == bare
+        assert "call_context" not in repr(with_ctx)
+
+    def test_replace_preserves_the_same_context_reference(self):
+        """洋葱各层经 `replace` 派生请求,上下文必须是同一实例而非拷贝。"""
+        from polygateway.types import _CallContext
+
+        ctx = _CallContext(now=_FakeMonotonic())
+        req = ChatRequest(messages=[{"role": "user", "content": "hi"}], call_context=ctx)
+        derived = dataclasses.replace(req, stream=False)
+        assert derived.call_context is ctx
+
+    def test_four_responses_default_call_stats_to_none(self):
+        """第三方合成响应的 `None` 表示未知,不得伪造 0(设计 §3)。"""
+        from polygateway.types import (
+            EmbeddingResponse,
+            OcrLayoutResult,
+            OcrTextResult,
+        )
+
+        llm = LLMResponse(
+            content="c",
+            thinking="",
+            model="m",
+            provider="p",
+            prompt_tokens=1,
+            completion_tokens=1,
+            latency_ms=1,
+            ttft_ms=None,
+            max_inter_token_ms=None,
+            cache_hit=False,
+            call_id="c1",
+        )
+        emb = EmbeddingResponse(
+            vectors=[],
+            dim=0,
+            model="m",
+            provider="p",
+            prompt_tokens=0,
+            usage_source="measured",
+            latency_ms=0,
+            call_id="c2",
+            source_name="s",
+        )
+        text = OcrTextResult(
+            text="", source_name="s", usage=Usage(0, 0), latency_ms=0, call_id="c3", raw={}
+        )
+        layout = OcrLayoutResult(
+            elements=[],
+            page_sizes=[],
+            source_name="s",
+            usage=Usage(0, 0),
+            latency_ms=0,
+            call_id="c4",
+            raw={},
+        )
+        assert (llm.call_stats, emb.call_stats, text.call_stats, layout.call_stats) == (
+            None,
+            None,
+            None,
+            None,
+        )
+
+    def test_call_stats_is_exported_from_package_root(self):
+        """四份平铺字段会漂移,故统计以单一对象出现在公共 API(设计 §3)。"""
+        import polygateway
+        from polygateway.types import CallStats
+
+        assert polygateway.CallStats is CallStats
+        assert "CallStats" in polygateway.__all__
+
+
+class _FakeMonotonic:
+    """确定性单调钟;不复用 contracts 的 FakeClock 以免 unit 反向依赖契约包。"""
+
+    def __init__(self, start: float = 1000.0) -> None:
+        self.t = start
+
+    def __call__(self) -> float:
+        return self.t
+
+    def advance(self, seconds: float) -> None:
+        self.t += seconds

tests/unit/test_usage_source_domain.py

@@ -35,6 +35,7 @@ from polygateway.types import (
     USAGE_SOURCES,
     BackpressurePolicy,
     BreakerConfig,
+    CallStats,
     ChatRequest,
     EmbeddingTransportResult,
     GlobalLimits,
@@ -44,6 +45,9 @@ from polygateway.types import (
     SourceConfig,
 )
 
+# 终态行的快照入参(1.3.5): `emit_terminal_failure` 不再收 `latency_ms`。
+_MIGRATED_STATS = CallStats(logical_call_id="lcid-mig", attempts=1, total_latency_ms=1)
+
 _REQ = ChatRequest(messages=[{"role": "user", "content": "hi"}])
 _DOMAIN = sorted(USAGE_SOURCES)
 
@@ -134,6 +138,7 @@ async def test_salvage_override_stays_in_domain(usage):
         stream=True,
         overlay={},
         call_id="cid",
+        reasoning_effort=None,
     )
     assert result.usage_source in USAGE_SOURCES
 
@@ -254,13 +259,15 @@ def _resp(usage_source):
 @pytest.mark.parametrize("emitted", _DOMAIN)
 async def test_emit_attempt_success_stays_in_domain(emitted):
     recorder = _MemoryRecorder()
-    await TelemetryEmitter(recorder, text_cap=None).emit_attempt(
+    await TelemetryEmitter(recorder, text_cap=None, scope="LLM").emit_attempt(
         request=_REQ,
         source=_src(),
         call_id="cid",
         latency_ms=10,
         response=_resp(emitted),
         error=None,
+        reasoning_applies=True,
+        operation="chat",
     )
     assert recorder.rows[0]["usage_source"] in USAGE_SOURCES
 
@@ -268,13 +275,15 @@ async def test_emit_attempt_success_stays_in_domain(emitted):
 async def test_emit_attempt_failed_attempt_stays_in_domain():
     """失败尝试无 response,`usage_source` 取 emitter 自己的字面量。"""
     recorder = _MemoryRecorder()
-    await TelemetryEmitter(recorder, text_cap=None).emit_attempt(
+    await TelemetryEmitter(recorder, text_cap=None, scope="LLM").emit_attempt(
         request=_REQ,
         source=_src(),
         call_id="cid",
         latency_ms=10,
         response=None,
         error="boom",
+        reasoning_applies=True,
+        operation="chat",
     )
     assert recorder.rows[0]["usage_source"] in USAGE_SOURCES
 
@@ -282,8 +291,10 @@ async def test_emit_attempt_failed_attempt_stays_in_domain():
 @pytest.mark.parametrize("emitted", _DOMAIN)
 async def test_emit_cache_hit_stays_in_domain(emitted):
     recorder = _MemoryRecorder()
-    await TelemetryEmitter(recorder, text_cap=None).emit_cache_hit(
+    await TelemetryEmitter(recorder, text_cap=None, scope="LLM").emit_cache_hit(
-        request=_REQ, response=_resp(emitted)
+        request=_REQ,
+        response=_resp(emitted),
+        operation="chat",
     )
     assert recorder.rows[0]["usage_source"] in USAGE_SOURCES
 
@@ -291,7 +302,11 @@ async def test_emit_cache_hit_stays_in_domain(emitted):
 async def test_emit_terminal_failure_stays_in_domain():
     """终态失败无具体源,`usage_source` 同样取 emitter 字面量。"""
     recorder = _MemoryRecorder()
-    await TelemetryEmitter(recorder, text_cap=None).emit_terminal_failure(
+    await TelemetryEmitter(recorder, text_cap=None, scope="LLM").emit_terminal_failure(
-        request=_REQ, call_id="cid", latency_ms=10, error="cancelled"
+        request=_REQ,
+        call_id="cid",
+        error="cancelled",
+        operation="chat",
+        stats=_MIGRATED_STATS,
     )
     assert recorder.rows[0]["usage_source"] in USAGE_SOURCES

tools/check_wiki_alignment.py

@@ -28,7 +28,7 @@ from polygateway import EmbeddingClient, GatewayClient, LLMResponse
 from polygateway.config import _SOURCE_FIELDS
 from polygateway.ocr import OcrClient
 from polygateway.providers import register_provider
-from polygateway.telemetry.sqlite import _COLUMNS as TELEMETRY_COLUMNS
+from polygateway.telemetry.sqlite import COLUMNS as TELEMETRY_COLUMNS
 
 # 参数名允许在 wiki 里以别名出现的白名单(仅限确无歧义的自解释形参)
 _PARAM_ALIASES: dict[str, set[str]] = {"env": {"env"}}

tools/telemetry_retention.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 import argparse
 import asyncio
+import re
 import sqlite3
 import sys
 from datetime import UTC, datetime, timedelta
@@ -30,6 +31,11 @@ if TYPE_CHECKING:
 
 TABLE = "llm_calls"
 
+# --table 的 schema 段白名单。收紧到普通标识符不是为了防注入(目标名走 to_regclass
+# 的参数化占位,且用 _quote 转义),而是让 --help 里"不支持复杂标识符"这句话与实现
+# 一致——文档说不支持、实现却照单全收,受害的是照文档做判断的人。
+_PLAIN_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_$]*")
+
 # 退出码是本脚本对调度器(cron/systemd)的公共契约,改动即破坏下游告警规则
 EXIT_OK = 0
 EXIT_USAGE = 1
@@ -59,6 +65,11 @@ _EPILOG = """\
 时间口径: 截止时刻 = 当前 UTC 时刻 - N 天,删除 created_at < 截止时刻 的行;
           --older-than-days 0 即"删除此刻之前的全部行"。
 
+--table: 本脚本只清理表 llm_calls,故 --table 只有 schema 一段可变(写成
+         --table <schema>.llm_calls)。给了它,目标就由参数精确解析、不再经
+         search_path 推断。含点或引号的复杂标识符不支持,此时请不给 --table,
+         退回 search_path 解析那条路径。
+
 示例:
   python tools/telemetry_retention.py --backend sqlite --path runs/telemetry.db \\
       --older-than-days 90                      # dry-run,只看会删什么
@@ -114,6 +125,11 @@ def _build_parser() -> _Parser:
         action="store_true",
         help="仅 sqlite: 删除后执行 VACUUM 回收文件空间;须与 --apply 同时给",
     )
+    parser.add_argument(
+        "--table",
+        metavar="SCHEMA.NAME",
+        help=f"仅 postgres: 把目标钉死为 <schema>.{TABLE},绕开 search_path 推断",
+    )
     return parser
 
 
@@ -150,10 +166,16 @@ def _validate_sqlite(parser: _Parser, args: argparse.Namespace) -> None:
         parser.error("--backend sqlite 不接受 --dsn")
     if args.batch_size is not None:
         parser.error("--batch-size 仅用于 --backend postgres")
+    if args.table is not None:
+        parser.error("--table 仅用于 --backend postgres:SQLite 的库文件即目标,无 schema 可消歧")
 
 
 def _validate_postgres(parser: _Parser, args: argparse.Namespace) -> None:
-    """Postgres 分支: 必须有 --dsn,拒绝 sqlite 专属参数,并在此落 --batch-size 缺省值。"""
+    """Postgres 分支: 必须有 --dsn,拒绝 sqlite 专属参数,并在此落 --batch-size 缺省值。
+
+    `--table` 在此解析成 `args.table_schema`(未给则 None): 校验与解析放在同一处,
+    后面的执行路径就只面对一个已经合法的 schema 名,不必再重复判断。
+    """
     if args.dsn is None:
         parser.error("--backend postgres 需要 --dsn")
     if args.path is not None:
@@ -164,6 +186,36 @@ def _validate_postgres(parser: _Parser, args: argparse.Namespace) -> None:
         args.batch_size = 1000
     elif args.batch_size < 1:
         parser.error("--batch-size 必须 >= 1")
+    args.table_schema = None if args.table is None else _parse_table(parser, args.table)
+
+
+def _parse_table(parser: _Parser, value: str) -> str:
+    """校验 `--table SCHEMA.NAME` 并返回 schema 段;任何不合法形态退出 1。
+
+    **表名段为什么不可变**: 只校验"两段、非空"的话,一次手误 `--table audit.events`
+    就会让本脚本对一张恰好也有 `created_at` / `tenant_id` 的业务表跑同一套分批 DELETE。
+    脚本的名字、退出码 3 的分区提示、README 的定位全都围绕遥测表写,它从未声称自己
+    是通用清理器;把这条校验去掉等于在一个拿 DELETE 权限跑的脚本上开静默的口子。
+    """
+    segments = value.split(".")
+    if len(segments) != 2:
+        parser.error(f"--table 必须是 <schema>.{TABLE} 这样的两段限定名,当前: {value!r}")
+    schema, name = segments
+    # 段内不可能再含 "." (上面按 "." 切成恰好两段),故此处只查其余形态
+    if not schema or not name:
+        parser.error(f"--table 的 schema 段与表名段都不得为空,当前: {value!r}")
+    if not _PLAIN_IDENTIFIER.fullmatch(schema):
+        parser.error(
+            f"--table 的 schema 段只接受普通标识符(字母或下划线开头,其后字母/数字/"
+            f"下划线/$),当前: {value!r};含空格、引号等需要加引号的复杂标识符不支持,"
+            "这种情形请不给 --table,退回 search_path 解析那条路径。"
+        )
+    if name != TABLE:
+        parser.error(
+            f"--table 的表名段必须逐字等于 {TABLE}:本脚本只清理遥测表 {TABLE},"
+            f"不是通用清理器,当前: {value!r}"
+        )
+    return schema
 
 
 def _print_stats(total: int, low: object, high: object, tenants: Sequence[tuple[str, int]]) -> None:
@@ -240,7 +292,9 @@ def _quote(identifier: str) -> str:
     return f'"{escaped}"'
 
 
-async def _run_postgres(dsn: str, cutoff: datetime, apply_: bool, batch_size: int) -> int:
+async def _run_postgres(
+    dsn: str, cutoff: datetime, apply_: bool, batch_size: int, table_schema: str | None
+) -> int:
     """PostgreSQL 分支: 分区表让路,普通表分批 DELETE(每批一个事务)。"""
     try:
         import asyncpg
@@ -257,7 +311,7 @@ async def _run_postgres(dsn: str, cutoff: datetime, apply_: bool, batch_size: in
         print(f"连接 PostgreSQL 失败: {exc}", file=sys.stderr)
         return EXIT_BACKEND
     try:
-        return await _purge_postgres(conn, cutoff, apply_, batch_size)
+        return await _purge_postgres(conn, cutoff, apply_, batch_size, table_schema)
     except asyncpg.PostgresError as exc:
         print(f"PostgreSQL 操作失败: {exc}", file=sys.stderr)
         return EXIT_BACKEND
@@ -265,23 +319,41 @@ async def _run_postgres(dsn: str, cutoff: datetime, apply_: bool, batch_size: in
         await conn.close()
 
 
-async def _purge_postgres(conn: Any, cutoff: datetime, apply_: bool, batch_size: int) -> int:
+async def _purge_postgres(
+    conn: Any, cutoff: datetime, apply_: bool, batch_size: int, table_schema: str | None
+) -> int:
     """已连上后的清理主体(conn 是 asyncpg.Connection,不 import 类型以免脚本硬依赖)。"""
-    # 先解析目标: to_regclass 走连接自己的 search_path,故必须把解析结果打出来——
+    # 给了 --table 就用引号限定名精确解析(绕开 search_path),否则维持裸表名解析——
-    # "我删的到底是哪张表"是这个脚本唯一不能猜的事(共享库里另有同名表的场景常见)。
+    # 后者走连接自己的 search_path,故无论哪条路都必须把解析结果打出来:"我删的到底是
+    # 哪张表"是这个脚本唯一不能猜的事(共享库里另有同名表的场景常见)。
+    lookup = TABLE if table_schema is None else f"{_quote(table_schema)}.{_quote(TABLE)}"
     target = await conn.fetchrow(
         "SELECT n.nspname AS schema, c.relname AS name, "
         "EXISTS (SELECT 1 FROM pg_partitioned_table p WHERE p.partrelid = c.oid) AS partitioned "
         "FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace "
         "WHERE c.oid = to_regclass($1)",
-        TABLE,
+        lookup,
     )
     if target is None:
+        # 两条路的诊断方向不同,消息分开写: 显式指定找不到多半是名字/大小写写错了,
+        # search_path 找不到则是连接配置的事。
+        if table_schema is None:
             print(f"目标库的 search_path 下找不到表 {TABLE}", file=sys.stderr)
+        else:
+            print(
+                f"显式指定的表 {table_schema}.{TABLE} 不存在或当前角色不可见。"
+                "注意: PG 中未加引号建的标识符在 catalog 里是小写。",
+                file=sys.stderr,
+            )
         return EXIT_BACKEND
     schema, name = target["schema"], target["name"]
     qualified = f"{_quote(schema)}.{_quote(name)}"
     print(f"目标表: {schema}.{name}")
+    if apply_ and table_schema is None:
+        # 只在 --apply 时提示: dry-run 不可逆性为零,且它本就以"看清楚再决定"为用途。
+        print(
+            "注意: 目标表由连接的 search_path 推断得到。要把目标钉死,请加 --table <schema>.<表名>。"
+        )
     if target["partitioned"]:
         print(
             f"{schema}.{name} 是分区表: 本脚本拒绝对分区表执行 DELETE。\n"
@@ -347,7 +419,9 @@ def main(argv: Sequence[str] | None = None) -> int:
     print(f"模式: {'apply(将真正删除)' if args.apply else 'dry-run(只统计,不删除)'}")
     if args.backend == "sqlite":
         return _run_sqlite(args.path, cutoff.strftime(_SQLITE_TIME_FORMAT), args.apply, args.vacuum)
-    return asyncio.run(_run_postgres(args.dsn, cutoff, args.apply, args.batch_size))
+    return asyncio.run(
+        _run_postgres(args.dsn, cutoff, args.apply, args.batch_size, args.table_schema)
+    )
 
 
 if __name__ == "__main__":