docs: document completion verdict and bump version to 1.3.10

CHANGELOG 1.3.10 (unreleased) with behaviour-change and breaking
sections, README capability rows and a 1.3.10 section, ARCHITECTURE
section 15 plus 6.2/7 updates, schema doc for the stream_end column,
migration impact notes, ROADMAP entry, .env.example MISSING_DONE
semantics, and a revision pointer on the 1.3.9 design. Follow-ups
filed as #32 and #33.

research-wiki/ARCHITECTURE.md

@@ -413,7 +413,7 @@ flowchart TB
 | 值 | 含义 | 生产者 | cost |
 | --- | --- | --- | --- |
 | `measured` | usage 帧完整可信 | 正常路径;OCR 成功行(0 token 是**事实**而非未知) | 按 token 换算 |
-| `estimated` | 有实测数字但可信度降级 | 打捞路径(收到 usage 帧但流被截断,§7.1) | 按 token 换算 |
+| `estimated` | 有实测数字但可信度降级 | 打捞路径(收到 usage 帧但流被截断,§7.1;1.3.10 起即 `stream_end="salvaged"`) | 按 token 换算 |
 | `unavailable` | 用量信息不可得 | usage 帧缺失、失败尝试、终态失败 | **NULL** |
 
 值域在 `types.py` 以模块级 frozenset 常量 `USAGE_SOURCES` 落地,**仅约束库内生产侧**(所有写入点从该常量取值),不在 `LLMResponse`/`Usage`/`TransportResult` 上加 `__post_init__` 值域校验——它们是运行时构造点,裸 `ValueError` 不属 §6 四分类、`RetryMW` 不捕会逃出 `chat()`;且 `LLMResponse` 是三项目已消费的公共类型,新增运行时校验属下游可见行为变更。历史库里既有的 `estimated` 行在新值域中依然合法可读。
@@ -470,7 +470,9 @@ flowchart TB
 | HTTP 429(body 无 insufficient_quota)、500/502/503/504 | `TransientError`(携 `Retry-After` 解析值,仅支持秒数形态) |
 | HTTP 429 + body 含 insufficient_quota、401、403 | `SourceDeadError` |
 | HTTP 400 | `RequestRejectedError` |
-| **空补全**: 200 且流程完整([DONE]/usage 正常)但 content 为空(2026-07-20 M1 验证发现,人类裁决) | `TransientError`(服务抖动,重试/换源;绝不缓存空响应) |
+| **空补全**: 200 且流程完整([DONE]/usage 正常)但 content 为空(2026-07-20 M1 验证发现,人类裁决) | `TransientError`(服务抖动,重试/换源;绝不缓存空响应)。1.3.10 起仅限**零产物**或无法区分抖动与结局的情形;上游明确的 length/过滤结局见 §15 |
+| finish_reason 为 `network_error`/`error`(上游自报失败,1.3.10) | `TransientError` |
+| 文本模式 length/过滤且无正文;保真模式 length 截断的半截工具(1.3.10) | `ResultInvalidError`(确定性结局,不重试、不计熔断) |
 | 解析层失败(结构化输出/OCR ZIP) | `ResultInvalidError` |
 
 **响应体留存(2026-08-16,Gitea issue #10;设计 `designs/2026-08-16-issue10-error-body-retention-design.md`)**: 上表每一条 HTTP 翻译**都必须携带响应体摘要**——摘要同时进入异常 message 与 `PolyGatewayError.body_text`(1.2.0 新增基类字段)。两者都要,因为逐次遥测写的是 `str(exc)`,只加字段进不了遥测表,而"事后可查"正是这条要求的目的。摘要口径由 `transports/_http_errors.summarize_body` 单点实现(折叠空白 → 限长 2048 字符 → 超长保留头 1400 + 尾 600 并记省略字数),两个 transport 共用,**不得各写一份**——issue #10 的成因正是"只有 429 那一支用了响应体"。`body_text` 是旁路数据,不参与任何治理判定;`_translate_429` 的类型细分仍解析未截断原文(摘要会破坏 JSON,改用它会让超长 body 的 `insufficient_quota` 退化成普通限速)。
@@ -806,3 +808,19 @@ src/polygateway/
 | 迁移 | 旧 text 污染无法自动判断，受影响集合必须迁移 namespace/salt；新模式天然隔离；无新遥测列/表，统一 helper 与取消结算不变 |
 
 本增量不会执行工具；length 结束原因与参数原样交回，由下游判断可执行性。嵌套 JSON 是独立可变快照，不承诺深冻结。许可已由原创 owner 明确批准 Apache-2.0。
+
+## 15. 统一完成判定（2026-10-14，#30/#31 已授权增量）
+
+本节修订 §6.2 空补全行、§7 `usage_source` 映射与 §14 协议/失败/缓存三行，详细边界见 [设计](designs/2026-10-14-issue30-31-completion-verdict-design.md)。
+
+| 接缝 | 增量契约 |
+|---|---|
+| 根因 | 1.3.9 以 `[DONE]` 存在、正文非空、字段白名单判定成功，上游正常结局落 Transient 被重试放大；本版以上游 `finish_reason` 与传输完整性为准 |
+| 内核 | `types.py` 纯函数 `_stream_is_complete` / `_classify_finish` / `_judge_outcome` / `_is_cacheable`，流式、非流式、缓存读写四处共用；只返回判定值，错误由调用点翻译 |
+| 流完整性 | `[DONE]` → `done`；无 DONE 但 finish 已到且其同帧或之后的 usage 为实测、干净 EOF → `eof_after_finish`；其余为截断：保真不打捞，文本按 `missing_done` |
+| 结局 | 首匹配表：上游错误 finish → Transient；坏工具（length → ResultInvalid）；零产物 + length/过滤 → 保真交付、文本 ResultInvalid；零产物其余 → Transient（保 2026-07-20 裁决）；有正文交付；有产物无正文按 finish 分模式 |
+| 字段 | 五层 null 视缺省；保真未知字段无损合并（字符串拼接、index 数组按 index、标签键幂等），冲突删键 + 有界告警；未知字符串片段计活性 |
+| 缓存 | 可缓存 ⊂ 可交付：salvaged、无正文、length/过滤/未知 finish 不写，读到即 miss；判定先于命中覆盖 |
+| 公共面 | `LLMResponse`/`TransportResult` 追加 `finish_reason`、`stream_end`；遥测加 `stream_end` 列，`record_llm_call` 加必填参数 |
+
+`usage_source` 与 `stream_end` 分工：前者答"账单可信吗"，后者答"内容完整吗"。`eof_after_finish ⇒ measured`；`salvaged ⇒ estimated|unavailable`；`estimated ⇒ salvaged`，逆命题不成立。诚实边界：中转在上游出错后主动正常关闭连接，与真完整在传输层不可区分。