docs: realign authoritative docs with the three-state usage_source

ARCHITECTURE.md 四处: §4.4 预扣量改指 effective_est_tokens(); §5.1 补三态值域表与
cost NULL 口径(含缓存命中行的例外与缺口查询必带 cache_hit 限定); §7.1 打捞路径
由强制 estimated 改为仅在收到 usage 帧时降级; §7.7 est_tokens 降为可选调优覆盖并
写明 tpm//60 派生规则与既有的全局 TPM 闸限制。

migrations/chsanalyzer.md 行 151 由保留改判有意放弃并写入理由; G2 标记已闭。
schemas/llm-calls.md 同步三态与 cost 口径。

research-wiki/schemas/llm-calls.md

@@ -16,15 +16,25 @@ date: 2026-07-20
 | parent_call_id / session_id | TEXT | 调用链路(agent step → LLM call) |
 | model / provider / source_name | TEXT NOT NULL | 溯源;model 由旧 Protocol 的 model_name 更名(VT 迁移 §8) |
 | messages / response / thinking | TEXT NOT NULL | messages 落库前多模态 part 摘要(与缓存 key 共用 digest_messages) |
-| prompt_tokens / completion_tokens | INTEGER NOT NULL | usage 帧;缺失按 est 兜底 |
-| usage_source | TEXT NOT NULL | measured / estimated |
+| prompt_tokens / completion_tokens | INTEGER NOT NULL | usage 帧;帧缺失记 0/0(不编造估值,由 usage_source 标注) |
+| usage_source | TEXT NOT NULL | measured / estimated / unavailable(2026-07-30 起三态,见下) |
 | latency_ms | INTEGER NOT NULL | 尝试耗时;缓存命中 0 |
 | ttft_ms / max_inter_token_ms | REAL | 流式活性测量 |
 | cache_hit | INTEGER NOT NULL DEFAULT 0 | 命中标记 |
 | error | TEXT | 异常信息;取消记 "cancelled" |
-| cost | REAL | M1 恒 NULL,M2 pricing 换算 |
+| cost | REAL | M2 起 pricing 换算;`usage_source='unavailable'` 的真实调用行为 NULL(缓存命中行例外,仍为 0.0) |
 | created_at | TEXT NOT NULL DEFAULT (datetime('now')) | 落库时刻 |
 
+## usage/成本口径(2026-07-30,est_tokens 解耦)
+
+| usage_source | 含义 | 生产者 | cost |
+|---|---|---|---|
+| `measured` | usage 帧完整可信 | 正常路径;OCR 成功行(0 token 是事实) | 按 token 换算 |
+| `estimated` | 有实测数字但可信度降级 | 打捞路径(收到 usage 帧但流被截断) | 按 token 换算 |
+| `unavailable` | 用量信息不可得 | usage 帧缺失、失败尝试、终态失败 | NULL |
+
+`SUM(cost)` 天然跳过 NULL,故账单汇总不再被虚构的估值污染;账目缺口的度量口径固定为 `WHERE usage_source = 'unavailable' AND cache_hit = false`。**`cache_hit` 限定不可省**:缓存命中行未产生新调用,cost 是事实上的 `0.0` 而非未知,本无账目缺口,漏掉该条件会让缺口度量偏高。
+
 ## 埋点位置(单一 helper 铁律)
 
 - `middleware/telemetry.py::TelemetryEmitter` 是全库**唯一** `record_llm_call` 调用点;