docs: fix the four blockers Codex found in the design

The enum belonged in types.py all along: making LLMResponse field-typed
on a symbol defined in thinking.py would have had the innermost layer
import a decision module, and import-linter would have caught it only
after the code was written.

The 4.1 table claimed reconciliation could still catch a failed disable
while section 5 said UNKNOWN never speaks. UNKNOWN has no falsifying
power; the guarantee only covers observable paths, and the doc now says
so instead of pretending otherwise.

Section 12 was written against a misreading: _record already is the
single helper the ironclad rule asks for, so there was no debt to
decline. Landing sites had missed ports.py, whose record_llm_call
freezes 24 explicit params with no defaults, and cache.py, where
_rehydrate revives the enum as a bare string.

research-wiki/designs/2026-08-25-thinking-observability-design.md

@@ -13,7 +13,7 @@ date: 2026-08-25
 
 ## 1. 问题不是 issue 说的那个
 
-issue #16/#17 判定"MiniMax-M3 开启推理静默失效，模型不推理"。**实测推翻了这个诊断**：M3 的推理完全正常——流式路径下 `reasoning_content` 有 124 字符完整推理过程，`prompt_tokens` 194→216、`completion_tokens` 3→60，三个独立信号一致。
+issue #16/#17（Gitea `iomgaa/PolyGateway`，原文经 `tea issues 16` / `17` 读取；本仓库 remote 非 GitHub，`gh` 读不到）判定"MiniMax-M3 开启推理静默失效，模型不推理"。**实测推翻了这个诊断**：M3 的推理完全正常——流式路径下 `reasoning_content` 有 124 字符完整推理过程，`prompt_tokens` 194→216、`completion_tokens` 3→60，三个独立信号一致。
 
 真正发生的是：**MiniMax 这一路上游不再返回 `usage.completion_tokens_details`**（qwen 与 deepseek 在同一网关同一 key 上照常返回），于是 `reasoning_tokens` 恒为 NULL；而 e2e 的四条用例把 `reasoning_tokens` 当作唯一判据，于是集体判红。
 
@@ -52,24 +52,32 @@ class ThinkingObservation(StrEnum):
     UNKNOWN  = "unknown"    # 无任何信号，判不出来
 ```
 
+**枚举定义在 `types.py`，裁定逻辑在 `thinking.py`——两者必须分开。** 它是 `LLMResponse`/`TransportResult` 的字段类型，而 `types.py` 是最内层、不得 import 任何具体实现（P7，import-linter 契约执法）。把枚举放进 `thinking.py` 会让最内层反向依赖决策模块，契约当场判红。纯值类型归最内层、决策逻辑归上层，是本设计的分层落法。
+
+取 `StrEnum` 而非裸 `str` 常量：取值域显式、可类型检查，且它是 `str` 子类，`dataclasses.asdict` + `json.dumps` 天然可序列化（缓存回放路径见 §6）。
+
 裁定纯函数 `observe_thinking(*, thinking: str, reasoning_tokens: int | None) -> ThinkingObservation`，四条分支按顺序：
 
 | 条件 | 结果 | 理由 |
 |---|---|---|
-| `thinking` 非空 | OBSERVED | 推理正文是事实本身，压倒一切 |
+| `thinking.strip()` 非空 | OBSERVED | 推理正文是事实本身，压倒一切 |
 | `reasoning_tokens > 0` | OBSERVED | 上游明确上报了推理用量 |
 | `reasoning_tokens == 0` | ABSENT | 上报了且为零 = "未推理"的正面证据 |
 | 其余（`None`） | UNKNOWN | 无信号，不猜 |
 
+**判据取 `bool(thinking.strip())` 而非 `bool(thinking)`**：transport 收集 `reasoning_content` 时只判 truthy（`openai_compat.py`），上游返回纯空白串就会被计成"观测到推理"。网关响应是外部输入，校验后使用（P5）。
+
 映射到实测：
 
 | 场景 | observation | 是否诚实 |
 |---|---|---|
 | M3 开启，流式 | OBSERVED | ✅ 有 185 字符正文 |
 | M3 开启，非流式 | UNKNOWN | ✅ 确实观测不到（正文与 ctd 双缺） |
-| M3 关闭 | UNKNOWN | ✅ 判不出，但 §5 的对账仍能抓住"该关没关" |
+| M3 关闭 | UNKNOWN | ✅ 判不出——**且必须承认判不出**，见下 |
 | qwen 开启 | OBSERVED | ✅ 两个信号都在 |
 
+**`UNKNOWN` 不具证伪力，不得声称它能保障关闭方向。** M3 关闭档落在 `UNKNOWN`，这意味着库无法证明推理真的关掉了。对账（§5）能提供的保障只有一个方向：**若模型真的推理了，可观测路径会把结果翻成 `OBSERVED`，告警随之触发**——M3 流式正属此列（关闭档若失效，正文会冒出来）。而不可观测路径（M3 非流式）没有任何保障，这一点必须写在文档里而不是假装有。**告警覆盖的是可观测路径，不是全部路径**。
+
 `ABSENT` 这一支在当前三家供应商上**实测永不触发**（未推理时都是整个容器缺失，无人报 `0`）。仍然保留：协议允许上报 `0`，而一旦有供应商这么做，它就是唯一能把"没推理"与"没上报"分开的信号——为一个已知会出现的未来留一个空槽，不是 YAGNI 违例。
 
 ### 4.2 明确不做：不把"可观测性"写进能力表
@@ -82,12 +90,18 @@ class ThinkingObservation(StrEnum):
 
 在 transport 拿到结果处做一次比较，矛盾即 warning：
 
-| 请求方向 | 观测 | 处置 |
-|---|---|---|
-| `enable_thinking=False` | OBSERVED | **warning**：能力表声称可关闭，实测推理了 → 附 model 与 evidence，指路 `register_capability` |
-| `enable_thinking=True` | ABSENT | **warning**：注入了开启参数，上游明确上报未推理 |
-| `None`（不干预） | 任意 | 不表态——调用方没提要求，无从谈"违背" |
-| 任意 | UNKNOWN | 不表态——不能证伪 |
+| 请求方向 | 观测 | 能力表 | 处置 |
+|---|---|---|---|
+| `enable_thinking=False` | OBSERVED | 已登记 `can_disable=True` | **warning**：能力表漂移——声明说可关闭，实测推理了。附 model 与 `evidence` 日期，指路 `register_capability` |
+| `enable_thinking=False` | OBSERVED | 未登记 | **warning**：关闭请求未被满足，且该模型能力未登记。指路实测后 `register_capability` |
+| `enable_thinking=True` | ABSENT | 任意 | **warning**：注入了开启参数，上游明确上报未推理 |
+| `enable_thinking=True` | UNKNOWN | 任意 | **warning 一次**：推理参数已注入但本路径观测不到，无法确认是否生效；**若为非流式路径，推理内容可能已计费却不回传**（M3 实测 completion 53 vs 关闭档 3） |
+| `False` | UNKNOWN | 任意 | 不表态——不能证伪（§4.1） |
+| `None`（不干预） | 任意 | 任意 | 不表态——调用方没提要求，无从谈"违背" |
+
+前两行必须分开：`resolve_thinking` 的 Phase 3 允许未登记模型按 provider 形态尽力注入并预先 warning，那是**事前猜测**；这里的对账是**事后实证**，两者文案不能混。对未登记模型说"能力表声称可关闭"是错的——它根本没登记。
+
+第四行是 issue #17 关切的"静默失效"的诚实版本：库不再默不作声，而是明说"我注入了，但我看不见结果"。M3 非流式每次都落这一档，故节流不可少。
 
 **不抛错**，三条理由：一次观测不足以否决一次成功的调用；P5 的降级方向铁律只对限流/熔断要求"报错而非放行"，可观测性属遥测方向，降级即 warning；矛盾结果已随 `LLMResponse` 与遥测落地，处置权归下游。
 
@@ -97,18 +111,30 @@ class ThinkingObservation(StrEnum):
 
 ## 6. 落点清单
 
+**源码**
+
 | 文件 | 变更 |
 |---|---|
-| `thinking.py`（**新建**） | 承载推理这件事的全部决策，见 §7 |
+| `types.py` | 新增 `ThinkingObservation`（枚举归最内层，§4.1）；`LLMResponse` 增 `thinking_observation: ThinkingObservation = UNKNOWN`（只增不删，迁移兼容）；`TransportResult` 同增 |
+| `thinking.py`（**新建**） | 推理这件事的全部**决策**，见 §7 |
 | `providers.py` | 收缩为纯注册表：`ProviderProfile`、`DEFAULT_PROFILES`、`get_provider`/`register_provider` |
-| `types.py` | `LLMResponse` 增 `thinking_observation: ThinkingObservation = UNKNOWN`（只增不删，迁移兼容）；`TransportResult` 同增（带默认值，与 `cached_prompt_tokens` 等既有先例同形态） |
+| **`ports.py`** | `TelemetryRecorder.record_llm_call` 24 参 → 25 参。该 docstring 明定"新增参数不设默认值"（库外无第三方实现者），故两个 recorder 与全部测试替身必须同步。**这是端口 Protocol 签名变更**，属 CLAUDE.md 强制人类确认档 |
 | `transports/openai_compat.py` | 组装 `TransportResult` 时调 `observe_thinking`；对账告警落此处（唯一同时握有请求方向与响应结果的地方） |
 | `middleware/retry.py` | 透传新字段 |
-| `middleware/telemetry.py` | `_AttemptUsage` 与三个 `emit_*` 各加一行 |
+| `middleware/telemetry.py` | `_AttemptUsage` 增一字段；三个 `emit_*` 各传一行；`_record` 签名增一参——**全部经既有单一出口 `_record` 抵达 recorder**，不新开调用点（§12） |
+| **`middleware/cache.py`** | `_rehydrate` 走 `LLMResponse(**fields)`，JSON 复活的是**裸字符串**而非枚举实例：须显式转 `ThinkingObservation(...)`。非法值（旧缓存/污染）转换失败由既有 try/except 吞成"按未命中回源"，降级方向正确 |
 | `telemetry/schema.py` | 新列 `thinking_observation TEXT`，两端 DDL + 两份 backfill + `COLUMNS`；INSERT 字段 24→25，物理列 25→26 |
+| `telemetry/sqlite.py`、`telemetry/postgres.py` | 实现新参 |
 | `client.py` | import 路径改指 `thinking.py` |
 | `__init__.py` | 新增包根导出，见 §7 |
-| `tests/e2e/test_thinking_live.py` | 判据重建，见 §8 |
+
+**测试**
+
+`tests/unit/` 下 `test_types.py`（默认值为 UNKNOWN、位置构造兼容、枚举归属模块）、`test_ports.py`（端口签名冻结测试与 recorder 替身）、`test_openai_compat.py`（裁定四分支、优先级、对账三类告警、节流只喊一次）、`test_retry.py`（透传）、`test_telemetry.py`（列数/列序/组装）、`test_cache.py`（回放后仍是枚举实例、非法值按未命中）、`test_package.py`（包根导出面，比照 `TelemetryStatus` 先例）、`test_providers.py`（拆分后的注册表）；`tests/integration/test_postgres_telemetry.py`（新列 backfill 与 round-trip）；`tests/e2e/test_thinking_live.py`（判据重建，§8）。
+
+**文档**（发布清单第 1 步要求构建前改完）
+
+`README.md` 的"必录 24 字段"→ 25，**须用 `inspect.signature` 实测而非凭记忆**；`research-wiki/ARCHITECTURE.md` 的 D11、§5.1 响应字段、§7.8 遥测字段、§8 模块结构（补 `thinking.py`）；`research-wiki/schemas/llm-calls.md`（标题仍写"22 字段"，已过期两轮，本次一并订正为 25）；`research-wiki/index.md`（登记本 design 与 finding）;`CHANGELOG.md`（断裂项置顶，§13）。
 
 `thinking_observation` **不进缓存 key**：它是结果不是请求。缓存回放的历史响应带回历史 observation，与 `reasoning_tokens`/`cached_prompt_tokens` 的既有回放口径一致。
 
@@ -121,7 +147,7 @@ class ThinkingObservation(StrEnum):
 | 模块 | 职责 | 内容 |
 |---|---|---|
 | `providers.py` | **provider 是什么** | `ProviderProfile`、`DEFAULT_PROFILES`、`get_provider`、`register_provider` |
-| `thinking.py` | **推理这件事的全部决策** | `ThinkingCapability`、`DEFAULT_CAPABILITIES`、`get_capability`、`register_capability`、`resolve_thinking`（请求侧注入）、`ThinkingUnsupportedError`、`ThinkingObservation`、`observe_thinking`（响应侧裁定）、对账告警 |
+| `thinking.py` | **推理这件事的全部决策** | `ThinkingCapability`、`DEFAULT_CAPABILITIES`、`get_capability`、`register_capability`、`resolve_thinking`（请求侧注入）、`ThinkingUnsupportedError`、`observe_thinking`（响应侧裁定）、对账告警。**不含 `ThinkingObservation` 定义**——纯值类型归 `types.py`（§4.1） |
 
 符合 P7"决策逻辑与状态存储分离"：注册表存声明，`thinking.py` 做决策。未来任何推理相关能力都有唯一归属，不必再挑"放哪个文件"。
 
@@ -179,15 +205,15 @@ class ThinkingObservation(StrEnum):
 
 | 层 | 覆盖 |
 |---|---|
-| 单元 | `observe_thinking` 四条分支；对账三种组合（False×OBSERVED、True×ABSENT、UNKNOWN 不表态）；节流只喊一次；`LLMResponse`/`TransportResult` 默认值为 UNKNOWN；schema 列数与列序断言（既有测试自动抓） |
-| 集成 | SQLite/PG 新列 backfill 与回读（既有测试模式） |
+| 单元 | `observe_thinking` 四条分支 + 空白串不算 OBSERVED；对账四类告警（False×OBSERVED 已登记 / False×OBSERVED 未登记 / True×ABSENT / True×UNKNOWN）与两类不表态；节流只喊一次；`LLMResponse`/`TransportResult` 默认值为 UNKNOWN 且位置构造不破；端口签名冻结（25 参）；缓存回放后仍是枚举实例、非法值按未命中；schema 列数与列序断言（既有测试自动抓）；包根导出面 |
+| 集成 | SQLite/PG 新列 backfill 与 round-trip（既有测试模式） |
 | e2e | §8 判据重建，合并前 `pytest -m slow` 真跑并存档报告 |
 
 **先失败后通过的证据**：`observe_thinking` 与对账的单测在字段落地前必然红；e2e 的 L2/L4 在判据改完、字段落地后应从当前 main 的 FAIL 转绿（库本来就拿到了 `thinking`，只是没人看）。L5 的新断言在旧代码上无法表达（`thinking_observation` 不存在），是纯新增覆盖。
 
 ## 12. 明确不做
 
-**不收敛遥测的四处参数列表复制。** CLAUDE.md 铁律点名"遥测调用点收敛为单一 helper，禁止复制参数列表"，而 `middleware/telemetry.py` 现在正是 `_AttemptUsage` + 三个 `emit_*` 各持一份，本次加字段会让它变成四处各加一行。这是**既有债务，不是本次引入**；反 gold-plating 明文禁止任务外重构，且 1.3.0 刚动过遥测路径，同版再改组装逻辑是叠加风险。**另立 issue 单独处理**。
+**不重构遥测组装路径。** 铁律"遥测调用点收敛为单一 helper"**当前已经满足**：`TelemetryEmitter._record` 是全库唯一调用 `record_llm_call` 的地方（`middleware/telemetry.py` 文件头即如此声明）。三个 `emit_*` 是三个语义不同的入口（逐次尝试 / 缓存命中 / 终态失败），各自组装参数是职责所在，不是复制粘贴债务——本次新增字段照样只经 `_record` 一个出口下沉。
 
 **不改 M3 的 `can_disable`**：2026-08-25 复测 `reasoning_effort=none` → prompt 194（= 基线）、completion 3、无正文，声明依然成立。只刷新 evidence 日期并补记两条新限制（非流式不可观测、仅 `reasoning_effort` 有效）。
 
@@ -207,5 +233,8 @@ class ThinkingObservation(StrEnum):
 - `LLMResponse.thinking_observation` 在 M3 开启流式档实测为 `OBSERVED`、非流式档为 `UNKNOWN`、qwen 开启档为 `OBSERVED`
 - 遥测 SQLite/PG 两端新列均可写可读，旧表 backfill 通过，列序断言绿
 - `tests/e2e/test_thinking_live.py` 全类绿（`pytest -m slow` 真跑，报告存档 `tests/outputs/e2e/`）
-- `make lint`（含 import-linter 契约）与全套件绿
-- CHANGELOG 显式列出深路径 import 断裂与改法、M3 非流式付费不可见推理这一事实
+- 端口 `record_llm_call` 25 参，两个 recorder 与全部测试替身同步，签名冻结测试绿
+- 缓存回放的 `thinking_observation` 是 `ThinkingObservation` 实例而非裸字符串
+- `make lint`（含 import-linter 契约，须确认 `types.py` 未 import `thinking.py`）与全套件绿
+- README 的遥测字段数经 `inspect.signature` 实测更新为 25；ARCHITECTURE §8 模块结构含 `thinking.py`；`schemas/llm-calls.md` 由过期的"22 字段"订正为 25；本 design 与 finding 进 `research-wiki/index.md`
+- CHANGELOG 本版条目**最前**列出深路径 import 断裂与改法、端口签名变更、M3 非流式付费不可见推理这一事实（§13）